### Build and Install Monocypher as System Library

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/10-integration-guide.md

Build the Monocypher library using 'make' and install it to the system using 'sudo make install'. This makes it available for linking via pkg-config.

```bash
cd monocypher/

# Build library
make

# Install to system
sudo make install PREFIX=/usr/local

# Build your code with pkg-config
gcc -std=c99 $(pkg-config monocypher --cflags) \
    your_project.c \
    $(pkg-config monocypher --libs) \
    -o program
```

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

### Compile and Run Blake2b Example

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/10-integration-guide.md

Instructions for compiling the C example using GCC and running the executable.

```bash
gcc -std=c99 monocypher.c example.c -o example
./example
```

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

### Compile Encryption Example

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/10-integration-guide.md

Command to compile the C encryption example using GCC.

```bash
gcc -std=c99 monocypher.c encrypt_example.c -o encrypt_example
```

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

### Incremental SHA-512 Hashing Example

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/07-optional-sha512.md

Demonstrates the process of hashing a message incrementally using SHA-512. Initialize the context, update it with message parts, and finalize to get the hash.

```c
crypto_sha512_ctx ctx;
uint8_t message[] = "Message to hash";
uint8_t hash[64];

crypto_sha512_init(&ctx);
crypto_sha512_update(&ctx, message, sizeof(message) - 1);
crypto_sha512_final(&ctx, hash);

// hash now contains 512-bit SHA-512 digest
```

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

### Install pkg-config for LibHydrogen

Source: https://github.com/loupvaillant/monocypher/blob/master/tests/speed/README.md

If 'speed-hydrogen' fails due to missing pkg-config, run 'make pkg-config-libhydrogen' as root.

```bash
make pkg-config-libhydrogen
```

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

### Change Installation Path

Source: https://github.com/loupvaillant/monocypher/blob/master/README.md

Customize the installation directory for Monocypher using the PREFIX variable.

```bash
$ make install PREFIX="/opt"
```

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

### Verify Monocypher Installation on Linux/Unix

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/10-integration-guide.md

After installing Monocypher using 'make install', verify the installation by checking the compiler flags and linker options using pkg-config.

```bash
# Verify installation
pkg-config --cflags monocypher
pkg-config --libs monocypher
```

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

### Integrate Monocypher with Meson

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/10-integration-guide.md

Meson build configuration for a project using Monocypher. This example creates a static library for Monocypher and links it to the main executable.

```meson
project('myapp', 'c',
        default_options: ['c_std=c99'])

monocypher_sources = [
    'monocypher/src/monocypher.c',
    'monocypher/src/optional/monocypher-ed25519.c'
]

monocypher_inc = include_directories('monocypher/src')

monocypher = static_library('monocypher',
    monocypher_sources,
    include_directories: monocypher_inc
)

executable('myapp',
    'main.c',
    link_with: monocypher,
    include_directories: monocypher_inc
)
```

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

### Run LibHydrogen Speed Benchmark

Source: https://github.com/loupvaillant/monocypher/blob/master/tests/speed/README.md

Execute 'make speed-hydrogen' to run the speed benchmark for LibHydrogen. This target assumes pkg-config is installed.

```bash
make speed-hydrogen
```

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

### Monocypher Authenticated Encryption Incremental Decryption Example

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/01-authenticated-encryption.md

Example demonstrating how to use `crypto_aead_read` to decrypt and verify ciphertext in chunks. Ensure the context is initialized with `crypto_aead_init_*` and the MAC is provided by the sender.

```c
crypto_aead_ctx ctx;
uint8_t key[32], nonce[24];
uint8_t ciphertext[1024];
uint8_t mac[16];  // From sender
uint8_t plaintext[1024];

crypto_aead_init_x(&ctx, key, nonce);

// Decrypt and verify chunk by chunk
int result = crypto_aead_read(&ctx, plaintext, mac, NULL, 0, 
                              ciphertext, 512);

if (result == 0) {
    result = crypto_aead_read(&ctx, plaintext + 512, mac, NULL, 0,
                              ciphertext + 512, 512);
}

if (result == 0) {
    // All chunks verified successfully
}
```

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

### Compile Monocypher on macOS

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/10-integration-guide.md

Build Monocypher on macOS using 'make' with CC=clang, and then install it using 'sudo make install'.

```bash
make CC=clang
sudo make install
```

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

### Integrate Monocypher with CMake

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/10-integration-guide.md

Example CMakeLists.txt to build a project that statically links Monocypher. Ensure Monocypher source files are correctly referenced.

```cmake
cmake_minimum_required(VERSION 3.10)
project(MyProject C)

set(CMAKE_C_STANDARD 99)

add_library(monocypher STATIC
    monocypher/src/monocypher.c
    monocypher/src/optional/monocypher-ed25519.c
)

target_include_directories(monocypher PUBLIC
    ${CMAKE_CURRENT_SOURCE_DIR}/monocypher/src
)

add_executable(myapp main.c)
target_link_libraries(myapp monocypher)
```

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

### Compile with Optional SHA-512 and Ed25519 (C++ Example)

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/10-integration-guide.md

Compile your project including the optional Ed25519 source file. Ensure C99 compatibility and specify the correct paths to the source files.

```bash
# Compilation
gcc -std=c99 -Wall \
    src/monocypher.c \
    src/optional/monocypher-ed25519.c \
    your_project.c \
    -o program
```

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

### Get Monocypher Version from Header

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/10-integration-guide.md

Illustrates how to find the Monocypher version by checking the version macro defined in the monocypher.h header file.

```c
// Located in monocypher.h
// version __git__ (replaced with actual version in releases)
```

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

### Encrypting Large Files in Chunks with XChaCha20

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/05-stream-cipher.md

Example demonstrating how to encrypt a large file by processing it in 256-byte chunks using the crypto_chacha20_x function. Ensure the key and nonce are properly initialized before use.

```c
#include <monocypher.h>
#include <stdint.h>

uint8_t key[32];
uint8_t nonce[24];
uint8_t plaintext[1024];
uint8_t ciphertext[1024];

// Encrypt large file in chunks
uint64_t counter = 0;

for (size_t offset = 0; offset < sizeof(plaintext); offset += 256) {
    size_t chunk_size = sizeof(plaintext) - offset;
    if (chunk_size > 256) chunk_size = 256;
    
    counter = crypto_chacha20_x(ciphertext + offset,
                                plaintext + offset,
                                chunk_size,
                                key, nonce, counter);
}

```

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

### Run Monocypher Benchmark with Custom CFLAGS

Source: https://github.com/loupvaillant/monocypher/blob/master/tests/speed/README.md

Adjust optimization options for Monocypher by specifying CFLAGS, for example, '-O2'.

```bash
make speed CFLAGS="-O2"
```

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

### Run Frama-c Analysis

Source: https://github.com/loupvaillant/monocypher/blob/master/README.md

Execute the script to parse and analyze Monocypher code with Frama-c. Ensure Frama-c is installed and refer to `frama-c.sh` for recommended settings.

```bash
$ tests/formal-analysis.sh
$ tests/frama-c.sh
```

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

### Get Monocypher Version with Git

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/10-integration-guide.md

Command to retrieve the Monocypher version using Git describe, which shows the latest tag and commit information.

```bash
git describe --tags
```

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

### Nonce Reuse Vulnerability Example

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/12-security-and-errors.md

This code demonstrates the incorrect usage of a nonce, leading to a security compromise. Reusing a nonce with the same key reveals the keystream, allowing attackers to XOR ciphertexts and potentially recover plaintexts.

```c
// WRONG - Using same nonce twice
uint8_t key[32] = {...};
uint8_t nonce[24] = {...};

// First message
crypto_aead_lock(c1, m1, key, nonce, NULL, 0, plaintext1, size1);

// SECURITY BREACH - Same nonce!
crypto_aead_lock(c2, m2, key, nonce, NULL, 0, plaintext2, size2);

// Attacker can: c1 XOR c2 = plaintext1 XOR plaintext2
// Often sufficient to recover both plaintexts
```

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

### Development vs. Production Key and Nonce Initialization

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/12-security-and-errors.md

Illustrates insecure key and nonce initialization for testing purposes versus secure generation using OS random sources for production environments. It also shows an alternative nonce generation strategy.

```c
// For testing - NOT secure
uint8_t key[32] = {1, 2, 3, ...};  // Fixed, predictable
uint8_t nonce[24] = {0, 0, 0, ...};  // Zero nonce
```

```c
// For real use - Secure
uint8_t key[32];
uint8_t nonce[24];

// Get from OS random source
get_secure_random_bytes(key, 32);
get_secure_random_bytes(nonce, 24);

// Or for nonces, use timestamp + random if needed
generate_unique_nonce(nonce);
```

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

### Build and Link Against Static Library

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/10-integration-guide.md

Build the static library 'libmonocypher.a' and then link your project against it. Ensure the include path to monocypher/src is provided.

```bash
cd monocypher/
make lib/libmonocypher.a

# Link against static library
gcc -std=c99 -I monocypher/src \
    your_project.c \
    monocypher/lib/libmonocypher.a \
    -o program
```

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

### Run Monocypher Speed Benchmark

Source: https://github.com/loupvaillant/monocypher/blob/master/tests/speed/README.md

Navigate to the tests/speed directory and run 'make speed' to benchmark Monocypher's performance on your machine. Ensure you run this on the target platform for accurate results.

```bash
cd tests/speed
make speed
```

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

### Hash a File with Blake2b

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/10-integration-guide.md

Demonstrates how to compute the Blake2b hash of a small data buffer. Ensure the output buffer is large enough for the hash.

```c
#include <monocypher.h>
#include <stdio.h>
#include <stdint.h>

int main(void) {
    uint8_t hash[32];
    uint8_t data[] = "Hello";
    
    crypto_blake2b(hash, sizeof(hash), data, sizeof(data) - 1);
    
    for (int i = 0; i < 32; i++) {
        printf("%02x", hash[i]);
    }
    printf("\n");
    
    return 0;
}
```

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

### Integrate Monocypher with Make/Makefile

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/10-integration-guide.md

A sample Makefile for compiling a project with Monocypher. Adjust MONOCYPHER_DIR to match your project structure.

```makefile
CC = gcc
CFLAGS = -std=c99 -Wall -Wextra -O3
MONOCYPHER_DIR = monocypher

SOURCES = main.c $(MONOCYPHER_DIR)/src/monocypher.c
HEADERS = $(MONOCYPHER_DIR)/src/monocypher.h

OBJECTS = $(SOURCES:.c=.o)
TARGET = myapp

all: $(TARGET)

$(TARGET): $(OBJECTS)
	$(CC) $(CFLAGS) -o $@ $^

%.o: %.c $(HEADERS)
	$(CC) $(CFLAGS) -c -o $@ $<

clean:
	rm -f $(OBJECTS) $(TARGET)

.PHONY: all clean
```

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

### Run TweetNaCl Benchmark with Custom CFLAGS

Source: https://github.com/loupvaillant/monocypher/blob/master/tests/speed/README.md

Adjust optimization options for TweetNaCl by specifying CFLAGS, for example, '-O2'.

```bash
make speed-tweetnacl CFLAGS="-O2"
```

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

### Build and Link Against Shared Library

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/10-integration-guide.md

Build the shared library 'libmonocypher.so' and link your project against it. After execution, set LD_LIBRARY_PATH to make the shared library accessible at runtime.

```bash
cd monocypher/
make lib/libmonocypher.so

# Link against shared library
gcc -std=c99 -I monocypher/src \
    your_project.c \
    monocypher/lib/libmonocypher.so \
    -o program

# Make shared library accessible at runtime
export LD_LIBRARY_PATH=monocypher/lib:$LD_LIBRARY_PATH
./program
```

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

### Formal Analysis with Frama-C

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/12-security-and-errors.md

This command initiates the formal analysis of Monocypher using Frama-C, a static analysis framework for C code, to verify its properties.

```bash
cd monocypher/tests
./formal-analysis.sh  # Run Frama-C analysis
```

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

### Initialize Incremental Keyed BLAKE2b Context

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/02-hashing.md

Initializes a context for incremental keyed BLAKE2b hashing (MAC generation). Provide a secret key and specify the desired output hash size (1-64 bytes).

```c
void crypto_blake2b_keyed_init(crypto_blake2b_ctx *ctx, size_t hash_size,
                               const uint8_t *key, size_t key_size);
```

```c
crypto_blake2b_ctx ctx;
uint8_t key[32];

crypto_blake2b_keyed_init(&ctx, 32, key, sizeof(key));
// Now use crypto_blake2b_update() to hash data
```

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

### Monocypher Usage in C++ with Namespace

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/10-integration-guide.md

When using the MONOCYPHER_CPP_NAMESPACE macro, access Monocypher functions within the specified C++ namespace, for example, 'crypto::crypto_blake2b'.

```cpp
#include <monocypher.h>

int main() {
    uint8_t hash[32];
    crypto::crypto_blake2b(hash, 32, nullptr, 0);
    return 0;
}
```

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

### Run Libsodium Speed Benchmark

Source: https://github.com/loupvaillant/monocypher/blob/master/tests/speed/README.md

Execute 'make speed-sodium' to run the speed benchmark for libsodium.

```bash
make speed-sodium
```

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

### BLAKE2b Hash Computation (Incremental)

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/MANIFEST.txt

Computes the BLAKE2b hash of a message incrementally, which is useful for large messages or streams. Remember to call crypto_blake2b_final to get the final hash.

```C
#include <monocypher.h>
#include <stdio.h>
#include <stdlib.h>

int main() {
    crypto_blake2b_ctx ctx;
    unsigned char hash[MONOCYPHER_HASH_SIZE];
    unsigned char buffer[] = "This is a message part.";
    size_t bytes_processed;

    // Initialize the context
    if (crypto_blake2b_init(&ctx, sizeof hash) != 0) {
        fprintf(stderr, "BLAKE2b initialization failed\n");
        return 1;
    }

    // Update the hash with data chunks
    bytes_processed = sizeof buffer;
    if (crypto_blake2b_update(&ctx, buffer, bytes_processed) != 0) {
        fprintf(stderr, "BLAKE2b update failed\n");
        return 1;
    }

    // Finalize the hash computation
    if (crypto_blake2b_final(&ctx, hash, sizeof hash) != 0) {
        fprintf(stderr, "BLAKE2b finalization failed\n");
        return 1;
    }

    printf("Incremental BLAKE2b hash computed successfully.\n");
    // Print the hash (example)
    for (size_t i = 0; i < sizeof hash; ++i) {
        printf("%02x", hash[i]);
    }
    printf("\n");
    return 0;
}
```

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

### Basic Monocypher Usage (Direct Integration)

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/10-integration-guide.md

Include the Monocypher header and use its functions, such as crypto_blake2b, for hashing messages. Ensure your project is compiled with C99 or later.

```c
#include <monocypher.h>

int main(void) {
    uint8_t hash[32];
    uint8_t message[] = "Hello, world!";
    
    crypto_blake2b(hash, sizeof(hash),
                   message, sizeof(message) - 1);
    
    return 0;
}
```

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

### Key Reuse Across Protocols Vulnerability

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/12-security-and-errors.md

This example illustrates the incorrect practice of using a single master key for multiple cryptographic operations like encryption, authentication, and key derivation. This can lead to security weaknesses.

```c
// WRONG
uint8_t master_key[32] = {...};

crypto_aead_lock(c, mac, master_key, nonce1, NULL, 0, m1, size1);
crypto_blake2b_keyed(h, 32, master_key, 32, data, data_size);
crypto_x25519(shared, master_key, peer_public);  // Uses first 32 bytes as secret key

// Weakness: master_key used in multiple contexts, potential attacks
```

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

### Run ed25519-donna Speed Benchmark

Source: https://github.com/loupvaillant/monocypher/blob/master/tests/speed/README.md

Execute 'make speed-donna' to run the speed benchmark for the portable, 32-bit version of ed25519-donna.

```bash
make speed-donna
```

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

### Generate Disguised Public Key Pair

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/11-common-patterns.md

Generates an X25519 key pair where the public key is indistinguishable from random data using the Elligator representation. This can be used to disguise public keys, for example, in protocols where a public key might otherwise reveal information.

```c
#include <monocypher.h>
#include <stdint.h>

void generate_hidden_key_pair(uint8_t hidden[32],
                              uint8_t secret[32],
                              uint8_t seed[32])
{
    // Generate key pair where public key looks like random data
    crypto_elligator_key_pair(hidden, secret, seed);
    
    // hidden is now indistinguishable from random 32 bytes
    // but can still be used for X25519 key exchange
}

// To recover the "public key" later
int recover_public_key(uint8_t public_key[32],
                       const uint8_t hidden[32])
{
    // hidden was created with crypto_elligator_key_pair()
    // We need to map it back to get the actual public key
    // This requires knowing which representative was used
    
    // For OPRF/DH: map is done internally; hidden IS the public key
    // For recovery: use crypto_elligator_rev() to get hidden value
    
    // Map hidden back to curve point
    crypto_elligator_map(public_key, hidden);
    return 0;
}

```

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

### Run Monocypher Test Suite

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/10-integration-guide.md

Command to navigate to the Monocypher directory and run its test suite. The output should indicate 'All tests OK!'.

```bash
cd monocypher/
make test
```

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

### Compile with Direct Source Integration

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/10-integration-guide.md

Compile your project by linking the Monocypher source file with your main C file. Use the -std=c99 flag for C99 compatibility.

```bash
gcc -std=c99 -Wall your_project/src/monocypher.c your_project/src/main.c -o program
```

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

### crypto_blake2b_keyed_init

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/02-hashing.md

Initializes a context for incremental keyed BLAKE2b hashing, suitable for authenticating streaming data. Requires a secret key.

```APIDOC
## crypto_blake2b_keyed_init

### Description
Initializes a context for incremental keyed BLAKE2b hashing, suitable for authenticating streaming data. Requires a secret key.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### C Function Signature
```c
void crypto_blake2b_keyed_init(crypto_blake2b_ctx *ctx, size_t hash_size, const uint8_t *key, size_t key_size);
```

### Parameters
- **ctx** (crypto_blake2b_ctx*) - Required - Context to initialize
- **hash_size** (size_t) - Required - Desired output size (1-64 bytes)
- **key** (uint8_t*) - Required - Secret key for authentication
- **key_size** (size_t) - Required - Size of key in bytes (1-64)

### Returns
void

### Example
```c
crypto_blake2b_ctx ctx;
uint8_t key[32];

crypto_blake2b_keyed_init(&ctx, 32, key, sizeof(key));
// Now use crypto_blake2b_update() to hash data
```
```

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

### Run TweetNaCl Speed Benchmark

Source: https://github.com/loupvaillant/monocypher/blob/master/tests/speed/README.md

Execute 'make speed-tweetnacl' to run the speed benchmark for TweetNaCl.

```bash
make speed-tweetnacl
```

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

### Compile and Link with pkg-config

Source: https://github.com/loupvaillant/monocypher/blob/master/README.md

Use pkg-config to obtain compiler and linker flags for integrating Monocypher into your C program.

```bash
$ gcc program.c $(pkg-config monocypher --cflags) -c
$ gcc program.o $(pkg-config monocypher --libs)   -o program
```

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

### Initialize XChaCha20 AEAD Context

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/01-authenticated-encryption.md

Initializes an AEAD context for XChaCha20 using a 24-byte nonce. Recommended for most applications. Requires a 32-byte key and a unique 24-byte nonce.

```c
void crypto_aead_init_x(crypto_aead_ctx *ctx,
                        const uint8_t key[32], const uint8_t nonce[24]);
```

```c
crypto_aead_ctx ctx;
uint8_t key[32];
uint8_t nonce[24];

crypto_aead_init_x(&ctx, key, nonce);
// Now use crypto_aead_write() and crypto_aead_read() for streaming
```

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

### Run c25519 Speed Benchmark

Source: https://github.com/loupvaillant/monocypher/blob/master/tests/speed/README.md

Execute 'make speed-c25519' to run the speed benchmark for c25519.

```bash
make speed-c25519
```

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

### crypto_blake2b_init

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/02-hashing.md

Initializes a context for incremental BLAKE2b hashing. This is used for hashing large messages or streaming data piece by piece.

```APIDOC
## crypto_blake2b_init

### Description
Initializes a context for incremental BLAKE2b hashing. This is used for hashing large messages or streaming data piece by piece.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### C Function Signature
```c
void crypto_blake2b_init(crypto_blake2b_ctx *ctx, size_t hash_size);
```

### Parameters
- **ctx** (crypto_blake2b_ctx*) - Required - Context to initialize
- **hash_size** (size_t) - Required - Desired output size (1-64 bytes)

### Returns
void

### Example
```c
crypto_blake2b_ctx ctx;
crypto_blake2b_init(&ctx, 32);  // Initialize for 256-bit hash
```
```

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

### crypto_aead_init_x

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/01-authenticated-encryption.md

Initializes an AEAD context for XChaCha20, which uses a 24-byte nonce. This is the recommended variant for most applications due to its larger nonce size, reducing the risk of nonce reuse.

```APIDOC
## crypto_aead_init_x

### Description
Initializes an AEAD context for XChaCha20 (24-byte nonce).

### Parameters
#### Path Parameters
- **ctx** (crypto_aead_ctx*) - Yes - Context to initialize
- **key** (uint8_t[32]) - Yes - 32-byte secret key
- **nonce** (uint8_t[24]) - Yes - 24-byte nonce, must be unique per key

### Returns
void

### Note
Recommended over DJB and IETF variants for most applications.

### Example
```c
crypto_aead_ctx ctx;
uint8_t key[32];
uint8_t nonce[24];

crypto_aead_init_x(&ctx, key, nonce);
// Now use crypto_aead_write() and crypto_aead_read() for streaming
```
```

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

### Securely Handle Passwords in Memory

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/11-common-patterns.md

Demonstrates how to securely handle passwords in memory by reading them into a buffer and then immediately wiping the buffer after use. This minimizes the time sensitive password data resides in memory.

```c
#include <monocypher.h>
#include <stdio.h>
#include <string.h>
#include <stdint.h>

void process_password(void)
{
    char password[256];
    
    // Read password from user
    printf("Enter password: ");
    fgets(password, sizeof(password), stdin);
    
    // Use password for hashing
    uint8_t salt[16] = {...};
    uint8_t hash[32];
    
    // (hash_password implementation)
    
    // Immediately wipe password from memory
    crypto_wipe(password, sizeof(password));
    
    // password is now securely wiped
}

```

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

### Secure Key Usage with Memory Protection

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/12-security-and-errors.md

This function demonstrates how to securely use a key by locking it in memory, disabling core dumps, performing crypto operations, wiping the key, and then unlocking it. It also shows how to lock all current and future memory for the process.

```c
#include <monocypher.h>
#include <sys/mman.h>
#include <signal.h>
#include <stdlib.h>

void secure_key_usage(uint8_t key[32])
{
    // 1. Lock in memory (prevent swap)
    mlock(key, 32);
    
    // 2. Disable core dumps
    struct rlimit core_limit = {0, 0};
    setrlimit(RLIMIT_CORE, &core_limit);
    
    // 3. Use key
    uint8_t hash[32];
    crypto_blake2b(hash, 32, key, 32);
    
    // 4. Wipe key
    crypto_wipe(key, 32);
    
    // 5. Unlock from memory
    munlock(key, 32);
    
    // 6. Disable swapping for whole process if possible
    mlockall(MCL_CURRENT | MCL_FUTURE);
}
```

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

### Initialize Incremental BLAKE2b Context

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/02-hashing.md

Initializes a context for incremental BLAKE2b hashing. This is suitable for large messages or streaming data. Specify the desired output hash size (1-64 bytes).

```c
void crypto_blake2b_init(crypto_blake2b_ctx *ctx, size_t hash_size);
```

```c
crypto_blake2b_ctx ctx;
crypto_blake2b_init(&ctx, 32);  // Initialize for 256-bit hash
```

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

### Equivalent Structure for No Argon2 Extras

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/08-types.md

Illustrates the structure equivalent to `crypto_argon2_no_extras`, showing how to manually define an Argon2 extras structure with NULL pointers and zero sizes.

```c
crypto_argon2_extras no_extras = {
    .key = NULL,
    .key_size = 0,
    .ad = NULL,
    .ad_size = 0
};
```

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

### Compile with Optional SHA-512 and Ed25519

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/10-integration-guide.md

Include both the core Monocypher source and the optional Ed25519 implementation source files during compilation. Ensure C99 compatibility.

```bash
gcc -std=c99 -Wall \
    your_project/src/monocypher.c \
    your_project/src/optional/monocypher-ed25519.c \
    your_project/src/main.c \
    -o program
```

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

### Poly1305 Initialization Function Signature

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/05-stream-cipher.md

Signature for initializing a Poly1305 context. Requires a 32-byte key that should only be used once.

```c
void crypto_poly1305_init(crypto_poly1305_ctx *ctx, const uint8_t key[32]);

```

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

### Copy Monocypher Source Files

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/10-integration-guide.md

Copy the core Monocypher header and source files into your project's include and source directories for direct integration.

```bash
cp monocypher/src/monocypher.h   your_project/include/
cp monocypher/src/monocypher.c   your_project/src/
```

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

### Runtime Security Checks with Valgrind and Clang Sanitizers

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/12-security-and-errors.md

Provides commands for runtime memory safety checks using Valgrind and for detecting memory and undefined behavior errors with Clang's sanitizers. It also mentions running the full Monocypher test suite.

```bash
# Valgrind (memory safety)
valgrind ./program

# Clang sanitizers
clang -fsanitize=memory,undefined main.c monocypher.c

# Full test suite
cd monocypher && make test
```

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

### Correct Buffer Size for crypto_blake2b

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/06-utilities.md

Ensure buffer sizes match function signatures exactly to avoid undefined behavior. Incorrect buffer sizes can lead to security vulnerabilities.

```c
uint8_t hash[16];

// WRONG - hash must be at least 32 bytes
crypto_blake2b(hash, 32, message, message_size);  // UNDEFINED BEHAVIOR

// CORRECT
uint8_t hash[32];
crypto_blake2b(hash, 32, message, message_size);
```

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

### Run Test Suite

Source: https://github.com/loupvaillant/monocypher/blob/master/README.md

Execute the Monocypher test suite to ensure the library is functioning correctly. It is crucial to run these tests before using the library.

```bash
$ make test
```

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

### Initialize SHA-512 Context

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/07-optional-sha512.md

Initializes an incremental SHA-512 context structure. This must be called before using `crypto_sha512_update` or `crypto_sha512_final`.

```c
#include "monocypher.h"
#include "optional/monocypher-ed25519.h"

crypto_sha512_ctx ctx;
crypto_sha512_init(&ctx);
```

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

### Compile Monocypher with SHA-512 Support

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/07-optional-sha512.md

To enable SHA-512 and related functions, compile Monocypher with the `monocypher-ed25519.c` source file. This command compiles the main library and the optional component.

```bash
# Compile with SHA-512 support
gcc -c src/monocypher.c src/optional/monocypher-ed25519.c
```

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

### Deriving Context-Specific Keys

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/12-security-and-errors.md

This code demonstrates the correct method for deriving unique keys for different cryptographic contexts from a master key. Using context-specific labels with a keyed hash function like BLAKE2b ensures that keys used for encryption, authentication, or key exchange are distinct and secure.

```c
uint8_t master_key[32] = {...};

// Derive context-specific keys
uint8_t encryption_key[32];
uint8_t authentication_key[32];
uint8_t exchange_key[32];

// Use context-specific labels
crypto_blake2b_keyed(encryption_key, 32,
                     (uint8_t *)"encryption", 10,
                     master_key, 32);

crypto_blake2b_keyed(authentication_key, 32,
                     (uint8_t *)"authentication", 14,
                     master_key, 32);

crypto_blake2b_keyed(exchange_key, 32,
                     (uint8_t *)"key_exchange", 12,
                     master_key, 32);

// Now use context-specific keys
```

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

### Change Build Configuration

Source: https://github.com/loupvaillant/monocypher/blob/master/README.md

Modify the default compiler and flags for building Monocypher if the defaults do not work on your platform.

```bash
$ make CC="clang -std=c11" CFLAGS="-O2"
```

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

### Recommended GCC Compilation Flags

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/10-integration-guide.md

A set of recommended GCC flags for compiling Monocypher in production. Includes optimization, warnings, and security features.

```bash
gcc -std=c99 -O3 -Wall -Wextra -fstack-protector-strong -fPIC
```

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

### crypto_aead_init_ietf

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/01-authenticated-encryption.md

Initializes an AEAD context for the IETF ChaCha20 variant, using a 12-byte nonce. This variant is limited to 2^32 messages per key and is also not recommended over `crypto_aead_init_x`.

```APIDOC
## crypto_aead_init_ietf

### Description
Initializes an AEAD context for IETF ChaCha20 (12-byte nonce).

### Parameters
#### Path Parameters
- **ctx** (crypto_aead_ctx*) - Yes - Context to initialize
- **key** (uint8_t[32]) - Yes - 32-byte secret key
- **nonce** (uint8_t[12]) - Yes - 12-byte nonce (IETF variant, RFC 7539)

### Returns
void

### Note
IETF standard variant. Limit to 2^32 messages with the same key due to 12-byte nonce. Use `crypto_aead_init_x` instead.

### Source
`src/monocypher.c:882-887`
```

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

### Include Optional SHA-512 Headers

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/07-optional-sha512.md

After compiling with optional components, include both the main Monocypher header and the optional header for SHA-512 and Ed25519 functionalities in your C source files.

```c
#include "monocypher.h"
#include "optional/monocypher-ed25519.h"
```

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

### Constant-Time Comparison for Secrets

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/12-security-and-errors.md

Demonstrates how to avoid secret-dependent branching and array indexing, which can lead to timing leaks. It shows the incorrect approach and the recommended constant-time alternatives using `crypto_verify32` and bitwise operations.

```c
// WRONG
if (secret_value == expected) { ... }
```

```c
// BETTER - Ensure both branches taken
int equal = crypto_verify32(secret_value, expected);
if (equal == 0) { ... }
```

```c
// WRONG
result = lookup_table[secret_byte];  // Timing leak via cache
```

```c
// BETTER - Use constant time approach
for (int i = 0; i < 256; i++) {
    mask = constant_time_eq(i, secret_byte);
    result |= (lookup_table[i] & mask);
}
```

```c
// WRONG
while (length-- && secret_data[i] == expected[i]) { ... }
```

```c
// BETTER - Compare all bytes always
int result = crypto_verify32(a, b);
```

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

### Monocypher Usage with Optional SHA-512

Source: https://github.com/loupvaillant/monocypher/blob/master/_autodocs/10-integration-guide.md

Include both monocypher.h and optional/monocypher-ed25519.h to use functions like crypto_sha512. Ensure the optional source file is included during compilation.

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

int main(void) {
    uint8_t hash[64];
    uint8_t message[] = "Test";
    
    crypto_sha512(hash, message, sizeof(message) - 1);
    
    return 0;
}
```