💾 Archived View for gmi.noulin.net › gitRepositories › bcrypt › file › crypt.3.gmi captured on 2023-07-10 at 18:00:49. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2023-01-29)
-=-=-=-=-=-=-
crypt.3 (16454B)
1 .\" Written and revised by Solar Designer <solar at openwall.com> in 2000-2011.
2 .\" No copyright is claimed, and this man page is hereby placed in the public
3 .\" domain. In case this attempt to disclaim copyright and place the man page
4 .\" in the public domain is deemed null and void, then the man page is
5 .\" Copyright (c) 2000-2011 Solar Designer and it is hereby released to the
6 .\" general public under the following terms:
7 .\"
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted.
10 .\"
11 .\" There's ABSOLUTELY NO WARRANTY, express or implied.
12 .\"
13 .\" This manual page in its current form is intended for use on systems
14 .\" based on the GNU C Library with crypt_blowfish patched into libcrypt.
15 .\"
16 .TH CRYPT 3 "July 7, 2014" "Openwall Project" "Library functions"
17 .ad l
18 .\" No macros in NAME to keep makewhatis happy.
19 .SH NAME
20 \fBcrypt\fR, \fBcrypt_r\fR, \fBcrypt_rn\fR, \fBcrypt_ra\fR,
21 \fBcrypt_gensalt\fR, \fBcrypt_gensalt_rn\fR, \fBcrypt_gensalt_ra\fR
22 \- password hashing
23 .SH SYNOPSIS
24 .B #define _XOPEN_SOURCE
25 .br
26 .B #include <unistd.h>
27 .sp
28 .in +8
29 .ti -8
30 .BI "char *crypt(const char *" key ", const char *" setting );
31 .in -8
32 .sp
33 .B #define _GNU_SOURCE
34 .br
35 .B #include <crypt.h>
36 .sp
37 .in +8
38 .ti -8
39 .BI "char *crypt_r(const char *" key ", const char *" setting ", struct crypt_data *" data );
40 .in -8
41 .sp
42 .B #define _OW_SOURCE
43 .br
44 .B #include <crypt.h>
45 .sp
46 .in +8
47 .ti -8
48 .BI "char *crypt_rn(const char *" key ", const char *" setting ", void *" data ", int " size );
49 .ti -8
50 .BI "char *crypt_ra(const char *" key ", const char *" setting ", void **" data ", int *" size );
51 .ti -8
52 .BI "char *crypt_gensalt(const char *" prefix ", unsigned long " count ", const char *" input ", int " size );
53 .ti -8
54 .BI "char *crypt_gensalt_rn(const char *" prefix ", unsigned long " count ", const char *" input ", int " size ", char *" output ", int " output_size );
55 .ti -8
56 .BI "char *crypt_gensalt_ra(const char *" prefix ", unsigned long " count ", const char *" input ", int " size );
57 .ad b
58 .de crypt
59 .BR crypt ,
60 .BR crypt_r ,
61 .BR crypt_rn ", \\$1"
62 .ie "\\$2"" .B crypt_ra
63 .el .BR crypt_ra "\\$2"
64 ..
65 .de crypt_gensalt
66 .BR crypt_gensalt ,
67 .BR crypt_gensalt_rn ", \\$1"
68 .ie "\\$2"" .B crypt_gensalt_ra
69 .el .BR crypt_gensalt_ra "\\$2"
70 ..
71 .SH DESCRIPTION
72 The
73 .crypt and
74 functions calculate a cryptographic hash function of
75 .I key
76 with one of a number of supported methods as requested with
77 .IR setting ,
78 which is also used to pass a salt and possibly other parameters to
79 the chosen method.
80 The hashing methods are explained below.
81 .PP
82 Unlike
83 .BR crypt ,
84 the functions
85 .BR crypt_r ,
86 .BR crypt_rn " and"
87 .B crypt_ra
88 are reentrant.
89 They place their result and possibly their private data in a
90 .I data
91 area of
92 .I size
93 bytes as passed to them by an application and/or in memory they
94 allocate dynamically. Some hashing algorithms may use the data area to
95 cache precomputed intermediate values across calls. Thus, applications
96 must properly initialize the data area before its first use.
97 .B crypt_r
98 requires that only
99 .I data->initialized
100 be reset to zero;
101 .BR crypt_rn " and " crypt_ra
102 require that either the entire data area is zeroed or, in the case of
103 .BR crypt_ra ,
104 .I *data
105 is NULL. When called with a NULL
106 .I *data
107 or insufficient
108 .I *size
109 for the requested hashing algorithm,
110 .B crypt_ra
111 uses
112 .BR realloc (3)
113 to allocate the required amount of memory dynamically. Thus,
114 .B crypt_ra
115 has the additional requirement that
116 .IR *data ,
117 when non-NULL, must point to an area allocated either with a previous
118 call to
119 .B crypt_ra
120 or with a
121 .BR malloc (3)
122 family call.
123 The memory allocated by
124 .B crypt_ra
125 should be freed with
126 .BR free "(3)."
127 .PP
128 The
129 .crypt_gensalt and
130 functions compile a string for use as
131 .I setting
132 \- with the given
133 .I prefix
134 (used to choose a hashing method), the iteration
135 .I count
136 (if supported by the chosen method) and up to
137 .I size
138 cryptographically random
139 .I input
140 bytes for use as the actual salt.
141 If
142 .I count
143 is 0, a low default will be picked.
144 The random bytes may be obtained from
145 .BR /dev/urandom .
146 Unlike
147 .BR crypt_gensalt ,
148 the functions
149 .BR crypt_gensalt_rn " and " crypt_gensalt_ra
150 are reentrant.
151 .B crypt_gensalt_rn
152 places its result in the
153 .I output
154 buffer of
155 .I output_size
156 bytes.
157 .B crypt_gensalt_ra
158 allocates memory for its result dynamically. The memory should be
159 freed with
160 .BR free "(3)."
161 .SH RETURN VALUE
162 Upon successful completion, the functions
163 .crypt and
164 return a pointer to a string containing the setting that was actually used
165 and a printable encoding of the hash function value.
166 The entire string is directly usable as
167 .I setting
168 with other calls to
169 .crypt and
170 and as
171 .I prefix
172 with calls to
173 .crypt_gensalt and .
174 .PP
175 The behavior of
176 .B crypt
177 on errors isn't well standardized. Some implementations simply can't fail
178 (unless the process dies, in which case they obviously can't return),
179 others return NULL or a fixed string. Most implementations don't set
180 .IR errno ,
181 but some do. SUSv2 specifies only returning NULL and setting
182 .I errno
183 as a valid behavior, and defines only one possible error
184 .RB "(" ENOSYS ,
185 "The functionality is not supported on this implementation.")
186 Unfortunately, most existing applications aren't prepared to handle
187 NULL returns from
188 .BR crypt .
189 The description below corresponds to this implementation of
190 .BR crypt " and " crypt_r
191 only, and to
192 .BR crypt_rn " and " crypt_ra .
193 The behavior may change to match standards, other implementations or
194 existing applications.
195 .PP
196 .BR crypt " and " crypt_r
197 may only fail (and return) when passed an invalid or unsupported
198 .IR setting ,
199 in which case they return a pointer to a magic string that is
200 shorter than 13 characters and is guaranteed to differ from
201 .IR setting .
202 This behavior is safe for older applications which assume that
203 .B crypt
204 can't fail, when both setting new passwords and authenticating against
205 existing password hashes.
206 .BR crypt_rn " and " crypt_ra
207 return NULL to indicate failure. All four functions set
208 .I errno
209 when they fail.
210 .PP
211 The functions
212 .crypt_gensalt and
213 return a pointer to the compiled string for
214 .IR setting ,
215 or NULL on error in which case
216 .I errno
217 is set.
218 .SH ERRORS
219 .TP
220 .B EINVAL
221 .crypt "" :
222 .I setting
223 is invalid or not supported by this implementation;
224 .sp
225 .crypt_gensalt "" :
226 .I prefix
227 is invalid or not supported by this implementation;
228 .I count
229 is invalid for the requested
230 .IR prefix ;
231 the input
232 .I size
233 is insufficient for the smallest valid salt with the requested
234 .IR prefix ;
235 .I input
236 is NULL.
237 .TP
238 .B ERANGE
239 .BR crypt_rn :
240 the provided data area
241 .I size
242 is insufficient for the requested hashing algorithm;
243 .sp
244 .BR crypt_gensalt_rn :
245 .I output_size
246 is too small to hold the compiled
247 .I setting
248 string.
249 .TP
250 .B ENOMEM
251 .B crypt
252 (original glibc only):
253 failed to allocate memory for the output buffer (which subsequent calls
254 would re-use);
255 .sp
256 .BR crypt_ra :
257 .I *data
258 is NULL or
259 .I *size
260 is insufficient for the requested hashing algorithm and
261 .BR realloc (3)
262 failed;
263 .sp
264 .BR crypt_gensalt_ra :
265 failed to allocate memory for the compiled
266 .I setting
267 string.
268 .TP
269 .B ENOSYS
270 .B crypt
271 (SUSv2):
272 the functionality is not supported on this implementation;
273 .sp
274 .BR crypt ,
275 .B crypt_r
276 (glibc 2.0 to 2.0.1 only):
277 .de no-crypt-add-on
278 the crypt add-on is not compiled in and
279 .I setting
280 requests something other than the MD5-based algorithm.
281 ..
282 .no-crypt-add-on
283 .TP
284 .B EOPNOTSUPP
285 .BR crypt ,
286 .B crypt_r
287 (glibc 2.0.2 to 2.1.3 only):
288 .no-crypt-add-on
289 .SH HASHING METHODS
290 The implemented hashing methods are intended specifically for processing
291 user passwords for storage and authentication;
292 they are at best inefficient for most other purposes.
293 .PP
294 It is important to understand that password hashing is not a replacement
295 for strong passwords.
296 It is always possible for an attacker with access to password hashes
297 to try guessing candidate passwords against the hashes.
298 There are, however, certain properties a password hashing method may have
299 which make these key search attacks somewhat harder.
300 .PP
301 All of the hashing methods use salts such that the same
302 .I key
303 may produce many possible hashes.
304 Proper use of salts may defeat a number of attacks, including:
305 .TP
306 1.
307 The ability to try candidate passwords against multiple hashes at the
308 price of one.
309 .TP
310 2.
311 The use of pre-hashed lists of candidate passwords.
312 .TP
313 3.
314 The ability to determine whether two users (or two accounts of one user)
315 have the same or different passwords without actually having to guess
316 one of the passwords.
317 .PP
318 The key search attacks depend on computing hashes of large numbers of
319 candidate passwords.
320 Thus, the computational cost of a good password hashing method must be
321 high \- but of course not too high to render it impractical.
322 .PP
323 All hashing methods implemented within the
324 .crypt and
325 interfaces use multiple iterations of an underlying cryptographic
326 primitive specifically in order to increase the cost of trying a
327 candidate password.
328 Unfortunately, due to hardware improvements, the hashing methods which
329 have a fixed cost become increasingly less secure over time.
330 .PP
331 In addition to salts, modern password hashing methods accept a variable
332 iteration
333 .IR count .
334 This makes it possible to adapt their cost to the hardware improvements
335 while still maintaining compatibility.
336 .PP
337 The following hashing methods are or may be implemented within the
338 described interfaces:
339 .PP
340 .de hash
341 .ad l
342 .TP
343 .I prefix
344 .ie "\\$1"" \{\
345 "" (empty string);
346 .br
347 a string matching ^[./0-9A-Za-z]{2} (see
348 .BR regex (7))
349 .\}
350 .el "\\$1"
351 .TP
352 .B Encoding syntax
353 \\$2
354 .TP
355 .B Maximum password length
356 \\$3 (uses \\$4-bit characters)
357 .TP
358 .B Effective key size
359 .ie "\\$5"" limited by the hash size only
360 .el up to \\$5 bits
361 .TP
362 .B Hash size
363 \\$6 bits
364 .TP
365 .B Salt size
366 \\$7 bits
367 .TP
368 .B Iteration count
369 \\$8
370 .ad b
371 ..
372 .ti -2
373 .B Traditional DES-based
374 .br
375 This method is supported by almost all implementations of
376 .BR crypt .
377 Unfortunately, it no longer offers adequate security because of its many
378 limitations.
379 Thus, it should not be used for new passwords unless you absolutely have
380 to be able to migrate the password hashes to other systems.
381 .hash "" "[./0-9A-Za-z]{13}" 8 7 56 64 12 25
382 .PP
383 .ti -2
384 .B Extended BSDI-style DES-based
385 .br
386 This method is used on BSDI and is also available on at least NetBSD,
387 OpenBSD, and FreeBSD due to the use of David Burren's FreeSec library.
388 .hash _ "_[./0-9A-Za-z]{19}" unlimited 7 56 64 24 "1 to 2**24-1 (must be odd)"
389 .PP
390 .ti -2
391 .B FreeBSD-style MD5-based
392 .br
393 This is Poul-Henning Kamp's MD5-based password hashing method originally
394 developed for FreeBSD.
395 It is currently supported on many free Unix-like systems, on Solaris 10
396 and newer, and it is part of the official glibc.
397 Its main disadvantage is the fixed iteration count, which is already
398 too low for the currently available hardware.
399 .hash "$1$" "\e$1\e$[^$]{1,8}\e$[./0-9A-Za-z]{22}" unlimited 8 "" 128 "6 to 48" 1000
400 .PP
401 .ti -2
402 .BR "OpenBSD-style Blowfish-based" " (" bcrypt )
403 .br
404 .B bcrypt
405 was originally developed by Niels Provos and David Mazieres for OpenBSD
406 and is also supported on recent versions of FreeBSD and NetBSD,
407 on Solaris 10 and newer, and on several GNU/*/Linux distributions.
408 It is, however, not part of the official glibc.
409 .PP
410 While both
411 .B bcrypt
412 and the BSDI-style DES-based hashing offer a variable iteration count,
413 .B bcrypt
414 may scale to even faster hardware, doesn't allow for certain optimizations
415 specific to password cracking only, doesn't have the effective key size
416 limitation, and uses 8-bit characters in passwords.
417 .hash "$2b$" "\e$2[abxy]\e$[0-9]{2}\e$[./A-Za-z0-9]{53}" 72 8 "" 184 128 "2**4 to 2**99 (current implementations are limited to 2**31 iterations)"
418 .PP
419 With
420 .BR bcrypt ,
421 the
422 .I count
423 passed to
424 .crypt_gensalt and
425 is the base-2 logarithm of the actual iteration count.
426 .PP
427 .B bcrypt
428 hashes used the "$2a$" prefix since 1997.
429 However, in 2011 an implementation bug was discovered in crypt_blowfish
430 (versions up to 1.0.4 inclusive) affecting handling of password characters with
431 the 8th bit set.
432 Besides fixing the bug,
433 to provide for upgrade strategies for existing systems, two new prefixes were
434 introduced: "$2x$", which fully re-introduces the bug, and "$2y$", which
435 guarantees correct handling of both 7- and 8-bit characters.
436 OpenBSD 5.5 introduced the "$2b$" prefix for behavior that exactly matches
437 crypt_blowfish's "$2y$", and current crypt_blowfish supports it as well.
438 Unfortunately, the behavior of "$2a$" on password characters with the 8th bit
439 set has to be considered system-specific.
440 When generating new password hashes, the "$2b$" or "$2y$" prefix should be used.
441 (If such hashes ever need to be migrated to a system that does not yet support
442 these new prefixes, the prefix in migrated copies of the already-generated
443 hashes may be changed to "$2a$".)
444 .PP
445 .crypt_gensalt and
446 support the "$2b$", "$2y$", and "$2a$" prefixes (the latter for legacy programs
447 or configurations), but not "$2x$" (which must not be used for new hashes).
448 .crypt and
449 support all four of these prefixes.
450 .SH PORTABILITY NOTES
451 Programs using any of these functions on a glibc 2.x system must be
452 linked against
453 .BR libcrypt .
454 However, many Unix-like operating systems and older versions of the
455 GNU C Library include the
456 .BR crypt " function in " libc .
457 .PP
458 The
459 .BR crypt_r ,
460 .BR crypt_rn ,
461 .BR crypt_ra ,
462 .crypt_gensalt and
463 functions are very non-portable.
464 .PP
465 The set of supported hashing methods is implementation-dependent.
466 .SH CONFORMING TO
467 The
468 .B crypt
469 function conforms to SVID, X/OPEN, and is available on BSD 4.3.
470 The strings returned by
471 .B crypt
472 are not required to be portable among conformant systems.
473 .PP
474 .B crypt_r
475 is a GNU extension.
476 There's also a
477 .B crypt_r
478 function on HP-UX and MKS Toolkit, but the prototypes and semantics differ.
479 .PP
480 .B crypt_gensalt
481 is an Openwall extension.
482 There's also a
483 .B crypt_gensalt
484 function on Solaris 10 and newer, but the prototypes and semantics differ.
485 .PP
486 .BR crypt_rn ,
487 .BR crypt_ra ,
488 .BR crypt_gensalt_rn ,
489 and
490 .B crypt_gensalt_ra
491 are Openwall extensions.
492 .SH HISTORY
493 A rotor-based
494 .B crypt
495 function appeared in Version 6 AT&T UNIX.
496 The "traditional"
497 .B crypt
498 first appeared in Version 7 AT&T UNIX.
499 .PP
500 The
501 .B crypt_r
502 function was introduced during glibc 2.0 development.
503 .SH BUGS
504 The return values of
505 .BR crypt " and " crypt_gensalt
506 point to static buffers that are overwritten by subsequent calls.
507 These functions are not thread-safe.
508 .RB ( crypt
509 on recent versions of Solaris uses thread-specific data and actually is
510 thread-safe.)
511 .PP
512 The strings returned by certain other implementations of
513 .B crypt
514 on error may be stored in read-only locations or only initialized once,
515 which makes it unsafe to always attempt to zero out the buffer normally
516 pointed to by the
517 .B crypt
518 return value as it would otherwise be preferable for security reasons.
519 The problem could be avoided with the use of
520 .BR crypt_r ,
521 .BR crypt_rn ,
522 or
523 .B crypt_ra
524 where the application has full control over output buffers of these functions
525 (and often over some of their private data as well).
526 Unfortunately, the functions aren't (yet?) available on platforms where
527 .B crypt
528 has this undesired property.
529 .PP
530 Applications using the thread-safe
531 .B crypt_r
532 need to allocate address space for the large (over 128 KB)
533 .I struct crypt_data
534 structure. Each thread needs a separate instance of the structure. The
535 .B crypt_r
536 interface makes it impossible to implement a hashing algorithm which
537 would need to keep an even larger amount of private data, without breaking
538 binary compatibility.
539 .B crypt_ra
540 allows for dynamically increasing the allocation size as required by the
541 hashing algorithm that is actually used. Unfortunately,
542 .B crypt_ra
543 is even more non-portable than
544 .BR crypt_r .
545 .PP
546 Multi-threaded applications or library functions which are meant to be
547 thread-safe should use
548 .BR crypt_gensalt_rn " or " crypt_gensalt_ra
549 rather than
550 .BR crypt_gensalt .
551 .SH SEE ALSO
552 .BR login (1),
553 .BR passwd (1),
554 .BR crypto (3),
555 .BR encrypt (3),
556 .BR free (3),
557 .BR getpass (3),
558 .BR getpwent (3),
559 .BR malloc (3),
560 .BR realloc (3),
561 .BR shadow (3),
562 .BR passwd (5),
563 .BR shadow (5),
564 .BR regex (7),
565 .BR pam (8)
566 .sp
567 Niels Provos and David Mazieres. A Future-Adaptable Password Scheme.
568 Proceedings of the 1999 USENIX Annual Technical Conference, June 1999.
569 .br
570 http://www.usenix.org/events/usenix99/provos.html
571 .sp
572 Robert Morris and Ken Thompson. Password Security: A Case History.
573 Unix Seventh Edition Manual, Volume 2, April 1978.
574 .br
575 http://plan9.bell-labs.com/7thEdMan/vol2/password