CRYPT_CHECKPASS(3) | Library Functions Manual | CRYPT_CHECKPASS(3)

# NAME

`crypt_checkpass`, `crypt_newhash` — password hashing

# SYNOPSIS

`#include <pwd.h>`
`#include <unistd.h>`

int
`crypt_checkpass`(const char *password, const char *hash);

int
`crypt_newhash`(const char *password, const char *pref, char *hash, size_t hashsize);

# DESCRIPTION

The `crypt_checkpass`() function simplifies checking a user's password. If both the hash and the password are the empty string, authentication is a success. Otherwise, the password is hashed and compared to the provided hash. If the hash is `NULL`, authentication will always fail, but a default amount of work is performed to simulate the hashing operation. A successful match will return 0. A failure will return -1 and set errno(2).

The `crypt_newhash`() function simplifies the creation of new password hashes. The provided password is randomly salted and hashed and stored in hash. The size of the available space is specified by hashsize, which should be `_PASSWORD_LEN`. The pref argument identifies the preferred hashing algorithm and parameters. Possible values are:

“bcrypt,<rounds>”
  The bcrypt algorithm, where the value of rounds can be between 4 and 31 and specifies the base 2 logarithm of the number of rounds. If rounds is omitted or the special value ‘a’, an appropriate number of rounds is automatically selected based on system performance.

# RETURN VALUES

The `crypt_checkpass`() and `crypt_newhash`() functions return the value 0 if successful; otherwise the value -1 is returned and the global variable errno is set to indicate the error.

# ERRORS

The `crypt_checkpass`() function sets errno to `EACCES` when authentication fails.

The `crypt_newhash`() function sets errno to `EINVAL` if pref is unsupported or insufficient space is provided.

# SEE ALSO

crypt(3), login.conf(5), passwd(5)

# HISTORY

The function `crypt_checkpass`() first appeared in OpenBSD 5.6, and `crypt_newhash`() in OpenBSD 5.7.

# AUTHORS

Ted Unangst <tedu@openbsd.org>

October 29, 2021 | Debian