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