Struct SecretValue

Source

pub struct SecretValue(/* private fields */);

Expand description

A secret held as bytes and zeroized when it is dropped.

Debug and Display print ***, so the value does not end up in logs or panic messages. Clone makes a second buffer, and each copy is zeroized on its own drop. == takes time that depends on the lengths only, not on the bytes.

The value is read in two ways:

borrowing it with as_sensitive_* and ref_sensitive_value, which make no copy;
lending a copy to a closure with exposed_in_*, which makes sure the copy is zeroized once the closure is done with it.

use secret_vault_value::SecretValue;

let secret_value = SecretValue::from("my-password");
assert_eq!(format!("{secret_value:?}"), "***");
assert_eq!(secret_value.to_string(), "***");
assert_eq!(secret_value.as_sensitive_str(), "my-password");

Implementations§

Source §

impl SecretValue

Source

pub fn new(src: Vec<u8>) -> SecretValue

Takes ownership of src without copying it.

Source

pub fn ref_sensitive_value(&self) -> &Vec<u8> ⓘ

Borrows the secret bytes.

Source

pub fn ref_sensitive_value_mut(&mut self) -> &mut Vec<u8> ⓘ

Borrows the secret bytes mutably.

Be aware that growing the vector may reallocate it, and the old allocation is freed without being zeroized. Reserve the capacity up front if the value is built in place.

Source

pub fn sensitive_value_to_str(&self) -> Result<&str, Utf8Error>

Borrows the secret as a string slice.

§Errors

Returns Utf8Error if the bytes are not valid UTF-8.

use secret_vault_value::SecretValue;

assert!(SecretValue::from("my-password").sensitive_value_to_str().is_ok());
assert!(SecretValue::new(vec![0xff]).sensitive_value_to_str().is_err());

Source

pub fn secure_clear(&mut self)

Zeroizes the bytes and leaves the value empty.

use secret_vault_value::SecretValue;

let mut secret_value = SecretValue::from("my-password");
secret_value.secure_clear();
assert!(secret_value.as_sensitive_bytes().is_empty());

Source

pub fn as_sensitive_str(&self) -> &str

Borrows the secret as a string slice.

§Panics

Panics if the bytes are not valid UTF-8. Use sensitive_value_to_str for binary secrets.

Source

pub fn as_sensitive_bytes(&self) -> &[u8] ⓘ

Borrows the secret bytes as a slice.

Source

pub fn exposed_in_as_str<T, Z, FN>(&self, f: FN) -> T
where Z: Zeroize, FN: Fn(String) -> (T, Z),

Lends a String copy of the secret to f and returns the first item of its result.

f returns a pair (T, Z): T is the result, Z is whatever must be zeroized once f returns, usually the String it was given. A copy that f neither returns as Z nor zeroizes itself is not zeroized. exposed_in_as_zstr needs no such pair.

If f panics, the copy is freed without being zeroized. Use exposed_in_as_zstr, which zeroizes it on unwinding too.

§Panics

Panics if the bytes are not valid UTF-8.

use secret_vault_value::SecretValue;

let secret_value = SecretValue::from("my-password");
let length = secret_value.exposed_in_as_str(|password| (password.len(), password));
assert_eq!(length, 11);

Source

pub fn exposed_in_as_zstr<T, FN>(&self, f: FN) -> T
where FN: Fn(Zeroizing<String>) -> T,

Lends a Zeroizing<String> copy of the secret to f and returns its result.

The copy is zeroized when f drops it.

§Panics

Panics if the bytes are not valid UTF-8.

use secret_vault_value::SecretValue;

let secret_value = SecretValue::from("my-password");
let length = secret_value.exposed_in_as_zstr(|password| password.len());
assert_eq!(length, 11);

Source

pub fn exposed_in_as_vec<T, Z, FN>(&self, f: FN) -> T
where Z: Zeroize, FN: Fn(Vec<u8>) -> (T, Z),

Lends a Vec<u8> copy of the secret to f and returns the first item of its result.

The (T, Z) pair works as in exposed_in_as_str: Z is zeroized once f returns.

If f panics, the copy is freed without being zeroized. Use exposed_in_as_zvec, which zeroizes it on unwinding too.

use secret_vault_value::SecretValue;

let secret_value = SecretValue::new(vec![1, 2, 3]);
let sum = secret_value.exposed_in_as_vec(|bytes| (bytes.iter().sum::<u8>(), bytes));
assert_eq!(sum, 6);

Source

pub fn exposed_in_as_zvec<T, FN>(&self, f: FN) -> T
where FN: Fn(Zeroizing<Vec<u8>>) -> T,

Lends a Zeroizing<Vec<u8>> copy of the secret to f and returns its result.

The copy is zeroized when f drops it.

use secret_vault_value::SecretValue;

let secret_value = SecretValue::new(vec![1, 2, 3]);
let sum = secret_value.exposed_in_as_zvec(|bytes| bytes.iter().sum::<u8>());
assert_eq!(sum, 6);

Source

pub async fn exposed_in_as_str_async<T, Z, FN, FI>(&self, f: FN) -> T
where Z: Zeroize, FN: Fn(String) -> FI, FI: Future<Output = (T, Z)>,

Async form of exposed_in_as_str: Z is zeroized once the future returned by f completes.

If f or its future panics, or the future is dropped before it completes (a timeout, a losing select! branch, an aborted task), the copy is freed without being zeroized. Use exposed_in_as_zstr_async, which zeroizes it in those cases too.

§Panics

Panics if the bytes are not valid UTF-8.

use secret_vault_value::SecretValue;

async fn password_length(secret_value: &SecretValue) -> usize {
    secret_value
        .exposed_in_as_str_async(|password| async move { (password.len(), password) })
        .await
}

Source

pub async fn exposed_in_as_zstr_async<T, FN, FI>(&self, f: FN) -> T
where FN: Fn(Zeroizing<String>) -> FI, FI: Future<Output = T>,

Async form of exposed_in_as_zstr: the copy is zeroized when the future returned by f drops it.

§Panics

Panics if the bytes are not valid UTF-8.

use secret_vault_value::SecretValue;

async fn password_length(secret_value: &SecretValue) -> usize {
    secret_value
        .exposed_in_as_zstr_async(|password| async move { password.len() })
        .await
}

Source

pub async fn exposed_in_as_vec_async<T, Z, FN, FI>(&self, f: FN) -> T
where Z: Zeroize, FN: Fn(Vec<u8>) -> FI, FI: Future<Output = (T, Z)>,

Async form of exposed_in_as_vec: Z is zeroized once the future returned by f completes.

If f or its future panics, or the future is dropped before it completes (a timeout, a losing select! branch, an aborted task), the copy is freed without being zeroized. Use exposed_in_as_zvec_async, which zeroizes it in those cases too.

use secret_vault_value::SecretValue;

async fn key_length(secret_value: &SecretValue) -> usize {
    secret_value
        .exposed_in_as_vec_async(|key| async move { (key.len(), key) })
        .await
}

Source

pub async fn exposed_in_as_zvec_async<T, FN, FI>(&self, f: FN) -> T
where FN: Fn(Zeroizing<Vec<u8>>) -> FI, FI: Future<Output = T>,

Async form of exposed_in_as_zvec: the copy is zeroized when the future returned by f drops it.

use secret_vault_value::SecretValue;

async fn key_length(secret_value: &SecretValue) -> usize {
    secret_value
        .exposed_in_as_zvec_async(|key| async move { key.len() })
        .await
}

Source §

impl SecretValue

Source

pub fn expose_json_value_as<T>(&self) -> Result<T, Error>
where T: for<'de> Deserialize<'de> + for<'de> Zeroize,

Parses the secret as JSON into T.

The Zeroize bound lets the caller wipe the result, but the result is not zeroized automatically: call zeroize() on it, or wrap it in zeroize::Zeroizing, once it is no longer needed.

§Errors

Returns serde_json::Error if the secret is not valid JSON for T.

use secret_vault_value::SecretValue;
use serde::Deserialize;
use zeroize::{Zeroize, Zeroizing};

#[derive(Deserialize, Zeroize)]
struct Credentials {
    user: String,
    password: String,
}

let secret_value = SecretValue::from(r#"{"user":"admin","password":"my-password"}"#);
let credentials = Zeroizing::new(secret_value.expose_json_value_as::<Credentials>()?);
assert_eq!(credentials.user, "admin");