crypto_pwhash()
function derives an outlen
bytes long key from a password passwd
whose length is passwdlen
and a salt salt
whose fixed length is crypto_pwhash_SALTBYTES
bytes. passwdlen
should be at least crypto_pwhash_PASSWD_MIN
and crypto_pwhash_PASSWD_MAX
. outlen
should be at least crypto_pwhash_BYTES_MIN
= 16
(128 bits) and at most crypto_pwhash_BYTES_MAX
.out
, representing the address of a dedicated storage area of outlen
bytes.opslimit
represents the maximum amount of computations to perform. Raising this number will make the function require more CPU cycles to compute a key. This number must be between crypto_pwhash_OPSLIMIT_MIN
and crypto_pwhash_OPSLIMIT_MAX
.memlimit
is the maximum amount of RAM in bytes that the function will use. This number must be between crypto_pwhash_MEMLIMIT_MIN
and crypto_pwhash_MEMLIMIT_MAX
.alg
is an identifier for the algorithm to use and should be set to one of the following values:crypto_pwhash_ALG_DEFAULT
: the currently recommended algorithm, which can change from one version of libsodium to another.crypto_pwhash_ALG_ARGON2I13
: version 1.3 of the Argon2i algorithm.crypto_pwhash_ALG_ARGON2ID13
: version 1.3 of the Argon2id algorithm, available since libsodium 1.0.13.crypto_pwhash_OPSLIMIT_INTERACTIVE
and crypto_pwhash_MEMLIMIT_INTERACTIVE
provide a baseline for these two parameters. This currently requires 64 MiB of dedicated RAM. Higher values may improve security (see below).crypto_pwhash_OPSLIMIT_MODERATE
and crypto_pwhash_MEMLIMIT_MODERATE
can be used. This requires 256 MiB of dedicated RAM and takes about 0.7 seconds on a 2.8 GHz Core i7 CPU.crypto_pwhash_OPSLIMIT_SENSITIVE
and crypto_pwhash_MEMLIMIT_SENSITIVE
can be used. With these parameters, deriving a key takes about 3.5 seconds on a 2.8 GHz Core i7 CPU and requires 1024 MiB of dedicated RAM.salt
should be unpredictable. randombytes_buf()
is the easiest way to fill the crypto_pwhash_SALTBYTES
bytes of the salt.opslimit
and memlimit
must be used. Therefore, these parameters must be stored for each user.0
on success and -1
if the computation didn't complete, usually because the operating system refused to allocate the amount of requested memory.crypto_pwhash_str()
function puts an ASCII encoded string into out
, which includes:passwd
of length passwdlen
;opslimit
, and memlimit
.out
must be a dedicated storage area that's large enough to hold crypto_pwhash_STRBYTES
bytes, but the actual output string may be shorter.0
on success and -1
if it didn't complete successfully.str
is a valid password verification string (as generated by crypto_pwhash_str()
) for passwd
whose length is passwdlen
.str
must be zero-terminated.0
if the verification succeeds and -1
on error.str
matches the parameters opslimit
, memlimit
, and the current default algorithm.1
if the string appears to be correct but doesn't match the given parameters. In that situation, applications may want to compute a new hash using the current parameters the next time the user logs in.0
if the parameters already match the given ones.-1
on error. If this happens, applications may want to compute a correct hash the next time the user logs in.memlimit
to the amount of memory you want to reserve for password hashing.opslimit
to 3
and measure the time it takes to hash a password.memlimit
, but keep opslimit
set to 3
.opslimit
.crypto_pwhash_ALG_ARGON2I13
crypto_pwhash_ALG_ARGON2ID13
crypto_pwhash_ALG_DEFAULT
crypto_pwhash_BYTES_MAX
crypto_pwhash_BYTES_MIN
crypto_pwhash_MEMLIMIT_INTERACTIVE
crypto_pwhash_MEMLIMIT_MAX
crypto_pwhash_MEMLIMIT_MIN
crypto_pwhash_MEMLIMIT_MODERATE
crypto_pwhash_MEMLIMIT_SENSITIVE
crypto_pwhash_OPSLIMIT_INTERACTIVE
crypto_pwhash_OPSLIMIT_MAX
crypto_pwhash_OPSLIMIT_MIN
crypto_pwhash_OPSLIMIT_MODERATE
crypto_pwhash_OPSLIMIT_SENSITIVE
crypto_pwhash_PASSWD_MAX
crypto_pwhash_PASSWD_MIN
crypto_pwhash_SALTBYTES
crypto_pwhash_STRBYTES
crypto_pwhash_STRPREFIX
opslimit
, the number of passes, must be at least 3
when using Argon2i.crypto_pwhash()
and crypto_pwhash_str()
will fail with a -1
return code for lower values.memlimit
, though the more memory, the better.sodium_init()
. crypto_pwhash_*
will still work without doing so but possibly way slower.crypto_pwhash_OPSLIMIT_*
and crypto_pwhash_MEMLIMIT_*
) to verify a password or produce a deterministic output. Save the parameters, including the algorithm identifier, alongside the hash instead.crypto_pwhash_str()
and crypto_pwhash_str_verify()
. The string produced by crypto_pwhash_str()
already includes an algorithm identifier and all the parameters, including the automatically generated salt, that were used to hash the password. Subsequently, crypto_pwhash_str_verify()
automatically decodes these parameterssodium_mlock()
to lock memory regions storing plaintext passwords and to call sodium_munlock()
right after crypto_pwhash_str()
and crypto_pwhash_str_verify()
return.sodium_munlock()
overwrites the region with zeros before unlocking it, so it must not be done before calling this function; otherwise, zeroes, instead of the password, would be hashed.