Re: [musl] Re: RFC: how to document musl-crypt failure ?

[Alejandro Colomar <alx+linux-man@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 2110 bytes --]

Hi Rich,

> Date: 2026-11-09 16:51:02+0100
> From: Alejandro Colomar <alx+linux-man@kernel.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>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]