Copyright (c) 2020 The NetBSD Foundation, Inc.
All rights reserved.
This code is derived from software contributed to The NetBSD Foundation
by Christos Zoulas.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
.Dd March 25, 2020 .Dt PW_GENSALT 3 .Os .Sh NAME .Nm pw_gensalt .Nd passwd salt generation function .Sh LIBRARY .Lb libcrypt .Sh SYNOPSIS n pwd.h .Ft int .Fn pw_gensalt "char *salt" "size_t saltlen" "const char *type" "const char *option" .Sh DESCRIPTION The .Fn pw_gensalt function generates a .Dq 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 .Ar saltlen bytes in .Ar salt using the hash function specified in .Ar type with the function-specific .Ar option .
h The new salt types follow the MCF standard and are of the form: .Li $<id>[$<param>=<value>(,<param>=<value>)*][$<salt>[$<hash>]] The characters allowed in the password salt are alphanumeric and include a forward slash and a period.
p
.The following types are available:
l -tag -width blowfish compact t old The original Unix implementation.
This is of the form
.Li _Gl/.???? ,
where
.Li ?
denotes a random alphanumeric character.
The minimum salt size is
.Dv 3 .
t new The Seventh Edition Unix 12 bit salt.
This has the same form as the
.Sq old .
The minimum salt size is
.Dv 10 .
The number of rounds can be specified in
.Ar option
and is enforced to be between
.Dv 7250
and
.Dv 16777215 .
t newsalt An alias for
.Sq new .
t md5 A salt generated using the
.Xr md5 1
algorithm.
This is of the form
.Li $1$????????$ .
The minimum salt size is
.Dv 13 .
t sha1 A salt generated using the
.Xr sha1 1
algorithm.
This is of the form
.Li $sha1$nrounds$????????$ ,
where
.Ar nrounds
is the number of rounds to be used.
The number of rounds can be specified in
.Ar option ,
and defaults to random if
.Dv NULL .
The minimum salt size is
.Dv 8
and the maximum is
.Dv 64 .
t blowfish A salt generated using the
.Sq blowfish
algorithm.
The minimum salt size is
.Dv 31
and the number of rounds needs to be specified in
.Ar option .
This is of the form:
.Li $2a$nrounds$??????????????????????$ .
The
.Li 2
in the salt string indicates the current blowfish version.
.It argon2
.It argon2id
.It argon2i
.It argon2
.El
.Sh RETURN VALUES
Upon successful completion, a value of 0 is returned.
Otherwise, a value of -1 is returned and
.Va errno
is set to indicate the error.
.Sh ERRORS
.Fn pw_gensalt
will fail if:
l -tag -width Er t Bq Er EINVAL If the
.Ar option
is not specified or has an illegal value.
t Bq Er ENOSPC The
.Ar saltlen
was not large enough to fit the salt for the specified
.Ar type.
.El
.Sh SEE ALSO
.Xr passwd 1 ,
.Xr pwhash 1
.Sh HISTORY
The
.Fn pw_gensalt
function was written in 1997 Niels Provos <provos@physnet.uni-hamburg.de>.