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