libsodium_crypto_pwhash_argon2i (libsodium v3.0.1)
View SourcePassword hashing and password-based key derivation with Argon2i version
1.3, the data-independent Argon2 variant. New applications should prefer
Argon2id through libsodium_crypto_pwhash; this module remains for
verifying and deriving keys from existing Argon2i parameters.
str/3 produces a self-describing string to store and check with
str_verify/2; crypto_pwhash_argon2i/6 derives a key from a password and
a saltbytes/0 byte salt. Argon2i requires an Opslimit of at least
opslimit_min/0 (3). Raise Opslimit and Memlimit (memory in bytes) as
far as your latency budget allows. All hashing runs on a dirty CPU
scheduler.
Ops = libsodium_crypto_pwhash_argon2i:opslimit_interactive(),
Mem = libsodium_crypto_pwhash_argon2i:memlimit_interactive(),
Str = libsodium_crypto_pwhash_argon2i:str(<<"correct horse">>, Ops, Mem),
0 = libsodium_crypto_pwhash_argon2i:str_verify(Str, <<"correct horse">>),
-1 = libsodium_crypto_pwhash_argon2i:str_verify(Str, <<"wrong horse">>),
0 = libsodium_crypto_pwhash_argon2i:str_needs_rehash(Str, Ops, Mem).Summary
Functions
Return the algorithm identifier for Argon2i version 1.3, the only Alg accepted by crypto_pwhash_argon2i/6.
Return crypto_pwhash_argon2i_bytes_max(), in bytes.
Return crypto_pwhash_argon2i_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_argon2i13/0.
Return crypto_pwhash_argon2i_memlimit_interactive(), in bytes.
Return crypto_pwhash_argon2i_memlimit_max(), in bytes.
Return crypto_pwhash_argon2i_memlimit_min(), in bytes.
Return crypto_pwhash_argon2i_memlimit_moderate(), in bytes.
Return crypto_pwhash_argon2i_memlimit_sensitive(), in bytes.
Return crypto_pwhash_argon2i_opslimit_interactive(), in bytes.
Return crypto_pwhash_argon2i_opslimit_max(), in bytes.
Return crypto_pwhash_argon2i_opslimit_min(), in bytes.
Return crypto_pwhash_argon2i_opslimit_moderate(), in bytes.
Return crypto_pwhash_argon2i_opslimit_sensitive(), in bytes.
Return crypto_pwhash_argon2i_passwd_max(), in bytes.
Return crypto_pwhash_argon2i_passwd_min(), in bytes.
Return crypto_pwhash_argon2i_saltbytes(), in bytes.
Hash Passwd for storage with the cost parameters Opslimit and
Memlimit and a random salt.
Check whether Str was hashed with Argon2i and exactly the cost
parameters Opslimit and Memlimit.
Check Passwd against Str, an Argon2i string produced by str/3.
Return crypto_pwhash_argon2i_strbytes(), in bytes.
Return crypto_pwhash_argon2i_strprefix() as a binary.
Functions
-spec alg_argon2i13() -> Result when Result :: 1.
Return the algorithm identifier for Argon2i version 1.3, the only Alg accepted by crypto_pwhash_argon2i/6.
-spec bytes_max() -> Result when Result :: 4294967295.
Return crypto_pwhash_argon2i_bytes_max(), in bytes.
-spec bytes_min() -> Result when Result :: 16.
Return crypto_pwhash_argon2i_bytes_min(), in bytes.
-spec crypto_pwhash_argon2i(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_argon2i13/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 :: 33554432.
Return crypto_pwhash_argon2i_memlimit_interactive(), in bytes.
-spec memlimit_max() -> Result when Result :: non_neg_integer().
Return crypto_pwhash_argon2i_memlimit_max(), in bytes.
-spec memlimit_min() -> Result when Result :: 8192.
Return crypto_pwhash_argon2i_memlimit_min(), in bytes.
-spec memlimit_moderate() -> Result when Result :: 134217728.
Return crypto_pwhash_argon2i_memlimit_moderate(), in bytes.
-spec memlimit_sensitive() -> Result when Result :: 536870912.
Return crypto_pwhash_argon2i_memlimit_sensitive(), in bytes.
-spec opslimit_interactive() -> Result when Result :: 4.
Return crypto_pwhash_argon2i_opslimit_interactive(), in bytes.
-spec opslimit_max() -> Result when Result :: 4294967295.
Return crypto_pwhash_argon2i_opslimit_max(), in bytes.
-spec opslimit_min() -> Result when Result :: 3.
Return crypto_pwhash_argon2i_opslimit_min(), in bytes.
-spec opslimit_moderate() -> Result when Result :: 6.
Return crypto_pwhash_argon2i_opslimit_moderate(), in bytes.
-spec opslimit_sensitive() -> Result when Result :: 8.
Return crypto_pwhash_argon2i_opslimit_sensitive(), in bytes.
-spec passwd_max() -> Result when Result :: 4294967295.
Return crypto_pwhash_argon2i_passwd_max(), in bytes.
-spec passwd_min() -> Result when Result :: 0.
Return crypto_pwhash_argon2i_passwd_min(), in bytes.
-spec saltbytes() -> Result when Result :: 16.
Return crypto_pwhash_argon2i_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 Argon2i 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 Argon2i 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_argon2i_strbytes(), in bytes.
-spec strprefix() -> Result when Result :: binary().
Return crypto_pwhash_argon2i_strprefix() as a binary.