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 April 9, 2011 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.It 192SHA-256 193.It 194SHA-512 195.El 196.Pp 197Other crypt formats may be easily added. 198An example salt would be: 199.Bl -tag -offset indent 200.It Cm "$4$thesalt$rest" 201.El 202.Pp 203.Ss "Traditional" crypt: 204.Pp 205The algorithm used will depend upon whether 206.Fn crypt_set_format 207has been called and whether a global default format has been specified. 208Unless a global default has been specified or 209.Fn crypt_set_format 210has set the format to something else, the built-in default format is 211used. 212This is currently 213.\" 214.\" NOTICE: Also make sure to update this 215.\" 216DES 217if it is available, or MD5 if not. 218.Pp 219How the salt is used will depend upon the algorithm for the hash. 220For 221best results, specify at least two characters of salt. 222.Pp 223The 224.Fn crypt_get_format 225function returns a constant string that represents the name of the 226algorithm currently used. 227Valid values are 228.\" 229.\" NOTICE: Also make sure to update this, too, as well 230.\" 231.Ql des , 232.Ql blf , 233.Ql md5 , 234.Ql sha256 , 235.Ql sha512 236and 237.Ql nth . 238.Pp 239The 240.Fn crypt_set_format 241function sets the default encoding format according to the supplied 242.Fa string . 243.Pp 244The global default format can be set using the 245.Pa /etc/auth.conf 246file using the 247.Va crypt_default 248property. 249.Sh RETURN VALUES 250The 251.Fn crypt 252function returns a pointer to the encrypted value on success, and NULL on 253failure. 254Note: this is not a standard behaviour, AT&T 255.Fn crypt 256will always return a pointer to a string. 257.Pp 258The 259.Fn crypt_set_format 260function will return 1 if the supplied encoding format was valid. 261Otherwise, a value of 0 is returned. 262.Sh SEE ALSO 263.Xr login 1 , 264.Xr passwd 1 , 265.Xr auth_getval 3 , 266.Xr getpass 3 , 267.Xr auth.conf 5 , 268.Xr passwd 5 269.Sh HISTORY 270A rotor-based 271.Fn crypt 272function appeared in 273.At v6 . 274The current style 275.Fn crypt 276first appeared in 277.At v7 . 278.Pp 279The 280.Tn DES 281section of the code (FreeSec 1.0) was developed outside the United 282States of America as an unencumbered replacement for the U.S.-only 283.Nx 284libcrypt encryption library. 285.Sh AUTHORS 286.An -nosplit 287Originally written by 288.An David Burren Aq davidb@werj.com.au , 289later additions and changes by 290.An Poul-Henning Kamp , 291.An Mark R V Murray , 292.An Michael Bretterklieber , 293.An Kris Kennaway , 294.An Brian Feldman , 295.An Paul Herman 296and 297.An Niels Provos . 298.Sh BUGS 299The 300.Fn crypt 301function returns a pointer to static data, and subsequent calls to 302.Fn crypt 303will modify the same data. 304Likewise, 305.Fn crypt_set_format 306modifies static data. 307.Pp 308The NT-hash scheme does not use a salt, 309and is not hard 310for a competent attacker 311to break. 312Its use is not recommended. 313