Struct CryptBox 

pub struct CryptBox<T> { /* private fields */ }

An “encrypted” box type, which encrypts the inner data

In particular:

• a CryptBox<T> owns three entire memory pages (12 KiB on modern systems, BEWARE!)
• the inner data is encrypted using Ascon128
• the pages are protected using mprotect by the flag Prot::NoAccess
• the memory will not be paged to the disk because of mlock

After creating a CryptBox<T> it is encrypted and can be decrypted to yield a PlainBox<T> instance. PlainBox<T> implements Deref and other traits which allow for deref coercion, but it does not implement any associated functions. To encrypt the underlying data again use CryptBox::encrypt. This approach eliminates unnecessary imports.

Both CryptBox<T> and PlainBox<T> implement Drop, which clears the memory they were using and sets it to zero, erasing all leftover data.

Note

This is not an allocator, thus storing types like Vec<T> or String does not make any sense (the CryptBox<T> will just store the fat pointer part of such structs).

Examples

Accessing data:

use insectbox::CryptBox;

let cb = CryptBox::new(b"I'm in a CryptBox :)".to_owned());
// at this point we can only decrypt such a box
let cb = cb.decrypt();
// because of deref coercion we can extract the data and do stuff with it
println!("{:?}", cb.as_ref());
// after finishing we can encrypt the data again
let cb = CryptBox::encrypt(cb);
// it will be dropped now, if this was the intended end of lifetime for cb
// we could have left it as a PlainBox<T>

Constructing from a constructor:

use insectbox::CryptBox;

fn make_arr<const N: usize>() -> [u8; N] {
    [0x69; N]
}

// will panic if size_of::<T>() + 16 > PAGE_SIZE
// AVOID large numbers
let cb = CryptBox::construct(make_arr::<32>);
let cb = cb.decrypt();

assert_eq!(&[0x69; 32], cb.as_slice());

Implementations

impl<T> CryptBox<T>

pub fn new(val: T) -> Self

Make a new CryptBox<T> by moving t into the memory owned by the box.

Panics

This function panics if size_of::<T>() + 16 > PAGE_SIZE or the encryption fails, or if the memory allocation failed.

pub fn construct<F: Fn() -> T>(f: F) -> Self

Make a new CryptBox<T> by calling f and assigning the result to the inner pointer.

Panics

This function panics if size_of::<T>() + 16 > PAGE_SIZE or the encryption fails, or if the memory allocation failed.

pub fn try_new(val: T) -> Option<CryptBox<T>>

Make a new CryptBox<T> by moving t into the memory owned by the box. Returns None on failure.

pub fn try_construct<F: Fn() -> T>(f: F) -> Option<CryptBox<T>>

Make a new CryptBox<T> by calling f and assigning the result to the inner pointer. Returns None on failure.

pub fn decrypt(self) -> PlainBox<T>

Consumes self and returns an instance of PlainBox<T> which can be used to access the inner data.

Panics

This will panic if there was a decryption failure. The allocation will be freed, unless it was the underlying memory which caused the failure.

pub fn encrypt(s: PlainBox<T>) -> CryptBox<T>

Takes ownership of a PlainBox<T> and encrypts it again as a CryptBox<T>.

Trait Implementations

impl<T: Debug> Debug for CryptBox<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> Drop for CryptBox<T>

fn drop(&mut self)

Executes the destructor for this type.