A Concise Binary Object Representation (CBOR)-based Serialization Format for the Software Updates for Internet of Things (SUIT) Manifest

4.1. IoT Firmware Update Constraints

The various constraints of IoT devices and the range of use cases that need to be supported create a broad set of requirements. For example, devices with:¶

• limited processing power and storage may require a simple representation of metadata.¶
• bandwidth constraints may require firmware compression or partial update support.¶
• bootloader complexity constraints may require simple selection between two bootable images.¶
• small internal storage may require external storage support.¶
• multiple microcontrollers may require coordinated update of all applications.¶
• large storage and complex functionality may require parallel update of many software components.¶
• extra information may need to be conveyed in the manifest in the earlier stages of the device lifecycle before those data items are stripped when the manifest is delivered to a constrained device.¶

Supporting the requirements introduced by the constraints on IoT devices requires the flexibility to represent a diverse set of possible metadata, but also requires that the encoding is kept simple.¶

4.2. SUIT Workflow Model

There are several fundamental assumptions that inform the model of Update Procedure workflow:¶

• Compatibility must be checked before any other operation is performed.¶
• All dependency manifests should be present before any payload is fetched.¶
• In some applications, payloads must be fetched and validated prior to installation.¶

There are several fundamental assumptions that inform the model of the Invocation Procedure workflow:¶

• Compatibility must be checked before any other operation is performed.¶
• All dependencies and payloads must be validated prior to loading.¶
• All loaded images must be validated prior to execution.¶

Based on these assumptions, the manifest is structured to work with a pull parser, where each section of the manifest is used in sequence. The expected workflow for a Recipient installing an update can be broken down into five steps:¶

1. Verify the signature of the manifest.¶
2. Verify the applicability of the manifest.¶
3. Resolve dependencies.¶
4. Fetch payload(s).¶
5. Install payload(s).¶

When installation is complete, similar information can be used for validating and running images in a further three steps:¶

1. Verify image(s).¶
2. Load image(s).¶
3. Run image(s).¶

If verification and running is implemented in a bootloader, then the bootloader MUST also verify the signature of the manifest and the applicability of the manifest in order to implement secure boot workflows. The bootloader may add its own authentication, e.g. a Message Authentication Code (MAC), to the manifest in order to prevent further verifications.¶

When multiple manifests are used for an update, each manifest's steps occur in a lockstep fashion; all manifests have dependency resolution performed before any manifest performs a payload fetch, etc.¶

5.1. Envelope

The SUIT Envelope is a container that encloses Delegation Chains, the Authentication Block, the Manifest, any Severable Elements, and any integrated payloads or dependencies. The Envelope is used instead of conventional cryptographic envelopes, such as COSE_Envelope because it allows modular processing, severing of elements, and integrated payloads in a way that would add substantial complexity with existing solutions. See Appendix C.1 for a description of the reasoning for this.¶

See Section 8.2 for more detail.¶

5.2. Delegation Chains

Delegation Chains allow a Recipient to establish a chain of trust from a Trust Anchor to the signer of a manifest by validating delegation claims. Each delegation claim is a [RFC8392] CBOR Web Tokens (CWTs). The first claim in each list is signed by a Trust Anchor. Each subsequent claim in a list is signed by the public key claimed in the preceding list element. The last element in each list claims a public key that can be used to verify a signature in the Authentication Block (Section 5.3).¶

See Section 8.3 for more detail.¶

5.3. Authentication Block

The Authentication Block contains a bstr-wrapped Section 10 and one or more [RFC8152] CBOR Object Signing and Encryption (COSE) authentication blocks. These blocks are one of:¶

• COSE_Sign_Tagged¶
• COSE_Sign1_Tagged¶
• COSE_Mac_Tagged¶
• COSE_Mac0_Tagged¶

Each of these objects is used in detached payload mode. The payload is the bstr-wrapped SUIT_Digest.¶

See Section 8.4 for more detail.¶

5.4. Manifest

The Manifest contains most metadata about one or more images. The Manifest is divided into Critical Metadata, Common Metadata, Command Sequences, and Integrity Check Values.¶

See Section 8.6 for more detail.¶

5.5. Severable Elements

Severable Elements are elements of the Envelope (Section 5.1) that have Integrity Check Values (Section 5.4.4) in the Manifest (Section 5.4).¶

Because of this organisation, these elements can be discarded or "Severed" from the Envelope without changing the signature of the Manifest. This allows savings based on the size of the Envelope in several scenarios, for example:¶

• A management system severs the Text and CoSWID sections before sending an Envelope to a constrained Recipient, which saves Recipient bandwidth.¶
• A Recipient severs the Installation section after installing the Update, which saves storage space.¶

See Section 8.8 for more detail.¶

5.6. Integrated Dependencies and Payloads

In some cases, it is beneficial to include a dependency or a payload in the Envelope of a manifest. For example:¶

• When an update is delivered via a comparatively unconstrained medium, such as a removable mass storage device, it may be beneficial to bundle updates into single files.¶
• When a manifest requires encryption, it must be referenced as a dependency, so a trivial manifest may be used to enclose the encrypted manifest. The encrypted manifest may be contained in the dependent manifest's envelope.¶
• When a manifest transports a small payload, such as an encrypted key, that payload may be placed in the manifest's envelope.¶

See Section 7.9.1, Section 8.5 for more detail.¶

6.1. Manifest Processor Setup

Prior to executing any command sequence, the manifest processor or its host application MUST inspect the manifest version field and fail when it encounters an unsupported encoding version. Next, the manifest processor or its host application MUST extract the manifest sequence number and perform a rollback check using this sequence number. The exact logic of rollback protection may vary by application, but it has the following properties:¶

• Whenever the manifest processor can choose between several manifests, it MUST select the latest valid, authentic manifest.¶
• If the latest valid, authentic manifest fails, it MAY select the next latest valid, authentic manifest, according to application-specific policy.¶

Here, valid means that a manifest has a supported encoding version and it has not been excluded for other reasons. Reasons for excluding typically involve first executing the manifest and may include:¶

• Test failed (e.g. Vendor ID/Class ID).¶
• Unsupported command encountered.¶
• Unsupported parameter encountered.¶
• Unsupported Component Identifier encountered.¶
• Payload not available.¶
• Dependency not available.¶
• Application crashed when executed.¶
• Watchdog timeout occurred.¶
• Dependency or Payload verification failed.¶
• Missing component from a set.¶
• Required parameter not supplied.¶

These failure reasons MAY be combined with retry mechanisms prior to marking a manifest as invalid.¶

Selecting an older manifest in the event of failure of the latest valid manifest is a robustness mechanism that is necessary for supporting the requirements in [I-D.ietf-suit-architecture], section 3.5. It may not be appropriate for all applications. In particular Trusted Execution Environments MAY require a failure to invoke a new installation, rather than a rollback approach. See [I-D.ietf-suit-information-model], Section 4.2.1 for more discussion on the security considerations that apply to rollback.¶

Following these initial tests, the manifest processor clears all parameter storage. This ensures that the manifest processor begins without any leaked data.¶

6.2. Required Checks

The RECOMMENDED process is to verify the signature of the manifest prior to parsing/executing any section of the manifest. This guards the parser against arbitrary input by unauthenticated third parties, but it costs extra energy when a Recipient receives an incompatible manifest.¶

When validating authenticity of manifests, the manifest processor MAY use an ACL (see Section 9) to determine the extent of the rights conferred by that authenticity. Where a device supports only one level of access, it MAY choose to skip signature verification of dependencies, since they are referenced by digest. Where a device supports more than one trusted party, it MAY choose to defer the verification of signatures of dependencies until the list of affected components is known so that it can skip redundant signature verifications. For example, a dependency signed by the same author as the dependent does not require a signature verification. Similarly, if the signer of the dependent has full rights to the device, according to the ACL, then no signature verification is necessary on the dependency.¶

Once a valid, authentic manifest has been selected, the manifest processor MUST examine the component list and verify that its maximum number of components is not exceeded and that each listed component is supported.¶

For each listed component, the manifest processor MUST provide storage for the supported parameters. If the manifest processor does not have sufficient temporary storage to process the parameters for all components, it MAY process components serially for each command sequence. See Section 6.6 for more details.¶

The manifest processor SHOULD check that the common sequence contains at least Check Vendor Identifier command and at least one Check Class Identifier command.¶

Because the common sequence contains Check Vendor Identifier and Check Class Identifier command(s), no custom commands are permitted in the common sequence. This ensures that any custom commands are only executed by devices that understand them.¶

If the manifest contains more than one component and/or dependency, each command sequence MUST begin with a Set Component Index or Set Dependency Index command.¶

If a dependency is specified, then the manifest processor MUST perform the following checks:¶

1. At the beginning of each section in the dependent: all previous sections of each dependency have been executed.¶
2. At the end of each section in the dependent: The corresponding section in each dependency has been executed.¶

If the interpreter does not support dependencies and a manifest specifies a dependency, then the interpreter MUST reject the manifest.¶

If a Recipient supports groups of interdependent components (a Component Set), then it SHOULD verify that all Components in the Component Set are specified by one update, that is: a single manifest and all its dependencies that together:¶

1. have sufficient permissions imparted by their signatures¶
2. specify a digest and a payload for every Component in the Component Set.¶

The single dependent manifest is sometimes called a Root Manifest.¶

6.3. Interpreter Fundamental Properties

The interpreter has a small set of design goals:¶

1. Executing an update MUST either result in an error, or a verifiably correct system state.¶
2. Executing a Trusted Invocation MUST either result in an error, or an invoked image.¶
3. Executing the same manifest on multiple Recipients MUST result in the same system state.¶

NOTE: when using A/B images, the manifest functions as two (or more) logical manifests, each of which applies to a system in a particular starting state. With that provision, design goal 3 holds.¶

6.4. Abstract Machine Description

The heart of the manifest is the list of commands, which are processed by a Manifest Processor-a form of interpreter. This Manifest Processor can be modeled as a simple abstract machine. This machine consists of several data storage locations that are modified by commands.¶

There are two types of commands, namely those that modify state (directives) and those that perform tests (conditions). Parameters are used as the inputs to commands. Some directives offer control flow operations. Directives target a specific component or dependency. A dependency is another SUIT_Envelope that describes additional components. Dependencies are identified by digest, but referenced in commands by Dependency Index, the index into the array of Dependencies. A component is a unit of code or data that can be targeted by an update. Components are identified by Component Identifiers, but referenced in commands by Component Index; Component Identifiers are arrays of binary strings and a Component Index is an index into the array of Component Identifiers.¶

Conditions MUST NOT have any side-effects other than informing the interpreter of success or failure. The Interpreter does not Abort if the Soft Failure flag (Section 8.7.5.23) is set when a Condition reports failure.¶

Directives MAY have side-effects in the parameter table, the interpreter state, or the current component. The Interpreter MUST Abort if a Directive reports failure regardless of the Soft Failure flag.¶

To simplify the logic describing the command semantics, the object "current" is used. It represents the component identified by the Component Index or the dependency identified by the Dependency Index:¶

current := components\[component-index\]
    if component-index is not false
    else dependencies\[dependency-index\]

As a result, Set Component Index is described as current := components[arg]. The actual operation performed for Set Component Index is described by the following pseudocode, however, because of the definition of current (above), these are semantically equivalent.¶

component-index := arg
dependency-index := false

Similarly, Set Dependency Index is semantically equivalent to current := dependencies[arg]¶

The following table describes the behavior of each command. "params" represents the parameters for the current component or dependency. Most commands operate on either a component or a dependency. Setting the Component Index clears the Dependency Index. Setting the Dependency Index clears the Component Index.¶

6.5. Special Cases of Component Index and Dependency Index

Component Index and Dependency Index can each take on one of three types:¶

1. Integer¶
2. Array of integers¶
3. True¶

Integers MUST always be supported by Set Component Index and Set Dependency Index. Arrays of integers MUST be supported by Set Component Index and Set Dependency Index if the Recipient supports 3 or more components or 3 or more dependencies, respectively. True MUST be supported by Set Component Index and Set Dependency Index if the Recipient supports 2 or more components or 2 or more dependencies, respectively. Each of these operates on the list of components or list of dependencies declared in the manifest.¶

Integer indices are the default case as described in the previous section. An array of integers represents a list of the components (Set Component Index) or a list of dependencies (Set Dependency Index) to which each subsequent command applies. The value True replaces the list of component indices or dependency indices with the full list of components or the full list of dependencies, respectively, as defined in the manifest.¶

When a command is executed, it either 1. operates on the component or dependency identified by the component index or dependency index if that index is an integer, or 2. it operates on each component or dependency identified by an array of indicies, or 3. it operates on every component or every dependency if the index is the boolean True. This is described by the following pseudocode:¶

if component-index is true:
    current-list = components
else if component-index is array:
    current-list = [ components[idx] for idx in component-index ]
else if component-index is integer:
    current-list = [ components[component-index] ]
else if dependency-index is true:
    current-list = dependencies
else if dependency-index is array:
    current-list = [ dependencies[idx] for idx in dependency-index ]
else:
    current-list = [ dependencies[dependency-index] ]
for current in current-list:
    cmd(current)

Try Each and Run Sequence are affected in the same way as other commands: they are invoked once for each possible Component or Dependency. This means that the sequences that are arguments to Try Each and Run Sequence are NOT invoked with Component Index = True or Dependency Index = True, nor are they invoked with array indices. They are only invoked with integer indices. The interpreter loops over the whole sequence, setting the Component Index or Dependency Index to each index in turn.¶

6.6. Serialized Processing Interpreter

In highly constrained devices, where storage for parameters is limited, the manifest processor MAY handle one component at a time, traversing the manifest tree once for each listed component. In this mode, the interpreter ignores any commands executed while the component index is not the current component. This reduces the overall volatile storage required to process the update so that the only limit on number of components is the size of the manifest. However, this approach requires additional processing power.¶

In order to operate in this mode, the manifest processor loops on each section for every supported component, simply ignoring commands when the current component is not selected.¶

When a serialized Manifest Processor encounters a component or dependency index of True, it does not ignore any commands. It applies them to the current component or dependency on each iteration.¶

6.7. Parallel Processing Interpreter

Advanced Recipients MAY make use of the Strict Order parameter and enable parallel processing of some Command Sequences, or it may reorder some Command Sequences. To perform parallel processing, once the Strict Order parameter is set to False, the Recipient may issue each or every command concurrently until the Strict Order parameter is returned to True or the Command Sequence ends. Then, it waits for all issued commands to complete before continuing processing of commands. To perform out-of-order processing, a similar approach is used, except the Recipient consumes all commands after the Strict Order parameter is set to False, then it sorts these commands into its preferred order, invokes them all, then continues processing.¶

Under each of these scenarios the parallel processing MUST halt until all issued commands have completed:¶

• Set Parameters.¶
• Override Parameters.¶
• Set Strict Order = True.¶
• Set Dependency Index.¶
• Set Component Index.¶

To perform more useful parallel operations, a manifest author may collect sequences of commands in a Run Sequence command. Then, each of these sequences MAY be run in parallel. Each sequence defaults to Strict Order = True. To isolate each sequence from each other sequence, each sequence MUST begin with a Set Component Index or Set Dependency Index directive with the following exception: when the index is either True or an array of indices, the Set Component Index or Set Dependency Index is implied. Any further Set Component Index directives MUST cause an Abort. This allows the interpreter that issues Run Sequence commands to check that the first element is correct, then issue the sequence to a parallel execution context to handle the remainder of the sequence.¶

6.8. Processing Dependencies

As described in Section 6.2, each manifest must invoke each of its dependencies sections from the corresponding section of the dependent. Any changes made to parameters by the dependency persist in the dependent.¶

When a Process Dependency command is encountered, the interpreter loads the dependency identified by the Current Dependency Index. The interpreter first executes the common-sequence section of the identified dependency, then it executes the section of the dependency that corresponds to the currently executing section of the dependent.¶

If the specified dependency does not contain the current section, Process Dependency succeeds immediately.¶

The Manifest Processor MUST also support a Dependency Index of True, which applies to every dependency, as described in Section 6.5¶

The interpreter also performs the checks described in Section 6.2 to ensure that the dependent is processing the dependency correctly.¶

6.9. Multiple Manifest Processors

When a system has multiple security domains, each domain might require independent verification of authenticity or security policies. Security domains might be divided by separation technology such as Arm TrustZone, Intel SGX, or another TEE technology. Security domains might also be divided into separate processors and memory spaces, with a communication interface between them.¶

For example, an application processor may have an attached communications module that contains a processor. The communications module might require metadata signed by a specific Trust Authority for regulatory approval. This may be a different Trust Authority than the application processor.¶

When there are two or more security domains (see [I-D.ietf-teep-architecture]), a manifest processor might be required in each. The first manifest processor is the normal manifest processor as described for the Recipient in Section 6.4. The second manifest processor only executes sections when the first manifest processor requests it. An API interface is provided from the second manifest processor to the first. This allows the first manifest processor to request a limited set of operations from the second. These operations are limited to: setting parameters, inserting an Envelope, invoking a Manifest Command Sequence. The second manifest processor declares a prefix to the first, which tells the first manifest processor when it should delegate to the second. These rules are enforced by underlying separation of privilege infrastructure, such as TEEs, or physical separation.¶

When the first manifest processor encounters a dependency prefix, that informs the first manifest processor that it should provide the second manifest processor with the corresponding dependency Envelope. This is done when the dependency is fetched. The second manifest processor immediately verifies any authentication information in the dependency Envelope. When a parameter is set for any component that matches the prefix, this parameter setting is passed to the second manifest processor via an API. As the first manifest processor works through the Procedure (set of command sequences) it is executing, each time it sees a Process Dependency command that is associated with the prefix declared by the second manifest processor, it uses the API to ask the second manifest processor to invoke that dependency section instead.¶

This mechanism ensures that the two or more manifest processors do not need to trust each other, except in a very limited case. When parameter setting across security domains is used, it must be very carefully considered. Only parameters that do not have an effect on security properties should be allowed. The dependency manifest MAY control which parameters are allowed to be set by using the Override Parameters directive. The second manifest processor MAY also control which parameters may be set by the first manifest processor by means of an ACL that lists the allowed parameters. For example, a URI may be set by a dependent without a substantial impact on the security properties of the manifest.¶

7.1. Compatibility Check Template

The goal of the compatibility check template ensure that Recipients only install compatible images.¶

In this template all information is contained in the common sequence and the following sequence of commands is used:¶

• Set Component Index directive (see Section 8.7.7.1)¶
• Set Parameters directive (see Section 8.7.7.5) for Vendor ID and Class ID (see Section 8.7.5)¶
• Check Vendor Identifier condition (see Section 8.7.5.2)¶
• Check Class Identifier condition (see Section 8.7.5.2)¶

7.2. Trusted Invocation Template

The goal of the Trusted Invocation template is to ensure that only authorized code is invoked; such as in Secure Boot or when a Trusted Application is loaded into a TEE.¶

The following commands are placed into the common sequence:¶

• Set Component Index directive (see Section 8.7.7.1)¶
• Override Parameters directive (see Section 8.7.7.6) for Image Digest and Image Size (see Section 8.7.5)¶

Then, the run sequence contains the following commands:¶

• Set Component Index directive (see Section 8.7.7.1)¶
• Check Image Match condition (see Section 8.7.6.2)¶
• Run directive (see Section 8.7.7.12)¶

7.3. Component Download Template

The goal of the Component Download template is to acquire and store an image.¶

The following commands are placed into the common sequence:¶

• Set Component Index directive (see Section 8.7.7.1)¶
• Override Parameters directive (see Section 8.7.7.6) for Image Digest and Image Size (see Section 8.7.5)¶

Then, the install sequence contains the following commands:¶

• Set Component Index directive (see Section 8.7.7.1)¶
• Set Parameters directive (see Section 8.7.7.5) for URI (see Section 8.7.5.13)¶
• Fetch directive (see Section 8.7.7.7)¶
• Check Image Match condition (see Section 8.7.6.2)¶

The Fetch directive needs the URI parameter to be set to determine where the image is retrieved from. Additionally, the destination of where the component shall be stored has to be configured. The URI is configured via the Set Parameters directive while the destination is configured via the Set Component Index directive.¶

Optionally, the Set Parameters directive in the install sequence MAY also contain Encryption Info (see Section 8.7.5.10), Compression Info (see Section 8.7.5.11), or Unpack Info (see Section 8.7.5.12) to perform simultaneous download and decryption, decompression, or unpacking, respectively.¶

7.4. Install Template

The goal of the Install template is to use an image already stored in an identified component to copy into a second component.¶

This template is typically used with the Component Download template, however a modification to that template is required: the Component Download operations are moved from the Payload Install sequence to the Payload Fetch sequence.¶

Then, the install sequence contains the following commands:¶

• Set Component Index directive (see Section 8.7.7.1)¶
• Set Parameters directive (see Section 8.7.7.5) for Source Component (see Section 8.7.5.14)¶
• Copy directive (see Section 8.7.7.9)¶
• Check Image Match condition (see Section 8.7.6.2)¶

7.5. Install and Transform Template

The goal of the Install and Transform template is to use an image already stored in an identified component to decompress, decrypt, or unpack at time of installation.¶

This template is typically used with the Component Download template, however a modification to that template is required: all Component Download operations are moved from the common sequence and the install sequence to the fetch sequence. The Component Download template targets a download component identifier, while the Install and Transform template uses an install component identifier. In-place unpacking, decompression, and decryption is complex and vulnerable to power failure. Therefore, these identifiers SHOULD be different; in-place installation SHOULD NOT be used without establishing guarantees of robustness to power failure.¶

The following commands are placed into the common sequence:¶

• Set Component Index directive for install component identifier (see Section 8.7.7.1)¶
• Override Parameters directive (see Section 8.7.7.6) for Image Digest and Image Size (see Section 8.7.5)¶

Then, the install sequence contains the following commands:¶

• Set Component Index directive for install component identifier (see Section 8.7.7.1)¶

• Set Parameters directive (see Section 8.7.7.5) for:¶

  • Source Component for download component identifier (see Section 8.7.5.14)¶
  • Encryption Info (see Section 8.7.5.10)¶
  • Compression Info (see Section 8.7.5.11)¶
  • Unpack Info (see Section 8.7.5.12)¶
• Copy directive (see Section 8.7.7.9)¶
• Check Image Match condition (see Section 8.7.6.2)¶

7.6. Integrated Payload Template

The goal of the Integrated Payload template is to install a payload that is included in the manifest envelope. It is identical to the Component Download template (Section 7.3) except that it places an added restriction on the URI passed to the Set Parameters directive.¶

An implementer MAY choose to place a payload in the envelope of a manifest. The payload envelope key MAY be a positive or negative integer. The payload envelope key MUST NOT be a value between 0 and 24 and it MUST NOT be used by any other envelope element in the manifest. The payload MUST be serialized in a bstr element.¶

The URI for a payload enclosed in this way MUST be expressed as a fragment-only reference, as defined in [RFC3986], Section 4.4. The fragment identifier is the stringified envelope key of the payload. For example, an envelope that contains a payload a key 42 would use a URI "#42", key -73 would use a URI "#-73".¶

7.7. Load from Nonvolatile Storage Template

The goal of the Load from Nonvolatile Storage template is to load an image from a non-volatile component into a volatile component, for example loading a firmware image from external Flash into RAM.¶

The following commands are placed into the load sequence:¶

• Set Component Index directive (see Section 8.7.7.1)¶
• Set Parameters directive (see Section 8.7.7.5) for Component Index (see Section 8.7.5)¶
• Copy directive (see Section 8.7.7.9)¶

As outlined in Section 6.4, the Copy directive needs a source and a destination to be configured. The source is configured via Component Index (with the Set Parameters directive) and the destination is configured via the Set Component Index directive.¶

7.8. Load & Decompress from Nonvolatile Storage Template

The goal of the Load & Decompress from Nonvolatile Storage template is to load an image from a non-volatile component into a volatile component, decompressing on-the-fly, for example loading a firmware image from external Flash into RAM.¶

The following commands are placed into the load sequence:¶

• Set Component Index directive (see Section 8.7.7.1)¶
• Set Parameters directive (see Section 8.7.7.5) for Source Component Index and Compression Info (see Section 8.7.5)¶
• Copy directive (see Section 8.7.7.9)¶

This template is similar to Section 7.7 but additionally performs decompression. Hence, the only difference is in setting the Compression Info parameter.¶

This template can be modified for decryption or unpacking by adding Decryption Info or Unpack Info to the Set Parameters directive.¶

7.9. Dependency Template

The goal of the Dependency template is to obtain, verify, and process a dependency manifest as appropriate.¶

The following commands are placed into the dependency resolution sequence:¶

• Set Dependency Index directive (see Section 8.7.7.2)¶
• Set Parameters directive (see Section 8.7.7.5) for URI (see Section 8.7.5)¶
• Fetch directive (see Section 8.7.7.7)¶
• Check Image Match condition (see Section 8.7.6.2)¶
• Process Dependency directive (see Section 8.7.7.4)¶

Then, the validate sequence contains the following operations:¶

• Set Dependency Index directive (see Section 8.7.7.2)¶
• Check Image Match condition (see Section 8.7.6.2)¶
• Process Dependency directive (see Section 8.7.7.4)¶

NOTE: Any changes made to parameters in a dependency persist in the dependent.¶

7.10. Encrypted Manifest Template

The goal of the Encrypted Manifest template is to fetch and decrypt a manifest so that it can be used as a dependency. To use an encrypted manifest, create a plaintext dependent, and add the encrypted manifest as a dependency. The dependent can include very little information.¶

The following operations are placed into the dependency resolution block:¶

• Set Dependency Index directive (see Section 8.7.7.2)¶

• Set Parameters directive (see Section 8.7.7.5) for¶

  • URI (see Section 8.7.5)¶
  • Encryption Info (see Section 8.7.5)¶
• Fetch directive (see Section 8.7.7.7)¶
• Check Image Match condition (see Section 8.7.6.2)¶
• Process Dependency directive (see Section 8.7.7.4)¶

Then, the validate block contains the following operations:¶

• Set Dependency Index directive (see Section 8.7.7.2)¶
• Check Image Match condition (see Section 8.7.6.2)¶
• Process Dependency directive (see Section 8.7.7.4)¶

A plaintext manifest and its encrypted dependency may also form a composite manifest (Section 7.9.1).¶

7.11. A/B Image Template

The goal of the A/B Image Template is to acquire, validate, and invoke one of two images, based on a test.¶

The following commands are placed in the common block:¶

• Set Component Index directive (see Section 8.7.7.1)¶

• Try Each¶

  • First Sequence:¶

    • Override Parameters directive (see Section 8.7.7.6, Section 8.7.5) for Offset A¶
    • Check Offset Condition (see Section 8.7.6.5)¶
    • Override Parameters directive (see Section 8.7.7.6) for Image Digest A and Image Size A (see Section 8.7.5)¶

  • Second Sequence:¶

    • Override Parameters directive (see Section 8.7.7.6, Section 8.7.5) for Offset B¶
    • Check Offset Condition (see Section 8.7.6.5)¶
    • Override Parameters directive (see Section 8.7.7.6) for Image Digest B and Image Size B (see Section 8.7.5)¶

The following commands are placed in the fetch block or install block¶

• Set Component Index directive (see Section 8.7.7.1)¶

• Try Each¶

  • First Sequence:¶

    • Override Parameters directive (see Section 8.7.7.6, Section 8.7.5) for Offset A¶
    • Check Offset Condition (see Section 8.7.6.5)¶
    • Set Parameters directive (see Section 8.7.7.6) for URI A (see Section 8.7.5)¶

  • Second Sequence:¶

    • Override Parameters directive (see Section 8.7.7.6, Section 8.7.5) for Offset B¶
    • Check Offset Condition (see Section 8.7.6.5)¶
    • Set Parameters directive (see Section 8.7.7.6) for URI B (see Section 8.7.5)¶
• Fetch¶

If Trusted Invocation (Section 7.2) is used, only the run sequence is added to this template, since the common sequence is populated by this template.¶

NOTE: Any test can be used to select between images, Check Offset Condition is used in this template because it is a typical test for execute-in-place devices.¶

8.1. Encoding Considerations

The map indices in the envelope encoding are reset to 1 for each map within the structure. This is to keep the indices as small as possible. The goal is to keep the index objects to single bytes (CBOR positive integers 1-23).¶

Wherever enumerations are used, they are started at 1. This allows detection of several common software errors that are caused by uninitialized variables. Positive numbers in enumerations are reserved for IANA registration. Negative numbers are used to identify application-specific values, as described in Section 11.¶

All elements of the envelope must be wrapped in a bstr to minimize the complexity of the code that evaluates the cryptographic integrity of the element and to ensure correct serialization for integrity and authenticity checks.¶

8.2. Envelope

The Envelope contains each of the other primary constituent parts of the SUIT metadata. It allows for modular processing of the manifest by ordering components in the expected order of processing.¶

The Envelope is encoded as a CBOR Map. Each element of the Envelope is enclosed in a bstr, which allows computation of a message digest against known bounds.¶

8.3. Delegation Chains

The suit-delegation element MAY carry one or more CBOR Web Tokens (CWTs) [RFC8392], with [RFC8747] cnf claims. They can be used to perform enhanced authorization decisions. The CWTs are arranged into a list of lists. Each list starts with a CWT authorized by a Trust Anchor, and finishes with a key used to authenticate the Manifest (see Section 8.4). This allows an Update Authority to delegate from a long term Trust Anchor, down through intermediaries, to a delegate without any out-of-band provisioning of Trust Anchors or intermediary keys.¶

A Recipient MAY choose to cache intermediaries and/or delegates. If an Update Distributor knows that a targeted Recipient has cached some intermediaries or delegates, it MAY choose to strip any cached intermediaries or delegates from the Delegation Chains in order to reduce bandwidth and energy.¶

8.4. Authenticated Manifests

The suit-authentication-wrapper contains a list containing a Section 10 and one or more cryptographic authentication wrappers for the Manifest. These are implemented as COSE_Mac_Tagged or COSE_Sign_Tagged blocks. Each of these blocks contains a SUIT_Digest of the Manifest. This enables modular processing of the manifest. The COSE_Mac_Tagged and COSE_Sign_Tagged blocks are described in RFC 8152 [RFC8152]. The suit-authentication-wrapper MUST come before any element in the SUIT_Envelope, except for the OPTIONAL suit-delegation, regardless of canonical encoding of CBOR. All validators MUST reject any SUIT_Envelope that begins with any element other than a suit-authentication-wrapper or suit-delegation.¶

A SUIT_Envelope that has not had authentication information added MUST still contain the suit-authentication-wrapper element, but the content MUST be a list containing only the SUIT_Digest.¶

A signing application MUST verify the suit-manifest element against the SUIT_Digest prior to signing.¶

8.5. Encrypted Manifests

To use an encrypted manifest, it must be a dependency of a plaintext manifest. This allows fine-grained control of what information is accessible to intermediate systems for the purposes of management, while still preserving the confidentiality of the manifest contents. This also means that a Recipient can process an encrypted manifest in the same way as an encrypted payload, allowing code reuse.¶

A template for using an encrypted manifest is covered in Encrypted Manifest Template (Section 7.10).¶

8.6. Manifest

The manifest contains:¶

• a version number (see Section 8.6.1)¶
• a sequence number (see Section 8.6.2)¶
• a reference URI (see Section 8.6.3)¶
• a common structure with information that is shared between command sequences (see Section 8.7.2)¶
• one or more lists of commands that the Recipient should perform (see Section 8.7.3)¶
• a reference to the full manifest (see Section 8.6.3)¶
• human-readable text describing the manifest found in the SUIT_Envelope (see Section 8.6.4)¶
• a Concise Software Identifier (CoSWID) found in the SUIT_Envelope (see Section 8.7.1)¶

The CoSWID, Text section, or any Command Sequence of the Update Procedure (Dependency Resolution, Image Fetch, Image Installation) can be either a CBOR structure or a SUIT_Digest. In each of these cases, the SUIT_Digest provides for a severable element. Severable elements are RECOMMENDED to implement. In particular, the human-readable text SHOULD be severable, since most useful text elements occupy more space than a SUIT_Digest, but are not needed by the Recipient. Because SUIT_Digest is a CBOR Array and each severable element is a CBOR bstr, it is straight-forward for a Recipient to determine whether an element has been severed. The key used for a severable element is the same in the SUIT_Manifest and in the SUIT_Envelope so that a Recipient can easily identify the correct data in the envelope. See Section 8.7.8 for more detail.¶

8.7. text-version-required

suit-text-version-required is used to represent a version-based dependency on suit-parameter-version as described in Section 8.7.5.18 and Section 8.7.6.8. To describe a version dependency, a Manifest Author SHOULD populate the suit-text map with a SUIT_Component_Identifier key for the dependency component, and place in the corresponding map a suit-text-version-required key with a free text expression that is representative of the version constraints placed on the dependency. This text SHOULD be expressive enough that a device operator can be expected to understand the dependency. This is a free text field and there are no specific formatting rules.¶

By way of example only, to express a dependency on a component "['x', 'y']", where the version should be any v1.x later than v1.2.5, but not v2.0 or above, the author would add the following structure to the suit-text element. Note that this text is in cbor-diag notation.¶

[h'78',h'79'] : {
    7 : ">=1.2.5,<2"
}

D8 DE                # tag(111)
   45                # bytes(5)
      2B 06 01 04 01 # X.690 Clause 8.19
#    1.3  6  1  4  1  show component encoding

NAMESPACE_CBOR_PEN = UUID5(NAMESPACE_OID, h'D86F452B06010401')
NAMESPACE_CBOR_PEN = 08cfcc43-47d9-5696-85b1-9c738465760e

Vendor ID = UUID5(DNS_PREFIX, vendor domain name)

Class ID = UUID5(Vendor ID, Class-Specific-Information)

Class ID = UUID5(
    UUID5(NAMESPACE_CBOR_PEN, CBOR_PEN),
    Class-Specific-Information)

8.8. Severable Elements

Because the manifest can be used by different actors at different times, some parts of the manifest can be removed or "Severed" without affecting later stages of the lifecycle. Severing of information is achieved by separating that information from the signed container so that removing it does not affect the signature. This means that ensuring integrity of severable parts of the manifest is a requirement for the signed portion of the manifest. Severing some parts makes it possible to discard parts of the manifest that are no longer necessary. This is important because it allows the storage used by the manifest to be greatly reduced. For example, no text size limits are needed if text is removed from the manifest prior to delivery to a constrained device.¶

Elements are made severable by removing them from the manifest, encoding them in a bstr, and placing a SUIT_Digest of the bstr in the manifest so that they can still be authenticated. The SUIT_Digest typically consumes 4 bytes more than the size of the raw digest, therefore elements smaller than (Digest Bits)/8 + 4 SHOULD NOT be severable. Elements larger than (Digest Bits)/8 + 4 MAY be severable, while elements that are much larger than (Digest Bits)/8 + 4 SHOULD be severable.¶

Because of this, all command sequences in the manifest are encoded in a bstr so that there is a single code path needed for all command sequences.¶

11.1. SUIT Commands

11.2. SUIT Parameters

11.3. SUIT Text Values

11.4. SUIT Component Text Values

11.5. SUIT Algorithm Identifiers

B.1. Example 0: Secure Boot

This example covers the following templates:¶

• Compatibility Check (Section 7.1)¶
• Secure Boot (Section 7.2)¶

It also serves as the minimum example.¶

{
    / authentication-wrapper / 2:bstr .cbor ({        digest: bstr
.cbor ([
            / algorithm-id / 2 / "sha256" /,
            / digest-bytes /
h'5c097ef64bf3bb9b494e71e1f2418eef8d466cc902f639a855ec9af3e9eddb99'
        ])        signatures: [
            bstr .cbor (18([
                    / protected / bstr .cbor ({
                        / alg / 1:-7 / "ES256" /,
                    }),
                    / unprotected / {
                    },
                    / payload / bstr .cbor ([
                        / algorithm-id / 2 / "sha256" /,
                        / digest-bytes /
h'5c097ef64bf3bb9b494e71e1f2418eef8d466cc902f639a855ec9af3e9eddb99'
                    ]),
                    / signature / h'60f5c3d03a3aa759bfef2ef0f5f97a93b1
f5e741f7463f4385af88513a5c2957bea2d6c4cfddd03392a267aab0fc0fd515560ed5
8e33fad26ac32a024c5a7143'
                ]))
        ]
    }),
    / manifest / 3:bstr .cbor ({
        / manifest-version / 1:1,
        / manifest-sequence-number / 2:0,
        / common / 3:bstr .cbor ({
            / components / 2:[
                [h'00']
            ],
            / common-sequence / 4:bstr .cbor ([
                / 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:bstr .cbor ([
                        / algorithm-id / 2 / "sha256" /,
                        / digest-bytes /
h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210'
                    ]),
                    / image-size / 14:34768,
                } ,
                / condition-vendor-identifier / 1,15 ,
                / condition-class-identifier / 2,15
            ]),
        }),
        / validate / 10:bstr .cbor ([
            / condition-image-match / 3,15
        ]),
        / run / 12:bstr .cbor ([
            / directive-run / 23,2
        ]),
    }),
}

Total size of Envelope without COSE authentication object: 159¶

Envelope:¶

a2025827815824820258205c097ef64bf3bb9b494e71e1f2418eef8d466c
c902f639a855ec9af3e9eddb99035871a50101020003585fa20281814100
0458568614a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af14
25695e48bf429b2d51f2ab450358248202582000112233445566778899aa
bbccddeeff0123456789abcdeffedcba98765432100e1987d0010f020f0a
4382030f0c43821702

Total size of Envelope with COSE authentication object: 272¶

Envelope with COSE authentication object:¶

a2025898825824820258205c097ef64bf3bb9b494e71e1f2418eef8d466c
c902f639a855ec9af3e9eddb99586fd28443a10126a05824820258205c09
7ef64bf3bb9b494e71e1f2418eef8d466cc902f639a855ec9af3e9eddb99
584060f5c3d03a3aa759bfef2ef0f5f97a93b1f5e741f7463f4385af8851
3a5c2957bea2d6c4cfddd03392a267aab0fc0fd515560ed58e33fad26ac3
2a024c5a7143035871a50101020003585fa202818141000458568614a401
50fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b
2d51f2ab450358248202582000112233445566778899aabbccddeeff0123
456789abcdeffedcba98765432100e1987d0010f020f0a4382030f0c4382
1702

B.2. Example 1: Simultaneous Download and Installation of Payload

This example covers the following templates:¶

• Compatibility Check (Section 7.1)¶
• Firmware Download (Section 7.3)¶

Simultaneous download and installation of payload. No secure boot is present in this example to demonstrate a download-only manifest.¶

{
    / authentication-wrapper / 2:bstr .cbor ({        digest: bstr
.cbor ([
            / algorithm-id / 2 / "sha256" /,
            / digest-bytes /
h'987eec85fa99fd31d332381b9810f90b05c2e0d4f284a6f4211207ed00fff750'
        ])        signatures: [
            bstr .cbor (18([
                    / protected / bstr .cbor ({
                        / alg / 1:-7 / "ES256" /,
                    }),
                    / unprotected / {
                    },
                    / payload / bstr .cbor ([
                        / algorithm-id / 2 / "sha256" /,
                        / digest-bytes /
h'987eec85fa99fd31d332381b9810f90b05c2e0d4f284a6f4211207ed00fff750'
                    ]),
                    / signature / h'750141d65b4f20a88dc70c6785a67e0f4f
085aead83ba2289d6e37271508cc91e0a0592f5c940c2257c9c0b26403c0ba4477f2ce
37b60089fe02cde7911d1c15'
                ]))
        ]
    }),
    / manifest / 3:bstr .cbor ({
        / manifest-version / 1:1,
        / manifest-sequence-number / 2:1,
        / common / 3:bstr .cbor ({
            / components / 2:[
                [h'00']
            ],
            / common-sequence / 4:bstr .cbor ([
                / 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:bstr .cbor ([
                        / algorithm-id / 2 / "sha256" /,
                        / digest-bytes /
h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210'
                    ]),
                    / image-size / 14:34768,
                } ,
                / condition-vendor-identifier / 1,15 ,
                / condition-class-identifier / 2,15
            ]),
        }),
        / install / 9:bstr .cbor ([
            / directive-set-parameters / 19,{
                / uri / 21:'http://example.com/file.bin',
            } ,
            / directive-fetch / 21,2 ,
            / condition-image-match / 3,15
        ]),
        / validate / 10:bstr .cbor ([
            / condition-image-match / 3,15
        ]),
    }),
}

Total size of Envelope without COSE authentication object: 194¶

Envelope:¶

a202582781582482025820987eec85fa99fd31d332381b9810f90b05c2e0
d4f284a6f4211207ed00fff750035894a50101020103585fa20281814100
0458568614a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af14
25695e48bf429b2d51f2ab450358248202582000112233445566778899aa
bbccddeeff0123456789abcdeffedcba98765432100e1987d0010f020f09
58258613a115781b687474703a2f2f6578616d706c652e636f6d2f66696c
652e62696e1502030f0a4382030f

Total size of Envelope with COSE authentication object: 307¶

Envelope with COSE authentication object:¶

a202589882582482025820987eec85fa99fd31d332381b9810f90b05c2e0
d4f284a6f4211207ed00fff750586fd28443a10126a0582482025820987e
ec85fa99fd31d332381b9810f90b05c2e0d4f284a6f4211207ed00fff750
5840750141d65b4f20a88dc70c6785a67e0f4f085aead83ba2289d6e3727
1508cc91e0a0592f5c940c2257c9c0b26403c0ba4477f2ce37b60089fe02
cde7911d1c15035894a50101020103585fa202818141000458568614a401
50fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b
2d51f2ab450358248202582000112233445566778899aabbccddeeff0123
456789abcdeffedcba98765432100e1987d0010f020f0958258613a11578
1b687474703a2f2f6578616d706c652e636f6d2f66696c652e62696e1502
030f0a4382030f

B.3. Example 2: Simultaneous Download, Installation, Secure Boot, Severed Fields

This example covers the following templates:¶

• Compatibility Check (Section 7.1)¶
• Secure Boot (Section 7.2)¶
• Firmware Download (Section 7.3)¶

This example also demonstrates severable elements (Section 5.5), and text (Section 8.6.4).¶

{
    / authentication-wrapper / 2:bstr .cbor ({        digest: bstr
.cbor ([
            / algorithm-id / 2 / "sha256" /,
            / digest-bytes /
h'75685579a83babd71ec8ef22fa49ac873f78a708a43a674e782ad30b6598d17a'
        ])        signatures: [
            bstr .cbor (18([
                    / protected / bstr .cbor ({
                        / alg / 1:-7 / "ES256" /,
                    }),
                    / unprotected / {
                    },
                    / payload / bstr .cbor ([
                        / algorithm-id / 2 / "sha256" /,
                        / digest-bytes /
h'75685579a83babd71ec8ef22fa49ac873f78a708a43a674e782ad30b6598d17a'
                    ]),
                    / signature / h'861b9bfb449125742baa648bc9d148cba4
5519cca8efecf705c2165ecdecaeba8b6ce2131284e66708788d741e8779d5973fa8e2
5da49eb203c81920719da949'
                ]))
        ]
    }),
    / manifest / 3:bstr .cbor ({
        / manifest-version / 1:1,
        / manifest-sequence-number / 2:2,
        / common / 3:bstr .cbor ({
            / components / 2:[
                [h'00']
            ],
            / common-sequence / 4:bstr .cbor ([
                / 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:bstr .cbor ([
                        / algorithm-id / 2 / "sha256" /,
                        / digest-bytes /
h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210'
                    ]),
                    / image-size / 14:34768,
                } ,
                / condition-vendor-identifier / 1,15 ,
                / condition-class-identifier / 2,15
            ]),
        }),
        / install / 9:[
            / algorithm-id / 2 / "sha256" /,
            / digest-bytes /
h'3ee96dc79641970ae46b929ccf0b72ba9536dd846020dbdc9f949d84ea0e18d2'
        ],
        / validate / 10:bstr .cbor ([
            / condition-image-match / 3,15
        ]),
        / run / 12:bstr .cbor ([
            / directive-run / 23,2
        ]),
        / text / 13:[
            / algorithm-id / 2 / "sha256" /,
            / digest-bytes /
h'23f48b2e2838650f43c144234aee18401ffe3cce4733b23881c3a8ae2d2b66e8'
        ],
    }),
    / install / 9:bstr .cbor ([
        / directive-set-parameters / 19,{
            / uri /
21:'http://example.com/very/long/path/to/file/file.bin',
        } ,
        / directive-fetch / 21,2 ,
        / condition-image-match / 3,15
    ]),
    / text / 13:bstr .cbor ({
        [h'00']:{
                / vendor-domain / 3:'arm.com',
                / component-description / 5:'This component is a
demonstration. The digest is a sample pattern, not a real one.',
            }
    }),
}

Total size of the Envelope without COSE authentication object or Severable Elements: 233¶

Envelope:¶

a20258278158248202582075685579a83babd71ec8ef22fa49ac873f78a7
08a43a674e782ad30b6598d17a0358bba70101020203585fa20281814100
0458568614a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af14
25695e48bf429b2d51f2ab450358248202582000112233445566778899aa
bbccddeeff0123456789abcdeffedcba98765432100e1987d0010f020f09
820258203ee96dc79641970ae46b929ccf0b72ba9536dd846020dbdc9f94
9d84ea0e18d20a4382030f0c438217020d8202582023f48b2e2838650f43
c144234aee18401ffe3cce4733b23881c3a8ae2d2b66e8

Total size of the Envelope with COSE authentication object but without Severable Elements: 346¶

Envelope:¶

a20258988258248202582075685579a83babd71ec8ef22fa49ac873f78a7
08a43a674e782ad30b6598d17a586fd28443a10126a05824820258207568
5579a83babd71ec8ef22fa49ac873f78a708a43a674e782ad30b6598d17a
5840861b9bfb449125742baa648bc9d148cba45519cca8efecf705c2165e
cdecaeba8b6ce2131284e66708788d741e8779d5973fa8e25da49eb203c8
1920719da9490358bba70101020203585fa202818141000458568614a401
50fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b
2d51f2ab450358248202582000112233445566778899aabbccddeeff0123
456789abcdeffedcba98765432100e1987d0010f020f09820258203ee96d
c79641970ae46b929ccf0b72ba9536dd846020dbdc9f949d84ea0e18d20a
4382030f0c438217020d8202582023f48b2e2838650f43c144234aee1840
1ffe3cce4733b23881c3a8ae2d2b66e8

Total size of Envelope with COSE authentication object: 929¶

Envelope with COSE authentication object:¶

a40258988258248202582075685579a83babd71ec8ef22fa49ac873f78a7
08a43a674e782ad30b6598d17a586fd28443a10126a05824820258207568
5579a83babd71ec8ef22fa49ac873f78a708a43a674e782ad30b6598d17a
5840861b9bfb449125742baa648bc9d148cba45519cca8efecf705c2165e
cdecaeba8b6ce2131284e66708788d741e8779d5973fa8e25da49eb203c8
1920719da9490358bba70101020203585fa202818141000458568614a401
50fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b
2d51f2ab450358248202582000112233445566778899aabbccddeeff0123
456789abcdeffedcba98765432100e1987d0010f020f09820258203ee96d
c79641970ae46b929ccf0b72ba9536dd846020dbdc9f949d84ea0e18d20a
4382030f0c438217020d8202582023f48b2e2838650f43c144234aee1840
1ffe3cce4733b23881c3a8ae2d2b66e809583c8613a1157832687474703a
2f2f6578616d706c652e636f6d2f766572792f6c6f6e672f706174682f74
6f2f66696c652f66696c652e62696e1502030f0d590204a20179019d2323
204578616d706c6520323a2053696d756c74616e656f757320446f776e6c
6f61642c20496e7374616c6c6174696f6e2c2053656375726520426f6f74
2c2053657665726564204669656c64730a0a202020205468697320657861
6d706c6520636f766572732074686520666f6c6c6f77696e672074656d70
6c617465733a0a202020200a202020202a20436f6d7061746962696c6974
7920436865636b20287b7b74656d706c6174652d636f6d7061746962696c
6974792d636865636b7d7d290a202020202a2053656375726520426f6f74
20287b7b74656d706c6174652d7365637572652d626f6f747d7d290a2020
20202a204669726d7761726520446f776e6c6f616420287b7b6669726d77
6172652d646f776e6c6f61642d74656d706c6174657d7d290a202020200a
2020202054686973206578616d706c6520616c736f2064656d6f6e737472
6174657320736576657261626c6520656c656d656e747320287b7b6f7672
2d736576657261626c657d7d292c20616e64207465787420287b7b6d616e
69666573742d6469676573742d746578747d7d292e814100a2036761726d
2e636f6d0578525468697320636f6d706f6e656e7420697320612064656d
6f6e7374726174696f6e2e20546865206469676573742069732061207361
6d706c65207061747465726e2c206e6f742061207265616c206f6e652e

B.4. Example 3: A/B images

This example covers the following templates:¶

• Compatibility Check (Section 7.1)¶
• Secure Boot (Section 7.2)¶
• Firmware Download (Section 7.3)¶
• A/B Image Template (Section 7.11)¶

{
    / authentication-wrapper / 2:bstr .cbor ({        digest: bstr
.cbor ([
            / algorithm-id / 2 / "sha256" /,
            / digest-bytes /
h'ae0c1ea689c9800a843550f38796b6fdbd52a0c78be5d26011d8e784da43d47c'
        ])        signatures: [
            bstr .cbor (18([
                    / protected / bstr .cbor ({
                        / alg / 1:-7 / "ES256" /,
                    }),
                    / unprotected / {
                    },
                    / payload / bstr .cbor ([
                        / algorithm-id / 2 / "sha256" /,
                        / digest-bytes /
h'ae0c1ea689c9800a843550f38796b6fdbd52a0c78be5d26011d8e784da43d47c'
                    ]),
                    / signature / h'359960bae5a7de2457c8f48d3250d96d1a
f2d36e08764b62d76f8a3f3041774b150b2c835bb1b2d7b1b2e629e1f08cc3b1b48fce
bb8fb38182c116161e02b33f'
                ]))
        ]
    }),
    / manifest / 3:bstr .cbor ({
        / manifest-version / 1:1,
        / manifest-sequence-number / 2:3,
        / common / 3:bstr .cbor ({
            / components / 2:[
                [h'00']
            ],
            / common-sequence / 4:bstr .cbor ([
                / directive-override-parameters / 20,{
                    / vendor-id /
1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf-
be9d-e663e4d41ffe /,
                    / class-id / 2:h'1492af1425695e48bf429b2d51f2ab45'
/ 1492af14-2569-5e48-bf42-9b2d51f2ab45 /,
                } ,
                / directive-try-each / 15,[
                    bstr .cbor ([
                        / directive-override-parameters / 20,{
                            / offset / 5:33792,
                        } ,
                        / condition-component-offset / 5,5 ,
                        / directive-override-parameters / 20,{
                            / image-digest / 3:bstr .cbor ([
                                / algorithm-id / 2 / "sha256" /,
                                / digest-bytes /
h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210'
                            ]),
                            / image-size / 14:34768,
                        }
                    ]) ,
                    bstr .cbor ([
                        / directive-override-parameters / 20,{
                            / offset / 5:541696,
                        } ,
                        / condition-component-offset / 5,5 ,
                        / directive-override-parameters / 20,{
                            / image-digest / 3:bstr .cbor ([
                                / algorithm-id / 2 / "sha256" /,
                                / digest-bytes /
h'0123456789abcdeffedcba987654321000112233445566778899aabbccddeeff'
                            ]),
                            / image-size / 14:76834,
                        }
                    ])
                ] ,
                / condition-vendor-identifier / 1,15 ,
                / condition-class-identifier / 2,15
            ]),
        }),
        / install / 9:bstr .cbor ([
            / directive-try-each / 15,[
                bstr .cbor ([
                    / directive-set-parameters / 19,{
                        / offset / 5:33792,
                    } ,
                    / condition-component-offset / 5,5 ,
                    / directive-set-parameters / 19,{
                        / uri / 21:'http://example.com/file1.bin',
                    }
                ]) ,
                bstr .cbor ([
                    / directive-set-parameters / 19,{
                        / offset / 5:541696,
                    } ,
                    / condition-component-offset / 5,5 ,
                    / directive-set-parameters / 19,{
                        / uri / 21:'http://example.com/file2.bin',
                    }
                ])
            ] ,
            / directive-fetch / 21,2 ,
            / condition-image-match / 3,15
        ]),
        / validate / 10:bstr .cbor ([
            / condition-image-match / 3,15
        ]),
    }),
}

Total size of Envelope without COSE authentication object: 330¶

Envelope:¶

a202582781582482025820ae0c1ea689c9800a843550f38796b6fdbd52a0
c78be5d26011d8e784da43d47c0359011ba5010102030358aaa202818141
000458a18814a20150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af
1425695e48bf429b2d51f2ab450f8258368614a105198400050514a20358
248202582000112233445566778899aabbccddeeff0123456789abcdeffe
dcba98765432100e1987d0583a8614a1051a00084400050514a203582482
0258200123456789abcdeffedcba987654321000112233445566778899aa
bbccddeeff0e1a00012c22010f020f095861860f82582a8613a105198400
050513a115781c687474703a2f2f6578616d706c652e636f6d2f66696c65
312e62696e582c8613a1051a00084400050513a115781c687474703a2f2f
6578616d706c652e636f6d2f66696c65322e62696e1502030f0a4382030f

Total size of Envelope with COSE authentication object: 443¶

Envelope with COSE authentication object:¶

a202589882582482025820ae0c1ea689c9800a843550f38796b6fdbd52a0
c78be5d26011d8e784da43d47c586fd28443a10126a0582482025820ae0c
1ea689c9800a843550f38796b6fdbd52a0c78be5d26011d8e784da43d47c
5840359960bae5a7de2457c8f48d3250d96d1af2d36e08764b62d76f8a3f
3041774b150b2c835bb1b2d7b1b2e629e1f08cc3b1b48fcebb8fb38182c1
16161e02b33f0359011ba5010102030358aaa202818141000458a18814a2
0150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf42
9b2d51f2ab450f8258368614a105198400050514a2035824820258200011
2233445566778899aabbccddeeff0123456789abcdeffedcba9876543210
0e1987d0583a8614a1051a00084400050514a20358248202582001234567
89abcdeffedcba987654321000112233445566778899aabbccddeeff0e1a
00012c22010f020f095861860f82582a8613a105198400050513a115781c
687474703a2f2f6578616d706c652e636f6d2f66696c65312e62696e582c
8613a1051a00084400050513a115781c687474703a2f2f6578616d706c65
2e636f6d2f66696c65322e62696e1502030f0a4382030f

B.5. Example 4: Load and Decompress from External Storage

This example covers the following templates:¶

• Compatibility Check (Section 7.1)¶
• Secure Boot (Section 7.2)¶
• Firmware Download (Section 7.3)¶
• Install (Section 7.4)¶
• Load & Decompress (Section 7.8)¶

{
    / authentication-wrapper / 2:bstr .cbor ({        digest: bstr
.cbor ([
            / algorithm-id / 2 / "sha256" /,
            / digest-bytes /
h'4b4c7c8c0fda76c9c9591a9db160918e2b3c96a58b0a5e4984fd4e8f9359a928'
        ])        signatures: [
            bstr .cbor (18([
                    / protected / bstr .cbor ({
                        / alg / 1:-7 / "ES256" /,
                    }),
                    / unprotected / {
                    },
                    / payload / bstr .cbor ([
                        / algorithm-id / 2 / "sha256" /,
                        / digest-bytes /
h'4b4c7c8c0fda76c9c9591a9db160918e2b3c96a58b0a5e4984fd4e8f9359a928'
                    ]),
                    / signature / h'd721cb3415f27cfeb8ef066bb6312ba758
32b57410a0c700de71cf8004ea23b9dd3c912a99fab111e9b8f2cc55c7dffcc37012de
cf72e44f69b3d3db8cc98cb6'
                ]))
        ]
    }),
    / manifest / 3:bstr .cbor ({
        / manifest-version / 1:1,
        / manifest-sequence-number / 2:4,
        / common / 3:bstr .cbor ({
            / components / 2:[
                [h'00'] ,
                [h'02'] ,
                [h'01']
            ],
            / common-sequence / 4:bstr .cbor ([
                / directive-set-component-index / 12,0 ,
                / 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:bstr .cbor ([
                        / algorithm-id / 2 / "sha256" /,
                        / digest-bytes /
h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210'
                    ]),
                    / image-size / 14:34768,
                } ,
                / condition-vendor-identifier / 1,15 ,
                / condition-class-identifier / 2,15
            ]),
        }),
        / payload-fetch / 8:bstr .cbor ([
            / directive-set-component-index / 12,1 ,
            / directive-set-parameters / 19,{
                / uri / 21:'http://example.com/file.bin',
            } ,
            / directive-fetch / 21,2 ,
            / condition-image-match / 3,15
        ]),
        / install / 9:bstr .cbor ([
            / directive-set-component-index / 12,0 ,
            / directive-set-parameters / 19,{
                / source-component / 22:1 / [h'02'] /,
            } ,
            / directive-copy / 22,2 ,
            / condition-image-match / 3,15
        ]),
        / validate / 10:bstr .cbor ([
            / directive-set-component-index / 12,0 ,
            / condition-image-match / 3,15
        ]),
        / load / 11:bstr .cbor ([
            / directive-set-component-index / 12,2 ,
            / directive-set-parameters / 19,{
                / image-digest / 3:bstr .cbor ([
                    / algorithm-id / 2 / "sha256" /,
                    / digest-bytes /
h'0123456789abcdeffedcba987654321000112233445566778899aabbccddeeff'
                ]),
                / image-size / 14:76834,
                / source-component / 22:0 / [h'00'] /,
                / compression-info / 19:1 / "gzip" /,
            } ,
            / directive-copy / 22,2 ,
            / condition-image-match / 3,15
        ]),
        / run / 12:bstr .cbor ([
            / directive-set-component-index / 12,2 ,
            / directive-run / 23,2
        ]),
    }),
}

Total size of Envelope without COSE authentication object: 287¶

Envelope:¶

a2025827815824820258204b4c7c8c0fda76c9c9591a9db160918e2b3c96
a58b0a5e4984fd4e8f9359a9280358f1a801010204035867a20283814100
814102814101045858880c0014a40150fa6b4a53d5ad5fdfbe9de663e4d4
1ffe02501492af1425695e48bf429b2d51f2ab4503582482025820001122
33445566778899aabbccddeeff0123456789abcdeffedcba98765432100e
1987d0010f020f085827880c0113a115781b687474703a2f2f6578616d70
6c652e636f6d2f66696c652e62696e1502030f094b880c0013a116011602
030f0a45840c00030f0b583a880c0213a4035824820258200123456789ab
cdeffedcba987654321000112233445566778899aabbccddeeff0e1a0001
2c22130116001602030f0c45840c021702

Total size of Envelope with COSE authentication object: 400¶

Envelope with COSE authentication object:¶

a2025898825824820258204b4c7c8c0fda76c9c9591a9db160918e2b3c96
a58b0a5e4984fd4e8f9359a928586fd28443a10126a05824820258204b4c
7c8c0fda76c9c9591a9db160918e2b3c96a58b0a5e4984fd4e8f9359a928
5840d721cb3415f27cfeb8ef066bb6312ba75832b57410a0c700de71cf80
04ea23b9dd3c912a99fab111e9b8f2cc55c7dffcc37012decf72e44f69b3
d3db8cc98cb60358f1a801010204035867a2028381410081410281410104
5858880c0014a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af
1425695e48bf429b2d51f2ab450358248202582000112233445566778899
aabbccddeeff0123456789abcdeffedcba98765432100e1987d0010f020f
085827880c0113a115781b687474703a2f2f6578616d706c652e636f6d2f
66696c652e62696e1502030f094b880c0013a116011602030f0a45840c00
030f0b583a880c0213a4035824820258200123456789abcdeffedcba9876
54321000112233445566778899aabbccddeeff0e1a00012c221301160016
02030f0c45840c021702

B.6. Example 5: Two Images

This example covers the following templates:¶

• Compatibility Check (Section 7.1)¶
• Secure Boot (Section 7.2)¶
• Firmware Download (Section 7.3)¶

Furthermore, it shows using these templates with two images.¶

{
    / authentication-wrapper / 2:bstr .cbor ({        digest: bstr
.cbor ([
            / algorithm-id / 2 / "sha256" /,
            / digest-bytes /
h'de7c7927a15bd2eda59cab1512875f17c9f1e9e23885ce1ac6d671eefcefa37a'
        ])        signatures: [
            bstr .cbor (18([
                    / protected / bstr .cbor ({
                        / alg / 1:-7 / "ES256" /,
                    }),
                    / unprotected / {
                    },
                    / payload / bstr .cbor ([
                        / algorithm-id / 2 / "sha256" /,
                        / digest-bytes /
h'de7c7927a15bd2eda59cab1512875f17c9f1e9e23885ce1ac6d671eefcefa37a'
                    ]),
                    / signature / h'e71e332c985fb0479f296685669d05348b
cdba8e186f25a5418f4682ea168df61661f54bf48f964577225ed455b22d277dd94de8
7c57f1baceedd6719f3d56ec'
                ]))
        ]
    }),
    / manifest / 3:bstr .cbor ({
        / manifest-version / 1:1,
        / manifest-sequence-number / 2:5,
        / common / 3:bstr .cbor ({
            / components / 2:[
                [h'00'] ,
                [h'01']
            ],
            / common-sequence / 4:bstr .cbor ([
                / directive-set-component-index / 12,0 ,
                / 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:bstr .cbor ([
                        / algorithm-id / 2 / "sha256" /,
                        / digest-bytes /
h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210'
                    ]),
                    / image-size / 14:34768,
                } ,
                / condition-vendor-identifier / 1,15 ,
                / condition-class-identifier / 2,15 ,
                / directive-set-component-index / 12,1 ,
                / directive-override-parameters / 20,{
                    / image-digest / 3:bstr .cbor ([
                        / algorithm-id / 2 / "sha256" /,
                        / digest-bytes /
h'0123456789abcdeffedcba987654321000112233445566778899aabbccddeeff'
                    ]),
                    / image-size / 14:76834,
                }
            ]),
        }),
        / install / 9:bstr .cbor ([
            / directive-set-component-index / 12,0 ,
            / directive-set-parameters / 19,{
                / uri / 21:'http://example.com/file1.bin',
            } ,
            / directive-fetch / 21,2 ,
            / condition-image-match / 3,15 ,
            / directive-set-component-index / 12,1 ,
            / directive-set-parameters / 19,{
                / uri / 21:'http://example.com/file2.bin',
            } ,
            / directive-fetch / 21,2 ,
            / condition-image-match / 3,15
        ]),
        / validate / 10:bstr .cbor ([
            / directive-set-component-index / 12,0 ,
            / condition-image-match / 3,15 ,
            / directive-set-component-index / 12,1 ,
            / condition-image-match / 3,15
        ]),
        / run / 12:bstr .cbor ([
            / directive-set-component-index / 12,0 ,
            / directive-run / 23,2
        ]),
    }),
}

Total size of Envelope without COSE authentication object: 304¶

Envelope:¶

a202582781582482025820de7c7927a15bd2eda59cab1512875f17c9f1e9
e23885ce1ac6d671eefcefa37a03590101a601010205035895a202828141
008141010458898c0c0014a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe
02501492af1425695e48bf429b2d51f2ab45035824820258200011223344
5566778899aabbccddeeff0123456789abcdeffedcba98765432100e1987
d0010f020f0c0114a2035824820258200123456789abcdeffedcba987654
321000112233445566778899aabbccddeeff0e1a00012c2209584f900c00
13a115781c687474703a2f2f6578616d706c652e636f6d2f66696c65312e
62696e1502030f0c0113a115781c687474703a2f2f6578616d706c652e63
6f6d2f66696c65322e62696e1502030f0a49880c00030f0c01030f0c4584
0c001702

Total size of Envelope with COSE authentication object: 417¶

Envelope with COSE authentication object:¶

a202589882582482025820de7c7927a15bd2eda59cab1512875f17c9f1e9
e23885ce1ac6d671eefcefa37a586fd28443a10126a0582482025820de7c
7927a15bd2eda59cab1512875f17c9f1e9e23885ce1ac6d671eefcefa37a
5840e71e332c985fb0479f296685669d05348bcdba8e186f25a5418f4682
ea168df61661f54bf48f964577225ed455b22d277dd94de87c57f1baceed
d6719f3d56ec03590101a601010205035895a20282814100814101045889
8c0c0014a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425
695e48bf429b2d51f2ab450358248202582000112233445566778899aabb
ccddeeff0123456789abcdeffedcba98765432100e1987d0010f020f0c01
14a2035824820258200123456789abcdeffedcba98765432100011223344
5566778899aabbccddeeff0e1a00012c2209584f900c0013a115781c6874
74703a2f2f6578616d706c652e636f6d2f66696c65312e62696e1502030f
0c0113a115781c687474703a2f2f6578616d706c652e636f6d2f66696c65
322e62696e1502030f0a49880c00030f0c01030f0c45840c001702

C.1. C.1 Design Rationale: Envelope

The Envelope is used instead of a COSE structure for several reasons:¶

1. This enables the use of Severable Elements (Section 8.8)¶
2. This enables modular processing of manifests, particularly with large signatures.¶
3. This enables multiple authentication schemes.¶
4. This allows integrity verification by a dependent to be unaffected by adding or removing authentication structures.¶

Modular processing is important because it allows a Manifest Processor to iterate forward over an Envelope, processing Delegation Chains and Authentication Blocks, retaining only intermediate values, without any need to seek forward and backwards in a stream until it gets to the Manifest itself. This allows the use of large, Post-Quantum signatures without requiring retention of the signature itself, or seeking forward and back.¶

Four authentication objects are supported by the Envelope:¶

• COSE_Sign_Tagged¶
• COSE_Sign1_Tagged¶
• COSE_Mac_Tagged¶
• COSE_Mac0_Tagged¶

The SUIT Envelope allows an Update Authority or intermediary to mix and match any number of different authentication blocks it wants without any concern for modifying the integrity of another authentication block. This also allows the addition or removal of an authentication blocks without changing the integrity check of the Manifest, which is important for dependency handling. See Section 6.2¶

C.2. C.2 Byte String Wrappers

Byte string wrappers are used in several places in the suit manifest. The primary reason for wrappers it to limit the parser extent when invoked at different times, with a possible loss of context.¶

The elements of the suit envelope are wrapped both to set the extents used by the parser and to simplify integrity checks by clearly defining the length of each element.¶

The common block is re-parsed in order to find components identifiers from their indices, to find dependency prefixes and digests from their identifiers, and to find the common sequence. The common sequence is wrapped so that it matches other sequences, simplifying the code path.¶

A severed SUIT command sequence will appear in the envelope, so it must be wrapped as with all envelope elements. For consistency, command sequences are also wrapped in the manifest. This also allows the parser to discern the difference between a command sequence and a SUIT_Digest.¶

Parameters that are structured types (arrays and maps) are also wrapped in a bstr. This is so that parser extents can be set correctly using only a reference to the beginning of the parameter. This enables a parser to store a simple list of references to parameters that can be retrieved when needed.¶