slot manager debug.

add read/write specs as well to the slot definitions.

Not terribly happy with how this all worked out. The subtle
differences between Data and Keys is really irritating.
it's the sort of thing you would say "let's make a trait"
for it but then the two behave just differently enough
that I worry I can't make a trait generic enough to encompass
all the weird stuff that exists in the hardware.

The existing implementation definitely looks like trait
territory, but it currently hides the subtleties around
key/data chaining and secure crypto engine handling of
the two regions as distinct entities. so long as we don't
plan to use those things, traits are a good idea, but
i don't feel like I can reject using the crypto engine
features out of hand this early on just to make the
APIs nice and square.
This commit is contained in:
bunnie 2025-10-20 23:32:29 +08:00
parent 5c60de32ce
commit 2095acfe13
No known key found for this signature in database
4 changed files with 230 additions and 60 deletions

View file

@ -21,9 +21,15 @@ pub const ACRAM_KEYSLOT_START: usize = 0x603D_E000;
pub const ACRAM_KEYSLOT_LEN: usize = 0x2000;
// pub const ACRAM_GKEYSLOT_START: usize = 0x603D_E400; // This is mentioned in the docs but I don't see it in
// the code?
pub const IFR_BASE: usize = 0x6040_0000;
pub const IFR_LEN: usize = 0x400;
/// This number is special: it only appears during certain portions of the chip life cycle in
/// some configurations, so it needs to be captured during manufacturing and copied elsewhere in the array.
/// It contains the lot ID, wafer ID, and wafer x/y position of the die.
pub const IFR_CP_ID_BASE: usize = 0x6040_00A0;
#[bitfield(u32)]
#[derive(PartialEq, Eq)]
#[derive(PartialEq, Eq, Debug)]
pub struct DataSlotAccess {
#[bit(24, rw)]
write_mode: bool,
@ -62,10 +68,41 @@ impl DataSlotAccess {
pub fn set_partition_access(&mut self, pa: &PartitionAccess) {
*self = Self::new_with_raw_value((self.raw_value() & !(0xf << 20)) | (pa.to_raw_u4().as_u32() << 20));
}
pub fn get_rw_permissions(&self) -> RwPerms {
match [self.core_rd_dis(), self.core_wr_dis()] {
[true, true] => RwPerms::Denied,
[false, true] => RwPerms::ReadOnly,
[true, false] => RwPerms::WriteOnly,
[false, false] => RwPerms::ReadWrite,
}
}
pub fn set_rw_permissions(&mut self, spec: RwPerms) {
match spec {
RwPerms::Denied => {
self.set_core_rd_dis(true);
self.set_core_wr_dis(true);
}
RwPerms::ReadOnly => {
self.set_core_rd_dis(false);
self.set_core_wr_dis(true);
}
RwPerms::WriteOnly => {
self.set_core_rd_dis(true);
self.set_core_wr_dis(false);
}
RwPerms::ReadWrite => {
self.set_core_rd_dis(false);
self.set_core_wr_dis(false);
}
RwPerms::Unspecified => panic!("RwPerms must be specified"),
}
}
}
#[bitfield(u32)]
#[derive(PartialEq, Eq)]
#[derive(PartialEq, Eq, Debug)]
pub struct KeySlotAccess {
#[bits(24..=31, rw)]
akey_id: u8,
@ -104,6 +141,37 @@ impl KeySlotAccess {
pub fn set_partition_access(&mut self, pa: &PartitionAccess) {
*self = Self::new_with_raw_value((self.raw_value() & !(0xf << 20)) | (pa.to_raw_u4().as_u32() << 20));
}
pub fn get_rw_permissions(&self) -> RwPerms {
match [self.core_rd_dis(), self.core_wr_dis()] {
[true, true] => RwPerms::Denied,
[false, true] => RwPerms::ReadOnly,
[true, false] => RwPerms::WriteOnly,
[false, false] => RwPerms::ReadWrite,
}
}
pub fn set_rw_permissions(&mut self, spec: RwPerms) {
match spec {
RwPerms::Denied => {
self.set_core_rd_dis(true);
self.set_core_wr_dis(true);
}
RwPerms::ReadOnly => {
self.set_core_rd_dis(false);
self.set_core_wr_dis(true);
}
RwPerms::WriteOnly => {
self.set_core_rd_dis(true);
self.set_core_wr_dis(false);
}
RwPerms::ReadWrite => {
self.set_core_rd_dis(false);
self.set_core_wr_dis(false);
}
RwPerms::Unspecified => panic!("RwPerms must be specified"),
}
}
}
#[derive(PartialEq, Eq, Clone, Copy, Debug)]
@ -123,9 +191,25 @@ pub enum AccessError {
TypeError,
/// Returned when an index request is out of valid bounds
OutOfBounds,
/// Returned when a buffer passed does not match the expected size
SizeError,
/// Returned when a set of slots that should have the same ACL don't. The value
/// inside is the value of the first ACL in the set.
DataAclInconsistency(DataSlotAccess),
KeyAclInconsistency(KeySlotAccess),
}
#[derive(PartialEq, Eq, Clone, Copy)]
/// Enum to specify read/write permissions to a given slot.
#[derive(PartialEq, Eq, Clone, Copy, Debug)]
pub enum RwPerms {
ReadOnly,
WriteOnly,
ReadWrite,
Denied,
Unspecified,
}
#[derive(PartialEq, Eq, Clone, Copy, Debug)]
/// Specifies what partitions can access a given slot. Some common patterns are
/// provided, a Custom field is also provided for other odd combinations.
pub enum PartitionAccess {
@ -169,14 +253,14 @@ impl PartitionAccess {
// can be shifted into place.
fn to_raw_u4(&self) -> u4 {
match self {
Self::None => u4::new(!0b0000),
Self::All => u4::new(!0b1111),
Self::Boot0 => u4::new(!0b0001),
Self::Boot1 => u4::new(!0b0010),
Self::Fw0 => u4::new(!0b0100),
Self::Fw1 => u4::new(!0b1000),
Self::AllBoots => u4::new(!0b0011),
Self::AllFws => u4::new(!0b1100),
Self::None => u4::new(!0b0000 & 0xF),
Self::All => u4::new(!0b1111 & 0xF),
Self::Boot0 => u4::new(!0b0001 & 0xF),
Self::Boot1 => u4::new(!0b0010 & 0xF),
Self::Fw0 => u4::new(!0b0100 & 0xF),
Self::Fw1 => u4::new(!0b1000 & 0xF),
Self::AllBoots => u4::new(!0b0011 & 0xF),
Self::AllFws => u4::new(!0b1100 & 0xF),
// Panic is the correct behavior here because it's a static code bug to try and use this coding in
// this fashion.
Self::Unspecified => panic!("Attempt to resolve an unspecified access pattern"),
@ -192,58 +276,113 @@ impl PartitionAccess {
///
/// The reason the two are bundled together is that semantic priority is given to getting the spec right
/// in the constants in this crate that define the access control tables.
#[derive(PartialEq, Eq, Clone)]
#[derive(PartialEq, Eq, Clone, Debug)]
pub enum SlotIndex {
Data(usize, PartitionAccess),
DataRange(Range<usize>, PartitionAccess),
Key(usize, PartitionAccess),
KeyRange(Range<usize>, PartitionAccess),
Data(usize, PartitionAccess, RwPerms),
DataRange(Range<usize>, PartitionAccess, RwPerms),
Key(usize, PartitionAccess, RwPerms),
KeyRange(Range<usize>, PartitionAccess, RwPerms),
}
#[derive(PartialEq, Eq, Clone, Debug)]
pub enum SlotType {
Data,
Key,
}
impl SlotIndex {
pub fn get_access_spec(&self) -> (PartitionAccess, RwPerms) {
match self {
Self::Data(_, spec, rw) => (*spec, *rw),
Self::DataRange(_, spec, rw) => (*spec, *rw),
Self::Key(_, spec, rw) => (*spec, *rw),
Self::KeyRange(_, spec, rw) => (*spec, *rw),
}
}
pub fn get_type(&self) -> SlotType {
match self {
Self::Data(_, _, _) | Self::DataRange(_, _, _) => SlotType::Data,
Self::Key(_, _, _) | Self::KeyRange(_, _, _) => SlotType::Key,
}
}
pub fn get_base(&self) -> usize {
match self {
Self::Data(base, _, _) => *base,
Self::DataRange(range, _, _) => range.start,
Self::Key(base, _, _) => *base,
Self::KeyRange(range, _, _) => range.start,
}
}
pub fn len(&self) -> usize {
match self {
Self::Data(_, _, _) => 1,
Self::DataRange(range, _, _) => range.len(),
Self::Key(_, _, _) => 1,
Self::KeyRange(range, _, _) => range.len(),
}
}
/// Returns `OutOfBounds` error if the index specified in the slot is out of bounds.
/// For ranges, returns the offset of the first element of the range.
pub fn try_into_data_offset(&self) -> Result<usize, AccessError> {
match self {
Self::Data(index, _) => {
Self::Data(index, _, _) => {
if *index < MAX_DATA_SLOTS {
Ok(*index * SLOT_ELEMENT_LEN_BYTES)
} else {
Err(AccessError::OutOfBounds)
}
}
Self::Key(index, _) => {
Self::Key(index, _, _) => {
if *index < MAX_KEY_SLOTS {
Ok(*index * SLOT_ELEMENT_LEN_BYTES)
} else {
Err(AccessError::OutOfBounds)
}
}
_ => Err(AccessError::TypeError),
Self::DataRange(range, _, _) => {
let index = range.start;
if range.end <= MAX_DATA_SLOTS {
Ok(index * SLOT_ELEMENT_LEN_BYTES)
} else {
Err(AccessError::OutOfBounds)
}
}
Self::KeyRange(range, _, _) => {
let index = range.start;
if range.end <= MAX_KEY_SLOTS {
Ok(index * SLOT_ELEMENT_LEN_BYTES)
} else {
Err(AccessError::OutOfBounds)
}
}
}
}
pub fn try_into_data_iter(&self) -> Result<SlotOffsetIter, AccessError> {
match self {
Self::Data(index, _) => {
Self::Data(index, _, _) => {
if *index < MAX_DATA_SLOTS {
Ok(SlotOffsetIter::Single(core::iter::once(*index * SLOT_ELEMENT_LEN_BYTES)))
} else {
Err(AccessError::OutOfBounds)
}
}
Self::DataRange(range, _) => {
Self::DataRange(range, _, _) => {
if range.end > MAX_DATA_SLOTS {
return Err(AccessError::OutOfBounds);
}
Ok(SlotOffsetIter::Range(range.clone().map(|idx| idx * SLOT_ELEMENT_LEN_BYTES)))
}
Self::Key(index, _) => {
Self::Key(index, _, _) => {
if *index < MAX_KEY_SLOTS {
Ok(SlotOffsetIter::Single(core::iter::once(*index * SLOT_ELEMENT_LEN_BYTES)))
} else {
Err(AccessError::OutOfBounds)
}
}
Self::KeyRange(range, _) => {
Self::KeyRange(range, _, _) => {
if range.end > MAX_KEY_SLOTS {
return Err(AccessError::OutOfBounds);
}
@ -254,21 +393,34 @@ impl SlotIndex {
pub fn try_into_acl_offset(&self) -> Result<usize, AccessError> {
match self {
Self::Data(index, _) => {
Self::Data(index, _, _) => {
if *index < MAX_DATA_SLOTS {
Ok(*index * size_of::<u32>())
} else {
Err(AccessError::OutOfBounds)
}
}
Self::Key(index, _) => {
Self::Key(index, _, _) => {
if *index < MAX_KEY_SLOTS {
Ok(*index * size_of::<u32>())
} else {
Err(AccessError::OutOfBounds)
}
}
_ => Err(AccessError::TypeError),
Self::DataRange(range, _, _) => {
if range.end <= MAX_DATA_SLOTS {
Ok(range.start * size_of::<u32>())
} else {
Err(AccessError::OutOfBounds)
}
}
Self::KeyRange(range, _, _) => {
if range.end <= MAX_KEY_SLOTS {
Ok(range.start * size_of::<u32>())
} else {
Err(AccessError::OutOfBounds)
}
}
}
}
@ -276,27 +428,27 @@ impl SlotIndex {
const ACL_SIZE: usize = core::mem::size_of::<u32>();
match self {
Self::Data(index, _) => {
Self::Data(index, _, _) => {
if *index < MAX_DATA_SLOTS {
Ok(SlotOffsetIter::Single(core::iter::once(*index * ACL_SIZE)))
} else {
Err(AccessError::OutOfBounds)
}
}
Self::DataRange(range, _) => {
Self::DataRange(range, _, _) => {
if range.end > MAX_DATA_SLOTS {
return Err(AccessError::OutOfBounds);
}
Ok(SlotOffsetIter::Range(range.clone().map(|idx| idx * ACL_SIZE)))
}
Self::Key(index, _) => {
Self::Key(index, _, _) => {
if *index < MAX_KEY_SLOTS {
Ok(SlotOffsetIter::Single(core::iter::once(*index * ACL_SIZE)))
} else {
Err(AccessError::OutOfBounds)
}
}
Self::KeyRange(range, _) => {
Self::KeyRange(range, _, _) => {
if range.end > MAX_KEY_SLOTS {
return Err(AccessError::OutOfBounds);
}

View file

@ -1,6 +1,6 @@
use xous::arch::PAGE_SIZE;
use crate::offsets::{PartitionAccess, SlotIndex};
use crate::offsets::{PartitionAccess, RwPerms, SlotIndex};
// we actually have 16MiB on the initial prototypes, but constraining to smaller for cost reduction
pub const SPI_FLASH_LEN: usize = 8192 * 1024;
@ -48,35 +48,40 @@ pub const DEFAULT_FCLK_FREQUENCY: u32 = 700_000_000;
/// are derived from. The seed may be blended with other bits of data scattered about
/// the RRAM array, other device identifiers and hardware measurements to create the final
/// device secret key.
pub const ROOT_SEED: SlotIndex = SlotIndex::Key(256, PartitionAccess::Fw0);
pub const ROOT_SEED: SlotIndex = SlotIndex::Key(256, PartitionAccess::Fw0, RwPerms::ReadOnly);
/// The `RMA_KEY` is a secret parameter that is unique per-device secret which is recorded
/// at manufacturing time. Its purpose is to facilitate the creation of a signed RMA
/// authorization certificate which upon receipt would blank the device and unlock various
/// features for debugging failed hardware.
pub const RMA_KEY: SlotIndex = SlotIndex::Key(257, PartitionAccess::Fw0);
pub const RMA_KEY: SlotIndex = SlotIndex::Key(257, PartitionAccess::Fw0, RwPerms::ReadOnly);
/// Reserved for use as a CP to FT tracking cookie. This is used to help track inventory
/// between CP and FT, if such a feature is desired in the supply chain.
pub const CP_COOKIE: SlotIndex = SlotIndex::Key(258, PartitionAccess::Fw0);
pub const CP_COOKIE: SlotIndex = SlotIndex::Key(258, PartitionAccess::Fw0, RwPerms::ReadOnly);
/// `NUISANCE_KEYS` are hashed together with `ROOT_SEED` to derive the core secret.
/// Their primary purpose is to annoy microscopists trying to read the secret key by
/// directly imaging the RRAM array. They also exist to reduce power side channels
/// created upon accessing keys in combination with `CHAFF_KEYS`. Note there is ECC
/// on the data (2C2D on top of 128 bits) so any readout with better than 97% accuracy
/// can trivially rely on ECC to repair the results.
/// can trivially rely on ECC to repair the results (and now you have a metric for how
/// reliable your readout needs to be).
///
/// The placement is picked based upon two competing theories:
/// - Data stored next to each other will be harder to read out because the simultaneous activation of
/// read-out word lines via secondary electron leakage will cause the data in adjacent cells to
/// super-impose on the bitline.
/// read-out word line transistors via secondary electron leakage will cause the data in adjacent cells to
/// super-impose on the bitline. You want to have several random bits superimposed to defeat probabilistic
/// models of leakage behavior.
/// - Data stored far from each other will be harder to read out based on the difficulty of achieving
/// flatness & uniformity in delayering over long distances.
///
/// Thus 2x 4k pages on either end of the key range are carved out for the nuisance keys.
pub const NUISANCE_KEYS_0: SlotIndex = SlotIndex::KeyRange(0..128, PartitionAccess::Fw0);
pub const NUISANCE_KEYS_1: SlotIndex = SlotIndex::KeyRange(1920..2048, PartitionAccess::Fw0);
/// Thus 2x 4k pages on either end of the key range are carved out for the nuisance keys. 4k page size
/// is convenient because that's the natural page size over which the key range will be carved up before
/// handing to other processes.
pub const NUISANCE_KEYS_0: SlotIndex = SlotIndex::KeyRange(0..128, PartitionAccess::Fw0, RwPerms::ReadOnly);
pub const NUISANCE_KEYS_1: SlotIndex =
SlotIndex::KeyRange(1920..2048, PartitionAccess::Fw0, RwPerms::ReadOnly);
pub const NUISANCE_KEYS: [SlotIndex; 2] = [NUISANCE_KEYS_0, NUISANCE_KEYS_1];
/// `CHAFF_KEYS` are a bank of keys that are hashed into the key array, but instead of
@ -86,19 +91,15 @@ pub const NUISANCE_KEYS: [SlotIndex; 2] = [NUISANCE_KEYS_0, NUISANCE_KEYS_1];
/// the key read-out, the CHAFF_KEYS have a random ordering that frustrates attempts to
/// correlate the power signature over repeated reboots. The read-out of the CHAFF_KEYS
/// needs to be strictly constant time, i.e. the permutation function can't leak a
/// side channel that reveals what the ordering is.
pub const CHAFF_KEYS: SlotIndex = SlotIndex::KeyRange(128..256, PartitionAccess::Fw0);
/// side channel that reveals what the ordering is. Better yet, CHAFF_KEYS can be read
/// out interleaved with the NUISANCE_KEY readout, where the selection to read a CHAFF_KEY
/// or a NUISANCE_KEY is done randomly, thus introducing some disorder in the power side
/// channel timing of the NUISANCE_KEY readout.
pub const CHAFF_KEYS: SlotIndex = SlotIndex::KeyRange(128..256, PartitionAccess::Fw0, RwPerms::ReadOnly);
/// All the slots of concern located in a single iterator. The idea is that everything is
/// condensed here and used to check for access integrity using the array below.
pub const ALL_SLOTS: [SlotIndex; 9] = [
crate::offsets::SERIAL_NUMBER,
crate::offsets::UUID,
crate::offsets::IFR_HASH,
ROOT_SEED,
RMA_KEY,
CP_COOKIE,
NUISANCE_KEYS_0,
NUISANCE_KEYS_1,
CHAFF_KEYS,
];
pub const DATA_SLOTS: [SlotIndex; 4] =
[crate::offsets::SERIAL_NUMBER, crate::offsets::UUID, crate::offsets::IFR_HASH, crate::offsets::CP_ID];
pub const KEY_SLOTS: [SlotIndex; 6] =
[ROOT_SEED, RMA_KEY, CP_COOKIE, NUISANCE_KEYS_0, NUISANCE_KEYS_1, CHAFF_KEYS];

View file

@ -1,4 +1,5 @@
use crate::offsets::PartitionAccess;
use crate::offsets::RwPerms;
use crate::offsets::SlotIndex;
// These define the start region of the partition. In general, each partition has signature
@ -94,8 +95,8 @@ pub const CP_BOOT_SETUP_DONE: usize = 83;
/// Incremented from 0 if system boot setup has been finished. This is for systems that have
/// a supplemental entropy source and want to replace the generated keys with keys that are
/// derived from a blend of entropy sources.
pub const SYS_BOOT_SETUP_DONE: usize = 84;
/// derived from a blend of entropy sources. It's only useful on platforms like baosec.
pub const IN_SYSTEM_BOOT_SETUP_DONE: usize = 84;
/// Total number of public key slots in the system. Pubkey revocations are at the "top of range"
pub const PUBKEY_SLOTS: usize = 4;
@ -120,14 +121,29 @@ pub const BOOT0_REVOCATION_OFFSET: usize = BOOT1_REVOCATION_OFFSET + PUBKEY_SLOT
/// even be all zeros (in which case LOT_CODE should be used). Its primary
/// purpose is to serve as a debugging hint for practical manufacturing issues. You are
/// free to read it and use it, but beware.
pub const SERIAL_NUMBER: SlotIndex = SlotIndex::Data(0, PartitionAccess::All);
pub const SERIAL_NUMBER: SlotIndex = SlotIndex::Data(0, PartitionAccess::All, RwPerms::ReadOnly);
/// `UUID` is a 256-bit random number that can be used as a UUID for the chip. It is publicly
/// readable and generated by a TRNG. This is suitable for putting into a KDF and generating
/// salts for algorithms that require such a parameter.
pub const UUID: SlotIndex = SlotIndex::Data(1, PartitionAccess::All);
pub const UUID: SlotIndex = SlotIndex::Data(1, PartitionAccess::All, RwPerms::ReadOnly);
/// `IFR_HASH` is a provisional slot for a hash of the IFR region. Whether the hash is meaningful
/// or not depends on if the chip is booted before it is sealed. At the time of writing, it's
/// not clear if the wafer probe infrastructure will allow this.
pub const IFR_HASH: SlotIndex = SlotIndex::Data(2, PartitionAccess::All);
pub const IFR_HASH: SlotIndex = SlotIndex::Data(2, PartitionAccess::All, RwPerms::ReadOnly);
/// `WAFER_ID` is a copy of the lot ID + wafer ID + x/y position data that should be captured
/// during CP.
pub const CP_ID: SlotIndex = SlotIndex::Data(3, PartitionAccess::All, RwPerms::ReadOnly);
// Notes on defining the boot0 IFR region.
// RISC-V boot0 region start is defined by IFR slot 6, bits [55:48]
// RISC-V boot1 region start (which is boot0 end) is defined by IFR slot 6, bits[47:40]
// These bits are compared against address [21:14], which means the RRAM region is
// sub-dividable into 256 16k blocks
// ** Boot0 should be from 0x0 - 0x2_0000 (128k reserved as R/O data)
// - "start" bits [55:48] == 0x00
// - "end" bits [47:40] == 0x08
//
// Furthermore, IFR slot 0x14, bits [127:120] should have 0x3a in it to enforce write disable on boot0

View file

@ -32,5 +32,6 @@ pub const DEFAULT_FCLK_FREQUENCY: u32 = 700_000_000;
/// All the slots of concern located in a single iterator. The idea is that everything is
/// condensed here and used to check for access integrity using the array below.
pub const ALL_SLOTS: [SlotIndex; 3] =
[crate::offsets::SERIAL_NUMBER, crate::offsets::UUID, crate::offsets::IFR_HASH];
pub const DATA_SLOTS: [SlotIndex; 4] =
[crate::offsets::SERIAL_NUMBER, crate::offsets::UUID, crate::offsets::IFR_HASH, crate::offsets::CP_ID];
pub const KEY_SLOTS: [SlotIndex; 0] = [];