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: 110The 111.Ar key 112is divided into groups of 8 characters (the last group is null-padded) 113and the low-order 7 bits of each character (56 bits per group) are 114used to form the 115.Tn DES 116key as follows: 117the first group of 56 bits becomes the initial 118.Tn DES 119key. 120For each additional group, the XOR of the encryption of the current 121.Tn DES 122key with itself and the group bits becomes the next 123.Tn DES 124key. 125.Pp 126The salt is a 9-character array consisting of an underscore followed 127by 4 bytes of iteration count and 4 bytes of salt. 128These are encoded as printable characters, 6 bits per character, 129least significant character first. 130The values 0 to 63 are encoded as ``./0-9A-Za-z''. 131This allows 24 bits for both 132.Fa count 133and 134.Fa salt . 135.Pp 136The 137.Fa salt 138introduces disorder in the 139.Tn DES 140algorithm in one of 16777216 or 4096 possible ways 141(i.e., with 24 or 12 bits: if bit 142.Em i 143of the 144.Ar salt 145is set, then bits 146.Em i 147and 148.Em i+24 149are swapped in the 150.Tn DES 151E-box output). 152.Pp 153The 154.Tn DES 155key is used to encrypt a 64-bit constant using 156.Ar count 157iterations of 158.Tn DES . 159The value returned is a 160.Dv null Ns -terminated 161string, 20 or 13 bytes (plus null) in length, consisting of the 162.Ar salt 163followed by the encoded 64-bit encryption. 164.Ss "Modular" crypt: 165If the salt begins with the string 166.Fa $digit$ 167then the Modular Crypt Format is used. 168The 169.Fa digit 170represents which algorithm is used in encryption. 171Following the token is 172the actual salt to use in the encryption. 173The length of the salt is limited 174to 8 characters--because the length of the returned output is also limited 175(_PASSWORD_LEN). 176The salt must be terminated with the end of the string 177(NULL) or a dollar sign. 178Any characters after the dollar sign are ignored. 179.Pp 180Currently supported algorithms are: 181.Pp 182.Bl -enum -compact -offset indent 183.It 184MD5 185.It 186Blowfish 187.It 188NT-Hash 189.It 190(unused) 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 -width 6n -offset indent 200.It Cm "$4$thesalt$rest" 201.El 202.Ss "Traditional" crypt: 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 , 232.Ql sha256 , 233.Ql sha512 234and 235.Ql nth . 236.Pp 237The 238.Fn crypt_set_format 239function sets the default encoding format according to the supplied 240.Fa string . 241.Sh RETURN VALUES 242The 243.Fn crypt 244function returns a pointer to the encrypted value on success, and NULL on 245failure. 246Note: this is not a standard behaviour, AT&T 247.Fn crypt 248will always return a pointer to a string. 249.Pp 250The 251.Fn crypt_set_format 252function will return 1 if the supplied encoding format was valid. 253Otherwise, a value of 0 is returned. 254.Sh SEE ALSO 255.Xr login 1 , 256.Xr passwd 1 , 257.Xr getpass 3 , 258.Xr passwd 5 259.Sh HISTORY 260A rotor-based 261.Fn crypt 262function appeared in 263.At v6 . 264The current style 265.Fn crypt 266first appeared in 267.At v7 . 268.Pp 269The 270.Tn DES 271section of the code (FreeSec 1.0) was developed outside the United 272States of America as an unencumbered replacement for the U.S.-only 273.Nx 274libcrypt encryption library. 275.Sh AUTHORS 276.An -nosplit 277Originally written by 278.An David Burren Aq davidb@werj.com.au , 279later additions and changes by 280.An Poul-Henning Kamp , 281.An Mark R V Murray , 282.An Michael Bretterklieber , 283.An Kris Kennaway , 284.An Brian Feldman , 285.An Paul Herman 286and 287.An Niels Provos . 288.Sh BUGS 289The 290.Fn crypt 291function returns a pointer to static data, and subsequent calls to 292.Fn crypt 293will modify the same data. 294Likewise, 295.Fn crypt_set_format 296modifies static data. 297.Pp 298The NT-hash scheme does not use a salt, 299and is not hard 300for a competent attacker 301to break. 302Its use is not recommended. 303