/ 
Crypt-Sodium-XS-0.000020
River stage zero No dependents
/ Crypt::Sodium::XS::OO::pwhash

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

Crypt::Sodium::XS
Crypt::Sodium::XS::pwhash
https://doc.libsodium.org/password_hashing

FEEDBACK

For reporting bugs, giving feedback, submitting patches, etc. please use the following:

  • IRC channel #sodium on irc.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.