6. Image metadata

This section describes the format options, usage models, and a metadata example.

6.1. Format profiles

The choice of metadata format depends on the software development practices and interoperability requirements of a particular deployment.

At least one of the following formats must be supported by the interface:

Table 1 Supported formats per segment

Profile ID	Profile name	Description
0x1	IETF SUIT CBOR	The full specification for the format is described in A Concise Binary Object Representation (CBOR)-based Serialization Format for the Software Updates for Internet of Things (SUIT) Manifest [SUIT]. The manifest contains an authentication header that is signed using CBOR Object Signing and Encryption (COSE). An example is provided in the following sections. Arm recommends this profile.
0x2	Implementation specified	A proprietary implementation. A description of the format should be made publicly available. This option is not preferable because it provides no interoperability.

It is expected that implementations are built to only support a single profile. However, an implementation can choose to support multiple profiles if necessary.

All Profile IDs not specified here are reserved for future use.

6.2. Usage models

The metadata can be supplied using one of two methods, depending on the protocol used:

• Embedded method: The metadata is prepended to each image.

• Standalone method: The metadata is standalone and separate from images. The metadata can describe metadata for multiple images. In this case, psa_fwu_set_manifest is used.

The decision is made by the caller depending on the firmware update protocol.

6.3. Example metadata

The manifest format described contains many optional and extensible fields covering the goals of this specification.

The following example shows an example of a single image specified as a SUIT CBOR manifest. Further examples are provided in at this link.

6.3.1. Summary

The example manifest contains two major subparts:

• Manifest authentication header. The authentication header authenticates the manifest data. It includes the following fields:

  • Signature information (alg and payload).

  • The raw signature (signature).

• Manifest content. It includes the following fields:

  • Manifest format version (manifest-version).

  • Manifest Sequence number (manifest-sequence-number).

  • Class UUID and Vendor UUID (class-id and vendor-id).

  • Image digest information (e.g. image-size, algorithm-id, digest-bytes)

  • Installation instructions (in this example there is only the condition-image-match and directive-run directive)

Implementation note:

An example open-source tool for generating SUIT manifests is available at :Example code to generate and parse SUIT manifests [SUIT-CODE]. The project also contains a small parser that can be included in small microcontrollers.

6.3.2. CBOR

The example manifest below conforms to IETF SUIT and is written in CBOR diagnostic language for illustrative purposes.

{
    / authentication-wrapper / 2:h'81d28443a10126a058248202582064d8094
da3ef71c5971b7b84e7f4be1f56452c32fdde7bc1c70889112f1d5d9958407d637397e
12abdd41bc026a8e8a22f0f902a5b972e7786d570a37ac43c370b64a6946b0311f059c
a01d40f74d88d6fd7193baa36f5cf20aa57c46a0411a6b704' / [
        18([
                / protected / h'a10126' / {
                    / alg / 1:-7 / ES256 /,
                } /,
                / unprotected / {
                },
                / payload / h'8202582064d8094da3ef71c5971b7b84e7f4be1f
56452c32fdde7bc1c70889112f1d5d99' / [
                    / algorithm-id / 2 / sha256 /,
                    / digest-bytes /
h'64d8094da3ef71c5971b7b84e7f4be1f56452c32fdde7bc1c70889112f1d5d99'
                ] /,
                / signature / h'7d637397e12abdd41bc026a8e8a22f0f902a5b
972e7786d570a37ac43c370b64a6946b0311f059ca01d40f74d88d6fd7193baa36f5cf
20aa57c46a0411a6b704'
            ])
    ] /,
    / manifest / 3:h'a50101020103585ea20244818141000458548614a40150fa6
b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab4503820
2582000112233445566778899aabbccddeeff0123456789abcdeffedcba98765432100
e1987d001f602f60a438203f60c438217f6' / {
        / manifest-version / 1:1,
        / manifest-sequence-number / 2:1,
        / common / 3:h'a20244818141000458548614a40150fa6b4a53d5ad5fdfb
e9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab450382025820001122334
45566778899aabbccddeeff0123456789abcdeffedcba98765432100e1987d001f602f
6' / {
            / components / 2:h'81814100' / [
                [h'00']
            ] /,
            / common-sequence / 4:h'8614a40150fa6b4a53d5ad5fdfbe9de663
e4d41ffe02501492af1425695e48bf429b2d51f2ab4503820258200011223344556677
8899aabbccddeeff0123456789abcdeffedcba98765432100e1987d001f602f6' / [
                / directive-override-parameters / 20,{
                    / vendor-id /
1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf-be9d-e663e4d41ffe /,
                    / class-id / 2:h'1492af1425695e48bf429b2d51f2ab45'
/ 1492af14-2569-5e48-bf42-9b2d51f2ab45 /,
                        / image-digest / 3:[
                        / algorithm-id / 2 / sha256 /,
                        / digest-bytes /
h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210'
                    ],
                    / image-size / 14:34768,
                } ,
                / condition-vendor-identifier / 1,F6 / nil / ,
                / condition-class-identifier / 2,F6 / nil /
            ] /,
        } /,
        / validate / 10:h'8203f6' / [
            / condition-image-match / 3,F6 / nil /
        ] /,
        / run / 12:h'8217f6' / [
            / directive-run / 23,F6 / nil /
        ] /,
    } /,
}

The total size of this example with COSE authentication object is estimated to be 231 bytes.