| // Licensed under the Apache-2.0 license | |
| // SPDX-License-Identifier: Apache-2.0 | |
| //! Reader for the handoff table that the caliptra-mcu-sw ROM leaves for the | |
| //! runtime image. | |
| //! | |
| //! The ROM reserves the last 1 KiB of DCCM for the table (`handoff_offset` in | |
| //! the caliptra-mcu-sw memory map) and writes it during a cold boot, before it | |
| //! loads the runtime image. The layout is `HandoffData` in | |
| //! `romtime/src/handoff.rs` of caliptra-mcu-sw: | |
| //! | |
| //! | Offset | Size | Contents | | |
| //! |-------:|-----:|------------------------------------------------------| | |
| //! | 0 | 64 | ROM table: marker, version, boot type, capabilities | | |
| //! | 64 | 64 | Runtime table, reserved for the runtime image | | |
| //! | 128 | 132 | Stable owner key: encrypted CMK and a validity marker | | |
| //! | |
| //! The major version changes when a field moves. The minor version increases | |
| //! when a field is added, so each accessor checks that the ROM's minor version | |
| //! has the field. This reader knows the fields of version 1.3. | |
| //! | |
| //! [`Handoff::at`] validates the ROM table and refers to it where it is in | |
| //! DCCM. The kernel can access DCCM. A service needs a mapping of the table's | |
| //! first [`ROM_TABLE_SIZE`] bytes in its system config. [`RomTable`] is | |
| //! `Copy`, so code that needs the table after DCCM is put to another use | |
| //! copies it out of [`Handoff::rom_table`] and passes the copy to | |
| //! [`Handoff::new`]. | |
| //! | |
| //! Bytes 8 to 19 of the ROM table hold the OCP LOCK HEK state when the ROM is | |
| //! built with its `ocp-lock` feature. This reader does not decode them. | |
| #![cfg_attr(not(test), no_std)] | |
| use core::mem::{offset_of, size_of}; | |
| use core::ptr::with_exposed_provenance; | |
| /// Value of the marker at the start of a handoff table: "MCUH". | |
| pub const MARKER: u32 = 0x4855_434d; | |
| /// Major version of the layout that this reader knows. | |
| pub const MAJOR_VERSION: u16 = 1; | |
| /// Size of the ROM table at the start of the handoff region. | |
| pub const ROM_TABLE_SIZE: usize = size_of::<RomTable>(); | |
| /// Offset of the stable owner key from the start of the handoff region. | |
| pub const STABLE_OWNER_KEY_OFFSET: usize = 128; | |
| /// Size of the stable owner key table: the CMK and its validity marker. | |
| pub const STABLE_OWNER_KEY_SIZE: usize = size_of::<StableOwnerKeyTable>(); | |
| /// Size of an encrypted Caliptra Cryptographic Manager key (CMK). | |
| pub const CMK_SIZE: usize = 128; | |
| /// Minor version that added the stable owner key. | |
| const STABLE_OWNER_KEY_MINOR_VERSION: u16 = 1; | |
| /// Minor version that added the firmware boot type. | |
| const FIRMWARE_BOOT_TYPE_MINOR_VERSION: u16 = 2; | |
| /// Minor version that added the ROM capabilities. | |
| const ROM_CAPABILITIES_MINOR_VERSION: u16 = 3; | |
| /// Value of the stable owner key's validity marker: "SOKV". | |
| const STABLE_OWNER_KEY_VALID: u32 = 0x564b_4f53; | |
| /// The ROM table as the ROM lays it out. | |
| #[repr(C)] | |
| #[derive(Clone, Copy, Debug, PartialEq, Eq)] | |
| pub struct RomTable { | |
| /// [`MARKER`] when the ROM has written the table. | |
| pub marker: u32, | |
| pub major_version: u16, | |
| pub minor_version: u16, | |
| /// OCP LOCK HEK state, or zero when the ROM has no OCP LOCK support. | |
| pub ocp_lock: [u32; 3], | |
| /// A [`FirmwareBootType`] value. | |
| pub firmware_boot_type: u8, | |
| pub reserved: [u8; 3], | |
| /// [`RomCapabilities`] bits. | |
| pub rom_capabilities: u32, | |
| pub padding: [u8; 36], | |
| } | |
| const _: () = assert!(size_of::<RomTable>() == 64); | |
| const _: () = assert!(offset_of!(RomTable, ocp_lock) == 8); | |
| const _: () = assert!(offset_of!(RomTable, firmware_boot_type) == 20); | |
| const _: () = assert!(offset_of!(RomTable, rom_capabilities) == 24); | |
| /// The stable owner key as the ROM lays it out. | |
| #[repr(C)] | |
| struct StableOwnerKeyTable { | |
| cmk: [u8; CMK_SIZE], | |
| /// The ROM writes [`STABLE_OWNER_KEY_VALID`] here after it has written | |
| /// the whole CMK. | |
| valid_marker: u32, | |
| } | |
| const _: () = assert!(size_of::<StableOwnerKeyTable>() == 132); | |
| /// Where the ROM got the runtime image. | |
| #[derive(Clone, Copy, Debug, PartialEq, Eq)] | |
| pub enum FirmwareBootType { | |
| /// The ROM did not record the source. | |
| Unknown, | |
| /// The ROM loaded the image from flash. | |
| Flash, | |
| /// The image was streamed through the OCP recovery interface. | |
| Streaming, | |
| /// The ROM loaded the image over the network. | |
| Network, | |
| } | |
| impl FirmwareBootType { | |
| /// A name for logs. | |
| pub const fn name(self) -> &'static str { | |
| match self { | |
| Self::Unknown => "unknown", | |
| Self::Flash => "flash", | |
| Self::Streaming => "streaming", | |
| Self::Network => "network", | |
| } | |
| } | |
| } | |
| bitflags::bitflags! { | |
| /// What the ROM image supports. A set bit does not mean that this boot | |
| /// used the feature. | |
| #[derive(Clone, Copy, Debug, PartialEq, Eq)] | |
| pub struct RomCapabilities: u32 { | |
| /// Streaming boot over I3C. | |
| const STREAMING_BOOT_I3C = 1 << 0; | |
| /// Boot from flash. | |
| const FLASH_BOOT = 1 << 1; | |
| /// Boot over the network. | |
| const NETWORK_BOOT = 1 << 2; | |
| /// OCP LOCK key management. | |
| const OCP_LOCK = 1 << 3; | |
| /// Device Ownership Transfer (DOT) firmware manifests. | |
| const FW_MANIFEST_DOT = 1 << 4; | |
| /// Component SVN manifests. | |
| const COMPONENT_SVN_MANIFEST = 1 << 5; | |
| /// The ROM derives a stable owner key and hands it off. | |
| const STABLE_OWNER_KEY = 1 << 6; | |
| /// DOT blob authentication during boot. | |
| const DOT_BOOT = 1 << 7; | |
| /// A recovery path for the DOT locked state. | |
| const DOT_LOCKED_RECOVERY = 1 << 8; | |
| /// DOT recovery over I3C. | |
| const I3C_DOT_RECOVERY = 1 << 9; | |
| } | |
| } | |
| /// Why there is no usable handoff table. | |
| #[derive(Clone, Copy, Debug, PartialEq, Eq)] | |
| pub enum Error { | |
| /// The table does not start with [`MARKER`]: the ROM has not written it. | |
| NoTable, | |
| /// The table has a major version other than [`MAJOR_VERSION`]. | |
| UnsupportedVersion(u16), | |
| } | |
| /// Why the handoff table has no firmware boot type. | |
| #[derive(Clone, Copy, Debug, PartialEq, Eq)] | |
| pub enum BootTypeError { | |
| /// The ROM's handoff version does not have the field. | |
| Unsupported, | |
| /// The field holds a value that is not a [`FirmwareBootType`]. | |
| Invalid(u8), | |
| } | |
| /// A ROM table with a valid marker and major version. | |
| #[derive(Clone, Copy, Debug, PartialEq, Eq)] | |
| pub struct Handoff<'a> { | |
| rom: &'a RomTable, | |
| } | |
| impl Handoff<'static> { | |
| /// Refers to the ROM table at the start of the handoff region. | |
| /// | |
| /// # Safety | |
| /// | |
| /// `base` must be the address of the handoff region and a multiple of 4. | |
| /// The first [`ROM_TABLE_SIZE`] bytes of the region must stay readable by | |
| /// the caller, and no code may write them from this call on. | |
| pub unsafe fn at(base: usize) -> Result<Self, Error> { | |
| let table = with_exposed_provenance::<RomTable>(base); | |
| // SAFETY: the caller guarantees that the table is aligned, stays | |
| // readable and is not written again. Every bit pattern is a valid | |
| // `RomTable`. | |
| Self::new(unsafe { &*table }) | |
| } | |
| } | |
| impl<'a> Handoff<'a> { | |
| /// Validates a ROM table. | |
| pub const fn new(rom: &'a RomTable) -> Result<Self, Error> { | |
| if rom.marker != MARKER { | |
| return Err(Error::NoTable); | |
| } | |
| if rom.major_version != MAJOR_VERSION { | |
| return Err(Error::UnsupportedVersion(rom.major_version)); | |
| } | |
| Ok(Self { rom }) | |
| } | |
| /// The table as the ROM wrote it. | |
| pub const fn rom_table(&self) -> &'a RomTable { | |
| self.rom | |
| } | |
| /// Major version of the table, which is [`MAJOR_VERSION`]. | |
| pub const fn major_version(&self) -> u16 { | |
| self.rom.major_version | |
| } | |
| /// Minor version of the table. | |
| pub const fn minor_version(&self) -> u16 { | |
| self.rom.minor_version | |
| } | |
| /// Where the ROM got the runtime image. | |
| pub const fn firmware_boot_type(&self) -> Result<FirmwareBootType, BootTypeError> { | |
| if self.rom.minor_version < FIRMWARE_BOOT_TYPE_MINOR_VERSION { | |
| return Err(BootTypeError::Unsupported); | |
| } | |
| match self.rom.firmware_boot_type { | |
| 0 => Ok(FirmwareBootType::Unknown), | |
| 1 => Ok(FirmwareBootType::Flash), | |
| 2 => Ok(FirmwareBootType::Streaming), | |
| 3 => Ok(FirmwareBootType::Network), | |
| other => Err(BootTypeError::Invalid(other)), | |
| } | |
| } | |
| /// What the ROM image supports, or `None` if the ROM's handoff version | |
| /// does not have the field. Bits that [`RomCapabilities`] does not name | |
| /// are kept. | |
| pub const fn rom_capabilities(&self) -> Option<RomCapabilities> { | |
| if self.rom.minor_version < ROM_CAPABILITIES_MINOR_VERSION { | |
| return None; | |
| } | |
| Some(RomCapabilities::from_bits_retain(self.rom.rom_capabilities)) | |
| } | |
| /// Refers to the stable owner key in the handoff region: an encrypted CMK | |
| /// that only the Caliptra core can use. Returns `None` if the ROM's | |
| /// handoff version does not have the key or the ROM did not write one. | |
| /// | |
| /// # Safety | |
| /// | |
| /// `base` must be the address of the handoff region that holds this | |
| /// table, and a multiple of 4. The [`STABLE_OWNER_KEY_SIZE`] bytes at | |
| /// [`STABLE_OWNER_KEY_OFFSET`] in the region must stay readable by the | |
| /// caller, and no code may write them from this call on. | |
| pub unsafe fn stable_owner_key(&self, base: usize) -> Option<&'static [u8; CMK_SIZE]> { | |
| if self.rom.minor_version < STABLE_OWNER_KEY_MINOR_VERSION { | |
| return None; | |
| } | |
| let table = with_exposed_provenance::<StableOwnerKeyTable>( | |
| base.wrapping_add(STABLE_OWNER_KEY_OFFSET), | |
| ); | |
| // SAFETY: the caller guarantees that the table stays readable and | |
| // is not written again. `base` and the offset are multiples of 4. | |
| // Every bit pattern is a valid `StableOwnerKeyTable`. | |
| let table: &'static StableOwnerKeyTable = unsafe { &*table }; | |
| (table.valid_marker == STABLE_OWNER_KEY_VALID).then_some(&table.cmk) | |
| } | |
| } | |
| #[cfg(test)] | |
| mod tests { | |
| use super::*; | |
| /// Size of `HandoffData` in caliptra-mcu-sw. | |
| const HANDOFF_SIZE: usize = 260; | |
| /// A handoff region. The tests write it at the byte offsets that the | |
| /// caliptra-mcu-sw handoff documentation lists. | |
| #[repr(C, align(4))] | |
| struct Region([u8; HANDOFF_SIZE]); | |
| impl Region { | |
| fn put(&mut self, offset: usize, bytes: &[u8]) { | |
| self.0[offset..offset + bytes.len()].copy_from_slice(bytes); | |
| } | |
| /// Writes a valid stable owner key. | |
| fn put_stable_owner_key(&mut self) { | |
| self.put(STABLE_OWNER_KEY_OFFSET, &[0x5a; CMK_SIZE]); | |
| self.put( | |
| STABLE_OWNER_KEY_OFFSET + CMK_SIZE, | |
| &STABLE_OWNER_KEY_VALID.to_le_bytes(), | |
| ); | |
| } | |
| fn base(&self) -> usize { | |
| (&raw const self.0).expose_provenance() | |
| } | |
| fn handoff(&'static self) -> Result<Handoff<'static>, Error> { | |
| // SAFETY: the region is aligned, and it stays readable and is | |
| // not written again because it is leaked behind a shared | |
| // reference. | |
| unsafe { Handoff::at(self.base()) } | |
| } | |
| fn stable_owner_key(&'static self) -> Option<&'static [u8; CMK_SIZE]> { | |
| let handoff = self.handoff().unwrap(); | |
| // SAFETY: as for `handoff`, and the region holds the whole | |
| // stable owner key table. | |
| unsafe { handoff.stable_owner_key(self.base()) } | |
| } | |
| } | |
| /// A region as the ROM writes it at handoff version 1.3 for a streaming | |
| /// boot, without a stable owner key, and then changed by `edit`. The | |
| /// region is leaked, as the handoff region in DCCM lasts for the whole | |
| /// program. | |
| fn region(edit: impl FnOnce(&mut Region)) -> &'static Region { | |
| let mut region = Box::new(Region([0; HANDOFF_SIZE])); | |
| region.put(0, &MARKER.to_le_bytes()); | |
| region.put(4, &1u16.to_le_bytes()); | |
| region.put(6, &3u16.to_le_bytes()); | |
| region.put(20, &[2]); | |
| region.put(24, &0x43u32.to_le_bytes()); | |
| edit(&mut region); | |
| Box::leak(region) | |
| } | |
| #[test] | |
| fn reads_the_fields_at_the_documented_offsets() { | |
| let handoff = region(|_| {}).handoff().unwrap(); | |
| assert_eq!(handoff.major_version(), 1); | |
| assert_eq!(handoff.minor_version(), 3); | |
| assert_eq!( | |
| handoff.firmware_boot_type(), | |
| Ok(FirmwareBootType::Streaming) | |
| ); | |
| assert_eq!( | |
| handoff.rom_capabilities(), | |
| Some( | |
| RomCapabilities::STREAMING_BOOT_I3C | |
| | RomCapabilities::FLASH_BOOT | |
| | RomCapabilities::STABLE_OWNER_KEY | |
| ) | |
| ); | |
| assert_eq!(handoff.rom_table().ocp_lock, [0; 3]); | |
| } | |
| #[test] | |
| fn refers_to_the_table_in_the_region() { | |
| let region = region(|_| {}); | |
| let handoff = region.handoff().unwrap(); | |
| assert_eq!( | |
| (&raw const *handoff.rom_table()).addr(), | |
| (&raw const region.0).addr() | |
| ); | |
| } | |
| #[test] | |
| fn a_copy_of_the_table_decodes_the_same() { | |
| let handoff = region(|_| {}).handoff().unwrap(); | |
| let copy = *handoff.rom_table(); | |
| let from_copy = Handoff::new(©).unwrap(); | |
| assert_eq!(from_copy, handoff); | |
| assert_eq!( | |
| from_copy.firmware_boot_type(), | |
| Ok(FirmwareBootType::Streaming) | |
| ); | |
| } | |
| #[test] | |
| fn rejects_a_region_without_the_marker() { | |
| let region = region(|r| r.put(0, &0u32.to_le_bytes())); | |
| assert_eq!(region.handoff(), Err(Error::NoTable)); | |
| } | |
| #[test] | |
| fn rejects_another_major_version() { | |
| let region = region(|r| r.put(4, &2u16.to_le_bytes())); | |
| assert_eq!(region.handoff(), Err(Error::UnsupportedVersion(2))); | |
| } | |
| #[test] | |
| fn accepts_a_later_minor_version() { | |
| let handoff = region(|r| r.put(6, &9u16.to_le_bytes())).handoff().unwrap(); | |
| assert_eq!(handoff.minor_version(), 9); | |
| assert_eq!( | |
| handoff.firmware_boot_type(), | |
| Ok(FirmwareBootType::Streaming) | |
| ); | |
| } | |
| #[test] | |
| fn decodes_each_boot_type() { | |
| let cases = [ | |
| (0, Ok(FirmwareBootType::Unknown)), | |
| (1, Ok(FirmwareBootType::Flash)), | |
| (2, Ok(FirmwareBootType::Streaming)), | |
| (3, Ok(FirmwareBootType::Network)), | |
| (4, Err(BootTypeError::Invalid(4))), | |
| (0xff, Err(BootTypeError::Invalid(0xff))), | |
| ]; | |
| for (value, expected) in cases { | |
| let handoff = region(|r| r.put(20, &[value])).handoff().unwrap(); | |
| assert_eq!(handoff.firmware_boot_type(), expected); | |
| } | |
| } | |
| #[test] | |
| fn boot_type_needs_minor_version_2() { | |
| let handoff = region(|r| r.put(6, &1u16.to_le_bytes())).handoff().unwrap(); | |
| assert_eq!( | |
| handoff.firmware_boot_type(), | |
| Err(BootTypeError::Unsupported) | |
| ); | |
| } | |
| #[test] | |
| fn rom_capabilities_need_minor_version_3() { | |
| let handoff = region(|r| r.put(6, &2u16.to_le_bytes())).handoff().unwrap(); | |
| assert_eq!(handoff.rom_capabilities(), None); | |
| assert_eq!( | |
| handoff.firmware_boot_type(), | |
| Ok(FirmwareBootType::Streaming) | |
| ); | |
| } | |
| #[test] | |
| fn rom_capabilities_keep_unnamed_bits() { | |
| let handoff = region(|r| r.put(24, &0x8000_0001u32.to_le_bytes())) | |
| .handoff() | |
| .unwrap(); | |
| let capabilities = handoff.rom_capabilities().unwrap(); | |
| assert!(capabilities.contains(RomCapabilities::STREAMING_BOOT_I3C)); | |
| assert_eq!(capabilities.bits(), 0x8000_0001); | |
| } | |
| #[test] | |
| fn stable_owner_key_needs_its_marker() { | |
| assert_eq!(region(|_| {}).stable_owner_key(), None); | |
| let without_marker = region(|r| r.put(STABLE_OWNER_KEY_OFFSET, &[0x5a; CMK_SIZE])); | |
| assert_eq!(without_marker.stable_owner_key(), None); | |
| let with_marker = region(Region::put_stable_owner_key); | |
| assert_eq!(with_marker.stable_owner_key(), Some(&[0x5a; CMK_SIZE])); | |
| } | |
| #[test] | |
| fn stable_owner_key_needs_minor_version_1() { | |
| let region = region(|r| { | |
| r.put_stable_owner_key(); | |
| r.put(6, &0u16.to_le_bytes()); | |
| }); | |
| assert_eq!(region.stable_owner_key(), None); | |
| } | |
| } |