libsodium_crypto_pwhash (libsodium v3.0.1)
View SourcePassword hashing and password-based key derivation with Argon2, a memory-hard function designed to make brute-force attacks expensive.
str/3 produces a self-describing ASCII string (algorithm, parameters,
random salt, and hash) to store and later check with str_verify/2;
crypto_pwhash/6 derives a key of a chosen length from a password and a
saltbytes/0 byte salt. The default algorithm is Argon2id
(alg_default/0); store every parameter alongside derived keys, since the
defaults may change in future versions.
Opslimit (CPU cost) and Memlimit (memory in bytes) should be as high as
your latency budget allows: opslimit_interactive/0 and
memlimit_interactive/0 suit online logins, _moderate and _sensitive
are slower and stronger. All hashing runs on a dirty CPU scheduler.
Ops = libsodium_crypto_pwhash:opslimit_interactive(),
Mem = libsodium_crypto_pwhash:memlimit_interactive(),
Str = libsodium_crypto_pwhash:str(<<"correct horse">>, Ops, Mem),
0 = libsodium_crypto_pwhash:str_verify(Str, <<"correct horse">>),
-1 = libsodium_crypto_pwhash:str_verify(Str, <<"wrong horse">>),
Salt = libsodium_randombytes:buf(libsodium_crypto_pwhash:saltbytes()),
Key = libsodium_crypto_pwhash:crypto_pwhash(32, <<"correct horse">>, Salt, Ops, Mem,
libsodium_crypto_pwhash:alg_default()),
32 = byte_size(Key).Summary
Functions
Return the algorithm identifier for Argon2i version 1.3 (crypto_pwhash_ALG_ARGON2I13).
Return the algorithm identifier for Argon2id version 1.3 (crypto_pwhash_ALG_ARGON2ID13).
Return the identifier of the recommended algorithm (currently Argon2id 1.3).
Return crypto_pwhash_bytes_max(), in bytes.
Return crypto_pwhash_bytes_min(), in bytes.
Derive an Outlen byte key from Passwd and the salt Salt (at least
saltbytes/0 bytes; only the first saltbytes/0 are used) with the
cost parameters Opslimit and Memlimit and the algorithm Alg
(alg_argon2i13/0, alg_argon2id13/0 or alg_default/0).
Return crypto_pwhash_memlimit_interactive(), in bytes.
Return crypto_pwhash_memlimit_max(), in bytes.
Return crypto_pwhash_memlimit_min(), in bytes.
Return crypto_pwhash_memlimit_moderate(), in bytes.
Return crypto_pwhash_memlimit_sensitive(), in bytes.
Return crypto_pwhash_opslimit_interactive(), in bytes.
Return crypto_pwhash_opslimit_max(), in bytes.
Return crypto_pwhash_opslimit_min(), in bytes.
Return crypto_pwhash_opslimit_moderate(), in bytes.
Return crypto_pwhash_opslimit_sensitive(), in bytes.
Return crypto_pwhash_passwd_max(), in bytes.
Return crypto_pwhash_passwd_min(), in bytes.
Return the names of the supported primitives as a binary, such as <<"argon2id,argon2i">>.
Return crypto_pwhash_saltbytes(), in bytes.
Hash Passwd for storage using the default algorithm with the cost
parameters Opslimit and Memlimit and a random salt.
Like str/3, but hash Passwd with the algorithm Alg
(alg_argon2i13/0 or alg_argon2id13/0). Returns -1 on failure.
Check whether Str (an Argon2i or Argon2id string) was hashed with
exactly the cost parameters Opslimit and Memlimit.
Return crypto_pwhash_strbytes(), in bytes.
Return crypto_pwhash_strprefix() as a binary.
Functions
-spec alg_argon2i13() -> Result when Result :: 1.
Return the algorithm identifier for Argon2i version 1.3 (crypto_pwhash_ALG_ARGON2I13).
-spec alg_argon2id13() -> Result when Result :: 2.
Return the algorithm identifier for Argon2id version 1.3 (crypto_pwhash_ALG_ARGON2ID13).
-spec alg_default() -> Result when Result :: 2.
Return the identifier of the recommended algorithm (currently Argon2id 1.3).
-spec bytes_max() -> Result when Result :: 4294967295.
Return crypto_pwhash_bytes_max(), in bytes.
-spec bytes_min() -> Result when Result :: 16.
Return crypto_pwhash_bytes_min(), in bytes.
-spec crypto_pwhash(Outlen, Passwd, Salt, Opslimit, Memlimit, Alg) -> Result when Outlen :: non_neg_integer(), Passwd :: binary(), Salt :: binary(), Opslimit :: non_neg_integer(), Memlimit :: non_neg_integer(), Alg :: integer(), Result :: binary() | -1.
Derive an Outlen byte key from Passwd and the salt Salt (at least
saltbytes/0 bytes; only the first saltbytes/0 are used) with the
cost parameters Opslimit and Memlimit and the algorithm Alg
(alg_argon2i13/0, alg_argon2id13/0 or alg_default/0).
Returns -1 when libsodium rejects the parameters (for example an
Outlen below bytes_min/0, limits out of range, or an unknown Alg)
or cannot allocate the requested memory.
-spec memlimit_interactive() -> Result when Result :: 67108864.
Return crypto_pwhash_memlimit_interactive(), in bytes.
-spec memlimit_max() -> Result when Result :: non_neg_integer().
Return crypto_pwhash_memlimit_max(), in bytes.
-spec memlimit_min() -> Result when Result :: 8192.
Return crypto_pwhash_memlimit_min(), in bytes.
-spec memlimit_moderate() -> Result when Result :: 268435456.
Return crypto_pwhash_memlimit_moderate(), in bytes.
-spec memlimit_sensitive() -> Result when Result :: 1073741824.
Return crypto_pwhash_memlimit_sensitive(), in bytes.
-spec opslimit_interactive() -> Result when Result :: 2.
Return crypto_pwhash_opslimit_interactive(), in bytes.
-spec opslimit_max() -> Result when Result :: 4294967295.
Return crypto_pwhash_opslimit_max(), in bytes.
-spec opslimit_min() -> Result when Result :: 1.
Return crypto_pwhash_opslimit_min(), in bytes.
-spec opslimit_moderate() -> Result when Result :: 3.
Return crypto_pwhash_opslimit_moderate(), in bytes.
-spec opslimit_sensitive() -> Result when Result :: 4.
Return crypto_pwhash_opslimit_sensitive(), in bytes.
-spec passwd_max() -> Result when Result :: 4294967295.
Return crypto_pwhash_passwd_max(), in bytes.
-spec passwd_min() -> Result when Result :: 0.
Return crypto_pwhash_passwd_min(), in bytes.
-spec primitive() -> Result when Result :: binary().
Return the names of the supported primitives as a binary, such as <<"argon2id,argon2i">>.
-spec saltbytes() -> Result when Result :: 16.
Return crypto_pwhash_saltbytes(), in bytes.
-spec str(Passwd, Opslimit, Memlimit) -> Result when Passwd :: binary(), Opslimit :: non_neg_integer(), Memlimit :: non_neg_integer(), Result :: binary() | -1.
Hash Passwd for storage using the default algorithm with the cost
parameters Opslimit and Memlimit and a random salt.
Returns an ASCII binary of at most strbytes/0 - 1 bytes starting with
strprefix/0, or -1 on failure.
-spec str_alg(Passwd, Opslimit, Memlimit, Alg) -> Result when Passwd :: binary(), Opslimit :: non_neg_integer(), Memlimit :: non_neg_integer(), Alg :: integer(), Result :: binary() | -1.
Like str/3, but hash Passwd with the algorithm Alg
(alg_argon2i13/0 or alg_argon2id13/0). Returns -1 on failure.
-spec str_needs_rehash(Str, Opslimit, Memlimit) -> Result when Str :: binary(), Opslimit :: non_neg_integer(), Memlimit :: non_neg_integer(), Result :: -1 | 0 | 1.
Check whether Str (an Argon2i or Argon2id string) was hashed with
exactly the cost parameters Opslimit and Memlimit.
Returns 0 when it was, 1 when the password should be rehashed (after
a successful str_verify/2), and -1 when Str is malformed or the
parameters are invalid.
Check Passwd against Str, a string produced by str/3 or
str_alg/4 (Argon2i and Argon2id strings are both accepted).
Returns 0 when the password matches and -1 when it does not or
Str is malformed.
-spec strbytes() -> Result when Result :: 128.
Return crypto_pwhash_strbytes(), in bytes.
-spec strprefix() -> Result when Result :: binary().
Return crypto_pwhash_strprefix() as a binary.