185 lines
4.8 KiB
Groff
185 lines
4.8 KiB
Groff
.\" $NetBSD: pw_gensalt.3,v 1.8 2021/10/12 12:03:47 nia Exp $
|
|
.\"
|
|
.\" 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 October 12, 2021
|
|
.Dt PW_GENSALT 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm pw_gensalt
|
|
.Nd passwd salt generation function
|
|
.Sh LIBRARY
|
|
.Lb libcrypt
|
|
.Sh SYNOPSIS
|
|
.In 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 .
|
|
.Pp
|
|
The new salt types follow the
|
|
.Dq Modular Crypt Format
|
|
(MCF) standard and are of the form:
|
|
.Bd -literal -offset indent
|
|
.Li $<id>[$<param>=<value>(,<param>=<value>)*][$<salt>[$<hash>]]
|
|
.Ed
|
|
.Pp
|
|
The characters allowed in the password salt are alphanumeric and
|
|
include a forward slash and a period (are in the regular expression
|
|
format
|
|
.Li [A-Za-z0-9/.] ) .
|
|
.Pp
|
|
The following types are available:
|
|
.Bl -tag -width blowfish -offset indent
|
|
.It 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 .
|
|
.It 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 .
|
|
.It newsalt
|
|
An alias for
|
|
.Sq new .
|
|
.It md5
|
|
A salt generated using the
|
|
.Xr md5 1
|
|
algorithm.
|
|
This is of the form
|
|
.Li $1$????????$ .
|
|
The minimum salt size is
|
|
.Dv 13 .
|
|
.It 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 .
|
|
.It blowfish
|
|
A salt generated using the
|
|
.Sq blowfish
|
|
algorithm.
|
|
The minimum salt size is
|
|
.Dv 30
|
|
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 argon2d
|
|
This is of the form:
|
|
.Li $argon2d$v=19$m=MEMORY,t=TIME,p=THREADS$????????????????$
|
|
.It argon2i
|
|
This is of the form:
|
|
.Li $argon2i$v=19$m=MEMORY,t=TIME,p=THREADS$????????????????$
|
|
.It argon2id
|
|
This is of the form:
|
|
.Li $argon2id$v=19$m=MEMORY,t=TIME,p=THREADS$????????????????$
|
|
.It argon2
|
|
An alias for
|
|
.Dq argon2id .
|
|
.Pp
|
|
See
|
|
.Xr crypt 3
|
|
for details on the Argon2 parameters.
|
|
.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:
|
|
.Bl -tag -width Er
|
|
.It Bq Er EINVAL
|
|
If the
|
|
.Ar option
|
|
is not specified or has an illegal value.
|
|
.It 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 by
|
|
.An Niels Provos Aq Mt provos@physnet.uni-hamburg.de .
|
|
.Pp
|
|
The
|
|
.Lk https://passlib.readthedocs.io/en/stable/modular_crypt_format.html "Modular Crypt Format (MCF)" .
|
|
.Pp
|
|
The
|
|
.Lk https://github.com/P-H-C/phc-string-format/blob/master/phc-sf-spec.md "Password Hashing Competition (PHC) format" .
|