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