libsodium_crypto_pwhash_argon2id (libsodium v3.0.1)
View SourcePassword hashing and password-based key derivation with Argon2id version
1.3, the hybrid Argon2 variant that resists both side-channel and GPU
attacks. This is the current default of libsodium_crypto_pwhash, which
should be preferred unless Argon2id must be selected explicitly.
str/3 produces a self-describing string to store and check with
str_verify/2; crypto_pwhash_argon2id/6 derives a key from a password
and a saltbytes/0 byte salt. Raise Opslimit (CPU cost) and Memlimit
(memory in bytes) as far as your latency budget allows, starting from the
_interactive limits for online logins. All hashing runs on a dirty CPU
scheduler.
Ops = libsodium_crypto_pwhash_argon2id:opslimit_interactive(),
Mem = libsodium_crypto_pwhash_argon2id:memlimit_interactive(),
Str = libsodium_crypto_pwhash_argon2id:str(<<"correct horse">>, Ops, Mem),
0 = libsodium_crypto_pwhash_argon2id:str_verify(Str, <<"correct horse">>),
-1 = libsodium_crypto_pwhash_argon2id:str_verify(Str, <<"wrong horse">>),
0 = libsodium_crypto_pwhash_argon2id:str_needs_rehash(Str, Ops, Mem).Summary
Functions
Return the algorithm identifier for Argon2id version 1.3, the only Alg accepted by crypto_pwhash_argon2id/6.
Return crypto_pwhash_argon2id_bytes_max(), in bytes.
Return crypto_pwhash_argon2id_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. Alg must be
alg_argon2id13/0.
Return crypto_pwhash_argon2id_memlimit_interactive(), in bytes.
Return crypto_pwhash_argon2id_memlimit_max(), in bytes.
Return crypto_pwhash_argon2id_memlimit_min(), in bytes.
Return crypto_pwhash_argon2id_memlimit_moderate(), in bytes.
Return crypto_pwhash_argon2id_memlimit_sensitive(), in bytes.
Return crypto_pwhash_argon2id_opslimit_interactive(), in bytes.
Return crypto_pwhash_argon2id_opslimit_max(), in bytes.
Return crypto_pwhash_argon2id_opslimit_min(), in bytes.
Return crypto_pwhash_argon2id_opslimit_moderate(), in bytes.
Return crypto_pwhash_argon2id_opslimit_sensitive(), in bytes.
Return crypto_pwhash_argon2id_passwd_max(), in bytes.
Return crypto_pwhash_argon2id_passwd_min(), in bytes.
Return crypto_pwhash_argon2id_saltbytes(), in bytes.
Hash Passwd for storage with the cost parameters Opslimit and
Memlimit and a random salt.
Check whether Str was hashed with Argon2id and exactly the cost
parameters Opslimit and Memlimit.
Check Passwd against Str, an Argon2id string produced by str/3.
Return crypto_pwhash_argon2id_strbytes(), in bytes.
Return crypto_pwhash_argon2id_strprefix() as a binary.
Functions
-spec alg_argon2id13() -> Result when Result :: 2.
Return the algorithm identifier for Argon2id version 1.3, the only Alg accepted by crypto_pwhash_argon2id/6.
-spec bytes_max() -> Result when Result :: 4294967295.
Return crypto_pwhash_argon2id_bytes_max(), in bytes.
-spec bytes_min() -> Result when Result :: 16.
Return crypto_pwhash_argon2id_bytes_min(), in bytes.
-spec crypto_pwhash_argon2id(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. Alg must be
alg_argon2id13/0.
Returns -1 when libsodium rejects the parameters (for example an
Outlen below bytes_min/0, limits out of range, or another Alg)
or cannot allocate the requested memory.
-spec memlimit_interactive() -> Result when Result :: 67108864.
Return crypto_pwhash_argon2id_memlimit_interactive(), in bytes.
-spec memlimit_max() -> Result when Result :: non_neg_integer().
Return crypto_pwhash_argon2id_memlimit_max(), in bytes.
-spec memlimit_min() -> Result when Result :: 8192.
Return crypto_pwhash_argon2id_memlimit_min(), in bytes.
-spec memlimit_moderate() -> Result when Result :: 268435456.
Return crypto_pwhash_argon2id_memlimit_moderate(), in bytes.
-spec memlimit_sensitive() -> Result when Result :: 1073741824.
Return crypto_pwhash_argon2id_memlimit_sensitive(), in bytes.
-spec opslimit_interactive() -> Result when Result :: 2.
Return crypto_pwhash_argon2id_opslimit_interactive(), in bytes.
-spec opslimit_max() -> Result when Result :: 4294967295.
Return crypto_pwhash_argon2id_opslimit_max(), in bytes.
-spec opslimit_min() -> Result when Result :: 1.
Return crypto_pwhash_argon2id_opslimit_min(), in bytes.
-spec opslimit_moderate() -> Result when Result :: 3.
Return crypto_pwhash_argon2id_opslimit_moderate(), in bytes.
-spec opslimit_sensitive() -> Result when Result :: 4.
Return crypto_pwhash_argon2id_opslimit_sensitive(), in bytes.
-spec passwd_max() -> Result when Result :: 4294967295.
Return crypto_pwhash_argon2id_passwd_max(), in bytes.
-spec passwd_min() -> Result when Result :: 0.
Return crypto_pwhash_argon2id_passwd_min(), in bytes.
-spec saltbytes() -> Result when Result :: 16.
Return crypto_pwhash_argon2id_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 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_needs_rehash(Str, Opslimit, Memlimit) -> Result when Str :: binary(), Opslimit :: non_neg_integer(), Memlimit :: non_neg_integer(), Result :: -1 | 0 | 1.
Check whether Str was hashed with Argon2id and 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, an Argon2id string produced by str/3.
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_argon2id_strbytes(), in bytes.
-spec strprefix() -> Result when Result :: binary().
Return crypto_pwhash_argon2id_strprefix() as a binary.