1
mirror of https://github.com/jedisct1/libsodium.git synced 2024-12-28 22:21:15 -07:00

Add preliminary documentation on scrypt

This commit is contained in:
Frank Denis 2014-05-08 12:32:49 -07:00
parent fda08703fc
commit d183c89490

View File

@ -255,6 +255,67 @@ This hash function provides:
`crypto_generichash` is currently being implemented using
[Blake2](https://blake2.net/).
## crypto_pwhash
High-level functions for password hashing are not defined yet: they will
eventually be wrappers for the winning function of the ongoing
[Password Hashing Competition](https://password-hashing.net/).
Meanwhile, the [scrypt](http://www.tarsnap.com/scrypt.html) function is
available through explicitly-named functions, and will remain available
in the library even after the PHC.
int crypto_pwhash_scryptxsalsa208sha256(unsigned char *out,
unsigned long long outlen,
const char *passwd,
unsigned long long passwdlen,
const unsigned char *salt,
size_t memlimit,
unsigned long long opslimit);
This function derives `outlen` bytes from a password `passwd` and a
salt `salt` that has to be `crypto_pwhash_scryptxsalsa208sha256_SALTBYTES`
bytes long.
The function will use at most `memlimit` bytes of memory and `opslimit`
is the maximum number of iterations to perform. Making the function
memory-hard and CPU intensive by increasing these parameters might increase
security.
Although password storage was not the primary goal of the scrypt
function, it can still be used for this purpose:
int crypto_pwhash_scryptxsalsa208sha256_str
(char out[crypto_pwhash_scryptxsalsa208sha256_STRBYTES],
const char *passwd,
unsigned long long passwdlen,
size_t memlimit,
unsigned long long opslimit);
This function returns a `crypto_pwhash_scryptxsalsa208sha256_STRBYTES`
bytes C string (the length includes the final `\0`) suitable for storage.
The string is guaranteed to only include ASCII characters.
The function will use at most `memlimit` bytes of memory and `opslimit`
is the maximum number of iterations to perform. These parameters are
included in the output string, and do not need to be stored separately.
The function automatically generates a random salt, which is also
included in the output string.
int crypto_pwhash_scryptxsalsa208sha256_str_verify
(const char str[crypto_pwhash_scryptxsalsa208sha256_STRBYTES],
const char *passwd,
unsigned long long passwdlen);
This function verifies that hashing the plaintext password `passwd`
results in the stored hash value included in `str` when using the same
parameters.
`0` is returned if the passwords are matching, `-1` is they are not.
The plaintext password should be immediately zeroed out from memory
after this function returns, using `sodium_memzero()`.
## Constants available as functions
In addition to constants for key sizes, output sizes and block sizes,