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

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

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

FEEDBACK

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

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.