1.\" Copyright (c) 1989, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)crypt.3 8.2 (Berkeley) 12/11/93 7.\" 8.Dd 9.Dt CRYPT 3 10.Os 11.Sh NAME 12.Nm crypt , 13.Nm setkey , 14.Nm encrypt , 15.Nm des_setkey , 16.Nm des_cipher 17.Nd DES encryption 18.Sh SYNOPSIS 19.Ft char 20.Fn *crypt "const char *key" "const char *setting" 21.Ft int 22.Fn setkey "char *key" 23.Ft int 24.Fn encrypt "char *block" "int flag" 25.Ft int 26.Fn des_setkey "const char *key" 27.Ft int 28.Fn des_cipher "const char *in" "char *out" "long salt" "int count" 29.Sh DESCRIPTION 30The 31.Xr crypt 32function 33performs password encryption. 34It is derived from the 35.Tn NBS 36Data Encryption Standard. 37Additional code has been added to deter 38key search attempts. 39The first argument to 40.Nm crypt 41is 42a 43.Dv NUL Ns -terminated 44string (normally a password typed by a user). 45The second is a character array, 9 bytes in length, consisting of an 46underscore (``_'') followed by 4 bytes of iteration count and 4 bytes 47of salt. 48Both the iteration 49.Fa count 50and the 51.Fa salt 52are encoded with 6 bits per character, least significant bits first. 53The values 0 to 63 are encoded by the characters ``./0-9A-Za-z'', 54respectively. 55.Pp 56The 57.Fa salt 58is used to induce disorder in to the 59.Tn DES 60algorithm 61in one of 16777216 62possible ways 63(specifically, if bit 64.Em i 65of the 66.Ar salt 67is set then bits 68.Em i 69and 70.Em i+24 71are swapped in the 72.Tn DES 73``E'' box output). 74The 75.Ar key 76is divided into groups of 8 characters (a short final group is null-padded) 77and the low-order 7 bits of each character (56 bits per group) are 78used to form the DES key as follows: the first group of 56 bits becomes the 79initial DES key. 80For each additional group, the XOR of the group bits and the encryption of 81the DES key with itself becomes the next DES key. 82Then the final DES key is used to perform 83.Ar count 84cumulative encryptions of a 64-bit constant. 85The value returned is a 86.Dv NUL Ns -terminated 87string, 20 bytes in length, consisting 88of the 89.Ar setting 90followed by the encoded 64-bit encryption. 91.Pp 92For compatibility with historical versions of 93.Xr crypt 3 , 94the 95.Ar setting 96may consist of 2 bytes of salt, encoded as above, in which case an 97iteration 98.Ar count 99of 25 is used, fewer perturbations of 100.Tn DES 101are available, at most 8 102characters of 103.Ar key 104are used, and the returned value is a 105.Dv NUL Ns -terminated 106string 13 bytes in length. 107.Pp 108The 109functions, 110.Fn encrypt , 111.Fn setkey , 112.Fn des_setkey 113and 114.Fn des_cipher 115allow limited access to the 116.Tn DES 117algorithm itself. 118The 119.Ar key 120argument to 121.Fn setkey 122is a 64 character array of 123binary values (numeric 0 or 1). 124A 56-bit key is derived from this array by dividing the array 125into groups of 8 and ignoring the last bit in each group. 126.Pp 127The 128.Fn encrypt 129argument 130.Fa block 131is also a 64 character array of 132binary values. 133If the value of 134.Fa flag 135is 0, 136the argument 137.Fa block 138is encrypted, otherwise it 139is decrypted. 140The encryption or decryption is returned in the original 141array 142.Fa block 143after using the 144key specified 145by 146.Fn setkey 147to process it. 148.Pp 149The 150.Fn des_setkey 151and 152.Fn des_cipher 153functions are faster but less portable than 154.Fn setkey 155and 156.Fn encrypt . 157The argument to 158.Fn des_setkey 159is a character array of length 8. 160The 161.Em least 162significant bit in each character is ignored and the next 7 bits of each 163character are concatenated to yield a 56-bit key. 164The function 165.Fn des_cipher 166encrypts (or decrypts if 167.Fa count 168is negative) the 64-bits stored in the 8 characters at 169.Fa in 170using 171.Xr abs 3 172of 173.Fa count 174iterations of 175.Tn DES 176and stores the 64-bit result in the 8 characters at 177.Fa out . 178The 179.Fa salt 180specifies perturbations to 181.Tn DES 182as described above. 183.Pp 184The function 185.Fn crypt 186returns a pointer to the encrypted value on success and NULL on failure. 187The functions 188.Fn setkey , 189.Fn encrypt , 190.Fn des_setkey , 191and 192.Fn des_cipher 193return 0 on success and 1 on failure. 194Historically, the functions 195.Fn setkey 196and 197.Fn encrypt 198did not return any value. 199They have been provided return values primarily to distinguish 200implementations where hardware support is provided but not 201available or where the DES encryption is not available due to the 202usual political silliness. 203.Sh SEE ALSO 204.Xr login 1 , 205.Xr passwd 1 , 206.Xr getpass 3 , 207.Xr passwd 5 208.sp 209.Rs 210.%T "Mathematical Cryptology for Computer Scientists and Mathematicians" 211.%A Wayne Patterson 212.%D 1987 213.%N ISBN 0-8476-7438-X 214.Re 215.Rs 216.%T "Password Security: A Case History" 217.%A R. Morris 218.%A Ken Thompson 219.%J "Communications of the ACM" 220.%V vol. 22 221.%P pp. 594-597 222.%D Nov. 1979 223.Re 224.Rs 225.%T "DES will be Totally Insecure within Ten Years" 226.%A M.E. Hellman 227.%J "IEEE Spectrum" 228.%V vol. 16 229.%P pp. 32-39 230.%D July 1979 231.Re 232.Sh HISTORY 233A rotor-based 234.Fn crypt 235function appeared in 236.At v6 . 237The current style 238.Fn crypt 239first appeared in 240.At v7 . 241.Sh BUGS 242Dropping the 243.Em least 244significant bit in each character of the argument to 245.Fn des_setkey 246is ridiculous. 247.Pp 248The 249.Fn crypt 250function leaves its result in an internal static object and returns 251a pointer to that object. 252Subsequent calls to 253.Fn crypt 254will modify the same object. 255