Struct cocoon::MiniCocoon

pub struct MiniCocoon { /* fields omitted */ }

This is a mini cocoon for a convenient and cool encryption.

Implementations

impl MiniCocoon

Stores data securely inside of a simple encrypted container ("mini cocoon").

Basic Usage

let cocoon = MiniCocoon::from_key(b"0123456789abcdef0123456789abcdef", &[0; 32]);

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");

Scroll down to Features and Methods Mapping, and also see crate's documentation for more use cases.

Default Configuration

Option	Value
Cipher	Chacha20Poly1305
Key derivation	PBKDF2 with 100 000 iterations

• Cipher can be customized using MiniCocoon::with_cipher method.
• Key derivation (KDF): only PBKDF2 is supported.

Features and Methods Mapping

Note: It is maybe not a complete list of API methods. Please, refer to the current documentation below to get familiarized with the full set of methods.

Method ↓ / Feature →	std	alloc	"no_std"
MiniCocoon::from_key	✔️	✔️	✔️
MiniCocoon::from_password	✔️	✔️	✔️
MiniCocoon::encrypt	✔️	✔️	✔️
MiniCocoon::decrypt	✔️	✔️	✔️
MiniCocoon::wrap	✔️	✔️	❌
MiniCocoon::unwrap	✔️	✔️	❌
MiniCocoon::dump	✔️	❌	❌
MiniCocoon::parse	✔️	❌	❌

pub fn from_key(key: &[u8], seed: &[u8]) -> Self

Creates a new MiniCocoon with a symmetric key seeding a random generator using a given seed buffer.

• key - a symmetric key of length 32
• seed - 32 random bytes to initialize an internal random generator

Examples

use cocoon::MiniCocoon;
use rand::Rng;

// Seed can be obtained by any cryptographically secure random generator.
// ThreadRng is used as an example.
let seed = rand::thread_rng().gen::<[u8; 32]>();

// Key must be 32 bytes of length. Let it be another 32 random bytes.
let key = rand::thread_rng().gen::<[u8; 32]>();

let cocoon = MiniCocoon::from_key(&key, &seed);

pub fn from_password(password: &[u8], seed: &[u8]) -> Self

Creates a new MiniCocoon with a password. Under the hood, an encryption key is created from the password using PBKDF2 algorithm.

• password - a password of any length
• seed - 32 random bytes to initialize an internal random generator

Examples

use cocoon::MiniCocoon;
use rand::Rng;

// Seed can be obtained by any cryptographically secure random generator.
// ThreadRng is used as an example.
let seed = rand::thread_rng().gen::<[u8; 32]>();

let cocoon = MiniCocoon::from_password(b"my password", &seed);

pub fn with_cipher(self, cipher: CocoonCipher) -> Self

Sets an encryption algorithm to wrap data on.

Examples

use cocoon::{MiniCocoon, CocoonCipher};
use rand::Rng;

let seed = rand::thread_rng().gen::<[u8; 32]>();
let key = rand::thread_rng().gen::<[u8; 32]>();

let cocoon = MiniCocoon::from_key(&key, &seed).with_cipher(CocoonCipher::Chacha20Poly1305);
cocoon.wrap(b"my secret data");

pub fn wrap(&self, data: &[u8]) -> Result<Vec<u8>, Error>

This is supported on crate features alloc or std only.

Wraps data to an encrypted container.

• data - a sensitive user data

Examples:

let seed = rand::thread_rng().gen::<[u8; 32]>();
let cocoon = MiniCocoon::from_password(b"password", &seed);

let wrapped = cocoon.wrap(b"my secret data")?;
assert_ne!(&wrapped, b"my secret data");

pub fn dump(&self, data: Vec<u8>, writer: &mut impl Write) -> Result<(), Error>

This is supported on crate feature std only.

Encrypts data in place, taking ownership over the buffer, and dumps the container into File, Cursor, or any other writer.

• data - a sensitive data inside of Vec to be encrypted in place
• writer - File, Cursor, or any other output

A data is going to be encrypted in place and stored in a file using the "mini cocoon" format.

Examples

let key = [ 1,  2,  3,  4,  5,  6,  7,  8,  9, 10, 11, 12, 13, 14, 15, 16,
           17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32];
let seed = rand::thread_rng().gen::<[u8; 32]>();

let cocoon = MiniCocoon::from_key(&key, &seed);

let mut data = b"my secret data".to_vec();

cocoon.dump(data, &mut file)?;

pub fn encrypt(&self, data: &mut [u8]) -> Result<[u8; 36], Error>

Encrypts data in place and returns a detached prefix of the container.

The prefix is needed to decrypt data with MiniCocoon::decrypt. This method doesn't use memory allocation and it is suitable in the build with no std and no alloc.

Examples

let cocoon = MiniCocoon::from_password(b"password", &[1; 32]);

let mut data = "my secret data".to_owned().into_bytes();

let detached_prefix = cocoon.encrypt(&mut data)?;
assert_ne!(data, b"my secret data");

pub fn unwrap(&self, container: &[u8]) -> Result<Vec<u8>, Error>

This is supported on crate features alloc or std only.

Unwraps data from the encrypted container (see MiniCocoon::wrap).

Examples

let key = b"0123456789abcdef0123456789abcdef";
let seed = rand::thread_rng().gen::<[u8; 32]>();

let cocoon = MiniCocoon::from_key(key, &seed);

let unwrapped = cocoon.unwrap(&wrapped)?;
assert_eq!(unwrapped, b"my secret data");

pub fn parse(&self, reader: &mut impl Read) -> Result<Vec<u8>, Error>

This is supported on crate feature std only.

Parses container from the reader (file, cursor, etc.), validates format, allocates memory and places decrypted data there.

• reader - File, Cursor, or any other input

Examples

let key = b"0123456789abcdef0123456789abcdef";
let seed = rand::thread_rng().gen::<[u8; 32]>();

let cocoon = MiniCocoon::from_key(key, &seed);

let data = cocoon.parse(&mut file)?;
assert_eq!(&data, b"my secret data");

pub fn decrypt(
    &self,
    data: &mut [u8],
    detached_prefix: &[u8]
) -> Result<(), Error>

Decrypts data in place using the parts returned by MiniCocoon::encrypt method.

The method doesn't use memory allocation and is suitable for "no std" and "no alloc" build.

Examples

let mut data = "my secret data".to_owned().into_bytes();
let cocoon = MiniCocoon::from_password(b"password", &[0; 32]);

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");