Struct SecureVec

pub struct SecureVec<T>
where
    T: Zeroize,
{ /* private fields */ }

A securely allocated, growable vector, analogous to std::vec::Vec.

SecureVec<T> is designed to hold a sequence of sensitive data elements. It serves as the foundational secure collection in this crate.

Security Model

When compiled with the std feature (the default), it provides several layers of protection:

• Zeroization on Drop: The memory region is securely zeroized when the vector is dropped.
• Memory Locking: The underlying memory pages are locked using mlock (Unix) or VirtualLock (Windows) to prevent the OS from swapping them to disk.
• Memory Encryption: On Windows, the memory is also encrypted using CryptProtectMemory.

In a no_std environment, it falls back to providing only the zeroization-on-drop guarantee.

Program Termination

Direct indexing (e.g., vec[0]) on a locked vector will cause the operating system to terminate the process with an access violation error.

Always use the provided scope methods (slice_scope, slice_mut_scope) for safe access.

Examples

Using SecureBytes (a type alias for SecureVec<u8>) to handle a secret key.

use secure_types::SecureBytes;

// Create a new, empty secure vector.
let mut secret_key = SecureBytes::new().unwrap();

// Push some sensitive data into it.
secret_key.push(0xAB);
secret_key.push(0xCD);
secret_key.push(0xEF);

// The memory is locked here.

// Use a scope to safely access the contents as a slice.
secret_key.slice_scope(|unlocked_slice| {
    assert_eq!(unlocked_slice, &[0xAB, 0xCD, 0xEF]);
    println!("Secret Key: {:?}", unlocked_slice);
});

// The memory is automatically locked again when the scope ends.

// When `secret_key` is dropped, its memory is securely zeroized.

Implementations

impl<T: Zeroize> SecureVec<T>

pub fn new() -> Result<Self, Error>

pub fn new_with_capacity(capacity: usize) -> Result<Self, Error>

pub fn from_vec(vec: Vec<T>) -> Result<Self, Error>

pub fn from_slice_mut(slice: &mut [T]) -> Result<Self, Error>

where T: Clone + DefaultIsZeroes,

Create a new SecureVec from a mutable slice. The slice is zeroized afterwards

pub fn from_slice(slice: &[T]) -> Result<Self, Error>

where T: Clone,

Create a new SecureVec from a slice. The slice is not zeroized, you are responsible for zeroizing it

pub fn len(&self) -> usize

pub fn as_ptr(&self) -> *const T

pub fn as_mut_ptr(&mut self) -> *mut u8

pub fn unlock_scope<F, R>(&self, f: F) -> R

where F: FnOnce(&SecureVec<T>) -> R,

Immutable access to the SecureVec

pub fn slice_scope<F, R>(&self, f: F) -> R

where F: FnOnce(&[T]) -> R,

Immutable access to the SecureVec as &[T]

pub fn slice_mut_scope<F, R>(&mut self, f: F) -> R

where F: FnOnce(&mut [T]) -> R,

Mutable access to the SecureVec as &mut [T]

pub fn iter_scope<F, R>(&self, f: F) -> R

where F: FnOnce(Iter<'_, T>) -> R,

Immutable access to the SecureVec as Iter<T>

Use with caution

You can actually return a new allocated Vec from this function

If you do that you are responsible for zeroizing its contents

pub fn iter_mut_scope<F, R>(&mut self, f: F) -> R

where F: FnOnce(IterMut<'_, T>) -> R,

Mutable access to the SecureVec as IterMut<T>

Use with caution

You can actually return a new allocated Vec from this function

If you do that you are responsible for zeroizing its contents

pub fn erase(&mut self)

Erase the underlying data and clears the vector

The memory is locked again and the capacity is preserved for reuse

pub fn clear(&mut self)

Clear the vector

This just sets the vector’s len to zero it does not erase the underlying data

pub fn push(&mut self, value: T)

pub fn reserve(&mut self, additional: usize)

Ensures that the vector has enough capacity for at least additional more elements.

If more capacity is needed, it will reallocate. This may cause the buffer location to change.

Panics

Panics if the new capacity overflows usize or if the allocation fails.

pub fn drain<R>(&mut self, range: R) -> Drain<'_, T>

where R: RangeBounds<usize>,

Creates a draining iterator that removes the specified range from the vector and yields the removed items.

Note: The vector is unlocked during the lifetime of the Drain iterator. The memory is relocked when the Drain iterator is dropped.

Panics

Panics if the starting point is greater than the end point or if the end point is greater than the length of the vector.

Trait Implementations

impl<T: Clone + Zeroize> Clone for SecureVec<T>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Zeroize> Drop for SecureVec<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<const LENGTH: usize> From<SecureArray<u8, LENGTH>> for SecureVec<u8>

fn from(array: SecureArray<u8, LENGTH>) -> Self

Converts to this type from the input type.

impl From<SecureVec<u8>> for SecureString

fn from(vec: SecureVec<u8>) -> Self

Converts to this type from the input type.

impl<T: Zeroize> Index<usize> for SecureVec<T>

type Output = T

The returned type after indexing.

fn index(&self, index: usize) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<const LENGTH: usize> TryFrom<SecureVec<u8>> for SecureArray<u8, LENGTH>

fn try_from(vec: SecureVec<u8>) -> Result<Self, Self::Error>

Tries to convert a SecureVec<u8> into a SecureArray<u8, LENGTH>.

This operation will only succeed if vec.len() == LENGTH. The original SecureVec is consumed.

type Error = Error

The type returned in the event of a conversion error.

impl<T: Zeroize + Send> Send for SecureVec<T>

impl<T: Zeroize + Send + Sync> Sync for SecureVec<T>