latticearc

Post-quantum cryptography library for Rust with unified API.

Why LatticeArc?

Overview

LatticeArc provides post-quantum cryptographic primitives implementing NIST FIPS 203-206 standards:

• ML-KEM (FIPS 203) - Key encapsulation
• ML-DSA (FIPS 204) - Digital signatures
• SLH-DSA (FIPS 205) - Hash-based signatures
• FN-DSA (FIPS 206) - Lattice signatures
• Hybrid encryption - PQC + classical for defense-in-depth
• TLS 1.3 - Post-quantum TLS integration

Unified API

LatticeArc uses a consistent builder pattern across all APIs:

// Crypto operations use CryptoConfig
CryptoConfig::new()
    .use_case(UseCase::FileStorage)
    .session(&session)

// TLS configuration uses TlsConfig
TlsConfig::new()
    .use_case(TlsUseCase::WebServer)
    .with_fallback(true)

Both APIs share the same intuitive pattern:

• ::new() creates defaults
• .use_case() selects algorithm by scenario
• .security_level() selects algorithm by security level

Quick Start

Add to your Cargo.toml:

[dependencies]
latticearc = "0.4"

Digital Signatures

use latticearc::{generate_signing_keypair, sign_with_key, verify, CryptoConfig};

// Generate signing keypair (defaults: ML-DSA-65 + Ed25519)
let config = CryptoConfig::new();
let (pk, sk, _scheme) = generate_signing_keypair(config.clone())?;

// Sign
let signed = sign_with_key(b"important document", &sk, &pk, config.clone())?;

// Verify
let is_valid = verify(&signed, config)?;

Encryption

use latticearc::{encrypt, decrypt, EncryptKey, DecryptKey, CryptoConfig, CryptoScheme};

let key = [0u8; 32];  // 256-bit key
let config = CryptoConfig::new().force_scheme(CryptoScheme::Symmetric);
let encrypted = encrypt(b"secret message", EncryptKey::Symmetric(&key), config)?;
let decrypted = decrypt(&encrypted, DecryptKey::Symmetric(&key), CryptoConfig::new())?;

With Use Case Selection

use latticearc::{generate_signing_keypair, sign_with_key, CryptoConfig, UseCase};

// Library auto-selects optimal algorithm
let config = CryptoConfig::new().use_case(UseCase::FinancialTransactions);
let (pk, sk, _scheme) = generate_signing_keypair(config.clone())?;
let signed = sign_with_key(b"financial data", &sk, &pk, config)?;

With Security Level

use latticearc::{generate_signing_keypair, sign_with_key, CryptoConfig, SecurityLevel};

// Maximum security (ML-DSA-87 + Ed25519)
let config = CryptoConfig::new().security_level(SecurityLevel::Maximum);
let (pk, sk, _scheme) = generate_signing_keypair(config.clone())?;
let signed = sign_with_key(b"classified", &sk, &pk, config)?;

Key Generation

use latticearc::generate_keypair;

// Generate Ed25519 keypair
let (public_key, private_key) = generate_keypair()?;

Hybrid Encryption

use latticearc::{generate_hybrid_keypair, encrypt, decrypt, EncryptKey, DecryptKey, CryptoConfig};

// Generate hybrid keypair (ML-KEM-768 + X25519)
let (pk, sk) = generate_hybrid_keypair()?;

// Encrypt using hybrid KEM (ML-KEM + X25519 + HKDF + AES-256-GCM)
let encrypted = encrypt(b"sensitive data", EncryptKey::Hybrid(&pk), CryptoConfig::new())?;

// Decrypt
let plaintext = decrypt(&encrypted, DecryptKey::Hybrid(&sk), CryptoConfig::new())?;

Hybrid Signatures

use latticearc::{generate_hybrid_signing_keypair, sign_hybrid, verify_hybrid_signature, SecurityMode};

// Generate hybrid signing keypair (ML-DSA-65 + Ed25519)
let (pk, sk) = generate_hybrid_signing_keypair(SecurityMode::Unverified)?;

// Sign (both ML-DSA and Ed25519)
let signature = sign_hybrid(b"document", &sk, SecurityMode::Unverified)?;

// Verify (both must pass)
let valid = verify_hybrid_signature(b"document", &signature, &pk, SecurityMode::Unverified)?;

With Zero Trust Session

For high-security environments with session-based verification:

use latticearc::{generate_signing_keypair, sign_with_key, verify, generate_keypair, CryptoConfig, VerifiedSession};

// Establish verified session
let (public_key, private_key) = generate_keypair()?;
let session = VerifiedSession::establish(&public_key, private_key.as_ref())?;

// Operations with session verification
let config = CryptoConfig::new().session(&session);
let (pk, sk, _scheme) = generate_signing_keypair(config.clone())?;
let signed = sign_with_key(b"authenticated message", &sk, &pk, config.clone())?;
let is_valid = verify(&signed, config)?;

Post-Quantum TLS

Native PQ key exchange via rustls 0.23.37+ (no extra dependencies):

use latticearc::tls::{TlsConfig, TlsUseCase};
use latticearc::SecurityLevel;

// Default: Hybrid mode (X25519MLKEM768 with X25519 fallback)
let config = TlsConfig::new();

// By use case
let config = TlsConfig::new().use_case(TlsUseCase::WebServer);

// By security level
let config = TlsConfig::new().security_level(SecurityLevel::Maximum);

Available key exchange groups: X25519MLKEM768 (hybrid, default), SECP256R1MLKEM768 (hybrid), MLKEM768 (PQ-only), MLKEM1024 (PQ-only), X25519 (classical fallback).

Low-Level Primitives

For direct access to NIST algorithms:

use latticearc::primitives::kem::ml_kem::{MlKem, MlKemSecurityLevel};
use rand::rngs::OsRng;

let mut rng = OsRng;
let (pk, sk) = MlKem::generate_keypair(&mut rng, MlKemSecurityLevel::MlKem768)?;
let (shared_secret, ciphertext) = MlKem::encapsulate(&mut rng, &pk)?;
let recovered = MlKem::decapsulate(&sk, &ciphertext)?;

Included Features

All features are included by default:

• Post-quantum KEM (ML-KEM-512/768/1024)
• Post-quantum signatures (ML-DSA, SLH-DSA, FN-DSA)
• Hybrid encryption (PQC + classical)
• Zero-knowledge proofs (Schnorr, Pedersen)
• TLS 1.3 integration
• Use case-based scheme selection
• Portable key format (JSON + CBOR) with UseCase/SecurityLevel-first design

Key Serialization

Keys are serialized using the LatticeArc Portable Key (LPK) format — dual JSON + CBOR encoding identified by use case or security level. See docs/KEY_FORMAT.md.

use latticearc::{PortableKey, KeyData, KeyType, UseCase};

// Generate → wrap → serialize → deserialize → use
let (pk, sk) = latticearc::generate_hybrid_keypair()?;
let (portable_pk, portable_sk) =
    PortableKey::from_hybrid_kem_keypair(UseCase::FileStorage, &pk, &sk)?;

// JSON for files/REST, CBOR for wire/storage
let json = portable_pk.to_json()?;
let cbor = portable_pk.to_cbor()?;

// Reconstruct for crypto operations
let restored_pk = PortableKey::from_json(&json)?.to_hybrid_public_key()?;

Algorithm Selection

By Use Case

By Security Level

For complete security level documentation, see the API Reference.

Runnable Examples

The latticearc crate includes comprehensive examples:

• basic_encryption.rs - Simple symmetric encryption with AES-256-GCM
• digital_signatures.rs - Digital signatures with ML-DSA and hybrid modes
• hybrid_encryption.rs - Hybrid encryption (ML-KEM + X25519 + HKDF)
• post_quantum_signatures.rs - Post-quantum signature schemes
• complete_secure_workflow.rs - End-to-end secure workflow with Zero Trust
• zero_knowledge_proofs.rs - Zero-knowledge proof demonstrations

Run an example with:

cargo run --example basic_encryption
cargo run --example digital_signatures

Security

• No unsafe code
• Constant-time operations
• Automatic secret zeroization
• CAVP test vector validation

Documentation

• API Reference

License

Apache-2.0

Contributing

See CONTRIBUTING.md in the repository root.