Re: Patch for crypt(3) man page.
I suspect this patch has been forgotten, so I am bumping this thread as a reminder. I'd like this man page cleaned up :-) On Wed, Jan 27, 2021 at 10:45:46PM +0100, 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 for picking this up, ingo. certainly ok with me. there is one instance of "specifieds" which needs fixed though. jmc > > 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 - 1.45 > +++ crypt.3 27 Jan 2021 21:30:22 - > @@ -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
Re: Patch for crypt(3) man page.
On Wed, Jan 27, 2021 at 10:45:46PM +0100, 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 for picking this up, ingo. certainly ok with me. there is one instance of "specifieds" which needs fixed though. jmc > > 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 - 1.45 > +++ crypt.3 27 Jan 2021 21:30:22 - > @@ -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: >
Re: Patch for crypt(3) man page.
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 - 1.45 > +++ crypt.3 27 Jan 2021 21:30:22 - > @@ -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
Re: Patch for crypt(3) man page.
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 - 1.45 +++ crypt.3 27 Jan 2021 21:30:22 - @@ -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
Patch for crypt(3) man page.
Hello everybody. I sent an email to the misc@ list yesterday regarding a patch proposal for a man page. Upon request, I am submitting the same proposal here with some changes. I reproduce the original email here for those who don follow misc@. / I have been porting a stupid old program to OpenBSD. I hit a bit or a road block because this program uses crypt() but the man page at OpenBSD is not clear enough regarding a couple of details. Specifically: the man page does not provide a clear explanation of the format in which the _setting_ parameter is to be fed to crypt(). In fact, it says: "The second, setting, currently supports a single form. If it begins with a string character (‘$’) and a number then a different algorithm is used depending on the number." So far, so good. What it doesn't say is that if you don't identify the algorithm as either "2a" or "2b" you get an errno and no hash. It also does not specify that you need to provide the log2 of rounds with the _setting_ param, and that such log2 of rounds must be expressed as a two digit number. I am pasting a proposed patch for the crypt(3) man page. Suggestions and ideas are welcome. I am aware the crypt() family is deprecated. --- crypt.3 Thu Jan 21 16:59:05 2021 +++ crypt.new Fri Jan 22 21:33:15 2021 @@ -75,9 +75,13 @@ 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. +Some algorithms use additional bytes to set parameters. +.Pp +At the moment, only Blowfish hashing is supported; see below for more +information. +The algorithm should be +.Ql $2b +unless compatibility with OpenBSD versions earlier than 5.5 is needed. .Ss Blowfish crypt The Blowfish version of crypt has 128 bits of .Fa salt @@ -103,6 +107,18 @@ An encoded .Sq 8 would specify 256 rounds. +The logarithm of the number of rounds must be specified as a two-digit +number; therefore, +.Ql 8 +would be encoded as +.Ql 08 +.Pp +A valid Blowfish +.Fa setting +with no password looks like this: +.Pp +.Dq $2b$12$FPWWO2RJ3CK4FINTw0Hi8O . +.Pp A valid Blowfish password looks like this: .Pp .Dq $2b$12$FPWWO2RJ3CK4FINTw0Hi8OiPKJcX653gzSS.jqltHFMxyDmmQ0Hqq . -- OpenPGP Key Fingerprint: BB5A C2A2 2CAD ACB7 D50D C081 1DB9 6FC4 5AB7 92FA
