Crate saorsa_pqc

Expand description

§Saorsa Post-Quantum Cryptography Library

A comprehensive, production-ready Post-Quantum Cryptography (PQC) library implementing NIST-standardized algorithms FIPS 203 (ML-KEM), FIPS 204 (ML-DSA), and FIPS 205 (SLH-DSA) with both pure PQC and hybrid (classical + PQC) modes.

§Features

§Key Encapsulation Mechanisms (KEM) - FIPS 203

ML-KEM-512: NIST Level 1 security (128-bit)
ML-KEM-768: NIST Level 3 security (192-bit)
ML-KEM-1024: NIST Level 5 security (256-bit)
Hybrid KEM: Classical ECDH + ML-KEM for defense-in-depth

§Digital Signatures - FIPS 204

ML-DSA-44: NIST Level 2 security (~128-bit)
ML-DSA-65: NIST Level 3 security (~192-bit)
ML-DSA-87: NIST Level 5 security (~256-bit)
Hybrid Signatures: Classical Ed25519 + ML-DSA for defense-in-depth

§Hash-Based Signatures - FIPS 205

SLH-DSA: 12 parameter sets (SHA2/SHAKE, 128/192/256-bit, fast/small)

§Symmetric Encryption (Quantum-Resistant)

ChaCha20-Poly1305: AEAD cipher providing quantum-resistant symmetric encryption
Password-based Key Derivation: PBKDF2 for secure key derivation from passwords
Authenticated Encryption: Built-in authentication prevents tampering

§Network Protocol Support

Raw Public Keys: Ed25519 key support for P2P authentication
Key Derivation: Utilities for network identity derivation
Protocol Agnostic: Designed for use with any network protocol

§Security Features

Memory Protection: Secure memory handling and cleanup
Constant-Time Operations: Resistance to side-channel attacks
Algorithm Negotiation: Automatic algorithm selection and fallback
Security Validation: Comprehensive parameter and key validation

§Quick Start

use saorsa_pqc::pqc::{MlKem768, MlKemOperations, HybridPublicKeyEncryption};
use saorsa_pqc::symmetric::{SymmetricKey, ChaCha20Poly1305Cipher};

// Key encapsulation with ML-KEM
let ml_kem = MlKem768::new();
let (pub_key, sec_key) = ml_kem.generate_keypair()?;
let (ciphertext, shared_secret) = ml_kem.encapsulate(&pub_key)?;
let recovered_secret = ml_kem.decapsulate(&sec_key, &ciphertext)?;
assert_eq!(shared_secret.as_bytes(), recovered_secret.as_bytes());

// Public key encryption
let pke = HybridPublicKeyEncryption::new();
let plaintext = b"Secret message";
let associated_data = b"context";
let encrypted = pke.encrypt(&pub_key, plaintext, associated_data)?;
let decrypted = pke.decrypt(&sec_key, &encrypted, associated_data)?;
assert_eq!(plaintext, &decrypted[..]);

// Quantum-resistant symmetric encryption
let key = SymmetricKey::generate();
let cipher = ChaCha20Poly1305Cipher::new(&key);
let (ciphertext, nonce) = cipher.encrypt(b"Quantum-safe data", None)?;
let decrypted = cipher.decrypt(&ciphertext, &nonce, None)?;
assert_eq!(b"Quantum-safe data", &decrypted[..]);

§Security Considerations

This library is designed with security as the primary concern:

No Panics: All operations return Result types with proper error handling
Memory Safety: Sensitive data is zeroed on drop and uses secure allocators
Timing Attacks: Constant-time implementations where cryptographically relevant
Algorithm Agility: Support for multiple algorithms and hybrid modes
Validation: Comprehensive input validation and parameter checking

§Performance

The library is optimized for both security and performance:

FIPS-Compliant Implementations: Uses FIPS 203/204/205 certified crates
Memory Pooling: Reduces allocation overhead for frequent operations
Parallel Processing: Optional multi-threading for batch operations
Zero-Copy: Minimal data copying in critical paths

§Feature Flags

The library is designed to work out-of-the-box with sensible defaults. Optional features are available for specific use cases:

simd: Enable SIMD acceleration for performance (requires wide crate)
cert_compression: Enable certificate compression optimization
dangerous_configuration: Enable dangerous configuration options (not recommended)
test-utils: Enable testing utilities
benchmarks: Enable benchmarking support

§Safety and Compliance

NIST Standards: Implements FIPS 203 (ML-KEM) and FIPS 204 (ML-DSA)
No Unsafe Code: Forbidden by lint configuration
Comprehensive Testing: Property-based testing and fuzzing
Security Auditing: Regular security audits and vulnerability scanning

Re-exports§

pub use api::init as api_init;
pub use api::kdf::helpers as kdf_helpers;
pub use api::kem::ml_kem_768;
pub use api::sig::ml_dsa_65;
pub use api::slh::slh_dsa_sha2_128s;
pub use api::supported_algorithms;
pub use api::version as api_version;
pub use api::HkdfSha3_256;
pub use api::HkdfSha3_512;
pub use api::KdfAlgorithm;
pub use api::MlDsa;
pub use api::MlDsaPublicKey as ApiMlDsaPublicKey;
pub use api::MlDsaSecretKey as ApiMlDsaSecretKey;
pub use api::MlDsaSignature as ApiMlDsaSignature;
pub use api::MlDsaVariant;
pub use api::MlKem;
pub use api::MlKemCiphertext as ApiMlKemCiphertext;
pub use api::MlKemPublicKey as ApiMlKemPublicKey;
pub use api::MlKemSecretKey as ApiMlKemSecretKey;
pub use api::MlKemSharedSecret;
pub use api::MlKemVariant;
pub use api::PqcError as ApiError;
pub use api::PqcResult as ApiResult;
pub use api::SlhDsa;
pub use api::SlhDsaPublicKey;
pub use api::SlhDsaSecretKey;
pub use api::SlhDsaSignature;
pub use api::SlhDsaVariant;
pub use pqc::types::HybridKemCiphertext;
pub use pqc::types::HybridKemPublicKey;
pub use pqc::types::HybridKemSecretKey;
pub use pqc::types::HybridSignaturePublicKey;
pub use pqc::types::HybridSignatureSecretKey;
pub use pqc::types::HybridSignatureValue;
pub use pqc::types::MlDsaPublicKey;
pub use pqc::types::MlDsaSecretKey;
pub use pqc::types::MlDsaSignature;
pub use pqc::types::MlKemCiphertext;
pub use pqc::types::MlKemPublicKey;
pub use pqc::types::MlKemSecretKey;
pub use pqc::types::PqcError;
pub use pqc::types::PqcResult;
pub use pqc::types::SharedSecret;
pub use pqc::EncryptedMessage;
pub use pqc::HybridKem;
pub use pqc::HybridPublicKeyEncryption;
pub use pqc::HybridSignature;
pub use pqc::MlDsa65;
pub use pqc::MlDsaOperations;
pub use pqc::MlKem768;
pub use pqc::MlKemOperations;
pub use symmetric::ChaCha20Poly1305Cipher;
pub use symmetric::EncryptedMessage as SymmetricEncryptedMessage;
pub use symmetric::SymmetricError;
pub use symmetric::SymmetricKey;

Modules§

api: Comprehensive API for Post-Quantum Cryptography
dsa_traits: All functionality is covered by traits, such that consumers can utilize trait objects as desired.
kem_traits: All functionality is covered by traits, such that consumers can utilize trait objects if desired.
ml_dsa_44: Functionality for the ML-DSA-44 security parameter set.
ml_dsa_65: Functionality for the ML-DSA-65 security parameter set.
ml_dsa_87: Functionality for the ML-DSA-87 security parameter set.
ml_kem_512: Functionality for the ML-KEM-512 security parameter set, which is claimed to be in security category 1, see table 2 & 3 on page 39 of spec.
ml_kem_768: Functionality for the ML-KEM-768 security parameter set, which is claimed to be in security category 3, see table 2 & 3 on page 39 of spec.
ml_kem_1024: Functionality for the ML-KEM-1024 security parameter set, which is claimed to be in security category 5, see table 2 & 3 on page 39 of spec.
pqc: Post-Quantum Cryptography module for Saorsa Labs projects
slh_dsa_sha2_128f: Functionality for the SLH-DSA-SHA2-128f security parameter set per FIPS 205 section 11.
slh_dsa_sha2_128s: Functionality for the SLH-DSA-SHA2-128s security parameter set per FIPS 205 section 11.
slh_dsa_sha2_192f: Functionality for the SLH-DSA-SHA2-192f security parameter set per FIPS 205 section 11.
slh_dsa_sha2_192s: Functionality for the SLH-DSA-SHA2-192s security parameter set per FIPS 205 section 11.
slh_dsa_sha2_256f: Functionality for the SLH-DSA-SHA2-256f security parameter set per FIPS 205 section 11.
slh_dsa_sha2_256s: Functionality for the SLH-DSA-SHA2-256s security parameter set per FIPS 205 section 11.
slh_dsa_shake_128f: Functionality for the SLH-DSA-SHAKE-128f security parameter set per FIPS 205 section 11.
slh_dsa_shake_128s: Functionality for the SLH-DSA-SHAKE-128s security parameter set per FIPS 205 section 11.
slh_dsa_shake_192f: Functionality for the SLH-DSA-SHAKE-192f security parameter set per FIPS 205 section 11.
slh_dsa_shake_192s: Functionality for the SLH-DSA-SHAKE-192s security parameter set per FIPS 205 section 11.
slh_dsa_shake_256f: Functionality for the SLH-DSA-SHAKE-256f security parameter set per FIPS 205 section 11.
slh_dsa_shake_256s: Functionality for the SLH-DSA-SHAKE-256s security parameter set per FIPS 205 section 11.
slh_traits: All functionality is covered by traits, such that consumers can utilize trait objects as desired.
symmetric: Quantum-resistant symmetric encryption using ChaCha20-Poly1305

Structs§

ApiCompatibilityInfo: API compatibility and version tracking information
DependencyVersionInfo: Core dependency versions for backwards compatibility tracking
LibraryInfo: Information about the library capabilities

Constants§

DEFAULT_SECURITY_LEVEL: Default security level provided by this library
SUPPORTED_ML_DSA: Supported ML-DSA parameter sets
SUPPORTED_ML_KEM: Supported ML-KEM parameter sets
VERSION: Library version information

Functions§

get_info: Get library information and capabilities
init: Initialize the library with optimal settings
is_compatible_with_version: Check if the current library version supports backward compatibility with a specific version

Crate saorsa_pqc

Crate saorsa_pqc Copy item path

§Saorsa Post-Quantum Cryptography Library

§Features

§Key Encapsulation Mechanisms (KEM) - FIPS 203

§Digital Signatures - FIPS 204

§Hash-Based Signatures - FIPS 205

§Symmetric Encryption (Quantum-Resistant)

§Network Protocol Support

§Security Features

§Quick Start

§Security Considerations

§Performance

§Feature Flags

§Safety and Compliance

Re-exports§

Modules§

Structs§

Constants§

Functions§

Crate saorsa_pqc