Struct safebox::SafeBox

pub struct SafeBox<T: ?Sized>(_);

A safe box for your secrets.

On Drop the content T is zeroed in RAM with memzero.

It can only be instantiated with Copy types. This forbids instantiating a SafeBox<Vec<T>> for example, which cannot be zeroed.

&T access is guarded behind the unsafe get_ref method. This prevents involuntary copies or clone of the content. Deref is not implemented.

&mut T is also guarded behind unsafe get_mut. This prevents involuntary memswap or memreplace of the content. And because DerefMut is not implemented, the content cannot be moved out either. Remember that it is perfectly safe to move or swap the SafeBox itself, because the content never moves, merely the smart pointer details.

Because only Copy types are accepted for the content, it is possible to provide a safe implementation of Clone. It allocates a new SafeBox with a memcopy of the content.

It is implemented as a wrapper around a Box.

Methods

impl<T: Copy> SafeBox<T>

pub fn new(v: T) -> Self

Allocate a new SafeBox from the given value.

Since v is passed by copy/move, it is advised to initialize with some safe value. Then use SafeBox::get_mut to write the secret value with the least amount of intermediate copies.

impl<T: Copy> SafeBox<[T]>

pub fn new_slice(v: T, len: usize) -> Self

Allocate a new SafeBox<[T]>.

The value v is copied into all len elements.

impl<T> SafeBox<[T]>

pub fn new_slice_with<F: Fn() -> T>(len: usize, f: F) -> Self

Allocate a new SafeBox<[T]>.

The function f is called to initialize the len elements.

use safebox::SafeBox;
use rand::prelude::*;
let random_secret = SafeBox::new_slice_with(8, &random::<u8>);

impl<T: ?Sized> SafeBox<T>

pub unsafe fn get_ref(&self) -> &T

A &T reference to the content.

This is unsafe, because it allows for copying the content around in memory. Of course, a secret must be read at some point to be useful. But you bear all responsibility in copying it around.

pub unsafe fn get_mut(&mut self) -> &mut T

A &mut T reference to the content.

This is unsafe, because it allows for copying the content around in memory. Of course, a secret must be initialized at some point to be useful. But you bear all responsibility in copying it around.

Trait Implementations

impl<T: ?Sized> Drop for SafeBox<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T: Copy> Clone for SafeBox<T>

fn clone(&self) -> Self

Clone a SafeBox<T> via memcopy.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Copy> Clone for SafeBox<[T]>

fn clone(&self) -> Self

Clone a SafeBox<[T]> via memcopy.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Default + Copy> Default for SafeBox<T>

fn default() -> Self

Allocate a new SafeBox with the default value.

See SafeBox::new.