Hello, I think the current crypt(3) manual page is not as helpful as it could be. Based on the current description, a user might think that a valid 'setting' to select MD5 without a salt might be crypt(pass, "$1") It would need to be "$1$", or, obviously better, "$1$salt". The manual page also says "The entire password string is passed as setting for interpretation." which... is confusing. You pass the parameters via 'setting' to _yield_ the "entire password string" - I'm not sure what is meant here by this phrase. (You need the entire string to perform _validation_, so that you can construct the 'setting', then call crypt(3) with the plaintext, then compare the result, but I think that's outside the scope of this manual page.) For the Argon2 and Blowfish functions, the manual page ought to describe the version string, and for both MD5 and Blowfish we should note that the salt is silently truncated if longer than allowed. Attached are my suggested improvements for this manual page - does that look ok? -Jan
? .crypt.3.swp Index: crypt.3 =================================================================== RCS file: /cvsroot/src/lib/libcrypt/crypt.3,v retrieving revision 1.35 diff -u -p -r1.35 crypt.3 --- crypt.3 17 Jan 2023 14:27:11 -0000 1.35 +++ crypt.3 16 Nov 2025 18:16:11 -0000 @@ -29,7 +29,7 @@ .\" .\" @(#)crypt.3 8.2 (Berkeley) 12/11/93 .\" -.Dd October 20, 2021 +.Dd November 16, 2025 .Dt CRYPT 3 .Os .Sh NAME @@ -64,16 +64,31 @@ The password hashing scheme used by is dependent upon the contents of the .Tn NUL Ns -terminated string -.Ar setting . -If it begins +.Ar setting : +.Pp +If +.Ar setting +begins with a string character .Pq Ql $ -and a number then a different algorithm is used depending on the number. +then a different algorithm is used depending on the +following characters. At the moment a .Ql $1 -chooses MD5 hashing and a +chooses MD5 hashing, .Ql $2 -chooses Blowfish hashing; see below for more information. +chooses Blowfish hashing, and +.Ql $argon2i , +.Ql $argon2d , +or +.Ql $argon2id +choose Argon2 hashing. +In either case, the additional parameters for the +hashing algorithm are separated by further +.Ql $ +characters; +see below for more information. +.Pp If .Ar setting begins with the @@ -254,19 +269,20 @@ as described above. For the .Tn MD5 password hashing scheme, the version number (in this case -.Ql 1 ) , +.Ql 1 ) +and .Fa salt -and the hashed password are separated -by the +are separated by the .Ql $ -character. -An encoded password hash looks like: -.Pp -.Dl "$1$2qGr5PPQ$eT08WBFev3RPLNChixg0H" -.Pp -The entire encoded MD5 password hash is passed as -.Fa setting -for interpretation. +character and passed to +.Nm +via the +.Ar setting +argument as, e.g., +.Ql $1$2qGr5PPQ . +Only the first 8 characters of the +.Fa salt +are used; any other characters are silently ignored. .Ss Argon2 password hashing Argon2 is a memory-hard password hashing algorithm. .Fn crypt @@ -274,30 +290,33 @@ provides all three variants: argon2i, ar It is recommended to use argon2id, which provides a hybrid combination using argon2i on the first pass, and argon2d on the remaining passes. -We parameterize on three variables. -First, +We parameterize on three variables, although four +variables separated by +.Ql $ +are specified: +.Pp +The first parameter, +.Va version ( Li v ) , +specifies the version of Argon to be used. +This version is currently fixed per RFC9106 as decimal +19. +Next, .Va m_cost ( Li m ) , specifies the memory usage in -.Tn KB . -Second, +.Tn KB ; .Va t_cost ( Li t ) , -specifies the number of iterations. -Third, +specifies the number of iterations, and lastly .Va parallelism ( Li p ) specifies the number of threads. This is currently ignored and one thread will always be used. -An encoded Argon2 password hash looks like: +Following these parameters is the salt. +.Pp +A complete Argon2 +.Ar setting +string might be .Bd -literal -offset indent -$argon2id$v=19$m=4096,t=6,p=1$qCatF9a1s/6TgcYB$ \e - yeYYrU/rh7E+LI2CAeHTSHVB3iO+OXiNIUHu6NPeTfo +.Ql $argon2id$v=19$m=4096,t=6,p=1$qCatF9a1s/6TgcYB .Ed -.Pp -containing five fields delimited by -.Ql $ . -The fields, in order, are variant name, version, parameter set, -128-bit salt, and Argon2 hash encoded in base64. -The entire encoded Argon2 password hash is required to be processed -correctly. .Ss "Blowfish" bcrypt The .Tn Blowfish @@ -327,16 +346,23 @@ The version number, the logarithm of the the concatenation of salt and hashed password are separated by the .Ql $ character. +Currently, the only supported version number on +.Nx +is +.Ql 2a . An encoded -.Sq 8 -would specify 256 rounds. -An encoded Blowfish password hash looks like: -.Pp -.Dl "$2a$12$eIAq8PR8sIUnJ1HaohxX2O9x9Qlm2vK97LJ5dsXdmB.eXF42qjchC" -.Pp -The entire encoded Blowfish password hash is passed as -.Fa setting -for interpretation. +.Sq 12 +would specify 4096 rounds. +Only the first 22 characters of the +.Fa salt +are used; any other characters are silently ignored. +.Pp +A complete Blowfish +.Ar setting +string might be +.Bd -literal -offset indent +.Ql $2a$12$eIAq8PR8sIUnJ1HaohxX2O +.Ed .Sh RETURN VALUES The function .Fn crypt