CRYPT_CHECKPASS(3) FreeBSD 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 <
[email protected]>
FreeBSD 14.1-RELEASE-p8 October 29, 2021 FreeBSD 14.1-RELEASE-p8