Changes to Runtime Specification

Comparing version 2.1 to 2.0
+812 additions -160 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/1b5589b23cfc2957a3c5934792643babc599aabc/runtime/README.md" target="_blank">chipsalliance/caliptra-sw/runtime/README.md</a> @ <code>1b5589b</code>
2+📄 Source: <a href="https://github.com/chipsalliance/caliptra-sw/blob/f2cc79ad8fb1c36a6bd29ac1c872ce23af74fd94/runtime/README.md" target="_blank">chipsalliance/caliptra-sw/runtime/README.md</a> @ <code>f2cc79a</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
@@ -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,12 +1026,42 @@
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.
8951031
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.
1059+
8961060 ### EXTEND\_PCR
8971061
898-Extends a Caliptra hardware PCR.
1062+Extends a Caliptra hardware PCR. This command is restricted to the PL0 PAUSER.
1063+PCR0 through PCR3 are reserved and cannot be extended with this command. PCR31
1064+is available to PL0 for MCU-managed SoC firmware measurements.
8991065
9001066 Command Code: `0x5043_5245` ("PCRE")
9011067
@@ -1161,35 +1327,69 @@
11611327 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian.
11621328 | fips\_status | u32 | Indicates if the command is FIPS approved or an error.
11631329
1164-### CERTIFY\_KEY\_EXTENDED
1165-
1166-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.
11671333
11681334 Command Code: `0x434B_4558` ("CKEX")
11691335
1170-*Table: `CERTIFY_KEY_EXTENDED` input arguments*
1336+*Table: `CERTIFY_KEY_EXTENDED_ECC384` input arguments*
11711337
11721338 | **Name** | **Type** | **Description** |
11731339 | ----------------- | -------- | --------------------------------------------------------------------------- |
11741340 | 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. |
11751342 | certify\_key\_req | u8[72] | Certify Key Request. |
1176-| flags | u32 | Flags determining which custom extensions to include in the certificate. |
1177-
1178-
1179-*Table: `CERTIFY_KEY_EXTENDED` input flags*
1343+
1344+
1345+*Table: `CERTIFY_KEY_EXTENDED_ECC384` input flags*
11801346
11811347 | **Name** | **Offset** |
1182-| --------------- | ---------- |
1183-| DMTF_OTHER_NAME | 1 << 31 |
1184-
1185-
1186-*Table: `CERTIFY_KEY_EXTENDED` output arguments*
1187-
1188-| **Name** | **Type** | **Description** |
1189-| ------------------ | -------- | -------------------------------------------------------------------------- |
1348+| ----------------- | ---------- |
1349+| DMTF\_OTHER\_NAME | 1 << 31 |
1350+
1351+
1352+*Table: `CERTIFY_KEY_EXTENDED_ECC384` output arguments*
1353+
1354+| **Name** | **Type** | **Description** |
1355+| ------------------ | --------- | -------------------------------------------------------------------------- |
11901356 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
11911357 | fips\_status | u32 | Indicates if the command is FIPS approved or an error. |
1192-| 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. |
11931393
11941394
11951395 ### CERTIFY\_KEY\_CHUNKS
@@ -1241,26 +1441,26 @@
12411441
12421442 *Table: `SET_AUTH_MANIFEST` input arguments*
12431443
1244-| **Name** | **Type** | **Description**
1245-| -------- | -------- | ---------------
1444+| **Name** | **Type** | **Description** |
1445+| -------- | -------- | --------------- |
12461446 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
12471447 | manifest size | u32 | The size of the full Authentication Manifest |
12481448 | preamble\_marker | u32 | Marker needs to be 0x4154_4D4E for the preamble to be valid |
12491449 | preamble\_size | u32 | Size of the preamble |
12501450 | preamble\_version | u32 | Version of the preamble |
12511451 | preamble\_flags | u32 | Manifest flags. See AUTH_MANIFEST_FLAGS below |
1252-| preamble\_vendor\_ecc384\_key | u32[24] | Vendor ECC384 key with X and Y coordinates in that order |
1253-| preamble\_vendor\_pqc\_key | u32[648] | Vendor MLDSA-87 or LMS-SHA192-H15 key |
1254-| preamble\_vendor\_ecc384\_sig | u32[24] | Vendor ECC384 signature |
1255-| preamble\_vendor\_PQC\_sig | u32[1157] | Vendor MLDSA-87 or LMOTS-SHA192-W4 signature |
1256-| preamble\_owner\_ecc384\_key | u32[24] | Owner ECC384 key with X and Y coordinates in that order |
1257-| preamble\_owner\_pqc\_key | u32[648] | Owner MLDSA-87 or LMS-SHA192-H15 key |
1258-| preamble\_owner\_ecc384\_sig | u32[24] | Owner ECC384 signature |
1259-| preamble\_owner\_PQC\_sig | u32[1157] | Owner MLDSA-87 or LMOTS-SHA192-W4 signature |
1260-| metadata\_vendor\_ecc384\_sig | u32[24] | Metadata Vendor ECC384 signature |
1261-| metadata\_vendor\_PQC\_sig | u32[1157] | Metadata Vendor MLDSA-87 or LMOTS-SHA192-W4 signature |
1262-| metadata\_owner\_ecc384\_sig | u32[24] | Metadata Owner ECC384 signature |
1263-| metadata\_owner\_PQC\_sig | u32[1157] | Metadata Owner MLDSA-87 or LMOTS-SHA192-W4 signature |
1452+| 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). |
1453+| 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). |
1454+| preamble\_vendor\_ecc384\_sig | u32[24] | Vendor ECC384 signature. See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields). |
1455+| 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). |
1456+| 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). |
1457+| 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). |
1458+| preamble\_owner\_ecc384\_sig | u32[24] | Owner ECC384 signature. See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields). |
1459+| 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). |
1460+| metadata\_vendor\_ecc384\_sig | u32[24] | Metadata Vendor ECC384 signature. See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields). |
1461+| 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). |
1462+| metadata\_owner\_ecc384\_sig | u32[24] | Metadata Owner ECC384 signature. See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields). |
1463+| 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). |
12641464 | metadata\_entry\_entry\_count | u32 | number of metadata entries |
12651465 | metadata\_entries | Metadata[80] | The max number of metadata entries is 80 but less can be used |
12661466
@@ -1283,17 +1483,17 @@
12831483 | **Name** | **Type** | **Description** |
12841484 | ------------------------ | --------- | ---------------- |
12851485 | Image Hash | u8[48] | SHA2-384 hash of a SOC image. |
1286-
1287-| 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)
1288-| 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)
1289-| 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)
1290-| 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)
1291-| 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)
1292-| 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)
1293-| 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)
1294-| 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)
1295-| 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)
1296-| 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)
1486+| 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) |
1487+| 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) |
1488+| flags | u32 | This corresponds to the `flags` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main/auth-manifest/README.md) |
1489+| 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) |
1490+| 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) |
1491+| 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) |
1492+| 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) |
1493+| Classification | u32 | This corresponds to the `Classification` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main/auth-manifest/README.md) |
1494+| 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) |
1495+| 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) |
1496+
12971497
12981498 ### VERIFY_AUTH_MANIFEST
12991499
@@ -1359,8 +1559,8 @@
13591559
13601560 *Table: `AUTHORIZE_AND_STASH` input arguments*
13611561
1362-| **Name** | **Type** | **Description**
1363-| ------------| -------- | ---------------
1562+| **Name** | **Type** | **Description** |
1563+| ------------ | -------- | --------------- |
13641564 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
13651565 | fw_id | u8[4] | Firmware id of the image, in little-endian format |
13661566 | 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. |
@@ -1400,8 +1600,8 @@
14001600 | **Name** | **Type** | **Description** |
14011601 | -------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
14021602 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
1403-
1404-| fw_id | u32 | Firmware id of the image, in little-endian format
1603+| fw_id | u32 | Firmware id of the image, in little-endian format |
1604+
14051605
14061606 *Table: `GET_IMAGE_INFO` output arguments*
14071607
@@ -1409,13 +1609,36 @@
14091609 | -------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
14101610 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
14111611 | fips_status | u32 | Indicates if the command is FIPS approved or an error. |
1412-| 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) |
1413-| 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) |
1414-| 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) |
1415-| 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) |
1416-| 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) |
1417-| 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) |
1612+| 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) |
1613+| flags | u32 | This corresponds to the `flags` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main/auth-manifest/README.md) |
1614+| 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) |
1615+| 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) |
1616+| 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) |
1617+| 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) |
14181618 | digest | u8[48] | SHA-384 digest of the image. **Only present in FW 2.0.2+ and 2.1.1+.** |
1619+
1620+
1621+### GET\_MCU\_FW\_SIZE
1622+
1623+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.
1624+
1625+Command Code: `0x474D_4653` ("GMFS")
1626+
1627+*Table: `GET_MCU_FW_SIZE` input arguments*
1628+
1629+| **Name** | **Type** | **Description** |
1630+| -------------- | -------------- | --------------------------------------------------------------------------- |
1631+| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
1632+
1633+
1634+*Table: `GET_MCU_FW_SIZE` output arguments*
1635+
1636+| **Name** | **Type** | **Description** |
1637+| -------------- | -------------- | -------------------------------------------------------------------------- |
1638+| chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
1639+| fips_status | u32 | Indicates if the command is FIPS approved or an error. |
1640+| size | u32 | Size of the MCU firmware image in bytes. |
1641+| sha384 | u8[48] | SHA-384 digest of the encrypted MCU firmware image. |
14191642
14201643
14211644 ### ACTIVATE_FIRMWARE
@@ -1433,7 +1656,43 @@
14331656 | count | u32 | Number of image_ids to activate. Item count of image_ids array parameter |
14341657 | mcu_image_size | u32 | Size of MCU image, if included in the activation |
14351658 | image_ids | Array of u8[4] | Array of Image ids in little-endian format |
1436-
1659+| flags | u32 | Optional flags (see below). Caliptra runtime 2.1.1+ only. |
1660+
1661+
1662+*Flags*
1663+
1664+| **Bit** | **Name** | **Description** |
1665+| ------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------ |
1666+| 0 | `INITIAL_ACTIVATE` | First-time MCU activation after the encrypted-boot flow. Caliptra runtime 2.1.1+ only. See below. |
1667+
1668+
1669+Unknown flag bits are rejected with `RUNTIME_MAILBOX_INVALID_PARAMS`.
1670+
1671+`INITIAL_ACTIVATE` is used exclusively by MCU ROM at the tail of the
1672+`EncryptedFirmware` boot flow. MCU ROM has already loaded firmware into MCU
1673+SRAM via `RI_DOWNLOAD_ENCRYPTED_FIRMWARE` and decrypted it in place via
1674+`CM_AES_GCM_DECRYPT_DMA`. When this flag is set, Caliptra Runtime:
1675+
1676+- Skips the hitless-update steps (set `RESET_REASON.FwHitlessUpd`, clear
1677+ `FW_EXEC_CTRL`, wait for MCU reset request and reset assertion, DMA-reload
1678+ from staging, re-`AuthorizeAndStash`).
1679+- Just publishes `FW_EXEC_CTRL[MCU]` (and any other requested bits) so that
1680+ MCI's `BOOT_RST_MCU` state releases MCU from reset on the next warm reset
1681+ that MCU ROM triggers.
1682+
1683+Caliptra Runtime only honors `INITIAL_ACTIVATE` when **all** of the following
1684+are true; otherwise the command fails with `IMAGE_VERIFIER_ACTIVATION_FAILED`:
1685+
1686+1. The MCU image bit is included in the activation request.
1687+2. The boot mode set by ROM is `EncryptedFirmware` (i.e., ROM received
1688+ `RI_DOWNLOAD_ENCRYPTED_FIRMWARE`).
1689+3. `FW_EXEC_CTRL[MCU]` is currently `0` — this is an initial activation,
1690+ not a hitless update masquerading as one.
1691+
1692+Together, these checks ensure that the MCU SRAM contents are
1693+integrity-protected end-to-end (ciphertext digest verified during recovery;
1694+GCM tag verified during `CM_AES_GCM_DECRYPT_DMA`) before Caliptra releases
1695+MCU to execute them.
14371696
14381697 *Table: `ACTIVATE_FIRMWARE` output arguments*
14391698
@@ -1442,6 +1701,28 @@
14421701 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
14431702 | fips_status | u32 | Indicates if the command is FIPS approved or an error. |
14441703
1704+
1705+## Mailbox commands: OCP LOCK v1.0
1706+
1707+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).
1708+
1709+### ENUMERATE_HPKE_HANDLES
1710+### REPORT_HEK_METADATA
1711+### GET_ALGORITHMS
1712+### INITIALIZE_MEK_SECRET
1713+### ROTATE_HPKE_KEY
1714+### GENERATE_MEK
1715+### GENERATE_MPK
1716+### REWRAP_MPK
1717+### ENABLE_MPK
1718+### MIX_MPK
1719+### GET_HPKE_PUB_KEY
1720+### TEST_ACCESS_KEY
1721+### GET_STATUS
1722+### CLEAR_KEY_CACHE
1723+### UNLOAD_MEK
1724+### LOAD_MEK
1725+### DERIVE_MEK
14451726
14461727 ## Mailbox commands: Cryptographic Mailbox (2.0)
14471728
@@ -1545,6 +1826,99 @@
15451826 | fips_status | u32 | FIPS approved or an error |
15461827 | hash size | u32 ||
15471828 | hash | u8[hash size] ||
1829+
1830+
1831+### CM\_SHAKE256\_INIT
1832+
1833+This starts the computation of a SHAKE256 extendable-output hash, which may be larger than a single mailbox command allows.
1834+
1835+**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.
1836+
1837+The sequence to use these are:
1838+* 1 `CM_SHAKE256_INIT` command
1839+* 0 or more `CM_SHAKE256_UPDATE` commands
1840+* 1 `CM_SHAKE256_FINAL` command
1841+
1842+For each command, the context from the previous command's output must be passed as an input.
1843+
1844+The `SHAKE256_CONTEXT_SIZE` is always exactly 44 bytes long (encrypted session token).
1845+
1846+The maximum supported input data size per command is 4096 bytes.
1847+
1848+Command Code: `0x434D_5849` ("CMXI")
1849+
1850+*Table: `CM_SHAKE256_INIT` input arguments*
1851+
1852+| **Name** | **Type** | **Description** |
1853+| --------- | ------------- | --------------- |
1854+| chksum | u32 ||
1855+| data size | u32 ||
1856+| data | u8[data size] | Data to hash |
1857+
1858+
1859+*Table: `CM_SHAKE256_INIT` output arguments*
1860+
1861+| **Name** | **Type** | **Description** |
1862+| ----------- | ------------------------- | -------------------------------------------------- |
1863+| chksum | u32 ||
1864+| fips_status | u32 | FIPS approved or an error |
1865+| context | u8[SHAKE256_CONTEXT_SIZE] | Passed to `CM_SHAKE256_UPDATE` / `CM_SHAKE256_FINAL` |
1866+
1867+
1868+### CM\_SHAKE256\_UPDATE
1869+
1870+This continues a SHAKE256 computation started by `CM_SHAKE256_INIT` or from another `CM_SHAKE256_UPDATE`.
1871+
1872+The context MUST be passed in from `CM_SHAKE256_INIT` or `CM_SHAKE256_UPDATE`.
1873+
1874+Command Code: `0x434D_5855` ("CMXU")
1875+
1876+*Table: `CM_SHAKE256_UPDATE` input arguments*
1877+
1878+| **Name** | **Type** | **Description** |
1879+| --------- | ------------------------- | ---------------------------------------------------- |
1880+| chksum | u32 ||
1881+| context | u8[SHAKE256_CONTEXT_SIZE] | From `CM_SHAKE256_INIT` / `CM_SHAKE256_UPDATE` |
1882+| data size | u32 ||
1883+| data | u8[data size] | Data to hash |
1884+
1885+
1886+*Table: `CM_SHAKE256_UPDATE` output arguments*
1887+
1888+| **Name** | **Type** | **Description** |
1889+| ----------- | ------------------------- | -------------------------------------------------- |
1890+| chksum | u32 ||
1891+| fips_status | u32 | FIPS approved or an error |
1892+| context | u8[SHAKE256_CONTEXT_SIZE] | Passed to `CM_SHAKE256_UPDATE` / `CM_SHAKE256_FINAL` |
1893+
1894+
1895+### CM\_SHAKE256\_FINAL
1896+
1897+This finalizes the SHAKE256 computation and produces the hash of all of the data.
1898+
1899+The context MUST be passed in from `CM_SHAKE256_INIT` or `CM_SHAKE256_UPDATE`.
1900+
1901+The output is always a 64-byte SHAKE256 digest.
1902+
1903+Command Code: `0x434D_5846` ("CMXF")
1904+
1905+*Table: `CM_SHAKE256_FINAL` input arguments*
1906+
1907+| **Name** | **Type** | **Description** |
1908+| ----------- | ------------------------- | ---------------------------------------------- |
1909+| chksum | u32 ||
1910+| context | u8[SHAKE256_CONTEXT_SIZE] | From `CM_SHAKE256_INIT` / `CM_SHAKE256_UPDATE` |
1911+| data size | u32 | May be 0 |
1912+| data | u8[data size] | Data to hash |
1913+
1914+
1915+*Table: `CM_SHAKE256_FINAL` output arguments*
1916+
1917+| **Name** | **Type** | **Description** |
1918+| ----------- | -------- | ------------------------- |
1919+| chksum | u32 ||
1920+| fips_status | u32 | FIPS approved or an error |
1921+| hash | u8[64] | SHAKE256 digest |
15481922
15491923
15501924 ### CM\_HMAC
@@ -1787,7 +2161,7 @@
17872161
17882162 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.
17892163
1790-Command Code: `0x434D_5D53` ("CMES")
2164+Command Code: `0x434D_4553` ("CMES")
17912165
17922166 *Table: `CM_ECDSA_SIGN` input arguments*
17932167 | **Name** | **Type** | **Description** |
@@ -1835,6 +2209,79 @@
18352209 | fips_status | u32 | FIPS approved or an error |
18362210
18372211
2212+### CM_MLKEM_KEY_GEN
2213+
2214+Generates an ML-KEM-1024 encapsulation key from the seed (seed\_d || seed\_z, 64 bytes) stored in a CMK with key usage `Mlkem`.
2215+
2216+The key generation algorithm is described in [FIPS 203](https://csrc.nist.gov/pubs/fips/203/final).
2217+
2218+Command Code: `0x434D_4C4B` ("CMLK")
2219+
2220+*Table: `CM_MLKEM_KEY_GEN` input arguments*
2221+| **Name** | **Type** | **Description** |
2222+| -------- | -------- | ---------------------------------------- |
2223+| chksum | u32 ||
2224+| CMK | CMK | ML-KEM seed (seed\_d &#124;&#124; seed\_z) |
2225+
2226+
2227+*Table: `CM_MLKEM_KEY_GEN` output arguments*
2228+| **Name** | **Type** | **Description** |
2229+| ----------- | -------- | ---------------------------------------- |
2230+| chksum | u32 ||
2231+| fips_status | u32 | FIPS approved or an error |
2232+| encaps_key | u8[1568] | ML-KEM-1024 encapsulation key |
2233+
2234+
2235+### CM_MLKEM_ENCAPSULATE
2236+
2237+Performs ML-KEM-1024 encapsulation against the provided encapsulation key, producing a ciphertext and a shared key wrapped as a CMK.
2238+
2239+The encapsulation algorithm is described in [FIPS 203](https://csrc.nist.gov/pubs/fips/203/final).
2240+
2241+Command Code: `0x434D_4C45` ("CMLE")
2242+
2243+*Table: `CM_MLKEM_ENCAPSULATE` input arguments*
2244+| **Name** | **Type** | **Description** |
2245+| ----------- | -------- | ---------------------------------------- |
2246+| chksum | u32 ||
2247+| key_usage | u32 | Key usage for the output CMK |
2248+| encaps_key | u8[1568] | ML-KEM-1024 encapsulation key |
2249+
2250+
2251+*Table: `CM_MLKEM_ENCAPSULATE` output arguments*
2252+| **Name** | **Type** | **Description** |
2253+| ----------- | -------- | ---------------------------------------- |
2254+| chksum | u32 ||
2255+| fips_status | u32 | FIPS approved or an error |
2256+| ciphertext | u8[1568] | ML-KEM-1024 ciphertext |
2257+| shared_key | CMK | CMK of the shared secret key |
2258+
2259+
2260+### CM_MLKEM_DECAPSULATE
2261+
2262+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.
2263+
2264+The decapsulation algorithm is described in [FIPS 203](https://csrc.nist.gov/pubs/fips/203/final).
2265+
2266+Command Code: `0x434D_4C44` ("CMLD")
2267+
2268+*Table: `CM_MLKEM_DECAPSULATE` input arguments*
2269+| **Name** | **Type** | **Description** |
2270+| ----------- | -------- | ---------------------------------------- |
2271+| chksum | u32 ||
2272+| key_usage | u32 | Key usage for the output CMK |
2273+| CMK | CMK | ML-KEM seed (seed\_d &#124;&#124; seed\_z) |
2274+| ciphertext | u8[1568] | ML-KEM-1024 ciphertext to decapsulate |
2275+
2276+
2277+*Table: `CM_MLKEM_DECAPSULATE` output arguments*
2278+| **Name** | **Type** | **Description** |
2279+| ----------- | -------- | ---------------------------------------- |
2280+| chksum | u32 ||
2281+| fips_status | u32 | FIPS approved or an error |
2282+| shared_key | CMK | CMK of the shared secret key |
2283+
2284+
18382285 ### CM_AES_ENCRYPT_INIT
18392286
18402287 Generic AES operation for unauthenticated AES operations.
@@ -1847,7 +2294,7 @@
18472294
18482295 The CMK must have been created for AES usage.
18492296
1850-Command Code: `0x434D_4349` ("CMCI")
2297+Command Code: `0x434D_4149` ("CMAI")
18512298
18522299 *Table: `CM_AES_ENCRYPT_INIT` input arguments*
18532300 | **Name** | **Type** | **Description** |
@@ -1881,8 +2328,7 @@
18812328 | mode | u32 ||
18822329 | key | u8[32] ||
18832330 | iv | u8[16] ||
1884-| fips_status | u8 | 1 = FIPS valid |
1885-| reserved | u8[75] | Reserved for additional fields |
2331+| reserved | u8[76] | Reserved for additional fields |
18862332
18872333
18882334 The size of the (encrypted) context is always exactly 156 bytes,
@@ -1899,7 +2345,7 @@
18992345 For CBC, the size must be a multiple of 16 bytes.
19002346 CTR mode supports input of any size up to the maximum cryptographic mailbox size.
19012347
1902-Command Code: `0x434D_4355` ("CMCU")
2348+Command Code: `0x434D_4155` ("CMAU")
19032349
19042350 *Table: `CM_AES_ENCRYPT_UPDATE` input arguments*
19052351 | **Name** | **Type** | **Description** |
@@ -1970,7 +2416,7 @@
19702416 For CBC, the size must be a multiple of 16 bytes.
19712417 CTR mode supports input of any size up to the maximum cryptographic mailbox size.
19722418
1973-Command Code: `0x434D_4155` ("CMAU")
2419+Command Code: `0x434D_4156` ("CMAV")
19742420
19752421 *Table: `CM_AES_DECRYPT_UPDATE` input arguments*
19762422 | **Name** | **Type** | **Description** |
@@ -2031,8 +2477,7 @@
20312477 | GHASH state | u8[16] ||
20322478 | current length | u32 | value mod 16 is buffer size |
20332479 | buffer | u8[16] ||
2034-| fips_status | u8 | 1 = FIPS valid |
2035-| reserved | u8[15] ||
2480+| reserved | u8[16] ||
20362481
20372482
20382483 The size of the (encrypted) context is always exactly 128 bytes,
@@ -2188,7 +2633,7 @@
21882633
21892634 The encrypted and authenticated context's internal structure will be the same as for encryption.
21902635
2191-### CM_AES_SPDM_GCM_DECRYPT_INIT
2636+### CM_AES_GCM_SPDM_DECRYPT_INIT
21922637
21932638 Starts an AES-256-GCM decryption computation in SPDM mode.
21942639
@@ -2304,6 +2749,45 @@
23042749 | plaintext | u8[plaintext size] ||
23052750
23062751
2752+### CM_AES_GCM_DECRYPT_DMA
2753+
2754+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.
2755+
2756+**Important restrictions:**
2757+- This command is only available in subsystem mode, as DMA is only available in subsystem.
2758+- This command is only available for MCU.
2759+- 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.
2760+- The command performs a two-pass operation:
2761+ 1. First pass: Verifies the SHA384 hash of the encrypted data at the AXI address
2762+ 2. Second pass: Performs in-place AES-GCM decryption via DMA
2763+
2764+The CMK must be an AES key (key usage = 3) that was previously imported using `CM_IMPORT`.
2765+
2766+Command Code: `0x434D_4444` ("CMDD")
2767+
2768+*Table: `CM_AES_GCM_DECRYPT_DMA` input arguments*
2769+| **Name** | **Type** | **Description** |
2770+| --------------------- | --------- | ---------------------------------------------------- |
2771+| chksum | u32 | Checksum over other input arguments |
2772+| cmk | CMK | Encrypted CMK containing the AES-256 key |
2773+| iv | u32[3] | AES-GCM initialization vector (12 bytes) |
2774+| tag | u32[4] | AES-GCM authentication tag (16 bytes) |
2775+| encrypted_data_sha384 | u8[48] | SHA384 hash of the encrypted data for verification |
2776+| axi_addr_lo | u32 | Lower 32 bits of the AXI address |
2777+| axi_addr_hi | u32 | Upper 32 bits of the AXI address |
2778+| length | u32 | Length of data to decrypt in bytes |
2779+| aad_length | u32 | Length of AAD in bytes (0-4095) |
2780+| aad | u8[...] | Additional authenticated data |
2781+
2782+
2783+*Table: `CM_AES_GCM_DECRYPT_DMA` output arguments*
2784+| **Name** | **Type** | **Description** |
2785+| ------------ | -------- | ----------------------------------------------------- |
2786+| chksum | u32 | Checksum over other output arguments |
2787+| fips_status | u32 | FIPS approved or an error |
2788+| tag_verified | u32 | 1 if GCM tag verification succeeded, 0 if it failed |
2789+
2790+
23072791 ### CM_ECDH_GENERATE
23082792
23092793 This computes the first half of an Elliptic Curve Diffie-Hellman exchange to compute an ephemeral shared key pair with another party.
@@ -2422,9 +2906,9 @@
24222906 ### CM\_DERIVE\_STABLE\_KEY
24232907
24242908 Derives an HMAC key that has a stable value across resets from either
2425-IDevId or LDevId.
2426-
2427-The (interior) value of the returned CMK will be the stable across resets as it is derived indirectly from the IDevId or LDevId CDIs.
2909+IDevId, LDevId, or the Owner Root Key (derived from HEK seed).
2910+
2911+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.
24282912 The actual encrypted bytes of the CMK will *not* be the same, and
24292913 the encrypted CMK itself cannot be used across resets. So, the key
24302914 will always need to be re-derived after every *cold* reset.
@@ -2432,26 +2916,36 @@
24322916 If a key usage other than HMAC is desired, then the KDF or HKDF
24332917 mailbox functions can be used to derive a key from the returned CMK.
24342918
2435-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.
2919+`key_type = OwnerKey` is only available in subsystem mode when the Stable Owner
2920+Key strap is enabled (`SS_STRAP_GENERIC[3]` bit 0 set to 1) and OCP LOCK is not
2921+enabled. If these requirements are not met, the command fails with
2922+`CMB_STABLE_OWNER_KEY_NOT_AVAILABLE`.
2923+
2924+For `OwnerKey`, this command derives from the ROM-populated Stable Owner Root
2925+Key. It first runs AES-256-CMAC KDF with `info` as the input data to produce an
2926+intermediate key, then runs HMAC-SHA512 KDF with `b"Stable Owner Key" || info`
2927+as the domain-separation input to produce the returned 64-byte HMAC key
2928+material. Caliptra wraps that key material as an encrypted CMK before returning
2929+it to the caller.
24362930
24372931 The command derivation is summarized below:
24382932
24392933 ![CM_DERIVE_STABLE_KEY Derivation](../images/caliptra-sw/runtime/../rom/dev/doc/svg/cm-derive-stable-key.svg)
24402934
2441-Command Code: `0x434D_4453` ("CMDS")
2935+Command Code: `0x494D_4453` ("IMDS")
24422936
24432937 *Table: `CM_DERIVE_STABLE_KEY` input arguments*
24442938
2445-| **Name** | **Type** | **Description**
2446-| -------- | -------- | ---------------
2939+| **Name** | **Type** | **Description** |
2940+| -------- | -------- | --------------- |
24472941 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
2448-| key_type | u32 | Source key to derive the stable key from. **0x0000_0001:** IDevId <br> **0x0000_0002:** LDevId |
2942+| 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) |
24492943 | info | u8[32] | Data to use in the key derivation. |
24502944
24512945
24522946 *Table: `CM_DERIVE_STABLE_KEY` output arguments*
2453-| **Name** | **Type** | **Description**
2454-| -------- | -------- | ---------------
2947+| **Name** | **Type** | **Description** |
2948+| -------- | -------- | --------------- |
24552949 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
24562950 | cmk | CMK | CMK that stores the stable key material |
24572951
@@ -2461,9 +2955,6 @@
24612955 Imports the specified key and returns a CMK for it.
24622956
24632957 Usage information is required so that the key can be verified and used appropriately.
2464-
2465-Note that it is the caller's responsibility to ensure that the source
2466-key material meets FIPS requirements, such as zeroization.
24672958
24682959 Command Code: `0x434D_494D` ("CMIM")
24692960
@@ -2548,14 +3039,14 @@
25483039
25493040 *Table: `GET_IDEV_ECC384_CSR` input arguments*
25503041
2551-| **Name** | **Type** | **Description**
2552-| -------- | -------- | ---------------
3042+| **Name** | **Type** | **Description** |
3043+| -------- | -------- | --------------- |
25533044 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
25543045
25553046
25563047 *Table: `GET_IDEV_ECC384_CSR` output arguments*
2557-| **Name** | **Type** | **Description**
2558-| -------- | -------- | ---------------
3048+| **Name** | **Type** | **Description** |
3049+| -------- | -------- | --------------- |
25593050 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
25603051 | data\_size | u32 | Length in bytes of the valid data in the data field. |
25613052 | data | u8[...] | DER-encoded ECC384 IDevID certificate signing request. |
@@ -2567,14 +3058,14 @@
25673058
25683059 *Table: `GET_IDEV_MLDSA87_CSR` input arguments*
25693060
2570-| **Name** | **Type** | **Description**
2571-| -------- | -------- | ---------------
3061+| **Name** | **Type** | **Description** |
3062+| -------- | -------- | --------------- |
25723063 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
25733064
25743065
25753066 *Table: `GET_IDEV_MLDSA87_CSR` output arguments*
2576-| **Name** | **Type** | **Description**
2577-| -------- | -------- | ---------------
3067+| **Name** | **Type** | **Description** |
3068+| -------- | -------- | --------------- |
25783069 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
25793070 | data\_size | u32 | Length in bytes of the valid data in the data field. |
25803071 | data | u8[...] | DER-encoded MLDSA87 IDevID certificate signing request. |
@@ -2594,14 +3085,14 @@
25943085
25953086 *Table: `GET_FMC_ALIAS_ECC384_CSR` input arguments*
25963087
2597-| **Name** | **Type** | **Description**
2598-| -------- | -------- | ---------------
3088+| **Name** | **Type** | **Description** |
3089+| -------- | -------- | --------------- |
25993090 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
26003091
26013092
26023093 *Table: `GET_FMC_ALIAS_ECC384_CSR` output arguments*
2603-| **Name** | **Type** | **Description**
2604-| -------- | -------- | ---------------
3094+| **Name** | **Type** | **Description** |
3095+| -------- | -------- | --------------- |
26053096 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
26063097 | data\_size | u32 | Length in bytes of the valid data in the data field. |
26073098 | data | u8[...] | DER-encoded ECC384 FMC Alias certificate signing request. |
@@ -2613,14 +3104,14 @@
26133104
26143105 *Table: `GET_FMC_ALIAS_MLDSA87_CSR` input arguments*
26153106
2616-| **Name** | **Type** | **Description**
2617-| -------- | -------- | ---------------
3107+| **Name** | **Type** | **Description** |
3108+| -------- | -------- | --------------- |
26183109 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
26193110
26203111
26213112 *Table: `GET_FMC_ALIAS_MLDSA87_CSR` output arguments*
2622-| **Name** | **Type** | **Description**
2623-| -------- | -------- | ---------------
3113+| **Name** | **Type** | **Description** |
3114+| -------- | -------- | --------------- |
26243115 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
26253116 | data\_size | u32 | Length in bytes of the valid data in the data field. |
26263117 | data | u8[...] | DER-encoded MLDSA87 FMC Alias certificate signing request. |
@@ -2628,50 +3119,50 @@
26283119
26293120 ### GET\_ATTESTED\_ECC384\_CSR
26303121
2631-Generates an attested ECC384 certificate signing request (CSR) in Entity Attestation Token (EAT) format as per the [OCP Device Identity Provisioning](https://opencomputeproject.github.io/Security/device-identity-provisioning/HEAD/) specification, signed by the `RT Alias` key for the requested Device Identity Key.
3122+Generates an attested ECC384 certificate signing request (CSR) in Entity Attestation Token (EAT) format as per the [OCP Device Identity Provisioning](https://opencomputeproject.github.io/Security/device-identity-provisioning/HEAD/) specification, signed by the `RT Alias` key for the requested Device Identity Key, or returns the keypair inventory discovery token when `key_id` is 0.
26323123
26333124 Command Code: `0x4145_4352` ("AECR")
26343125
26353126 *Table: `GET_ATTESTED_ECC384_CSR` input arguments*
26363127
2637-| **Name** | **Type** | **Description**
2638-| -------- | -------- | ---------------
3128+| **Name** | **Type** | **Description** |
3129+| -------- | -------- | --------------- |
26393130 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
2640-| key_id | u32 | Key ID for which CSR is requested.<br> **0x0000_0001:** LDevId <br> **0x0000_0002:** FMC Alias <br> **0x0000_0003:** RT Alias |
3131+| 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 |
26413132 | nonce | u8[32] | Nonce to be included in the CSR EAT. |
26423133
26433134
26443135 *Table: `GET_ATTESTED_ECC384_CSR` output arguments*
26453136
2646-| **Name** | **Type** | **Description**
2647-| -------- | -------- | ---------------
3137+| **Name** | **Type** | **Description** |
3138+| -------- | -------- | --------------- |
26483139 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
26493140 | data\_size | u32 | Length in bytes of the valid data in the data field. |
2650-| data | u8[...] | DER-encoded ECC384 attested certificate signing request. |
3141+| data | u8[...] | COSE Sign1 signed EAT token containing attested CSR (or keypair inventory when key_id = 0). |
26513142
26523143
26533144 ### GET\_ATTESTED\_MLDSA87\_CSR
26543145
2655-Generates an attested MLDSA87 certificate signing request (CSR) in Entity Attestation Token (EAT) format as per the [OCP Device Identity Provisioning](https://opencomputeproject.github.io/Security/device-identity-provisioning/HEAD/) specification, signed by the `RT Alias` key for the requested Device Identity Key.
3146+Generates an attested MLDSA87 certificate signing request (CSR) in Entity Attestation Token (EAT) format as per the [OCP Device Identity Provisioning](https://opencomputeproject.github.io/Security/device-identity-provisioning/HEAD/) specification, signed by the `RT Alias` key for the requested Device Identity Key, or returns the keypair inventory discovery token when `key_id` is 0.
26563147
26573148 Command Code: `0x414D_4352` ("AMCR")
26583149
26593150 *Table: `GET_ATTESTED_MLDSA87_CSR` input arguments*
26603151
2661-| **Name** | **Type** | **Description**
2662-| -------- | -------- | ---------------
3152+| **Name** | **Type** | **Description** |
3153+| -------- | -------- | --------------- |
26633154 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
2664-| key_id | u32 | Key ID for which CSR is requested.<br> **0x0000_0001:** LDevId <br> **0x0000_0002:** FMC Alias <br> **0x0000_0003:** RT Alias |
3155+| 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 |
26653156 | nonce | u8[32] | Nonce to be included in the CSR EAT. |
26663157
26673158
26683159 *Table: `GET_ATTESTED_MLDSA87_CSR` output arguments*
26693160
2670-| **Name** | **Type** | **Description**
2671-| -------- | -------- | ---------------
3161+| **Name** | **Type** | **Description** |
3162+| -------- | -------- | --------------- |
26723163 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
26733164 | data\_size | u32 | Length in bytes of the valid data in the data field. |
2674-| data | u8[...] | DER-encoded MLDSA87 attested certificate signing request. |
3165+| data | u8[...] | COSE Sign1 signed EAT token containing attested CSR (or keypair inventory when key_id = 0). |
26753166
26763167
26773168 ### SIGN\_WITH\_EXPORTED\_ECDSA
@@ -2682,23 +3173,57 @@
26823173
26833174 *Table: `SIGN_WITH_EXPORTED_ECDSA` input arguments*
26843175
2685-| **Name** | **Type** | **Description**
2686-| -------- | -------- | ---------------
3176+| **Name** | **Type** | **Description** |
3177+| -------- | -------- | --------------- |
26873178 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
2688-| exported_cdi_handle | u8[32] | The Exported CDI handle returned by the DPE `DeriveContext` command. Little endian. |
2689-| tbs | u8[48] | The bytes to be signed. Little endian. |
3179+| exported_cdi_handle | u8[32] | The exported CDI handle returned by the DPE `DeriveContext` command. Opaque byte array; copy the bytes exactly as returned. |
3180+| tbs | u8[48] | The 48-byte SHA-384 digest to be signed. Raw byte array; no byte swapping is required. |
26903181
26913182
26923183 *Table: `SIGN_WITH_EXPORTED_ECDSA` output arguments*
2693-| **Name** | **Type** | **Description**
2694-| -------- | -------- | ---------------
3184+| **Name** | **Type** | **Description** |
3185+| -------- | -------- | --------------- |
26953186 | derived_pubkey_x | u8[48] | The X BigNum of the ECDSA public key associated with the signing key. |
26963187 | derived_pubkey_y | u8[48] | The Y BigNum of the ECDSA public key associated with the signing key. |
26973188 | signature_r | u8[48] | The R BigNum of an ECDSA signature. |
26983189 | signature_s | u8[48] | The S BigNum of an ECDSA signature. |
26993190
27003191
2701-The `exported_cdi` can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
3192+The `exported_cdi_handle` can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
3193+
3194+### SIGN\_WITH\_EXPORTED\_MLDSA
3195+
3196+Command Code: `0x5357_4D4C` ("SWML")
3197+
3198+**Note**: This command is only available in the locality of the PL0 PAUSER.
3199+
3200+*Table: `SIGN_WITH_EXPORTED_MLDSA` input arguments*
3201+
3202+| **Name** | **Type** | **Description** |
3203+| -------- | -------- | --------------- |
3204+| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
3205+| exported_cdi_handle | u8[32] | The exported CDI handle returned by the DPE `DeriveContext` command. Opaque byte array; copy the bytes exactly as returned. |
3206+| sign_type | u32 | Signing mode selector. `0` = `Mu` (64-byte pre-hash input), `1` = `Raw` (arbitrary byte array input). |
3207+| 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. |
3208+| 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. |
3209+
3210+
3211+*Table: `SIGN_WITH_EXPORTED_MLDSA` output arguments*
3212+
3213+| **Name** | **Type** | **Description** |
3214+| -------- | -------- | --------------- |
3215+| derived_pubkey | u8[2592] | The ML-DSA public key derived from the exported CDI handle and the DPE environment. |
3216+| signature | u8[4627] | The ML-DSA signature produced by the derived key. |
3217+
3218+
3219+The `exported_cdi_handle` can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
3220+
3221+This command derives an ML-DSA key pair from the provided exported CDI handle and signs either:
3222+
3223+- a 64-byte `Mu` message digest, or
3224+- a `Raw` message payload of up to 1024 bytes.
3225+
3226+The command performs the signing under PL0-only access control and returns the derived public key together with the signature.
27023227
27033228 ### REVOKE\_EXPORTED\_CDI\_HANDLE
27043229
@@ -2708,16 +3233,47 @@
27083233
27093234 *Table: `REVOKE_EXPORTED_CDI_HANDLE` input arguments*
27103235
2711-| **Name** | **Type** | **Description**
2712-| -------- | -------- | ---------------
3236+| **Name** | **Type** | **Description** |
3237+| -------- | -------- | --------------- |
27133238 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
2714-| exported_cdi_handle | u8[32] | The Exported CDI handle returned by the DPE `DeriveContext` command. Little endian. |
2715-
2716-
2717-The `exported_cdi` can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
3239+| exported_cdi_handle | u8[32] | The exported CDI handle returned by the DPE `DeriveContext` command. Opaque byte array; copy the bytes exactly as returned. |
3240+
3241+
3242+The `exported_cdi_handle` can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
27183243
27193244 The `exported_cdi_handle` is no longer usable after calling `REVOKE_EXPORTED_CDI_HANDLE` with it. After the `exported_cdi_handle`
2720-has been revoked, a new exported CDI can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
3245+has been revoked, a new exported CDI handle can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
3246+
3247+### EXTERNAL_MAILBOX_CMD
3248+
3249+Command Code: `0x4558_544D` ("EXTM")
3250+
3251+**Important restrictions:**
3252+- This command is only available in subsystem mode in 2.1+.
3253+- This command is only available for MCU.
3254+
3255+Executes a mailbox command located at an AXI address.
3256+This allows for executing mailbox commands that are larger than the mailbox allows.
3257+
3258+This is currently mostly useful for FIRMWARE_LOAD (as part of an update) or SET_AUTH_MANIFEST.
3259+
3260+The response is still written to the mailbox.
3261+
3262+The checksum is over the EXTM command, *not* the command that is loaded over AXI.
3263+That external command will still need its own checksum, if applicable.
3264+
3265+*Table: `EXTERNAL_MAILBOX_CMD` input arguments*
3266+
3267+| **Name** | **Type** | **Description** |
3268+| -------- | -------- | --------------- |
3269+| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
3270+| command_id | u32 | Command ID for the mailbox command to be executed. Little endian. |
3271+| command_size | u32 | Size of the mailbox command to be executed. Little endian. |
3272+| axi_address_low | u32 | Lower 32 bits of the AXI address that contains the mailbox command. Little endian. |
3273+| axi_address_high | u32 | High 32 bits of the AXI address that contains the mailbox command. Little endian. |
3274+
3275+
3276+The response will be the response of the executed external command.
27213277
27223278 ### REALLOCATE\_DPE\_CONTEXT\_LIMITS
27233279
@@ -2727,24 +3283,119 @@
27273283
27283284 *Table: `REALLOCATE_DPE_CONTEXT_LIMITS` input arguments*
27293285
2730-| **Name** | **Type** | **Description**
2731-| -------- | -------- | ---------------
3286+| **Name** | **Type** | **Description** |
3287+| -------- | -------- | --------------- |
27323288 | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
27333289 | pl0_context_limit | u32 | Number of contexts to allocate to PL0. PL1 will receive remaining contexts. |
27343290
27353291
27363292 *Table: `REALLOCATE_DPE_CONTEXT_LIMITS` output arguments*
2737-| **Name** | **Type** | **Description**
2738-| -------- | -------- | ---------------
3293+| **Name** | **Type** | **Description** |
3294+| -------- | -------- | --------------- |
27393295 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
27403296 | fips_status | u32 | Indicates if the command is FIPS approved or an error. |
27413297 | new_pl0_context_limit | u32 | Number of contexts assigned to PL0 after the reallocation |
27423298 | new_pl1_context_limit | u32 | Number of contexts assigned to PL1 after the reallocation |
27433299
27443300
2745-This allows the user to reallocate the 32 DPE contexts between PL0 and PL1. By default, each gets 16 contexts.
3301+This allows the user to reallocate the 64 DPE contexts between PL0 and PL1. By default, each gets 32 contexts.
27463302
27473303 **Note**: 2 PL0 contexts are used by Caliptra itself during initialization.
3304+
3305+### FE\_PROG
3306+
3307+Programs Field Entropy (FE) into one of 4 FE partitions in the OTP fuse controller. This command
3308+is typically used during device provisioning flows.
3309+
3310+**Note**: This command is only available when the device is in the **Production** lifecycle state.
3311+
3312+Command Code: `0x4645_5052` ("FEPR")
3313+
3314+*Table: `FE_PROG` input arguments*
3315+
3316+| **Name** | **Type** | **Description**
3317+| -------- | -------- | ---------------
3318+| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian.
3319+| partition | u32 | FE partition number (valid values: 0–3).
3320+
3321+`FE_PROG` returns no output arguments other than the mailbox response header.
3322+
3323+### PRODUCTION\_AUTH\_DEBUG\_UNLOCK\_REQ
3324+
3325+Initiates the production debug unlock flow by generating a cryptographic challenge. The caller
3326+must solve the challenge by signing it with the appropriate ECC and MLDSA keys and returning
3327+the result via the [`PRODUCTION_AUTH_DEBUG_UNLOCK_TOKEN`](#production_auth_debug_unlock_token)
3328+command.
3329+
3330+This command performs the same function as the ROM's `AUTH_DEBUG_UNLOCK_REQ` command
3331+(documented in the [ROM README](../rom/dev/README.md#debug-unlock)), but is available at
3332+runtime.
3333+
3334+**Note**: This command requires the device to be in the **Production** lifecycle state and the
3335+`PROD_DEBUG_UNLOCK_REQ` bit in the `SS_DBG_MANUF_SERVICE_REG_REQ` register to be set.
3336+
3337+Command Code: `0x5044_5552` ("PDUR")
3338+
3339+*Table: `PRODUCTION_AUTH_DEBUG_UNLOCK_REQ` input arguments*
3340+
3341+| **Name** | **Type** | **Description**
3342+| -------- | -------- | ---------------
3343+| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian.
3344+| length | u32 | Length of the payload in DWORDs.
3345+| unlock\_level | u8 | Debug unlock level (1–8).
3346+| reserved | u8[3] | Reserved.
3347+
3348+*Table: `PRODUCTION_AUTH_DEBUG_UNLOCK_REQ` output arguments*
3349+
3350+| **Name** | **Type** | **Description**
3351+| -------- | -------- | ---------------
3352+| chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian.
3353+| fips\_status | u32 | Indicates if the command is FIPS approved or an error.
3354+| length | u32 | Length of the response payload in DWORDs.
3355+| unique\_device\_identifier | u8[32] | Device identifier of the Caliptra device. Byte array; pass through as-is to the token command.
3356+| challenge | u8[48] | Random challenge number generated by Caliptra. Byte array; pass through as-is to the token command.
3357+
3358+### PRODUCTION\_AUTH\_DEBUG\_UNLOCK\_TOKEN
3359+
3360+Completes the production debug unlock handshake by validating the caller's solution to the
3361+challenge generated by
3362+[`PRODUCTION_AUTH_DEBUG_UNLOCK_REQ`](#production_auth_debug_unlock_req). The caller must
3363+provide the device identifier and challenge from the previous request along with ECC-384 and
3364+ML-DSA-87 signatures proving possession of the authorized debug unlock key.
3365+
3366+Upon successful validation, Caliptra authorizes the debug unlock by setting the unlock level
3367+in the `SS_SOC_DBG_UNLOCK_LEVEL` register.
3368+
3369+This command performs the same function as the ROM's `AUTH_DEBUG_UNLOCK_TOKEN` command
3370+(documented in the [ROM README](../rom/dev/README.md#debug-unlock)), but is available at
3371+runtime.
3372+
3373+**Note**: This command requires a preceding successful `PRODUCTION_AUTH_DEBUG_UNLOCK_REQ` in
3374+the same boot session. The challenge is consumed on use and cannot be replayed.
3375+
3376+Command Code: `0x5044_5554` ("PDUT")
3377+
3378+*Table: `PRODUCTION_AUTH_DEBUG_UNLOCK_TOKEN` input arguments*
3379+
3380+| **Name** | **Type** | **Description**
3381+| -------- | -------- | ---------------
3382+| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian.
3383+| length | u32 | Length of the payload in DWORDs.
3384+| unique\_device\_identifier | u8[32] | Device identifier (must match value from challenge response). Byte array; copied verbatim from the challenge response.
3385+| unlock\_level | u8 | Debug unlock level (1–8, must match the original request).
3386+| reserved | u8[3] | Reserved.
3387+| challenge | u8[48] | Challenge (must match value from challenge response). Byte array; copied verbatim from the challenge response.
3388+| 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).
3389+| mldsa\_public\_key | u8[2592] | ML-DSA-87 public key. See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields).
3390+| 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).
3391+| 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).
3392+
3393+The signed message for both ECC and ML-DSA signatures is the hash of the concatenation:
3394+`unique_device_identifier || unlock_level || reserved || challenge` (all as raw bytes).
3395+ECC uses SHA2-384; ML-DSA uses SHA2-512.
3396+
3397+`PRODUCTION_AUTH_DEBUG_UNLOCK_TOKEN` returns no output arguments other than the mailbox
3398+response header.
27483399
27493400 ## Checksum
27503401
@@ -2768,15 +3419,15 @@
27683419
27693420 ## FIPS status
27703421
2771-For every command, the firmware responds with a FIPS status of FIPS approved. There is
2772-currently no use case for any other responses or error values.
3422+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.
27733423
27743424 *Table: FIPS status codes*
27753425
27763426 | **Name** | **Value** | Description |
27773427 | --------------- | --------------------------- | --------------------------------------------------- |
27783428 | `FIPS_APPROVED` | `0x0000_0000` | Status of command is FIPS approved |
2779-| `RESERVED` | `0x0000_0001 - 0xFFFF_FFFF` | Other values reserved, will not be sent by Caliptra |
3429+| `FIPS_NOT_APPROVED_USER_SUPPLIED_DIGEST` | `0x5553_5244` | Command is not FIPS approved because the caller supplied the digest instead of the raw message |
3430+| `RESERVED` | `0x0000_0002 - 0xFFFF_FFFF` | Other values reserved, will not be sent by Caliptra |
27803431
27813432
27823433 ## Runtime Firmware updates
@@ -2855,14 +3506,14 @@
28553506 To prevent this, we establish active context limits for each PAUSER
28563507 privilege level:
28573508
2858-* PL0 - 16 active contexts
2859-* PL1 - 16 active contexts
3509+* PL0 - 32 active contexts
3510+* PL1 - 32 active contexts
28603511
28613512 If a DPE command were to activate a new context such that the total number of
28623513 active contexts in a privilege level is above its active context limit, the
28633514 InvokeDpe command should fail.
28643515
2865-At boot Caliptra Runtime FW consumes part of the PL0 active contexts (initially 16) to DeriveContext for:
3516+At boot Caliptra Runtime FW consumes part of the PL0 active contexts (initially 32) to DeriveContext for:
28663517 - RTFW Journey (RTFJ) Measurement (1)
28673518 - Caliptra Configured Initialization Values digest (CCIV) (1)
28683519 - ROM Stashed Measurements (max 8)
@@ -2870,20 +3521,20 @@
28703521 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
28713522 of active contexts in PL0's locality, and hence allow PL1 to DOS PL0.
28723523
2873-### DPE profile implementation
2874-
2875-The DPE iRoT profile leaves some choices up to implementers. This section
2876-describes specific requirements for the Caliptra DPE implementation.
3524+### Caliptra DPE Profile
3525+
3526+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.
28773527
28783528 | Name | Value | Description |
28793529 | -------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------ |
2880-| Profile Variant | `DPE_PROFILE_IROT_P384_SHA384` | The profile variant that Caliptra implements. |
3530+| Profile Variant | `Caliptra DPE Profile` | Derived from `DPE_PROFILE_IROT_P384_SHA384`. |
28813531 | KDF | SP800-108 HMAC-CTR | KDF to use for CDI (tcg.derive.kdf-sha384) and asymmetric key (tcg.derive.kdf-sha384-p384) derivation. |
28823532 | Simulation Context Support | Yes | Whether Caliptra implements the optional Simulation Contexts feature. |
28833533 | Supports ExtendTci | Yes | Whether Caliptra implements the optional ExtendTci command. |
28843534 | Supports Auto Init | Yes | Whether Caliptra will automatically initialize the default DPE context. |
28853535 | Supports Rotate Context | Yes | Whether Caliptra supports the optional RotateContextHandle command. |
28863536 | CertifyKey Alias Key | Caliptra Runtime Alias Key | The key that will be used to sign certificates that are produced by the DPE CertifyKey command. |
3537+| `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. |
28873538
28883539
28893540 ### Supported DPE commands
@@ -2894,6 +3545,7 @@
28943545 * InitializeContext
28953546 * DeriveContext
28963547 * **Note**: The "export-cdi" flag is only available in the locality of the PL0 PAUSER.
3548+ * **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.
28973549 * CertifyKey
28983550 * Caliptra DPE supports two formats for CertifyKey: X.509 and PKCS#10 CSR.
28993551 X.509 is only available to PL0 PAUSERs.