diff options
Diffstat (limited to 'lib/libc/crypt/crypt.3')
| -rw-r--r-- | lib/libc/crypt/crypt.3 | 105 |
1 files changed, 61 insertions, 44 deletions
diff --git a/lib/libc/crypt/crypt.3 b/lib/libc/crypt/crypt.3 index daa9c4d844a..36058c75671 100644 --- a/lib/libc/crypt/crypt.3 +++ b/lib/libc/crypt/crypt.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: crypt.3,v 1.15 2000/04/15 02:15:22 aaron Exp $ +.\" $OpenBSD: crypt.3,v 1.16 2000/04/18 02:31:34 aaron Exp $ .\" .\" FreeSec: libcrypt .\" @@ -56,24 +56,32 @@ .Sh DESCRIPTION The .Fn crypt -function performs password encryption, based on the +function performs password encryption based on the .Tn NBS Data Encryption Standard (DES). Additional code has been added to deter key search attempts and to use stronger hashing algorithms. +.Pp The first argument to .Fn crypt is a .Dv null Ns -terminated string, typically a user's typed password. The second is in one of three forms: -if it begins with an underscore (``_'') then an extended format is used -in interpreting both the key and the setting, as outlined below. If it begins -with an string character (``$'') and a number then a different algorithm -is used depending on the number. At the moment a ``$1'' chooses MD5 hashing -and a ``$2'' chooses Blowfish hashing, see below for more information. -.Ss Extended crypt: -.Pp +if it begins with an underscore +.Pq Ql _ +then an extended format is used +in interpreting both the key and the setting, as outlined below. +If it begins +with a string character +.Pq Ql $ +and a number then a different algorithm is used depending on the number. +At the moment a +.Ql $1 +chooses MD5 hashing and a +.Ql $2 +chooses Blowfish hashing; see below for more information. +.Ss Extended crypt The .Ar key is divided into groups of 8 characters (the last group is null-padded) @@ -87,61 +95,68 @@ The setting is a 9-character array consisting of an underscore followed by 4 bytes of iteration count and 4 bytes of salt. These are encoded as printable characters, 6 bits per character, least significant character first. -The values 0 to 63 are encoded as ``./0-9A-Za-z''. +The values 0 to 63 are encoded as +.Dq \&./0-9A-Za-z . This allows 24 bits for both .Fa count and .Fa salt . -.Ss "MD5" crypt: -.Pp +.Ss "MD5" crypt For .Tn MD5 crypt the version number, .Fa salt -and the hashed password are separated -by the ``$'' character. The maximum length of a password is limited by +and the hashed password are separated by the +.Ql $ +character. +The maximum length of a password is limited by the length counter of the MD5 context, which is about -2**64. A valid MD5 password entry looks like this: +2**64. +A valid MD5 password entry looks like this: .Pp -``$1$caeiHQwX$hsKqOjrFRRN6K32OWkCBf1''. +.Dq $1$caeiHQwX$hsKqOjrFRRN6K32OWkCBf1 . .Pp The whole MD5 password string is passed as .Fa setting for interpretation. -.Ss "Blowfish" crypt: -.Pp +.Ss "Blowfish" crypt The .Tn Blowfish version of crypt has 128 bits of .Fa salt -in order to make building -dictionaries of common passwords space consuming. The initial state -of the +in order to make building dictionaries of common passwords space consuming. +The initial state of the .Tn Blowfish cipher is expanded using the .Fa salt and the .Fa password repeating the process a variable number of rounds, which is encoded in -the password string. The maximum password length is 72. The final Blowfish -password entry is created by encrypting -the string ``OrpheanBeholderScryDoubt'' with the +the password string. +The maximum password length is 72. +The final Blowfish password entry is created by encrypting the string +.Pp +.Dq OrpheanBeholderScryDoubt +.Pp +with the .Tn Blowfish state 64 times. .Pp The version number, the logarithm of the number of rounds and -the concatenation of salt and -hashed password are separated by the ``$'' character. An encoded ``8'' +the concatenation of salt and hashed password are separated by the +.Ql $ +character. +An encoded +.Sq 8 would specify 256 rounds. A valid Blowfish password looks like this: .Pp -``$2a$12$eIAq8PR8sIUnJ1HaohxX2O9x9Qlm2vK97LJ5dsXdmB.eXF42qjchC''. +.Dq $2a$12$eIAq8PR8sIUnJ1HaohxX2O9x9Qlm2vK97LJ5dsXdmB.eXF42qjchC . .Pp The whole Blowfish password string is passed as .Fa setting for interpretation. -.Ss "Traditional" crypt: -.Pp +.Ss "Traditional" crypt The first 8 bytes of the key are null-padded, and the low-order 7 bits of each character is used to form the 56-bit .Tn DES @@ -153,8 +168,7 @@ Thus only 12 bits of are used. .Fa count is set to 25. -.Ss DES Algorithm: -.Pp +.Ss DES Algorithm The .Fa salt introduces disorder in the @@ -182,10 +196,10 @@ string, 20 or 13 bytes (plus null) in length, consisting of the .Ar setting followed by the encoded 64-bit encryption. .Pp -The functions, +The functions .Fn encrypt , .Fn setkey , -.Fn des_setkey +.Fn des_setkey , and .Fn des_cipher provide access to the @@ -243,7 +257,9 @@ E-box output as described above. .Pp The function .Fn crypt -returns a pointer to the encrypted value on success, and NULL on failure. +returns a pointer to the encrypted value on success, and +.Dv NULL +on failure. The functions .Fn setkey , .Fn encrypt , @@ -254,7 +270,7 @@ return 0 on success and 1 on failure. .Pp The .Fn crypt , -.Fn setkey +.Fn setkey , and .Fn des_setkey functions all manipulate the same key space. @@ -265,12 +281,8 @@ functions all manipulate the same key space. .Xr getpass 3 , .Xr md5 3 , .Xr passwd 5 -.Sh BUGS -The -.Fn crypt -function returns a pointer to static data, and subsequent calls to -.Fn crypt -will modify the same object. +.Sh AUTHOR +David Burren <davidb@werj.com.au> .Sh HISTORY A rotor-based .Fn crypt @@ -289,9 +301,14 @@ Programs linked against the interface may be exported from the U.S.A. only if they use .Fn crypt solely for authentication purposes and avoid use of -the other programmer interfaces listed above. Special care has been taken +the other programmer interfaces listed above. +Special care has been taken in the library so that programs which only use the .Fn crypt interface do not pull in the other components. -.Sh AUTHOR -David Burren <davidb@werj.com.au> +.Sh BUGS +The +.Fn crypt +function returns a pointer to static data, and subsequent calls to +.Fn crypt +will modify the same object. |