1.\" $NetBSD: crypt.3,v 1.14 2002/05/24 04:02:49 itojun 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. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)crypt.3 8.2 (Berkeley) 12/11/93 35.\" 36.Dd December 11, 1993 37.Dt CRYPT 3 38.Os 39.Sh NAME 40.Nm crypt , 41.Nm setkey , 42.Nm encrypt , 43.Nm des_setkey , 44.Nm des_cipher 45.Nd password encryption 46.Sh LIBRARY 47.Lb libcrypt 48.Sh SYNOPSIS 49.Fd #include \*[Lt]unistd.h\*[Gt] 50.Ft char 51.Fn *crypt "const char *key" "const char *setting" 52.Ft int 53.Fn encrypt "char *block" "int flag" 54.Ft int 55.Fn des_setkey "const char *key" 56.Ft int 57.Fn des_cipher "const char *in" "char *out" "long salt" "int count" 58.Fd #include \*[Lt]stdlib.h\*[Gt] 59.Ft int 60.Fn setkey "const char *key" 61.Sh DESCRIPTION 62The 63.Fn crypt 64function 65performs password encryption. The encryption scheme used by 66.Fn crypt 67is dependent upon the contents of the 68.Dv NUL Ns -terminated 69string 70.Ar setting . 71If it begins 72with a string character 73.Pq Ql $ 74and a number then a different algorithm is used depending on the number. 75At the moment a 76.Ql $1 77chooses MD5 hashing and a 78.Ql $2 79chooses Blowfish hashing; see below for more information. 80If 81.Ar setting 82begins with the ``_'' character, DES encryption with a user specified number 83of perturbations is selected. If 84.Ar setting 85begins with any other character, DES encryption with a fixed number 86of perturbations is selected. 87.Ss DES encryption 88The DES encryption scheme is derived from the 89.Tn NBS 90Data Encryption Standard. 91Additional code has been added to deter key search attempts and to use 92stronger hashing algorithms. In the DES case, the first argument to 93.Fn crypt 94is a character array, 9 bytes in length, consisting of an underscore (``_'') 95followed by 4 bytes of iteration count and 4 bytes of salt. 96Both the iteration 97.Fa count 98and the 99.Fa salt 100are encoded with 6 bits per character, least significant bits first. 101The values 0 to 63 are encoded by the characters ``./0-9A-Za-z'', 102respectively. 103.Pp 104The 105.Fa salt 106is used to induce disorder in to the 107.Tn DES 108algorithm 109in one of 16777216 110possible ways 111(specifically, if bit 112.Em i 113of the 114.Ar salt 115is set then bits 116.Em i 117and 118.Em i+24 119are swapped in the 120.Tn DES 121``E'' box output). 122The 123.Ar key 124is divided into groups of 8 characters (a short final group is null-padded) 125and the low-order 7 bits of each character (56 bits per group) are 126used to form the DES key as follows: the first group of 56 bits becomes the 127initial DES key. 128For each additional group, the XOR of the group bits and the encryption of 129the DES key with itself becomes the next DES key. 130Then the final DES key is used to perform 131.Ar count 132cumulative encryptions of a 64-bit constant. 133The value returned is a 134.Dv NUL Ns -terminated 135string, 20 bytes in length, consisting 136of the 137.Ar setting 138followed by the encoded 64-bit encryption. 139.Pp 140For compatibility with historical versions of 141.Xr crypt 3 , 142the 143.Ar setting 144may consist of 2 bytes of salt, encoded as above, in which case an 145iteration 146.Ar count 147of 25 is used, fewer perturbations of 148.Tn DES 149are available, at most 8 150characters of 151.Ar key 152are used, and the returned value is a 153.Dv NUL Ns -terminated 154string 13 bytes in length. 155.Pp 156The 157functions 158.Fn encrypt , 159.Fn setkey , 160.Fn des_setkey 161and 162.Fn des_cipher 163allow limited access to the 164.Tn DES 165algorithm itself. 166The 167.Ar key 168argument to 169.Fn setkey 170is a 64 character array of 171binary values (numeric 0 or 1). 172A 56-bit key is derived from this array by dividing the array 173into groups of 8 and ignoring the last bit in each group. 174.Pp 175The 176.Fn encrypt 177argument 178.Fa block 179is also a 64 character array of 180binary values. 181If the value of 182.Fa flag 183is 0, 184the argument 185.Fa block 186is encrypted, otherwise it 187is decrypted. 188The encryption or decryption is returned in the original 189array 190.Fa block 191after using the 192key specified 193by 194.Fn setkey 195to process it. 196.Pp 197The 198.Fn des_setkey 199and 200.Fn des_cipher 201functions are faster but less portable than 202.Fn setkey 203and 204.Fn encrypt . 205The argument to 206.Fn des_setkey 207is a character array of length 8. 208The 209.Em least 210significant bit in each character is ignored and the next 7 bits of each 211character are concatenated to yield a 56-bit key. 212The function 213.Fn des_cipher 214encrypts (or decrypts if 215.Fa count 216is negative) the 64-bits stored in the 8 characters at 217.Fa in 218using 219.Xr abs 3 220of 221.Fa count 222iterations of 223.Tn DES 224and stores the 64-bit result in the 8 characters at 225.Fa out . 226The 227.Fa salt 228specifies perturbations to 229.Tn DES 230as described above. 231.Ss MD5 encryption 232For the 233.Tn MD5 234encryption scheme, the version number (in this case ``1''), 235.Fa salt 236and the hashed password are separated 237by the ``$'' character. A valid password looks like this: 238.Pp 239``$1$2qGr5PPQ$eT08WBFev3RPLNChixg0H.''. 240.Pp 241The entire password string is passed as 242.Fa setting 243for interpretation. 244.Ss "Blowfish" crypt 245The 246.Tn Blowfish 247version of crypt has 128 bits of 248.Fa salt 249in order to make building dictionaries of common passwords space consuming. 250The initial state of the 251.Tn Blowfish 252cipher is expanded using the 253.Fa salt 254and the 255.Fa password 256repeating the process a variable number of rounds, which is encoded in 257the password string. 258The maximum password length is 72. 259The final Blowfish password entry is created by encrypting the string 260.Pp 261.Dq OrpheanBeholderScryDoubt 262.Pp 263with the 264.Tn Blowfish 265state 64 times. 266.Pp 267The version number, the logarithm of the number of rounds and 268the concatenation of salt and hashed password are separated by the 269.Ql $ 270character. 271An encoded 272.Sq 8 273would specify 256 rounds. 274A valid Blowfish password looks like this: 275.Pp 276.Dq $2a$12$eIAq8PR8sIUnJ1HaohxX2O9x9Qlm2vK97LJ5dsXdmB.eXF42qjchC . 277.Pp 278The whole Blowfish password string is passed as 279.Fa setting 280for interpretation. 281.Sh RETURN VALUES 282The function 283.Fn crypt 284returns a pointer to the encrypted value on success and NULL on failure. 285The functions 286.Fn setkey , 287.Fn encrypt , 288.Fn des_setkey , 289and 290.Fn des_cipher 291return 0 on success and 1 on failure. 292Historically, the functions 293.Fn setkey 294and 295.Fn encrypt 296did not return any value. 297They have been provided return values primarily to distinguish 298implementations where hardware support is provided but not 299available or where the DES encryption is not available due to the 300usual political silliness. 301.Sh SEE ALSO 302.Xr login 1 , 303.Xr passwd 1 , 304.Xr getpass 3 , 305.Xr md5 3 , 306.Xr passwd 5 , 307.Xr passwd.conf 5 308.sp 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 333A rotor-based 334.Fn crypt 335function appeared in 336.At v6 . 337The current style 338.Fn crypt 339first appeared in 340.At v7 . 341.Sh BUGS 342Dropping the 343.Em least 344significant bit in each character of the argument to 345.Fn des_setkey 346is ridiculous. 347.Pp 348The 349.Fn crypt 350function leaves its result in an internal static object and returns 351a pointer to that object. 352Subsequent calls to 353.Fn crypt 354will modify the same object. 355