On 2021-01-21, Rubén Llorente <port...@use.startmail.com> wrote: > Hello everybody. > > 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. I am not aware > of any style guide and the fix is trivial, so I'd rather post it in misc > than on a developer list.
Please send to tech@. A couple of comments inline. > Suggestions and ideas are welcome. > > I am aware the crypt() family is deprecated. > > --- crypt.3 Thu Jan 21 16:59:05 2021 > +++ crypt.new Thu Jan 21 20:11:31 2021 > @@ -70,14 +70,17 @@ > 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. Perhaps keep that but explain that some algorithms use additional bytes to set parameters. This or similar text would need to be readded if another algorithm was supported (perhaps someone feels like adding argon2id one day). > -At the moment > -.Ql $2 > -chooses Blowfish hashing; see below for more information. > +currently supports a single form, and must be formatted as > +.Fa $algorithm$lrounds$salt > +.Pp > +The > +.Fa algorithm > +must be either "2a" or "2b", which select the old and new implementation of > Blowfish hashing respectively. The Keep to <80 columns. New sentence -> new line. "old" and "new" are problematic words to use, and the hashing itself didn't change, it's to do with how the input password is handled. (On some non-OpenBSD systems, and on all systems for _most_ passwords, 2a and 2b are identical). In OpenBSD bcrypt has used the following: $2$ original, no longer supported (only used for a short time) $2a$ defines use of UTF-8 and null terminator $2b$ avoids wraparound bug in OpenBSD's $2a implementation Other implementations using $2a don't have this bug (though it's possibly some may have added it later for backwards-compatibility). Perhaps something like: The algorithm should be "2b" unless compatibility with OpenBSD versions earlier than 5.5 is needed. And leave it at that, if someone reading the manual wants to dig into it further that's a good starting point. > +.Fa lrounds > +preference must be a two digit number between "04" and "31", whereas > +.Fa salt > +is a character string which represents 128 bits of radix-64 encoded salt. > + > .Ss Blowfish crypt > The Blowfish version of crypt has 128 bits of > .Fa salt > >
