lib-q-aead

A high-performance, quantum-resistant Authenticated Encryption with Associated Data (AEAD) library for Rust, designed for the libQ cryptographic ecosystem.

Overview

lib-q-aead provides AEAD implementations chosen for large-state, quantum-resistant security margins. The library emphasizes security-first design with constant-time primitives where implemented and robust input validation.

None of these AEAD modes is NIST-approved. NIST's approved AEADs are AES-GCM and AES-CCM (SP 800-38D / SP 800-38C) and Ascon (SP 800-232); this crate ships none of them. Of the seven modes registered here, Saturnin and Romulus were NIST Lightweight Cryptography candidates that were not selected (Ascon won), Rocca-S is an IETF draft (draft-nakano-rocca-s), and the SHAKE256, duplex-sponge, and tweakable-CTR modes are libQ constructions over the FIPS 202 Keccak-f[1600] permutation. The permutation is NIST-standardized in those three cases; the AEAD mode built on it is not. Treat every algorithm here as pre-standard for compliance purposes.

Features

• Large-state symmetric security: 256-bit keys and 256-bit tags, chosen for margin against Grover-style key search — except Romulus-N/M, which are 128-bit in both (measured: cargo test -p lib-q-aead --features romulus-n,romulus-m --test nonce_misuse all_registry_aeads_take_a_128_bit_nonce -- --nocapture prints RomulusNAead: key 16 B, nonce 16 B, tag 16 B)
• Security-First: Constant-time primitives and robust input validation
• High Performance: Optimized implementations with minimal overhead
• Modular Design: Pluggable architecture supporting multiple algorithms
• No-Std Support: Works in embedded and no-std environments

Read Key commitment (CMT-1) below before using any mode for key wrapping, envelope encryption, or multi-recipient encryption — these AEADs are not key-committing.

Supported Algorithms

SHAKE256 AEAD

• Algorithm: SHAKE256-based AEAD construction
• Security Level: 128-bit post-quantum security
• Key Size: 256 bits (32 bytes)
• Nonce Size: 128 bits (16 bytes)
• Tag Size: 256 bits (32 bytes)

Saturnin AEAD

• Algorithm: Saturnin block cipher in AEAD mode
• Security Level: 128-bit post-quantum security
• Key Size: 256 bits (32 bytes)
• Nonce Size: 128 bits (16 bytes)
• Tag Size: 256 bits (32 bytes) (full Saturnin AEAD; matches lib-q-saturnin::SaturninAead)

Semantic decrypt (Layer B)

Factory-returned handles use the Layer A decrypt → Result path via lib-q-core traits and contexts. The concrete registry types in this crate (SaturninAead, Shake256Aead, DuplexSpongeAead, TweakAead, RomulusNAead, RomulusMAead) implement lib_q_core::AeadDecryptSemantic where the underlying algorithm does—call decrypt_semantic on those concrete types (not on Box<dyn AeadWithMetadata>). Discoverability: AeadMetadata::supports_semantic_decrypt and AeadWithMetadata::supports_semantic_decrypt report whether Layer B is available for the canonical algorithm row; registry test stubs override the trait method to false (see docs/adr/003-aead-decrypt-layers.md). Test-only MockAead in plugin.rs tests is Layer A + metadata only.

Quick Start

Basic Usage

use lib_q_aead::{create_aead, Algorithm, AeadKey, Nonce};

// Create an AEAD instance
let aead = create_aead(Algorithm::Shake256Aead)?;

// Generate or load your key and nonce
let key = AeadKey::new(vec![0x01; 32]); // In practice, use secure random generation
let nonce = Nonce::new(vec![0x02; 16]); // In practice, use secure random generation

// Your data to encrypt
let plaintext = b"Hello, World!";
let associated_data = b"metadata";

// Encrypt
let ciphertext = aead.encrypt(&key, &nonce, plaintext, Some(associated_data))?;

// Decrypt
let decrypted = aead.decrypt(&key, &nonce, &ciphertext, Some(associated_data))?;

assert_eq!(decrypted, plaintext);

Advanced Usage with Security Configuration

use lib_q_aead::{
    create_aead, Algorithm, AeadKey, Nonce,
    security::{SecurityConfig, SecurityContext}
};

// Create AEAD with custom security configuration
let aead = create_aead(Algorithm::Shake256Aead)?;

// Configure security settings
let security_config = SecurityConfig::strict();
let security_ctx = SecurityContext::with_config(security_config);

// Security context can be used to track operation metadata
let key = AeadKey::new(secure_random_bytes(32));
let nonce = Nonce::new(secure_random_bytes(16));

let ciphertext = aead.encrypt(&key, &nonce, plaintext, Some(associated_data))?;

Security Features

Constant-Time Operation Wrapper

The timing module enforces a fixed wall-clock duration for wrapped operations, preventing timing side-channels from leaking information about internal control flow. The wrapper uses compiler_fence(SeqCst) and core::hint::black_box to prevent the compiler from eliding the busy-wait or reordering results past the timing barrier.

use lib_q_aead::security::timing::{TimingProtection, protect_timing};

// Wrap an operation so it always takes at least target_duration_ns
let result = protect_timing(|| {
    perform_sensitive_operation()
})?;

// Custom target duration (5 µs)
let timing_protection = TimingProtection::strict();
let result = timing_protection.protect(|| {
    perform_sensitive_operation()
})?;

Constant-Time Operations

All critical operations are implemented in constant time:

use lib_q_aead::security::constant_time::constant_time_eq;

// Secure comparison
let is_equal = constant_time_eq(&tag1, &tag2);

// Secure selection
let result = constant_time_select(condition, &value1, &value2);

Input Validation

Comprehensive input validation prevents common security issues:

use lib_q_aead::security::validation::{validate_key, validate_nonce};

// Validate key material
validate_key(key_bytes)?;

// Validate nonce
validate_nonce(nonce_bytes)?;

Performance

The library is optimized for high performance while maintaining security:

• SHAKE256 AEAD: ~2-5μs per operation (typical)
• Saturnin AEAD: ~1-3μs per operation (typical)
• Memory Usage: Minimal stack allocation with secure cleanup
• Constant-Time Wrapper: Fixed wall-clock overhead per protected call

Feature Flags

• shake256: Enable SHAKE256 AEAD implementation (default)
• saturnin: Enable Saturnin AEAD implementation
• std: Enable standard library features (default)
• no-std: Disable standard library for embedded environments

Security Considerations

Key Management

• Always use cryptographically secure random number generation for keys
• Never reuse keys across different contexts
• Implement proper key rotation policies

Nonce Management

• Never reuse nonces with the same key
• Use cryptographically secure random number generation for nonces
• Consider using counter-based nonces for high-throughput scenarios

Timing Attacks

• The TimingProtection wrapper enforces a fixed wall-clock duration per call, preventing timing side-channels at the API boundary
• Set target_duration_ns above the worst-case execution time of the wrapped operation
• Constant-time algorithmic behavior (e.g. constant-time comparisons via subtle) is still required at the primitive level

Examples

See the examples/ directory for comprehensive usage examples:

• basic_usage.rs: Basic encryption/decryption
• security_features.rs: Advanced security features
• performance_benchmarks.rs: Performance testing
• no_std_example.rs: Embedded usage

Testing

The library includes comprehensive tests:

# Run all tests
cargo test

# Run security tests
cargo test --test comprehensive_security_tests

# Run performance benchmarks
cargo bench

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Security

For security issues, please see the main libQ repository's security policy.

Workspace

Exposes Saturnin and SHAKE-based AEAD integrations for lib-q-hpke and the umbrella stack. See the workspace README for the full crate graph.

Key commitment (CMT-1)

No libQ AEAD is key-committing, and none of them claims to be. CMT-1 asks whether one ciphertext can be made to decrypt successfully under two distinct keys, with the nonce and associated data free on each side. That property is not part of the AEAD security goal these modes were designed for, and libQ does not provide it.

Do not use any libQ AEAD for multi-recipient encryption, key wrapping / envelope encryption, or password-based decryption as an identification or authorization signal without binding the key externally — e.g. put H(key ‖ context) in the associated data, or carry an explicit key commitment beside the ciphertext (lib-q-mve does the latter: see MVE_COMMIT_LABEL).

Two modes have a demonstrated break: a test produces one ciphertext that decrypts successfully under two distinct keys. For the other seven a bounded search found nothing, which is not evidence that they commit — read the box under the table before quoting any row of it.

| Mode | Key / tag | CMT-1 status | |---|---|---| | SaturninQcb | 256 / 256-bit | BROKEN. Cheap search then closed-form algebra. Measured over 200 independent key pairs, all of which broke: mean 249 padding-search tries ≈ ~500 Saturnin block calls (median 201, min 1, max 1316), and 0 searches of the 256-bit tag. Cause: associated data enters the tag by plain XOR through a public keyed permutation, so side 2's associated data is solved, not searched. | | SaturninShortAead | 256-bit / no tag | BROKEN. ~2^8 random keys at any nonce length, including the 16-byte default — the nonce is the redundancy and CMT-1 lets the adversary choose it. Measured acceptance 78 / 20 000 random keys (0.0039, predicted 2^-8). | | SaturninAead (CTR-Cascade) | 256 / 256-bit | no cheap break found — not shown to commit | | Shake256Aead | 256 / 256-bit | no cheap break found — not shown to commit | | DuplexSpongeAead | 256 / 256-bit | no cheap break found — not shown to commit | | TweakAead | 256 / 256-bit | no cheap break found — not shown to commit. Its tag is a sponge hash of key ‖ nonce ‖ ad ‖ ct, which is the shape a committing mode has; that is an argument for looking here first, not a result. | | RoccaSAead | 256 / 256-bit | no cheap break found — not shown to commit | | RomulusN / RomulusM | 128 / 128-bit | no cheap break found — not shown to commit. With a 128-bit tag the generic CMT-1 cost is only ~2^64, the weakest margin in the set. |

The "no cheap break found" rows are not evidence of key commitment and must never be quoted as if they were. Each comes from 20 000 random (key, nonce, associated-data) trials against a fixed ciphertext. Against a 256-bit tag the expected yield of that search is ~2^-242 hits, so it returns zero whether or not the mode commits — and it would return zero just the same against a mode with a 2^40 structural break the search does not model. All those rows rule out is the class of break the two Saturnin modes fell into: one cheap enough for ~2^14 trials to stumble onto.

Demonstrating the positive — that a mode is committing — is not achievable by search at these tag sizes at all, however many trials are run. It needs a proof, or a committing transform (bind H(key ‖ nonce ‖ associated data) into the tag) that changes the construction. libQ has neither, which is why no row above reads "committing".

Neither broken mode is reachable through this crate. lib-q-aead's registry exposes Shake256Aead, SaturninAead, DuplexSpongeAead, TweakAead, RomulusNAead, RomulusMAead and RoccaSAead — it never re-exports SaturninQcb or SaturninShortAead (verified: rg -n "Qcb|qcb" lib-q-aead/src returns nothing, while rg -c "Saturnin" lib-q-aead/src matches six files). Reaching either break requires depending on lib-q-saturnin directly; the table covers them because they are part of the same suite and the two rows are the only demonstrated results in it.

Reproduce (each prints its own measurements with --nocapture):

# the two breaks, and the measured QCB attack cost
cargo test -p lib-q-saturnin --test key_commitment -- --nocapture
cargo test -p lib-q-saturnin --features aead-short --lib key_commitment_tests -- --nocapture
# the bounded searches for the registry modes
cargo test -p lib-q-aead \
  --features "saturnin,duplex-sponge-aead,tweak-aead,romulus-n,romulus-m,rocca-s" \
  --test key_commitment -- --nocapture

Sources: lib-q-saturnin/tests/key_commitment.rs, lib-q-saturnin/src/aead_short.rs (key_commitment_tests), lib-q-aead/tests/key_commitment.rs. Card t_16ddf21c.

Nonce extension (XChaCha-style) — evaluated and deliberately not pursued

Every libQ AEAD uses a 128-bit nonce. XChaCha20-Poly1305 exists to stretch a 96-bit nonce to 192 bits so that random nonces stop colliding around 2^32 messages per key; at 128 bits the birthday bound is already 2^64, beyond any realistic message volume. Nonce extension therefore buys nothing here and is not planned — please do not re-raise it. The adjacent gap that is real is key and context commitment, above.

Subresource integrity (SHA-384)

Paths in integrity-manifest.json are relative to the package root (including web/ and nodejs/ when both ship).