[feat] Add Stable Owner Key derivation from HEK seed (#3625)

mhatrevi · web-flow · commit 24205a83ba55 · 2026-05-06T20:36:21.000Z
* [feat] Add Stable Owner Key derivation from HEK seed

ROM derives a Stable Owner Root Key from HEK seed via HKDF into KV15
during cold boot. CM_DERIVE_STABLE_KEY gains OwnerKey (0x3) which uses
CMAC-KDF + HMAC-KDF with label "Stable Owner Key" to produce child
keys as encrypted CMKs.

Both ROM firmware processor and runtime handle the new key type with
identical derivation logic. Adds integration tests for all three key
types (IDevId, LDevId, OwnerKey) and a separate test verifying
different personalization seeds produce different keys.

* Addressing feedback + updating ROM hash

* Addressing PR feedback

* Addressing PR feedback

* Additional tests

* Addressing feedback

* Adding derivation documentation

* Updating ROM hash

* Filtering tests for FPGA
diff --git a/FROZEN_IMAGES.sha384sum b/FROZEN_IMAGES.sha384sum
@@ -1,3 +1,3 @@
 # WARNING: Do not update this file without the approval of the Caliptra TAC
-015d6f71f1fff828e2152a6c245574f01e8be137e0a379f1ec95aa03b5abdee3e72a7524cae7a710cfb6b4c3f0683c8d  caliptra-rom-no-log.bin
-cc1e28b0ab4ca2fe636f5a88f31aff803285472feefbeceb261754591f47552ae1fc008ff11a3da405874f6ab232de46  caliptra-rom-with-log.bin
+3befdf9287ced84ee193c4f960841919cc37a21647143671f61dbebcc252355dc643340edb456a69d83a6ad01c314fef  caliptra-rom-no-log.bin
+bbbc22da3331d2c8af8961f5db5123cdcd4dd7c1ee9d152bb296ad1effb0ea4e4f9f531e2923e268a943dd4cac69cae8  caliptra-rom-with-log.bin
diff --git a/api/src/mailbox.rs b/api/src/mailbox.rs
@@ -4934,13 +4934,15 @@ pub enum CmStableKeyType {
     Reserved = 0,
     IDevId,
     LDevId,
+    OwnerKey,
 }
 
 impl From<u32> for CmStableKeyType {
     fn from(val: u32) -> Self {
         match val {
             1_u32 => CmStableKeyType::IDevId,
             2_u32 => CmStableKeyType::LDevId,
+            3_u32 => CmStableKeyType::OwnerKey,
             _ => CmStableKeyType::Reserved,
         }
     }
@@ -4951,6 +4953,7 @@ impl From<CmStableKeyType> for u32 {
         match val {
             CmStableKeyType::IDevId => 1,
             CmStableKeyType::LDevId => 2,
+            CmStableKeyType::OwnerKey => 3,
             CmStableKeyType::Reserved => 0,
         }
     }
diff --git a/common/src/boot_status.rs b/common/src/boot_status.rs
@@ -35,6 +35,8 @@ pub enum RomBootStatus {
     IDevIdMakeCsrEnvelopeComplete = IDEVID_BOOT_STATUS_BASE + 7,
     IDevIdSendCsrEnvelopeComplete = IDEVID_BOOT_STATUS_BASE + 8,
     IDevIdDerivationComplete = IDEVID_BOOT_STATUS_BASE + 9,
+    IDevIdDecryptHekSeedComplete = IDEVID_BOOT_STATUS_BASE + 10,
+    IDevIdStableOwnerRootKeyDerivationComplete = IDEVID_BOOT_STATUS_BASE + 11,
 
     // Ldevid Statuses
     LDevIdCdiDerivationComplete = LDEVID_BOOT_STATUS_BASE,
diff --git a/common/src/keyids.rs b/common/src/keyids.rs
@@ -47,9 +47,13 @@ pub const KEY_ID_DPE_PRIV_KEY: KeyId = KeyId::KeyId11;
 pub const KEY_ID_EXPORTED_DPE_CDI: KeyId = KeyId::KeyId12;
 pub const KEY_ID_STABLE_IDEV: KeyId = KeyId::KeyId0;
 pub const KEY_ID_STABLE_LDEV: KeyId = KeyId::KeyId1;
+pub const KEY_ID_STABLE_OWNER: KeyId = KeyId::KeyId15;
 
 pub const KEY_ID_TMP: KeyId = KeyId::KeyId3;
 
+#[cfg(feature = "rom")]
+pub const KEY_ID_HEK_SEED: KeyId = KeyId::KeyId14;
+
 pub mod ocp_lock {
     use super::KeyId;
 
diff --git a/drivers/src/soc_ifc.rs b/drivers/src/soc_ifc.rs
@@ -644,6 +644,24 @@ impl SocIfc {
         )
     }
 
+    /// Check if the Stable Owner Key feature is enabled via SS_STRAP_GENERIC[3] bit 0.
+    pub fn stable_owner_key_enabled(&self) -> bool {
+        self.soc_ifc.regs().ss_strap_generic().at(3).read() & 1 != 0
+    }
+
+    /// Check if the Stable Owner Key feature is available.
+    /// Requires subsystem mode, the strap bit to be set, and OCP LOCK
+    /// to be disabled (both consume fuse_hek_seed via DOE and are
+    /// mutually exclusive).
+    ///
+    /// TODO(2.2): When a dedicated DOE path and fuse register are added for
+    /// the stable owner key seed, the OCP LOCK check here should be relaxed.
+    /// The two features will only conflict when the stable owner key is
+    /// derived from the shared HEK seed (2.1 path), not from a dedicated seed.
+    pub fn stable_owner_key_available(&self) -> bool {
+        self.subsystem_mode() && self.stable_owner_key_enabled() && !self.ocp_lock_enabled()
+    }
+
     pub fn otp_dai_idle_bit_num(&self) -> u32 {
         (self.soc_ifc.regs().ss_strap_generic().at(0).read() >> 16) & 0xFFFF
     }
diff --git a/error/src/lib.rs b/error/src/lib.rs
@@ -2724,6 +2724,11 @@ impl CaliptraError {
             0xa005_5000,
             "DOT Error: Invalid key type"
         ),
+        (
+            CMB_STABLE_OWNER_KEY_NOT_AVAILABLE,
+            0xa005_5001,
+            "Crypto Mailbox Error: Stable Owner Key is not available when OCP LOCK is enabled"
+        ),
         (
             CMB_HMAC_INVALID_ENC_CMK,
             0xa005_5020,
diff --git a/hw-model/src/lib.rs b/hw-model/src/lib.rs
@@ -251,6 +251,8 @@ pub struct InitParams<'a> {
 
     pub ocp_lock_en: bool,
 
+    pub stable_owner_key_en: bool,
+
     pub uds_fuse_row_granularity_64: bool,
 
     pub otp_dai_idle_bit_offset: u32,
@@ -343,6 +345,7 @@ impl Default for InitParams<'_> {
             dbg_manuf_service: Default::default(),
             subsystem_mode: false,
             ocp_lock_en: cfg!(feature = "ocp-lock"),
+            stable_owner_key_en: false,
             uds_fuse_row_granularity_64: true,
             otp_dai_idle_bit_offset: 30,
             otp_direct_access_cmd_reg_offset: 0x80,
diff --git a/hw-model/src/model_emulated.rs b/hw-model/src/model_emulated.rs
@@ -242,9 +242,17 @@ impl HwModel for ModelEmulated {
 
         let ss_strap_generic_reg_0 = params.otp_dai_idle_bit_offset << 16;
         let ss_strap_generic_reg_1 = params.otp_direct_access_cmd_reg_offset;
-        root_bus
-            .soc_reg
-            .set_strap_generic(&[ss_strap_generic_reg_0, ss_strap_generic_reg_1, 0, 0]);
+        let ss_strap_generic_reg_3 = if params.stable_owner_key_en {
+            1u32
+        } else {
+            0u32
+        };
+        root_bus.soc_reg.set_strap_generic(&[
+            ss_strap_generic_reg_0,
+            ss_strap_generic_reg_1,
+            0,
+            ss_strap_generic_reg_3,
+        ]);
 
         {
             let mut iccm_ram = root_bus.iccm.ram().borrow_mut();
diff --git a/rom/dev/README.md b/rom/dev/README.md
@@ -95,6 +95,23 @@ The ROM configures the entropy source (CSRNG) during initialization using the fo
 - In debug mode (`debug_locked == false`), entropy source configuration registers remain unlocked for characterization.
 - In production mode, ROM locks the entropy source configuration after programming to prevent modification.
 
+### Stable Owner Key Root Derivation
+
+The Stable Owner Key feature is only available in subsystem mode when OCP LOCK is disabled and the following subsystem strap is set:
+
+| Register                         | Field/Bits | Description                                             |
+| :------------------------------- | :--------- | :------------------------------------------------------ |
+| SS_STRAP_GENERIC[3]              | [0]        | Stable Owner Key enable. When set to 1, ROM derives the Stable Owner Root Key from the HEK seed and allows `CM_DERIVE_STABLE_KEY` with `key_type = OwnerKey` when the other availability requirements are met. When clear, Stable Owner Key derivation is disabled. |
+
+When the feature is available, ROM derives the Stable Owner Root Key during the IDevID stage before clearing DOE secrets:
+
+1. DOE decrypts the obfuscated HEK seed into `KEY_ID_HEK_SEED` (`KeyId14`) with HMAC block usage.
+2. HKDF-Extract uses HMAC-SHA512 with salt `stable_owner_root_key`, zero-padded to 64 bytes, and reads `KEY_ID_HEK_SEED` as HMAC block data. The resulting PRK overwrites `KEY_ID_HEK_SEED` with HMAC key usage.
+3. HKDF-Expand uses HMAC-SHA512 with the PRK and label `stable_owner_root_key` to populate `KEY_ID_STABLE_OWNER` (`KeyId15`) with AES key usage.
+4. ROM write-locks `KEY_ID_STABLE_OWNER` and erases the temporary `KEY_ID_HEK_SEED` slot.
+
+If subsystem mode is not active, the strap is clear, or OCP LOCK is enabled, ROM skips this derivation and `CM_DERIVE_STABLE_KEY` with `key_type = OwnerKey` is unavailable.
+
 For a comprehensive overview of the SOC interface registers, please refer to the following link::
 https://chipsalliance.github.io/caliptra-rtl/main/external-regs/?p=caliptra_top_reg.generic_and_fuse_reg
 
diff --git a/rom/dev/src/flow/cold_reset/fw_processor/mod.rs b/rom/dev/src/flow/cold_reset/fw_processor/mod.rs
@@ -424,14 +424,25 @@ impl FirmwareProcessor {
                     CommandId::GET_IDEV_MLDSA87_CSR => {
                         GetIdevMldsa87CsrCmd::execute(cmd_bytes, persistent_data, resp)?
                     }
-                    CommandId::CM_DERIVE_STABLE_KEY => CmDeriveStableKeyCmd::execute(
-                        cmd_bytes,
-                        env.aes_gcm,
-                        env.hmac,
-                        env.trng,
-                        persistent_data,
-                        resp,
-                    )?,
+                    CommandId::CM_DERIVE_STABLE_KEY => {
+                        // Reject OwnerKey if the Stable Owner Key feature is not available.
+                        let req = CmDeriveStableKeyReq::ref_from_bytes(cmd_bytes)
+                            .map_err(|_| CaliptraError::FW_PROC_MAILBOX_INVALID_REQUEST_LENGTH)?;
+                        let key_type: CmStableKeyType = req.key_type.into();
+                        if key_type == CmStableKeyType::OwnerKey
+                            && !soc_ifc.stable_owner_key_available()
+                        {
+                            Err(CaliptraError::CMB_STABLE_OWNER_KEY_NOT_AVAILABLE)?;
+                        }
+                        CmDeriveStableKeyCmd::execute(
+                            cmd_bytes,
+                            env.aes_gcm,
+                            env.hmac,
+                            env.trng,
+                            persistent_data,
+                            resp,
+                        )?
+                    }
                     CommandId::CM_RANDOM_GENERATE => {
                         CmRandomGenerateCmd::execute(cmd_bytes, env.trng, resp)?
                     }
@@ -1124,26 +1135,48 @@ impl FirmwareProcessor {
             CmStableKeyType::LDevId => AesKey::KV(KeyReadArgs::new(
                 caliptra_common::keyids::KEY_ID_STABLE_LDEV,
             )),
+            CmStableKeyType::OwnerKey => AesKey::KV(KeyReadArgs::new(
+                caliptra_common::keyids::KEY_ID_STABLE_OWNER,
+            )),
             CmStableKeyType::Reserved => Err(CaliptraError::DOT_INVALID_KEY_TYPE)?,
         };
         let k0 = cmac_kdf(aes, aes_key, &request.info, None, 4)?;
 
-        // Prepend "DOT Final" to info and use as label for HMAC KDF
-        const PREFIX: &[u8] = b"DOT Final";
-        let mut data = [0u8; CM_STABLE_KEY_INFO_SIZE_BYTES + PREFIX.len()];
-        data[..PREFIX.len()].copy_from_slice(PREFIX);
-        data[PREFIX.len()..].copy_from_slice(&request.info);
-
+        // Prepend a domain-separation prefix to info and use as label for HMAC KDF
+        const DOT_PREFIX: &[u8] = b"DOT Final";
+        const OWNER_PREFIX: &[u8] = b"Stable Owner Key";
         let mut tag: Array4x16 = Array4x16::default();
-        hmac_kdf(
-            hmac,
-            HmacKey::Array4x16(&Array4x16::from(k0)),
-            &data[..],
-            None,
-            trng,
-            HmacTag::Array4x16(&mut tag),
-            HmacMode::Hmac512,
-        )?;
+        match key_type {
+            CmStableKeyType::OwnerKey => {
+                let mut data = [0u8; CM_STABLE_KEY_INFO_SIZE_BYTES + OWNER_PREFIX.len()];
+                data[..OWNER_PREFIX.len()].copy_from_slice(OWNER_PREFIX);
+                data[OWNER_PREFIX.len()..].copy_from_slice(&request.info);
+                hmac_kdf(
+                    hmac,
+                    HmacKey::Array4x16(&Array4x16::from(k0)),
+                    &data,
+                    None,
+                    trng,
+                    HmacTag::Array4x16(&mut tag),
+                    HmacMode::Hmac512,
+                )?;
+            }
+            CmStableKeyType::IDevId | CmStableKeyType::LDevId => {
+                let mut data = [0u8; CM_STABLE_KEY_INFO_SIZE_BYTES + DOT_PREFIX.len()];
+                data[..DOT_PREFIX.len()].copy_from_slice(DOT_PREFIX);
+                data[DOT_PREFIX.len()..].copy_from_slice(&request.info);
+                hmac_kdf(
+                    hmac,
+                    HmacKey::Array4x16(&Array4x16::from(k0)),
+                    &data,
+                    None,
+                    trng,
+                    HmacTag::Array4x16(&mut tag),
+                    HmacMode::Hmac512,
+                )?;
+            }
+            CmStableKeyType::Reserved => Err(CaliptraError::DOT_INVALID_KEY_TYPE)?,
+        }
 
         let mut key_material = [0u8; 64];
         for (i, word) in tag.0.iter().enumerate() {
diff --git a/rom/dev/src/flow/cold_reset/idev_id.rs b/rom/dev/src/flow/cold_reset/idev_id.rs
@@ -25,8 +25,8 @@ use caliptra_cfi_lib::{cfi_assert, cfi_assert_bool, cfi_launder};
 use caliptra_common::{
     crypto::{Crypto, Ecc384KeyPair, MlDsaKeyPair, PubKey},
     keyids::{
-        KEY_ID_FE, KEY_ID_IDEVID_ECDSA_PRIV_KEY, KEY_ID_IDEVID_MLDSA_KEYPAIR_SEED,
-        KEY_ID_ROM_FMC_CDI, KEY_ID_UDS,
+        KEY_ID_FE, KEY_ID_HEK_SEED, KEY_ID_IDEVID_ECDSA_PRIV_KEY, KEY_ID_IDEVID_MLDSA_KEYPAIR_SEED,
+        KEY_ID_ROM_FMC_CDI, KEY_ID_STABLE_OWNER, KEY_ID_UDS,
     },
     x509,
     RomBootStatus::*,
@@ -40,6 +40,9 @@ use zeroize::Zeroize;
 /// Initialization Vector used by Deobfuscation Engine during UDS / field entropy decryption.
 const DOE_IV: Array4x4 = Array4xN::<4, 16>([0xfb10365b, 0xa1179741, 0xfba193a1, 0x0f406d7e]);
 
+/// Label used for HKDF-Extract (salt) and HKDF-Expand (info) when deriving the Stable Owner Root Key.
+const STABLE_OWNER_ROOT_KEY_LABEL: &[u8] = b"stable_owner_root_key";
+
 /// Dice Initial Device Identity (IDEVID) Layer
 pub enum InitDevIdLayer {}
 
@@ -76,6 +79,9 @@ impl InitDevIdLayer {
         // Decrypt the Field Entropy
         Self::decrypt_field_entropy(env, KEY_ID_FE)?;
 
+        // Derive Stable Owner Root Key from HEK seed (if enabled).
+        Self::derive_stable_owner_root_key(env)?;
+
         // Clear Deobfuscation Engine Secrets
         Self::clear_doe_secrets(env)?;
 
@@ -170,6 +176,116 @@ impl InitDevIdLayer {
         Ok(())
     }
 
+    /// Derive the Stable Owner Root Key.
+    ///
+    /// Decrypts the HEK seed via DOE and derives the Stable Owner Root Key
+    /// via HKDF. No-op if the feature is not available (checks subsystem
+    /// mode, strap enable bit, and OCP LOCK exclusivity).
+    #[cfg_attr(feature = "cfi", cfi_impl_fn)]
+    fn derive_stable_owner_root_key(env: &mut RomEnvFips) -> CaliptraResult<()> {
+        if !env.soc_ifc.stable_owner_key_available() {
+            return Ok(());
+        }
+        Self::decrypt_hek_seed(env, KEY_ID_HEK_SEED)?;
+        Self::hkdf_stable_owner_root_key(env, KEY_ID_HEK_SEED, KEY_ID_STABLE_OWNER)
+    }
+
+    /// Decrypt HEK Seed
+    ///
+    /// # Arguments
+    ///
+    /// * `env` - ROM Environment
+    /// * `key_id` - Key Vault slot to store the decrypted HEK seed in
+    #[cfg_attr(feature = "cfi", cfi_impl_fn)]
+    fn decrypt_hek_seed(env: &mut RomEnvFips, key_id: KeyId) -> CaliptraResult<()> {
+        env.doe.decrypt_hek_seed(&DOE_IV, key_id)?;
+        report_boot_status(IDevIdDecryptHekSeedComplete.into());
+        Ok(())
+    }
+
+    /// Derive Stable Owner Root Key from HEK Seed via HKDF (RFC 5869).
+    ///
+    /// The DOE hardware restricts the HEK seed to HMAC_BLOCK only (cannot be
+    /// used as an HMAC key). We work around this with a two-step construction:
+    ///
+    /// 1. HKDF-Extract: HMAC(key=fixed_salt, data=hek_seed_kv) → PRK
+    ///    (hek_seed is read as HMAC block data, which is allowed)
+    /// 2. HKDF-Expand:  HMAC-KDF(key=PRK, label="stable_owner_root_key") → output
+    ///
+    /// # Arguments
+    ///
+    /// * `env` - ROM Environment
+    /// * `hek_seed_temp` - Temporary KV slot holding the DOE-decrypted HEK seed
+    /// * `stable_owner` - Persistent KV slot for the derived stable owner root key
+    #[cfg_attr(feature = "cfi", cfi_impl_fn)]
+    fn hkdf_stable_owner_root_key(
+        env: &mut RomEnv,
+        hek_seed_temp: KeyId,
+        stable_owner: KeyId,
+    ) -> CaliptraResult<()> {
+        cprintln!(
+            "[idev] Deriving STABLE_OWNER_ROOT_KEY: temp={}, output={}",
+            hek_seed_temp as u8,
+            stable_owner as u8
+        );
+
+        // Step 1: HKDF-Extract — HMAC(key=fixed_salt, data=HEK_seed_in_KV)
+        // The salt is a fixed domain-separation string zero-padded to 64 bytes.
+        let mut salt_bytes = [0u8; 64];
+        for (dst, src) in salt_bytes
+            .iter_mut()
+            .zip(STABLE_OWNER_ROOT_KEY_LABEL.iter())
+        {
+            *dst = *src;
+        }
+        let salt = Array4x16::from(salt_bytes);
+
+        // HEK seed is read via HMAC_BLOCK (allowed by hardware).
+        // Output overwrites the temp slot with HMAC_KEY usage so Step 2 can
+        // read it as an HMAC key.
+        //
+        // From this point on, the temp slot must be erased on every exit
+        // path (success or error) so the HEK seed never lingers in the KV.
+        let result = (|| -> CaliptraResult<()> {
+            env.hmac.hmac(
+                HmacKey::Array4x16(&salt),
+                HmacData::Key(KeyReadArgs::new(hek_seed_temp)),
+                &mut env.trng,
+                HmacTag::Key(KeyWriteArgs::new(
+                    hek_seed_temp,
+                    KeyUsage::default().set_hmac_key_en(),
+                )),
+                HmacMode::Hmac512,
+            )?;
+
+            // Step 2: HKDF-Expand — HMAC-KDF(key=PRK, label) → stable owner root key
+            hmac_kdf(
+                &mut env.hmac,
+                HmacKey::Key(KeyReadArgs::new(hek_seed_temp)),
+                STABLE_OWNER_ROOT_KEY_LABEL,
+                None,
+                &mut env.trng,
+                HmacTag::Key(KeyWriteArgs::new(
+                    stable_owner,
+                    KeyUsage::default().set_aes_key_en(),
+                )),
+                HmacMode::Hmac512,
+            )?;
+            env.key_vault.set_key_write_lock(stable_owner);
+            Ok(())
+        })();
+
+        // Always erase the temporary HEK seed slot, even if a step above failed.
+        let erase_result = env.key_vault.erase_key(hek_seed_temp);
+
+        // Surface the derivation error first; otherwise propagate any erase error.
+        result?;
+        erase_result?;
+
+        report_boot_status(IDevIdStableOwnerRootKeyDerivationComplete.into());
+        Ok(())
+    }
+
     /// Clear Deobfuscation Engine secrets
     ///
     /// # Arguments
diff --git a/rom/dev/tests/rom_integration_tests/test_derive_stable_key.rs b/rom/dev/tests/rom_integration_tests/test_derive_stable_key.rs
diff --git a/runtime/README.md b/runtime/README.md
diff --git a/runtime/src/cryptographic_mailbox.rs b/runtime/src/cryptographic_mailbox.rs
diff --git a/runtime/tests/runtime_integration_tests/common.rs b/runtime/tests/runtime_integration_tests/common.rs
diff --git a/runtime/tests/runtime_integration_tests/test_cryptographic_mailbox.rs b/runtime/tests/runtime_integration_tests/test_cryptographic_mailbox.rs

Original file line number	Diff line number	Diff line change
`@@ -4934,13 +4934,15 @@ pub enum CmStableKeyType {`
`4934`	`4934`	`Reserved = 0,`
`4935`	`4935`	`IDevId,`
`4936`	`4936`	`LDevId,`
	`4937`	`+ OwnerKey,`
`4937`	`4938`	`}`
`4938`	`4939`
`4939`	`4940`	`impl From<u32> for CmStableKeyType {`
`4940`	`4941`	`fn from(val: u32) -> Self {`
`4941`	`4942`	`match val {`
`4942`	`4943`	`1_u32 => CmStableKeyType::IDevId,`
`4943`	`4944`	`2_u32 => CmStableKeyType::LDevId,`
	`4945`	`+ 3_u32 => CmStableKeyType::OwnerKey,`
`4944`	`4946`	`_ => CmStableKeyType::Reserved,`
`4945`	`4947`	`}`
`4946`	`4948`	`}`
`@@ -4951,6 +4953,7 @@ impl From<CmStableKeyType> for u32 {`
`4951`	`4953`	`match val {`
`4952`	`4954`	`CmStableKeyType::IDevId => 1,`
`4953`	`4955`	`CmStableKeyType::LDevId => 2,`
	`4956`	`+ CmStableKeyType::OwnerKey => 3,`
`4954`	`4957`	`CmStableKeyType::Reserved => 0,`
`4955`	`4958`	`}`
`4956`	`4959`	`}`