[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <avXOTLv8xJqyy5qh@devuan>
Date: Thu, 12 Nov 2026 15:37:11 +0100
From: Alejandro Colomar <alx+linux-man@...nel.org>
To: Rich Felker <dalias@...c.org>
Cc: Walter Harms <wharms@....de>,
"linux-man@...r.kernel.org" <linux-man@...r.kernel.org>, libc-alpha@...rceware.org, musl@...ts.openwall.com,
~hallyn/shadow@...ts.sr.ht
Subject: Re: Re: RFC: how to document musl-crypt failure ?
Hi Rich,
> Date: 2026-11-09 16:51:02+0100
> From: Alejandro Colomar <alx+linux-man@...nel.org>
>
[...]
> > I would not document future behavior, and would document existing
> > behavior only as an implementation detail, not an application-facing
> > contract. The only contract with the application is that crypt(P,H)
> > will never return a string identical to H except on valid password (in
> > the absence of theoretical hash collisions) regardless of the validity
> > of P and H.
>
> Okay. Thank you very much! I'll work on a patch, and CC you when it's
> ready.
What do you think of this?
diff --git i/man/man3/crypt.3 w/man/man3/crypt.3
index e0a74b955b3e..4a75fac2f627 100644
--- i/man/man3/crypt.3
+++ w/man/man3/crypt.3
@@ -259,6 +259,28 @@ .SS salt
is equal to
.I xxx
otherwise.
+.SH EXAMPLES
+When comparing a password against an existing hash,
+that hash (and no other) must be passed as
+.IR salt .
+If and only if
+.I salt
+compares equal
+(see
+.BR streq (3))
+to the returned string,
+the password matches the existing hash specified by
+.IR salt .
+.P
+.in +4n
+.EX
+if (streq(H, crypt(P, H))) {
+ // good password
+} else {
+ // bad password
+}
+.EE
+.in
.SH SEE ALSO
.BR login (1),
.BR passwd (1),
which reads as:
--- HEAD:man/man3/crypt.3
+++ ./man/man3/crypt.3
@@ -152,6 +152,19 @@ NOTES
than 1000, 999999999 if xxx is greater than 999999999, and
is equal to xxx otherwise.
+EXAMPLES
+ When comparing a password against an existing hash, that
+ hash (and no other) must be passed as salt. If and only
+ if salt compares equal (see streq(3)) to the returned
+ string, the password matches the existing hash specified
+ by salt.
+
+ if (streq(H, crypt(P, H))) {
+ // good password
+ } else {
+ // bad password
+ }
+
SEE ALSO
login(1), passwd(1), encrypt(3), getpass(3), passwd(5)
Cheers,
Alex
--
<https://www.alejandro-colomar.es>
Download attachment "signature.asc" of type "application/pgp-signature" (834 bytes)
Powered by blists - more mailing lists
Confused about mailing lists and their use?
Read about mailing lists on Wikipedia
and check out these
guidelines on proper formatting of your messages.
