Crate lib_q_sig

Expand description

lib-Q SIG - Post-quantum Digital Signatures

This crate provides implementations of post-quantum digital signature schemes following the lib-Q architecture with proper security validation and provider pattern integration.

§Architecture

This implementation follows the lib-Q provider pattern:

Provider Pattern: Implements SignatureOperations trait for integration with lib-q-core
Security Validation: Comprehensive input validation and security checks using SecurityValidator
Algorithm Support: Full support for NIST-approved signature algorithms
Memory Safety: Automatic zeroization of sensitive data with secure memory management
no_std Support: Works in constrained environments with external randomness
Context Integration: Seamless integration with SignatureContext for unified API

§Supported Algorithms

ML-DSA: CRYSTALS-ML-DSA (Levels 1, 3, 4)
- ML-DSA-44: Level 1 security (128-bit)
- ML-DSA-65: Level 3 security (192-bit)
- ML-DSA-87: Level 4 security (256-bit)
FN-DSA: FIPS 206 FN-DSA (Levels 1, 5)
- FN-DSA: Level 1 security (128-bit)
- FN-DSA-512: Level 1 security (128-bit)
- FN-DSA-1024: Level 5 security (256-bit)
SLH-DSA: SPHINCS+ (Levels 1, 3, 5)
- SLH-DSA-SHA256-128f-Robust: Level 1 security (128-bit)
- SLH-DSA-SHA256-192f-Robust: Level 3 security (192-bit)
- SLH-DSA-SHA256-256f-Robust: Level 5 security (256-bit)
- SLH-DSA-SHAKE256-128f-Robust: Level 1 security (128-bit)
- SLH-DSA-SHAKE256-192f-Robust: Level 3 security (192-bit)
- SLH-DSA-SHAKE256-256f-Robust: Level 5 security (256-bit)

§Feature Support

All signature algorithms support:

no_std: Works in constrained environments with external randomness
WASM: JavaScript-compatible bindings for web environments
Security validation: Comprehensive input validation and security checks
Memory safety: Automatic zeroization of sensitive data
Provider integration: Full integration with lib-q-core provider system

§SLH-DSA features and tests

slh-dsa: SLH-DSA with caller-supplied randomness (e.g. generate_keypair_with_randomness, provider calls with Some(&buf)). This is the integration surface for no_std and embedder-provided entropy.
slh-dsa-std: Adds lib-q-random / std so APIs that take optional randomness can use None as “OS-backed RNG” on typical std targets. Integration tests that exercise that implicit-RNG path are gated on this feature.

cargo test -p lib-q-sig --features slh-dsa
cargo test -p lib-q-sig --features slh-dsa-std

§Usage

§With std (automatic randomness)

use lib_q_core::{
    Algorithm,
    SignatureContext,
    create_signature_context,
};
use lib_q_sig::LibQSignatureProvider;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create signature context with provider
    let mut ctx = create_signature_context();
    ctx.set_provider(Box::new(LibQSignatureProvider::new()?));

    // Generate keypair (requires std feature for automatic randomness)
    let keypair = ctx.generate_keypair(Algorithm::MlDsa65, None)?;

    // Sign message
    let message = b"Hello, lib-Q!";
    let signature =
        ctx.sign(Algorithm::MlDsa65, keypair.secret_key(), message, None)?;

    // Verify signature
    let is_valid = ctx.verify(
        Algorithm::MlDsa65,
        keypair.public_key(),
        message,
        &signature,
    )?;
    assert!(is_valid);
    Ok(())
}

§Without std (external randomness)

use lib_q_core::{
    Algorithm,
    SignatureContext,
    create_signature_context,
};
use lib_q_sig::LibQSignatureProvider;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create signature context with provider
    let mut ctx = create_signature_context();
    ctx.set_provider(Box::new(LibQSignatureProvider::new()?));

    // Provide randomness externally (required in no_std environments)
    let key_randomness = [0u8; 32]; // Get from hardware RNG
    let signing_randomness = [0u8; 32]; // Get from hardware RNG

    // Generate keypair with external randomness
    let keypair =
        ctx.generate_keypair(Algorithm::MlDsa65, Some(&key_randomness))?;

    // Sign message with external randomness
    let message = b"Hello, lib-Q!";
    let signature = ctx.sign(
        Algorithm::MlDsa65,
        keypair.secret_key(),
        message,
        Some(&signing_randomness),
    )?;

    // Verify signature
    let is_valid = ctx.verify(
        Algorithm::MlDsa65,
        keypair.public_key(),
        message,
        &signature,
    )?;
    assert!(is_valid);
    Ok(())
}

§WASM (JavaScript) Environment

use js_sys::Uint8Array;
use lib_q_sig::ml_dsa::MlDsa;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create ML-DSA instance
    let ml_dsa = MlDsa::ml_dsa_65();

    // Generate keypair (with optional randomness)
    let keypair = ml_dsa.generate_keypair_wasm(None)?;

    // Sign message
    let message = Uint8Array::from(b"Hello, WASM!");
    let signature =
        ml_dsa.sign_wasm(keypair.secret_key(), message, None)?;

    // Verify signature
    let is_valid =
        ml_dsa.verify_wasm(keypair.public_key(), message, signature)?;
    assert!(is_valid);
    Ok(())
}

§Provider Pattern Integration

The LibQSignatureProvider implements the SignatureOperations trait and integrates seamlessly with the lib-q-core provider system:

use lib_q_core::{
    Algorithm,
    SignatureContext,
    create_signature_context,
};
use lib_q_sig::LibQSignatureProvider;

fn example() -> Result<(), Box<dyn std::error::Error>> {
    // Create provider and integrate with context
    let provider = LibQSignatureProvider::new()?;
    let mut ctx = create_signature_context();
    ctx.set_provider(Box::new(provider));

    // All operations go through the provider with security validation
    let keypair = ctx.generate_keypair(Algorithm::MlDsa65, None)?;
    let signature = ctx.sign(
        Algorithm::MlDsa65,
        keypair.secret_key(),
        b"message",
        None,
    )?;
    let is_valid = ctx.verify(
        Algorithm::MlDsa65,
        keypair.public_key(),
        b"message",
        &signature,
    )?;
    Ok(())
}

§Security Features

The implementation includes comprehensive security measures:

Input Validation: All inputs are validated for correctness and security
Memory Safety: Sensitive data is automatically zeroized after use
Algorithm Validation: Only NIST-approved algorithms are supported
Key Size Validation: Keys are validated against expected sizes for each algorithm
Randomness Validation: Randomness inputs are validated for quality and size
Error Handling: Secure error messages that don’t leak sensitive information

§Feature Flags

ml-dsa: Enable ML-DSA signature algorithms
fn-dsa: Enable FN-DSA signature algorithms
slh-dsa: Enable SLH-DSA signature algorithms
std: Enable standard library features (automatic randomness generation)
alloc: Enable heap allocation (required for most operations)
wasm: Enable WebAssembly bindings for JavaScript environments

Re-exports§

pub use provider::LibQSignatureProvider;

Modules§

fn_dsa: FN-DSA (FIPS 206) Post-Quantum Digital Signatures
ml_dsa: CRYSTALS-ML-DSA implementation
provider: lib-Q Signature Provider Implementation
slh_dsa: SLH-DSA (SPHINCS+) implementation for lib-Q

Structs§

SigKeypair: Signature keypair with automatic memory zeroization
SigPublicKey: Signature public key
SigSecretKey: Signature secret key with automatic memory zeroization
SignatureContext: Signature context for digital signature operations

Enums§

Algorithm: Algorithm identifiers for cryptographic operations
AlgorithmCategory: Algorithm categories
Error: The error type for lib-Q operations

Traits§

Signature: Trait for digital signatures
SignatureOperations: Digital Signature operations

Functions§

available_algorithms: Get available signature algorithms with proper NIST naming
create_signature: Create a signature instance by algorithm name (legacy compatibility)
create_signature_context: Create a signature context for the specified algorithm

Type Aliases§

Result: Result type for lib-Q operations

Crate lib_q_sig

Crate lib_q_sig Copy item path

§Architecture

§Supported Algorithms

§Feature Support

§SLH-DSA features and tests

§Usage

§With std (automatic randomness)

§Without std (external randomness)

§WASM (JavaScript) Environment

§Provider Pattern Integration

§Security Features

§Feature Flags

Re-exports§

Modules§

Structs§

Enums§

Traits§

Functions§

Type Aliases§

Crate lib_q_sig