Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[doc] Manifest-Based Image Auth #1749

Merged
merged 1 commit into from
Oct 30, 2024
Merged

[doc] Manifest-Based Image Auth #1749

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
190 changes: 154 additions & 36 deletions runtime/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FW public-key chain

It's ambiguous whether this is a firmware signing key chain or a firmware attestation key chain. I presume this is the former.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Caliptra FW key pair

Caliptra FW signing key pair I presume, to disambiguate from DICE.

Is this the vendor signing key or owner signing key?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

multi-factor authentication

Bike-shedding here but I feel like "joint authentication" might be a better term, to avoid connotations of human-driven multi-factor authentication flows.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A local verifier provides an authentication of SoC FW by matching SoC FW measurements with measurements from the Caliptra measurement manifest.

So what is a "local verifier"? Is it a piece of logic living inside Caliptra? Is it a role that is shared with the SoC?


The Caliptra-Endorsed Local Verifier could be required by the owner only or both the vendor and the owner.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does it mean for a local verifier to be "required" by a vendor or owner? Is the functionality enabled or disabled based on whether it is required?


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.
Copy link
Contributor

@fdamato fdamato Oct 29, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it is still not clear to me the difference between the 2 usage models.
- In case of "Caliptra-Endorsed Local Verifier" what is the remediation action SOC Manager should take in case of failure ? Assuming boot is not stopped.

Also being Calipta the RTM for the SOC, I would encourage Caliptra RT FW to attest to this failure in the DPE (How ???) Certificate.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not 100% clear to me either. Maybe @mhatrevi can weigh in?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks Chris. I really would like to understand better the difference between usage models.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unresolving as I have the same question.

  • The "Caliptra-Endorsed Aggregated Measured Boot" section states that one signed manifest includes measurements for a collection of different components.
  • The "Caliptra-Endorsed Local Verifier" section first paragraph states that measurements of components are compared to a manifest.

Those sound like the same thing.

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.

So in both models the SoC is checking in with Caliptra whenever it boots code. In the second model the SoC is doing its own verification on top of that. If that's the case, it seems like we could just describe a single model of manifest flows. We can just say that this is a feature that SoCs can rely on, and they can optionally also do their own verification on top of that.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Have filed as #1757


### 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

Expand Down Expand Up @@ -813,62 +913,81 @@ 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** |
| ------------ | -------- | -------------------------------------------------------------------------- |
| 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. |
Expand All @@ -882,7 +1001,6 @@ Command Code: `0x4154_5348` ("ATSH")
| | | 2 = ShaAcc |

*Table: `AUTHORIZE_AND_STASH_FLAGS` input flags*

| **Name** | **Value** |
| ----------- | --------- |
| SKIP_STASH | 1 << 0 |
Expand Down
Loading