| @@ -1,5 +1,5 @@ |
| 1 | 1 | <div style="font-size: 0.85em; color: #656d76; margin-bottom: 1em; padding: 0.5em; background: #f6f8fa; border-radius: 4px;"> |
| 2 | | -📄 Source: <a href="https://github.com/chipsalliance/caliptra-sw/blob/e6e5db26702ee88d530d2789ac87749472a6641c/auth-manifest/README.md" target="_blank">chipsalliance/caliptra-sw/auth-manifest/README.md</a> @ <code>e6e5db2</code> |
| 2 | +📄 Source: <a href="https://github.com/chipsalliance/caliptra-sw/blob/e56467181b5313e53cf6cdc92f705a4127480fc2/auth-manifest/README.md" target="_blank">chipsalliance/caliptra-sw/auth-manifest/README.md</a> @ <code>e564671</code> |
| 3 | 3 | </div> |
| 4 | 4 | |
| 5 | 5 | ## SOC Manifest |
| @@ -7,49 +7,62 @@ |
| 7 | 7 | The Caliptra SOC manifest has two main components: |
| 8 | 8 | |
| 9 | 9 | - ### **Preamble** |
| 10 | | - The Preamble section contains the authorization 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 ECC and LMS private keys endorse the manifest’s public keys, and these endorsements (signatures) are part of the Preamble as well. |
| 11 | 10 | |
| 12 | | - *Note: All fields are little endian unless specified* |
| 11 | + The Preamble section contains the authorization manifest **ECC** and **PQC (LMS or MLDSA)** public keys of the vendor and the owner. |
| 12 | + These public keys correspond to the private keys that sign the Image Metadata Collection (IMC) section. |
| 13 | + Those signatures are also stored in the Preamble. |
| 14 | + The Caliptra firmware’s ECC and PQC private keys endorse the manifest’s public keys, and these endorsements (signatures) are part of the Preamble as well. |
| 15 | + |
| 16 | + *Note: All fields are little endian unless specified* |
| 13 | 17 | |
| 14 | 18 | | Field | Size (bytes) | Description | |
| 15 | | -| ------- | -------------- | ------------ | |
| 16 | | -| Manifest Marker | 4 | Magic Number marking the start of the manifest. The value must be 0x41544D4E (‘ATMN’ in ASCII) | |
| 17 | | -| Manifest Size | 4 | Size of the full manifest structure | |
| 18 | | -| Version | 4 | Manifest version | |
| 19 | | -| Flags | 4 | Feature flags.<br />**Bit0:** - Vendor Signature Required. If set, the vendor public keys will be used to verify the signatures signed with the <br />vendor private key. Otherwise, vendor signatures will not be used for verification.<br />**Bit1-Bit31:** Reserved | |
| 20 | | -| Vendor ECC Public Key | 96 | 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) | |
| 21 | | -| Vendor LMS Public Key | 48 | 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. | |
| 22 | | -| Vendor ECC Signature | 96 | 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) | |
| 23 | | -| Vendor LMS Signature | 1620 | 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. | |
| 24 | | -| Owner ECC Public Key | 96 | 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) | |
| 25 | | -| Owner LMS Public Key | 48 | 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. | |
| 26 | | -| Owner ECC Signature | 96 | 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) | |
| 27 | | -| Owner LMS Signature | 1620 | Owner LMS signature of the 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. | |
| 28 | | -| IMC Vendor ECC Signature | 96 | Vendor ECDSA P-384 Signature of the Image Metadata Collection hashed using SHA2-384.<br />**X-Coordinate:** Public Key X-Coordinate (48 bytes)<br />**Y-Coordinate:** Public Key Y-Coordinate(48bytes) | |
| 29 | | -| IMC Vendor LMS Signature | 1620 | Vendor LMOTS-SHA192-W4 signature of the Image Metadata Collection 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 field should be zeroed out. | |
| 30 | | -| IMC Owner ECC Signature | 96 | Owner ECDSA P-384 Signature of the Image Metadata Collection hashed using SHA2-384.<br />**X-Coordinate:** Public Key X-Coordinate (48 bytes)<br />**Y-Coordinate:** Public Key Y-Coordinate(48bytes) | |
| 31 | | -| IMC Owner LMS Signature | 1620 | Owner LMOTS-SHA192-W4 signature of the Image Metadata Collection 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 field should be zeroed out. | |
| 19 | +| ---------------------------------- | ------------ | ----------- | |
| 20 | +| **Manifest Marker** | 4 | Magic number marking the start of the manifest. The value must be `0x324D5441` (`'ATM2'` in ASCII). | |
| 21 | +| **Manifest Size** | 4 | Size of the full manifest structure in bytes. | |
| 22 | +| **Version** | 4 | Manifest version. The current version is `0x00000002`. | |
| 23 | +| **SVN** | 4 | Security Version Number used for anti-rollback. The maximum value is vendor-defined and is limited by the maximum size of the Caliptra fuse allocated for anti-rollback. | |
| 24 | +| **Flags** | 4 | Manifest feature flags.<br/>**Bit 0** – Vendor Signature Required. If set, the vendor public keys (ECC and PQC) will be used to verify signatures signed with the vendor private keys. If clear, vendor signatures are not used for verification.<br/>**Bits 1–31** – Reserved. | |
| 25 | +| **Vendor ECC Public Key** | 96 | Vendor ECC P-384 public key used to verify the IMC signature and endorse PQC keys.<br/>**X-Coordinate:** 48 bytes<br/>**Y-Coordinate:** 48 bytes. | |
| 26 | +| **Vendor PQC Public Key (LMS or MLDSA)** | 2592 | Vendor **PQC** public key used to verify the IMC signature and to endorse the vendor measurement keys.<br/>This field is sized to support **MLDSA87** (2592-byte public key).<br/>When:<br/>• **MLDSA87** is used, the field holds the full 2592-byte MLDSA87 public key.<br/>• **LMS** (e.g., LMS-SHA192-H15) is used, the LMS public key (e.g., 48 bytes) is stored at the beginning of the field and the remaining bytes **must be zeroed**. | |
| 27 | +| **Vendor ECC Signature** | 96 | Vendor ECDSA P-384 signature over the Preamble fields that are covered by policy, typically including Version, SVN, Flags, and vendor ECC/PQC public keys, hashed using SHA2-384.<br/>**R-Coordinate:** 48 bytes<br/>**S-Coordinate:** 48 bytes. | |
| 28 | +| **Vendor PQC Signature (LMS or MLDSA)** | 4628 | Vendor PQC signature over the same Preamble fields as the ECC signature.<br/>This field is sized to support the **MLDSA87** signature (4628 bytes).<br/>When:<br/>• **MLDSA87** is used, the entire field holds the MLDSA87 signature (per FIPS-204 definition, up to 4628 bytes).<br/>• **LMS** (e.g., LMS-SHA192-H15 / LMOTS-SHA192-W4) is used, the LMS signature (e.g., ~1620 bytes) is stored at the beginning and the remaining bytes **must be zeroed**.<br/>If PQC validation is not required, this field **must be zeroed**. | |
| 29 | +| **Owner ECC Public Key** | 96 | Owner ECC P-384 public key used to verify the IMC signature and endorse PQC keys on behalf of the platform owner.<br/>**X-Coordinate:** 48 bytes<br/>**Y-Coordinate:** 48 bytes. | |
| 30 | +| **Owner PQC Public Key (LMS or MLDSA)** | 2592 | Owner **PQC** public key used to verify the IMC signature and to endorse owner measurement keys.<br/>Same encoding rules as **Vendor PQC Public Key (LMS or MLDSA)**: MLDSA87 fills the field; LMS occupies the beginning and zero-pads the rest. | |
| 31 | +| **Owner ECC Signature** | 96 | Owner ECDSA P-384 signature over the Preamble fields that are covered by policy for the owner (Version, SVN, Flags, owner ECC/PQC keys, etc.), hashed using SHA2-384.<br/>**R-Coordinate:** 48 bytes<br/>**S-Coordinate:** 48 bytes. | |
| 32 | +| **Owner PQC Signature (LMS or MLDSA)** | 4628 | Owner PQC signature over the same Preamble fields as the Owner ECC signature.<br/>Same layout rules as **Vendor PQC Signature (LMS or MLDSA)** (MLDSA87 uses full field; LMS uses prefix + zero padding).<br/>If PQC validation is not required, this field **must be zeroed**. | |
| 33 | +| **IMC Vendor ECC Signature** | 96 | Vendor ECDSA P-384 signature over the **Image Metadata Collection (IMC)**, hashed using SHA2-384.<br/>**R-Coordinate:** 48 bytes<br/>**S-Coordinate:** 48 bytes. | |
| 34 | +| **IMC Vendor PQC Signature (LMS or MLDSA)** | 4628 | Vendor PQC signature over the **IMC**.<br/>Uses the same encoding as **Vendor PQC Signature (LMS or MLDSA)**, but the signed message is the serialized IMC instead of the Preamble.<br/>If PQC validation is not required, this field **must be zeroed**. | |
| 35 | +| **IMC Owner ECC Signature** | 96 | Owner ECDSA P-384 signature over the **IMC**, hashed using SHA2-384.<br/>**R-Coordinate:** 48 bytes<br/>**S-Coordinate:** 48 bytes. | |
| 36 | +| **IMC Owner PQC Signature (LMS or MLDSA)** | 4628 | Owner PQC signature over the **IMC**.<br/>Same encoding rules as the other PQC signature fields (LMS or MLDSA; unused bytes zero-padded).<br/>If PQC validation is not required, this field **must be zeroed**. | |
| 32 | 37 | |
| 33 | 38 | |
| 34 | 39 | - ### **Image Metadata Entry** |
| 40 | + |
| 35 | 41 | | Field | Size (bytes) | Description | |
| 36 | | -| --------------- | -------------- | ---------------------------------- | |
| 37 | | -| Firmware Id | u32 | Id of the image | |
| 38 | | -| Flags | u32 | See `METADATA_ENTRY_FLAGS` below | |
| 39 | | -| Digest | u32[12] | Digest of the image | |
| 42 | +| ----------------------- | ------------ | ----------- | |
| 43 | +| **Image Hash** | 48 | SHA2-384 hash of a SOC image. | |
| 44 | +| **Image Identifier** | 4 | Unique value selected by the vendor to distinguish between images. | |
| 45 | +| **Component Id** | 4 | Identifies the image component to be loaded. This corresponds to the `ComponentIdentifier` field defined in the DMTF PLDM Firmware Update Specification (DSP0267). | |
| 46 | +| **Flags** | 4 | Image-specific flags.<br/>**Bit 0:** If set, the image hash will **not** be verified; otherwise, the metadata image hash will be compared against the calculated hash of the image.<br/>**Bit 1:** If set, indicates that the image is an MCU Runtime image; otherwise, it indicates a SOC image.<br/>**Bits 8–14:** Firmware execution control bit mapped to this image.<br/>Other bits: reserved. | |
| 47 | +| **Image Load Address High** | 4 | High 4 bytes of the 64-bit AXI address where the image will be loaded for verification and execution. | |
| 48 | +| **Image Load Address Low** | 4 | Low 4 bytes of the 64-bit AXI address where the image will be loaded for verification and execution. | |
| 49 | +| **Staging Address High** | 4 | High 4 bytes of the 64-bit AXI address where the image will be temporarily written during firmware update download and verification. | |
| 50 | +| **Staging Address Low** | 4 | Low 4 bytes of the 64-bit AXI address where the image will be temporarily written during firmware update download and verification. | |
| 40 | 51 | |
| 41 | | - |
| 42 | | -- ### **METADATA ENTRY FLAGS** |
| 43 | | -| Field | Size (bits) | Description | |
| 44 | | -| -------------------- | ------------- | ----------------- | |
| 45 | | -| Image Source | 2 | 1: InRequest | |
| 46 | | -| Ignore Auth Check | 1 | If set, the image digest is not compared for the firmware id | |
| 47 | 52 | |
| 48 | 53 | |
| 49 | 54 | - ### **Image Metadata Collection** |
| 50 | | -The Image Metadata Collection (IMC) is a collection of Image Metadata entries (IME). Each IME has a hash that matches a 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 = 1. Up to 127 image hashes are supported. |
| 55 | + |
| 56 | +The Image Metadata Collection (IMC) is a collection of Image Metadata Entries (IMEs). |
| 57 | +Each IME has a hash that matches a SOC image. |
| 58 | +The manifest vendor and owner private keys sign the IMC. |
| 59 | +The Preamble holds the IMC signatures. |
| 60 | +The manifest IMC vendor signatures are optional and are validated only if the **Flags Bit 0 = 1**. |
| 61 | +Up to 127 image hashes are supported. |
| 51 | 62 | |
| 52 | 63 | | Field | Size (bytes) | Description | |
| 53 | | -| ------- | -------------- | ------------ | |
| 54 | | -| Image Metadata Entry (IME) Count | 4 | Number of IME(s) in the IMC | |
| 55 | | -| Image Metadata Entry (N) | Variable | List of Image Metadata Entry structures | |
| 64 | +| -------------------------------- | ------------ | --------------------------------------- | |
| 65 | +| **Image Metadata Entry (IME) Count** | 4 | Number of IME(s) in the IMC. | |
| 66 | +| **Image Metadata Entry (N)** | Variable | List of Image Metadata Entry structures | |
| 67 | + |
| 68 | + |