Debian Codegraph @

upstream/debian-unstable/man3/crypt.3

raw
1 .\" Written and revised by Solar Designer <solar at openwall.com> in 2000-2011.
2 .\" Revised by Zack Weinberg <zackw at panix.com> in 2017.
3 .\" Converted to mdoc format by Zack Weinberg in 2018.
4 .\"
5 .\" No copyright is claimed, and this man page is hereby placed in the public
6 .\" domain. In case this attempt to disclaim copyright and place the man page
7 .\" in the public domain is deemed null and void, then the man page is
8 .\" Copyright 2000-2011 Solar Designer, 2017, 2018 Zack Weinberg, and it is
9 .\" hereby released to the general public under the following terms:
10 .\"
11 .\" Redistribution and use in source and binary forms, with or without
12 .\" modification, are permitted.
13 .\"
14 .\" There's ABSOLUTELY NO WARRANTY, express or implied.
15 .\"
16 .Dd October 11, 2017
17 .Dt CRYPT 3
18 .Os "Openwall Project"
19 .Sh NAME
20 .Nm crypt , crypt_r , crypt_rn , crypt_ra
21 .Nd passphrase hashing
22 .Sh LIBRARY
23 .Lb libcrypt
24 .Sh SYNOPSIS
25 .In crypt.h
26 .Ft "char *"
27 .Fo crypt
28 .Fa "const char *phrase"
29 .Fa "const char *setting"
30 .Fc
31 .Ft "char *"
32 .Fo crypt_r
33 .Fa "const char *phrase"
34 .Fa "const char *setting"
35 .Fa "struct crypt_data *data"
36 .Fc
37 .Ft "char *"
38 .Fo crypt_rn
39 .Fa "const char *phrase"
40 .Fa "const char *setting"
41 .Fa "struct crypt_data *data"
42 .Fa "int size"
43 .Fc
44 .Ft "char *"
45 .Fo crypt_ra
46 .Fa "const char *phrase"
47 .Fa "const char *setting"
48 .Fa "void **data"
49 .Fa "int *size"
50 .Fc
51 .Sh DESCRIPTION
52 The
53 .Nm crypt ,
54 .Nm crypt_r ,
55 .Nm crypt_rn ,
56 and
57 .Nm crypt_ra
58 functions irreversibly
59 .Dq hash
60 .Fa phrase
61 for storage in the system password database
62 .Pq Xr shadow 5
63 using a cryptographic
64 .Dq hashing method.
65 The result of this operation is called a
66 .Dq hashed passphrase
67 or just a
68 .Dq hash.
69 Hashing methods are described in
70 .Xr crypt 5 .
71 .Pp
72 .Fa setting
73 controls which hashing method to use,
74 and also supplies various parameters to the chosen method,
75 most importantly a random
76 .Dq salt
77 which ensures that no two stored hashes are the same,
78 even if the
79 .Fa phrase
80 strings are the same.
81 .Pp
82 The
83 .Fa data
84 argument to
85 .Nm crypt_r
86 is a structure of type
87 .Vt "struct crypt_data" .
88 It has at least these fields:
89 .Bd -literal -offset indent
90 struct crypt_data {
91 char output[CRYPT_OUTPUT_SIZE];
92 char setting[CRYPT_OUTPUT_SIZE];
93 char input[CRYPT_MAX_PASSPHRASE_SIZE];
94 char initialized;
95 };
96 .Ed
97 .Pp
98 Upon a successful return from
99 .Nm crypt_r ,
100 the hashed passphrase will be stored in
101 .Fa output .
102 Applications are encouraged, but not required, to use the
103 .Fa input
104 and
105 .Fa setting
106 fields to store the strings that they will pass as
107 .Fa input phrase
108 and
109 .Fa setting
110 to
111 .Nm crypt_r .
112 This will make it easier to erase all sensitive data
113 after it is no longer needed.
114 .Pp
115 The
116 .Fa initialized
117 field must be set to zero before the first time a
118 .Vt "struct crypt_data"
119 object is first used in a call to
120 .Fn crypt_r .
121 We recommend zeroing the entire object,
122 not just
123 .Fa initialized
124 and not just the documented fields,
125 before the first use.
126 (Of course, do this before storing anything in
127 .Fa setting
128 and
129 .Fa input . )
130 .Pp
131 The
132 .Fa data
133 argument to
134 .Nm crypt_rn
135 should also point to a
136 .Vt "struct crypt_data"
137 object, and
138 .Fa size
139 should be the size of that object, cast to
140 .Vt int .
141 When used with
142 .Nm crypt_rn ,
143 the entire
144 .Fa data
145 object (except for the
146 .Fa input
147 and
148 .Fa setting
149 fields) must be zeroed before its first use;
150 this is not just a recommendation, as it is for
151 .Nm crypt_r .
152 Otherwise, the fields of the object have the same uses that they do for
153 .Nm crypt_r .
154 .Pp
155 On the first call to
156 .Nm crypt_ra ,
157 .Fa data
158 should be the address of a
159 .Vt "void *"
160 variable set to NULL, and
161 .Fa size
162 should be the address of an
163 .Vt int
164 variable set to zero.
165 .Nm crypt_ra
166 will allocate and initialize a
167 .Vt "struct crypt_data"
168 object, using
169 .Xr malloc 3 ,
170 and write its address and size into the variables pointed to by
171 .Fa data
172 and
173 .Fa size .
174 These can be reused in subsequent calls.
175 After the application is done hashing passphrases,
176 it should deallocate the
177 .Vt "struct crypt_data"
178 object using
179 .Xr free 3 .
180 .Sh RETURN VALUES
181 Upon successful completion,
182 .Nm crypt ,
183 .Nm crypt_r ,
184 .Nm crypt_rn ,
185 and
186 .Nm crypt_ra
187 return a pointer to a string which encodes both the hashed passphrase,
188 and the settings that were used to encode it.
189 This string is directly usable as
190 .Fa setting
191 in other calls to
192 .Nm crypt ,
193 .Nm crypt_r ,
194 .Nm crypt_rn ,
195 and
196 .Nm crypt_ra ,
197 and as
198 .Fa prefix
199 in calls to
200 .Nm crypt_gensalt ,
201 .Nm crypt_gensalt_rn ,
202 and
203 .Nm crypt_gensalt_ra .
204 It will be entirely printable ASCII,
205 and will not contain whitespace
206 or the characters
207 .Sq Li \&: ,
208 .Sq Li \&; ,
209 .Sq Li \&* ,
210 .Sq Li \&! ,
211 or
212 .Sq Li \&\e .
213 See
214 .Xr crypt 5
215 for more detail on the format of hashed passphrases.
216 .Pp
217 .Nm crypt
218 places its result in a static storage area,
219 which will be overwritten by subsequent calls to
220 .Nm crypt .
221 It is not safe to call
222 .Nm crypt
223 from multiple threads simultaneously.
224 It's also not recommended to use the pointer
225 returned as an argument for another call to
226 .Nm crypt ,
227 as some implementations, including earlier
228 releases of libxcrypt, may overwrite the underlying
229 static output buffer before computing the hash.
230 .Pp
231 .Nm crypt_r ,
232 .Nm crypt_rn ,
233 and
234 .Nm crypt_ra
235 place their result in the
236 .Fa output
237 field of their
238 .Fa data
239 argument.
240 It is safe to call them from multiple threads simultaneously,
241 as long as a separate
242 .Fa data
243 object is used for each thread.
244 It's also not recommended to use the pointer
245 returned as an argument for another call to
246 .Nm crypt_r ,
247 .Nm crypt_rn ,
248 and
249 .Nm crypt_ra
250 using the same
251 .Fa data
252 object for subsequent calls, as some implementations,
253 including earlier releases of libxcrypt, may overwrite the
254 .Fa output
255 field of the passed
256 .Fa data
257 argument before computing the hash.
258 Calling
259 .Nm crypt_ra
260 with the
261 .Fa phrase
262 and/or
263 .Fa setting
264 parameters located within a passed
265 .Fa data
266 object which is smaller than the size of
267 .Vt "struct crypt_data"
268 is not recommended, as some implementations, including
269 earlier releases of libxcrypt, may not preserve the
270 passed literals, if the
271 .Fa data
272 object needs to be altered.
273 .Pp
274 Upon error,
275 .Nm crypt_r ,
276 .Nm crypt_rn ,
277 and
278 .Nm crypt_ra
279 write an
280 .Em invalid
281 hash to the
282 .Fa output
283 field of their
284 .Fa data
285 argument, and
286 .Nm crypt
287 writes an invalid hash to its static storage area.
288 This string will be shorter than 13 characters,
289 will begin with a
290 .Sq Li \&* ,
291 and will not compare equal to
292 .Fa setting .
293 .Pp
294 Upon error,
295 .Nm crypt_rn
296 and
297 .Nm crypt_ra
298 return a null pointer.
299 .Nm crypt_r
300 and
301 .Nm crypt
302 may also return a null pointer,
303 or they may return a pointer to the invalid hash,
304 depending on how libcrypt was configured.
305 (The option to return the invalid hash is for compatibility
306 with old applications that assume that
307 .Nm crypt
308 cannot return a null pointer.
309 See
310 .Sx PORTABILITY NOTES
311 below.)
312 .Pp
313 All four functions set
314 .Va errno
315 when they fail.
316 When the functions succeed, the value of
317 .Va errno
318 is unspecified and must not be relied upon.
319 .Sh ERRORS
320 .Bl -tag -width Er
321 .It Er EINVAL
322 .Fa setting
323 is invalid, or requests a hashing method that is not supported.
324 .It Er ERANGE
325 .Fa phrase
326 is too long
327 (more than
328 .Dv CRYPT_MAX_PASSPHRASE_SIZE
329 characters; some hashing methods may have lower limits).
330 .br
331 .Nm crypt_rn
332 only:
333 .Fa size
334 is too small for the hashing method requested by
335 .Fa setting .
336 .It Er ENOMEM
337 Failed to allocate internal scratch memory.
338 .br
339 .Nm crypt_ra
340 only: failed to allocate memory for
341 .Fa data .
342 .It Er ENOSYS No or Er EOPNOTSUPP
343 Hashing passphrases is not supported at all on this installation,
344 or the hashing method requested by
345 .Fa setting
346 is not supported.
347 These error codes are not used by this version of libcrypt,
348 but may be encountered on other systems.
349 .El
350 .Sh PORTABILITY NOTES
351 .Nm crypt
352 is included in POSIX, but
353 .Nm crypt_r ,
354 .Nm crypt_rn ,
355 and
356 .Nm crypt_ra
357 are not part of any standard.
358 .Pp
359 POSIX does not specify any hashing methods,
360 and does not require hashed passphrases to be portable between systems.
361 In practice, hashed passphrases are portable
362 as long as both systems support the hashing method that was used.
363 However, the set of supported hashing methods
364 varies considerably from system to system.
365 .Pp
366 The behavior of
367 .Nm crypt
368 on errors isn't well standardized.
369 Some implementations simply can't fail
370 (except by crashing the program),
371 others return a null pointer or a fixed string.
372 Most implementations don't set
373 .Va errno ,
374 but some do.
375 POSIX specifies returning a null pointer and setting
376 .Va errno ,
377 but it defines only one possible error,
378 .Er ENOSYS ,
379 in the case where
380 .Nm crypt
381 is not supported at all.
382 Some older applications are not prepared to handle null pointers
383 returned by
384 .Nm crypt .
385 The behavior described above for this implementation,
386 setting
387 .Va errno
388 and returning an invalid hash different from
389 .Fa setting ,
390 is chosen to make these applications fail closed when an error occurs.
391 .Pp
392 Due to historical restrictions
393 on the export of cryptographic software from the USA,
394 .Nm crypt
395 is an optional POSIX component.
396 Applications should therefore be prepared for
397 .Nm crypt
398 not to be available,
399 or to always fail (setting
400 .Va errno
401 to
402 .Er ENOSYS )
403 at runtime.
404 .Pp
405 POSIX specifies that
406 .Nm crypt
407 is declared in
408 .In unistd.h ,
409 but only if the macro
410 .Dv _XOPEN_CRYPT
411 is defined and has a value greater than or equal to zero.
412 Since libcrypt does not provide
413 .In unistd.h ,
414 it declares
415 .Nm crypt ,
416 .Nm crypt_r ,
417 .Nm crypt_rn ,
418 and
419 .Nm crypt_ra
420 in
421 .In crypt.h
422 instead.
423 .Pp
424 On a minority of systems (notably recent versions of Solaris),
425 .Nm crypt
426 uses a thread-specific static storage buffer,
427 which makes it safe to call from multiple threads simultaneously,
428 but does not prevent each call within a thread
429 from overwriting the results of the previous one.
430 .Sh BUGS
431 Some implementations of
432 .Nm crypt ,
433 upon error,
434 return an invalid hash that is stored in a read-only location
435 or only initialized once,
436 which means that it is only safe to erase the buffer pointed to by the
437 .Nm crypt
438 return value if an error did not occur.
439 .Pp
440 .Vt "struct crypt_data"
441 may be quite large (32kB in this implementation of libcrypt;
442 over 128kB in some other implementations).
443 This is large enough that it may be unwise to allocate it on the stack.
444 .Pp
445 Some recently designed hashing methods need even more scratch memory,
446 but the
447 .Nm crypt_r
448 interface makes it impossible to change the size of
449 .Vt "struct crypt_data"
450 without breaking binary compatibility.
451 The
452 .Nm crypt_rn
453 interface could accommodate larger allocations for specific hashing methods,
454 but the caller of
455 .Nm crypt_rn
456 has no way of knowing how much memory to allocate.
457 .Nm crypt_ra
458 does the allocation itself,
459 but can only make a single call to
460 .Xr malloc 3 .
461 .Sh ATTRIBUTES
462 For an explanation of the terms used in this section, see
463 .Xr attributes 7 .
464 .TS
465 allbox;
466 lb lb lb
467 l l l.
468 Interface Attribute Value
469 T{
470 .Nm crypt
471 T} Thread safety MT-Unsafe race:crypt
472 T{
473 .Nm crypt_r ,
474 .Nm crypt_rn ,
475 .Nm crypt_ra
476 T} Thread safety MT-Safe
477 .TE
478 .sp
479 .Sh HISTORY
480 A rotor-based
481 .Nm crypt
482 function appeared in
483 .At v6 .
484 The
485 .Dq traditional
486 DES-based
487 .Nm crypt
488 first appeared in
489 .At v7 .
490 .Pp
491 .Nm crypt_r
492 originates with the GNU C Library.
493 There's also a
494 .Nm crypt_r
495 function on HP-UX and MKS Toolkit, but the prototypes and semantics
496 differ.
497 .Pp
498 .Nm crypt_rn
499 and
500 .Nm crypt_ra
501 originate with the Openwall project.
502 .Sh SEE ALSO
503 .Xr crypt_gensalt 3 ,
504 .Xr getpass 3 ,
505 .Xr getpwent 3 ,
506 .Xr shadow 3 ,
507 .Xr login 1 ,
508 .Xr passwd 1 ,
509 .Xr crypt 5 ,
510 .Xr passwd 5 ,
511 .Xr shadow 5 ,
512 .Xr pam 8