[PATCH v1] man/man3/crypt.3: These functions accept many algorithms, not only DES

[PATCH v1] man/man3/crypt.3: These functions accept many algorithms, not only DES

[Alejandro Colomar]

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

This page was written as if DES was the only portable algorithm, and
glibc was a weird one supporting other algorithms.  These days (and
since a long time ago), DES has been long deprecated, and crypt(3)
supports many algorithms in all systems.

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---

Hi!

The patch for documenting the detail about "*" will come later.
This was a cleanup that seemed necessary before doing that.
Let me know what you think about it.  I'll reply with a copy of the
formatted page, so you don't need to apply the patch to review it.


Have a lovely night!
Alex

 man/man3/crypt.3 | 84 ++++--------------------------------------------
 1 file changed, 6 insertions(+), 78 deletions(-)

diff --git a/man/man3/crypt.3 b/man/man3/crypt.3
index 7c9a50a534b7..6c0511240898 100644
--- a/man/man3/crypt.3
+++ b/man/man3/crypt.3
@@ -47,56 +47,21 @@ .SH SYNOPSIS
 .SH DESCRIPTION
 .BR crypt ()
 is the password hashing function.
-It is based on the Data Encryption
-Standard algorithm with variations intended (among other things) to
-discourage use of hardware implementations of a key search.
 .P
 .I key
 is a user's typed password.
 .P
 .I salt
-is a two-character string chosen from the set
-.RB [ a\-zA\-Z0\-9./ ].
-This string is used to
-perturb the algorithm in one of 4096 different ways.
+is a string
+used for determining the hasing algorithm
+(possibly including parameters).
+It is also used to perturb the algorithm.
 .P
-By taking the lowest 7 bits of each of the first eight characters of the
-.IR key ,
-a 56-bit key is obtained.
-This 56-bit key is used to encrypt repeatedly a
-constant string (usually a string consisting of all zeros).
 The returned
-value points to the hashed password, a series of 13 printable ASCII
-characters (the first two characters represent the salt itself).
+value points to the hashed password.
 The return value points to static data whose content is
 overwritten by each call.
 .P
-Warning: the key space consists of
-.if t 2\s-2\u56\s0\d
-.if n 2**56
-equal 7.2e16 possible values.
-Exhaustive searches of this key space are
-possible using massively parallel computers.
-Software, such as
-.BR crack (1),
-is available which will search the portion of this key space that is
-generally used by humans for passwords.
-Hence, password selection should,
-at minimum, avoid common words and names.
-The use of a
-.BR passwd (1)
-program that checks for crackable passwords during the selection process is
-recommended.
-.P
-The DES algorithm itself has a few quirks which make the use of the
-.BR crypt ()
-interface a very poor choice for anything other than password
-authentication.
-If you are planning on using the
-.BR crypt ()
-interface for a cryptography project, don't do it: get a good book on
-encryption and one of the widely available DES libraries.
-.P
 .BR crypt_r ()
 is a reentrant version of
 .BR crypt ().
@@ -122,40 +87,6 @@ .SH ERRORS
 .BR crypt ()
 function was not implemented,
 probably because of U.S.A.\& export restrictions.
-.\" The following level of detail is not necessary in this man page.
-.\" .P
-.\" When encrypting a plain text P using DES with the key K results in the
-.\" encrypted text C, then the complementary plain text P' being encrypted
-.\" using the complementary key K' will result in the complementary encrypted
-.\" text C'.
-.\" .P
-.\" Weak keys are keys which stay invariant under the DES key transformation.
-.\" The four known weak keys 0101010101010101, fefefefefefefefe,
-.\" 1f1f1f1f0e0e0e0e and e0e0e0e0f1f1f1f1 must be avoided.
-.\" .P
-.\" There are six known half weak key pairs, which keys lead to the same
-.\" encrypted data.  Keys which are part of such key clusters should be
-.\" avoided.
-.\" Sorry, I could not find out what they are.
-.\""
-.\" .P
-.\" Heavily redundant data causes trouble with DES encryption, when used in the
-.\" .I codebook
-.\" mode that
-.\" .BR crypt ()
-.\" implements.  The
-.\" .BR crypt ()
-.\" interface should be used only for its intended purpose of password
-.\" verification, and should not be used as part of a data encryption tool.
-.\" .P
-.\" The first and last three output bits of the fourth S-box can be
-.\" represented as function of their input bits.  Empiric studies have
-.\" shown that S-boxes partially compute the same output for similar input.
-.\" It is suspected that this may contain a back door which could allow the
-.\" NSA to decrypt DES encrypted data.
-.\" .P
-.\" Making encrypted data computed using crypt() publicly available has
-.\" to be considered insecure for the given reasons.
 .TP
 .B EPERM
 .I /proc/sys/crypto/fips_enabled
@@ -217,10 +148,7 @@ .SS Availability in glibc
 .I libxcrypt
 is an ABI-compatible drop-in replacement.
 .SH NOTES
-.SS Features in glibc
-The glibc version of this function supports additional
-hashing algorithms.
-.P
+.SS salt
 If
 .I salt
 is a character string starting with the characters

base-commit: b951aa8a5356e12f635650d0136abed715e0d607
-- 
2.55.0


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

Re: [PATCH v1] man/man3/crypt.3: These functions accept many algorithms, not only DES

[Alejandro Colomar]

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

> Date: 2026-11-10 00:58:45+0100
> From: Alejandro Colomar <alx@kernel.org>
>
> This page was written as if DES was the only portable algorithm, and
> glibc was a weird one supporting other algorithms.  These days (and
> since a long time ago), DES has been long deprecated, and crypt(3)
> supports many algorithms in all systems.
> 
> Signed-off-by: Alejandro Colomar <alx@kernel.org>
> ---
> 
> Hi!
> 
> The patch for documenting the detail about "*" will come later.
> This was a cleanup that seemed necessary before doing that.
> Let me know what you think about it.  I'll reply with a copy of the
> formatted page, so you don't need to apply the patch to review it.

Below is a diff of the formatted page.


Cheers,
Alex
---

$ MANWIDTH=64 diffman-git -U99 HEAD
--- HEAD^:man/man3/crypt.3
+++ HEAD:man/man3/crypt.3
@@ -1,183 +1,155 @@
 crypt(3)            Library Functions Manual           crypt(3)
 
 NAME
      crypt, crypt_r - password hashing
 
 LIBRARY
      Password hashing library (libcrypt, -lcrypt)
 
 SYNOPSIS
      #include <unistd.h>
 
      char *crypt(const char *key, const char *salt);
 
      #include <crypt.h>
 
      char *crypt_r(const char *key, const char *salt,
                    struct crypt_data *restrict data);
 
  Feature Test Macro Requirements for glibc (see fea‐
  ture_test_macros(7)):
 
      crypt():
          Since glibc 2.28:
              _DEFAULT_SOURCE
          glibc 2.27 and earlier:
              _XOPEN_SOURCE
 
      crypt_r():
          _GNU_SOURCE
 
 DESCRIPTION
-     crypt() is the password hashing function.  It is based on
-     the Data Encryption Standard algorithm with variations in‐
-     tended (among other things) to discourage use of hardware
-     implementations of a key search.
+     crypt() is the password hashing function.
 
      key is a user’s typed password.
 
-     salt is a two‐character string chosen from the set
-     [a-zA-Z0-9./].  This string is used to perturb the algo‐
-     rithm in one of 4096 different ways.
-
-     By taking the lowest 7 bits of each of the first eight
-     characters of the key, a 56‐bit key is obtained.  This
-     56‐bit key is used to encrypt repeatedly a constant string
-     (usually a string consisting of all zeros).  The returned
-     value points to the hashed password, a series of 13 print‐
-     able ASCII characters (the first two characters represent
-     the salt itself).  The return value points to static data
-     whose content is overwritten by each call.
-
-     Warning: the key space consists of 2**56 equal 7.2e16 pos‐
-     sible values.  Exhaustive searches of this key space are
-     possible using massively parallel computers.  Software,
-     such as crack(1), is available which will search the por‐
-     tion of this key space that is generally used by humans
-     for passwords.  Hence, password selection should, at mini‐
-     mum, avoid common words and names.  The use of a passwd(1)
-     program that checks for crackable passwords during the se‐
-     lection process is recommended.
-
-     The DES algorithm itself has a few quirks which make the
-     use of the crypt() interface a very poor choice for any‐
-     thing other than password authentication.  If you are
-     planning on using the crypt() interface for a cryptography
-     project, don’t do it: get a good book on encryption and
-     one of the widely available DES libraries.
+     salt is a string used for determining the hasing algorithm
+     (possibly including parameters).  It is also used to per‐
+     turb the algorithm.
+
+     The returned value points to the hashed password.  The re‐
+     turn value points to static data whose content is over‐
+     written by each call.
 
      crypt_r() is a reentrant version of crypt().  The struc‐
      ture pointed to by data is used to store result data and
      bookkeeping information.  Other than allocating it, the
      only thing that the caller should do with this structure
      is to set data->initialized to zero before the first call
      to crypt_r().
 
 RETURN VALUE
      On success, a pointer to the hashed password is returned.
      On error, NULL is returned.
 
 ERRORS
      EINVAL
             salt has the wrong format.
 
      ENOSYS
             The crypt() function was not implemented, probably
             because of U.S.A. export restrictions.
 
      EPERM  /proc/sys/crypto/fips_enabled has a nonzero value,
             and an attempt was made to use a weak hashing type,
             such as DES.
 
 ATTRIBUTES
      For an explanation of the terms used in this section, see
      attributes(7).
      ┌─────────────────┬───────────────┬──────────────────────┐
      │ Interface       │ Attribute     │ Value                │
      ├─────────────────┼───────────────┼──────────────────────┤
      │ crypt()         │ Thread safety │ MT‐Unsafe race:crypt │
      ├─────────────────┼───────────────┼──────────────────────┤
      │ crypt_r()       │ Thread safety │ MT‐Safe              │
      └─────────────────┴───────────────┴──────────────────────┘
 
 STANDARDS
      crypt()
             POSIX.1‐2008.
 
      crypt_r()
             GNU.
 
 HISTORY
      crypt()
             POSIX.1‐2001, SVr4, 4.3BSD.
 
    Availability in glibc
      The crypt(), encrypt(3), and setkey(3) functions are part
      of the POSIX.1‐2008 XSI Options Group for Encryption and
      are optional.  If the interfaces are not available, then
      the symbolic constant _XOPEN_CRYPT is either not defined,
      or it is defined to -1 and availability can be checked at
      run time with sysconf(3).  This may be the case if the
      downstream distribution has switched from glibc crypt to
      libxcrypt.  When recompiling applications in such distrib‐
      utions, the programmer must detect if _XOPEN_CRYPT is not
      available and include <crypt.h> for the function proto‐
      types; otherwise libxcrypt is an ABI‐compatible drop‐in
      replacement.
 
 NOTES
-   Features in glibc
-     The glibc version of this function supports additional
-     hashing algorithms.
-
+   salt
      If salt is a character string starting with the characters
      "$id$" followed by a string optionally terminated by "$",
      then the result has the form:
 
             $id$salt$hashed
 
      id identifies the hashing method used instead of DES and
      this then determines how the rest of the password string
      is interpreted.  The following values of id are supported:
             ID   Method
             ───────────────────────────────────────────────────
             1    MD5
             2a   Blowfish (not in mainline glibc; added in
                  some Linux distributions)
             5    SHA‐256 (since glibc 2.7)
             6    SHA‐512 (since glibc 2.7)
 
      Thus, $5$salt$hashed and $6$salt$hashed contain the pass‐
      word hashed with, respectively, functions based on SHA‐256
      and SHA‐512.
 
      "salt" stands for the up to 16 characters following "$id$"
      in the salt.  The "hashed" part of the password string is
      the actual computed password.  The size of this string is
      fixed:
             MD5       22 characters
             SHA‐256   43 characters
             SHA‐512   86 characters
 
      The characters in "salt" and "hashed" are drawn from the
      set [a-zA-Z0-9./].  In the MD5 and SHA implementations the
      entire key is significant (instead of only the first 8
      bytes in DES).
 
      Since glibc 2.7, the SHA‐256 and SHA‐512 implementations
      support a user‐supplied number of hashing rounds, default‐
      ing to 5000.  If the "$id$"charactersinthesaltare followed
      by "rounds=xxx$", where xxx is an integer, then the result
      has the form
 
             $id$rounds=yyy$salt$hashed
 
      where yyy is the number of hashing rounds actually used.
      The number of rounds actually used is 1000 if xxx is less
      than 1000, 999999999 if xxx is greater than 999999999, and
      is equal to xxx otherwise.
 
 SEE ALSO
      login(1), passwd(1), encrypt(3), getpass(3), passwd(5)
 
 Linux man‐pages (unreleased) (date)                    crypt(3)


-- 
<https://www.alejandro-colomar.es>

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

Re: [PATCH v1] man/man3/crypt.3: These functions accept many algorithms, not only DES

[Serge E. Hallyn]

On Tue, Nov 10, 2026 at 01:01:19AM +0100, Alejandro Colomar wrote:
> > Date: 2026-11-10 00:58:45+0100
> > From: Alejandro Colomar <alx@kernel.org>
> >
> > This page was written as if DES was the only portable algorithm, and
> > glibc was a weird one supporting other algorithms.  These days (and
> > since a long time ago), DES has been long deprecated, and crypt(3)
> > supports many algorithms in all systems.
> > 
> > Signed-off-by: Alejandro Colomar <alx@kernel.org>
> > ---
> > 
> > Hi!
> > 
> > The patch for documenting the detail about "*" will come later.
> > This was a cleanup that seemed necessary before doing that.
> > Let me know what you think about it.  I'll reply with a copy of the
> > formatted page, so you don't need to apply the patch to review it.
> 
> Below is a diff of the formatted page.
> 
> 
> Cheers,
> Alex
> ---
> 
> $ MANWIDTH=64 diffman-git -U99 HEAD
> --- HEAD^:man/man3/crypt.3
> +++ HEAD:man/man3/crypt.3
> @@ -1,183 +1,155 @@
>  crypt(3)            Library Functions Manual           crypt(3)
>  
>  NAME
>       crypt, crypt_r - password hashing
>  
>  LIBRARY
>       Password hashing library (libcrypt, -lcrypt)
>  
>  SYNOPSIS
>       #include <unistd.h>
>  
>       char *crypt(const char *key, const char *salt);
>  
>       #include <crypt.h>
>  
>       char *crypt_r(const char *key, const char *salt,
>                     struct crypt_data *restrict data);
>  
>   Feature Test Macro Requirements for glibc (see fea‐
>   ture_test_macros(7)):
>  
>       crypt():
>           Since glibc 2.28:
>               _DEFAULT_SOURCE
>           glibc 2.27 and earlier:
>               _XOPEN_SOURCE
>  
>       crypt_r():
>           _GNU_SOURCE
>  
>  DESCRIPTION
> -     crypt() is the password hashing function.  It is based on
> -     the Data Encryption Standard algorithm with variations in‐
> -     tended (among other things) to discourage use of hardware
> -     implementations of a key search.
> +     crypt() is the password hashing function.
>  
>       key is a user’s typed password.
>  
> -     salt is a two‐character string chosen from the set
> -     [a-zA-Z0-9./].  This string is used to perturb the algo‐
> -     rithm in one of 4096 different ways.
> -
> -     By taking the lowest 7 bits of each of the first eight
> -     characters of the key, a 56‐bit key is obtained.  This
> -     56‐bit key is used to encrypt repeatedly a constant string
> -     (usually a string consisting of all zeros).  The returned
> -     value points to the hashed password, a series of 13 print‐
> -     able ASCII characters (the first two characters represent
> -     the salt itself).  The return value points to static data
> -     whose content is overwritten by each call.
> -
> -     Warning: the key space consists of 2**56 equal 7.2e16 pos‐
> -     sible values.  Exhaustive searches of this key space are
> -     possible using massively parallel computers.  Software,
> -     such as crack(1), is available which will search the por‐
> -     tion of this key space that is generally used by humans
> -     for passwords.  Hence, password selection should, at mini‐
> -     mum, avoid common words and names.  The use of a passwd(1)
> -     program that checks for crackable passwords during the se‐
> -     lection process is recommended.
> -
> -     The DES algorithm itself has a few quirks which make the
> -     use of the crypt() interface a very poor choice for any‐
> -     thing other than password authentication.  If you are
> -     planning on using the crypt() interface for a cryptography
> -     project, don’t do it: get a good book on encryption and
> -     one of the widely available DES libraries.
> +     salt is a string used for determining the hasing algorithm

typo: hashing

> +     (possibly including parameters).  It is also used to per‐
> +     turb the algorithm.
> +
> +     The returned value points to the hashed password.  The re‐
> +     turn value points to static data whose content is over‐
> +     written by each call.
>  
>       crypt_r() is a reentrant version of crypt().  The struc‐
>       ture pointed to by data is used to store result data and
>       bookkeeping information.  Other than allocating it, the
>       only thing that the caller should do with this structure
>       is to set data->initialized to zero before the first call
>       to crypt_r().
>  
>  RETURN VALUE
>       On success, a pointer to the hashed password is returned.
>       On error, NULL is returned.
>  
>  ERRORS
>       EINVAL
>              salt has the wrong format.
>  
>       ENOSYS
>              The crypt() function was not implemented, probably
>              because of U.S.A. export restrictions.
>  
>       EPERM  /proc/sys/crypto/fips_enabled has a nonzero value,
>              and an attempt was made to use a weak hashing type,
>              such as DES.
>  
>  ATTRIBUTES
>       For an explanation of the terms used in this section, see
>       attributes(7).
>       ┌─────────────────┬───────────────┬──────────────────────┐
>       │ Interface       │ Attribute     │ Value                │
>       ├─────────────────┼───────────────┼──────────────────────┤
>       │ crypt()         │ Thread safety │ MT‐Unsafe race:crypt │
>       ├─────────────────┼───────────────┼──────────────────────┤
>       │ crypt_r()       │ Thread safety │ MT‐Safe              │
>       └─────────────────┴───────────────┴──────────────────────┘
>  
>  STANDARDS
>       crypt()
>              POSIX.1‐2008.
>  
>       crypt_r()
>              GNU.
>  
>  HISTORY
>       crypt()
>              POSIX.1‐2001, SVr4, 4.3BSD.
>  
>     Availability in glibc
>       The crypt(), encrypt(3), and setkey(3) functions are part
>       of the POSIX.1‐2008 XSI Options Group for Encryption and
>       are optional.  If the interfaces are not available, then
>       the symbolic constant _XOPEN_CRYPT is either not defined,
>       or it is defined to -1 and availability can be checked at
>       run time with sysconf(3).  This may be the case if the
>       downstream distribution has switched from glibc crypt to
>       libxcrypt.  When recompiling applications in such distrib‐
>       utions, the programmer must detect if _XOPEN_CRYPT is not
>       available and include <crypt.h> for the function proto‐
>       types; otherwise libxcrypt is an ABI‐compatible drop‐in
>       replacement.
>  
>  NOTES
> -   Features in glibc
> -     The glibc version of this function supports additional
> -     hashing algorithms.
> -
> +   salt
>       If salt is a character string starting with the characters
>       "$id$" followed by a string optionally terminated by "$",
>       then the result has the form:
>  
>              $id$salt$hashed
>  
>       id identifies the hashing method used instead of DES and
>       this then determines how the rest of the password string
>       is interpreted.  The following values of id are supported:
>              ID   Method
>              ───────────────────────────────────────────────────
>              1    MD5
>              2a   Blowfish (not in mainline glibc; added in
>                   some Linux distributions)
>              5    SHA‐256 (since glibc 2.7)
>              6    SHA‐512 (since glibc 2.7)
>  
>       Thus, $5$salt$hashed and $6$salt$hashed contain the pass‐
>       word hashed with, respectively, functions based on SHA‐256
>       and SHA‐512.
>  
>       "salt" stands for the up to 16 characters following "$id$"
>       in the salt.  The "hashed" part of the password string is
>       the actual computed password.  The size of this string is
>       fixed:
>              MD5       22 characters
>              SHA‐256   43 characters
>              SHA‐512   86 characters
>  
>       The characters in "salt" and "hashed" are drawn from the
>       set [a-zA-Z0-9./].  In the MD5 and SHA implementations the
>       entire key is significant (instead of only the first 8
>       bytes in DES).
>  
>       Since glibc 2.7, the SHA‐256 and SHA‐512 implementations
>       support a user‐supplied number of hashing rounds, default‐
>       ing to 5000.  If the "$id$"charactersinthesaltare followed
>       by "rounds=xxx$", where xxx is an integer, then the result
>       has the form
>  
>              $id$rounds=yyy$salt$hashed
>  
>       where yyy is the number of hashing rounds actually used.
>       The number of rounds actually used is 1000 if xxx is less
>       than 1000, 999999999 if xxx is greater than 999999999, and
>       is equal to xxx otherwise.
>  
>  SEE ALSO
>       login(1), passwd(1), encrypt(3), getpass(3), passwd(5)
>  
>  Linux man‐pages (unreleased) (date)                    crypt(3)
> 
> 
> -- 
> <https://www.alejandro-colomar.es>

Re: [PATCH v1] man/man3/crypt.3: These functions accept many algorithms, not only DES

[Alejandro Colomar]

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

Hi Serge,

> Date: 2026-11-11 09:05:40-0600
> From: "Serge E. Hallyn" <serge@hallyn.com>
>
[...]
> > -     salt is a two‐character string chosen from the set
> > -     [a-zA-Z0-9./].  This string is used to perturb the algo‐
> > -     rithm in one of 4096 different ways.
> > -
> > -     By taking the lowest 7 bits of each of the first eight
> > -     characters of the key, a 56‐bit key is obtained.  This
> > -     56‐bit key is used to encrypt repeatedly a constant string
> > -     (usually a string consisting of all zeros).  The returned
> > -     value points to the hashed password, a series of 13 print‐
> > -     able ASCII characters (the first two characters represent
> > -     the salt itself).  The return value points to static data
> > -     whose content is overwritten by each call.
> > -
> > -     Warning: the key space consists of 2**56 equal 7.2e16 pos‐
> > -     sible values.  Exhaustive searches of this key space are
> > -     possible using massively parallel computers.  Software,
> > -     such as crack(1), is available which will search the por‐
> > -     tion of this key space that is generally used by humans
> > -     for passwords.  Hence, password selection should, at mini‐
> > -     mum, avoid common words and names.  The use of a passwd(1)
> > -     program that checks for crackable passwords during the se‐
> > -     lection process is recommended.
> > -
> > -     The DES algorithm itself has a few quirks which make the
> > -     use of the crypt() interface a very poor choice for any‐
> > -     thing other than password authentication.  If you are
> > -     planning on using the crypt() interface for a cryptography
> > -     project, don’t do it: get a good book on encryption and
> > -     one of the widely available DES libraries.
> > +     salt is a string used for determining the hasing algorithm
> 
> typo: hashing

Thanks!  Fixed.

> > +     (possibly including parameters).  It is also used to per‐
> > +     turb the algorithm.

BTW, I suspect the salt is not used for perturbing the algorithm
anymore.  From musl's source code, at least for SHA-512, I _think_ it's
not reading past the third '$', and thus it's not reading any random-ish
bytes.

Should I drop the second sentence?


Have a lovely night!
Alex

> > +
> > +     The returned value points to the hashed password.  The re‐
> > +     turn value points to static data whose content is over‐
> > +     written by each call.

-- 
<https://www.alejandro-colomar.es>

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

Re: [musl] Re: [PATCH v1] man/man3/crypt.3: These functions accept many algorithms, not only DES

[Rich Felker]

On Wed, Nov 11, 2026 at 07:55:01PM +0100, Alejandro Colomar wrote:
> Hi Serge,
> 
> > Date: 2026-11-11 09:05:40-0600
> > From: "Serge E. Hallyn" <serge@hallyn.com>
> >
> [...]
> > > -     salt is a two‐character string chosen from the set
> > > -     [a-zA-Z0-9./].  This string is used to perturb the algo‐
> > > -     rithm in one of 4096 different ways.
> > > -
> > > -     By taking the lowest 7 bits of each of the first eight
> > > -     characters of the key, a 56‐bit key is obtained.  This
> > > -     56‐bit key is used to encrypt repeatedly a constant string
> > > -     (usually a string consisting of all zeros).  The returned
> > > -     value points to the hashed password, a series of 13 print‐
> > > -     able ASCII characters (the first two characters represent
> > > -     the salt itself).  The return value points to static data
> > > -     whose content is overwritten by each call.
> > > -
> > > -     Warning: the key space consists of 2**56 equal 7.2e16 pos‐
> > > -     sible values.  Exhaustive searches of this key space are
> > > -     possible using massively parallel computers.  Software,
> > > -     such as crack(1), is available which will search the por‐
> > > -     tion of this key space that is generally used by humans
> > > -     for passwords.  Hence, password selection should, at mini‐
> > > -     mum, avoid common words and names.  The use of a passwd(1)
> > > -     program that checks for crackable passwords during the se‐
> > > -     lection process is recommended.
> > > -
> > > -     The DES algorithm itself has a few quirks which make the
> > > -     use of the crypt() interface a very poor choice for any‐
> > > -     thing other than password authentication.  If you are
> > > -     planning on using the crypt() interface for a cryptography
> > > -     project, don’t do it: get a good book on encryption and
> > > -     one of the widely available DES libraries.
> > > +     salt is a string used for determining the hasing algorithm
> > 
> > typo: hashing
> 
> Thanks!  Fixed.
> 
> > > +     (possibly including parameters).  It is also used to per‐
> > > +     turb the algorithm.
> 
> BTW, I suspect the salt is not used for perturbing the algorithm
> anymore.  From musl's source code, at least for SHA-512, I _think_ it's
> not reading past the third '$', and thus it's not reading any random-ish
> bytes.
> 
> Should I drop the second sentence?

I'm not sure where you're getting this from. All implementations of
the same password hash function need to produce the same result, or
user credentials would not be portable between different ones. And a
password hash that does not use any salt would not be fit for purpose.

In musl's crypt_sha512.c, the salt is isolated from the setting string
in lines 262-266 and used in the sha512_update operations that follow.

Rich

Re: [musl] Re: [PATCH v1] man/man3/crypt.3: These functions accept many algorithms, not only DES

[Alejandro Colomar]

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

Hi Rich,

> Date: 2026-11-11 16:13:13-0500
> From: Rich Felker <dalias@libc.org>
>
[...]
> 
> I'm not sure where you're getting this from. All implementations of
> the same password hash function need to produce the same result, or
> user credentials would not be portable between different ones. And a
> password hash that does not use any salt would not be fit for purpose.
> 
> In musl's crypt_sha512.c, the salt is isolated from the setting string
> in lines 262-266 and used in the sha512_update operations that follow.

I'm not a cryptographer, so my reading of that code isn't very good.
Thanks for correcting me!


Have a lovely night!
Alex

> 
> Rich

-- 
<https://www.alejandro-colomar.es>

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

Re: [PATCH v1] man/man3/crypt.3: These functions accept many algorithms, not only DES

[Vincent Lefevre]

Hi,

On 2026-11-10 01:01:19 +0100, Alejandro Colomar wrote:
> $ MANWIDTH=64 diffman-git -U99 HEAD
> --- HEAD^:man/man3/crypt.3
> +++ HEAD:man/man3/crypt.3
[...]
>  STANDARDS
>       crypt()
>              POSIX.1‐2008.
[...]
>  NOTES
> -   Features in glibc
> -     The glibc version of this function supports additional
> -     hashing algorithms.
> -
> +   salt
>       If salt is a character string starting with the characters
>       "$id$" followed by a string optionally terminated by "$",
>       then the result has the form:
>  
>              $id$salt$hashed
[...]

The "$" character is disallowed by POSIX (in 2008 and still in the
current edition) in the salt argument:

  https://pubs.opengroup.org/onlinepubs/9699919799.2008edition/functions/crypt.html
  https://pubs.opengroup.org/onlinepubs/9799919799/functions/crypt.html

(this breaks a "shall").

I think that something should be said about that.

-- 
Vincent Lefèvre <vincent@vinc17.net> - Web: <https://www.vinc17.net/>
100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/>
Work: CR INRIA - computer arithmetic / Pascaline project (LIP, ENS-Lyon)

Re: [PATCH v1] man/man3/crypt.3: These functions accept many algorithms, not only DES

[Rich Felker]

On Thu, Nov 12, 2026 at 02:52:23AM +0100, Vincent Lefevre wrote:
> Hi,
> 
> On 2026-11-10 01:01:19 +0100, Alejandro Colomar wrote:
> > $ MANWIDTH=64 diffman-git -U99 HEAD
> > --- HEAD^:man/man3/crypt.3
> > +++ HEAD:man/man3/crypt.3
> [...]
> >  STANDARDS
> >       crypt()
> >              POSIX.1‐2008.
> [...]
> >  NOTES
> > -   Features in glibc
> > -     The glibc version of this function supports additional
> > -     hashing algorithms.
> > -
> > +   salt
> >       If salt is a character string starting with the characters
> >       "$id$" followed by a string optionally terminated by "$",
> >       then the result has the form:
> >  
> >              $id$salt$hashed
> [...]
> 
> The "$" character is disallowed by POSIX (in 2008 and still in the
> current edition) in the salt argument:
> 
>   https://pubs.opengroup.org/onlinepubs/9699919799.2008edition/functions/crypt.html
>   https://pubs.opengroup.org/onlinepubs/9799919799/functions/crypt.html
> 
> (this breaks a "shall").
> 
> I think that something should be said about that.

That's the whole reason '$' was chosen: POSIX doesn't define the
behavior (since a "shall" is violated) so the implementation is free
to define a behavior here. The behaviors for the portable base64
character set documented in POSIX uses only 2 characters as salt
(insufficient) and the common agreed-upon definition for how they are
used is as salt for the classic DES-based password hash.

Rich

Re: [PATCH v1] man/man3/crypt.3: These functions accept many algorithms, not only DES

[Vincent Lefevre]

On 2026-11-11 21:53:39 -0500, Rich Felker wrote:
> That's the whole reason '$' was chosen: POSIX doesn't define the
> behavior (since a "shall" is violated) so the implementation is free
> to define a behavior here. The behaviors for the portable base64
> character set documented in POSIX uses only 2 characters as salt
> (insufficient) and the common agreed-upon definition for how they are
> used is as salt for the classic DES-based password hash.

But the behavior is completely out of scope of POSIX.

-- 
Vincent Lefèvre <vincent@vinc17.net> - Web: <https://www.vinc17.net/>
100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/>
Work: CR INRIA - computer arithmetic / Pascaline project (LIP, ENS-Lyon)

Re: [musl] Re: [PATCH v1] man/man3/crypt.3: These functions accept many algorithms, not only DES

[Rich Felker]

On Thu, Nov 12, 2026 at 04:29:29AM +0100, Vincent Lefevre wrote:
> On 2026-11-11 21:53:39 -0500, Rich Felker wrote:
> > That's the whole reason '$' was chosen: POSIX doesn't define the
> > behavior (since a "shall" is violated) so the implementation is free
> > to define a behavior here. The behaviors for the portable base64
> > character set documented in POSIX uses only 2 characters as salt
> > (insufficient) and the common agreed-upon definition for how they are
> > used is as salt for the classic DES-based password hash.
> 
> But the behavior is completely out of scope of POSIX.

Yes. And that's allowed because POSIX does not define the behavior but
leaves it undefined. I'm not sure if you're objecting to something
here or questioning how it should be documented or something else..?

Rich

Re: [musl] Re: [PATCH v1] man/man3/crypt.3: These functions accept many algorithms, not only DES

[Alejandro Colomar]

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

Hi Rich, Vincent,

> Date: 2026-11-11 22:37:42-0500
> From: Rich Felker <dalias@libc.org>
>
> On Thu, Nov 12, 2026 at 04:29:29AM +0100, Vincent Lefevre wrote:
> > On 2026-11-11 21:53:39 -0500, Rich Felker wrote:
> > > That's the whole reason '$' was chosen: POSIX doesn't define the
> > > behavior (since a "shall" is violated) so the implementation is free
> > > to define a behavior here. The behaviors for the portable base64
> > > character set documented in POSIX uses only 2 characters as salt
> > > (insufficient) and the common agreed-upon definition for how they are
> > > used is as salt for the classic DES-based password hash.
> > 
> > But the behavior is completely out of scope of POSIX.
> 
> Yes. And that's allowed because POSIX does not define the behavior but
> leaves it undefined. I'm not sure if you're objecting to something
> here or questioning how it should be documented or something else..?

Yeah, I think it'd be okay to document that this is an extension to
POSIX.  Perhaps, we could add this:

	@@ -111,6 +111,9 @@ .SH ATTRIBUTES
	 .BR crypt_r ()
	 T}     Thread safety   MT-Safe
	 .TE
	+.SH VERSIONS
	+While POSIX only specifies the DES algorithms for these functions,
	+all systems implement several other algorithms.
	 .SH STANDARDS
	 .TP
	 .BR crypt ()



Have a lovely day!
Alex

> 
> Rich

-- 
<https://www.alejandro-colomar.es>

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

Re: [musl] Re: [PATCH v1] man/man3/crypt.3: These functions accept many algorithms, not only DES

[Vincent Lefevre]

On 2026-11-12 11:28:20 +0100, Alejandro Colomar wrote:
> Yeah, I think it'd be okay to document that this is an extension to
> POSIX.  Perhaps, we could add this:
> 
> 	@@ -111,6 +111,9 @@ .SH ATTRIBUTES
> 	 .BR crypt_r ()
> 	 T}     Thread safety   MT-Safe
> 	 .TE
> 	+.SH VERSIONS
> 	+While POSIX only specifies the DES algorithms for these functions,
> 	+all systems implement several other algorithms.

No, POSIX just says: "The algorithm is implementation-defined."
No mention of DES algorithms at all.

And note that only ENOSYS is specified as a case of failure,
which could explain why some applications do not check whether
the returned value is a null pointer (i.e. they assume that if
crypt() succeeds in usual cases, then an ENOSYS error is not
possible and crypt() never fails).

But my point was that POSIX disallows the "$" character in salt:

  [...] The salt argument shall be a string of at least two bytes
  in length not including the null character chosen from the set:

  a b c d e f g h i j k l m n o p q r s t u v w x y z
  A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
  0 1 2 3 4 5 6 7 8 9 . /

This means that when "$" is supported by some implementation,
the interpretation of the return value may be different from
what POSIX specifies.

Various people said that the choice of returning "*" in case of
failure as done by musl was a violation of POSIX. But this is
not true for 2 reasons:
  * the use of the "$" character in salt by the application;
  * the fact that POSIX does not give any requirement on the
    hash (so the use of a hash that could be interpreted as
    being invalid on the system for unsupported passwords is
    a valid behavior).

-- 
Vincent Lefèvre <vincent@vinc17.net> - Web: <https://www.vinc17.net/>
100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/>
Work: CR INRIA - computer arithmetic / Pascaline project (LIP, ENS-Lyon)

Re: [musl] Re: [PATCH v1] man/man3/crypt.3: These functions accept many algorithms, not only DES

[Alejandro Colomar]

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

Hi Vincent,

> Date: 2026-11-12 12:40:33+0100
> From: Vincent Lefevre <vincent@vinc17.net>
>
> On 2026-11-12 11:28:20 +0100, Alejandro Colomar wrote:
> > Yeah, I think it'd be okay to document that this is an extension to
> > POSIX.  Perhaps, we could add this:
> > 
> > 	@@ -111,6 +111,9 @@ .SH ATTRIBUTES
> > 	 .BR crypt_r ()
> > 	 T}     Thread safety   MT-Safe
> > 	 .TE
> > 	+.SH VERSIONS
> > 	+While POSIX only specifies the DES algorithms for these functions,
> > 	+all systems implement several other algorithms.
> 
> No, POSIX just says: "The algorithm is implementation-defined."
> No mention of DES algorithms at all.

Oh right.

> And note that only ENOSYS is specified as a case of failure,
> which could explain why some applications do not check whether
> the returned value is a null pointer (i.e. they assume that if
> crypt() succeeds in usual cases, then an ENOSYS error is not
> possible and crypt() never fails).
> 
> But my point was that POSIX disallows the "$" character in salt:
> 
>   [...] The salt argument shall be a string of at least two bytes
>   in length not including the null character chosen from the set:
> 
>   a b c d e f g h i j k l m n o p q r s t u v w x y z
>   A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
>   0 1 2 3 4 5 6 7 8 9 . /

Isn't that salt specification used exclusively by DES?
So, while POSIX doesn't specify the algorithm, it is consensus that
a call that is strictly conforming to POSIX will result in DES being
used.

> This means that when "$" is supported by some implementation,
> the interpretation of the return value may be different from
> what POSIX specifies.

Kind of.  They better don't deviate from it in non-confirming ways;
one could argue that musl's "x" return value is indeed such a
non-conforming return value, and a NULL return value would be better
(both more conforming and safer).

> Various people said that the choice of returning "*" in case of
> failure as done by musl was a violation of POSIX. But this is
> not true for 2 reasons:
>   * the use of the "$" character in salt by the application;
>   * the fact that POSIX does not give any requirement on the
>     hash (so the use of a hash that could be interpreted as
>     being invalid on the system for unsupported passwords is
>     a valid behavior).

I think that's a stretch of the undefined behavior.  Yes, in theory one
has passed an invalid salt, and then anything may happen.  But given
that POSIX specifies the return value in a way that doesn't seem
incompatible with this extension, I think it would be more appropriate
to behave in a way that conforms to this specification.

	Upon successful completion,
	crypt() shall return a pointer to the hashed password;
	the first two bytes of the returned value
	shall be those of the salt argument.
	Otherwise,
	it shall return a null pointer and set errno to indicate the error.

Given that there's no successfully hashed password, I think it'd be most
appropriate to return a null pointer.


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es>

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

Re: [musl] Re: [PATCH v1] man/man3/crypt.3: These functions accept many algorithms, not only DES

[Rich Felker]

On Thu, Nov 12, 2026 at 11:28:20AM +0100, Alejandro Colomar wrote:
> Hi Rich, Vincent,
> 
> > Date: 2026-11-11 22:37:42-0500
> > From: Rich Felker <dalias@libc.org>
> >
> > On Thu, Nov 12, 2026 at 04:29:29AM +0100, Vincent Lefevre wrote:
> > > On 2026-11-11 21:53:39 -0500, Rich Felker wrote:
> > > > That's the whole reason '$' was chosen: POSIX doesn't define the
> > > > behavior (since a "shall" is violated) so the implementation is free
> > > > to define a behavior here. The behaviors for the portable base64
> > > > character set documented in POSIX uses only 2 characters as salt
> > > > (insufficient) and the common agreed-upon definition for how they are
> > > > used is as salt for the classic DES-based password hash.
> > > 
> > > But the behavior is completely out of scope of POSIX.
> > 
> > Yes. And that's allowed because POSIX does not define the behavior but
> > leaves it undefined. I'm not sure if you're objecting to something
> > here or questioning how it should be documented or something else..?
> 
> Yeah, I think it'd be okay to document that this is an extension to
> POSIX.  Perhaps, we could add this:
> 
> 	@@ -111,6 +111,9 @@ .SH ATTRIBUTES
> 	 .BR crypt_r ()
> 	 T}     Thread safety   MT-Safe
> 	 .TE
> 	+.SH VERSIONS
> 	+While POSIX only specifies the DES algorithms for these functions,
> 	+all systems implement several other algorithms.

POSIX doesn't specify any algorithm. It specifies the input format for
salt in a way that's aligned with the traditional DES password hashing
algorithm but it doesn't assign any actual definition for the
algorithm.

DES hash provides the implementation-defined algorithm POSIX mandates
exists but doesn't specify. The other hashes fill in the gaps where
the specification leaves things undefined.

For practical purposes POSIX is irrelevant to the way you choose salt
strings for producing new password hashes; it only specifies how to
call the function and validate a password against a hash.

Rich

Re: [musl] Re: [PATCH v1] man/man3/crypt.3: These functions accept many algorithms, not only DES

[Alejandro Colomar]

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

Hi Rich,

> Date: 2026-11-12 07:08:32-0500
> From: Rich Felker <dalias@libc.org>
>
[...]
> > 	+.SH VERSIONS
> > 	+While POSIX only specifies the DES algorithms for these functions,
> > 	+all systems implement several other algorithms.
> 
> POSIX doesn't specify any algorithm. It specifies the input format for
> salt in a way that's aligned with the traditional DES password hashing
> algorithm but it doesn't assign any actual definition for the
> algorithm.
> 
> DES hash provides the implementation-defined algorithm POSIX mandates
> exists but doesn't specify. The other hashes fill in the gaps where
> the specification leaves things undefined.
> 
> For practical purposes POSIX is irrelevant to the way you choose salt
> strings for producing new password hashes; it only specifies how to
> call the function and validate a password against a hash.

How about something this (we can improve the wording)?

	diff --git i/man/man3/crypt.3 w/man/man3/crypt.3
	index 524781d3c2a0..d579bc5394fb 100644
	--- i/man/man3/crypt.3
	+++ w/man/man3/crypt.3
	@@ -111,6 +111,9 @@ .SH ATTRIBUTES
	 .BR crypt_r ()
	 T}     Thread safety   MT-Safe
	 .TE
	+.SH VERSIONS
	+POSIX specifies a quite useless API,
	+and all systems extend it significantly.
	 .SH STANDARDS
	 .TP
	 .BR crypt ()


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es>

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

Re: [musl] Re: [PATCH v1] man/man3/crypt.3: These functions accept many algorithms, not only DES

[Szabolcs Nagy]

* Alejandro Colomar <alx+linux-man@kernel.org> [2026-11-12 13:27:13 +0100]:
> How about something this (we can improve the wording)?
> 
> 	diff --git i/man/man3/crypt.3 w/man/man3/crypt.3
> 	index 524781d3c2a0..d579bc5394fb 100644
> 	--- i/man/man3/crypt.3
> 	+++ w/man/man3/crypt.3
> 	@@ -111,6 +111,9 @@ .SH ATTRIBUTES
> 	 .BR crypt_r ()
> 	 T}     Thread safety   MT-Safe
> 	 .TE
> 	+.SH VERSIONS
> 	+POSIX specifies a quite useless API,
> 	+and all systems extend it significantly.

please don't put nonsense into the official man pages.

your job is to document the interface contract including
implementation defined behaviour, not to judge the spec
and other systems.

Re: [musl] Re: [PATCH v1] man/man3/crypt.3: These functions accept many algorithms, not only DES

[Alejandro Colomar]

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

Hi Szabolcs,

> Date: 2026-11-12 13:41:14+0100
> From: Szabolcs Nagy <nsz@port70.net>
>
> * Alejandro Colomar <alx+linux-man@kernel.org> [2026-11-12 13:27:13 +0100]:
> > How about something this (we can improve the wording)?
> > 
> > 	diff --git i/man/man3/crypt.3 w/man/man3/crypt.3
> > 	index 524781d3c2a0..d579bc5394fb 100644
> > 	--- i/man/man3/crypt.3
> > 	+++ w/man/man3/crypt.3
> > 	@@ -111,6 +111,9 @@ .SH ATTRIBUTES
> > 	 .BR crypt_r ()
> > 	 T}     Thread safety   MT-Safe
> > 	 .TE
> > 	+.SH VERSIONS
> > 	+POSIX specifies a quite useless API,
> > 	+and all systems extend it significantly.
> 
> please don't put nonsense into the official man pages.

I agree I could have used more precise wording.

I think you could have used more precise wording too, since you're
complaining about that.  What is nonsense in what I said?  Is it perhaps
too offensive?  Yes; I think I should have said s/useless/limited/.

Is it completely nonsense?  I think not.

> your job

Ironically, your job is *not* to judge or specify my job (if it's a job
at all).

I suggest that you limit yourself to comment on what *the manual pages*
should say, rather than on what *I* should do.

I'll continue as if you had said s/your job/the job of the manual pages/

> is to document the interface contract including
> implementation defined behaviour,

The contract is specified in the sections of the manual page that are
meant for that, such as DESCRIPTION, RETURN VALUE, etc.

VERSIONS is a section for discussing differences between
implementations, and between implementations and the spec (although this
might also go in STANDARDS; it's a blurry line).

> not to judge the spec

I do agree that we should not judge the spec unnecessarily.

But about what you said literally, I disagree.  The manual pages have
been full of opinions --where appropriate-- since the very early times
of manual pages.  Already in the early BSDs there were comments about
strncpy(3), for example.

Here's some of them:

	$ git show man-pages-5.00:man3/strcpy.3 \
	| MANWIDTH=64 lman /dev/stdin \
	| grep -A5 NOTES;
	NOTES
	     Some  programmers consider strncpy() to be inefficient and
	     error prone.  If the programmer knows (i.e., includes code
	     to test!)  that the size  of  dest  is  greater  than  the
	     length of src, then strcpy() can be used.

See <https://lore.kernel.org/linux-man/anJZza-qbi_y5r1N@devuan/> for
a (incomplete) list of historic counter-examples.

> and other systems.

I didn't judge other systems, I think.


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es>

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

Re: [musl] Re: [PATCH v1] man/man3/crypt.3: These functions accept many algorithms, not only DES

[Vincent Lefevre]

On 2026-11-12 13:08:12 +0100, Alejandro Colomar wrote:
> > This means that when "$" is supported by some implementation,
> > the interpretation of the return value may be different from
> > what POSIX specifies.
> 
> Kind of.  They better don't deviate from it in non-confirming ways;
> one could argue that musl's "x" return value is indeed such a
> non-conforming return value, and a NULL return value would be better
> (both more conforming and safer).

This is more complex. The issue is that in the past, crypt() seemed to
have been designed so that it could not fail (except in the case where
it wasn't providing any implementation, i.e. it was always failing),
so that applications did not expect a null pointer and some of them
still do not check this case. Hence the choice done my musl.

Problems could be avoided only by writing more robust applications:
  * They should have had a check for the null pointer.
  * When a hash is obtained, applications should also check
    whether the hash has the expected form (for instance,
    the "*" returned by musl does not).

-- 
Vincent Lefèvre <vincent@vinc17.net> - Web: <https://www.vinc17.net/>
100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/>
Work: CR INRIA - computer arithmetic / Pascaline project (LIP, ENS-Lyon)

Re: [musl] Re: [PATCH v1] man/man3/crypt.3: These functions accept many algorithms, not only DES

[Vincent Lefevre]

On 2026-11-12 13:27:13 +0100, Alejandro Colomar wrote:
> How about something this (we can improve the wording)?
> 
> 	diff --git i/man/man3/crypt.3 w/man/man3/crypt.3
> 	index 524781d3c2a0..d579bc5394fb 100644
> 	--- i/man/man3/crypt.3
> 	+++ w/man/man3/crypt.3
> 	@@ -111,6 +111,9 @@ .SH ATTRIBUTES
> 	 .BR crypt_r ()
> 	 T}     Thread safety   MT-Safe
> 	 .TE
> 	+.SH VERSIONS
> 	+POSIX specifies a quite useless API,
> 	+and all systems extend it significantly.
> 	 .SH STANDARDS
> 	 .TP
> 	 .BR crypt ()

The API was useful in the past, but things have evolved.
Just say that all systems extend the POSIX specification
significantly.

-- 
Vincent Lefèvre <vincent@vinc17.net> - Web: <https://www.vinc17.net/>
100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/>
Work: CR INRIA - computer arithmetic / Pascaline project (LIP, ENS-Lyon)

Re: [musl] Re: [PATCH v1] man/man3/crypt.3: These functions accept many algorithms, not only DES

[Alejandro Colomar]

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

Hi Vincent,

> Date: 2026-11-12 14:17:37+0100
> From: Vincent Lefevre <vincent@vinc17.net>
>
> On 2026-11-12 13:27:13 +0100, Alejandro Colomar wrote:
> > How about something this (we can improve the wording)?
> > 
> > 	diff --git i/man/man3/crypt.3 w/man/man3/crypt.3
> > 	index 524781d3c2a0..d579bc5394fb 100644
> > 	--- i/man/man3/crypt.3
> > 	+++ w/man/man3/crypt.3
> > 	@@ -111,6 +111,9 @@ .SH ATTRIBUTES
> > 	 .BR crypt_r ()
> > 	 T}     Thread safety   MT-Safe
> > 	 .TE
> > 	+.SH VERSIONS
> > 	+POSIX specifies a quite useless API,
> > 	+and all systems extend it significantly.
> > 	 .SH STANDARDS
> > 	 .TP
> > 	 .BR crypt ()
> 
> The API was useful in the past, but things have evolved.
> Just say that all systems extend the POSIX specification
> significantly.

Hmm, yeah, I didn't intend to say POSIX is bad; I just wanted to let
people know that POSIX is irrelevant about crypt(3) these days (as Rich
said).  Perhaps:

	The POSIX specification is significantly outdated,
	and all systems extend it significantly.

What do you think?


Cheers,
Alex

> 
> -- 
> Vincent Lefèvre <vincent@vinc17.net> - Web: <https://www.vinc17.net/>
> 100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/>
> Work: CR INRIA - computer arithmetic / Pascaline project (LIP, ENS-Lyon)
> 

-- 
<https://www.alejandro-colomar.es>

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

Re: [musl] Re: [PATCH v1] man/man3/crypt.3: These functions accept many algorithms, not only DES

[Alejandro Colomar]

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

Hi Vincent,

> Date: 2026-11-12 14:15:47+0100
> From: Vincent Lefevre <vincent@vinc17.net>
>
> On 2026-11-12 13:08:12 +0100, Alejandro Colomar wrote:
> > > This means that when "$" is supported by some implementation,
> > > the interpretation of the return value may be different from
> > > what POSIX specifies.
> > 
> > Kind of.  They better don't deviate from it in non-confirming ways;
> > one could argue that musl's "x" return value is indeed such a
> > non-conforming return value, and a NULL return value would be better
> > (both more conforming and safer).
> 
> This is more complex. The issue is that in the past, crypt() seemed to
> have been designed so that it could not fail (except in the case where
> it wasn't providing any implementation, i.e. it was always failing),
> so that applications did not expect a null pointer and some of them
> still do not check this case. Hence the choice done my musl.

It would be interesting to list all FOSS programs that forget to check
for NULL, and perhaps talk to them to update their code.


Cheers,
Alex

> Problems could be avoided only by writing more robust applications:
>   * They should have had a check for the null pointer.
>   * When a hash is obtained, applications should also check
>     whether the hash has the expected form (for instance,
>     the "*" returned by musl does not).
> 
> -- 
> Vincent Lefèvre <vincent@vinc17.net> - Web: <https://www.vinc17.net/>
> 100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/>
> Work: CR INRIA - computer arithmetic / Pascaline project (LIP, ENS-Lyon)

-- 
<https://www.alejandro-colomar.es>

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

Re: [musl] Re: [PATCH v1] man/man3/crypt.3: These functions accept many algorithms, not only DES

[Vincent Lefevre]

FYI, Debian uses the man page from Openwall Project October 11, 2017,
which has sections about portability.

It is available online there:

  https://man.cx/CRYPT(3)

-- 
Vincent Lefèvre <vincent@vinc17.net> - Web: <https://www.vinc17.net/>
100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/>
Work: CR INRIA - computer arithmetic / Pascaline project (LIP, ENS-Lyon)

Re: [musl] Re: [PATCH v1] man/man3/crypt.3: These functions accept many algorithms, not only DES

[Vincent Lefevre]

On 2026-11-12 14:23:08 +0100, Alejandro Colomar wrote:
> Hmm, yeah, I didn't intend to say POSIX is bad; I just wanted to let
> people know that POSIX is irrelevant about crypt(3) these days (as Rich
> said).  Perhaps:
> 
> 	The POSIX specification is significantly outdated,
> 	and all systems extend it significantly.
> 
> What do you think?

OK for me.

-- 
Vincent Lefèvre <vincent@vinc17.net> - Web: <https://www.vinc17.net/>
100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/>
Work: CR INRIA - computer arithmetic / Pascaline project (LIP, ENS-Lyon)

Re: [musl] Re: [PATCH v1] man/man3/crypt.3: These functions accept many algorithms, not only DES

[Rich Felker]

On Thu, Nov 12, 2026 at 02:45:16PM +0100, Vincent Lefevre wrote:
> On 2026-11-12 14:23:08 +0100, Alejandro Colomar wrote:
> > Hmm, yeah, I didn't intend to say POSIX is bad; I just wanted to let
> > people know that POSIX is irrelevant about crypt(3) these days (as Rich
> > said).  Perhaps:
> > 
> > 	The POSIX specification is significantly outdated,
> > 	and all systems extend it significantly.
> > 
> > What do you think?
> 
> OK for me.

It's not "outdated". It just does not mandate particular algorithms
but leaves these choices up to the implementation. As usual the scope
of POSIX is what applications need to know to interface with the
system, not administrative policy. This is why POSIX doesn't define
things like mount, how init works, etc. either. They are in the scope
of things that applications generally don't have to care about; only
system components do.

I do think there are changes to the POSIX crypt spec that could make
it better, like defining more errors and specifying explicitly that
salts beginning with '$' and '_' select additional
implementation-defined algorithms and settings, etc. But overall the
issue here is just a difference in expectation, not anything
inherently bad.

Rich

Re: [musl] Re: [PATCH v1] man/man3/crypt.3: These functions accept many algorithms, not only DES

[Alejandro Colomar]

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

Hi Rich,

> Date: 2026-11-12 08:55:01-0500
> From: Rich Felker <dalias@libc.org>
>
> On Thu, Nov 12, 2026 at 02:45:16PM +0100, Vincent Lefevre wrote:
> > On 2026-11-12 14:23:08 +0100, Alejandro Colomar wrote:
> > > Hmm, yeah, I didn't intend to say POSIX is bad; I just wanted to let
> > > people know that POSIX is irrelevant about crypt(3) these days (as Rich
> > > said).  Perhaps:
> > > 
> > > 	The POSIX specification is significantly outdated,
> > > 	and all systems extend it significantly.
> > > 
> > > What do you think?
> > 
> > OK for me.
> 
> It's not "outdated". It just does not mandate particular algorithms
> but leaves these choices up to the implementation. As usual the scope
> of POSIX is what applications need to know to interface with the
> system, not administrative policy. This is why POSIX doesn't define
> things like mount, how init works, etc. either. They are in the scope
> of things that applications generally don't have to care about; only
> system components do.

But is the POSIX specification really useful for applications?
An application is probably not interested in knowing that it shall
pass two characters as the salt from the set './[A-Za-z]'.
An application should not rely on the specified return value either.

> 
> I do think there are changes to the POSIX crypt spec that could make
> it better, like defining more errors and specifying explicitly that
> salts beginning with '$' and '_' select additional
> implementation-defined algorithms and settings, etc. But overall the
> issue here is just a difference in expectation, not anything
> inherently bad.

I agree it's not inherently bad.  It's just that extensions have grown
for a long time, and deviated between themselves for various reasons
(most notably in the return value), enough that programmers must be
aware of too many implementation-defined details that they should
entirely ignore POSIX.


Cheers,
Alex

> Rich
> 

-- 
<https://www.alejandro-colomar.es>

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

Re: [musl] Re: [PATCH v1] man/man3/crypt.3: These functions accept many algorithms, not only DES

[Rich Felker]

On Thu, Nov 12, 2026 at 03:07:14PM +0100, Alejandro Colomar wrote:
> Hi Rich,
> 
> > Date: 2026-11-12 08:55:01-0500
> > From: Rich Felker <dalias@libc.org>
> >
> > On Thu, Nov 12, 2026 at 02:45:16PM +0100, Vincent Lefevre wrote:
> > > On 2026-11-12 14:23:08 +0100, Alejandro Colomar wrote:
> > > > Hmm, yeah, I didn't intend to say POSIX is bad; I just wanted to let
> > > > people know that POSIX is irrelevant about crypt(3) these days (as Rich
> > > > said).  Perhaps:
> > > > 
> > > > 	The POSIX specification is significantly outdated,
> > > > 	and all systems extend it significantly.
> > > > 
> > > > What do you think?
> > > 
> > > OK for me.
> > 
> > It's not "outdated". It just does not mandate particular algorithms
> > but leaves these choices up to the implementation. As usual the scope
> > of POSIX is what applications need to know to interface with the
> > system, not administrative policy. This is why POSIX doesn't define
> > things like mount, how init works, etc. either. They are in the scope
> > of things that applications generally don't have to care about; only
> > system components do.
> 
> But is the POSIX specification really useful for applications?

Yes. It tells you enough to validate a password for authentication
purposes:

	const char *result = crypt(password, hash);
	if (result && strcmp(result, hash)==0) {
		/* password validated */
	}

> An application is probably not interested in knowing that it shall
> pass two characters as the salt from the set './[A-Za-z]'.

Yes, it's less useful to know that, unless you don't care about hash
strength or portability to other systems. In that case you can use it
to make hashes.

> An application should not rely on the specified return value either.

It can rely on it for validating passwords against existing hashes.
That is the more usual application need. Setting new passwords is
usually an administrative task, except for non-system uses like making
.htaccess files.

Rich

Re: [musl] Re: [PATCH v1] man/man3/crypt.3: These functions accept many algorithms, not only DES

[Alejandro Colomar]

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

Hi Rich,

> Date: 2026-11-12 09:43:49-0500
> From: Rich Felker <dalias@libc.org>
>
[...]
> > But is the POSIX specification really useful for applications?
> 
> Yes. It tells you enough to validate a password for authentication
> purposes:
> 
> 	const char *result = crypt(password, hash);
> 	if (result && strcmp(result, hash)==0) {
> 		/* password validated */
> 	}

Is this really specified by POSIX?

Unless I'm missing something, I only see something about it in EXAMPLES,
which is non-normative, and it doesn't even explain that this is the
only way to do it correctly, but rather as a possible example.  Notably,
I don't find any text that says that passing a different hash as salt
could potentially result in a hash that matches the stored hash.

That is, I don't see any text (normative or non-normative) in the POSIX
specification that implies this:

            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.

The example is useful, but I'd say it's not enough.  I think the example
should contain wording like that one above (which we're discussing in
the other thread for the manual page).


Cheers,
alex

[...]
> 
> > An application should not rely on the specified return value either.
> 
> It can rely on it for validating passwords against existing hashes.
> That is the more usual application need. Setting new passwords is
> usually an administrative task, except for non-system uses like making
> .htaccess files.
> 
> Rich

-- 
<https://www.alejandro-colomar.es>

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

Re: [musl] Re: [PATCH v1] man/man3/crypt.3: These functions accept many algorithms, not only DES

[Rich Felker]

On Thu, Nov 12, 2026 at 03:58:30PM +0100, Alejandro Colomar wrote:
> Hi Rich,
> 
> > Date: 2026-11-12 09:43:49-0500
> > From: Rich Felker <dalias@libc.org>
> >
> [...]
> > > But is the POSIX specification really useful for applications?
> > 
> > Yes. It tells you enough to validate a password for authentication
> > purposes:
> > 
> > 	const char *result = crypt(password, hash);
> > 	if (result && strcmp(result, hash)==0) {
> > 		/* password validated */
> > 	}
> 
> Is this really specified by POSIX?
> 
> Unless I'm missing something, I only see something about it in EXAMPLES,
> which is non-normative, and it doesn't even explain that this is the
> only way to do it correctly, but rather as a possible example.

Indeed it's what I'd call "underspecified", but it's clear from the
example that this is the intended usage.

> Notably,
> I don't find any text that says that passing a different hash as salt
> could potentially result in a hash that matches the stored hash.

The lack of specifying anything about whether that's possible doesn't
mean you can assume it's not.

> That is, I don't see any text (normative or non-normative) in the POSIX
> specification that implies this:
> 
>             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.
> 
> The example is useful, but I'd say it's not enough.  I think the example
> should contain wording like that one above (which we're discussing in
> the other thread for the manual page).

It says that the hash is a function of the password and the salt
characters. So obviously, if the password is correct,
strcmp(hash,crypt(pass,hash))==0. Whether it's nonzero for other
values of pass depends on the degree to which the hash is
collision-free, which is of course implementation-defined but needs to
be good in order to have any reasonable security properties.

Whether another hash can be passed to setting without risking
collisions is just not something that's specified, so you can't assume
it. It should be noted that the APPLICATION USAGE text mentions:

    "Several implementations offer extensions via characters outside
    of the set specified for the salt argument for specifying
    alternative algorithms; while not portable, these extensions may
    offer better security."

You do not need a specification to tell you that passing the wrong
hash as setting is unsafe. You only need to look at the scope of
implementation choices allowed and consider whether they would admit
anything that would make it unsafe. And they do.


As an aside, can we please remove the language using nonstandard
gnulib functions (streq) that are not part of any standard library?
This is not doing anyone a service. Experienced C programmers will
understand it as essentially pseudocode and write something correct
themselves, but novices will be confused why their code doesn't work.
I assume you have some sort of thing against strcmp, but that kind of
polemic treatment does not belong in descriptive documentation.

Rich

Re: [musl] Re: [PATCH v1] man/man3/crypt.3: These functions accept many algorithms, not only DES

[Alejandro Colomar]

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

Hi Rich,

> Date: 2026-11-12 13:08:52-0500
> From: Rich Felker <dalias@libc.org>
>
[...]
> As an aside, can we please remove the language using nonstandard
> gnulib functions (streq) that are not part of any standard library?
> This is not doing anyone a service. Experienced C programmers will
> understand it as essentially pseudocode and write something correct
> themselves, but novices will be confused why their code doesn't work.

Okay.

> I assume you have some sort of thing against strcmp,

I do.

> but that kind of
> polemic treatment does not belong in descriptive documentation.

Ok.

As an aside, would you mind implementing streq(3) in musl?


Have a lovely night!
Alex

> 
> Rich

-- 
<https://www.alejandro-colomar.es>

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