CRYPTO_ARGON2I(3MONOCYPHER)

💖 CRYPTO_ARGON2I 💖

okay bestie, settle in, because this is the 3monocypher page for crypto_argon2i and it's literally the password-hashing baddie of your dreams ✨ (it lives in the LOCAL section of the manual, iykyk)

---

✨ NAME ✨

crypto_argon2i — password key derivation 🎀

---

🌸 SYNOPSIS 🌸

#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);

---

🦋 DESCRIPTION 🦋

Argon2i is a resource intensive password key derivation scheme, optimised for your typical x86-like processor. It runs in constant time with respect to the contents of the password. no leaking, periodt 💅

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. iconic behaviour honestly.

The version Monocypher gives you has no threading support, so the degree of parallelism is limited to 1. That's considered good enough for most purposes, fr fr.

---

🎀 the arguments to crypto_argon2i() 🎀

• hash — the output hash. The way this works: if all parameters to crypto_argon2i() or crypto_argon2i_general() are identical between two calls, then the output hash is also identical. In other words, every single input parameter passed to the function influences the output value. no sneaky hidden inputs, we love consistency ✨
• hash_size — length of hash, in bytes. You should set this to 32 or 64 for compatibility with the crypto_verify*() constant time comparison functions.
• work_area — temporary buffer for the algorithm, allocated by the caller. It must be nb_blocks × 1024 bytes big, and suitably aligned for 64-bit integers. If you're not sure how to allocate that buffer, just use malloc(). It's giving "trust the process".

The work area is automatically wiped by crypto_argon2i(). we love a self-cleaning queen 🧚

• nb_blocks — the number of blocks for the work area. Must be at least 8. A value of 100000 (one hundred megabytes) is a good starting point. If the computation takes too long, reduce this number. If it's too fast, increase this number. If it's still too fast with all available memory, increase nb_iterations. tuning era 💅
• nb_iterations — the number of iterations. It must be at least 1. A value of 3 is strongly recommended; any value lower than 3 enables significantly more efficient attacks. so like, don't. just don't 🙈
• password — the password to hash. It should be wiped with crypto_wipe(3monocypher) after being hashed.
• password_size — length of password, 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). every password gets its own, no sharing 🍓
• salt_size — length of salt, in bytes. Must be at least 8. 16 is recommended.

The arguments may overlap or point at the same buffer. go off, memory layout 💜

---

Use crypto_verify16(3monocypher), crypto_verify32(3monocypher) or crypto_verify64(3monocypher) to compare password hashes to prevent timing attacks. seriously, this one matters.

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 (that is, 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. basically: dial it in, bestie 📈

---

🌈 crypto_argon2i_general() — the deluxe version 🌈

crypto_argon2i_general() is a variant of crypto_argon2i() that supports keyed hashing and hashing of additional data. The additional arguments are:

• key — a key to use in the hash. Can 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 is only possible upon user login. plot twist 😭
• key_size — length of key, in bytes. Must be zero if there is no key.
• ad — additional data. This is additional data that goes into the hash, similar to the authenticated encryption with authenticated data (AEAD) construction in crypto_lock_aead(3monocypher). This most likely has no practical application but is exposed for the sake of completeness. This parameter may be NULL if ad_size is zero.
• ad_size — length of ad, in bytes. Must be zero if there is no additional data.

---

⭐ RETURN VALUES ⭐

These functions return nothing. that's it, that's the section 💀

---

🎀 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     */
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);
}

---

👑 SEE ALSO 👑

crypto_lock(3monocypher), crypto_verify16(3monocypher), crypto_wipe(3monocypher), intro(3monocypher)

---

💜 STANDARDS 💜

These functions implement Argon2i. An RFC draft is being maintained.

---

🧚 HISTORY 🧚

The 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. glow-up confirmed ✨

---

🔥 CAVEATS 🔥

Any deviation from the specified input and output length ranges results in undefined behaviour. Make sure your inputs are correct. no cap, check your sizes before you ship 🙈

---

and that's the whole page, bestie 🫶 — this manual page came out of the Debian crew on September 26, 2020, filed under CRYPTO_ARGON2I(3MONOCYPHER). go hash something responsibly 💅💖