1.\" Copyright (c) 1989, 1991 The Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)crypt.3 6.7.1.1 (Berkeley) 08/19/91 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 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 fails. 139The encryption is returned in the original 140array 141.Fa block 142after using the 143key specified 144by 145.Fn setkey 146to process it. 147.Pp 148The 149.Fn des_setkey 150and 151.Fn des_cipher 152functions are faster but less portable than 153.Fn setkey 154and 155.Fn encrypt . 156The argument to 157.Fn des_setkey 158is a character array of length 8. 159The 160.Em least 161significant bit in each character is ignored and the next 7 bits of each 162character are concatenated to yield a 56-bit key. 163The function 164.Fn des_cipher 165encrypts the 64-bits stored in the 8 characters at 166.Fa in 167using 168.Xr abs 3 169of 170.Fa count 171iterations of 172.Tn DES 173and stores the 64-bit result in the 8 characters at 174.Fa out . 175The 176.Fa salt 177specifies perturbations to 178.Tn DES 179as described above. 180.Pp 181The function 182.Fn crypt 183returns a pointer to the encrypted value on success and NULL on failure. 184The functions 185.Fn setkey , 186.Fn encrypt , 187.Fn des_setkey , 188and 189.Fn des_cipher 190return 0 on success and 1 on failure. 191Historically, the functions 192.Fn setkey 193and 194.Fn encrypt 195did not return any value. 196They have been provided return values primarily to distinguish 197implementations where hardware support is provided but not 198available or where the DES encryption is not available due to the 199usual political silliness. 200.Sh SEE ALSO 201.Xr login 1 , 202.Xr passwd 1 , 203.Xr getpass 3 , 204.Xr passwd 5 205.sp 206.Rs 207.%T "Mathematical Cryptology for Computer Scientists and Mathematicians" 208.%A Wayne Patterson 209.%D 1987 210.%N ISBN 0-8476-7438-X 211.Re 212.Rs 213.%T "Password Security: A Case History" 214.%A R. Morris 215.%A Ken Thompson 216.%J "Communications of the ACM" 217.%V vol. 22 218.%P pp. 594-597 219.%D Nov. 1979 220.Re 221.Rs 222.%T "DES will be Totally Insecure within Ten Years" 223.%A M.E. Hellman 224.%J "IEEE Spectrum" 225.%V vol. 16 226.%P pp. 32-39 227.%D July 1979 228.Re 229.Sh HISTORY 230A rotor-based 231.Fn crypt 232function appeared in 233.At v6 . 234The current style 235.Fn crypt 236first appeared in 237.At v7 . 238.Sh BUGS 239Dropping the 240.Em least 241significant bit in each character of the argument to 242.Fn des_setkey 243is ridiculous. 244.Pp 245The 246.Fn crypt 247function leaves its result in an internal static object and returns 248a pointer to that object. 249Subsequent calls to 250.Fn crypt 251will modify the same object. 252