| @@ -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/c43041a0e8e8cf14a742f87117cbc02fb917a499/auth-manifest/README.md" target="_blank">chipsalliance/caliptra-sw/auth-manifest/README.md</a> @ <code>c43041a</code> |
| 2 | +📄 Source: <a href="https://github.com/chipsalliance/caliptra-sw/blob/af5f9cf200595ef01b3c00569625b59a9e915da7/auth-manifest/README.md" target="_blank">chipsalliance/caliptra-sw/auth-manifest/README.md</a> @ <code>af5f9cf</code> |
| 3 | 3 | </div> |
| 4 | 4 | |
| 5 | 5 | ## SOC Manifest |
| @@ -13,7 +13,7 @@ |
| 13 | 13 | Those signatures are also stored in the Preamble. |
| 14 | 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 | 15 | |
| 16 | | - *Note: All fields are little endian unless specified* |
| 16 | + *Note: Do not treat the entire manifest as little endian. Scalar `u32` fields use little-endian layout. ECC key and signature fields are stored as big-endian `u32` words. Raw byte-array fields, such as image hashes, use the exact byte sequence produced by standard tools like OpenSSL unless a field description explicitly says otherwise.* |
| 17 | 17 | |
| 18 | 18 | | Field | Size (bytes) | Description | |
| 19 | 19 | | ---------------------------------- | ------------ | ----------- | |
| @@ -28,8 +28,8 @@ |
| 28 | 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 | 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 | 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**. | |
| 31 | +| **Owner ECC Signature** | 96 | Owner ECDSA P-384 signature, made by the firmware-image owner key, over the concatenation of the Preamble **Version**, **SVN**, and **Flags** fields followed by the **Owner ECC Public Key** and **Owner PQC Public Key**, hashed using SHA2-384. The Manifest Marker, Preamble Size, Vendor ECC/PQC Public Keys, and Vendor ECC/PQC Signatures are not covered.<br/>**R-Coordinate:** 48 bytes<br/>**S-Coordinate:** 48 bytes. | |
| 32 | +| **Owner PQC Signature (LMS or MLDSA)** | 4628 | Owner PQC signature over the same message as the Owner ECC signature. LMS signs the SHA2-384 digest of the message; MLDSA87 signs the message directly.<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 | 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 | 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 | 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. | |
| @@ -39,27 +39,31 @@ |
| 39 | 39 | ### **Image Metadata Collection** |
| 40 | 40 | |
| 41 | 41 | The Image Metadata Collection (IMC) is a collection of Image Metadata Entries (IMEs). |
| 42 | | -Each IME has a hash that matches a SOC image. |
| 42 | +Each IME has a digest that matches a SOC image. |
| 43 | 43 | The manifest vendor and owner private keys sign the IMC. |
| 44 | 44 | The Preamble holds the IMC signatures. |
| 45 | 45 | The manifest IMC vendor signatures are optional and are validated only if the **Flags Bit 0 = 1**. |
| 46 | 46 | |
| 47 | 47 | When Flags Bit 1 (`DEBUG_IMAGE`) is set, Runtime requires Flags Bit 0, subsystem mode, asserted `SS_DEBUG_INTENT`, and clear `SS_STRAP_GENERIC[3][31]` (`DISABLE_VENDOR_DEBUG_IMAGES`). Vendor and owner authentication remain required, along with all SVN, metadata, digest, duplicate-ID, and authorization checks. |
| 48 | | -Up to 80 image hashes are supported. |
| 48 | +Up to 127 image metadata entries are supported. |
| 49 | 49 | |
| 50 | 50 | | Field | Size (bytes) | Description | |
| 51 | 51 | | -------------------------------- | ------------ | --------------------------------------- | |
| 52 | 52 | | **Image Metadata Entry (IME) Count** | 4 | Number of IME(s) in the IMC. | |
| 53 | | -| **Image Metadata Entry (N)** | Variable | List of Image Metadata Entry structures | |
| 53 | +| **Image Metadata Entry (N)** | Variable | List of 80-byte Image Metadata Entry structures | |
| 54 | 54 | |
| 55 | 55 | #### **Image Metadata Entry** |
| 56 | + |
| 57 | +The serialized IME layout follows `AuthManifestImageMetadata` in |
| 58 | +`auth-manifest/types/src/lib.rs`. Multi-word addresses are encoded as the low |
| 59 | +32-bit word followed by the high 32-bit word. |
| 56 | 60 | |
| 57 | 61 | | Field | Size (bytes) | Description | |
| 58 | 62 | | ----------------------- | ------------ | ----------- | |
| 59 | 63 | | **Firmware ID (`fw_id`)** | 4 | Platform-wide identifier for a firmware image. It must be unique across the active vendor + owner and owner-only Image Metadata Collections. | |
| 60 | 64 | | **Component ID (`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). | |
| 61 | 65 | | **Classification (`classification`)** | 4 | Component classification value associated with the image. | |
| 62 | | -| **Flags (`flags`)** | 4 | Image-specific flags.<br/>**Bits 1:0:** Image source.<br/>**Bit 2:** If set, the image digest will **not** be verified; otherwise, the metadata image digest will be compared against the calculated digest of the image.<br/>**Bits 8–14:** Firmware execution control bit mapped to this image.<br/>Other bits: reserved. | |
| 66 | +| **Flags (`flags`)** | 4 | Image-specific flags.<br/>**Bits 1:0:** Image source.<br/>**Bit 2:** If set, the image digest will **not** be verified; otherwise, the metadata image digest will be compared against the calculated digest of the image.<br/>**Bit 3:** If set, Runtime streams the image into SHA-384 using one four-byte DMA command per word instead of burst reads. The image address and size must be four-byte aligned.<br/>**Bits 8–14:** Firmware execution control bit mapped to this image.<br/>Other bits: reserved. | |
| 63 | 67 | | **Image Load Address Low (`image_load_address.lo`)** | 4 | Low 4 bytes of the 64-bit AXI address where the image will be loaded for verification and execution. | |
| 64 | 68 | | **Image Load Address High (`image_load_address.hi`)** | 4 | High 4 bytes of the 64-bit AXI address where the image will be loaded for verification and execution. | |
| 65 | 69 | | **Image Staging Address Low (`image_staging_address.lo`)** | 4 | Low 4 bytes of the 64-bit AXI address where the image will be temporarily written during firmware update download and verification. | |
| @@ -67,10 +71,58 @@ |
| 67 | 71 | | **Image Digest (`digest`)** | 48 | SHA2-384 digest of the SOC image. | |
| 68 | 72 | |
| 69 | 73 | |
| 74 | +For both vendor + owner and owner-only manifests, the `dma_single_dword_read` |
| 75 | +boolean in each TOML `image_metadata_list` entry is optional and defaults to |
| 76 | +`false` (burst DMA) when omitted. Set it to `true` to opt in to single-DWORD DMA |
| 77 | +hashing from the image's load or staging address by setting IME flag bit 3. |
| 78 | +Existing TOML configurations do not need to add this field. |
| 79 | + |
| 80 | +For MCU hitless activation (`fw_id = 2`), set `image_load_address` to the full |
| 81 | +64-bit MCU SRAM address, `MCI_BASE + 0x00c00000`. Runtime copies the staged |
| 82 | +image to this fixed destination and authorizes it there. `ACTIVATE_FIRMWARE` |
| 83 | +rejects a different load address, a source or destination range that overflows |
| 84 | +the 64-bit AXI address space, or an image larger than the hardware-reported |
| 85 | +MCU SRAM capacity before requesting an MCU reset or copying the image. |
| 86 | +This applies to both vendor + owner and owner-only manifests; encrypted-boot |
| 87 | +`INITIAL_ACTIVATE` does not use these hitless-update checks. |
| 88 | +See [ACTIVATE_FIRMWARE](../runtime/README.md#activate_firmware). |
| 89 | + |
| 90 | +#### **Optional Device UEID Entry** |
| 91 | + |
| 92 | +The original SoC manifest can be bound to a device without changing the |
| 93 | +manifest layout. An active IME with `fw_id = 0x00000FFF` is reserved for this |
| 94 | +purpose. This value is allocated immediately below the vendor-defined SoC image |
| 95 | +ID range, which begins at `0x00001000`. This entry is optional, counts toward |
| 96 | +`entry_count`, and is covered by the existing IMC signatures. |
| 97 | + |
| 98 | +The entry's 48-byte `digest` field has the following encoding: |
| 99 | + |
| 100 | +| Digest bytes | Contents | |
| 101 | +| ------------ | -------- | |
| 102 | +| `0..=16` | Device UEID: the UEID type byte followed by the four 32-bit manufacturer serial-number fuse words in little-endian byte order. | |
| 103 | +| `17..=47` | Zero padding. | |
| 104 | + |
| 105 | + |
| 106 | +The other IME fields are not interpreted for device binding and should retain |
| 107 | +their default values. `AuthManifestImageMetadata::new_ueid` constructs the |
| 108 | +canonical entry for programmatic manifest generation. The authorization |
| 109 | +manifest app can encode the same entry through its existing |
| 110 | +`image_metadata_list` configuration. |
| 111 | + |
| 112 | +After authenticating the IMC, Runtime compares all 48 digest bytes with the |
| 113 | +device UEID and canonical zero padding. A mismatch rejects |
| 114 | +`SET_AUTH_MANIFEST` or `VERIFY_AUTH_MANIFEST` with |
| 115 | +`RUNTIME_AUTH_MANIFEST_UEID_MISMATCH`. Omission preserves the existing |
| 116 | +device-independent behavior. The UEID entry cannot be retrieved or used for |
| 117 | +image authorization or activation. |
| 118 | + |
| 119 | +The reserved ID has no special meaning in an Owner Authorization Manifest and |
| 120 | +does not trigger device UEID validation in `SET_OWNER_AUTH_MANIFEST`. |
| 121 | + |
| 70 | 122 | ## Owner Authorization Manifest |
| 71 | 123 | |
| 72 | 124 | The Owner Authorization Manifest is a smaller, owner-only manifest loaded with |
| 73 | | -[`SET_OWNER_AUTH_MANIFEST`](../runtime/README.md#set_owner-auth-manifest). It |
| 125 | +[`SET_OWNER_AUTH_MANIFEST`](../runtime/README.md#set_owner_auth_manifest). It |
| 74 | 126 | carries owner public keys, owner signatures, and an owner-only Image Metadata |
| 75 | 127 | Collection. Runtime stores these entries separately from the vendor + owner |
| 76 | 128 | collection loaded by `SET_AUTH_MANIFEST` and searches the owner-only collection |