NAME
Crypt::Sodium::XS::pwhash - Password hashing and verification
SYNOPSIS
use Crypt::Sodium::XS::pwhash ":default";
my $passphrase = "this is a passphrase.";
# key derivation
my $salt = sodium_random_bytes($pwhash->SALTBYTES);
my $key_length = 32;
my $key = pwhash($passphrase, $salt, $key_length);
# password storage
my $pwhash_str = pwhash_str($passphrase);
die "bad password" unless pwhash_verify($pwhash_str, $passphrase);
if (pwhash_str_needs_rehash($pwhash_str)) {
my $new_pwhash_str = pwhash_str($passphrase);
}DESCRIPTION
Secret keys used to encrypt or sign confidential data have to be chosen from a very large keyspace. However, passwords are usually short, human-generated strings, making dictionary attacks practical.
Crypt::Sodium::XS::pwhash functions derive a secret key of any size from a password and a salt.
The generated key has the size defined by the application, no matter what the password length is.
The same password hashed with same parameters will always produce the same output.
The same password hashed with different salts will produce different outputs.
The function deriving a key from a password and a salt is CPU intensive and intentionally requires a fair amount of memory. Therefore, it mitigates brute-force attacks by requiring a significant effort to verify each password.
Common use cases:
Password storage
Or rather: storing what it takes to verify a password without having to store the actual password.
Deriving a secret key from a password
For example, for disk encryption. Crypt::Sodium::XS::pwhash's high-level
pwhash_*API currently leverages the Argon2id function on all platforms (when not using primitive-specific functions). This can change at any point in time, but it is guaranteed that a given version of libsodium can verify all hashes produced by all previous versions, from any platform. Applications don't have to worry about backward compatibility.
The more specific pwhash_scryptsalsa208sha256_* API uses the more conservative and widely deployed Scrypt function.
FUNCTIONS
Nothing is exported by default. A :default tag imports the functions and constants as documented below. A separate import tag is provided for each of the primitives listed in "PRIMITIVES". For example, :argon2i imports pwhash_argon2i_str. You should use at least one import tag.
pwhash
my $hash = pwhash($password, $salt, $hash_length, $opslimit, $memlimit);$hash_length specifies the desired output hash length. It is optional. If omitted or the provided argument is false, the default of "pwhash_STRBYTES" will be used. If provided, it must be from "pwhash_BYTES_MIN" to "pwhash_BYTES_MAX", inclusive.
$opslimit specifies the cpu-hardness of generating the hash. It is optional. If omitted or the provided argument is false, the default of "pwhash_OPSLIMIT_INTERACTIVE" will be used. If provided, it must be from "pwhash_OPSLIMIT_MIN" to "pwhash_OPSLIMIT_MAX", inclusive.
$memlimit specifies the memory-hardness of generating the hash. It is optional. If omitted or the provided argument is false, the default of "pwhash_MEMLIMIT_INTERACTIVE" will be used. If provided, it must be from "pwhash_MEMLIMIT_MIN" to "pwhash_MEMLIMIT_MAX", inclusive.
pwhash_salt
my $salt = pwhash_salt();Generate a random salt of "pwhash_SALTBYTES" length.
pwhash_str
my $hash_string = pwhash_str($password, $opslimit, $memlimit);pwhash_str_needs_rehash
my $needs_rehash = pwhash_str_needs_rehash($string);
my $needs_rehash = pwhash_str_needs_rehash($string, $opslimit);
my $needs_rehash = pwhash_str_needs_rehash($string, $opslimit, $memlimit);pwhash_verify
my $is_valid = pwhash_verify($hash_string, $password);CONSTANTS
pwhash_PRIMITIVE
my $default_primitive = pwhash_PRIMITIVE();pwhash_BYTES_MAX
my $hash_max_length = pwhash_BYTES_MAX();pwhash_BYTES_MIN
my $hash_min_length = pwhash_BYTES_MAX();pwhash_MEMLIMIT_INTERACTIVE
my $memlimit = pwhash_MEMLIMIT_INTERACTIVE();pwhash_MEMLIMIT_MAX
my $memlimit = pwhash_MEMLIMIT_MAX();pwhash_MEMLIMIT_MIN
my $memlimit = pwhash_MEMLIMIT_MIN();pwhash_MEMLIMIT_MODERATE
my $memlimit = pwhash_MEMLIMIT_MODERATE();pwhash_MEMLIMIT_SENSITIVE
my $memlimit = pwhash_MEMLIMIT_SENSITIVE();pwhash_OPSLIMIT_INTERACTIVE
my $opslimit = pwhash_OPSLIMIT_INTERACTIVE();pwhash_OPSLIMIT_MAX
my $memlimit = pwhash_OPSLIMIT_MAX();pwhash_OPSLIMIT_MIN
my $memlimit = pwhash_OPSLIMIT_MIN();pwhash_OPSLIMIT_MODERATE
my $opslimit = pwhash_OPSLIMIT_MODERATE();pwhash_OPSLIMIT_SENSITIVE
my $opslimit = pwhash_OPSLIMIT_SENSITIVE();pwhash_PASSWD_MAX
my $hash_max_length = pwhash_PASSWD_MAX();pwhash_PASSWD_MIN
my $hash_min_length = pwhash_PASSWD_MIN();pwhash_SALTBYTES
my $salt_length = pwhash_SALTBYTES();pwhash_STRBYTES
my $hash_string_length = pwhash_STRBYTES();pwhash_STRPREFIX
my $hash_string_prefix = pwhash_STRPREFIX();PRIMITIVES
All constants (except _PRIMITIVE) and functions have pwhash_<primitive>-prefixed couterparts (e.g., pwhash_argon2id, pwhash_argon2i_STRBYTES).
argon2i and argon2id are version 1.3 of the primitive.
argon2i
argon2id
scryptsalsa208sha256
SEE ALSO
FEEDBACK
For reporting bugs, giving feedback, submitting patches, etc. please use the following:
RT queue at https://rt.cpan.org/Dist/Display.html?Name=Crypt-Sodium-XS
IRC channel
#sodiumonirc.perl.org.Email the author directly.
AUTHOR
Brad Barden <perlmodules@5c30.org>
COPYRIGHT & LICENSE
Copyright (c) 2022 Brad Barden. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.