From 34003b69f15553890ad3486d04e0af8f75ec6974 Mon Sep 17 00:00:00 2001 From: mlvisaya <38512415+mlvisaya@users.noreply.github.com> Date: Fri, 20 Dec 2024 17:43:49 -0800 Subject: [PATCH] Update SOC Manifest for Caliptra 2.0 (#1797) * Update SOC Manifest for Caliptra 2.0 - Updated the "Preamble" section to include detailed descriptions of the Version, SVN, Flags, and other fields. - Reformatted field tables for improved readability and consistency. - Added new fields such as IMC Vendor ECC Signature, IMC Vendor LMS Signature, IMC Owner ECC Signature, and IMC Owner LMS Signature. - Expanded "Image Metadata Entry" section with new fields like Image Identifier, Flags, Image Load Address, Classification, Version Number, and Version String. - Revised "Image Metadata Collection" section for clarity and added a new table format. --- auth-manifest/README.md | 65 ++++++++++++++++++++++++----------------- 1 file changed, 39 insertions(+), 26 deletions(-) diff --git a/auth-manifest/README.md b/auth-manifest/README.md index 57ad7feeb5..cff6c6d347 100644 --- a/auth-manifest/README.md +++ b/auth-manifest/README.md @@ -3,37 +3,50 @@ The Caliptra SOC manifest has two main components: - ### **Preamble** + 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. *Note: All fields are little endian unless specified* -| Field | Size (bytes) | Description| -|-------|--------|------------| -| Manifest Marker | 4 | Magic Number marking the start of the manifest. The value must be 0x41544D4E (‘ATMN’ in ASCII)| -| Manifest Size | 4 | Size of the full manifest structure | -| Version | 4 | Manifest version | -| Flags | 4 | Feature flags.
**Bit0:** - Vendor Signature Required. If set, verify the vendor IMC signature(s)
**Bit1-Bit31:** Reserved | -| Vendor ECC Public Key | 96 | ECC P-384 public key used to verify the IMC Signature.
**X-Coordinate:** Public Key X-Coordinate (48 bytes)
**Y-Coordinate:** Public Key Y-Coordinate (48 bytes) | -| Vendor LMS Public Key | 48 | LMS public key used to verify the IMC Signature.
**tree_type:** LMS Algorithm Type (4 bytes)
**otstype:** LMS Ots Algorithm Type (4 bytes)
**id:** (16 bytes)
**digest:** (24 bytes)
Note: If LMS validation is not required, this should field should be zeroed out.| -| Vendor ECC Signature | 96 | Vendor ECDSA P-384 signature of the Version, Flags, Vendor ECC and LMS public keys, hashed using SHA2-384.
**R-Coordinate:** Random Point (48 bytes)
**S-Coordinate:** Proof (48 bytes) | -| Vendor LMS Signature | 1620 | Vendor LMS signature of the Version, Flags, Vendor ECC and LMS public keys, hashed using SHA2-384.
**q:** Leaf of the Merkle tree where the OTS public key appears (4 bytes)
**ots:** Lmots Signature (1252 bytes)
**tree_type:** Lms Algorithm Type (4 bytes)
**tree_path:** Path through the tree from the leaf associated with the LM-OTS signature to the root. (360 bytes)
Note: If LMS validation is not required, this should field should be zeroed out.| -| Owner ECC Public Key | 96 | ECC P-384 public key used to verify the IMC Signature.
**X-Coordinate:** Public Key X-Coordinate (48 bytes)
**Y-Coordinate:** Public Key Y-Coordinate (48 bytes) | -| Owner LMS Public Key | 48 | LMS public key used to verify the IMC Signature.
**tree_type:** LMS Algorithm Type (4 bytes)
**otstype:** LMS Ots Algorithm Type (4 bytes)
**id:** (16 bytes)
**digest:** (24 bytes)
Note: If LMS validation is not required, this should field should be zeroed out.| -| Owner ECC Signature | 96 | Owner ECDSA P-384 signature of the Version, Flags, Owner ECC and LMS public keys, hashed using SHA2-384.
**R-Coordinate:** Random Point (48 bytes)
**S-Coordinate:** Proof (48 bytes) | -| Owner LMS Signature | 1620 | Owner LMS signature of the Version, Flags, Owner ECC and LMS public keys, hashed using SHA2-384.
**q:** Leaf of the Merkle tree where the OTS public key appears (4 bytes)
**ots:** Lmots Signature (1252 bytes)
**tree_type:** Lms Algorithm Type (4 bytes)
**tree_path:** Path through the tree from the leaf associated with the LM-OTS signature to the root. (360 bytes)
Note: If LMS validation is not required, this should field should be zeroed out.| +| Field | Size (bytes) | Description | +| ------------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Manifest Marker | 4 | Magic Number marking the start of the manifest. The value must be 0x41544D4E (‘ATMN’ in ASCII) | +| Manifest Size | 4 | Size of the full manifest structure | +| Version | 4 | Manifest version. The current version is 0x00000002. | +| 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. | +| Flags | 4 | Feature flags.
**Bit0:** - Vendor Signature Required. If set, the vendor public keys will be used to verify the signatures signed with the
vendor private key. Otherwise, vendor signatures will not be used for verification.
**Bit1-Bit31:** Reserved | +| Vendor ECC Public Key | 96 | Vendor ECC P-384 public key used to verify the IMC Signature.
**X-Coordinate:** Public Key X-Coordinate (48 bytes)
**Y-Coordinate:** Public Key Y-Coordinate (48 bytes) | +| Vendor LMS Public Key | 48 | Vendor LMS-SHA192-H15 public key used to verify the IMC Signature
**tree_type:** LMS Algorithm Type (4 bytes)
**otstype:** LMS Ots Algorithm Type (4 bytes) 
**id:** (16 bytes)
**digest:** (24 bytes)
Note: If LMS validation is not required, this field should be zeroed out. | +| Vendor ECC Signature | 96 | Vendor ECDSA P-384 signature of the Version, SVN, Flags, Vendor ECC and LMS public keys, hashed using SHA2-384.
**R-Coordinate:** Random Point (48 bytes)
**S-Coordinate:** Proof (48 bytes) | +| Vendor LMS Signature | 1620 | Vendor LMOTS-SHA192-W4 signature of the Version, SVN, Flags, Vendor ECC and LMS public keys, hashed using SHA2-384.
**q:** Leaf of the Merkle tree where the OTS public key appears (4 bytes)
**ots:** Lmots Signature (1252 bytes)
**tree_type:** Lms Algorithm Type (4 bytes)
**tree_path:** Path through the tree from the leaf associated with the LM-OTS signature to the root. (360 bytes)
Note: If LMS validation is not required, this field should be zeroed out. | +| Owner ECC Public Key | 96 | Owner ECC P-384 public key used to verify the IMC Signature.
**X-Coordinate:** Public Key X-Coordinate (48 bytes)
**Y-Coordinate:** Public Key Y-Coordinate (48 bytes) | +| Owner LMS Public Key | 48 | Owner LMS-SHA192-H15 public key used to verify the IMC Signature.
**tree_type:** LMS Algorithm Type (4 bytes)
**otstype:** LMS Ots Algorithm Type (4 bytes)
**id:** (16 bytes)
**digest:** (24 bytes)
Note: If LMS validation is not required, this field should be zeroed out. | +| Owner ECC Signature | 96 | Owner ECDSA P-384 signature of the Version, SVN, Flags, Owner ECC and LMS public keys, hashed using SHA2-384.
**R-Coordinate:** Random Point (48 bytes)
**S-Coordinate:** Proof (48 bytes) | +| Owner LMS Signature | 1620 | Owner LMOTS-SHA192-W4 signature of the Version, SVN, Flags, Owner ECC and LMS public keys, hashed using SHA2-384.
**q:** Leaf of the Merkle tree where the OTS public key appears (4 bytes)
**ots:** Lmots Signature (1252 bytes)
**tree_type:** Lms Algorithm Type (4 bytes)
**tree_path:** Path through the tree from the leaf associated with the LM-OTS signature to the root. (360 bytes)
Note: If LMS validation is not required, this field should be zeroed out. | +| IMC Vendor ECC Signature | 96 | Vendor ECDSA P-384 Signature of the Image Metadata Collection hashed using SHA2-384.
**X-Coordinate:** Public Key X-Coordinate (48 bytes)
**Y-Coordinate:** Public Key Y-Coordinate(48bytes) | +| IMC Vendor LMS Signature | 1620 | Vendor LMOTS-SHA192-W4 signature of the Image Metadata Collection hashed using SHA2-384.
**q:** Leaf of the Merkle tree where the OTS public key appears (4 bytes)
**ots:** Lmots Signature (1252 bytes)
**tree_type:** Lms Algorithm Type (4 bytes)
**tree_path:** Path through the tree from the leaf associated with the LM-OTS signature to the root. (360 bytes)
Note: If LMS validation is not required, this field should be zeroed out. | +| IMC Owner ECC Signature | 96 | Owner ECDSA P-384 Signature of the Image Metadata Collection hashed using SHA2-384.
**X-Coordinate:** Public Key X-Coordinate (48 bytes)
**Y-Coordinate:** Public Key Y-Coordinate(48bytes) | +| IMC Owner LMS Signature | 1620 | Owner LMOTS-SHA192-W4 signature of the Image Metadata Collection hashed using SHA2-384
**q:** Leaf of the Merkle tree where the OTS public key appears (4 bytes)
**ots:** Lmots Signature (1252 bytes)
**tree_type:** Lms Algorithm Type (4 bytes)
**tree_path:** Path through the tree from the leaf associated with the LM-OTS signature to the root. (360 bytes)
Note: If LMS validation is not required, this field should be zeroed out. | - ### **Image Metadata Entry** -| Field | Size (bytes) | Description| -|-------|--------|------------| -| Image Hash | 48 | SHA2-384 hash of a SOC image | -| Image Source | 4 | | + +| Field | Size (bytes) | Description | +| ----------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Image Hash | 48 | SHA2-384 hash of a SOC image | +| Image Identifier | 4 | Unique value selected by the vendor to distinguish between component images. | +| Flags | 4 | A set of 32-bit flags specific to the image.
**Bit0**: If set, the image hash will not be verified otherwise the metadata image hash will be compared against the calculated hash of the image.
**Bit1**: If set, it indicates that the image is a MCU Runtime image, otherwise it indicates a SOC Image. | +| Image Load Address High | 4 | The higher 4 bytes of the 64-bit AXI address where the image will be loaded for verification and execution or staging. | +| Image Load Address Low | 4 | The lower 4 bytes of the 64-bit AXI address where the image will be loaded for verification and execution or staging | +| Classification | 4 | This field indicates the DMTF Firmware classification of the image.
Refer to the description of ComponentClassification in [DMTF PLDM Firmware Update Specification](https://www.dmtf.org/sites/default/files/standards/documents/DSP0267_1.3.0.pdf) | +| Version Number | 4 | This is a vendor-defined field which can used to compare versions of the image.
This is useful when comparing the current version in the device with the one in this package by using
integer comparison rather than comparing using the VersionString.
For example, this can be in the form of MajorMinorRevisionPatch or a timestamp corresponding to the release date.
This functions the same as the ComponentComparisonStamp in [DMTF PLDM Firmware Update Specification](https://www.dmtf.org/sites/default/files/standards/documents/DSP0267_1.3.0.pdf) | +| Version String | 32 |
A null-terminated utf-8 string that indicates the version of the image, the maximum length is limited
to 32 bytes including the string terminator.

Example: "1.2.0" | +| ImageSize | 4 | Size in bytes of the image. | - ### **Image Metadata Collection** -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 sixteen image hashes are supported. - -| Field | Size (bytes) | Description| -|-------|--------|------------| -| Revision | 4 | Version of the IMC structure | -| Reserved | 4 | Reserved | -| Image Metadata Entry (IME) Count | 4 | Number of IME(s) in the IMC | -| Image Metadata Entry (N) | Variable | List of Image Metadata Entry structures | \ No newline at end of file + +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. + +| Field | Size (bytes) | Description | +| -------------------------------- | ------------ | --------------------------------------- | +| Image Metadata Entry (IME) Count | 4 | Number of IME(s) in the IMC | +| Image Metadata Entry (N) | Variable | List of Image Metadata Entry structures |