1.\" $OpenBSD: crypt.3,v 1.27 2007/10/08 11:55:27 pyr Exp $ 2.\" 3.\" FreeSec: libcrypt 4.\" 5.\" Copyright (c) 1994 David Burren 6.\" All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 4. Neither the name of the author nor the names of other contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" Manual page, using -mandoc macros 33.\" 34.Dd $Mdocdate: October 8 2007 $ 35.Dt CRYPT 3 36.Os 37.Sh NAME 38.Nm crypt , 39.Nm setkey , 40.Nm encrypt , 41.Nm des_setkey , 42.Nm des_cipher , 43.Nm bcrypt_gensalt , 44.Nm bcrypt , 45.Nm md5crypt 46.Nd DES encryption 47.Sh SYNOPSIS 48.Fd #include <pwd.h> 49.Fd #include <unistd.h> 50.Ft char * 51.Fn crypt "const char *key" "const char *setting" 52.Ft int 53.Fn setkey "const char *key" 54.Ft int 55.Fn encrypt "char *block" "int flag" 56.Ft int 57.Fn des_setkey "const char *key" 58.Ft int 59.Fn des_cipher "const char *in" "char *out" "int32_t salt" "int count" 60.Ft char * 61.Fn bcrypt_gensalt "u_int8_t log_rounds" 62.Ft char * 63.Fn bcrypt "const char *key" "const char *salt" 64.Ft char * 65.Fn md5crypt "const char *key" "const char *salt" 66.Sh DESCRIPTION 67The 68.Fn crypt 69function performs password encryption based on the 70.Tn NBS 71Data Encryption Standard (DES). 72Additional code has been added to deter key search attempts and to use 73stronger hashing algorithms. 74.Pp 75The first argument to 76.Fn crypt 77is a 78.Dv NUL Ns -terminated 79string, typically a user's typed password. 80The second is in one of three forms: 81if it begins with an underscore 82.Pq Ql _ 83then an extended format is used 84in interpreting both the key and the setting, as outlined below. 85If it begins 86with a string character 87.Pq Ql $ 88and a number then a different algorithm is used depending on the number. 89At the moment a 90.Ql $1 91chooses MD5 hashing and a 92.Ql $2 93chooses Blowfish hashing; see below for more information. 94.Ss Extended crypt 95The 96.Ar key 97is divided into groups of 8 characters (the last group is null-padded) 98and the low-order 7 bits of each character (56 bits per group) are 99used to form the DES key as follows: 100the first group of 56 bits becomes the initial DES key. 101For each additional group, the XOR of the encryption of the current DES 102key with itself and the group bits becomes the next DES key. 103.Pp 104The setting is a 9-character array consisting of an underscore followed 105by 4 bytes of iteration count and 4 bytes of salt. 106These are encoded as printable characters, 6 bits per character, 107least significant character first. 108The values 0 to 63 are encoded as 109.Dq \&./0-9A-Za-z . 110This allows 24 bits for both 111.Fa count 112and 113.Fa salt . 114.Ss "MD5" crypt 115For 116.Tn MD5 117crypt the version number, 118.Fa salt 119and the hashed password are separated by the 120.Ql $ 121character. 122The maximum length of a password is limited by 123the length counter of the MD5 context, which is about 1242**64. 125A valid MD5 password entry looks like this: 126.Pp 127.Dq $1$caeiHQwX$hsKqOjrFRRN6K32OWkCBf1 . 128.Pp 129The whole MD5 password string is passed as 130.Fa setting 131for interpretation. 132.Ss "Blowfish" crypt 133The 134.Tn Blowfish 135version of crypt has 128 bits of 136.Fa salt 137in order to make building dictionaries of common passwords space consuming. 138The initial state of the 139.Tn Blowfish 140cipher is expanded using the 141.Fa salt 142and the 143.Fa password 144repeating the process a variable number of rounds, which is encoded in 145the password string. 146The maximum password length is 72. 147The final Blowfish password entry is created by encrypting the string 148.Pp 149.Dq OrpheanBeholderScryDoubt 150.Pp 151with the 152.Tn Blowfish 153state 64 times. 154.Pp 155The version number, the logarithm of the number of rounds and 156the concatenation of salt and hashed password are separated by the 157.Ql $ 158character. 159An encoded 160.Sq 8 161would specify 256 rounds. 162A valid Blowfish password looks like this: 163.Pp 164.Dq $2a$12$eIAq8PR8sIUnJ1HaohxX2O9x9Qlm2vK97LJ5dsXdmB.eXF42qjchC . 165.Pp 166The whole Blowfish password string is passed as 167.Fa setting 168for interpretation. 169.Ss "Traditional" crypt 170The first 8 bytes of the key are null-padded, and the low-order 7 bits of 171each character is used to form the 56-bit 172.Tn DES 173key. 174.Pp 175The setting is a 2-character array of the ASCII-encoded salt. 176Thus only 12 bits of 177.Fa salt 178are used. 179.Fa count 180is set to 25. 181.Ss DES Algorithm 182The 183.Fa salt 184introduces disorder in the 185.Tn DES 186algorithm in one of 16777216 or 4096 possible ways 187(i.e., with 24 or 12 bits: if bit 188.Em i 189of the 190.Ar salt 191is set, then bits 192.Em i 193and 194.Em i+24 195are swapped in the 196.Tn DES 197E-box output). 198.Pp 199The DES key is used to encrypt a 64-bit constant using 200.Ar count 201iterations of 202.Tn DES . 203The value returned is a 204.Dv NUL Ns -terminated 205string, 20 or 13 bytes (plus NUL) in length, consisting of the 206.Ar setting 207followed by the encoded 64-bit encryption. 208.Pp 209The functions 210.Fn encrypt , 211.Fn setkey , 212.Fn des_setkey , 213and 214.Fn des_cipher 215provide access to the 216.Tn DES 217algorithm itself. 218.Fn setkey 219is passed a 64-byte array of binary values (numeric 0 or 1). 220A 56-bit key is extracted from this array by dividing the 221array into groups of 8, and ignoring the last bit in each group. 222That bit is reserved for a byte parity check by DES, but is ignored 223by these functions. 224.Pp 225The 226.Fa block 227argument to 228.Fn encrypt 229is also a 64-byte array of binary values. 230If the value of 231.Fa flag 232is 0, 233.Fa block 234is encrypted otherwise it is decrypted. 235The result is returned in the original array 236.Fa block 237after using the key specified by 238.Fn setkey 239to process it. 240.Pp 241The argument to 242.Fn des_setkey 243is a character array of length 8. 244The least significant bit (the parity bit) in each character is ignored, 245and the remaining bits are concatenated to form a 56-bit key. 246The function 247.Fn des_cipher 248encrypts (or decrypts if 249.Fa count 250is negative) the 64-bits stored in the 8 characters at 251.Fa in 252using 253.Xr abs 3 254of 255.Fa count 256iterations of 257.Tn DES 258and stores the 64-bit result in the 8 characters at 259.Fa out 260(which may be the same as 261.Fa in ) . 262The 263.Fa salt 264specifies perturbations to the 265.Tn DES 266E-box output as described above. 267.Pp 268The 269.Fn crypt , 270.Fn setkey , 271and 272.Fn des_setkey 273functions all manipulate the same key space. 274.Sh RETURN VALUES 275The function 276.Fn crypt 277returns a pointer to the encrypted value on success, and 278.Dv NULL 279on failure. 280The functions 281.Fn setkey , 282.Fn encrypt , 283.Fn des_setkey , 284and 285.Fn des_cipher 286return 0 on success and 1 on failure. 287.Sh SEE ALSO 288.Xr login 1 , 289.Xr passwd 1 , 290.Xr blowfish 3 , 291.Xr getpass 3 , 292.Xr md5 3 , 293.Xr passwd 5 294.Sh HISTORY 295A rotor-based 296.Fn crypt 297function appeared in 298.At v3 . 299The current style 300.Fn crypt 301first appeared in 302.At v7 . 303.Pp 304This library (FreeSec 1.0) was developed outside the United States of America 305as an unencumbered replacement for the U.S.-only libcrypt encryption 306library. 307Programs linked against the 308.Fn crypt 309interface may be exported from the U.S.A. only if they use 310.Fn crypt 311solely for authentication purposes and avoid use of 312the other programmer interfaces listed above. 313Special care has been taken 314in the library so that programs which only use the 315.Fn crypt 316interface do not pull in the other components. 317.Sh AUTHORS 318.An David Burren Aq davidb@werj.com.au 319.Sh BUGS 320The 321.Fn crypt 322function returns a pointer to static data, and subsequent calls to 323.Fn crypt 324will modify the same object. 325