PW_GENSALT(3) FreeBSD 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
<
[email protected]>.
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.
FreeBSD 14.1-RELEASE-p8 October 12, 2021 FreeBSD 14.1-RELEASE-p8