| @@ -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/a32ac08170df3018580f45db2304fea35e3362d0/auth-manifest/README.md" target="_blank">chipsalliance/caliptra-sw/auth-manifest/README.md</a> @ <code>a32ac08</code> |
| 2 | +📄 Source: <a href="https://github.com/chipsalliance/caliptra-sw/blob/61a20816d836d39f2c97c151bce08dc5e7c199cd/auth-manifest/README.md" target="_blank">chipsalliance/caliptra-sw/auth-manifest/README.md</a> @ <code>61a2081</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 | | ---------------------------------- | ------------ | ----------- | |
| @@ -39,20 +39,24 @@ |
| 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 | | ----------------------- | ------------ | ----------- | |
| @@ -67,10 +71,42 @@ |
| 67 | 71 | | **Image Digest (`digest`)** | 48 | SHA2-384 digest of the SOC image. | |
| 68 | 72 | |
| 69 | 73 | |
| 74 | +#### **Optional Device UEID Entry** |
| 75 | + |
| 76 | +The original SoC manifest can be bound to a device without changing the |
| 77 | +manifest layout. An active IME with `fw_id = 0x00000FFF` is reserved for this |
| 78 | +purpose. This value is allocated immediately below the vendor-defined SoC image |
| 79 | +ID range, which begins at `0x00001000`. This entry is optional, counts toward |
| 80 | +`entry_count`, and is covered by the existing IMC signatures. |
| 81 | + |
| 82 | +The entry's 48-byte `digest` field has the following encoding: |
| 83 | + |
| 84 | +| Digest bytes | Contents | |
| 85 | +| ------------ | -------- | |
| 86 | +| `0..=16` | Device UEID: the UEID type byte followed by the four 32-bit manufacturer serial-number fuse words in little-endian byte order. | |
| 87 | +| `17..=47` | Zero padding. | |
| 88 | + |
| 89 | + |
| 90 | +The other IME fields are not interpreted for device binding and should retain |
| 91 | +their default values. `AuthManifestImageMetadata::new_ueid` constructs the |
| 92 | +canonical entry for programmatic manifest generation. The authorization |
| 93 | +manifest app can encode the same entry through its existing |
| 94 | +`image_metadata_list` configuration. |
| 95 | + |
| 96 | +After authenticating the IMC, Runtime compares all 48 digest bytes with the |
| 97 | +device UEID and canonical zero padding. A mismatch rejects |
| 98 | +`SET_AUTH_MANIFEST` or `VERIFY_AUTH_MANIFEST` with |
| 99 | +`RUNTIME_AUTH_MANIFEST_UEID_MISMATCH`. Omission preserves the existing |
| 100 | +device-independent behavior. The UEID entry cannot be retrieved or used for |
| 101 | +image authorization or activation. |
| 102 | + |
| 103 | +The reserved ID has no special meaning in an Owner Authorization Manifest and |
| 104 | +does not trigger device UEID validation in `SET_OWNER_AUTH_MANIFEST`. |
| 105 | + |
| 70 | 106 | ## Owner Authorization Manifest |
| 71 | 107 | |
| 72 | 108 | 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 |
| 109 | +[`SET_OWNER_AUTH_MANIFEST`](../runtime/README.md#set_owner_auth_manifest). It |
| 74 | 110 | carries owner public keys, owner signatures, and an owner-only Image Metadata |
| 75 | 111 | Collection. Runtime stores these entries separately from the vendor + owner |
| 76 | 112 | collection loaded by `SET_AUTH_MANIFEST` and searches the owner-only collection |