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/b86bbb793cc236e80b37f3d4359a9758672b70a1/runtime/README.md" target="_blank">chipsalliance/caliptra-sw/runtime/README.md</a> @ <code>b86bbb7</code>
	2	+📄 Source: <a href="https://github.com/chipsalliance/caliptra-sw/blob/a38c99b60c97df406201e098df1b89e9301a26d1/runtime/README.md" target="_blank">chipsalliance/caliptra-sw/runtime/README.md</a> @ <code>a38c99b</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
@@ -25,9 +25,14 @@
25	25	* [Cryptographic mailbox commands](#cryptographic-mailbox-commands-new-in-20)
26	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	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	+
	34	+
28	35	## Spec Opens
29		-
30		-* Cryptographic Mailbox: ML-KEM support
31	36
32	37	## Runtime Firmware environment
33	38
@@ -40,6 +45,20 @@
40	45	* Initialize the [DICE Protection Environment (DPE)](#dice-protection-environment-dpe)
41	46	* Initialize any SRAM structures used by Runtime Firmware
42	47	* Upload the firwmare to the Manufacturer Control Unit (2.0, susbystem mode only)
	48	+
	49	+#### Encrypted Firmware Support (2.1, subsystem mode only)
	50	+
	51	+When ROM receives the `RI_DOWNLOAD_ENCRYPTED_FIRMWARE` command instead of `RI_DOWNLOAD_FIRMWARE`, it sets the boot mode to `EncryptedFirmware`. In this mode:
	52	+
	53	+1. Runtime downloads the encrypted MCU firmware to MCU SRAM via the recovery interface
	54	+2. Runtime does not activate the MCU firmware immediately
	55	+3. The MCU ROM can then:
	56	+ - Import an AES key using `CM_IMPORT`
	57	+ - Decrypt the firmware in-place using `CM_AES_GCM_DECRYPT_DMA`
	58	+ - 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.
	59	+ - Trigger a warm reset; MCI releases MCU once `FW_EXEC_CTRL[MCU]` is asserted, and MCU FwBoot jumps into the decrypted firmware.
	60	+
	61	+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	62
44	63	For behavior during other types of reset, see [Runtime firmware updates](#runtime-firmware-updates).
45	64
@@ -94,7 +113,7 @@
94	113
95	114	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	115
97		-These mailbox commands provide SHA, HMAC, HKDF, AES, RNG, MLDSA, and ECDSA services.
	116	+These mailbox commands provide SHA, HMAC, HKDF, AES, RNG, MLDSA, ECDSA, and ML-KEM services.
98	117
99	118	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	119
@@ -126,8 +145,7 @@
126	145
127	146	\| Name \| Bits \| Description \|
128	147	\| ------------- \| -------- \| -------------------------------------- \|
129		-\| version \| 8 \| CMK version. Currently always 1. \|
130		-\| flags \| 8 \| Bit 0 = FIPS valid \|
	148	+\| version \| 16 \| CMK version. Currently always 1. \|
131	149	\| length \| 16 \| how many bits of key material are used \|
132	150	\| key usage \| 8 \| represents which kind of key this is \|
133	151	\| id \| 24 \| ID number \|
@@ -162,8 +180,10 @@
162	180	\| --------- \| --------- \|
163	181	\| 0 \| Reserved \|
164	182	\| 1 \| HMAC \|
165		-\| 2 \| HKDF \|
166		-\| 3 \| AES \|
	183	+\| 2 \| AES \|
	184	+\| 3 \| ECDSA \|
	185	+\| 4 \| MLDSA \|
	186	+\| 5 \| ML-KEM \|
167	187
168	188
169	189	#### Replay Prevention and Deletion
@@ -187,7 +207,7 @@
187	207
188	208	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	209
190		-Manifest-based image authorization is implemented via two mailbox commands: [`SET_AUTH_MANIFEST`](#set-auth-manifest), and [`AUTHORIZE_AND_STASH`](#authorize-and-stash).
	210	+Manifest-based image authorization is implemented via two mailbox commands: [`SET_AUTH_MANIFEST`](#set_auth_manifest), and [`AUTHORIZE_AND_STASH`](#authorize_and_stash).
191	211
192	212	### Caliptra-Endorsed Aggregated Measured Boot
193	213
@@ -303,6 +323,68 @@
303	323	Mailbox user 0xFFFF_FFFF is reserved for Caliptra internal use. All mailbox
304	324	commands from that user will fail.
305	325
	326	+### Byte order of cryptographic fields
	327	+
	328	+Several mailbox commands include ECC P-384 and ML-DSA-87 public keys,
	329	+signatures, and SHA digest values stored as `[u32]` arrays.
	330	+The "big endian" / "little endian" labels in individual command tables describe
	331	+how the standard byte representation produced by cryptographic
	332	+tools maps to those `u32` words.
	333	+
	334	+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.
	335	+
	336	+#### ECC P-384 fields (big-endian words)
	337	+
	338	+Each 4-byte group from the standard representation is byte-reversed on the
	339	+wire.
	340	+
	341	+Example — suppose OpenSSL produces a 48-byte X coordinate starting with:
	342	+
	343	+```
	344	+OpenSSL raw bytes: AB CD EF 01 23 45 67 89 ...
	345	+ ~~~~~~~~~~~ ~~~~~~~~~~~
	346	+Mailbox bytes: 01 EF CD AB 89 67 45 23 ...
	347	+```
	348	+
	349	+In other words: split the tool output into 4-byte groups, then reverse each
	350	+group.
	351	+
	352	+#### ML-DSA-87 fields (little-endian words)
	353	+
	354	+No conversion is needed. Copy the raw bytes produced by an ML-DSA-87
	355	+implementation (e.g., OpenSSL 3.5+, the `fips204` crate, or the NIST reference
	356	+implementation) directly into the mailbox buffer.
	357	+
	358	+```
	359	+openssl pkey output: AB CD EF 01 23 45 67 89 ...
	360	+Mailbox bytes: AB CD EF 01 23 45 67 89 ... (identical)
	361	+```
	362	+
	363	+#### SHA digest fields (big-endian words)
	364	+
	365	+Hash digests stored as `u32[N]` arrays use the same big-endian word convention
	366	+as ECC fields. Each 4-byte group of the standard hash output is byte-reversed
	367	+on the wire.
	368	+
	369	+Example — suppose `openssl dgst -sha384` produces a digest starting with:
	370	+
	371	+```
	372	+openssl output: A1 B2 C3 D4 E5 F6 07 18 ...
	373	+ ~~~~~~~~~~~ ~~~~~~~~~~~
	374	+Mailbox u32[12]: D4 C3 B2 A1 18 07 F6 E5 ...
	375	+```
	376	+
	377	+#### u8 byte-array fields (no conversion needed)
	378	+
	379	+When ECC P-384 keys, signatures, or SHA digests are declared as `u8[48]` (rather
	380	+than `u32[12]`), they use standard big-endian byte order — the same format
	381	+produced by OpenSSL and other cryptographic tools. No byte-swapping is required.
	382	+
	383	+For example, the `ECDSA384_SIGNATURE_VERIFY` input fields (`pub_key_x`,
	384	+`pub_key_y`, `signature_r`, `signature_s`, `hash`) and the `QUOTE_PCRS_ECC384`
	385	+output fields (`digest`, `signature_r`, `signature_s`) can be used directly with
	386	+`openssl` or OpenSSL's `BN_bin2bn()` without any conversion.
	387	+
306	388	### FW\_LOAD
307	389
308	390	The `FIRMWARE_LOAD` command is handled by both ROM and Runtime Firmware.
@@ -367,7 +449,14 @@
367	449	\| -------- \| -------- \| ---------------
368	450	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian.
369	451	\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error.
370		-\| capabilities \| u8[16] \| Firmware capabilities
	452	+\| capabilities \| u8[16] \| Firmware capabilities. See table below for details.
	453	+
	454	+Table: Firmware Capabilities Flags
	455	+
	456	+\| Name \| Bit \| Description
	457	+\| --------------- \| ------- \| ---------------
	458	+\| `RT_BASE` \| 64 \| Base capabilities for Caliptra Runtime v2.1.
	459	+\| `RT_OCP_LOCK` \| 65 \| Runtime firmware and hardware supports OCP LOCK.
371	460
372	461	### GET\_IDEV\_ECC384\_CERT
373	462
@@ -740,7 +829,7 @@
740	829	\| Name \| Type \| Description
741	830	\| -------- \| -------- \| ---------------
742	831	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian.
743		-\| digest \| u32[12] \| Owner public key hash.
	832	+\| digest \| u32[12] \| Owner public key hash. See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields).
744	833
745	834	Table: `INSTALL_OWNER_PK_HASH` output arguments
746	835
@@ -811,13 +900,13 @@
811	900	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian.
812	901	\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error.
813	902
814		-### INVOKE\_DPE\_COMMAND
815		-
816		-Invokes a serialized DPE command.
	903	+### INVOKE\_DPE\_ECC384
	904	+
	905	+Invokes a serialized EC-P384 DPE profile command.
817	906
818	907	Command Code: `0x4450_4543` ("DPEC")
819	908
820		-Table: `INVOKE_DPE_COMMAND` input arguments
	909	+Table: `INVOKE_DPE_ECC384` input arguments
821	910
822	911	\| Name \| Type \| Description
823	912	\| -------- \| -------- \| ---------------
@@ -825,7 +914,49 @@
825	914	\| data\_size \| u32 \| Length in bytes of the valid data in the data field.
826	915	\| data \| u8[...] \| DPE command structure as defined in the DPE iRoT profile.
827	916
828		-Table: `INVOKE_DPE_COMMAND` output arguments
	917	+Table: `INVOKE_DPE_ECC384` output arguments
	918	+
	919	+\| Name \| Type \| Description
	920	+\| -------- \| -------- \| ---------------
	921	+\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian.
	922	+\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error.
	923	+\| data\_size \| u32 \| Length in bytes of the valid data in the data field.
	924	+\| data \| u8[...] \| DPE response structure as defined in the DPE iRoT profile.
	925	+
	926	+### INVOKE\_DPE\_MLDSA87
	927	+
	928	+Invokes a serialized ML-DSA-87 DPE profile command. In subsystem mode a response
	929	+can be DMA'ed to an external address. This is especially useful for large
	930	+commands like `CertifyKey` or `DeriveContext` when exporting a CDI. Both of
	931	+these responses contain a potentially large certificate/CSR. To use this
	932	+feature, set the EXTERNAL_AXI_RESPONSE in `flags` and set the corresponding
	933	+AXI address and size fields. The response over the mailbox will only contain a
	934	+mailbox header (`chksum` and `fips_status`). The full response including the
	935	+mailbox header will be found at the given address.
	936	+
	937	+Command Code: `0x4450_4543` ("DPEC")
	938	+
	939	+Table: `INVOKE_DPE_MLDSA87` input arguments
	940	+
	941	+\| Name \| Type \| Description \|
	942	+\| -------------- \| -------- \| --------------------------------------------------------------------------- \|
	943	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
	944	+\| flags \| u32 \| Flags to give configurations of the command. \|
	945	+\| axi\_addr\_lo \| u32 \| Lower word of the destination physical address. \|
	946	+\| axi\_addr\_hi \| u32 \| Upper word of the destination physical address. \|
	947	+\| axi\_max\_size \| u32 \| Maximum DMA response size. \|
	948	+\| data\_size \| u32 \| Length in bytes of the valid data in the data field. \|
	949	+\| data \| u8[...] \| DPE command structure as defined in the DPE iRoT profile. \|
	950	+
	951	+
	952	+Table: `INVOKE_DPE_MLDSA87` input flags
	953	+
	954	+\| Name \| Value \|
	955	+\| ----------------------- \| --------- \|
	956	+\| EXTERNAL\_AXI\_RESPONSE \| 1 << 31 \|
	957	+
	958	+
	959	+Table: `INVOKE_DPE_MLDSA87` output arguments
829	960
830	961	\| Name \| Type \| Description
831	962	\| -------- \| -------- \| ---------------
@@ -888,8 +1019,36 @@
888	1019	\| PCRs \| PcrValue[32] \| Values of all PCRs.
889	1020	\| nonce \| u8[32] \| Return the nonce used as input for convenience.
890	1021	\| 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.
	1022	+\| 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	1023	\| 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.
	1024	+
	1025	+Digest byte order: The `digest` field has two transformations applied relative
	1026	+to the standard `openssl dgst -sha512` output: (1) the 16 u32 words are in
	1027	+reversed order, and (2) the bytes within each word are reversed. For example, if
	1028	+`openssl dgst -sha512` produces `A1 B2 C3 D4 E5 F6 07 18 ... P1 P2 P3 P4`,
	1029	+the mailbox response contains `P4 P3 P2 P1 ... 18 07 F6 E5 D4 C3 B2 A1`.
	1030	+
	1031	+To independently recompute this digest from PCR values and nonce, compute the
	1032	+SHA2-512 hash, then apply two steps:
	1033	+
	1034	+```
	1035	+openssl dgst -sha512 output (64 bytes, shown as 16 four-byte groups):
	1036	+ A1 B2 C3 D4 \| E5 F6 07 18 \| ... \| M1 M2 M3 M4 \| P1 P2 P3 P4
	1037	+
	1038	+Step 1 — reverse the bytes within each 4-byte group:
	1039	+ D4 C3 B2 A1 \| 18 07 F6 E5 \| ... \| M4 M3 M2 M1 \| P4 P3 P2 P1
	1040	+
	1041	+Step 2 — reverse the order of all 16 groups:
	1042	+ P4 P3 P2 P1 \| M4 M3 M2 M1 \| ... \| 18 07 F6 E5 \| D4 C3 B2 A1
	1043	+ ^^^^^^^^^^^^ ^^^^^^^^^^^^
	1044	+ (last group from Step 1 is now first) (first group is now last)
	1045	+
	1046	+Mailbox digest = result of Step 2
	1047	+```
	1048	+
	1049	+To verify the signature with an external tool such as OpenSSL, pass the `digest`
	1050	+bytes as-is as the pre-hashed message to ML-DSA-87 verification — no conversion
	1051	+is needed because the signature was computed over these exact bytes.
893	1052
894	1053	### EXTEND\_PCR
895	1054
@@ -1149,35 +1308,69 @@
1149	1308	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian.
1150	1309	\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error.
1151	1310
1152		-### CERTIFY\_KEY\_EXTENDED
1153		-
1154		-Produces a DPE leaf certificate or CSR containing custom extensions provided by the SoC.
	1311	+### CERTIFY\_KEY\_EXTENDED\_ECC384
	1312	+
	1313	+Produces an ECC-P384 DPE leaf certificate or CSR containing custom extensions provided by the SoC.
1155	1314
1156	1315	Command Code: `0x434B_4558` ("CKEX")
1157	1316
1158		-Table: `CERTIFY_KEY_EXTENDED` input arguments
	1317	+Table: `CERTIFY_KEY_EXTENDED_ECC384` input arguments
1159	1318
1160	1319	\| Name \| Type \| Description \|
1161	1320	\| ----------------- \| -------- \| --------------------------------------------------------------------------- \|
1162	1321	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
	1322	+\| flags \| u32 \| Flags determining which custom extensions to include in the certificate. \|
1163	1323	\| 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
	1324	+
	1325	+
	1326	+Table: `CERTIFY_KEY_EXTENDED_ECC384` input flags
1168	1327
1169	1328	\| Name \| Offset \|
1170		-\| --------------- \| ---------- \|
1171		-\| DMTF_OTHER_NAME \| 1 << 31 \|
1172		-
1173		-
1174		-Table: `CERTIFY_KEY_EXTENDED` output arguments
1175		-
1176		-\| Name \| Type \| Description \|
1177		-\| ------------------ \| -------- \| -------------------------------------------------------------------------- \|
	1329	+\| ----------------- \| ---------- \|
	1330	+\| DMTF\_OTHER\_NAME \| 1 << 31 \|
	1331	+
	1332	+
	1333	+Table: `CERTIFY_KEY_EXTENDED_ECC384` output arguments
	1334	+
	1335	+\| Name \| Type \| Description \|
	1336	+\| ------------------ \| --------- \| -------------------------------------------------------------------------- \|
1178	1337	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
1179	1338	\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error. \|
1180		-\| certify\_key\_resp \| u8[2176] \| Certify Key Response. \|
	1339	+\| size \| u32 \| The size of the response in the certify\_key\_resp field. \|
	1340	+\| certify\_key\_resp \| u8[25152] \| Certify Key Response. \|
	1341	+
	1342	+
	1343	+### CERTIFY\_KEY\_EXTENDED\_MLDSA87
	1344	+
	1345	+Produces an ML-DSA-87 DPE leaf certificate or CSR containing custom extensions provided by the SoC.
	1346	+
	1347	+Command Code: `0x434B_584D` ("CKXM")
	1348	+
	1349	+Table: `CERTIFY_KEY_EXTENDED_MLDSA87` input arguments
	1350	+
	1351	+\| Name \| Type \| Description \|
	1352	+\| ----------------- \| -------- \| --------------------------------------------------------------------------- \|
	1353	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
	1354	+\| flags \| u32 \| Flags determining which custom extensions to include in the certificate. \|
	1355	+\| certify\_key\_req \| u8[72] \| Certify Key Request. \|
	1356	+
	1357	+
	1358	+Table: `CERTIFY_KEY_EXTENDED_MLDSA87` input flags
	1359	+
	1360	+\| Name \| Offset \|
	1361	+\| ----------------------- \| ---------- \|
	1362	+\| DMTF\_OTHER\_NAME \| 1 << 31 \|
	1363	+\| EXTERNAL\_AXI\_RESPONSE \| 1 << 30 \|
	1364	+
	1365	+
	1366	+Table: `CERTIFY_KEY_EXTENDED_MLDSA87` output arguments
	1367	+
	1368	+\| Name \| Type \| Description \|
	1369	+\| ------------------ \| --------- \| -------------------------------------------------------------------------- \|
	1370	+\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
	1371	+\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error. \|
	1372	+\| size \| u32 \| The size of the response in the certify\_key\_resp field. \|
	1373	+\| certify\_key\_resp \| u8[25152] \| Certify Key Response. \|
1181	1374
1182	1375
1183	1376	### SET_AUTH_MANIFEST
@@ -1188,26 +1381,26 @@
1188	1381
1189	1382	Table: `SET_AUTH_MANIFEST` input arguments
1190	1383
1191		-\| Name \| Type \| Description
1192		-\| -------- \| -------- \| ---------------
	1384	+\| Name \| Type \| Description \|
	1385	+\| -------- \| -------- \| --------------- \|
1193	1386	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
1194	1387	\| manifest size \| u32 \| The size of the full Authentication Manifest \|
1195	1388	\| preamble\_marker \| u32 \| Marker needs to be 0x4154_4D4E for the preamble to be valid \|
1196	1389	\| preamble\_size \| u32 \| Size of the preamble \|
1197	1390	\| preamble\_version \| u32 \| Version of the preamble \|
1198	1391	\| preamble\_flags \| u32 \| Manifest flags. See AUTH_MANIFEST_FLAGS below \|
1199		-\| preamble\_vendor\_ecc384\_key \| u32[24] \| Vendor ECC384 key with X and Y coordinates in that order \|
1200		-\| preamble\_vendor\_pqc\_key \| u32[648] \| Vendor MLDSA-87 or LMS-SHA192-H15 key \|
1201		-\| preamble\_vendor\_ecc384\_sig \| u32[24] \| Vendor ECC384 signature \|
1202		-\| preamble\_vendor\_PQC\_sig \| u32[1157] \| Vendor MLDSA-87 or LMOTS-SHA192-W4 signature \|
1203		-\| preamble\_owner\_ecc384\_key \| u32[24] \| Owner ECC384 key with X and Y coordinates in that order \|
1204		-\| preamble\_owner\_pqc\_key \| u32[648] \| Owner MLDSA-87 or LMS-SHA192-H15 key \|
1205		-\| preamble\_owner\_ecc384\_sig \| u32[24] \| Owner ECC384 signature \|
1206		-\| preamble\_owner\_PQC\_sig \| u32[1157] \| Owner MLDSA-87 or LMOTS-SHA192-W4 signature \|
1207		-\| metadata\_vendor\_ecc384\_sig \| u32[24] \| Metadata Vendor ECC384 signature \|
1208		-\| metadata\_vendor\_PQC\_sig \| u32[1157] \| Metadata Vendor MLDSA-87 or LMOTS-SHA192-W4 signature \|
1209		-\| metadata\_owner\_ecc384\_sig \| u32[24] \| Metadata Owner ECC384 signature \|
1210		-\| metadata\_owner\_PQC\_sig \| u32[1157] \| Metadata Owner MLDSA-87 or LMOTS-SHA192-W4 signature \|
	1392	+\| 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). \|
	1393	+\| 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). \|
	1394	+\| preamble\_vendor\_ecc384\_sig \| u32[24] \| Vendor ECC384 signature. See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields). \|
	1395	+\| 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). \|
	1396	+\| 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). \|
	1397	+\| 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). \|
	1398	+\| preamble\_owner\_ecc384\_sig \| u32[24] \| Owner ECC384 signature. See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields). \|
	1399	+\| 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). \|
	1400	+\| metadata\_vendor\_ecc384\_sig \| u32[24] \| Metadata Vendor ECC384 signature. See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields). \|
	1401	+\| 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). \|
	1402	+\| metadata\_owner\_ecc384\_sig \| u32[24] \| Metadata Owner ECC384 signature. See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields). \|
	1403	+\| 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). \|
1211	1404	\| metadata\_entry\_entry\_count \| u32 \| number of metadata entries \|
1212	1405	\| metadata\_entries \| Metadata[127] \| The max number of metadata entries is 127 but less can be used \|
1213	1406
@@ -1225,17 +1418,17 @@
1225	1418	\| Name \| Type \| Description \|
1226	1419	\| ------------------------ \| --------- \| ---------------- \|
1227	1420	\| Image Hash \| u8[48] \| SHA2-384 hash of a SOC image. \|
1228		-
1229		-\| 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)
1230		-\| 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)
1231		-\| 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)
1232		-\| 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)
1233		-\| 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)
1234		-\| 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)
1235		-\| 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)
1236		-\| 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)
1237		-\| 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)
1238		-\| 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)
	1421	+\| 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) \|
	1422	+\| 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) \|
	1423	+\| flags \| u32 \| This corresponds to the `flags` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main/auth-manifest/README.md) \|
	1424	+\| 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) \|
	1425	+\| 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) \|
	1426	+\| 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) \|
	1427	+\| 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) \|
	1428	+\| Classification \| u32 \| This corresponds to the `Classification` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main/auth-manifest/README.md) \|
	1429	+\| 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) \|
	1430	+\| 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) \|
	1431	+
1239	1432
1240	1433	### VERIFY_AUTH_MANIFEST
1241	1434
@@ -1257,8 +1450,8 @@
1257	1450
1258	1451	Table: `AUTHORIZE_AND_STASH` input arguments
1259	1452
1260		-\| Name \| Type \| Description
1261		-\| ------------\| -------- \| ---------------
	1453	+\| Name \| Type \| Description \|
	1454	+\| ------------ \| -------- \| --------------- \|
1262	1455	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
1263	1456	\| fw_id \| u8[4] \| Firmware id of the image, in little-endian format \|
1264	1457	\| 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. \|
@@ -1280,8 +1473,8 @@
1280	1473	\| --------------- \| -------- \| -------------------------------------------------------------------------- \|
1281	1474	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
1282	1475	\| fips_status \| u32 \| Indicates if the command is FIPS approved or an error. \|
1283		-
1284		-\| auth_req_result \| u32 \|AUTHORIZE_IMAGE (0xDEADC0DE), IMAGE_NOT_AUTHORIZED (0x21523F21) or IMAGE_HASH_MISMATCH (0x8BFB95CB)
	1476	+\| auth_req_result \| u32 \| AUTHORIZE_IMAGE (0xDEADC0DE), IMAGE_NOT_AUTHORIZED (0x21523F21) or IMAGE_HASH_MISMATCH (0x8BFB95CB) \|
	1477	+
1285	1478
1286	1479	### GET_IMAGE_INFO
1287	1480
@@ -1294,8 +1487,8 @@
1294	1487	\| Name \| Type \| Description \|
1295	1488	\| -------------- \| -------------- \| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- \|
1296	1489	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
1297		-
1298		-\| fw_id \| u32 \| Firmware id of the image, in little-endian format
	1490	+\| fw_id \| u32 \| Firmware id of the image, in little-endian format \|
	1491	+
1299	1492
1300	1493	Table: `GET_IMAGE_INFO` output arguments
1301	1494
@@ -1303,13 +1496,36 @@
1303	1496	\| -------------- \| -------------- \| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- \|
1304	1497	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
1305	1498	\| fips_status \| u32 \| Indicates if the command is FIPS approved or an error. \|
1306		-\| 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) \|
1307		-\| 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) \|
1308		-\| 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) \|
1309		-\| 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) \|
1310		-\| 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) \|
1311		-\| 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) \|
	1499	+\| Component_id \| u32 \| This corresponds to the `Component Id` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main/auth-manifest/README.md) \|
	1500	+\| flags \| u32 \| This corresponds to the `flags` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main/auth-manifest/README.md) \|
	1501	+\| Image Load Address High \| u32 \| This corresponds to the `Image Load Address High` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main/auth-manifest/README.md) \|
	1502	+\| Image Load Address Low \| u32 \| This corresponds to the `Image Load Address Low` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main/auth-manifest/README.md) \|
	1503	+\| Staging Address High \| u32 \| This corresponds to the `Staging Address High` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main/auth-manifest/README.md) \|
	1504	+\| Staging Address Low \| u32 \| This corresponds to the `Staging Address Low` field in the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main/auth-manifest/README.md) \|
1312	1505	\| digest \| u8[48] \| SHA-384 digest of the image. Only present in FW 2.0.2+ and 2.1.1+. \|
	1506	+
	1507	+
	1508	+### GET\_MCU\_FW\_SIZE
	1509	+
	1510	+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.
	1511	+
	1512	+Command Code: `0x474D_4653` ("GMFS")
	1513	+
	1514	+Table: `GET_MCU_FW_SIZE` input arguments
	1515	+
	1516	+\| Name \| Type \| Description \|
	1517	+\| -------------- \| -------------- \| --------------------------------------------------------------------------- \|
	1518	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
	1519	+
	1520	+
	1521	+Table: `GET_MCU_FW_SIZE` output arguments
	1522	+
	1523	+\| Name \| Type \| Description \|
	1524	+\| -------------- \| -------------- \| -------------------------------------------------------------------------- \|
	1525	+\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
	1526	+\| fips_status \| u32 \| Indicates if the command is FIPS approved or an error. \|
	1527	+\| size \| u32 \| Size of the MCU firmware image in bytes. \|
	1528	+\| sha384 \| u8[48] \| SHA-384 digest of the encrypted MCU firmware image. \|
1313	1529
1314	1530
1315	1531	### ACTIVATE_FIRMWARE
@@ -1327,7 +1543,43 @@
1327	1543	\| count \| u32 \| Number of image_ids to activate. Item count of image_ids array parameter \|
1328	1544	\| mcu_image_size \| u32 \| Size of MCU image, if included in the activation \|
1329	1545	\| image_ids \| Array of u8[4] \| Array of Image ids in little-endian format \|
1330		-
	1546	+\| flags \| u32 \| Optional flags (see below). Caliptra runtime 2.1.1+ only. \|
	1547	+
	1548	+
	1549	+Flags
	1550	+
	1551	+\| Bit \| Name \| Description \|
	1552	+\| ------- \| ----------------- \| ------------------------------------------------------------------------------------------------------------------------ \|
	1553	+\| 0 \| `INITIAL_ACTIVATE` \| First-time MCU activation after the encrypted-boot flow. Caliptra runtime 2.1.1+ only. See below. \|
	1554	+
	1555	+
	1556	+Unknown flag bits are rejected with `RUNTIME_MAILBOX_INVALID_PARAMS`.
	1557	+
	1558	+`INITIAL_ACTIVATE` is used exclusively by MCU ROM at the tail of the
	1559	+`EncryptedFirmware` boot flow. MCU ROM has already loaded firmware into MCU
	1560	+SRAM via `RI_DOWNLOAD_ENCRYPTED_FIRMWARE` and decrypted it in place via
	1561	+`CM_AES_GCM_DECRYPT_DMA`. When this flag is set, Caliptra Runtime:
	1562	+
	1563	+- Skips the hitless-update steps (set `RESET_REASON.FwHitlessUpd`, clear
	1564	+ `FW_EXEC_CTRL`, wait for MCU reset request and reset assertion, DMA-reload
	1565	+ from staging, re-`AuthorizeAndStash`).
	1566	+- Just publishes `FW_EXEC_CTRL[MCU]` (and any other requested bits) so that
	1567	+ MCI's `BOOT_RST_MCU` state releases MCU from reset on the next warm reset
	1568	+ that MCU ROM triggers.
	1569	+
	1570	+Caliptra Runtime only honors `INITIAL_ACTIVATE` when all of the following
	1571	+are true; otherwise the command fails with `IMAGE_VERIFIER_ACTIVATION_FAILED`:
	1572	+
	1573	+1. The MCU image bit is included in the activation request.
	1574	+2. The boot mode set by ROM is `EncryptedFirmware` (i.e., ROM received
	1575	+ `RI_DOWNLOAD_ENCRYPTED_FIRMWARE`).
	1576	+3. `FW_EXEC_CTRL[MCU]` is currently `0` — this is an initial activation,
	1577	+ not a hitless update masquerading as one.
	1578	+
	1579	+Together, these checks ensure that the MCU SRAM contents are
	1580	+integrity-protected end-to-end (ciphertext digest verified during recovery;
	1581	+GCM tag verified during `CM_AES_GCM_DECRYPT_DMA`) before Caliptra releases
	1582	+MCU to execute them.
1331	1583
1332	1584	Table: `ACTIVATE_FIRMWARE` output arguments
1333	1585
@@ -1336,6 +1588,28 @@
1336	1588	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
1337	1589	\| fips_status \| u32 \| Indicates if the command is FIPS approved or an error. \|
1338	1590
	1591	+
	1592	+## Mailbox commands: OCP LOCK v1.0
	1593	+
	1594	+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).
	1595	+
	1596	+### ENUMERATE_HPKE_HANDLES
	1597	+### REPORT_HEK_METADATA
	1598	+### GET_ALGORITHMS
	1599	+### INITIALIZE_MEK_SECRET
	1600	+### ROTATE_HPKE_KEY
	1601	+### GENERATE_MEK
	1602	+### GENERATE_MPK
	1603	+### REWRAP_MPK
	1604	+### ENABLE_MPK
	1605	+### MIX_MPK
	1606	+### GET_HPKE_PUB_KEY
	1607	+### TEST_ACCESS_KEY
	1608	+### GET_STATUS
	1609	+### CLEAR_KEY_CACHE
	1610	+### UNLOAD_MEK
	1611	+### LOAD_MEK
	1612	+### DERIVE_MEK
1339	1613
1340	1614	## Mailbox commands: Cryptographic Mailbox (2.0)
1341	1615
@@ -1439,6 +1713,99 @@
1439	1713	\| fips_status \| u32 \| FIPS approved or an error \|
1440	1714	\| hash size \| u32 \|\|
1441	1715	\| hash \| u8[hash size] \|\|
	1716	+
	1717	+
	1718	+### CM\_SHAKE256\_INIT
	1719	+
	1720	+This starts the computation of a SHAKE256 extendable-output hash, which may be larger than a single mailbox command allows.
	1721	+
	1722	+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.
	1723	+
	1724	+The sequence to use these are:
	1725	+* 1 `CM_SHAKE256_INIT` command
	1726	+* 0 or more `CM_SHAKE256_UPDATE` commands
	1727	+* 1 `CM_SHAKE256_FINAL` command
	1728	+
	1729	+For each command, the context from the previous command's output must be passed as an input.
	1730	+
	1731	+The `SHAKE256_CONTEXT_SIZE` is always exactly 44 bytes long (encrypted session token).
	1732	+
	1733	+The maximum supported input data size per command is 4096 bytes.
	1734	+
	1735	+Command Code: `0x434D_5849` ("CMXI")
	1736	+
	1737	+Table: `CM_SHAKE256_INIT` input arguments
	1738	+
	1739	+\| Name \| Type \| Description \|
	1740	+\| --------- \| ------------- \| --------------- \|
	1741	+\| chksum \| u32 \|\|
	1742	+\| data size \| u32 \|\|
	1743	+\| data \| u8[data size] \| Data to hash \|
	1744	+
	1745	+
	1746	+Table: `CM_SHAKE256_INIT` output arguments
	1747	+
	1748	+\| Name \| Type \| Description \|
	1749	+\| ----------- \| ------------------------- \| -------------------------------------------------- \|
	1750	+\| chksum \| u32 \|\|
	1751	+\| fips_status \| u32 \| FIPS approved or an error \|
	1752	+\| context \| u8[SHAKE256_CONTEXT_SIZE] \| Passed to `CM_SHAKE256_UPDATE` / `CM_SHAKE256_FINAL` \|
	1753	+
	1754	+
	1755	+### CM\_SHAKE256\_UPDATE
	1756	+
	1757	+This continues a SHAKE256 computation started by `CM_SHAKE256_INIT` or from another `CM_SHAKE256_UPDATE`.
	1758	+
	1759	+The context MUST be passed in from `CM_SHAKE256_INIT` or `CM_SHAKE256_UPDATE`.
	1760	+
	1761	+Command Code: `0x434D_5855` ("CMXU")
	1762	+
	1763	+Table: `CM_SHAKE256_UPDATE` input arguments
	1764	+
	1765	+\| Name \| Type \| Description \|
	1766	+\| --------- \| ------------------------- \| ---------------------------------------------------- \|
	1767	+\| chksum \| u32 \|\|
	1768	+\| context \| u8[SHAKE256_CONTEXT_SIZE] \| From `CM_SHAKE256_INIT` / `CM_SHAKE256_UPDATE` \|
	1769	+\| data size \| u32 \|\|
	1770	+\| data \| u8[data size] \| Data to hash \|
	1771	+
	1772	+
	1773	+Table: `CM_SHAKE256_UPDATE` output arguments
	1774	+
	1775	+\| Name \| Type \| Description \|
	1776	+\| ----------- \| ------------------------- \| -------------------------------------------------- \|
	1777	+\| chksum \| u32 \|\|
	1778	+\| fips_status \| u32 \| FIPS approved or an error \|
	1779	+\| context \| u8[SHAKE256_CONTEXT_SIZE] \| Passed to `CM_SHAKE256_UPDATE` / `CM_SHAKE256_FINAL` \|
	1780	+
	1781	+
	1782	+### CM\_SHAKE256\_FINAL
	1783	+
	1784	+This finalizes the SHAKE256 computation and produces the hash of all of the data.
	1785	+
	1786	+The context MUST be passed in from `CM_SHAKE256_INIT` or `CM_SHAKE256_UPDATE`.
	1787	+
	1788	+The output is always a 64-byte SHAKE256 digest.
	1789	+
	1790	+Command Code: `0x434D_5846` ("CMXF")
	1791	+
	1792	+Table: `CM_SHAKE256_FINAL` input arguments
	1793	+
	1794	+\| Name \| Type \| Description \|
	1795	+\| ----------- \| ------------------------- \| ---------------------------------------------- \|
	1796	+\| chksum \| u32 \|\|
	1797	+\| context \| u8[SHAKE256_CONTEXT_SIZE] \| From `CM_SHAKE256_INIT` / `CM_SHAKE256_UPDATE` \|
	1798	+\| data size \| u32 \| May be 0 \|
	1799	+\| data \| u8[data size] \| Data to hash \|
	1800	+
	1801	+
	1802	+Table: `CM_SHAKE256_FINAL` output arguments
	1803	+
	1804	+\| Name \| Type \| Description \|
	1805	+\| ----------- \| -------- \| ------------------------- \|
	1806	+\| chksum \| u32 \|\|
	1807	+\| fips_status \| u32 \| FIPS approved or an error \|
	1808	+\| hash \| u8[64] \| SHAKE256 digest \|
1442	1809
1443	1810
1444	1811	### CM\_HMAC
@@ -1729,6 +2096,79 @@
1729	2096	\| fips_status \| u32 \| FIPS approved or an error \|
1730	2097
1731	2098
	2099	+### CM_MLKEM_KEY_GEN
	2100	+
	2101	+Generates an ML-KEM-1024 encapsulation key from the seed (seed\_d \|\| seed\_z, 64 bytes) stored in a CMK with key usage `Mlkem`.
	2102	+
	2103	+The key generation algorithm is described in [FIPS 203](https://csrc.nist.gov/pubs/fips/203/final).
	2104	+
	2105	+Command Code: `0x434D_4C4B` ("CMLK")
	2106	+
	2107	+Table: `CM_MLKEM_KEY_GEN` input arguments
	2108	+\| Name \| Type \| Description \|
	2109	+\| -------- \| -------- \| ---------------------------------------- \|
	2110	+\| chksum \| u32 \|\|
	2111	+\| CMK \| CMK \| ML-KEM seed (seed\_d \|\| seed\_z) \|
	2112	+
	2113	+
	2114	+Table: `CM_MLKEM_KEY_GEN` output arguments
	2115	+\| Name \| Type \| Description \|
	2116	+\| ----------- \| -------- \| ---------------------------------------- \|
	2117	+\| chksum \| u32 \|\|
	2118	+\| fips_status \| u32 \| FIPS approved or an error \|
	2119	+\| encaps_key \| u8[1568] \| ML-KEM-1024 encapsulation key \|
	2120	+
	2121	+
	2122	+### CM_MLKEM_ENCAPSULATE
	2123	+
	2124	+Performs ML-KEM-1024 encapsulation against the provided encapsulation key, producing a ciphertext and a shared key wrapped as a CMK.
	2125	+
	2126	+The encapsulation algorithm is described in [FIPS 203](https://csrc.nist.gov/pubs/fips/203/final).
	2127	+
	2128	+Command Code: `0x434D_4C45` ("CMLE")
	2129	+
	2130	+Table: `CM_MLKEM_ENCAPSULATE` input arguments
	2131	+\| Name \| Type \| Description \|
	2132	+\| ----------- \| -------- \| ---------------------------------------- \|
	2133	+\| chksum \| u32 \|\|
	2134	+\| key_usage \| u32 \| Key usage for the output CMK \|
	2135	+\| encaps_key \| u8[1568] \| ML-KEM-1024 encapsulation key \|
	2136	+
	2137	+
	2138	+Table: `CM_MLKEM_ENCAPSULATE` output arguments
	2139	+\| Name \| Type \| Description \|
	2140	+\| ----------- \| -------- \| ---------------------------------------- \|
	2141	+\| chksum \| u32 \|\|
	2142	+\| fips_status \| u32 \| FIPS approved or an error \|
	2143	+\| ciphertext \| u8[1568] \| ML-KEM-1024 ciphertext \|
	2144	+\| shared_key \| CMK \| CMK of the shared secret key \|
	2145	+
	2146	+
	2147	+### CM_MLKEM_DECAPSULATE
	2148	+
	2149	+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.
	2150	+
	2151	+The decapsulation algorithm is described in [FIPS 203](https://csrc.nist.gov/pubs/fips/203/final).
	2152	+
	2153	+Command Code: `0x434D_4C44` ("CMLD")
	2154	+
	2155	+Table: `CM_MLKEM_DECAPSULATE` input arguments
	2156	+\| Name \| Type \| Description \|
	2157	+\| ----------- \| -------- \| ---------------------------------------- \|
	2158	+\| chksum \| u32 \|\|
	2159	+\| key_usage \| u32 \| Key usage for the output CMK \|
	2160	+\| CMK \| CMK \| ML-KEM seed (seed\_d \|\| seed\_z) \|
	2161	+\| ciphertext \| u8[1568] \| ML-KEM-1024 ciphertext to decapsulate \|
	2162	+
	2163	+
	2164	+Table: `CM_MLKEM_DECAPSULATE` output arguments
	2165	+\| Name \| Type \| Description \|
	2166	+\| ----------- \| -------- \| ---------------------------------------- \|
	2167	+\| chksum \| u32 \|\|
	2168	+\| fips_status \| u32 \| FIPS approved or an error \|
	2169	+\| shared_key \| CMK \| CMK of the shared secret key \|
	2170	+
	2171	+
1732	2172	### CM_AES_ENCRYPT_INIT
1733	2173
1734	2174	Generic AES operation for unauthenticated AES operations.
@@ -1775,8 +2215,7 @@
1775	2215	\| mode \| u32 \|\|
1776	2216	\| key \| u8[32] \|\|
1777	2217	\| iv \| u8[16] \|\|
1778		-\| fips_status \| u8 \| 1 = FIPS valid \|
1779		-\| reserved \| u8[75] \| Reserved for additional fields \|
	2218	+\| reserved \| u8[76] \| Reserved for additional fields \|
1780	2219
1781	2220
1782	2221	The size of the (encrypted) context is always exactly 156 bytes,
@@ -1925,8 +2364,7 @@
1925	2364	\| GHASH state \| u8[16] \|\|
1926	2365	\| current length \| u32 \| value mod 16 is buffer size \|
1927	2366	\| buffer \| u8[16] \|\|
1928		-\| fips_status \| u8 \| 1 = FIPS valid \|
1929		-\| reserved \| u8[15] \|\|
	2367	+\| reserved \| u8[16] \|\|
1930	2368
1931	2369
1932	2370	The size of the (encrypted) context is always exactly 128 bytes,
@@ -2198,6 +2636,44 @@
2198	2636	\| plaintext \| u8[plaintext size] \|\|
2199	2637
2200	2638
	2639	+### CM_AES_GCM_DECRYPT_DMA
	2640	+
	2641	+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.
	2642	+
	2643	+Important restrictions:
	2644	+- This command is only available in subsystem mode, as DMA is only available in subsystem.
	2645	+- 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.
	2646	+- The command performs a two-pass operation:
	2647	+ 1. First pass: Verifies the SHA384 hash of the encrypted data at the AXI address
	2648	+ 2. Second pass: Performs in-place AES-GCM decryption via DMA
	2649	+
	2650	+The CMK must be an AES key (key usage = 3) that was previously imported using `CM_IMPORT`.
	2651	+
	2652	+Command Code: `0x434D_4444` ("CMDD")
	2653	+
	2654	+Table: `CM_AES_GCM_DECRYPT_DMA` input arguments
	2655	+\| Name \| Type \| Description \|
	2656	+\| --------------------- \| --------- \| ---------------------------------------------------- \|
	2657	+\| chksum \| u32 \| Checksum over other input arguments \|
	2658	+\| cmk \| CMK \| Encrypted CMK containing the AES-256 key \|
	2659	+\| iv \| u32[3] \| AES-GCM initialization vector (12 bytes) \|
	2660	+\| tag \| u32[4] \| AES-GCM authentication tag (16 bytes) \|
	2661	+\| encrypted_data_sha384 \| u8[48] \| SHA384 hash of the encrypted data for verification \|
	2662	+\| axi_addr_lo \| u32 \| Lower 32 bits of the AXI address \|
	2663	+\| axi_addr_hi \| u32 \| Upper 32 bits of the AXI address \|
	2664	+\| length \| u32 \| Length of data to decrypt in bytes \|
	2665	+\| aad_length \| u32 \| Length of AAD in bytes (0-4095) \|
	2666	+\| aad \| u8[...] \| Additional authenticated data \|
	2667	+
	2668	+
	2669	+Table: `CM_AES_GCM_DECRYPT_DMA` output arguments
	2670	+\| Name \| Type \| Description \|
	2671	+\| ------------ \| -------- \| ----------------------------------------------------- \|
	2672	+\| chksum \| u32 \| Checksum over other output arguments \|
	2673	+\| fips_status \| u32 \| FIPS approved or an error \|
	2674	+\| tag_verified \| u32 \| 1 if GCM tag verification succeeded, 0 if it failed \|
	2675	+
	2676	+
2201	2677	### CM_ECDH_GENERATE
2202	2678
2203	2679	This computes the first half of an Elliptic Curve Diffie-Hellman exchange to compute an ephemeral shared key pair with another party.
@@ -2316,9 +2792,9 @@
2316	2792	### CM\_DERIVE\_STABLE\_KEY
2317	2793
2318	2794	Derives an HMAC key that has a stable value across resets from either
2319		-IDevId or LDevId.
2320		-
2321		-The (interior) value of the returned CMK will be the stable across resets as it is derived indirectly from the IDevId or LDevId CDIs.
	2795	+IDevId, LDevId, or the Owner Root Key (derived from HEK seed).
	2796	+
	2797	+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.
2322	2798	The actual encrypted bytes of the CMK will not be the same, and
2323	2799	the encrypted CMK itself cannot be used across resets. So, the key
2324	2800	will always need to be re-derived after every cold reset.
@@ -2326,22 +2802,32 @@
2326	2802	If a key usage other than HMAC is desired, then the KDF or HKDF
2327	2803	mailbox functions can be used to derive a key from the returned CMK.
2328	2804
2329		-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.
	2805	+`key_type = OwnerKey` is only available in subsystem mode when the Stable Owner
	2806	+Key strap is enabled (`SS_STRAP_GENERIC[3]` bit 0 set to 1) and OCP LOCK is not
	2807	+enabled. If these requirements are not met, the command fails with
	2808	+`CMB_STABLE_OWNER_KEY_NOT_AVAILABLE`.
	2809	+
	2810	+For `OwnerKey`, this command derives from the ROM-populated Stable Owner Root
	2811	+Key. It first runs AES-256-CMAC KDF with `info` as the input data to produce an
	2812	+intermediate key, then runs HMAC-SHA512 KDF with `b"Stable Owner Key" \|\| info`
	2813	+as the domain-separation input to produce the returned 64-byte HMAC key
	2814	+material. Caliptra wraps that key material as an encrypted CMK before returning
	2815	+it to the caller.
2330	2816
2331	2817	Command Code: `0x434D_4453` ("CMDS")
2332	2818
2333	2819	Table: `CM_DERIVE_STABLE_KEY` input arguments
2334	2820
2335		-\| Name \| Type \| Description
2336		-\| -------- \| -------- \| ---------------
	2821	+\| Name \| Type \| Description \|
	2822	+\| -------- \| -------- \| --------------- \|
2337	2823	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
2338		-\| key_type \| u32 \| Source key to derive the stable key from. 0x0000_0001: IDevId <br> 0x0000_0002: LDevId \|
	2824	+\| 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) \|
2339	2825	\| info \| u8[32] \| Data to use in the key derivation. \|
2340	2826
2341	2827
2342	2828	Table: `CM_DERIVE_STABLE_KEY` output arguments
2343		-\| Name \| Type \| Description
2344		-\| -------- \| -------- \| ---------------
	2829	+\| Name \| Type \| Description \|
	2830	+\| -------- \| -------- \| --------------- \|
2345	2831	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
2346	2832	\| cmk \| CMK \| CMK that stores the stable key material \|
2347	2833
@@ -2351,9 +2837,6 @@
2351	2837	Imports the specified key and returns a CMK for it.
2352	2838
2353	2839	Usage information is required so that the key can be verified and used appropriately.
2354		-
2355		-Note that it is the caller's responsibility to ensure that the source
2356		-key material meets FIPS requirements, such as zeroization.
2357	2840
2358	2841	Command Code: `0x434D_494D` ("CMIM")
2359	2842
@@ -2438,14 +2921,14 @@
2438	2921
2439	2922	Table: `GET_IDEV_ECC384_CSR` input arguments
2440	2923
2441		-\| Name \| Type \| Description
2442		-\| -------- \| -------- \| ---------------
	2924	+\| Name \| Type \| Description \|
	2925	+\| -------- \| -------- \| --------------- \|
2443	2926	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
2444	2927
2445	2928
2446	2929	Table: `GET_IDEV_ECC384_CSR` output arguments
2447		-\| Name \| Type \| Description
2448		-\| -------- \| -------- \| ---------------
	2930	+\| Name \| Type \| Description \|
	2931	+\| -------- \| -------- \| --------------- \|
2449	2932	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
2450	2933	\| data\_size \| u32 \| Length in bytes of the valid data in the data field. \|
2451	2934	\| data \| u8[...] \| DER-encoded ECC384 IDevID certificate signing request. \|
@@ -2457,14 +2940,14 @@
2457	2940
2458	2941	Table: `GET_IDEV_MLDSA87_CSR` input arguments
2459	2942
2460		-\| Name \| Type \| Description
2461		-\| -------- \| -------- \| ---------------
	2943	+\| Name \| Type \| Description \|
	2944	+\| -------- \| -------- \| --------------- \|
2462	2945	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
2463	2946
2464	2947
2465	2948	Table: `GET_IDEV_MLDSA87_CSR` output arguments
2466		-\| Name \| Type \| Description
2467		-\| -------- \| -------- \| ---------------
	2949	+\| Name \| Type \| Description \|
	2950	+\| -------- \| -------- \| --------------- \|
2468	2951	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
2469	2952	\| data\_size \| u32 \| Length in bytes of the valid data in the data field. \|
2470	2953	\| data \| u8[...] \| DER-encoded MLDSA87 IDevID certificate signing request. \|
@@ -2484,14 +2967,14 @@
2484	2967
2485	2968	Table: `GET_FMC_ALIAS_ECC384_CSR` input arguments
2486	2969
2487		-\| Name \| Type \| Description
2488		-\| -------- \| -------- \| ---------------
	2970	+\| Name \| Type \| Description \|
	2971	+\| -------- \| -------- \| --------------- \|
2489	2972	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
2490	2973
2491	2974
2492	2975	Table: `GET_FMC_ALIAS_ECC384_CSR` output arguments
2493		-\| Name \| Type \| Description
2494		-\| -------- \| -------- \| ---------------
	2976	+\| Name \| Type \| Description \|
	2977	+\| -------- \| -------- \| --------------- \|
2495	2978	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
2496	2979	\| data\_size \| u32 \| Length in bytes of the valid data in the data field. \|
2497	2980	\| data \| u8[...] \| DER-encoded ECC384 FMC Alias certificate signing request. \|
@@ -2503,14 +2986,14 @@
2503	2986
2504	2987	Table: `GET_FMC_ALIAS_MLDSA87_CSR` input arguments
2505	2988
2506		-\| Name \| Type \| Description
2507		-\| -------- \| -------- \| ---------------
	2989	+\| Name \| Type \| Description \|
	2990	+\| -------- \| -------- \| --------------- \|
2508	2991	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
2509	2992
2510	2993
2511	2994	Table: `GET_FMC_ALIAS_MLDSA87_CSR` output arguments
2512		-\| Name \| Type \| Description
2513		-\| -------- \| -------- \| ---------------
	2995	+\| Name \| Type \| Description \|
	2996	+\| -------- \| -------- \| --------------- \|
2514	2997	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
2515	2998	\| data\_size \| u32 \| Length in bytes of the valid data in the data field. \|
2516	2999	\| data \| u8[...] \| DER-encoded MLDSA87 FMC Alias certificate signing request. \|
@@ -2524,8 +3007,8 @@
2524	3007
2525	3008	Table: `GET_ATTESTED_ECC384_CSR` input arguments
2526	3009
2527		-\| Name \| Type \| Description
2528		-\| -------- \| -------- \| ---------------
	3010	+\| Name \| Type \| Description \|
	3011	+\| -------- \| -------- \| --------------- \|
2529	3012	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
2530	3013	\| key_id \| u32 \| Key ID for which CSR is requested.<br> 0x0000_0001: LDevId <br> 0x0000_0002: FMC Alias <br> 0x0000_0003: RT Alias \|
2531	3014	\| nonce \| u8[32] \| Nonce to be included in the CSR EAT. \|
@@ -2533,8 +3016,8 @@
2533	3016
2534	3017	Table: `GET_ATTESTED_ECC384_CSR` output arguments
2535	3018
2536		-\| Name \| Type \| Description
2537		-\| -------- \| -------- \| ---------------
	3019	+\| Name \| Type \| Description \|
	3020	+\| -------- \| -------- \| --------------- \|
2538	3021	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
2539	3022	\| data\_size \| u32 \| Length in bytes of the valid data in the data field. \|
2540	3023	\| data \| u8[...] \| DER-encoded ECC384 attested certificate signing request. \|
@@ -2548,8 +3031,8 @@
2548	3031
2549	3032	Table: `GET_ATTESTED_MLDSA87_CSR` input arguments
2550	3033
2551		-\| Name \| Type \| Description
2552		-\| -------- \| -------- \| ---------------
	3034	+\| Name \| Type \| Description \|
	3035	+\| -------- \| -------- \| --------------- \|
2553	3036	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
2554	3037	\| key_id \| u32 \| Key ID for which CSR is requested.<br> 0x0000_0001: LDevId <br> 0x0000_0002: FMC Alias <br> 0x0000_0003: RT Alias \|
2555	3038	\| nonce \| u8[32] \| Nonce to be included in the CSR EAT. \|
@@ -2557,8 +3040,8 @@
2557	3040
2558	3041	Table: `GET_ATTESTED_MLDSA87_CSR` output arguments
2559	3042
2560		-\| Name \| Type \| Description
2561		-\| -------- \| -------- \| ---------------
	3043	+\| Name \| Type \| Description \|
	3044	+\| -------- \| -------- \| --------------- \|
2562	3045	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
2563	3046	\| data\_size \| u32 \| Length in bytes of the valid data in the data field. \|
2564	3047	\| data \| u8[...] \| DER-encoded MLDSA87 attested certificate signing request. \|
@@ -2572,16 +3055,16 @@
2572	3055
2573	3056	Table: `SIGN_WITH_EXPORTED_ECDSA` input arguments
2574	3057
2575		-\| Name \| Type \| Description
2576		-\| -------- \| -------- \| ---------------
	3058	+\| Name \| Type \| Description \|
	3059	+\| -------- \| -------- \| --------------- \|
2577	3060	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
2578		-\| exported_cdi_handle \| u8[32] \| The Exported CDI handle returned by the DPE `DeriveContext` command. Little endian. \|
2579		-\| tbs \| u8[48] \| The bytes to be signed. Little endian. \|
	3061	+\| exported_cdi_handle \| u8[32] \| The exported CDI handle returned by the DPE `DeriveContext` command. Opaque byte array; copy the bytes exactly as returned. \|
	3062	+\| tbs \| u8[48] \| The 48-byte SHA-384 digest to be signed. Raw byte array; no byte swapping is required. \|
2580	3063
2581	3064
2582	3065	Table: `SIGN_WITH_EXPORTED_ECDSA` output arguments
2583		-\| Name \| Type \| Description
2584		-\| -------- \| -------- \| ---------------
	3066	+\| Name \| Type \| Description \|
	3067	+\| -------- \| -------- \| --------------- \|
2585	3068	\| derived_pubkey_x \| u8[48] \| The X BigNum of the ECDSA public key associated with the signing key. \|
2586	3069	\| derived_pubkey_y \| u8[48] \| The Y BigNum of the ECDSA public key associated with the signing key. \|
2587	3070	\| signature_r \| u8[48] \| The R BigNum of an ECDSA signature. \|
@@ -2598,10 +3081,10 @@
2598	3081
2599	3082	Table: `REVOKE_EXPORTED_CDI_HANDLE` input arguments
2600	3083
2601		-\| Name \| Type \| Description
2602		-\| -------- \| -------- \| ---------------
	3084	+\| Name \| Type \| Description \|
	3085	+\| -------- \| -------- \| --------------- \|
2603	3086	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
2604		-\| exported_cdi_handle \| u8[32] \| The Exported CDI handle returned by the DPE `DeriveContext` command. Little endian. \|
	3087	+\| exported_cdi_handle \| u8[32] \| The exported CDI handle returned by the DPE `DeriveContext` command. Opaque byte array; copy the bytes exactly as returned. \|
2605	3088
2606	3089
2607	3090	The `exported_cdi` can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
@@ -2609,6 +3092,35 @@
2609	3092	The `exported_cdi_handle` is no longer usable after calling `REVOKE_EXPORTED_CDI_HANDLE` with it. After the `exported_cdi_handle`
2610	3093	has been revoked, a new exported CDI can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
2611	3094
	3095	+### EXTERNAL_MAILBOX_CMD
	3096	+
	3097	+Command Code: `0x4558_544D` ("EXTM")
	3098	+
	3099	+Note: This command is only available in subsystem mode in 2.1+.
	3100	+
	3101	+Executes a mailbox command located at an AXI address.
	3102	+This allows for executing mailbox commands that are larger than the mailbox allows.
	3103	+
	3104	+This is currently mostly useful for FIRMWARE_LOAD (as part of an update) or SET_AUTH_MANIFEST.
	3105	+
	3106	+The response is still written to the mailbox.
	3107	+
	3108	+The checksum is over the EXTM command, not the command that is loaded over AXI.
	3109	+That external command will still need its own checksum, if applicable.
	3110	+
	3111	+Table: `EXTERNAL_MAILBOX_CMD` input arguments
	3112	+
	3113	+\| Name \| Type \| Description \|
	3114	+\| -------- \| -------- \| --------------- \|
	3115	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
	3116	+\| command_id \| u32 \| Command ID for the mailbox command to be executed. Little endian. \|
	3117	+\| command_size \| u32 \| Size of the mailbox command to be executed. Little endian. \|
	3118	+\| axi_address_low \| u32 \| Lower 32 bits of the AXI address that contains the mailbox command. Little endian. \|
	3119	+\| axi_address_high \| u32 \| High 32 bits of the AXI address that contains the mailbox command. Little endian. \|
	3120	+
	3121	+
	3122	+The response will be the response of the executed external command.
	3123	+
2612	3124	### REALLOCATE\_DPE\_CONTEXT\_LIMITS
2613	3125
2614	3126	Command Code: '5243_5458` ("RCTX")
@@ -2617,24 +3129,119 @@
2617	3129
2618	3130	Table: `REALLOCATE_DPE_CONTEXT_LIMITS` input arguments
2619	3131
2620		-\| Name \| Type \| Description
2621		-\| -------- \| -------- \| ---------------
	3132	+\| Name \| Type \| Description \|
	3133	+\| -------- \| -------- \| --------------- \|
2622	3134	\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
2623	3135	\| pl0_context_limit \| u32 \| Number of contexts to allocate to PL0. PL1 will receive remaining contexts. \|
2624	3136
2625	3137
2626	3138	Table: `REALLOCATE_DPE_CONTEXT_LIMITS` output arguments
2627		-\| Name \| Type \| Description
2628		-\| -------- \| -------- \| ---------------
	3139	+\| Name \| Type \| Description \|
	3140	+\| -------- \| -------- \| --------------- \|
2629	3141	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
2630	3142	\| fips_status \| u32 \| Indicates if the command is FIPS approved or an error. \|
2631	3143	\| new_pl0_context_limit \| u32 \| Number of contexts assigned to PL0 after the reallocation \|
2632	3144	\| new_pl1_context_limit \| u32 \| Number of contexts assigned to PL1 after the reallocation \|
2633	3145
2634	3146
2635		-This allows the user to reallocate the 32 DPE contexts between PL0 and PL1. By default, each gets 16 contexts.
	3147	+This allows the user to reallocate the 64 DPE contexts between PL0 and PL1. By default, each gets 32 contexts.
2636	3148
2637	3149	Note: 2 PL0 contexts are used by Caliptra itself during initialization.
	3150	+
	3151	+### FE\_PROG
	3152	+
	3153	+Programs Field Entropy (FE) into one of 4 FE partitions in the OTP fuse controller. This command
	3154	+is typically used during device provisioning flows.
	3155	+
	3156	+Note: This command is only available when the device is in the Production lifecycle state.
	3157	+
	3158	+Command Code: `0x4645_5052` ("FEPR")
	3159	+
	3160	+Table: `FE_PROG` input arguments
	3161	+
	3162	+\| Name \| Type \| Description
	3163	+\| -------- \| -------- \| ---------------
	3164	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian.
	3165	+\| partition \| u32 \| FE partition number (valid values: 0–3).
	3166	+
	3167	+`FE_PROG` returns no output arguments other than the mailbox response header.
	3168	+
	3169	+### PRODUCTION\_AUTH\_DEBUG\_UNLOCK\_REQ
	3170	+
	3171	+Initiates the production debug unlock flow by generating a cryptographic challenge. The caller
	3172	+must solve the challenge by signing it with the appropriate ECC and MLDSA keys and returning
	3173	+the result via the [`PRODUCTION_AUTH_DEBUG_UNLOCK_TOKEN`](#production_auth_debug_unlock_token)
	3174	+command.
	3175	+
	3176	+This command performs the same function as the ROM's `AUTH_DEBUG_UNLOCK_REQ` command
	3177	+(documented in the [ROM README](../rom/dev/README.md#debug-unlock)), but is available at
	3178	+runtime.
	3179	+
	3180	+Note: This command requires the device to be in the Production lifecycle state and the
	3181	+`PROD_DEBUG_UNLOCK_REQ` bit in the `SS_DBG_MANUF_SERVICE_REG_REQ` register to be set.
	3182	+
	3183	+Command Code: `0x5044_5552` ("PDUR")
	3184	+
	3185	+Table: `PRODUCTION_AUTH_DEBUG_UNLOCK_REQ` input arguments
	3186	+
	3187	+\| Name \| Type \| Description
	3188	+\| -------- \| -------- \| ---------------
	3189	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian.
	3190	+\| length \| u32 \| Length of the payload in DWORDs.
	3191	+\| unlock\_level \| u8 \| Debug unlock level (1–8).
	3192	+\| reserved \| u8[3] \| Reserved.
	3193	+
	3194	+Table: `PRODUCTION_AUTH_DEBUG_UNLOCK_REQ` output arguments
	3195	+
	3196	+\| Name \| Type \| Description
	3197	+\| -------- \| -------- \| ---------------
	3198	+\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian.
	3199	+\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error.
	3200	+\| length \| u32 \| Length of the response payload in DWORDs.
	3201	+\| unique\_device\_identifier \| u8[32] \| Device identifier of the Caliptra device. Byte array; pass through as-is to the token command.
	3202	+\| challenge \| u8[48] \| Random challenge number generated by Caliptra. Byte array; pass through as-is to the token command.
	3203	+
	3204	+### PRODUCTION\_AUTH\_DEBUG\_UNLOCK\_TOKEN
	3205	+
	3206	+Completes the production debug unlock handshake by validating the caller's solution to the
	3207	+challenge generated by
	3208	+[`PRODUCTION_AUTH_DEBUG_UNLOCK_REQ`](#production_auth_debug_unlock_req). The caller must
	3209	+provide the device identifier and challenge from the previous request along with ECC-384 and
	3210	+ML-DSA-87 signatures proving possession of the authorized debug unlock key.
	3211	+
	3212	+Upon successful validation, Caliptra authorizes the debug unlock by setting the unlock level
	3213	+in the `SS_SOC_DBG_UNLOCK_LEVEL` register.
	3214	+
	3215	+This command performs the same function as the ROM's `AUTH_DEBUG_UNLOCK_TOKEN` command
	3216	+(documented in the [ROM README](../rom/dev/README.md#debug-unlock)), but is available at
	3217	+runtime.
	3218	+
	3219	+Note: This command requires a preceding successful `PRODUCTION_AUTH_DEBUG_UNLOCK_REQ` in
	3220	+the same boot session. The challenge is consumed on use and cannot be replayed.
	3221	+
	3222	+Command Code: `0x5044_5554` ("PDUT")
	3223	+
	3224	+Table: `PRODUCTION_AUTH_DEBUG_UNLOCK_TOKEN` input arguments
	3225	+
	3226	+\| Name \| Type \| Description
	3227	+\| -------- \| -------- \| ---------------
	3228	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian.
	3229	+\| length \| u32 \| Length of the payload in DWORDs.
	3230	+\| unique\_device\_identifier \| u8[32] \| Device identifier (must match value from challenge response). Byte array; copied verbatim from the challenge response.
	3231	+\| unlock\_level \| u8 \| Debug unlock level (1–8, must match the original request).
	3232	+\| reserved \| u8[3] \| Reserved.
	3233	+\| challenge \| u8[48] \| Challenge (must match value from challenge response). Byte array; copied verbatim from the challenge response.
	3234	+\| 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).
	3235	+\| mldsa\_public\_key \| u8[2592] \| ML-DSA-87 public key. See [Byte order of cryptographic fields](#byte-order-of-cryptographic-fields).
	3236	+\| 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).
	3237	+\| 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).
	3238	+
	3239	+The signed message for both ECC and ML-DSA signatures is the hash of the concatenation:
	3240	+`unique_device_identifier \|\| unlock_level \|\| reserved \|\| challenge` (all as raw bytes).
	3241	+ECC uses SHA2-384; ML-DSA uses SHA2-512.
	3242	+
	3243	+`PRODUCTION_AUTH_DEBUG_UNLOCK_TOKEN` returns no output arguments other than the mailbox
	3244	+response header.
2638	3245
2639	3246	## Checksum
2640	3247
@@ -2745,14 +3352,14 @@
2745	3352	To prevent this, we establish active context limits for each PAUSER
2746	3353	privilege level:
2747	3354
2748		-* PL0 - 16 active contexts
2749		-* PL1 - 16 active contexts
	3355	+* PL0 - 32 active contexts
	3356	+* PL1 - 32 active contexts
2750	3357
2751	3358	If a DPE command were to activate a new context such that the total number of
2752	3359	active contexts in a privilege level is above its active context limit, the
2753	3360	InvokeDpe command should fail.
2754	3361
2755		-At boot Caliptra Runtime FW consumes part of the PL0 active contexts (initially 16) to DeriveContext for:
	3362	+At boot Caliptra Runtime FW consumes part of the PL0 active contexts (initially 32) to DeriveContext for:
2756	3363	- RTFW Journey (RTFJ) Measurement (1)
2757	3364	- Caliptra Configured Initialization Values digest (CCIV) (1)
2758	3365	- ROM Stashed Measurements (max 8)

Changes to Runtime Specification