Diff: Runtime Specification

@@ -1,8 +1,8 @@
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/51ff0a89f169bbf8e06acb49b31db555e99fefb6/runtime/README.md" target="_blank">chipsalliance/caliptra-sw/runtime/README.md</a> @ <code>51ff0a8</code>
	2	+📄 Source: <a href="https://github.com/chipsalliance/caliptra-sw/blob/6ec4a4a473a8a9aaf9788649bf7fbcdea1ee0c36/runtime/README.md" target="_blank">chipsalliance/caliptra-sw/runtime/README.md</a> @ <code>6ec4a4a</code>
3	3	</div>
4	4
5		-# Caliptra Runtime Firmware v1.1
	5	+# Caliptra Runtime Firmware v1.2
6	6
7	7	This specification describes the Caliptra Runtime Firmware.
8	8
@@ -62,7 +62,100 @@
62	62	possible; however, it will have its own copies of all of these drivers linked into
63	63	the Runtime Firmware binary.
64	64
65		-## Maibox commands
	65	+## Manifest-Based Image Authorization (new in 1.2)
	66	+
	67	+Caliptra's goal is to enable integrators to meet standard security requirements for creating cryptographic identity and securely reporting measurements through DICE and DPE Certificate chains and Caliptra-owned private-public key pairs. In addition, Caliptra 1.0 provides an `ECDSA384_SIGNATURE_VERIFY` command to enable an SoC RoT to verify its own FW signatures so that it can develop an SoC secure boot using Caliptra cryptography. Caliptra 1.1 expanded the verify command to a PQC-safe `LMS_SIGNATURE_VERIFY` command. In each of these cases, it is left up to the vendor to ensure that they build a secure environment for introducing and verifying FW integrity and authenticity and then executing mutable FW.
	68	+
	69	+The Caliptra Measurement manifest feature expands on Caliptra-provided secure verifier abilities. The Measurement Manifest feature provides a standard Caliptra-supported definition to enable the following use cases for integrators, vendors, and owners.
	70	+
	71	+* Caliptra-Endorsed Aggregated Measured Boot
	72	+* Caliptra-Endorsed Local Verifier
	73	+
	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	+
	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/6ec4a4a473a8a9aaf9788649bf7fbcdea1ee0c36/auth-manifest/README.md).
	77	+
	78	+### Caliptra-Endorsed Aggregated Measured Boot
	79	+
	80	+Aggregated Measured Boot is a verified boot where one signed manifest attests to FW integrity of many different FW measurements. The authenticity of the FW is tied to the trust in the public key signing the measurement manifest, which is endorsed by the Caliptra Vendor and/or Owner FW Keys.
	81	+
	82	+### Caliptra-Endorsed Local Verifier
	83	+
	84	+A local verifier provides an authentication of SoC FW by matching SoC FW measurements with measurements from the Caliptra measurement manifest. In this case, the SoC RoT still has its own FW public-key chain that is verified by the SoC RoT, but in addition the SoC RoT introduces the Caliptra Measurement Manifest, which is endorsed by the Caliptra FW key pair. Caliptra provides approval or disapproval of the measurement of any FW back to the SoC RoT. This effectively provides a multi-factor authentication of SoC FW.
	85	+
	86	+The Caliptra-Endorsed Local Verifier could be required by the owner only or both the vendor and the owner.
	87	+
	88	+The main difference between Caliptra-Endorsed Aggregated Measured Boot and Caliptra-Endorsed Local Verifier is whether the SoC RoT is relying on the Measurement Manifest for SoC Secure Boot services as opposed to using it as an additional verification.
	89	+
	90	+### SoC RoT Enforcement of Measurement Manifest
	91	+
	92	+In both use cases, the SoC RoT chooses to provide the Caliptra Measurement Manifest and to enforce the result of the authorization. Caliptra 1.x is not capable of providing any enforcement of measurements for SoC FW execution.
	93	+
	94	+### Caliptra Measurement Manifest Signing Keys Authenticity
	95	+
	96	+Caliptra 1.0 and 1.1 do not put any requirements on how the SoC RoT ensures integrity and authenticity of SoC FW other than requiring the SoC RoT to provide a measurement to Caliptra of any SoC FW before execution. Caliptra Measurement Manifest enables the SoC RoT to perform the integrity check through Caliptra-authorized FW signing keys.
	97	+
	98	+### Unique Measurement Manifest Signing Keys
	99	+
	100	+In order to reduce usage of the Caliptra FW Signing keys, the measurement manifest will be signed by new key pairs: one for the owner and optionally one for the vendor. These new key pairs are endorsed once by the Caliptra FW signing keys, the signature being in the Measurement Manifest, thus allowing the measurement manifest keys to be used independently of the Caliptra FW signing keys.
	101	+
	102	+### Caliptra Measurement Manifest Vendor Public Key Authenticity
	103	+
	104	+The Measurement Manifest MUST have an endorsement by the Caliptra Vendor Public Key. In order to fulfill this requirement, the Vendor has 2 options:
	105	+
	106	+* Vendor signing of `Image Metadata Collection` required: The Vendor creates a new Measurement keypair which will sign the measurement manifest and endorses this new public key with the Caliptra FW Vendor Private Key. The signature covers both the new public key as well as the flags field which indicates that the new Measurement Key Pair will be enforced.
	107	+* Vendor signing of `Image Metadata Collection` not required: Vendor leaves the Vendor public key as all zeros, and clears the flag which enforces vendor signing and then endorses these fields with a signature in the Measurement Manifest. In this case, the Vendor releases ownership of enforcing any specific FW in execution.
	108	+
	109	+### Caliptra Measurement Manifest Owner Public Key Authenticity
	110	+
	111	+Caliptra will always verify the endorsement of the Measurement Manifest Owner Public key and require that it signed the measurement manifest.
	112	+
	113	+This feature is accomplished by having the SoC send a manifest to Caliptra Runtime through the `SET_AUTH_MANIFEST` mailbox command. The manifest will include a set of hashes for the different SoC images. Later, the SOC will ask for authorization for its images from the Caliptra Runtime through the `AUTHORIZE_AND_STASH` new mailbox command. Caliptra Runtime will authorize the image based on whether its hash was contained in the manifest.
	114	+
	115	+#### Preamble
	116	+
	117	+The manifest begins with the Preamble section, which contains new manifest ECC and LMS public keys of the vendor and the owner. These public keys correspond to the private keys that sign the Image Metadata Collection (IMC) section. These signatures are included in the Preamble. The Caliptra firmware's private keys endorse the manifest's public keys and these endorsements (i.e., signatures) are part of the Preamble as well.
	118	+
	119	+#### Image Metadata Collection (IMC)
	120	+
	121	+The IMC is a collection of Image Metadata entries (IME). Each IME has a hash that matches one of the multiple SoC images. The manifest vendor and owner private keys sign the IMC. The Preamble holds the IMC signatures. The manifest IMC vendor signatures are optional and are validated only if the Flags field Bit 0 is set to 1. Up to 127 image hashes will be supported.
	122	+
	123	+#### Caliptra Measurement Manifest Keys Endorsement Verification Steps
	124	+
	125	+When Caliptra receives the Measurement Manifest, Caliptra will:
	126	+
	127	+* Verify the vendor endorsement using the Caliptra Vendor FW Public Key and compare with the vendor endorsement signature.
	128	+* If the vendor endorsement is invalid, the `SET_AUTH_MANIFEST` command will be rejected.
	129	+* If the vendor endorsement is valid, Caliptra will check if a vendor manifest measurement key is required:
	130	+ * If the key is required, Caliptra will trust the Vendor Public key that was just endorsed.
	131	+ * If the key is not required, Caliptra will not perform any more vendor verifications on this measurement manifest.
	132	+* Verify the owner endorsement using the Caliptra owner public key and compare with the owner endorsement signature.
	133	+ * If the owner endorsement is invalid, the `SET_AUTH_MANIFEST` command will be rejected.
	134	+ * Otherwise, the owner public key will be trusted and Caliptra will use it to verify the overall measurement manifest.
	135	+
	136	+### Image Authorization Sequence
	137	+
	138	+The diagram below illustrates how this feature is part of the Caliptra boot flow, and the order of operations needed to use the feature.
	139	+
	140	+```mermaid
	141	+sequenceDiagram
	142	+ ROM->>FMC: Launch FMC
	143	+ FMC->>Runtime: Launch RT
	144	+ Runtime->>SOC: RDY_FOR_RT
	145	+ Note over Runtime,SOC: Manifest Load
	146	+ SOC->>Runtime: SET_AUTH_MANIFEST
	147	+ Runtime-->>SOC: Success/Failure
	148	+ Note over Runtime,SOC: Image Authorization
	149	+ loop n times
	150	+ SOC->>Runtime: AUTHORIZE_AND_STASH
	151	+ Runtime-->>SOC: Success/Failure
	152	+ end
	153	+
	154	+ Note over Runtime,SOC: DPE Attestation
	155	+ SOC->>Runtime: DPE Attestation
	156	+```
	157	+
	158	+## Mailbox commands
66	159
67	160	All mailbox command codes are little endian.
68	161
@@ -84,6 +177,81 @@
84	177	* CPTRA\_FW\_ERROR\_NON\_FATAL: Status code of mailbox command. Any result
85	178	other than `SUCCESS` signifies a mailbox command failure.
86	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	+
87	255	### CALIPTRA\_FW\_LOAD
88	256
89	257	The `CALIPTRA_FW_LOAD` command is handled by both ROM and Runtime Firmware.
@@ -101,6 +269,8 @@
101	269
102	270	Command Code: `0x4657_4C44` ("FWLD")
103	271
	272	+Privilege Level: PL0 or PL1
	273	+
104	274	Table: `CALIPTRA_FW_LOAD` input arguments
105	275
106	276	\| Name \| Type \| Description
@@ -114,6 +284,8 @@
114	284	Exposes a command to retrieve firmware capabilities
115	285
116	286	Command Code: `0x4341_5053` ("CAPS")
	287	+
	288	+Privilege Level: PL0 or PL1
117	289
118	290	Table: `CAPABILITIES` input arguments
119	291
@@ -134,6 +306,8 @@
134	306	Exposes a command to reconstruct the IDEVID CERT.
135	307
136	308	Command Code: `0x4944_4543` ("IDEC")
	309	+
	310	+Privilege Level: PL0 or PL1
137	311
138	312	Table: `GET_IDEV_CERT` input arguments
139	313
@@ -162,6 +336,8 @@
162	336
163	337	Command Code: `0x4944_4550` ("IDEP")
164	338
	339	+Privilege Level: PL0
	340	+
165	341	Table: `POPULATE_IDEV_CERT` input arguments
166	342
167	343	\| Name \| Type \| Description
@@ -182,6 +358,8 @@
182	358	Exposes a command to get an IDEVID public key.
183	359
184	360	Command Code: `0x4944_4549` ("IDEI")
	361	+
	362	+Privilege Level: PL0 or PL1
185	363
186	364	Table: `GET_IDEV_INFO` input arguments
187	365
@@ -200,9 +378,11 @@
200	378
201	379	### GET\_LDEV\_CERT
202	380
203		-Exposes a command to get a self-signed LDevID certificate signed by IDevID.
	381	+Exposes a command to get an LDevID certificate signed by IDevID.
204	382
205	383	Command Code: `0x4C44_4556` ("LDEV")
	384	+
	385	+Privilege Level: PL0 or PL1
206	386
207	387	Table: `GET_LDEV_CERT` input arguments
208	388
@@ -221,9 +401,11 @@
221	401
222	402	### GET\_FMC\_ALIAS\_CERT
223	403
224		-Exposes a command to get a self-signed FMC alias certificate signed by LDevID.
	404	+Exposes a command to get an FMC alias certificate signed by LDevID.
225	405
226	406	Command Code: `0x4345_5246` ("CERF")
	407	+
	408	+Privilege Level: PL0 or PL1
227	409
228	410	Table: `GET_FMC_ALIAS_CERT` input arguments
229	411
@@ -242,9 +424,11 @@
242	424
243	425	### GET\_RT\_ALIAS\_CERT
244	426
245		-Exposes a command to get a self-signed Runtime alias certificate signed by the FMC alias.
	427	+Exposes a command to get a Runtime alias certificate signed by the FMC alias.
246	428
247	429	Command Code: `0x4345_5252` ("CERR")
	430	+
	431	+Privilege Level: PL0 or PL1
248	432
249	433	Table: `GET_RT_ALIAS_CERT` input arguments
250	434
@@ -270,6 +454,8 @@
270	454	and the cause will be logged as a non-fatal error.
271	455
272	456	Command Code: `0x5349_4756` ("SIGV")
	457	+
	458	+Privilege Level: PL0 or PL1
273	459
274	460	Table: `ECDSA384_SIGNATURE_VERIFY` input arguments
275	461
@@ -307,6 +493,8 @@
307	493	\| h \| 15 \| Height of the tree
308	494
309	495	Command Code: `0x4C4D_5356` ("LMSV")
	496	+
	497	+Privilege Level: PL0 or PL1
310	498
311	499	Table: `LMS_SIGNATURE_VERIFY` input arguments
312	500
@@ -329,9 +517,44 @@
329	517	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian.
330	518	\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error.
331	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	+
332	555	### STASH\_MEASUREMENT
333	556
334		-Makes a measurement into the DPE default context. This command is intendend for
	557	+Makes a measurement into the DPE default context. This command is intended for
335	558	callers who update infrequently and cannot tolerate a changing DPE API surface.
336	559
337	560	* Call the DPE DeriveContext command with the DefaultContext in the locality of
@@ -339,6 +562,8 @@
339	562	* Extend the measurement into PCR31 (`PCR_ID_STASH_MEASUREMENT`).
340	563
341	564	Command Code: `0x4D45_4153` ("MEAS")
	565	+
	566	+Privilege Level: PL0
342	567
343	568	Table: `STASH_MEASUREMENT` input arguments
344	569
@@ -375,6 +600,8 @@
375	600
376	601	Command Code: `0x4453_424C` ("DSBL")
377	602
	603	+Privilege Level: PL0
	604	+
378	605	Table: `DISABLE_ATTESTATION` input arguments
379	606
380	607	\| Name \| Type \| Description
@@ -393,6 +620,8 @@
393	620	Invokes a serialized DPE command.
394	621
395	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))
396	625
397	626	Table: `INVOKE_DPE_COMMAND` input arguments
398	627
@@ -417,6 +646,8 @@
417	646	All PCR values are hashed together with the nonce to produce the quote.
418	647
419	648	Command Code: `0x5043_5251` ("PCRQ")
	649	+
	650	+Privilege Level: PL0 or PL1
420	651
421	652	Table: `QUOTE_PCRS` input arguments
422	653
@@ -446,6 +677,8 @@
446	677
447	678	Command Code: `0x5043_5245` ("PCRE")
448	679
	680	+Privilege Level: PL0 or PL1
	681	+
449	682	Table: `EXTEND_PCR` input arguments
450	683
451	684	\| Name \| Type \| Description
@@ -461,6 +694,10 @@
461	694	\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian.
462	695	\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error.
463	696
	697	+PCRs 0-3 (the FMC/RT current and journey PCRs) and PCR31 (the stash-measurement
	698	+PCR) are reserved for Caliptra's own use and cannot be extended through this
	699	+command by any caller; requests targeting them fail with `RUNTIME_PCR_RESERVED`.
	700	+
464	701	Note that extensions made into Caliptra's PCRs are _not_ appended to Caliptra's internal PCR log.
465	702
466	703	### GET\_PCR\_LOG
@@ -468,6 +705,8 @@
468	705	Gets Caliptra's internal PCR log.
469	706
470	707	Command Code: `0x504C_4F47` ("PLOG")
	708	+
	709	+Privilege Level: PL0 or PL1
471	710
472	711	Table: `GET_PCR_LOG` input arguments
473	712
@@ -496,6 +735,8 @@
496	735
497	736	Command Code: `0x5043_5252` ("PCRR")
498	737
	738	+Privilege Level: PL0 or PL1
	739	+
499	740	Table: `INCREMENT_PCR_RESET_COUNTER` input arguments
500	741
501	742	\| Name \| Type \| Description
@@ -515,6 +756,8 @@
515	756	Associates a unique tag with a DPE context.
516	757
517	758	Command Code: `0x5451_4754` ("TAGT")
	759	+
	760	+Privilege Level: PL0 or PL1; tags only contexts in the caller's own locality
518	761
519	762	Table: `DPE_TAG_TCI` input arguments
520	763
@@ -536,6 +779,8 @@
536	779	Retrieves the TCI measurements corresponding to the tagged DPE context.
537	780
538	781	Command Code: `0x4754_4744` ("GTGD")
	782	+
	783	+Privilege Level: PL0 or PL1; not locality-scoped, either level can read any tagged TCI
539	784
540	785	Table: `DPE_GET_TAGGED_TCI` input arguments
541	786
@@ -557,7 +802,11 @@
557	802
558	803	Retrieves information about the current Runtime Firmware, FMC, and ROM.
559	804
	805	+NOTE: Additional fields and info may be appended to the response in subsequent FW versions.
	806	+
560	807	Command Code: `0x494E_464F` ("INFO")
	808	+
	809	+Privilege Level: PL0 or PL1
561	810
562	811	Table: `FW_INFO` input arguments
563	812
@@ -582,12 +831,15 @@
582	831	\| rom_sha256_digest \| u32[8] \| Digest of ROM binary.
583	832	\| fmc_sha384_digest \| u32[12] \| Digest of FMC binary.
584	833	\| runtime_sha384_digest \| u32[12] \| Digest of runtime binary.
	834	+\| owner_pub_key_hash \| u32[12] \| Hash of the owner public keys provided in the image bundle manifest.
585	835
586	836	### VERSION
587	837
588	838	FIPS command to get version info for the module
589	839
590	840	Command Code: `0x4650_5652` ("FPVR")
	841	+
	842	+Privilege Level: PL0 or PL1
591	843
592	844	Table: `VERSION` input arguments
593	845
@@ -611,6 +863,8 @@
611	863
612	864	Command Code: `0x4650_4C54`
613	865
	866	+Privilege Level: PL0 or PL1
	867	+
614	868	Table: `SELF_TEST_START` input arguments
615	869
616	870	\| Name \| Type \| Description
@@ -630,6 +884,8 @@
630	884
631	885	Command Code: `0x4650_4C67`
632	886
	887	+Privilege Level: PL0 or PL1
	888	+
633	889	Table: `SELF_TEST_GET_RESULTS` input arguments
634	890
635	891	\| Name \| Type \| Description
@@ -648,6 +904,8 @@
648	904	FIPS command to zeroize and shut down the module
649	905
650	906	Command Code: `0x4650_5344` ("FPSD")
	907	+
	908	+Privilege Level: PL0 or PL1
651	909
652	910	Table: `SHUTDOWN` input arguments
653	911
@@ -672,6 +930,8 @@
672	930
673	931	Command Code: `0x414C_544E` ("ALTN")
674	932
	933	+Privilege Level: PL0 or PL1
	934	+
675	935	Table: `ADD_SUBJECT_ALT_NAME` input arguments
676	936
677	937	\| Name \| Type \| Description
@@ -693,6 +953,8 @@
693	953
694	954	Command Code: `0x434B_4558` ("CKEX")
695	955
	956	+Privilege Level: PL0
	957	+
696	958	Table: `CERTIFY_KEY_EXTENDED` input arguments
697	959
698	960	\| Name \| Type \| Description
@@ -715,6 +977,439 @@
715	977	\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error.
716	978	\| certify\_key\_resp \| u8[2176] \| Certify Key Response.
717	979
	980	+### SET\_AUTH\_MANIFEST
	981	+
	982	+Command Code: `0x4154_4D4E` ("ATMN")
	983	+
	984	+Privilege Level: PL0
	985	+
	986	+Table: `SET_AUTH_MANIFEST` input arguments
	987	+
	988	+\| Name \| Type \| Description \|
	989	+\| ------------------------------ \| ------------------ \| --------------- \|
	990	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
	991	+\| manifest size \| u32 \| The size of the full Authentication Manifest \|
	992	+\| manifest\_marker \| u32 \| Marker needs to be 0x4154_4D4E for the preamble to be valid \|
	993	+\| preamble\_size \| u32 \| Size of the preamble \|
	994	+\| manifest\_version \| u32 \| Version of the preamble \|
	995	+\| manifest\_flags \| u32 \| Manifest flags. See `AUTH_MANIFEST_FLAGS` below. \|
	996	+\| manifest\_vendor\_ecc384\_key \| u32[24] \| Manifest Vendor ECC P-384 public key used to verify the IMC Signature. <br> X-Coordinate: Public Key X-Coordinate (48 bytes) <br> Y-Coordinate: Public Key Y-Coordinate (48 bytes) \|
	997	+\| manifest\_vendor\_lms\_key \| u32[12] \| Manifest Vendor LMS public key used to verify the IMC Signature. <br> tree_type: LMS Algorithm Type (4 bytes) <br> otstype: LMS Ots Algorithm Type (4 bytes) <br> id: (16 bytes) <br> digest: (24 bytes) <br> Note: If LMS validation is not required, this should field should be zeroed out. \|
	998	+\| manifest\_vendor\_ecc384\_sig \| u32[24] \| Manifest Vendor ECDSA P-384 signature of the Version, Flags, Vendor ECC and LMS public keys, hashed using SHA2-384. <br> R-Coordinate: Random Point (48 bytes) <br> S-Coordinate: Proof (48 bytes) \|
	999	+\| manifest\_vendor\_LMS\_sig \| u32[405] \| Vendor LMS signature of the Version, Flags, Vendor ECC and LMS public keys, hashed using SHA2-384. <br> q: Leaf of the Merkle tree where the OTS public key appears (4 bytes) <br> ots: Lmots Signature (1252 bytes) <br> tree_type: Lms Algorithm Type (4 bytes) <br> tree_path: Path through the tree from the leaf associated with the LM-OTS signature to the root. (360 bytes) <br> Note: If LMS validation is not required, this should field should be zeroed out. \|
	1000	+\| manifest\_owner\_ecc384\_key \| u32[24] \| Manifest Owner ECC P-384 public key used to verify the IMC Signature. <br> X-Coordinate: Public Key X-Coordinate (48 bytes) <br> Y-Coordinate: Public Key Y-Coordinate (48 bytes) \|
	1001	+\| manifest\_owner\_lms\_key \| u32[12] \| Manifest Owner LMS public key used to verify the IMC Signature. <br> tree_type: LMS Algorithm Type (4 bytes) <br> otstype: LMS Ots Algorithm Type (4 bytes) <br> id: (16 bytes) <br> digest: (24 bytes) <br> Note: If LMS validation is not required, this should field should be zeroed out. \|
	1002	+\| manifest\_owner\_ecc384\_sig \| u32[24] \| Owner ECDSA P-384 signature of the Owner ECC and LMS public keys, hashed using SHA2-384. <br> R-Coordinate: Random Point (48 bytes) <br> S-Coordinate: Proof (48 bytes) \|
	1003	+\| manifest\_owner\_LMS\_sig \| u32[405] \| Owner LMS signature of the Version, Flags, Owner ECC and LMS public keys, hashed using SHA2-384. <br> q: Leaf of the Merkle tree where the OTS public key appears (4 bytes) <br> ots: Lmots Signature (1252 bytes) <br> tree_type: Lms Algorithm Type (4 bytes) <br> tree_path: Path through the tree from the leaf associated with the LM-OTS signature to the root. (360 bytes) <br> Note: If LMS validation is not required, this should field should be zeroed out. \|
	1004	+\| metadata\_vendor\_ecc384\_sig \| u32[24] \| Metadata Vendor ECC384 signature over the image metadata collection using the manifest vendor ecc384 key. \|
	1005	+\| metadata\_vendor\_LMS\_sig \| u32[405] \| Metadata Vendor LMOTS-SHA192-W4 signature over the image metadata collection using the manifest vendor LMS key. \|
	1006	+\| metadata\_owner\_ecc384\_sig \| u32[24] \| Metadata Owner ECC384 signature over the image metadata collection using the manifest owner ecc384 key. \|
	1007	+\| metadata\_owner\_LMS\_sig \| u32[405] \| Metadata Owner LMOTS-SHA192-W4 signature over the image metadata collection manifest owner LMS key. \|
	1008	+\| metadata\_entry\_entry\_count \| u32 \| number of metadata entries \|
	1009	+\| metadata\_entries \| MetaData[127] \| The max number of metadata entries is 127 but less can be used \|
	1010	+
	1011	+
	1012	+
	1013	+Table: `AUTH_MANIFEST_FLAGS` input flags
	1014	+
	1015	+\| Name \| Value \|
	1016	+\| --------------------------- \| ----------- \|
	1017	+\| VENDOR_SIGNATURE_REQUIRED \| 1 << 0 \|
	1018	+
	1019	+
	1020	+Table: `AUTH_MANIFEST_METADATA_ENTRY` digest entries
	1021	+
	1022	+\| Name \| Type \| Description \|
	1023	+\| --------------- \| ---------- \| ---------------------------------- \|
	1024	+\| fw\_id \| u32 \| Id of the image \|
	1025	+\| flags \| u32 \| See `METADATA_ENTRY_FLAGS` below \|
	1026	+\| digest \| u32[48] \| Digest of the image \|
	1027	+
	1028	+
	1029	+
	1030	+Table: `METADATA_ENTRY_FLAGS` input flags
	1031	+
	1032	+\| Name \| Size (Bits) \| Description \|
	1033	+\| --------------------- \| ----------------- \| ----------------- \|
	1034	+\| image\_source \| 2 \| 1: InRequest \|
	1035	+\| ignore\_auth\_check \| 1 \| If set, the image digest is not compared for the firmware id \|
	1036	+
	1037	+
	1038	+Table: `SET_AUTH_MANIFEST` output arguments
	1039	+
	1040	+\| Name \| Type \| Description \|
	1041	+\| -------- \| -------- \| --------------- \|
	1042	+\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
	1043	+\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error. \|
	1044	+
	1045	+
	1046	+
	1047	+### AUTHORIZE_AND_STASH
	1048	+
	1049	+Command Code: `0x4154_5348` ("ATSH")
	1050	+
	1051	+Privilege Level: PL0 or PL1; stashing the measurement requires PL0, so a PL1 caller must set the `SKIP_STASH` flag
	1052	+
	1053	+Table: `AUTHORIZE_AND_STASH` input arguments
	1054	+
	1055	+\| Name \| Type \| Description \|
	1056	+\| ------------ \| -------- \| --------------- \|
	1057	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
	1058	+\| fw_id \| u8[4] \| Firmware id of the image, in little-endian format \|
	1059	+\| measurement \| u8[48] \| Digest of the image requested for authorization \|
	1060	+\| context \| u8[48] \| Context field for `svn`; e.g., a hash of the public key that authenticated the SVN. \|
	1061	+\| svn \| u32 \| SVN \|
	1062	+\| flags \| u32 \| See AUTHORIZE_AND_STASH_FLAGS below \|
	1063	+\| source \| u32 \| Enumeration values: { InRequest(1) } \|
	1064	+
	1065	+
	1066	+Table: `AUTHORIZE_AND_STASH_FLAGS` input flags
	1067	+
	1068	+\| Name \| Value \|
	1069	+\| ------------ \| ------------ \|
	1070	+\| SKIP\_STASH \| 1 << 0 \|
	1071	+
	1072	+
	1073	+Table: `AUTHORIZE_AND_STASH` output arguments
	1074	+\| Name \| Type \| Description
	1075	+\| ----------------\| -------- \| ---------------
	1076	+\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
	1077	+\| fips_status \| u32 \| Indicates if the command is FIPS approved or an error. \|
	1078	+\| auth_req_result \| u32 \| AUTHORIZE_IMAGE (0xDEADC0DE), IMAGE_NOT_AUTHORIZED (0x21523F21) or IMAGE_HASH_MISMATCH (0x8BFB95CB) \|
	1079	+
	1080	+
	1081	+### GET\_IDEVID\_CSR
	1082	+
	1083	+Command Code: `0x4944_4352` ("IDCR")
	1084	+
	1085	+Privilege Level: PL0 or PL1
	1086	+
	1087	+Table: `GET_IDEVID_CSR` input arguments
	1088	+
	1089	+\| Name \| Type \| Description
	1090	+\| -------- \| -------- \| ---------------
	1091	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
	1092	+
	1093	+
	1094	+Table: `GET_IDEVID_CSR` output arguments
	1095	+\| Name \| Type \| Description
	1096	+\| -------- \| -------- \| ---------------
	1097	+\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
	1098	+\| data\_size \| u32 \| Length in bytes of the valid data in the data field. \|
	1099	+\| data \| u8[...] \| DER-encoded IDevID certificate signing request. \|
	1100	+
	1101	+
	1102	+The `mfg_flag_gen_idev_id_csr` manufacturing flag MUST have been set to generate a CSR.
	1103	+
	1104	+When called from ROM, if the CSR was not previously provisioned this command will return `FW_PROC_MAILBOX_UNPROVISIONED_CSR(0x0102000A)`.
	1105	+
	1106	+When called from runtime, if the CSR was not previously provisioned this command will return `RUNTIME_GET_IDEV_ID_UNPROVISIONED(0x000E0051)`. If the ROM did not support CSR generation, this command will return `RUNTIME_GET_IDEV_ID_UNSUPPORTED_ROM(0x000E0052)`.
	1107	+
	1108	+
	1109	+
	1110	+When the `mfg_flag_gen_idev_id_csr` flag has been set, the SoC MUST wait for the `flow_status_set_idevid_csr_ready` bit to be set by Caliptra. Once set, the SoC MUST clear the `mfg_flag_gen_idev_id_csr` flag for Caliptra to progress.
	1111	+
	1112	+### GET\_FMC\_ALIAS\_CSR
	1113	+
	1114	+Command Code: `0x464D_4352` ("FMCR")
	1115	+
	1116	+Privilege Level: PL0 or PL1
	1117	+
	1118	+Table: `GET_FMC_ALIAS_CSR` input arguments
	1119	+
	1120	+\| Name \| Type \| Description
	1121	+\| -------- \| -------- \| ---------------
	1122	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
	1123	+
	1124	+
	1125	+Table: `GET_FMC_ALIAS_CSR` output arguments
	1126	+\| Name \| Type \| Description
	1127	+\| -------- \| -------- \| ---------------
	1128	+\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
	1129	+\| data\_size \| u32 \| Length in bytes of the valid data in the data field. \|
	1130	+\| data \| u8[...] \| DER-encoded FMC ALIAS certificate signing request. \|
	1131	+
	1132	+
	1133	+The FMC Alias CSR is generated unconditionally on every cold boot.
	1134	+
	1135	+### SIGN\_WITH\_EXPORTED\_ECDSA
	1136	+
	1137	+Command Code: `0x5357_4545` ("SWEE")
	1138	+
	1139	+Privilege Level: PL0
	1140	+
	1141	+Table: `SIGN_WITH_EXPORTED_ECDSA` input arguments
	1142	+
	1143	+\| Name \| Type \| Description
	1144	+\| -------- \| -------- \| ---------------
	1145	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
	1146	+\| exported_cdi_handle \| u8[32] \| The Exported CDI handle returned by the DPE `DeriveContext` command. Little endian. \|
	1147	+\| tbs \| u8[48] \| The bytes to be signed. Little endian. \|
	1148	+
	1149	+
	1150	+Table: `SIGN_WITH_EXPORTED_ECDSA` output arguments
	1151	+\| Name \| Type \| Description
	1152	+\| -------- \| -------- \| ---------------
	1153	+\| derived_pubkey_x \| u8[48] \| The X BigNum of the ECDSA public key associated with the signing key. \|
	1154	+\| derived_pubkey_y \| u8[48] \| The Y BigNum of the ECDSA public key associated with the signing key. \|
	1155	+\| signature_r \| u8[48] \| The R BigNum of an ECDSA signature. \|
	1156	+\| signature_s \| u8[48] \| The S BigNum of an ECDSA signature. \|
	1157	+
	1158	+
	1159	+The `exported_cdi_handle` can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
	1160	+
	1161	+### REVOKE\_EXPORTED\_CDI\_HANDLE
	1162	+
	1163	+Command Code: `5256_4348` ("RVCH")
	1164	+
	1165	+Privilege Level: PL0
	1166	+
	1167	+Table: `REVOKE_EXPORTED_CDI_HANDLE` input arguments
	1168	+
	1169	+\| Name \| Type \| Description
	1170	+\| -------- \| -------- \| ---------------
	1171	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
	1172	+\| exported_cdi_handle \| u8[32] \| The Exported CDI handle returned by the DPE `DeriveContext` command. Little endian. \|
	1173	+
	1174	+
	1175	+The `exported_cdi_handle` can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
	1176	+
	1177	+The `exported_cdi_handle` is no longer usable after calling `REVOKE_EXPORTED_CDI_HANDLE` with it. After the `exported_cdi_handle`
	1178	+has been revoked, a new exported CDI handle can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
	1179	+
	1180	+### REALLOCATE\_DPE\_CONTEXT\_LIMITS
	1181	+
	1182	+Command Code: '5243_5458` ("RCTX")
	1183	+
	1184	+Privilege Level: PL0
	1185	+
	1186	+Table: `REALLOCATE_DPE_CONTEXT_LIMITS` input arguments
	1187	+
	1188	+\| Name \| Type \| Description
	1189	+\| -------- \| -------- \| ---------------
	1190	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian. \|
	1191	+\| pl0_context_limit \| u32 \| Number of contexts to allocate to PL0. PL1 will receive remaining contexts. \|
	1192	+
	1193	+
	1194	+Table: `REALLOCATE_DPE_CONTEXT_LIMITS` output arguments
	1195	+\| Name \| Type \| Description
	1196	+\| -------- \| -------- \| ---------------
	1197	+\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian. \|
	1198	+\| fips_status \| u32 \| Indicates if the command is FIPS approved or an error. \|
	1199	+\| new_pl0_context_limit \| u32 \| Number of contexts assigned to PL0 after the reallocation \|
	1200	+\| new_pl1_context_limit \| u32 \| Number of contexts assigned to PL1 after the reallocation \|
	1201	+
	1202	+
	1203	+This allows the user to reallocate the 32 DPE contexts between PL0 and PL1. By default, each gets 16 contexts.
	1204	+
	1205	+Note: 2 PL0 contexts are used by Caliptra itself during initialization.
	1206	+
	1207	+## PQC (ML-DSA-87) commands
	1208	+
	1209	+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.
	1210	+The availability of these commands is advertised to the SoC via the `RT_MLDSA_ATTESTATION` bit in the [`CAPABILITIES`](#capabilities) output.
	1211	+
	1212	+### SET\_PQ\_SEED
	1213	+
	1214	+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.
	1215	+
	1216	+Command Code: `0x5051_5344` ("PQSD")
	1217	+
	1218	+Privilege Level: PL0
	1219	+
	1220	+Table: `SET_PQ_SEED` input arguments
	1221	+
	1222	+\| Name \| Type \| Description
	1223	+\| -------- \| --------- \| ---------------
	1224	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian.
	1225	+\| seed \| u8[48] \| `PQ.DevID.Seed`. Per-device unique symmetric seed, provided by the SoC.
	1226	+
	1227	+Table: `SET_PQ_SEED` output arguments
	1228	+
	1229	+\| Name \| Type \| Description
	1230	+\| -------- \| -------- \| ---------------
	1231	+\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian.
	1232	+\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error.
	1233	+
	1234	+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.
	1235	+The production `PQ.DevID.Seed` must never be delivered while Caliptra is `DebugUnlocked`.
	1236	+Integrators may still call `SET_PQ_SEED` with a non-production seed while `DebugUnlocked` for local bring-up and debug.
	1237	+
	1238	+### GET\_PQ\_CSR
	1239	+
	1240	+Returns a CSR for the `PQ.DevID` ML-DSA-87 public key, for collection during manufacturing/provisioning, mirroring [`GET_IDEVID_CSR`](#get_idevid_csr).
	1241	+
	1242	+Command Code: `0x5051_4353` ("PQCS")
	1243	+
	1244	+Privilege Level: PL0 or PL1
	1245	+
	1246	+Table: `GET_PQ_CSR` input arguments
	1247	+
	1248	+\| Name \| Type \| Description
	1249	+\| -------- \| -------- \| ---------------
	1250	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian.
	1251	+
	1252	+Table: `GET_PQ_CSR` output arguments
	1253	+
	1254	+\| Name \| Type \| Description
	1255	+\| -------- \| --------- \| ---------------
	1256	+\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian.
	1257	+\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error.
	1258	+\| data\_size \| u32 \| Length in bytes of the valid data in the data field, with a maximum of 12800.
	1259	+\| data \| u8[12800] \| DER-encoded ML-DSA-87 `PQ.DevID` certificate signing request.
	1260	+
	1261	+### GET\_PQ\_INFO
	1262	+
	1263	+Returns the raw ML-DSA-87 `PQ.DevID` public key.
	1264	+
	1265	+Command Code: `0x5051_494E` ("PQIN")
	1266	+
	1267	+Privilege Level: PL0 or PL1
	1268	+
	1269	+Table: `GET_PQ_INFO` input arguments
	1270	+
	1271	+\| Name \| Type \| Description
	1272	+\| -------- \| -------- \| ---------------
	1273	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian.
	1274	+
	1275	+Table: `GET_PQ_INFO` output arguments
	1276	+
	1277	+\| Name \| Type \| Description
	1278	+\| -------- \| --------- \| ---------------
	1279	+\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian.
	1280	+\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error.
	1281	+\| pq\_pub\_key \| u8[2592] \| Encoded ML-DSA-87 `PQ.DevID` public key (FIPS 204).
	1282	+
	1283	+### POPULATE\_PQ\_CERT
	1284	+
	1285	+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).
	1286	+
	1287	+Command Code: `0x5050_5143` ("PPQC")
	1288	+
	1289	+Privilege Level: PL0
	1290	+
	1291	+Table: `POPULATE_PQ_CERT` input arguments
	1292	+
	1293	+\| Name \| Type \| Description
	1294	+\| -------- \| -------- \| ---------------
	1295	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian.
	1296	+\| cert\_size \| u32 \| Size of the DER-encoded `PQ.DevID` certificate, with a maximum of 8192.
	1297	+\| cert \| u8[8192] \| DER-encoded `PQ.DevID` certificate.
	1298	+
	1299	+Table: `POPULATE_PQ_CERT` output arguments
	1300	+
	1301	+\| Name \| Type \| Description
	1302	+\| -------- \| -------- \| ---------------
	1303	+\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian.
	1304	+\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error.
	1305	+
	1306	+### GET\_PQ\_CERT
	1307	+
	1308	+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).
	1309	+
	1310	+Command Code: `0x4750_5143` ("GPQC")
	1311	+
	1312	+Privilege Level: PL0 or PL1
	1313	+
	1314	+Table: `GET_PQ_CERT` input arguments
	1315	+
	1316	+\| Name \| Type \| Description
	1317	+\| -------- \| -------- \| ---------------
	1318	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian.
	1319	+\| tbs\_size \| u32 \| Size of the TBS, with a maximum of 3543.
	1320	+\| 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`.
	1321	+\| tbs \| u8[3543] \| TBS. Only bytes up to tbs_size are used.
	1322	+
	1323	+Table: `GET_PQ_CERT` output arguments
	1324	+
	1325	+\| Name \| Type \| Description
	1326	+\| -------- \| -------- \| ---------------
	1327	+\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian.
	1328	+\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error.
	1329	+\| cert\_size \| u32 \| Length in bytes of the valid data in the cert field, with a maximum of 8192.
	1330	+\| cert \| u8[8192] \| DER-encoded `PQ.DevID` certificate.
	1331	+
	1332	+### INVOKE\_DPE\_MLDSA87
	1333	+
	1334	+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.
	1335	+
	1336	+Command Code: `0x4D4C_4450` ("MLDP")
	1337	+
	1338	+Privilege Level: PL0 or PL1; a subset of DPE commands requires PL0 (see [Mailbox command privilege levels](#mailbox-command-privilege-levels))
	1339	+
	1340	+Table: `INVOKE_DPE_MLDSA87` input arguments
	1341	+
	1342	+\| Name \| Type \| Description
	1343	+\| -------- \| -------- \| ---------------
	1344	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian.
	1345	+\| data\_size \| u32 \| Length in bytes of the valid data in the data field.
	1346	+\| data \| u8[512] \| Encoded DPE command. Only bytes up to data_size are used.
	1347	+
	1348	+Table: `INVOKE_DPE_MLDSA87` output arguments
	1349	+
	1350	+\| Name \| Type \| Description
	1351	+\| -------- \| ----------- \| ---------------
	1352	+\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian.
	1353	+\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error.
	1354	+\| data\_size \| u32 \| Length in bytes of the valid data in the data field.
	1355	+\| data \| u8[25168] \| Encoded DPE response. Only bytes up to data_size are used.
	1356	+
	1357	+### CERTIFY\_KEY\_EXTENDED\_MLDSA87
	1358	+
	1359	+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.
	1360	+
	1361	+Command Code: `0x434B_454D` ("CKEM")
	1362	+
	1363	+Privilege Level: PL0
	1364	+
	1365	+Table: `CERTIFY_KEY_EXTENDED_MLDSA87` input arguments
	1366	+
	1367	+\| Name \| Type \| Description
	1368	+\| -------- \| -------- \| ---------------
	1369	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian.
	1370	+\| flags \| u32 \| Flags determining which custom extensions to include in the certificate. See [`CERTIFY_KEY_EXTENDED` input flags](#certify_key_extended).
	1371	+\| certify\_key\_req \| u8[72] \| Certify Key Request.
	1372	+
	1373	+Table: `CERTIFY_KEY_EXTENDED_MLDSA87` output arguments
	1374	+
	1375	+\| Name \| Type \| Description
	1376	+\| -------- \| -------- \| ---------------
	1377	+\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian.
	1378	+\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error.
	1379	+\| size \| u32 \| Length in bytes of the valid data in the certify_key_resp field.
	1380	+\| certify\_key\_resp \| u8[25152] \| Certify Key Response.
	1381	+
	1382	+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).
	1383	+
	1384	+### SIGN\_WITH\_EXPORTED\_MLDSA
	1385	+
	1386	+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.
	1387	+
	1388	+Command Code: `0x5357_4D4C` ("SWML")
	1389	+
	1390	+Privilege Level: PL0
	1391	+
	1392	+Table: `SIGN_WITH_EXPORTED_MLDSA` input arguments
	1393	+
	1394	+\| Name \| Type \| Description
	1395	+\| -------- \| -------- \| ---------------
	1396	+\| chksum \| u32 \| Checksum over other input arguments, computed by the caller. Little endian.
	1397	+\| exported\_cdi\_handle \| u8[32] \| The Exported CDI handle returned by the DPE `DeriveContext` command.
	1398	+\| 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`.
	1399	+\| message\_size \| u32 \| Length in bytes of the valid data in the message field.
	1400	+\| message \| u8[1024] \| Raw message (`SIGN_MODE_DATA`) or external `mu` (`SIGN_MODE_EXTERNAL_MU`). Only bytes up to message_size are used.
	1401	+
	1402	+Table: `SIGN_WITH_EXPORTED_MLDSA` output arguments
	1403	+
	1404	+\| Name \| Type \| Description
	1405	+\| -------- \| --------- \| ---------------
	1406	+\| chksum \| u32 \| Checksum over other output arguments, computed by Caliptra. Little endian.
	1407	+\| fips\_status \| u32 \| Indicates if the command is FIPS approved or an error.
	1408	+\| derived\_pubkey \| u8[2592] \| The ML-DSA-87 public key associated with the signing key.
	1409	+\| signature \| u8[4627] \| The ML-DSA-87 signature.
	1410	+
	1411	+The `exported_cdi_handle` can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags, as with `SIGN_WITH_EXPORTED_ECDSA`.
	1412	+
718	1413	## Checksum
719	1414
720	1415	For every command except for FW_LOAD, the request and response feature a checksum. This
@@ -780,10 +1475,10 @@
780	1475
781	1476	1. Validate DPE state in SRAM
782	1477	1. Ensure the TCI tree is well-formed
783		- 1. Ensure all nodes chain to the root (TYPE = RTJM, “Internal TCI” flag is set)
	1478	+ 1. Ensure all nodes chain to the root (TYPE = RTMR, “Internal TCI” flag is set)
784	1479	1. Verify that the “Latest TCI” field of the TCI Node that contains the
785		- Runtime Journey PCR (TYPE = RTJM, “Internal TCI” flag is set) matches the
786		- “Latest” Runtime PCR value from PCRX
	1480	+ Runtime PCRs (TYPE = RTMR, “Internal TCI” flag is set) matches the
	1481	+ “Latest” and Journey Runtime PCR values.
787	1482	1. Ensure `SHA384_HASH(0x00..00, TCI from SRAM) == RT_FW_JOURNEY_PCR`
788	1483	1. Check that retired and inactive contexts do not have tags
789	1484	1. If any validations fail, Runtime Firmware executes the
@@ -802,8 +1497,9 @@
802	1497	* PL0 - High privilege. Only 1 PAUSER in the SoC may be at PL0. The PL0 PAUSER
803	1498	is denoted in the signed Caliptra firmware image. The PL0 PAUSER may call any
804	1499	supported DPE commands. Only PL0 can use the CertifyKey command. Success of the
805		- CertifyKey command signifies to the caller that it is at PL0. Only PL0 can use
806		- the POPULATE\_IDEV\_CERT mailbox command.
	1500	+ CertifyKey command signifies to the caller that it is at PL0. A number of
	1501	+ mailbox commands are also restricted to PL0; see
	1502	+ [Mailbox command privilege levels](#mailbox-command-privilege-levels).
807	1503	* PL1 - Restricted privilege. All other PAUSERs in the SoC are PL1. Caliptra
808	1504	SHALL fail any calls to the DPE CertifyKey with format=X509 by PL1 callers.
809	1505	PL1 callers should use the CSR format instead.
@@ -832,26 +1528,27 @@
832	1528
833	1529	At boot Caliptra Runtime FW consumes part of the PL0 active contexts (initially 16) to DeriveContext for:
834	1530	- RTFW Journey (RTFJ) Measurement (1)
835		- - Mailbox Valid Pauser digest (MBVP) (1)
	1531	+ - Caliptra Configured Initialization Values digest (CCIV) (1)
836	1532	- ROM Stashed Measurements (max 8)
837	1533
838	1534	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
839	1535	of active contexts in PL0's locality, and hence allow PL1 to DOS PL0.
840	1536
841		-### DPE profile implementation
842		-
843		-The DPE iRoT profile leaves some choices up to implementers. This section
844		-describes specific requirements for the Caliptra DPE implementation.
845		-
846		-\| Name \| Value \| Description
847		-\| ---- \| ----- \| -----------
848		-\| Profile Variant \| `DPE_PROFILE_IROT_P384_SHA384` \| The profile variant that Caliptra implements.
849		-\| KDF \| SP800-108 HMAC-CTR \| KDF to use for CDI (tcg.derive.kdf-sha384) and asymmetric key (tcg.derive.kdf-sha384-p384) derivation.
850		-\| Simulation Context Support \| Yes \| Whether Caliptra implements the optional Simulation Contexts feature.
851		-\| Supports ExtendTci \| Yes \| Whether Caliptra implements the optional ExtendTci command.
852		-\| Supports Auto Init \| Yes \| Whether Caliptra will automatically initialize the default DPE context.
853		-\| Supports Rotate Context \| Yes \| Whether Caliptra supports the optional RotateContextHandle command.
854		-\| CertifyKey Alias Key \| Caliptra Runtime Alias Key \| The key that will be used to sign certificates that are produced by the DPE CertifyKey command.
	1537	+### Caliptra DPE Profile
	1538	+
	1539	+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.
	1540	+
	1541	+\| Name \| Value \| Description \|
	1542	+\| -------------------------- \| ------------------------------ \| ------------------------------------------------------------------------------------------------------ \|
	1543	+\| Profile Variant \| `Caliptra DPE Profile` \| Derived from `DPE_PROFILE_IROT_P384_SHA384`. \|
	1544	+\| KDF \| SP800-108 HMAC-CTR \| KDF to use for CDI (tcg.derive.kdf-sha384) and asymmetric key (tcg.derive.kdf-sha384-p384) derivation. \|
	1545	+\| Simulation Context Support \| Yes \| Whether Caliptra implements the optional Simulation Contexts feature. \|
	1546	+\| Supports ExtendTci \| Yes \| Whether Caliptra implements the optional ExtendTci command. \|
	1547	+\| Supports Auto Init \| Yes \| Whether Caliptra will automatically initialize the default DPE context. \|
	1548	+\| Supports Rotate Context \| Yes \| Whether Caliptra supports the optional RotateContextHandle command. \|
	1549	+\| CertifyKey Alias Key \| Caliptra Runtime Alias Key \| The key that will be used to sign certificates that are produced by the DPE CertifyKey command. \|
	1550	+\| `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. \|
	1551	+
855	1552
856	1553	### Supported DPE commands
857	1554
@@ -860,6 +1557,8 @@
860	1557	* GetProfile
861	1558	* InitializeContext
862	1559	* DeriveContext
	1560	+ * 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.
	1561	+ * Note: The "export-cdi" flag is only available in the locality of the PL0 PAUSER.
863	1562	* CertifyKey
864	1563	* Caliptra DPE supports two formats for CertifyKey: X.509 and PKCS#10 CSR.
865	1564	X.509 is only available to PL0 PAUSERs.
@@ -884,14 +1583,21 @@
884	1583
885	1584	* Runtime Firmware SHALL initialize the default context in “internal-cdi” mode.
886	1585	* Perform the following initial measurements:
887		- * Call DeriveContext with Caliptra Journey PCR
	1586	+ * Call DeriveContext with Caliptra RT PCRs
888	1587	* INPUT\_DATA = PCRX (RT journey PCR as defined in the FHT)
889		- * TYPE = “RTJM”
	1588	+ * TYPE = “RTMR”
890	1589	* CONTEXT\_HANDLE = default context
891	1590	* TARGET\_LOCALITY = Caliptra locality (0xFFFFFFFF)
892		- * Call DeriveContext with mailbox valid PAUSERS
893		- * INPUT\_DATA = Hash of [CPTRA\_VALID\_PAUSER register](https://chipsalliance.github.io/caliptra-rtl/main/internal-regs/?p=clp.soc_ifc_reg.CPTRA_MBOX_VALID_PAUSER%5B0%5D).
894		- * TYPE = “MBVP”
	1591	+ * Call DeriveContext with hash of initialization values below
	1592	+ * INPUT\_DATA = Hash of:
	1593	+ * [CPTRA\_VALID\_PAUSER register](https://chipsalliance.github.io/caliptra-rtl/main/internal-regs/?p=clp.soc_ifc_reg.CPTRA_MBOX_VALID_PAUSER%5B0%5D)
	1594	+ * PL0 PAUSER locality
	1595	+ * Flags from FW image manifest header
	1596	+ * FMC load address
	1597	+ * FMC entry point
	1598	+ * Runtime load address
	1599	+ * Runtime entry point
	1600	+ * TYPE = "CCIV"
895	1601	* CONTEXT\_HANDLE = default context
896	1602	* TARGET\_LOCALITY = PL0 PAUSER
897	1603	* Call DeriveContext for each STASH\_MEASUREMENT call made during Caliptra ROM execution
@@ -951,29 +1657,29 @@
951	1657
952	1658	### DPE leaf certificate definition
953	1659
954		-\| Field \| Sub field \| Value
955		-\| ------------- \| --------- \| ---------
956		-\| Version \| v3 \| 2
957		-\| Serial Number \| \| First 20 bytes of sha256 hash of DPE Alias public key
958		-\| Issuer Name \| CN \| Caliptra Runtime Alias
959		-\| \| serialNumber \| First 20 bytes of sha384 hash of Runtime Alias public key
960		-\| Validity \| notBefore \| notBefore from firmware manifest
961		-\| \| notAfter \| notAfter from firmware manifest
962		-\| Subject Name \| CN \| Caliptra DPE Leaf
963		-\| \| serialNumber \| SHA384 hash of Subject public key
964		-\| Subject Public Key Info \| Algorithm \| ecdsa-with-SHA384
965		-\| \| Parameters \| Named Curve = prime384v1
966		-\| \| Public Key \| DPE Alias Public Key value
967		-\| Signature Algorithm Identifier \| Algorithm \| ecdsa-with-SHA384
968		-\| \| Parameters \| Named Curve = prime384v1
969		-\| Signature Value \| \| Digital signature for the certificate
970		-\| KeyUsage \| keyCertSign \| 1
971		-\| Basic Constraints \| CA \| False
972		-\| Policy OIDs \| \| id-tcg-kp-attestLoc
973		-\| tcg-dice-MultiTcbInfo\* \| FWIDs \| [0] "Journey" TCI Value
974		-\| \| \| [1] "Current" TCI Value. Latest `INPUT_DATA` made by DeriveContext.
975		-\| \| Type \| 4-byte TYPE field of TCI node
976		-\| \| VendorInfo \| Locality of the caller (analog for PAUSER)
	1660	+\| Field \| Sub field \| Value
	1661	+\| ------------- \| --------- \| ---------
	1662	+\| Version \| v3 \| 2
	1663	+\| Serial Number \| \| First 20 bytes of sha256 hash of DPE Alias public key
	1664	+\| Issuer Name \| CN \| Caliptra Runtime Alias
	1665	+\| \| serialNumber \| First 20 bytes of sha384 hash of Runtime Alias public key
	1666	+\| Validity \| notBefore \| notBefore from firmware manifest
	1667	+\| \| notAfter \| notAfter from firmware manifest
	1668	+\| Subject Name \| CN \| Caliptra DPE Leaf
	1669	+\| \| serialNumber \| SHA384 hash of Subject public key
	1670	+\| Subject Public Key Info \| Algorithm \| ecdsa-with-SHA384
	1671	+\| \| Parameters \| Named Curve = prime384v1
	1672	+\| \| Public Key \| DPE Alias Public Key value
	1673	+\| Signature Algorithm Identifier \| Algorithm \| ecdsa-with-SHA384
	1674	+\| \| Parameters \| Named Curve = prime384v1
	1675	+\| Signature Value \| \| Digital signature for the certificate
	1676	+\| KeyUsage \| keyCertSign \| 1
	1677	+\| Basic Constraints \| CA \| False
	1678	+\| Policy OIDs \| \| id-tcg-kp-attestLoc
	1679	+\| tcg-dice-MultiTcbInfo\* \| FWIDs \| [0] "Current" TCI Value. Latest `INPUT_DATA` made by DeriveContext
	1680	+\| \| IntegrityRegisters \| [0] "Journey" TCI Value.
	1681	+\| \| Type \| 4-byte TYPE field of TCI node
	1682	+\| \| VendorInfo \| Locality of the caller (analog for PAUSER)
977	1683
978	1684	\*MultiTcbInfo contains one TcbInfo for each TCI Node in the path from the
979	1685	current TCI Node to the root. Max of 32.

Changes to Runtime Specification