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