Struct SecureString

Source

pub struct SecureString { /* private fields */ }

Expand description

A securely allocated, growable UTF-8 string, just like std::string::String.

It is a wrapper around SecureVec and inherits all of its security guarantees.

Access to the string contents is provided through scoped methods like unlock_str, which ensure the memory is only unlocked for the briefest possible time.

§Notes

If you return a new allocated String from one of the unlock methods you are responsible for zeroizing the memory.

§Example

use secure_types::{SecureString, Zeroize};

// Create a SecureString
let mut secret = SecureString::from("my_super_secret");

// The memory is locked here

// Safely append more data.
secret.push_str("_password");

// The memory is locked here.

// Use a scope to safely access the content as a &str.
secret.unlock_str(|exposed_str| {
    assert_eq!(exposed_str, "my_super_secret_password");
});

// Not recommended but if you allocate a new String make sure to zeroize it
let mut exposed = secret.unlock_str(|exposed_str| {
    String::from(exposed_str)
});

// Do what you need to to do with the new string
// When you are done with it, zeroize it
exposed.zeroize();

// When `secret` is dropped, its data zeroized.

Implementations§

Source §

pub unsafe fn from_utf8_unchecked(vec: SecureVec<u8>) -> SecureString

Creates a SecureString from a SecureVec<u8> without checking UTF-8.

§Safety

The caller must guarantee vec holds valid UTF-8. Violating this breaks the SecureString invariant and will make unlock_str/char_len/serde panic.

Source

pub fn erase(&mut self)

Source

pub fn byte_len(&self) -> usize

Returns the length of the inner SecureVec

If you want the character length use char_len

Source

pub fn is_empty(&self) -> bool

Source

pub fn drain(&mut self, range: Range<usize>)

Removes the specified range from the string

§Panics

Panics if the range is not on UTF-8 char boundaries.

Source

pub fn char_len(&self) -> usize

Returns the number of chars in the string

§Panics

Panics if the string is not valid UTF-8.

Source

pub fn char_len_unchecked(&self) -> usize

Returns the number of chars in the string

§Safety

The caller must guarantee that the string is valid UTF-8.

Source

pub fn push_str(&mut self, string: &str)

Push a &str into the SecureString

Source

pub fn unlock_str<F, R>(&self, f: F) -> R
where F: FnOnce(&str) -> R,

Immutable access as &str

It uses the from_utf8 function to check the validity of the internal bytes. If the bytes are not valid UTF-8, the function panics.

Source

pub fn unlock_str_unchecked<F, R>(&self, f: F) -> R
where F: FnOnce(&str) -> R,

Immutable access as &str

It uses the from_utf8_unchecked function to bypass the validity check.

§Safety

The caller must guarantee that the internal bytes are valid UTF-8.

Source

pub fn secure_mut<F, R>(&mut self, f: F) -> R
where F: FnOnce(&mut SecureString) -> R,

Mutable access to the SecureString

This method does not unlock the memory.

Source

pub fn insert_text_at_char_idx( &mut self, char_idx: usize, text_to_insert: &str, ) -> usize

Inserts text at the given character index

§Returns

The number of characters inserted

§Example

use secure_types::SecureString;

let mut string = SecureString::from("GreekFeta");
string.insert_text_at_char_idx(9, "Cheese");
string.unlock_str(|str| {
    assert_eq!(str, "GreekFetaCheese");
});

Source

pub fn delete_text_char_range(&mut self, char_range: Range<usize>)

Deletes the text in the given character range

§Example

use secure_types::SecureString;

let mut string = SecureString::from("GreekFetaCheese");
string.delete_text_char_range(9..15);
string.unlock_str(|str| {
    assert_eq!(str, "GreekFeta");
});