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