# crypt_gensalt_rn - encode settings for passphrase hashing - man(3) - [phpMan] [_CRYPT_GENSALT_(3)](https://www.chedong.com/phpMan.php/man/CRYPTGENSALT/3/markdown) Library Functions Manual [_CRYPT_GENSALT_(3)](https://www.chedong.com/phpMan.php/man/CRYPTGENSALT/3/markdown) ## NAME crypt_gensalt, crypt_gensalt_rn, crypt_gensalt_ra — encode settings for passphrase hashing ## LIBRARY Crypt Library (libcrypt, -lcrypt) ## SYNOPSIS ### #include _char_ _*_ **crypt_gensalt**(_const_ _char_ _*prefix_, _unsigned_ _long_ _count_, _const_ _char_ _*rbytes_, _int_ _nrbytes_); _char_ _*_ **crypt_gensalt_rn**(_const_ _char_ _*_ _prefix_, _unsigned_ _long_ _count_, _const_ _char_ _*rbytes_, _int_ _nrbytes_, _char_ _*_ _output_, _int_ _output_size_); _char_ _*_ **crypt_gensalt_ra**(_const_ _char_ _*prefix_, _unsigned_ _long_ _count_, _const_ _char_ _*rbytes_, _int_ _nrbytes_); ## DESCRIPTION The **crypt_gensalt**, **crypt_gensalt_rn**, and **crypt_gensalt_ra **functions compile a string for use as the _setting_ argument to **crypt**, **crypt_r**, **crypt_rn**, and **crypt_ra**. _prefix_ selects the hash‐ ing method to use. _count_ controls the CPU time cost of the hash; the valid range for _count_ and the exact meaning of “CPU time cost” depends on the hashing method, but larger numbers correspond to more costly hashes. _rbytes_ should point to _nrbytes_ cryptographically random bytes for use as “salt.” If _prefix_ is a null pointer, the best available hashing method will be selected. (**CAUTION**: if _prefix_ is an empty string, the “traditional” DES-based hashing method will be selected; this method is unacceptably weak by modern standards.) If _count_ is 0, a low default cost will be selected. If _rbytes_ is a null pointer, an appropriate number of random bytes will be obtained from the operating system, and _nrbytes_ is ignored. See [_crypt_(5)](https://www.chedong.com/phpMan.php/man/crypt/5/markdown) for other strings that can be used as _prefix_, and valid values of _count_ for each. ## RETURN VALUES **crypt_gensalt**, **crypt_gensalt_rn**, and **crypt_gensalt_ra **return a pointer to an encoded setting string. This string will be entirely printable ASCII, and will not contain whitespace or the characters ‘**:**’, ‘**;**’, ‘*****’, ‘**!**’, or ‘**\**’. See [_crypt_(5)](https://www.chedong.com/phpMan.php/man/crypt/5/markdown) for more detail on the format of this string. Upon error, they return a null pointer and set _errno_ to an appropriate error code. **crypt_gensalt **places its result in a static storage area, which will be overwritten by subse‐ quent calls to **crypt_gensalt**. It is not safe to call **crypt_gensalt **from multiple threads si‐ multaneously. However, it _is_ safe to pass the string returned by **crypt_gensalt **directly to **crypt **without copying it; each function has its own static storage area. **crypt_gensalt_rn **places its result in the supplied _output_ buffer, which has _output_size_ bytes of storage available. _output_size_ should be greater than or equal to CRYPT_GENSALT_OUTPUT_SIZE. **crypt_gensalt_ra **allocates memory for its result using [_malloc_(3)](https://www.chedong.com/phpMan.php/man/malloc/3/markdown). It should be freed with [_free_(3)](https://www.chedong.com/phpMan.php/man/free/3/markdown) after use. Upon error, in addition to returning a null pointer, **crypt_gensalt **and **crypt_gensalt_rn **will write an invalid setting string to their output buffer, if there is enough space; this string will begin with a ‘*****’ and will not be equal to _prefix_. ## ERRORS EINVAL _prefix_ is invalid or not supported by this implementation; _count_ is in‐ valid for the requested _prefix_; the input _nrbytes_ is insufficient for the smallest valid salt with the requested _prefix_. ERANGE **crypt_gensalt_rn **only: _output_size_ is too small to hold the compiled _setting_ string. ENOMEM Failed to allocate internal scratch memory. **crypt_gensalt_ra **only: failed to allocate memory for the compiled _setting_ string. ENOSYS, EACCES, EIO, etc. Obtaining random bytes from the operating system failed. This can only happen when _rbytes_ is a null pointer. ## FEATURE TEST MACROS The following macros are defined by <_crypt.h_>: CRYPT_GENSALT_IMPLEMENTS_DEFAULT_PREFIX A null pointer can be specified as the _prefix_ argument. CRYPT_GENSALT_IMPLEMENTS_AUTO_ENTROPY A null pointer can be specified as the _rbytes_ argument. ## PORTABILITY NOTES The functions **crypt_gensalt**, **crypt_gensalt_rn**, and **crypt_gensalt_ra **are not part of any stan‐ dard. They originate with the Openwall project. A function with the name **crypt_gensalt **also exists on Solaris 10 and newer, but its prototype and semantics differ. The default prefix and auto entropy features are available since libxcrypt version 4.0.0. Portable software can use feature test macros to find out whether null pointers can be used for the _prefix_ and _rbytes_ arguments. The set of supported hashing methods varies considerably from system to system. ## ATTRIBUTES For an explanation of the terms used in this section, see [_attributes_(7)](https://www.chedong.com/phpMan.php/man/attributes/7/markdown). ┌───────────────────┬───────────────┬──────────────────────────────┐ │ **Interface **│ **Attribute **│ **Value **│ ├───────────────────┼───────────────┼──────────────────────────────┤ │ **crypt_gensalt **│ Thread safety │ MT-Unsafe race:crypt_gensalt │ ├───────────────────┼───────────────┼──────────────────────────────┤ │ **crypt_gensalt_rn**, │ Thread safety │ MT-Safe │ │ **crypt_gensalt_ra **│ │ │ └───────────────────┴───────────────┴──────────────────────────────┘ ## SEE ALSO [_crypt_(3)](https://www.chedong.com/phpMan.php/man/crypt/3/markdown), [_getpass_(3)](https://www.chedong.com/phpMan.php/man/getpass/3/markdown), [_getpwent_(3)](https://www.chedong.com/phpMan.php/man/getpwent/3/markdown), [_shadow_(3)](https://www.chedong.com/phpMan.php/man/shadow/3/markdown), [_login_(1)](https://www.chedong.com/phpMan.php/man/login/1/markdown), [_passwd_(1)](https://www.chedong.com/phpMan.php/man/passwd/1/markdown), [_crypt_(5)](https://www.chedong.com/phpMan.php/man/crypt/5/markdown), [_passwd_(5)](https://www.chedong.com/phpMan.php/man/passwd/5/markdown), [_shadow_(5)](https://www.chedong.com/phpMan.php/man/shadow/5/markdown), [_pam_(8)](https://www.chedong.com/phpMan.php/man/pam/8/markdown) Openwall Project October 11, 2017 [_CRYPT_GENSALT_(3)](https://www.chedong.com/phpMan.php/man/CRYPTGENSALT/3/markdown)