Changes to Runtime Specification

Comparing version 2.1 to 2.0
+88 additions -24 deletions
@@ -1,8 +1,8 @@
11 <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/e56467181b5313e53cf6cdc92f705a4127480fc2/runtime/README.md" target="_blank">chipsalliance/caliptra-sw/runtime/README.md</a> @ <code>e564671</code>
2+đź“„ Source: <a href="https://github.com/chipsalliance/caliptra-sw/blob/9248d7956e8f6c9514eff3136fa532392d9ac5c1/runtime/README.md" target="_blank">chipsalliance/caliptra-sw/runtime/README.md</a> @ <code>9248d79</code>
33 </div>
44
5-# Caliptra Runtime Firmware v2.0.1
5+# Caliptra Runtime Firmware v2.0
66
77 *Spec version: 0.3*
88
@@ -24,6 +24,10 @@
2424 * [MCU Runtime loading](#boot-and-initialization) (subsystem mode)
2525 * [Cryptographic mailbox commands](#cryptographic-mailbox-commands-new-in-20)
2626 * `ECDSA384_SIGNATURE_VERIFY` and `LMS_SIGNATURE_VERIFY`require the hash to be included in the message, as the SHA accelerator registers are no longer accessible outside Caliptra.
27+
28+v2.1:
29+
30+* [External mailbox commands](#external-mailbox-cmd)
2731
2832 ## Spec Opens
2933
@@ -126,8 +130,7 @@
126130
127131 | **Name** | **Bits** | **Description** |
128132 | ------------- | -------- | -------------------------------------- |
129-| version | 8 | CMK version. Currently always 1. |
130-| flags | 8 | Bit 0 = FIPS valid |
133+| version | 16 | CMK version. Currently always 1. |
131134 | length | 16 | how many bits of key material are used |
132135 | key usage | 8 | represents which kind of key this is |
133136 | id | 24 | ID number |
@@ -367,7 +370,14 @@
367370 | -------- | -------- | ---------------
368371 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian.
369372 | fips\_status | u32 | Indicates if the command is FIPS approved or an error.
370-| capabilities | u8[16] | Firmware capabilities
373+| capabilities | u8[16] | Firmware capabilities. See table below for details.
374+
375+*Table: Firmware Capabilities Flags*
376+
377+| **Name** | **Bit** | **Description**
378+| --------------- | ------- | ---------------
379+| `RT_BASE` | 64 | Base capabilities for Caliptra Runtime v2.1.
380+| `RT_OCP_LOCK` | 65 | Runtime firmware and hardware supports OCP LOCK.
371381
372382 ### GET\_IDEV\_ECC384\_CERT
373383
@@ -811,13 +821,13 @@
811821 | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian.
812822 | fips\_status | u32 | Indicates if the command is FIPS approved or an error.
813823
814-### INVOKE\_DPE\_COMMAND
815-
816-Invokes a serialized DPE command.
824+### INVOKE\_DPE\_ECC384
825+
826+Invokes a serialized EC-P384 DPE profile command.
817827
818828 Command Code: `0x4450_4543` ("DPEC")
819829
820-*Table: `INVOKE_DPE_COMMAND` input arguments*
830+*Table: `INVOKE_DPE_ECC384` input arguments*
821831
822832 | **Name** | **Type** | **Description**
823833 | -------- | -------- | ---------------
@@ -825,7 +835,30 @@
825835 | data\_size | u32 | Length in bytes of the valid data in the data field.
826836 | data | u8[...] | DPE command structure as defined in the DPE iRoT profile.
827837
828-*Table: `INVOKE_DPE_COMMAND` output arguments*
838+*Table: `INVOKE_DPE_ECC384` output arguments*
839+
840+| **Name** | **Type** | **Description**
841+| -------- | -------- | ---------------
842+| chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian.
843+| fips\_status | u32 | Indicates if the command is FIPS approved or an error.
844+| data\_size | u32 | Length in bytes of the valid data in the data field.
845+| data | u8[...] | DPE response structure as defined in the DPE iRoT profile.
846+
847+### INVOKE\_DPE\_MLDSA87
848+
849+Invokes a serialized ML-DSA-87 DPE profile command.
850+
851+Command Code: `0x4450_4543` ("DPEC")
852+
853+*Table: `INVOKE_DPE_MLDSA87` input arguments*
854+
855+| **Name** | **Type** | **Description**
856+| -------- | -------- | ---------------
857+| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian.
858+| data\_size | u32 | Length in bytes of the valid data in the data field.
859+| data | u8[...] | DPE command structure as defined in the DPE iRoT profile.
860+
861+*Table: `INVOKE_DPE_MLDSA87` output arguments*
829862
830863 | **Name** | **Type** | **Description**
831864 | -------- | -------- | ---------------
@@ -1335,6 +1368,15 @@
13351368 | fips_status | u32 | Indicates if the command is FIPS approved or an error. |
13361369
13371370
1371+## Mailbox commands: OCP LOCK v1.0
1372+
1373+These commands are defined in the OCP LOCK v1.0 [specification](https://github.com/chipsalliance/Caliptra/blob/main/doc/ocp_lock/releases/OCP_LOCK_Specification_v1.0_RC2.pdf).
1374+
1375+### ENUMERATE_HPKE_HANDLES
1376+### REPORT_HEK_METADATA
1377+### GET_ALGORITHMS
1378+### INITIALIZE_MEK_SECRET
1379+
13381380 ## Mailbox commands: Cryptographic Mailbox (2.0)
13391381
13401382 These commands are used by the [Cryptograhic Mailbox](#cryptographic-mailbox-commands-new-in-20) system.
@@ -1773,8 +1815,7 @@
17731815 | mode | u32 ||
17741816 | key | u8[32] ||
17751817 | iv | u8[16] ||
1776-| fips_status | u8 | 1 = FIPS valid |
1777-| reserved | u8[75] | Reserved for additional fields |
1818+| reserved | u8[76] | Reserved for additional fields |
17781819
17791820
17801821 The size of the (encrypted) context is always exactly 156 bytes,
@@ -1923,8 +1964,7 @@
19231964 | GHASH state | u8[16] ||
19241965 | current length | u32 | value mod 16 is buffer size |
19251966 | buffer | u8[16] ||
1926-| fips_status | u8 | 1 = FIPS valid |
1927-| reserved | u8[15] ||
1967+| reserved | u8[16] ||
19281968
19291969
19301970 The size of the (encrypted) context is always exactly 128 bytes,
@@ -2324,8 +2364,6 @@
23242364 If a key usage other than HMAC is desired, then the KDF or HKDF
23252365 mailbox functions can be used to derive a key from the returned CMK.
23262366
2327-Note that in Caliptra 2.0 in subsystem mode, derived stable keys, their derivatives, and commands using them will be marked with a FIPS status of invalid since the UDS and FE cannot be completely zeroized.
2328-
23292367 Command Code: `0x434D_4453` ("CMDS")
23302368
23312369 *Table: `CM_DERIVE_STABLE_KEY` input arguments*
@@ -2349,9 +2387,6 @@
23492387 Imports the specified key and returns a CMK for it.
23502388
23512389 Usage information is required so that the key can be verified and used appropriately.
2352-
2353-Note that it is the caller's responsibility to ensure that the source
2354-key material meets FIPS requirements, such as zeroization.
23552390
23562391 Command Code: `0x434D_494D` ("CMIM")
23572392
@@ -2559,6 +2594,35 @@
25592594 The `exported_cdi_handle` is no longer usable after calling `REVOKE_EXPORTED_CDI_HANDLE` with it. After the `exported_cdi_handle`
25602595 has been revoked, a new exported CDI can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
25612596
2597+### EXTERNAL_MAILBOX_CMD
2598+
2599+Command Code: `0x4558_544D` ("EXTM")
2600+
2601+**Note**: This command is only available in subsystem mode in 2.1+.
2602+
2603+Executes a mailbox command located at an AXI address.
2604+This allows for executing mailbox commands that are larger than the mailbox allows.
2605+
2606+This is currently mostly useful for FIRMWARE_LOAD (as part of an update) or SET_AUTH_MANIFEST.
2607+
2608+The response is still written to the mailbox.
2609+
2610+The checksum is over the EXTM command, *not* the command that is loaded over AXI.
2611+That external command will still need its own checksum, if applicable.
2612+
2613+*Table: `EXTERNAL_MAILBOX_CMD` input arguments*
2614+
2615+| **Name** | **Type** | **Description**
2616+| -------- | -------- | ---------------
2617+| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
2618+| command_id | u32 | Command ID for the mailbox command to be executed. Little endian. |
2619+| command_size | u32 | Size of the mailbox command to be executed. Little endian. |
2620+| axi_address_low | u32 | Lower 32 bits of the AXI address that contains the mailbox command. Little endian. |
2621+| axi_address_high | u32 | High 32 bits of the AXI address that contains the mailbox command. Little endian. |
2622+
2623+
2624+The response will be the response of the executed external command.
2625+
25622626 ### REALLOCATE\_DPE\_CONTEXT\_LIMITS
25632627
25642628 Command Code: '5243_5458` ("RCTX")
@@ -2652,10 +2716,10 @@
26522716
26532717 1. Validate DPE state in SRAM
26542718 1. Ensure the TCI tree is well-formed
2655- 1. Ensure all nodes chain to the root (TYPE = RTJM, “Internal TCI” flag is set)
2719+ 1. Ensure all nodes chain to the root (TYPE = RTMR, “Internal TCI” flag is set)
26562720 1. Verify that the “Latest TCI” field of the TCI Node that contains the
2657- Runtime Journey PCR (TYPE = RTJM, “Internal TCI” flag is set) matches the
2658- “Latest” Runtime PCR value from PCRX
2721+ Runtime PCRs (TYPE = RTMR, “Internal TCI” flag is set) matches the
2722+ “Latest” and Journey Runtime PCR values.
26592723 1. Ensure `SHA384_HASH(0x00..00, TCI from SRAM) == RT_FW_JOURNEY_PCR`
26602724 1. Check that retired and inactive contexts do not have tags
26612725 1. If any validations fail, Runtime Firmware executes the
@@ -2758,9 +2822,9 @@
27582822
27592823 * Runtime Firmware SHALL initialize the default context in “internal-cdi” mode.
27602824 * Perform the following initial measurements:
2761- * Call DeriveContext with Caliptra Journey PCR
2825+ * Call DeriveContext with Caliptra RT PCRs
27622826 * INPUT\_DATA = PCRX (RT journey PCR as defined in the FHT)
2763- * TYPE = “RTJM”
2827+ * TYPE = “RTMR”
27642828 * CONTEXT\_HANDLE = default context
27652829 * TARGET\_LOCALITY = Caliptra locality (0xFFFFFFFF)
27662830 * Call DeriveContext with mailbox valid PAUSERS