Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/man/man3/crypt.3 @ 68:5028fdace37b

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