Argon2 Reference Implementation

The low-level API uses an argon2_context structure to provide fine-grained control over the hashing process. This allows for advanced features like keyed hashing and secure memory erasure.

Key Features:

• secret parameter: Used for keyed hashing (HMAC-like). Provides a secret key to be folded into the hash.
• ad (associated data) parameter: Folds additional data into the hash value.
• flags parameter: Controls secure memory erasure. Use ARGON2_FLAG_CLEAR_PASSWORD or ARGON2_FLAG_CLEAR_SECRET to wipe sensitive buffers after use.

Implementation Pattern:

1. Initialize an argon2_context struct.
2. Call the variant-specific context function (e.g., argon2i_ctx(&context)).
3. Check the return code against ARGON2_OK.

Example:

argon2_context context = {
    hash2,  /* output array */
    HASHLEN, /* digest length */
    pwd, /* password array */
    pwdlen, /* password length */
    salt,  /* salt array */
    SALTLEN, /* salt length */
    NULL, 0, /* optional secret data */
    NULL, 0, /* optional associated data */
    t_cost, m_cost, parallelism, parallelism,
    ARGON2_VERSION_13, /* algorithm version */
    NULL, NULL, /* custom memory functions */
    ARGON2_DEFAULT_FLAGS
};

int rc = argon2i_ctx(&context);

#include "argon2.h"
#include <stdio.h>
#include <string.h>
#include <stdlib.h>

#define HASHLEN 32
#define SALTLEN 16
#define PWD "password"

int main(void)
{
    uint8_t hash1[HASHLEN];
    uint8_t hash2[HASHLEN];

    uint8_t salt[SALTLEN];
    memset( salt, 0x00, SALTLEN );

    uint8_t *pwd = (uint8_t *)strdup(PWD);
    uint32_t pwdlen = strlen((char *)pwd);

    uint32_t t_cost = 2;            // 2-pass computation
    uint32_t m_cost = (1<<16);      // 64 mebibytes memory usage
    uint32_t parallelism = 1;       // number of threads and lanes

    // high-level API
    argon2i_hash_raw(t_cost, m_cost, parallelism, pwd, pwdlen, salt, SALTLEN, hash1, HASHLEN);

    // low-level API
    argon2_context context = {
        hash2,  /* output array, at least HASHLEN in size */
        HASHLEN, /* digest length */
        pwd, /* password array */
        pwdlen, /* password length */
        salt,  /* salt array */
        SALTLEN, /* salt length */
        NULL, 0, /* optional secret data */
        NULL, 0, /* optional associated data */
        t_cost, m_cost, parallelism, parallelism,
        ARGON2_VERSION_13, /* algorithm version */
        NULL, NULL, /* custom memory allocation / deallocation functions */
        /* by default only internal memory is cleared (pwd is not wiped) */
        ARGON2_DEFAULT_FLAGS
    };

    int rc = argon2i_ctx( &context );
    if(ARGON2_OK != rc) {
        printf("Error: %s\n", argon2_error_message(rc));
        exit(1);
    }
    free(pwd);

    for( int i=0; i<HASHLEN; ++i ) printf( "%02x", hash1[i] ); printf( "\n" );
    if (memcmp(hash1, hash2, HASHLEN)) {
        for( int i=0; i<HASHLEN; ++i ) {
            printf( "%02x", hash2[i] );
        }
        printf( "\nfail\n" );
    }
    else printf( "ok\n" );
    return 0;
}

The argon2 CLI tool allows you to test specific Argon2 instances. The password is read from stdin.

Usage: ./argon2 [-h] salt [-i|-d|-id] [-t iterations] [-m memory] [-p parallelism] [-l hash length] [-e|-r] [-v (10|13)]

Parameters:

• salt: The salt to use (at least 8 characters).
• -i: Use Argon2i (default).
• -d: Use Argon2d.
• -id: Use Argon2id.
• -t N: Sets iterations to N (default 3).
• -m N: Sets memory usage to $2^N$ KiB (default 12).
• -p N: Sets parallelism to N threads (default 1).
• -l N: Sets hash output length to N bytes (default 32).
• -e: Output only encoded hash.
• -r: Output only the raw bytes of the hash.
• -v (10|13): Argon2 version (defaults to 13).
• -h: Print usage.

Example: To hash "password" using "somesalt" with 2 iterations, 64 MiB memory ($2^{16}$ KiB), 4 threads, and a 24-byte hash:

echo -n "password" | ./argon2 somesalt -t 2 -m 16 -p 4 -l 24