Struct privatebox::PrivateBox [−][src]
pub struct PrivateBox<T: RngCore> { /* fields omitted */ }
Expand description
A wrapper around XChaChaPoly1305 for convenient encryption
Implementations
impl<T: RngCore> PrivateBox<T>
[src]
impl<T: RngCore> PrivateBox<T>
[src]Generates basic containers that store encrypted data
Basic Usage
let mut privatebox = PrivateBox::new(b"0123456789abcdef0123456789abcdef", OsRng); let header = b"stored plain text"; let metadata = b"plain text"; let container = privatebox.encrypt(b"secret data", &*header, &*metadata)?; assert_ne!(&container, b"secret data"); let (decrypted_message, authenticated_header) = privatebox.decrypt(&container, &*metadata)?; assert_eq!(decrypted_message, b"secret data"); assert_eq!(authenticated_header, b"stored plain text");
Associated Data
Associated data in an AEAD is data that is authenticated but not encrypted.
It is provided during the encryption and decryption stage. It does not
necessarily have to be stored with the ciphertext. Hence PrivateBox::encrypt
has an authenticated header
(stored in container) and metadata
(stored separately).
The metadata thus is provided separately from the container during PrivateBox::decrypt
. When doing
detached encryption/decryption there is just assoc_data
as storage is handled
by user. For use cases check out this stackexchange answer
Nonces
Nonces are arbitrary numbers used in encryption and are one time use per key. PrivateBox uses XChaChaPoly1305 which is ChaChaPoly1305 with an extended nonce (24 bytes instead of 12). Therefore it is OK (libsodium ref) to use a random number generator for nonce generation. The random number generator provided upon the creation of PrivateBox is used to generate nonces. The generator is not cloned during encryption so each pass produces a different nonce.
Features
Enabling alloc
(on by default) lets you access PrivateBox::encrypt
and PrivateBox::decrypt
pub fn new(key: &[u8; 32], rng: T) -> Self
[src]
pub fn new(key: &[u8; 32], rng: T) -> Self
[src]Creates a new PrivateBox
with a symmetric key and a random number generator
key
- a 32 byte symmetric keyrng
- a random number generator that generates nonces, implementsRngCore
Examples
use privatebox::PrivateBox; use rand_core::{RngCore, OsRng}; // Key must have a length of 32 bytes. let mut key = [0u8; 32]; OsRng.fill_bytes(&mut key); let privatebox = PrivateBox::new(&key, OsRng);
pub fn encrypt_detached(
&mut self,
data: &mut [u8],
assoc_data: &[u8]
) -> Result<[u8; 40], PrivateBoxError>
[src]
pub fn encrypt_detached(
&mut self,
data: &mut [u8],
assoc_data: &[u8]
) -> Result<[u8; 40], PrivateBoxError>
[src]Encrypts message in place with associated data and returns a detached prefix for the data.
message
- data to be encrypted in placeassoc_data
- associated data to be used
The prefix is needed to decrypt the data with PrivateBox::decrypt
The prefix is an array of bytes with nonce first, tag second.
This method does not use memory allocation and suitable in the build without alloc
Examples
let mut privatebox = PrivateBox::new(&[1;32], OsRng); let mut message = *b"secret data"; let assoc_data = *b"plain text"; let detached_prefix = privatebox.encrypt_detached(&mut message, &assoc_data); assert_ne!(&message, b"secret data");
pub fn decrypt_detached(
&self,
message: &mut [u8],
assoc_data: &[u8],
detached_prefix: &[u8; 40]
) -> Result<(), PrivateBoxError>
[src]
pub fn decrypt_detached(
&self,
message: &mut [u8],
assoc_data: &[u8],
detached_prefix: &[u8; 40]
) -> Result<(), PrivateBoxError>
[src]Decrypts message in place using associated data and prefix returned by the PrivateBox::encrypt
method.
message
- data to be encrypted in placeassoc_data
- associated data to be used in decryption
The method doesn’t use memory allocation and is suitable in the build without alloc
Examples
let mut privatebox = PrivateBox::new(&[1;32], OsRng); let mut message = *b"secret data"; let detached_prefix = privatebox.encrypt_detached(&mut message, &[])?; assert_ne!(&message, b"secret data"); privatebox.decrypt_detached(&mut message, &[], &detached_prefix)?; assert_eq!(&message, b"secret data");
pub fn encrypt(
&mut self,
message: &[u8],
header: &[u8],
metadata: &[u8]
) -> Result<Vec<u8>, PrivateBoxError>
[src]
This is supported on crate feature alloc
only.
pub fn encrypt(
&mut self,
message: &[u8],
header: &[u8],
metadata: &[u8]
) -> Result<Vec<u8>, PrivateBoxError>
[src]alloc
only.Encrypts message and outputs a container with all necessary data to decrypt
message
- data to be encryptedheader
- data to be authenticated and stored in the containermetadata
- data to be authenticated but not stored
Examples
let mut privatebox = PrivateBox::new(&[1;32], OsRng); let message = *b"secret data"; let header = *b"attached data"; let metadata = *b"detached data"; let container = privatebox.encrypt(&message, &header, &metadata)?;
pub fn decrypt(
&self,
container: &[u8],
metadata: &[u8]
) -> Result<(Vec<u8>, Vec<u8>), PrivateBoxError>
[src]
This is supported on crate feature alloc
only.
pub fn decrypt(
&self,
container: &[u8],
metadata: &[u8]
) -> Result<(Vec<u8>, Vec<u8>), PrivateBoxError>
[src]alloc
only.Decrypts a container and outputs the authenticated header and decrypted message
During decryption the header and provided metadata
is concatenated to produce the
full associated data. Successful decryption means that the provided metadata was authenticated.
container
- the container outputed byPrivateBox::encrypt
metadata
- authenticated data not stored in the container
Examples
let mut privatebox = PrivateBox::new(&[1;32], OsRng); let message = *b"secret data"; let header = *b"attached data"; let metadata = *b"detached data"; let container = privatebox.encrypt(&message, &header, &metadata)?; // Note only the metadata is required for decryption let (decrypted_message, authenticated_header) = privatebox.decrypt(&container, &metadata)?; assert_eq!(&decrypted_message, &message); assert_eq!(&authenticated_header, &header);
pub fn parse_insecure_header(
&self,
container: &[u8]
) -> Result<Vec<u8>, PrivateBoxError>
[src]
This is supported on crate feature alloc
only.
pub fn parse_insecure_header(
&self,
container: &[u8]
) -> Result<Vec<u8>, PrivateBoxError>
[src]alloc
only.Retrieve the insecure header data from a container
container
- container outputted byPrivateBox::encrypt
The header data is not authenticated, it is insecure. It may have been altered so use at your own risk.
Examples
let mut privatebox = PrivateBox::new(&[1;32], OsRng); let header = &[4, 4, 1, 1]; let container = privatebox.encrypt(&*b"data", header, &[])?; let insecure_header = privatebox.parse_insecure_header(&container)?; // In this case header and insecure header are the same (but not guranteed) assert_eq!(&insecure_header, header);
Auto Trait Implementations
impl<T> RefUnwindSafe for PrivateBox<T> where
T: RefUnwindSafe,
T: RefUnwindSafe,
impl<T> Send for PrivateBox<T> where
T: Send,
T: Send,
impl<T> Sync for PrivateBox<T> where
T: Sync,
T: Sync,
impl<T> Unpin for PrivateBox<T> where
T: Unpin,
T: Unpin,
impl<T> UnwindSafe for PrivateBox<T> where
T: UnwindSafe,
T: UnwindSafe,
Blanket Implementations
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]pub fn borrow_mut(&mut self) -> &mut T
[src]
pub fn borrow_mut(&mut self) -> &mut T
[src]Mutably borrows from an owned value. Read more
impl<T> Same<T> for T
impl<T> Same<T> for T
type Output = T
type Output = T
Should always be Self