secure/lib/libcipher/cipher.3

   1 .\" FreeSec: libcrypt for NetBSD
   2 .\"
   3 .\" Copyright (c) 1994 David Burren
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 4. Neither the name of the author nor the names of other contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\" $FreeBSD: src/secure/lib/libcipher/cipher.3,v 1.6.2.3 2001/12/14 15:21:13 ru Exp $
  31 .\"
  32 .\" Manual page, using -mandoc macros
  33 .\"
  34 .Dd March 9, 1994
  35 .Dt CIPHER 3
  36 .Os
  37 .Sh NAME
  38 .Nm setkey ,
  39 .Nm encrypt ,
  40 .Nm des_setkey ,
  41 .Nm des_cipher
  42 .Nd DES encryption
  43 .Sh LIBRARY
  44 .Lb libcipher
  45 .Sh SYNOPSIS
  46 .In unistd.h
  47 .Ft int
  48 .Fn setkey "const char *key"
  49 .Ft int
  50 .Fn encrypt "char *block" "int flag"
  51 .Ft int
  52 .Fn des_setkey "const char *key"
  53 .Ft int
  54 .Fn des_cipher "const char *in" "char *out" "long salt" "int count"
  55 .Sh DESCRIPTION
  56 The functions,
  57 .Fn encrypt ,
  58 .Fn setkey ,
  59 .Fn des_setkey
  60 and
  61 .Fn des_cipher
  62 provide access to the
  63 .Tn DES
  64 algorithm.
  65 .Fn setkey
  66 is passed a 64-byte array of binary values (numeric 0 or 1).
  67 A 56-bit key is extracted from this array by dividing the
  68 array into groups of 8, and ignoring the last bit in each group.
  69 That bit is reserved for a byte parity check by DES, but is ignored
  70 by these functions.
  71 .Pp
  72 The
  73 .Fa block
  74 argument to
  75 .Fn encrypt
  76 is also a 64-byte array of binary values.
  77 If the value of
  78 .Fa flag
  79 is 0,
  80 .Fa block
  81 is encrypted otherwise it is decrypted.
  82 The result is returned in the original array
  83 .Fa block
  84 after using the key specified by
  85 .Fn setkey
  86 to process it.
  87 .Pp
  88 The argument to
  89 .Fn des_setkey
  90 is a character array of length 8.
  91 The least significant bit (the parity bit) in each character is ignored,
  92 and the remaining bits are concatenated to form a 56-bit key.
  93 The function
  94 .Fn des_cipher
  95 encrypts (or decrypts if
  96 .Fa count
  97 is negative) the 64-bits stored in the 8 characters at
  98 .Fa in
  99 using
 100 .Xr abs 3
 101 of
 102 .Fa count
 103 iterations of
 104 .Tn DES
 105 and stores the 64-bit result in the 8 characters at
 106 .Fa out
 107 (which may be the same as
 108 .Fa in ) .
 109 The
 110 .Fa salt
 111 introduces disorder in the
 112 .Tn DES
 113 algorithm in one of 16777216 or 4096 possible ways
 114 (ie. with 24 or 12 bits: if bit
 115 .Em i
 116 of the
 117 .Ar salt
 118 is set, then bits
 119 .Em i
 120 and
 121 .Em i+24
 122 are swapped in the
 123 .Tn DES
 124 E-box output).
 125 .Pp
 126 The functions
 127 .Fn setkey ,
 128 .Fn encrypt ,
 129 .Fn des_setkey ,
 130 and
 131 .Fn des_cipher
 132 return 0 on success and 1 on failure.
 133 .Pp
 134 The
 135 .Fn setkey
 136 and
 137 .Fn des_setkey
 138 functions manipulate the same key space.
 139 .Sh SEE ALSO
 140 .Xr login 1 ,
 141 .Xr passwd 1 ,
 142 .Xr crypt 3 ,
 143 .Xr getpass 3 ,
 144 .Xr passwd 5
 145 .Sh HISTORY
 146 This library (FreeSec 1.0) was developed outside the United States of America
 147 as an unencumbered replacement for the U.S.-only
 148 .Nx
 149 libcrypt encryption
 150 library.
 151 Users should be aware that this code (and programs staticly linked with it)
 152 may not be exported from the U.S., although it apparently can be imported.
 153 .Sh AUTHORS
 154 .An David Burren Aq davidb@werj.com.au