On 2021/01/27 22:45, Ingo Schwarze wrote: > 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
Thanks, I think this is a lot better. OK with me. > 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
