Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.

PW_GENSALT(3)              Library Functions Manual              PW_GENSALT(3)

NAME
     pw_gensalt - passwd salt generation function

LIBRARY
     Crypt Library (libcrypt, -lcrypt)

SYNOPSIS
     #include <pwd.h>

     int
     pw_gensalt(char *salt, size_t saltlen, const char *type,
         const char *option);

DESCRIPTION
     The pw_gensalt() function generates a "salt" to be added to a password
     hashing function to guarantee uniqueness and slow down dictionary and
     brute force attacks.  The function places a random array of saltlen bytes
     in salt using the hash function specified in type with the function-
     specific option.

     The new salt types follow the "Modular Crypt Format" (MCF) standard and
     are of the form:

           $<id>[$<param>=<value>(,<param>=<value>)*][$<salt>[$<hash>]]

     The characters allowed in the password salt are alphanumeric and include
     a forward slash and a period (are in the regular expression format
     [A-Za-z0-9/.]).

     The following types are available:

           old       The original Unix implementation.  This is of the form
                     _Gl/.????, where ? denotes a random alphanumeric
                     character.  The minimum salt size is 3.

           new       The Seventh Edition Unix 12 bit salt.  This has the same
                     form as the `old'.  The minimum salt size is 10.  The
                     number of rounds can be specified in option and is
                     enforced to be between 7250 and 16777215.

           newsalt   An alias for `new'.

           md5       A salt generated using the md5(1) algorithm.  This is of
                     the form $1$????????$.  The minimum salt size is 13.

           sha1      A salt generated using the sha1(1) algorithm.  This is of
                     the form $sha1$nrounds$????????$, where nrounds is the
                     number of rounds to be used.  The number of rounds can be
                     specified in option, and defaults to random if NULL.  The
                     minimum salt size is 8 and the maximum is 64.

           blowfish  A salt generated using the `blowfish' algorithm.  The
                     minimum salt size is 30 and the number of rounds needs to
                     be specified in option.  This is of the form:
                     $2a$nrounds$??????????????????????.  The 2 in the salt
                     string indicates the current blowfish version.

           argon2d   This is of the form:
                     $argon2d$v=19$m=MEMORY,t=TIME,p=THREADS$????????????????$

           argon2i   This is of the form:
                     $argon2i$v=19$m=MEMORY,t=TIME,p=THREADS$????????????????$

           argon2id  This is of the form:
                     $argon2id$v=19$m=MEMORY,t=TIME,p=THREADS$????????????????$

           argon2    An alias for "argon2id".

                     See crypt(3) for details on the Argon2 parameters.

RETURN VALUES
     Upon successful completion, a value of 0 is returned.  Otherwise, a value
     of -1 is returned and errno is set to indicate the error.

ERRORS
     pw_gensalt() will fail if:

     [EINVAL]           If the option is not specified or has an illegal
                        value.

     [ENOSPC]           The saltlen was not large enough to fit the salt for
                        the specified type.

SEE ALSO
     passwd(1), pwhash(1)

HISTORY
     The pw_gensalt() function was written in 1997 by Niels Provos
     <provos@physnet.uni-hamburg.de>.

     The Modular Crypt Format (MCF):
     https://passlib.readthedocs.io/en/stable/modular_crypt_format.html.

     The Password Hashing Competition (PHC) format:
     https://github.com/P-H-C/phc-string-format/blob/master/phc-sf-spec.md.

NetBSD 10.99                   October 12, 2021                   NetBSD 10.99