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)

SaturninQcb now applies a committing transform (CTX); no other libQ AEAD is key-committing, and none of the rest 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 most of these modes were designed for; outside SaturninQcb, libQ does not provide it.

Do not use any libQ AEAD other than SaturninQcb 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). Even for SaturninQcb, treat this as claimed, not proven: see the table row and the sign-off obligations in lib-q-saturnin/src/commit.rs.

One mode, SaturninShortAead, has a demonstrated break: a test produces one ciphertext that decrypts successfully under two distinct keys. SaturninQcb had a break of the same class; it is retained verbatim as a regression test (lib-q-saturnin/tests/key_commitment.rs) and now fails tag verification on every one of 200 independent instances (see the table). 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.

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. SaturninQcb now has one (above — claimed, and RED pending sign-off); the rest of libQ does not, which is why no other row above reads "committing".

Neither SaturninQcb nor SaturninShortAead 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). Depending on this crate pulls in lib-q-saturnin's qcb feature (default-on) and therefore compiles SaturninQcb's CTX fix transitively, but does not make the type reachable; reaching either mode directly requires depending on lib-q-saturnin itself. The table covers both because they are part of the same suite.

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

# the retained (now-defeated) QCB attack, and the CTX byte-layout / binding gate
cargo test -p lib-q-saturnin --test key_commitment -- --nocapture
cargo test -p lib-q-saturnin --test qcb_ctx_spec -- --nocapture
# the still-live SaturninShortAead break
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/src/commit.rs, lib-q-saturnin/tests/key_commitment.rs, lib-q-saturnin/tests/qcb_ctx_spec.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.