blob: da46a6eae3de8707cdca4e005f6aa845c48251b6 [file]
// Licensed under the Apache-2.0 license
// SPDX-License-Identifier: Apache-2.0
//! # DICE Protection Environment HAL Traits
//!
//! This module provides blocking Hardware Abstraction Layer (HAL) traits for
//! a client of a DICE Protection Environment (DPE). The TCG specification
//! "DICE Protection Environment" defines the DPE and its commands.
//!
//! ## Key Components
//!
//! - `Profile` - The types that a DPE profile defines
//! - `P384Sha384` - The profile that uses ECDSA P-384 and SHA-384
//! - `ContextHandle` - Names a context of the DPE
//! - `Sign` - Trait for the DPE `Sign` command
//!
//! ## Scope
//!
//! The module has a trait for the `Sign` command. The other DPE commands have
//! no trait.
//!
//! A driver implements a command trait once for each profile that its DPE
//! supports. The driver decides how a command reaches the DPE. The DPE can be
//! another processor behind a mailbox, or a library in the same firmware.
//!
//! A DPE holds contexts. A context is a chain of measurements, from which the
//! DPE derives keys. A context belongs to one caller, which the DPE calls a
//! locality. The DPE learns the locality of a command from the way the command
//! arrives, so the traits have no locality parameter.
//!
//! ## Example Usage
//!
//! ```rust
//! use openprot_hal_blocking::digest::Digest;
//! use openprot_hal_blocking::dpe::{ContextHandle, Error, ErrorKind, P384Sha384, Sign};
//! use openprot_hal_blocking::ecdsa::P384Signature;
//!
//! const LABEL: [u8; 48] = [1; 48];
//!
//! fn sign_twice<D: Sign<P384Sha384>>(
//! dpe: &mut D,
//! digest: &Digest<12>,
//! signatures: &mut [P384Signature; 2],
//! ) -> Result<(), ErrorKind> {
//! let [first, second] = signatures;
//! let handle = dpe
//! .sign(&ContextHandle::DEFAULT, &LABEL, digest, first)
//! .map_err(|error| error.kind())?;
//! // The second command uses the handle that the first one returned.
//! dpe.sign(&handle, &LABEL, digest, second)
//! .map_err(|error| error.kind())?;
//! Ok(())
//! }
//! # use openprot_hal_blocking::dpe::ErrorType;
//! # struct Fake;
//! # impl ErrorType for Fake { type Error = core::convert::Infallible; }
//! # impl Sign<P384Sha384> for Fake {
//! # fn sign(
//! # &mut self,
//! # handle: &ContextHandle,
//! # _label: &[u8; 48],
//! # _digest: &Digest<12>,
//! # signature: &mut P384Signature,
//! # ) -> Result<ContextHandle, Self::Error> {
//! # *signature = P384Signature::new([2; 48], [3; 48]);
//! # Ok(*handle)
//! # }
//! # }
//! # let empty = || P384Signature::new([0; 48], [0; 48]);
//! # let mut signatures = [empty(), empty()];
//! # assert!(sign_twice(&mut Fake, &Digest::new([0; 12]), &mut signatures).is_ok());
//! ```
use core::fmt;
use crate::digest::{DigestAlgorithm, Sha2_384};
use crate::ecdsa::P384Signature;
/// Error kind.
///
/// A common set of DPE errors. Generic code can act on these kinds without
/// knowing the error type of an implementation.
#[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)]
#[non_exhaustive]
pub enum ErrorKind {
/// The handle does not name a context of the DPE.
InvalidHandle,
/// The context belongs to another locality.
InvalidLocality,
/// The DPE rejected an argument of the command.
InvalidArgument,
/// The DPE does not support the command, the profile or an argument.
NotSupported,
/// The DPE is in use and cannot serve the command.
Busy,
/// The DPE did not respond in time.
Timeout,
/// The command did not reach the DPE, or its response could not be read.
Transport,
/// The response of the DPE is malformed.
InvalidResponse,
/// The DPE failed to execute the command.
Internal,
}
impl fmt::Display for ErrorKind {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::InvalidHandle => write!(f, "invalid DPE context handle"),
Self::InvalidLocality => write!(f, "DPE context belongs to another locality"),
Self::InvalidArgument => write!(f, "invalid DPE command argument"),
Self::NotSupported => write!(f, "DPE command not supported"),
Self::Busy => write!(f, "DPE is busy"),
Self::Timeout => write!(f, "DPE timed out"),
Self::Transport => write!(f, "DPE transport failure"),
Self::InvalidResponse => write!(f, "malformed DPE response"),
Self::Internal => write!(f, "DPE internal error"),
}
}
}
/// Trait for DPE errors.
///
/// Implementations define their own error types and map them to an
/// [`ErrorKind`], on which generic code can act.
pub trait Error: fmt::Debug {
/// Converts the error to a generic error kind.
fn kind(&self) -> ErrorKind;
}
impl Error for core::convert::Infallible {
fn kind(&self) -> ErrorKind {
match *self {}
}
}
/// Trait for types that have an associated error type.
pub trait ErrorType {
/// Error type.
type Error: Error;
}
impl<T: ErrorType + ?Sized> ErrorType for &mut T {
type Error = T::Error;
}
/// The types that a DPE profile defines.
///
/// A profile selects the algorithms of a DPE, and with them the sizes of
/// labels, digests and signatures.
pub trait Profile {
/// A label, which selects one of the keys of a context.
type Label;
/// The digest that [`Sign`] signs.
type Digest;
/// The signature that [`Sign`] returns.
type Signature;
}
/// The DPE profile that uses ECDSA P-384 and SHA-384.
#[derive(Debug, Copy, Clone, Eq, PartialEq)]
pub struct P384Sha384;
impl Profile for P384Sha384 {
type Label = [u8; 48];
type Digest = <Sha2_384 as DigestAlgorithm>::Digest;
type Signature = P384Signature;
}
/// Names a context of a DPE.
///
/// A command that takes a handle returns the handle to use for that context
/// in the next command. The DPE can return a new handle, and the old one then
/// no longer names the context.
#[derive(Debug, Copy, Clone, Eq, PartialEq)]
pub struct ContextHandle(pub [u8; 16]);
impl ContextHandle {
/// The handle of the default context of the caller's locality.
pub const DEFAULT: Self = Self([0; 16]);
}
/// The DPE `Sign` command for profile `P`.
pub trait Sign<P: Profile>: ErrorType {
/// Signs `digest` with a key of the context that `handle` names and
/// stores the signature in `signature`.
///
/// Returns the handle to use for the context in the next command.
///
/// The DPE derives the key from the measurements of the context and from
/// `label`, so the same context and label give the same key until a
/// measurement changes.
///
/// # Errors
///
/// When the response is lost, the caller cannot tell whether the DPE
/// replaced `handle`.
///
/// After an error, the content of `signature` is unspecified.
fn sign(
&mut self,
handle: &ContextHandle,
label: &P::Label,
digest: &P::Digest,
signature: &mut P::Signature,
) -> Result<ContextHandle, Self::Error>;
}
impl<P: Profile, T: Sign<P> + ?Sized> Sign<P> for &mut T {
fn sign(
&mut self,
handle: &ContextHandle,
label: &P::Label,
digest: &P::Digest,
signature: &mut P::Signature,
) -> Result<ContextHandle, Self::Error> {
T::sign(self, handle, label, digest, signature)
}
}