Diff: Runtime Specification

@@ -1,10 +1,10 @@
1	1	<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/8f13b41132ddd85c3c2fa2c8ce5a766758b20fd8/runtime/README.md" target="_blank">chipsalliance/caliptra-sw/runtime/README.md</a> @ <code>8f13b41</code>
	2	+📄 Source: <a href="https://github.com/chipsalliance/caliptra-sw/blob/6980f7d09b351299e61d7242ac7a8c3c4e8cb695/runtime/README.md" target="_blank">chipsalliance/caliptra-sw/runtime/README.md</a> @ <code>6980f7d</code>
3	3	</div>
4	4
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
8	8
9	9	This specification describes the Caliptra Runtime Firmware.
10	10
@@ -23,11 +23,17 @@
23	23	* Add support for passive mode (same as 1.x) and subsystem (or active) mode
24	24	* [MCU Runtime loading](#boot-and-initialization) (subsystem mode)
25	25	* [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	+
27	35
28	36	## Spec Opens
29		-
30		-* Cryptographic Mailbox: ML-KEM support
31	37
32	38	## Runtime Firmware environment
33	39
@@ -39,7 +45,21 @@
39	45
40	46	* Initialize the [DICE Protection Environment (DPE)](#dice-protection-environment-dpe)
41	47	* Initialize any SRAM structures used by Runtime Firmware
42		-* Upload the firwmare to the Manufacturer Control Unit (2.0, susbystem mode only)
	48	+* 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.
43	63
44	64	For behavior during other types of reset, see [Runtime firmware updates](#runtime-firmware-updates).
45	65
@@ -94,7 +114,7 @@
94	114
95	115	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.
96	116
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.
98	118
99	119	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.
100	120
@@ -126,8 +146,7 @@
126	146
127	147	\| Name \| Bits \| Description \|
128	148	\| ------------- \| -------- \| -------------------------------------- \|
129		-\| version \| 8 \| CMK version. Currently always 1. \|
130		-\| flags \| 8 \| Bit 0 = FIPS valid \|
	149	+\| version \| 16 \| CMK version. Currently always 1. \|
131	150	\| length \| 16 \| how many bits of key material are used \|
132	151	\| key usage \| 8 \| represents which kind of key this is \|
133	152	\| id \| 24 \| ID number \|
@@ -162,8 +181,10 @@
162	181	\| --------- \| --------- \|
163	182	\| 0 \| Reserved \|
164	183	\| 1 \| HMAC \|
165		-\| 2 \| HKDF \|
166		-\| 3 \| AES \|
	184	+\| 2 \| AES \|
	185	+\| 3 \| ECDSA \|
	186	+\| 4 \| MLDSA \|
	187	+\| 5 \| ML-KEM \|
167	188
168	189
169	190	#### Replay Prevention and Deletion
@@ -187,7 +208,7 @@
187	208
188	209	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.
189	210
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.
191	212
192	213	### Caliptra-Endorsed Aggregated Measured Boot
193	214
@@ -303,6 +324,68 @@
303	324	Mailbox user 0xFFFF_FFFF is reserved for Caliptra internal use. All mailbox
304	325	commands from that user will fail.
305	326
	327	+### Byte order of cryptographic fields
	328	+
	329	+Several mailbox commands include ECC P-384 and ML-DSA-87 public keys,
	330	+signatures, and SHA digest values stored as `[u32]` arrays.
	331	+The "big endian" / "little endian" labels in individual command tables describe
	332	+how the standard byte representation produced by cryptographic
	333	+tools maps to those `u32` words.
	334	+
	335	+Generally, any fields specified as little-endian byte representation will match the standard byte representation of the cryptographic protocols, since the RISC-V processor is a little-endian processor.
	336	+
	337	+#### ECC P-384 fields (big-endian words)
	338	+
	339	+Each 4-byte group from the standard representation is byte-reversed on the
	340	+wire.
	341	+
	342	+Example — suppose OpenSSL produces a 48-byte X coordinate starting with:
	343	+
	344	+```
	345	+OpenSSL raw bytes: AB CD EF 01 23 45 67 89 ...
	346	+ ~~~~~~~~~~~ ~~~~~~~~~~~
	347	+Mailbox bytes: 01 EF CD AB 89 67 45 23 ...
	348	+```
	349	+
	350	+In other words: split the tool output into 4-byte groups, then reverse each
	351	+group.
	352	+
	353	+#### ML-DSA-87 fields (little-endian words)
	354	+
	355	+No conversion is needed. Copy the raw bytes produced by an ML-DSA-87
	356	+implementation (e.g., OpenSSL 3.5+, the `fips204` crate, or the NIST reference
	357	+implementation) directly into the mailbox buffer.
	358	+
	359	+```
	360	+openssl pkey output: AB CD EF 01 23 45 67 89 ...
	361	+Mailbox bytes: AB CD EF 01 23 45 67 89 ... (identical)
	362	+```
	363	+
	364	+#### SHA digest fields (big-endian words)
	365	+
	366	+Hash digests stored as `u32[N]` arrays use the same big-endian word convention
	367	+as ECC fields. Each 4-byte group of the standard hash output is byte-reversed
	368	+on the wire.
	369	+
	370	+Example — suppose `openssl dgst -sha384` produces a digest starting with:
	371	+
	372	+```
	373	+openssl output: A1 B2 C3 D4 E5 F6 07 18 ...
	374	+ ~~~~~~~~~~~ ~~~~~~~~~~~
	375	+Mailbox u32[12]: D4 C3 B2 A1 18 07 F6 E5 ...
	376	+```
	377	+
	378	+#### u8 byte-array fields (no conversion needed)
	379	+
	380	+When ECC P-384 keys, signatures, or SHA digests are declared as `u8[48]` (rather
	381	+than `u32[12]`), they use standard big-endian byte order — the same format
	382	+produced by OpenSSL and other cryptographic tools. No byte-swapping is required.
	383	+
	384	+For example, the `ECDSA384_SIGNATURE_VERIFY` input fields (`pub_key_x`,
	385	+`pub_key_y`, `signature_r`, `signature_s`, `hash`) and the `QUOTE_PCRS_ECC384`
	386	+output fields (`digest`, `signature_r`, `signature_s`) can be used directly with
	387	+`openssl` or OpenSSL's `BN_bin2bn()` without any conversion.
	388	+
306	389	### FW\_LOAD
307	390
308	391	The `FIRMWARE_LOAD` command is handled by both ROM and Runtime Firmware.
@@ -367,7 +450,14 @@
367	450	\| -------- \| -------- \| ---------------
368	451	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian.
369	452	\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error.
370		-\| capabilities \| u8[16] \| Firmware capabilities
	453	+\| capabilities \| u8[16] \| Firmware capabilities. See table below for details.
	454	+
	455	+Table: Firmware Capabilities Flags
	456	+
	457	+\| Name \| Bit \| Description
	458	+\| --------------- \| ------- \| ---------------
	459	+\| `RT_BASE` \| 64 \| Base capabilities for Caliptra Runtime v2.1.
	460	+\| `RT_OCP_LOCK` \| 65 \| Runtime firmware and hardware supports OCP LOCK.
371	461
372	462	### GET\_IDEV\_ECC384\_CERT
373	463
@@ -656,7 +746,7 @@
656	746	\| Name \| Type \| Description
657	747	\| -------- \| -------- \| ---------------
658	748	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian.
659		-\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error.
	749	+\| fips\_status \| u32 \| `FIPS_NOT_APPROVED_USER_SUPPLIED_DIGEST`, because the caller supplies the digest.
660	750
661	751	### LMS\_SIGNATURE\_VERIFY
662	752
@@ -697,7 +787,7 @@
697	787	\| Name \| Type \| Description
698	788	\| -------- \| -------- \| ---------------
699	789	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian.
700		-\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error.
	790	+\| fips\_status \| u32 \| `FIPS_NOT_APPROVED_USER_SUPPLIED_DIGEST`, because the caller supplies the digest.
701	791
702	792	### MLDSA87_SIGNATURE_VERIFY
703	793
@@ -740,7 +830,7 @@
740	830	\| Name \| Type \| Description
741	831	\| -------- \| -------- \| ---------------
742	832	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian.
743		-\| digest \| u32[12] \| Owner public key hash.
	833	+\| digest \| u32[12] \| Owner public key hash. See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields).
744	834
745	835	Table: `INSTALL_OWNER_PK_HASH` output arguments
746	836
@@ -811,13 +901,13 @@
811	901	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian.
812	902	\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error.
813	903
814		-### INVOKE\_DPE\_COMMAND
815		-
816		-Invokes a serialized DPE command.
	904	+### INVOKE\_DPE\_ECC384
	905	+
	906	+Invokes a serialized EC-P384 DPE profile command.
817	907
818	908	Command Code: `0x4450_4543` ("DPEC")
819	909
820		-Table: `INVOKE_DPE_COMMAND` input arguments
	910	+Table: `INVOKE_DPE_ECC384` input arguments
821	911
822	912	\| Name \| Type \| Description
823	913	\| -------- \| -------- \| ---------------
@@ -825,7 +915,53 @@
825	915	\| data\_size \| u32 \| Length in bytes of the valid data in the data field.
826	916	\| data \| u8[...] \| DPE command structure as defined in the DPE iRoT profile.
827	917
828		-Table: `INVOKE_DPE_COMMAND` output arguments
	918	+Table: `INVOKE_DPE_ECC384` output arguments
	919	+
	920	+\| Name \| Type \| Description
	921	+\| -------- \| -------- \| ---------------
	922	+\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian.
	923	+\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error.
	924	+\| data\_size \| u32 \| Length in bytes of the valid data in the data field.
	925	+\| data \| u8[...] \| DPE response structure as defined in the DPE iRoT profile.
	926	+
	927	+### INVOKE\_DPE\_MLDSA87
	928	+
	929	+Invokes a serialized ML-DSA-87 DPE profile command. In subsystem mode a response
	930	+can be DMA'ed to an external address. This is especially useful for large
	931	+commands like `CertifyKey` or `DeriveContext` when exporting a CDI. Both of
	932	+these responses contain a potentially large certificate/CSR. To use this
	933	+feature, set the `EXTERNAL_AXI_RESPONSE` in `flags` and set the corresponding
	934	+AXI address and size fields. The response over the mailbox will only contain a
	935	+mailbox header (`chksum` and `fips_status`). The full response including the
	936	+mailbox header will be found at the given address.
	937	+
	938	+Important restrictions for `EXTERNAL_AXI_RESPONSE` flag use:
	939	+- This command is only available in subsystem mode, as DMA is only available in subsystem.
	940	+- This command is only available for MCU.
	941	+
	942	+Command Code: `0x4450_4543` ("DPEC")
	943	+
	944	+Table: `INVOKE_DPE_MLDSA87` input arguments
	945	+
	946	+\| Name \| Type \| Description \|
	947	+\| -------------- \| -------- \| --------------------------------------------------------------------------- \|
	948	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
	949	+\| flags \| u32 \| Flags to give configurations of the command. \|
	950	+\| axi\_addr\_lo \| u32 \| Lower word of the destination physical address. \|
	951	+\| axi\_addr\_hi \| u32 \| Upper word of the destination physical address. \|
	952	+\| axi\_max\_size \| u32 \| Maximum DMA response size. \|
	953	+\| data\_size \| u32 \| Length in bytes of the valid data in the data field. \|
	954	+\| data \| u8[...] \| DPE command structure as defined in the DPE iRoT profile. \|
	955	+
	956	+
	957	+Table: `INVOKE_DPE_MLDSA87` input flags
	958	+
	959	+\| Name \| Value \|
	960	+\| ----------------------- \| --------- \|
	961	+\| EXTERNAL\_AXI\_RESPONSE \| 1 << 31 \|
	962	+
	963	+
	964	+Table: `INVOKE_DPE_MLDSA87` output arguments
829	965
830	966	\| Name \| Type \| Description
831	967	\| -------- \| -------- \| ---------------
@@ -888,8 +1024,36 @@
888	1024	\| PCRs \| PcrValue[32] \| Values of all PCRs.
889	1025	\| nonce \| u8[32] \| Return the nonce used as input for convenience.
890	1026	\| reset\_ctrs \| u32[32] \| Reset counters for all PCRs.
891		-\| digest \| u8[64] \| Return the SHA2-512 digest over the PCR values and the nonce, in byte reversed order.
	1027	+\| digest \| u8[64] \| SHA2-512 digest over the PCR values and the nonce, in DWORD-reversed order with per-word byte swap. See note below.
892	1028	\| signature \| u8[4628] \| MLDSA-87 signature over the `digest` (4627 bytes + 1 Reserved byte). </br> The FMC Alias MLDSA seed stored in Key Vault slot 8 is utilized to generate the private key, which is subsequently used for the signing operation.
	1029	+
	1030	+Digest byte order: The `digest` field has two transformations applied relative
	1031	+to the standard `openssl dgst -sha512` output: (1) the 16 u32 words are in
	1032	+reversed order, and (2) the bytes within each word are reversed. For example, if
	1033	+`openssl dgst -sha512` produces `A1 B2 C3 D4 E5 F6 07 18 ... P1 P2 P3 P4`,
	1034	+the mailbox response contains `P4 P3 P2 P1 ... 18 07 F6 E5 D4 C3 B2 A1`.
	1035	+
	1036	+To independently recompute this digest from PCR values and nonce, compute the
	1037	+SHA2-512 hash, then apply two steps:
	1038	+
	1039	+```
	1040	+openssl dgst -sha512 output (64 bytes, shown as 16 four-byte groups):
	1041	+ A1 B2 C3 D4 \| E5 F6 07 18 \| ... \| M1 M2 M3 M4 \| P1 P2 P3 P4
	1042	+
	1043	+Step 1 — reverse the bytes within each 4-byte group:
	1044	+ D4 C3 B2 A1 \| 18 07 F6 E5 \| ... \| M4 M3 M2 M1 \| P4 P3 P2 P1
	1045	+
	1046	+Step 2 — reverse the order of all 16 groups:
	1047	+ P4 P3 P2 P1 \| M4 M3 M2 M1 \| ... \| 18 07 F6 E5 \| D4 C3 B2 A1
	1048	+ ^^^^^^^^^^^^ ^^^^^^^^^^^^
	1049	+ (last group from Step 1 is now first) (first group is now last)
	1050	+
	1051	+Mailbox digest = result of Step 2
	1052	+```
	1053	+
	1054	+To verify the signature with an external tool such as OpenSSL, pass the `digest`
	1055	+bytes as-is as the pre-hashed message to ML-DSA-87 verification — no conversion
	1056	+is needed because the signature was computed over these exact bytes.
893	1057
894	1058	### EXTEND\_PCR
895	1059
@@ -1149,35 +1313,69 @@
1149	1313	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian.
1150	1314	\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error.
1151	1315
1152		-### CERTIFY\_KEY\_EXTENDED
1153		-
1154		-Produces a DPE leaf certificate or CSR containing custom extensions provided by the SoC.
	1316	+### CERTIFY\_KEY\_EXTENDED\_ECC384
	1317	+
	1318	+Produces an ECC-P384 DPE leaf certificate or CSR containing custom extensions provided by the SoC.
1155	1319
1156	1320	Command Code: `0x434B_4558` ("CKEX")
1157	1321
1158		-Table: `CERTIFY_KEY_EXTENDED` input arguments
	1322	+Table: `CERTIFY_KEY_EXTENDED_ECC384` input arguments
1159	1323
1160	1324	\| Name \| Type \| Description \|
1161	1325	\| ----------------- \| -------- \| --------------------------------------------------------------------------- \|
1162	1326	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
	1327	+\| flags \| u32 \| Flags determining which custom extensions to include in the certificate. \|
1163	1328	\| certify\_key\_req \| u8[72] \| Certify Key Request. \|
1164		-\| flags \| u32 \| Flags determining which custom extensions to include in the certificate. \|
1165		-
1166		-
1167		-Table: `CERTIFY_KEY_EXTENDED` input flags
	1329	+
	1330	+
	1331	+Table: `CERTIFY_KEY_EXTENDED_ECC384` input flags
1168	1332
1169	1333	\| Name \| Offset \|
1170		-\| --------------- \| ---------- \|
1171		-\| DMTF_OTHER_NAME \| 1 << 31 \|
1172		-
1173		-
1174		-Table: `CERTIFY_KEY_EXTENDED` output arguments
1175		-
1176		-\| Name \| Type \| Description \|
1177		-\| ------------------ \| -------- \| -------------------------------------------------------------------------- \|
	1334	+\| ----------------- \| ---------- \|
	1335	+\| DMTF\_OTHER\_NAME \| 1 << 31 \|
	1336	+
	1337	+
	1338	+Table: `CERTIFY_KEY_EXTENDED_ECC384` output arguments
	1339	+
	1340	+\| Name \| Type \| Description \|
	1341	+\| ------------------ \| --------- \| -------------------------------------------------------------------------- \|
1178	1342	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
1179	1343	\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error. \|
1180		-\| certify\_key\_resp \| u8[2176] \| Certify Key Response. \|
	1344	+\| size \| u32 \| The size of the response in the certify\_key\_resp field. \|
	1345	+\| certify\_key\_resp \| u8[25152] \| Certify Key Response. \|
	1346	+
	1347	+
	1348	+### CERTIFY\_KEY\_EXTENDED\_MLDSA87
	1349	+
	1350	+Produces an ML-DSA-87 DPE leaf certificate or CSR containing custom extensions provided by the SoC.
	1351	+
	1352	+Command Code: `0x434B_584D` ("CKXM")
	1353	+
	1354	+Table: `CERTIFY_KEY_EXTENDED_MLDSA87` input arguments
	1355	+
	1356	+\| Name \| Type \| Description \|
	1357	+\| ----------------- \| -------- \| --------------------------------------------------------------------------- \|
	1358	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
	1359	+\| flags \| u32 \| Flags determining which custom extensions to include in the certificate. \|
	1360	+\| certify\_key\_req \| u8[72] \| Certify Key Request. \|
	1361	+
	1362	+
	1363	+Table: `CERTIFY_KEY_EXTENDED_MLDSA87` input flags
	1364	+
	1365	+\| Name \| Offset \|
	1366	+\| ----------------------- \| ---------- \|
	1367	+\| DMTF\_OTHER\_NAME \| 1 << 31 \|
	1368	+\| EXTERNAL\_AXI\_RESPONSE \| 1 << 30 \|
	1369	+
	1370	+
	1371	+Table: `CERTIFY_KEY_EXTENDED_MLDSA87` output arguments
	1372	+
	1373	+\| Name \| Type \| Description \|
	1374	+\| ------------------ \| --------- \| -------------------------------------------------------------------------- \|
	1375	+\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
	1376	+\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error. \|
	1377	+\| size \| u32 \| The size of the response in the certify\_key\_resp field. \|
	1378	+\| certify\_key\_resp \| u8[25152] \| Certify Key Response. \|
1181	1379
1182	1380
1183	1381	### CERTIFY\_KEY\_CHUNKS
@@ -1229,26 +1427,26 @@
1229	1427
1230	1428	Table: `SET_AUTH_MANIFEST` input arguments
1231	1429
1232		-\| Name \| Type \| Description
1233		-\| -------- \| -------- \| ---------------
	1430	+\| Name \| Type \| Description \|
	1431	+\| -------- \| -------- \| --------------- \|
1234	1432	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
1235	1433	\| manifest size \| u32 \| The size of the full Authentication Manifest \|
1236	1434	\| preamble\_marker \| u32 \| Marker needs to be 0x4154_4D4E for the preamble to be valid \|
1237	1435	\| preamble\_size \| u32 \| Size of the preamble \|
1238	1436	\| preamble\_version \| u32 \| Version of the preamble \|
1239	1437	\| preamble\_flags \| u32 \| Manifest flags. See AUTH_MANIFEST_FLAGS below \|
1240		-\| preamble\_vendor\_ecc384\_key \| u32[24] \| Vendor ECC384 key with X and Y coordinates in that order \|
1241		-\| preamble\_vendor\_pqc\_key \| u32[648] \| Vendor MLDSA-87 or LMS-SHA192-H15 key \|
1242		-\| preamble\_vendor\_ecc384\_sig \| u32[24] \| Vendor ECC384 signature \|
1243		-\| preamble\_vendor\_PQC\_sig \| u32[1157] \| Vendor MLDSA-87 or LMOTS-SHA192-W4 signature \|
1244		-\| preamble\_owner\_ecc384\_key \| u32[24] \| Owner ECC384 key with X and Y coordinates in that order \|
1245		-\| preamble\_owner\_pqc\_key \| u32[648] \| Owner MLDSA-87 or LMS-SHA192-H15 key \|
1246		-\| preamble\_owner\_ecc384\_sig \| u32[24] \| Owner ECC384 signature \|
1247		-\| preamble\_owner\_PQC\_sig \| u32[1157] \| Owner MLDSA-87 or LMOTS-SHA192-W4 signature \|
1248		-\| metadata\_vendor\_ecc384\_sig \| u32[24] \| Metadata Vendor ECC384 signature \|
1249		-\| metadata\_vendor\_PQC\_sig \| u32[1157] \| Metadata Vendor MLDSA-87 or LMOTS-SHA192-W4 signature \|
1250		-\| metadata\_owner\_ecc384\_sig \| u32[24] \| Metadata Owner ECC384 signature \|
1251		-\| metadata\_owner\_PQC\_sig \| u32[1157] \| Metadata Owner MLDSA-87 or LMOTS-SHA192-W4 signature \|
	1438	+\| 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). \|
	1439	+\| 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). \|
	1440	+\| preamble\_vendor\_ecc384\_sig \| u32[24] \| Vendor ECC384 signature. See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields). \|
	1441	+\| 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). \|
	1442	+\| 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). \|
	1443	+\| 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). \|
	1444	+\| preamble\_owner\_ecc384\_sig \| u32[24] \| Owner ECC384 signature. See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields). \|
	1445	+\| 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). \|
	1446	+\| metadata\_vendor\_ecc384\_sig \| u32[24] \| Metadata Vendor ECC384 signature. See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields). \|
	1447	+\| 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). \|
	1448	+\| metadata\_owner\_ecc384\_sig \| u32[24] \| Metadata Owner ECC384 signature. See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields). \|
	1449	+\| 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). \|
1252	1450	\| metadata\_entry\_entry\_count \| u32 \| number of metadata entries \|
1253	1451	\| metadata\_entries \| Metadata[80] \| The max number of metadata entries is 80 but less can be used \|
1254	1452
@@ -1266,17 +1464,17 @@
1266	1464	\| Name \| Type \| Description \|
1267	1465	\| ------------------------ \| --------- \| ---------------- \|
1268	1466	\| Image Hash \| u8[48] \| SHA2-384 hash of a SOC image. \|
1269		-
1270		-\| 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)
1271		-\| 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)
1272		-\| 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)
1273		-\| 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)
1274		-\| 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)
1275		-\| 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)
1276		-\| 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)
1277		-\| 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)
1278		-\| 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)
1279		-\| 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)
	1467	+\| 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) \|
	1468	+\| 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) \|
	1469	+\| flags \| u32 \| This corresponds to the `flags` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main/auth-manifest/README.md) \|
	1470	+\| 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) \|
	1471	+\| 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) \|
	1472	+\| 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) \|
	1473	+\| 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) \|
	1474	+\| Classification \| u32 \| This corresponds to the `Classification` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main/auth-manifest/README.md) \|
	1475	+\| 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) \|
	1476	+\| 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) \|
	1477	+
1280	1478
1281	1479	### VERIFY_AUTH_MANIFEST
1282	1480
@@ -1342,8 +1540,8 @@
1342	1540
1343	1541	Table: `AUTHORIZE_AND_STASH` input arguments
1344	1542
1345		-\| Name \| Type \| Description
1346		-\| ------------\| -------- \| ---------------
	1543	+\| Name \| Type \| Description \|
	1544	+\| ------------ \| -------- \| --------------- \|
1347	1545	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
1348	1546	\| fw_id \| u8[4] \| Firmware id of the image, in little-endian format \|
1349	1547	\| 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. \|
@@ -1379,8 +1577,8 @@
1379	1577	\| Name \| Type \| Description \|
1380	1578	\| -------------- \| -------------- \| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- \|
1381	1579	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
1382		-
1383		-\| fw_id \| u32 \| Firmware id of the image, in little-endian format
	1580	+\| fw_id \| u32 \| Firmware id of the image, in little-endian format \|
	1581	+
1384	1582
1385	1583	Table: `GET_IMAGE_INFO` output arguments
1386	1584
@@ -1388,13 +1586,36 @@
1388	1586	\| -------------- \| -------------- \| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- \|
1389	1587	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
1390	1588	\| fips_status \| u32 \| Indicates if the command is FIPS approved or an error. \|
1391		-\| 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) \|
1392		-\| 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) \|
1393		-\| 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) \|
1394		-\| 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) \|
1395		-\| 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) \|
1396		-\| 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) \|
	1589	+\| 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) \|
	1590	+\| flags \| u32 \| This corresponds to the `flags` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main/auth-manifest/README.md) \|
	1591	+\| 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) \|
	1592	+\| 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) \|
	1593	+\| 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) \|
	1594	+\| 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) \|
1397	1595	\| digest \| u8[48] \| SHA-384 digest of the image. Only present in FW 2.0.2+ and 2.1.1+. \|
	1596	+
	1597	+
	1598	+### GET\_MCU\_FW\_SIZE
	1599	+
	1600	+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.
	1601	+
	1602	+Command Code: `0x474D_4653` ("GMFS")
	1603	+
	1604	+Table: `GET_MCU_FW_SIZE` input arguments
	1605	+
	1606	+\| Name \| Type \| Description \|
	1607	+\| -------------- \| -------------- \| --------------------------------------------------------------------------- \|
	1608	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
	1609	+
	1610	+
	1611	+Table: `GET_MCU_FW_SIZE` output arguments
	1612	+
	1613	+\| Name \| Type \| Description \|
	1614	+\| -------------- \| -------------- \| -------------------------------------------------------------------------- \|
	1615	+\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
	1616	+\| fips_status \| u32 \| Indicates if the command is FIPS approved or an error. \|
	1617	+\| size \| u32 \| Size of the MCU firmware image in bytes. \|
	1618	+\| sha384 \| u8[48] \| SHA-384 digest of the encrypted MCU firmware image. \|
1398	1619
1399	1620
1400	1621	### ACTIVATE_FIRMWARE
@@ -1412,7 +1633,43 @@
1412	1633	\| count \| u32 \| Number of image_ids to activate. Item count of image_ids array parameter \|
1413	1634	\| mcu_image_size \| u32 \| Size of MCU image, if included in the activation \|
1414	1635	\| image_ids \| Array of u8[4] \| Array of Image ids in little-endian format \|
1415		-
	1636	+\| flags \| u32 \| Optional flags (see below). Caliptra runtime 2.1.1+ only. \|
	1637	+
	1638	+
	1639	+Flags
	1640	+
	1641	+\| Bit \| Name \| Description \|
	1642	+\| ------- \| ----------------- \| ------------------------------------------------------------------------------------------------------------------------ \|
	1643	+\| 0 \| `INITIAL_ACTIVATE` \| First-time MCU activation after the encrypted-boot flow. Caliptra runtime 2.1.1+ only. See below. \|
	1644	+
	1645	+
	1646	+Unknown flag bits are rejected with `RUNTIME_MAILBOX_INVALID_PARAMS`.
	1647	+
	1648	+`INITIAL_ACTIVATE` is used exclusively by MCU ROM at the tail of the
	1649	+`EncryptedFirmware` boot flow. MCU ROM has already loaded firmware into MCU
	1650	+SRAM via `RI_DOWNLOAD_ENCRYPTED_FIRMWARE` and decrypted it in place via
	1651	+`CM_AES_GCM_DECRYPT_DMA`. When this flag is set, Caliptra Runtime:
	1652	+
	1653	+- Skips the hitless-update steps (set `RESET_REASON.FwHitlessUpd`, clear
	1654	+ `FW_EXEC_CTRL`, wait for MCU reset request and reset assertion, DMA-reload
	1655	+ from staging, re-`AuthorizeAndStash`).
	1656	+- Just publishes `FW_EXEC_CTRL[MCU]` (and any other requested bits) so that
	1657	+ MCI's `BOOT_RST_MCU` state releases MCU from reset on the next warm reset
	1658	+ that MCU ROM triggers.
	1659	+
	1660	+Caliptra Runtime only honors `INITIAL_ACTIVATE` when all of the following
	1661	+are true; otherwise the command fails with `IMAGE_VERIFIER_ACTIVATION_FAILED`:
	1662	+
	1663	+1. The MCU image bit is included in the activation request.
	1664	+2. The boot mode set by ROM is `EncryptedFirmware` (i.e., ROM received
	1665	+ `RI_DOWNLOAD_ENCRYPTED_FIRMWARE`).
	1666	+3. `FW_EXEC_CTRL[MCU]` is currently `0` — this is an initial activation,
	1667	+ not a hitless update masquerading as one.
	1668	+
	1669	+Together, these checks ensure that the MCU SRAM contents are
	1670	+integrity-protected end-to-end (ciphertext digest verified during recovery;
	1671	+GCM tag verified during `CM_AES_GCM_DECRYPT_DMA`) before Caliptra releases
	1672	+MCU to execute them.
1416	1673
1417	1674	Table: `ACTIVATE_FIRMWARE` output arguments
1418	1675
@@ -1421,6 +1678,28 @@
1421	1678	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
1422	1679	\| fips_status \| u32 \| Indicates if the command is FIPS approved or an error. \|
1423	1680
	1681	+
	1682	+## Mailbox commands: OCP LOCK v1.0
	1683	+
	1684	+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).
	1685	+
	1686	+### ENUMERATE_HPKE_HANDLES
	1687	+### REPORT_HEK_METADATA
	1688	+### GET_ALGORITHMS
	1689	+### INITIALIZE_MEK_SECRET
	1690	+### ROTATE_HPKE_KEY
	1691	+### GENERATE_MEK
	1692	+### GENERATE_MPK
	1693	+### REWRAP_MPK
	1694	+### ENABLE_MPK
	1695	+### MIX_MPK
	1696	+### GET_HPKE_PUB_KEY
	1697	+### TEST_ACCESS_KEY
	1698	+### GET_STATUS
	1699	+### CLEAR_KEY_CACHE
	1700	+### UNLOAD_MEK
	1701	+### LOAD_MEK
	1702	+### DERIVE_MEK
1424	1703
1425	1704	## Mailbox commands: Cryptographic Mailbox (2.0)
1426	1705
@@ -1524,6 +1803,99 @@
1524	1803	\| fips_status \| u32 \| FIPS approved or an error \|
1525	1804	\| hash size \| u32 \|\|
1526	1805	\| hash \| u8[hash size] \|\|
	1806	+
	1807	+
	1808	+### CM\_SHAKE256\_INIT
	1809	+
	1810	+This starts the computation of a SHAKE256 extendable-output hash, which may be larger than a single mailbox command allows.
	1811	+
	1812	+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.
	1813	+
	1814	+The sequence to use these are:
	1815	+* 1 `CM_SHAKE256_INIT` command
	1816	+* 0 or more `CM_SHAKE256_UPDATE` commands
	1817	+* 1 `CM_SHAKE256_FINAL` command
	1818	+
	1819	+For each command, the context from the previous command's output must be passed as an input.
	1820	+
	1821	+The `SHAKE256_CONTEXT_SIZE` is always exactly 44 bytes long (encrypted session token).
	1822	+
	1823	+The maximum supported input data size per command is 4096 bytes.
	1824	+
	1825	+Command Code: `0x434D_5849` ("CMXI")
	1826	+
	1827	+Table: `CM_SHAKE256_INIT` input arguments
	1828	+
	1829	+\| Name \| Type \| Description \|
	1830	+\| --------- \| ------------- \| --------------- \|
	1831	+\| chksum \| u32 \|\|
	1832	+\| data size \| u32 \|\|
	1833	+\| data \| u8[data size] \| Data to hash \|
	1834	+
	1835	+
	1836	+Table: `CM_SHAKE256_INIT` output arguments
	1837	+
	1838	+\| Name \| Type \| Description \|
	1839	+\| ----------- \| ------------------------- \| -------------------------------------------------- \|
	1840	+\| chksum \| u32 \|\|
	1841	+\| fips_status \| u32 \| FIPS approved or an error \|
	1842	+\| context \| u8[SHAKE256_CONTEXT_SIZE] \| Passed to `CM_SHAKE256_UPDATE` / `CM_SHAKE256_FINAL` \|
	1843	+
	1844	+
	1845	+### CM\_SHAKE256\_UPDATE
	1846	+
	1847	+This continues a SHAKE256 computation started by `CM_SHAKE256_INIT` or from another `CM_SHAKE256_UPDATE`.
	1848	+
	1849	+The context MUST be passed in from `CM_SHAKE256_INIT` or `CM_SHAKE256_UPDATE`.
	1850	+
	1851	+Command Code: `0x434D_5855` ("CMXU")
	1852	+
	1853	+Table: `CM_SHAKE256_UPDATE` input arguments
	1854	+
	1855	+\| Name \| Type \| Description \|
	1856	+\| --------- \| ------------------------- \| ---------------------------------------------------- \|
	1857	+\| chksum \| u32 \|\|
	1858	+\| context \| u8[SHAKE256_CONTEXT_SIZE] \| From `CM_SHAKE256_INIT` / `CM_SHAKE256_UPDATE` \|
	1859	+\| data size \| u32 \|\|
	1860	+\| data \| u8[data size] \| Data to hash \|
	1861	+
	1862	+
	1863	+Table: `CM_SHAKE256_UPDATE` output arguments
	1864	+
	1865	+\| Name \| Type \| Description \|
	1866	+\| ----------- \| ------------------------- \| -------------------------------------------------- \|
	1867	+\| chksum \| u32 \|\|
	1868	+\| fips_status \| u32 \| FIPS approved or an error \|
	1869	+\| context \| u8[SHAKE256_CONTEXT_SIZE] \| Passed to `CM_SHAKE256_UPDATE` / `CM_SHAKE256_FINAL` \|
	1870	+
	1871	+
	1872	+### CM\_SHAKE256\_FINAL
	1873	+
	1874	+This finalizes the SHAKE256 computation and produces the hash of all of the data.
	1875	+
	1876	+The context MUST be passed in from `CM_SHAKE256_INIT` or `CM_SHAKE256_UPDATE`.
	1877	+
	1878	+The output is always a 64-byte SHAKE256 digest.
	1879	+
	1880	+Command Code: `0x434D_5846` ("CMXF")
	1881	+
	1882	+Table: `CM_SHAKE256_FINAL` input arguments
	1883	+
	1884	+\| Name \| Type \| Description \|
	1885	+\| ----------- \| ------------------------- \| ---------------------------------------------- \|
	1886	+\| chksum \| u32 \|\|
	1887	+\| context \| u8[SHAKE256_CONTEXT_SIZE] \| From `CM_SHAKE256_INIT` / `CM_SHAKE256_UPDATE` \|
	1888	+\| data size \| u32 \| May be 0 \|
	1889	+\| data \| u8[data size] \| Data to hash \|
	1890	+
	1891	+
	1892	+Table: `CM_SHAKE256_FINAL` output arguments
	1893	+
	1894	+\| Name \| Type \| Description \|
	1895	+\| ----------- \| -------- \| ------------------------- \|
	1896	+\| chksum \| u32 \|\|
	1897	+\| fips_status \| u32 \| FIPS approved or an error \|
	1898	+\| hash \| u8[64] \| SHAKE256 digest \|
1527	1899
1528	1900
1529	1901	### CM\_HMAC
@@ -1814,6 +2186,79 @@
1814	2186	\| fips_status \| u32 \| FIPS approved or an error \|
1815	2187
1816	2188
	2189	+### CM_MLKEM_KEY_GEN
	2190	+
	2191	+Generates an ML-KEM-1024 encapsulation key from the seed (seed\_d \|\| seed\_z, 64 bytes) stored in a CMK with key usage `Mlkem`.
	2192	+
	2193	+The key generation algorithm is described in [FIPS 203](https://csrc.nist.gov/pubs/fips/203/final).
	2194	+
	2195	+Command Code: `0x434D_4C4B` ("CMLK")
	2196	+
	2197	+Table: `CM_MLKEM_KEY_GEN` input arguments
	2198	+\| Name \| Type \| Description \|
	2199	+\| -------- \| -------- \| ---------------------------------------- \|
	2200	+\| chksum \| u32 \|\|
	2201	+\| CMK \| CMK \| ML-KEM seed (seed\_d \|\| seed\_z) \|
	2202	+
	2203	+
	2204	+Table: `CM_MLKEM_KEY_GEN` output arguments
	2205	+\| Name \| Type \| Description \|
	2206	+\| ----------- \| -------- \| ---------------------------------------- \|
	2207	+\| chksum \| u32 \|\|
	2208	+\| fips_status \| u32 \| FIPS approved or an error \|
	2209	+\| encaps_key \| u8[1568] \| ML-KEM-1024 encapsulation key \|
	2210	+
	2211	+
	2212	+### CM_MLKEM_ENCAPSULATE
	2213	+
	2214	+Performs ML-KEM-1024 encapsulation against the provided encapsulation key, producing a ciphertext and a shared key wrapped as a CMK.
	2215	+
	2216	+The encapsulation algorithm is described in [FIPS 203](https://csrc.nist.gov/pubs/fips/203/final).
	2217	+
	2218	+Command Code: `0x434D_4C45` ("CMLE")
	2219	+
	2220	+Table: `CM_MLKEM_ENCAPSULATE` input arguments
	2221	+\| Name \| Type \| Description \|
	2222	+\| ----------- \| -------- \| ---------------------------------------- \|
	2223	+\| chksum \| u32 \|\|
	2224	+\| key_usage \| u32 \| Key usage for the output CMK \|
	2225	+\| encaps_key \| u8[1568] \| ML-KEM-1024 encapsulation key \|
	2226	+
	2227	+
	2228	+Table: `CM_MLKEM_ENCAPSULATE` output arguments
	2229	+\| Name \| Type \| Description \|
	2230	+\| ----------- \| -------- \| ---------------------------------------- \|
	2231	+\| chksum \| u32 \|\|
	2232	+\| fips_status \| u32 \| FIPS approved or an error \|
	2233	+\| ciphertext \| u8[1568] \| ML-KEM-1024 ciphertext \|
	2234	+\| shared_key \| CMK \| CMK of the shared secret key \|
	2235	+
	2236	+
	2237	+### CM_MLKEM_DECAPSULATE
	2238	+
	2239	+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.
	2240	+
	2241	+The decapsulation algorithm is described in [FIPS 203](https://csrc.nist.gov/pubs/fips/203/final).
	2242	+
	2243	+Command Code: `0x434D_4C44` ("CMLD")
	2244	+
	2245	+Table: `CM_MLKEM_DECAPSULATE` input arguments
	2246	+\| Name \| Type \| Description \|
	2247	+\| ----------- \| -------- \| ---------------------------------------- \|
	2248	+\| chksum \| u32 \|\|
	2249	+\| key_usage \| u32 \| Key usage for the output CMK \|
	2250	+\| CMK \| CMK \| ML-KEM seed (seed\_d \|\| seed\_z) \|
	2251	+\| ciphertext \| u8[1568] \| ML-KEM-1024 ciphertext to decapsulate \|
	2252	+
	2253	+
	2254	+Table: `CM_MLKEM_DECAPSULATE` output arguments
	2255	+\| Name \| Type \| Description \|
	2256	+\| ----------- \| -------- \| ---------------------------------------- \|
	2257	+\| chksum \| u32 \|\|
	2258	+\| fips_status \| u32 \| FIPS approved or an error \|
	2259	+\| shared_key \| CMK \| CMK of the shared secret key \|
	2260	+
	2261	+
1817	2262	### CM_AES_ENCRYPT_INIT
1818	2263
1819	2264	Generic AES operation for unauthenticated AES operations.
@@ -1860,8 +2305,7 @@
1860	2305	\| mode \| u32 \|\|
1861	2306	\| key \| u8[32] \|\|
1862	2307	\| iv \| u8[16] \|\|
1863		-\| fips_status \| u8 \| 1 = FIPS valid \|
1864		-\| reserved \| u8[75] \| Reserved for additional fields \|
	2308	+\| reserved \| u8[76] \| Reserved for additional fields \|
1865	2309
1866	2310
1867	2311	The size of the (encrypted) context is always exactly 156 bytes,
@@ -2010,8 +2454,7 @@
2010	2454	\| GHASH state \| u8[16] \|\|
2011	2455	\| current length \| u32 \| value mod 16 is buffer size \|
2012	2456	\| buffer \| u8[16] \|\|
2013		-\| fips_status \| u8 \| 1 = FIPS valid \|
2014		-\| reserved \| u8[15] \|\|
	2457	+\| reserved \| u8[16] \|\|
2015	2458
2016	2459
2017	2460	The size of the (encrypted) context is always exactly 128 bytes,
@@ -2283,6 +2726,45 @@
2283	2726	\| plaintext \| u8[plaintext size] \|\|
2284	2727
2285	2728
	2729	+### CM_AES_GCM_DECRYPT_DMA
	2730	+
	2731	+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.
	2732	+
	2733	+Important restrictions:
	2734	+- This command is only available in subsystem mode, as DMA is only available in subsystem.
	2735	+- This command is only available for MCU.
	2736	+- 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.
	2737	+- The command performs a two-pass operation:
	2738	+ 1. First pass: Verifies the SHA384 hash of the encrypted data at the AXI address
	2739	+ 2. Second pass: Performs in-place AES-GCM decryption via DMA
	2740	+
	2741	+The CMK must be an AES key (key usage = 3) that was previously imported using `CM_IMPORT`.
	2742	+
	2743	+Command Code: `0x434D_4444` ("CMDD")
	2744	+
	2745	+Table: `CM_AES_GCM_DECRYPT_DMA` input arguments
	2746	+\| Name \| Type \| Description \|
	2747	+\| --------------------- \| --------- \| ---------------------------------------------------- \|
	2748	+\| chksum \| u32 \| Checksum over other input arguments \|
	2749	+\| cmk \| CMK \| Encrypted CMK containing the AES-256 key \|
	2750	+\| iv \| u32[3] \| AES-GCM initialization vector (12 bytes) \|
	2751	+\| tag \| u32[4] \| AES-GCM authentication tag (16 bytes) \|
	2752	+\| encrypted_data_sha384 \| u8[48] \| SHA384 hash of the encrypted data for verification \|
	2753	+\| axi_addr_lo \| u32 \| Lower 32 bits of the AXI address \|
	2754	+\| axi_addr_hi \| u32 \| Upper 32 bits of the AXI address \|
	2755	+\| length \| u32 \| Length of data to decrypt in bytes \|
	2756	+\| aad_length \| u32 \| Length of AAD in bytes (0-4095) \|
	2757	+\| aad \| u8[...] \| Additional authenticated data \|
	2758	+
	2759	+
	2760	+Table: `CM_AES_GCM_DECRYPT_DMA` output arguments
	2761	+\| Name \| Type \| Description \|
	2762	+\| ------------ \| -------- \| ----------------------------------------------------- \|
	2763	+\| chksum \| u32 \| Checksum over other output arguments \|
	2764	+\| fips_status \| u32 \| FIPS approved or an error \|
	2765	+\| tag_verified \| u32 \| 1 if GCM tag verification succeeded, 0 if it failed \|
	2766	+
	2767	+
2286	2768	### CM_ECDH_GENERATE
2287	2769
2288	2770	This computes the first half of an Elliptic Curve Diffie-Hellman exchange to compute an ephemeral shared key pair with another party.
@@ -2401,9 +2883,9 @@
2401	2883	### CM\_DERIVE\_STABLE\_KEY
2402	2884
2403	2885	Derives an HMAC key that has a stable value across resets from either
2404		-IDevId or LDevId.
2405		-
2406		-The (interior) value of the returned CMK will be the stable across resets as it is derived indirectly from the IDevId or LDevId CDIs.
	2886	+IDevId, LDevId, or the Owner Root Key (derived from HEK seed).
	2887	+
	2888	+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.
2407	2889	The actual encrypted bytes of the CMK will not be the same, and
2408	2890	the encrypted CMK itself cannot be used across resets. So, the key
2409	2891	will always need to be re-derived after every cold reset.
@@ -2411,22 +2893,36 @@
2411	2893	If a key usage other than HMAC is desired, then the KDF or HKDF
2412	2894	mailbox functions can be used to derive a key from the returned CMK.
2413	2895
2414		-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.
	2896	+`key_type = OwnerKey` is only available in subsystem mode when the Stable Owner
	2897	+Key strap is enabled (`SS_STRAP_GENERIC[3]` bit 0 set to 1) and OCP LOCK is not
	2898	+enabled. If these requirements are not met, the command fails with
	2899	+`CMB_STABLE_OWNER_KEY_NOT_AVAILABLE`.
	2900	+
	2901	+For `OwnerKey`, this command derives from the ROM-populated Stable Owner Root
	2902	+Key. It first runs AES-256-CMAC KDF with `info` as the input data to produce an
	2903	+intermediate key, then runs HMAC-SHA512 KDF with `b"Stable Owner Key" \|\| info`
	2904	+as the domain-separation input to produce the returned 64-byte HMAC key
	2905	+material. Caliptra wraps that key material as an encrypted CMK before returning
	2906	+it to the caller.
	2907	+
	2908	+The command derivation is summarized below:
	2909	+
	2910	+![CM_DERIVE_STABLE_KEY Derivation](../images/caliptra-sw/runtime/../rom/dev/doc/svg/cm-derive-stable-key.svg)
2415	2911
2416	2912	Command Code: `0x434D_4453` ("CMDS")
2417	2913
2418	2914	Table: `CM_DERIVE_STABLE_KEY` input arguments
2419	2915
2420		-\| Name \| Type \| Description
2421		-\| -------- \| -------- \| ---------------
	2916	+\| Name \| Type \| Description \|
	2917	+\| -------- \| -------- \| --------------- \|
2422	2918	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
2423		-\| key_type \| u32 \| Source key to derive the stable key from. 0x0000_0001: IDevId <br> 0x0000_0002: LDevId \|
	2919	+\| 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) \|
2424	2920	\| info \| u8[32] \| Data to use in the key derivation. \|
2425	2921
2426	2922
2427	2923	Table: `CM_DERIVE_STABLE_KEY` output arguments
2428		-\| Name \| Type \| Description
2429		-\| -------- \| -------- \| ---------------
	2924	+\| Name \| Type \| Description \|
	2925	+\| -------- \| -------- \| --------------- \|
2430	2926	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
2431	2927	\| cmk \| CMK \| CMK that stores the stable key material \|
2432	2928
@@ -2436,9 +2932,6 @@
2436	2932	Imports the specified key and returns a CMK for it.
2437	2933
2438	2934	Usage information is required so that the key can be verified and used appropriately.
2439		-
2440		-Note that it is the caller's responsibility to ensure that the source
2441		-key material meets FIPS requirements, such as zeroization.
2442	2935
2443	2936	Command Code: `0x434D_494D` ("CMIM")
2444	2937
@@ -2523,14 +3016,14 @@
2523	3016
2524	3017	Table: `GET_IDEV_ECC384_CSR` input arguments
2525	3018
2526		-\| Name \| Type \| Description
2527		-\| -------- \| -------- \| ---------------
	3019	+\| Name \| Type \| Description \|
	3020	+\| -------- \| -------- \| --------------- \|
2528	3021	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
2529	3022
2530	3023
2531	3024	Table: `GET_IDEV_ECC384_CSR` output arguments
2532		-\| Name \| Type \| Description
2533		-\| -------- \| -------- \| ---------------
	3025	+\| Name \| Type \| Description \|
	3026	+\| -------- \| -------- \| --------------- \|
2534	3027	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
2535	3028	\| data\_size \| u32 \| Length in bytes of the valid data in the data field. \|
2536	3029	\| data \| u8[...] \| DER-encoded ECC384 IDevID certificate signing request. \|
@@ -2542,14 +3035,14 @@
2542	3035
2543	3036	Table: `GET_IDEV_MLDSA87_CSR` input arguments
2544	3037
2545		-\| Name \| Type \| Description
2546		-\| -------- \| -------- \| ---------------
	3038	+\| Name \| Type \| Description \|
	3039	+\| -------- \| -------- \| --------------- \|
2547	3040	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
2548	3041
2549	3042
2550	3043	Table: `GET_IDEV_MLDSA87_CSR` output arguments
2551		-\| Name \| Type \| Description
2552		-\| -------- \| -------- \| ---------------
	3044	+\| Name \| Type \| Description \|
	3045	+\| -------- \| -------- \| --------------- \|
2553	3046	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
2554	3047	\| data\_size \| u32 \| Length in bytes of the valid data in the data field. \|
2555	3048	\| data \| u8[...] \| DER-encoded MLDSA87 IDevID certificate signing request. \|
@@ -2569,14 +3062,14 @@
2569	3062
2570	3063	Table: `GET_FMC_ALIAS_ECC384_CSR` input arguments
2571	3064
2572		-\| Name \| Type \| Description
2573		-\| -------- \| -------- \| ---------------
	3065	+\| Name \| Type \| Description \|
	3066	+\| -------- \| -------- \| --------------- \|
2574	3067	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
2575	3068
2576	3069
2577	3070	Table: `GET_FMC_ALIAS_ECC384_CSR` output arguments
2578		-\| Name \| Type \| Description
2579		-\| -------- \| -------- \| ---------------
	3071	+\| Name \| Type \| Description \|
	3072	+\| -------- \| -------- \| --------------- \|
2580	3073	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
2581	3074	\| data\_size \| u32 \| Length in bytes of the valid data in the data field. \|
2582	3075	\| data \| u8[...] \| DER-encoded ECC384 FMC Alias certificate signing request. \|
@@ -2588,14 +3081,14 @@
2588	3081
2589	3082	Table: `GET_FMC_ALIAS_MLDSA87_CSR` input arguments
2590	3083
2591		-\| Name \| Type \| Description
2592		-\| -------- \| -------- \| ---------------
	3084	+\| Name \| Type \| Description \|
	3085	+\| -------- \| -------- \| --------------- \|
2593	3086	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
2594	3087
2595	3088
2596	3089	Table: `GET_FMC_ALIAS_MLDSA87_CSR` output arguments
2597		-\| Name \| Type \| Description
2598		-\| -------- \| -------- \| ---------------
	3090	+\| Name \| Type \| Description \|
	3091	+\| -------- \| -------- \| --------------- \|
2599	3092	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
2600	3093	\| data\_size \| u32 \| Length in bytes of the valid data in the data field. \|
2601	3094	\| data \| u8[...] \| DER-encoded MLDSA87 FMC Alias certificate signing request. \|
@@ -2609,8 +3102,8 @@
2609	3102
2610	3103	Table: `GET_ATTESTED_ECC384_CSR` input arguments
2611	3104
2612		-\| Name \| Type \| Description
2613		-\| -------- \| -------- \| ---------------
	3105	+\| Name \| Type \| Description \|
	3106	+\| -------- \| -------- \| --------------- \|
2614	3107	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
2615	3108	\| key_id \| u32 \| Key ID for which CSR is requested.<br> 0x0000_0001: LDevId <br> 0x0000_0002: FMC Alias <br> 0x0000_0003: RT Alias \|
2616	3109	\| nonce \| u8[32] \| Nonce to be included in the CSR EAT. \|
@@ -2618,8 +3111,8 @@
2618	3111
2619	3112	Table: `GET_ATTESTED_ECC384_CSR` output arguments
2620	3113
2621		-\| Name \| Type \| Description
2622		-\| -------- \| -------- \| ---------------
	3114	+\| Name \| Type \| Description \|
	3115	+\| -------- \| -------- \| --------------- \|
2623	3116	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
2624	3117	\| data\_size \| u32 \| Length in bytes of the valid data in the data field. \|
2625	3118	\| data \| u8[...] \| DER-encoded ECC384 attested certificate signing request. \|
@@ -2633,8 +3126,8 @@
2633	3126
2634	3127	Table: `GET_ATTESTED_MLDSA87_CSR` input arguments
2635	3128
2636		-\| Name \| Type \| Description
2637		-\| -------- \| -------- \| ---------------
	3129	+\| Name \| Type \| Description \|
	3130	+\| -------- \| -------- \| --------------- \|
2638	3131	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
2639	3132	\| key_id \| u32 \| Key ID for which CSR is requested.<br> 0x0000_0001: LDevId <br> 0x0000_0002: FMC Alias <br> 0x0000_0003: RT Alias \|
2640	3133	\| nonce \| u8[32] \| Nonce to be included in the CSR EAT. \|
@@ -2642,8 +3135,8 @@
2642	3135
2643	3136	Table: `GET_ATTESTED_MLDSA87_CSR` output arguments
2644	3137
2645		-\| Name \| Type \| Description
2646		-\| -------- \| -------- \| ---------------
	3138	+\| Name \| Type \| Description \|
	3139	+\| -------- \| -------- \| --------------- \|
2647	3140	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
2648	3141	\| data\_size \| u32 \| Length in bytes of the valid data in the data field. \|
2649	3142	\| data \| u8[...] \| DER-encoded MLDSA87 attested certificate signing request. \|
@@ -2657,23 +3150,23 @@
2657	3150
2658	3151	Table: `SIGN_WITH_EXPORTED_ECDSA` input arguments
2659	3152
2660		-\| Name \| Type \| Description
2661		-\| -------- \| -------- \| ---------------
	3153	+\| Name \| Type \| Description \|
	3154	+\| -------- \| -------- \| --------------- \|
2662	3155	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
2663		-\| exported_cdi_handle \| u8[32] \| The Exported CDI handle returned by the DPE `DeriveContext` command. Little endian. \|
2664		-\| tbs \| u8[48] \| The bytes to be signed. Little endian. \|
	3156	+\| exported_cdi_handle \| u8[32] \| The exported CDI handle returned by the DPE `DeriveContext` command. Opaque byte array; copy the bytes exactly as returned. \|
	3157	+\| tbs \| u8[48] \| The 48-byte SHA-384 digest to be signed. Raw byte array; no byte swapping is required. \|
2665	3158
2666	3159
2667	3160	Table: `SIGN_WITH_EXPORTED_ECDSA` output arguments
2668		-\| Name \| Type \| Description
2669		-\| -------- \| -------- \| ---------------
	3161	+\| Name \| Type \| Description \|
	3162	+\| -------- \| -------- \| --------------- \|
2670	3163	\| derived_pubkey_x \| u8[48] \| The X BigNum of the ECDSA public key associated with the signing key. \|
2671	3164	\| derived_pubkey_y \| u8[48] \| The Y BigNum of the ECDSA public key associated with the signing key. \|
2672	3165	\| signature_r \| u8[48] \| The R BigNum of an ECDSA signature. \|
2673	3166	\| signature_s \| u8[48] \| The S BigNum of an ECDSA signature. \|
2674	3167
2675	3168
2676		-The `exported_cdi` can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
	3169	+The `exported_cdi_handle` can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
2677	3170
2678	3171	### REVOKE\_EXPORTED\_CDI\_HANDLE
2679	3172
@@ -2683,16 +3176,47 @@
2683	3176
2684	3177	Table: `REVOKE_EXPORTED_CDI_HANDLE` input arguments
2685	3178
2686		-\| Name \| Type \| Description
2687		-\| -------- \| -------- \| ---------------
	3179	+\| Name \| Type \| Description \|
	3180	+\| -------- \| -------- \| --------------- \|
2688	3181	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
2689		-\| exported_cdi_handle \| u8[32] \| The Exported CDI handle returned by the DPE `DeriveContext` command. Little endian. \|
2690		-
2691		-
2692		-The `exported_cdi` can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
	3182	+\| exported_cdi_handle \| u8[32] \| The exported CDI handle returned by the DPE `DeriveContext` command. Opaque byte array; copy the bytes exactly as returned. \|
	3183	+
	3184	+
	3185	+The `exported_cdi_handle` can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
2693	3186
2694	3187	The `exported_cdi_handle` is no longer usable after calling `REVOKE_EXPORTED_CDI_HANDLE` with it. After the `exported_cdi_handle`
2695		-has been revoked, a new exported CDI can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
	3188	+has been revoked, a new exported CDI handle can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
	3189	+
	3190	+### EXTERNAL_MAILBOX_CMD
	3191	+
	3192	+Command Code: `0x4558_544D` ("EXTM")
	3193	+
	3194	+Important restrictions:
	3195	+- This command is only available in subsystem mode in 2.1+.
	3196	+- This command is only available for MCU.
	3197	+
	3198	+Executes a mailbox command located at an AXI address.
	3199	+This allows for executing mailbox commands that are larger than the mailbox allows.
	3200	+
	3201	+This is currently mostly useful for FIRMWARE_LOAD (as part of an update) or SET_AUTH_MANIFEST.
	3202	+
	3203	+The response is still written to the mailbox.
	3204	+
	3205	+The checksum is over the EXTM command, not the command that is loaded over AXI.
	3206	+That external command will still need its own checksum, if applicable.
	3207	+
	3208	+Table: `EXTERNAL_MAILBOX_CMD` input arguments
	3209	+
	3210	+\| Name \| Type \| Description \|
	3211	+\| -------- \| -------- \| --------------- \|
	3212	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
	3213	+\| command_id \| u32 \| Command ID for the mailbox command to be executed. Little endian. \|
	3214	+\| command_size \| u32 \| Size of the mailbox command to be executed. Little endian. \|
	3215	+\| axi_address_low \| u32 \| Lower 32 bits of the AXI address that contains the mailbox command. Little endian. \|
	3216	+\| axi_address_high \| u32 \| High 32 bits of the AXI address that contains the mailbox command. Little endian. \|
	3217	+
	3218	+
	3219	+The response will be the response of the executed external command.
2696	3220
2697	3221	### REALLOCATE\_DPE\_CONTEXT\_LIMITS
2698	3222
@@ -2702,24 +3226,119 @@
2702	3226
2703	3227	Table: `REALLOCATE_DPE_CONTEXT_LIMITS` input arguments
2704	3228
2705		-\| Name \| Type \| Description
2706		-\| -------- \| -------- \| ---------------
	3229	+\| Name \| Type \| Description \|
	3230	+\| -------- \| -------- \| --------------- \|
2707	3231	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
2708	3232	\| pl0_context_limit \| u32 \| Number of contexts to allocate to PL0. PL1 will receive remaining contexts. \|
2709	3233
2710	3234
2711	3235	Table: `REALLOCATE_DPE_CONTEXT_LIMITS` output arguments
2712		-\| Name \| Type \| Description
2713		-\| -------- \| -------- \| ---------------
	3236	+\| Name \| Type \| Description \|
	3237	+\| -------- \| -------- \| --------------- \|
2714	3238	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
2715	3239	\| fips_status \| u32 \| Indicates if the command is FIPS approved or an error. \|
2716	3240	\| new_pl0_context_limit \| u32 \| Number of contexts assigned to PL0 after the reallocation \|
2717	3241	\| new_pl1_context_limit \| u32 \| Number of contexts assigned to PL1 after the reallocation \|
2718	3242
2719	3243
2720		-This allows the user to reallocate the 32 DPE contexts between PL0 and PL1. By default, each gets 16 contexts.
	3244	+This allows the user to reallocate the 64 DPE contexts between PL0 and PL1. By default, each gets 32 contexts.
2721	3245
2722	3246	Note: 2 PL0 contexts are used by Caliptra itself during initialization.
	3247	+
	3248	+### FE\_PROG
	3249	+
	3250	+Programs Field Entropy (FE) into one of 4 FE partitions in the OTP fuse controller. This command
	3251	+is typically used during device provisioning flows.
	3252	+
	3253	+Note: This command is only available when the device is in the Production lifecycle state.
	3254	+
	3255	+Command Code: `0x4645_5052` ("FEPR")
	3256	+
	3257	+Table: `FE_PROG` input arguments
	3258	+
	3259	+\| Name \| Type \| Description
	3260	+\| -------- \| -------- \| ---------------
	3261	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian.
	3262	+\| partition \| u32 \| FE partition number (valid values: 0–3).
	3263	+
	3264	+`FE_PROG` returns no output arguments other than the mailbox response header.
	3265	+
	3266	+### PRODUCTION\_AUTH\_DEBUG\_UNLOCK\_REQ
	3267	+
	3268	+Initiates the production debug unlock flow by generating a cryptographic challenge. The caller
	3269	+must solve the challenge by signing it with the appropriate ECC and MLDSA keys and returning
	3270	+the result via the [`PRODUCTION_AUTH_DEBUG_UNLOCK_TOKEN`](#production_auth_debug_unlock_token)
	3271	+command.
	3272	+
	3273	+This command performs the same function as the ROM's `AUTH_DEBUG_UNLOCK_REQ` command
	3274	+(documented in the [ROM README](../rom/dev/README.md#debug-unlock)), but is available at
	3275	+runtime.
	3276	+
	3277	+Note: This command requires the device to be in the Production lifecycle state and the
	3278	+`PROD_DEBUG_UNLOCK_REQ` bit in the `SS_DBG_MANUF_SERVICE_REG_REQ` register to be set.
	3279	+
	3280	+Command Code: `0x5044_5552` ("PDUR")
	3281	+
	3282	+Table: `PRODUCTION_AUTH_DEBUG_UNLOCK_REQ` input arguments
	3283	+
	3284	+\| Name \| Type \| Description
	3285	+\| -------- \| -------- \| ---------------
	3286	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian.
	3287	+\| length \| u32 \| Length of the payload in DWORDs.
	3288	+\| unlock\_level \| u8 \| Debug unlock level (1–8).
	3289	+\| reserved \| u8[3] \| Reserved.
	3290	+
	3291	+Table: `PRODUCTION_AUTH_DEBUG_UNLOCK_REQ` output arguments
	3292	+
	3293	+\| Name \| Type \| Description
	3294	+\| -------- \| -------- \| ---------------
	3295	+\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian.
	3296	+\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error.
	3297	+\| length \| u32 \| Length of the response payload in DWORDs.
	3298	+\| unique\_device\_identifier \| u8[32] \| Device identifier of the Caliptra device. Byte array; pass through as-is to the token command.
	3299	+\| challenge \| u8[48] \| Random challenge number generated by Caliptra. Byte array; pass through as-is to the token command.
	3300	+
	3301	+### PRODUCTION\_AUTH\_DEBUG\_UNLOCK\_TOKEN
	3302	+
	3303	+Completes the production debug unlock handshake by validating the caller's solution to the
	3304	+challenge generated by
	3305	+[`PRODUCTION_AUTH_DEBUG_UNLOCK_REQ`](#production_auth_debug_unlock_req). The caller must
	3306	+provide the device identifier and challenge from the previous request along with ECC-384 and
	3307	+ML-DSA-87 signatures proving possession of the authorized debug unlock key.
	3308	+
	3309	+Upon successful validation, Caliptra authorizes the debug unlock by setting the unlock level
	3310	+in the `SS_SOC_DBG_UNLOCK_LEVEL` register.
	3311	+
	3312	+This command performs the same function as the ROM's `AUTH_DEBUG_UNLOCK_TOKEN` command
	3313	+(documented in the [ROM README](../rom/dev/README.md#debug-unlock)), but is available at
	3314	+runtime.
	3315	+
	3316	+Note: This command requires a preceding successful `PRODUCTION_AUTH_DEBUG_UNLOCK_REQ` in
	3317	+the same boot session. The challenge is consumed on use and cannot be replayed.
	3318	+
	3319	+Command Code: `0x5044_5554` ("PDUT")
	3320	+
	3321	+Table: `PRODUCTION_AUTH_DEBUG_UNLOCK_TOKEN` input arguments
	3322	+
	3323	+\| Name \| Type \| Description
	3324	+\| -------- \| -------- \| ---------------
	3325	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian.
	3326	+\| length \| u32 \| Length of the payload in DWORDs.
	3327	+\| unique\_device\_identifier \| u8[32] \| Device identifier (must match value from challenge response). Byte array; copied verbatim from the challenge response.
	3328	+\| unlock\_level \| u8 \| Debug unlock level (1–8, must match the original request).
	3329	+\| reserved \| u8[3] \| Reserved.
	3330	+\| challenge \| u8[48] \| Challenge (must match value from challenge response). Byte array; copied verbatim from the challenge response.
	3331	+\| ecc\_public\_key \| u8[96] \| ECC P-384 public key (X \|\| Y, 48 bytes each). See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields).
	3332	+\| mldsa\_public\_key \| u8[2592] \| ML-DSA-87 public key. See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields).
	3333	+\| ecc\_signature \| u8[96] \| ECC P-384 signature over the SHA2-384 message digest. R (48 bytes) \| S (48 bytes). See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields).
	3334	+\| 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).
	3335	+
	3336	+The signed message for both ECC and ML-DSA signatures is the hash of the concatenation:
	3337	+`unique_device_identifier \|\| unlock_level \|\| reserved \|\| challenge` (all as raw bytes).
	3338	+ECC uses SHA2-384; ML-DSA uses SHA2-512.
	3339	+
	3340	+`PRODUCTION_AUTH_DEBUG_UNLOCK_TOKEN` returns no output arguments other than the mailbox
	3341	+response header.
2723	3342
2724	3343	## Checksum
2725	3344
@@ -2743,15 +3362,15 @@
2743	3362
2744	3363	## FIPS status
2745	3364
2746		-For every command, the firmware responds with a FIPS status of FIPS approved. There is
2747		-currently no use case for any other responses or error values.
	3365	+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.
2748	3366
2749	3367	Table: FIPS status codes
2750	3368
2751	3369	\| Name \| Value \| Description \|
2752	3370	\| --------------- \| --------------------------- \| --------------------------------------------------- \|
2753	3371	\| `FIPS_APPROVED` \| `0x0000_0000` \| Status of command is FIPS approved \|
2754		-\| `RESERVED` \| `0x0000_0001 - 0xFFFF_FFFF` \| Other values reserved, will not be sent by Caliptra \|
	3372	+\| `FIPS_NOT_APPROVED_USER_SUPPLIED_DIGEST` \| `0x5553_5244` \| Command is not FIPS approved because the caller supplied the digest instead of the raw message \|
	3373	+\| `RESERVED` \| `0x0000_0002 - 0xFFFF_FFFF` \| Other values reserved, will not be sent by Caliptra \|
2755	3374
2756	3375
2757	3376	## Runtime Firmware updates
@@ -2830,14 +3449,14 @@
2830	3449	To prevent this, we establish active context limits for each PAUSER
2831	3450	privilege level:
2832	3451
2833		-* PL0 - 16 active contexts
2834		-* PL1 - 16 active contexts
	3452	+* PL0 - 32 active contexts
	3453	+* PL1 - 32 active contexts
2835	3454
2836	3455	If a DPE command were to activate a new context such that the total number of
2837	3456	active contexts in a privilege level is above its active context limit, the
2838	3457	InvokeDpe command should fail.
2839	3458
2840		-At boot Caliptra Runtime FW consumes part of the PL0 active contexts (initially 16) to DeriveContext for:
	3459	+At boot Caliptra Runtime FW consumes part of the PL0 active contexts (initially 32) to DeriveContext for:
2841	3460	- RTFW Journey (RTFJ) Measurement (1)
2842	3461	- Caliptra Configured Initialization Values digest (CCIV) (1)
2843	3462	- ROM Stashed Measurements (max 8)
@@ -2845,20 +3464,20 @@
2845	3464	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
2846	3465	of active contexts in PL0's locality, and hence allow PL1 to DOS PL0.
2847	3466
2848		-### DPE profile implementation
2849		-
2850		-The DPE iRoT profile leaves some choices up to implementers. This section
2851		-describes specific requirements for the Caliptra DPE implementation.
	3467	+### Caliptra DPE Profile
	3468	+
	3469	+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.
2852	3470
2853	3471	\| Name \| Value \| Description \|
2854	3472	\| -------------------------- \| ------------------------------ \| ------------------------------------------------------------------------------------------------------ \|
2855		-\| Profile Variant \| `DPE_PROFILE_IROT_P384_SHA384` \| The profile variant that Caliptra implements. \|
	3473	+\| Profile Variant \| `Caliptra DPE Profile` \| Derived from `DPE_PROFILE_IROT_P384_SHA384`. \|
2856	3474	\| KDF \| SP800-108 HMAC-CTR \| KDF to use for CDI (tcg.derive.kdf-sha384) and asymmetric key (tcg.derive.kdf-sha384-p384) derivation. \|
2857	3475	\| Simulation Context Support \| Yes \| Whether Caliptra implements the optional Simulation Contexts feature. \|
2858	3476	\| Supports ExtendTci \| Yes \| Whether Caliptra implements the optional ExtendTci command. \|
2859	3477	\| Supports Auto Init \| Yes \| Whether Caliptra will automatically initialize the default DPE context. \|
2860	3478	\| Supports Rotate Context \| Yes \| Whether Caliptra supports the optional RotateContextHandle command. \|
2861	3479	\| CertifyKey Alias Key \| Caliptra Runtime Alias Key \| The key that will be used to sign certificates that are produced by the DPE CertifyKey command. \|
	3480	+\| `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. \|
2862	3481
2863	3482
2864	3483	### Supported DPE commands
@@ -2869,6 +3488,7 @@
2869	3488	* InitializeContext
2870	3489	* DeriveContext
2871	3490	* Note: The "export-cdi" flag is only available in the locality of the PL0 PAUSER.
	3491	+ * 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.
2872	3492	* CertifyKey
2873	3493	* Caliptra DPE supports two formats for CertifyKey: X.509 and PKCS#10 CSR.
2874	3494	X.509 is only available to PL0 PAUSERs.

Changes to Runtime Specification