Monocypher

https://monocypher.org/manual
Admin
Monocypher is a cryptographic library providing authenticated encryption, hashing, password hashing,...
Tokens:33,320
Snippets:252
Trust Score:9.1
Update:6 months ago
Show doc for...
Tokens:
Raw
### Hashing Shared Secret with Public Keys

Source: https://monocypher.org/manual/x25519

To avoid vulnerabilities where different key pairs produce the same shared secret, hash the shared secret concatenated with both public keys. This example uses BLAKE2b, which can be implemented using `crypto_blake2b()`.

```c
BLAKE2b(shared_secret || your_pk || their_pk)
```

--------------------------------

### Hash Message Incrementally (SHA-512)

Source: https://monocypher.org/manual/sha512

Suitable for hashing large messages or streaming data. Initialize the context, update with message chunks, and finalize to get the hash. Ensure the output buffer is 64 bytes.

```c
uint8_t hash   [ 64]; /* Output hash (64 bytes) */
uint8_t message[500] = {1}; /* Message to hash  */
crypto_sha512_ctx ctx;
crypto_sha512_init(&ctx);
for (size_t i = 0; i < 500; i += 100) {
    crypto_sha512_update(&ctx, message + i, 100);
}
crypto_sha512_final(&ctx, hash);
```

--------------------------------

### Poly1305 Incremental Interface

Source: https://monocypher.org/manual/poly1305

Allows for message authentication in chunks, suitable for large messages or streaming data. It involves initialization, updating with message parts, and finalization to get the MAC.

```APIDOC
## Poly1305 Incremental Interface

### Description
Initializes a Poly1305 context, updates it with message chunks, and finalizes to produce the MAC. This is useful for authenticating messages that cannot be processed in a single block.

### Functions
- `crypto_poly1305_init(crypto_poly1305_ctx *ctx, const uint8_t key[32])`
- `crypto_poly1305_update(crypto_poly1305_ctx *ctx, const uint8_t *message, size_t message_size)`
- `crypto_poly1305_final(crypto_poly1305_ctx *ctx, uint8_t mac[16])`

### Parameters
#### `crypto_poly1305_init`
- **ctx** (crypto_poly1305_ctx *) - Pointer to the Poly1305 context structure to initialize.
- **key** (const uint8_t[32]) - The 32-byte secret authentication key. Should be wiped after initialization.

#### `crypto_poly1305_update`
- **ctx** (crypto_poly1305_ctx *) - Pointer to the initialized Poly1305 context.
- **message** (const uint8_t *) - Pointer to the message chunk to authenticate.
- **message_size** (size_t) - Length of the message chunk in bytes.

#### `crypto_poly1305_final`
- **ctx** (crypto_poly1305_ctx *) - Pointer to the Poly1305 context.
- **mac** (uint8_t[16]) - Output buffer for the 16-byte MAC.

### Request Example
```c
const uint8_t msg[500]= {1}; /* Message to authenticate */
uint8_t       key[ 32]; /* Random secret key (use only once) */
uint8_t       mac[ 16]; /* Message authentication code (MAC) */
crypto_poly1305_ctx ctx;
arc4random_buf(key, 32);
crypto_poly1305_init(&ctx, key);
/* Wipe the key */
crypto_wipe(key, 32);
for (int i = 0; i < 500; i += 100) {
    crypto_poly1305_update(&ctx, msg + i, 100);
}
crypto_poly1305_final(&ctx, mac);
```

### Response
#### Return Values
These functions return nothing.

#### Success Response (200)
N/A (C function)

#### Response Example
N/A (C function)
```

--------------------------------

### Key Derivation with BLAKE2b and ChaCha20

Source: https://monocypher.org/manual/blake2b

Derives a key using BLAKE2b for key extraction and ChaCha20 for key expansion. The salt must be 64 bytes or less, and the info must be exactly 8 bytes.

```c
void kdf(uint8_t *okm,  size_t okm_size,  /* unlimited   */
         uint8_t *ikm,  size_t ikm_size,  /* unlimited   */
         uint8_t *salt, size_t salt_size, /* <= 64 bytes */
         uint8_t info[8])                 /* ==  8 bytes */
{
	/* Extract */
	uint8_t prk[32];
	crypto_blake2b_keyed(prk , sizeof(prk),
	                     salt, salt_size,
	                     ikm , ikm_size);
	/* Expand */
	crypto_chacha20_djb(okm, NULL, okm_size, prk, info, 0);
}
```

--------------------------------

### Simple ChaCha20 Encryption and Decryption

Source: https://monocypher.org/manual/chacha20

Demonstrates basic encryption and decryption using crypto_chacha20_x, followed by memory wiping for security.

```C
uint8_t key        [ 32]; /* Secret random key              */
uint8_t nonce      [ 24]; /* Unique nonce (possibly random) */
uint8_t plain_text [500] = {1}; /* Secret message           */
uint8_t cipher_text[500]; /* Encrypted message              */
arc4random_buf(key,   32);
arc4random_buf(nonce, 24);
crypto_chacha20_x(cipher_text, plain_text, 500, key, nonce, 0);
/* Wipe secrets if they are no longer needed */
crypto_wipe(key,        32);
crypto_wipe(plain_text, 500);
```

```C
uint8_t       key        [ 32]; /* Same key as above        */
const uint8_t nonce      [ 24]; /* Same nonce as above      */
uint8_t       cipher_text[500]; /* Message to decrypt       */
uint8_t       plain_text [500]; /* Secret message           */
crypto_chacha20_x(plain_text, cipher_text, 500, key, nonce, 0);
/* Wipe secrets if they are no longer needed */
crypto_wipe(key,        32);
/* The plaintext likely needs to be processed before you wipe it */
crypto_wipe(plain_text, 12);
```

--------------------------------

### Initialize Incremental SHA-512 Hashing

Source: https://monocypher.org/manual/sha512

Use crypto_sha512_init() to set up a context for incremental SHA-512 hashing. This is useful for hashing data streams or large files in chunks.

```c
void crypto_sha512_init(crypto_sha512_ctx *ctx);
```

--------------------------------

### Hash a password with Argon2

Source: https://monocypher.org/manual/argon2

Demonstrates how to configure and execute the Argon2 hashing function using recommended baseline parameters.

```c
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[] = "Okay Password!";
crypto_argon2_inputs inputs = {
    .pass      = password,                   /* User password */
    .salt      = salt,                 /* Salt for the password */
    .pass_size = sizeof(password) - 1,       /* Password length */
    .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);
}
```

--------------------------------

### Initialize Incremental HMAC-SHA-512

Source: https://monocypher.org/manual/sha512

Use crypto_sha512_hmac_init() to set up a context for incremental HMAC-SHA-512 hashing. This is useful for hashing data streams or large files in chunks.

```c
void crypto_sha512_hmac_init(crypto_sha512_hmac_ctx *ctx, const unsigned char *key, uint32_t key_size);
```

--------------------------------

### Implement XEdDSA Signing

Source: https://monocypher.org/manual/eddsa

Implements XEdDSA signing using low-level Monocypher building blocks. This function requires a secret key, a random nonce, and the message to sign. Secrets are wiped after use.

```c
#include <monocypher.h>
#include <monocypher-ed25519.h>
#include <string.h>

void xed25519_sign(uint8_t signature[64],
                   const uint8_t secret_key[32],
                   const uint8_t random[64],
                   const uint8_t *message, size_t message_size)
{
	static const uint8_t zero   [32] = {0};
	static const uint8_t minus_1[32] = {
		0xec, 0xd3, 0xf5, 0x5c, 0x1a, 0x63, 0x12, 0x58,
		0xd6, 0x9c, 0xf7, 0xa2, 0xde, 0xf9, 0xde, 0x14,
		0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
		0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x10,
	};
	static const uint8_t prefix[32] = {
		0xfe, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
		0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
		0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
		0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
	};

	/* Key pair (a, A) */
	uint8_t A[32];  /* XEdDSA public key  */
	uint8_t a[32];  /* XEdDSA private key */
	crypto_eddsa_trim_scalar(a, secret_key);
	crypto_eddsa_scalarbase(A, a);
	int is_negative = A[31] & 0x80; /* Retrieve sign bit */
	A[31] &= 0x7f;                  /* Clear sign bit    */
	if (is_negative) {
		/* a = -a */
		crypto_eddsa_mul_add(a, a, minus_1, zero);
	}

	/* Secret nonce r */
	uint8_t r[64];
	crypto_sha512_ctx ctx;
	crypto_sha512_init  (&ctx);
	crypto_sha512_update(&ctx, prefix , 32);
	crypto_sha512_update(&ctx, a      , 32);
	crypto_sha512_update(&ctx, message, message_size);
	crypto_sha512_update(&ctx, random , 64);
	crypto_sha512_final (&ctx, r);
	crypto_eddsa_reduce(r, r);

	/* First half of the signature R */
	uint8_t R[32];
	crypto_eddsa_scalarbase(R, r);

	/* hash(R || A || M) */
	uint8_t H[64];
	crypto_sha512_init  (&ctx);
	crypto_sha512_update(&ctx, R      , 32);
	crypto_sha512_update(&ctx, A      , 32);
	crypto_sha512_update(&ctx, message, message_size);
	crypto_sha512_final (&ctx, H);
	crypto_eddsa_reduce(H, H);

	/* Signature */
	memcpy(signature, R, 32);
	crypto_eddsa_mul_add(signature + 32, a, H, r);

	/* Wipe secrets (A, R, and H are not secret) */
	crypto_wipe(a, 32);
	crypto_wipe(r, 32);
}
```

--------------------------------

### Key Derivation with BLAKE2b and XChaCha20

Source: https://monocypher.org/manual/blake2b

Derives a key using BLAKE2b for key extraction and XChaCha20 for key expansion. This version supports an unlimited info size and generates a nonce using BLAKE2b.

```c
void xkdf(uint8_t *okm,  size_t okm_size,  /* unlimited   */
          uint8_t *ikm,  size_t ikm_size,  /* unlimited   */
          uint8_t *salt, size_t salt_size, /* <= 64 bytes */
          uint8_t *info, size_t info_size) /* unlimited   */
{
	/* Extract */
	uint8_t prk[32];
	crypto_blake2b_keyed(prk , sizeof(prk),
	                     salt, salt_size,
	                     ikm , ikm_size);
	/* Expand */
	uint8_t nonce[24];
	crypto_blake2b(nonce, sizeof(nonce), info, info_size);
	crypto_chacha20_x(okm, NULL, okm_size, prk, nonce, 0);
}
```

--------------------------------

### Derive Keys using HKDF (SHA-512)

Source: https://monocypher.org/manual/sha512

Derives keys from input key material using the HKDF standard. Requires input key material (IKM), a salt, and optional info for domain separation. The output keying material (OKM) size must be specified.

```c
uint8_t okm[128]; /* Output random keys */
uint8_t ikm [96]; /* Input key material */
uint8_t salt[16]; /* Random salt        */
uint8_t info[11] = "Lorem ipsum"; /* Domain separation  */
arc4random_buf(salt, sizeof(salt));
crypto_sha512_hkdf(okm, sizeof(okm),
                   ikm, sizeof(ikm),
                   salt, sizeof(salt),
                   info, sizeof(info));
uint8_t *key1 = okm +  0;
uint8_t *key2 = okm + 32;
uint8_t *key3 = okm + 64;
uint8_t *key4 = okm + 96;
/* Wipe okm when it is no longer needed */
```

--------------------------------

### Key Derivation Functions

Source: https://monocypher.org/manual/blake2b

Explains the usage of BLAKE2b for key extraction and expansion processes.

```APIDOC
## Key Derivation

### Description
BLAKE2b is used to implement KDFs through extraction and expansion steps. Extraction derives a pseudo-random key (PRK) from input key material (IKM) and salt, while expansion generates output key material (OKM).

### Parameters
- **IKM** (bytes) - Required - Input key material containing secret entropy.
- **salt** (bytes) - Optional - Random salt to increase security.
- **info** (string) - Optional - Domain separation string.
```

--------------------------------

### XEdDSA Implementation with Low-Level Blocks

Source: https://monocypher.org/manual/eddsa

Implements XEdDSA signatures using X25519 keys with Monocypher's low-level building blocks.

```APIDOC
## Implement XEdDSA (signatures with X25519 keys normally used for key exchange) with the low-level building blocks
```c
#include <monocypher.h>
#include <monocypher-ed25519.h>
#include <string.h>

void xed25519_sign(uint8_t signature[64],
                   const uint8_t secret_key[32],
                   const uint8_t random[64],
                   const uint8_t *message, size_t message_size)
{
	static const uint8_t zero   [32] = {0};
	static const uint8_t minus_1[32] = {
		0xec, 0xd3, 0xf5, 0x5c, 0x1a, 0x63, 0x12, 0x58,
		0xd6, 0x9c, 0xf7, 0xa2, 0xde, 0xf9, 0xde, 0x14,
		0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
		0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x10,
	};
	static const uint8_t prefix[32] = {
		0xfe, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
		0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
		0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
		0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
	};

	/* Key pair (a, A) */
	uint8_t A[32];  /* XEdDSA public key  */
	uint8_t a[32];  /* XEdDSA private key */
	crypto_eddsa_trim_scalar(a, secret_key);
	crypto_eddsa_scalarbase(A, a);
	int is_negative = A[31] & 0x80; /* Retrieve sign bit */
	A[31] &= 0x7f;                  /* Clear sign bit    */
	if (is_negative) {
		/* a = -a */
		crypto_eddsa_mul_add(a, a, minus_1, zero);
	}

	/* Secret nonce r */
	uint8_t r[64];
	crypto_sha512_ctx ctx;
	crypto_sha512_init  (&ctx);
	crypto_sha512_update(&ctx, prefix , 32);
	crypto_sha512_update(&ctx, a      , 32);
	crypto_sha512_update(&ctx, message, message_size);
	crypto_sha512_update(&ctx, random , 64);
	crypto_sha512_final (&ctx, r);
	crypto_eddsa_reduce(r, r);

	/* First half of the signature R */
	uint8_t R[32];
	crypto_eddsa_scalarbase(R, r);

	/* hash(R || A || M) */
	uint8_t H[64];
	crypto_sha512_init  (&ctx);
	crypto_sha512_update(&ctx, R      , 32);
	crypto_sha512_update(&ctx, A      , 32);
	crypto_sha512_update(&ctx, message, message_size);
	crypto_sha512_final (&ctx, H);
	crypto_eddsa_reduce(H, H);

	/* Signature */
	memcpy(signature, R, 32);
	crypto_eddsa_mul_add(signature + 32, a, H, r);

	/* Wipe secrets (A, R, and H are not secret) */
	crypto_wipe(a, 32);
	crypto_wipe(r, 32);
}

int xed25519_verify(const uint8_t signature[64],
                    const uint8_t public_key[32],
                    const uint8_t *message, size_t message_size)
{
	/* Convert X25519 key to EdDSA */
	uint8_t A[32];
	crypto_x25519_to_eddsa(A, public_key);

	/* hash(R || A || M) */
	uint8_t H[64];
	crypto_sha512_ctx ctx;
	crypto_sha512_init  (&ctx);
	crypto_sha512_update(&ctx, signature, 32);
	crypto_sha512_update(&ctx, A        , 32);
	crypto_sha512_update(&ctx, message  , message_size);
	crypto_sha512_final (&ctx, H);
	crypto_eddsa_reduce(H, H);

	/* Check signature */
	return crypto_eddsa_check_equation(signature, A, H);
}
```
```

--------------------------------

### Key Derivation with BLAKE2b alone

Source: https://monocypher.org/manual/blake2b

Derives a key using only BLAKE2b for both extraction and expansion. This method is more complex, involving iterative updates and counter management.

```c
#define MIN(a, b) ((a) < (b) ? (a) : (b))

void b2kdf(uint8_t *okm,  size_t okm_size,  /* unlimited   */
           uint8_t *ikm,  size_t ikm_size,  /* unlimited   */
           uint8_t *salt, size_t salt_size, /* <= 64 bytes */
           uint8_t *info, size_t info_size) /* unlimited   */
{
	/* Extract */
	uint8_t prk[64];
	crypto_blake2b_keyed(prk , sizeof(prk),
	                     salt, salt_size,
	                     ikm , ikm_size);
	/* Expand */
	uint8_t ctr[8] = {0};
	while(okm_size > 0) {
		size_t size = MIN(okm_size, 64);
		crypto_blake2b_ctx ctx;
		crypto_blake2b_keyed_init(&ctx, size, prk, 64);
		crypto_blake2b_update(&ctx, ctr, sizeof(ctr));
		crypto_blake2b_update(&ctx, info, info_size);
		crypto_blake2b_final(&ctx, okm);
		okm      += size;
		okm_size -= size;
		/* increment ctr */
		unsigned acc = 1;
		for (size_t i = 0; i < sizeof(ctr); i++) {
			acc    = ctr[i] + acc;
			ctr[i] = acc & 0xff;
			acc  >>= 8;
		}
	}
}
```

--------------------------------

### Compute MAC incrementally with BLAKE2b

Source: https://monocypher.org/manual/blake2b

Use `crypto_blake2b_keyed_init`, `crypto_blake2b_update`, and `crypto_blake2b_final` for incremental MAC computation. The key is wiped after initialization, and message segments are wiped after each update.

```c
uint8_t hash   [ 16];
uint8_t key    [ 32];
uint8_t message[500] = {1}; /* Message to authenticate */
arc4random_buf(key, sizeof(key));
crypto_blake2b_ctx ctx;
crypto_blake2b_keyed_init(&ctx, sizeof(hash), key,
                          sizeof(key));
/* Wipe the key */
crypto_wipe(key, sizeof(key));
for (size_t i = 0; i < 500; i += 100) {
	crypto_blake2b_update(&ctx, message + i, 100);
	/* Wipe secrets if they are no longer needed */
	crypto_wipe(message + i, 100);
}
crypto_blake2b_final(&ctx, hash);
```

--------------------------------

### Hash a message incrementally with BLAKE2b

Source: https://monocypher.org/manual/blake2b

Use `crypto_blake2b_init`, `crypto_blake2b_update`, and `crypto_blake2b_final` for incremental hashing. This is useful for large messages that cannot fit into memory at once.

```c
uint8_t hash   [ 64]; /* Output hash (64 bytes) */
uint8_t message[500] = {1}; /* Message to hash  */
crypto_blake2b_ctx ctx;
crypto_blake2b_init(&ctx, sizeof(hash));
for (size_t i = 0; i < 500; i += 100) {
	crypto_blake2b_update(&ctx, message + i, 100);
}
crypto_blake2b_final(&ctx, hash);
```

--------------------------------

### Encrypt with Incremental Interface

Source: https://monocypher.org/manual/aead

Uses the incremental context-based interface for AEAD encryption.

```c
uint8_t key        [32];    /* Random, secret session key  */
uint8_t nonce      [24];    /* Use only once per key       */
uint8_t plain_text [12] = "Lorem ipsum"; /* Secret message */
uint8_t mac        [16];    /* Message authentication code */
uint8_t cipher_text[12];              /* Encrypted message */
arc4random_buf(key,   32);
arc4random_buf(nonce, 24);
crypto_aead_ctx ctx;
crypto_aead_init_x(&ctx, key, nonce);
crypto_aead_write(&ctx, cipher_text, mac,
                  NULL, 0,
                  plain_text, sizeof(plain_text));
/* Wipe secrets if they are no longer needed */
crypto_wipe(plain_text, 12);
crypto_wipe(key, 32);
crypto_wipe(&ctx, sizeof(ctx));
/* Transmit cipher_text, nonce, and mac over the network,
 * store them in a file, etc.
 */
```

--------------------------------

### Perform timing-safe comparisons with Monocypher

Source: https://monocypher.org/manual/verify

Use these functions to compare secrets or MACs. Ensure input lengths match the function suffix to avoid undefined behavior.

```c
#include     <monocypher.h>
int   
crypto_verify16(const uint8_t a[16], const uint8_t b[16]);
int   
crypto_verify32(const uint8_t a[32], const uint8_t b[32]);
int   
crypto_verify64(const uint8_t a[64], const uint8_t b[64]);
```

--------------------------------

### Derive Keys using HKDF Expand (SHA-512)

Source: https://monocypher.org/manual/sha512

Expands a pseudo-random key (PRK) into output keying material (OKM) using HKDF. This is often used after an initial extraction step. Ensure correct sizes for PRK and OKM.

```c
uint8_t okm [96]; /* Output secret keys        */
uint8_t pk_a[32]; /* Alice public X25519 key   */
uint8_t pk_b[32]; /* Bob   public X25519 key   */
uint8_t skab[32]; /* Alice & bob shared secret */
uint8_t ikm [96]; /* Input key material        */
uint8_t salt[16]; /* Random salt               */
uint8_t info[ 6] = "X25519"; /* Domain separation         */
arc4random_buf(salt, sizeof(salt));

/* Extract */
uint8_t prk[64]; /* pseudo-random key         */
crypto_sha512_hmac_ctx ctx;
crypto_sha512_hmac_init  (&ctx, salt, sizeof(salt));
crypto_sha512_hmac_update(&ctx, pk_a, sizeof(pk_a));
crypto_sha512_hmac_update(&ctx, pk_b, sizeof(pk_b));
crypto_sha512_hmac_update(&ctx, skab, sizeof(skab));
crypto_sha512_hmac_final (&ctx, prk);

/* Expand */
crypto_sha512_hkdf_expand(okm, sizeof(okm),
                          prk, sizeof(prk),
                          info, sizeof(info));
uint8_t *key1 = okm +  0;
uint8_t *key2 = okm + 32;
uint8_t *key3 = okm + 64;
/* Wipe okm when it is no longer needed */
```

--------------------------------

### Hash a message with BLAKE2b

Source: https://monocypher.org/manual/blake2b

Use `crypto_blake2b` to hash a message all at once. Ensure the output buffer is large enough for the hash size.

```c
uint8_t hash   [64]; /* Output hash (64 bytes)          */
uint8_t message[12] = "Lorem ipsum"; /* Message to hash */
crypto_blake2b(hash, sizeof(hash), message, sizeof(message));
```

--------------------------------

### Hash Message All at Once (SHA-512)

Source: https://monocypher.org/manual/sha512

Use this function for hashing a complete message that fits in memory. Ensure the output buffer is 64 bytes.

```c
uint8_t hash   [64]; /* Output hash (64 bytes)          */
uint8_t message[12] = "Lorem ipsum"; /* Message to hash */
crypto_sha512(hash, message, 12);
```

--------------------------------

### Keyed BLAKE2b for MAC and KDF

Source: https://monocypher.org/manual/blake2b

Implements keyed BLAKE2b for message authentication codes (MACs) and as a random oracle. This is recommended over prefix-MAC for better security arguments.

```APIDOC
## CRYPTO_BLAKE2B_KEYED

### Description
Implements keyed BLAKE2b, suitable for message authentication codes (MACs) or as a random oracle, similar to HMAC. This is recommended for better security arguments when using BLAKE2b.

### Method
`crypto_blake2b_keyed`

### Parameters
#### Arguments
- **hash** (uint8_t *) - Output buffer for the MAC.
- **hash_size** (size_t) - Length of the MAC in bytes. Must be between 1 and 64. Values below 16 are discouraged for MACs, and below 32 for KDFs.
- **key** (uint8_t *) - The secret key. May overlap with hash or message. May be NULL if key_size is 0.
- **key_size** (size_t) - Length of the key in bytes. Must be between 0 and 64. 32 is a good default.
- **message** (const uint8_t *) - The message to compute the MAC for. May overlap with hash or key.
- **message_size** (size_t) - Length of the message in bytes.

### CRYPTO_BLAKE2B_KEYED_INIT, UPDATE, FINAL

### Description
Provides a streaming interface for keyed BLAKE2b operations. This allows for computing MACs on large messages or when message parts are processed sequentially.

### Method
`crypto_blake2b_keyed_init`
`crypto_blake2b_update`
`crypto_blake2b_final`

### Parameters
#### `crypto_blake2b_keyed_init`
- **ctx** (crypto_blake2b_ctx *) - Pointer to the BLAKE2b context structure.
- **hash_size** (size_t) - Length of the hash in bytes. Must be between 1 and 64.
- **key** (uint8_t *) - The secret key. May overlap with hash or message. May be NULL if key_size is 0.
- **key_size** (size_t) - Length of the key in bytes. Must be between 0 and 64.

#### `crypto_blake2b_update`
- **ctx** (crypto_blake2b_ctx *) - Pointer to the BLAKE2b context structure.
- **message** (const uint8_t *) - The message chunk to process. May overlap with hash or key.
- **message_size** (size_t) - Length of the message chunk in bytes.

#### `crypto_blake2b_final`
- **ctx** (crypto_blake2b_ctx *) - Pointer to the BLAKE2b context structure.
- **hash** (uint8_t *) - Output buffer for the final MAC.

### Notes
- Use `crypto_verify16()`, `crypto_verify32()`, or `crypto_verify64()` to compare MACs to avoid timing attacks.
- The key can be wiped using `crypto_wipe()` after use.
```

--------------------------------

### Generate Dirty Public Keys for X25519

Source: https://monocypher.org/manual/x25519

Use `crypto_x25519_dirty_fast` or `crypto_x25519_dirty_small` to generate public keys that are compatible with `crypto_x25519` but also include a low-order point. These functions leak information about the private key and should only be used for ephemeral keys. `_fast` uses more memory and code but is quicker, while `_small` is slower but more memory and code efficient.

```c
/* Example usage for crypto_x25519_dirty_fast and crypto_x25519_dirty_small */
/* Actual function calls would be here, but are not provided in the source. */
/* The description covers their functionality and differences. */
```

--------------------------------

### Constant-Time Comparison Functions

Source: https://monocypher.org/manual

Always use constant-time comparison functions like crypto_verify16(), crypto_verify32(), or crypto_verify64() for comparing secrets. Standard comparison functions can leak information through timing differences, enabling attackers to recover secrets.

```c
if (crypto_verify16(secret1, secret2) != 0) {
    // secrets differ
}

```

```c
if (crypto_verify32(secret1, secret2) != 0) {
    // secrets differ
}

```

```c
if (crypto_verify64(secret1, secret2) != 0) {
    // secrets differ
}

```

--------------------------------

### Argon2 Input Parameters Struct

Source: https://monocypher.org/manual/argon2

Specifies the core inputs for the Argon2 hashing function, including the password, salt, and their respective sizes. The password should be wiped using `crypto_wipe()` after hashing. The salt should be randomly generated and at least 8 bytes, with 16 bytes recommended.

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

--------------------------------

### Conversion and Low-level Building Blocks

Source: https://monocypher.org/manual/eddsa

Functions for converting keys and performing low-level cryptographic operations.

```APIDOC
## crypto_eddsa_to_x25519

### Description
Converts an EdDSA public key to an X25519 public key.

### Parameters
- **x25519** (uint8_t[32]) - Required - Output buffer for the X25519 key.
- **eddsa** (uint8_t[32]) - Required - The input EdDSA public key.

## crypto_eddsa_check_equation

### Description
Low-level check for the EdDSA signature equation. Does not run in constant time.

### Parameters
- **Rs** (uint8_t[64]) - Required - The signature.
- **A** (uint8_t[32]) - Required - The public key.
- **h** (uint8_t[32]) - Required - The hash.

### Response
- **Return Value** (int) - Returns 0 if checks hold, -1 otherwise.
```

--------------------------------

### Perform X25519 Key Exchange and Key Derivation

Source: https://monocypher.org/manual/x25519

Generates a key pair, performs the exchange, and derives two session keys using BLAKE2b. Always wipe sensitive data after use.

```c
const uint8_t their_pk     [32]; /* Their public key          */
uint8_t       your_sk      [32]; /* Your secret key           */
uint8_t       your_pk      [32]; /* Your public key           */
uint8_t       shared_secret[32]; /* Shared secret (NOT a key) */
arc4random_buf(your_sk, 32);
crypto_x25519_public_key(your_pk, your_sk);
crypto_x25519(shared_secret, your_sk, their_pk);
/* Wipe secrets if they are no longer needed */
crypto_wipe(your_sk, 32);

uint8_t shared_keys[64]; /* Two shared session keys */
crypto_blake2b_ctx ctx;
crypto_blake2b_init  (&ctx, 64);
crypto_blake2b_update(&ctx, shared_secret, 32);
crypto_blake2b_update(&ctx, your_pk      , 32);
crypto_blake2b_update(&ctx, their_pk     , 32);
crypto_blake2b_final (&ctx, shared_keys);
const uint8_t *key_1 = shared_keys;      /* Shared key 1 */
const uint8_t *key_2 = shared_keys + 32; /* Shared key 2 */
/* Wipe secrets if they are no longer needed */
crypto_wipe(shared_secret, 32);
```

--------------------------------

### Include Monocypher SHA-512 Header

Source: https://monocypher.org/manual/sha512

Required header for accessing SHA-512, HMAC, and HKDF functions.

```c
#include     <monocypher-ed25519.h>
```

--------------------------------

### BLAKE2b Hashing Functions

Source: https://monocypher.org/manual/blake2b

Direct and incremental interfaces for BLAKE2b hashing.

```c
void   
crypto_blake2b(uint8_t *hash, size_t hash_size, const uint8_t *message, size_t message_size);
void   
crypto_blake2b_init(crypto_blake2b_ctx *ctx, size_t hash_size);
void   
crypto_blake2b_update(crypto_blake2b_ctx *ctx, const uint8_t *message, size_t message_size);
void   
crypto_blake2b_final(crypto_blake2b_ctx *ctx, uint8_t *hash);
```

--------------------------------

### Expand HKDF Pseudo-Random Key

Source: https://monocypher.org/manual/sha512

Use crypto_sha512_hkdf_expand() to expand a pseudo-random key (PRK) into longer output key material (OKM). The PRK can originate from any uniformly random source, not necessarily crypto_sha512_hmac(). Inputs and outputs cannot overlap.

```c
void crypto_sha512_hkdf_expand(unsigned char *okm, uint32_t okm_size, const unsigned char *prk, uint32_t prk_size, const unsigned char *info, uint32_t info_size);
```

--------------------------------

### Incremental Hashing Interface

Source: https://monocypher.org/manual/blake2b

Details the three-step incremental interface for hashing large files or streams.

```APIDOC
## Incremental Hashing

### Description
Provides an interface to hash data in chunks to manage memory usage efficiently.

### Steps
1. **Initialisation**: `crypto_blake2b_init`() or `crypto_blake2b_keyed_init`() sets up the context.
2. **Update**: `crypto_blake2b_update`() hashes message chunks.
3. **Finalisation**: `crypto_blake2b_final`() produces the final hash and wipes the context.
```

--------------------------------

### Perform incremental Poly1305 authentication

Source: https://monocypher.org/manual/poly1305

Authenticates a message in chunks using an initialization, update, and finalization sequence.

```c
const uint8_t msg[500]= {1}; /* Message to authenticate      */
uint8_t       key[ 32]; /* Random secret key (use only once) */
uint8_t       mac[ 16]; /* Message authentication code (MAC) */
crypto_poly1305_ctx ctx;
arc4random_buf(key, 32);
crypto_poly1305_init(&ctx, key);
/* Wipe the key */
crypto_wipe(key, 32);
for (int i = 0; i < 500; i += 100) {
    crypto_poly1305_update(&ctx, msg, 100);
}
crypto_poly1305_final(&ctx, mac);
```

--------------------------------

### Non-sequential ChaCha20 Encryption

Source: https://monocypher.org/manual/chacha20

Demonstrates how to encrypt non-contiguous parts of a message by manually managing the block counter.

```C
uint8_t key        [ 32]; /* Secret random key              */
uint8_t nonce      [ 24]; /* Unique nonce (possibly random) */
uint8_t plain_text [500] = {1}; /* Message to be encrypted  */
uint8_t cipher_text[500]; /* Will be the encrypted message  */
arc4random_buf(key,   32);
arc4random_buf(nonce, 24);
/* Encrypt the second part of the message first... */
crypto_chacha20_x(cipher_text + (3 * 64),
                  plain_text  + (3 * 64),
                  500         - (3 * 64),
                  key, nonce, 3);
/* ...then encrypt the first part */
crypto_chacha20_x(cipher_text, plain_text, 3 * 64, key, nonce, 0);
/* Wipe secrets if they are no longer needed */
crypto_wipe(key,        32);
crypto_wipe(plain_text, 500);
```

--------------------------------

### crypto_argon2() - Password Hashing

Source: https://monocypher.org/manual/argon2

This function hashes a password using the Argon2 algorithm. It requires configuration for the algorithm type, memory usage (nb_blocks), number of iterations (nb_passes), and parallelism (nb_lanes). Input parameters include the password, salt, and their sizes. An optional extras struct can be provided for additional parameters. The function returns nothing upon successful execution and writes the hash to the provided output buffer.

```APIDOC
## crypto_argon2()

### Description
Hashes a password using the Argon2 algorithm.

### Method
N/A (This is a C function, not an HTTP API endpoint)

### Endpoint
N/A

### Parameters
#### Input Buffers
- **hash** (uint8_t *) - Output buffer for the generated hash.
- **hash_size** (size_t) - The size of the output hash buffer (e.g., 32 bytes for a 256-bit hash).
- **work_area** (void *) - Pointer to the allocated memory for computation. Its size should be `config.nb_blocks * 1024` bytes.

#### Configuration (`crypto_argon2_config` struct)
- **algorithm** (uint32_t) - The Argon2 variant to use (e.g., `CRYPTO_ARGON2_I` for Argon2i, `CRYPTO_ARGON2_ID` for Argon2id).
- **nb_blocks** (uint32_t) - The number of memory blocks to use for the computation. This determines the memory footprint (in KiB).
- **nb_passes** (uint32_t) - The number of iterations (passes) the algorithm performs.
- **nb_lanes** (uint32_t) - The number of parallel lanes to use. Monocypher does not support actual parallelism, so this should typically be 1.

#### Inputs (`crypto_argon2_inputs` struct)
- **pass** (const uint8_t *) - Pointer to the user's password.
- **salt** (const uint8_t *) - Pointer to the salt.
- **pass_size** (size_t) - The size of the password in bytes.
- **salt_size** (size_t) - The size of the salt in bytes.

#### Extras (`crypto_argon2_extras` struct)
- **ad** (const uint8_t *) - Optional additional data. Must be zero if unused.
- **ad_size** (size_t) - The size of the additional data in bytes. Must be zero if `ad` is NULL.

### Return Values
`crypto_argon2()` returns nothing.

### Request Example
```c
#include <monocypher.h>
#include <stdlib.h>
#include <stdint.h>

// Assume arc4random_buf() is available for generating random salt
// void arc4random_buf(void *buf, size_t nbytes);

uint8_t hash[32];               /* Output hash     */
uint8_t salt[16];               /* Random salt     */

/* Recommended baseline parameters */
const 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[] = "Okay Password!";
const crypto_argon2_inputs inputs = {
    .pass      = password,                   /* User password */
    .salt      = salt,                 /* Salt for the password */
    .pass_size = sizeof(password) - 1,       /* Password length */
    .salt_size = 16
};

crypto_argon2_extras extras = {0};   /* Extra parameters unused */

/* Allocate work area. Note the conversion to size_t. */
void *work_area = malloc((size_t)config.nb_blocks * 1024);
if (work_area == NULL) {
    /* Handle malloc() failure */
    crypto_wipe(password, sizeof(password)); /* Wipe secrets if no longer needed */
} else {
    arc4random_buf(salt, 16);
    crypto_argon2(hash, sizeof(hash), work_area,
                  config, inputs, extras);
    crypto_wipe(password, sizeof(password)); /* Wipe secrets if no longer needed */
    free(work_area);
}
```

### Response
#### Success Response (N/A)
This function does not return a status code. Success is indicated by the absence of a crash or error during execution. The hash is written to the `hash` buffer.

#### Response Example
N/A (The output is written to the `hash` buffer provided as an argument).

### Error Handling
Monocypher does not perform input validation. Incorrect parameters or buffer sizes can lead to undefined behavior. Ensure all inputs conform to the Argon2 specification and Monocypher's requirements.
```
Tokens:
Raw