🦀 CrabGraph

A safe, ergonomic, and high-performance cryptographic library for Rust, built on top of audited primitives from the RustCrypto ecosystem and other trusted sources.

⚠️ Security Notice

This library is NOT yet audited by third-party cryptographic experts. While it uses audited primitives (RustCrypto, dalek-cryptography), mistakes in composition can still lead to vulnerabilities. DO NOT use in production without a professional security audit.

Note: The optional rsa-support feature has a known vulnerability (RUSTSEC-2023-0071 - Marvin timing attack). Use Ed25519/X25519 instead.

For security issues, please see SECURITY.md.

✨ Features

• 🔒 Authenticated Encryption (AEAD): AES-GCM, ChaCha20-Poly1305
• 📦 Streaming Encryption: Process large files chunk-by-chunk with STREAM construction
• 🔑 Key Derivation: PBKDF2, Argon2, HKDF
• ✍️ Digital Signatures: Ed25519, ECDSA (P-256, P-384), (optional: RSA-PSS)
• 🤝 Key Exchange: X25519, P-256, P-384 (Elliptic Curve Diffie-Hellman)
• 🔐 Message Authentication: HMAC (SHA-256, SHA-512)
• #️⃣ Hashing: SHA-256, SHA-384, SHA-512, (optional: SHA-3, BLAKE2)
• 🌐 TLS Support: rustls CryptoProvider for reqwest, hyper-rustls, tokio-rustls
• 🔒 Optional RSA Support: RSA-OAEP encryption & RSA-PSS signatures (⚠️ opt-in only, not recommended)
• 🎲 Secure Random: Cryptographically secure RNG wrapper
• 🧹 Memory Safety: Automatic zeroization of sensitive data
• 🌐 Interoperability: Helpers for CryptoJS compatibility
• 🚀 Performance: Zero-copy operations, hardware acceleration support
• 📦 No-std Support: Core functionality available in embedded contexts

🌐 Live Demo

Try CrabGraph in WebAssembly!

Experience CrabGraph's cryptographic capabilities directly in your browser. This interactive demo showcases real-world usage of the library compiled to WebAssembly, demonstrating encryption, key derivation, and signing operations with zero installation required.

🚀 Quick Start

Add to your Cargo.toml:

[dependencies]
crabgraph = "0.3.1"

Authenticated Encryption (AES-GCM)

use crabgraph::{aead::AesGcm256, CrabResult};

fn main() -> CrabResult<()> {
    // Generate a random key
    let key = AesGcm256::generate_key()?;
    
    // Create cipher instance
    let cipher = AesGcm256::new(&key)?;
    
    // Encrypt data with associated data (AAD)
    let plaintext = b"Secret message";
    let aad = b"public header";
    let ciphertext = cipher.encrypt(plaintext, Some(aad))?;
    
    // Decrypt
    let decrypted = cipher.decrypt(&ciphertext, Some(aad))?;
    assert_eq!(decrypted, plaintext);
    
    Ok(())
}

Key Derivation (Argon2)

use crabgraph::{kdf::argon2_derive, CrabResult};

fn main() -> CrabResult<()> {
    let password = b"correct horse battery staple";
    let salt = b"random_salt_16by"; // 16+ bytes
    
    // Derive a 32-byte key
    let key = argon2_derive(password, salt, 32)?;
    
    println!("Derived key: {}", hex::encode(&key));
    Ok(())
}

Digital Signatures (Ed25519)

use crabgraph::{asym::Ed25519KeyPair, CrabResult};

fn main() -> CrabResult<()> {
    // Generate keypair
    let keypair = Ed25519KeyPair::generate()?;
    
    // Sign message
    let message = b"Important document";
    let signature = keypair.sign(message);
    
    // Verify signature
    assert!(keypair.verify(message, &signature)?);
    
    Ok(())
}

Serialization (Serde)

use crabgraph::{aead::AesGcm256, asym::Ed25519KeyPair, CrabResult};

fn main() -> CrabResult<()> {
    // Encrypt data
    let key = AesGcm256::generate_key()?;
    let cipher = AesGcm256::new(&key)?;
    let ciphertext = cipher.encrypt(b"Secret message", None)?;
    
    // Serialize to JSON
    let json = serde_json::to_string(&ciphertext)?;
    println!("Ciphertext JSON: {}", json);
    
    // Deserialize and decrypt
    let restored: crabgraph::aead::Ciphertext = serde_json::from_str(&json)?;
    let plaintext = cipher.decrypt(&restored, None)?;
    
    // Works with keys and signatures too
    let keypair = Ed25519KeyPair::generate()?;
    let pubkey_json = serde_json::to_string(&keypair.public_key())?;
    
    Ok(())
}

Streaming Encryption for Large Files

use crabgraph::{
    aead::stream::{Aes256GcmStreamEncryptor, Aes256GcmStreamDecryptor},
    rand::secure_bytes,
    CrabResult
};

fn main() -> CrabResult<()> {
    // Generate a 32-byte key for AES-256-GCM
    let key = secure_bytes(32)?;
    
    // Create stream encryptor (auto-generates 7-byte nonce)
    let mut encryptor = Aes256GcmStreamEncryptor::new(&key)?;
    let nonce = encryptor.nonce().to_vec(); // Save nonce for decryption
    
    // Encrypt chunks (64 KB default chunk size)
    let chunk1 = b"First chunk of data...";
    let chunk2 = b"Second chunk of data...";
    let chunk3 = b"Final chunk of data!";
    
    let encrypted1 = encryptor.encrypt_next(chunk1)?;
    let encrypted2 = encryptor.encrypt_next(chunk2)?;
    let encrypted3 = encryptor.encrypt_last(chunk3)?; // Consumes encryptor
    
    // Decrypt using saved nonce
    let mut decryptor = Aes256GcmStreamDecryptor::from_nonce(&key, &nonce)?;
    
    let decrypted1 = decryptor.decrypt_next(&encrypted1)?;
    let decrypted2 = decryptor.decrypt_next(&encrypted2)?;
    let decrypted3 = decryptor.decrypt_last(&encrypted3)?; // Consumes decryptor
    
    assert_eq!(decrypted1, chunk1);
    assert_eq!(decrypted2, chunk2);
    assert_eq!(decrypted3, chunk3);
    
    Ok(())
}

See examples/serde_example.rs for JSON, TOML, and binary serialization examples.

HMAC Authentication

use crabgraph::{mac::hmac_sha256, CrabResult};

fn main() -> CrabResult<()> {
    let key = b"secret_key_at_least_32_bytes_long!!!";
    let message = b"Message to authenticate";
    
    // Generate HMAC
    let tag = hmac_sha256(key, message)?;
    
    // Verify HMAC
    let is_valid = crabgraph::mac::hmac_sha256_verify(key, message, &tag)?;
    assert!(is_valid);
    
    Ok(())
}

📚 Documentation

• API Documentation
• GitHub Pages Docs
• 📊 Performance Benchmarks
• Migration from CryptoJS
• Examples

⚡ Performance

CrabGraph delivers excellent performance with minimal overhead over raw primitives:

Operation	Speed	Throughput
AES-256-GCM Encrypt (1KB)	~0.95 μs	~1,079 MB/s
ChaCha20-Poly1305 Encrypt (1KB)	~2.7 μs	~378 MB/s
Ed25519 Sign	~16 μs	~62,500 ops/sec
Ed25519 Verify	~47 μs	~21,277 ops/sec
Argon2id KDF (32B)	~11 ms	Intentionally slow (security)

📊 Full benchmark results: ariajsarkar.github.io/crabgraph-bench

Benchmarks run on modern hardware with AES-NI. Your results may vary.

🏗️ Architecture

CrabGraph is built on these audited cryptographic libraries:

• RustCrypto: aes-gcm, chacha20poly1305, sha2, hmac, pbkdf2, hkdf
• dalek-cryptography: ed25519-dalek, x25519-dalek
• Argon2: Official Rust bindings to the Argon2 reference implementation

🎯 Design Principles

1. Safe by Default: AEAD modes, proper nonce handling, automatic secret zeroization
2. No Footguns: High-level API hides complexity; low-level access requires opt-in
3. Audited Primitives: Never implements crypto from scratch
4. Performance: Zero-copy, hardware acceleration, minimal allocations
5. Ergonomic: Builder patterns, clear error messages, comprehensive docs
6. Interoperable: Helpers for common JS library compatibility

🧪 Testing & Quality

# Run all tests
cargo test --all-features

# Run benchmarks
cargo bench

# Run fuzzing (requires cargo-fuzz)
cargo fuzz run aead_fuzz

# Security audit
cargo audit

🔧 Feature Flags

• default: Enables std support
• std: Standard library support (enabled by default)
• alloc: Allocation support without full std
• no_std: Embedded/bare-metal support
• extended-hashes: SHA-3 and BLAKE2 support
• rsa-support: RSA encryption/signatures (⚠️ NOT enabled by default - opt-in only, has known vulnerability RUSTSEC-2023-0071)
• serde-support: Serialization for keys and ciphertexts
• zero-copy: bytes crate integration for high-performance scenarios
• tls: TLS CryptoProvider for rustls (includes P-256, P-384, SHA-384)
• rustls-provider: Alias for tls feature
• wasm: WebAssembly support (⚠️ Temporarily unavailable in v0.3.3 - see CHANGELOG for details)

TLS Support (New in v0.4.0)

Use crabgraph as the TLS crypto backend for reqwest, hyper-rustls, and other rustls-based libraries:

[dependencies]
crabgraph = { version = "0.4.0-pre", features = ["tls"] }

use crabgraph::tls;

fn main() {
    // Install crabgraph as the default TLS provider (call once at startup)
    tls::install_default();
    
    // Now all rustls-based libraries will use crabgraph
    // let client = reqwest::Client::new();
}

Supported Cipher Suites:

• TLS 1.3: AES-256-GCM, AES-128-GCM, ChaCha20-Poly1305
• TLS 1.2: ECDHE-ECDSA/RSA with AES-GCM and ChaCha20-Poly1305
• Key Exchange: X25519, P-256, P-384

Enabling RSA Support

RSA is not included by default due to security concerns. To use RSA:

[dependencies]
crabgraph = { version = "0.2", features = ["rsa-support"] }

⚠️ Security Warning: RSA has a known timing attack vulnerability (RUSTSEC-2023-0071). Use Ed25519 for signatures and X25519+AEAD for encryption unless RSA is specifically required for legacy compatibility.

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md and our Code of Conduct.

📜 License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

🙏 Acknowledgments

Built on the shoulders of giants:

• RustCrypto team
• dalek-cryptography contributors
• Argon2 reference implementation authors

⚠️ Disclaimer

This software is provided "as is", without warranty of any kind. See LICENSE files for details.

IMPORTANT: Cryptography is hard. This library has not undergone a formal security audit. Use at your own risk, especially in production environments. Always consult with security professionals for critical applications.