feat: improve hidden data handling

Cargo.toml

@@ -13,11 +13,13 @@ edition = "2018"
 base58-monero = { version = "0.3.2", default-features = false }
 base64 = "0.13.0"
 bincode = "1.3.3"
+generic-array = "0.14.6"
 newtype-ops = "0.1.4"
 serde = { version = "1.0.0", features = ["derive"] }
 serde_json = "1.0.0"
+subtle = "2.4.1"
 thiserror = "1.0.0"
-zeroize = "1.3.0"
+zeroize = { version = "1.3.0", features = ["zeroize_derive"] }
 
 [dev-dependencies]
 rand = "0.7.0"

src/hidden.rs

@@ -1,4 +1,4 @@
-// Copyright 2020. The Tari Project
+// Copyright 2022. The Tari Project
 //
 // Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
 // following conditions are met:
@@ -20,74 +20,250 @@
 // WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
 // USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-//! A wrapper to conceal secrets when output into logs or displayed.
+//! Sometimes you need to handle sensitive data, like a passphrase or key material.
+//! There are pitfalls here that you want to avoid: the data should be zeroized when it goes out of scope, shouldn't be
+//! displayed or output to debug logs, shouldn't be unintentionally copied or moved, and often should have strict type
+//! differentiation to avoid it being misused in an unintended context. This library provides a generic type and macro
+//! that can help.
 
-use std::fmt;
+use std::{
+    any::type_name,
+    fmt,
+    ops::{Deref, DerefMut},
+};
 
-use serde::{Deserialize, Serialize};
+use serde::Deserialize;
+use zeroize::Zeroize;
 
-/// A simple struct with a single inner value to wrap content of any type.
-#[derive(Copy, Clone, Serialize, Deserialize, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
+/// This is a macro that produces a hidden type from an underlying data type.
+///
+/// It is a thin wrapper around `Hidden` and retains its 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.
+///
+/// The macro is a useful way to generate a hidden type that is subject to the compiler's type guarantees.
+/// This can be useful if you need multiple hidden types that use the same underlying data type, but shouldn't be
+/// confused for each other.
+///
+/// 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.
+///
+/// ```edition2018
+/// # #[macro_use] extern crate tari_utilities;
+/// # use tari_utilities::Hidden;
+/// # use zeroize::Zeroize;
+/// # fn main() {
+/// // Define a hidden type with a `[u8; 32]` data type
+/// hidden_type!(MyHiddenType, [u8; 32]);
+///
+/// // Instantiate using existing data
+/// let mut example = MyHiddenType::from([1u8; 32]);
+///
+/// // Access the data by immutable reference
+/// assert_eq!(example.reveal(), &[1u8; 32]);
+///
+/// // Access the data by mutable reference
+/// let example_mut_ref = example.reveal_mut();
+/// *example_mut_ref = [42u8; 32];
+/// assert_eq!(example.reveal(), &[42u8; 32]);
+///
+/// // Clone the data safely
+/// let mut example_clone = example.clone();
+///
+/// // Zeroize the data manually
+/// example_clone.zeroize();
+/// assert_eq!(example_clone.reveal(), &[0u8; 32]);
+/// # }
+/// ```
+#[macro_export]
+macro_rules! hidden_type {
+    ($name:ident, $type:ty) => {
+        /// A hidden type
+        #[derive(Clone, Debug, Zeroize)]
+        pub struct $name {
+            data: Hidden<$type>,
+        }
+
+        impl $name {
+            /// Get an immutable reference to the data
+            #[allow(dead_code)]
+            pub fn reveal(&self) -> &$type {
+                self.data.reveal()
+            }
+
+            /// Get a mutable reference to the data
+            #[allow(dead_code)]
+            pub fn reveal_mut(&mut self) -> &mut $type {
+                self.data.reveal_mut()
+            }
+        }
+
+        impl From<$type> for $name {
+            /// Hide existing data
+            fn from(t: $type) -> Self {
+                Self {
+                    data: Hidden::hide(t),
+                }
+            }
+        }
+    };
+}
+
+/// 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.
+///
+/// ```edition2018
+/// # use tari_utilities::hidden::Hidden;
+/// # use zeroize::Zeroize;
+///
+/// // 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]);
+/// ```
+#[derive(Clone, Deserialize)]
 #[serde(transparent)]
-pub struct Hidden<T> {
-    inner: T,
+pub struct Hidden<T>
+where T: Zeroize
+{
+    inner: Box<T>,
 }
 
-impl<T> Hidden<T> {
-    /// Hides a value.
+impl<T> Hidden<T>
+where T: Zeroize
+{
+    /// Create new hidden data from the underlying type
     pub fn hide(inner: T) -> Self {
-        Self { inner }
-    }
-
-    /// Returns ownership of the inner value discarding the wrapper.
-    pub fn into_inner(self) -> T {
-        self.inner
+        Self { inner: Box::new(inner) }
     }
 
-    /// Provides access to the inner value (immutable).
+    /// Reveal the hidden data as an immutable reference
     pub fn reveal(&self) -> &T {
-        &self.inner
+        self.inner.deref()
     }
 
-    /// Provides access to the inner value (mutable).
+    /// Reveal the hidden data as a mutable reference
     pub fn reveal_mut(&mut self) -> &mut T {
-        &mut self.inner
+        self.inner.deref_mut()
     }
 }
 
-impl<T> From<T> for Hidden<T> {
-    fn from(inner: T) -> Self {
-        Self::hide(inner)
+/// Only output masked data for debugging, keeping the hidden data hidden
+impl<T> fmt::Debug for Hidden<T>
+where T: Zeroize
+{
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "Hidden<{}>", type_name::<T>())
     }
 }
 
-/// Defines a masked value for the type to output as debug information. Concealing the secrets within.
-impl<T> fmt::Debug for Hidden<T> {
+/// Only display masked data, keeping the hidden data hidden
+impl<T> fmt::Display for Hidden<T>
+where T: Zeroize
+{
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        write!(f, "Hidden<{}>", std::any::type_name::<T>())
+        write!(f, "Hidden<{}>", type_name::<T>())
     }
 }
 
-/// Defines a masked value for the type to display. Concealing the secrets within.
-impl<T> fmt::Display for Hidden<T> {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        write!(f, "Hidden<{}>", std::any::type_name::<T>())
+/// Zeroize the hidden data
+impl<T> Zeroize for Hidden<T>
+where T: Zeroize
+{
+    fn zeroize(&mut self) {
+        self.inner.zeroize();
+    }
+}
+
+/// Zeroize the hidden data when dropped
+impl<T> Drop for Hidden<T>
+where T: Zeroize
+{
+    fn drop(&mut self) {
+        self.zeroize();
     }
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use super::*;
 
     #[test]
-    fn into_applies_wrapper_deref_removes_it() {
-        let wrapped: Hidden<u8> = Hidden::hide(42);
-        assert_eq!(42, *wrapped.reveal());
+    fn references() {
+        // Check immutable reference
+        assert_eq!(Hidden::hide(0u8).reveal(), &0u8);
+
+        // Check mutable reference
+        let mut hidden = Hidden::hide([0u8; 32]);
+        let hidden_mut_ref = hidden.reveal_mut();
+
+        *hidden_mut_ref = [42u8; 32];
+        assert_eq!(hidden.reveal(), &[42u8; 32]);
     }
 
     #[test]
-    fn hidden_value_derived_trats() {
-        let wrapped: Hidden<u8> = 0.into();
-        assert_eq!(wrapped, Hidden::default());
+    fn deserialize() {
+        let value = 1u8;
+        let hidden = Hidden::<u8>::hide(value);
+
+        let ser = value.to_string();
+
+        let deser: Hidden<u8> = serde_json::from_str(&ser).unwrap();
+        assert_eq!(hidden.reveal(), deser.reveal());
+    }
+
+    #[test]
+    fn masking() {
+        let hidden = Hidden::<u8>::hide(1u8);
+        let formatted = format!("{}", hidden);
+        let expected = format!("Hidden<{}>", type_name::<u8>());
+        assert_eq!(formatted, expected);
+    }
+
+    #[test]
+    fn macro_types() {
+        hidden_type!(TypeA, [u8; 32]);
+        hidden_type!(TypeB, [u8; 32]);
+        let a = TypeA::from([1u8; 32]);
+        let b = TypeB::from([1u8; 32]);
+
+        assert_eq!(a.reveal(), &[1u8; 32]);
+        assert_eq!(b.reveal(), &[1u8; 32]);
     }
 }

src/lib.rs

@@ -30,10 +30,11 @@ pub mod fixed_set;
 pub mod hash;
 pub mod hex;
 #[macro_use]
-pub mod locks;
 pub mod hidden;
+pub mod locks;
 pub mod message_format;
 pub mod password;
+pub mod safe_array;
 pub mod serde;
 
 pub use self::{

src/message_format.rs

@@ -71,7 +71,7 @@ where T: DeserializeOwned + Serialize
 
     fn to_base64(&self) -> Result<String, MessageFormatError> {
         let val = self.to_binary()?;
-        Ok(base64::encode(&val))
+        Ok(base64::encode(val))
     }
 
     fn from_binary(msg: &[u8]) -> Result<Self, MessageFormatError> {