PW_GENSALT(3)

NAME
pw_gensalt - passwd salt generation function

LIBRARY
libcrypt

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.