libaegis

libaegis provides portable C implementations of the AEGIS family of high-performance authenticated ciphers. It supports runtime CPU detection to utilize hardware acceleration where available.

Supported AEGIS Variants:

• AEGIS-128L: 16 and 32 bytes tags (software, AES-NI, ARM Crypto, Altivec).
• AEGIS-128X2: 16 and 32 bytes tags (software, VAES + AVX2, AES-NI, ARM Crypto, Altivec).
• AEGIS-128X4: 16 and 32 bytes tags (software, AVX512, VAES + AVX2, AES-NI, ARM Crypto, Altivec).
• AEGIS-256: 16 and 32 bytes tags (software, AES-NI, ARM Crypto, Altivec).
• AEGIS-256X2: 16 and 32 bytes tags (software, VAES + AVX2, AES-NI, ARM Crypto, Altivec).
• AEGIS-256X4: 16 and 32 bytes tags (software, AVX512, VAES + AVX2, AES-NI, ARM Crypto, Altivec).

Key Capabilities:

• AEGIS-MAC with incremental updates.
• Encryption/decryption with attached or detached tags.
• Incremental encryption and decryption.
• Random-Access File (RAF) API for encrypted filesystems and databases.
• Unauthenticated encryption/decryption (stream cipher mode).
• Deterministic pseudorandom stream generation.

The optional Merkle tree feature maintains a live hash commitment over the entire file's plaintext content. This allows you to generate a single digest representing the current state of the file, useful for remote attestation or detecting out-of-band modifications.

Implementation Details:

• Leaf Hashing: Leaves are derived from your hash_leaf callback over plaintext chunk data (not the AEGIS AEAD tags). To keep hashing stable, depend on chunk, chunk_len, and chunk_idx.
• Configuration: You must provide a aegis_raf_merkle_config containing callbacks for hash_leaf, hash_parent, hash_empty, and hash_commitment.
• Verification: Use aegis128l_raf_merkle_verify() to check for corruption.
• Commitment: Use aegis128l_raf_merkle_commitment() to retrieve the root commitment, which includes the file's content, version, algorithm, chunk size, and identity.

// Provide hash callbacks and a caller-allocated buffer
aegis_raf_merkle_config merkle = {
    .hash_leaf       = my_hash_leaf,       // hash plaintext chunk data (not the RAF auth tag)
    .hash_parent     = my_hash_parent,     // combine two child digests
    .hash_empty      = my_hash_empty,      // digest for missing/empty nodes
    .hash_commitment = my_hash_commitment, // hash(root, ctx, file_size)
    .hash_len        = 32,                 // digest size (8..64 bytes)
    .max_chunks      = 1024,
    .buf             = merkle_buf,
    .len             = sizeof merkle_buf,
};

// Pass merkle config when creating the RAF context
aegis_raf_config cfg = {
    .scratch = &scratch, .chunk_size = 4096,
    .flags = AEGIS_RAF_CREATE, .merkle = &merkle,
};

// After writes, verify Merkle state against current file contents or read the root commitment
aegis128l_raf_merkle_verify(&ctx, &corrupted_chunk);
uint8_t root[32];
aegis128l_raf_merkle_commitment(&ctx, root, sizeof root);

The RAF API allows for working with encrypted files as if they were regular files. It supports reading/writing arbitrary byte ranges, extending, or truncating files without loading the entire file into memory. This is ideal for encrypted filesystems or databases.

Core Components:

• Pluggable I/O: You must provide callbacks for read_at, write_at, get_size, set_size, and sync via an aegis_raf_io struct.
• RNG: You must provide a random number generator callback via aegis_raf_rng.
• Scratch Buffer: To enable zero-allocation operation, callers must provide a scratch buffer via aegis_raf_scratch. The size is determined by AEGIS128L_RAF_SCRATCH_SIZE(chunk_size) (or the variant-specific equivalent).
• Contexts: Use aegis*_raf_create() for new files and aegis*_raf_open() for existing files.

Opening an existing file:

1. Use aegis_raf_probe() to read the file's algorithm ID and chunk size.
2. Allocate a scratch buffer based on the probed chunk_size.
3. Call the appropriate *_raf_open() function.

#include <aegis.h>

// Allocate scratch buffer (can be stack, heap, or static)
CRYPTO_ALIGN(64) uint8_t scratch_buf[AEGIS128L_RAF_SCRATCH_SIZE(4096)];
aegis_raf_scratch scratch = { .buf = scratch_buf, .len = sizeof scratch_buf };

aegis128l_raf_ctx ctx;
aegis_raf_config cfg = { .scratch = &scratch, .chunk_size = 4096, .flags = AEGIS_RAF_CREATE };
aegis_raf_io io = { /* your I/O callbacks */ };
aegis_raf_rng rng = { /* your RNG callback */ };

aegis128l_raf_create(&ctx, &io, &rng, &cfg, master_key);
aegis128l_raf_write(&ctx, &written, data, len, offset);
aegis128l_raf_read(&ctx, &bytes_read, len, offset);
aegis128l_raf_close(&ctx);  // automatically calls sync

AEGIS can function as a standalone Message Authentication Code (MAC). The API supports incremental updates, allowing you to process data in chunks using a state object.

Usage Rules:

• Never use the same key for both MAC and encryption.
• If you need to authenticate multiple messages with the same key, do not re-initialize. Instead, use aegis256_mac_state_clone() to clone the state or aegis256_mac_reset() to reset it.
• A NULL nonce in aegis256_mac_init() results in an all-zero nonce.

#include <aegis.h>
#include <string.h>

int main(void) {
    aegis_init();

    uint8_t key[aegis256_KEYBYTES];
    memset(key, 0x42, sizeof key);

    /* Initialize the MAC state */
    aegis256_mac_state st;
    aegis256_mac_init(&st, key, NULL);

    /* Feed data in chunks */
    aegis256_mac_update(&st, (const uint8_t *) "hello, ", 7);
    aegis256_mac_update(&st, (const uint8_t *) "world", 5);

    /* Finalize and get the tag */
    uint8_t tag[32];
    aegis256_mac_final(&st, tag, sizeof tag);

    return 0;
}

Use the *_encrypt_detached() and *_decrypt_detached() functions when you want the ciphertext and the authentication tag to be stored in separate buffers.

Important:

• The ciphertext buffer must be at least the size of the message.
• The tag buffer must be large enough to hold the authentication tag (e.g., 32 bytes for aegis256).
• aegis256_decrypt_detached() returns a non-zero value if authentication fails (indicating tampering).

All AEGIS variants (e.g., aegis128l_, aegis256_, aegis128x2_) follow this same API pattern; you only need to adjust the prefix and the sizes of the key and nonce.

#include <aegis.h>
#include <string.h>

int main(void) {
    aegis_init();

    uint8_t key[aegis256_KEYBYTES];     /* 32 bytes */
    uint8_t nonce[aegis256_NPUBBYTES];  /* 32 bytes */
    memset(key, 0x42, sizeof key);
    memset(nonce, 0x00, sizeof nonce);

    const char *message = "hello, world";
    size_t message_len = strlen(message);

    uint8_t ciphertext[128]; 
    uint8_t tag[32];         

    /* Encrypt (detached mode) */
    aegis256_encrypt_detached(ciphertext, tag, sizeof tag,
                              (const uint8_t *) message, message_len,
                              NULL, 0,   /* no additional data */
                              nonce, key);

    /* Decrypt and verify */
    uint8_t decrypted[128];

    if (aegis256_decrypt_detached(decrypted, ciphertext, message_len,
                                  tag, sizeof tag,
                                  NULL, 0,
                                  nonce, key) != 0) {
        /* Authentication failed */
        return 1;
    }

    return 0;
}