[src/trunk]: src/lib/libcrypt PR/55095: David A. Holland: pw_gensalt(3) undoc...

[christos <christos%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/972d3c559137
branches:  trunk
changeset: 970484:972d3c559137
user:      christos <christos%NetBSD.org@localhost>
date:      Wed Mar 25 17:11:06 2020 +0000

description:
PR/55095: David A. Holland: pw_gensalt(3) undocumented

diffstat:

 lib/libcrypt/Makefile     |    4 +-
 lib/libcrypt/pw_gensalt.3 |  153 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 155 insertions(+), 2 deletions(-)

diffs (175 lines):

diff -r 16c0af3bbf38 -r 972d3c559137 lib/libcrypt/Makefile
--- a/lib/libcrypt/Makefile     Wed Mar 25 17:06:17 2020 +0000
+++ b/lib/libcrypt/Makefile     Wed Mar 25 17:11:06 2020 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: Makefile,v 1.26 2019/10/21 02:36:48 jhigh Exp $
+#      $NetBSD: Makefile,v 1.27 2020/03/25 17:11:06 christos Exp $
 
 .include <bsd.own.mk>
 
@@ -21,7 +21,7 @@
 
 WARNS?=        5
 
-MAN=   crypt.3
+MAN=   crypt.3 pw_gensalt.3
 MLINKS= crypt.3 encrypt.3 crypt.3 setkey.3
 
 
diff -r 16c0af3bbf38 -r 972d3c559137 lib/libcrypt/pw_gensalt.3
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/lib/libcrypt/pw_gensalt.3 Wed Mar 25 17:11:06 2020 +0000
@@ -0,0 +1,153 @@
+.\"    $NetBSD: pw_gensalt.3,v 1.1 2020/03/25 17:11:06 christos 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 March 25, 2020
+.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 .
+.Ph
+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.
+.Pp
+.The following types are available:
+.Bl -tag -width blowfish compact
+.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$??????????????????????$ .
+.\" .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:
+.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 pwhash 1
+.Sh HISTORY
+The
+.Fn pw_gensalt
+function was written in 1997 Niels Provos <provos%physnet.uni-hamburg.de@localhost>.