lib/libcrypt/crypt.3

   1 .\"     $NetBSD: crypt.3,v 1.19 2005/08/16 10:10:16 drochner Exp $
   2 .\"
   3 .\" Copyright (c) 1989, 1991, 1993
   4 .\"     The Regents of the University of California.  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 .\" 3. Neither the name of the University nor the names of its 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 REGENTS 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 REGENTS 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 .\"     @(#)crypt.3     8.2 (Berkeley) 12/11/93
  31 .\"
  32 .Dd September 4, 2005
  33 .Dt CRYPT 3
  34 .Os
  35 .Sh NAME
  36 .Nm crypt ,
  37 .Nm setkey ,
  38 .Nm encrypt ,
  39 .Nm des_setkey ,
  40 .Nm des_cipher
  41 .Nd password encryption
  42 .Sh LIBRARY
  43 .Lb libcrypt
  44 .Sh SYNOPSIS
  45 .In unistd.h
  46 .Ft char
  47 .Fn *crypt "const char *key" "const char *setting"
  48 .Ft int
  49 .Fn encrypt "char *block" "int flag"
  50 .Ft int
  51 .Fn des_setkey "const char *key"
  52 .Ft int
  53 .Fn des_cipher "const char *in" "char *out" "long salt" "int count"
  54 .In stdlib.h
  55 .Ft int
  56 .Fn setkey "const char *key"
  57 .Sh DESCRIPTION
  58 The
  59 .Fn crypt
  60 function
  61 performs password encryption.
  62 The encryption scheme used by
  63 .Fn crypt
  64 is dependent upon the contents of the
  65 .Dv NUL Ns -terminated
  66 string
  67 .Ar setting .
  68 If it begins
  69 with a string character
  70 .Pq Ql $
  71 and a number then a different algorithm is used depending on the number.
  72 At the moment a
  73 .Ql $1
  74 chooses MD5 hashing and a
  75 .Ql $2
  76 chooses Blowfish hashing; see below for more information.
  77 If
  78 .Ar setting
  79 begins with the ``_'' character, DES encryption with a user specified number
  80 of perturbations is selected.
  81 If
  82 .Ar setting
  83 begins with any other character, DES encryption with a fixed number
  84 of perturbations is selected.
  85 .Ss DES encryption
  86 The DES encryption scheme is derived from the
  87 .Tn NBS
  88 Data Encryption Standard.
  89 Additional code has been added to deter key search attempts and to use
  90 stronger hashing algorithms.
  91 In the DES case, the second argument to
  92 .Fn crypt
  93 is a character array, 9 bytes in length, consisting of an underscore (``_'')
  94 followed by 4 bytes of iteration count and 4 bytes of salt.
  95 Both the iteration
  96 .Fa count
  97 and the
  98 .Fa salt
  99 are encoded with 6 bits per character, least significant bits first.
 100 The values 0 to 63 are encoded by the characters ``./0-9A-Za-z'',
 101 respectively.
 102 .Pp
 103 The
 104 .Fa salt
 105 is used to induce disorder in to the
 106 .Tn DES
 107 algorithm
 108 in one of 16777216
 109 possible ways
 110 (specifically, if bit
 111 .Em i
 112 of the
 113 .Ar salt
 114 is set then bits
 115 .Em i
 116 and
 117 .Em i+24
 118 are swapped in the
 119 .Tn DES
 120 ``E'' box output).
 121 The
 122 .Ar key
 123 is divided into groups of 8 characters (a short final group is null-padded)
 124 and the low-order 7 bits of each character (56 bits per group) are
 125 used to form the DES key as follows: the first group of 56 bits becomes the
 126 initial DES key.
 127 For each additional group, the XOR of the group bits and the encryption of
 128 the DES key with itself becomes the next DES key.
 129 Then the final DES key is used to perform
 130 .Ar count
 131 cumulative encryptions of a 64-bit constant.
 132 The value returned is a
 133 .Dv NUL Ns -terminated
 134 string, 20 bytes in length, consisting
 135 of the
 136 .Ar setting
 137 followed by the encoded 64-bit encryption.
 138 .Pp
 139 For compatibility with historical versions of
 140 .Xr crypt 3 ,
 141 the
 142 .Ar setting
 143 may consist of 2 bytes of salt, encoded as above, in which case an
 144 iteration
 145 .Ar count
 146 of 25 is used, fewer perturbations of
 147 .Tn DES
 148 are available, at most 8
 149 characters of
 150 .Ar key
 151 are used, and the returned value is a
 152 .Dv NUL Ns -terminated
 153 string 13 bytes in length.
 154 .Pp
 155 The
 156 functions
 157 .Fn encrypt ,
 158 .Fn setkey ,
 159 .Fn des_setkey
 160 and
 161 .Fn des_cipher
 162 allow limited access to the
 163 .Tn DES
 164 algorithm itself.
 165 The
 166 .Ar key
 167 argument to
 168 .Fn setkey
 169 is a 64 character array of
 170 binary values (numeric 0 or 1).
 171 A 56-bit key is derived from this array by dividing the array
 172 into groups of 8 and ignoring the last bit in each group.
 173 .Pp
 174 The
 175 .Fn encrypt
 176 argument
 177 .Fa block
 178 is also a 64 character array of
 179 binary values.
 180 If the value of
 181 .Fa flag
 182 is 0,
 183 the argument
 184 .Fa block
 185 is encrypted, otherwise it
 186 is decrypted.
 187 The encryption or decryption is returned in the original
 188 array
 189 .Fa block
 190 after using the
 191 key specified
 192 by
 193 .Fn setkey
 194 to process it.
 195 .Pp
 196 The
 197 .Fn des_setkey
 198 and
 199 .Fn des_cipher
 200 functions are faster but less portable than
 201 .Fn setkey
 202 and
 203 .Fn encrypt .
 204 The argument to
 205 .Fn des_setkey
 206 is a character array of length 8.
 207 The
 208 .Em least
 209 significant bit in each character is ignored and the next 7 bits of each
 210 character are concatenated to yield a 56-bit key.
 211 The function
 212 .Fn des_cipher
 213 encrypts (or decrypts if
 214 .Fa count
 215 is negative) the 64-bits stored in the 8 characters at
 216 .Fa in
 217 using
 218 .Xr abs 3
 219 of
 220 .Fa count
 221 iterations of
 222 .Tn DES
 223 and stores the 64-bit result in the 8 characters at
 224 .Fa out .
 225 The
 226 .Fa salt
 227 specifies perturbations to
 228 .Tn DES
 229 as described above.
 230 .Ss MD5 encryption
 231 For the
 232 .Tn MD5
 233 encryption scheme, the version number (in this case ``1''),
 234 .Fa salt
 235 and the hashed password are separated
 236 by the ``$'' character.
 237 A valid password looks like this:
 238 .Pp
 239 ``$1$2qGr5PPQ$eT08WBFev3RPLNChixg0H.''.
 240 .Pp
 241 The entire password string is passed as
 242 .Fa setting
 243 for interpretation.
 244 .Ss "Blowfish" crypt
 245 The
 246 .Tn Blowfish
 247 version of crypt has 128 bits of
 248 .Fa salt
 249 in order to make building dictionaries of common passwords space consuming.
 250 The initial state of the
 251 .Tn Blowfish
 252 cipher is expanded using the
 253 .Fa salt
 254 and the
 255 .Fa password
 256 repeating the process a variable number of rounds, which is encoded in
 257 the password string.
 258 The maximum password length is 72.
 259 The final Blowfish password entry is created by encrypting the string
 260 .Pp
 261 .Dq OrpheanBeholderScryDoubt
 262 .Pp
 263 with the
 264 .Tn Blowfish
 265 state 64 times.
 266 .Pp
 267 The version number, the logarithm of the number of rounds and
 268 the concatenation of salt and hashed password are separated by the
 269 .Ql $
 270 character.
 271 An encoded
 272 .Sq 8
 273 would specify 256 rounds.
 274 A valid Blowfish password looks like this:
 275 .Pp
 276 .Dq $2a$12$eIAq8PR8sIUnJ1HaohxX2O9x9Qlm2vK97LJ5dsXdmB.eXF42qjchC .
 277 .Pp
 278 The whole Blowfish password string is passed as
 279 .Fa setting
 280 for interpretation.
 281 .Sh RETURN VALUES
 282 The function
 283 .Fn crypt
 284 returns a pointer to the encrypted value on success and NULL on failure.
 285 The functions
 286 .Fn setkey ,
 287 .Fn encrypt ,
 288 .Fn des_setkey ,
 289 and
 290 .Fn des_cipher
 291 return 0 on success and 1 on failure.
 292 Historically, the functions
 293 .Fn setkey
 294 and
 295 .Fn encrypt
 296 did not return any value.
 297 They have been provided return values primarily to distinguish
 298 implementations where hardware support is provided but not
 299 available or where the DES encryption is not available due to the
 300 usual political silliness.
 301 .Sh SEE ALSO
 302 .Xr login 1 ,
 303 .Xr passwd 1 ,
 304 .Xr pwhash 1 ,
 305 .Xr getpass 3 ,
 306 .Xr md5 3 ,
 307 .Xr passwd 5 ,
 308 .Xr passwd.conf 5
 309 .Rs
 310 .%T "Mathematical Cryptology for Computer Scientists and Mathematicians"
 311 .%A Wayne Patterson
 312 .%D 1987
 313 .%N ISBN 0-8476-7438-X
 314 .Re
 315 .Rs
 316 .%T "Password Security: A Case History"
 317 .%A R. Morris
 318 .%A Ken Thompson
 319 .%J "Communications of the ACM"
 320 .%V vol. 22
 321 .%P pp. 594-597
 322 .%D Nov. 1979
 323 .Re
 324 .Rs
 325 .%T "DES will be Totally Insecure within Ten Years"
 326 .%A M.E. Hellman
 327 .%J "IEEE Spectrum"
 328 .%V vol. 16
 329 .%P pp. 32-39
 330 .%D July 1979
 331 .Re
 332 .Sh HISTORY
 333 A rotor-based
 334 .Fn crypt
 335 function appeared in
 336 .At v6 .
 337 The current style
 338 .Fn crypt
 339 first appeared in
 340 .At v7 .
 341 .Sh BUGS
 342 Dropping the
 343 .Em least
 344 significant bit in each character of the argument to
 345 .Fn des_setkey
 346 is ridiculous.
 347 .Pp
 348 The
 349 .Fn crypt
 350 function leaves its result in an internal static object and returns
 351 a pointer to that object.
 352 Subsequent calls to
 353 .Fn crypt
 354 will modify the same object.