Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 319 insertions, 0 deletions

diff --git a/man/man3/crypt.3 b/man/man3/crypt.3
new file mode 100644
index 0000000..831a530
--- /dev/null
+++ b/man/man3/crypt.3
@@ -0,0 +1,319 @@
+'\" t
+.\" Michael Haardt (michael@cantor.informatik.rwth.aachen.de)
+.\"     Sat Sep  3 22:00:30 MET DST 1994
+.\"
+.\" SPDX-License-Identifier: GPL-2.0-or-later
+.\"
+.\" Sun Feb 19 21:32:25 1995, faith@cs.unc.edu edited details away
+.\"
+.\" TO DO: This manual page should go more into detail how DES is perturbed,
+.\" which string will be encrypted, and what determines the repetition factor.
+.\" Is a simple repetition using ECB used, or something more advanced?  I hope
+.\" the presented explanations are at least better than nothing, but by no
+.\" means enough.
+.\"
+.\" added _XOPEN_SOURCE, aeb, 970705
+.\" added GNU MD5 stuff, aeb, 011223
+.\"
+.TH crypt 3 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+crypt, crypt_r \- password hashing
+.SH LIBRARY
+Password hashing library
+.RI ( libcrypt ", " \-lcrypt )
+.SH SYNOPSIS
+.nf
+.B #include <unistd.h>
+.P
+.BI "char *crypt(const char *" key ", const char *" salt );
+.P
+.B #include <crypt.h>
+.P
+.BI "char *crypt_r(const char *" key ", const char *" salt ,
+.BI "              struct crypt_data *restrict " data );
+.fi
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.BR crypt ():
+.nf
+    Since glibc 2.28:
+        _DEFAULT_SOURCE
+    glibc 2.27 and earlier:
+        _XOPEN_SOURCE
+.fi
+.P
+.BR crypt_r ():
+.nf
+    _GNU_SOURCE
+.fi
+.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
+[\fBa\-zA\-Z0\-9./\fP].
+This string is used to
+perturb the algorithm in one of 4096 different ways.
+.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).
+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 ().
+The structure pointed to by
+.I 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
+.I data\->initialized
+to zero before the first call to
+.BR crypt_r ().
+.SH RETURN VALUE
+On success, a pointer to the hashed password is returned.
+On error, NULL is returned.
+.SH ERRORS
+.TP
+.B EINVAL
+.I salt
+has the wrong format.
+.TP
+.B ENOSYS
+The
+.BR crypt ()
+function was not implemented, probably because of U.S.A. export restrictions.
+.\" This 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
+has a nonzero value,
+and an attempt was made to use a weak hashing type, such as DES.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR crypt ()
+T}	Thread safety	MT-Unsafe race:crypt
+T{
+.na
+.nh
+.BR crypt_r ()
+T}	Thread safety	MT-Safe
+.TE
+.SH STANDARDS
+.TP
+.BR crypt ()
+POSIX.1-2008.
+.TP
+.BR crypt_r ()
+GNU.
+.SH HISTORY
+.TP
+.BR crypt ()
+POSIX.1-2001, SVr4, 4.3BSD.
+.SS Availability in glibc
+The
+.BR crypt (),
+.BR encrypt (3),
+and
+.BR 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
+.B _XOPEN_CRYPT
+is either not defined,
+or it is defined to \-1 and availability can be checked at run time with
+.BR sysconf (3).
+This may be the case if the downstream distribution has switched from glibc
+crypt to
+.IR libxcrypt .
+When recompiling applications in such distributions,
+the programmer must detect if
+.B _XOPEN_CRYPT
+is not available and include
+.I <crypt.h>
+for the function prototypes;
+otherwise
+.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
+If
+.I salt
+is a character string starting with the characters "$\fIid\fP$"
+followed by a string optionally terminated by "$",
+then the result has the form:
+.RS
+.P
+$\fIid\fP$\fIsalt\fP$\fIhashed\fP
+.RE
+.P
+.I 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
+.I id
+are supported:
+.RS
+.TS
+lb lb
+l lx.
+ID	Method
+_
+1	MD5
+2a	T{
+Blowfish (not in mainline glibc; added in some
+Linux distributions)
+T}
+.\" openSUSE has Blowfish, but AFAICS, this option is not supported
+.\" natively by glibc -- mtk, Jul 08
+.\"
+.\" md5 | Sun MD5
+.\" glibc doesn't appear to natively support Sun MD5; I don't know
+.\" if any distros add the support.
+5	SHA-256 (since glibc 2.7)
+6	SHA-512 (since glibc 2.7)
+.TE
+.RE
+.P
+Thus, $5$\fIsalt\fP$\fIhashed\fP and $6$\fIsalt\fP$\fIhashed\fP
+contain the password hashed with, respectively, functions
+based on SHA-256 and SHA-512.
+.P
+"\fIsalt\fP" stands for the up to 16 characters
+following "$\fIid\fP$" in the salt.
+The "\fIhashed\fP"
+part of the password string is the actual computed password.
+The size of this string is fixed:
+.RS
+.TS
+lb l.
+MD5	22 characters
+SHA-256	43 characters
+SHA-512	86 characters
+.TE
+.RE
+.P
+The characters in "\fIsalt\fP" and "\fIhashed\fP" are drawn from the set
+[\fBa\-zA\-Z0\-9./\fP].
+In the MD5 and SHA implementations the entire
+.I key
+is significant (instead of only the first
+8 bytes in DES).
+.P
+Since glibc 2.7,
+.\" glibc commit 9425cb9eea6a62fc21d99aafe8a60f752b934b05
+the SHA-256 and SHA-512 implementations support a user-supplied number of
+hashing rounds, defaulting to 5000.
+If the "$\fIid\fP$" characters in the salt are
+followed by "rounds=\fIxxx\fP$", where \fIxxx\fP is an integer, then the
+result has the form
+.RS
+.P
+$\fIid\fP$\fIrounds=yyy\fP$\fIsalt\fP$\fIhashed\fP
+.RE
+.P
+where \fIyyy\fP is the number of hashing rounds actually used.
+The number of rounds actually used is 1000 if
+.I xxx
+is less than
+1000, 999999999 if
+.I xxx
+is greater than 999999999, and
+is equal to
+.I xxx
+otherwise.
+.SH SEE ALSO
+.BR login (1),
+.BR passwd (1),
+.BR encrypt (3),
+.BR getpass (3),
+.BR passwd (5)