gen/crypt.3

   1 .\" $OpenBSD: crypt.3,v 1.5 1996/12/10 09:06:09 deraadt Exp $
   2 .\"
   3 .\" FreeSec: libcrypt
   4 .\"
   5 .\" Copyright (c) 1994 David Burren
   6 .\" All rights reserved.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 4. Neither the name of the author nor the names of other contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\" Manual page, using -mandoc macros
  33 .\"
  34 .Dd March 9, 1994
  35 .Dt CRYPT 3
  36 .Os "FreeSec 1.0"
  37 .Sh NAME
  38 .Nm crypt ,
  39 .Nm setkey ,
  40 .Nm encrypt ,
  41 .Nm des_setkey ,
  42 .Nm des_cipher ,
  43 .Nd DES encryption
  44 .Sh SYNOPSIS
  45 .Fd #include <unistd.h>
  46 .Ft char
  47 .Fn *crypt "const char *key" "const char *setting"
  48 .Ft void
  49 .Fn setkey "char *key"
  50 .Ft void
  51 .Fn encrypt "char *block" "int flag"
  52 .Ft int
  53 .Fn des_setkey "const char *key"
  54 .Ft int
  55 .Fn des_cipher "const char *in" "char *out" "long salt" "int count"
  56 .Sh DESCRIPTION
  57 The
  58 .Fn crypt
  59 function performs password encryption, based on the
  60 .Tn NBS
  61 Data Encryption Standard (DES).
  62 Additional code has been added to deter key search attempts.
  63 The first argument to
  64 .Fn crypt
  65 is a
  66 .Dv null Ns -terminated
  67 string, typically a user's typed password.
  68 The second is in one of two forms:
  69 if it begins with an underscore (``_'') then an extended format is used
  70 in interpreting both the key and the setting, as outlined below.
  71 .Ss Extended crypt:
  72 .Pp
  73 The
  74 .Ar key
  75 is divided into groups of 8 characters (the last group is null-padded)
  76 and the low-order 7 bits of each each character (56 bits per group) are
  77 used to form the DES key as follows:
  78 the first group of 56 bits becomes the initial DES key.
  79 For each additional group, the XOR of the encryption of the current DES
  80 key with itself and the group bits becomes the next DES key.
  81 .Pp
  82 The setting is a 9-character array consisting of an underscore followed
  83 by 4 bytes of iteration count and 4 bytes of salt.
  84 These are encoded as printable characters, 6 bits per character,
  85 least significant character first.
  86 The values 0 to 63 are encoded as ``./0-9A-Za-z''.
  87 This allows 24 bits for both
  88 .Fa count
  89 and
  90 .Fa salt .
  91 .Ss "Traditional" crypt:
  92 .Pp
  93 The first 8 bytes of the key are null-padded, and the low-order 7 bits of
  94 each character is used to form the 56-bit
  95 .Tn DES
  96 key.
  97 .Pp
  98 The setting is a 2-character array of the ASCII-encoded salt.
  99 Thus only 12 bits of
 100 .Fa salt
 101 are used.
 102 .Fa count
 103 is set to 25.
 104 .Ss Algorithm:
 105 .Pp
 106 The
 107 .Fa salt
 108 introduces disorder in the
 109 .Tn DES
 110 algorithm in one of 16777216 or 4096 possible ways
 111 (ie. with 24 or 12 bits: if bit
 112 .Em i
 113 of the
 114 .Ar salt
 115 is set, then bits
 116 .Em i
 117 and
 118 .Em i+24
 119 are swapped in the
 120 .Tn DES
 121 E-box output).
 122 .Pp
 123 The DES key is used to encrypt a 64-bit constant using
 124 .Ar count
 125 iterations of
 126 .Tn DES .
 127 The value returned is a
 128 .Dv null Ns -terminated
 129 string, 20 or 13 bytes (plus null) in length, consisting of the
 130 .Ar setting
 131 followed by the encoded 64-bit encryption.
 132 .Pp
 133 The functions,
 134 .Fn encrypt ,
 135 .Fn setkey ,
 136 .Fn des_setkey
 137 and
 138 .Fn des_cipher
 139 provide access to the
 140 .Tn DES
 141 algorithm itself.
 142 .Fn setkey
 143 is passed a 64-byte array of binary values (numeric 0 or 1).
 144 A 56-bit key is extracted from this array by dividing the
 145 array into groups of 8, and ignoring the last bit in each group.
 146 That bit is reserved for a byte parity check by DES, but is ignored
 147 by these functions.
 148 .Pp
 149 The
 150 .Fa block
 151 argument to
 152 .Fn encrypt
 153 is also a 64-byte array of binary values.
 154 If the value of
 155 .Fa flag
 156 is 0,
 157 .Fa block
 158 is encrypted otherwise it is decrypted.
 159 The result is returned in the original array
 160 .Fa block
 161 after using the key specified by
 162 .Fn setkey
 163 to process it.
 164 .Pp
 165 The argument to
 166 .Fn des_setkey
 167 is a character array of length 8.
 168 The least significant bit (the parity bit) in each character is ignored,
 169 and the remaining bits are concatenated to form a 56-bit key.
 170 The function
 171 .Fn des_cipher
 172 encrypts (or decrypts if
 173 .Fa count
 174 is negative) the 64-bits stored in the 8 characters at
 175 .Fa in
 176 using
 177 .Xr abs 3
 178 of
 179 .Fa count
 180 iterations of
 181 .Tn DES
 182 and stores the 64-bit result in the 8 characters at
 183 .Fa out
 184 (which may be the same as
 185 .Fa in
 186 ).
 187 The
 188 .Fa salt
 189 specifies perturbations to the
 190 .Tn DES
 191 E-box output as described above.
 192 .Pp
 193 The function
 194 .Fn crypt
 195 returns a pointer to the encrypted value on success, and NULL on failure.
 196 The functions
 197 .Fn setkey ,
 198 .Fn encrypt ,
 199 .Fn des_setkey ,
 200 and
 201 .Fn des_cipher
 202 return 0 on success and 1 on failure.
 203 .Pp
 204 The
 205 .Fn crypt ,
 206 .Fn setkey
 207 and
 208 .Fn des_setkey
 209 functions all manipulate the same key space.
 210 .Sh SEE ALSO
 211 .Xr login 1 ,
 212 .Xr passwd 1 ,
 213 .Xr getpass 3 ,
 214 .Xr passwd 5
 215 .Sh BUGS
 216 The
 217 .Fn crypt
 218 function returns a pointer to static data, and subsequent calls to
 219 .Fn crypt
 220 will modify the same object.
 221 .Sh HISTORY
 222 A rotor-based
 223 .Fn crypt
 224 function appeared in
 225 .At v6 .
 226 The current style
 227 .Fn crypt
 228 first appeared in
 229 .At v7 .
 230 .Pp
 231 This library (FreeSec 1.0) was developed outside the United States of America
 232 as an unencumbered replacement for the U.S.-only libcrypt encryption
 233 library.
 234 Programs linked against the
 235 .Fn crypt
 236 interface may be exported from the U.S.A. only if they use
 237 .Fn crypt
 238 solely for authentication purposes and avoid use of
 239 the other programmer interfaces listed above. Special care has been taken
 240 in the library so that programs which only use the
 241 .Fn crypt
 242 interface do not pull in the other components.
 243 .Sh AUTHOR
 244 David Burren <davidb@werj.com.au>