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