search..
No manual entry for -- in section 3
CRYPT_GENSALT(3)	    Library Functions Manual	       CRYPT_GENSALT(3)

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 com-
       pile 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  ex-
       act  meaning  of	 count depend on the hashing method, but larger numbers
       correspond to more costly hashes in terms of CPU time and possibly  mem-
       ory  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 ig-
       nored.

       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 unspeci-
       fied 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 implemen-
			  tation; 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 libx-
       crypt 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 ar-
       guments.

       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)