[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <avSERDjw/CeqN60U@hallyn.com>
Date: Wed, 11 Nov 2026 09:05:40 -0600
From: "Serge E. Hallyn" <serge@...lyn.com>
To: Alejandro Colomar <alx+linux-man@...nel.org>
Cc: Alejandro Colomar <alx@...nel.org>, linux-man@...r.kernel.org,
libc-alpha@...rceware.org, Walter Harms <wharms@....de>,
Rich Felker <dalias@...c.org>, ~hallyn/shadow@...ts.sr.ht,
musl@...ts.openwall.com
Subject: Re: [PATCH v1] man/man3/crypt.3: These functions accept many
algorithms, not only DES
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@...nel.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@...nel.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>
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.
