islet_hes/hw/
mod.rs

1//! Hardware specific structures and interfaces.
2use alloc::vec::Vec;
3use tinyvec::ArrayVec;
4
5pub const MAX_HW_HASH_VALUE_SIZE: usize = 64;
6pub const MAX_HW_SW_TYPE_SIZE: usize = 10;
7pub const MAX_HW_SW_VERSION_SIZE: usize = 14;
8
9/// Represents a hash value. Calculated by sha256, sha384 or sha512.
10pub type HWHash = ArrayVec<[u8; MAX_HW_HASH_VALUE_SIZE]>;
11/// Represents a software type value.
12pub type HWSWType = ArrayVec<[u8; MAX_HW_SW_TYPE_SIZE]>;
13/// Represents a software version value.
14pub type HWSWVersion = ArrayVec<[u8; MAX_HW_SW_VERSION_SIZE]>;
15
16/// Structure representing boot measurement metadata,
17/// as it is stored in emulated HW.
18#[derive(Debug, Default, Clone)]
19pub struct BootMeasurementMetadata {
20    /// Identifier of the measurement method used
21    /// to compute the measurement value.
22    pub measurement_type: u16,
23    /// Signer identity (hash of public key)
24    pub signer_id: HWHash,
25    /// Representing the role of the SW component
26    pub sw_type: HWSWType,
27    /// Version of the SW component in the form of:
28    /// "major.minor.revision+build"
29    pub sw_version: HWSWVersion,
30}
31
32/// Structure representing the boot measurement metadata and value.
33#[derive(Debug, Default, Clone)]
34pub struct BootMeasurement {
35    /// Contains boot measurement metadata
36    pub metadata: BootMeasurementMetadata,
37    /// Value of boot measurement (hash)
38    pub measurement_value: HWHash,
39}
40
41/// Represents a binary hardware 256bit symmetric key
42pub type HWSymmetricKey = ArrayVec<[u8; 32]>;
43/// Represents a binary hardware asymmetric key.
44/// Currently using ECC Curve-P384 (384bit), might be a subject to change.
45pub type HWAsymmetricKey = ArrayVec<[u8; 48]>;
46
47/// Interface for fetching hardware specific data:
48/// - Boot measurements,
49/// - Hardware keys,
50/// - Claims data,
51/// In compliance with
52/// [documentation-service.arm.com/static/610aaec33d73a34b640e333b](Arm CCA
53/// Security Model 1.0).
54pub trait HWData {
55    type Error;
56    // ---------------HW Keys -------------------
57    /// Hardware unique 256bit symmetric key. It represents a randomly unique
58    /// seed for each manufactured instance of CCA enabled system.
59    fn huk(&self) -> Result<HWSymmetricKey, Self::Error>;
60    /// Group unique 256bit symmetric key.
61    /// It represents a randomly unique seed that may be shared
62    /// with some group of manufactured CCA enabled systems
63    /// with the same immutable hardware security properties.
64    fn guk(&self) -> Result<HWSymmetricKey, Self::Error>;
65    /// Byte string representing CCA Platform Attestation Key.
66    /// Optional, can be derived in runtime.
67    fn cpak(&self) -> Result<Option<HWAsymmetricKey>, Self::Error>;
68
69    // ---------------HW Bootloader Hash---------
70    /// BL2 image signed hash.
71    fn bl_hash(&self) -> Result<HWHash, Self::Error>;
72
73    // -------------- HW claims -----------------
74    /// Software state of the system. Each entry represents a
75    /// [`BootMeasurement`] of software component within the device.
76    fn boot_measurements(&self) -> Result<Vec<BootMeasurement>, Self::Error>;
77
78    /// A byte string representing the original implementation signer
79    /// of the attestation key and indentifies contract between the report
80    /// and verification.
81    fn implementation_id(&self) -> Result<[u8; 32], Self::Error>;
82    /// Represents the current lifecycle state of the instance.
83    /// Custom claim with a value encoded as integer that
84    /// is divided to convey a major state and a minor state. The
85    /// PSA state and implementation state are encoded as follows:
86    /// - version\[15:8\] - PSA lifecycle state - major
87    /// - version\[7:0\]  - IMPLEMENTATION DEFINED state - minor
88    /// Possible PSA lifecycle states:
89    /// - Unknown (0x1000u),
90    /// - PSA_RoT_Provisioning (0x2000u),
91    /// - Secured (0x3000u),
92    /// - Non_PSA_RoT_Debug(0x4000u),
93    /// - Recoverable_PSA_RoT_Debug (0x5000u),
94    /// - Decommissioned (0x6000u)
95    fn security_lifecycle(&self) -> Result<u32, Self::Error>;
96    /// Contains the name of a document that describes the 'profile'
97    /// of the token, being a full description of the claims, their usage,
98    /// verification and token signing. The document name may include
99    /// versioning. Custom claim with a value encoded as text string.
100    fn profile_definition(&self) -> Result<Option<ArrayVec<[u8; 35]>>, Self::Error>;
101    /// The value is a text string that can be used to locate the
102    /// service or a URL specifying the address of the service. t is used by
103    /// a Relying Party to locate a validation service for the token.
104    fn verification_service_url(&self) -> Result<Option<ArrayVec<[u8; 32]>>, Self::Error>;
105    /// Describes the set of chosen implementation options of the CCA platform.
106    fn platform_config(&self) -> Result<ArrayVec<[u8; 32]>, Self::Error>;
107}
islet_hes/hw/mod.rs

islet_hes/hw/
mod.rs
