Hi, this page is a mess. It is full of unclear wordings, in some cases verging incorrect statements. At the same time, parts of it are wordy.
Here is an attempt to start fixing it. I refrained from trying to explain $2a$ (as suggested by sthen@) or to document the missing bcrypt_gensalt(3) in the same patch because this patch is already quite large. Rationale: * Rename the "salt" argument of bcrypt(3) to "setting" to match crypt(3). It is *not* the salt, it is exactly the same for both functions. * Avoid talking about "first" and "second" arguments, just use the argument names as in every other manual page. * Properly document ".Fa setting" using a syntax display. * Precisely explain the format of the encoded salt, and mention what happens with additional bytes. * Mention what happens to excessive bytes in the key. * Precisely describe the return value for Blowfish. * Below RETURN VALUES, avoid the misleading statement that it returns just "the encrypted value"; it actually returns much more than that. What exactly depends on the algorithm, and those details were already covered in the algorithm-specific section(s) above. So instead mention what this heap of bytes is typically used for. I hope i got this right; OK? Ingo Index: crypt.3 =================================================================== RCS file: /cvs/src/lib/libc/crypt/crypt.3,v retrieving revision 1.45 diff -u -r1.45 crypt.3 --- crypt.3 6 Apr 2015 20:49:41 -0000 1.45 +++ crypt.3 27 Jan 2021 21:30:22 -0000 @@ -49,7 +49,7 @@ .Ft char * .Fn bcrypt_gensalt "u_int8_t log_rounds" .Ft char * -.Fn bcrypt "const char *key" "const char *salt" +.Fn bcrypt "const char *key" "const char *setting" .Sh DESCRIPTION These functions are deprecated in favor of .Xr crypt_checkpass 3 @@ -62,58 +62,80 @@ 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 NUL-terminated -string -.Fa key , +The +.Fa key +is a NUL-terminated string, typically a user's typed password. -The second, -.Fa setting , -currently supports a single form. -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 -.Ql $2 -chooses Blowfish hashing; see below for more information. +The +.Fa setting +argument is required to begin with an algorithm identifier enclosed +in dollar signs. +The meaning of the rest of the +.Fa setting +argument is algorithm-specific. +.Pp +Currently, only +.Sx Blowfish crypt +is supported, so +.Fa setting +needs to begin with +.Qq $2b$ . .Ss Blowfish crypt -The Blowfish version of crypt has 128 bits of -.Fa salt +The Blowfish version of crypt has 128 bits of salt in order to make building dictionaries of common passwords space consuming. +.Pp +The format of +.Fa setting +is: +.Pp +.Sm off +.D1 $ Cm 2b No $ Ar log_rounds No $ Ar encoded_salt +.Sm on +.Pp +The binary logarithm of the number of rounds +is specified as a decimal number containing exactly two digits +in the range 04 to 31, inclusive. +For example, +.Qq $2b$08$ +requests 256 rounds. +.Pp +The +.Ar encoded_salt +is a byte array of at least 22 bytes, with the first 172 bits +encoding the 128-bit salt in base64 form. +Any additional bytes are ignored. +.Pp The initial state of the 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. +salt and the +.Fa key +repeating the process the specifieds number of rounds. +.Pp +The maximum +.Fa key +length is 72; excessive bytes are silently discarded. The final Blowfish password entry is created by encrypting the string -.Pp -.Dq OrpheanBeholderScryDoubt -.Pp +.Qq OrpheanBeholderScryDoubt with the 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 -.Ql $ -character. -An encoded -.Sq 8 -would specify 256 rounds. -A valid Blowfish password looks like this: -.Pp -.Dq $2b$12$FPWWO2RJ3CK4FINTw0Hi8OiPKJcX653gzSS.jqltHFMxyDmmQ0Hqq . +The return value contains a copy of +.Ar setting +at the beginning, followed by 31 bytes containing the encrypted password +encoded in base64 form, so the return value is effectively of the type +.Vt char[60] . +For example, a valid return value for Blowfish looks like this: .Pp -The whole Blowfish password string is passed as -.Fa setting -for interpretation. +.Dl $2b$12$FPWWO2RJ3CK4FINTw0Hi8OiPKJcX653gzSS.jqltHFMxyDmmQ0Hqq .Sh RETURN VALUES -The function +The functions .Fn crypt -returns a pointer to the encrypted value on success, and +and +.Fn bcrypt +return a string usable for the +.Ar password +field in the +.Xr master.passwd 5 +file on success or .Dv NULL on failure. .Sh SEE ALSO
