pw_gensalt(3) - NetBSD Manual Pages

Command:
Section:
Arch:
Collection:
>>>
PW_GENSALT(3)           NetBSD 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-spe-
     cific 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 charac-
                     ter.  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