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