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