diff options
Diffstat (limited to 'man3/crypt.3')
| -rw-r--r-- | man3/crypt.3 | 320 |
1 files changed, 320 insertions, 0 deletions
diff --git a/man3/crypt.3 b/man3/crypt.3 new file mode 100644 index 0000000..c6873a5 --- /dev/null +++ b/man3/crypt.3 @@ -0,0 +1,320 @@ +'\" 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 2023-07-20 "Linux man-pages 6.05.01" +.SH NAME +crypt, crypt_r \- password hashing +.SH LIBRARY +Password hashing library +.RI ( libcrypt ", " \-lcrypt ) +.SH SYNOPSIS +.nf +.B #include <unistd.h> +.PP +.BI "char *crypt(const char *" key ", const char *" salt ); +.PP +.B #include <crypt.h> +.PP +.BI "char *crypt_r(const char *" key ", const char *" salt , +.BI " struct crypt_data *restrict " data ); +.fi +.PP +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.PP +.BR crypt (): +.nf + Since glibc 2.28: + _DEFAULT_SOURCE + glibc 2.27 and earlier: + _XOPEN_SOURCE +.fi +.PP +.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. +.PP +.I key +is a user's typed password. +.PP +.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. +.PP +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. +.PP +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. +.PP +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. +.PP +.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. . . +.\" .PP +.\" 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'. +.\" .PP +.\" 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. +.\" .PP +.\" 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. +.\"" +.\" .PP +.\" 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. +.\" .PP +.\" 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. +.\" .PP +.\" 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 +.sp 1 +.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. +.PP +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 +.PP +$\fIid\fP$\fIsalt\fP$\fIhashed\fP +.RE +.PP +.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 +.PP +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. +.PP +"\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 +.PP +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). +.PP +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 +.PP +$\fIid\fP$\fIrounds=yyy\fP$\fIsalt\fP$\fIhashed\fP +.RE +.PP +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) |