NAME
Crypt::Sodium::XS::OO::pwhash - Password hashing and verification
SYNOPSIS
use Crypt::Sodium::XS;
use Crypt::Sodium::XS::Util "sodium_random_bytes";
my $pwhash = Crypt::Sodium::XS->pwhash;
my $passphrase = "this is a passphrase.";
# key derivation
my $salt = sodium_random_bytes($pwhash->SALTBYTES);
my $key_length = 32;
my $key = $pwhash->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.
CONSTRUCTOR
new
my $pwhash = Crypt::Sodium::XS::OO::pwhash->new;
my $pwhash = Crypt::Sodium::XS::OO::pwhash->new(primitive => 'argon2id');
my $pwhash = Crypt::Sodium::XS->pwhash;Returns a new onetimeauth object for the given primitive. If not given, the default primitive is default.
METHODS
PRIMITIVE
my $pwhash = Crypt::Sodium::XS::OO::pwhash->new;
my $default_primitive = $pwhash->PRIMITIVE;BYTES_MAX
my $hash_max_length = $pwhash->BYTES_MAX;BYTES_MIN
my $hash_min_length = $pwhash->BYTES_MAX;MEMLIMIT_INTERACTIVE
my $memlimit = $pwhash->MEMLIMIT_INTERACTIVE;MEMLIMIT_MAX
my $memlimit = $pwhash->MEMLIMIT_MAX;MEMLIMIT_MIN
my $memlimit = $pwhash->MEMLIMIT_MIN;MEMLIMIT_MODERATE
my $memlimit = $pwhash->MEMLIMIT_MODERATE;MEMLIMIT_SENSITIVE
my $memlimit = $pwhash->MEMLIMIT_SENSITIVE;OPSLIMIT_INTERACTIVE
my $opslimit = $pwhash->OPSLIMIT_INTERACTIVE;OPSLIMIT_MAX
my $memlimit = $pwhash->OPSLIMIT_MAX;OPSLIMIT_MIN
my $memlimit = $pwhash->OPSLIMIT_MIN;OPSLIMIT_MODERATE
my $opslimit = $pwhash->OPSLIMIT_MODERATE;OPSLIMIT_SENSITIVE
my $opslimit = $pwhash->OPSLIMIT_SENSITIVE;PASSWD_MAX
my $hash_max_length = $pwhash->PASSWD_MAX;PASSWD_MIN
my $hash_min_length = $pwhash->PASSWD_MIN;SALTBYTES
my $salt_length = $pwhash->SALTBYTES;STRBYTES
my $hash_string_length = $pwhash->STRBYTES;STRPREFIX
my $hash_string_prefix = $pwhash->STRPREFIX;primitives
my @primitives = $pwhash->primitives;Returns a list of all supported primitive names (including 'default').
pwhash
my $hash
= $pwhash->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 "STRBYTES" will be used. If provided, it must be from "BYTES_MIN" to "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 "OPSLIMIT_INTERACTIVE" will be used. If provided, it must be from "OPSLIMIT_MIN" to "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 "MEMLIMIT_INTERACTIVE" will be used. If provided, it must be from "MEMLIMIT_MIN" to "MEMLIMIT_MAX", inclusive.
salt
my $salt = $pwhash->salt;Generate a random salt of "SALTBYTES" length.
str
my $hash_string = $pwhash->str($password, $opslimit, $memlimit);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);verify
my $is_valid = $pwhash->verify($hash_string, $password);SEE ALSO
FEEDBACK
For reporting bugs, giving feedback, submitting patches, etc. please use the following:
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.