Crate libq

Expand description

lib-Q - Post-Quantum Cryptography Library

A modern, secure cryptography library built exclusively with NIST-approved post-quantum algorithms. Written in Rust with WASM compilation support.

§Architecture Principles

Zero Dynamic Allocations: Stack-only operations for constrained environments
Memory Safety: Automatic zeroization of sensitive data using Zeroize trait
Constant-Time: Operations designed to prevent timing attacks
Post-Quantum Only: NIST-approved algorithms for quantum resistance
Provider Pattern: Pluggable cryptographic implementations
Unified API: Same interface for Rust crate and WASM usage

§Security Features

Four-Tier Security: Level 1 (128-bit), Level 3 (192-bit), Level 4 (256-bit), Level 5 (256-bit+)
Algorithm Diversity: ML-KEM, HQC, ML-DSA, FN-DSA, Saturnin, Romulus (N/M)
Input Validation: Comprehensive validation of all cryptographic inputs
Error Handling: Secure error messages that don’t leak sensitive information
AEAD Layer B: The libq::aead::context() / WASM AEAD context path stays Layer A (Result only). For lib_q_core::AeadDecryptSemantic::decrypt_semantic, depend on concrete types from lib-q-aead, lib-q-saturnin, lib-q-duplex-aead, lib-q-tweak-aead, or lib-q-romulus (see docs/adr/003-aead-decrypt-layers.md).

§Example Usage

use libq::{
    Algorithm,
    HashContext,
    Utils,
    create_hash_context,
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize hash context
    let mut hash_ctx = create_hash_context();

    // Hash data via the umbrella-wired `lib-q-hash` provider
    let result = hash_ctx.hash(Algorithm::Shake256, b"Hello, World!");
    match result {
        Ok(hash) => println!("Hash: {}", Utils::bytes_to_hex(&hash)),
        Err(e) => println!("Hash error: {:?}", e),
    }

    // Generate random bytes
    let random_bytes = Utils::random_bytes(32)?;
    println!("Random bytes: {}", Utils::bytes_to_hex(&random_bytes));

    // Note: Algorithm operations require feature flags:
    // - For ML-DSA signatures: enable 'ml-dsa' feature
    // - For ML-KEM key exchange: enable 'ml-kem' feature
    // - For FN-DSA signatures: enable 'fn-dsa' feature
    // - For AEAD: use `libq::aead::context()` and enable `saturnin`, `romulus`, or other AEAD features

    Ok(())
}

§Feature Flags

std: Enable standard library features (default)
no_std: Marker feature; this crate uses #![no_std] when std is off, but path dependencies may still enable std (see crate README). For embedded builds, prefer leaf crates (lib-q-core, lib-q-kem, …) with --no-default-features and alloc.
wasm: Enable WebAssembly compilation support
ml-kem: Enable ML-KEM key encapsulation mechanism
ml-dsa: Enable ML-DSA digital signature algorithm
slh-dsa: Enable SLH-DSA (FIPS 205) algorithm metadata and shared types in lib-q-core
fn-dsa: Enable FN-DSA digital signature algorithm
saturnin: Enable Saturnin authenticated encryption
romulus: Enable Romulus-N and Romulus-M AEAD (LWC / SKINNY-128-384+)
hqc: Enable HQC key encapsulation mechanism (HQC-128 / HQC-192 / HQC-256)
random: Enable lib-q-random for secure random number generation
random-custom-entropy: Enable custom entropy source support
all-algorithms: Enable all available algorithms
zkp: Expose zero-knowledge / STARK API under libq::zkp (STARK core is always linked)
zkp-plonky / zkp-plonky-*: Add the Plonky3-derived STARK stack under libq::zkp::plonky
zkp-parallel: Rayon-backed parallel proving (STARK)
zkp-recursive-experimental: Experimental recursive proof Merkle path (STARK)
security-hardened: Enable comprehensive security features

§Security Considerations

This library is designed with security as the primary concern:

All sensitive data is automatically zeroized when dropped
Operations are designed to be constant-time where possible
Input validation is comprehensive and secure
Error messages don’t leak sensitive information
Memory allocations are minimized for constrained environments

§WASM Support

The library can be compiled to WebAssembly for use in web applications:

wasm-pack build --target web --out-dir pkg

For getrandom on wasm32-unknown-unknown, use the same flags as CI: CARGO_TARGET_WASM32_UNKNOWN_UNKNOWN_RUSTFLAGS='--cfg getrandom_backend="wasm_js" -C panic=abort'.

This provides a JavaScript API that mirrors the Rust API where wasm-bindgen is enabled.

Modules§

aead: AEAD backed by lib-q-aead (SHAKE256-AEAD and feature-gated algorithms).
wasm: WebAssembly bindings for lib-Q
zkp: Zero-knowledge proof types and functions.

Structs§

AeadContext: AEAD context for authenticated encryption operations
CoreLibQCryptoProvider: Main lib-Q cryptographic provider
CustomEntropyConfig: Custom entropy source configuration
CustomEntropySource: Custom entropy source registration
EntropyContext: Context data for entropy callbacks
EntropyQuality: Entropy quality assessment result
EntropyValidator: Comprehensive entropy validator
HashContext: Hash context for hash operations
KemContext: KEM context for key encapsulation operations
LibQCbKemProvider: lib-Q Classical McEliece KEM provider implementation
LibQCryptoProvider: Main lib-Q cryptographic provider
LibQHashProvider: lib-Q hash provider implementation
LibQHqcProvider: HQC provider for libQ integration
LibQKemProvider: lib-Q KEM provider implementation
LibQRng: Main libQ random number generator
LibQSignatureProvider: lib-Q signature provider implementation
SecurityValidator: Centralized security validator for lib-Q
SignatureContext: Signature context for digital signature operations
Utils: The core API provides a clean interface that:

Enums§

Algorithm: Algorithm identifiers for cryptographic operations
AlgorithmCategory: Algorithm categories
CustomEntropyQuality: Entropy source quality levels
DecryptSemanticOutcome: Semantic result of an AEAD decrypt after parseable inputs were accepted.
Error: The error type for lib-Q operations
SecurityLevel: Security levels for cryptographic algorithms

Constants§

VERSION

Traits§

AeadDecryptSemantic: AEAD implementations that expose a semantic decrypt API (Layer B).

Functions§

algorithms_by_category: Get algorithms by category
algorithms_by_security_level: Get algorithms by security level
available_algorithms: Get available KEM algorithms (no_std version)
create_hash_context: Create a HashContext with LibQHashProvider installed.
create_kem_context: Create a new KEM context
create_signature: Legacy boxed Signature factory (std only; matches lib-q-sig / Box<dyn Signature>). Create a signature instance by algorithm name (legacy compatibility)
create_signature_context: Create a SignatureContext with LibQSignatureProvider already installed (ML-DSA and SLH-DSA from lib-q-sig defaults; FN-DSA when the fn-dsa feature is enabled on this crate).
get_custom_entropy_source_info: Get information about the currently registered entropy source
has_custom_entropy_source: Check if a custom entropy source is currently registered
init: Initialize the core library
new_custom_rng: Create a new RNG with custom entropy source
new_deterministic_rng: Create a new deterministic RNG instance
new_secure_rng: Create a new secure RNG instance
register_custom_entropy_source^⚠: Register a custom entropy source for the current thread
sig_available_algorithms: Get available signature algorithms with proper NIST naming
supported_algorithms: Get all supported algorithms
unregister_custom_entropy_source: Unregister the current custom entropy source
version: Get library version information

Type Aliases§

Result: Result type for lib-Q operations

Crate libq

Crate libq Copy item path

§Architecture Principles

§Security Features

§Example Usage

§Feature Flags

§Security Considerations

§WASM Support

Modules§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Crate libq