| blob | a4b37774ac403539b4e42c996e911d1de1f334b3 |
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 and data encryption
21 .SH LIBRARY
22 Encryption and decryption library
23 .RI ( libcrypto ", " \-lcrypto )
24 .SH SYNOPSIS
25 .nf
26 .B #include <unistd.h>
27 .PP
28 .BI "char *crypt(const char *" key ", const char *" salt );
29 .PP
30 .B #include <crypt.h>
31 .PP
32 .BI "char *crypt_r(const char *" key ", const char *" salt ,
33 .BI " struct crypt_data *restrict " data );
34 .fi
35 .PP
36 .RS -4
37 Feature Test Macro Requirements for glibc (see
38 .BR feature_test_macros (7)):
39 .RE
40 .PP
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 .PP
49 .BR crypt_r ():
50 .nf
51 _GNU_SOURCE
52 .fi
53 .SH DESCRIPTION
54 .BR crypt ()
55 is the password encryption 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 .PP
60 .I key
61 is a user's typed password.
62 .PP
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 .PP
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 encrypted 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 .PP
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 .PP
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 .PP
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 encrypted 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 .\" .PP
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 .\" .PP
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 .\" .PP
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 .\" .PP
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 .\" .PP
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 .\" .PP
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 encryption type, such as DES.
169 .SH ATTRIBUTES
170 For an explanation of the terms used in this section, see
171 .BR attributes (7).
172 .ad l
173 .nh
174 .TS
175 allbox;
176 lbx lb lb
177 l l l.
178 Interface Attribute Value
179 T{
180 .BR crypt ()
181 T} Thread safety MT-Unsafe race:crypt
182 T{
183 .BR crypt_r ()
184 T} Thread safety MT-Safe
185 .TE
186 .hy
187 .ad
188 .sp 1
189 .SH STANDARDS
190 .BR crypt ():
191 POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD.
192 .BR crypt_r ()
193 is a GNU extension.
194 .SH NOTES
195 .SS Availability in glibc
196 The
197 .BR crypt (),
198 .BR encrypt (3),
199 and
200 .BR setkey (3)
201 functions are part of the POSIX.1-2008 XSI Options Group for Encryption
202 and are optional.
203 If the interfaces are not available, then the symbolic constant
204 .B _XOPEN_CRYPT
205 is either not defined,
206 or it is defined to \-1 and availability can be checked at run time with
207 .BR sysconf (3).
208 This may be the case if the downstream distribution has switched from glibc
209 crypt to
210 .IR libxcrypt .
211 When recompiling applications in such distributions,
212 the programmer must detect if
213 .B _XOPEN_CRYPT
214 is not available and include
215 .I <crypt.h>
216 for the function prototypes;
217 otherwise
218 .I libxcrypt
219 is an ABI-compatible drop-in replacement.
220 .SS Features in glibc
221 The glibc version of this function supports additional
222 encryption algorithms.
223 .PP
224 If
225 .I salt
226 is a character string starting with the characters "$\fIid\fP$"
227 followed by a string optionally terminated by "$",
228 then the result has the form:
229 .RS
230 .PP
231 $\fIid\fP$\fIsalt\fP$\fIencrypted\fP
232 .RE
233 .PP
234 .I id
235 identifies the encryption method used instead of DES and this
236 then determines how the rest of the password string is interpreted.
237 The following values of
238 .I id
239 are supported:
240 .RS
241 .TS
242 lb lb
243 l lx.
244 ID Method
245 _
246 1 MD5
247 2a T{
248 Blowfish (not in mainline glibc; added in some
249 Linux distributions)
250 T}
251 .\" openSUSE has Blowfish, but AFAICS, this option is not supported
252 .\" natively by glibc -- mtk, Jul 08
253 .\"
254 .\" md5 | Sun MD5
255 .\" glibc doesn't appear to natively support Sun MD5; I don't know
256 .\" if any distros add the support.
257 5 SHA-256 (since glibc 2.7)
258 6 SHA-512 (since glibc 2.7)
259 .TE
260 .RE
261 .PP
262 Thus, $5$\fIsalt\fP$\fIencrypted\fP and $6$\fIsalt\fP$\fIencrypted\fP
263 contain the password encrypted with, respectively, functions
264 based on SHA-256 and SHA-512.
265 .PP
266 "\fIsalt\fP" stands for the up to 16 characters
267 following "$\fIid\fP$" in the salt.
268 The "\fIencrypted\fP"
269 part of the password string is the actual computed password.
270 The size of this string is fixed:
271 .RS
272 .TS
273 lb l.
274 MD5 22 characters
275 SHA-256 43 characters
276 SHA-512 86 characters
277 .TE
278 .RE
279 .PP
280 The characters in "\fIsalt\fP" and "\fIencrypted\fP" are drawn from the set
281 [\fBa\-zA\-Z0\-9./\fP].
282 In the MD5 and SHA implementations the entire
283 .I key
284 is significant (instead of only the first
285 8 bytes in DES).
286 .PP
287 Since glibc 2.7,
288 .\" glibc commit 9425cb9eea6a62fc21d99aafe8a60f752b934b05
289 the SHA-256 and SHA-512 implementations support a user-supplied number of
290 hashing rounds, defaulting to 5000.
291 If the "$\fIid\fP$" characters in the salt are
292 followed by "rounds=\fIxxx\fP$", where \fIxxx\fP is an integer, then the
293 result has the form
294 .RS
295 .PP
296 $\fIid\fP$\fIrounds=yyy\fP$\fIsalt\fP$\fIencrypted\fP
297 .RE
298 .PP
299 where \fIyyy\fP is the number of hashing rounds actually used.
300 The number of rounds actually used is 1000 if
301 .I xxx
302 is less than
303 1000, 999999999 if
304 .I xxx
305 is greater than 999999999, and
306 is equal to
307 .I xxx
308 otherwise.
309 .SH SEE ALSO
310 .BR login (1),
311 .BR passwd (1),
312 .BR encrypt (3),
313 .BR getpass (3),
314 .BR passwd (5)