NAME

crypto_argon2 — password-based key derivation

SYNOPSIS

#include <monocypher.h>

void
crypto_argon2(uint8_t *hash, uint32_t hash_size, void *work_area, crypto_argon2_config config, crypto_argon2_inputs inputs, crypto_argon2_extras extras);

extern const crypto_argon2_extras crypto_argon2_no_extras;

DESCRIPTION

Argon2 is a resource intensive password-based key derivation scheme optimised for the typical x86-like processor. It runs in constant time with respect to the contents of the password.

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_argon2() are:

hash: The output hash. If all parameters to crypto_argon2() 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.
hash_size: Length of hash, in bytes. This argument should be set to 32 or 64 for compatibility with the crypto_verify32(3monocypher) or crypto_verify64(3monocypher) constant time comparison functions.
work_area: Temporary buffer for the algorithm, allocated by the caller. It must be config.nb_blocks × 1024 bytes big and suitably aligned for 64-bit integers. If you are not sure how to allocate that buffer, just use malloc(3).
The work area is automatically wiped by crypto_argon2().
config: A struct of type crypto_argon2_config that determines the base parameters of this particular instance of Argon2. These are domain parameters and remain constant between multiple invocations of crypto_argon2().
inputs: A struct of type crypto_argon2_inputs that contains the actual input parameters.
extras: A struct of type crypto_argon2_extras that contains optional extra input parameters, which are not commonly used.

The crypto_argon2_config struct is defined as follows:

typedef struct {
    uint32_t algorithm;
    uint32_t nb_blocks;
    uint32_t nb_passes;
    uint32_t nb_lanes;
} crypto_argon2_config;

Its members are:

algorithm: This value determines which variant of Argon2 should be used. CRYPTO_ARGON2_D indicates Argon2d, CRYPTO_ARGON2_I indicates Argon2i, CRYPTO_ARGON2_ID indicates Argon2id.
nb_blocks: The number of blocks for the work area. Must be at least 8 × nb_lanes. A value of 100000 (one hundred megabytes) is a good starting point. If the computation takes too long, reduce this number. If it is too fast, increase it. If it is still too fast with all available memory, increase nb_passes.
nb_passes: The number of passes. Must be at least 1. A value of 3 is strongly recommended when using Argon2i; any value lower than 3 enables significantly more efficient attacks.
nb_lanes: The level of parallelism. Must be at least 1. Since Monocypher does not support threads, this does not actually increase the number of threads. It is only provided for completeness to match the Argon2 specification. Otherwise, leaving it to 1 is strongly recommended.
Users who want to take actual advantage of parallelism should instead call several instances of Argon2 in parallel. The extras parameter may be used to differentiate the inputs and produce independent digests that can be hashed together.

The crypto_argon2_inputs struct is defined as follows:

typedef struct {
    const uint8_t *pass;
    const uint8_t *salt;
    uint32_t pass_size;
    uint32_t salt_size;
} crypto_argon2_inputs;

Its members are:

pass: The password to hash. It should be wiped with crypto_wipe(3monocypher) after being hashed.
pass_size: Length of pass, in bytes.
salt: A password salt. This should be filled with random bytes, generated separately for each password to be hashed. See intro(3monocypher) for advice about generating random bytes (use the operating system's random number generator).
salt_size: Length of salt, in bytes. Must be at least 8. 16 is recommended.

The crypto_argon2_extras struct is defined as follows:

typedef struct {
    const uint8_t *key;
    const uint8_t *ad;
    uint32_t key_size;
    uint32_t ad_size;
} crypto_argon2_extras;

Its members are:

key: A key to use in the hash. May be 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 in.
key_size: Length of key, in bytes. Must be zero if there is no key.
ad: Additional data. May be NULL if ad_size is zero. This is additional data that goes into the hash, similar to the authenticated encryption construction in crypto_aead_lock(3monocypher). Can be used to differentiate inputs when invoking several Argon2 instances in parallel: each instance gets a different thread number as additional data, generating as many independent digests as we need. We can then hash those digests with crypto_blake2b(3monocypher).
ad_size: Length of ad, in bytes. Must be zero if there is no additional data.

The arguments in the config and extras structs 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_passes 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. Argon2i with three iterations and 100000 blocks (one hundred megabytes of memory) is a good starting point. So is Argon2id with one iteration and 300000 blocks. Adjust nb_blocks first. If using all available memory is not slow enough, increase nb_passes.

RETURN VALUES

crypto_argon2() returns nothing.

EXAMPLES

The following example assumes the existence of 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     */
uint8_t              salt[16];               /* Random salt     */
crypto_argon2_config config = {
    .algorithm = CRYPTO_ARGON2_I,            /* Argon2i         */
    .nb_blocks = 100000,                     /* 100 megabytes   */
    .nb_passes = 3,                          /* 3 iterations    */
    .nb_lanes  = 1                           /* Single-threaded */
};
uint8_t password[14] = "Okay Password!";
crypto_argon2_inputs inputs = {
    .pass      = password,                     /* User password */
    .pass_size = sizeof(password),           /* Password length */
    .salt      = salt,                 /* Salt for the password */
    .salt_size = 16
};
crypto_argon2_extras extras = {0};   /* Extra parameters unused */

/* Allocate work area.
 * Note the conversion to size_t.
 * Without it we cannot allocate more than 4GiB.
 */
void *work_area = malloc((size_t)config.nb_blocks * 1024);
if (work_area == NULL) {
    /* Handle malloc() failure */
    /* Wipe secrets if they are no longer needed */
    crypto_wipe(password, sizeof(password));
} else {
    arc4random_buf(salt, 16);
    crypto_argon2(hash, 32, work_area,
                  config, inputs, extras);
    /* Wipe secrets if they are no longer needed */
    crypto_wipe(password, sizeof(password));
    free(work_area);
}

STANDARDS

crypto_argon2() implements Argon2 as described in RFC 9106, but does not support actual parallelism.

HISTORY

In Monocypher 0.1, crypto_argon2i() implemented Argon2i and had all extra parameters as input. It was then split into a crypto_argon2i_general() and a simplified crypto_argon2i() function in Monocypher 1.1.0. Both were replaced by crypto_argon2() in Monocypher 4.0.0.

CAVEATS

Monocypher does not perform any input validation. Any deviation from the algorithm constants, specified input and output length ranges results in undefined behaviour. Make sure your inputs are correct.