diff --git a/runtime/README.md b/runtime/README.md index 357e71134a..51a65a4a98 100644 --- a/runtime/README.md +++ b/runtime/README.md @@ -10,6 +10,10 @@ v1.1: * [LMS Signature Verification](#lms_signature_verify-new-in-11) +v1.2: + +* [Manifest-Based Image Authorization](#manifest-based-image-authorization-new-in-12) + v2.0: * Add support for passive mode (same as 1.x) and subsystem (or active) mode @@ -153,6 +157,102 @@ This scheme avoids having to store the IV while avoiding IV reuse problems. GCM prevents an adversary from changing internal CMID parameters, such as changing an AES key to an ECDSA key, which has sensitive internal structure (although ECDSA is not currently supported). +## Manifest-Based Image Authorization (new in 1.2) + +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. + +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. + +* Caliptra-Endorsed Aggregated Measured Boot +* Caliptra-Endorsed Local Verifier + +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. + +Manifest-based image authorization is implemented via three mailbox commands: [`SET_AUTH_MANIFEST`](#set-auth-manifest), [`SET_IMAGE_METADATA`](#set-image-metadata), and [`AUTHORIZE_AND_STASH`](#authorize-and-stash). + +### Caliptra-Endorsed Aggregated Measured Boot + +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. + +### Caliptra-Endorsed Local Verifier + +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. + +The Caliptra-Endorsed Local Verifier could be required by the owner only or both the vendor and the owner. + +The main difference between Caliptra-Endorsed Aggregated Measured Boot and Caliptra-Endorsed Local Verifier is if the SoC RoT is relying on the Measurement Manifest for SoC Secure Boot services as opposed as using it as an additional verification. + +### SoC RoT Enforcement of Measurement Manifest + +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. + +### Caliptra Measurement Manifest Signing Keys Authenticity + +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. + +### Unique Measurement Manifest Signing Keys + +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 possibly one for the vendor. These new key pairs are endorsed once using a single signature within the Measurement Manifest, thus allowing the measurement manifest keys to be used independently of the Caliptra FW signing keys. + +### Caliptra Measurement Manifest Vendor Public Key Authenticity + +The Measurement Manifest MUST have an endorsement by the Caliptra Vendor Public Key. In order to fulfill this requirement, the Vendor has 2 options: + +* Vendor signing required: The Vendor creates a new Measurement keypair which will sign the measurement manifest and endorses the 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. +* Vendor signing **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. + +### Caliptra Measurement Manifest Owner Public Key Authenticity + +Caliptra will always verify the endorsement of the Measurement Manifest Owner Public key and require that it signed the measurement manifest. + +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 commands. Caliptra Runtime will authorize the image based on whether its hash was contained in the manifest. + +#### Preamble + +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. + +#### Image Metadata Collection (IMC) + +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 16 image hashes will be supported. + +#### Caliptra Measurement Manifest Keys Endorsement Verification Steps + +When Caliptra receives the Measurement Manifest, Caliptra will: + +* Verify the vendor endorsement using the Caliptra Vendor FW Public Key and compare with the vendor endorsement signature. +* If the vendor endorsement is invalid, the `SET_AUTH_MANIFEST` command will be rejected. +* If the vendor endorsement is valid, Caliptra will check if a vendor manifest measurement key is required: + * If the key is required, Caliptra will trust the Vendor Public key that was just endorsed. + * If the key is not required, Caliptra will not perform any more vendor verifications on this measurement manifest. +* Verify the owner endorsement using the Caliptra owner public key and compare with the owner endorsement signature. + * If the owner endorsement is invalid, the `SET_AUTH_MANIFEST` command will be rejected. + * Otherwise, the owner public key will be trusted and Caliptra will use it to verify the overall measurement manifest. + +#### Measurement Manifest Version Number + +A Measurement Manifest VN is used to ensure that some enforcement is possible if a progression of measurements is required. 32 bits of the existing unused `IDEVID_MANUF_IDENTIFIER` fuse (128 bits) can be repurposed for this. This can be accomplished by updating Caliptra's main specification to redefine the fuse definition and its usage from "Programming time" to "Field Programmable". + +### Image Authorization Sequence + +The diagram below illustrates how this feature is part of the Caliptra boot flow, and the order of operations needed to use the feature. + +```mermaid +sequenceDiagram + ROM->>FMC: Launch FMC + FMC->>Runtime: Launch RT + Runtime->>SOC: RDY_FOR_RT + Note over Runtime,SOC: Manifest Load + SOC->>Runtime: SET_MANIFEST + Runtime-->>SOC: Success/Failure + Note over Runtime,SOC: Image Authorization + loop n times + SOC->>Runtime: AUTHORIZE_AND_STASH + Runtime-->>SOC: Success/Failure + end + + Note over Runtime,SOC: DPE Attestation + SOC->>Runtime: DPE Attestation +``` ## Mailbox commands @@ -813,49 +913,33 @@ Command Code: `0x434B_4558` ("CKEX") ### SET_AUTH_MANIFEST +The SoC uses this command and `SET_IMAGE_METADTA` to program an image manifest for Manifest-Based Image Authorization to Caliptra. In response to these commands, the Caliptra Runtime will verify the manifest by authenticating the public keys and in turn using them to authenticate the IMC. On successful verification, the Runtime will store the IMEs into DCCM for future use. + Command Code: `0x4154_4D4E` ("ATMN") *Table: `SET_AUTH_MANIFEST` input arguments* - -| **Name** | **Type** | **Description** | -| ----------------------------- | ------------ | --------------------------------------------------------------------------- | -| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. | -| manifest size | u32 | The size of the full Authentication Manifest | -| preamble_marker | u32 | Marker needs to be 0x4154_4D4E for the preamble to be valid | -| preamble_size | u32 | Size of the preamble | -| preamble_version | u32 | Version of the preamble | -| preamble_flags | u32 | Preamble flags | -| preamble_vendor_ecc384_key | u32[24] | Vendor ECC384 key with X and Y coordinates in that order | -| preamble_vendor_lms_key | u32[6] | Vendor LMS-SHA192-H15 key | -| preamble_vendor_ecc384_sig | u32[24] | Vendor ECC384 signature | -| preamble_vendor_LMS_sig | u32[1344] | Vendor LMOTS-SHA192-W4 signature | -| preamble_owner_ecc384_key | u32[24] | Owner ECC384 key with X and Y coordinates in that order | -| preamble_owner_lms_key | u32[6] | Owner LMS-SHA192-H15 key | -| preamble_owner_ecc384_sig | u32[24] | Owner ECC384 signature | -| preamble_owner_LMS_sig | u32[1344] | Owner LMOTS-SHA192-W4 signature | -| metadata_vendor_ecc384_sig | u32[24] | Metadata Vendor ECC384 signature | -| metadata_vendor_LMS_sig | u32[1344] | Metadata Vendor LMOTS-SHA192-W4 signature | -| metadata_owner_ecc384_sig | u32[24] | Metadata Owner ECC384 signature | -| metadata_owner_LMS_sig | u32[1344] | Metadata Owner LMOTS-SHA192-W4 signature | -| metadata_header_revision | u32 | Revision of the metadata header | -| metadata_header_reserved | u32[3] | Reserved | -| metadata_entry_entry_count | u32 | number of metadata entries | -| metadata_entries | MetaData[16] | The max number of metadata is 16 but less can be used | - +| **Name** | **Type** | **Description** | +| -------------------------- | --------- | --------------------------------------------------------------------------- | +| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. | +| manifest size | u32 | The size of the full Authentication Manifest | +| preamble_marker | u32 | Marker needs to be 0x4154_4D4E for the preamble to be valid | +| preamble_size | u32 | Size of the preamble | +| preamble_version | u32 | Version of the preamble | +| preamble_flags | u32 | Preamble flags | +| preamble_vendor_ecc384_key | u32[24] | Vendor ECC384 public key with X and Y coordinates in that order | +| preamble_vendor_lms_key | u32[6] | Vendor LMS-SHA192-H15 public key | +| preamble_vendor_ecc384_sig | u32[24] | Vendor ECC384 signature | +| preamble_vendor_LMS_sig | u32[1344] | Vendor LMOTS-SHA192-W4 signature | +| preamble_owner_ecc384_key | u32[24] | Owner ECC384 key with X and Y coordinates in that order | +| preamble_owner_lms_key | u32[6] | Owner LMS-SHA192-H15 key | +| preamble_owner_ecc384_sig | u32[24] | Owner ECC384 signature | +| preamble_owner_LMS_sig | u32[1344] | Owner LMOTS-SHA192-W4 signature | *Table: `AUTH_MANIFEST_FLAGS` input flags* - | **Name** | **Value** | | ------------------------- | --------- | | VENDOR_SIGNATURE_REQUIRED | 1 << 0 | -*Table: `AUTH_MANIFEST_METADATA_ENTRY` digest entries* - -| **Name** | **Type** | **Description** | -| ------------- | -------- | ---------------------- | -| digest | u32[48] | Digest of the metadata | -| image_source | u32 | Image source | - *Table: `SET_AUTH_MANIFEST` output arguments* | **Name** | **Type** | **Description** | @@ -863,12 +947,47 @@ Command Code: `0x4154_4D4E` ("ATMN") | chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. | | fips\_status | u32 | Indicates if the command is FIPS approved or an error. | +### SET_IMAGE_METADATA + +This command is used alonside `SET_AUTH_MANIFEST` to provide image metadata signatures for manifest-based image authorization. + +Command Code: `0x5349_4D44` ("SIMD") + +*Table: `SET_IMAGE_METADATA` input arguments* +| **Name** | **Type** | **Description** | +| -------------------------- | ------------ | --------------------------------------------------------------------------- | +| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. | +| metadata_vendor_ecc384_sig | u32[24] | Metadata Vendor ECC384 signature | +| metadata_vendor_LMS_sig | u32[1344] | Metadata Vendor LMOTS-SHA192-W4 signature | +| metadata_owner_ecc384_sig | u32[24] | Metadata Owner ECC384 signature | +| metadata_owner_LMS_sig | u32[1344] | Metadata Owner LMOTS-SHA192-W4 signature | +| metadata_header_revision | u32 | Revision of the metadata header | +| metadata_header_reserved | u32[3] | Reserved | +| metadata_entry_entry_count | u32 | number of metadata entries | +| metadata_entries | MetaData[16] | The max number of metadata is 16 but less can be used | + +*Table: `SET_IMAGE_METADATA_ENTRY` digest entries* +| **Name** | **Type** | **Description** | +| ------------ | -------- | ---------------------- | +| digest | u32[48] | Digest of the metadata | +| image_source | u32 | Image source | + +*Table: `SET_IMAGE_METADATA` output arguments* +| **Name** | **Type** | **Description** | +| ----------- | -------- | -------------------------------------------------------------------------- | +| chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. | +| fips_status | u32 | Indicates if the command is FIPS approved or an error. | + ### AUTHORIZE_AND_STASH +The SoC uses this command to request authorization of its various SoC images. This command has the option to receive the image hash directly from SoC or from an external source (e.g., SHA Acc). + +The SoC uses this command repeatedly to ask for authorization to run its different images. The Runtime will verify that the image hash is contained in the IMC and will allow or reject the image based on that check. The command also enables stashing of the image hash by default with an option to skip stashing if needed. The SVN field is intended for anti-rollback protection. + + Command Code: `0x4154_5348` ("ATSH") *Table: `AUTHORIZE_AND_STASH` input arguments* - | **Name** | **Type** | **Description** | | ----------- | -------- | ----------------------------------------------------------------------------------- | | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. | @@ -882,7 +1001,6 @@ Command Code: `0x4154_5348` ("ATSH") | | | 2 = ShaAcc | *Table: `AUTHORIZE_AND_STASH_FLAGS` input flags* - | **Name** | **Value** | | ----------- | --------- | | SKIP_STASH | 1 << 0 |