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 secure, post-quantum AEAD implementations using NIST-approved algorithms. The library emphasizes security-first design with constant-time primitives where implemented and robust input validation.

Features

Quantum-Resistant: Implements NIST-approved post-quantum algorithms
Security-First: Constant-time primitives and robust input validation
High Performance: Optimized implementations with minimal overhead
Modular Design: Pluggable architecture supporting multiple algorithms
Production Ready: Extensive testing and security validation
No-Std Support: Works in embedded and no-std environments

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.

lib-q-aead 0.0.4