crypto_pwhash()function derives an
outlenbytes long key from a password
passwdwhose length is
passwdlenand a salt
saltwhose fixed length is
passwdlenshould be at least
outlenshould be at least
16(128 bits) and at most
out, representing the address of a dedicated storage area of
opslimitrepresents 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
memlimitis the maximum amount of RAM in bytes that the function will use. This number must be between
algis 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_MEMLIMIT_INTERACTIVEprovide a baseline for these two parameters. This currently requires 64 MiB of dedicated RAM. Higher values may improve security (see below).
crypto_pwhash_MEMLIMIT_MODERATEcan 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_MEMLIMIT_SENSITIVEcan 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.
saltshould be unpredictable.
randombytes_buf()is the easiest way to fill the
crypto_pwhash_SALTBYTESbytes of the salt.
memlimitmust be used. Therefore, these parameters must be stored for each user.
0on success and
-1if 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:
outmust be a dedicated storage area that's large enough to hold
crypto_pwhash_STRBYTESbytes, but the actual output string may be shorter.
0on success and
-1if it didn't complete successfully.
stris a valid password verification string (as generated by
passwdwhose length is
strmust be zero-terminated.
0if the verification succeeds and
strmatches the parameters
memlimit, and the current default algorithm.
1if 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.
0if the parameters already match the given ones.
-1on error. If this happens, applications may want to compute a correct hash the next time the user logs in.
memlimitto the amount of memory you want to reserve for password hashing.
3and measure the time it takes to hash a password.
memlimit, but keep
opslimit, the number of passes, must be at least
3when using Argon2i.
crypto_pwhash_str()will fail with a
-1return code for lower values.
memlimit, though the more memory, the better.
crypto_pwhash_*will still work without doing so but possibly way slower.
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_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 parameters
sodium_mlock()to lock memory regions storing plaintext passwords and to call
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.