Changes to Runtime Specification

Comparing version 2.1 to 2.0
+803 additions -153 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/a52b30163a3b4211a7b164c98c5cd74c2a65c5ed/runtime/README.md" target="_blank">chipsalliance/caliptra-sw/runtime/README.md</a> @ <code>a52b301</code>
2+📄 Source: <a href="https://github.com/chipsalliance/caliptra-sw/blob/3f95d0949a362885b6ffacc00e1d4cd2da646a31/runtime/README.md" target="_blank">chipsalliance/caliptra-sw/runtime/README.md</a> @ <code>3f95d09</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
@@ -23,11 +23,17 @@
2323 * Add support for passive mode (same as 1.x) and subsystem (or active) mode
2424 * [MCU Runtime loading](#boot-and-initialization) (subsystem mode)
2525 * [Cryptographic mailbox commands](#cryptographic-mailbox-commands-new-in-20)
26-* `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. These commands return a non-approved FIPS status because the caller supplies the digest.
26+* `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.
27+
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+* `ECDSA384_SIGNATURE_VERIFY` and `LMS_SIGNATURE_VERIFY` return a non-approved FIPS status because the caller supplies the digest.
34+
2735
2836 ## Spec Opens
29-
30-* Cryptographic Mailbox: ML-KEM support
3137
3238 ## Runtime Firmware environment
3339
@@ -40,6 +46,20 @@
4046 * Initialize the [DICE Protection Environment (DPE)](#dice-protection-environment-dpe)
4147 * Initialize any SRAM structures used by Runtime Firmware
4248 * Upload the firmware to the Manufacturer Control Unit (2.0, subsystem mode only)
49+
50+#### Encrypted Firmware Support (2.1, subsystem mode only)
51+
52+When ROM receives the `RI_DOWNLOAD_ENCRYPTED_FIRMWARE` command instead of `RI_DOWNLOAD_FIRMWARE`, it sets the boot mode to `EncryptedFirmware`. In this mode:
53+
54+1. Runtime downloads the encrypted MCU firmware to MCU SRAM via the recovery interface
55+2. Runtime does **not** activate the MCU firmware immediately
56+3. The MCU ROM can then:
57+ - Import an AES key using `CM_IMPORT`
58+ - Decrypt the firmware in-place using `CM_AES_GCM_DECRYPT_DMA`
59+ - Send `ACTIVATE_FIRMWARE` with the `INITIAL_ACTIVATE` flag set, so Runtime publishes `FW_EXEC_CTRL[MCU]` without performing the hitless-update reload/verify dance (the firmware was already integrity-checked end-to-end by `RI_DOWNLOAD_ENCRYPTED_FIRMWARE` and `CM_AES_GCM_DECRYPT_DMA`). See [`ACTIVATE_FIRMWARE`](#activate_firmware) for the gating rules.
60+ - Trigger a warm reset; MCI releases MCU once `FW_EXEC_CTRL[MCU]` is asserted, and MCU FwBoot jumps into the decrypted firmware.
61+
62+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.
4363
4464 For behavior during other types of reset, see [Runtime firmware updates](#runtime-firmware-updates).
4565
@@ -94,7 +114,7 @@
94114
95115 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.
96116
97-These mailbox commands provide SHA, HMAC, HKDF, AES, RNG, MLDSA, and ECDSA services.
117+These mailbox commands provide SHA, HMAC, HKDF, AES, RNG, MLDSA, ECDSA, and ML-KEM services.
98118
99119 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.
100120
@@ -126,8 +146,7 @@
126146
127147 | **Name** | **Bits** | **Description** |
128148 | ------------- | -------- | -------------------------------------- |
129-| version | 8 | CMK version. Currently always 1. |
130-| flags | 8 | Bit 0 = FIPS valid |
149+| version | 16 | CMK version. Currently always 1. |
131150 | length | 16 | how many bits of key material are used |
132151 | key usage | 8 | represents which kind of key this is |
133152 | id | 24 | ID number |
@@ -162,8 +181,10 @@
162181 | --------- | --------- |
163182 | 0 | Reserved |
164183 | 1 | HMAC |
165-| 2 | HKDF |
166-| 3 | AES |
184+| 2 | AES |
185+| 3 | ECDSA |
186+| 4 | MLDSA |
187+| 5 | ML-KEM |
167188
168189
169190 #### Replay Prevention and Deletion
@@ -187,7 +208,7 @@
187208
188209 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.
189210
190-Manifest-based image authorization is implemented via three mailbox commands: [`SET_AUTH_MANIFEST`](#set-auth-manifest), [`SET_OWNER_AUTH_MANIFEST`](#set-owner-auth-manifest), and [`AUTHORIZE_AND_STASH`](#authorize-and-stash). A firmware ID identifies one platform firmware image and must be unique across the active vendor + owner and owner-only Image Metadata Collections. Both set commands reject a manifest containing an ID in the other active collection. `AUTHORIZE_AND_STASH` searches the vendor + owner collection first and then the owner-only collection; the provenance of the matching entry is reflected in its `auth_req_result` field.
211+Manifest-based image authorization is implemented via three mailbox commands: [`SET_AUTH_MANIFEST`](#set_auth_manifest), [`SET_OWNER_AUTH_MANIFEST`](#set_owner_auth_manifest), and [`AUTHORIZE_AND_STASH`](#authorize_and_stash). A firmware ID identifies one platform firmware image and must be unique across the active vendor + owner and owner-only Image Metadata Collections. Both set commands reject a manifest containing an ID in the other active collection. `AUTHORIZE_AND_STASH` searches the vendor + owner collection first and then the owner-only collection; the provenance of the matching entry is reflected in its `auth_req_result` field.
191212
192213 ### Caliptra-Endorsed Aggregated Measured Boot
193214
@@ -303,7 +324,69 @@
303324 Mailbox user 0xFFFF_FFFF is reserved for Caliptra internal use. All mailbox
304325 commands from that user will fail.
305326
306-### FW\_LOAD
327+### Byte order of cryptographic fields
328+
329+Several mailbox commands include ECC P-384 and ML-DSA-87 public keys,
330+signatures, and SHA digest values stored as `[u32]` arrays.
331+The "big endian" / "little endian" labels in individual command tables describe
332+how the **standard byte representation** produced by cryptographic
333+tools maps to those `u32` words.
334+
335+Generally, any fields specified as **little-endian** byte representation will match the standard byte representation of the cryptographic protocols, since the RISC-V processor is a little-endian processor.
336+
337+#### ECC P-384 fields (big-endian words)
338+
339+Each 4-byte group from the standard representation is byte-reversed on the
340+wire.
341+
342+Example — suppose OpenSSL produces a 48-byte X coordinate starting with:
343+
344+```
345+OpenSSL raw bytes: AB CD EF 01 23 45 67 89 ...
346+ ~~~~~~~~~~~ ~~~~~~~~~~~
347+Mailbox bytes: 01 EF CD AB 89 67 45 23 ...
348+```
349+
350+In other words: split the tool output into 4-byte groups, then reverse each
351+group.
352+
353+#### ML-DSA-87 fields (little-endian words)
354+
355+No conversion is needed. Copy the raw bytes produced by an ML-DSA-87
356+implementation (e.g., OpenSSL 3.5+, the `fips204` crate, or the NIST reference
357+implementation) directly into the mailbox buffer.
358+
359+```
360+openssl pkey output: AB CD EF 01 23 45 67 89 ...
361+Mailbox bytes: AB CD EF 01 23 45 67 89 ... (identical)
362+```
363+
364+#### SHA digest fields (big-endian words)
365+
366+Hash digests stored as `u32[N]` arrays use the same big-endian word convention
367+as ECC fields. Each 4-byte group of the standard hash output is byte-reversed
368+on the wire.
369+
370+Example — suppose `openssl dgst -sha384` produces a digest starting with:
371+
372+```
373+openssl output: A1 B2 C3 D4 E5 F6 07 18 ...
374+ ~~~~~~~~~~~ ~~~~~~~~~~~
375+Mailbox u32[12]: D4 C3 B2 A1 18 07 F6 E5 ...
376+```
377+
378+#### u8 byte-array fields (no conversion needed)
379+
380+When ECC P-384 keys, signatures, or SHA digests are declared as `u8[48]` (rather
381+than `u32[12]`), they use standard big-endian byte order — the same format
382+produced by OpenSSL and other cryptographic tools. No byte-swapping is required.
383+
384+For example, the `ECDSA384_SIGNATURE_VERIFY` input fields (`pub_key_x`,
385+`pub_key_y`, `signature_r`, `signature_s`, `hash`) and the `QUOTE_PCRS_ECC384`
386+output fields (`digest`, `signature_r`, `signature_s`) can be used directly with
387+`openssl` or OpenSSL's `BN_bin2bn()` without any conversion.
388+
389+### FIRMWARE\_LOAD
307390
308391 The `FIRMWARE_LOAD` command is handled by both ROM and Runtime Firmware.
309392
@@ -367,7 +450,14 @@
367450 | -------- | -------- | ---------------
368451 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian.
369452 | fips\_status | u32 | Indicates if the command is FIPS approved or an error.
370-| capabilities | u8[16] | Firmware capabilities
453+| capabilities | u8[16] | Firmware capabilities. See table below for details.
454+
455+*Table: Firmware Capabilities Flags*
456+
457+| **Name** | **Bit** | **Description**
458+| --------------- | ------- | ---------------
459+| `RT_BASE` | 64 | Base capabilities for Caliptra Runtime v2.1.
460+| `RT_OCP_LOCK` | 65 | Runtime firmware and hardware supports OCP LOCK.
371461
372462 ### GET\_IDEV\_ECC384\_CERT
373463
@@ -656,7 +746,7 @@
656746 | **Name** | **Type** | **Description**
657747 | -------- | -------- | ---------------
658748 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian.
659-| fips\_status | u32 | Indicates if the command is FIPS approved or an error.
749+| fips\_status | u32 | `FIPS_NOT_APPROVED_USER_SUPPLIED_DIGEST`, because the caller supplies the digest.
660750
661751 ### LMS\_SIGNATURE\_VERIFY
662752
@@ -697,7 +787,7 @@
697787 | **Name** | **Type** | **Description**
698788 | -------- | -------- | ---------------
699789 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian.
700-| fips\_status | u32 | Indicates if the command is FIPS approved or an error.
790+| fips\_status | u32 | `FIPS_NOT_APPROVED_USER_SUPPLIED_DIGEST`, because the caller supplies the digest.
701791
702792 ### MLDSA87_SIGNATURE_VERIFY
703793
@@ -740,7 +830,7 @@
740830 | **Name** | **Type** | **Description**
741831 | -------- | -------- | ---------------
742832 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian.
743-| digest | u32[12] | Owner public key hash.
833+| digest | u32[12] | Owner public key hash. See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields).
744834
745835 *Table: `INSTALL_OWNER_PK_HASH` output arguments*
746836
@@ -811,13 +901,13 @@
811901 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian.
812902 | fips\_status | u32 | Indicates if the command is FIPS approved or an error.
813903
814-### INVOKE\_DPE\_COMMAND
815-
816-Invokes a serialized DPE command.
904+### INVOKE\_DPE\_ECC384
905+
906+Invokes a serialized EC-P384 DPE profile command.
817907
818908 Command Code: `0x4450_4543` ("DPEC")
819909
820-*Table: `INVOKE_DPE_COMMAND` input arguments*
910+*Table: `INVOKE_DPE_ECC384` input arguments*
821911
822912 | **Name** | **Type** | **Description**
823913 | -------- | -------- | ---------------
@@ -825,7 +915,53 @@
825915 | data\_size | u32 | Length in bytes of the valid data in the data field.
826916 | data | u8[...] | DPE command structure as defined in the DPE iRoT profile.
827917
828-*Table: `INVOKE_DPE_COMMAND` output arguments*
918+*Table: `INVOKE_DPE_ECC384` output arguments*
919+
920+| **Name** | **Type** | **Description**
921+| -------- | -------- | ---------------
922+| chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian.
923+| fips\_status | u32 | Indicates if the command is FIPS approved or an error.
924+| data\_size | u32 | Length in bytes of the valid data in the data field.
925+| data | u8[...] | DPE response structure as defined in the DPE iRoT profile.
926+
927+### INVOKE\_DPE\_MLDSA87
928+
929+Invokes a serialized ML-DSA-87 DPE profile command. In subsystem mode a response
930+can be DMA'ed to an external address. This is especially useful for large
931+commands like `CertifyKey` or `DeriveContext` when exporting a CDI. Both of
932+these responses contain a potentially large certificate/CSR. To use this
933+feature, set the `EXTERNAL_AXI_RESPONSE` in `flags` and set the corresponding
934+AXI address and size fields. The response over the mailbox will only contain a
935+mailbox header (`chksum` and `fips_status`). The full response including the
936+mailbox header will be found at the given address.
937+
938+**Important restrictions for `EXTERNAL_AXI_RESPONSE` flag use:**
939+- This command is only available in subsystem mode, as DMA is only available in subsystem.
940+- This command is only available for MCU.
941+
942+Command Code: `0x4450_454D` ("DPEM")
943+
944+*Table: `INVOKE_DPE_MLDSA87` input arguments*
945+
946+| **Name** | **Type** | **Description** |
947+| -------------- | -------- | --------------------------------------------------------------------------- |
948+| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
949+| flags | u32 | Flags to give configurations of the command. |
950+| axi\_addr\_lo | u32 | Lower word of the destination physical address. |
951+| axi\_addr\_hi | u32 | Upper word of the destination physical address. |
952+| axi\_max\_size | u32 | Maximum DMA response size. |
953+| data\_size | u32 | Length in bytes of the valid data in the data field. |
954+| data | u8[...] | DPE command structure as defined in the DPE iRoT profile. |
955+
956+
957+*Table: `INVOKE_DPE_MLDSA87` input flags*
958+
959+| **Name** | **Value** |
960+| ----------------------- | --------- |
961+| EXTERNAL\_AXI\_RESPONSE | 1 << 31 |
962+
963+
964+*Table: `INVOKE_DPE_MLDSA87` output arguments*
829965
830966 | **Name** | **Type** | **Description**
831967 | -------- | -------- | ---------------
@@ -888,8 +1024,36 @@
8881024 | PCRs | PcrValue[32] | Values of all PCRs.
8891025 | nonce | u8[32] | Return the nonce used as input for convenience.
8901026 | reset\_ctrs | u32[32] | Reset counters for all PCRs.
891-| digest | u8[64] | Return the SHA2-512 digest over the PCR values and the nonce, in byte reversed order.
1027+| digest | u8[64] | SHA2-512 digest over the PCR values and the nonce, in DWORD-reversed order with per-word byte swap. See note below.
8921028 | signature | u8[4628] | MLDSA-87 signature over the `digest` (4627 bytes + 1 Reserved byte). </br> The FMC Alias MLDSA seed stored in Key Vault slot 8 is utilized to generate the private key, which is subsequently used for the signing operation.
1029+
1030+**Digest byte order:** The `digest` field has two transformations applied relative
1031+to the standard `openssl dgst -sha512` output: (1) the 16 u32 words are in
1032+reversed order, and (2) the bytes within each word are reversed. For example, if
1033+`openssl dgst -sha512` produces `A1 B2 C3 D4 E5 F6 07 18 ... P1 P2 P3 P4`,
1034+the mailbox response contains `P4 P3 P2 P1 ... 18 07 F6 E5 D4 C3 B2 A1`.
1035+
1036+To **independently recompute** this digest from PCR values and nonce, compute the
1037+SHA2-512 hash, then apply two steps:
1038+
1039+```
1040+openssl dgst -sha512 output (64 bytes, shown as 16 four-byte groups):
1041+ A1 B2 C3 D4 | E5 F6 07 18 | ... | M1 M2 M3 M4 | P1 P2 P3 P4
1042+
1043+Step 1 — reverse the bytes within each 4-byte group:
1044+ D4 C3 B2 A1 | 18 07 F6 E5 | ... | M4 M3 M2 M1 | P4 P3 P2 P1
1045+
1046+Step 2 — reverse the order of all 16 groups:
1047+ P4 P3 P2 P1 | M4 M3 M2 M1 | ... | 18 07 F6 E5 | D4 C3 B2 A1
1048+ ^^^^^^^^^^^^ ^^^^^^^^^^^^
1049+ (last group from Step 1 is now first) (first group is now last)
1050+
1051+Mailbox digest = result of Step 2
1052+```
1053+
1054+To **verify the signature** with an external tool such as OpenSSL, pass the `digest`
1055+bytes as-is as the pre-hashed message to ML-DSA-87 verification — no conversion
1056+is needed because the signature was computed over these exact bytes.
8931057
8941058 ### EXTEND\_PCR
8951059
@@ -1158,35 +1322,69 @@
11581322 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian.
11591323 | fips\_status | u32 | Indicates if the command is FIPS approved or an error.
11601324
1161-### CERTIFY\_KEY\_EXTENDED
1162-
1163-Produces a DPE leaf certificate or CSR containing custom extensions provided by the SoC.
1325+### CERTIFY\_KEY\_EXTENDED\_ECC384
1326+
1327+Produces an ECC-P384 DPE leaf certificate or CSR containing custom extensions provided by the SoC.
11641328
11651329 Command Code: `0x434B_4558` ("CKEX")
11661330
1167-*Table: `CERTIFY_KEY_EXTENDED` input arguments*
1331+*Table: `CERTIFY_KEY_EXTENDED_ECC384` input arguments*
11681332
11691333 | **Name** | **Type** | **Description** |
11701334 | ----------------- | -------- | --------------------------------------------------------------------------- |
11711335 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
1336+| flags | u32 | Flags determining which custom extensions to include in the certificate. |
11721337 | certify\_key\_req | u8[72] | Certify Key Request. |
1173-| flags | u32 | Flags determining which custom extensions to include in the certificate. |
1174-
1175-
1176-*Table: `CERTIFY_KEY_EXTENDED` input flags*
1338+
1339+
1340+*Table: `CERTIFY_KEY_EXTENDED_ECC384` input flags*
11771341
11781342 | **Name** | **Offset** |
1179-| --------------- | ---------- |
1180-| DMTF_OTHER_NAME | 1 << 31 |
1181-
1182-
1183-*Table: `CERTIFY_KEY_EXTENDED` output arguments*
1184-
1185-| **Name** | **Type** | **Description** |
1186-| ------------------ | -------- | -------------------------------------------------------------------------- |
1343+| ----------------- | ---------- |
1344+| DMTF\_OTHER\_NAME | 1 << 31 |
1345+
1346+
1347+*Table: `CERTIFY_KEY_EXTENDED_ECC384` output arguments*
1348+
1349+| **Name** | **Type** | **Description** |
1350+| ------------------ | --------- | -------------------------------------------------------------------------- |
11871351 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
11881352 | fips\_status | u32 | Indicates if the command is FIPS approved or an error. |
1189-| certify\_key\_resp | u8[2176] | Certify Key Response. |
1353+| size | u32 | The size of the response in the certify\_key\_resp field. |
1354+| certify\_key\_resp | u8[25152] | Certify Key Response. |
1355+
1356+
1357+### CERTIFY\_KEY\_EXTENDED\_MLDSA87
1358+
1359+Produces an ML-DSA-87 DPE leaf certificate or CSR containing custom extensions provided by the SoC.
1360+
1361+Command Code: `0x434B_584D` ("CKXM")
1362+
1363+*Table: `CERTIFY_KEY_EXTENDED_MLDSA87` input arguments*
1364+
1365+| **Name** | **Type** | **Description** |
1366+| ----------------- | -------- | --------------------------------------------------------------------------- |
1367+| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
1368+| flags | u32 | Flags determining which custom extensions to include in the certificate. |
1369+| certify\_key\_req | u8[72] | Certify Key Request. |
1370+
1371+
1372+*Table: `CERTIFY_KEY_EXTENDED_MLDSA87` input flags*
1373+
1374+| **Name** | **Offset** |
1375+| ----------------------- | ---------- |
1376+| DMTF\_OTHER\_NAME | 1 << 31 |
1377+| EXTERNAL\_AXI\_RESPONSE | 1 << 30 |
1378+
1379+
1380+*Table: `CERTIFY_KEY_EXTENDED_MLDSA87` output arguments*
1381+
1382+| **Name** | **Type** | **Description** |
1383+| ------------------ | --------- | -------------------------------------------------------------------------- |
1384+| chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
1385+| fips\_status | u32 | Indicates if the command is FIPS approved or an error. |
1386+| size | u32 | The size of the response in the certify\_key\_resp field. |
1387+| certify\_key\_resp | u8[25152] | Certify Key Response. |
11901388
11911389
11921390 ### CERTIFY\_KEY\_CHUNKS
@@ -1238,26 +1436,26 @@
12381436
12391437 *Table: `SET_AUTH_MANIFEST` input arguments*
12401438
1241-| **Name** | **Type** | **Description**
1242-| -------- | -------- | ---------------
1439+| **Name** | **Type** | **Description** |
1440+| -------- | -------- | --------------- |
12431441 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
12441442 | manifest size | u32 | The size of the full Authentication Manifest |
12451443 | preamble\_marker | u32 | Marker needs to be 0x4154_4D4E for the preamble to be valid |
12461444 | preamble\_size | u32 | Size of the preamble |
12471445 | preamble\_version | u32 | Version of the preamble |
12481446 | preamble\_flags | u32 | Manifest flags. See AUTH_MANIFEST_FLAGS below |
1249-| preamble\_vendor\_ecc384\_key | u32[24] | Vendor ECC384 key with X and Y coordinates in that order |
1250-| preamble\_vendor\_pqc\_key | u32[648] | Vendor MLDSA-87 or LMS-SHA192-H15 key |
1251-| preamble\_vendor\_ecc384\_sig | u32[24] | Vendor ECC384 signature |
1252-| preamble\_vendor\_PQC\_sig | u32[1157] | Vendor MLDSA-87 or LMOTS-SHA192-W4 signature |
1253-| preamble\_owner\_ecc384\_key | u32[24] | Owner ECC384 key with X and Y coordinates in that order |
1254-| preamble\_owner\_pqc\_key | u32[648] | Owner MLDSA-87 or LMS-SHA192-H15 key |
1255-| preamble\_owner\_ecc384\_sig | u32[24] | Owner ECC384 signature |
1256-| preamble\_owner\_PQC\_sig | u32[1157] | Owner MLDSA-87 or LMOTS-SHA192-W4 signature |
1257-| metadata\_vendor\_ecc384\_sig | u32[24] | Metadata Vendor ECC384 signature |
1258-| metadata\_vendor\_PQC\_sig | u32[1157] | Metadata Vendor MLDSA-87 or LMOTS-SHA192-W4 signature |
1259-| metadata\_owner\_ecc384\_sig | u32[24] | Metadata Owner ECC384 signature |
1260-| metadata\_owner\_PQC\_sig | u32[1157] | Metadata Owner MLDSA-87 or LMOTS-SHA192-W4 signature |
1447+| preamble\_vendor\_ecc384\_key | u32[24] | Vendor ECC384 key with X and Y coordinates in that order. See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields). |
1448+| preamble\_vendor\_pqc\_key | u32[648] | Vendor MLDSA-87 or LMS-SHA192-H15 key. See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields). |
1449+| preamble\_vendor\_ecc384\_sig | u32[24] | Vendor ECC384 signature. See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields). |
1450+| preamble\_vendor\_PQC\_sig | u32[1157] | Vendor MLDSA-87 or LMOTS-SHA192-W4 signature. See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields). |
1451+| preamble\_owner\_ecc384\_key | u32[24] | Owner ECC384 key with X and Y coordinates in that order. See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields). |
1452+| preamble\_owner\_pqc\_key | u32[648] | Owner MLDSA-87 or LMS-SHA192-H15 key. See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields). |
1453+| preamble\_owner\_ecc384\_sig | u32[24] | Owner ECC384 signature. See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields). |
1454+| preamble\_owner\_PQC\_sig | u32[1157] | Owner MLDSA-87 or LMOTS-SHA192-W4 signature. See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields). |
1455+| metadata\_vendor\_ecc384\_sig | u32[24] | Metadata Vendor ECC384 signature. See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields). |
1456+| metadata\_vendor\_PQC\_sig | u32[1157] | Metadata Vendor MLDSA-87 or LMOTS-SHA192-W4 signature. See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields). |
1457+| metadata\_owner\_ecc384\_sig | u32[24] | Metadata Owner ECC384 signature. See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields). |
1458+| metadata\_owner\_PQC\_sig | u32[1157] | Metadata Owner MLDSA-87 or LMOTS-SHA192-W4 signature. See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields). |
12611459 | metadata\_entry\_entry\_count | u32 | number of metadata entries |
12621460 | metadata\_entries | Metadata[80] | The max number of metadata entries is 80 but less can be used |
12631461
@@ -1275,17 +1473,17 @@
12751473 | **Name** | **Type** | **Description** |
12761474 | ------------------------ | --------- | ---------------- |
12771475 | Image Hash | u8[48] | SHA2-384 hash of a SOC image. |
1278-
1279-| 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)
1280-| 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)
1281-| 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)
1282-| 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)
1283-| 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)
1284-| 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)
1285-| 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)
1286-| 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)
1287-| 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)
1288-| 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)
1476+| 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) |
1477+| 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) |
1478+| flags | u32 | This corresponds to the `flags` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main/auth-manifest/README.md) |
1479+| 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) |
1480+| 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) |
1481+| 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) |
1482+| 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) |
1483+| Classification | u32 | This corresponds to the `Classification` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main/auth-manifest/README.md) |
1484+| 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) |
1485+| 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) |
1486+
12891487
12901488 ### VERIFY_AUTH_MANIFEST
12911489
@@ -1351,8 +1549,8 @@
13511549
13521550 *Table: `AUTHORIZE_AND_STASH` input arguments*
13531551
1354-| **Name** | **Type** | **Description**
1355-| ------------| -------- | ---------------
1552+| **Name** | **Type** | **Description** |
1553+| ------------ | -------- | --------------- |
13561554 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
13571555 | fw_id | u8[4] | Firmware id of the image, in little-endian format |
13581556 | 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. |
@@ -1392,8 +1590,8 @@
13921590 | **Name** | **Type** | **Description** |
13931591 | -------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
13941592 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
1395-
1396-| fw_id | u32 | Firmware id of the image, in little-endian format
1593+| fw_id | u32 | Firmware id of the image, in little-endian format |
1594+
13971595
13981596 *Table: `GET_IMAGE_INFO` output arguments*
13991597
@@ -1401,13 +1599,36 @@
14011599 | -------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
14021600 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
14031601 | fips_status | u32 | Indicates if the command is FIPS approved or an error. |
1404-| 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) |
1405-| 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) |
1406-| 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) |
1407-| 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) |
1408-| 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) |
1409-| 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) |
1602+| 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) |
1603+| flags | u32 | This corresponds to the `flags` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main/auth-manifest/README.md) |
1604+| 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) |
1605+| 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) |
1606+| 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) |
1607+| 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) |
14101608 | digest | u8[48] | SHA-384 digest of the image. **Only present in FW 2.0.2+ and 2.1.1+.** |
1609+
1610+
1611+### GET\_MCU\_FW\_SIZE
1612+
1613+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.
1614+
1615+Command Code: `0x474D_4653` ("GMFS")
1616+
1617+*Table: `GET_MCU_FW_SIZE` input arguments*
1618+
1619+| **Name** | **Type** | **Description** |
1620+| -------------- | -------------- | --------------------------------------------------------------------------- |
1621+| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
1622+
1623+
1624+*Table: `GET_MCU_FW_SIZE` output arguments*
1625+
1626+| **Name** | **Type** | **Description** |
1627+| -------------- | -------------- | -------------------------------------------------------------------------- |
1628+| chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
1629+| fips_status | u32 | Indicates if the command is FIPS approved or an error. |
1630+| size | u32 | Size of the MCU firmware image in bytes. |
1631+| sha384 | u8[48] | SHA-384 digest of the encrypted MCU firmware image. |
14111632
14121633
14131634 ### ACTIVATE_FIRMWARE
@@ -1425,7 +1646,43 @@
14251646 | count | u32 | Number of image_ids to activate. Item count of image_ids array parameter |
14261647 | mcu_image_size | u32 | Size of MCU image, if included in the activation |
14271648 | image_ids | Array of u8[4] | Array of Image ids in little-endian format |
1428-
1649+| flags | u32 | Optional flags (see below). Caliptra runtime 2.1.1+ only. |
1650+
1651+
1652+*Flags*
1653+
1654+| **Bit** | **Name** | **Description** |
1655+| ------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------ |
1656+| 0 | `INITIAL_ACTIVATE` | First-time MCU activation after the encrypted-boot flow. Caliptra runtime 2.1.1+ only. See below. |
1657+
1658+
1659+Unknown flag bits are rejected with `RUNTIME_MAILBOX_INVALID_PARAMS`.
1660+
1661+`INITIAL_ACTIVATE` is used exclusively by MCU ROM at the tail of the
1662+`EncryptedFirmware` boot flow. MCU ROM has already loaded firmware into MCU
1663+SRAM via `RI_DOWNLOAD_ENCRYPTED_FIRMWARE` and decrypted it in place via
1664+`CM_AES_GCM_DECRYPT_DMA`. When this flag is set, Caliptra Runtime:
1665+
1666+- Skips the hitless-update steps (set `RESET_REASON.FwHitlessUpd`, clear
1667+ `FW_EXEC_CTRL`, wait for MCU reset request and reset assertion, DMA-reload
1668+ from staging, re-`AuthorizeAndStash`).
1669+- Just publishes `FW_EXEC_CTRL[MCU]` (and any other requested bits) so that
1670+ MCI's `BOOT_RST_MCU` state releases MCU from reset on the next warm reset
1671+ that MCU ROM triggers.
1672+
1673+Caliptra Runtime only honors `INITIAL_ACTIVATE` when **all** of the following
1674+are true; otherwise the command fails with `IMAGE_VERIFIER_ACTIVATION_FAILED`:
1675+
1676+1. The MCU image bit is included in the activation request.
1677+2. The boot mode set by ROM is `EncryptedFirmware` (i.e., ROM received
1678+ `RI_DOWNLOAD_ENCRYPTED_FIRMWARE`).
1679+3. `FW_EXEC_CTRL[MCU]` is currently `0` — this is an initial activation,
1680+ not a hitless update masquerading as one.
1681+
1682+Together, these checks ensure that the MCU SRAM contents are
1683+integrity-protected end-to-end (ciphertext digest verified during recovery;
1684+GCM tag verified during `CM_AES_GCM_DECRYPT_DMA`) before Caliptra releases
1685+MCU to execute them.
14291686
14301687 *Table: `ACTIVATE_FIRMWARE` output arguments*
14311688
@@ -1434,6 +1691,28 @@
14341691 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
14351692 | fips_status | u32 | Indicates if the command is FIPS approved or an error. |
14361693
1694+
1695+## Mailbox commands: OCP LOCK v1.0
1696+
1697+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).
1698+
1699+### ENUMERATE_HPKE_HANDLES
1700+### REPORT_HEK_METADATA
1701+### GET_ALGORITHMS
1702+### INITIALIZE_MEK_SECRET
1703+### ROTATE_HPKE_KEY
1704+### GENERATE_MEK
1705+### GENERATE_MPK
1706+### REWRAP_MPK
1707+### ENABLE_MPK
1708+### MIX_MPK
1709+### GET_HPKE_PUB_KEY
1710+### TEST_ACCESS_KEY
1711+### GET_STATUS
1712+### CLEAR_KEY_CACHE
1713+### UNLOAD_MEK
1714+### LOAD_MEK
1715+### DERIVE_MEK
14371716
14381717 ## Mailbox commands: Cryptographic Mailbox (2.0)
14391718
@@ -1537,6 +1816,99 @@
15371816 | fips_status | u32 | FIPS approved or an error |
15381817 | hash size | u32 ||
15391818 | hash | u8[hash size] ||
1819+
1820+
1821+### CM\_SHAKE256\_INIT
1822+
1823+This starts the computation of a SHAKE256 extendable-output hash, which may be larger than a single mailbox command allows.
1824+
1825+**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.
1826+
1827+The sequence to use these are:
1828+* 1 `CM_SHAKE256_INIT` command
1829+* 0 or more `CM_SHAKE256_UPDATE` commands
1830+* 1 `CM_SHAKE256_FINAL` command
1831+
1832+For each command, the context from the previous command's output must be passed as an input.
1833+
1834+The `SHAKE256_CONTEXT_SIZE` is always exactly 44 bytes long (encrypted session token).
1835+
1836+The maximum supported input data size per command is 4096 bytes.
1837+
1838+Command Code: `0x434D_5849` ("CMXI")
1839+
1840+*Table: `CM_SHAKE256_INIT` input arguments*
1841+
1842+| **Name** | **Type** | **Description** |
1843+| --------- | ------------- | --------------- |
1844+| chksum | u32 ||
1845+| data size | u32 ||
1846+| data | u8[data size] | Data to hash |
1847+
1848+
1849+*Table: `CM_SHAKE256_INIT` output arguments*
1850+
1851+| **Name** | **Type** | **Description** |
1852+| ----------- | ------------------------- | -------------------------------------------------- |
1853+| chksum | u32 ||
1854+| fips_status | u32 | FIPS approved or an error |
1855+| context | u8[SHAKE256_CONTEXT_SIZE] | Passed to `CM_SHAKE256_UPDATE` / `CM_SHAKE256_FINAL` |
1856+
1857+
1858+### CM\_SHAKE256\_UPDATE
1859+
1860+This continues a SHAKE256 computation started by `CM_SHAKE256_INIT` or from another `CM_SHAKE256_UPDATE`.
1861+
1862+The context MUST be passed in from `CM_SHAKE256_INIT` or `CM_SHAKE256_UPDATE`.
1863+
1864+Command Code: `0x434D_5855` ("CMXU")
1865+
1866+*Table: `CM_SHAKE256_UPDATE` input arguments*
1867+
1868+| **Name** | **Type** | **Description** |
1869+| --------- | ------------------------- | ---------------------------------------------------- |
1870+| chksum | u32 ||
1871+| context | u8[SHAKE256_CONTEXT_SIZE] | From `CM_SHAKE256_INIT` / `CM_SHAKE256_UPDATE` |
1872+| data size | u32 ||
1873+| data | u8[data size] | Data to hash |
1874+
1875+
1876+*Table: `CM_SHAKE256_UPDATE` output arguments*
1877+
1878+| **Name** | **Type** | **Description** |
1879+| ----------- | ------------------------- | -------------------------------------------------- |
1880+| chksum | u32 ||
1881+| fips_status | u32 | FIPS approved or an error |
1882+| context | u8[SHAKE256_CONTEXT_SIZE] | Passed to `CM_SHAKE256_UPDATE` / `CM_SHAKE256_FINAL` |
1883+
1884+
1885+### CM\_SHAKE256\_FINAL
1886+
1887+This finalizes the SHAKE256 computation and produces the hash of all of the data.
1888+
1889+The context MUST be passed in from `CM_SHAKE256_INIT` or `CM_SHAKE256_UPDATE`.
1890+
1891+The output is always a 64-byte SHAKE256 digest.
1892+
1893+Command Code: `0x434D_5846` ("CMXF")
1894+
1895+*Table: `CM_SHAKE256_FINAL` input arguments*
1896+
1897+| **Name** | **Type** | **Description** |
1898+| ----------- | ------------------------- | ---------------------------------------------- |
1899+| chksum | u32 ||
1900+| context | u8[SHAKE256_CONTEXT_SIZE] | From `CM_SHAKE256_INIT` / `CM_SHAKE256_UPDATE` |
1901+| data size | u32 | May be 0 |
1902+| data | u8[data size] | Data to hash |
1903+
1904+
1905+*Table: `CM_SHAKE256_FINAL` output arguments*
1906+
1907+| **Name** | **Type** | **Description** |
1908+| ----------- | -------- | ------------------------- |
1909+| chksum | u32 ||
1910+| fips_status | u32 | FIPS approved or an error |
1911+| hash | u8[64] | SHAKE256 digest |
15401912
15411913
15421914 ### CM\_HMAC
@@ -1779,7 +2151,7 @@
17792151
17802152 The signature consists of its `r` and `s` values described in [FIPS 186-5](https://csrc.nist.gov/pubs/fips/186-5/final) encoded in big-endian byte order.
17812153
1782-Command Code: `0x434D_5D53` ("CMES")
2154+Command Code: `0x434D_4553` ("CMES")
17832155
17842156 *Table: `CM_ECDSA_SIGN` input arguments*
17852157 | **Name** | **Type** | **Description** |
@@ -1827,6 +2199,79 @@
18272199 | fips_status | u32 | FIPS approved or an error |
18282200
18292201
2202+### CM_MLKEM_KEY_GEN
2203+
2204+Generates an ML-KEM-1024 encapsulation key from the seed (seed\_d || seed\_z, 64 bytes) stored in a CMK with key usage `Mlkem`.
2205+
2206+The key generation algorithm is described in [FIPS 203](https://csrc.nist.gov/pubs/fips/203/final).
2207+
2208+Command Code: `0x434D_4C4B` ("CMLK")
2209+
2210+*Table: `CM_MLKEM_KEY_GEN` input arguments*
2211+| **Name** | **Type** | **Description** |
2212+| -------- | -------- | ---------------------------------------- |
2213+| chksum | u32 ||
2214+| CMK | CMK | ML-KEM seed (seed\_d &#124;&#124; seed\_z) |
2215+
2216+
2217+*Table: `CM_MLKEM_KEY_GEN` output arguments*
2218+| **Name** | **Type** | **Description** |
2219+| ----------- | -------- | ---------------------------------------- |
2220+| chksum | u32 ||
2221+| fips_status | u32 | FIPS approved or an error |
2222+| encaps_key | u8[1568] | ML-KEM-1024 encapsulation key |
2223+
2224+
2225+### CM_MLKEM_ENCAPSULATE
2226+
2227+Performs ML-KEM-1024 encapsulation against the provided encapsulation key, producing a ciphertext and a shared key wrapped as a CMK.
2228+
2229+The encapsulation algorithm is described in [FIPS 203](https://csrc.nist.gov/pubs/fips/203/final).
2230+
2231+Command Code: `0x434D_4C45` ("CMLE")
2232+
2233+*Table: `CM_MLKEM_ENCAPSULATE` input arguments*
2234+| **Name** | **Type** | **Description** |
2235+| ----------- | -------- | ---------------------------------------- |
2236+| chksum | u32 ||
2237+| key_usage | u32 | Key usage for the output CMK |
2238+| encaps_key | u8[1568] | ML-KEM-1024 encapsulation key |
2239+
2240+
2241+*Table: `CM_MLKEM_ENCAPSULATE` output arguments*
2242+| **Name** | **Type** | **Description** |
2243+| ----------- | -------- | ---------------------------------------- |
2244+| chksum | u32 ||
2245+| fips_status | u32 | FIPS approved or an error |
2246+| ciphertext | u8[1568] | ML-KEM-1024 ciphertext |
2247+| shared_key | CMK | CMK of the shared secret key |
2248+
2249+
2250+### CM_MLKEM_DECAPSULATE
2251+
2252+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.
2253+
2254+The decapsulation algorithm is described in [FIPS 203](https://csrc.nist.gov/pubs/fips/203/final).
2255+
2256+Command Code: `0x434D_4C44` ("CMLD")
2257+
2258+*Table: `CM_MLKEM_DECAPSULATE` input arguments*
2259+| **Name** | **Type** | **Description** |
2260+| ----------- | -------- | ---------------------------------------- |
2261+| chksum | u32 ||
2262+| key_usage | u32 | Key usage for the output CMK |
2263+| CMK | CMK | ML-KEM seed (seed\_d &#124;&#124; seed\_z) |
2264+| ciphertext | u8[1568] | ML-KEM-1024 ciphertext to decapsulate |
2265+
2266+
2267+*Table: `CM_MLKEM_DECAPSULATE` output arguments*
2268+| **Name** | **Type** | **Description** |
2269+| ----------- | -------- | ---------------------------------------- |
2270+| chksum | u32 ||
2271+| fips_status | u32 | FIPS approved or an error |
2272+| shared_key | CMK | CMK of the shared secret key |
2273+
2274+
18302275 ### CM_AES_ENCRYPT_INIT
18312276
18322277 Generic AES operation for unauthenticated AES operations.
@@ -1839,7 +2284,7 @@
18392284
18402285 The CMK must have been created for AES usage.
18412286
1842-Command Code: `0x434D_4349` ("CMCI")
2287+Command Code: `0x434D_4149` ("CMAI")
18432288
18442289 *Table: `CM_AES_ENCRYPT_INIT` input arguments*
18452290 | **Name** | **Type** | **Description** |
@@ -1873,8 +2318,7 @@
18732318 | mode | u32 ||
18742319 | key | u8[32] ||
18752320 | iv | u8[16] ||
1876-| fips_status | u8 | 1 = FIPS valid |
1877-| reserved | u8[75] | Reserved for additional fields |
2321+| reserved | u8[76] | Reserved for additional fields |
18782322
18792323
18802324 The size of the (encrypted) context is always exactly 156 bytes,
@@ -1891,7 +2335,7 @@
18912335 For CBC, the size must be a multiple of 16 bytes.
18922336 CTR mode supports input of any size up to the maximum cryptographic mailbox size.
18932337
1894-Command Code: `0x434D_4355` ("CMCU")
2338+Command Code: `0x434D_4155` ("CMAU")
18952339
18962340 *Table: `CM_AES_ENCRYPT_UPDATE` input arguments*
18972341 | **Name** | **Type** | **Description** |
@@ -1962,7 +2406,7 @@
19622406 For CBC, the size must be a multiple of 16 bytes.
19632407 CTR mode supports input of any size up to the maximum cryptographic mailbox size.
19642408
1965-Command Code: `0x434D_4155` ("CMAU")
2409+Command Code: `0x434D_4156` ("CMAV")
19662410
19672411 *Table: `CM_AES_DECRYPT_UPDATE` input arguments*
19682412 | **Name** | **Type** | **Description** |
@@ -2023,8 +2467,7 @@
20232467 | GHASH state | u8[16] ||
20242468 | current length | u32 | value mod 16 is buffer size |
20252469 | buffer | u8[16] ||
2026-| fips_status | u8 | 1 = FIPS valid |
2027-| reserved | u8[15] ||
2470+| reserved | u8[16] ||
20282471
20292472
20302473 The size of the (encrypted) context is always exactly 128 bytes,
@@ -2180,7 +2623,7 @@
21802623
21812624 The encrypted and authenticated context's internal structure will be the same as for encryption.
21822625
2183-### CM_AES_SPDM_GCM_DECRYPT_INIT
2626+### CM_AES_GCM_SPDM_DECRYPT_INIT
21842627
21852628 Starts an AES-256-GCM decryption computation in SPDM mode.
21862629
@@ -2296,6 +2739,45 @@
22962739 | plaintext | u8[plaintext size] ||
22972740
22982741
2742+### CM_AES_GCM_DECRYPT_DMA
2743+
2744+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.
2745+
2746+**Important restrictions:**
2747+- This command is only available in subsystem mode, as DMA is only available in subsystem.
2748+- This command is only available for MCU.
2749+- 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.
2750+- The command performs a two-pass operation:
2751+ 1. First pass: Verifies the SHA384 hash of the encrypted data at the AXI address
2752+ 2. Second pass: Performs in-place AES-GCM decryption via DMA
2753+
2754+The CMK must be an AES key (key usage = 3) that was previously imported using `CM_IMPORT`.
2755+
2756+Command Code: `0x434D_4444` ("CMDD")
2757+
2758+*Table: `CM_AES_GCM_DECRYPT_DMA` input arguments*
2759+| **Name** | **Type** | **Description** |
2760+| --------------------- | --------- | ---------------------------------------------------- |
2761+| chksum | u32 | Checksum over other input arguments |
2762+| cmk | CMK | Encrypted CMK containing the AES-256 key |
2763+| iv | u32[3] | AES-GCM initialization vector (12 bytes) |
2764+| tag | u32[4] | AES-GCM authentication tag (16 bytes) |
2765+| encrypted_data_sha384 | u8[48] | SHA384 hash of the encrypted data for verification |
2766+| axi_addr_lo | u32 | Lower 32 bits of the AXI address |
2767+| axi_addr_hi | u32 | Upper 32 bits of the AXI address |
2768+| length | u32 | Length of data to decrypt in bytes |
2769+| aad_length | u32 | Length of AAD in bytes (0-4095) |
2770+| aad | u8[...] | Additional authenticated data |
2771+
2772+
2773+*Table: `CM_AES_GCM_DECRYPT_DMA` output arguments*
2774+| **Name** | **Type** | **Description** |
2775+| ------------ | -------- | ----------------------------------------------------- |
2776+| chksum | u32 | Checksum over other output arguments |
2777+| fips_status | u32 | FIPS approved or an error |
2778+| tag_verified | u32 | 1 if GCM tag verification succeeded, 0 if it failed |
2779+
2780+
22992781 ### CM_ECDH_GENERATE
23002782
23012783 This computes the first half of an Elliptic Curve Diffie-Hellman exchange to compute an ephemeral shared key pair with another party.
@@ -2414,9 +2896,9 @@
24142896 ### CM\_DERIVE\_STABLE\_KEY
24152897
24162898 Derives an HMAC key that has a stable value across resets from either
2417-IDevId or LDevId.
2418-
2419-The (interior) value of the returned CMK will be the stable across resets as it is derived indirectly from the IDevId or LDevId CDIs.
2899+IDevId, LDevId, or the Owner Root Key (derived from HEK seed).
2900+
2901+The (interior) value of the returned CMK will be the stable across resets as it is derived indirectly from the IDevId or LDevId CDIs, or from the HEK-seed-derived Owner Root Key.
24202902 The actual encrypted bytes of the CMK will *not* be the same, and
24212903 the encrypted CMK itself cannot be used across resets. So, the key
24222904 will always need to be re-derived after every *cold* reset.
@@ -2424,26 +2906,36 @@
24242906 If a key usage other than HMAC is desired, then the KDF or HKDF
24252907 mailbox functions can be used to derive a key from the returned CMK.
24262908
2427-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.
2909+`key_type = OwnerKey` is only available in subsystem mode when the Stable Owner
2910+Key strap is enabled (`SS_STRAP_GENERIC[3]` bit 0 set to 1) and OCP LOCK is not
2911+enabled. If these requirements are not met, the command fails with
2912+`CMB_STABLE_OWNER_KEY_NOT_AVAILABLE`.
2913+
2914+For `OwnerKey`, this command derives from the ROM-populated Stable Owner Root
2915+Key. It first runs AES-256-CMAC KDF with `info` as the input data to produce an
2916+intermediate key, then runs HMAC-SHA512 KDF with `b"Stable Owner Key" || info`
2917+as the domain-separation input to produce the returned 64-byte HMAC key
2918+material. Caliptra wraps that key material as an encrypted CMK before returning
2919+it to the caller.
24282920
24292921 The command derivation is summarized below:
24302922
24312923 ![CM_DERIVE_STABLE_KEY Derivation](../images/caliptra-sw/runtime/../rom/dev/doc/svg/cm-derive-stable-key.svg)
24322924
2433-Command Code: `0x434D_4453` ("CMDS")
2925+Command Code: `0x494D_4453` ("IMDS")
24342926
24352927 *Table: `CM_DERIVE_STABLE_KEY` input arguments*
24362928
2437-| **Name** | **Type** | **Description**
2438-| -------- | -------- | ---------------
2929+| **Name** | **Type** | **Description** |
2930+| -------- | -------- | --------------- |
24392931 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
2440-| key_type | u32 | Source key to derive the stable key from. **0x0000_0001:** IDevId <br> **0x0000_0002:** LDevId |
2932+| key_type | u32 | Source key to derive the stable key from. **0x0000_0001:** IDevId <br> **0x0000_0002:** LDevId <br> **0x0000_0003:** OwnerKey (derived from HEK seed) |
24412933 | info | u8[32] | Data to use in the key derivation. |
24422934
24432935
24442936 *Table: `CM_DERIVE_STABLE_KEY` output arguments*
2445-| **Name** | **Type** | **Description**
2446-| -------- | -------- | ---------------
2937+| **Name** | **Type** | **Description** |
2938+| -------- | -------- | --------------- |
24472939 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
24482940 | cmk | CMK | CMK that stores the stable key material |
24492941
@@ -2453,9 +2945,6 @@
24532945 Imports the specified key and returns a CMK for it.
24542946
24552947 Usage information is required so that the key can be verified and used appropriately.
2456-
2457-Note that it is the caller's responsibility to ensure that the source
2458-key material meets FIPS requirements, such as zeroization.
24592948
24602949 Command Code: `0x434D_494D` ("CMIM")
24612950
@@ -2540,14 +3029,14 @@
25403029
25413030 *Table: `GET_IDEV_ECC384_CSR` input arguments*
25423031
2543-| **Name** | **Type** | **Description**
2544-| -------- | -------- | ---------------
3032+| **Name** | **Type** | **Description** |
3033+| -------- | -------- | --------------- |
25453034 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
25463035
25473036
25483037 *Table: `GET_IDEV_ECC384_CSR` output arguments*
2549-| **Name** | **Type** | **Description**
2550-| -------- | -------- | ---------------
3038+| **Name** | **Type** | **Description** |
3039+| -------- | -------- | --------------- |
25513040 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
25523041 | data\_size | u32 | Length in bytes of the valid data in the data field. |
25533042 | data | u8[...] | DER-encoded ECC384 IDevID certificate signing request. |
@@ -2559,14 +3048,14 @@
25593048
25603049 *Table: `GET_IDEV_MLDSA87_CSR` input arguments*
25613050
2562-| **Name** | **Type** | **Description**
2563-| -------- | -------- | ---------------
3051+| **Name** | **Type** | **Description** |
3052+| -------- | -------- | --------------- |
25643053 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
25653054
25663055
25673056 *Table: `GET_IDEV_MLDSA87_CSR` output arguments*
2568-| **Name** | **Type** | **Description**
2569-| -------- | -------- | ---------------
3057+| **Name** | **Type** | **Description** |
3058+| -------- | -------- | --------------- |
25703059 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
25713060 | data\_size | u32 | Length in bytes of the valid data in the data field. |
25723061 | data | u8[...] | DER-encoded MLDSA87 IDevID certificate signing request. |
@@ -2586,14 +3075,14 @@
25863075
25873076 *Table: `GET_FMC_ALIAS_ECC384_CSR` input arguments*
25883077
2589-| **Name** | **Type** | **Description**
2590-| -------- | -------- | ---------------
3078+| **Name** | **Type** | **Description** |
3079+| -------- | -------- | --------------- |
25913080 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
25923081
25933082
25943083 *Table: `GET_FMC_ALIAS_ECC384_CSR` output arguments*
2595-| **Name** | **Type** | **Description**
2596-| -------- | -------- | ---------------
3084+| **Name** | **Type** | **Description** |
3085+| -------- | -------- | --------------- |
25973086 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
25983087 | data\_size | u32 | Length in bytes of the valid data in the data field. |
25993088 | data | u8[...] | DER-encoded ECC384 FMC Alias certificate signing request. |
@@ -2605,14 +3094,14 @@
26053094
26063095 *Table: `GET_FMC_ALIAS_MLDSA87_CSR` input arguments*
26073096
2608-| **Name** | **Type** | **Description**
2609-| -------- | -------- | ---------------
3097+| **Name** | **Type** | **Description** |
3098+| -------- | -------- | --------------- |
26103099 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
26113100
26123101
26133102 *Table: `GET_FMC_ALIAS_MLDSA87_CSR` output arguments*
2614-| **Name** | **Type** | **Description**
2615-| -------- | -------- | ---------------
3103+| **Name** | **Type** | **Description** |
3104+| -------- | -------- | --------------- |
26163105 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
26173106 | data\_size | u32 | Length in bytes of the valid data in the data field. |
26183107 | data | u8[...] | DER-encoded MLDSA87 FMC Alias certificate signing request. |
@@ -2626,8 +3115,8 @@
26263115
26273116 *Table: `GET_ATTESTED_ECC384_CSR` input arguments*
26283117
2629-| **Name** | **Type** | **Description**
2630-| -------- | -------- | ---------------
3118+| **Name** | **Type** | **Description** |
3119+| -------- | -------- | --------------- |
26313120 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
26323121 | key_id | u32 | Key ID for which CSR is requested.<br> **0x0000_0001:** LDevId <br> **0x0000_0002:** FMC Alias <br> **0x0000_0003:** RT Alias |
26333122 | nonce | u8[32] | Nonce to be included in the CSR EAT. |
@@ -2635,8 +3124,8 @@
26353124
26363125 *Table: `GET_ATTESTED_ECC384_CSR` output arguments*
26373126
2638-| **Name** | **Type** | **Description**
2639-| -------- | -------- | ---------------
3127+| **Name** | **Type** | **Description** |
3128+| -------- | -------- | --------------- |
26403129 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
26413130 | data\_size | u32 | Length in bytes of the valid data in the data field. |
26423131 | data | u8[...] | DER-encoded ECC384 attested certificate signing request. |
@@ -2650,8 +3139,8 @@
26503139
26513140 *Table: `GET_ATTESTED_MLDSA87_CSR` input arguments*
26523141
2653-| **Name** | **Type** | **Description**
2654-| -------- | -------- | ---------------
3142+| **Name** | **Type** | **Description** |
3143+| -------- | -------- | --------------- |
26553144 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
26563145 | key_id | u32 | Key ID for which CSR is requested.<br> **0x0000_0001:** LDevId <br> **0x0000_0002:** FMC Alias <br> **0x0000_0003:** RT Alias |
26573146 | nonce | u8[32] | Nonce to be included in the CSR EAT. |
@@ -2659,8 +3148,8 @@
26593148
26603149 *Table: `GET_ATTESTED_MLDSA87_CSR` output arguments*
26613150
2662-| **Name** | **Type** | **Description**
2663-| -------- | -------- | ---------------
3151+| **Name** | **Type** | **Description** |
3152+| -------- | -------- | --------------- |
26643153 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
26653154 | data\_size | u32 | Length in bytes of the valid data in the data field. |
26663155 | data | u8[...] | DER-encoded MLDSA87 attested certificate signing request. |
@@ -2674,23 +3163,57 @@
26743163
26753164 *Table: `SIGN_WITH_EXPORTED_ECDSA` input arguments*
26763165
2677-| **Name** | **Type** | **Description**
2678-| -------- | -------- | ---------------
3166+| **Name** | **Type** | **Description** |
3167+| -------- | -------- | --------------- |
26793168 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
2680-| exported_cdi_handle | u8[32] | The Exported CDI handle returned by the DPE `DeriveContext` command. Little endian. |
2681-| tbs | u8[48] | The bytes to be signed. Little endian. |
3169+| exported_cdi_handle | u8[32] | The exported CDI handle returned by the DPE `DeriveContext` command. Opaque byte array; copy the bytes exactly as returned. |
3170+| tbs | u8[48] | The 48-byte SHA-384 digest to be signed. Raw byte array; no byte swapping is required. |
26823171
26833172
26843173 *Table: `SIGN_WITH_EXPORTED_ECDSA` output arguments*
2685-| **Name** | **Type** | **Description**
2686-| -------- | -------- | ---------------
3174+| **Name** | **Type** | **Description** |
3175+| -------- | -------- | --------------- |
26873176 | derived_pubkey_x | u8[48] | The X BigNum of the ECDSA public key associated with the signing key. |
26883177 | derived_pubkey_y | u8[48] | The Y BigNum of the ECDSA public key associated with the signing key. |
26893178 | signature_r | u8[48] | The R BigNum of an ECDSA signature. |
26903179 | signature_s | u8[48] | The S BigNum of an ECDSA signature. |
26913180
26923181
2693-The `exported_cdi` can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
3182+The `exported_cdi_handle` can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
3183+
3184+### SIGN\_WITH\_EXPORTED\_MLDSA
3185+
3186+Command Code: `0x5357_4D4C` ("SWML")
3187+
3188+**Note**: This command is only available in the locality of the PL0 PAUSER.
3189+
3190+*Table: `SIGN_WITH_EXPORTED_MLDSA` input arguments*
3191+
3192+| **Name** | **Type** | **Description** |
3193+| -------- | -------- | --------------- |
3194+| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
3195+| exported_cdi_handle | u8[32] | The exported CDI handle returned by the DPE `DeriveContext` command. Opaque byte array; copy the bytes exactly as returned. |
3196+| sign_type | u32 | Signing mode selector. `0` = `Mu` (64-byte pre-hash input), `1` = `Raw` (arbitrary byte array input). |
3197+| tbs_size | u32 | Length of the message to be signed. For `Mu`, this must be exactly 64 bytes. For `Raw`, this may be up to 1024 bytes. |
3198+| tbs | u8[1024] | The message bytes to be signed. For `Mu`, this field contains a 64-byte message digest. For `Raw`, it contains the raw input bytes to sign. |
3199+
3200+
3201+*Table: `SIGN_WITH_EXPORTED_MLDSA` output arguments*
3202+
3203+| **Name** | **Type** | **Description** |
3204+| -------- | -------- | --------------- |
3205+| derived_pubkey | u8[2592] | The ML-DSA public key derived from the exported CDI handle and the DPE environment. |
3206+| signature | u8[4627] | The ML-DSA signature produced by the derived key. |
3207+
3208+
3209+The `exported_cdi_handle` can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
3210+
3211+This command derives an ML-DSA key pair from the provided exported CDI handle and signs either:
3212+
3213+- a 64-byte `Mu` message digest, or
3214+- a `Raw` message payload of up to 1024 bytes.
3215+
3216+The command performs the signing under PL0-only access control and returns the derived public key together with the signature.
26943217
26953218 ### REVOKE\_EXPORTED\_CDI\_HANDLE
26963219
@@ -2700,16 +3223,47 @@
27003223
27013224 *Table: `REVOKE_EXPORTED_CDI_HANDLE` input arguments*
27023225
2703-| **Name** | **Type** | **Description**
2704-| -------- | -------- | ---------------
3226+| **Name** | **Type** | **Description** |
3227+| -------- | -------- | --------------- |
27053228 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
2706-| exported_cdi_handle | u8[32] | The Exported CDI handle returned by the DPE `DeriveContext` command. Little endian. |
2707-
2708-
2709-The `exported_cdi` can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
3229+| exported_cdi_handle | u8[32] | The exported CDI handle returned by the DPE `DeriveContext` command. Opaque byte array; copy the bytes exactly as returned. |
3230+
3231+
3232+The `exported_cdi_handle` can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
27103233
27113234 The `exported_cdi_handle` is no longer usable after calling `REVOKE_EXPORTED_CDI_HANDLE` with it. After the `exported_cdi_handle`
2712-has been revoked, a new exported CDI can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
3235+has been revoked, a new exported CDI handle can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
3236+
3237+### EXTERNAL_MAILBOX_CMD
3238+
3239+Command Code: `0x4558_544D` ("EXTM")
3240+
3241+**Important restrictions:**
3242+- This command is only available in subsystem mode in 2.1+.
3243+- This command is only available for MCU.
3244+
3245+Executes a mailbox command located at an AXI address.
3246+This allows for executing mailbox commands that are larger than the mailbox allows.
3247+
3248+This is currently mostly useful for FIRMWARE_LOAD (as part of an update) or SET_AUTH_MANIFEST.
3249+
3250+The response is still written to the mailbox.
3251+
3252+The checksum is over the EXTM command, *not* the command that is loaded over AXI.
3253+That external command will still need its own checksum, if applicable.
3254+
3255+*Table: `EXTERNAL_MAILBOX_CMD` input arguments*
3256+
3257+| **Name** | **Type** | **Description** |
3258+| -------- | -------- | --------------- |
3259+| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
3260+| command_id | u32 | Command ID for the mailbox command to be executed. Little endian. |
3261+| command_size | u32 | Size of the mailbox command to be executed. Little endian. |
3262+| axi_address_low | u32 | Lower 32 bits of the AXI address that contains the mailbox command. Little endian. |
3263+| axi_address_high | u32 | High 32 bits of the AXI address that contains the mailbox command. Little endian. |
3264+
3265+
3266+The response will be the response of the executed external command.
27133267
27143268 ### REALLOCATE\_DPE\_CONTEXT\_LIMITS
27153269
@@ -2719,24 +3273,119 @@
27193273
27203274 *Table: `REALLOCATE_DPE_CONTEXT_LIMITS` input arguments*
27213275
2722-| **Name** | **Type** | **Description**
2723-| -------- | -------- | ---------------
3276+| **Name** | **Type** | **Description** |
3277+| -------- | -------- | --------------- |
27243278 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
27253279 | pl0_context_limit | u32 | Number of contexts to allocate to PL0. PL1 will receive remaining contexts. |
27263280
27273281
27283282 *Table: `REALLOCATE_DPE_CONTEXT_LIMITS` output arguments*
2729-| **Name** | **Type** | **Description**
2730-| -------- | -------- | ---------------
3283+| **Name** | **Type** | **Description** |
3284+| -------- | -------- | --------------- |
27313285 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
27323286 | fips_status | u32 | Indicates if the command is FIPS approved or an error. |
27333287 | new_pl0_context_limit | u32 | Number of contexts assigned to PL0 after the reallocation |
27343288 | new_pl1_context_limit | u32 | Number of contexts assigned to PL1 after the reallocation |
27353289
27363290
2737-This allows the user to reallocate the 32 DPE contexts between PL0 and PL1. By default, each gets 16 contexts.
3291+This allows the user to reallocate the 64 DPE contexts between PL0 and PL1. By default, each gets 32 contexts.
27383292
27393293 **Note**: 2 PL0 contexts are used by Caliptra itself during initialization.
3294+
3295+### FE\_PROG
3296+
3297+Programs Field Entropy (FE) into one of 4 FE partitions in the OTP fuse controller. This command
3298+is typically used during device provisioning flows.
3299+
3300+**Note**: This command is only available when the device is in the **Production** lifecycle state.
3301+
3302+Command Code: `0x4645_5052` ("FEPR")
3303+
3304+*Table: `FE_PROG` input arguments*
3305+
3306+| **Name** | **Type** | **Description**
3307+| -------- | -------- | ---------------
3308+| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian.
3309+| partition | u32 | FE partition number (valid values: 0–3).
3310+
3311+`FE_PROG` returns no output arguments other than the mailbox response header.
3312+
3313+### PRODUCTION\_AUTH\_DEBUG\_UNLOCK\_REQ
3314+
3315+Initiates the production debug unlock flow by generating a cryptographic challenge. The caller
3316+must solve the challenge by signing it with the appropriate ECC and MLDSA keys and returning
3317+the result via the [`PRODUCTION_AUTH_DEBUG_UNLOCK_TOKEN`](#production_auth_debug_unlock_token)
3318+command.
3319+
3320+This command performs the same function as the ROM's `AUTH_DEBUG_UNLOCK_REQ` command
3321+(documented in the [ROM README](../rom/dev/README.md#debug-unlock)), but is available at
3322+runtime.
3323+
3324+**Note**: This command requires the device to be in the **Production** lifecycle state and the
3325+`PROD_DEBUG_UNLOCK_REQ` bit in the `SS_DBG_MANUF_SERVICE_REG_REQ` register to be set.
3326+
3327+Command Code: `0x5044_5552` ("PDUR")
3328+
3329+*Table: `PRODUCTION_AUTH_DEBUG_UNLOCK_REQ` input arguments*
3330+
3331+| **Name** | **Type** | **Description**
3332+| -------- | -------- | ---------------
3333+| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian.
3334+| length | u32 | Length of the payload in DWORDs.
3335+| unlock\_level | u8 | Debug unlock level (1–8).
3336+| reserved | u8[3] | Reserved.
3337+
3338+*Table: `PRODUCTION_AUTH_DEBUG_UNLOCK_REQ` output arguments*
3339+
3340+| **Name** | **Type** | **Description**
3341+| -------- | -------- | ---------------
3342+| chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian.
3343+| fips\_status | u32 | Indicates if the command is FIPS approved or an error.
3344+| length | u32 | Length of the response payload in DWORDs.
3345+| unique\_device\_identifier | u8[32] | Device identifier of the Caliptra device. Byte array; pass through as-is to the token command.
3346+| challenge | u8[48] | Random challenge number generated by Caliptra. Byte array; pass through as-is to the token command.
3347+
3348+### PRODUCTION\_AUTH\_DEBUG\_UNLOCK\_TOKEN
3349+
3350+Completes the production debug unlock handshake by validating the caller's solution to the
3351+challenge generated by
3352+[`PRODUCTION_AUTH_DEBUG_UNLOCK_REQ`](#production_auth_debug_unlock_req). The caller must
3353+provide the device identifier and challenge from the previous request along with ECC-384 and
3354+ML-DSA-87 signatures proving possession of the authorized debug unlock key.
3355+
3356+Upon successful validation, Caliptra authorizes the debug unlock by setting the unlock level
3357+in the `SS_SOC_DBG_UNLOCK_LEVEL` register.
3358+
3359+This command performs the same function as the ROM's `AUTH_DEBUG_UNLOCK_TOKEN` command
3360+(documented in the [ROM README](../rom/dev/README.md#debug-unlock)), but is available at
3361+runtime.
3362+
3363+**Note**: This command requires a preceding successful `PRODUCTION_AUTH_DEBUG_UNLOCK_REQ` in
3364+the same boot session. The challenge is consumed on use and cannot be replayed.
3365+
3366+Command Code: `0x5044_5554` ("PDUT")
3367+
3368+*Table: `PRODUCTION_AUTH_DEBUG_UNLOCK_TOKEN` input arguments*
3369+
3370+| **Name** | **Type** | **Description**
3371+| -------- | -------- | ---------------
3372+| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian.
3373+| length | u32 | Length of the payload in DWORDs.
3374+| unique\_device\_identifier | u8[32] | Device identifier (must match value from challenge response). Byte array; copied verbatim from the challenge response.
3375+| unlock\_level | u8 | Debug unlock level (1–8, must match the original request).
3376+| reserved | u8[3] | Reserved.
3377+| challenge | u8[48] | Challenge (must match value from challenge response). Byte array; copied verbatim from the challenge response.
3378+| ecc\_public\_key | u8[96] | ECC P-384 public key (X &#124;&#124; Y, 48 bytes each). See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields).
3379+| mldsa\_public\_key | u8[2592] | ML-DSA-87 public key. See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields).
3380+| ecc\_signature | u8[96] | ECC P-384 signature over the SHA2-384 message digest. R (48 bytes) &#124; S (48 bytes). See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields).
3381+| mldsa\_signature | u8[4628] | ML-DSA-87 signature over the SHA2-512 message digest (4627 bytes + 1 reserved byte). See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields).
3382+
3383+The signed message for both ECC and ML-DSA signatures is the hash of the concatenation:
3384+`unique_device_identifier || unlock_level || reserved || challenge` (all as raw bytes).
3385+ECC uses SHA2-384; ML-DSA uses SHA2-512.
3386+
3387+`PRODUCTION_AUTH_DEBUG_UNLOCK_TOKEN` returns no output arguments other than the mailbox
3388+response header.
27403389
27413390 ## Checksum
27423391
@@ -2760,15 +3409,15 @@
27603409
27613410 ## FIPS status
27623411
2763-For every command, the firmware responds with a FIPS status of FIPS approved. There is
2764-currently no use case for any other responses or error values.
3412+For successful commands, the firmware responds with a FIPS status indicating whether the service is FIPS approved. A non-approved status is not a command error.
27653413
27663414 *Table: FIPS status codes*
27673415
27683416 | **Name** | **Value** | Description |
27693417 | --------------- | --------------------------- | --------------------------------------------------- |
27703418 | `FIPS_APPROVED` | `0x0000_0000` | Status of command is FIPS approved |
2771-| `RESERVED` | `0x0000_0001 - 0xFFFF_FFFF` | Other values reserved, will not be sent by Caliptra |
3419+| `FIPS_NOT_APPROVED_USER_SUPPLIED_DIGEST` | `0x5553_5244` | Command is not FIPS approved because the caller supplied the digest instead of the raw message |
3420+| `RESERVED` | `0x0000_0002 - 0xFFFF_FFFF` | Other values reserved, will not be sent by Caliptra |
27723421
27733422
27743423 ## Runtime Firmware updates
@@ -2847,14 +3496,14 @@
28473496 To prevent this, we establish active context limits for each PAUSER
28483497 privilege level:
28493498
2850-* PL0 - 16 active contexts
2851-* PL1 - 16 active contexts
3499+* PL0 - 32 active contexts
3500+* PL1 - 32 active contexts
28523501
28533502 If a DPE command were to activate a new context such that the total number of
28543503 active contexts in a privilege level is above its active context limit, the
28553504 InvokeDpe command should fail.
28563505
2857-At boot Caliptra Runtime FW consumes part of the PL0 active contexts (initially 16) to DeriveContext for:
3506+At boot Caliptra Runtime FW consumes part of the PL0 active contexts (initially 32) to DeriveContext for:
28583507 - RTFW Journey (RTFJ) Measurement (1)
28593508 - Caliptra Configured Initialization Values digest (CCIV) (1)
28603509 - ROM Stashed Measurements (max 8)
@@ -2862,20 +3511,20 @@
28623511 Further, it is not allowed for PL1 to call DeriveContext with the intent to change locality to PL0's locality; this would increase the number
28633512 of active contexts in PL0's locality, and hence allow PL1 to DOS PL0.
28643513
2865-### DPE profile implementation
2866-
2867-The DPE iRoT profile leaves some choices up to implementers. This section
2868-describes specific requirements for the Caliptra DPE implementation.
3514+### Caliptra DPE Profile
3515+
3516+Caliptra defines the **Caliptra DPE Profile**, which inherits from the [OCP DPE iRoT Profile](https://github.com/opencomputeproject/Security/tree/main/specifications/dpe-irot-profile) (`DPE_PROFILE_IROT_P384_SHA384`) with some modifications. This section describes the profile attributes and specific requirements for the Caliptra DPE implementation.
28693517
28703518 | Name | Value | Description |
28713519 | -------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------ |
2872-| Profile Variant | `DPE_PROFILE_IROT_P384_SHA384` | The profile variant that Caliptra implements. |
3520+| Profile Variant | `Caliptra DPE Profile` | Derived from `DPE_PROFILE_IROT_P384_SHA384`. |
28733521 | KDF | SP800-108 HMAC-CTR | KDF to use for CDI (tcg.derive.kdf-sha384) and asymmetric key (tcg.derive.kdf-sha384-p384) derivation. |
28743522 | Simulation Context Support | Yes | Whether Caliptra implements the optional Simulation Contexts feature. |
28753523 | Supports ExtendTci | Yes | Whether Caliptra implements the optional ExtendTci command. |
28763524 | Supports Auto Init | Yes | Whether Caliptra will automatically initialize the default DPE context. |
28773525 | Supports Rotate Context | Yes | Whether Caliptra supports the optional RotateContextHandle command. |
28783526 | CertifyKey Alias Key | Caliptra Runtime Alias Key | The key that will be used to sign certificates that are produced by the DPE CertifyKey command. |
3527+| `export-cdi-format` | KeyVault Slot Handle | Overrides the iRoT profile default (which returns the actual CDI) to return a 32-byte handle to a KeyVault slot instead. |
28793528
28803529
28813530 ### Supported DPE commands
@@ -2886,6 +3535,7 @@
28863535 * InitializeContext
28873536 * DeriveContext
28883537 * **Note**: The "export-cdi" flag is only available in the locality of the PL0 PAUSER.
3538+ * **Note**: The value returned when `export-cdi` is requested is a 32-byte handle to a KeyVault slot containing the CDI, not the actual CDI. This overrides the default iRoT profile behavior.
28893539 * CertifyKey
28903540 * Caliptra DPE supports two formats for CertifyKey: X.509 and PKCS#10 CSR.
28913541 X.509 is only available to PL0 PAUSERs.