Debian Codegraph @

upstream/debian-trixie/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 .Pp
225 .Nm crypt_r ,
226 .Nm crypt_rn ,
227 and
228 .Nm crypt_ra
229 place their result in the
230 .Fa output
231 field of their
232 .Fa data
233 argument.
234 It is safe to call them from multiple threads simultaneously,
235 as long as a separate
236 .Fa data
237 object is used for each thread.
238 .Pp
239 Upon error,
240 .Nm crypt_r ,
241 .Nm crypt_rn ,
242 and
243 .Nm crypt_ra
244 write an
245 .Em invalid
246 hash to the
247 .Fa output
248 field of their
249 .Fa data
250 argument, and
251 .Nm crypt
252 writes an invalid hash to its static storage area.
253 This string will be shorter than 13 characters,
254 will begin with a
255 .Sq Li \&* ,
256 and will not compare equal to
257 .Fa setting .
258 .Pp
259 Upon error,
260 .Nm crypt_rn
261 and
262 .Nm crypt_ra
263 return a null pointer.
264 .Nm crypt_r
265 and
266 .Nm crypt
267 may also return a null pointer,
268 or they may return a pointer to the invalid hash,
269 depending on how libcrypt was configured.
270 (The option to return the invalid hash is for compatibility
271 with old applications that assume that
272 .Nm crypt
273 cannot return a null pointer.
274 See
275 .Sx PORTABILITY NOTES
276 below.)
277 .Pp
278 All four functions set
279 .Va errno
280 when they fail.
281 When the functions succeed, the value of
282 .Va errno
283 is unspecified and must not be relied upon.
284 .Sh ERRORS
285 .Bl -tag -width Er
286 .It Er EINVAL
287 .Fa setting
288 is invalid, or requests a hashing method that is not supported.
289 .It Er ERANGE
290 .Fa phrase
291 is too long
292 (more than
293 .Dv CRYPT_MAX_PASSPHRASE_SIZE
294 characters; some hashing methods may have lower limits).
295 .br
296 .Nm crypt_rn
297 only:
298 .Fa size
299 is too small for the hashing method requested by
300 .Fa setting .
301 .It Er ENOMEM
302 Failed to allocate internal scratch memory.
303 .br
304 .Nm crypt_ra
305 only: failed to allocate memory for
306 .Fa data .
307 .It Er ENOSYS No or Er EOPNOTSUPP
308 Hashing passphrases is not supported at all on this installation,
309 or the hashing method requested by
310 .Fa setting
311 is not supported.
312 These error codes are not used by this version of libcrypt,
313 but may be encountered on other systems.
314 .El
315 .Sh PORTABILITY NOTES
316 .Nm crypt
317 is included in POSIX, but
318 .Nm crypt_r ,
319 .Nm crypt_rn ,
320 and
321 .Nm crypt_ra
322 are not part of any standard.
323 .Pp
324 POSIX does not specify any hashing methods,
325 and does not require hashed passphrases to be portable between systems.
326 In practice, hashed passphrases are portable
327 as long as both systems support the hashing method that was used.
328 However, the set of supported hashing methods
329 varies considerably from system to system.
330 .Pp
331 The behavior of
332 .Nm crypt
333 on errors isn't well standardized.
334 Some implementations simply can't fail
335 (except by crashing the program),
336 others return a null pointer or a fixed string.
337 Most implementations don't set
338 .Va errno ,
339 but some do.
340 POSIX specifies returning a null pointer and setting
341 .Va errno ,
342 but it defines only one possible error,
343 .Er ENOSYS ,
344 in the case where
345 .Nm crypt
346 is not supported at all.
347 Some older applications are not prepared to handle null pointers
348 returned by
349 .Nm crypt .
350 The behavior described above for this implementation,
351 setting
352 .Va errno
353 and returning an invalid hash different from
354 .Fa setting ,
355 is chosen to make these applications fail closed when an error occurs.
356 .Pp
357 Due to historical restrictions
358 on the export of cryptographic software from the USA,
359 .Nm crypt
360 is an optional POSIX component.
361 Applications should therefore be prepared for
362 .Nm crypt
363 not to be available,
364 or to always fail (setting
365 .Va errno
366 to
367 .Er ENOSYS )
368 at runtime.
369 .Pp
370 POSIX specifies that
371 .Nm crypt
372 is declared in
373 .In unistd.h ,
374 but only if the macro
375 .Dv _XOPEN_CRYPT
376 is defined and has a value greater than or equal to zero.
377 Since libcrypt does not provide
378 .In unistd.h ,
379 it declares
380 .Nm crypt ,
381 .Nm crypt_r ,
382 .Nm crypt_rn ,
383 and
384 .Nm crypt_ra
385 in
386 .In crypt.h
387 instead.
388 .Pp
389 On a minority of systems (notably recent versions of Solaris),
390 .Nm crypt
391 uses a thread-specific static storage buffer,
392 which makes it safe to call from multiple threads simultaneously,
393 but does not prevent each call within a thread
394 from overwriting the results of the previous one.
395 .Sh BUGS
396 Some implementations of
397 .Nm crypt ,
398 upon error,
399 return an invalid hash that is stored in a read-only location
400 or only initialized once,
401 which means that it is only safe to erase the buffer pointed to by the
402 .Nm crypt
403 return value if an error did not occur.
404 .Pp
405 .Vt "struct crypt_data"
406 may be quite large (32kB in this implementation of libcrypt;
407 over 128kB in some other implementations).
408 This is large enough that it may be unwise to allocate it on the stack.
409 .Pp
410 Some recently designed hashing methods need even more scratch memory,
411 but the
412 .Nm crypt_r
413 interface makes it impossible to change the size of
414 .Vt "struct crypt_data"
415 without breaking binary compatibility.
416 The
417 .Nm crypt_rn
418 interface could accommodate larger allocations for specific hashing methods,
419 but the caller of
420 .Nm crypt_rn
421 has no way of knowing how much memory to allocate.
422 .Nm crypt_ra
423 does the allocation itself,
424 but can only make a single call to
425 .Xr malloc 3 .
426 .Sh ATTRIBUTES
427 For an explanation of the terms used in this section, see
428 .Xr attributes 7 .
429 .TS
430 allbox;
431 lb lb lb
432 l l l.
433 Interface Attribute Value
434 T{
435 .Nm crypt
436 T} Thread safety MT-Unsafe race:crypt
437 T{
438 .Nm crypt_r ,
439 .Nm crypt_rn ,
440 .Nm crypt_ra
441 T} Thread safety MT-Safe
442 .TE
443 .sp
444 .Sh HISTORY
445 A rotor-based
446 .Nm crypt
447 function appeared in
448 .At v6 .
449 The
450 .Dq traditional
451 DES-based
452 .Nm crypt
453 first appeared in
454 .At v7 .
455 .Pp
456 .Nm crypt_r
457 originates with the GNU C Library.
458 There's also a
459 .Nm crypt_r
460 function on HP-UX and MKS Toolkit, but the prototypes and semantics
461 differ.
462 .Pp
463 .Nm crypt_rn
464 and
465 .Nm crypt_ra
466 originate with the Openwall project.
467 .Sh SEE ALSO
468 .Xr crypt_gensalt 3 ,
469 .Xr getpass 3 ,
470 .Xr getpwent 3 ,
471 .Xr shadow 3 ,
472 .Xr login 1 ,
473 .Xr passwd 1 ,
474 .Xr crypt 5 ,
475 .Xr passwd 5 ,
476 .Xr shadow 5 ,
477 .Xr pam 8