Struct cocoon::MiniCocoon [−][src]
pub struct MiniCocoon { /* fields omitted */ }
Expand description
This is a mini cocoon for a convenient and cool encryption.
Implementations
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 | ✔️ | ❌ | ❌ |
Creates a new MiniCocoon
with a symmetric key seeding a random generator
using a given seed
buffer.
key
- a symmetric key of length 32seed
- 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);
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 lengthseed
- 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);
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");
This is supported on crate features alloc
or std
only.
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");
This is supported on crate feature std
only.
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 ofVec
to be encrypted in placewriter
-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)?;
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");
This is supported on crate features alloc
or std
only.
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");
This is supported on crate feature std
only.
std
only.Parses container from the reader (file, cursor, etc.), validates format, allocates memory and places decrypted data there.
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");
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");