Struct RTSecret

pub struct RTSecret<T: Zeroize, MEC: ChooseMinimallyRepresentableUInt>(/* private fields */);

A runtime secret with optional zeroization for the type T and exposure count tracking. It is the runtime version of Secret<T, MEC, EC>.

Implementations

impl<T: Zeroize, MEC: ChooseMinimallyRepresentableUInt> RTSecret<T, MEC>

pub const fn new(t: T) -> Self

Creates a new RTSecret with the provided secret value t.

Parameters

• t: The secret value.

Returns

The newly created RTSecret.

pub fn new_with(f: impl FnOnce() -> T) -> Self

Creates a new RTSecret with the provided secret value returned by the closure f.

Parameters

• f: A closure that returns the secret value.

Returns

The newly created RTSecret.

pub fn exposure_count( &self, ) -> <MEC as ChooseMinimallyRepresentableUInt>::Output

Retrieves the current exposure count of the secret and returns it as an unsigned integer.

Note: The actual unsigned integer type returned depends on the type-level value of the type parameter MEC, it is the minimal representable Rust’s unsigned integer type that can represent the value. e.g. if MEC is typenum::consts::U67, then the returned type is u8.

Trait Implementations

impl<T, MEC> Clone for RTSecret<T, MEC>

where T: CloneableSecret, MEC: ChooseMinimallyRepresentableUInt + Unsigned,

Available on crate feature cloneable-secret only.

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T, MEC> Debug for RTSecret<T, MEC>

where T: DebugSecret, MEC: ChooseMinimallyRepresentableUInt + Unsigned,

Available on crate feature debug-secret only.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: Zeroize, MEC: ChooseMinimallyRepresentableUInt> Drop for RTSecret<T, MEC>

fn drop(&mut self)

Zeroizes the secret value when dropped if the zeroize feature is enabled.

impl<'secret, T: Zeroize, MEC: ChooseMinimallyRepresentableUInt + Unsigned + IsGreater<U0, Output = True> + Debug> RTExposeSecret<'secret, &'secret T> for RTSecret<T, MEC>

fn expose_secret<ReturnType, ClosureType>( &self, scope: ClosureType, ) -> ReturnType

where for<'brand> ClosureType: FnOnce(RTExposedSecret<'brand, &'brand T>) -> ReturnType,

Exposes the secret with runtime checking that the exposure count is not more than the maximally allowed exposure count represented by the type parameter MEC. Note: It is impossible to return the ‘exposed secret’ as the return value of the closure.

Example:

use sosecrets_rs::{
    prelude::typenum::U2,
    runtime::{secret::RTSecret, traits::RTExposeSecret},
};
#[cfg(feature = "zeroize")]
use zeroize::Zeroize;

struct A {
    inner: i32,
}

#[cfg(feature = "zeroize")]
impl Zeroize for A {
    fn zeroize(&mut self) {
        self.inner.zeroize()
    }
}

let secret_one = RTSecret::<A, U2>::new(A { inner: 69 });
let returned_value = secret_one.expose_secret(|exposed_secret| A { inner: (*exposed_secret).inner + 1});
assert_eq!(returned_value.inner, 70);

Example (this does NOT compile):

use sosecrets_rs::{
    prelude::typenum::U2,
    runtime::{secret::RTSecret, traits::RTExposeSecret},
};
#[cfg(feature = "zeroize")]
use zeroize::Zeroize;

struct A {
    inner: i32,
}

#[cfg(feature = "zeroize")]
impl Zeroize for A {
    fn zeroize(&mut self) {
        self.inner.zeroize()
    }
}

let secret_one = RTSecret::<A, U2>::new(A { inner: 69 });
let _ = secret_one.expose_secret(|exposed_secret| exposed_secret);
let _ = secret_one.expose_secret(|exposed_secret| *exposed_secret); // Only if T is not `Copy`

Parameters

• self.
• scope: A closure that takes the exposed secret and returns a value of the ReturnType.

Panics

This function panics only if the secret is exposed more than the maximally allowed exposure count represented by the type parameter MEC.

Returns

A value of type ReturnType which is the type of the returned value from the closure named scope.

fn try_expose_secret<ReturnType, ClosureType>( &self, scope: ClosureType, ) -> Result<ReturnType, ExposeSecretError<MEC>>

where for<'brand> ClosureType: FnOnce(RTExposedSecret<'brand, &'brand T>) -> ReturnType,

Return the Result containing Ok(scope(exposed_secret)), with runtime checking that the exposure count is not more than the maximally allowed exposure count represented by the type parameter MEC. Note: It is impossible to return the ‘exposed secret’ as the return value of the closure.

Example:

use sosecrets_rs::{
    prelude::{typenum::U2, RTSecret},
    runtime::traits::RTExposeSecret,
};
#[cfg(feature = "zeroize")]
use zeroize::Zeroize;

struct A {
    inner: i32,
}

#[cfg(feature = "zeroize")]
impl Zeroize for A {
    fn zeroize(&mut self) {
        self.inner.zeroize()
    }
}

let secret_one = RTSecret::<A, U2>::new(A { inner: 69 });
let returned_value = secret_one.try_expose_secret(|exposed_secret| A { inner: (*exposed_secret).inner + 1});
assert!(returned_value.is_ok());

Example (this example will not compile):

use sosecrets_rs::{
    prelude::typenum::U2,
    runtime::{secret::RTSecret, traits::RTExposeSecret},
};
#[cfg(feature = "zeroize")]
use zeroize::Zeroize;

struct A {
    inner: i32,
}

#[cfg(feature = "zeroize")]
impl Zeroize for A {
    fn zeroize(&mut self) {
        self.inner.zeroize()
    }
}

let secret_one = RTSecret::<A, U2>::new(A { inner: 69 });
let _ = secret_one.try_expose_secret(|exposed_secret| exposed_secret);
let _ = secret_one.try_expose_secret(|exposed_secret| *exposed_secret); // Only if T is not `Copy`

Parameters

• self.
• scope: A closure that takes the exposed secret and returns a value of the ReturnType.

Returns

• Ok: The value returned by the closure.
• Err: If the exposure count exceeds the maximum allowed, returns an ExposeSecretError.

type Error = ExposeSecretError<MEC>

The type representing the Error variant as part of the Result returned type in try_expose_secret.

type Exposed<'brand> = RTExposedSecret<'brand, &'brand T> where 'secret: 'brand

The type representing the exposed secret.