NAME

Database::BI::Password - Hash and check the login password

VERSION

0.023.1

SYNOPSIS

use Database::BI::Password qw(hash_password verify_password is_password_hash);

my $hash = hash_password('correct horse battery staple');
# pbkdf2-sha256$200000$<salt>$<key>

verify_password('correct horse battery staple', $hash);   # 1
verify_password('wrong', $hash);                          # 0

DESCRIPTION

The login (config password_hash, see "Logging in" in Database::BI) stores only a hash of the password, never the password. The hash is PBKDF2-HMAC-SHA256 (RFC 8018) with a random 16-byte salt and a 32-byte key, written as pbkdf2-sha256$<rounds>$<salt>$<key>, the salt and key in base64 without padding. script/database-bi password makes one.

FUNCTIONS

hash_password

my $hash = hash_password($password, rounds => 200_000);

API SPECIFICATION

INPUT

$password: string, required, not empty (a character string is hashed as UTF-8)
rounds:    integer, optional, 10_000 to 100_000_000 (default 200_000)
salt:      16 bytes, optional (default random); for tests

OUTPUT

The hash string. Croaks on a missing password, rounds out of range, or a salt of another length; the messages are in %Database::BI::Password::MESSAGES. Crypt::URandom, which makes the salt, croaks when the system has no source of random bytes.

verify_password

my $ok = verify_password($password, $hash);

API SPECIFICATION

INPUT

$password: string
$hash:     string, as hash_password returns

OUTPUT

1 when the password is the one hashed, else 0, including for a missing password or a hash that is not one. Every byte of the key is compared, so the time taken does not depend on how much of it matched.

is_password_hash

is_password_hash($value);

API SPECIFICATION

INPUT

$value: anything

OUTPUT

1 when the value is a hash verify_password can check, else 0.

AUTHOR

Nigel Horne <njh@nigelhorne.com>

LICENCE AND COPYRIGHT

Copyright 2026 Nigel Horne.

Usage is subject to the GPL2 licence terms.