Changes to Runtime Specification

Comparing version 2.1 to 2.0
+615 additions -103 deletions
@@ -1,10 +1,10 @@
11 <div style="font-size: 0.85em; color: #656d76; margin-bottom: 1em; padding: 0.5em; background: #f6f8fa; border-radius: 4px;">
2-📄 Source: <a href="https://github.com/chipsalliance/caliptra-sw/blob/294bcacbd34aca6e23ce7b652885e3236f7e7afe/runtime/README.md" target="_blank">chipsalliance/caliptra-sw/runtime/README.md</a> @ <code>294bcac</code>
2+📄 Source: <a href="https://github.com/chipsalliance/caliptra-sw/blob/0a7d46b7cf8a9ccbfc195a8b148268df68d7b80f/runtime/README.md" target="_blank">chipsalliance/caliptra-sw/runtime/README.md</a> @ <code>0a7d46b</code>
33 </div>
44
5-# Caliptra Runtime Firmware v2.0.1
6-
7-*Spec version: 0.3*
5+# Caliptra Runtime Firmware v2.1
6+
7+*Spec version: 1.0*
88
99 This specification describes the Caliptra Runtime Firmware.
1010
@@ -25,9 +25,14 @@
2525 * [Cryptographic mailbox commands](#cryptographic-mailbox-commands-new-in-20)
2626 * `ECDSA384_SIGNATURE_VERIFY` and `LMS_SIGNATURE_VERIFY`require the hash to be included in the message, as the SHA accelerator registers are no longer accessible outside Caliptra.
2727
28+v2.1:
29+
30+* [External mailbox commands](#external-mailbox-cmd)
31+* [Encrypted firmware support](#encrypted-firmware-support-21-subsystem-mode-only)
32+* [OCP LOCK v1.0 commands](#mailbox-commands-ocp-lock-v10)
33+
34+
2835 ## Spec Opens
29-
30-* Cryptographic Mailbox: ML-KEM support
3136
3237 ## Runtime Firmware environment
3338
@@ -40,6 +45,19 @@
4045 * Initialize the [DICE Protection Environment (DPE)](#dice-protection-environment-dpe)
4146 * Initialize any SRAM structures used by Runtime Firmware
4247 * Upload the firwmare to the Manufacturer Control Unit (2.0, susbystem mode only)
48+
49+#### Encrypted Firmware Support (2.1, subsystem mode only)
50+
51+When ROM receives the `RI_DOWNLOAD_ENCRYPTED_FIRMWARE` command instead of `RI_DOWNLOAD_FIRMWARE`, it sets the boot mode to `EncryptedFirmware`. In this mode:
52+
53+1. Runtime downloads the encrypted MCU firmware to MCU SRAM via the recovery interface
54+2. Runtime does **not** activate the MCU firmware immediately
55+3. The MCU ROM can then:
56+ - Import an AES key using `CM_IMPORT`
57+ - Decrypt the firmware in-place using `CM_AES_GCM_DECRYPT_DMA`
58+ - Send `CM_ACTIVATE_FIRMWARE` to activate the decrypted MCU firmware
59+
60+The `CM_AES_GCM_DECRYPT_DMA` command is intended to be used for the `EncryptedFirmware` boot mode and performs a SHA384 integrity check of the ciphertext before decryption, but can be used to decrypt other images as well in any boot mode.
4361
4462 For behavior during other types of reset, see [Runtime firmware updates](#runtime-firmware-updates).
4563
@@ -94,7 +112,7 @@
94112
95113 CM itself does not provide any storage for the keys: when generated, they are returned to the caller in encrypted form, and must be passed back to be used.
96114
97-These mailbox commands provide SHA, HMAC, HKDF, AES, RNG, MLDSA, and ECDSA services.
115+These mailbox commands provide SHA, HMAC, HKDF, AES, RNG, MLDSA, ECDSA, and ML-KEM services.
98116
99117 Note that while MLDSA and ECDSA keys can be imported, generated, and used in the cryptographic mailbox commands (i.e., `CM_*` commands) through CMKs, these keys are *NOT* tied DICE or DPE, so their use may be restricted for certain purposes.
100118
@@ -126,8 +144,7 @@
126144
127145 | **Name** | **Bits** | **Description** |
128146 | ------------- | -------- | -------------------------------------- |
129-| version | 8 | CMK version. Currently always 1. |
130-| flags | 8 | Bit 0 = FIPS valid |
147+| version | 16 | CMK version. Currently always 1. |
131148 | length | 16 | how many bits of key material are used |
132149 | key usage | 8 | represents which kind of key this is |
133150 | id | 24 | ID number |
@@ -162,8 +179,10 @@
162179 | --------- | --------- |
163180 | 0 | Reserved |
164181 | 1 | HMAC |
165-| 2 | HKDF |
166-| 3 | AES |
182+| 2 | AES |
183+| 3 | ECDSA |
184+| 4 | MLDSA |
185+| 5 | ML-KEM |
167186
168187
169188 #### Replay Prevention and Deletion
@@ -187,7 +206,7 @@
187206
188207 Each of these abilities are tied to Caliptra Vendor and Owner FW signing keys and should be independent of any SoC RoT FW signing keys.
189208
190-Manifest-based image authorization is implemented via two mailbox commands: [`SET_AUTH_MANIFEST`](#set-auth-manifest), and [`AUTHORIZE_AND_STASH`](#authorize-and-stash).
209+Manifest-based image authorization is implemented via two mailbox commands: [`SET_AUTH_MANIFEST`](#set_auth_manifest), and [`AUTHORIZE_AND_STASH`](#authorize_and_stash).
191210
192211 ### Caliptra-Endorsed Aggregated Measured Boot
193212
@@ -367,7 +386,14 @@
367386 | -------- | -------- | ---------------
368387 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian.
369388 | fips\_status | u32 | Indicates if the command is FIPS approved or an error.
370-| capabilities | u8[16] | Firmware capabilities
389+| capabilities | u8[16] | Firmware capabilities. See table below for details.
390+
391+*Table: Firmware Capabilities Flags*
392+
393+| **Name** | **Bit** | **Description**
394+| --------------- | ------- | ---------------
395+| `RT_BASE` | 64 | Base capabilities for Caliptra Runtime v2.1.
396+| `RT_OCP_LOCK` | 65 | Runtime firmware and hardware supports OCP LOCK.
371397
372398 ### GET\_IDEV\_ECC384\_CERT
373399
@@ -811,13 +837,13 @@
811837 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian.
812838 | fips\_status | u32 | Indicates if the command is FIPS approved or an error.
813839
814-### INVOKE\_DPE\_COMMAND
815-
816-Invokes a serialized DPE command.
840+### INVOKE\_DPE\_ECC384
841+
842+Invokes a serialized EC-P384 DPE profile command.
817843
818844 Command Code: `0x4450_4543` ("DPEC")
819845
820-*Table: `INVOKE_DPE_COMMAND` input arguments*
846+*Table: `INVOKE_DPE_ECC384` input arguments*
821847
822848 | **Name** | **Type** | **Description**
823849 | -------- | -------- | ---------------
@@ -825,7 +851,49 @@
825851 | data\_size | u32 | Length in bytes of the valid data in the data field.
826852 | data | u8[...] | DPE command structure as defined in the DPE iRoT profile.
827853
828-*Table: `INVOKE_DPE_COMMAND` output arguments*
854+*Table: `INVOKE_DPE_ECC384` output arguments*
855+
856+| **Name** | **Type** | **Description**
857+| -------- | -------- | ---------------
858+| chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian.
859+| fips\_status | u32 | Indicates if the command is FIPS approved or an error.
860+| data\_size | u32 | Length in bytes of the valid data in the data field.
861+| data | u8[...] | DPE response structure as defined in the DPE iRoT profile.
862+
863+### INVOKE\_DPE\_MLDSA87
864+
865+Invokes a serialized ML-DSA-87 DPE profile command. In subsystem mode a response
866+can be DMA'ed to an external address. This is especially useful for large
867+commands like `CertifyKey` or `DeriveContext` when exporting a CDI. Both of
868+these responses contain a potentially large certificate/CSR. To use this
869+feature, set the EXTERNAL_AXI_RESPONSE in `flags` and set the corresponding
870+AXI address and size fields. The response over the mailbox will only contain a
871+mailbox header (`chksum` and `fips_status`). The full response including the
872+mailbox header will be found at the given address.
873+
874+Command Code: `0x4450_4543` ("DPEC")
875+
876+*Table: `INVOKE_DPE_MLDSA87` input arguments*
877+
878+| **Name** | **Type** | **Description** |
879+| -------------- | -------- | --------------------------------------------------------------------------- |
880+| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
881+| flags | u32 | Flags to give configurations of the command. |
882+| axi\_addr\_lo | u32 | Lower word of the destination physical address. |
883+| axi\_addr\_hi | u32 | Upper word of the destination physical address. |
884+| axi\_max\_size | u32 | Maximum DMA response size. |
885+| data\_size | u32 | Length in bytes of the valid data in the data field. |
886+| data | u8[...] | DPE command structure as defined in the DPE iRoT profile. |
887+
888+
889+*Table: `INVOKE_DPE_MLDSA87` input flags*
890+
891+| **Name** | **Value** |
892+| ----------------------- | --------- |
893+| EXTERNAL\_AXI\_RESPONSE | 1 << 31 |
894+
895+
896+*Table: `INVOKE_DPE_MLDSA87` output arguments*
829897
830898 | **Name** | **Type** | **Description**
831899 | -------- | -------- | ---------------
@@ -1143,35 +1211,69 @@
11431211 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian.
11441212 | fips\_status | u32 | Indicates if the command is FIPS approved or an error.
11451213
1146-### CERTIFY\_KEY\_EXTENDED
1147-
1148-Produces a DPE leaf certificate or CSR containing custom extensions provided by the SoC.
1214+### CERTIFY\_KEY\_EXTENDED\_ECC384
1215+
1216+Produces an ECC-P384 DPE leaf certificate or CSR containing custom extensions provided by the SoC.
11491217
11501218 Command Code: `0x434B_4558` ("CKEX")
11511219
1152-*Table: `CERTIFY_KEY_EXTENDED` input arguments*
1220+*Table: `CERTIFY_KEY_EXTENDED_ECC384` input arguments*
11531221
11541222 | **Name** | **Type** | **Description** |
11551223 | ----------------- | -------- | --------------------------------------------------------------------------- |
11561224 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
1225+| flags | u32 | Flags determining which custom extensions to include in the certificate. |
11571226 | certify\_key\_req | u8[72] | Certify Key Request. |
1158-| flags | u32 | Flags determining which custom extensions to include in the certificate. |
1159-
1160-
1161-*Table: `CERTIFY_KEY_EXTENDED` input flags*
1227+
1228+
1229+*Table: `CERTIFY_KEY_EXTENDED_ECC384` input flags*
11621230
11631231 | **Name** | **Offset** |
1164-| --------------- | ---------- |
1165-| DMTF_OTHER_NAME | 1 << 31 |
1166-
1167-
1168-*Table: `CERTIFY_KEY_EXTENDED` output arguments*
1169-
1170-| **Name** | **Type** | **Description** |
1171-| ------------------ | -------- | -------------------------------------------------------------------------- |
1232+| ----------------- | ---------- |
1233+| DMTF\_OTHER\_NAME | 1 << 31 |
1234+
1235+
1236+*Table: `CERTIFY_KEY_EXTENDED_ECC384` output arguments*
1237+
1238+| **Name** | **Type** | **Description** |
1239+| ------------------ | --------- | -------------------------------------------------------------------------- |
11721240 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
11731241 | fips\_status | u32 | Indicates if the command is FIPS approved or an error. |
1174-| certify\_key\_resp | u8[2176] | Certify Key Response. |
1242+| size | u32 | The size of the response in the certify\_key\_resp field. |
1243+| certify\_key\_resp | u8[25152] | Certify Key Response. |
1244+
1245+
1246+### CERTIFY\_KEY\_EXTENDED\_MLDSA87
1247+
1248+Produces an ML-DSA-87 DPE leaf certificate or CSR containing custom extensions provided by the SoC.
1249+
1250+Command Code: `0x434B_584D` ("CKXM")
1251+
1252+*Table: `CERTIFY_KEY_EXTENDED_MLDSA87` input arguments*
1253+
1254+| **Name** | **Type** | **Description** |
1255+| ----------------- | -------- | --------------------------------------------------------------------------- |
1256+| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
1257+| flags | u32 | Flags determining which custom extensions to include in the certificate. |
1258+| certify\_key\_req | u8[72] | Certify Key Request. |
1259+
1260+
1261+*Table: `CERTIFY_KEY_EXTENDED_MLDSA87` input flags*
1262+
1263+| **Name** | **Offset** |
1264+| ----------------------- | ---------- |
1265+| DMTF\_OTHER\_NAME | 1 << 31 |
1266+| EXTERNAL\_AXI\_RESPONSE | 1 << 30 |
1267+
1268+
1269+*Table: `CERTIFY_KEY_EXTENDED_MLDSA87` output arguments*
1270+
1271+| **Name** | **Type** | **Description** |
1272+| ------------------ | --------- | -------------------------------------------------------------------------- |
1273+| chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
1274+| fips\_status | u32 | Indicates if the command is FIPS approved or an error. |
1275+| size | u32 | The size of the response in the certify\_key\_resp field. |
1276+| certify\_key\_resp | u8[25152] | Certify Key Response. |
11751277
11761278
11771279 ### SET_AUTH_MANIFEST
@@ -1182,8 +1284,8 @@
11821284
11831285 *Table: `SET_AUTH_MANIFEST` input arguments*
11841286
1185-| **Name** | **Type** | **Description**
1186-| -------- | -------- | ---------------
1287+| **Name** | **Type** | **Description** |
1288+| -------- | -------- | --------------- |
11871289 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
11881290 | manifest size | u32 | The size of the full Authentication Manifest |
11891291 | preamble\_marker | u32 | Marker needs to be 0x4154_4D4E for the preamble to be valid |
@@ -1219,17 +1321,17 @@
12191321 | **Name** | **Type** | **Description** |
12201322 | ------------------------ | --------- | ---------------- |
12211323 | Image Hash | u8[48] | SHA2-384 hash of a SOC image. |
1222-
1223-| Image_id | u32 | This corresponds to the `Image Identifier` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main-2.x/auth-manifest/README.md)
1224-| Component_id | u32 | This corresponds to the `Component Id` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main-2.x/auth-manifest/README.md)
1225-| flags | u32 | This corresponds to the `flags` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main-2.x/auth-manifest/README.md)
1226-| Image Load Address High | u32 | This corresponds to the `Image Load Address High` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main-2.x/auth-manifest/README.md)
1227-| Image Load Address Low | u32 | This corresponds to the `Image Load Address Low` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main-2.x/auth-manifest/README.md)
1228-| Staging Address High | u32 | This corresponds to the `Staging Address High` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main-2.x/auth-manifest/README.md)
1229-| Staging Address Low | u32 | This corresponds to the `Staging Address Low` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main-2.x/auth-manifest/README.md)
1230-| Classification | u32 | This corresponds to the `Classification` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main-2.x/auth-manifest/README.md)
1231-| Version Number | u32 | This corresponds to the `Version Number` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main-2.x/auth-manifest/README.md)
1232-| Version String | u8[32] | This corresponds to the `Version String` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main-2.x/auth-manifest/README.md)
1324+| Image_id | u32 | This corresponds to the `Image Identifier` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main/auth-manifest/README.md) |
1325+| Component_id | u32 | This corresponds to the `Component Id` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main/auth-manifest/README.md) |
1326+| flags | u32 | This corresponds to the `flags` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main/auth-manifest/README.md) |
1327+| Image Load Address High | u32 | This corresponds to the `Image Load Address High` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main/auth-manifest/README.md) |
1328+| Image Load Address Low | u32 | This corresponds to the `Image Load Address Low` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main/auth-manifest/README.md) |
1329+| Staging Address High | u32 | This corresponds to the `Staging Address High` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main/auth-manifest/README.md) |
1330+| Staging Address Low | u32 | This corresponds to the `Staging Address Low` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main/auth-manifest/README.md) |
1331+| Classification | u32 | This corresponds to the `Classification` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main/auth-manifest/README.md) |
1332+| Version Number | u32 | This corresponds to the `Version Number` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main/auth-manifest/README.md) |
1333+| Version String | u8[32] | This corresponds to the `Version String` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main/auth-manifest/README.md) |
1334+
12331335
12341336 ### VERIFY_AUTH_MANIFEST
12351337
@@ -1251,8 +1353,8 @@
12511353
12521354 *Table: `AUTHORIZE_AND_STASH` input arguments*
12531355
1254-| **Name** | **Type** | **Description**
1255-| ------------| -------- | ---------------
1356+| **Name** | **Type** | **Description** |
1357+| ------------ | -------- | --------------- |
12561358 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
12571359 | fw_id | u8[4] | Firmware id of the image, in little-endian format |
12581360 | measurement | u8[48] | Digest of the image requested for authorization. The `source` field needs to be set to '1` for InRequest, otherwise<br />this field is ignored. |
@@ -1274,8 +1376,8 @@
12741376 | --------------- | -------- | -------------------------------------------------------------------------- |
12751377 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
12761378 | fips_status | u32 | Indicates if the command is FIPS approved or an error. |
1277-
1278-| auth_req_result | u32 |AUTHORIZE_IMAGE (0xDEADC0DE), IMAGE_NOT_AUTHORIZED (0x21523F21) or IMAGE_HASH_MISMATCH (0x8BFB95CB)
1379+| auth_req_result | u32 | AUTHORIZE_IMAGE (0xDEADC0DE), IMAGE_NOT_AUTHORIZED (0x21523F21) or IMAGE_HASH_MISMATCH (0x8BFB95CB) |
1380+
12791381
12801382 ### GET_IMAGE_INFO
12811383
@@ -1288,8 +1390,8 @@
12881390 | **Name** | **Type** | **Description** |
12891391 | -------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
12901392 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
1291-
1292-| fw_id | u32 | Firmware id of the image, in little-endian format
1393+| fw_id | u32 | Firmware id of the image, in little-endian format |
1394+
12931395
12941396 *Table: `GET_IMAGE_INFO` output arguments*
12951397
@@ -1297,13 +1399,36 @@
12971399 | -------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
12981400 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
12991401 | fips_status | u32 | Indicates if the command is FIPS approved or an error. |
1300-| Component_id | u32 | This corresponds to the `Component Id` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/caliptra-2.0/auth-manifest/README.md) |
1301-| flags | u32 | This corresponds to the `flags` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/caliptra-2.0/auth-manifest/README.md) |
1302-| Image Load Address High | u32 | This corresponds to the `Image Load Address High` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/caliptra-2.0/auth-manifest/README.md) |
1303-| Image Load Address Low | u32 | This corresponds to the `Image Load Address Low` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/caliptra-2.0/auth-manifest/README.md) |
1304-| Staging Address High | u32 | This corresponds to the `Staging Address High` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/caliptra-2.0/auth-manifest/README.md) |
1305-| Staging Address Low | u32 | This corresponds to the `Staging Address Low` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/caliptra-2.0/auth-manifest/README.md) |
1402+| Component_id | u32 | This corresponds to the `Component Id` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main/auth-manifest/README.md) |
1403+| flags | u32 | This corresponds to the `flags` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main/auth-manifest/README.md) |
1404+| Image Load Address High | u32 | This corresponds to the `Image Load Address High` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main/auth-manifest/README.md) |
1405+| Image Load Address Low | u32 | This corresponds to the `Image Load Address Low` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main/auth-manifest/README.md) |
1406+| Staging Address High | u32 | This corresponds to the `Staging Address High` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main/auth-manifest/README.md) |
1407+| Staging Address Low | u32 | This corresponds to the `Staging Address Low` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main/auth-manifest/README.md) |
13061408 | digest | u8[48] | SHA-384 digest of the image. **Only present in FW 2.0.2+ and 2.1.1+.** |
1409+
1410+
1411+### GET\_MCU\_FW\_SIZE
1412+
1413+Returns the size and SHA-384 digest of the MCU firmware image that was downloaded during the recovery flow. This command is used by MCU ROM during encrypted boot so it can issue `CM_AES_GCM_DECRYPT_DMA` with the correct size and without recomputing the digest.
1414+
1415+Command Code: `0x474D_4653` ("GMFS")
1416+
1417+*Table: `GET_MCU_FW_SIZE` input arguments*
1418+
1419+| **Name** | **Type** | **Description** |
1420+| -------------- | -------------- | --------------------------------------------------------------------------- |
1421+| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
1422+
1423+
1424+*Table: `GET_MCU_FW_SIZE` output arguments*
1425+
1426+| **Name** | **Type** | **Description** |
1427+| -------------- | -------------- | -------------------------------------------------------------------------- |
1428+| chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
1429+| fips_status | u32 | Indicates if the command is FIPS approved or an error. |
1430+| size | u32 | Size of the MCU firmware image in bytes. |
1431+| sha384 | u8[48] | SHA-384 digest of the encrypted MCU firmware image. |
13071432
13081433
13091434 ### ACTIVATE_FIRMWARE
@@ -1330,6 +1455,28 @@
13301455 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
13311456 | fips_status | u32 | Indicates if the command is FIPS approved or an error. |
13321457
1458+
1459+## Mailbox commands: OCP LOCK v1.0
1460+
1461+These commands are defined in the OCP LOCK v1.0 [specification](https://github.com/chipsalliance/Caliptra/blob/main/doc/ocp_lock/releases/OCP_LOCK_Specification_v1.0_RC2.pdf).
1462+
1463+### ENUMERATE_HPKE_HANDLES
1464+### REPORT_HEK_METADATA
1465+### GET_ALGORITHMS
1466+### INITIALIZE_MEK_SECRET
1467+### ROTATE_HPKE_KEY
1468+### GENERATE_MEK
1469+### GENERATE_MPK
1470+### REWRAP_MPK
1471+### ENABLE_MPK
1472+### MIX_MPK
1473+### GET_HPKE_PUB_KEY
1474+### TEST_ACCESS_KEY
1475+### GET_STATUS
1476+### CLEAR_KEY_CACHE
1477+### UNLOAD_MEK
1478+### LOAD_MEK
1479+### DERIVE_MEK
13331480
13341481 ## Mailbox commands: Cryptographic Mailbox (2.0)
13351482
@@ -1433,6 +1580,99 @@
14331580 | fips_status | u32 | FIPS approved or an error |
14341581 | hash size | u32 ||
14351582 | hash | u8[hash size] ||
1583+
1584+
1585+### CM\_SHAKE256\_INIT
1586+
1587+This starts the computation of a SHAKE256 extendable-output hash, which may be larger than a single mailbox command allows.
1588+
1589+**Note:** Unlike the CM\_SHA commands, SHAKE256 cannot save and restore hardware state between calls. Instead, the SHA3 hardware state is kept live, and the context returned to the caller is an encrypted random session token. If any other SHA3 operation occurs between INIT and FINAL, the session is invalidated and UPDATE/FINAL will return an error.
1590+
1591+The sequence to use these are:
1592+* 1 `CM_SHAKE256_INIT` command
1593+* 0 or more `CM_SHAKE256_UPDATE` commands
1594+* 1 `CM_SHAKE256_FINAL` command
1595+
1596+For each command, the context from the previous command's output must be passed as an input.
1597+
1598+The `SHAKE256_CONTEXT_SIZE` is always exactly 44 bytes long (encrypted session token).
1599+
1600+The maximum supported input data size per command is 4096 bytes.
1601+
1602+Command Code: `0x434D_5849` ("CMXI")
1603+
1604+*Table: `CM_SHAKE256_INIT` input arguments*
1605+
1606+| **Name** | **Type** | **Description** |
1607+| --------- | ------------- | --------------- |
1608+| chksum | u32 ||
1609+| data size | u32 ||
1610+| data | u8[data size] | Data to hash |
1611+
1612+
1613+*Table: `CM_SHAKE256_INIT` output arguments*
1614+
1615+| **Name** | **Type** | **Description** |
1616+| ----------- | ------------------------- | -------------------------------------------------- |
1617+| chksum | u32 ||
1618+| fips_status | u32 | FIPS approved or an error |
1619+| context | u8[SHAKE256_CONTEXT_SIZE] | Passed to `CM_SHAKE256_UPDATE` / `CM_SHAKE256_FINAL` |
1620+
1621+
1622+### CM\_SHAKE256\_UPDATE
1623+
1624+This continues a SHAKE256 computation started by `CM_SHAKE256_INIT` or from another `CM_SHAKE256_UPDATE`.
1625+
1626+The context MUST be passed in from `CM_SHAKE256_INIT` or `CM_SHAKE256_UPDATE`.
1627+
1628+Command Code: `0x434D_5855` ("CMXU")
1629+
1630+*Table: `CM_SHAKE256_UPDATE` input arguments*
1631+
1632+| **Name** | **Type** | **Description** |
1633+| --------- | ------------------------- | ---------------------------------------------------- |
1634+| chksum | u32 ||
1635+| context | u8[SHAKE256_CONTEXT_SIZE] | From `CM_SHAKE256_INIT` / `CM_SHAKE256_UPDATE` |
1636+| data size | u32 ||
1637+| data | u8[data size] | Data to hash |
1638+
1639+
1640+*Table: `CM_SHAKE256_UPDATE` output arguments*
1641+
1642+| **Name** | **Type** | **Description** |
1643+| ----------- | ------------------------- | -------------------------------------------------- |
1644+| chksum | u32 ||
1645+| fips_status | u32 | FIPS approved or an error |
1646+| context | u8[SHAKE256_CONTEXT_SIZE] | Passed to `CM_SHAKE256_UPDATE` / `CM_SHAKE256_FINAL` |
1647+
1648+
1649+### CM\_SHAKE256\_FINAL
1650+
1651+This finalizes the SHAKE256 computation and produces the hash of all of the data.
1652+
1653+The context MUST be passed in from `CM_SHAKE256_INIT` or `CM_SHAKE256_UPDATE`.
1654+
1655+The output is always a 64-byte SHAKE256 digest.
1656+
1657+Command Code: `0x434D_5846` ("CMXF")
1658+
1659+*Table: `CM_SHAKE256_FINAL` input arguments*
1660+
1661+| **Name** | **Type** | **Description** |
1662+| ----------- | ------------------------- | ---------------------------------------------- |
1663+| chksum | u32 ||
1664+| context | u8[SHAKE256_CONTEXT_SIZE] | From `CM_SHAKE256_INIT` / `CM_SHAKE256_UPDATE` |
1665+| data size | u32 | May be 0 |
1666+| data | u8[data size] | Data to hash |
1667+
1668+
1669+*Table: `CM_SHAKE256_FINAL` output arguments*
1670+
1671+| **Name** | **Type** | **Description** |
1672+| ----------- | -------- | ------------------------- |
1673+| chksum | u32 ||
1674+| fips_status | u32 | FIPS approved or an error |
1675+| hash | u8[64] | SHAKE256 digest |
14361676
14371677
14381678 ### CM\_HMAC
@@ -1723,6 +1963,79 @@
17231963 | fips_status | u32 | FIPS approved or an error |
17241964
17251965
1966+### CM_MLKEM_KEY_GEN
1967+
1968+Generates an ML-KEM-1024 encapsulation key from the seed (seed\_d || seed\_z, 64 bytes) stored in a CMK with key usage `Mlkem`.
1969+
1970+The key generation algorithm is described in [FIPS 203](https://csrc.nist.gov/pubs/fips/203/final).
1971+
1972+Command Code: `0x434D_4C4B` ("CMLK")
1973+
1974+*Table: `CM_MLKEM_KEY_GEN` input arguments*
1975+| **Name** | **Type** | **Description** |
1976+| -------- | -------- | ---------------------------------------- |
1977+| chksum | u32 ||
1978+| CMK | CMK | ML-KEM seed (seed\_d &#124;&#124; seed\_z) |
1979+
1980+
1981+*Table: `CM_MLKEM_KEY_GEN` output arguments*
1982+| **Name** | **Type** | **Description** |
1983+| ----------- | -------- | ---------------------------------------- |
1984+| chksum | u32 ||
1985+| fips_status | u32 | FIPS approved or an error |
1986+| encaps_key | u8[1568] | ML-KEM-1024 encapsulation key |
1987+
1988+
1989+### CM_MLKEM_ENCAPSULATE
1990+
1991+Performs ML-KEM-1024 encapsulation against the provided encapsulation key, producing a ciphertext and a shared key wrapped as a CMK.
1992+
1993+The encapsulation algorithm is described in [FIPS 203](https://csrc.nist.gov/pubs/fips/203/final).
1994+
1995+Command Code: `0x434D_4C45` ("CMLE")
1996+
1997+*Table: `CM_MLKEM_ENCAPSULATE` input arguments*
1998+| **Name** | **Type** | **Description** |
1999+| ----------- | -------- | ---------------------------------------- |
2000+| chksum | u32 ||
2001+| key_usage | u32 | Key usage for the output CMK |
2002+| encaps_key | u8[1568] | ML-KEM-1024 encapsulation key |
2003+
2004+
2005+*Table: `CM_MLKEM_ENCAPSULATE` output arguments*
2006+| **Name** | **Type** | **Description** |
2007+| ----------- | -------- | ---------------------------------------- |
2008+| chksum | u32 ||
2009+| fips_status | u32 | FIPS approved or an error |
2010+| ciphertext | u8[1568] | ML-KEM-1024 ciphertext |
2011+| shared_key | CMK | CMK of the shared secret key |
2012+
2013+
2014+### CM_MLKEM_DECAPSULATE
2015+
2016+Performs ML-KEM-1024 decapsulation using the seed in the provided CMK and the given ciphertext, recovering the shared key wrapped as a CMK. This uses the hardware's combined keygen\_decapsulate operation to avoid materializing the full 3168-byte decapsulation key in memory.
2017+
2018+The decapsulation algorithm is described in [FIPS 203](https://csrc.nist.gov/pubs/fips/203/final).
2019+
2020+Command Code: `0x434D_4C44` ("CMLD")
2021+
2022+*Table: `CM_MLKEM_DECAPSULATE` input arguments*
2023+| **Name** | **Type** | **Description** |
2024+| ----------- | -------- | ---------------------------------------- |
2025+| chksum | u32 ||
2026+| key_usage | u32 | Key usage for the output CMK |
2027+| CMK | CMK | ML-KEM seed (seed\_d &#124;&#124; seed\_z) |
2028+| ciphertext | u8[1568] | ML-KEM-1024 ciphertext to decapsulate |
2029+
2030+
2031+*Table: `CM_MLKEM_DECAPSULATE` output arguments*
2032+| **Name** | **Type** | **Description** |
2033+| ----------- | -------- | ---------------------------------------- |
2034+| chksum | u32 ||
2035+| fips_status | u32 | FIPS approved or an error |
2036+| shared_key | CMK | CMK of the shared secret key |
2037+
2038+
17262039 ### CM_AES_ENCRYPT_INIT
17272040
17282041 Generic AES operation for unauthenticated AES operations.
@@ -1769,8 +2082,7 @@
17692082 | mode | u32 ||
17702083 | key | u8[32] ||
17712084 | iv | u8[16] ||
1772-| fips_status | u8 | 1 = FIPS valid |
1773-| reserved | u8[75] | Reserved for additional fields |
2085+| reserved | u8[76] | Reserved for additional fields |
17742086
17752087
17762088 The size of the (encrypted) context is always exactly 156 bytes,
@@ -1919,8 +2231,7 @@
19192231 | GHASH state | u8[16] ||
19202232 | current length | u32 | value mod 16 is buffer size |
19212233 | buffer | u8[16] ||
1922-| fips_status | u8 | 1 = FIPS valid |
1923-| reserved | u8[15] ||
2234+| reserved | u8[16] ||
19242235
19252236
19262237 The size of the (encrypted) context is always exactly 128 bytes,
@@ -2192,6 +2503,44 @@
21922503 | plaintext | u8[plaintext size] ||
21932504
21942505
2506+### CM_AES_GCM_DECRYPT_DMA
2507+
2508+Performs in-place AES-256-GCM decryption of data at an AXI address using DMA. This command is specifically designed for decrypting MCU firmware that was downloaded via the `RI_DOWNLOAD_ENCRYPTED_FIRMWARE` command.
2509+
2510+**Important restrictions:**
2511+- This command is only available in subsystem mode, as DMA is only available in subsystem.
2512+- This command is only available when the boot mode is `EncryptedFirmware`, which is set by ROM when it receives the `RI_DOWNLOAD_ENCRYPTED_FIRMWARE` command.
2513+- The command performs a two-pass operation:
2514+ 1. First pass: Verifies the SHA384 hash of the encrypted data at the AXI address
2515+ 2. Second pass: Performs in-place AES-GCM decryption via DMA
2516+
2517+The CMK must be an AES key (key usage = 3) that was previously imported using `CM_IMPORT`.
2518+
2519+Command Code: `0x434D_4444` ("CMDD")
2520+
2521+*Table: `CM_AES_GCM_DECRYPT_DMA` input arguments*
2522+| **Name** | **Type** | **Description** |
2523+| --------------------- | --------- | ---------------------------------------------------- |
2524+| chksum | u32 | Checksum over other input arguments |
2525+| cmk | CMK | Encrypted CMK containing the AES-256 key |
2526+| iv | u32[3] | AES-GCM initialization vector (12 bytes) |
2527+| tag | u32[4] | AES-GCM authentication tag (16 bytes) |
2528+| encrypted_data_sha384 | u8[48] | SHA384 hash of the encrypted data for verification |
2529+| axi_addr_lo | u32 | Lower 32 bits of the AXI address |
2530+| axi_addr_hi | u32 | Upper 32 bits of the AXI address |
2531+| length | u32 | Length of data to decrypt in bytes |
2532+| aad_length | u32 | Length of AAD in bytes (0-4095) |
2533+| aad | u8[...] | Additional authenticated data |
2534+
2535+
2536+*Table: `CM_AES_GCM_DECRYPT_DMA` output arguments*
2537+| **Name** | **Type** | **Description** |
2538+| ------------ | -------- | ----------------------------------------------------- |
2539+| chksum | u32 | Checksum over other output arguments |
2540+| fips_status | u32 | FIPS approved or an error |
2541+| tag_verified | u32 | 1 if GCM tag verification succeeded, 0 if it failed |
2542+
2543+
21952544 ### CM_ECDH_GENERATE
21962545
21972546 This computes the first half of an Elliptic Curve Diffie-Hellman exchange to compute an ephemeral shared key pair with another party.
@@ -2320,22 +2669,20 @@
23202669 If a key usage other than HMAC is desired, then the KDF or HKDF
23212670 mailbox functions can be used to derive a key from the returned CMK.
23222671
2323-Note that in Caliptra 2.0 in subsystem mode, derived stable keys, their derivatives, and commands using them will be marked with a FIPS status of invalid since the UDS and FE cannot be completely zeroized.
2324-
23252672 Command Code: `0x434D_4453` ("CMDS")
23262673
23272674 *Table: `CM_DERIVE_STABLE_KEY` input arguments*
23282675
2329-| **Name** | **Type** | **Description**
2330-| -------- | -------- | ---------------
2676+| **Name** | **Type** | **Description** |
2677+| -------- | -------- | --------------- |
23312678 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
23322679 | key_type | u32 | Source key to derive the stable key from. **0x0000_0001:** IDevId <br> **0x0000_0002:** LDevId |
23332680 | info | u8[32] | Data to use in the key derivation. |
23342681
23352682
23362683 *Table: `CM_DERIVE_STABLE_KEY` output arguments*
2337-| **Name** | **Type** | **Description**
2338-| -------- | -------- | ---------------
2684+| **Name** | **Type** | **Description** |
2685+| -------- | -------- | --------------- |
23392686 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
23402687 | cmk | CMK | CMK that stores the stable key material |
23412688
@@ -2345,9 +2692,6 @@
23452692 Imports the specified key and returns a CMK for it.
23462693
23472694 Usage information is required so that the key can be verified and used appropriately.
2348-
2349-Note that it is the caller's responsibility to ensure that the source
2350-key material meets FIPS requirements, such as zeroization.
23512695
23522696 Command Code: `0x434D_494D` ("CMIM")
23532697
@@ -2432,14 +2776,14 @@
24322776
24332777 *Table: `GET_IDEV_ECC384_CSR` input arguments*
24342778
2435-| **Name** | **Type** | **Description**
2436-| -------- | -------- | ---------------
2779+| **Name** | **Type** | **Description** |
2780+| -------- | -------- | --------------- |
24372781 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
24382782
24392783
24402784 *Table: `GET_IDEV_ECC384_CSR` output arguments*
2441-| **Name** | **Type** | **Description**
2442-| -------- | -------- | ---------------
2785+| **Name** | **Type** | **Description** |
2786+| -------- | -------- | --------------- |
24432787 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
24442788 | data\_size | u32 | Length in bytes of the valid data in the data field. |
24452789 | data | u8[...] | DER-encoded ECC384 IDevID certificate signing request. |
@@ -2451,14 +2795,14 @@
24512795
24522796 *Table: `GET_IDEV_MLDSA87_CSR` input arguments*
24532797
2454-| **Name** | **Type** | **Description**
2455-| -------- | -------- | ---------------
2798+| **Name** | **Type** | **Description** |
2799+| -------- | -------- | --------------- |
24562800 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
24572801
24582802
24592803 *Table: `GET_IDEV_MLDSA87_CSR` output arguments*
2460-| **Name** | **Type** | **Description**
2461-| -------- | -------- | ---------------
2804+| **Name** | **Type** | **Description** |
2805+| -------- | -------- | --------------- |
24622806 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
24632807 | data\_size | u32 | Length in bytes of the valid data in the data field. |
24642808 | data | u8[...] | DER-encoded MLDSA87 IDevID certificate signing request. |
@@ -2478,14 +2822,14 @@
24782822
24792823 *Table: `GET_FMC_ALIAS_ECC384_CSR` input arguments*
24802824
2481-| **Name** | **Type** | **Description**
2482-| -------- | -------- | ---------------
2825+| **Name** | **Type** | **Description** |
2826+| -------- | -------- | --------------- |
24832827 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
24842828
24852829
24862830 *Table: `GET_FMC_ALIAS_ECC384_CSR` output arguments*
2487-| **Name** | **Type** | **Description**
2488-| -------- | -------- | ---------------
2831+| **Name** | **Type** | **Description** |
2832+| -------- | -------- | --------------- |
24892833 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
24902834 | data\_size | u32 | Length in bytes of the valid data in the data field. |
24912835 | data | u8[...] | DER-encoded ECC384 FMC Alias certificate signing request. |
@@ -2497,19 +2841,67 @@
24972841
24982842 *Table: `GET_FMC_ALIAS_MLDSA87_CSR` input arguments*
24992843
2500-| **Name** | **Type** | **Description**
2501-| -------- | -------- | ---------------
2844+| **Name** | **Type** | **Description** |
2845+| -------- | -------- | --------------- |
25022846 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
25032847
25042848
25052849 *Table: `GET_FMC_ALIAS_MLDSA87_CSR` output arguments*
2506-| **Name** | **Type** | **Description**
2507-| -------- | -------- | ---------------
2850+| **Name** | **Type** | **Description** |
2851+| -------- | -------- | --------------- |
25082852 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
25092853 | data\_size | u32 | Length in bytes of the valid data in the data field. |
25102854 | data | u8[...] | DER-encoded MLDSA87 FMC Alias certificate signing request. |
25112855
25122856
2857+### GET\_ATTESTED\_ECC384\_CSR
2858+
2859+Generates an attested ECC384 certificate signing request (CSR) in Entity Attestation Token (EAT) format as per the [OCP Device Identity Provisioning](https://opencomputeproject.github.io/Security/device-identity-provisioning/HEAD/) specification, signed by the `RT Alias` key for the requested Device Identity Key.
2860+
2861+Command Code: `0x4145_4352` ("AECR")
2862+
2863+*Table: `GET_ATTESTED_ECC384_CSR` input arguments*
2864+
2865+| **Name** | **Type** | **Description** |
2866+| -------- | -------- | --------------- |
2867+| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
2868+| key_id | u32 | Key ID for which CSR is requested.<br> **0x0000_0001:** LDevId <br> **0x0000_0002:** FMC Alias <br> **0x0000_0003:** RT Alias |
2869+| nonce | u8[32] | Nonce to be included in the CSR EAT. |
2870+
2871+
2872+*Table: `GET_ATTESTED_ECC384_CSR` output arguments*
2873+
2874+| **Name** | **Type** | **Description** |
2875+| -------- | -------- | --------------- |
2876+| chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
2877+| data\_size | u32 | Length in bytes of the valid data in the data field. |
2878+| data | u8[...] | DER-encoded ECC384 attested certificate signing request. |
2879+
2880+
2881+### GET\_ATTESTED\_MLDSA87\_CSR
2882+
2883+Generates an attested MLDSA87 certificate signing request (CSR) in Entity Attestation Token (EAT) format as per the [OCP Device Identity Provisioning](https://opencomputeproject.github.io/Security/device-identity-provisioning/HEAD/) specification, signed by the `RT Alias` key for the requested Device Identity Key.
2884+
2885+Command Code: `0x414D_4352` ("AMCR")
2886+
2887+*Table: `GET_ATTESTED_MLDSA87_CSR` input arguments*
2888+
2889+| **Name** | **Type** | **Description** |
2890+| -------- | -------- | --------------- |
2891+| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
2892+| key_id | u32 | Key ID for which CSR is requested.<br> **0x0000_0001:** LDevId <br> **0x0000_0002:** FMC Alias <br> **0x0000_0003:** RT Alias |
2893+| nonce | u8[32] | Nonce to be included in the CSR EAT. |
2894+
2895+
2896+*Table: `GET_ATTESTED_MLDSA87_CSR` output arguments*
2897+
2898+| **Name** | **Type** | **Description** |
2899+| -------- | -------- | --------------- |
2900+| chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
2901+| data\_size | u32 | Length in bytes of the valid data in the data field. |
2902+| data | u8[...] | DER-encoded MLDSA87 attested certificate signing request. |
2903+
2904+
25132905 ### SIGN\_WITH\_EXPORTED\_ECDSA
25142906
25152907 Command Code: `0x5357_4545` ("SWEE")
@@ -2518,16 +2910,16 @@
25182910
25192911 *Table: `SIGN_WITH_EXPORTED_ECDSA` input arguments*
25202912
2521-| **Name** | **Type** | **Description**
2522-| -------- | -------- | ---------------
2913+| **Name** | **Type** | **Description** |
2914+| -------- | -------- | --------------- |
25232915 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
25242916 | exported_cdi_handle | u8[32] | The Exported CDI handle returned by the DPE `DeriveContext` command. Little endian. |
25252917 | tbs | u8[48] | The bytes to be signed. Little endian. |
25262918
25272919
25282920 *Table: `SIGN_WITH_EXPORTED_ECDSA` output arguments*
2529-| **Name** | **Type** | **Description**
2530-| -------- | -------- | ---------------
2921+| **Name** | **Type** | **Description** |
2922+| -------- | -------- | --------------- |
25312923 | derived_pubkey_x | u8[48] | The X BigNum of the ECDSA public key associated with the signing key. |
25322924 | derived_pubkey_y | u8[48] | The Y BigNum of the ECDSA public key associated with the signing key. |
25332925 | signature_r | u8[48] | The R BigNum of an ECDSA signature. |
@@ -2544,8 +2936,8 @@
25442936
25452937 *Table: `REVOKE_EXPORTED_CDI_HANDLE` input arguments*
25462938
2547-| **Name** | **Type** | **Description**
2548-| -------- | -------- | ---------------
2939+| **Name** | **Type** | **Description** |
2940+| -------- | -------- | --------------- |
25492941 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
25502942 | exported_cdi_handle | u8[32] | The Exported CDI handle returned by the DPE `DeriveContext` command. Little endian. |
25512943
@@ -2555,6 +2947,35 @@
25552947 The `exported_cdi_handle` is no longer usable after calling `REVOKE_EXPORTED_CDI_HANDLE` with it. After the `exported_cdi_handle`
25562948 has been revoked, a new exported CDI can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
25572949
2950+### EXTERNAL_MAILBOX_CMD
2951+
2952+Command Code: `0x4558_544D` ("EXTM")
2953+
2954+**Note**: This command is only available in subsystem mode in 2.1+.
2955+
2956+Executes a mailbox command located at an AXI address.
2957+This allows for executing mailbox commands that are larger than the mailbox allows.
2958+
2959+This is currently mostly useful for FIRMWARE_LOAD (as part of an update) or SET_AUTH_MANIFEST.
2960+
2961+The response is still written to the mailbox.
2962+
2963+The checksum is over the EXTM command, *not* the command that is loaded over AXI.
2964+That external command will still need its own checksum, if applicable.
2965+
2966+*Table: `EXTERNAL_MAILBOX_CMD` input arguments*
2967+
2968+| **Name** | **Type** | **Description** |
2969+| -------- | -------- | --------------- |
2970+| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
2971+| command_id | u32 | Command ID for the mailbox command to be executed. Little endian. |
2972+| command_size | u32 | Size of the mailbox command to be executed. Little endian. |
2973+| axi_address_low | u32 | Lower 32 bits of the AXI address that contains the mailbox command. Little endian. |
2974+| axi_address_high | u32 | High 32 bits of the AXI address that contains the mailbox command. Little endian. |
2975+
2976+
2977+The response will be the response of the executed external command.
2978+
25582979 ### REALLOCATE\_DPE\_CONTEXT\_LIMITS
25592980
25602981 Command Code: '5243_5458` ("RCTX")
@@ -2563,24 +2984,115 @@
25632984
25642985 *Table: `REALLOCATE_DPE_CONTEXT_LIMITS` input arguments*
25652986
2566-| **Name** | **Type** | **Description**
2567-| -------- | -------- | ---------------
2987+| **Name** | **Type** | **Description** |
2988+| -------- | -------- | --------------- |
25682989 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
25692990 | pl0_context_limit | u32 | Number of contexts to allocate to PL0. PL1 will receive remaining contexts. |
25702991
25712992
25722993 *Table: `REALLOCATE_DPE_CONTEXT_LIMITS` output arguments*
2573-| **Name** | **Type** | **Description**
2574-| -------- | -------- | ---------------
2994+| **Name** | **Type** | **Description** |
2995+| -------- | -------- | --------------- |
25752996 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
25762997 | fips_status | u32 | Indicates if the command is FIPS approved or an error. |
25772998 | new_pl0_context_limit | u32 | Number of contexts assigned to PL0 after the reallocation |
25782999 | new_pl1_context_limit | u32 | Number of contexts assigned to PL1 after the reallocation |
25793000
25803001
2581-This allows the user to reallocate the 32 DPE contexts between PL0 and PL1. By default, each gets 16 contexts.
3002+This allows the user to reallocate the 64 DPE contexts between PL0 and PL1. By default, each gets 32 contexts.
25823003
25833004 **Note**: 2 PL0 contexts are used by Caliptra itself during initialization.
3005+
3006+### FE\_PROG
3007+
3008+Programs Field Entropy (FE) into one of 4 FE partitions in the OTP fuse controller. This command
3009+is typically used during device provisioning flows.
3010+
3011+**Note**: This command is only available when the device is in the **Production** lifecycle state.
3012+
3013+Command Code: `0x4645_5052` ("FEPR")
3014+
3015+*Table: `FE_PROG` input arguments*
3016+
3017+| **Name** | **Type** | **Description**
3018+| -------- | -------- | ---------------
3019+| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian.
3020+| partition | u32 | FE partition number (valid values: 0–3).
3021+
3022+`FE_PROG` returns no output arguments other than the mailbox response header.
3023+
3024+### PRODUCTION\_AUTH\_DEBUG\_UNLOCK\_REQ
3025+
3026+Initiates the production debug unlock flow by generating a cryptographic challenge. The caller
3027+must solve the challenge by signing it with the appropriate ECC and MLDSA keys and returning
3028+the result via the [`PRODUCTION_AUTH_DEBUG_UNLOCK_TOKEN`](#production_auth_debug_unlock_token)
3029+command.
3030+
3031+This command performs the same function as the ROM's `AUTH_DEBUG_UNLOCK_REQ` command
3032+(documented in the [ROM README](../rom/dev/README.md#debug-unlock)), but is available at
3033+runtime.
3034+
3035+**Note**: This command requires the device to be in the **Production** lifecycle state and the
3036+`PROD_DEBUG_UNLOCK_REQ` bit in the `SS_DBG_MANUF_SERVICE_REG_REQ` register to be set.
3037+
3038+Command Code: `0x5044_5552` ("PDUR")
3039+
3040+*Table: `PRODUCTION_AUTH_DEBUG_UNLOCK_REQ` input arguments*
3041+
3042+| **Name** | **Type** | **Description**
3043+| -------- | -------- | ---------------
3044+| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian.
3045+| length | u32 | Length of the payload in DWORDs.
3046+| unlock\_level | u8 | Debug unlock level (1–8).
3047+| reserved | u8[3] | Reserved.
3048+
3049+*Table: `PRODUCTION_AUTH_DEBUG_UNLOCK_REQ` output arguments*
3050+
3051+| **Name** | **Type** | **Description**
3052+| -------- | -------- | ---------------
3053+| chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian.
3054+| fips\_status | u32 | Indicates if the command is FIPS approved or an error.
3055+| length | u32 | Length of the response payload in DWORDs.
3056+| unique\_device\_identifier | u8[32] | Device identifier of the Caliptra device.
3057+| challenge | u8[48] | Random challenge number generated by Caliptra.
3058+
3059+### PRODUCTION\_AUTH\_DEBUG\_UNLOCK\_TOKEN
3060+
3061+Completes the production debug unlock handshake by validating the caller's solution to the
3062+challenge generated by
3063+[`PRODUCTION_AUTH_DEBUG_UNLOCK_REQ`](#production_auth_debug_unlock_req). The caller must
3064+provide the device identifier and challenge from the previous request along with ECC-384 and
3065+ML-DSA-87 signatures proving possession of the authorized debug unlock key.
3066+
3067+Upon successful validation, Caliptra authorizes the debug unlock by setting the unlock level
3068+in the `SS_SOC_DBG_UNLOCK_LEVEL` register.
3069+
3070+This command performs the same function as the ROM's `AUTH_DEBUG_UNLOCK_TOKEN` command
3071+(documented in the [ROM README](../rom/dev/README.md#debug-unlock)), but is available at
3072+runtime.
3073+
3074+**Note**: This command requires a preceding successful `PRODUCTION_AUTH_DEBUG_UNLOCK_REQ` in
3075+the same boot session. The challenge is consumed on use and cannot be replayed.
3076+
3077+Command Code: `0x5044_5554` ("PDUT")
3078+
3079+*Table: `PRODUCTION_AUTH_DEBUG_UNLOCK_TOKEN` input arguments*
3080+
3081+| **Name** | **Type** | **Description**
3082+| -------- | -------- | ---------------
3083+| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian.
3084+| length | u32 | Length of the payload in DWORDs.
3085+| unique\_device\_identifier | u8[32] | Device identifier (must match value from challenge response).
3086+| unlock\_level | u8 | Debug unlock level (1–8, must match the original request).
3087+| reserved | u8[3] | Reserved.
3088+| challenge | u8[48] | Challenge (must match value from challenge response).
3089+| ecc\_public\_key | u8[96] | ECC P-384 public key.
3090+| mldsa\_public\_key | u8[2592] | ML-DSA-87 public key.
3091+| ecc\_signature | u8[96] | ECC P-384 signature of the message hashed using SHA2-384. R (48 bytes) &#124; S (48 bytes).
3092+| mldsa\_signature | u8[4628] | ML-DSA-87 signature of the message hashed using SHA2-512 (4627 bytes + 1 reserved byte).
3093+
3094+`PRODUCTION_AUTH_DEBUG_UNLOCK_TOKEN` returns no output arguments other than the mailbox
3095+response header.
25843096
25853097 ## Checksum
25863098
@@ -2691,14 +3203,14 @@
26913203 To prevent this, we establish active context limits for each PAUSER
26923204 privilege level:
26933205
2694-* PL0 - 16 active contexts
2695-* PL1 - 16 active contexts
3206+* PL0 - 32 active contexts
3207+* PL1 - 32 active contexts
26963208
26973209 If a DPE command were to activate a new context such that the total number of
26983210 active contexts in a privilege level is above its active context limit, the
26993211 InvokeDpe command should fail.
27003212
2701-At boot Caliptra Runtime FW consumes part of the PL0 active contexts (initially 16) to DeriveContext for:
3213+At boot Caliptra Runtime FW consumes part of the PL0 active contexts (initially 32) to DeriveContext for:
27023214 - RTFW Journey (RTFJ) Measurement (1)
27033215 - Caliptra Configured Initialization Values digest (CCIV) (1)
27043216 - ROM Stashed Measurements (max 8)