Changes to Runtime Specification

Comparing version 2.1 to 2.0
+838 additions -165 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/a32ac08170df3018580f45db2304fea35e3362d0/runtime/README.md" target="_blank">chipsalliance/caliptra-sw/runtime/README.md</a> @ <code>a32ac08</code>
2+📄 Source: <a href="https://github.com/chipsalliance/caliptra-sw/blob/61a20816d836d39f2c97c151bce08dc5e7c199cd/runtime/README.md" target="_blank">chipsalliance/caliptra-sw/runtime/README.md</a> @ <code>61a2081</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. Mailbox commands that look up a firmware ID select exactly one collection through bits `[2:1]` of their `flags` argument.
191212
192213 ### Caliptra-Endorsed Aggregated Measured Boot
193214
@@ -305,7 +326,69 @@
305326 Mailbox user 0xFFFF_FFFF is reserved for Caliptra internal use. All mailbox
306327 commands from that user will fail.
307328
308-### FW\_LOAD
329+### Byte order of cryptographic fields
330+
331+Several mailbox commands include ECC P-384 and ML-DSA-87 public keys,
332+signatures, and SHA digest values stored as `[u32]` arrays.
333+The "big endian" / "little endian" labels in individual command tables describe
334+how the **standard byte representation** produced by cryptographic
335+tools maps to those `u32` words.
336+
337+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.
338+
339+#### ECC P-384 fields (big-endian words)
340+
341+Each 4-byte group from the standard representation is byte-reversed on the
342+wire.
343+
344+Example — suppose OpenSSL produces a 48-byte X coordinate starting with:
345+
346+```
347+OpenSSL raw bytes: AB CD EF 01 23 45 67 89 ...
348+ ~~~~~~~~~~~ ~~~~~~~~~~~
349+Mailbox bytes: 01 EF CD AB 89 67 45 23 ...
350+```
351+
352+In other words: split the tool output into 4-byte groups, then reverse each
353+group.
354+
355+#### ML-DSA-87 fields (little-endian words)
356+
357+No conversion is needed. Copy the raw bytes produced by an ML-DSA-87
358+implementation (e.g., OpenSSL 3.5+, the `fips204` crate, or the NIST reference
359+implementation) directly into the mailbox buffer.
360+
361+```
362+openssl pkey output: AB CD EF 01 23 45 67 89 ...
363+Mailbox bytes: AB CD EF 01 23 45 67 89 ... (identical)
364+```
365+
366+#### SHA digest fields (big-endian words)
367+
368+Hash digests stored as `u32[N]` arrays use the same big-endian word convention
369+as ECC fields. Each 4-byte group of the standard hash output is byte-reversed
370+on the wire.
371+
372+Example — suppose `openssl dgst -sha384` produces a digest starting with:
373+
374+```
375+openssl output: A1 B2 C3 D4 E5 F6 07 18 ...
376+ ~~~~~~~~~~~ ~~~~~~~~~~~
377+Mailbox u32[12]: D4 C3 B2 A1 18 07 F6 E5 ...
378+```
379+
380+#### u8 byte-array fields (no conversion needed)
381+
382+When ECC P-384 keys, signatures, or SHA digests are declared as `u8[48]` (rather
383+than `u32[12]`), they use standard big-endian byte order — the same format
384+produced by OpenSSL and other cryptographic tools. No byte-swapping is required.
385+
386+For example, the `ECDSA384_SIGNATURE_VERIFY` input fields (`pub_key_x`,
387+`pub_key_y`, `signature_r`, `signature_s`, `hash`) and the `QUOTE_PCRS_ECC384`
388+output fields (`digest`, `signature_r`, `signature_s`) can be used directly with
389+`openssl` or OpenSSL's `BN_bin2bn()` without any conversion.
390+
391+### FIRMWARE\_LOAD
309392
310393 The `FIRMWARE_LOAD` command is handled by both ROM and Runtime Firmware.
311394
@@ -369,7 +452,14 @@
369452 | -------- | -------- | ---------------
370453 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian.
371454 | fips\_status | u32 | Indicates if the command is FIPS approved or an error.
372-| capabilities | u8[16] | Firmware capabilities
455+| capabilities | u8[16] | Firmware capabilities. See table below for details.
456+
457+*Table: Firmware Capabilities Flags*
458+
459+| **Name** | **Bit** | **Description**
460+| --------------- | ------- | ---------------
461+| `RT_BASE` | 64 | Base capabilities for Caliptra Runtime v2.1.
462+| `RT_OCP_LOCK` | 65 | Runtime firmware and hardware supports OCP LOCK.
373463
374464 ### GET\_IDEV\_ECC384\_CERT
375465
@@ -658,7 +748,7 @@
658748 | **Name** | **Type** | **Description**
659749 | -------- | -------- | ---------------
660750 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian.
661-| fips\_status | u32 | Indicates if the command is FIPS approved or an error.
751+| fips\_status | u32 | `FIPS_NOT_APPROVED_USER_SUPPLIED_DIGEST`, because the caller supplies the digest.
662752
663753 ### LMS\_SIGNATURE\_VERIFY
664754
@@ -699,7 +789,7 @@
699789 | **Name** | **Type** | **Description**
700790 | -------- | -------- | ---------------
701791 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian.
702-| fips\_status | u32 | Indicates if the command is FIPS approved or an error.
792+| fips\_status | u32 | `FIPS_NOT_APPROVED_USER_SUPPLIED_DIGEST`, because the caller supplies the digest.
703793
704794 ### MLDSA87_SIGNATURE_VERIFY
705795
@@ -742,7 +832,7 @@
742832 | **Name** | **Type** | **Description**
743833 | -------- | -------- | ---------------
744834 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian.
745-| digest | u32[12] | Owner public key hash.
835+| digest | u32[12] | Owner public key hash. See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields).
746836
747837 *Table: `INSTALL_OWNER_PK_HASH` output arguments*
748838
@@ -813,13 +903,13 @@
813903 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian.
814904 | fips\_status | u32 | Indicates if the command is FIPS approved or an error.
815905
816-### INVOKE\_DPE\_COMMAND
817-
818-Invokes a serialized DPE command.
906+### INVOKE\_DPE\_ECC384
907+
908+Invokes a serialized EC-P384 DPE profile command.
819909
820910 Command Code: `0x4450_4543` ("DPEC")
821911
822-*Table: `INVOKE_DPE_COMMAND` input arguments*
912+*Table: `INVOKE_DPE_ECC384` input arguments*
823913
824914 | **Name** | **Type** | **Description**
825915 | -------- | -------- | ---------------
@@ -827,7 +917,53 @@
827917 | data\_size | u32 | Length in bytes of the valid data in the data field.
828918 | data | u8[...] | DPE command structure as defined in the DPE iRoT profile.
829919
830-*Table: `INVOKE_DPE_COMMAND` output arguments*
920+*Table: `INVOKE_DPE_ECC384` output arguments*
921+
922+| **Name** | **Type** | **Description**
923+| -------- | -------- | ---------------
924+| chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian.
925+| fips\_status | u32 | Indicates if the command is FIPS approved or an error.
926+| data\_size | u32 | Length in bytes of the valid data in the data field.
927+| data | u8[...] | DPE response structure as defined in the DPE iRoT profile.
928+
929+### INVOKE\_DPE\_MLDSA87
930+
931+Invokes a serialized ML-DSA-87 DPE profile command. In subsystem mode a response
932+can be DMA'ed to an external address. This is especially useful for large
933+commands like `CertifyKey` or `DeriveContext` when exporting a CDI. Both of
934+these responses contain a potentially large certificate/CSR. To use this
935+feature, set the `EXTERNAL_AXI_RESPONSE` in `flags` and set the corresponding
936+AXI address and size fields. The response over the mailbox will only contain a
937+mailbox header (`chksum` and `fips_status`). The full response including the
938+mailbox header will be found at the given address.
939+
940+**Important restrictions for `EXTERNAL_AXI_RESPONSE` flag use:**
941+- This command is only available in subsystem mode, as DMA is only available in subsystem.
942+- This command is only available for MCU.
943+
944+Command Code: `0x4450_454D` ("DPEM")
945+
946+*Table: `INVOKE_DPE_MLDSA87` input arguments*
947+
948+| **Name** | **Type** | **Description** |
949+| -------------- | -------- | --------------------------------------------------------------------------- |
950+| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
951+| flags | u32 | Flags to give configurations of the command. |
952+| axi\_addr\_lo | u32 | Lower word of the destination physical address. |
953+| axi\_addr\_hi | u32 | Upper word of the destination physical address. |
954+| axi\_max\_size | u32 | Maximum DMA response size. |
955+| data\_size | u32 | Length in bytes of the valid data in the data field. |
956+| data | u8[...] | DPE command structure as defined in the DPE iRoT profile. |
957+
958+
959+*Table: `INVOKE_DPE_MLDSA87` input flags*
960+
961+| **Name** | **Value** |
962+| ----------------------- | --------- |
963+| EXTERNAL\_AXI\_RESPONSE | 1 << 31 |
964+
965+
966+*Table: `INVOKE_DPE_MLDSA87` output arguments*
831967
832968 | **Name** | **Type** | **Description**
833969 | -------- | -------- | ---------------
@@ -890,8 +1026,36 @@
8901026 | PCRs | PcrValue[32] | Values of all PCRs.
8911027 | nonce | u8[32] | Return the nonce used as input for convenience.
8921028 | reset\_ctrs | u32[32] | Reset counters for all PCRs.
893-| digest | u8[64] | Return the SHA2-512 digest over the PCR values and the nonce, in byte reversed order.
1029+| 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.
8941030 | 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.
1031+
1032+**Digest byte order:** The `digest` field has two transformations applied relative
1033+to the standard `openssl dgst -sha512` output: (1) the 16 u32 words are in
1034+reversed order, and (2) the bytes within each word are reversed. For example, if
1035+`openssl dgst -sha512` produces `A1 B2 C3 D4 E5 F6 07 18 ... P1 P2 P3 P4`,
1036+the mailbox response contains `P4 P3 P2 P1 ... 18 07 F6 E5 D4 C3 B2 A1`.
1037+
1038+To **independently recompute** this digest from PCR values and nonce, compute the
1039+SHA2-512 hash, then apply two steps:
1040+
1041+```
1042+openssl dgst -sha512 output (64 bytes, shown as 16 four-byte groups):
1043+ A1 B2 C3 D4 | E5 F6 07 18 | ... | M1 M2 M3 M4 | P1 P2 P3 P4
1044+
1045+Step 1 — reverse the bytes within each 4-byte group:
1046+ D4 C3 B2 A1 | 18 07 F6 E5 | ... | M4 M3 M2 M1 | P4 P3 P2 P1
1047+
1048+Step 2 — reverse the order of all 16 groups:
1049+ P4 P3 P2 P1 | M4 M3 M2 M1 | ... | 18 07 F6 E5 | D4 C3 B2 A1
1050+ ^^^^^^^^^^^^ ^^^^^^^^^^^^
1051+ (last group from Step 1 is now first) (first group is now last)
1052+
1053+Mailbox digest = result of Step 2
1054+```
1055+
1056+To **verify the signature** with an external tool such as OpenSSL, pass the `digest`
1057+bytes as-is as the pre-hashed message to ML-DSA-87 verification — no conversion
1058+is needed because the signature was computed over these exact bytes.
8951059
8961060 ### EXTEND\_PCR
8971061
@@ -1163,35 +1327,69 @@
11631327 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian.
11641328 | fips\_status | u32 | Indicates if the command is FIPS approved or an error.
11651329
1166-### CERTIFY\_KEY\_EXTENDED
1167-
1168-Produces a DPE leaf certificate or CSR containing custom extensions provided by the SoC.
1330+### CERTIFY\_KEY\_EXTENDED\_ECC384
1331+
1332+Produces an ECC-P384 DPE leaf certificate or CSR containing custom extensions provided by the SoC.
11691333
11701334 Command Code: `0x434B_4558` ("CKEX")
11711335
1172-*Table: `CERTIFY_KEY_EXTENDED` input arguments*
1336+*Table: `CERTIFY_KEY_EXTENDED_ECC384` input arguments*
11731337
11741338 | **Name** | **Type** | **Description** |
11751339 | ----------------- | -------- | --------------------------------------------------------------------------- |
11761340 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
1341+| flags | u32 | Flags determining which custom extensions to include in the certificate. |
11771342 | certify\_key\_req | u8[72] | Certify Key Request. |
1178-| flags | u32 | Flags determining which custom extensions to include in the certificate. |
1179-
1180-
1181-*Table: `CERTIFY_KEY_EXTENDED` input flags*
1343+
1344+
1345+*Table: `CERTIFY_KEY_EXTENDED_ECC384` input flags*
11821346
11831347 | **Name** | **Offset** |
1184-| --------------- | ---------- |
1185-| DMTF_OTHER_NAME | 1 << 31 |
1186-
1187-
1188-*Table: `CERTIFY_KEY_EXTENDED` output arguments*
1189-
1190-| **Name** | **Type** | **Description** |
1191-| ------------------ | -------- | -------------------------------------------------------------------------- |
1348+| ----------------- | ---------- |
1349+| DMTF\_OTHER\_NAME | 1 << 31 |
1350+
1351+
1352+*Table: `CERTIFY_KEY_EXTENDED_ECC384` output arguments*
1353+
1354+| **Name** | **Type** | **Description** |
1355+| ------------------ | --------- | -------------------------------------------------------------------------- |
11921356 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
11931357 | fips\_status | u32 | Indicates if the command is FIPS approved or an error. |
1194-| certify\_key\_resp | u8[2176] | Certify Key Response. |
1358+| size | u32 | The size of the response in the certify\_key\_resp field. |
1359+| certify\_key\_resp | u8[25152] | Certify Key Response. |
1360+
1361+
1362+### CERTIFY\_KEY\_EXTENDED\_MLDSA87
1363+
1364+Produces an ML-DSA-87 DPE leaf certificate or CSR containing custom extensions provided by the SoC.
1365+
1366+Command Code: `0x434B_584D` ("CKXM")
1367+
1368+*Table: `CERTIFY_KEY_EXTENDED_MLDSA87` input arguments*
1369+
1370+| **Name** | **Type** | **Description** |
1371+| ----------------- | -------- | --------------------------------------------------------------------------- |
1372+| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
1373+| flags | u32 | Flags determining which custom extensions to include in the certificate. |
1374+| certify\_key\_req | u8[72] | Certify Key Request. |
1375+
1376+
1377+*Table: `CERTIFY_KEY_EXTENDED_MLDSA87` input flags*
1378+
1379+| **Name** | **Offset** |
1380+| ----------------------- | ---------- |
1381+| DMTF\_OTHER\_NAME | 1 << 31 |
1382+| EXTERNAL\_AXI\_RESPONSE | 1 << 30 |
1383+
1384+
1385+*Table: `CERTIFY_KEY_EXTENDED_MLDSA87` output arguments*
1386+
1387+| **Name** | **Type** | **Description** |
1388+| ------------------ | --------- | -------------------------------------------------------------------------- |
1389+| chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
1390+| fips\_status | u32 | Indicates if the command is FIPS approved or an error. |
1391+| size | u32 | The size of the response in the certify\_key\_resp field. |
1392+| certify\_key\_resp | u8[25152] | Certify Key Response. |
11951393
11961394
11971395 ### CERTIFY\_KEY\_CHUNKS
@@ -1239,30 +1437,42 @@
12391437
12401438 The SoC uses this command and `SET_IMAGE_METADTA` to program an image manifest for Manifest-Based Image Authorization to Caliptra. In response to these commands, the Caliptra Runtime will verify the manifest by authenticating the public keys and in turn using them to authenticate the IMC. On successful verification, the Runtime will store the IMEs into DCCM for future use. Every active `fw_id` must be unique within this manifest and must not appear in the installed owner-only manifest. A collision rejects the command without replacing either active collection.
12411439
1440+The original SoC manifest may include an optional device UEID IME with the
1441+reserved `fw_id` `0x0000_0FFF`, immediately below the vendor-defined SoC image
1442+ID range beginning at `0x0000_1000`. Its 48-byte digest contains the 17-byte
1443+device UEID followed by 31 zero bytes.
1444+After authenticating the IMC, Runtime compares the complete value with the UEID
1445+assembled from the IDevID certificate-attribute fuses. A mismatch, including
1446+nonzero padding, rejects the command with
1447+`RUNTIME_AUTH_MANIFEST_UEID_MISMATCH` without replacing the active manifest.
1448+The UEID entry is excluded from normal image lookup, authorization, and
1449+activation. This interpretation does not apply to the owner-only manifest
1450+loaded by `SET_OWNER_AUTH_MANIFEST`.
1451+
12421452 Command Code: `0x4154_4D4E` ("ATMN")
12431453
12441454 *Table: `SET_AUTH_MANIFEST` input arguments*
12451455
1246-| **Name** | **Type** | **Description**
1247-| -------- | -------- | ---------------
1456+| **Name** | **Type** | **Description** |
1457+| -------- | -------- | --------------- |
12481458 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
12491459 | manifest size | u32 | The size of the full Authentication Manifest |
12501460 | preamble\_marker | u32 | Marker needs to be 0x4154_4D4E for the preamble to be valid |
12511461 | preamble\_size | u32 | Size of the preamble |
12521462 | preamble\_version | u32 | Version of the preamble |
12531463 | preamble\_flags | u32 | Manifest flags. See AUTH_MANIFEST_FLAGS below |
1254-| preamble\_vendor\_ecc384\_key | u32[24] | Vendor ECC384 key with X and Y coordinates in that order |
1255-| preamble\_vendor\_pqc\_key | u32[648] | Vendor MLDSA-87 or LMS-SHA192-H15 key |
1256-| preamble\_vendor\_ecc384\_sig | u32[24] | Vendor ECC384 signature |
1257-| preamble\_vendor\_PQC\_sig | u32[1157] | Vendor MLDSA-87 or LMOTS-SHA192-W4 signature |
1258-| preamble\_owner\_ecc384\_key | u32[24] | Owner ECC384 key with X and Y coordinates in that order |
1259-| preamble\_owner\_pqc\_key | u32[648] | Owner MLDSA-87 or LMS-SHA192-H15 key |
1260-| preamble\_owner\_ecc384\_sig | u32[24] | Owner ECC384 signature |
1261-| preamble\_owner\_PQC\_sig | u32[1157] | Owner MLDSA-87 or LMOTS-SHA192-W4 signature |
1262-| metadata\_vendor\_ecc384\_sig | u32[24] | Metadata Vendor ECC384 signature |
1263-| metadata\_vendor\_PQC\_sig | u32[1157] | Metadata Vendor MLDSA-87 or LMOTS-SHA192-W4 signature |
1264-| metadata\_owner\_ecc384\_sig | u32[24] | Metadata Owner ECC384 signature |
1265-| metadata\_owner\_PQC\_sig | u32[1157] | Metadata Owner MLDSA-87 or LMOTS-SHA192-W4 signature |
1464+| 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). |
1465+| 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). |
1466+| preamble\_vendor\_ecc384\_sig | u32[24] | Vendor ECC384 signature. See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields). |
1467+| 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). |
1468+| 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). |
1469+| 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). |
1470+| preamble\_owner\_ecc384\_sig | u32[24] | Owner ECC384 signature. See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields). |
1471+| 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). |
1472+| metadata\_vendor\_ecc384\_sig | u32[24] | Metadata Vendor ECC384 signature. See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields). |
1473+| 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). |
1474+| metadata\_owner\_ecc384\_sig | u32[24] | Metadata Owner ECC384 signature. See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields). |
1475+| 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). |
12661476 | metadata\_entry\_entry\_count | u32 | number of metadata entries |
12671477 | metadata\_entries | Metadata[80] | The max number of metadata entries is 80 but less can be used |
12681478
@@ -1285,21 +1495,21 @@
12851495 | **Name** | **Type** | **Description** |
12861496 | ------------------------ | --------- | ---------------- |
12871497 | Image Hash | u8[48] | SHA2-384 hash of a SOC image. |
1288-
1289-| 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)
1290-| 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)
1291-| 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)
1292-| 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)
1293-| 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)
1294-| 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)
1295-| 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)
1296-| 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)
1297-| 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)
1298-| 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)
1498+| 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) |
1499+| 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) |
1500+| flags | u32 | This corresponds to the `flags` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main/auth-manifest/README.md) |
1501+| 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) |
1502+| 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) |
1503+| 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) |
1504+| 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) |
1505+| Classification | u32 | This corresponds to the `Classification` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main/auth-manifest/README.md) |
1506+| 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) |
1507+| 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) |
1508+
12991509
13001510 ### VERIFY_AUTH_MANIFEST
13011511
1302-This command verifies the integrity and authenticity of the provided image manifest, including the `DEBUG_IMAGE` policy described above. Unlike `SET_AUTH_MANIFEST`, it performs validation only and does not persist the manifest in DCCM or modify `FW_INFO.debug_policy`. It also rejects a `fw_id` collision with the currently installed owner-only manifest.
1512+This command verifies the integrity and authenticity of the provided image manifest, including the `DEBUG_IMAGE` policy described above and the optional device UEID. Unlike `SET_AUTH_MANIFEST`, it performs validation only and does not persist the manifest in DCCM or modify `FW_INFO.debug_policy`. It also rejects a `fw_id` collision with the currently installed owner-only manifest.
13031513
13041514 Command Code: `0x4154_564D` ("ATVM")
13051515
@@ -1316,11 +1526,11 @@
13161526
13171527 1. The manifest's `owner_pub_keys` are signed by the firmware-image owner key (latched from FMC at boot via `manifest1.preamble.owner_pub_keys`). This signature also covers the policy fields `version`, `svn`, `flags`, and `owner_pub_keys`.
13181528 2. The manifest's IMC is signed by the manifest's own `owner_pub_keys`, which were just verified to chain to the firmware-image owner key.
1319-3. The manifest's `svn` is checked against the floor encoded in `SS_STRAP_GENERIC[3][15:8]` (subsystem mode only). The check is skipped when the lifecycle is `Unprovisioned` or anti-rollback is disabled.
1529+3. The manifest's `svn` is checked against the floor encoded in `SS_STRAP_GENERIC[3][15:8]`. The check is skipped when the lifecycle is `Unprovisioned` or anti-rollback is disabled.
13201530
13211531 #### Owner Authorization Manifest Minimum SVN
13221532
1323-`SS_STRAP_GENERIC[3][15:8]` carries a binary value in the range `0..255`; it does not carry a fuse bitmap. Before Caliptra starts, MCU firmware is responsible for deriving the owner-manifest minimum SVN from the platform's monotonic storage and programming the resulting integer into this strap. The strap is then locked by `CPTRA_FUSE_WR_DONE`.
1533+`SS_STRAP_GENERIC[3][15:8]` carries a binary value in the range `0..255`; it does not carry a fuse bitmap. Before Caliptra starts, platform firmware is responsible for deriving the owner-manifest minimum SVN from the platform's monotonic storage and programming the resulting integer into this strap. The strap is then locked by `CPTRA_FUSE_WR_DONE`.
13241534
13251535 This software interface does not define a new Caliptra fuse field. If a platform uses the same thermometer encoding as the existing SVN fuses, a 256-bit-aligned platform field can use bits 0 through 254 to encode SVN values 1 through 255, with all zeros encoding SVN 0 and bit 255 reserved. The authoritative physical fuse allocation belongs to the SoC/platform fuse-controller specification.
13261536
@@ -1349,6 +1559,14 @@
13491559
13501560 The response is a `MailboxRespHeader` (no payload).
13511561
1562+### VERIFY_OWNER_AUTH_MANIFEST
1563+
1564+This command verifies the integrity, authenticity, policy fields, SVN, and firmware-ID collisions of an Owner Authorization Manifest. Unlike `SET_OWNER_AUTH_MANIFEST`, it does not replace the active owner-only metadata collection or update the owner manifest digest or current SVN.
1565+
1566+Command Code: `0x4F41_564D` ("OAVM")
1567+
1568+The input arguments and response are the same as the `SET_OWNER_AUTH_MANIFEST` command.
1569+
13521570
13531571 ### AUTHORIZE_AND_STASH
13541572
@@ -1361,22 +1579,23 @@
13611579
13621580 *Table: `AUTHORIZE_AND_STASH` input arguments*
13631581
1364-| **Name** | **Type** | **Description**
1365-| ------------| -------- | ---------------
1582+| **Name** | **Type** | **Description** |
1583+| ------------ | -------- | --------------- |
13661584 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
13671585 | fw_id | u8[4] | Firmware id of the image, in little-endian format |
13681586 | 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. |
13691587 | context | u8[48] | Context field for `svn`; e.g., a hash of the public key that authenticated the SVN. |
13701588 | svn | u32 | The version of the image |
1371-| flags | u32 | See AUTHORIZE_AND_STASH_FLAGS below |
1589+| flags | u32 | See `AUTHORIZE_AND_STASH_FLAGS` below. |
13721590 | source | u32 | This field identifies the source of the digest to be used to compare with the SoC's<br />SHA digest in the SoC Manifest<br /><br />Values<br />1 - InRequest - Use the hash in the 'measurement' field of this command<br /><br />2 - LoadAddress - The image located in the `ImageLoadAddress` will be streamed to the SHA Accelerator to <br /> retrieve the digest that will be used for authorization.<br />3 - ImageStagingAddress - The image located in the `StagingAddress` will be streamed to the SHA Accelerator to<br /> retrieve the digest that will be used for authorization |
13731591 | image_size | u32 | The size of the image to hash. Only valid if source is `ImageLoadAddress` or `StagingAddress` |
13741592
13751593
13761594 *Table: `AUTHORIZE_AND_STASH_FLAGS` input flags*
1377-| **Name** | **Value** |
1378-| ----------- | --------- |
1379-| SKIP\_STASH | 1 << 0 |
1595+| **Bits** | **Name** | **Description** |
1596+| -------- | ------------------ | --------------- |
1597+| 0 | SKIP\_STASH | Skip stashing the authorized measurement. |
1598+| [2:1] | MANIFEST\_SOURCE | `00`: vendor + owner manifest; `01`: owner-only manifest. `10` and `11` are invalid. |
13801599
13811600
13821601 *Table: `AUTHORIZE_AND_STASH` output arguments*
@@ -1384,16 +1603,13 @@
13841603 | --------------- | -------- | -------------------------------------------------------------------------- |
13851604 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
13861605 | fips_status | u32 | Indicates if the command is FIPS approved or an error. |
1387-| auth_req_result | u32 | IMAGE_AUTHORIZED_VENDOR_OWNER (0xDEADC0DE, alias of legacy `AUTHORIZE_IMAGE`/`IMAGE_AUTHORIZED`), IMAGE_AUTHORIZED_OWNER_ONLY (0xC0DEDEAD), IMAGE_NOT_AUTHORIZED (0x21523F21) or IMAGE_HASH_MISMATCH (0x8BFB95CB). Lookup order: vendor + owner collection first, then owner-only collection populated by `SET_OWNER_AUTH_MANIFEST`. Active firmware IDs are unique across the collections, and the success value indicates which collection produced the match. |
1606+| auth_req_result | u32 | IMAGE_AUTHORIZED_VENDOR_OWNER (0xDEADC0DE, alias of legacy `AUTHORIZE_IMAGE`/`IMAGE_AUTHORIZED`), IMAGE_AUTHORIZED_OWNER_ONLY (0xC0DEDEAD), IMAGE_NOT_AUTHORIZED (0x21523F21) or IMAGE_HASH_MISMATCH (0x8BFB95CB). The success value identifies the selected collection that produced the match. |
13881607
13891608
13901609 ### GET_IMAGE_INFO
13911610
13921611 The MCU uses this command to retrieve the active Image Metadata Entry for a
1393-firmware ID. The Runtime searches the vendor + owner Image Metadata Collection
1394-first, then the owner-only collection installed by
1395-[`SET_OWNER_AUTH_MANIFEST`](#set_owner_auth_manifest). Active firmware IDs are
1396-unique across the collections, so the response is unambiguous.
1612+firmware ID from the collection selected by bits `[2:1]` of `flags`.
13971613
13981614 Command Code: `0x494D_4530` ("IME0")
13991615
@@ -1402,8 +1618,9 @@
14021618 | **Name** | **Type** | **Description** |
14031619 | -------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
14041620 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
1405-
1406-| fw_id | u32 | Firmware id of the image, in little-endian format
1621+| fw_id | u32 | Firmware id of the image, in little-endian format |
1622+| flags | u32 | Bits `[2:1]` select the Image Metadata Collection: `00` selects the vendor + owner manifest; `01` selects the owner-only manifest. `10` and `11` are invalid. All other bits are reserved and must be zero. |
1623+
14071624
14081625 *Table: `GET_IMAGE_INFO` output arguments*
14091626
@@ -1411,13 +1628,36 @@
14111628 | -------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
14121629 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
14131630 | fips_status | u32 | Indicates if the command is FIPS approved or an error. |
1414-| 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) |
1415-| 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) |
1416-| 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) |
1417-| 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) |
1418-| 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) |
1419-| 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) |
1631+| 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) |
1632+| flags | u32 | This corresponds to the `flags` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main/auth-manifest/README.md) |
1633+| 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) |
1634+| 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) |
1635+| 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) |
1636+| 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) |
14201637 | digest | u8[48] | SHA-384 digest of the image. **Only present in FW 2.0.2+ and 2.1.1+.** |
1638+
1639+
1640+### GET\_MCU\_FW\_SIZE
1641+
1642+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.
1643+
1644+Command Code: `0x474D_4653` ("GMFS")
1645+
1646+*Table: `GET_MCU_FW_SIZE` input arguments*
1647+
1648+| **Name** | **Type** | **Description** |
1649+| -------------- | -------------- | --------------------------------------------------------------------------- |
1650+| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
1651+
1652+
1653+*Table: `GET_MCU_FW_SIZE` output arguments*
1654+
1655+| **Name** | **Type** | **Description** |
1656+| -------------- | -------------- | -------------------------------------------------------------------------- |
1657+| chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
1658+| fips_status | u32 | Indicates if the command is FIPS approved or an error. |
1659+| size | u32 | Size of the MCU firmware image in bytes. |
1660+| sha384 | u8[48] | SHA-384 digest of the encrypted MCU firmware image. |
14211661
14221662
14231663 ### ACTIVATE_FIRMWARE
@@ -1435,7 +1675,44 @@
14351675 | count | u32 | Number of image_ids to activate. Item count of image_ids array parameter |
14361676 | mcu_image_size | u32 | Size of MCU image, if included in the activation |
14371677 | image_ids | Array of u8[4] | Array of Image ids in little-endian format |
1438-
1678+| flags | u32 | Optional flags (see below). Caliptra runtime 2.1.1+ only. |
1679+
1680+
1681+*Flags*
1682+
1683+| **Bits** | **Name** | **Description** |
1684+| -------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------ |
1685+| 0 | `INITIAL_ACTIVATE` | First-time MCU activation after the encrypted-boot flow. Caliptra runtime 2.1.1+ only. See below. |
1686+| [2:1] | `MANIFEST_SOURCE` | `00`: vendor + owner manifest; `01`: owner-only manifest. `10` and `11` are invalid. |
1687+
1688+
1689+Unknown flag bits are rejected with `RUNTIME_MAILBOX_INVALID_PARAMS`.
1690+
1691+`INITIAL_ACTIVATE` is used exclusively by MCU ROM at the tail of the
1692+`EncryptedFirmware` boot flow. MCU ROM has already loaded firmware into MCU
1693+SRAM via `RI_DOWNLOAD_ENCRYPTED_FIRMWARE` and decrypted it in place via
1694+`CM_AES_GCM_DECRYPT_DMA`. When this flag is set, Caliptra Runtime:
1695+
1696+- Skips the hitless-update steps (set `RESET_REASON.FwHitlessUpd`, clear
1697+ `FW_EXEC_CTRL`, wait for MCU reset request and reset assertion, DMA-reload
1698+ from staging, re-`AuthorizeAndStash`).
1699+- Just publishes `FW_EXEC_CTRL[MCU]` (and any other requested bits) so that
1700+ MCI's `BOOT_RST_MCU` state releases MCU from reset on the next warm reset
1701+ that MCU ROM triggers.
1702+
1703+Caliptra Runtime only honors `INITIAL_ACTIVATE` when **all** of the following
1704+are true; otherwise the command fails with `IMAGE_VERIFIER_ACTIVATION_FAILED`:
1705+
1706+1. The MCU image bit is included in the activation request.
1707+2. The boot mode set by ROM is `EncryptedFirmware` (i.e., ROM received
1708+ `RI_DOWNLOAD_ENCRYPTED_FIRMWARE`).
1709+3. `FW_EXEC_CTRL[MCU]` is currently `0` — this is an initial activation,
1710+ not a hitless update masquerading as one.
1711+
1712+Together, these checks ensure that the MCU SRAM contents are
1713+integrity-protected end-to-end (ciphertext digest verified during recovery;
1714+GCM tag verified during `CM_AES_GCM_DECRYPT_DMA`) before Caliptra releases
1715+MCU to execute them.
14391716
14401717 *Table: `ACTIVATE_FIRMWARE` output arguments*
14411718
@@ -1444,6 +1721,28 @@
14441721 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
14451722 | fips_status | u32 | Indicates if the command is FIPS approved or an error. |
14461723
1724+
1725+## Mailbox commands: OCP LOCK v1.0
1726+
1727+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).
1728+
1729+### ENUMERATE_HPKE_HANDLES
1730+### REPORT_HEK_METADATA
1731+### GET_ALGORITHMS
1732+### INITIALIZE_MEK_SECRET
1733+### ROTATE_HPKE_KEY
1734+### GENERATE_MEK
1735+### GENERATE_MPK
1736+### REWRAP_MPK
1737+### ENABLE_MPK
1738+### MIX_MPK
1739+### GET_HPKE_PUB_KEY
1740+### TEST_ACCESS_KEY
1741+### GET_STATUS
1742+### CLEAR_KEY_CACHE
1743+### UNLOAD_MEK
1744+### LOAD_MEK
1745+### DERIVE_MEK
14471746
14481747 ## Mailbox commands: Cryptographic Mailbox (2.0)
14491748
@@ -1547,6 +1846,99 @@
15471846 | fips_status | u32 | FIPS approved or an error |
15481847 | hash size | u32 ||
15491848 | hash | u8[hash size] ||
1849+
1850+
1851+### CM\_SHAKE256\_INIT
1852+
1853+This starts the computation of a SHAKE256 extendable-output hash, which may be larger than a single mailbox command allows.
1854+
1855+**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.
1856+
1857+The sequence to use these are:
1858+* 1 `CM_SHAKE256_INIT` command
1859+* 0 or more `CM_SHAKE256_UPDATE` commands
1860+* 1 `CM_SHAKE256_FINAL` command
1861+
1862+For each command, the context from the previous command's output must be passed as an input.
1863+
1864+The `SHAKE256_CONTEXT_SIZE` is always exactly 44 bytes long (encrypted session token).
1865+
1866+The maximum supported input data size per command is 4096 bytes.
1867+
1868+Command Code: `0x434D_5849` ("CMXI")
1869+
1870+*Table: `CM_SHAKE256_INIT` input arguments*
1871+
1872+| **Name** | **Type** | **Description** |
1873+| --------- | ------------- | --------------- |
1874+| chksum | u32 ||
1875+| data size | u32 ||
1876+| data | u8[data size] | Data to hash |
1877+
1878+
1879+*Table: `CM_SHAKE256_INIT` output arguments*
1880+
1881+| **Name** | **Type** | **Description** |
1882+| ----------- | ------------------------- | -------------------------------------------------- |
1883+| chksum | u32 ||
1884+| fips_status | u32 | FIPS approved or an error |
1885+| context | u8[SHAKE256_CONTEXT_SIZE] | Passed to `CM_SHAKE256_UPDATE` / `CM_SHAKE256_FINAL` |
1886+
1887+
1888+### CM\_SHAKE256\_UPDATE
1889+
1890+This continues a SHAKE256 computation started by `CM_SHAKE256_INIT` or from another `CM_SHAKE256_UPDATE`.
1891+
1892+The context MUST be passed in from `CM_SHAKE256_INIT` or `CM_SHAKE256_UPDATE`.
1893+
1894+Command Code: `0x434D_5855` ("CMXU")
1895+
1896+*Table: `CM_SHAKE256_UPDATE` input arguments*
1897+
1898+| **Name** | **Type** | **Description** |
1899+| --------- | ------------------------- | ---------------------------------------------------- |
1900+| chksum | u32 ||
1901+| context | u8[SHAKE256_CONTEXT_SIZE] | From `CM_SHAKE256_INIT` / `CM_SHAKE256_UPDATE` |
1902+| data size | u32 ||
1903+| data | u8[data size] | Data to hash |
1904+
1905+
1906+*Table: `CM_SHAKE256_UPDATE` output arguments*
1907+
1908+| **Name** | **Type** | **Description** |
1909+| ----------- | ------------------------- | -------------------------------------------------- |
1910+| chksum | u32 ||
1911+| fips_status | u32 | FIPS approved or an error |
1912+| context | u8[SHAKE256_CONTEXT_SIZE] | Passed to `CM_SHAKE256_UPDATE` / `CM_SHAKE256_FINAL` |
1913+
1914+
1915+### CM\_SHAKE256\_FINAL
1916+
1917+This finalizes the SHAKE256 computation and produces the hash of all of the data.
1918+
1919+The context MUST be passed in from `CM_SHAKE256_INIT` or `CM_SHAKE256_UPDATE`.
1920+
1921+The output is always a 64-byte SHAKE256 digest.
1922+
1923+Command Code: `0x434D_5846` ("CMXF")
1924+
1925+*Table: `CM_SHAKE256_FINAL` input arguments*
1926+
1927+| **Name** | **Type** | **Description** |
1928+| ----------- | ------------------------- | ---------------------------------------------- |
1929+| chksum | u32 ||
1930+| context | u8[SHAKE256_CONTEXT_SIZE] | From `CM_SHAKE256_INIT` / `CM_SHAKE256_UPDATE` |
1931+| data size | u32 | May be 0 |
1932+| data | u8[data size] | Data to hash |
1933+
1934+
1935+*Table: `CM_SHAKE256_FINAL` output arguments*
1936+
1937+| **Name** | **Type** | **Description** |
1938+| ----------- | -------- | ------------------------- |
1939+| chksum | u32 ||
1940+| fips_status | u32 | FIPS approved or an error |
1941+| hash | u8[64] | SHAKE256 digest |
15501942
15511943
15521944 ### CM\_HMAC
@@ -1789,7 +2181,7 @@
17892181
17902182 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.
17912183
1792-Command Code: `0x434D_5D53` ("CMES")
2184+Command Code: `0x434D_4553` ("CMES")
17932185
17942186 *Table: `CM_ECDSA_SIGN` input arguments*
17952187 | **Name** | **Type** | **Description** |
@@ -1837,6 +2229,79 @@
18372229 | fips_status | u32 | FIPS approved or an error |
18382230
18392231
2232+### CM_MLKEM_KEY_GEN
2233+
2234+Generates an ML-KEM-1024 encapsulation key from the seed (seed\_d || seed\_z, 64 bytes) stored in a CMK with key usage `Mlkem`.
2235+
2236+The key generation algorithm is described in [FIPS 203](https://csrc.nist.gov/pubs/fips/203/final).
2237+
2238+Command Code: `0x434D_4C4B` ("CMLK")
2239+
2240+*Table: `CM_MLKEM_KEY_GEN` input arguments*
2241+| **Name** | **Type** | **Description** |
2242+| -------- | -------- | ---------------------------------------- |
2243+| chksum | u32 ||
2244+| CMK | CMK | ML-KEM seed (seed\_d &#124;&#124; seed\_z) |
2245+
2246+
2247+*Table: `CM_MLKEM_KEY_GEN` output arguments*
2248+| **Name** | **Type** | **Description** |
2249+| ----------- | -------- | ---------------------------------------- |
2250+| chksum | u32 ||
2251+| fips_status | u32 | FIPS approved or an error |
2252+| encaps_key | u8[1568] | ML-KEM-1024 encapsulation key |
2253+
2254+
2255+### CM_MLKEM_ENCAPSULATE
2256+
2257+Performs ML-KEM-1024 encapsulation against the provided encapsulation key, producing a ciphertext and a shared key wrapped as a CMK.
2258+
2259+The encapsulation algorithm is described in [FIPS 203](https://csrc.nist.gov/pubs/fips/203/final).
2260+
2261+Command Code: `0x434D_4C45` ("CMLE")
2262+
2263+*Table: `CM_MLKEM_ENCAPSULATE` input arguments*
2264+| **Name** | **Type** | **Description** |
2265+| ----------- | -------- | ---------------------------------------- |
2266+| chksum | u32 ||
2267+| key_usage | u32 | Key usage for the output CMK |
2268+| encaps_key | u8[1568] | ML-KEM-1024 encapsulation key |
2269+
2270+
2271+*Table: `CM_MLKEM_ENCAPSULATE` output arguments*
2272+| **Name** | **Type** | **Description** |
2273+| ----------- | -------- | ---------------------------------------- |
2274+| chksum | u32 ||
2275+| fips_status | u32 | FIPS approved or an error |
2276+| ciphertext | u8[1568] | ML-KEM-1024 ciphertext |
2277+| shared_key | CMK | CMK of the shared secret key |
2278+
2279+
2280+### CM_MLKEM_DECAPSULATE
2281+
2282+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.
2283+
2284+The decapsulation algorithm is described in [FIPS 203](https://csrc.nist.gov/pubs/fips/203/final).
2285+
2286+Command Code: `0x434D_4C44` ("CMLD")
2287+
2288+*Table: `CM_MLKEM_DECAPSULATE` input arguments*
2289+| **Name** | **Type** | **Description** |
2290+| ----------- | -------- | ---------------------------------------- |
2291+| chksum | u32 ||
2292+| key_usage | u32 | Key usage for the output CMK |
2293+| CMK | CMK | ML-KEM seed (seed\_d &#124;&#124; seed\_z) |
2294+| ciphertext | u8[1568] | ML-KEM-1024 ciphertext to decapsulate |
2295+
2296+
2297+*Table: `CM_MLKEM_DECAPSULATE` output arguments*
2298+| **Name** | **Type** | **Description** |
2299+| ----------- | -------- | ---------------------------------------- |
2300+| chksum | u32 ||
2301+| fips_status | u32 | FIPS approved or an error |
2302+| shared_key | CMK | CMK of the shared secret key |
2303+
2304+
18402305 ### CM_AES_ENCRYPT_INIT
18412306
18422307 Generic AES operation for unauthenticated AES operations.
@@ -1849,7 +2314,7 @@
18492314
18502315 The CMK must have been created for AES usage.
18512316
1852-Command Code: `0x434D_4349` ("CMCI")
2317+Command Code: `0x434D_4149` ("CMAI")
18532318
18542319 *Table: `CM_AES_ENCRYPT_INIT` input arguments*
18552320 | **Name** | **Type** | **Description** |
@@ -1883,8 +2348,7 @@
18832348 | mode | u32 ||
18842349 | key | u8[32] ||
18852350 | iv | u8[16] ||
1886-| fips_status | u8 | 1 = FIPS valid |
1887-| reserved | u8[75] | Reserved for additional fields |
2351+| reserved | u8[76] | Reserved for additional fields |
18882352
18892353
18902354 The size of the (encrypted) context is always exactly 156 bytes,
@@ -1901,7 +2365,7 @@
19012365 For CBC, the size must be a multiple of 16 bytes.
19022366 CTR mode supports input of any size up to the maximum cryptographic mailbox size.
19032367
1904-Command Code: `0x434D_4355` ("CMCU")
2368+Command Code: `0x434D_4155` ("CMAU")
19052369
19062370 *Table: `CM_AES_ENCRYPT_UPDATE` input arguments*
19072371 | **Name** | **Type** | **Description** |
@@ -1972,7 +2436,7 @@
19722436 For CBC, the size must be a multiple of 16 bytes.
19732437 CTR mode supports input of any size up to the maximum cryptographic mailbox size.
19742438
1975-Command Code: `0x434D_4155` ("CMAU")
2439+Command Code: `0x434D_4156` ("CMAV")
19762440
19772441 *Table: `CM_AES_DECRYPT_UPDATE` input arguments*
19782442 | **Name** | **Type** | **Description** |
@@ -2033,8 +2497,7 @@
20332497 | GHASH state | u8[16] ||
20342498 | current length | u32 | value mod 16 is buffer size |
20352499 | buffer | u8[16] ||
2036-| fips_status | u8 | 1 = FIPS valid |
2037-| reserved | u8[15] ||
2500+| reserved | u8[16] ||
20382501
20392502
20402503 The size of the (encrypted) context is always exactly 128 bytes,
@@ -2190,7 +2653,7 @@
21902653
21912654 The encrypted and authenticated context's internal structure will be the same as for encryption.
21922655
2193-### CM_AES_SPDM_GCM_DECRYPT_INIT
2656+### CM_AES_GCM_SPDM_DECRYPT_INIT
21942657
21952658 Starts an AES-256-GCM decryption computation in SPDM mode.
21962659
@@ -2306,6 +2769,45 @@
23062769 | plaintext | u8[plaintext size] ||
23072770
23082771
2772+### CM_AES_GCM_DECRYPT_DMA
2773+
2774+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.
2775+
2776+**Important restrictions:**
2777+- This command is only available in subsystem mode, as DMA is only available in subsystem.
2778+- This command is only available for MCU.
2779+- 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.
2780+- The command performs a two-pass operation:
2781+ 1. First pass: Verifies the SHA384 hash of the encrypted data at the AXI address
2782+ 2. Second pass: Performs in-place AES-GCM decryption via DMA
2783+
2784+The CMK must be an AES key (key usage = 3) that was previously imported using `CM_IMPORT`.
2785+
2786+Command Code: `0x434D_4444` ("CMDD")
2787+
2788+*Table: `CM_AES_GCM_DECRYPT_DMA` input arguments*
2789+| **Name** | **Type** | **Description** |
2790+| --------------------- | --------- | ---------------------------------------------------- |
2791+| chksum | u32 | Checksum over other input arguments |
2792+| cmk | CMK | Encrypted CMK containing the AES-256 key |
2793+| iv | u32[3] | AES-GCM initialization vector (12 bytes) |
2794+| tag | u32[4] | AES-GCM authentication tag (16 bytes) |
2795+| encrypted_data_sha384 | u8[48] | SHA384 hash of the encrypted data for verification |
2796+| axi_addr_lo | u32 | Lower 32 bits of the AXI address |
2797+| axi_addr_hi | u32 | Upper 32 bits of the AXI address |
2798+| length | u32 | Length of data to decrypt in bytes |
2799+| aad_length | u32 | Length of AAD in bytes (0-4095) |
2800+| aad | u8[...] | Additional authenticated data |
2801+
2802+
2803+*Table: `CM_AES_GCM_DECRYPT_DMA` output arguments*
2804+| **Name** | **Type** | **Description** |
2805+| ------------ | -------- | ----------------------------------------------------- |
2806+| chksum | u32 | Checksum over other output arguments |
2807+| fips_status | u32 | FIPS approved or an error |
2808+| tag_verified | u32 | 1 if GCM tag verification succeeded, 0 if it failed |
2809+
2810+
23092811 ### CM_ECDH_GENERATE
23102812
23112813 This computes the first half of an Elliptic Curve Diffie-Hellman exchange to compute an ephemeral shared key pair with another party.
@@ -2424,9 +2926,9 @@
24242926 ### CM\_DERIVE\_STABLE\_KEY
24252927
24262928 Derives an HMAC key that has a stable value across resets from either
2427-IDevId or LDevId.
2428-
2429-The (interior) value of the returned CMK will be the stable across resets as it is derived indirectly from the IDevId or LDevId CDIs.
2929+IDevId, LDevId, or the Owner Root Key (derived from HEK seed).
2930+
2931+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.
24302932 The actual encrypted bytes of the CMK will *not* be the same, and
24312933 the encrypted CMK itself cannot be used across resets. So, the key
24322934 will always need to be re-derived after every *cold* reset.
@@ -2434,26 +2936,39 @@
24342936 If a key usage other than HMAC is desired, then the KDF or HKDF
24352937 mailbox functions can be used to derive a key from the returned CMK.
24362938
2437-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.
2939+`key_type = OwnerKey` is only available in subsystem mode when the Stable Owner
2940+Key strap is enabled (`SS_STRAP_GENERIC[3]` bit 0 set to 1) and OCP LOCK is not
2941+enabled. If these requirements are not met, the command fails with
2942+`CMB_STABLE_OWNER_KEY_NOT_AVAILABLE`.
2943+
2944+In Runtime, this command is restricted to the PL0 PAUSER authenticated by the
2945+firmware manifest for all key types.
2946+
2947+For `OwnerKey`, this command derives from the ROM-populated Stable Owner Root
2948+Key. It first runs AES-256-CMAC KDF with `info` as the input data to produce an
2949+intermediate key, then runs HMAC-SHA512 KDF with `b"Stable Owner Key" || info`
2950+as the domain-separation input to produce the returned 64-byte HMAC key
2951+material. Caliptra wraps that key material as an encrypted CMK before returning
2952+it to the caller.
24382953
24392954 The command derivation is summarized below:
24402955
24412956 ![CM_DERIVE_STABLE_KEY Derivation](../images/caliptra-sw/runtime/../rom/dev/doc/svg/cm-derive-stable-key.svg)
24422957
2443-Command Code: `0x434D_4453` ("CMDS")
2958+Command Code: `0x494D_4453` ("IMDS")
24442959
24452960 *Table: `CM_DERIVE_STABLE_KEY` input arguments*
24462961
2447-| **Name** | **Type** | **Description**
2448-| -------- | -------- | ---------------
2962+| **Name** | **Type** | **Description** |
2963+| -------- | -------- | --------------- |
24492964 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
2450-| key_type | u32 | Source key to derive the stable key from. **0x0000_0001:** IDevId <br> **0x0000_0002:** LDevId |
2965+| 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) |
24512966 | info | u8[32] | Data to use in the key derivation. |
24522967
24532968
24542969 *Table: `CM_DERIVE_STABLE_KEY` output arguments*
2455-| **Name** | **Type** | **Description**
2456-| -------- | -------- | ---------------
2970+| **Name** | **Type** | **Description** |
2971+| -------- | -------- | --------------- |
24572972 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
24582973 | cmk | CMK | CMK that stores the stable key material |
24592974
@@ -2463,9 +2978,6 @@
24632978 Imports the specified key and returns a CMK for it.
24642979
24652980 Usage information is required so that the key can be verified and used appropriately.
2466-
2467-Note that it is the caller's responsibility to ensure that the source
2468-key material meets FIPS requirements, such as zeroization.
24692981
24702982 Command Code: `0x434D_494D` ("CMIM")
24712983
@@ -2550,14 +3062,14 @@
25503062
25513063 *Table: `GET_IDEV_ECC384_CSR` input arguments*
25523064
2553-| **Name** | **Type** | **Description**
2554-| -------- | -------- | ---------------
3065+| **Name** | **Type** | **Description** |
3066+| -------- | -------- | --------------- |
25553067 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
25563068
25573069
25583070 *Table: `GET_IDEV_ECC384_CSR` output arguments*
2559-| **Name** | **Type** | **Description**
2560-| -------- | -------- | ---------------
3071+| **Name** | **Type** | **Description** |
3072+| -------- | -------- | --------------- |
25613073 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
25623074 | data\_size | u32 | Length in bytes of the valid data in the data field. |
25633075 | data | u8[...] | DER-encoded ECC384 IDevID certificate signing request. |
@@ -2569,14 +3081,14 @@
25693081
25703082 *Table: `GET_IDEV_MLDSA87_CSR` input arguments*
25713083
2572-| **Name** | **Type** | **Description**
2573-| -------- | -------- | ---------------
3084+| **Name** | **Type** | **Description** |
3085+| -------- | -------- | --------------- |
25743086 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
25753087
25763088
25773089 *Table: `GET_IDEV_MLDSA87_CSR` output arguments*
2578-| **Name** | **Type** | **Description**
2579-| -------- | -------- | ---------------
3090+| **Name** | **Type** | **Description** |
3091+| -------- | -------- | --------------- |
25803092 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
25813093 | data\_size | u32 | Length in bytes of the valid data in the data field. |
25823094 | data | u8[...] | DER-encoded MLDSA87 IDevID certificate signing request. |
@@ -2596,14 +3108,14 @@
25963108
25973109 *Table: `GET_FMC_ALIAS_ECC384_CSR` input arguments*
25983110
2599-| **Name** | **Type** | **Description**
2600-| -------- | -------- | ---------------
3111+| **Name** | **Type** | **Description** |
3112+| -------- | -------- | --------------- |
26013113 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
26023114
26033115
26043116 *Table: `GET_FMC_ALIAS_ECC384_CSR` output arguments*
2605-| **Name** | **Type** | **Description**
2606-| -------- | -------- | ---------------
3117+| **Name** | **Type** | **Description** |
3118+| -------- | -------- | --------------- |
26073119 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
26083120 | data\_size | u32 | Length in bytes of the valid data in the data field. |
26093121 | data | u8[...] | DER-encoded ECC384 FMC Alias certificate signing request. |
@@ -2615,14 +3127,14 @@
26153127
26163128 *Table: `GET_FMC_ALIAS_MLDSA87_CSR` input arguments*
26173129
2618-| **Name** | **Type** | **Description**
2619-| -------- | -------- | ---------------
3130+| **Name** | **Type** | **Description** |
3131+| -------- | -------- | --------------- |
26203132 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
26213133
26223134
26233135 *Table: `GET_FMC_ALIAS_MLDSA87_CSR` output arguments*
2624-| **Name** | **Type** | **Description**
2625-| -------- | -------- | ---------------
3136+| **Name** | **Type** | **Description** |
3137+| -------- | -------- | --------------- |
26263138 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
26273139 | data\_size | u32 | Length in bytes of the valid data in the data field. |
26283140 | data | u8[...] | DER-encoded MLDSA87 FMC Alias certificate signing request. |
@@ -2636,8 +3148,8 @@
26363148
26373149 *Table: `GET_ATTESTED_ECC384_CSR` input arguments*
26383150
2639-| **Name** | **Type** | **Description**
2640-| -------- | -------- | ---------------
3151+| **Name** | **Type** | **Description** |
3152+| -------- | -------- | --------------- |
26413153 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
26423154 | key_id | u32 | Key ID for which CSR is requested.<br> **0x0000_0000:** Keypair inventory discovery <br> **0x0000_0001:** LDevId <br> **0x0000_0002:** FMC Alias <br> **0x0000_0003:** RT Alias |
26433155 | nonce | u8[32] | Nonce to be included in the CSR EAT. |
@@ -2645,8 +3157,8 @@
26453157
26463158 *Table: `GET_ATTESTED_ECC384_CSR` output arguments*
26473159
2648-| **Name** | **Type** | **Description**
2649-| -------- | -------- | ---------------
3160+| **Name** | **Type** | **Description** |
3161+| -------- | -------- | --------------- |
26503162 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
26513163 | data\_size | u32 | Length in bytes of the valid data in the data field. |
26523164 | data | u8[...] | COSE Sign1 signed EAT token containing attested CSR (or keypair inventory when key_id = 0). |
@@ -2660,8 +3172,8 @@
26603172
26613173 *Table: `GET_ATTESTED_MLDSA87_CSR` input arguments*
26623174
2663-| **Name** | **Type** | **Description**
2664-| -------- | -------- | ---------------
3175+| **Name** | **Type** | **Description** |
3176+| -------- | -------- | --------------- |
26653177 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
26663178 | key_id | u32 | Key ID for which CSR is requested.<br> **0x0000_0000:** Keypair inventory discovery <br> **0x0000_0001:** LDevId <br> **0x0000_0002:** FMC Alias <br> **0x0000_0003:** RT Alias |
26673179 | nonce | u8[32] | Nonce to be included in the CSR EAT. |
@@ -2669,8 +3181,8 @@
26693181
26703182 *Table: `GET_ATTESTED_MLDSA87_CSR` output arguments*
26713183
2672-| **Name** | **Type** | **Description**
2673-| -------- | -------- | ---------------
3184+| **Name** | **Type** | **Description** |
3185+| -------- | -------- | --------------- |
26743186 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
26753187 | data\_size | u32 | Length in bytes of the valid data in the data field. |
26763188 | data | u8[...] | COSE Sign1 signed EAT token containing attested CSR (or keypair inventory when key_id = 0). |
@@ -2684,23 +3196,57 @@
26843196
26853197 *Table: `SIGN_WITH_EXPORTED_ECDSA` input arguments*
26863198
2687-| **Name** | **Type** | **Description**
2688-| -------- | -------- | ---------------
3199+| **Name** | **Type** | **Description** |
3200+| -------- | -------- | --------------- |
26893201 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
2690-| exported_cdi_handle | u8[32] | The Exported CDI handle returned by the DPE `DeriveContext` command. Little endian. |
2691-| tbs | u8[48] | The bytes to be signed. Little endian. |
3202+| exported_cdi_handle | u8[32] | The exported CDI handle returned by the DPE `DeriveContext` command. Opaque byte array; copy the bytes exactly as returned. |
3203+| tbs | u8[48] | The 48-byte SHA-384 digest to be signed. Raw byte array; no byte swapping is required. |
26923204
26933205
26943206 *Table: `SIGN_WITH_EXPORTED_ECDSA` output arguments*
2695-| **Name** | **Type** | **Description**
2696-| -------- | -------- | ---------------
3207+| **Name** | **Type** | **Description** |
3208+| -------- | -------- | --------------- |
26973209 | derived_pubkey_x | u8[48] | The X BigNum of the ECDSA public key associated with the signing key. |
26983210 | derived_pubkey_y | u8[48] | The Y BigNum of the ECDSA public key associated with the signing key. |
26993211 | signature_r | u8[48] | The R BigNum of an ECDSA signature. |
27003212 | signature_s | u8[48] | The S BigNum of an ECDSA signature. |
27013213
27023214
2703-The `exported_cdi` can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
3215+The `exported_cdi_handle` can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
3216+
3217+### SIGN\_WITH\_EXPORTED\_MLDSA
3218+
3219+Command Code: `0x5357_4D4C` ("SWML")
3220+
3221+**Note**: This command is only available in the locality of the PL0 PAUSER.
3222+
3223+*Table: `SIGN_WITH_EXPORTED_MLDSA` input arguments*
3224+
3225+| **Name** | **Type** | **Description** |
3226+| -------- | -------- | --------------- |
3227+| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
3228+| exported_cdi_handle | u8[32] | The exported CDI handle returned by the DPE `DeriveContext` command. Opaque byte array; copy the bytes exactly as returned. |
3229+| sign_type | u32 | Signing mode selector. `0` = `Mu` (64-byte pre-hash input), `1` = `Raw` (arbitrary byte array input). |
3230+| 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. |
3231+| 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. |
3232+
3233+
3234+*Table: `SIGN_WITH_EXPORTED_MLDSA` output arguments*
3235+
3236+| **Name** | **Type** | **Description** |
3237+| -------- | -------- | --------------- |
3238+| derived_pubkey | u8[2592] | The ML-DSA public key derived from the exported CDI handle and the DPE environment. |
3239+| signature | u8[4627] | The ML-DSA signature produced by the derived key. |
3240+
3241+
3242+The `exported_cdi_handle` can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
3243+
3244+This command derives an ML-DSA key pair from the provided exported CDI handle and signs either:
3245+
3246+- a 64-byte `Mu` message digest, or
3247+- a `Raw` message payload of up to 1024 bytes.
3248+
3249+The command performs the signing under PL0-only access control and returns the derived public key together with the signature.
27043250
27053251 ### REVOKE\_EXPORTED\_CDI\_HANDLE
27063252
@@ -2710,16 +3256,47 @@
27103256
27113257 *Table: `REVOKE_EXPORTED_CDI_HANDLE` input arguments*
27123258
2713-| **Name** | **Type** | **Description**
2714-| -------- | -------- | ---------------
3259+| **Name** | **Type** | **Description** |
3260+| -------- | -------- | --------------- |
27153261 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
2716-| exported_cdi_handle | u8[32] | The Exported CDI handle returned by the DPE `DeriveContext` command. Little endian. |
2717-
2718-
2719-The `exported_cdi` can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
3262+| exported_cdi_handle | u8[32] | The exported CDI handle returned by the DPE `DeriveContext` command. Opaque byte array; copy the bytes exactly as returned. |
3263+
3264+
3265+The `exported_cdi_handle` can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
27203266
27213267 The `exported_cdi_handle` is no longer usable after calling `REVOKE_EXPORTED_CDI_HANDLE` with it. After the `exported_cdi_handle`
2722-has been revoked, a new exported CDI can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
3268+has been revoked, a new exported CDI handle can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
3269+
3270+### EXTERNAL_MAILBOX_CMD
3271+
3272+Command Code: `0x4558_544D` ("EXTM")
3273+
3274+**Important restrictions:**
3275+- This command is only available in subsystem mode in 2.1+.
3276+- This command is only available for MCU.
3277+
3278+Executes a mailbox command located at an AXI address.
3279+This allows for executing mailbox commands that are larger than the mailbox allows.
3280+
3281+This is currently mostly useful for FIRMWARE_LOAD (as part of an update) or SET_AUTH_MANIFEST.
3282+
3283+The response is still written to the mailbox.
3284+
3285+The checksum is over the EXTM command, *not* the command that is loaded over AXI.
3286+That external command will still need its own checksum, if applicable.
3287+
3288+*Table: `EXTERNAL_MAILBOX_CMD` input arguments*
3289+
3290+| **Name** | **Type** | **Description** |
3291+| -------- | -------- | --------------- |
3292+| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
3293+| command_id | u32 | Command ID for the mailbox command to be executed. Little endian. |
3294+| command_size | u32 | Size of the mailbox command to be executed. Little endian. |
3295+| axi_address_low | u32 | Lower 32 bits of the AXI address that contains the mailbox command. Little endian. |
3296+| axi_address_high | u32 | High 32 bits of the AXI address that contains the mailbox command. Little endian. |
3297+
3298+
3299+The response will be the response of the executed external command.
27233300
27243301 ### REALLOCATE\_DPE\_CONTEXT\_LIMITS
27253302
@@ -2729,24 +3306,119 @@
27293306
27303307 *Table: `REALLOCATE_DPE_CONTEXT_LIMITS` input arguments*
27313308
2732-| **Name** | **Type** | **Description**
2733-| -------- | -------- | ---------------
3309+| **Name** | **Type** | **Description** |
3310+| -------- | -------- | --------------- |
27343311 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
27353312 | pl0_context_limit | u32 | Number of contexts to allocate to PL0. PL1 will receive remaining contexts. |
27363313
27373314
27383315 *Table: `REALLOCATE_DPE_CONTEXT_LIMITS` output arguments*
2739-| **Name** | **Type** | **Description**
2740-| -------- | -------- | ---------------
3316+| **Name** | **Type** | **Description** |
3317+| -------- | -------- | --------------- |
27413318 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
27423319 | fips_status | u32 | Indicates if the command is FIPS approved or an error. |
27433320 | new_pl0_context_limit | u32 | Number of contexts assigned to PL0 after the reallocation |
27443321 | new_pl1_context_limit | u32 | Number of contexts assigned to PL1 after the reallocation |
27453322
27463323
2747-This allows the user to reallocate the 32 DPE contexts between PL0 and PL1. By default, each gets 16 contexts.
3324+This allows the user to reallocate the 64 DPE contexts between PL0 and PL1. By default, each gets 32 contexts.
27483325
27493326 **Note**: 2 PL0 contexts are used by Caliptra itself during initialization.
3327+
3328+### FE\_PROG
3329+
3330+Programs Field Entropy (FE) into one of 4 FE partitions in the OTP fuse controller. This command
3331+is typically used during device provisioning flows.
3332+
3333+**Note**: This command is only available when the device is in the **Production** lifecycle state.
3334+
3335+Command Code: `0x4645_5052` ("FEPR")
3336+
3337+*Table: `FE_PROG` input arguments*
3338+
3339+| **Name** | **Type** | **Description**
3340+| -------- | -------- | ---------------
3341+| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian.
3342+| partition | u32 | FE partition number (valid values: 0–3).
3343+
3344+`FE_PROG` returns no output arguments other than the mailbox response header.
3345+
3346+### PRODUCTION\_AUTH\_DEBUG\_UNLOCK\_REQ
3347+
3348+Initiates the production debug unlock flow by generating a cryptographic challenge. The caller
3349+must solve the challenge by signing it with the appropriate ECC and MLDSA keys and returning
3350+the result via the [`PRODUCTION_AUTH_DEBUG_UNLOCK_TOKEN`](#production_auth_debug_unlock_token)
3351+command.
3352+
3353+This command performs the same function as the ROM's `AUTH_DEBUG_UNLOCK_REQ` command
3354+(documented in the [ROM README](../rom/dev/README.md#debug-unlock)), but is available at
3355+runtime.
3356+
3357+**Note**: This command requires the device to be in the **Production** lifecycle state and the
3358+`PROD_DEBUG_UNLOCK_REQ` bit in the `SS_DBG_MANUF_SERVICE_REG_REQ` register to be set.
3359+
3360+Command Code: `0x5044_5552` ("PDUR")
3361+
3362+*Table: `PRODUCTION_AUTH_DEBUG_UNLOCK_REQ` input arguments*
3363+
3364+| **Name** | **Type** | **Description**
3365+| -------- | -------- | ---------------
3366+| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian.
3367+| length | u32 | Length of the payload in DWORDs.
3368+| unlock\_level | u8 | Debug unlock level (1–8).
3369+| reserved | u8[3] | Reserved.
3370+
3371+*Table: `PRODUCTION_AUTH_DEBUG_UNLOCK_REQ` output arguments*
3372+
3373+| **Name** | **Type** | **Description**
3374+| -------- | -------- | ---------------
3375+| chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian.
3376+| fips\_status | u32 | Indicates if the command is FIPS approved or an error.
3377+| length | u32 | Length of the response payload in DWORDs.
3378+| unique\_device\_identifier | u8[32] | Device identifier of the Caliptra device. Byte array; pass through as-is to the token command.
3379+| challenge | u8[48] | Random challenge number generated by Caliptra. Byte array; pass through as-is to the token command.
3380+
3381+### PRODUCTION\_AUTH\_DEBUG\_UNLOCK\_TOKEN
3382+
3383+Completes the production debug unlock handshake by validating the caller's solution to the
3384+challenge generated by
3385+[`PRODUCTION_AUTH_DEBUG_UNLOCK_REQ`](#production_auth_debug_unlock_req). The caller must
3386+provide the device identifier and challenge from the previous request along with ECC-384 and
3387+ML-DSA-87 signatures proving possession of the authorized debug unlock key.
3388+
3389+Upon successful validation, Caliptra authorizes the debug unlock by setting the unlock level
3390+in the `SS_SOC_DBG_UNLOCK_LEVEL` register.
3391+
3392+This command performs the same function as the ROM's `AUTH_DEBUG_UNLOCK_TOKEN` command
3393+(documented in the [ROM README](../rom/dev/README.md#debug-unlock)), but is available at
3394+runtime.
3395+
3396+**Note**: This command requires a preceding successful `PRODUCTION_AUTH_DEBUG_UNLOCK_REQ` in
3397+the same boot session. The challenge is consumed on use and cannot be replayed.
3398+
3399+Command Code: `0x5044_5554` ("PDUT")
3400+
3401+*Table: `PRODUCTION_AUTH_DEBUG_UNLOCK_TOKEN` input arguments*
3402+
3403+| **Name** | **Type** | **Description**
3404+| -------- | -------- | ---------------
3405+| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian.
3406+| length | u32 | Length of the payload in DWORDs.
3407+| unique\_device\_identifier | u8[32] | Device identifier (must match value from challenge response). Byte array; copied verbatim from the challenge response.
3408+| unlock\_level | u8 | Debug unlock level (1–8, must match the original request).
3409+| reserved | u8[3] | Reserved.
3410+| challenge | u8[48] | Challenge (must match value from challenge response). Byte array; copied verbatim from the challenge response.
3411+| 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).
3412+| mldsa\_public\_key | u8[2592] | ML-DSA-87 public key. See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields).
3413+| 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).
3414+| 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).
3415+
3416+The signed message for both ECC and ML-DSA signatures is the hash of the concatenation:
3417+`unique_device_identifier || unlock_level || reserved || challenge` (all as raw bytes).
3418+ECC uses SHA2-384; ML-DSA uses SHA2-512.
3419+
3420+`PRODUCTION_AUTH_DEBUG_UNLOCK_TOKEN` returns no output arguments other than the mailbox
3421+response header.
27503422
27513423 ## Checksum
27523424
@@ -2770,15 +3442,15 @@
27703442
27713443 ## FIPS status
27723444
2773-For every command, the firmware responds with a FIPS status of FIPS approved. There is
2774-currently no use case for any other responses or error values.
3445+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.
27753446
27763447 *Table: FIPS status codes*
27773448
27783449 | **Name** | **Value** | Description |
27793450 | --------------- | --------------------------- | --------------------------------------------------- |
27803451 | `FIPS_APPROVED` | `0x0000_0000` | Status of command is FIPS approved |
2781-| `RESERVED` | `0x0000_0001 - 0xFFFF_FFFF` | Other values reserved, will not be sent by Caliptra |
3452+| `FIPS_NOT_APPROVED_USER_SUPPLIED_DIGEST` | `0x5553_5244` | Command is not FIPS approved because the caller supplied the digest instead of the raw message |
3453+| `RESERVED` | `0x0000_0002 - 0xFFFF_FFFF` | Other values reserved, will not be sent by Caliptra |
27823454
27833455
27843456 ## Runtime Firmware updates
@@ -2857,14 +3529,14 @@
28573529 To prevent this, we establish active context limits for each PAUSER
28583530 privilege level:
28593531
2860-* PL0 - 16 active contexts
2861-* PL1 - 16 active contexts
3532+* PL0 - 32 active contexts
3533+* PL1 - 32 active contexts
28623534
28633535 If a DPE command were to activate a new context such that the total number of
28643536 active contexts in a privilege level is above its active context limit, the
28653537 InvokeDpe command should fail.
28663538
2867-At boot Caliptra Runtime FW consumes part of the PL0 active contexts (initially 16) to DeriveContext for:
3539+At boot Caliptra Runtime FW consumes part of the PL0 active contexts (initially 32) to DeriveContext for:
28683540 - RTFW Journey (RTFJ) Measurement (1)
28693541 - Caliptra Configured Initialization Values digest (CCIV) (1)
28703542 - ROM Stashed Measurements (max 8)
@@ -2872,20 +3544,20 @@
28723544 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
28733545 of active contexts in PL0's locality, and hence allow PL1 to DOS PL0.
28743546
2875-### DPE profile implementation
2876-
2877-The DPE iRoT profile leaves some choices up to implementers. This section
2878-describes specific requirements for the Caliptra DPE implementation.
3547+### Caliptra DPE Profile
3548+
3549+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.
28793550
28803551 | Name | Value | Description |
28813552 | -------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------ |
2882-| Profile Variant | `DPE_PROFILE_IROT_P384_SHA384` | The profile variant that Caliptra implements. |
3553+| Profile Variant | `Caliptra DPE Profile` | Derived from `DPE_PROFILE_IROT_P384_SHA384`. |
28833554 | KDF | SP800-108 HMAC-CTR | KDF to use for CDI (tcg.derive.kdf-sha384) and asymmetric key (tcg.derive.kdf-sha384-p384) derivation. |
28843555 | Simulation Context Support | Yes | Whether Caliptra implements the optional Simulation Contexts feature. |
28853556 | Supports ExtendTci | Yes | Whether Caliptra implements the optional ExtendTci command. |
28863557 | Supports Auto Init | Yes | Whether Caliptra will automatically initialize the default DPE context. |
28873558 | Supports Rotate Context | Yes | Whether Caliptra supports the optional RotateContextHandle command. |
28883559 | CertifyKey Alias Key | Caliptra Runtime Alias Key | The key that will be used to sign certificates that are produced by the DPE CertifyKey command. |
3560+| `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. |
28893561
28903562
28913563 ### Supported DPE commands
@@ -2896,6 +3568,7 @@
28963568 * InitializeContext
28973569 * DeriveContext
28983570 * **Note**: The "export-cdi" flag is only available in the locality of the PL0 PAUSER.
3571+ * **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.
28993572 * CertifyKey
29003573 * Caliptra DPE supports two formats for CertifyKey: X.509 and PKCS#10 CSR.
29013574 X.509 is only available to PL0 PAUSERs.