diff options
| author | christos <christos@NetBSD.org> | 2020-03-25 17:11:06 +0000 |
|---|---|---|
| committer | christos <christos@NetBSD.org> | 2020-03-25 17:11:06 +0000 |
| commit | ebb3b272bb9afdfb386f09ebcb0ca946f14a7caa (patch) | |
| tree | 53bd2612ac25ca2ea9073611ec7f78d13641910e /lib/libcrypt | |
| parent | 3bb70afdaba214d22077357e275b96f0d5520e4c (diff) | |
PR/55095: David A. Holland: pw_gensalt(3) undocumented
Diffstat (limited to 'lib/libcrypt')
| -rw-r--r-- | lib/libcrypt/Makefile | 4 | ||||
| -rw-r--r-- | lib/libcrypt/pw_gensalt.3 | 153 |
2 files changed, 155 insertions, 2 deletions
diff --git a/lib/libcrypt/Makefile b/lib/libcrypt/Makefile index 14abcd41bc8..68b59fa7677 100644 --- a/lib/libcrypt/Makefile +++ b/lib/libcrypt/Makefile @@ -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 @@ LDADD+= -largon2 WARNS?= 5 -MAN= crypt.3 +MAN= crypt.3 pw_gensalt.3 MLINKS= crypt.3 encrypt.3 crypt.3 setkey.3 diff --git a/lib/libcrypt/pw_gensalt.3 b/lib/libcrypt/pw_gensalt.3 new file mode 100644 index 00000000000..e2ee37a4b7f --- /dev/null +++ b/lib/libcrypt/pw_gensalt.3 @@ -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>. |
