# dcrypt: A Modern, High-Assurance Cryptographic Library in Rust
[](https://crates.io/crates/dcrypt)
[](https://docs.rs/dcrypt)
[](https://opensource.org/licenses/Apache-2.0)
[](https://github.com/ioi-foundation/dcrypt/actions)
**dcrypt** (Decentralized Cryptography) is a comprehensive cryptographic library implemented entirely in safe Rust. It bridges the gap between traditional security and the post-quantum future by providing NIST-standardized Post-Quantum Cryptography (PQC) algorithms alongside novel, production-ready hybrid constructions.
Spearheaded by the **IOI Foundation** as the security cornerstone for next-generation decentralized infrastructure, dcrypt eliminates foreign function interfaces (FFI) and `unsafe` code blocks in cryptographic logic, ensuring memory safety and cross-platform compatibility from embedded devices to enterprise servers.
## 🚀 Novel Capabilities
dcrypt introduces capabilities critical for the transition to quantum-safe and decentralized computing:
1. **Pure-Rust FIPS 204 (ML-DSA)**: A production-ready implementation of the complete **CRYSTALS-Dilithium** signature scheme with zero `unsafe` code, spec-aligned hint handling, and a fixed-window constant-time signer bounded by the public FIPS 204 Appendix C loop limit.
2. **Pure-Rust FIPS 203 (ML-KEM)**: A complete implementation of **CRYSTALS-Kyber** with protections against timing side-channels.
3. **Native Hybrid Cryptography**: First-class support for hybrid Key Encapsulation Mechanisms (e.g., `ECDH P-256 + Kyber-768`) and hybrid Digital Signatures, ensuring security even if one underlying primitive is compromised.
4. **BLS12-381 Pairing Engine**: A fully featured implementation of the pairing-friendly curve, including optimal Ate pairings and IETF-compliant **Hash-to-Curve**, essential for Zero-Knowledge Proofs and Signature Aggregation.
## 🛡️ Key Design Principles
* **Pure Rust & Memory Safety**: Implemented with **zero FFI dependencies** to eliminate memory vulnerabilities like buffer overflows and use-after-free errors common in C/C++ wrapped libraries.
* **Post-Quantum Ready**: Full support for NIST-selected algorithms, protecting data against "Harvest Now, Decrypt Later" attacks.
* **Defense-in-Depth**: Hybrid schemes combine battle-tested classical algorithms (ECDH/ECDSA) with modern PQC primitives.
* **Constant-Time Assurance**: Security-sensitive paths are designed to avoid secret-dependent timing behavior where supported, and ML-DSA signing uses a fixed public rejection window derived from FIPS 204 Appendix C. This work is backed by a built-in **Constant-Time Verification Suite** that statistically detects timing leaks during CI.
* **Type Safety**: High-level APIs prevent misuse through strong typing (e.g., distinct types for `Nonce`, `Key`, and `Tag` prevents byte-array confusion).
* **`no_std` & Cross-Platform**: Fully functional in `no_std` environments (requiring `alloc`), making it suitable for IoT, embedded systems, and WASM targets.
## 📦 Quick Start
Add `dcrypt` to your project's `Cargo.toml`.
```toml
[dependencies]
dcrypt = { version = "1.0" }
```
### Example 1: Hybrid Post-Quantum Key Exchange
Securely exchange keys using a hybrid scheme (`EcdhP256` + `Kyber768`). This ensures security remains intact even if quantum computers break elliptic curve cryptography.
```rust
use dcrypt::hybrid::kem::EcdhP256Kyber768;
use dcrypt::api::Kem;
use rand::rngs::OsRng;
fn main() -> Result<(), Box<dyn std::error::Error>> {
let mut rng = OsRng;
// 1. Alice generates a Hybrid Keypair
// (Contains both a P-256 keypair and a Kyber-768 keypair)
let (alice_pk, alice_sk) = EcdhP256Kyber768::keypair(&mut rng)?;
// 2. Bob encapsulates a shared secret against Alice's public key
let (ciphertext, shared_secret_bob) = EcdhP256Kyber768::encapsulate(&mut rng, &alice_pk)?;
// 3. Alice decapsulates the ciphertext to recover the shared secret
let shared_secret_alice = EcdhP256Kyber768::decapsulate(&alice_sk, &ciphertext)?;
// 4. Verify secrets match
assert_eq!(shared_secret_bob.as_ref(), shared_secret_alice.as_ref());
println!("Hybrid Quantum-Safe Key Exchange successful!");
Ok(())
}
```
### Example 2: Authenticated Encryption (AES-256-GCM)
Standard symmetric encryption remains a core part of the library, featuring ergonomic key management.
```rust
use dcrypt::symmetric::aes::{Aes256Gcm, Aes256Key};
use dcrypt::symmetric::cipher::{SymmetricCipher, Aead};
fn main() -> Result<(), Box<dyn std::error::Error>> {
// Generate a secure random key
let key = Aes256Key::generate();
let cipher = Aes256Gcm::new(&key)?;
let nonce = Aes256Gcm::generate_nonce();
let plaintext = b"Quantum resistance is futile... actually it's necessary.";
let aad = Some(b"metadata".as_slice());
// Encrypt
let ciphertext = cipher.encrypt(&nonce, plaintext, aad)?;
// Decrypt
let decrypted = cipher.decrypt(&nonce, &ciphertext, aad)?;
assert_eq!(plaintext.to_vec(), decrypted);
Ok(())
}
```
### Example 3: BLS12-381 Bilinear Pairings
Perform bilinear pairings and hash-to-curve operations standard in decentralized identity and ZK systems.
```rust
use dcrypt::algorithms::ec::bls12_381::{
pairing, G1Projective, G2Affine, G2Projective, Scalar
};
fn main() -> Result<(), Box<dyn std::error::Error>> {
// 1. Hash a message to a point on G1 using IETF hash-to-curve
let msg = b"Decentralized Identity";
let dst = b"BLS_SIG_BLS12381G1_XMD:SHA-256_SSWU_RO_NUL_";
// hash_to_curve returns a projective point
let point_g1 = G1Projective::hash_to_curve(msg, dst)?.to_affine();
// 2. Generate a secret scalar and public G2 point
let secret = Scalar::from(42u64); // In reality, use random generation
let public_g2 = G2Affine::from(G2Projective::generator() * secret);
// 3. Compute Pairing e(H(m), [s]G2)
let result = pairing(&point_g1, &public_g2);
println!("Pairing computed successfully: {:?}", result);
Ok(())
}
```
## 📚 Supported Algorithms
dcrypt provides a unified API for classical, post-quantum, and hybrid operations:
| **Symmetric Encryption (AEAD)** | `AES-128/256-GCM`, `ChaCha20-Poly1305`, `XChaCha20-Poly1305` |
| **Public Key Encryption (PKE)** | `ECIES` (P-192, P-224, P-256, P-384, P-521) |
| **Hash Functions** | `SHA-2` (224, 256, 384, 512), `SHA-3`, `BLAKE2b/s` |
| **XOFs** | `SHAKE-128/256`, `BLAKE3` |
| **Password Hashing** | `Argon2id` (default), `Argon2i`, `Argon2d`, `PBKDF2` |
| **Key Derivation** | `HKDF`, `PBKDF2` |
| **Digital Signatures** | `ECDSA` (P-192 to P-521), `Ed25519` |
| **Post-Quantum Signatures** | `Dilithium` / `ML-DSA` (Levels 2, 3, 5) |
| **Key Exchange / KEM** | `ECDH` (P-Curves, K-256, B-283) |
| **Pairing-Friendly Curves** | `BLS12-381` (G1, G2, Gt, Pairings, Hash-to-Curve) |
| **Post-Quantum KEMs**| `Kyber` / `ML-KEM` (Levels 512, 768, 1024) |
| **Hybrid Schemes** | `EcdhP256Kyber768`, `EcdhP384Kyber1024`, `EcdsaDilithiumHybrid` |
## 🏗️ Architecture
The library is organized as a workspace of specialized crates to align type-safety boundaries with security boundaries:
* **`dcrypt-api`**: Defines core traits (`SymmetricCipher`, `Kem`, `Signature`), error types, and fundamental data structures.
* **`dcrypt-algorithms`**: Low-level, constant-time implementations of cryptographic kernels (hashing, curve arithmetic, lattice math).
* **`dcrypt-common`**: Shared security primitives, including `SecretBuffer` (automatic zeroization) and `SecureCompare`.
* **`dcrypt-symmetric`**: High-level AEADs, stream ciphers, and secure key management wrappers.
* **`dcrypt-pke`**: Public Key Encryption schemes, specifically **ECIES** (Elliptic Curve Integrated Encryption Scheme) over standard NIST curves.
* **`dcrypt-kem`**: Implementations of Key Encapsulation Mechanisms (Kyber, ECDH, McEliece placeholders).
* **`dcrypt-sign`**: Implementations of Digital Signatures (Dilithium, ECDSA, Ed25519, SPHINCS+ placeholders).
* **`dcrypt-hybrid`**: Ready-to-use combiners for KEMs and Signatures ensuring crypto-agility.
* **`dcrypt-tests`**: Contains the ACVP test harness and Constant-Time Verification Suite.
## 🔒 Security & Verification
Security is the primary driver for dcrypt. The library employs a rigorous testing methodology:
### Constant-Time Verification
We utilize a custom statistical analysis engine (`dcrypt-tests/src/suites/constant_time`) that integrates into our CI.
* **Methodology**: Uses interleaved A/B timing measurements, bootstrap confidence intervals, Kolmogorov-Smirnov tests, Welch-style mean-shift checks, and Holm-Bonferroni correction across the combined signals.
* **Noise Gating**: Maintains a persistent noise profile and aborts inconclusive runs when the host environment is materially noisier than the historical baseline.
* **Coverage**: Exercises critical paths in Kyber, ML-DSA/Dilithium, hybrid constructions, ECDH, and AEAD implementations against timing side-channels.
### FIPS/NIST Compliance
* **ACVP Test Harness**: Includes a full test harness compatible with NIST's Automated Cryptographic Validation Program (ACVP) JSON vectors to ensure implementation correctness against official standards.
* **Parameters**: All PQC parameters strictly adhere to FIPS 203 (ML-KEM) and FIPS 204 (ML-DSA).
* **ML-DSA Signing Bound**: The constant-time ML-DSA signer uses the public fixed rejection bound from FIPS 204 Appendix C, Table 3.
## 📄 License
This project is licensed under the **Apache License, Version 2.0**.