lib.rs raw

//! # CipherBox
//!
//! A secure, encrypted storage library for Rust that provides password-based encryption
//! for any serializable data using industry-standard cryptography.
//!
//! ## Features
//!
//! - **ChaCha20-Poly1305 encryption**: Fast, secure authenticated encryption
//! - **Key commitment**: A BLAKE3-derived commitment binds each ciphertext to a
//!   single key, a property the Poly1305 tag alone cannot provide
//! - **Argon2id key derivation**: Password-based key derivation with a random
//!   salt, over the NFC-normalized password, with cost parameters stored
//!   alongside the ciphertext
//! - **Memory hygiene**: Automatic zeroization of sensitive data, including
//!   key derivation memory and serialization buffers
//! - **Type safety**: Generic over any serializable type, stored as
//!   self-describing CBOR so stored types can gain and lose fields
//! - **Stable format**: A versioned storage format with an authenticated header
//! - **Simple API**: Easy-to-use read/write interface
//!
//! ## Quick Start
//!
//! ```
//! use cipherbox::CipherBox;
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! // Create a box with secret data
//! let secret_data = String::from("my secret message");
//! let cipher_box = CipherBox::new(secret_data);
//!
//! // Encrypt and write to storage
//! // Use any [`std::io::Read`] for `read()`, and any [`std::io::Write`] for `write()`.
//! let mut encrypted_data = Vec::new();
//! cipher_box.write("my-password", &mut encrypted_data)?;
//!
//! // Read back and decrypt
//! let restored: CipherBox<String> = CipherBox::read("my-password", encrypted_data.as_slice())?;
//! assert_eq!(restored.as_str(), "my secret message");
//! # Ok(())
//! # }
//! ```
//!
//! ## Security Features
//!
//! - All sensitive data is automatically zeroized when dropped
//! - Uses cryptographically secure random number generation for salts and nonces
//! - Password verification through authenticated encryption
//! - No plaintext data is stored on disk

pub mod container;
pub mod error;
mod key;
mod normalize;
mod secret_buffer;
mod storage;

pub use container::CipherBox;
pub use error::Error;
pub use storage::recognizes;