Crate lib_q_cb_kem 

lib-Q Classical McEliece KEM - Post-quantum Key Encapsulation Mechanism

This crate provides a pure Rust implementation of the Classical McEliece KEM 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 KemOperations trait for integration with lib-q-core
• Security Validation: Comprehensive input validation and security checks
• Algorithm Support: Full support for NIST-approved Classical McEliece variants
• Memory Safety: Automatic zeroization of sensitive data
• no_std Support: Works in constrained environments

Supported Algorithms

• Classical McEliece: All NIST-approved variants (348864, 460896, 6688128, 6960119, 8192128)
• Hash Functions: SHA3 (SHAKE256) support

Feature Support

All KEM 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
• Hash function: SHA3 (SHAKE256) hash function

Usage

With libQ Integration

use lib_q_core::{Algorithm, KemContext, create_kem_context};
use lib_q_cb_kem::LibQCbKemProvider;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create KEM context with Classical McEliece provider
    let mut ctx = create_kem_context();
    ctx.set_provider(Box::new(LibQCbKemProvider::new()?));

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

    // Encapsulate shared secret
    let (ciphertext, shared_secret) = ctx.encapsulate(Algorithm::CbKem348864, &keypair.public_key, None)?;

    // Decapsulate shared secret
    let decapsulated_secret = ctx.decapsulate(Algorithm::CbKem348864, &keypair.secret_key, &ciphertext)?;
    assert_eq!(shared_secret, decapsulated_secret);
    Ok(())
}

Direct Usage (no_std compatible)

use lib_q_cb_kem::{keypair, encapsulate, decapsulate, LibQRng};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create deterministic RNG for testing (use hardware RNG in production)
    let mut rng = LibQRng::new_deterministic(0x0102030405060708);

    // Generate keypair
    let (public_key, secret_key) = keypair(&mut rng);

    // Encapsulate shared secret
    let (ciphertext, shared_secret) = encapsulate(&public_key, &mut rng);

    // Decapsulate shared secret
    let decapsulated_secret = decapsulate(&secret_key, &ciphertext);
    assert_eq!(shared_secret.as_ref(), decapsulated_secret.as_ref());
    Ok(())
}

Structs

AesStatenist-aes-rng

NIST SP 800-90A Rev. 1 CTR_DRBG (AES-256, no derivation function).

Ciphertext

The ciphertext computed by the encapsulator.

LibQCbKemProvideralloc

lib-Q Classical McEliece KEM provider implementation

LibQRng

Classical McEliece compatible RNG

PublicKey

A Classic McEliece public key. These are very large compared to keys in most other cryptographic algorithms.

SecretKey

A Classic McEliece secret key.

SharedSecret

The shared secret computed by the KEM. Returned from both the encapsulator and decapsulator.

Enums

NistDrbgErrornist-aes-rng

Errors from the NIST CTR_DRBG implementation.

Constants

CRYPTO_BYTES

The number of bytes required to store the shared secret negotiated between both parties

CRYPTO_CIPHERTEXTBYTES

The number of bytes required to store the ciphertext resulting from the encryption

CRYPTO_PRIMITIVE

Name of the variant

CRYPTO_PUBLICKEYBYTES

The number of bytes required to store the public key

CRYPTO_SECRETKEYBYTES

The number of bytes required to store the secret key

MAX_BYTES_PER_REQUESTnist-aes-rng

NIST SP 800-90A: max number of bytes per generate request (2^19 bits).

RESEED_INTERVALnist-aes-rng

NIST SP 800-90A: maximum number of generate requests between reseeds.

SEEDLENnist-aes-rng

NIST SP 800-90A Table 3 (AES-256): seed length in bytes.

Functions

decapsulate

KEM Decapsulation.

decapsulate_boxedalloc

Convenient wrapper around decapsulate that stores the shared secret on the heap and returns it with the 'static lifetime.

encapsulate

KEM Encapsulation.

encapsulate_boxedalloc

Convenient wrapper around encapsulate that stores the shared secret on the heap and returns it with the 'static lifetime.

keypair

KEM Keypair generation.

keypair_boxedalloc

Convenient wrapper around keypair that stores the public and private keys on the heap and returns them with the 'static lifetime.