crypt(3) manual page

[Jan Schaumann <jschauma%netmeister.org@localhost>]

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