[−][src]Crate cocoon
Cocoon
Cocoon
is a protected container to wrap sensitive data with a strong
encryption and format validation. A format of Cocoon
is developed for the following practical cases:
- As a file format to organize a simple secure storage:
- Key store.
- Password store.
- Sensitive data store.
- For encrypted data transfer:
- As a secure in-memory container.
Problem
Every time when you need a secure storage you re-invent the wheel: you have to take care
how to encrypt data properly, how to store and transmit randomly generated
buffers, then to get data back, parse, and decrypt securely. Instead you can use Cocoon
.
Basic Usage
Wrap/Unwrap
One party wraps a private data into a container using Cocoon::wrap
.
Another party (or the same one, or whoever knows the password) unwraps a private data
out of the container using Cocoon::unwrap
.
let cocoon = Cocoon::new(b"password"); let wrapped = cocoon.wrap(b"my secret data")?; assert_ne!(&wrapped, b"my secret data"); let unwrapped = cocoon.unwrap(&wrapped)?; assert_eq!(unwrapped, b"my secret data");
Dump/Parse
You can store data to file. Put data into Vec
container, the data is going to be
encrypted in place and stored in a file using the "cocoon" format.
let mut data = b"my secret data".to_vec(); let cocoon = Cocoon::new(b"password"); cocoon.dump(data, &mut file)?; let data = cocoon.parse(&mut file)?; assert_eq!(&data, b"my secret data");
Encrypt/Decrypt
You can encrypt data in place and avoid re-allocations. The method operates with a detached
meta-data (a container format prefix) in the array on the stack. It is suitable for "no_std
"
build and whenever you want to evade re-allocations of a huge amount of data. You have to care
how to store and transfer a data length and a container prefix though.
let mut data = "my secret data".to_owned().into_bytes(); let cocoon = Cocoon::from_crypto_rng(b"password", good_rng); let detached_prefix = cocoon.encrypt(&mut data)?; assert_ne!(data, b"my secret data"); cocoon.decrypt(&mut data, &detached_prefix)?; assert_eq!(data, b"my secret data");
Study Case
You implement a database of secrets which must be stored to an encrypted file using a user
password. There are a lot of ways how your database can be represented in memory and how
it could be serialized. You handle these aspects on your own, e.g. you can use
HashMap
to manage data and use borsh
, or bincode
,
to serialize the data. You can even compress serialized buffer before encryption.
In the end you use Cocoon
to put the final image into encrypted container.
use borsh::BorshSerialize; use cocoon::{Cocoon, Error}; use std::collections::HashMap; use std::fs::File; #[derive(BorshSerialize)] struct Database { inner: HashMap<String, String>, } fn main() -> Result<(), Error> { let mut file = File::create("target/test.db")?; let mut db = Database { inner: HashMap::new() }; db.inner.insert("my.email@example.com".to_string(), "eKPV$PM8TV5A2".to_string()); let encoded = db.try_to_vec().unwrap(); // Don't use hard-coded password in real life! // It could be a user-supplied password. let cocoon = Cocoon::new(b"secret password"); // Dump serialized database into file as an encrypted container. let container = cocoon.dump(encoded, &mut file)?; Ok(()) }
Crate Features
You can customize the package compilation with the following feature set:
Feature | Description |
---|---|
std | Enables almost all API, including I/O, excluding getrandom feature. |
alloc | Enables API with memory allocation, but without std dependency. |
getrandom | Enables Cocoon::from_entropy . |
no features | Creation and decryption a cocoon on the stack with no thread RNG, I/O, heap. |
std
is enabled by default, so you can just link the cocoon
to you project:
[dependencies]
cocoon = "0"
To use no features:
[dependencies]
cocoon = { version = "0", default-features = false }
To use only alloc
feature:
[dependencies]
cocoon = { version = "0", default-features = false, features = ['alloc'] }
Cryptography
256-bit cryptography is chosen as a Cocoon
baseline.
Cipher (AEAD) | Key Derivation Function (KDF) |
---|---|
Chacha20-Poly1305 | PBKDF2-SHA256: 100000 iterations |
AES256-GCM |
- Key: 256-bit.
- Salt for KDF: random 128-bit + predefined part.
- Nonce for encryption: random 96-bit.
Key derivation parameters comply with NIST SP 800-132 recommendations (salt, iterations), and cipher parameters (key, nonce) fit requirements of a particular cipher. AEAD is chosen in order to authenticate an encrypted data together with an unencrypted header.
Zeroization
Encryption key is wrapped into zeroizing container
(provided by zeroize
crate), which means that the key is erased automatically once it is dropped.
Container Creation
First, a random material is generated. A salt is going to get mixed into a master key, and a nonce is used for AEAD encryption. All arrays are put into a header which prefixes the final container.
Then a master key is derived from a password using selected Key Derivation Function (KDF, e.g. PBKDF2) and a random salt.
At this moment we have everything to encrypt data and to create a container. Authenticated Encryption with Associated Data (AEAD) is used to encrypt data and to produce a tag which controls integrity of both header and data. The tag is deliberately placed at the beginning that allows to detach the whole prefix (header and tag) which helps certain cases, e.g. it allows to work on stack, makes API more flexible, gets additional control over the container format.
Container can be dumped to file, or it can be kept in the buffer.
Container Parsing
It starts from header parsing because random material is needed to restore a master key in order to decrypt a data.
Random generator is not needed in this case. (That's why Cocoon::parse_only
is provided
as an alternative way to initialize Cocoon
to only parse a container without necessity
to initialize RNG.)
A master key is derived from a password and a salt.
Finally, integrity of all parts is verified and data is decrypted.
Structs
Cocoon | Stores data securely inside of encrypted container. |
Enums
CocoonCipher | 256-bit AEAD ciphers (Authenticated Encryption with Associated Data). |
CocoonKdf | Key derivation functions (KDF) to derive master key from user password. PBKDF2 by default. |
Error | Error variants produced by the Cocoon API. |
Constants
PREFIX_SIZE | The size of the cocoon prefix which appears in detached form in |