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 SUIT Digest Container, see 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 Slot A¶
    • Check Slot 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 Slot B¶
    • Check Slot 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 Slot A¶
    • Check Slot 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 Slot B¶
    • Check Slot 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 Slot 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 SUIT Digest Container (see Section 10) and one or more cryptographic authentication wrappers for the Manifest. These blocks are implemented as COSE_Mac_Tagged or COSE_Sign_Tagged structures. 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.9 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.¶

107({
        / authentication-wrapper / 2:<<[
            digest: <<[
                / algorithm-id / -16 / "sha256" /,
                / digest-bytes /
h'a6c4590ac53043a98e8c4106e1e31b305516d7cf0a655eddfac6d45c810e036a'
            ]>>,
            signature: <<18([
                    / protected / <<{
                        / alg / 1:-7 / "ES256" /,
                    }>>,
                    / unprotected / {
                    },
                    / payload / F6 / nil /,
                    / signature / h'd11a2dd9610fb62a707335f58407922570
9f96e8117e7eeed98a2f207d05c8ecfba1755208f6abea977b8a6efe3bc2ca3215e119
3be201467d052b42db6b7287'
                ])>>
            ]
        ]>>,
        / manifest / 3:<<{
            / manifest-version / 1:1,
            / manifest-sequence-number / 2:0,
            / common / 3:<<{
                / components / 2:[
                    [h'00']
                ],
                / common-sequence / 4:<<[
                    / 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 / -16 / "sha256" /,
                            / digest-bytes /
h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210'
                        ]>>,
                        / image-size / 14:34768,
                    } ,
                    / condition-vendor-identifier / 1,15 ,
                    / condition-class-identifier / 2,15
                ]>>,
            }>>,
            / validate / 10:<<[
                / condition-image-match / 3,15
            ]>>,
            / run / 12:<<[
                / directive-run / 23,2
            ]>>,
        }>>,
    })

Total size of Envelope without COSE authentication object: 161¶

Envelope:¶

d86ba2025827815824822f5820a6c4590ac53043a98e8c4106e1e31b3055
16d7cf0a655eddfac6d45c810e036a035871a50101020003585fa2028181
41000458568614a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492
af1425695e48bf429b2d51f2ab45035824822f5820001122334455667788
99aabbccddeeff0123456789abcdeffedcba98765432100e1987d0010f02
0f0a4382030f0c43821702

Total size of Envelope with COSE authentication object: 237¶

Envelope with COSE authentication object:¶

d86ba2025873825824822f5820a6c4590ac53043a98e8c4106e1e31b3055
16d7cf0a655eddfac6d45c810e036a584ad28443a10126a0f65840d11a2d
d9610fb62a707335f584079225709f96e8117e7eeed98a2f207d05c8ecfb
a1755208f6abea977b8a6efe3bc2ca3215e1193be201467d052b42db6b72
87035871a50101020003585fa202818141000458568614a40150fa6b4a53
d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab45
035824822f582000112233445566778899aabbccddeeff0123456789abcd
effedcba98765432100e1987d0010f020f0a4382030f0c43821702

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.¶

107({
        / authentication-wrapper / 2:<<[
            digest: <<[
                / algorithm-id / -16 / "sha256" /,
                / digest-bytes /
h'60c61d6eb7a1aaeddc49ce8157a55cff0821537eeee77a4ded44155b03045132'
            ]>>,
            signature: <<18([
                    / protected / <<{
                        / alg / 1:-7 / "ES256" /,
                    }>>,
                    / unprotected / {
                    },
                    / payload / F6 / nil /,
                    / signature / h'5249dacaf0ffc8326931b09586eb7e3769
e71a0e6a40ad8153db4980db9b05bd1742ddb46085fa11e62b65a79895c12ac7abe266
8ccc5afdd74466aed7bca389'
                ])>>
            ]
        ]>>,
        / manifest / 3:<<{
            / manifest-version / 1:1,
            / manifest-sequence-number / 2:1,
            / common / 3:<<{
                / components / 2:[
                    [h'00']
                ],
                / common-sequence / 4:<<[
                    / 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 / -16 / "sha256" /,
                            / digest-bytes /
h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210'
                        ]>>,
                        / image-size / 14:34768,
                    } ,
                    / condition-vendor-identifier / 1,15 ,
                    / condition-class-identifier / 2,15
                ]>>,
            }>>,
            / install / 9:<<[
                / directive-set-parameters / 19,{
                    / uri / 21:'http://example.com/file.bin',
                } ,
                / directive-fetch / 21,2 ,
                / condition-image-match / 3,15
            ]>>,
            / validate / 10:<<[
                / condition-image-match / 3,15
            ]>>,
        }>>,
    })

Total size of Envelope without COSE authentication object: 196¶

Envelope:¶

d86ba2025827815824822f582060c61d6eb7a1aaeddc49ce8157a55cff08
21537eeee77a4ded44155b03045132035894a50101020103585fa2028181
41000458568614a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492
af1425695e48bf429b2d51f2ab45035824822f5820001122334455667788
99aabbccddeeff0123456789abcdeffedcba98765432100e1987d0010f02
0f0958258613a115781b687474703a2f2f6578616d706c652e636f6d2f66
696c652e62696e1502030f0a4382030f

Total size of Envelope with COSE authentication object: 272¶

Envelope with COSE authentication object:¶

d86ba2025873825824822f582060c61d6eb7a1aaeddc49ce8157a55cff08
21537eeee77a4ded44155b03045132584ad28443a10126a0f658405249da
caf0ffc8326931b09586eb7e3769e71a0e6a40ad8153db4980db9b05bd17
42ddb46085fa11e62b65a79895c12ac7abe2668ccc5afdd74466aed7bca3
89035894a50101020103585fa202818141000458568614a40150fa6b4a53
d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab45
035824822f582000112233445566778899aabbccddeeff0123456789abcd
effedcba98765432100e1987d0010f020f0958258613a115781b68747470
3a2f2f6578616d706c652e636f6d2f66696c652e62696e1502030f0a4382
030f

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).¶

107({
        / authentication-wrapper / 2:<<[
            digest: <<[
                / algorithm-id / -16 / "sha256" /,
                / digest-bytes /
h'e45dcdb2074b951f1c88b866469939c2a83ed433a31fc7dfcb3f63955bd943ec'
            ]>>,
            signature: <<18([
                    / protected / <<{
                        / alg / 1:-7 / "ES256" /,
                    }>>,
                    / unprotected / {
                    },
                    / payload / F6 / nil /,
                    / signature / h'b4fd3a6a18fe1062573488cf24ac96ef9f
30ac746696e50be96533b356b8156e4332587fe6f4e8743ae525d72005fddd4c1213d5
5a8061b2ce67b83640f4777c'
                ])>>
            ]
        ]>>,
        / manifest / 3:<<{
            / manifest-version / 1:1,
            / manifest-sequence-number / 2:2,
            / common / 3:<<{
                / components / 2:[
                    [h'00']
                ],
                / common-sequence / 4:<<[
                    / 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 / -16 / "sha256" /,
                            / digest-bytes /
h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210'
                        ]>>,
                        / image-size / 14:34768,
                    } ,
                    / condition-vendor-identifier / 1,15 ,
                    / condition-class-identifier / 2,15
                ]>>,
            }>>,
            / install / 9:[
                / algorithm-id / -16 / "sha256" /,
                / digest-bytes /
h'3ee96dc79641970ae46b929ccf0b72ba9536dd846020dbdc9f949d84ea0e18d2'
            ],
            / validate / 10:<<[
                / condition-image-match / 3,15
            ]>>,
            / run / 12:<<[
                / directive-run / 23,2
            ]>>,
            / text / 13:[
                / algorithm-id / -16 / "sha256" /,
                / digest-bytes /
h'2bfc4d0cc6680be7dd9f5ca30aa2bb5d1998145de33d54101b80e2ca49faf918'
            ],
        }>>,
        / install / 9:<<[
            / 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:<<{
            [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: 235¶

Envelope:¶

d86ba2025827815824822f5820e45dcdb2074b951f1c88b866469939c2a8
3ed433a31fc7dfcb3f63955bd943ec0358bba70101020203585fa2028181
41000458568614a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492
af1425695e48bf429b2d51f2ab45035824822f5820001122334455667788
99aabbccddeeff0123456789abcdeffedcba98765432100e1987d0010f02
0f09822f58203ee96dc79641970ae46b929ccf0b72ba9536dd846020dbdc
9f949d84ea0e18d20a4382030f0c438217020d822f58202bfc4d0cc6680b
e7dd9f5ca30aa2bb5d1998145de33d54101b80e2ca49faf918

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

Envelope:¶

d86ba2025873825824822f5820e45dcdb2074b951f1c88b866469939c2a8
3ed433a31fc7dfcb3f63955bd943ec584ad28443a10126a0f65840b4fd3a
6a18fe1062573488cf24ac96ef9f30ac746696e50be96533b356b8156e43
32587fe6f4e8743ae525d72005fddd4c1213d55a8061b2ce67b83640f477
7c0358bba70101020203585fa202818141000458568614a40150fa6b4a53
d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab45
035824822f582000112233445566778899aabbccddeeff0123456789abcd
effedcba98765432100e1987d0010f020f09822f58203ee96dc79641970a
e46b929ccf0b72ba9536dd846020dbdc9f949d84ea0e18d20a4382030f0c
438217020d822f58202bfc4d0cc6680be7dd9f5ca30aa2bb5d1998145de3
3d54101b80e2ca49faf918

Total size of Envelope with COSE authentication object and Severable Elements: 894¶

Envelope with COSE authentication object:¶

d86ba4025873825824822f5820e45dcdb2074b951f1c88b866469939c2a8
3ed433a31fc7dfcb3f63955bd943ec584ad28443a10126a0f65840b4fd3a
6a18fe1062573488cf24ac96ef9f30ac746696e50be96533b356b8156e43
32587fe6f4e8743ae525d72005fddd4c1213d55a8061b2ce67b83640f477
7c0358bba70101020203585fa202818141000458568614a40150fa6b4a53
d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab45
035824822f582000112233445566778899aabbccddeeff0123456789abcd
effedcba98765432100e1987d0010f020f09822f58203ee96dc79641970a
e46b929ccf0b72ba9536dd846020dbdc9f949d84ea0e18d20a4382030f0c
438217020d822f58202bfc4d0cc6680be7dd9f5ca30aa2bb5d1998145de3
3d54101b80e2ca49faf91809583c8613a1157832687474703a2f2f657861
6d706c652e636f6d2f766572792f6c6f6e672f706174682f746f2f66696c
652f66696c652e62696e1502030f0d590204a20179019d2323204578616d
706c6520323a2053696d756c74616e656f757320446f776e6c6f61642c20
496e7374616c6c6174696f6e2c2053656375726520426f6f742c20536576
65726564204669656c64730a0a2020202054686973206578616d706c6520
636f766572732074686520666f6c6c6f77696e672074656d706c61746573
3a0a202020200a202020202a20436f6d7061746962696c69747920436865
636b20287b7b74656d706c6174652d636f6d7061746962696c6974792d63
6865636b7d7d290a202020202a2053656375726520426f6f7420287b7b74
656d706c6174652d7365637572652d626f6f747d7d290a202020202a2046
69726d7761726520446f776e6c6f616420287b7b6669726d776172652d64
6f776e6c6f61642d74656d706c6174657d7d290a202020200a2020202054
686973206578616d706c6520616c736f2064656d6f6e7374726174657320
736576657261626c6520656c656d656e747320287b7b6f76722d73657665
7261626c657d7d292c20616e64207465787420287b7b6d616e6966657374
2d6469676573742d746578747d7d292e814100a2036761726d2e636f6d05
78525468697320636f6d706f6e656e7420697320612064656d6f6e737472
6174696f6e2e205468652064696765737420697320612073616d706c6520
7061747465726e2c206e6f742061207265616c206f6e652e

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)¶

107({
        / authentication-wrapper / 2:<<[
            digest: <<[
                / algorithm-id / -16 / "sha256" /,
                / digest-bytes /
h'7c9b3cb72c262608a42f944d59d659ff2b801c78af44def51b8ff51e9f45721b'
            ]>>,
            signature: <<18([
                    / protected / <<{
                        / alg / 1:-7 / "ES256" /,
                    }>>,
                    / unprotected / {
                    },
                    / payload / F6 / nil /,
                    / signature / h'e33d618df0ad21e609529ab1a876afb231
faff1d6a3189b5360324c2794250b87cf00cf83be50ea17dc721ca85393cd8e839a066
d5dec0ad87a903ab31ea9afa'
                ])>>
            ]
        ]>>,
        / manifest / 3:<<{
            / manifest-version / 1:1,
            / manifest-sequence-number / 2:3,
            / common / 3:<<{
                / components / 2:[
                    [h'00']
                ],
                / common-sequence / 4:<<[
                    / 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,[
                        <<[
                            / directive-override-parameters / 20,{
                                / offset / 5:33792,
                            } ,
                            / condition-component-offset / 5,5 ,
                            / directive-override-parameters / 20,{
                                / image-digest / 3:<<[
                                    / algorithm-id / -16 / "sha256" /,
                                    / digest-bytes /
h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210'
                                ]>>,
                                / image-size / 14:34768,
                            }
                        ]>> ,
                        <<[
                            / directive-override-parameters / 20,{
                                / offset / 5:541696,
                            } ,
                            / condition-component-offset / 5,5 ,
                            / directive-override-parameters / 20,{
                                / image-digest / 3:<<[
                                    / algorithm-id / -16 / "sha256" /,
                                    / digest-bytes /
h'0123456789abcdeffedcba987654321000112233445566778899aabbccddeeff'
                                ]>>,
                                / image-size / 14:76834,
                            }
                        ]>>
                    ] ,
                    / condition-vendor-identifier / 1,15 ,
                    / condition-class-identifier / 2,15
                ]>>,
            }>>,
            / install / 9:<<[
                / directive-try-each / 15,[
                    <<[
                        / directive-set-parameters / 19,{
                            / offset / 5:33792,
                        } ,
                        / condition-component-offset / 5,5 ,
                        / directive-set-parameters / 19,{
                            / uri / 21:'http://example.com/file1.bin',
                        }
                    ]>> ,
                    <<[
                        / 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:<<[
                / condition-image-match / 3,15
            ]>>,
        }>>,
    })

Total size of Envelope without COSE authentication object: 332¶

Envelope:¶

d86ba2025827815824822f58207c9b3cb72c262608a42f944d59d659ff2b
801c78af44def51b8ff51e9f45721b0359011ba5010102030358aaa20281
8141000458a18814a20150fa6b4a53d5ad5fdfbe9de663e4d41ffe025014
92af1425695e48bf429b2d51f2ab450f8258368614a105198400050514a2
035824822f582000112233445566778899aabbccddeeff0123456789abcd
effedcba98765432100e1987d0583a8614a1051a00084400050514a20358
24822f58200123456789abcdeffedcba9876543210001122334455667788
99aabbccddeeff0e1a00012c22010f020f095861860f82582a8613a10519
8400050513a115781c687474703a2f2f6578616d706c652e636f6d2f6669
6c65312e62696e582c8613a1051a00084400050513a115781c687474703a
2f2f6578616d706c652e636f6d2f66696c65322e62696e1502030f0a4382
030f

Total size of Envelope with COSE authentication object: 408¶

Envelope with COSE authentication object:¶

d86ba2025873825824822f58207c9b3cb72c262608a42f944d59d659ff2b
801c78af44def51b8ff51e9f45721b584ad28443a10126a0f65840e33d61
8df0ad21e609529ab1a876afb231faff1d6a3189b5360324c2794250b87c
f00cf83be50ea17dc721ca85393cd8e839a066d5dec0ad87a903ab31ea9a
fa0359011ba5010102030358aaa202818141000458a18814a20150fa6b4a
53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab
450f8258368614a105198400050514a2035824822f582000112233445566
778899aabbccddeeff0123456789abcdeffedcba98765432100e1987d058
3a8614a1051a00084400050514a2035824822f58200123456789abcdeffe
dcba987654321000112233445566778899aabbccddeeff0e1a00012c2201
0f020f095861860f82582a8613a105198400050513a115781c687474703a
2f2f6578616d706c652e636f6d2f66696c65312e62696e582c8613a1051a
00084400050513a115781c687474703a2f2f6578616d706c652e636f6d2f
66696c65322e62696e1502030f0a4382030f

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)¶

107({
        / authentication-wrapper / 2:<<[
            digest: <<[
                / algorithm-id / -16 / "sha256" /,
                / digest-bytes /
h'15736702a00f510805dcf89d6913a2cfb417ed414faa760f974d6755c68ba70a'
            ]>>,
            signature: <<18([
                    / protected / <<{
                        / alg / 1:-7 / "ES256" /,
                    }>>,
                    / unprotected / {
                    },
                    / payload / F6 / nil /,
                    / signature / h'3ada2532326d512132c388677798c24ffd
cc979bfae2a26b19c8c8bbf511fd7dd85f1501662c1a9e1976b759c4019bab44ba5434
efb45d3868aedbca593671f3'
                ])>>
            ]
        ]>>,
        / manifest / 3:<<{
            / manifest-version / 1:1,
            / manifest-sequence-number / 2:4,
            / common / 3:<<{
                / components / 2:[
                    [h'00'] ,
                    [h'02'] ,
                    [h'01']
                ],
                / common-sequence / 4:<<[
                    / 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:<<[
                            / algorithm-id / -16 / "sha256" /,
                            / digest-bytes /
h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210'
                        ]>>,
                        / image-size / 14:34768,
                    } ,
                    / condition-vendor-identifier / 1,15 ,
                    / condition-class-identifier / 2,15
                ]>>,
            }>>,
            / payload-fetch / 8:<<[
                / 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:<<[
                / 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:<<[
                / directive-set-component-index / 12,0 ,
                / condition-image-match / 3,15
            ]>>,
            / load / 11:<<[
                / directive-set-component-index / 12,2 ,
                / directive-set-parameters / 19,{
                    / image-digest / 3:<<[
                        / algorithm-id / -16 / "sha256" /,
                        / digest-bytes /
h'0123456789abcdeffedcba987654321000112233445566778899aabbccddeeff'
                    ]>>,
                    / image-size / 14:76834,
                    / source-component / 22:0 / [h'00'] /,
                    / compression-info / 19:<<{
                        / compression-algorithm / 1:1 / "gzip" /,
                    }>>,
                } ,
                / directive-copy / 22,2 ,
                / condition-image-match / 3,15
            ]>>,
            / run / 12:<<[
                / directive-set-component-index / 12,2 ,
                / directive-run / 23,2
            ]>>,
        }>>,
    })

Total size of Envelope without COSE authentication object: 292¶

Envelope:¶

d86ba2025827815824822f582015736702a00f510805dcf89d6913a2cfb4
17ed414faa760f974d6755c68ba70a0358f4a801010204035867a2028381
4100814102814101045858880c0014a40150fa6b4a53d5ad5fdfbe9de663
e4d41ffe02501492af1425695e48bf429b2d51f2ab45035824822f582000
112233445566778899aabbccddeeff0123456789abcdeffedcba98765432
100e1987d0010f020f085827880c0113a115781b687474703a2f2f657861
6d706c652e636f6d2f66696c652e62696e1502030f094b880c0013a11601
1602030f0a45840c00030f0b583d880c0213a4035824822f582001234567
89abcdeffedcba987654321000112233445566778899aabbccddeeff0e1a
00012c221343a1010116001602030f0c45840c021702

Total size of Envelope with COSE authentication object: 368¶

Envelope with COSE authentication object:¶

d86ba2025873825824822f582015736702a00f510805dcf89d6913a2cfb4
17ed414faa760f974d6755c68ba70a584ad28443a10126a0f658403ada25
32326d512132c388677798c24ffdcc979bfae2a26b19c8c8bbf511fd7dd8
5f1501662c1a9e1976b759c4019bab44ba5434efb45d3868aedbca593671
f30358f4a801010204035867a20283814100814102814101045858880c00
14a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48
bf429b2d51f2ab45035824822f582000112233445566778899aabbccddee
ff0123456789abcdeffedcba98765432100e1987d0010f020f085827880c
0113a115781b687474703a2f2f6578616d706c652e636f6d2f66696c652e
62696e1502030f094b880c0013a116011602030f0a45840c00030f0b583d
880c0213a4035824822f58200123456789abcdeffedcba98765432100011
2233445566778899aabbccddeeff0e1a00012c221343a101011600160203
0f0c45840c021702

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.¶

107({
        / authentication-wrapper / 2:<<[
            digest: <<[
                / algorithm-id / -16 / "sha256" /,
                / digest-bytes /
h'd1e73f16e4126007bc4d804cd33b0209fbab34728e60ee8c00f3387126748dd2'
            ]>>,
            signature: <<18([
                    / protected / <<{
                        / alg / 1:-7 / "ES256" /,
                    }>>,
                    / unprotected / {
                    },
                    / payload / F6 / nil /,
                    / signature / h'b7ae0a46a28f02e25cda6d9a255bbaf863
30141831fae5a78012d648bc6cee55102e0f1890bdeacc3adaa4fae0560f83a45eecae
65cabce642f56d84ab97ef8d'
                ])>>
            ]
        ]>>,
        / manifest / 3:<<{
            / manifest-version / 1:1,
            / manifest-sequence-number / 2:5,
            / common / 3:<<{
                / components / 2:[
                    [h'00'] ,
                    [h'01']
                ],
                / common-sequence / 4:<<[
                    / 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:<<[
                            / algorithm-id / -16 / "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:<<[
                            / algorithm-id / -16 / "sha256" /,
                            / digest-bytes /
h'0123456789abcdeffedcba987654321000112233445566778899aabbccddeeff'
                        ]>>,
                        / image-size / 14:76834,
                    }
                ]>>,
            }>>,
            / install / 9:<<[
                / 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:<<[
                / directive-set-component-index / 12,0 ,
                / condition-image-match / 3,15 ,
                / directive-set-component-index / 12,1 ,
                / condition-image-match / 3,15
            ]>>,
            / run / 12:<<[
                / directive-set-component-index / 12,0 ,
                / directive-run / 23,2
            ]>>,
        }>>,
    })

Total size of Envelope without COSE authentication object: 306¶

Envelope:¶

d86ba2025827815824822f5820d1e73f16e4126007bc4d804cd33b0209fb
ab34728e60ee8c00f3387126748dd203590101a601010205035895a20282
8141008141010458898c0c0014a40150fa6b4a53d5ad5fdfbe9de663e4d4
1ffe02501492af1425695e48bf429b2d51f2ab45035824822f5820001122
33445566778899aabbccddeeff0123456789abcdeffedcba98765432100e
1987d0010f020f0c0114a2035824822f58200123456789abcdeffedcba98
7654321000112233445566778899aabbccddeeff0e1a00012c2209584f90
0c0013a115781c687474703a2f2f6578616d706c652e636f6d2f66696c65
312e62696e1502030f0c0113a115781c687474703a2f2f6578616d706c65
2e636f6d2f66696c65322e62696e1502030f0a49880c00030f0c01030f0c
45840c001702

Total size of Envelope with COSE authentication object: 382¶

Envelope with COSE authentication object:¶

d86ba2025873825824822f5820d1e73f16e4126007bc4d804cd33b0209fb
ab34728e60ee8c00f3387126748dd2584ad28443a10126a0f65840b7ae0a
46a28f02e25cda6d9a255bbaf86330141831fae5a78012d648bc6cee5510
2e0f1890bdeacc3adaa4fae0560f83a45eecae65cabce642f56d84ab97ef
8d03590101a601010205035895a202828141008141010458898c0c0014a4
0150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf42
9b2d51f2ab45035824822f582000112233445566778899aabbccddeeff01
23456789abcdeffedcba98765432100e1987d0010f020f0c0114a2035824
822f58200123456789abcdeffedcba987654321000112233445566778899
aabbccddeeff0e1a00012c2209584f900c0013a115781c687474703a2f2f
6578616d706c652e636f6d2f66696c65312e62696e1502030f0c0113a115
781c687474703a2f2f6578616d706c652e636f6d2f66696c65322e62696e
1502030f0a49880c00030f0c01030f0c45840c001702

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.¶