cortexai_encryption/
lib.rs

1//! At-rest encryption for sensitive data in cortex.
2//!
3//! This crate provides encryption primitives for protecting sessions, checkpoints,
4//! and other sensitive data at rest. It supports:
5//!
6//! - **AES-256-GCM** authenticated encryption (default)
7//! - **ChaCha20-Poly1305** authenticated encryption (optional)
8//! - **Argon2id** password-based key derivation
9//! - **Key rotation** via versioned keys and envelope encryption
10//! - **Secure memory** handling with automatic zeroing
11//!
12//! # Quick Start
13//!
14//! ```rust
15//! use cortexai_encryption::{EncryptionKey, EnvelopeEncryptor, DataEncryptor};
16//!
17//! // Generate a random 256-bit key
18//! let key = EncryptionKey::generate(32);
19//!
20//! // Create an encryptor
21//! let encryptor = EnvelopeEncryptor::new(key);
22//!
23//! // Encrypt structured data
24//! let secret = serde_json::json!({"user": "alice", "token": "secret123"});
25//! let ciphertext = encryptor.encrypt_data(&secret).unwrap();
26//!
27//! // Decrypt
28//! let decrypted: serde_json::Value = encryptor.decrypt_data(&ciphertext).unwrap();
29//! assert_eq!(secret, decrypted);
30//! ```
31//!
32//! # Key Derivation
33//!
34//! For password-based encryption:
35//!
36//! ```rust
37//! use cortexai_encryption::{Argon2KeyDerivation, KeyDerivation, EnvelopeEncryptor};
38//!
39//! let kdf = Argon2KeyDerivation::new();
40//! let salt = kdf.generate_salt(16);
41//! let key = kdf.derive_encryption_key(b"user-password", &salt, 32).unwrap();
42//!
43//! let encryptor = EnvelopeEncryptor::new(key);
44//! ```
45//!
46//! # Key Rotation
47//!
48//! ```rust
49//! use cortexai_encryption::{EncryptionKey, EnvelopeEncryptor};
50//!
51//! let key1 = EncryptionKey::generate(32);
52//! let mut encryptor = EnvelopeEncryptor::new(key1);
53//!
54//! // Encrypt with v1
55//! let ciphertext = encryptor.encrypt(b"secret", None).unwrap();
56//!
57//! // Rotate to v2
58//! let key2 = EncryptionKey::generate(32);
59//! encryptor.rotate_key(key2);
60//!
61//! // Old ciphertext still decrypts (key v1 retained)
62//! let plaintext = encryptor.decrypt(&ciphertext, None).unwrap();
63//!
64//! // Re-encrypt with new key
65//! let new_ciphertext = encryptor.re_encrypt(&ciphertext, None).unwrap();
66//! ```
67//!
68//! # Store Wrappers
69//!
70//! For encrypting session and checkpoint stores:
71//!
72//! ```rust,ignore
73//! use cortexai_encryption::{EncryptedSessionStore, EncryptedCheckpointStore};
74//!
75//! // Wrap existing stores with encryption
76//! let encrypted_sessions = EncryptedSessionStore::new(session_store, encryptor.clone());
77//! let encrypted_checkpoints = EncryptedCheckpointStore::new(checkpoint_store, encryptor);
78//! ```
79
80pub mod error;
81pub mod key;
82pub mod traits;
83
84#[cfg(feature = "aes")]
85pub mod aes_cipher;
86
87#[cfg(feature = "chacha")]
88pub mod chacha_cipher;
89
90pub mod envelope;
91pub mod stores;
92
93// Re-exports
94pub use error::{CryptoError, CryptoResult};
95pub use key::{Argon2KeyDerivation, EncryptionKey, KeyRing, VersionedKey};
96pub use traits::{Cipher, DataEncryptor, KeyDerivation};
97
98#[cfg(feature = "aes")]
99pub use aes_cipher::Aes256GcmCipher;
100
101#[cfg(feature = "chacha")]
102pub use chacha_cipher::ChaCha20Poly1305Cipher;
103
104pub use envelope::EnvelopeEncryptor;
105pub use stores::{EncryptedCheckpointStore, EncryptedSessionStore};
cortexai_encryption/lib.rs

cortexai_encryption/
lib.rs
