Struct Secret

pub struct Secret<T: Zeroize, MEC: Unsigned, EC: Add<U1> + IsLessOrEqual<MEC, Output = True> + Unsigned = U0>(/* private fields */);

The Secret struct represents a secure container for managing sensitive values with built-in exposure control.

It provides a mechanism to limit the number of times a secret can be exposed at compile time. Exposure of secret is strictly limited to a lexical scope. The behavior of the Secret type is customizable through various features, such as zeroization, cloning support, and debugging capabilities.

Type Parameters

• T: The underlying type of the secret.
• MEC: Maximum Exposure Count, a type-level unsigned integer, with typenum::Unsigned bound, indicating the maximum allowed exposures for the secret.
• EC: Exposure Count, a type-level unsigned integer, with typenum::Unsigned bound, representing the current exposure count of the secret. It is limited by the Maximum Exposure Count, if EC is greater than MEC, the program cannot be compiled.

Features

• zeroize (optional): If enabled, the secret will be automatically zeroized (cleared) after reaching its maximum exposure count.
• cloneable-secret (optional): If enabled, the underlying type T must implement the sosecrets_rs::traits::CloneableSecret trait, allowing the secret to be cloned.
• debug-secret (optional): If enabled, the underlying type T must implement the sosecrets_rs::traits::DebugSecret trait, enabling debugging of the secret.

Implementations

impl<T: Zeroize, MEC: Unsigned> Secret<T, MEC, U0>

where U0: IsLessOrEqual<MEC, Output = True>,

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

Creates a new Secret instance with the specified value.

Parameters

• value: The initial value to be stored in the secret.

Returns

A new Secret instance initialized with the provided value.

Examples

use sosecrets_rs::prelude::*;
use typenum::U5;

// Create a new secret with a maximum exposure count of 5
let secret = Secret::<_, U5>::new("my_secret_value".to_string());

pub fn new_with<ClosureType>(closure: ClosureType) -> Self

where ClosureType: FnOnce() -> T,

Creates a new Secret instance by generating the value with a closure.

Parameters

• closure: A closure that generates the initial value to be stored in the secret.

Returns

A new Secret instance initialized with the value produced by the closure.

Examples

use sosecrets_rs::prelude::*;
use typenum::U3;

// Create a new secret with a maximum exposure count of 3 using a closure
let secret = Secret::<_, U3>::new_with(|| "generated_secret_value".to_string());

Trait Implementations

impl<T, MEC, EC> Clone for Secret<T, MEC, EC>

where T: CloneableSecret, MEC: Unsigned, EC: Unsigned + Add<U1> + IsLessOrEqual<MEC, Output = True>,

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, EC> Debug for Secret<T, MEC, EC>

where T: DebugSecret, MEC: Unsigned, EC: Unsigned + Add<U1> + IsLessOrEqual<MEC, Output = True>,

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, EC> Drop for Secret<T, MEC, EC>

where MEC: Unsigned, EC: Add<U1> + Unsigned + IsLessOrEqual<MEC, Output = True>,

fn drop(&mut self)

Executes the destructor for this type.

impl<'max, T: Zeroize, MEC: Unsigned, EC: Add<U1> + Unsigned + IsLessOrEqual<MEC, Output = True>> ExposeSecret<'max, &'max T, MEC, EC> for Secret<T, MEC, EC>

fn expose_secret<ReturnType, ClosureType>( self, scope: ClosureType, ) -> (Secret<T, MEC, <EC as Add<U1>>::Output>, ReturnType)

where <EC as Add<U1>>::Output: Add<U1> + Unsigned + IsLessOrEqual<MEC, Output = True>, for<'brand> ClosureType: FnOnce(ExposedSecret<'brand, &'brand T>) -> ReturnType,

Exposes the secret value to a closure, consuming the Secret. At compile time, if the type parameter EC ‘is greater than’ MEC, calling this method will be a compile error.

Example:

use sosecrets_rs::{prelude::{Secret, typenum::U2}, traits::ExposeSecret};

struct UseSecret {
    inner: i32,
}

impl UseSecret {

    fn new(v: i32) -> Self {
        Self {
            inner: v,
        }
    }
}

let new_secret: Secret<_, U2> = Secret::new(69);

let (new_secret, returned_value) = new_secret.expose_secret(|exposed_secret| {
    let returned_value = UseSecret::new(*exposed_secret);
    returned_value
});
assert_eq!(69, returned_value.inner);

let (_new_secret, returned_value) = new_secret.expose_secret(|exposed_secret| {
    let returned_value = UseSecret::new(*exposed_secret);
    returned_value
});
assert_eq!(69, returned_value.inner);

Example (this will not compile):

use sosecrets_rs::{prelude::{Secret, typenum::U2}, traits::ExposeSecret};

struct UseSecret {
    inner: i32,
}

impl UseSecret {

    fn new(v: i32) -> Self {
        Self {
            inner: v,
        }
    }
}

let (new_secret, returned_value) = new_secret.expose_secret(|exposed_secret| {
    let returned_value = UseSecret::new(*exposed_secret);
    returned_value
});
assert_eq!(69, returned_value.inner);

let (_new_secret, returned_value) = new_secret.expose_secret(|exposed_secret| {
    let returned_value = UseSecret::new(*exposed_secret);
    returned_value
});
assert_eq!(69, returned_value.inner);

let (_new_secret, returned_value) = new_secret.expose_secret(|exposed_secret| {
    let returned_value = UseSecret::new(*exposed_secret);
    returned_value
});

type Exposed<'brand> = ExposedSecret<'brand, &'brand T> where 'max: 'brand

A wrapper type representing the exposed secret. It is associated with a lifetime 'brand, indicating the lifetime of the wrapper type, which is strictly a subtype of 'max,

type Next = Secret<T, MEC, <EC as Add<UInt<UTerm, B1>>>::Output> where EC: Add<U1> + Unsigned + IsLessOrEqual<MEC, Output = True>, Sum<EC, U1>: Unsigned + IsLessOrEqual<MEC, Output = True> + Add<U1>

The Secret<T, _, _> with an incremented count (i.e. EC) after exposing the secret. It is a new value of a type which implements the same trait, namely, ExposeSecret with an incremented exposure count, i.e. the new EC = previous EC + 1.