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 a 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 that the function will use, in bytes. 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 base line 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.
memlimithave to be used. Therefore, these parameters have to 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, 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
strhas to 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 it 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, has to 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_*) in order to verify a password or produce a deterministic output. Save the parameters (including the algorithm identifier) along with the hash instead.
crypto_pwhash_str_verify(). The string produced by
crypto_pwhash_str()already includes an algorithm identifier, as well as all the parameters (including the automatically generated salt) that have been used to hash the password. Subsequently,
crypto_pwhash_str_verify()automatically decodes these parameters.
sodium_mlock()to lock memory regions storing cleartext 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).