1.\" FreeSec: libcrypt for NetBSD 2.\" 3.\" Copyright (c) 1994 David Burren 4.\" 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.\" 4. Neither the name of the author nor the names of other contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" $FreeBSD$ 31.\" 32.\" Manual page, using -mandoc macros 33.\" 34.Dd January 19, 1997 35.Dt CRYPT 3 36.Os 37.Sh NAME 38.Nm crypt 39.Nd Trapdoor encryption 40.Sh LIBRARY 41.Lb libcrypt 42.Sh SYNOPSIS 43.In unistd.h 44.Ft char * 45.Fn crypt "const char *key" "const char *salt" 46.Ft const char * 47.Fn crypt_get_format "void" 48.Ft int 49.Fn crypt_set_format "const char *string" 50.Sh DESCRIPTION 51The 52.Fn crypt 53function performs password hashing with additional code added to 54deter key search attempts. 55Different algorithms can be used to 56in the hash. 57.\" 58.\" NOTICE: 59.\" If you add more algorithms, make sure to update this list 60.\" and the default used for the Traditional format, below. 61.\" 62Currently these include the 63.Tn NBS 64.Tn Data Encryption Standard (DES) , 65.Tn MD5 66hash, 67.Tn NT-Hash 68(compatible with Microsoft's NT scheme) 69and 70.Tn Blowfish . 71The algorithm used will depend upon the format of the Salt (following 72the Modular Crypt Format (MCF)), if 73.Tn DES 74and/or 75.Tn Blowfish 76is installed or not, and whether 77.Fn crypt_set_format 78has been called to change the default. 79.Pp 80The first argument to 81.Nm 82is the data to hash (usually a password), in a 83.Dv null Ns -terminated 84string. 85The second is the salt, in one of three forms: 86.Pp 87.Bl -tag -width Traditional -compact -offset indent 88.It Extended 89If it begins with an underscore 90.Pq Dq _ 91then the 92.Tn DES 93Extended Format 94is used in interpreting both the key and the salt, as outlined below. 95.It Modular 96If it begins with the string 97.Dq $digit$ 98then the Modular Crypt Format is used, as outlined below. 99.It Traditional 100If neither of the above is true, it assumes the Traditional Format, 101using the entire string as the salt (or the first portion). 102.El 103.Pp 104All routines are designed to be time-consuming. 105A brief test on a 106.Tn Pentium 107166/MMX shows the 108.Tn DES 109crypt to do approximately 2640 crypts 110a CPU second and MD5 to do about 62 crypts a CPU second. 111.Ss DES Extended Format: 112.Pp 113The 114.Ar key 115is divided into groups of 8 characters (the last group is null-padded) 116and the low-order 7 bits of each character (56 bits per group) are 117used to form the 118.Tn DES 119key as follows: 120the first group of 56 bits becomes the initial 121.Tn DES 122key. 123For each additional group, the XOR of the encryption of the current 124.Tn DES 125key with itself and the group bits becomes the next 126.Tn DES 127key. 128.Pp 129The salt is a 9-character array consisting of an underscore followed 130by 4 bytes of iteration count and 4 bytes of salt. 131These are encoded as printable characters, 6 bits per character, 132least significant character first. 133The values 0 to 63 are encoded as ``./0-9A-Za-z''. 134This allows 24 bits for both 135.Fa count 136and 137.Fa salt . 138.Pp 139The 140.Fa salt 141introduces disorder in the 142.Tn DES 143algorithm in one of 16777216 or 4096 possible ways 144(i.e., with 24 or 12 bits: if bit 145.Em i 146of the 147.Ar salt 148is set, then bits 149.Em i 150and 151.Em i+24 152are swapped in the 153.Tn DES 154E-box output). 155.Pp 156The 157.Tn DES 158key is used to encrypt a 64-bit constant using 159.Ar count 160iterations of 161.Tn DES . 162The value returned is a 163.Dv null Ns -terminated 164string, 20 or 13 bytes (plus null) in length, consisting of the 165.Ar salt 166followed by the encoded 64-bit encryption. 167.Ss "Modular" crypt: 168.Pp 169If the salt begins with the string 170.Fa $digit$ 171then the Modular Crypt Format is used. 172The 173.Fa digit 174represents which algorithm is used in encryption. 175Following the token is 176the actual salt to use in the encryption. 177The length of the salt is limited 178to 8 characters--because the length of the returned output is also limited 179(_PASSWORD_LEN). 180The salt must be terminated with the end of the string 181(NULL) or a dollar sign. 182Any characters after the dollar sign are ignored. 183.Pp 184Currently supported algorithms are: 185.Pp 186.Bl -enum -compact -offset indent 187.It 188MD5 189.It 190Blowfish 191.It 192NT-Hash 193.El 194.Pp 195Other crypt formats may be easily added. 196An example salt would be: 197.Bl -tag -offset indent 198.It Cm "$4$thesalt$rest" 199.El 200.Pp 201.Ss "Traditional" crypt: 202.Pp 203The algorithm used will depend upon whether 204.Fn crypt_set_format 205has been called and whether a global default format has been specified. 206Unless a global default has been specified or 207.Fn crypt_set_format 208has set the format to something else, the built-in default format is 209used. 210This is currently 211.\" 212.\" NOTICE: Also make sure to update this 213.\" 214DES 215if it is available, or MD5 if not. 216.Pp 217How the salt is used will depend upon the algorithm for the hash. 218For 219best results, specify at least two characters of salt. 220.Pp 221The 222.Fn crypt_get_format 223function returns a constant string that represents the name of the 224algorithm currently used. 225Valid values are 226.\" 227.\" NOTICE: Also make sure to update this, too, as well 228.\" 229.Ql des , 230.Ql blf , 231.Ql md5 232and 233.Ql nth . 234.Pp 235The 236.Fn crypt_set_format 237function sets the default encoding format according to the supplied 238.Fa string . 239.Pp 240The global default format can be set using the 241.Pa /etc/auth.conf 242file using the 243.Va crypt_default 244property. 245.Sh RETURN VALUES 246The 247.Fn crypt 248function returns a pointer to the encrypted value on success, and NULL on 249failure. 250Note: this is not a standard behaviour, AT&T 251.Fn crypt 252will always return a pointer to a string. 253.Pp 254The 255.Fn crypt_set_format 256function will return 1 if the supplied encoding format was valid. 257Otherwise, a value of 0 is returned. 258.Sh SEE ALSO 259.Xr login 1 , 260.Xr passwd 1 , 261.Xr auth_getval 3 , 262.Xr cipher 3 , 263.Xr getpass 3 , 264.Xr auth.conf 5 , 265.Xr passwd 5 266.Sh BUGS 267The 268.Fn crypt 269function returns a pointer to static data, and subsequent calls to 270.Fn crypt 271will modify the same data. 272Likewise, 273.Fn crypt_set_format 274modifies static data. 275.Pp 276The NT-hash scheme does not use a salt, 277and is not hard 278for a competent attacker 279to break. 280Its use is not recommended. 281.Sh HISTORY 282A rotor-based 283.Fn crypt 284function appeared in 285.At v6 . 286The current style 287.Fn crypt 288first appeared in 289.At v7 . 290.Pp 291The 292.Tn DES 293section of the code (FreeSec 1.0) was developed outside the United 294States of America as an unencumbered replacement for the U.S.-only 295.Nx 296libcrypt encryption library. 297.Sh AUTHORS 298.An -nosplit 299Originally written by 300.An David Burren Aq davidb@werj.com.au , 301later additions and changes by 302.An Poul-Henning Kamp , 303.An Mark R V Murray , 304.An Michael Bretterklieber , 305.An Kris Kennaway , 306.An Brian Feldman , 307.An Paul Herman 308and 309.An Niels Provos . 310