[debug] Add debug::Error, a wrapper for attaching context to errors

This type cannot be created except via special macros in the `debug`
module that generate log statements. We may eventually also attach
extra debugging information to errors, and this type is a good place
to do so.

Signed-off-by: Miguel Young de la Sota <[email protected]>

Fix some syntax and rebase errors
Signed-off-by: Kesavan Yogeswaran <[email protected]>

Author: mcy

src/cert/mod.rs

@@ -104,6 +104,8 @@ impl From<untrusted::EndOfInput> for Error {
     }
 }
 
+debug_from!(Error => io::Error, untrusted::EndOfInput);
+
 impl<'cert> Cert<'cert> {
     /// Parses `cert`, producing a parsed certificate in the given format.
     ///

src/debug.rs

@@ -11,45 +11,162 @@
 //! Manticore code *should not* call into the [`log`] crate directly outside of
 //! this module.
 
+// TODO: Remove this once we start using these macros in Manticore.
 #![allow(unused)]
 
+use core::fmt;
+
 #[cfg(doc)]
 use __raw_log as log;
 
+/// A wrapped Manticore error.
+///
+/// This type should always be referred to as `manticore::Error`. It represents
+/// an error with extra (potentially redacted) information attached. This type
+/// cannot be directly created by users of the library.
+#[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct Error<E> {
+    inner: E,
+}
+
+impl<E> Error<E> {
+    /// Creates a new `Error`. This function is an implementation detail,
+    /// and should not be called by users.
+    #[doc(hidden)]
+    pub fn __new(inner: E) -> Self {
+        Self { inner }
+    }
+
+    /// Transforms the wrapper error by way of an [`Into`] conversion.
+    ///
+    /// Generally, this function should not be necessary, because Manticore-
+    /// defined error types manually implement the relevant [`From`]
+    /// implementations for `manticore::Error`, which in turn call `cast()`.
+    pub fn cast<F: From<E>>(self) -> Error<F> {
+        Error {
+            inner: self.inner.into(),
+        }
+    }
+
+    /// Gets the wrapped error.
+    pub fn into_inner(self) -> E {
+        self.inner
+    }
+}
+
+impl<E> AsRef<E> for Error<E> {
+    fn as_ref(&self) -> &E {
+        &self.inner
+    }
+}
+
+impl<E> AsMut<E> for Error<E> {
+    fn as_mut(&mut self) -> &mut E {
+        &mut self.inner
+    }
+}
+
+impl<E: fmt::Display> fmt::Display for Error<E> {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        struct DisplayAsDebug<'a, E>(&'a E);
+        impl<E: fmt::Display> fmt::Debug for DisplayAsDebug<'_, E> {
+            fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+                self.0.fmt(f)
+            }
+        }
+
+        f.debug_struct("manticore::Error")
+            .field("inner", &DisplayAsDebug(&self.inner))
+            .finish()
+    }
+}
+
+/// Generates `From` implementations for `manticore::Error`.
+///
+/// We would like to write this `impl`:
+/// ```compile_fail
+/// # use manticore::Error;
+/// impl<E1, E2> From<Error<E1>> for Error<E2> where E2: From<E1> {
+///     fn from(e: Error<E1>) -> Error<E2> {
+///         e.cast()
+///     }
+/// }
+/// ```
+///
+/// Unfortunately, the trait coherence rules mean that for `E1 == E2`,
+/// this conflicts with the standard library's `impl<T> From<T> for T`
+/// impl. We work around this by calling this macro for every Manticore
+/// error definition that has `From` impls.
+macro_rules! debug_from {
+    // An error generic over one type with a single trait bound
+    ($e:ident<$trait:ident: $bound:path> => $($f:ty),+ $(,)?) => {$(
+        impl<$trait: $bound> From<$crate::Error<$f>> for $crate::Error<$e<$trait>> {
+            fn from(e: $crate::Error<$f>) -> Self {
+                e.cast()
+            }
+        }
+    )*};
+    // An error generic over one type
+    ($e:ident<$trait:ident> => $($f:ty),+ $(,)?) => {$(
+        impl<$trait> From<$crate::Error<$f>> for $crate::Error<$e<$trait>> {
+            fn from(e: $crate::Error<$f>) -> Self {
+                e.cast()
+            }
+        }
+    )*};
+    ($e:ty => $($f:ty),+ $(,)?) => {$(
+        impl From<$crate::Error<$f>> for $crate::Error<$e> {
+            fn from(e: $crate::Error<$f>) -> Self {
+                e.cast()
+            }
+        }
+    )*};
+}
+
 /// Checks a condition, logging if it fails.
 ///
 /// If the condition does not hold, constructs the given error, logs it, and
 /// returns out of the current function with it.
 macro_rules! check {
     ($cond:expr, $error:expr) => {
         if !$cond {
-            let e = $error;
-            error!(
-                "check failure: `{}`; returned {:?}"
-                stringify!($cond), e
-            );
-            return Err(e);
+            let error = $error;
+            fail!(
+                error,
+                "check failure: `{}`; returned {:?}",
+                stringify!($cond),
+                error,
+            )?;
         }
-    }
+    };
 }
 
 /// Logs a newly-created error value and returns it.
 ///
-/// This function is useful for marking where errors originate in tests.
+/// This macro is the main way to generate [`Error`] values.
+///
 /// For example, instead of writing `foo.ok_or(MyError)`, instead write
-/// `foo.ok_or_else(|| trace!(MyError))`.
-macro_rules! trace {
+/// `foo.ok_or_else(|| fail!(MyError))`.
+macro_rules! fail {
     ($error:expr, $($format:tt)+) => {{
         error!($($format)+);
-        $error
+        Err($crate::debug::Error::__new($error))
     }};
     ($error:expr) => {{
-        let e = $error;
-        error!("generated error: `{:?}`", e);
-        e
+        let error = $error;
+        error!("generated error: `{:?}`", error);
+        Err($crate::debug::Error::__new(error))
     }};
 }
 
+/// Redactable version of [`log::trace!()`].
+macro_rules! trace {
+    ($($args:tt)*) => {
+        #[cfg(feature = "log")]
+        let _ = __raw_log::trace!($($args)*);
+    }
+}
+
 /// Redactable version of [`log::info!()`].
 macro_rules! info {
     ($($args:tt)*) => {
@@ -78,7 +195,7 @@ macro_rules! error {
 /// test binary.
 ///
 /// This needs to happen here, since the test binary's main() cannot be
-/// overriden.
+/// overridden.
 #[cfg(test)]
 #[ctor::ctor]
 fn init_test_logger() {
@@ -90,7 +207,7 @@ fn init_test_logger() {
             let name = thread.name().unwrap_or("<unknown>");
             for line in record.args().to_string().trim().lines() {
                 // NOTE: we explicitly print to stderr, since this allows the
-                // Rust test harness to supress log statements originating from
+                // Rust test harness to suppress log statements originating from
                 // passing tests.
                 eprintln!(
                     "[{level}({thread}) {file}:{line}] {msg}",

src/hardware/flash.rs

@@ -58,6 +58,7 @@ impl From<OutOfMemory> for Error {
         Error::Internal
     }
 }
+debug_from!(Error => OutOfMemory);
 
 /// Provides access to a flash-like storage device.
 ///

src/lib.rs

@@ -53,11 +53,11 @@
 // `debug`.
 #[cfg(feature = "log")]
 extern crate log as __raw_log;
+#[macro_use]
+mod debug;
 
 #[macro_use]
 pub mod protocol;
-#[macro_use]
-mod debug;
 
 #[cfg(feature = "serde")]
 mod serde;
@@ -71,3 +71,12 @@ pub mod mem;
 pub mod net;
 pub mod server;
 pub mod session;
+
+pub use debug::Error;
+
+/// [`Result`] type to use throughout Manticore, which incorporates the
+/// [`manticore::Error`] type.
+///
+/// [`Result`]: std::result::Result
+/// [`manticore::Error`]: crate::Error
+pub type Result<T, E> = core::result::Result<T, Error<E>>;

src/manifest/mod.rs

@@ -274,6 +274,8 @@ impl From<hash::Error> for Error {
     }
 }
 
+debug_from!(Error => io::Error, flash::Error, OutOfMemory, sig::Error, hash::Error);
+
 /// A manifest type.
 ///
 /// A type that implements this trait is not itself a "parsed" instance of the

src/net/mod.rs

@@ -50,6 +50,8 @@ impl From<io::Error> for Error {
     }
 }
 
+debug_from!(Error => io::Error);
+
 /// A header type, which represents a protocol over the wire.
 pub trait Header: Copy {
     /// The command type enum associated with this header.

src/protocol/cerberus/error.rs

@@ -256,3 +256,80 @@ impl From<session::Error> for Error {
         Self::Internal
     }
 }
+
+impl<E: SpecificError> From<E> for Error<E> {
+    fn from(e: E) -> Self {
+        Self::Specific(e)
+    }
+}
+
+debug_from!(Error<E> => OutOfMemory, crypto::csrng::Error, crypto::hash::Error, crypto::sig::Error, session::Error);
+debug_from!(Error<E: SpecificError> => E);
+
+/// A type that describes a message-specific error.
+///
+/// This trait is an implementation detail.
+#[doc(hidden)]
+pub trait SpecificError: Sized {
+    /// Converts an error into this error type, if it represents one.
+    fn from_raw(code: u8) -> Result<Self, wire::Error>;
+
+    /// Copies this error into an error code.
+    fn to_raw(&self) -> Result<u8, wire::Error>;
+}
+
+/// An empty [`SpecificError`], for use with messages without interesting error
+/// messages.
+#[derive(Clone, Copy, PartialEq, Eq, Debug)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+pub enum NoSpecificError {}
+impl SpecificError for NoSpecificError {
+    fn from_raw(_: u8) -> Result<Self, wire::Error> {
+        Err(wire::Error::OutOfRange)
+    }
+
+    fn to_raw(&self) -> Result<u8, wire::Error> {
+        match *self {}
+    }
+}
+
+/// Helper for creating specific errors. Compare `wire_enum!`.
+macro_rules! specific_error {
+    (
+        $(#[$emeta:meta])*
+        $vis:vis enum $name:ident {$(
+            $(#[$vmeta:meta])*
+            $var:ident = $code:literal
+        ),* $(,)*}
+    ) => {
+        #[derive(Clone, Copy, PartialEq, Eq, Debug)]
+        #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+        $(#[$emeta])*
+        $vis enum $name {$(
+            $(#[$vmeta])*
+            $var,
+        )*}
+
+        impl $crate::protocol::error::SpecificError for $name {
+            fn from_raw(code: u8) -> Result<Self, $crate::protocol::wire::Error> {
+                match code {
+                    $($code => Ok(Self::$var),)*
+                    _ => Err($crate::protocol::wire::Error::OutOfRange),
+                }
+            }
+            fn to_raw(&self) -> Result<u8, $crate::protocol::wire::Error> {
+                match self {$(
+                    Self::$var => Ok($code),
+                )*}
+            }
+        }
+    };
+}
+
+specific_error! {
+    /// Errors specific to the [`protocol::Challenge`] and related messages.
+    pub enum ChallengeError {
+        /// The requested certificate chain does not exist.
+        UnknownChain = 0x00,
+    }
+}

src/protocol/wire.rs

@@ -58,6 +58,8 @@ impl From<OutOfMemory> for Error {
     }
 }
 
+debug_from!(Error => io::Error, OutOfMemory);
+
 /// A type which can be serialized into the Cerberus wire format.
 pub trait ToWire: Sized {
     /// Serializes `self` into `w`.
@@ -207,7 +209,12 @@ macro_rules! wire_enum {
         impl core::str::FromStr for $name {
             type Err = $crate::protocol::wire::WireEnumFromStrError;
 
-            fn from_str(s: &str) -> Result<Self, $crate::protocol::wire::WireEnumFromStrError> {
+            fn from_str(
+                s: &str
+            ) -> core::result::Result<
+                Self,
+                $crate::protocol::wire::WireEnumFromStrError
+            > {
                 match s {
                     $(stringify!($variant) => Ok(Self::$variant),)*
                     _ => Err($crate::protocol::wire::WireEnumFromStrError),

src/server/handler.rs

@@ -123,6 +123,8 @@ impl<H: net::Header> From<net::Error> for Error<H> {
     }
 }
 
+debug_from!(Error<H: net::Header> => wire::Error, net::Error);
+
 /// A request handler builder.
 ///
 /// See the module documentation for more information.