Provided by: libcrypt2-dev_4.1.1-1_amd64 bug

NAME

       crypt_gensalt, crypt_gensalt_rn, crypt_gensalt_ra - encode settings for passphrase hashing

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);

       Link with -lcrypt.

DESCRIPTION

       crypt_gensalt, crypt_gensalt_rn, and crypt_gensalt_ra 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 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) for other strings that can be used as prefix, and valid values of  count  for
       each.

RETURN VALUE

       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.

       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.

FEATURE TEST MACROS

       The following macros are defined by crypt.h:

       CRYPT_GENSALT_IMPLEMENTS_DEFAULT_PREFIX
              A null pointer can be specified as prefix argument.

       CRYPT_GENSALT_IMPLEMENTS_AUTO_ENTROPY
              A null pointer can be specified as 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 could be
       specified as 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).

       ┌──────────────────┬───────────────┬──────────────────────────────┐
       │InterfaceAttributeValue                        │
       ├──────────────────┼───────────────┼──────────────────────────────┤
       │crypt_gensalt     │ Thread safety │ MT-Unsafe race:crypt_gensalt │
       ├──────────────────┼───────────────┼──────────────────────────────┤
       │crypt_gensalt_rn, │ Thread safety │ MT-Safe                      │
       │crypt_gensalt_ra  │               │                              │
       └──────────────────┴───────────────┴──────────────────────────────┘

SEE ALSO

       crypt(3), crypt_rn(3), getpass(3), getpwent(3), shadow(3), login(1), passwd(1), crypt(5),
       passwd(5), shadow(5), pam(8)