NAME

       crypt_gensalt, crypt_gensalt_rn, crypt_gensalt_ra — encode settings for passphrase hashing

LIBRARY

       Crypt Library (libcrypt, -lcrypt)

SYNOPSIS

       #include <crypt.h>

       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) 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) 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.   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).  It should be freed with free(3) 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).
       ┌───────────────────┬───────────────┬──────────────────────────────┐
       │ 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), getpass(3), getpwent(3), shadow(3), login(1), passwd(1), crypt(5), passwd(5), shadow(5), pam(8)

Openwall Project                                 March 27, 2024                                 CRYPT_GENSALT(3)