--- name: "crypt_gensalt" section: "3" platform: "linux" package: "libxcrypt" version: "4.5.2-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/crypt_gensalt" --- # crypt\_gensalt(3) encode settings for passphrase hashing ## NAME **crypt\_gensalt**, **crypt\_gensalt\_rn**, **crypt\_gensalt\_ra** – encode settings for passphrase hashing ## LIBRARY library “libcrypt” ## 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 hashing method to use. *count* controls the processing cost of the hash; the valid range and exact meaning of *count* depend on the hashing method, but larger numbers correspond to more costly hashes in terms of CPU time and possibly memory usage. *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)](/crypt/5.md) 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)](/crypt/5.md) for more detail on the format of this string. Upon error, they return a null pointer and set *errno* to an appropriate error code. When the functions succeed, the value of *errno* is unspecified and must not be relied upon. **crypt\_gensalt** places its result in a static storage area, which will be overwritten by subsequent calls to **crypt\_gensalt**. It is not safe to call **crypt\_gensalt** from multiple threads simultaneously. It's also not recommended to use the pointer returned as an argument for another call to **crypt\_gensalt**, as some implementations, including earlier releases of libxcrypt, may overwrite the underlying static output buffer before computing the setting. 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. It's also not recommended to use the pointer returned as an argument for another call to **crypt\_gensalt\_rn** using the same *output* buffer for subsequent calls, as some implementations, including earlier releases of libxcrypt, may overwrite the supplied buffer before computing the setting. **crypt\_gensalt\_ra** allocates memory for its result using [malloc(3)](/malloc/3.md). It should be freed with [free(3)](/free/3.md) 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 invalid 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 standard. 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)](/attributes/7.md). | | | | | --- | --- | --- | | **Interface** | **Attribute** | **Value** | | | Thread safety | MT-Unsafe race:crypt\_gensalt | | | Thread safety | MT-Safe | ## SEE ALSO [crypt(3)](/crypt/3.md), [getpass(3)](/getpass/3.md), [getpwent(3)](/getpwent/3.md), [shadow(3)](/shadow/3.md), [login(1)](/login/1.md), [passwd(1)](/passwd/1.md), [crypt(5)](/crypt/5.md), [passwd(5)](/passwd/5.md), [shadow(5)](/shadow/5.md), [pam(8)](/pam/8.md)