CRYPTO_ARGON2I(3MONOCYPHER) | 3MONOCYPHER | CRYPTO_ARGON2I(3MONOCYPHER) |
crypto_argon2i
—
#include <monocypher.h>
void
crypto_argon2i
(uint8_t *hash,
uint32_t hash_size, void
*work_area, uint32_t nb_blocks,
uint32_t nb_iterations, const uint8_t
*password, uint32_t password_size,
const uint8_t *salt, uint32_t
salt_size);
void
crypto_argon2i_general
(uint8_t
*hash, uint32_t hash_size, void
*work_area, uint32_t nb_blocks,
uint32_t nb_iterations, const uint8_t
*password, uint32_t password_size,
const uint8_t *salt, uint32_t
salt_size, const uint8_t *key,
uint32_t key_size, const uint8_t
*ad, uint32_t ad_size);
Typical applications are password checking (for online services) and key derivation (for encryption). Derived keys can be used to encrypt, for example, private keys or password databases.
The version provided by Monocypher has no threading support, so the degree of parallelism is limited to 1. This is considered good enough for most purposes.
The arguments to crypto_argon2i
() are:
crypto_argon2i
() or
crypto_argon2i_general
() are identical between two
calls, then the output hash is also identical. In
other words, all input parameters passed to the function influence the
output value.crypto_verify*
() constant time comparison
functions.malloc
().
The work area is automatically wiped by
crypto_argon2i
().
The arguments may overlap or point at the same buffer.
Use crypto_verify16(3monocypher), crypto_verify32(3monocypher), or crypto_verify64(3monocypher) to compare password hashes to prevent timing attacks.
To select the nb_blocks and nb_iterations parameters, it should first be decided how long the computation should take. For user authentication, values somewhere between half a second (convenient) and several seconds (paranoid) are recommended. The computation should use as much memory as can be spared.
Since parameter selection depends on your hardware, some trial and error will be required in order to determine the ideal settings. Three iterations and 100000 blocks (one hundred megabytes of memory) is a good starting point. Adjust nb_blocks first. If using all available memory is not slow enough, increase nb_iterations.
crypto_argon2i_general
() is a variant of
crypto_argon2i
() that supports keyed hashing and
hashing of additional data. The additional arguments are:
NULL
if
key_size is zero. The key is generally not needed,
but it does have some uses. In the context of password derivation, it
would be stored separately from the password database and would remain
secret even if an attacker were to steal the database. Note that changing
the key requires rehashing the user's password, which can only be done
when the user logs inNULL
if
ad_size is zero.arc4random_buf
(), which fills the given buffer with
cryptographically secure random bytes. If
arc4random_buf
() does not exist on your system, see
intro(3monocypher) for advice about how to
generate cryptographically secure random bytes.
This example shows how to hash a password with the recommended baseline parameters:
uint8_t hash[32]; /* Output hash */ char *password = "Okay Password!"; /* User's password */ uint32_t password_size = 14; /* Password length */ uint8_t salt[16]; /* Random salt */ const uint32_t nb_blocks = 100000; /* 100 megabytes */ const uint32_t nb_iterations = 3; /* 3 iterations */ void *work_area = malloc(nb_blocks * 1024); /* Work area */ if (work_area == NULL) { /* Handle malloc() failure */ /* Wipe secrets if they are no longer needed */ crypto_wipe(password, password_size); } else { arc4random_buf(salt, 16); crypto_argon2i(hash, 32, work_area, nb_blocks, nb_iterations, (uint8_t *)password, password_size, salt, 16); /* Wipe secrets if they are no longer needed */ crypto_wipe(password, password_size); free(work_area); }
crypto_argon2i_general
() function first appeared in
Monocypher 0.1 but was called crypto_argon2i
(); it was
renamed to its current name in Monocypher 1.1.0. The current
crypto_argon2i
() first appeared in Monocypher 1.1.0.
September 9, 2021 | Debian |