]>
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 | .\" | |
460495ca | 36 | .TH CRYPT 3 2015-08-08 "" "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 MK |
42 | .br |
43 | .B #include <unistd.h> | |
68e4db0a | 44 | .PP |
fea681da | 45 | .BI "char *crypt(const char *" key ", const char *" salt ); |
f90f031e | 46 | |
3c5faf11 MK |
47 | .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" |
48 | .br | |
49 | .B #include <crypt.h> | |
68e4db0a | 50 | .PP |
8fe60aef | 51 | .BI "char *crypt_r(const char *" key ", const char *" salt , |
4e602cb2 MK |
52 | .BI " struct crypt_data *" data ); |
53 | .fi | |
68e4db0a | 54 | .PP |
e9329f6d | 55 | Link with \fI\-lcrypt\fP. |
fea681da | 56 | .SH DESCRIPTION |
e511ffb6 | 57 | .BR crypt () |
c13182ef MK |
58 | is the password encryption function. |
59 | It is based on the Data Encryption | |
fea681da MK |
60 | Standard algorithm with variations intended (among other things) to |
61 | discourage use of hardware implementations of a key search. | |
62 | .PP | |
63 | .I key | |
64 | is a user's typed password. | |
65 | .PP | |
66 | .I salt | |
67 | is a two-character string chosen from the set | |
3cc95d3f | 68 | [\fBa\-zA\-Z0\-9./\fP]. |
c13182ef | 69 | This string is used to |
fea681da MK |
70 | perturb the algorithm in one of 4096 different ways. |
71 | .PP | |
72 | By taking the lowest 7 bits of each of the first eight characters of the | |
73 | .IR key , | |
c13182ef MK |
74 | a 56-bit key is obtained. |
75 | This 56-bit key is used to encrypt repeatedly a | |
76 | constant string (usually a string consisting of all zeros). | |
77 | The returned | |
fea681da | 78 | value points to the encrypted password, a series of 13 printable ASCII |
c13182ef MK |
79 | characters (the first two characters represent the salt itself). |
80 | The return value points to static data whose content is | |
81 | overwritten by each call. | |
fea681da | 82 | .PP |
f64cc745 | 83 | Warning: the key space consists of |
fea681da MK |
84 | .if t 2\s-2\u56\s0\d |
85 | .if n 2**56 | |
c13182ef MK |
86 | equal 7.2e16 possible values. |
87 | Exhaustive searches of this key space are | |
88 | possible using massively parallel computers. | |
89 | Software, such as | |
fea681da MK |
90 | .BR crack (1), |
91 | is available which will search the portion of this key space that is | |
c13182ef MK |
92 | generally used by humans for passwords. |
93 | Hence, password selection should, | |
94 | at minimum, avoid common words and names. | |
95 | The use of a | |
fea681da MK |
96 | .BR passwd (1) |
97 | program that checks for crackable passwords during the selection process is | |
98 | recommended. | |
99 | .PP | |
100 | The DES algorithm itself has a few quirks which make the use of the | |
2777b1ca | 101 | .BR crypt () |
fea681da | 102 | interface a very poor choice for anything other than password |
c13182ef MK |
103 | authentication. |
104 | If you are planning on using the | |
2777b1ca | 105 | .BR crypt () |
fea681da MK |
106 | interface for a cryptography project, don't do it: get a good book on |
107 | encryption and one of the widely available DES libraries. | |
847e0d88 | 108 | .PP |
4e602cb2 MK |
109 | .BR crypt_r () |
110 | is a reentrant version of | |
111 | .BR crypt (). | |
112 | The structure pointed to by | |
113 | .I data | |
114 | is used to store result data and bookkeeping information. | |
115 | Other than allocating it, | |
116 | the only thing that the caller should do with this structure is to set | |
117 | .I data->initialized | |
118 | to zero before the first call to | |
119 | .BR crypt_r (). | |
47297adb | 120 | .SH RETURN VALUE |
4e602cb2 | 121 | On success, a pointer to the encrypted password is returned. |
fea681da MK |
122 | On error, NULL is returned. |
123 | .SH ERRORS | |
124 | .TP | |
17b028d6 MK |
125 | .B EINVAL |
126 | .I salt | |
127 | has the wrong format. | |
128 | .TP | |
fea681da | 129 | .B ENOSYS |
c13182ef | 130 | The |
e511ffb6 | 131 | .BR crypt () |
fea681da MK |
132 | function was not implemented, probably because of U.S.A. export restrictions. |
133 | .\" This level of detail is not necessary in this man page. . . | |
134 | .\" .PP | |
135 | .\" When encrypting a plain text P using DES with the key K results in the | |
136 | .\" encrypted text C, then the complementary plain text P' being encrypted | |
137 | .\" using the complementary key K' will result in the complementary encrypted | |
138 | .\" text C'. | |
139 | .\" .PP | |
140 | .\" Weak keys are keys which stay invariant under the DES key transformation. | |
141 | .\" The four known weak keys 0101010101010101, fefefefefefefefe, | |
142 | .\" 1f1f1f1f0e0e0e0e and e0e0e0e0f1f1f1f1 must be avoided. | |
143 | .\" .PP | |
144 | .\" There are six known half weak key pairs, which keys lead to the same | |
145 | .\" encrypted data. Keys which are part of such key clusters should be | |
146 | .\" avoided. | |
147 | .\" Sorry, I could not find out what they are. | |
148 | .\"" | |
149 | .\" .PP | |
150 | .\" Heavily redundant data causes trouble with DES encryption, when used in the | |
151 | .\" .I codebook | |
152 | .\" mode that | |
2777b1ca | 153 | .\" .BR crypt () |
fea681da | 154 | .\" implements. The |
2777b1ca | 155 | .\" .BR crypt () |
fea681da MK |
156 | .\" interface should be used only for its intended purpose of password |
157 | .\" verification, and should not be used as part of a data encryption tool. | |
158 | .\" .PP | |
159 | .\" The first and last three output bits of the fourth S-box can be | |
160 | .\" represented as function of their input bits. Empiric studies have | |
161 | .\" shown that S-boxes partially compute the same output for similar input. | |
162 | .\" It is suspected that this may contain a back door which could allow the | |
163 | .\" NSA to decrypt DES encrypted data. | |
164 | .\" .PP | |
b9560046 | 165 | .\" Making encrypted data computed using crypt() publicly available has |
fea681da | 166 | .\" to be considered insecure for the given reasons. |
17b028d6 MK |
167 | .TP |
168 | .B EPERM | |
fa16a05d SP |
169 | .I /proc/sys/crypto/fips_enabled |
170 | has a nonzero value, | |
17b028d6 | 171 | and an attempt was made to use a weak encryption type, such as DES. |
dee90154 | 172 | .SH ATTRIBUTES |
aca8edbf MK |
173 | For an explanation of the terms used in this section, see |
174 | .BR attributes (7). | |
175 | .TS | |
176 | allbox; | |
177 | lb lb lb | |
178 | l l l. | |
179 | Interface Attribute Value | |
180 | T{ | |
dee90154 | 181 | .BR crypt () |
11f85593 | 182 | T} Thread safety MT-Unsafe race:crypt |
aca8edbf | 183 | T{ |
dee90154 | 184 | .BR crypt_r () |
aca8edbf MK |
185 | T} Thread safety MT-Safe |
186 | .TE | |
47297adb | 187 | .SH CONFORMING TO |
4e602cb2 | 188 | .BR crypt (): |
da93f334 | 189 | POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. |
4209865f PB |
190 | .BR crypt_r () |
191 | is a GNU extension. | |
d597239c | 192 | .SH NOTES |
c634028a | 193 | .SS Glibc notes |
cefb5a17 MK |
194 | The glibc2 version of this function supports additional |
195 | encryption algorithms. | |
847e0d88 | 196 | .PP |
fea681da MK |
197 | If |
198 | .I salt | |
cefb5a17 MK |
199 | is a character string starting with the characters "$\fIid\fP$" |
200 | followed by a string terminated by "$": | |
4391d173 | 201 | .RS |
847e0d88 | 202 | .PP |
cefb5a17 | 203 | $\fIid\fP$\fIsalt\fP$\fIencrypted\fP |
847e0d88 | 204 | .PP |
4391d173 | 205 | .RE |
cefb5a17 MK |
206 | then instead of using the DES machine, |
207 | .I id | |
208 | identifies the encryption method used and this then determines how the rest | |
209 | of the password string is interpreted. | |
210 | The following values of | |
211 | .I id | |
212 | are supported: | |
bb3797a4 | 213 | .RS |
cefb5a17 MK |
214 | .TS |
215 | l l. | |
216 | ID | Method | |
217 | _ | |
218 | 1 | MD5 | |
caa21260 MK |
219 | 2a | Blowfish (not in mainline glibc; added in some |
220 | | Linux distributions) | |
bb3797a4 MK |
221 | .\" openSUSE has Blowfish, but AFAICS, this option is not supported |
222 | .\" natively by glibc -- mtk, Jul 08 | |
223 | .\" | |
cefb5a17 | 224 | .\" md5 | Sun MD5 |
bb3797a4 MK |
225 | .\" glibc doesn't appear to natively support Sun MD5; I don't know |
226 | .\" if any distros add the support. | |
cefb5a17 MK |
227 | 5 | SHA-256 (since glibc 2.7) |
228 | 6 | SHA-512 (since glibc 2.7) | |
229 | .TE | |
bb3797a4 | 230 | .RE |
847e0d88 | 231 | .PP |
cefb5a17 MK |
232 | So $5$\fIsalt\fP$\fIencrypted\fP is an SHA-256 encoded |
233 | password and $6$\fIsalt\fP$\fIencrypted\fP is an | |
234 | SHA-512 encoded one. | |
847e0d88 | 235 | .PP |
bb3797a4 MK |
236 | "\fIsalt\fP" stands for the up to 16 characters |
237 | following "$\fIid\fP$" in the salt. | |
cefb5a17 MK |
238 | The encrypted part of the password string is the actual computed password. |
239 | The size of this string is fixed: | |
240 | .TS | |
241 | l l. | |
242 | MD5 | 22 characters | |
243 | SHA-256 | 43 characters | |
244 | SHA-512 | 86 characters | |
245 | .TE | |
847e0d88 | 246 | .sp 1 |
cefb5a17 | 247 | The characters in "\fIsalt\fP" and "\fIencrypted\fP" are drawn from the set |
43d19bc7 | 248 | [\fBa\-zA\-Z0\-9./\fP]. |
2419294d | 249 | In the MD5 and SHA implementations the entire |
c13182ef | 250 | .I key |
cefb5a17 | 251 | is significant (instead of only the first |
2419294d | 252 | 8 bytes in DES). |
47297adb | 253 | .SH SEE ALSO |
fea681da MK |
254 | .BR login (1), |
255 | .BR passwd (1), | |
256 | .BR encrypt (3), | |
257 | .BR getpass (3), | |
0a4f8b7b | 258 | .BR passwd (5) |