1.\" $NetBSD: pw_gensalt.3,v 1.8 2021/10/12 12:03:47 nia Exp $ 2.\" 3.\" Copyright (c) 2020 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Christos Zoulas. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.\" 31.Dd October 12, 2021 32.Dt PW_GENSALT 3 33.Os 34.Sh NAME 35.Nm pw_gensalt 36.Nd passwd salt generation function 37.Sh LIBRARY 38.Lb libcrypt 39.Sh SYNOPSIS 40.In pwd.h 41.Ft int 42.Fn pw_gensalt "char *salt" "size_t saltlen" "const char *type" "const char *option" 43.Sh DESCRIPTION 44The 45.Fn pw_gensalt 46function generates a 47.Dq salt 48to be added to a password hashing function to guarantee uniqueness and 49slow down dictionary and brute force attacks. 50The function places a random array of 51.Ar saltlen 52bytes in 53.Ar salt 54using the hash function specified in 55.Ar type 56with the function-specific 57.Ar option . 58.Pp 59The new salt types follow the 60.Dq Modular Crypt Format 61(MCF) standard and are of the form: 62.Bd -literal -offset indent 63.Li $<id>[$<param>=<value>(,<param>=<value>)*][$<salt>[$<hash>]] 64.Ed 65.Pp 66The characters allowed in the password salt are alphanumeric and 67include a forward slash and a period (are in the regular expression 68format 69.Li [A-Za-z0-9/.] ) . 70.Pp 71The following types are available: 72.Bl -tag -width blowfish -offset indent 73.It old 74The original Unix implementation. 75This is of the form 76.Li _Gl/.???? , 77where 78.Li \&? 79denotes a random alphanumeric character. 80The minimum salt size is 81.Dv 3 . 82.It new 83The Seventh Edition Unix 12 bit salt. 84This has the same form as the 85.Sq old . 86The minimum salt size is 87.Dv 10 . 88The number of rounds can be specified in 89.Ar option 90and is enforced to be between 91.Dv 7250 92and 93.Dv 16777215 . 94.It newsalt 95An alias for 96.Sq new . 97.It md5 98A salt generated using the 99.Xr md5 1 100algorithm. 101This is of the form 102.Li $1$????????$ . 103The minimum salt size is 104.Dv 13 . 105.It sha1 106A salt generated using the 107.Xr sha1 1 108algorithm. 109This is of the form 110.Li $sha1$nrounds$????????$ , 111where 112.Ar nrounds 113is the number of rounds to be used. 114The number of rounds can be specified in 115.Ar option , 116and defaults to random if 117.Dv NULL . 118The minimum salt size is 119.Dv 8 120and the maximum is 121.Dv 64 . 122.It blowfish 123A salt generated using the 124.Sq blowfish 125algorithm. 126The minimum salt size is 127.Dv 30 128and the number of rounds needs to be specified in 129.Ar option . 130This is of the form: 131.Li $2a$nrounds$?????????????????????? . 132The 133.Li 2 134in the salt string indicates the current blowfish version. 135.It argon2d 136This is of the form: 137.Li $argon2d$v=19$m=MEMORY,t=TIME,p=THREADS$????????????????$ 138.It argon2i 139This is of the form: 140.Li $argon2i$v=19$m=MEMORY,t=TIME,p=THREADS$????????????????$ 141.It argon2id 142This is of the form: 143.Li $argon2id$v=19$m=MEMORY,t=TIME,p=THREADS$????????????????$ 144.It argon2 145An alias for 146.Dq argon2id . 147.Pp 148See 149.Xr crypt 3 150for details on the Argon2 parameters. 151.El 152.Sh RETURN VALUES 153Upon successful completion, a value of 0 is returned. 154Otherwise, a value of \-1 is returned and 155.Va errno 156is set to indicate the error. 157.Sh ERRORS 158.Fn pw_gensalt 159will fail if: 160.Bl -tag -width Er 161.It Bq Er EINVAL 162If the 163.Ar option 164is not specified or has an illegal value. 165.It Bq Er ENOSPC 166The 167.Ar saltlen 168was not large enough to fit the salt for the specified 169.Ar type . 170.El 171.Sh SEE ALSO 172.Xr passwd 1 , 173.Xr pwhash 1 174.Sh HISTORY 175The 176.Fn pw_gensalt 177function was written in 1997 by 178.An Niels Provos Aq Mt provos@physnet.uni-hamburg.de . 179.Pp 180The 181.Lk https://passlib.readthedocs.io/en/stable/modular_crypt_format.html "Modular Crypt Format (MCF)" . 182.Pp 183The 184.Lk https://github.com/P-H-C/phc-string-format/blob/master/phc-sf-spec.md "Password Hashing Competition (PHC) format" . 185