Struct secrets::SecretVec

pub struct SecretVec<T> { /* fields omitted */ }

A type that wraps a dynamic amount of allocated memory suitable for cryptographic secrets.

When initialized with existing data, the memory of the existing data is zeroed out. That said, this library cannot guarantee that that memory has not been copied elsewhere, swapped to disk, or otherwise handled insecurely so rely on this with caution.

Examples

Generating cryptographic keys:

use secrets::SecretVec;

let secret   = SecretVec::<u8>::random(32);
let secret_r = secret.borrow();

println!("{:?}", secret_r);

Secrets from existing mutable data:

use secrets::SecretVec;

// static data for the test; static data *can't* be wiped, but
// copies of it will be
let reference : &'static [u8; 4] = b"\xfa\x12\x00\xd9";
let zeroes    : &'static [u8; 4] = b"\x00\x00\x00\x00";

let mut bytes = *reference;
let secret    = SecretVec::from(&mut bytes[..]);
let secret_r  = secret.borrow();

assert_eq!(*reference, &*secret_r);
assert_eq!(*zeroes,    bytes);

Accessing array contents through pointers:

use secrets::SecretVec;
use std::ptr;

let mut secret   = unsafe { SecretVec::<u8>::uninitialized(4) };
let mut secret_w = secret.borrow_mut();

unsafe {
    ptr::write_bytes(
        secret_w.as_mut_ptr(),
        0xd0,
        secret_w.len(),
    );
}

assert_eq!(*b"\xd0\xd0\xd0\xd0", &*secret_w);

Wrapping custom struct types:

use secrets::{SecretVec, Zeroable};

#[derive(Debug)]
#[derive(PartialEq)]
struct SensitiveData { a: u64, b: u8 };

impl Zeroable for SensitiveData {};
impl Default  for SensitiveData {
    fn default() -> Self { SensitiveData { a: 100, b: 255 } }
}

let zeroed  = SecretVec::<SensitiveData>::zero(1);
let default = SecretVec::<SensitiveData>::default(1);

assert_eq!(SensitiveData { a: 0, b: 0 }, zeroed .borrow()[0]);
assert_eq!(SensitiveData::default(),     default.borrow()[0]);

Methods

impl<T> SecretVec<T> where
    T: Default, 

fn default(len: usize) -> Self

Creates a new SecretVec filled with len of the default value for T.

impl<T> SecretVec<T> where
    T: Randomizable, 

fn random(len: usize) -> Self

Creates a new SecretVec filled with len cryptographically random objects of type T.

impl<T> SecretVec<T> where
    T: Zeroable, 

fn zero(len: usize) -> Self

Creates a new SecretVec filled with len zeroed objects of type T.

impl<T> SecretVec<T>

unsafe fn uninitialized(len: usize) -> Self

Creates a new SecretVec capable of storing len objects of type T.

By default, the allocated region is filled with 0xd0 bytes in order to help catch bugs due to uninitialized data. This method is marked as unsafe because filling an arbitrary type with garbage data is undefined behavior.

unsafe fn new<F>(len: usize, init: F) -> Self where
    F: FnOnce(&mut T), 

Creates and initializes a new SecretVec capable of storing an object of type T.

Initialization is handled by a closure passed to method, which accepts a reference to the object to be initialized. The data in this reference will be uninitialized until written to, so care must be taken to initialize its memory without reading from it to avoid undefined behavior.

fn len(&self) -> usize

Returns the number of elements in the SecretVec.

fn size(&self) -> usize

Returns the size in bytes of the data contained in the SecretVec

fn borrow(&self) -> RefVec<T>

Returns a RefVec<T> from which elements in the SecretVec can be safely read from using slice semantics.

fn borrow_mut(&mut self) -> RefVecMut<T>

Returns a RefVecMut<T> from which elements in the SecretVec can be safely read from or written to using slice semantics.

Trait Implementations

impl<T: Debug> Debug for SecretVec<T>

fn fmt(&self, __arg_0: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<T> PartialEq for SecretVec<T>

fn eq(&self, s: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T> Eq for SecretVec<T>

impl<'a, T> From<&'a mut [T]> for SecretVec<T> where
    T: Zeroable, 

fn from(data: &mut [T]) -> Self

Moves the contents of data into a SecretVec and zeroes out the contents of data.