Diff: Runtime Specification

@@ -1,5 +1,5 @@
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/b8d1f5916a778e2f34976ea021459fc6575032a2/runtime/README.md" target="_blank">chipsalliance/caliptra-sw/runtime/README.md</a> @ <code>b8d1f59</code>
	2	+📄 Source: <a href="https://github.com/chipsalliance/caliptra-sw/blob/10d4f5891650a6ae38150cac3ffbbe220b7db8ac/runtime/README.md" target="_blank">chipsalliance/caliptra-sw/runtime/README.md</a> @ <code>10d4f58</code>
3	3	</div>
4	4
5	5	# Caliptra Runtime Firmware v1.2
@@ -73,7 +73,7 @@
73	73
74	74	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.
75	75
76		-Manifest-based image authorization is implemented via two mailbox commands: [`SET_AUTH_MANIFEST`](#set-auth-manifest) and [`AUTHORIZE_AND_STASH`](#authorize-and-stash). For image format of the manifest, please refer [this file](https://github.com/chipsalliance/caliptra-sw/blob/b8d1f5916a778e2f34976ea021459fc6575032a2/auth-manifest/README.md).
	76	+Manifest-based image authorization is implemented via two mailbox commands: [`SET_AUTH_MANIFEST`](#set-auth-manifest) and [`AUTHORIZE_AND_STASH`](#authorize-and-stash). For image format of the manifest, please refer [this file](https://github.com/chipsalliance/caliptra-sw/blob/10d4f5891650a6ae38150cac3ffbbe220b7db8ac/auth-manifest/README.md).
77	77
78	78	### Caliptra-Endorsed Aggregated Measured Boot
79	79
@@ -177,6 +177,81 @@
177	177	* CPTRA\_FW\_ERROR\_NON\_FATAL: Status code of mailbox command. Any result
178	178	other than `SUCCESS` signifies a mailbox command failure.
179	179
	180	+### Mailbox command privilege levels
	181	+
	182	+Mailbox commands maintain the PL information of their caller and can allow or
	183	+disallow clients from invoking a call based on their PL level. Callers are
	184	+classified as PL0 or PL1 by comparing the mailbox PAUSER against the `pl0_pauser`
	185	+field of the signed firmware image header; see [PAUSER privilege levels](#pauser-privilege-levels).
	186	+
	187	+A command marked `PL0` is rejected outright for PL1 callers. A command marked
	188	+`PL0 or PL1` is available to every caller. `INVOKE_DPE_COMMAND` and
	189	+`INVOKE_DPE_MLDSA87` are available to both levels, but restrict a subset of the
	190	+DPE commands they carry to PL0.
	191	+
	192	+If the PL0 PAUSER flag is not set in the firmware image header, no caller is
	193	+PL0, so every PL0 command is unavailable for that firmware image. Independently
	194	+of privilege level, commands from the reserved PAUSER are rejected outright.
	195	+
	196	+Privilege level is not the only caller-dependent restriction. Commands that
	197	+operate on DPE contexts are also scoped by locality, and PAUSER maps 1:1 to
	198	+locality, so a caller can generally only reach the contexts it created. The
	199	+`PL0-only functionality` column below calls out where that matters.
	200	+
	201	+Table: Mailbox command privilege levels
	202	+
	203	+\| Command \| Privilege Level \| PL0-only functionality
	204	+\| ----------- \| ------------------- \| --------------------------
	205	+\| `CALIPTRA_FW_LOAD` \| PL0 or PL1 \|
	206	+\| `CAPABILITIES` \| PL0 or PL1 \|
	207	+\| `GET_IDEV_CERT` \| PL0 or PL1 \|
	208	+
	209	+\| `POPULATE_IDEV_CERT` \| PL0 \| Entire command
	210	+\| `GET_IDEV_INFO` \| PL0 or PL1 \|
	211	+\| `GET_LDEV_CERT` \| PL0 or PL1 \|
	212	+\| `GET_FMC_ALIAS_CERT` \| PL0 or PL1 \|
	213	+\| `GET_RT_ALIAS_CERT` \| PL0 or PL1 \|
	214	+\| `ECDSA384_SIGNATURE_VERIFY` \| PL0 or PL1 \|
	215	+\| `LMS_SIGNATURE_VERIFY` \| PL0 or PL1 \|
	216	+\| `MLDSA87_SIGNATURE_VERIFY` \| PL0 or PL1 \|
	217	+
	218	+\| `STASH_MEASUREMENT` \| PL0 \| Entire command
	219	+\| `DISABLE_ATTESTATION` \| PL0 \| Entire command
	220	+\| `INVOKE_DPE_COMMAND` \| PL0 or PL1 \| `CertifyKey` with `format=X509`; `DeriveContext` with the `export-cdi` flag; `DeriveContext` with `change-locality` targeting the PL0 PAUSER
	221	+\| `QUOTE_PCRS` \| PL0 or PL1 \|
	222	+\| `EXTEND_PCR` \| PL0 or PL1 \|
	223	+\| `GET_PCR_LOG` \| PL0 or PL1 \|
	224	+\| `INCREMENT_PCR_RESET_COUNTER` \| PL0 or PL1 \|
	225	+
	226	+\| `DPE_TAG_TCI` \| PL0 or PL1 \| Tags only contexts in the caller's own locality, so PL1 cannot tag a PL0 context (and vice versa)
	227	+\| `DPE_GET_TAGGED_TCI` \| PL0 or PL1 \| Looks up by tag only; either level can read any tagged TCI
	228	+\| `FW_INFO` \| PL0 or PL1 \|
	229	+\| `VERSION` \| PL0 or PL1 \|
	230	+\| `SELF_TEST_START` \| PL0 or PL1 \|
	231	+\| `SELF_TEST_GET_RESULTS` \| PL0 or PL1 \|
	232	+\| `SHUTDOWN` \| PL0 or PL1 \|
	233	+\| `ADD_SUBJECT_ALT_NAME` \| PL0 or PL1 \|
	234	+
	235	+\| `CERTIFY_KEY_EXTENDED` \| PL0 \| Entire command
	236	+\| `SET_AUTH_MANIFEST` \| PL0 \| Entire command
	237	+\| `AUTHORIZE_AND_STASH` \| PL0 or PL1 \| Stashing the measurement. A PL1 caller must set the `SKIP_STASH` flag; otherwise an authorized image fails when the measurement is stashed into DPE
	238	+\| `GET_IDEVID_CSR` \| PL0 or PL1 \|
	239	+\| `GET_FMC_ALIAS_CSR` \| PL0 or PL1 \|
	240	+
	241	+\| `SIGN_WITH_EXPORTED_ECDSA` \| PL0 \| Entire command
	242	+\| `REVOKE_EXPORTED_CDI_HANDLE` \| PL0 \| Entire command
	243	+\| `REALLOCATE_DPE_CONTEXT_LIMITS` \| PL0 \| Entire command
	244	+\| `SET_PQ_SEED` \| PL0 \| Entire command
	245	+\| `GET_PQ_CSR` \| PL0 or PL1 \|
	246	+\| `GET_PQ_INFO` \| PL0 or PL1 \|
	247	+
	248	+\| `POPULATE_PQ_CERT` \| PL0 \| Entire command
	249	+\| `GET_PQ_CERT` \| PL0 or PL1 \|
	250	+
	251	+\| `INVOKE_DPE_MLDSA87` \| PL0 or PL1 \| Same DPE command restrictions as `INVOKE_DPE_COMMAND`
	252	+\| `CERTIFY_KEY_EXTENDED_MLDSA87` \| PL0 \| Entire command
	253	+\| `SIGN_WITH_EXPORTED_MLDSA` \| PL0 \| Entire command
	254	+
180	255	### CALIPTRA\_FW\_LOAD
181	256
182	257	The `CALIPTRA_FW_LOAD` command is handled by both ROM and Runtime Firmware.
@@ -194,6 +269,8 @@
194	269
195	270	Command Code: `0x4657_4C44` ("FWLD")
196	271
	272	+Privilege Level: PL0 or PL1
	273	+
197	274	Table: `CALIPTRA_FW_LOAD` input arguments
198	275
199	276	\| Name \| Type \| Description
@@ -207,6 +284,8 @@
207	284	Exposes a command to retrieve firmware capabilities
208	285
209	286	Command Code: `0x4341_5053` ("CAPS")
	287	+
	288	+Privilege Level: PL0 or PL1
210	289
211	290	Table: `CAPABILITIES` input arguments
212	291
@@ -227,6 +306,8 @@
227	306	Exposes a command to reconstruct the IDEVID CERT.
228	307
229	308	Command Code: `0x4944_4543` ("IDEC")
	309	+
	310	+Privilege Level: PL0 or PL1
230	311
231	312	Table: `GET_IDEV_CERT` input arguments
232	313
@@ -255,6 +336,8 @@
255	336
256	337	Command Code: `0x4944_4550` ("IDEP")
257	338
	339	+Privilege Level: PL0
	340	+
258	341	Table: `POPULATE_IDEV_CERT` input arguments
259	342
260	343	\| Name \| Type \| Description
@@ -275,6 +358,8 @@
275	358	Exposes a command to get an IDEVID public key.
276	359
277	360	Command Code: `0x4944_4549` ("IDEI")
	361	+
	362	+Privilege Level: PL0 or PL1
278	363
279	364	Table: `GET_IDEV_INFO` input arguments
280	365
@@ -297,6 +382,8 @@
297	382
298	383	Command Code: `0x4C44_4556` ("LDEV")
299	384
	385	+Privilege Level: PL0 or PL1
	386	+
300	387	Table: `GET_LDEV_CERT` input arguments
301	388
302	389	\| Name \| Type \| Description
@@ -318,6 +405,8 @@
318	405
319	406	Command Code: `0x4345_5246` ("CERF")
320	407
	408	+Privilege Level: PL0 or PL1
	409	+
321	410	Table: `GET_FMC_ALIAS_CERT` input arguments
322	411
323	412	\| Name \| Type \| Description
@@ -339,6 +428,8 @@
339	428
340	429	Command Code: `0x4345_5252` ("CERR")
341	430
	431	+Privilege Level: PL0 or PL1
	432	+
342	433	Table: `GET_RT_ALIAS_CERT` input arguments
343	434
344	435	\| Name \| Type \| Description
@@ -363,6 +454,8 @@
363	454	and the cause will be logged as a non-fatal error.
364	455
365	456	Command Code: `0x5349_4756` ("SIGV")
	457	+
	458	+Privilege Level: PL0 or PL1
366	459
367	460	Table: `ECDSA384_SIGNATURE_VERIFY` input arguments
368	461
@@ -400,6 +493,8 @@
400	493	\| h \| 15 \| Height of the tree
401	494
402	495	Command Code: `0x4C4D_5356` ("LMSV")
	496	+
	497	+Privilege Level: PL0 or PL1
403	498
404	499	Table: `LMS_SIGNATURE_VERIFY` input arguments
405	500
@@ -422,6 +517,41 @@
422	517	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian.
423	518	\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error.
424	519
	520	+### MLDSA87\_SIGNATURE\_VERIFY
	521	+
	522	+Verifies an ML-DSA-87 (FIPS 204) signature. As with the ECDSA and LMS
	523	+verify commands, the message digest to be verified is taken from
	524	+Caliptra's SHA384 accelerator peripheral. Callers must stream the
	525	+message through the SHA accelerator before issuing this command;
	526	+carrying the raw message in-band would put hashing outside the FIPS
	527	+module boundary and is therefore disallowed.
	528	+
	529	+ML-DSA-87 is stateless and does not have the per-key signature budget that
	530	+LMS does, which is the primary motivation for adding this command alongside
	531	+the existing `LMS_SIGNATURE_VERIFY`.
	532	+
	533	+In the event of an invalid signature, the mailbox command will report
	534	+`CMD_FAILURE` and the cause will be logged as a non-fatal error.
	535	+
	536	+Command Code: `0x4D44_5356` ("MDSV")
	537	+
	538	+Privilege Level: PL0 or PL1
	539	+
	540	+Table: `MLDSA87_SIGNATURE_VERIFY` input arguments
	541	+
	542	+\| Name \| Type \| Description
	543	+\| -------- \| --------- \| ---------------
	544	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian.
	545	+\| pub\_key \| u8[2592] \| Encoded ML-DSA-87 public key (FIPS 204).
	546	+\| signature \| u8[4627] \| Encoded ML-DSA-87 signature (FIPS 204).
	547	+
	548	+Table: `MLDSA87_SIGNATURE_VERIFY` output arguments
	549	+
	550	+\| Name \| Type \| Description
	551	+\| -------- \| -------- \| ---------------
	552	+\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian.
	553	+\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error.
	554	+
425	555	### STASH\_MEASUREMENT
426	556
427	557	Makes a measurement into the DPE default context. This command is intended for
@@ -430,9 +560,10 @@
430	560	* Call the DPE DeriveContext command with the DefaultContext in the locality of
431	561	the PL0 PAUSER.
432	562	* Extend the measurement into PCR31 (`PCR_ID_STASH_MEASUREMENT`).
433		-* Note: This command can only be called in the locality of the PL0 PAUSER.
434	563
435	564	Command Code: `0x4D45_4153` ("MEAS")
	565	+
	566	+Privilege Level: PL0
436	567
437	568	Table: `STASH_MEASUREMENT` input arguments
438	569
@@ -469,6 +600,8 @@
469	600
470	601	Command Code: `0x4453_424C` ("DSBL")
471	602
	603	+Privilege Level: PL0
	604	+
472	605	Table: `DISABLE_ATTESTATION` input arguments
473	606
474	607	\| Name \| Type \| Description
@@ -487,6 +620,8 @@
487	620	Invokes a serialized DPE command.
488	621
489	622	Command Code: `0x4450_4543` ("DPEC")
	623	+
	624	+Privilege Level: PL0 or PL1; a subset of DPE commands requires PL0 (see [Mailbox command privilege levels](#mailbox-command-privilege-levels))
490	625
491	626	Table: `INVOKE_DPE_COMMAND` input arguments
492	627
@@ -511,6 +646,8 @@
511	646	All PCR values are hashed together with the nonce to produce the quote.
512	647
513	648	Command Code: `0x5043_5251` ("PCRQ")
	649	+
	650	+Privilege Level: PL0 or PL1
514	651
515	652	Table: `QUOTE_PCRS` input arguments
516	653
@@ -536,9 +673,13 @@
536	673
537	674	### EXTEND\_PCR
538	675
539		-Extends a Caliptra hardware PCR.
	676	+Extends a Caliptra hardware PCR. This command is restricted to the PL0 PAUSER.
	677	+PCR0 through PCR3 are reserved and cannot be extended with this command. PCR31
	678	+is available to PL0 for MCU-managed SoC firmware measurements.
540	679
541	680	Command Code: `0x5043_5245` ("PCRE")
	681	+
	682	+Privilege Level: PL0 or PL1
542	683
543	684	Table: `EXTEND_PCR` input arguments
544	685
@@ -555,6 +696,10 @@
555	696	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian.
556	697	\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error.
557	698
	699	+PCRs 0-3 (the FMC/RT current and journey PCRs) and PCR31 (the stash-measurement
	700	+PCR) are reserved for Caliptra's own use and cannot be extended through this
	701	+command by any caller; requests targeting them fail with `RUNTIME_PCR_RESERVED`.
	702	+
558	703	Note that extensions made into Caliptra's PCRs are _not_ appended to Caliptra's internal PCR log.
559	704
560	705	### GET\_PCR\_LOG
@@ -562,6 +707,8 @@
562	707	Gets Caliptra's internal PCR log.
563	708
564	709	Command Code: `0x504C_4F47` ("PLOG")
	710	+
	711	+Privilege Level: PL0 or PL1
565	712
566	713	Table: `GET_PCR_LOG` input arguments
567	714
@@ -590,6 +737,8 @@
590	737
591	738	Command Code: `0x5043_5252` ("PCRR")
592	739
	740	+Privilege Level: PL0 or PL1
	741	+
593	742	Table: `INCREMENT_PCR_RESET_COUNTER` input arguments
594	743
595	744	\| Name \| Type \| Description
@@ -609,6 +758,8 @@
609	758	Associates a unique tag with a DPE context.
610	759
611	760	Command Code: `0x5451_4754` ("TAGT")
	761	+
	762	+Privilege Level: PL0 or PL1; tags only contexts in the caller's own locality
612	763
613	764	Table: `DPE_TAG_TCI` input arguments
614	765
@@ -630,6 +781,8 @@
630	781	Retrieves the TCI measurements corresponding to the tagged DPE context.
631	782
632	783	Command Code: `0x4754_4744` ("GTGD")
	784	+
	785	+Privilege Level: PL0 or PL1; not locality-scoped, either level can read any tagged TCI
633	786
634	787	Table: `DPE_GET_TAGGED_TCI` input arguments
635	788
@@ -654,6 +807,8 @@
654	807	NOTE: Additional fields and info may be appended to the response in subsequent FW versions.
655	808
656	809	Command Code: `0x494E_464F` ("INFO")
	810	+
	811	+Privilege Level: PL0 or PL1
657	812
658	813	Table: `FW_INFO` input arguments
659	814
@@ -686,6 +841,8 @@
686	841
687	842	Command Code: `0x4650_5652` ("FPVR")
688	843
	844	+Privilege Level: PL0 or PL1
	845	+
689	846	Table: `VERSION` input arguments
690	847
691	848	\| Name \| Type \| Description
@@ -708,6 +865,8 @@
708	865
709	866	Command Code: `0x4650_4C54`
710	867
	868	+Privilege Level: PL0 or PL1
	869	+
711	870	Table: `SELF_TEST_START` input arguments
712	871
713	872	\| Name \| Type \| Description
@@ -727,6 +886,8 @@
727	886
728	887	Command Code: `0x4650_4C67`
729	888
	889	+Privilege Level: PL0 or PL1
	890	+
730	891	Table: `SELF_TEST_GET_RESULTS` input arguments
731	892
732	893	\| Name \| Type \| Description
@@ -745,6 +906,8 @@
745	906	FIPS command to zeroize and shut down the module
746	907
747	908	Command Code: `0x4650_5344` ("FPSD")
	909	+
	910	+Privilege Level: PL0 or PL1
748	911
749	912	Table: `SHUTDOWN` input arguments
750	913
@@ -769,6 +932,8 @@
769	932
770	933	Command Code: `0x414C_544E` ("ALTN")
771	934
	935	+Privilege Level: PL0 or PL1
	936	+
772	937	Table: `ADD_SUBJECT_ALT_NAME` input arguments
773	938
774	939	\| Name \| Type \| Description
@@ -790,6 +955,8 @@
790	955
791	956	Command Code: `0x434B_4558` ("CKEX")
792	957
	958	+Privilege Level: PL0
	959	+
793	960	Table: `CERTIFY_KEY_EXTENDED` input arguments
794	961
795	962	\| Name \| Type \| Description
@@ -815,6 +982,8 @@
815	982	### SET\_AUTH\_MANIFEST
816	983
817	984	Command Code: `0x4154_4D4E` ("ATMN")
	985	+
	986	+Privilege Level: PL0
818	987
819	988	Table: `SET_AUTH_MANIFEST` input arguments
820	989
@@ -881,6 +1050,8 @@
881	1050
882	1051	Command Code: `0x4154_5348` ("ATSH")
883	1052
	1053	+Privilege Level: PL0 or PL1; stashing the measurement requires PL0, so a PL1 caller must set the `SKIP_STASH` flag
	1054	+
884	1055	Table: `AUTHORIZE_AND_STASH` input arguments
885	1056
886	1057	\| Name \| Type \| Description \|
@@ -913,6 +1084,8 @@
913	1084
914	1085	Command Code: `0x4944_4352` ("IDCR")
915	1086
	1087	+Privilege Level: PL0 or PL1
	1088	+
916	1089	Table: `GET_IDEVID_CSR` input arguments
917	1090
918	1091	\| Name \| Type \| Description
@@ -942,6 +1115,8 @@
942	1115
943	1116	Command Code: `0x464D_4352` ("FMCR")
944	1117
	1118	+Privilege Level: PL0 or PL1
	1119	+
945	1120	Table: `GET_FMC_ALIAS_CSR` input arguments
946	1121
947	1122	\| Name \| Type \| Description
@@ -963,7 +1138,7 @@
963	1138
964	1139	Command Code: `0x5357_4545` ("SWEE")
965	1140
966		-Note: This command is only available in the locality of the PL0 PAUSER.
	1141	+Privilege Level: PL0
967	1142
968	1143	Table: `SIGN_WITH_EXPORTED_ECDSA` input arguments
969	1144
@@ -983,13 +1158,13 @@
983	1158	\| signature_s \| u8[48] \| The S BigNum of an ECDSA signature. \|
984	1159
985	1160
986		-The `exported_cdi` can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
	1161	+The `exported_cdi_handle` can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
987	1162
988	1163	### REVOKE\_EXPORTED\_CDI\_HANDLE
989	1164
990	1165	Command Code: `5256_4348` ("RVCH")
991	1166
992		-Note: This command is only available in the locality of the PL0 PAUSER.
	1167	+Privilege Level: PL0
993	1168
994	1169	Table: `REVOKE_EXPORTED_CDI_HANDLE` input arguments
995	1170
@@ -999,16 +1174,16 @@
999	1174	\| exported_cdi_handle \| u8[32] \| The Exported CDI handle returned by the DPE `DeriveContext` command. Little endian. \|
1000	1175
1001	1176
1002		-The `exported_cdi` can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
1003		-
1004		-The `exported_cdi_handle` is no longer usable after calling `REVOKE_EXPORTED_CDI_HANDLE` with it. After the `exported_cdi_handle`
1005		-has been revoked, a new exported CDI can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
	1177	+The `exported_cdi_handle` can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
	1178	+
	1179	+The `exported_cdi_handle` is no longer usable after calling `REVOKE_EXPORTED_CDI_HANDLE` with it. After the `exported_cdi_handle`
	1180	+has been revoked, a new exported CDI handle can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
1006	1181
1007	1182	### REALLOCATE\_DPE\_CONTEXT\_LIMITS
1008	1183
1009	1184	Command Code: '5243_5458` ("RCTX")
1010	1185
1011		-Note: This command is only available in the locality of the PL0 PAUSER.
	1186	+Privilege Level: PL0
1012	1187
1013	1188	Table: `REALLOCATE_DPE_CONTEXT_LIMITS` input arguments
1014	1189
@@ -1030,6 +1205,212 @@
1030	1205	This allows the user to reallocate the 32 DPE contexts between PL0 and PL1. By default, each gets 16 contexts.
1031	1206
1032	1207	Note: 2 PL0 contexts are used by Caliptra itself during initialization.
	1208	+
	1209	+## PQC (ML-DSA-87) commands
	1210	+
	1211	+The following commands implement the `PQ.DevID` post-quantum identity retrofit described in [Software-based PQC features](https://github.com/chipsalliance/Caliptra/blob/main/doc/caliptra_1x/Caliptra.md#software-based-pqc-features-caliptra-13). All ML-DSA-87 cryptography is implemented in software; there is no hardware PQC accelerator on Caliptra 1.x silicon.
	1212	+The availability of these commands is advertised to the SoC via the `RT_MLDSA_ATTESTATION` bit in the [`CAPABILITIES`](#capabilities) output.
	1213	+
	1214	+### SET\_PQ\_SEED
	1215	+
	1216	+Delivers `PQ.DevID.Seed` from the SoC to Caliptra. Caliptra derives `PQ.DevID.CDI` from the seed via an HMAC-based KDF, derives the ML-DSA-87 `PQ.DevID` keypair, and caches the public key digest in persistent data.
	1217	+
	1218	+Command Code: `0x5051_5344` ("PQSD")
	1219	+
	1220	+Privilege Level: PL0
	1221	+
	1222	+Table: `SET_PQ_SEED` input arguments
	1223	+
	1224	+\| Name \| Type \| Description
	1225	+\| -------- \| --------- \| ---------------
	1226	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian.
	1227	+\| seed \| u8[48] \| `PQ.DevID.Seed`. Per-device unique symmetric seed, provided by the SoC.
	1228	+
	1229	+Table: `SET_PQ_SEED` output arguments
	1230	+
	1231	+\| Name \| Type \| Description
	1232	+\| -------- \| -------- \| ---------------
	1233	+\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian.
	1234	+\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error.
	1235	+
	1236	+Deriving `PQ.DevID.CDI` and the ML-DSA-87 key material can exceed the default mailbox command watchdog budget; Runtime Firmware extends the watchdog for this command.
	1237	+The production `PQ.DevID.Seed` must never be delivered while Caliptra is `DebugUnlocked`.
	1238	+Integrators may still call `SET_PQ_SEED` with a non-production seed while `DebugUnlocked` for local bring-up and debug.
	1239	+
	1240	+### GET\_PQ\_CSR
	1241	+
	1242	+Returns a CSR for the `PQ.DevID` ML-DSA-87 public key, for collection during manufacturing/provisioning, mirroring [`GET_IDEVID_CSR`](#get_idevid_csr).
	1243	+
	1244	+Command Code: `0x5051_4353` ("PQCS")
	1245	+
	1246	+Privilege Level: PL0 or PL1
	1247	+
	1248	+Table: `GET_PQ_CSR` input arguments
	1249	+
	1250	+\| Name \| Type \| Description
	1251	+\| -------- \| -------- \| ---------------
	1252	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian.
	1253	+
	1254	+Table: `GET_PQ_CSR` output arguments
	1255	+
	1256	+\| Name \| Type \| Description
	1257	+\| -------- \| --------- \| ---------------
	1258	+\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian.
	1259	+\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error.
	1260	+\| data\_size \| u32 \| Length in bytes of the valid data in the data field, with a maximum of 12800.
	1261	+\| data \| u8[12800] \| DER-encoded ML-DSA-87 `PQ.DevID` certificate signing request.
	1262	+
	1263	+### GET\_PQ\_INFO
	1264	+
	1265	+Returns the raw ML-DSA-87 `PQ.DevID` public key.
	1266	+
	1267	+Command Code: `0x5051_494E` ("PQIN")
	1268	+
	1269	+Privilege Level: PL0 or PL1
	1270	+
	1271	+Table: `GET_PQ_INFO` input arguments
	1272	+
	1273	+\| Name \| Type \| Description
	1274	+\| -------- \| -------- \| ---------------
	1275	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian.
	1276	+
	1277	+Table: `GET_PQ_INFO` output arguments
	1278	+
	1279	+\| Name \| Type \| Description
	1280	+\| -------- \| --------- \| ---------------
	1281	+\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian.
	1282	+\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error.
	1283	+\| pq\_pub\_key \| u8[2592] \| Encoded ML-DSA-87 `PQ.DevID` public key (FIPS 204).
	1284	+
	1285	+### POPULATE\_PQ\_CERT
	1286	+
	1287	+Allows the SoC to provide a DER-encoded `PQ.DevID` certificate on every boot, once it has been issued by the vendor/owner PQC provisioning CA. Mirrors [`POPULATE_IDEV_CERT`](#populate_idev_cert).
	1288	+
	1289	+Command Code: `0x5050_5143` ("PPQC")
	1290	+
	1291	+Privilege Level: PL0
	1292	+
	1293	+Table: `POPULATE_PQ_CERT` input arguments
	1294	+
	1295	+\| Name \| Type \| Description
	1296	+\| -------- \| -------- \| ---------------
	1297	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian.
	1298	+\| cert\_size \| u32 \| Size of the DER-encoded `PQ.DevID` certificate, with a maximum of 8192.
	1299	+\| cert \| u8[8192] \| DER-encoded `PQ.DevID` certificate.
	1300	+
	1301	+Table: `POPULATE_PQ_CERT` output arguments
	1302	+
	1303	+\| Name \| Type \| Description
	1304	+\| -------- \| -------- \| ---------------
	1305	+\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian.
	1306	+\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error.
	1307	+
	1308	+### GET\_PQ\_CERT
	1309	+
	1310	+Given a caller-supplied TBS and ML-DSA-87 signature over that TBS, DER-assembles and returns the resulting `PQ.DevID` certificate. Stateless: it does not read the certificate buffer populated by `POPULATE_PQ_CERT`. Mirrors [`GET_IDEV_CERT`](#get_idev_cert).
	1311	+
	1312	+Command Code: `0x4750_5143` ("GPQC")
	1313	+
	1314	+Privilege Level: PL0 or PL1
	1315	+
	1316	+Table: `GET_PQ_CERT` input arguments
	1317	+
	1318	+\| Name \| Type \| Description
	1319	+\| -------- \| -------- \| ---------------
	1320	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian.
	1321	+\| tbs\_size \| u32 \| Size of the TBS, with a maximum of 3543.
	1322	+\| signature \| u8[4627] \| ML-DSA-87 signature (FIPS 204) over the TBS, supplied by the caller. Not verified or computed by Caliptra; used as-is to assemble the certificate's `signatureValue`.
	1323	+\| tbs \| u8[3543] \| TBS. Only bytes up to tbs_size are used.
	1324	+
	1325	+Table: `GET_PQ_CERT` output arguments
	1326	+
	1327	+\| Name \| Type \| Description
	1328	+\| -------- \| -------- \| ---------------
	1329	+\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian.
	1330	+\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error.
	1331	+\| cert\_size \| u32 \| Length in bytes of the valid data in the cert field, with a maximum of 8192.
	1332	+\| cert \| u8[8192] \| DER-encoded `PQ.DevID` certificate.
	1333	+
	1334	+### INVOKE\_DPE\_MLDSA87
	1335	+
	1336	+Invokes a DPE command using the ML-DSA-87 crypto backend, mirroring [`INVOKE_DPE_COMMAND`](#invoke_dpe_command) but rooted in the ML-DSA-87 DPE profile.
	1337	+
	1338	+Command Code: `0x4D4C_4450` ("MLDP")
	1339	+
	1340	+Privilege Level: PL0 or PL1; a subset of DPE commands requires PL0 (see [Mailbox command privilege levels](#mailbox-command-privilege-levels))
	1341	+
	1342	+Table: `INVOKE_DPE_MLDSA87` input arguments
	1343	+
	1344	+\| Name \| Type \| Description
	1345	+\| -------- \| -------- \| ---------------
	1346	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian.
	1347	+\| data\_size \| u32 \| Length in bytes of the valid data in the data field.
	1348	+\| data \| u8[512] \| Encoded DPE command. Only bytes up to data_size are used.
	1349	+
	1350	+Table: `INVOKE_DPE_MLDSA87` output arguments
	1351	+
	1352	+\| Name \| Type \| Description
	1353	+\| -------- \| ----------- \| ---------------
	1354	+\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian.
	1355	+\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error.
	1356	+\| data\_size \| u32 \| Length in bytes of the valid data in the data field.
	1357	+\| data \| u8[25168] \| Encoded DPE response. Only bytes up to data_size are used.
	1358	+
	1359	+### CERTIFY\_KEY\_EXTENDED\_MLDSA87
	1360	+
	1361	+The ML-DSA-87 counterpart to [`CERTIFY_KEY_EXTENDED`](#certify_key_extended): produces a DPE leaf certificate or CSR, signed with ML-DSA-87, containing custom extensions provided by the SoC.
	1362	+
	1363	+Command Code: `0x434B_454D` ("CKEM")
	1364	+
	1365	+Privilege Level: PL0
	1366	+
	1367	+Table: `CERTIFY_KEY_EXTENDED_MLDSA87` input arguments
	1368	+
	1369	+\| Name \| Type \| Description
	1370	+\| -------- \| -------- \| ---------------
	1371	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian.
	1372	+\| flags \| u32 \| Flags determining which custom extensions to include in the certificate. See [`CERTIFY_KEY_EXTENDED` input flags](#certify_key_extended).
	1373	+\| certify\_key\_req \| u8[72] \| Certify Key Request.
	1374	+
	1375	+Table: `CERTIFY_KEY_EXTENDED_MLDSA87` output arguments
	1376	+
	1377	+\| Name \| Type \| Description
	1378	+\| -------- \| -------- \| ---------------
	1379	+\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian.
	1380	+\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error.
	1381	+\| size \| u32 \| Length in bytes of the valid data in the certify_key_resp field.
	1382	+\| certify\_key\_resp \| u8[25152] \| Certify Key Response.
	1383	+
	1384	+This command can take tens of millions of CPU cycles due to the software ML-DSA-87 implementation; see [Performance considerations](https://github.com/chipsalliance/Caliptra/blob/main/doc/caliptra_1x/Caliptra.md#performance-considerations).
	1385	+
	1386	+### SIGN\_WITH\_EXPORTED\_MLDSA
	1387	+
	1388	+The ML-DSA-87 counterpart to [`SIGN_WITH_EXPORTED_ECDSA`](#sign_with_exported_ecdsa): signs with an ML-DSA-87 key pair derived from a previously exported DPE CDI handle.
	1389	+
	1390	+Command Code: `0x5357_4D4C` ("SWML")
	1391	+
	1392	+Privilege Level: PL0
	1393	+
	1394	+Table: `SIGN_WITH_EXPORTED_MLDSA` input arguments
	1395	+
	1396	+\| Name \| Type \| Description
	1397	+\| -------- \| -------- \| ---------------
	1398	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian.
	1399	+\| exported\_cdi\_handle \| u8[32] \| The Exported CDI handle returned by the DPE `DeriveContext` command.
	1400	+\| sign\_mode \| u32 \| `0` (`SIGN_MODE_DATA`): `message[..message_size]` is the raw message to sign, and Caliptra computes `mu` internally. `1` (`SIGN_MODE_EXTERNAL_MU`): `message[..MU_SIZE]` is a caller-supplied external `mu`; `message_size` must equal `MU_SIZE`.
	1401	+\| message\_size \| u32 \| Length in bytes of the valid data in the message field.
	1402	+\| message \| u8[1024] \| Raw message (`SIGN_MODE_DATA`) or external `mu` (`SIGN_MODE_EXTERNAL_MU`). Only bytes up to message_size are used.
	1403	+
	1404	+Table: `SIGN_WITH_EXPORTED_MLDSA` output arguments
	1405	+
	1406	+\| Name \| Type \| Description
	1407	+\| -------- \| --------- \| ---------------
	1408	+\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian.
	1409	+\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error.
	1410	+\| derived\_pubkey \| u8[2592] \| The ML-DSA-87 public key associated with the signing key.
	1411	+\| signature \| u8[4627] \| The ML-DSA-87 signature.
	1412	+
	1413	+The `exported_cdi_handle` can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags, as with `SIGN_WITH_EXPORTED_ECDSA`.
1033	1414
1034	1415	## Checksum
1035	1416
@@ -1118,8 +1499,9 @@
1118	1499	* PL0 - High privilege. Only 1 PAUSER in the SoC may be at PL0. The PL0 PAUSER
1119	1500	is denoted in the signed Caliptra firmware image. The PL0 PAUSER may call any
1120	1501	supported DPE commands. Only PL0 can use the CertifyKey command. Success of the
1121		- CertifyKey command signifies to the caller that it is at PL0. Only PL0 can use
1122		- the POPULATE\_IDEV\_CERT mailbox command.
	1502	+ CertifyKey command signifies to the caller that it is at PL0. A number of
	1503	+ mailbox commands are also restricted to PL0; see
	1504	+ [Mailbox command privilege levels](#mailbox-command-privilege-levels).
1123	1505	* PL1 - Restricted privilege. All other PAUSERs in the SoC are PL1. Caliptra
1124	1506	SHALL fail any calls to the DPE CertifyKey with format=X509 by PL1 callers.
1125	1507	PL1 callers should use the CSR format instead.
@@ -1154,20 +1536,21 @@
1154	1536	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
1155	1537	of active contexts in PL0's locality, and hence allow PL1 to DOS PL0.
1156	1538
1157		-### DPE profile implementation
1158		-
1159		-The DPE iRoT profile leaves some choices up to implementers. This section
1160		-describes specific requirements for the Caliptra DPE implementation.
1161		-
1162		-\| Name \| Value \| Description
1163		-\| ---- \| ----- \| -----------
1164		-\| Profile Variant \| `DPE_PROFILE_IROT_P384_SHA384` \| The profile variant that Caliptra implements.
1165		-\| KDF \| SP800-108 HMAC-CTR \| KDF to use for CDI (tcg.derive.kdf-sha384) and asymmetric key (tcg.derive.kdf-sha384-p384) derivation.
1166		-\| Simulation Context Support \| Yes \| Whether Caliptra implements the optional Simulation Contexts feature.
1167		-\| Supports ExtendTci \| Yes \| Whether Caliptra implements the optional ExtendTci command.
1168		-\| Supports Auto Init \| Yes \| Whether Caliptra will automatically initialize the default DPE context.
1169		-\| Supports Rotate Context \| Yes \| Whether Caliptra supports the optional RotateContextHandle command.
1170		-\| CertifyKey Alias Key \| Caliptra Runtime Alias Key \| The key that will be used to sign certificates that are produced by the DPE CertifyKey command.
	1539	+### Caliptra DPE Profile
	1540	+
	1541	+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.
	1542	+
	1543	+\| Name \| Value \| Description \|
	1544	+\| -------------------------- \| ------------------------------ \| ------------------------------------------------------------------------------------------------------ \|
	1545	+\| Profile Variant \| `Caliptra DPE Profile` \| Derived from `DPE_PROFILE_IROT_P384_SHA384`. \|
	1546	+\| KDF \| SP800-108 HMAC-CTR \| KDF to use for CDI (tcg.derive.kdf-sha384) and asymmetric key (tcg.derive.kdf-sha384-p384) derivation. \|
	1547	+\| Simulation Context Support \| Yes \| Whether Caliptra implements the optional Simulation Contexts feature. \|
	1548	+\| Supports ExtendTci \| Yes \| Whether Caliptra implements the optional ExtendTci command. \|
	1549	+\| Supports Auto Init \| Yes \| Whether Caliptra will automatically initialize the default DPE context. \|
	1550	+\| Supports Rotate Context \| Yes \| Whether Caliptra supports the optional RotateContextHandle command. \|
	1551	+\| CertifyKey Alias Key \| Caliptra Runtime Alias Key \| The key that will be used to sign certificates that are produced by the DPE CertifyKey command. \|
	1552	+\| `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. \|
	1553	+
1171	1554
1172	1555	### Supported DPE commands
1173	1556
@@ -1176,6 +1559,7 @@
1176	1559	* GetProfile
1177	1560	* InitializeContext
1178	1561	* DeriveContext
	1562	+ * 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.
1179	1563	* Note: The "export-cdi" flag is only available in the locality of the PL0 PAUSER.
1180	1564	* CertifyKey
1181	1565	* Caliptra DPE supports two formats for CertifyKey: X.509 and PKCS#10 CSR.

Changes to Runtime Specification