Struct tari_utilities::hidden::Hidden

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

A generic type for data that needs to be kept hidden and zeroized when out of scope, and is accessible only by reference.

You can define a hidden type using any underlying data type that implements Zeroize. This is the case for most basic types that you probably care about.

Hidden data has useful properties:

• The data is not subject to Debug or Display output, which are masked.
• The data can only be accessed by (immutable or mutable) reference.
• The data zeroizes when dropped, and can also be manually zeroized.
• Cloning is safe.

Note that it may not be safe to dereference the hidden data if its type implements Copy. If the type does not implement Copy, you should be fine. If it does, avoid dereferencing.

Hidden data supports transparent deserialization, but you’ll need to implement serialization yourself if you need it.

// In this example, we need to handle secret data of type `[u8; 32]`.

// We can create hidden data from existing data; in this case, it's the caller's responsibility to make sure the existing data is handled securely
let hidden_from_data = Hidden::<[u8; 32]>::hide([1u8; 32]);

// We can access the hidden data as a reference, but not take ownership of it
assert_eq!(hidden_from_data.reveal(), &[1u8; 32]);

// We can create default hidden data and then modify it as a mutable reference; this is common for functions that act on data in place
let mut hidden_in_place = Hidden::<[u8; 32]>::hide([0u8; 32]);
let hidden_in_place_mut_ref = hidden_in_place.reveal_mut();
*hidden_in_place_mut_ref = [42u8; 32];
assert_eq!(hidden_in_place.reveal(), &[42u8; 32]);

// Cloning is safe to do
let mut clone = hidden_in_place.clone();
assert_eq!(hidden_in_place.reveal(), clone.reveal());

// You can manually zeroize the data if you need to
clone.zeroize();
assert_eq!(clone.reveal(), &[0u8; 32]);

Implementations

impl<T> Hidden<T>

where T: Zeroize,

pub fn hide(inner: T) -> Self

Create new hidden data from the underlying type

pub fn reveal(&self) -> &T

Reveal the hidden data as an immutable reference

pub fn reveal_mut(&mut self) -> &mut T

Reveal the hidden data as a mutable reference

Trait Implementations

impl<T> Clone for Hidden<T>

where T: Zeroize + Clone,

fn clone(&self) -> Hidden<T>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T> Debug for Hidden<T>

where T: Zeroize,

Only output masked data for debugging, keeping the hidden data hidden

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

Formats the value using the given formatter.

impl<'de, T> Deserialize<'de> for Hidden<T>

where T: Zeroize + Deserialize<'de>,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<T> Display for Hidden<T>

where T: Zeroize,

Only display masked data, keeping the hidden data hidden

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

Formats the value using the given formatter.

impl<T> Drop for Hidden<T>

where T: Zeroize,

Zeroize the hidden data when dropped

fn drop(&mut self)

Executes the destructor for this type.

impl<T> Zeroize for Hidden<T>

where T: Zeroize,

Zeroize the hidden data

fn zeroize(&mut self)

Zero out this object from memory using Rust intrinsics which ensure the zeroization operation is not “optimized away” by the compiler.