| blob | b619149a1d6aa14c453f9809b8c785471d56c765 |
1 '\" t
2 .\" Michael Haardt (michael@cantor.informatik.rwth.aachen.de)
3 .\" Sat Sep 3 22:00:30 MET DST 1994
4 .\"
5 .\" SPDX-License-Identifier: GPL-2.0-or-later
6 .\"
7 .\" Sun Feb 19 21:32:25 1995, faith@cs.unc.edu edited details away
8 .\"
9 .\" TO DO: This manual page should go more into detail how DES is perturbed,
10 .\" which string will be encrypted, and what determines the repetition factor.
11 .\" Is a simple repetition using ECB used, or something more advanced? I hope
12 .\" the presented explanations are at least better than nothing, but by no
13 .\" means enough.
14 .\"
15 .\" added _XOPEN_SOURCE, aeb, 970705
16 .\" added GNU MD5 stuff, aeb, 011223
17 .\"
18 .TH crypt 3 (date) "Linux man-pages (unreleased)"
19 .SH NAME
20 crypt, crypt_r \- password hashing
21 .SH LIBRARY
22 Password hashing library
23 .RI ( libcrypt ", " \-lcrypt )
24 .SH SYNOPSIS
25 .nf
26 .B #include <unistd.h>
27 .P
28 .BI "char *crypt(const char *" key ", const char *" salt );
29 .P
30 .B #include <crypt.h>
31 .P
32 .BI "char *crypt_r(const char *" key ", const char *" salt ,
33 .BI " struct crypt_data *restrict " data );
34 .fi
35 .P
36 .RS -4
37 Feature Test Macro Requirements for glibc (see
38 .BR feature_test_macros (7)):
39 .RE
40 .P
41 .BR crypt ():
42 .nf
43 Since glibc 2.28:
44 _DEFAULT_SOURCE
45 glibc 2.27 and earlier:
46 _XOPEN_SOURCE
47 .fi
48 .P
49 .BR crypt_r ():
50 .nf
51 _GNU_SOURCE
52 .fi
53 .SH DESCRIPTION
54 .BR crypt ()
55 is the password hashing function.
56 It is based on the Data Encryption
57 Standard algorithm with variations intended (among other things) to
58 discourage use of hardware implementations of a key search.
59 .P
60 .I key
61 is a user's typed password.
62 .P
63 .I salt
64 is a two-character string chosen from the set
65 [\fBa\-zA\-Z0\-9./\fP].
66 This string is used to
67 perturb the algorithm in one of 4096 different ways.
68 .P
69 By taking the lowest 7 bits of each of the first eight characters of the
70 .IR key ,
71 a 56-bit key is obtained.
72 This 56-bit key is used to encrypt repeatedly a
73 constant string (usually a string consisting of all zeros).
74 The returned
75 value points to the hashed password, a series of 13 printable ASCII
76 characters (the first two characters represent the salt itself).
77 The return value points to static data whose content is
78 overwritten by each call.
79 .P
80 Warning: the key space consists of
81 .if t 2\s-2\u56\s0\d
82 .if n 2**56
83 equal 7.2e16 possible values.
84 Exhaustive searches of this key space are
85 possible using massively parallel computers.
86 Software, such as
87 .BR crack (1),
88 is available which will search the portion of this key space that is
89 generally used by humans for passwords.
90 Hence, password selection should,
91 at minimum, avoid common words and names.
92 The use of a
93 .BR passwd (1)
94 program that checks for crackable passwords during the selection process is
95 recommended.
96 .P
97 The DES algorithm itself has a few quirks which make the use of the
98 .BR crypt ()
99 interface a very poor choice for anything other than password
100 authentication.
101 If you are planning on using the
102 .BR crypt ()
103 interface for a cryptography project, don't do it: get a good book on
104 encryption and one of the widely available DES libraries.
105 .P
106 .BR crypt_r ()
107 is a reentrant version of
108 .BR crypt ().
109 The structure pointed to by
110 .I data
111 is used to store result data and bookkeeping information.
112 Other than allocating it,
113 the only thing that the caller should do with this structure is to set
114 .I data\->initialized
115 to zero before the first call to
116 .BR crypt_r ().
117 .SH RETURN VALUE
118 On success, a pointer to the hashed password is returned.
119 On error, NULL is returned.
120 .SH ERRORS
121 .TP
122 .B EINVAL
123 .I salt
124 has the wrong format.
125 .TP
126 .B ENOSYS
127 The
128 .BR crypt ()
129 function was not implemented, probably because of U.S.A. export restrictions.
130 .\" This level of detail is not necessary in this man page. . .
131 .\" .P
132 .\" When encrypting a plain text P using DES with the key K results in the
133 .\" encrypted text C, then the complementary plain text P' being encrypted
134 .\" using the complementary key K' will result in the complementary encrypted
135 .\" text C'.
136 .\" .P
137 .\" Weak keys are keys which stay invariant under the DES key transformation.
138 .\" The four known weak keys 0101010101010101, fefefefefefefefe,
139 .\" 1f1f1f1f0e0e0e0e and e0e0e0e0f1f1f1f1 must be avoided.
140 .\" .P
141 .\" There are six known half weak key pairs, which keys lead to the same
142 .\" encrypted data. Keys which are part of such key clusters should be
143 .\" avoided.
144 .\" Sorry, I could not find out what they are.
145 .\""
146 .\" .P
147 .\" Heavily redundant data causes trouble with DES encryption, when used in the
148 .\" .I codebook
149 .\" mode that
150 .\" .BR crypt ()
151 .\" implements. The
152 .\" .BR crypt ()
153 .\" interface should be used only for its intended purpose of password
154 .\" verification, and should not be used as part of a data encryption tool.
155 .\" .P
156 .\" The first and last three output bits of the fourth S-box can be
157 .\" represented as function of their input bits. Empiric studies have
158 .\" shown that S-boxes partially compute the same output for similar input.
159 .\" It is suspected that this may contain a back door which could allow the
160 .\" NSA to decrypt DES encrypted data.
161 .\" .P
162 .\" Making encrypted data computed using crypt() publicly available has
163 .\" to be considered insecure for the given reasons.
164 .TP
165 .B EPERM
166 .I /proc/sys/crypto/fips_enabled
167 has a nonzero value,
168 and an attempt was made to use a weak hashing type, such as DES.
169 .SH ATTRIBUTES
170 For an explanation of the terms used in this section, see
171 .BR attributes (7).
172 .TS
173 allbox;
174 lbx lb lb
175 l l l.
176 Interface Attribute Value
177 T{
178 .na
179 .nh
180 .BR crypt ()
181 T} Thread safety MT-Unsafe race:crypt
182 T{
183 .na
184 .nh
185 .BR crypt_r ()
186 T} Thread safety MT-Safe
187 .TE
188 .SH STANDARDS
189 .TP
190 .BR crypt ()
191 POSIX.1-2008.
192 .TP
193 .BR crypt_r ()
194 GNU.
195 .SH HISTORY
196 .TP
197 .BR crypt ()
198 POSIX.1-2001, SVr4, 4.3BSD.
199 .SS Availability in glibc
200 The
201 .BR crypt (),
202 .BR encrypt (3),
203 and
204 .BR setkey (3)
205 functions are part of the POSIX.1-2008 XSI Options Group for Encryption
206 and are optional.
207 If the interfaces are not available, then the symbolic constant
208 .B _XOPEN_CRYPT
209 is either not defined,
210 or it is defined to \-1 and availability can be checked at run time with
211 .BR sysconf (3).
212 This may be the case if the downstream distribution has switched from glibc
213 crypt to
214 .IR libxcrypt .
215 When recompiling applications in such distributions,
216 the programmer must detect if
217 .B _XOPEN_CRYPT
218 is not available and include
219 .I <crypt.h>
220 for the function prototypes;
221 otherwise
222 .I libxcrypt
223 is an ABI-compatible drop-in replacement.
224 .SH NOTES
225 .SS Features in glibc
226 The glibc version of this function supports additional
227 hashing algorithms.
228 .P
229 If
230 .I salt
231 is a character string starting with the characters "$\fIid\fP$"
232 followed by a string optionally terminated by "$",
233 then the result has the form:
234 .RS
235 .P
236 $\fIid\fP$\fIsalt\fP$\fIhashed\fP
237 .RE
238 .P
239 .I id
240 identifies the hashing method used instead of DES and this
241 then determines how the rest of the password string is interpreted.
242 The following values of
243 .I id
244 are supported:
245 .RS
246 .TS
247 lb lb
248 l lx.
249 ID Method
250 _
251 1 MD5
252 2a T{
253 Blowfish (not in mainline glibc; added in some
254 Linux distributions)
255 T}
256 .\" openSUSE has Blowfish, but AFAICS, this option is not supported
257 .\" natively by glibc -- mtk, Jul 08
258 .\"
259 .\" md5 | Sun MD5
260 .\" glibc doesn't appear to natively support Sun MD5; I don't know
261 .\" if any distros add the support.
262 5 SHA-256 (since glibc 2.7)
263 6 SHA-512 (since glibc 2.7)
264 .TE
265 .RE
266 .P
267 Thus, $5$\fIsalt\fP$\fIhashed\fP and $6$\fIsalt\fP$\fIhashed\fP
268 contain the password hashed with, respectively, functions
269 based on SHA-256 and SHA-512.
270 .P
271 "\fIsalt\fP" stands for the up to 16 characters
272 following "$\fIid\fP$" in the salt.
273 The "\fIhashed\fP"
274 part of the password string is the actual computed password.
275 The size of this string is fixed:
276 .RS
277 .TS
278 lb l.
279 MD5 22 characters
280 SHA-256 43 characters
281 SHA-512 86 characters
282 .TE
283 .RE
284 .P
285 The characters in "\fIsalt\fP" and "\fIhashed\fP" are drawn from the set
286 [\fBa\-zA\-Z0\-9./\fP].
287 In the MD5 and SHA implementations the entire
288 .I key
289 is significant (instead of only the first
290 8 bytes in DES).
291 .P
292 Since glibc 2.7,
293 .\" glibc commit 9425cb9eea6a62fc21d99aafe8a60f752b934b05
294 the SHA-256 and SHA-512 implementations support a user-supplied number of
295 hashing rounds, defaulting to 5000.
296 If the "$\fIid\fP$" characters in the salt are
297 followed by "rounds=\fIxxx\fP$", where \fIxxx\fP is an integer, then the
298 result has the form
299 .RS
300 .P
301 $\fIid\fP$\fIrounds=yyy\fP$\fIsalt\fP$\fIhashed\fP
302 .RE
303 .P
304 where \fIyyy\fP is the number of hashing rounds actually used.
305 The number of rounds actually used is 1000 if
306 .I xxx
307 is less than
308 1000, 999999999 if
309 .I xxx
310 is greater than 999999999, and
311 is equal to
312 .I xxx
313 otherwise.
314 .SH SEE ALSO
315 .BR login (1),
316 .BR passwd (1),
317 .BR encrypt (3),
318 .BR getpass (3),
319 .BR passwd (5)