Merge pull request #1 from AriajSarkar/dev

Feat: v2

Author: AriajSarkar

.gitignore

@@ -17,6 +17,7 @@ fuzz/artifacts/
 *.swo
 *~
 .DS_Store
+copilot-instructions.md
 
 # Testing
 *.profraw

CHANGELOG.md

@@ -7,11 +7,90 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- **Streaming AEAD Encryption** - High-performance streaming encryption for large files
+  - `Aes256GcmStreamEncryptor` and `Aes256GcmStreamDecryptor` for AES-256-GCM
+  - `ChaCha20Poly1305StreamEncryptor` and `ChaCha20Poly1305StreamDecryptor`
+  - Uses RustCrypto's `aead::stream` module (STREAM construction from RFC)
+  - Implements EncryptorBE32/DecryptorBE32 with proper nonce derivation
+  - Auto-generates 7-byte nonces (12-byte AEAD nonce - 5 bytes for counter/flag)
+  - Methods: `new()`, `nonce()`, `encrypt_next()`, `encrypt_last()`, `from_nonce()`, `decrypt_next()`, `decrypt_last()`
+  - Proper ownership semantics (encrypt_last/decrypt_last consume self)
+  - Each chunk independently authenticated with nonce-reuse resistance
+  - Maximum 2^32 chunks per stream
+  - Default chunk size: 64 KB, max chunk size: 1 MB
+  - 5 comprehensive tests covering roundtrip, large data, authentication failures, and edge cases
+  - Total test count increased to 108 tests (from 103)
+
+- **Comprehensive RFC/NIST Test Vectors** - 13 new test cases covering 28 test vectors from 8 standards
+  - NIST CAVP vectors for AES-128/256-GCM (3 test cases)
+  - RFC 7539 vectors for ChaCha20-Poly1305 (2 test cases)
+  - RFC 4634 vectors for SHA-256/512 (7 test vectors)
+  - RFC 4231 vectors for HMAC-SHA256/512 (10 test vectors)
+  - RFC 6070 vectors for PBKDF2 (4 test cases, adapted for security minimums)
+  - RFC 5869 vectors for HKDF (2 test cases)
+
+- **Constant-Time Operations Audit** - Complete review and documentation
+  - Added `subtle` crate v2.6 for constant-time comparisons
+  - Updated `constant_time_eq()` to use industry-standard `subtle::ConstantTimeEq`
+  - Created comprehensive `CONSTANT_TIME_AUDIT.md` documentation
+  - Verified all MAC and AEAD operations use constant-time tag verification
+  - Added security notes to MAC verification functions
+  - Documented guidelines for when to use constant-time comparisons
+
+- **Serde Serialization Support** (behind `serde-support` feature flag)
+  - Full serialization/deserialization for `Ciphertext` (encrypted data)
+  - Serialization for Ed25519 public keys and signatures
+  - Support for JSON, TOML, bincode, and all serde formats
+  - Comprehensive example demonstrating usage patterns
+  - Binary serialization ~55% more compact than JSON
+  - Perfect for storing encrypted data and cryptographic keys
+
+- **Dependency Updates** - Updated 21 packages to latest stable versions
+  - RustCrypto: aes-gcm 0.10.3, chacha20poly1305 0.10.1, pbkdf2 0.12.2, argon2 0.5.3
+  - Asymmetric: ed25519-dalek 2.2.0 (from 2.1), x25519-dalek 2.0.1
+  - Security: zeroize 1.8.2, subtle 2.6.1 (new), pkcs8 0.10.2 (new)
+  - Encoding: base64 0.22.1
+  - Dev deps: proptest 1.9.0 (from 1.5.0), hex-literal 1.1.0, serde_json 1.0.141, serde_bytes 0.11.19
+  - All tests passing (193 with all features: 103 unit + 6 integration + 7 interop + 13 RFC vectors + 64 doc tests)
+  - Avoided breaking changes: getrandom stays on 0.2.x, rand_core on 0.6.x for RustCrypto compatibility
+
+- **PKCS#8 Key Import/Export** (RFC 5208, RFC 5958, RFC 8410)
+  - Full PKCS#8 DER/PEM support for Ed25519 and X25519 private keys
+  - SPKI (SubjectPublicKeyInfo) DER/PEM support for public keys
+  - Standards-compliant implementation using `pkcs8` crate v0.10.2
+  - OpenSSL-compatible key formats
+  - Algorithm OIDs: Ed25519 (1.3.101.112), X25519 (1.3.101.110)
+  - 8 new methods: `to_pkcs8_der/pem`, `from_pkcs8_der/pem` for keypairs
+  - 8 new methods: `to_public_key_der/pem`, `from_public_key_der/pem` for public keys
+  - Comprehensive example in `examples/pkcs8_example.rs`
+  - All doc tests passing with roundtrip verification
+
 ### Planned
-- RSA encryption and signatures (optional feature)
-- PKCS#8 key import/export
 - Streaming encryption API
 - SHA-3 and BLAKE2 support
+- Property-based testing with proptest
+
+## [0.2.0] - 2025-10-29
+
+### Added
+- **RSA Support** (behind `rsa-support` feature flag)
+  - RSA-OAEP encryption with SHA-256
+  - RSA-PSS signatures with SHA-256
+  - 2048-bit and 4096-bit key generation
+  - PEM/DER import/export (PKCS#8)
+  - Complete test suite with RFC test vectors
+  - Benchmarks for RSA operations
+  - Example code demonstrating usage
+
+### Security
+- ⚠️ **IMPORTANT**: RSA implementation has known vulnerability (RUSTSEC-2023-0071 - Marvin timing attack)
+- Added prominent security warnings in documentation
+- Recommend Ed25519 for signatures and X25519+AEAD for encryption unless RSA is required for compatibility
+
+### Changed
+- Excluded development files from published crate (`.github/`, `fuzz/`, `TODOs.md`, etc.)
+- Updated documentation to include RSA examples and security warnings
 
 ## [0.1.0] - 2025-10-28
 

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "crabgraph"
-version = "0.1.1"
+version = "0.2.0"
 authors = ["Raj Sarkar <ariajsarkar@gmail.com>"]
 edition = "2021"
 rust-version = "1.70"
@@ -12,55 +12,73 @@ documentation = "https://docs.rs/crabgraph"
 license = "MIT OR Apache-2.0"
 keywords = ["cryptography", "crypto", "encryption", "security", "authentication"]
 categories = ["cryptography", "authentication", "encoding", "no-std"]
+exclude = [
+    ".github/",
+    ".gitignore",
+    "fuzz/",
+    "target/",
+    "TODOs.md",
+    "rustfmt.toml",
+    "Cargo.lock",
+    "docs/",
+]
 
 [dependencies]
-# AEAD ciphers
-aes-gcm = { version = "0.10", features = ["std"] }
-chacha20poly1305 = { version = "0.10", features = ["std"] }
+# AEAD ciphers - RustCrypto audited implementations
+aes-gcm = { version = "0.10.3", features = ["std", "stream"] }
+chacha20poly1305 = { version = "0.10.1", features = ["std", "stream"] }
 
-# Key derivation
-pbkdf2 = { version = "0.12", features = ["simple"] }
-argon2 = { version = "0.5", features = ["std"] }
-hkdf = "0.12"
+# Key derivation functions
+pbkdf2 = { version = "0.12.2", features = ["simple"] }
+argon2 = { version = "0.5.3", features = ["std"] }
+hkdf = "0.12.4"
 
-# Hashing
-sha2 = { version = "0.10", features = ["oid"] }
-sha3 = { version = "0.10", optional = true }
-blake2 = { version = "0.10", optional = true }
+# Hashing algorithms
+sha2 = { version = "0.10.9", features = ["oid"] }
+sha3 = { version = "0.10.8", optional = true }
+blake2 = { version = "0.10.6", optional = true }
 
-# MAC
-hmac = "0.12"
+# Message Authentication Codes
+hmac = "0.12.1"
 
 # Asymmetric cryptography
-ed25519-dalek = { version = "2.1", features = ["rand_core"] }
-x25519-dalek = { version = "2.0", features = ["static_secrets"] }
-rsa = { version = "0.9", optional = true, features = ["sha2"] }
+ed25519-dalek = { version = "2.2", features = ["rand_core", "pkcs8", "pem"] }
+x25519-dalek = { version = "2.0.1", features = ["static_secrets"] }
+rsa = { version = "0.9.8", optional = true, features = ["sha2"] }
+pkcs8 = { version = "0.10.2", features = ["pem", "alloc"] }
 
 # Random number generation
-getrandom = "0.2"
-rand_core = "0.6"
+getrandom = "0.2.16"
+rand_core = "0.6.4"
 
 # Secure memory handling
-zeroize = { version = "1.7", features = ["derive"] }
+zeroize = { version = "1.8.2", features = ["derive"] }
 
-# Encoding
-base64 = "0.21"
-hex = "0.4"
+# Constant-time operations
+subtle = { version = "2.6.1", default-features = false }
+
+# Encoding utilities
+base64 = "0.22.1"
+hex = "0.4.3"
 
 # Error handling
-thiserror = "1.0"
+thiserror = "1.0.69"
 
 # Serialization (optional)
-serde = { version = "1.0", features = ["derive"], optional = true }
+serde = { version = "1.0.215", features = ["derive"], optional = true }
 
 # Zero-copy optimizations (optional)
-bytes = { version = "1.5", optional = true }
+bytes = { version = "1.9.0", optional = true }
 
 [dev-dependencies]
-criterion = { version = "0.5", features = ["html_reports"] }
-proptest = "1.4"
-quickcheck = "1.0"
-hex-literal = "0.4"
+criterion = { version = "0.7.0", features = ["html_reports"] }
+proptest = "1.9.0"
+quickcheck = "1.0.3"
+hex-literal = "1.1.0"
+serde_json = "1.0.141"
+bincode = "1.3.3"
+toml = "0.8.23"
+serde_bytes = "0.11.19"
 
 [features]
 default = ["std"]
@@ -73,6 +91,14 @@ serde-support = ["serde"]
 zero-copy = ["bytes"]
 wasm = ["getrandom/js"]
 
+[[example]]
+name = "rsa_example"
+required-features = ["rsa-support"]
+
+[[example]]
+name = "serde_example"
+required-features = ["serde-support"]
+
 [[bench]]
 name = "aead_bench"
 harness = false

README.md

@@ -19,11 +19,13 @@ For security issues, please see [SECURITY.md](SECURITY.md).
 ## ✨ Features
 
 - 🔒 **Authenticated Encryption (AEAD)**: AES-GCM, ChaCha20-Poly1305
-- 🔑 **Key Derivation**: PBKDF2, Argon2, HKDF
-- ✍️ **Digital Signatures**: Ed25519
+- � **Streaming Encryption**: Process large files chunk-by-chunk with STREAM construction
+- �🔑 **Key Derivation**: PBKDF2, Argon2, HKDF
+- ✍️ **Digital Signatures**: Ed25519, (optional: RSA-PSS)
 - 🤝 **Key Exchange**: X25519 (Elliptic Curve Diffie-Hellman)
 - 🔐 **Message Authentication**: HMAC (SHA-256, SHA-512)
 - #️⃣ **Hashing**: SHA-256, SHA-512, (optional: SHA-3, BLAKE2)
+- 🔒 **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
@@ -101,6 +103,77 @@ fn main() -> CrabResult<()> {
 }
 ```
 
+### Serialization (Serde)
+
+```rust
+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
+
+```rust
+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
 
 ```rust
@@ -167,11 +240,22 @@ cargo audit
 - `alloc`: Allocation support without full std
 - `no_std`: Embedded/bare-metal support
 - `extended-hashes`: SHA-3 and BLAKE2 support
-- `rsa-support`: RSA encryption/signatures (large dependency)
+- `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
 - `wasm`: WebAssembly support
 
+### Enabling RSA Support
+
+RSA is **not included by default** due to security concerns. To use RSA:
+
+```toml
+[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](CONTRIBUTING.md) and our [Code of Conduct](CODE_OF_CONDUCT.md).