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/7575a31842f21837d768c7a67f04132eb61c8850/runtime/README.md" target="_blank">chipsalliance/caliptra-sw/runtime/README.md</a> @ <code>7575a31</code>
	2	+📄 Source: <a href="https://github.com/chipsalliance/caliptra-sw/blob/5e44fc2319cd998578bca2f3e73e9f8499cf92f4/runtime/README.md" target="_blank">chipsalliance/caliptra-sw/runtime/README.md</a> @ <code>5e44fc2</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
@@ -40,6 +46,20 @@
40	46	* Initialize the [DICE Protection Environment (DPE)](#dice-protection-environment-dpe)
41	47	* Initialize any SRAM structures used by Runtime Firmware
42	48	* Upload the firwmare to the Manufacturer Control Unit (2.0, susbystem 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 two mailbox commands: [`SET_AUTH_MANIFEST`](#set-auth-manifest), and [`AUTHORIZE_AND_STASH`](#authorize-and-stash).
	211	+Manifest-based image authorization is implemented via two mailbox commands: [`SET_AUTH_MANIFEST`](#set_auth_manifest), and [`AUTHORIZE_AND_STASH`](#authorize_and_stash).
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[127] \| The max number of metadata entries is 127 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
@@ -1298,8 +1496,8 @@
1298	1496
1299	1497	Table: `AUTHORIZE_AND_STASH` input arguments
1300	1498
1301		-\| Name \| Type \| Description
1302		-\| ------------\| -------- \| ---------------
	1499	+\| Name \| Type \| Description \|
	1500	+\| ------------ \| -------- \| --------------- \|
1303	1501	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
1304	1502	\| fw_id \| u8[4] \| Firmware id of the image, in little-endian format \|
1305	1503	\| 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. \|
@@ -1321,8 +1519,8 @@
1321	1519	\| --------------- \| -------- \| -------------------------------------------------------------------------- \|
1322	1520	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
1323	1521	\| fips_status \| u32 \| Indicates if the command is FIPS approved or an error. \|
1324		-
1325		-\| auth_req_result \| u32 \|AUTHORIZE_IMAGE (0xDEADC0DE), IMAGE_NOT_AUTHORIZED (0x21523F21) or IMAGE_HASH_MISMATCH (0x8BFB95CB)
	1522	+\| auth_req_result \| u32 \| AUTHORIZE_IMAGE (0xDEADC0DE), IMAGE_NOT_AUTHORIZED (0x21523F21) or IMAGE_HASH_MISMATCH (0x8BFB95CB) \|
	1523	+
1326	1524
1327	1525	### GET_IMAGE_INFO
1328	1526
@@ -1335,8 +1533,8 @@
1335	1533	\| Name \| Type \| Description \|
1336	1534	\| -------------- \| -------------- \| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- \|
1337	1535	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
1338		-
1339		-\| fw_id \| u32 \| Firmware id of the image, in little-endian format
	1536	+\| fw_id \| u32 \| Firmware id of the image, in little-endian format \|
	1537	+
1340	1538
1341	1539	Table: `GET_IMAGE_INFO` output arguments
1342	1540
@@ -1344,13 +1542,36 @@
1344	1542	\| -------------- \| -------------- \| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- \|
1345	1543	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
1346	1544	\| fips_status \| u32 \| Indicates if the command is FIPS approved or an error. \|
1347		-\| 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) \|
1348		-\| 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) \|
1349		-\| 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) \|
1350		-\| 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) \|
1351		-\| 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) \|
1352		-\| 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) \|
	1545	+\| 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) \|
	1546	+\| flags \| u32 \| This corresponds to the `flags` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main/auth-manifest/README.md) \|
	1547	+\| 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) \|
	1548	+\| 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) \|
	1549	+\| 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) \|
	1550	+\| 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) \|
1353	1551	\| digest \| u8[48] \| SHA-384 digest of the image. Only present in FW 2.0.2+ and 2.1.1+. \|
	1552	+
	1553	+
	1554	+### GET\_MCU\_FW\_SIZE
	1555	+
	1556	+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.
	1557	+
	1558	+Command Code: `0x474D_4653` ("GMFS")
	1559	+
	1560	+Table: `GET_MCU_FW_SIZE` input arguments
	1561	+
	1562	+\| Name \| Type \| Description \|
	1563	+\| -------------- \| -------------- \| --------------------------------------------------------------------------- \|
	1564	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
	1565	+
	1566	+
	1567	+Table: `GET_MCU_FW_SIZE` output arguments
	1568	+
	1569	+\| Name \| Type \| Description \|
	1570	+\| -------------- \| -------------- \| -------------------------------------------------------------------------- \|
	1571	+\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
	1572	+\| fips_status \| u32 \| Indicates if the command is FIPS approved or an error. \|
	1573	+\| size \| u32 \| Size of the MCU firmware image in bytes. \|
	1574	+\| sha384 \| u8[48] \| SHA-384 digest of the encrypted MCU firmware image. \|
1354	1575
1355	1576
1356	1577	### ACTIVATE_FIRMWARE
@@ -1368,7 +1589,43 @@
1368	1589	\| count \| u32 \| Number of image_ids to activate. Item count of image_ids array parameter \|
1369	1590	\| mcu_image_size \| u32 \| Size of MCU image, if included in the activation \|
1370	1591	\| image_ids \| Array of u8[4] \| Array of Image ids in little-endian format \|
1371		-
	1592	+\| flags \| u32 \| Optional flags (see below). Caliptra runtime 2.1.1+ only. \|
	1593	+
	1594	+
	1595	+Flags
	1596	+
	1597	+\| Bit \| Name \| Description \|
	1598	+\| ------- \| ----------------- \| ------------------------------------------------------------------------------------------------------------------------ \|
	1599	+\| 0 \| `INITIAL_ACTIVATE` \| First-time MCU activation after the encrypted-boot flow. Caliptra runtime 2.1.1+ only. See below. \|
	1600	+
	1601	+
	1602	+Unknown flag bits are rejected with `RUNTIME_MAILBOX_INVALID_PARAMS`.
	1603	+
	1604	+`INITIAL_ACTIVATE` is used exclusively by MCU ROM at the tail of the
	1605	+`EncryptedFirmware` boot flow. MCU ROM has already loaded firmware into MCU
	1606	+SRAM via `RI_DOWNLOAD_ENCRYPTED_FIRMWARE` and decrypted it in place via
	1607	+`CM_AES_GCM_DECRYPT_DMA`. When this flag is set, Caliptra Runtime:
	1608	+
	1609	+- Skips the hitless-update steps (set `RESET_REASON.FwHitlessUpd`, clear
	1610	+ `FW_EXEC_CTRL`, wait for MCU reset request and reset assertion, DMA-reload
	1611	+ from staging, re-`AuthorizeAndStash`).
	1612	+- Just publishes `FW_EXEC_CTRL[MCU]` (and any other requested bits) so that
	1613	+ MCI's `BOOT_RST_MCU` state releases MCU from reset on the next warm reset
	1614	+ that MCU ROM triggers.
	1615	+
	1616	+Caliptra Runtime only honors `INITIAL_ACTIVATE` when all of the following
	1617	+are true; otherwise the command fails with `IMAGE_VERIFIER_ACTIVATION_FAILED`:
	1618	+
	1619	+1. The MCU image bit is included in the activation request.
	1620	+2. The boot mode set by ROM is `EncryptedFirmware` (i.e., ROM received
	1621	+ `RI_DOWNLOAD_ENCRYPTED_FIRMWARE`).
	1622	+3. `FW_EXEC_CTRL[MCU]` is currently `0` — this is an initial activation,
	1623	+ not a hitless update masquerading as one.
	1624	+
	1625	+Together, these checks ensure that the MCU SRAM contents are
	1626	+integrity-protected end-to-end (ciphertext digest verified during recovery;
	1627	+GCM tag verified during `CM_AES_GCM_DECRYPT_DMA`) before Caliptra releases
	1628	+MCU to execute them.
1372	1629
1373	1630	Table: `ACTIVATE_FIRMWARE` output arguments
1374	1631
@@ -1377,6 +1634,28 @@
1377	1634	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
1378	1635	\| fips_status \| u32 \| Indicates if the command is FIPS approved or an error. \|
1379	1636
	1637	+
	1638	+## Mailbox commands: OCP LOCK v1.0
	1639	+
	1640	+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).
	1641	+
	1642	+### ENUMERATE_HPKE_HANDLES
	1643	+### REPORT_HEK_METADATA
	1644	+### GET_ALGORITHMS
	1645	+### INITIALIZE_MEK_SECRET
	1646	+### ROTATE_HPKE_KEY
	1647	+### GENERATE_MEK
	1648	+### GENERATE_MPK
	1649	+### REWRAP_MPK
	1650	+### ENABLE_MPK
	1651	+### MIX_MPK
	1652	+### GET_HPKE_PUB_KEY
	1653	+### TEST_ACCESS_KEY
	1654	+### GET_STATUS
	1655	+### CLEAR_KEY_CACHE
	1656	+### UNLOAD_MEK
	1657	+### LOAD_MEK
	1658	+### DERIVE_MEK
1380	1659
1381	1660	## Mailbox commands: Cryptographic Mailbox (2.0)
1382	1661
@@ -1480,6 +1759,99 @@
1480	1759	\| fips_status \| u32 \| FIPS approved or an error \|
1481	1760	\| hash size \| u32 \|\|
1482	1761	\| hash \| u8[hash size] \|\|
	1762	+
	1763	+
	1764	+### CM\_SHAKE256\_INIT
	1765	+
	1766	+This starts the computation of a SHAKE256 extendable-output hash, which may be larger than a single mailbox command allows.
	1767	+
	1768	+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.
	1769	+
	1770	+The sequence to use these are:
	1771	+* 1 `CM_SHAKE256_INIT` command
	1772	+* 0 or more `CM_SHAKE256_UPDATE` commands
	1773	+* 1 `CM_SHAKE256_FINAL` command
	1774	+
	1775	+For each command, the context from the previous command's output must be passed as an input.
	1776	+
	1777	+The `SHAKE256_CONTEXT_SIZE` is always exactly 44 bytes long (encrypted session token).
	1778	+
	1779	+The maximum supported input data size per command is 4096 bytes.
	1780	+
	1781	+Command Code: `0x434D_5849` ("CMXI")
	1782	+
	1783	+Table: `CM_SHAKE256_INIT` input arguments
	1784	+
	1785	+\| Name \| Type \| Description \|
	1786	+\| --------- \| ------------- \| --------------- \|
	1787	+\| chksum \| u32 \|\|
	1788	+\| data size \| u32 \|\|
	1789	+\| data \| u8[data size] \| Data to hash \|
	1790	+
	1791	+
	1792	+Table: `CM_SHAKE256_INIT` output arguments
	1793	+
	1794	+\| Name \| Type \| Description \|
	1795	+\| ----------- \| ------------------------- \| -------------------------------------------------- \|
	1796	+\| chksum \| u32 \|\|
	1797	+\| fips_status \| u32 \| FIPS approved or an error \|
	1798	+\| context \| u8[SHAKE256_CONTEXT_SIZE] \| Passed to `CM_SHAKE256_UPDATE` / `CM_SHAKE256_FINAL` \|
	1799	+
	1800	+
	1801	+### CM\_SHAKE256\_UPDATE
	1802	+
	1803	+This continues a SHAKE256 computation started by `CM_SHAKE256_INIT` or from another `CM_SHAKE256_UPDATE`.
	1804	+
	1805	+The context MUST be passed in from `CM_SHAKE256_INIT` or `CM_SHAKE256_UPDATE`.
	1806	+
	1807	+Command Code: `0x434D_5855` ("CMXU")
	1808	+
	1809	+Table: `CM_SHAKE256_UPDATE` input arguments
	1810	+
	1811	+\| Name \| Type \| Description \|
	1812	+\| --------- \| ------------------------- \| ---------------------------------------------------- \|
	1813	+\| chksum \| u32 \|\|
	1814	+\| context \| u8[SHAKE256_CONTEXT_SIZE] \| From `CM_SHAKE256_INIT` / `CM_SHAKE256_UPDATE` \|
	1815	+\| data size \| u32 \|\|
	1816	+\| data \| u8[data size] \| Data to hash \|
	1817	+
	1818	+
	1819	+Table: `CM_SHAKE256_UPDATE` output arguments
	1820	+
	1821	+\| Name \| Type \| Description \|
	1822	+\| ----------- \| ------------------------- \| -------------------------------------------------- \|
	1823	+\| chksum \| u32 \|\|
	1824	+\| fips_status \| u32 \| FIPS approved or an error \|
	1825	+\| context \| u8[SHAKE256_CONTEXT_SIZE] \| Passed to `CM_SHAKE256_UPDATE` / `CM_SHAKE256_FINAL` \|
	1826	+
	1827	+
	1828	+### CM\_SHAKE256\_FINAL
	1829	+
	1830	+This finalizes the SHAKE256 computation and produces the hash of all of the data.
	1831	+
	1832	+The context MUST be passed in from `CM_SHAKE256_INIT` or `CM_SHAKE256_UPDATE`.
	1833	+
	1834	+The output is always a 64-byte SHAKE256 digest.
	1835	+
	1836	+Command Code: `0x434D_5846` ("CMXF")
	1837	+
	1838	+Table: `CM_SHAKE256_FINAL` input arguments
	1839	+
	1840	+\| Name \| Type \| Description \|
	1841	+\| ----------- \| ------------------------- \| ---------------------------------------------- \|
	1842	+\| chksum \| u32 \|\|
	1843	+\| context \| u8[SHAKE256_CONTEXT_SIZE] \| From `CM_SHAKE256_INIT` / `CM_SHAKE256_UPDATE` \|
	1844	+\| data size \| u32 \| May be 0 \|
	1845	+\| data \| u8[data size] \| Data to hash \|
	1846	+
	1847	+
	1848	+Table: `CM_SHAKE256_FINAL` output arguments
	1849	+
	1850	+\| Name \| Type \| Description \|
	1851	+\| ----------- \| -------- \| ------------------------- \|
	1852	+\| chksum \| u32 \|\|
	1853	+\| fips_status \| u32 \| FIPS approved or an error \|
	1854	+\| hash \| u8[64] \| SHAKE256 digest \|
1483	1855
1484	1856
1485	1857	### CM\_HMAC
@@ -1770,6 +2142,79 @@
1770	2142	\| fips_status \| u32 \| FIPS approved or an error \|
1771	2143
1772	2144
	2145	+### CM_MLKEM_KEY_GEN
	2146	+
	2147	+Generates an ML-KEM-1024 encapsulation key from the seed (seed\_d \|\| seed\_z, 64 bytes) stored in a CMK with key usage `Mlkem`.
	2148	+
	2149	+The key generation algorithm is described in [FIPS 203](https://csrc.nist.gov/pubs/fips/203/final).
	2150	+
	2151	+Command Code: `0x434D_4C4B` ("CMLK")
	2152	+
	2153	+Table: `CM_MLKEM_KEY_GEN` input arguments
	2154	+\| Name \| Type \| Description \|
	2155	+\| -------- \| -------- \| ---------------------------------------- \|
	2156	+\| chksum \| u32 \|\|
	2157	+\| CMK \| CMK \| ML-KEM seed (seed\_d \|\| seed\_z) \|
	2158	+
	2159	+
	2160	+Table: `CM_MLKEM_KEY_GEN` output arguments
	2161	+\| Name \| Type \| Description \|
	2162	+\| ----------- \| -------- \| ---------------------------------------- \|
	2163	+\| chksum \| u32 \|\|
	2164	+\| fips_status \| u32 \| FIPS approved or an error \|
	2165	+\| encaps_key \| u8[1568] \| ML-KEM-1024 encapsulation key \|
	2166	+
	2167	+
	2168	+### CM_MLKEM_ENCAPSULATE
	2169	+
	2170	+Performs ML-KEM-1024 encapsulation against the provided encapsulation key, producing a ciphertext and a shared key wrapped as a CMK.
	2171	+
	2172	+The encapsulation algorithm is described in [FIPS 203](https://csrc.nist.gov/pubs/fips/203/final).
	2173	+
	2174	+Command Code: `0x434D_4C45` ("CMLE")
	2175	+
	2176	+Table: `CM_MLKEM_ENCAPSULATE` input arguments
	2177	+\| Name \| Type \| Description \|
	2178	+\| ----------- \| -------- \| ---------------------------------------- \|
	2179	+\| chksum \| u32 \|\|
	2180	+\| key_usage \| u32 \| Key usage for the output CMK \|
	2181	+\| encaps_key \| u8[1568] \| ML-KEM-1024 encapsulation key \|
	2182	+
	2183	+
	2184	+Table: `CM_MLKEM_ENCAPSULATE` output arguments
	2185	+\| Name \| Type \| Description \|
	2186	+\| ----------- \| -------- \| ---------------------------------------- \|
	2187	+\| chksum \| u32 \|\|
	2188	+\| fips_status \| u32 \| FIPS approved or an error \|
	2189	+\| ciphertext \| u8[1568] \| ML-KEM-1024 ciphertext \|
	2190	+\| shared_key \| CMK \| CMK of the shared secret key \|
	2191	+
	2192	+
	2193	+### CM_MLKEM_DECAPSULATE
	2194	+
	2195	+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.
	2196	+
	2197	+The decapsulation algorithm is described in [FIPS 203](https://csrc.nist.gov/pubs/fips/203/final).
	2198	+
	2199	+Command Code: `0x434D_4C44` ("CMLD")
	2200	+
	2201	+Table: `CM_MLKEM_DECAPSULATE` input arguments
	2202	+\| Name \| Type \| Description \|
	2203	+\| ----------- \| -------- \| ---------------------------------------- \|
	2204	+\| chksum \| u32 \|\|
	2205	+\| key_usage \| u32 \| Key usage for the output CMK \|
	2206	+\| CMK \| CMK \| ML-KEM seed (seed\_d \|\| seed\_z) \|
	2207	+\| ciphertext \| u8[1568] \| ML-KEM-1024 ciphertext to decapsulate \|
	2208	+
	2209	+
	2210	+Table: `CM_MLKEM_DECAPSULATE` output arguments
	2211	+\| Name \| Type \| Description \|
	2212	+\| ----------- \| -------- \| ---------------------------------------- \|
	2213	+\| chksum \| u32 \|\|
	2214	+\| fips_status \| u32 \| FIPS approved or an error \|
	2215	+\| shared_key \| CMK \| CMK of the shared secret key \|
	2216	+
	2217	+
1773	2218	### CM_AES_ENCRYPT_INIT
1774	2219
1775	2220	Generic AES operation for unauthenticated AES operations.
@@ -1816,8 +2261,7 @@
1816	2261	\| mode \| u32 \|\|
1817	2262	\| key \| u8[32] \|\|
1818	2263	\| iv \| u8[16] \|\|
1819		-\| fips_status \| u8 \| 1 = FIPS valid \|
1820		-\| reserved \| u8[75] \| Reserved for additional fields \|
	2264	+\| reserved \| u8[76] \| Reserved for additional fields \|
1821	2265
1822	2266
1823	2267	The size of the (encrypted) context is always exactly 156 bytes,
@@ -1966,8 +2410,7 @@
1966	2410	\| GHASH state \| u8[16] \|\|
1967	2411	\| current length \| u32 \| value mod 16 is buffer size \|
1968	2412	\| buffer \| u8[16] \|\|
1969		-\| fips_status \| u8 \| 1 = FIPS valid \|
1970		-\| reserved \| u8[15] \|\|
	2413	+\| reserved \| u8[16] \|\|
1971	2414
1972	2415
1973	2416	The size of the (encrypted) context is always exactly 128 bytes,
@@ -2239,6 +2682,45 @@
2239	2682	\| plaintext \| u8[plaintext size] \|\|
2240	2683
2241	2684
	2685	+### CM_AES_GCM_DECRYPT_DMA
	2686	+
	2687	+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.
	2688	+
	2689	+Important restrictions:
	2690	+- This command is only available in subsystem mode, as DMA is only available in subsystem.
	2691	+- This command is only available for MCU.
	2692	+- 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.
	2693	+- The command performs a two-pass operation:
	2694	+ 1. First pass: Verifies the SHA384 hash of the encrypted data at the AXI address
	2695	+ 2. Second pass: Performs in-place AES-GCM decryption via DMA
	2696	+
	2697	+The CMK must be an AES key (key usage = 3) that was previously imported using `CM_IMPORT`.
	2698	+
	2699	+Command Code: `0x434D_4444` ("CMDD")
	2700	+
	2701	+Table: `CM_AES_GCM_DECRYPT_DMA` input arguments
	2702	+\| Name \| Type \| Description \|
	2703	+\| --------------------- \| --------- \| ---------------------------------------------------- \|
	2704	+\| chksum \| u32 \| Checksum over other input arguments \|
	2705	+\| cmk \| CMK \| Encrypted CMK containing the AES-256 key \|
	2706	+\| iv \| u32[3] \| AES-GCM initialization vector (12 bytes) \|
	2707	+\| tag \| u32[4] \| AES-GCM authentication tag (16 bytes) \|
	2708	+\| encrypted_data_sha384 \| u8[48] \| SHA384 hash of the encrypted data for verification \|
	2709	+\| axi_addr_lo \| u32 \| Lower 32 bits of the AXI address \|
	2710	+\| axi_addr_hi \| u32 \| Upper 32 bits of the AXI address \|
	2711	+\| length \| u32 \| Length of data to decrypt in bytes \|
	2712	+\| aad_length \| u32 \| Length of AAD in bytes (0-4095) \|
	2713	+\| aad \| u8[...] \| Additional authenticated data \|
	2714	+
	2715	+
	2716	+Table: `CM_AES_GCM_DECRYPT_DMA` output arguments
	2717	+\| Name \| Type \| Description \|
	2718	+\| ------------ \| -------- \| ----------------------------------------------------- \|
	2719	+\| chksum \| u32 \| Checksum over other output arguments \|
	2720	+\| fips_status \| u32 \| FIPS approved or an error \|
	2721	+\| tag_verified \| u32 \| 1 if GCM tag verification succeeded, 0 if it failed \|
	2722	+
	2723	+
2242	2724	### CM_ECDH_GENERATE
2243	2725
2244	2726	This computes the first half of an Elliptic Curve Diffie-Hellman exchange to compute an ephemeral shared key pair with another party.
@@ -2357,9 +2839,9 @@
2357	2839	### CM\_DERIVE\_STABLE\_KEY
2358	2840
2359	2841	Derives an HMAC key that has a stable value across resets from either
2360		-IDevId or LDevId.
2361		-
2362		-The (interior) value of the returned CMK will be the stable across resets as it is derived indirectly from the IDevId or LDevId CDIs.
	2842	+IDevId, LDevId, or the Owner Root Key (derived from HEK seed).
	2843	+
	2844	+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.
2363	2845	The actual encrypted bytes of the CMK will not be the same, and
2364	2846	the encrypted CMK itself cannot be used across resets. So, the key
2365	2847	will always need to be re-derived after every cold reset.
@@ -2367,22 +2849,32 @@
2367	2849	If a key usage other than HMAC is desired, then the KDF or HKDF
2368	2850	mailbox functions can be used to derive a key from the returned CMK.
2369	2851
2370		-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.
	2852	+`key_type = OwnerKey` is only available in subsystem mode when the Stable Owner
	2853	+Key strap is enabled (`SS_STRAP_GENERIC[3]` bit 0 set to 1) and OCP LOCK is not
	2854	+enabled. If these requirements are not met, the command fails with
	2855	+`CMB_STABLE_OWNER_KEY_NOT_AVAILABLE`.
	2856	+
	2857	+For `OwnerKey`, this command derives from the ROM-populated Stable Owner Root
	2858	+Key. It first runs AES-256-CMAC KDF with `info` as the input data to produce an
	2859	+intermediate key, then runs HMAC-SHA512 KDF with `b"Stable Owner Key" \|\| info`
	2860	+as the domain-separation input to produce the returned 64-byte HMAC key
	2861	+material. Caliptra wraps that key material as an encrypted CMK before returning
	2862	+it to the caller.
2371	2863
2372	2864	Command Code: `0x434D_4453` ("CMDS")
2373	2865
2374	2866	Table: `CM_DERIVE_STABLE_KEY` input arguments
2375	2867
2376		-\| Name \| Type \| Description
2377		-\| -------- \| -------- \| ---------------
	2868	+\| Name \| Type \| Description \|
	2869	+\| -------- \| -------- \| --------------- \|
2378	2870	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
2379		-\| key_type \| u32 \| Source key to derive the stable key from. 0x0000_0001: IDevId <br> 0x0000_0002: LDevId \|
	2871	+\| 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) \|
2380	2872	\| info \| u8[32] \| Data to use in the key derivation. \|
2381	2873
2382	2874
2383	2875	Table: `CM_DERIVE_STABLE_KEY` output arguments
2384		-\| Name \| Type \| Description
2385		-\| -------- \| -------- \| ---------------
	2876	+\| Name \| Type \| Description \|
	2877	+\| -------- \| -------- \| --------------- \|
2386	2878	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
2387	2879	\| cmk \| CMK \| CMK that stores the stable key material \|
2388	2880
@@ -2392,9 +2884,6 @@
2392	2884	Imports the specified key and returns a CMK for it.
2393	2885
2394	2886	Usage information is required so that the key can be verified and used appropriately.
2395		-
2396		-Note that it is the caller's responsibility to ensure that the source
2397		-key material meets FIPS requirements, such as zeroization.
2398	2887
2399	2888	Command Code: `0x434D_494D` ("CMIM")
2400	2889
@@ -2479,14 +2968,14 @@
2479	2968
2480	2969	Table: `GET_IDEV_ECC384_CSR` input arguments
2481	2970
2482		-\| Name \| Type \| Description
2483		-\| -------- \| -------- \| ---------------
	2971	+\| Name \| Type \| Description \|
	2972	+\| -------- \| -------- \| --------------- \|
2484	2973	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
2485	2974
2486	2975
2487	2976	Table: `GET_IDEV_ECC384_CSR` output arguments
2488		-\| Name \| Type \| Description
2489		-\| -------- \| -------- \| ---------------
	2977	+\| Name \| Type \| Description \|
	2978	+\| -------- \| -------- \| --------------- \|
2490	2979	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
2491	2980	\| data\_size \| u32 \| Length in bytes of the valid data in the data field. \|
2492	2981	\| data \| u8[...] \| DER-encoded ECC384 IDevID certificate signing request. \|
@@ -2498,14 +2987,14 @@
2498	2987
2499	2988	Table: `GET_IDEV_MLDSA87_CSR` input arguments
2500	2989
2501		-\| Name \| Type \| Description
2502		-\| -------- \| -------- \| ---------------
	2990	+\| Name \| Type \| Description \|
	2991	+\| -------- \| -------- \| --------------- \|
2503	2992	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
2504	2993
2505	2994
2506	2995	Table: `GET_IDEV_MLDSA87_CSR` output arguments
2507		-\| Name \| Type \| Description
2508		-\| -------- \| -------- \| ---------------
	2996	+\| Name \| Type \| Description \|
	2997	+\| -------- \| -------- \| --------------- \|
2509	2998	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
2510	2999	\| data\_size \| u32 \| Length in bytes of the valid data in the data field. \|
2511	3000	\| data \| u8[...] \| DER-encoded MLDSA87 IDevID certificate signing request. \|
@@ -2525,14 +3014,14 @@
2525	3014
2526	3015	Table: `GET_FMC_ALIAS_ECC384_CSR` input arguments
2527	3016
2528		-\| Name \| Type \| Description
2529		-\| -------- \| -------- \| ---------------
	3017	+\| Name \| Type \| Description \|
	3018	+\| -------- \| -------- \| --------------- \|
2530	3019	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
2531	3020
2532	3021
2533	3022	Table: `GET_FMC_ALIAS_ECC384_CSR` output arguments
2534		-\| Name \| Type \| Description
2535		-\| -------- \| -------- \| ---------------
	3023	+\| Name \| Type \| Description \|
	3024	+\| -------- \| -------- \| --------------- \|
2536	3025	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
2537	3026	\| data\_size \| u32 \| Length in bytes of the valid data in the data field. \|
2538	3027	\| data \| u8[...] \| DER-encoded ECC384 FMC Alias certificate signing request. \|
@@ -2544,14 +3033,14 @@
2544	3033
2545	3034	Table: `GET_FMC_ALIAS_MLDSA87_CSR` input arguments
2546	3035
2547		-\| Name \| Type \| Description
2548		-\| -------- \| -------- \| ---------------
	3036	+\| Name \| Type \| Description \|
	3037	+\| -------- \| -------- \| --------------- \|
2549	3038	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
2550	3039
2551	3040
2552	3041	Table: `GET_FMC_ALIAS_MLDSA87_CSR` output arguments
2553		-\| Name \| Type \| Description
2554		-\| -------- \| -------- \| ---------------
	3042	+\| Name \| Type \| Description \|
	3043	+\| -------- \| -------- \| --------------- \|
2555	3044	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
2556	3045	\| data\_size \| u32 \| Length in bytes of the valid data in the data field. \|
2557	3046	\| data \| u8[...] \| DER-encoded MLDSA87 FMC Alias certificate signing request. \|
@@ -2565,8 +3054,8 @@
2565	3054
2566	3055	Table: `GET_ATTESTED_ECC384_CSR` input arguments
2567	3056
2568		-\| Name \| Type \| Description
2569		-\| -------- \| -------- \| ---------------
	3057	+\| Name \| Type \| Description \|
	3058	+\| -------- \| -------- \| --------------- \|
2570	3059	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
2571	3060	\| key_id \| u32 \| Key ID for which CSR is requested.<br> 0x0000_0001: LDevId <br> 0x0000_0002: FMC Alias <br> 0x0000_0003: RT Alias \|
2572	3061	\| nonce \| u8[32] \| Nonce to be included in the CSR EAT. \|
@@ -2574,8 +3063,8 @@
2574	3063
2575	3064	Table: `GET_ATTESTED_ECC384_CSR` output arguments
2576	3065
2577		-\| Name \| Type \| Description
2578		-\| -------- \| -------- \| ---------------
	3066	+\| Name \| Type \| Description \|
	3067	+\| -------- \| -------- \| --------------- \|
2579	3068	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
2580	3069	\| data\_size \| u32 \| Length in bytes of the valid data in the data field. \|
2581	3070	\| data \| u8[...] \| DER-encoded ECC384 attested certificate signing request. \|
@@ -2589,8 +3078,8 @@
2589	3078
2590	3079	Table: `GET_ATTESTED_MLDSA87_CSR` input arguments
2591	3080
2592		-\| Name \| Type \| Description
2593		-\| -------- \| -------- \| ---------------
	3081	+\| Name \| Type \| Description \|
	3082	+\| -------- \| -------- \| --------------- \|
2594	3083	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
2595	3084	\| key_id \| u32 \| Key ID for which CSR is requested.<br> 0x0000_0001: LDevId <br> 0x0000_0002: FMC Alias <br> 0x0000_0003: RT Alias \|
2596	3085	\| nonce \| u8[32] \| Nonce to be included in the CSR EAT. \|
@@ -2598,8 +3087,8 @@
2598	3087
2599	3088	Table: `GET_ATTESTED_MLDSA87_CSR` output arguments
2600	3089
2601		-\| Name \| Type \| Description
2602		-\| -------- \| -------- \| ---------------
	3090	+\| Name \| Type \| Description \|
	3091	+\| -------- \| -------- \| --------------- \|
2603	3092	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
2604	3093	\| data\_size \| u32 \| Length in bytes of the valid data in the data field. \|
2605	3094	\| data \| u8[...] \| DER-encoded MLDSA87 attested certificate signing request. \|
@@ -2613,23 +3102,23 @@
2613	3102
2614	3103	Table: `SIGN_WITH_EXPORTED_ECDSA` input arguments
2615	3104
2616		-\| Name \| Type \| Description
2617		-\| -------- \| -------- \| ---------------
	3105	+\| Name \| Type \| Description \|
	3106	+\| -------- \| -------- \| --------------- \|
2618	3107	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
2619		-\| exported_cdi_handle \| u8[32] \| The Exported CDI handle returned by the DPE `DeriveContext` command. Little endian. \|
2620		-\| tbs \| u8[48] \| The bytes to be signed. Little endian. \|
	3108	+\| exported_cdi_handle \| u8[32] \| The exported CDI handle returned by the DPE `DeriveContext` command. Opaque byte array; copy the bytes exactly as returned. \|
	3109	+\| tbs \| u8[48] \| The 48-byte SHA-384 digest to be signed. Raw byte array; no byte swapping is required. \|
2621	3110
2622	3111
2623	3112	Table: `SIGN_WITH_EXPORTED_ECDSA` output arguments
2624		-\| Name \| Type \| Description
2625		-\| -------- \| -------- \| ---------------
	3113	+\| Name \| Type \| Description \|
	3114	+\| -------- \| -------- \| --------------- \|
2626	3115	\| derived_pubkey_x \| u8[48] \| The X BigNum of the ECDSA public key associated with the signing key. \|
2627	3116	\| derived_pubkey_y \| u8[48] \| The Y BigNum of the ECDSA public key associated with the signing key. \|
2628	3117	\| signature_r \| u8[48] \| The R BigNum of an ECDSA signature. \|
2629	3118	\| signature_s \| u8[48] \| The S BigNum of an ECDSA signature. \|
2630	3119
2631	3120
2632		-The `exported_cdi` can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
	3121	+The `exported_cdi_handle` can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
2633	3122
2634	3123	### REVOKE\_EXPORTED\_CDI\_HANDLE
2635	3124
@@ -2639,16 +3128,47 @@
2639	3128
2640	3129	Table: `REVOKE_EXPORTED_CDI_HANDLE` input arguments
2641	3130
2642		-\| Name \| Type \| Description
2643		-\| -------- \| -------- \| ---------------
	3131	+\| Name \| Type \| Description \|
	3132	+\| -------- \| -------- \| --------------- \|
2644	3133	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
2645		-\| exported_cdi_handle \| u8[32] \| The Exported CDI handle returned by the DPE `DeriveContext` command. Little endian. \|
2646		-
2647		-
2648		-The `exported_cdi` can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
	3134	+\| exported_cdi_handle \| u8[32] \| The exported CDI handle returned by the DPE `DeriveContext` command. Opaque byte array; copy the bytes exactly as returned. \|
	3135	+
	3136	+
	3137	+The `exported_cdi_handle` can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
2649	3138
2650	3139	The `exported_cdi_handle` is no longer usable after calling `REVOKE_EXPORTED_CDI_HANDLE` with it. After the `exported_cdi_handle`
2651		-has been revoked, a new exported CDI can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
	3140	+has been revoked, a new exported CDI handle can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
	3141	+
	3142	+### EXTERNAL_MAILBOX_CMD
	3143	+
	3144	+Command Code: `0x4558_544D` ("EXTM")
	3145	+
	3146	+Important restrictions:
	3147	+- This command is only available in subsystem mode in 2.1+.
	3148	+- This command is only available for MCU.
	3149	+
	3150	+Executes a mailbox command located at an AXI address.
	3151	+This allows for executing mailbox commands that are larger than the mailbox allows.
	3152	+
	3153	+This is currently mostly useful for FIRMWARE_LOAD (as part of an update) or SET_AUTH_MANIFEST.
	3154	+
	3155	+The response is still written to the mailbox.
	3156	+
	3157	+The checksum is over the EXTM command, not the command that is loaded over AXI.
	3158	+That external command will still need its own checksum, if applicable.
	3159	+
	3160	+Table: `EXTERNAL_MAILBOX_CMD` input arguments
	3161	+
	3162	+\| Name \| Type \| Description \|
	3163	+\| -------- \| -------- \| --------------- \|
	3164	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
	3165	+\| command_id \| u32 \| Command ID for the mailbox command to be executed. Little endian. \|
	3166	+\| command_size \| u32 \| Size of the mailbox command to be executed. Little endian. \|
	3167	+\| axi_address_low \| u32 \| Lower 32 bits of the AXI address that contains the mailbox command. Little endian. \|
	3168	+\| axi_address_high \| u32 \| High 32 bits of the AXI address that contains the mailbox command. Little endian. \|
	3169	+
	3170	+
	3171	+The response will be the response of the executed external command.
2652	3172
2653	3173	### REALLOCATE\_DPE\_CONTEXT\_LIMITS
2654	3174
@@ -2658,24 +3178,119 @@
2658	3178
2659	3179	Table: `REALLOCATE_DPE_CONTEXT_LIMITS` input arguments
2660	3180
2661		-\| Name \| Type \| Description
2662		-\| -------- \| -------- \| ---------------
	3181	+\| Name \| Type \| Description \|
	3182	+\| -------- \| -------- \| --------------- \|
2663	3183	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
2664	3184	\| pl0_context_limit \| u32 \| Number of contexts to allocate to PL0. PL1 will receive remaining contexts. \|
2665	3185
2666	3186
2667	3187	Table: `REALLOCATE_DPE_CONTEXT_LIMITS` output arguments
2668		-\| Name \| Type \| Description
2669		-\| -------- \| -------- \| ---------------
	3188	+\| Name \| Type \| Description \|
	3189	+\| -------- \| -------- \| --------------- \|
2670	3190	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
2671	3191	\| fips_status \| u32 \| Indicates if the command is FIPS approved or an error. \|
2672	3192	\| new_pl0_context_limit \| u32 \| Number of contexts assigned to PL0 after the reallocation \|
2673	3193	\| new_pl1_context_limit \| u32 \| Number of contexts assigned to PL1 after the reallocation \|
2674	3194
2675	3195
2676		-This allows the user to reallocate the 32 DPE contexts between PL0 and PL1. By default, each gets 16 contexts.
	3196	+This allows the user to reallocate the 64 DPE contexts between PL0 and PL1. By default, each gets 32 contexts.
2677	3197
2678	3198	Note: 2 PL0 contexts are used by Caliptra itself during initialization.
	3199	+
	3200	+### FE\_PROG
	3201	+
	3202	+Programs Field Entropy (FE) into one of 4 FE partitions in the OTP fuse controller. This command
	3203	+is typically used during device provisioning flows.
	3204	+
	3205	+Note: This command is only available when the device is in the Production lifecycle state.
	3206	+
	3207	+Command Code: `0x4645_5052` ("FEPR")
	3208	+
	3209	+Table: `FE_PROG` input arguments
	3210	+
	3211	+\| Name \| Type \| Description
	3212	+\| -------- \| -------- \| ---------------
	3213	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian.
	3214	+\| partition \| u32 \| FE partition number (valid values: 0–3).
	3215	+
	3216	+`FE_PROG` returns no output arguments other than the mailbox response header.
	3217	+
	3218	+### PRODUCTION\_AUTH\_DEBUG\_UNLOCK\_REQ
	3219	+
	3220	+Initiates the production debug unlock flow by generating a cryptographic challenge. The caller
	3221	+must solve the challenge by signing it with the appropriate ECC and MLDSA keys and returning
	3222	+the result via the [`PRODUCTION_AUTH_DEBUG_UNLOCK_TOKEN`](#production_auth_debug_unlock_token)
	3223	+command.
	3224	+
	3225	+This command performs the same function as the ROM's `AUTH_DEBUG_UNLOCK_REQ` command
	3226	+(documented in the [ROM README](../rom/dev/README.md#debug-unlock)), but is available at
	3227	+runtime.
	3228	+
	3229	+Note: This command requires the device to be in the Production lifecycle state and the
	3230	+`PROD_DEBUG_UNLOCK_REQ` bit in the `SS_DBG_MANUF_SERVICE_REG_REQ` register to be set.
	3231	+
	3232	+Command Code: `0x5044_5552` ("PDUR")
	3233	+
	3234	+Table: `PRODUCTION_AUTH_DEBUG_UNLOCK_REQ` input arguments
	3235	+
	3236	+\| Name \| Type \| Description
	3237	+\| -------- \| -------- \| ---------------
	3238	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian.
	3239	+\| length \| u32 \| Length of the payload in DWORDs.
	3240	+\| unlock\_level \| u8 \| Debug unlock level (1–8).
	3241	+\| reserved \| u8[3] \| Reserved.
	3242	+
	3243	+Table: `PRODUCTION_AUTH_DEBUG_UNLOCK_REQ` output arguments
	3244	+
	3245	+\| Name \| Type \| Description
	3246	+\| -------- \| -------- \| ---------------
	3247	+\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian.
	3248	+\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error.
	3249	+\| length \| u32 \| Length of the response payload in DWORDs.
	3250	+\| unique\_device\_identifier \| u8[32] \| Device identifier of the Caliptra device. Byte array; pass through as-is to the token command.
	3251	+\| challenge \| u8[48] \| Random challenge number generated by Caliptra. Byte array; pass through as-is to the token command.
	3252	+
	3253	+### PRODUCTION\_AUTH\_DEBUG\_UNLOCK\_TOKEN
	3254	+
	3255	+Completes the production debug unlock handshake by validating the caller's solution to the
	3256	+challenge generated by
	3257	+[`PRODUCTION_AUTH_DEBUG_UNLOCK_REQ`](#production_auth_debug_unlock_req). The caller must
	3258	+provide the device identifier and challenge from the previous request along with ECC-384 and
	3259	+ML-DSA-87 signatures proving possession of the authorized debug unlock key.
	3260	+
	3261	+Upon successful validation, Caliptra authorizes the debug unlock by setting the unlock level
	3262	+in the `SS_SOC_DBG_UNLOCK_LEVEL` register.
	3263	+
	3264	+This command performs the same function as the ROM's `AUTH_DEBUG_UNLOCK_TOKEN` command
	3265	+(documented in the [ROM README](../rom/dev/README.md#debug-unlock)), but is available at
	3266	+runtime.
	3267	+
	3268	+Note: This command requires a preceding successful `PRODUCTION_AUTH_DEBUG_UNLOCK_REQ` in
	3269	+the same boot session. The challenge is consumed on use and cannot be replayed.
	3270	+
	3271	+Command Code: `0x5044_5554` ("PDUT")
	3272	+
	3273	+Table: `PRODUCTION_AUTH_DEBUG_UNLOCK_TOKEN` input arguments
	3274	+
	3275	+\| Name \| Type \| Description
	3276	+\| -------- \| -------- \| ---------------
	3277	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian.
	3278	+\| length \| u32 \| Length of the payload in DWORDs.
	3279	+\| unique\_device\_identifier \| u8[32] \| Device identifier (must match value from challenge response). Byte array; copied verbatim from the challenge response.
	3280	+\| unlock\_level \| u8 \| Debug unlock level (1–8, must match the original request).
	3281	+\| reserved \| u8[3] \| Reserved.
	3282	+\| challenge \| u8[48] \| Challenge (must match value from challenge response). Byte array; copied verbatim from the challenge response.
	3283	+\| 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).
	3284	+\| mldsa\_public\_key \| u8[2592] \| ML-DSA-87 public key. See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields).
	3285	+\| 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).
	3286	+\| 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).
	3287	+
	3288	+The signed message for both ECC and ML-DSA signatures is the hash of the concatenation:
	3289	+`unique_device_identifier \|\| unlock_level \|\| reserved \|\| challenge` (all as raw bytes).
	3290	+ECC uses SHA2-384; ML-DSA uses SHA2-512.
	3291	+
	3292	+`PRODUCTION_AUTH_DEBUG_UNLOCK_TOKEN` returns no output arguments other than the mailbox
	3293	+response header.
2679	3294
2680	3295	## Checksum
2681	3296
@@ -2699,15 +3314,15 @@
2699	3314
2700	3315	## FIPS status
2701	3316
2702		-For every command, the firmware responds with a FIPS status of FIPS approved. There is
2703		-currently no use case for any other responses or error values.
	3317	+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.
2704	3318
2705	3319	Table: FIPS status codes
2706	3320
2707	3321	\| Name \| Value \| Description \|
2708	3322	\| --------------- \| --------------------------- \| --------------------------------------------------- \|
2709	3323	\| `FIPS_APPROVED` \| `0x0000_0000` \| Status of command is FIPS approved \|
2710		-\| `RESERVED` \| `0x0000_0001 - 0xFFFF_FFFF` \| Other values reserved, will not be sent by Caliptra \|
	3324	+\| `FIPS_NOT_APPROVED_USER_SUPPLIED_DIGEST` \| `0x5553_5244` \| Command is not FIPS approved because the caller supplied the digest instead of the raw message \|
	3325	+\| `RESERVED` \| `0x0000_0002 - 0xFFFF_FFFF` \| Other values reserved, will not be sent by Caliptra \|
2711	3326
2712	3327
2713	3328	## Runtime Firmware updates
@@ -2786,14 +3401,14 @@
2786	3401	To prevent this, we establish active context limits for each PAUSER
2787	3402	privilege level:
2788	3403
2789		-* PL0 - 16 active contexts
2790		-* PL1 - 16 active contexts
	3404	+* PL0 - 32 active contexts
	3405	+* PL1 - 32 active contexts
2791	3406
2792	3407	If a DPE command were to activate a new context such that the total number of
2793	3408	active contexts in a privilege level is above its active context limit, the
2794	3409	InvokeDpe command should fail.
2795	3410
2796		-At boot Caliptra Runtime FW consumes part of the PL0 active contexts (initially 16) to DeriveContext for:
	3411	+At boot Caliptra Runtime FW consumes part of the PL0 active contexts (initially 32) to DeriveContext for:
2797	3412	- RTFW Journey (RTFJ) Measurement (1)
2798	3413	- Caliptra Configured Initialization Values digest (CCIV) (1)
2799	3414	- ROM Stashed Measurements (max 8)
@@ -2801,20 +3416,20 @@
2801	3416	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
2802	3417	of active contexts in PL0's locality, and hence allow PL1 to DOS PL0.
2803	3418
2804		-### DPE profile implementation
2805		-
2806		-The DPE iRoT profile leaves some choices up to implementers. This section
2807		-describes specific requirements for the Caliptra DPE implementation.
	3419	+### Caliptra DPE Profile
	3420	+
	3421	+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.
2808	3422
2809	3423	\| Name \| Value \| Description \|
2810	3424	\| -------------------------- \| ------------------------------ \| ------------------------------------------------------------------------------------------------------ \|
2811		-\| Profile Variant \| `DPE_PROFILE_IROT_P384_SHA384` \| The profile variant that Caliptra implements. \|
	3425	+\| Profile Variant \| `Caliptra DPE Profile` \| Derived from `DPE_PROFILE_IROT_P384_SHA384`. \|
2812	3426	\| KDF \| SP800-108 HMAC-CTR \| KDF to use for CDI (tcg.derive.kdf-sha384) and asymmetric key (tcg.derive.kdf-sha384-p384) derivation. \|
2813	3427	\| Simulation Context Support \| Yes \| Whether Caliptra implements the optional Simulation Contexts feature. \|
2814	3428	\| Supports ExtendTci \| Yes \| Whether Caliptra implements the optional ExtendTci command. \|
2815	3429	\| Supports Auto Init \| Yes \| Whether Caliptra will automatically initialize the default DPE context. \|
2816	3430	\| Supports Rotate Context \| Yes \| Whether Caliptra supports the optional RotateContextHandle command. \|
2817	3431	\| CertifyKey Alias Key \| Caliptra Runtime Alias Key \| The key that will be used to sign certificates that are produced by the DPE CertifyKey command. \|
	3432	+\| `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. \|
2818	3433
2819	3434
2820	3435	### Supported DPE commands
@@ -2825,6 +3440,7 @@
2825	3440	* InitializeContext
2826	3441	* DeriveContext
2827	3442	* Note: The "export-cdi" flag is only available in the locality of the PL0 PAUSER.
	3443	+ * 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.
2828	3444	* CertifyKey
2829	3445	* Caliptra DPE supports two formats for CertifyKey: X.509 and PKCS#10 CSR.
2830	3446	X.509 is only available to PL0 PAUSERs.

Changes to Runtime Specification