{"id":31841577,"url":"https://github.com/dirvine/saorsa-pqc","last_synced_at":"2025-10-12T05:21:11.440Z","repository":{"id":310398552,"uuid":"1039591344","full_name":"dirvine/saorsa-pqc","owner":"dirvine","description":"Post-Quantum Cryptography library for Saorsa Labs projects","archived":false,"fork":false,"pushed_at":"2025-09-16T11:51:28.000Z","size":22680,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-16T13:37:42.427Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dirvine.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-17T15:13:43.000Z","updated_at":"2025-09-16T11:51:32.000Z","dependencies_parsed_at":null,"dependency_job_id":"87ce60d5-f91c-4aff-976b-4f1d8c675d5d","html_url":"https://github.com/dirvine/saorsa-pqc","commit_stats":null,"previous_names":["dirvine/saorsa-pqc"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/dirvine/saorsa-pqc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dirvine%2Fsaorsa-pqc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dirvine%2Fsaorsa-pqc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dirvine%2Fsaorsa-pqc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dirvine%2Fsaorsa-pqc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dirvine","download_url":"https://codeload.github.com/dirvine/saorsa-pqc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dirvine%2Fsaorsa-pqc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279010341,"owners_count":26084738,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-12T02:00:06.719Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-12T05:21:09.438Z","updated_at":"2025-10-12T05:21:11.435Z","avatar_url":"https://github.com/dirvine.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Saorsa Post-Quantum Cryptography Library\n\n[![Crates.io](https://img.shields.io/crates/v/saorsa-pqc.svg)](https://crates.io/crates/saorsa-pqc)\n[![Documentation](https://docs.rs/saorsa-pqc/badge.svg)](https://docs.rs/saorsa-pqc)\n[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](https://github.com/dirvine/saorsa-pqc)\n[![Build Status](https://github.com/dirvine/saorsa-pqc/workflows/CI/badge.svg)](https://github.com/dirvine/saorsa-pqc/actions)\n\nA comprehensive, production-ready Post-Quantum Cryptography library providing a complete quantum-secure cryptographic suite. Implements NIST FIPS 203, 204, and 205 standardized algorithms for asymmetric cryptography, plus comprehensive cryptographic primitives including BLAKE3, SHA3, HMAC, HKDF, AES-256-GCM, and ChaCha20-Poly1305. This library provides high-performance, thoroughly tested implementations with a clean, safe API, all validated against official NIST ACVP, RFC, and specification test vectors.\n\n## 🎯 Features\n\n- **Complete Quantum-Secure Suite**: Both asymmetric (PQC) and symmetric encryption with comprehensive cryptographic primitives\n- **FIPS 140-3 Compliant RNG**: ChaCha20-based DRBG with continuous health monitoring per NIST SP 800-90A/B\n- **FIPS-Certified Implementations**: Uses NIST FIPS-certified crates for ML-KEM, ML-DSA, and SLH-DSA\n- **Extensive Cryptographic Library**: BLAKE3, SHA3, HMAC, HKDF, AES-256-GCM, ChaCha20-Poly1305, and HPKE\n- **Official Test Vector Validation**: All algorithms validated against NIST ACVP, RFC, and specification test vectors\n- **Comprehensive API**: Simple, user-friendly interfaces with FIPS-compliant RNG management\n- **High Performance**: Optimized implementations with SIMD support where available\n- **Memory Safety**: Automatic zeroization of sensitive data\n- **Type Safety**: Strongly typed wrappers prevent misuse\n- **No Unsafe Code**: Pure Rust implementations in the API layer\n- **Deterministic Testing**: Support for reproducible key generation from seeds\n\n## 📦 Installation\n\n```toml\n[dependencies]\nsaorsa-pqc = \"0.3\"\n```\n\n## 🔐 Supported Algorithms\n\n### 🔒 Cryptographic Primitives (All Quantum-Resistant)\n\n#### Hash Functions\n- **BLAKE3**: Modern cryptographic hash with tree hashing\n  - ✅ **High Performance**: Faster than SHA2/SHA3 with parallelization\n  - ✅ **256-bit Output**: Configurable output length (XOF capability)\n  - ✅ **Test Vectors**: Validated against official BLAKE3 specification vectors\n  - ✅ **Use Cases**: General hashing, key derivation, checksums\n\n- **SHA3-256/SHA3-512**: NIST FIPS 202 Keccak-based hash functions\n  - ✅ **NIST Standard**: FIPS 202 compliant implementation\n  - ✅ **Quantum Resistance**: Based on different mathematical foundation than SHA2\n  - ✅ **Test Vectors**: Validated against NIST FIPS 202 official test vectors\n  - ✅ **Use Cases**: Digital signatures, certificates, blockchain applications\n\n#### Key Derivation Functions (KDF)\n- **HKDF-SHA3-256/HKDF-SHA3-512**: Extract-and-expand key derivation\n  - ✅ **RFC 5869 Based**: Adapted for SHA3 hash functions\n  - ✅ **Secure Key Derivation**: Extract entropy then expand to desired length\n  - ✅ **Test Vectors**: Validated against RFC 5869 methodology\n  - ✅ **Use Cases**: Deriving encryption keys from shared secrets\n\n#### Message Authentication Codes (MAC)\n- **HMAC-SHA3-256/HMAC-SHA3-512**: Hash-based message authentication\n  - ✅ **Constant-Time Verification**: Resistant to timing attacks\n  - ✅ **NIST CAVS Tested**: Validated against NIST test methodology\n  - ✅ **Flexible Key Sizes**: Accepts arbitrary key lengths\n  - ✅ **Use Cases**: Message integrity, authentication tokens\n\n#### Authenticated Encryption (AEAD)\n- **AES-256-GCM**: Hardware-accelerated authenticated encryption\n  - ✅ **Hardware Support**: AES-NI acceleration on modern CPUs\n  - ✅ **256-bit Security**: Quantum-resistant key size\n  - ✅ **NIST CAVP Tested**: Validated against NIST SP 800-38D test vectors\n  - ✅ **Use Cases**: High-speed data encryption, VPN tunnels\n\n- **ChaCha20-Poly1305**: Software-optimized authenticated encryption\n  - ✅ **Constant-Time**: Resistant to side-channel attacks\n  - ✅ **256-bit Security**: Full 256-bit key strength\n  - ✅ **IETF Standard**: RFC 8439 compliant\n  - ✅ **Test Vectors**: Validated against RFC 8439 official test vectors\n  - ✅ **Use Cases**: Mobile devices, embedded systems, general encryption\n\n#### Hybrid Public Key Encryption (HPKE)\n- **HPKE with ML-KEM**: RFC 9180 hybrid encryption bound to post-quantum KEMs\n  - ✅ **Post-Quantum**: Combines ML-KEM with symmetric primitives\n  - ✅ **Multiple Modes**: Base mode and PSK (pre-shared key) mode\n  - ✅ **Flexible Configuration**: Choose KEM (ML-KEM variant), KDF, and AEAD\n  - ✅ **Test Vectors**: Custom test vectors for ML-KEM combinations\n  - ✅ **Use Cases**: End-to-end encryption, secure messaging, hybrid cryptosystems\n\n### ML-KEM (FIPS 203) - Key Encapsulation\n- **ML-KEM-512**: NIST Level 1 (128-bit security)\n- **ML-KEM-768**: NIST Level 3 (192-bit security)\n- **ML-KEM-1024**: NIST Level 5 (256-bit security)\n\n### ML-DSA (FIPS 204) - Digital Signatures\n- **ML-DSA-44**: NIST Level 2 (~128-bit security)\n- **ML-DSA-65**: NIST Level 3 (~192-bit security)\n- **ML-DSA-87**: NIST Level 5 (~256-bit security)\n\n### SLH-DSA (FIPS 205) - Stateless Hash-Based Signatures\n12 variants covering all combinations of:\n- Hash functions: SHA2, SHAKE\n- Security levels: 128, 192, 256 bits\n- Trade-offs: Small signatures (s) vs Fast signing (f)\n\n## 💻 Quick Start\n\n### NEW: Trait-Based API (v0.3.11+)\n\nThe library now provides a trait-based abstraction layer for PQC algorithms, enabling easier integration and algorithm agility:\n\n```rust\nuse saorsa_pqc::pqc::{Kem, Sig, MlKem768Trait, MlDsa65Trait, ConstantTimeCompare};\n\n// Key Encapsulation with trait API\nlet (kem_pk, kem_sk) = MlKem768Trait::keypair();\nlet (shared_secret, ciphertext) = MlKem768Trait::encap(\u0026kem_pk);\nlet recovered = MlKem768Trait::decap(\u0026kem_sk, \u0026ciphertext)?;\nassert!(shared_secret.ct_eq(\u0026recovered)); // Constant-time comparison\n\n// Digital Signatures with trait API\nlet (sig_pk, sig_sk) = MlDsa65Trait::keypair();\nlet message = b\"Quantum-resistant message\";\nlet signature = MlDsa65Trait::sign(\u0026sig_sk, message);\nassert!(MlDsa65Trait::verify(\u0026sig_pk, message, \u0026signature));\n\n// BLAKE3 helpers for secure key derivation\nuse saorsa_pqc::pqc::blake3_helpers;\nlet derived_key = blake3_helpers::derive_key(\"app-context\", shared_secret.as_ref());\n```\n\n**Key Features of Trait API:**\n- **Zero-copy buffers**: Efficient memory usage without unnecessary allocations\n- **Automatic zeroization**: Secret keys are wiped from memory when dropped\n- **Constant-time operations**: Protection against timing attacks\n- **Generic programming**: Write code that works with any KEM or signature algorithm\n\n### Quantum-Secure Symmetric Encryption (ChaCha20-Poly1305)\n\n```rust\nuse saorsa_pqc::api::ChaCha20Poly1305;\nuse saorsa_pqc::api::symmetric::{generate_key, generate_nonce};\n\n// Generate a random 256-bit key (quantum-secure)\nlet key = generate_key();\nlet cipher = ChaCha20Poly1305::new(\u0026key);\n\n// Encrypt data with authenticated encryption\nlet nonce = generate_nonce(); // 96-bit nonce\nlet plaintext = b\"Secret quantum-secure message\";\nlet aad = b\"Additional authenticated data\";\n\n// Encrypt with associated data (AEAD)\nlet ciphertext = cipher.encrypt_with_aad(\u0026nonce, plaintext, aad)?;\n\n// Decrypt and verify authenticity\nlet decrypted = cipher.decrypt_with_aad(\u0026nonce, \u0026ciphertext, aad)?;\n\nassert_eq!(\u0026decrypted[..], plaintext);\n\n// Simple encryption without AAD\nlet ciphertext2 = cipher.encrypt(\u0026nonce, plaintext)?;\nlet decrypted2 = cipher.decrypt(\u0026nonce, \u0026ciphertext2)?;\nassert_eq!(\u0026decrypted2[..], plaintext);\n```\n\n### Key Encapsulation (ML-KEM)\n\n```rust\nuse saorsa_pqc::api::{ml_kem_768, MlKemPublicKey, MlKemSecretKey};\n\n// Generate keypair (RNG handled internally)\nlet kem = ml_kem_768();\nlet (public_key, secret_key) = kem.generate_keypair()?;\n\n// Encapsulate - creates shared secret and ciphertext\nlet (shared_secret, ciphertext) = kem.encapsulate(\u0026public_key)?;\n\n// Decapsulate - recovers shared secret from ciphertext\nlet recovered_secret = kem.decapsulate(\u0026secret_key, \u0026ciphertext)?;\n\nassert_eq!(shared_secret.to_bytes(), recovered_secret.to_bytes());\n```\n\n### Digital Signatures (ML-DSA)\n\n```rust\nuse saorsa_pqc::api::{ml_dsa_65, MlDsaPublicKey, MlDsaSecretKey};\n\n// Generate keypair\nlet dsa = ml_dsa_65();\nlet (public_key, secret_key) = dsa.generate_keypair()?;\n\n// Sign message\nlet message = b\"Authenticate this message\";\nlet signature = dsa.sign(\u0026secret_key, message)?;\n\n// Verify signature\nlet is_valid = dsa.verify(\u0026public_key, message, \u0026signature)?;\nassert!(is_valid);\n```\n\n### Stateless Signatures (SLH-DSA)\n\n```rust\nuse saorsa_pqc::api::{slh_dsa_sha2_128s, SlhDsaPublicKey, SlhDsaSecretKey};\n\n// Generate keypair (note: SLH-DSA keygen is slow)\nlet slh = slh_dsa_sha2_128s();\nlet (public_key, secret_key) = slh.generate_keypair()?;\n\n// Sign and verify\nlet message = b\"Quantum-resistant message\";\nlet signature = slh.sign(\u0026secret_key, message)?;\nlet is_valid = slh.verify(\u0026public_key, message, \u0026signature)?;\nassert!(is_valid);\n```\n\n## 🧪 Testing \u0026 Validation\n\nThis library has been extensively tested against official test vectors from multiple authoritative sources:\n\n### Comprehensive Test Vector Validation\n\n#### Post-Quantum Algorithms (NIST ACVP)\n- **Official NIST ACVP Vectors**: [github.com/usnistgov/ACVP-Server](https://github.com/usnistgov/ACVP-Server/tree/master/gen-val/json-files)\n  - ✅ **ML-KEM**: [Keygen](https://github.com/usnistgov/ACVP-Server/tree/master/gen-val/json-files/ML-KEM-keyGen-FIPS203), [Encapsulation/Decapsulation](https://github.com/usnistgov/ACVP-Server/tree/master/gen-val/json-files/ML-KEM-encapDecap-FIPS203)\n  - ✅ **ML-DSA**: [Keygen](https://github.com/usnistgov/ACVP-Server/tree/master/gen-val/json-files/ML-DSA-keyGen-FIPS204), [Signature Generation/Verification](https://github.com/usnistgov/ACVP-Server/tree/master/gen-val/json-files/ML-DSA-sigGen-FIPS204)\n  - ✅ **SLH-DSA**: [Comprehensive test vectors](https://github.com/usnistgov/ACVP-Server/tree/master/gen-val/json-files/SLH-DSA-sigGen-FIPS205) for all 12 variants\n\n#### Cryptographic Primitives (Official Standards)\n- ✅ **BLAKE3**: Official specification test vectors from [BLAKE3 team](https://github.com/BLAKE3-team/BLAKE3/blob/master/test_vectors/test_vectors.json)\n- ✅ **SHA3-256/512**: NIST FIPS 202 test vectors for empty input, \"abc\", and multi-million character tests\n- ✅ **AES-256-GCM**: NIST CAVP test vectors from SP 800-38D with various key, IV, and AAD combinations\n- ✅ **HKDF-SHA3**: Test vectors adapted from RFC 5869 methodology for SHA3 variants\n- ✅ **HMAC-SHA3**: Test vectors derived from NIST CAVS testing methodology\n- ✅ **ChaCha20-Poly1305**: RFC 8439 official test vectors\n- ✅ **HPKE**: RFC 9180 methodology adapted for ML-KEM combinations\n\n#### Additional Test Sources\n- **C2SP/CCTV Test Vectors**: [github.com/C2SP/CCTV](https://github.com/C2SP/CCTV/tree/main/ML-KEM)\n  - Intermediate values for debugging\n  - Invalid input testing (modulus vectors)\n  - Edge case testing (unlucky NTT sampling)\n\n### Running Tests\n\n```bash\n# Run all tests\ncargo test --all-features\n\n# Run specific algorithm tests\ncargo test --test nist_official_vectors\ncargo test --test extended_crypto_vectors\n\n# Run with release optimizations (faster)\ncargo test --release\n```\n\n### Test Coverage\n\n#### Post-Quantum Algorithm Coverage\n- ✅ Key generation deterministic tests\n- ✅ Encapsulation/Decapsulation correctness\n- ✅ Signature generation and verification\n- ✅ Wrong message/ciphertext rejection\n- ✅ Serialization round-trips\n- ✅ Context handling (ML-DSA)\n- ✅ Parameter validation\n- ✅ Cross-implementation compatibility\n\n#### Cryptographic Primitive Coverage\n- ✅ **Hash Functions**: BLAKE3 (empty, single byte, multi-part, million character), SHA3-256/512 (NIST FIPS 202)\n- ✅ **Key Derivation**: HKDF-SHA3-256/512 deterministic output, salt handling, different context values\n- ✅ **Message Authentication**: HMAC-SHA3-256/512 with various key sizes, constant-time verification\n- ✅ **AEAD Encryption**: AES-256-GCM and ChaCha20-Poly1305 with AAD, authentication failure detection\n- ✅ **HPKE**: All ML-KEM variants with different KDF/AEAD combinations, wrong key rejection\n- ✅ **Security Properties**: Memory zeroization, constant-time operations, authentication tag verification\n- ✅ **Error Handling**: Invalid input sizes, wrong authentication tags, corrupted data\n\n## 📊 Performance Benchmarks\n\nRun comprehensive benchmarks:\n\n```bash\ncargo bench --bench comprehensive_benchmarks\n```\n\n### Benchmark Results (M1 Pro)\n\n| Algorithm | Operation | Time | Throughput |\n|-----------|-----------|------|------------|\n| ML-KEM-768 | KeyGen | ~50 μs | - |\n| ML-KEM-768 | Encapsulate | ~55 μs | - |\n| ML-KEM-768 | Decapsulate | ~65 μs | - |\n| ML-DSA-65 | KeyGen | ~120 μs | - |\n| ML-DSA-65 | Sign | ~350 μs | - |\n| ML-DSA-65 | Verify | ~130 μs | - |\n| SLH-DSA-SHA2-128f | KeyGen | ~3 ms | - |\n| SLH-DSA-SHA2-128f | Sign | ~90 ms | - |\n| SLH-DSA-SHA2-128f | Verify | ~4 ms | - |\n| ChaCha20-Poly1305 | Encrypt (1KB) | ~0.8 μs | 1.25 GB/s |\n| ChaCha20-Poly1305 | Encrypt (64KB) | ~12 μs | 5.3 GB/s |\n| ChaCha20-Poly1305 | Decrypt (64KB) | ~12 μs | 5.3 GB/s |\n| AES-256-GCM | Encrypt (1KB) | ~0.6 μs | 1.67 GB/s |\n| AES-256-GCM | Encrypt (64KB) | ~8 μs | 8.0 GB/s |\n| BLAKE3 | Hash (1KB) | ~0.4 μs | 2.5 GB/s |\n| SHA3-256 | Hash (1KB) | ~1.2 μs | 833 MB/s |\n| HMAC-SHA3-256 | MAC (1KB) | ~1.3 μs | 769 MB/s |\n\n*Note: Performance varies by hardware. AES-GCM benefits from AES-NI acceleration. ChaCha20-Poly1305 and BLAKE3 benefit from SIMD acceleration (AVX2/NEON).*\n\n## 🔒 Security Considerations\n\n### Quantum Security\n- **Symmetric Algorithms**: All symmetric algorithms (AES-256-GCM, ChaCha20-Poly1305) provide quantum resistance with 256-bit keys, offering 128-bit quantum security against Grover's algorithm\n- **Hash Functions**: BLAKE3 and SHA3 maintain security against quantum attacks as they're based on different mathematical foundations\n- **Post-Quantum Asymmetric**: ML-KEM, ML-DSA, and SLH-DSA are specifically designed to resist both classical and quantum attacks\n- **Complete Protection**: Use ML-KEM for key exchange, then derive symmetric keys for AES-256-GCM or ChaCha20-Poly1305 encryption\n- **Algorithm Selection Guide**:\n  - **Performance Priority**: BLAKE3 (hashing), AES-256-GCM (encryption if AES-NI available)\n  - **Security Priority**: SHA3 (standardized), ChaCha20-Poly1305 (constant-time)\n  - **Compatibility**: SHA3 and AES-256-GCM (NIST standards)\n  - **Embedded/Mobile**: BLAKE3 and ChaCha20-Poly1305 (software-optimized)\n\n### Implementation Security\n1. **Memory Safety**: All sensitive data is automatically zeroized on drop\n2. **Constant Time**: Critical operations designed to be constant-time (HMAC verification, ChaCha20-Poly1305)\n3. **FIPS 140-3 RNG**: ChaCha20-based DRBG with continuous health monitoring (SP 800-90A/B compliant)\n4. **No Key Reuse**: Fresh randomness for each operation requiring it\n5. **Input Validation**: All inputs validated before cryptographic operations\n6. **AEAD Protection**: Both AES-256-GCM and ChaCha20-Poly1305 provide confidentiality and authenticity\n7. **Algorithm Diversity**: Multiple implementations allow for algorithm agility and risk mitigation\n8. **Test Vector Compliance**: All implementations validated against official standards\n\n### FIPS 140-3 Compliance\n\nThe library implements a FIPS 140-3 compliant random number generator:\n\n- **DRBG Mechanism**: ChaCha20-based deterministic random bit generator (approved for FIPS 140-3)\n- **Continuous Health Monitoring**: Implements Repetition Count Test (RCT) and Adaptive Proportion Test (APT) per NIST SP 800-90B\n- **Entropy Source Validation**: Startup health tests and continuous monitoring of OS entropy\n- **Automatic Reseeding**: Reseeds after 1MB of output to ensure prediction resistance and backtracking resistance\n- **Security Strengths**: Supports 128-bit, 192-bit, and 256-bit security levels\n- **Compliance**: Meets requirements of NIST SP 800-90A (DRBG) and SP 800-90B (Entropy Sources)\n\n```rust\nuse saorsa_pqc::pqc::{FipsRng, SecurityStrength};\n\n// Create FIPS-compliant RNG for 256-bit security\nlet mut rng = FipsRng::new(SecurityStrength::Bits256)?;\n\n// Generate cryptographic random bytes\nlet mut key_material = [0u8; 32];\nrng.fill_bytes(\u0026mut key_material);\n\n// Manual reseed for prediction resistance\nrng.reseed()?;\n```\n\n**Testing**: 29 comprehensive tests validate FIPS compliance including:\n- Known Answer Tests (KAT)\n- Statistical distribution tests (chi-square)\n- Continuous health monitoring\n- Reseed mechanisms\n- Non-repeatability validation\n\n## 📚 API Documentation\n\nFull API documentation is available at [docs.rs/saorsa-pqc](https://docs.rs/saorsa-pqc)\n\n### Key Types\n- `MlKemPublicKey`, `MlKemSecretKey`, `MlKemCiphertext`, `MlKemSharedSecret`\n- `MlDsaPublicKey`, `MlDsaSecretKey`, `MlDsaSignature`\n- `SlhDsaPublicKey`, `SlhDsaSecretKey`, `SlhDsaSignature`\n\n### Convenience Functions\n- `ml_kem_512()`, `ml_kem_768()`, `ml_kem_1024()`\n- `ml_dsa_44()`, `ml_dsa_65()`, `ml_dsa_87()`\n- `slh_dsa_sha2_128s()`, `slh_dsa_sha2_128f()`, etc.\n\n## 🛠️ Advanced Usage\n\n### Algorithm Selection Guide\n\nChoose the right cryptographic primitives for your use case:\n\n#### Hash Functions\n```rust\nuse saorsa_pqc::api::hash::{Blake3Hasher, Sha3_256Hasher};\nuse saorsa_pqc::api::traits::Hash;\n\n// High performance: BLAKE3\nlet mut hasher = Blake3Hasher::new();\nhasher.update(b\"data to hash\");\nlet hash = hasher.finalize();\n\n// NIST standard: SHA3-256\nlet mut hasher = Sha3_256Hasher::new();\nhasher.update(b\"data to hash\");\nlet hash = hasher.finalize();\n```\n\n#### AEAD Encryption\n```rust\nuse saorsa_pqc::api::aead::{Aes256GcmAead, AeadCipher, GcmNonce};\nuse saorsa_pqc::api::traits::Aead;\n\n// Hardware accelerated: AES-256-GCM\nlet key = [0u8; 32]; // Use proper key generation\nlet aead = Aes256GcmAead::new(\u0026key)?;\nlet nonce = GcmNonce::generate();\nlet ciphertext = aead.encrypt(\u0026nonce, b\"plaintext\", b\"aad\")?;\n\n// Software optimized: ChaCha20-Poly1305 (via enum)\nlet ciphertext = AeadCipher::ChaCha20Poly1305\n    .encrypt(\u0026key, nonce.as_ref(), b\"plaintext\", b\"aad\")?;\n```\n\n#### Key Derivation\n```rust\nuse saorsa_pqc::api::kdf::HkdfSha3_256;\nuse saorsa_pqc::api::traits::Kdf;\n\n// Derive encryption key from shared secret\nlet shared_secret = b\"shared secret from ML-KEM\";\nlet info = b\"application context\";\nlet mut derived_key = [0u8; 32];\nHkdfSha3_256::derive(shared_secret, None, info, \u0026mut derived_key)?;\n```\n\n#### HPKE (Hybrid Encryption)\n```rust\nuse saorsa_pqc::api::hpke::{HpkeConfig, seal, open};\nuse saorsa_pqc::api::{MlKem, MlKemVariant, kdf::KdfAlgorithm, aead::AeadCipher};\n\n// Configure HPKE with ML-KEM + AES-GCM\nlet config = HpkeConfig {\n    kem: MlKemVariant::MlKem768,\n    kdf: KdfAlgorithm::HkdfSha3_256,\n    aead: AeadCipher::Aes256Gcm,\n};\n\n// Generate recipient keypair\nlet kem = MlKem::new(MlKemVariant::MlKem768);\nlet (pk, sk) = kem.generate_keypair()?;\n\n// Encrypt\nlet (enc_key, ciphertext) = seal(\n    config,\n    \u0026pk.to_bytes(),\n    b\"context info\",\n    b\"secret message\",\n    b\"associated data\"\n)?;\n\n// Decrypt\nlet plaintext = open(\n    config,\n    \u0026sk.to_bytes(),\n    \u0026enc_key,\n    b\"context info\",\n    \u0026ciphertext,\n    b\"associated data\"\n)?;\n```\n\n### Complete Quantum-Secure Communication\n\nCombine ML-KEM key exchange with symmetric primitives:\n\n```rust\nuse saorsa_pqc::api::{ml_kem_768, ChaCha20Poly1305};\nuse saorsa_pqc::api::symmetric::generate_nonce;\n\n// Alice generates ML-KEM keypair\nlet kem = ml_kem_768();\nlet (alice_pk, alice_sk) = kem.generate_keypair()?;\n\n// Bob encapsulates a shared secret using Alice's public key\nlet (shared_secret, ciphertext) = kem.encapsulate(\u0026alice_pk)?;\n\n// Alice decapsulates to get the same shared secret\nlet recovered_secret = kem.decapsulate(\u0026alice_sk, \u0026ciphertext)?;\n\n// Derive proper encryption key from shared secret using HKDF\nuse saorsa_pqc::api::kdf::HkdfSha3_256;\nuse saorsa_pqc::api::traits::Kdf;\n\nlet mut encryption_key = [0u8; 32];\nHkdfSha3_256::derive(\n    \u0026shared_secret.to_bytes(),\n    None,\n    b\"saorsa-pqc encryption key\",\n    \u0026mut encryption_key\n)?;\n\n// Create cipher with derived key\nlet cipher = ChaCha20Poly1305::new(\u0026encryption_key);\n\n// Now Bob can encrypt messages to Alice\nlet nonce = generate_nonce();\nlet message = b\"Quantum-secure message\";\nlet encrypted = cipher.encrypt(\u0026nonce, message)?;\n\n// Alice decrypts using the same key\nlet decrypted = cipher.decrypt(\u0026nonce, \u0026encrypted)?;\nassert_eq!(decrypted, message);\n```\n\n## 🛠️ Additional Features\n\n### Serialization\n\n```rust\n// All keys and signatures support serialization\nlet pk_bytes = public_key.to_bytes();\nlet restored_pk = MlKemPublicKey::from_bytes(\n    MlKemVariant::MlKem768, \n    \u0026pk_bytes\n)?;\n```\n\n### Context Support (ML-DSA)\n\n```rust\n// ML-DSA supports domain separation via context\nlet context = b\"application-specific-context\";\nlet signature = dsa.sign_with_context(\u0026secret_key, message, context)?;\nlet is_valid = dsa.verify_with_context(\u0026public_key, message, \u0026signature, context)?;\n```\n\n### Deterministic Key Generation\n\n```rust\n// Generate keys from seed (for testing/reproducibility)\n// Uses FIPS 203 deterministic generation with two 32-byte seeds\nlet d_seed = [0u8; 32];  // First seed value\nlet z_seed = [1u8; 32];  // Second seed value\nlet kem = ml_kem_768();\nlet (pk, sk) = kem.generate_keypair_from_seed(\u0026d_seed, \u0026z_seed);\n\n// Deterministic generation produces identical keys\nlet (pk2, sk2) = kem.generate_keypair_from_seed(\u0026d_seed, \u0026z_seed);\nassert_eq!(pk.to_bytes(), pk2.to_bytes());\n```\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit issues and pull requests.\n\n### Development Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/dirvine/saorsa-pqc\ncd saorsa-pqc\n\n# Run tests\ncargo test --all-features\n\n# Run benchmarks\ncargo bench\n\n# Check code quality\ncargo clippy --all-features\ncargo fmt --check\n```\n\n## 📄 License\n\nThis project is dual-licensed under:\n- MIT License\n- Apache License 2.0\n\nChoose whichever license works best for your use case.\n\n## 🙏 Acknowledgments\n\nThis library builds upon the excellent work of:\n- [fips203](https://crates.io/crates/fips203) - ML-KEM implementation\n- [fips204](https://crates.io/crates/fips204) - ML-DSA implementation\n- [fips205](https://crates.io/crates/fips205) - SLH-DSA implementation\n- [blake3](https://crates.io/crates/blake3) - BLAKE3 hash function\n- [sha3](https://crates.io/crates/sha3) - SHA3 and Keccak implementations\n- [aes-gcm](https://crates.io/crates/aes-gcm) - AES-GCM AEAD cipher\n- [chacha20poly1305](https://crates.io/crates/chacha20poly1305) - ChaCha20-Poly1305 AEAD\n- [hkdf](https://crates.io/crates/hkdf) - HMAC-based Key Derivation Function\n- [hmac](https://crates.io/crates/hmac) - HMAC implementation\n\n## 📮 Contact\n\n- **Author**: David Irvine\n- **Email**: david@saorsalabs.com\n- **GitHub**: [@dirvine](https://github.com/dirvine)\n\n## 🚀 Roadmap\n\n- [ ] Hardware security module (HSM) support\n- [ ] WebAssembly bindings  \n- [ ] C FFI bindings\n- [ ] Hybrid modes (PQC + Classical)\n- [ ] SHAKE256 XOF implementation\n- [ ] Additional KDF algorithms (PBKDF2, Argon2)\n- [ ] Side-channel resistance validation\n- [ ] Formal verification of critical paths\n- [ ] Performance optimizations for specific platforms\n\n---\n\n## 📅 2024 NIST Updates\n\nThis library incorporates the latest NIST standards released in 2024:\n- **August 13, 2024**: ML-KEM, ML-DSA, and SLH-DSA algorithms enabled on ACVTS Production server\n- **FIPS 203, 204, 205**: Final standards published replacing draft versions\n- **Test Vectors**: Updated to match the final NIST specifications\n\n**Note**: This library is under active development. While the underlying FIPS implementations are certified, always perform your own security audit before production use.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdirvine%2Fsaorsa-pqc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdirvine%2Fsaorsa-pqc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdirvine%2Fsaorsa-pqc/lists"}