facil.io
Cryptography & TLS

#Argon2

c
#define FIO_ARGON2
#include "fio-stl.h"

Argon2 is a memory-hard password hashing function from RFC 9106. It uses BLAKE2b underneath and lets you tune time, memory, and lane count so attackers have to pay real rent.

This implementation supports Argon2d, Argon2i, and Argon2id. It is single-threaded: parallelism affects the Argon2 lane layout, but lanes are processed sequentially.

When comparing Argon2 outputs, use fio_ct_is_eq or another constant-time comparison.

#Types

#fio_argon2_type_e

c
typedef enum {
  FIO_ARGON2D = 0,
  FIO_ARGON2I = 1,
  FIO_ARGON2ID = 2,
} fio_argon2_type_e;
  • FIO_ARGON2D: data-dependent access, faster, weaker against side-channel observers.
  • FIO_ARGON2I: data-independent access.
  • FIO_ARGON2ID: hybrid mode, commonly recommended for password hashing.

#fio_argon2_args_s

c
typedef struct {
  fio_buf_info_s password;
  fio_buf_info_s salt;
  fio_buf_info_s secret;
  fio_buf_info_s ad;
  uint32_t t_cost;
  uint32_t m_cost;
  uint32_t parallelism;
  uint32_t outlen;
  fio_argon2_type_e type;
} fio_argon2_args_s;

Arguments:

Field Meaning
password Password / message P.
salt Salt / nonce S; use a unique random salt.
secret Optional secret key K.
ad Optional associated data X.
t_cost Pass count, minimum 1.
m_cost Memory cost in KiB, minimum 8 * parallelism.
parallelism Lane count, minimum 1; processed sequentially here.
outlen Output length in bytes, minimum 4, default 32.
type FIO_ARGON2D, FIO_ARGON2I, or FIO_ARGON2ID.

#API

#fio_argon2

c
SFUNC fio_u512 fio_argon2(fio_argon2_args_s args);
#define fio_argon2(...) fio_argon2((fio_argon2_args_s){__VA_ARGS__})

Computes an Argon2 hash and returns up to 64 bytes in fio_u512. Use the first outlen bytes; if outlen is 0, the default is 32 bytes.

For outputs longer than 64 bytes, use fio_argon2_hash.

#fio_argon2_hash

c
SFUNC int fio_argon2_hash(void *out, fio_argon2_args_s args);
#define fio_argon2_hash(out, ...)                                              \
  fio_argon2_hash(out, (fio_argon2_args_s){__VA_ARGS__})

Writes the Argon2 output into a caller-provided buffer. Supports arbitrary output lengths of at least 4 bytes.

Returns 0 on success, -1 on error.

#Example

c
#define FIO_ARGON2
#include "fio-stl.h"

int check_password(const char *password,
                   size_t password_len,
                   const void *salt,
                   size_t salt_len,
                   const uint8_t expected[32]) {
  fio_u512 hash = fio_argon2(
      .password = FIO_BUF_INFO2((void *)password, password_len),
      .salt = FIO_BUF_INFO2((void *)salt, salt_len),
      .t_cost = 3,
      .m_cost = 65536,     /* 64 MiB */
      .parallelism = 4,
      .outlen = 32,
      .type = FIO_ARGON2ID);

  return fio_ct_is_eq(hash.u8, expected, 32) ? 0 : -1;
}

#Practical Notes

  • Store the salt and cost settings with the password hash. Future you will not remember them. Future you never does.
  • Pick FIO_ARGON2ID for password hashing unless you have a specific reason not to.
  • Raise m_cost and t_cost until the slow path is acceptable for your login flow.
  • Do not compare hashes with memcmp; use constant-time comparison.