huschi.net

CRYPT_GENSALT(3)               Library Functions              CRYPT_GENSALT(3)
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 cor-
       respond to more costly hashes.  rbytes should point to nrbytes  crypto-
       graphically 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 new-
       er, but its prototype and semantics differ.
       The  default prefix and auto entropy features are available since libx-
       crypt 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 at-
       tributes(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), crypt_r(3), crypt_ra(3), crypt_rn(3), getpass(3), getp-
       went(3), shadow(3), login(1), passwd(1), crypt(5), passwd(5), shad-
       ow(5), pam(8)
Openwall Project                October 9, 2017               CRYPT_GENSALT(3)