PW_GENSALT(3)

PW_GENSALT(3) | Library Functions Manual | PW_GENSALT(3)

# NAME

`pw_gensalt` —
passwd salt generation function

# LIBRARY

Crypt Library (libcrypt, -lcrypt)

# SYNOPSIS

`#include <pwd.h>`

int
`pw_gensalt`(char *salt, size_t saltlen, const char *type, const char *option);

# DESCRIPTION

The `pw_gensalt`() function generates a “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 saltlen bytes in salt using the hash function specified in type with the function-specific option.

The new salt types follow the “Modular Crypt Format” (MCF) standard and are of the form:

    $<id>[$<param>=<value>(,<param>=<value>)*][$<salt>[$<hash>]]

The characters allowed in the password salt are alphanumeric and include a forward slash and a period (are in the regular expression format `[A-Za-z0-9/.]`).

The following types are available:

old
  The original Unix implementation. This is of the form `_Gl/.????`, where `?` denotes a random alphanumeric character. The minimum salt size is `3`.
new
  The Seventh Edition Unix 12 bit salt. This has the same form as the ‘old’. The minimum salt size is `10`. The number of rounds can be specified in option and is enforced to be between `7250` and `16777215`.
newsalt
  An alias for ‘new’.
md5
  A salt generated using the md5(1) algorithm. This is of the form `$1$????????$`. The minimum salt size is `13`.
sha1
  A salt generated using the sha1(1) algorithm. This is of the form `$sha1$nrounds$????????$`, where nrounds is the number of rounds to be used. The number of rounds can be specified in option, and defaults to random if `NULL`. The minimum salt size is `8` and the maximum is `64`.
blowfish
  A salt generated using the ‘blowfish’ algorithm. The minimum salt size is `30` and the number of rounds needs to be specified in option. This is of the form: `$2a$nrounds$??????????????????????`. The `2` in the salt string indicates the current blowfish version.
argon2d
  This is of the form: `$argon2d$v=19$m=MEMORY,t=TIME,p=THREADS$????????????????$`
argon2i
  This is of the form: `$argon2i$v=19$m=MEMORY,t=TIME,p=THREADS$????????????????$`
argon2id
  This is of the form: `$argon2id$v=19$m=MEMORY,t=TIME,p=THREADS$????????????????$`
argon2
  An alias for “argon2id”.

  See crypt(3) for details on the Argon2 parameters.

# RETURN VALUES

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and errno is set to indicate the error.

# ERRORS

`pw_gensalt`() will fail if:

[`EINVAL`]
  If the option is not specified or has an illegal value.
[`ENOSPC`]
  The saltlen was not large enough to fit the salt for the specified type.

# SEE ALSO

passwd(1), pwhash(1)

# HISTORY

The `pw_gensalt`() function was written in 1997 by Niels Provos <provos@physnet.uni-hamburg.de>.

The Modular Crypt Format (MCF).

The Password Hashing Competition (PHC) format.

October 12, 2021 | NetBSD 10.1