<?xml version="1.0" encoding="UTF-8"?>
  <?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?>
  <!-- generated by https://github.com/cabo/kramdown-rfc2629 version 1.2.9 -->

<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
]>

<?rfc rfcedstyle="yes"?>
<?rfc toc="yes"?>
<?rfc tocindent="yes"?>
<?rfc sortrefs="yes"?>
<?rfc symrefs="yes"?>
<?rfc strict="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc text-list-symbols="-o*+"?>
<?rfc docmapping="yes"?>

<rfc ipr="pre5378Trust200902" docName="draft-ietf-suit-manifest-00" category="info">

  <front>
    <title abbrev="Firmware Manifest Format">SUIT CBOR manifest serialisation format</title>

    <author initials="B." surname="Moran" fullname="Brendan Moran">
      <organization>Arm Limited</organization>
      <address>
        <email>Brendan.Moran@arm.com</email>
      </address>
    </author>
    <author initials="H." surname="Tschofenig" fullname="Hannes Tschofenig">
      <organization>Arm Limited</organization>
      <address>
        <email>hannes.tschofenig@arm.com</email>
      </address>
    </author>
    <author initials="H." surname="Birkholz" fullname="Henk Birkholz">
      <organization>Fraunhofer SIT</organization>
      <address>
        <email>henk.birkholz@sit.fraunhofer.de</email>
      </address>
    </author>

    <date year="2019" month="October" day="21"/>

    <area>Security</area>
    <workgroup>SUIT</workgroup>
    <keyword>Internet-Draft</keyword>

    <abstract>


<t>This specification describes the format of a manifest.  A manifest is
a bundle of metadata about the firmware for an IoT device, where to
find the firmware, the devices to which it applies, and cryptographic
information protecting the manifest.</t>



    </abstract>


  </front>

  <middle>


<section anchor="introduction" title="Introduction">

<t>A firmware update mechanism is an essential security feature for IoT devices to deal with vulnerabilities. While the transport of firmware images to the devices themselves is important there are already various techniques available, such as the Lightweight Machine-to-Machine (LwM2M) protocol offering device management of IoT devices. Equally important is the inclusion of meta-data about the conveyed firmware image (in the form of a manifest) and the use of end-to-end security protection to detect modifications and (optionally) to make reverse engineering more difficult. End-to-end security allows the author, who builds the firmware image, to be sure that no other party (including potential adversaries) can install firmware updates on IoT devices without adequate privileges. This authorization process is ensured by the use of dedicated symmetric or asymmetric keys installed on the IoT device: for use cases where only integrity protection is required it is sufficient to install a trust anchor on the IoT device. For confidentiality protected firmware images it is additionally required to install either one or multiple symmetric or asymmetric keys on the IoT device. Starting security protection at the author is a risk mitigation technique so firmware images and manifests can be stored on untrusted respositories; it also reduces the scope of a compromise of any repository or intermediate system to be no worse than a denial of service.</t>

<t>It is assumed that the reader is familiar with the high-level firmware update architecture <xref target="Architecture"/>. This document is structured as follows: In <xref target="manifest-structure"/> we describe the main building blocks of the manifest and <xref target="manifest-cddl"/> contains the description of the CBOR of the manifest.</t>

<t>The SUIT manifest is heavily optimised for consumption by constrained devices. This means that it is not constructed as a conventional descriptive document, as described in <xref target="Behaviour"/>. This means that a user viewing the contents of the document will require tooling to view the contents in a more descriptive way.</t>

</section>
<section anchor="conventions-and-terminology" title="Conventions and Terminology">

<t>The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL
NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”,
“MAY”, and “OPTIONAL” in this document are to be interpreted as
described in BCP 14 <xref target="RFC2119"/> <xref target="RFC8174"/> when, and only when, they
appear in all capitals, as shown here.</t>

<t><list style="symbols">
  <t>SUIT: Sofware Update for the Internet of Things, the IETF working group for this standard.</t>
  <t>Payload: A piece of information to be delivered. Typically Firmware for the purposes of SUIT.</t>
  <t>Resource: A piece of information that is used to construct a payload.</t>
  <t>Manifest: A piece of information that describes one or more payloads, one or more resources, and the processors needed to transform resources into payloads.</t>
  <t>Update: One or more manifests that describe one or more payloads.</t>
  <t>Update Authority: The owner of a cryptographic key used to sign updates, trusted by recipient devices.</t>
  <t>Recipient: The system, typically an IoT device, that receives a manifest.</t>
  <t>Condition: A test for a property of the Recipient or its components.</t>
  <t>Directive: An action for the Recipient to perform.</t>
  <t>Command: A Condition or a Directive.</t>
</list></t>

</section>
<section anchor="suit-digest-container" title="SUIT digest container">
<t>RFC 8152 <xref target="RFC8152"/> provides containers for signature, MAC, and encryption, but no basic digest container. The container needed for a digest requires a type identifier and a container for the raw digest data. Some forms of digest may require additional parameters. These can be added following the digest. Algorithm identifiers defined in RFC 6920 <xref target="RFC6920"/> are reused for this digest container. This structure is described by the following CDDL:</t>

<figure><artwork><![CDATA[
SUIT_Digest = [
 suit-digest-algorithm-id : $suit-digest-algorithm-ids,
 suit-digest-bytes : bytes,
 ? suit-digest-parameters : any
]

; Named Information Hash Algorithm Identifiers
digest-algorithm-ids /= algorithm-id-sha256
digest-algorithm-ids /= algorithm-id-sha256-128
digest-algorithm-ids /= algorithm-id-sha256-120
digest-algorithm-ids /= algorithm-id-sha256-96
digest-algorithm-ids /= algorithm-id-sha256-64
digest-algorithm-ids /= algorithm-id-sha256-32
digest-algorithm-ids /= algorithm-id-sha384
digest-algorithm-ids /= algorithm-id-sha512
digest-algorithm-ids /= algorithm-id-sha3-224
digest-algorithm-ids /= algorithm-id-sha3-256
digest-algorithm-ids /= algorithm-id-sha3-384
digest-algorithm-ids /= algorithm-id-sha3-512
]]></artwork></figure>

</section>
<section anchor="distributing-firmware" title="Distributing firmware">
<t>Distributing firmware in a multi-party environment is a difficult operation. Each party requires a different subset of data. Some data may not be accessible to all parties. Multiple signatures may be required from parties with different authorities. This topic is covered in more depth in <xref target="Architecture"/></t>

</section>
<section anchor="workflow-of-a-device-applying-a-firmware-update" title="Workflow of a device applying a firmware update">
<t>The manifest is designed to work with a pull parser, where each section of the manifest is used in sequence. The expected workflow for a device installing an update can be broken down into 5 steps:</t>

<t><list style="numbers">
  <t>Verify the signature of the manifest</t>
  <t>Verify the applicability of the manifest</t>
  <t>Resolve dependencies</t>
  <t>Fetch payload(s)</t>
  <t>Install payload(s)</t>
</list></t>

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

<t><list style="numbers">
  <t>Verify image(s)</t>
  <t>Load image(s)</t>
  <t>Run image(s)</t>
</list></t>

<t>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.</t>

</section>
<section anchor="suit-manifest-goals" title="SUIT manifest goals">
<t>The manifest described in this document is intended to simplify the construction of constrained device firmware update solutions. It is also intended to allow update authors to describe complex update processes for complex devices.</t>

<t>Manifests implemented as descriptive documents require changes to the parser and the information model whenever a new feature is added. This is particularly accentuated when the parser is a fixed-function minimal parser (or a pull parser) such as the type that is typically used in a bootloader or in a constrained client. The issue is not as significant in devices that can use general purpose parsers.</t>

<t>The manifest detailed in this document aims to address these and more problems by changing the processing model from a piece of software that loads a manifest, interprets the data, then performs some actions, into a model in which the software performs exactly the operations stated in the manifest, in order. This allows the manifest to encode data in a way that matches precisely with what the parser expects. It also makes inflexible code, like a bootloader, more flexible in what it can do; because the manifest defines part of the “program,” the manifest’s execution defines part of the behaviour of the system. Further detail on this approach is covered in <xref target="Behaviour"/></t>

<t>The SUIT manifest can be used for a variety of purposes throughout its lifecycle. The manifest allows:</t>

<t><list style="numbers">
  <t>the Firmware Author to reason about releasing a firmware.</t>
  <t>the Network Operator to reason about compatibility of a firmware.</t>
  <t>the Device Operator to reason about the impact of a firmware.</t>
  <t>the Device Operator to manage distribution of firmware to devices.</t>
  <t>the Plant Manager to reason about timing and acceptance of firmware updates.</t>
  <t>the device to reason about the authority &amp; authenticity of a firmware prior to installation.</t>
  <t>the device to reason about the applicability of a firmware.</t>
  <t>the device to reason about the installation of a firmware.</t>
  <t>the device to reason about the authenticity of a firmware at boot.</t>
</list></t>

<t>Each of these uses happens at a different stage of the manifest lifecycle, so each has different requirements.</t>

<t>To verify authenticity at boot time, only the smallest portion of the manifest is required. This core part of the manifest describes only the fully installed firmware and any of its dependencies.</t>

</section>
<section anchor="suit-manifest-design-overview" title="SUIT manifest design overview">
<t>In order to provide flexible behaviour to constrained devices, while still allowing more powerful devices to use their full capabilities, the SUIT manifest takes a new approach, encoding the required behaviour of a Recipient device, instead of just presenting the information used to determine that behaviour. This gives benefits equivalent to those provided by a scripting language or byte code, with two substantial differences. First, the language is extremely high level, consisting of only the operations that a device may perform during update and secure boot of a firmware image. The language specifies behaviours in a linearised form, without branches or loops. Conditional processing is supported, and parallel and out-of-order processing may be performed by sufficiently capable devices.</t>

<t>By structuring the data in this way, the manifest processor becomes a very simple engine that uses a pull parser to interpret the manifest. This pull parser invokes a series of command handlers that evaluate a Condition or execute a Directive. Most data is structured in a highly regular pattern, which simplifies the parser.</t>

<t>The results of this allow a Recipient with minimal functionality to perform complex updates with reduced overhead. Conditional execution of commands allows a simple device to perform important decisions at validation-time, such as which differential update to download for a given current version, or which hash to check, based on the installation address.</t>

<t>Dependency handling is vastly simplified as well. Dependencies function like subroutines of the language. When a manifest has a dependency, it can invoke that dependency’s commands and modify their behaviour by setting parameters. Because some parameters come with security implications, the dependencies also have a mechanism to reject modifications to parameters on a fine-grained level.</t>

<t>Developing a robust permissions system works in this model too. The Recipient can use a simple ACL that is a table of Identities and Component Identifier permissions to ensure that only manifests authenticated by the appropriate identity have access to define a component.</t>

<t>Capability reporting is similarly simplified. A Recipient can report the Commands and Parameters that it supports. This is sufficiently precise for a manifest author to create a manifest that the Recipient can accept.</t>

<t>The simplicity of design in the Recipient due to all of these benefits allows even a highly constrained platform to use advanced update capabilities.</t>

<section anchor="severable-elements" title="Severable Elements">
<t>Because the manifest can be used by different actors at different times, some parts of the manifest can be removed without affecting later stages of the lifecycle. This is called “Severing.” 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 authenticity 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.</t>

<t>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 never 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.</t>

</section>
<section anchor="conventions" title="Conventions">
<t>The map indices in this 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).</t>

<t>Wherever enumerations are used, they are started at 1. This allows detection of several common software errors that are caused by uninitialised variables. Positive numbers in enumerations are reserved for IANA registration. Negative numbers are used to identify application-specific implementations.</t>

<t>CDDL names are hyphenated and CDDL structures follow the convention adopted in COSE <xref target="RFC8152"/>: SUIT_Structure_Name.</t>

</section>
<section anchor="payloads" title="Payloads">
<t>Payloads can take many forms, for example, binary, hex, s-record, elf, binary diff, PEM certificate, CBOR Web Token, serialised configuration. These payloads fall into two broad categories: those that require installation-time unpacking and those that do not. Binary, PEM certificate, and CBOR Web Token do not require installation-time unpacking. Hex, s-record, elf, and serialised configuration require installation-time unpacking.</t>

<t>Some payloads cannot be directly converted to a writable binary stream. Hex, s-record, and elf may contain gaps and they have no guarantee of monotonic increase of address, which makes pre-processing them into a binary stream difficult on constrained platforms. Serialised configuration may be unpacked into a configuration database, which makes it impossible to preprocess into a binary stream, suitable for direct writing.</t>

<t>Where a specialised unpacking algorithm is needed, a digest is not always calculable over an installed payload. For example, an elf, s-record or hex file may contain gaps that can contain any data, while not changing whether or not an installed payload is valid. Serialised configuration may update only some device data rather than all of it. This means that the digest cannot always be calculated over an installed payload when a specialised installer is used.</t>

<t>This presents two problems for the manifest: first, it must indicate that a specialised installer is needed and, second, it cannot provide a hash of the payload that is checkable after installation. These two problems are resolved in two ways:</t>

<t><list style="numbers">
  <t>Payloads that need a specialised installer must indicate this in suit-payload-info-unpack.</t>
  <t>Payloads that need specialised verification must indicate this in the SUIT_Payload section or SUIT_Parameter_Image_Digest by indicating a SUIT_Digest algorithm that correctly validates their information.</t>
</list></t>

</section>
</section>
<section anchor="manifest-structure" title="Manifest Structure">
<t>The manifest is divided into several sections in a hierarchy as follows:</t>

<t><list style="numbers">
  <t>The outer wrapper
  <list style="numbers">
      <t>The authentication wrapper</t>
      <t>The manifest
      <list style="numbers">
          <t>Critical Information</t>
          <t>List of dependencies</t>
          <t>List of payloads</t>
          <t>List of payloads in dependencies</t>
          <t>Common list of conditions, directives</t>
          <t>Dependency resolution Reference or list of conditions, directives</t>
          <t>Payload fetch Reference or list of conditions, directives</t>
          <t>Installation Reference or list of conditions, directives</t>
          <t>Verification conditions/directives</t>
          <t>Load conditions/directives</t>
          <t>Run conditions/directives</t>
          <t>Text / Reference</t>
          <t>COSWID / Reference</t>
        </list></t>
      <t>Dependency resolution conditions/directives</t>
      <t>Payload fetch conditions/directives</t>
      <t>Installation conditions/directives</t>
      <t>Text</t>
      <t>COSWID / Reference</t>
      <t>Intermediate Certificate(s) / CWTs</t>
      <t>Small Payload(s)</t>
    </list></t>
</list></t>

<section anchor="outer-wrapper" title="Outer wrapper">
<t>This object is a container for the other pieces of the manifest to provide a common mechanism to find each of the parts. All elements of the outer wrapper are contained in bstr objects. Wherever the manifest references an object in the outer wrapper, the bstr is included in the digest calculation.</t>

<t>The CDDL that describes the wrapper is below</t>

<figure><artwork><![CDATA[
SUIT_Outer_Wrapper = {
    suit-authentication-wrapper => bstr .cbor
                                   SUIT_Authentication_Wrapper / nil,
    suit-manifest               => bstr .cbor Manifest,
    suit-dependency-resolution  => bstr .cbor SUIT_Command_Sequence,
    suit-payload-fetch          => bstr .cbor SUIT_Command_Sequence,
    suit-install                => bstr .cbor SUIT_Command_Sequence,
    suit-text-external          => bstr .cbor SUIT_Text_Info,
    suit-coswid-external        => bstr .cbor COSWID
}
suit-authentication-wrapper = 1
suit-manifest = 2
suit-dependency-resolution = 7
suit-payload-fetch = 8
suit-install = 9
suit-text = 13
suit-coswid = 14

SUIT_Authentication_Wrapper = [ * (COSE_Mac_Tagged / COSE_Sign_Tagged /
                                   COSE_Mac0_Tagged / COSE_Sign1_Tagged)]
]]></artwork></figure>

<t>All elements of the outer wrapper 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 serialisation for integrity and authenticity checks.</t>

<t>The suit-authentication-wrapper contains a list of 1 or more cryptographic authentication wrappers for the core part of the manifest. These are implemented as  COSE_Mac_Tagged or COSE_Sign_Tagged blocks. The Manifest is authenticated by these blocks in “detached payload” mode. The COSE_Mac_Tagged and COSE_Sign_Tagged blocks are described in RFC 8152 <xref target="RFC8152"/> and are beyond the scope of this document. The suit-authentication-wrapper MUST come first in the SUIT_Outer_Wrapper, regardless of canonical encoding of CBOR. All validators MUST reject any SUIT_Outer_Wrapper that begins with any element other than a suit-authentication-wrapper.</t>

<t>A manifest that has not had authentication information added MUST still contain the suit-authentication-wrapper element, but the content MUST be null.</t>

<t>suit-manifest contains a Manifest structure, which describes the payload(s) to be installed and any dependencies on other manifests.</t>

<t>Each of suit-dependency-resolution, suit-payload-fetch, and suit-payload-installation contain the severable contents of the identically named portions of the manifest, described in <xref target="secmanifest"/>.</t>

<t>suit-text contains all the human-readable information that describes any and all parts of the manifest, its payload(s) and its resource(s).</t>

<t>suit-coswid contains a Concise Software Identifier. This may be discarded by the recipient if not needed.</t>

</section>
<section anchor="secmanifest" title="Manifest">

<t>The manifest describes the critical metadata for the referenced payload(s). In addition, it contains:</t>

<t><list style="numbers">
  <t>a version number for the manifest structure itself</t>
  <t>a sequence number</t>
  <t>a list of dependencies</t>
  <t>a list of components affected</t>
  <t>a list of components affected by dependencies</t>
  <t>a reference for each of the severable blocks.</t>
  <t>a list of actions that the recipient should perform.</t>
</list></t>

<t>The following CDDL fragment defines the manifest.</t>

<figure><artwork><![CDATA[
SUIT_Manifest = {
    suit-manifest-version         => 1,
    suit-manifest-sequence-number => uint,
    ? suit-dependencies           => [ + SUIT_Dependency ],
    ? suit-components             => [ + SUIT_Component ],
    ? suit-dependency-components  => [ + SUIT_Component_Reference ],
    ? suit-common                 => bstr .cbor SUIT_Command_Sequence,
    ? suit-dependency-resolution  => Digest / bstr .cbor SUIT_Command_Sequence,
    ? suit-payload-fetch          => Digest / bstr .cbor SUIT_Command_Sequence,
    ? suit-install                => Digest / bstr .cbor SUIT_Command_Sequence
    ? suit-validate               => bstr .cbor SUIT_Command_Sequence
    ? suit-load                   => bstr .cbor SUIT_Command_Sequence
    ? suit-run                    => bstr .cbor SUIT_Command_Sequence
    ? suit-text-info              => Digest / bstr .cbor SUIT_Text_Map
    ? suit-coswid                 => Digest / bstr .cbor COSWID
}

suit-manifest-version = 1
suit-manifest-sequence-number = 2
suit-dependencies = 3
suit-components = 4
suit-dependency-components = 5
suit-common = 6
suit-dependency-resolution = 7
suit-payload-fetch = 8
suit-install = 9
suit-validate = 10
suit-load = 11
suit-run = 12
suit-text-info = 13
suit-coswid = 14
]]></artwork></figure>

<t>Several fields in the Manifest can be either a CBOR structure or a SUIT_Digest. In each of these cases, the SUIT_Digest provides for a severable field. Severable fields are RECOMMENDED to implement. In particular, text SHOULD be severable, since most useful text elements occupy more space than a SUIT_Digest, but are not needed by recipient devices. 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.</t>

<t>The suit-manifest-version indicates the version of serialisation used to encode the manifest. Version 1 is the version described in this document. suit-manifest-version is MANDATORY.</t>

<t>The suit-manifest-sequence-number is a monotonically increasing anti-rollback counter. It also helps devices to determine which in a set of manifests is the “root” manifest in a given update. Each manifest MUST have a sequence number higher than each of its dependencies. Each recipient MUST reject any manifest that has a sequence number lower than its current sequence number. It MAY be convenient to use a UTC timestamp in seconds as the sequence number. suit-manifest-sequence-number is MANDATORY.</t>

<t>suit-dependencies is a list of SUIT_Dependency blocks that specify manifests that must be present before the current manifest can be processed. suit-dependencies is OPTIONAL.</t>

<t>In order to distinguish between components that are affected by the current manifest and components that are affected by a dependency, they are kept in separate lists. Components affected by the current manifest include the digest and size of the result. Components affected by a manifest only include the component identifier and the index of the manifest that fully defines the component.</t>

<t>suit-components is a list of SUIT_Component blocks that specify the vital information about the content a component identifier should contain following the update. These are the component identifiers that will be affected by the content of the current manifest. suit-components is OPTIONAL, but at least one manifest MUST contain a suit-components block.</t>

<t>suit-dependency-components is a list of SUIT_Component_Reference blocks that specify component identifiers that will be affected by the content of a dependency of the current manifest. suit-dependency-components is OPTIONAL.</t>

<t>suit-common is a SUIT_Command_Sequence to execute prior to executing any other command sequence. Typical actions in suit-common include setting expected device identity and image digests when they are conditional (see <xref target="secconditional"/> for more information on conditional sequences). suit-common is OPTIONAL.</t>

<t>suit-dependency-resolution is a SUIT_Command_Sequence to execute in order to perform dependency resolution. Typical actions include configuring URIs of dependency manifests, fetching dependency manifests, and validating dependency manifests’ contents. suit-dependency-resolution is MANDATORY when suit-dependencies is present.</t>

<t>suit-payload-fetch is a SUIT_Command_Sequence to execute in order to obtain a payload. Some manifests may include these actions in the suit-install section instead if they operate in a streaming installation mode. This is particularly relevant for constrained devices without any temporary storage for staging the update. suit-payload-fetch is OPTIONAL.</t>

<t>suit-install is a SUIT_Command_Sequence to execute in order to install a payload. Typical actions include verifying a payload stored in temporary storage, copying a staged payload from temporary storage, and unpacking a payload. suit-install is OPTIONAL.</t>

<t>suit-validate is a SUIT_Command_Sequence to execute in order to validate that the result of applying the update is correct. Typical actions involve image validation and manifest validation. suit-validate is MANDATORY. If the manifest contains dependencies, one process-dependency invocation per dependency or one process-dependency invocation targeting all dependencies SHOULD be present in validate.</t>

<t>suit-load is a SUIT_Command_Sequence to execute in order to prepare a payload for execution. Typical actions include copying an image from permanent storage into RAM, optionally including actions such as decryption or decompression. suit-load is OPTIONAL.</t>

<t>suit-run is a SUIT_Command_Sequence to execute in order to run an image. suit-run typically contains a single instruction: either the “run” directive for the bootable manifest or the “process dependencies” directive for any dependents of the bootable manifest. suit-run is OPTIONAL. Only one manifest in an update may contain the “run” directive.</t>

<t>suit-text-info is a digest that uniquely identifies the content of the Text that is packaged in the OuterWrapper. text is OPTIONAL.</t>

<t>suit-coswid is a digest that uniquely identifies the content of the concise-software-identifier that is packaged in the OuterWrapper. coswid is OPTIONAL.</t>

</section>
<section anchor="suitdependency" title="SUIT_Dependency">

<t>SUIT_Dependency specifies a manifest that describes a dependency of the current manifest.</t>

<t>The following CDDL describes the SUIT_Dependency structure.</t>

<figure><artwork><![CDATA[
SUIT_Dependency = {
    suit-dependency-digest => SUIT_Digest,
    suit-dependency-prefix => SUIT_Component_Identifier,
}
]]></artwork></figure>

<t>The suit-dependency-digest specifies the dependency manifest uniquely by identifying a particular Manifest structure. The digest is calculated over the Manifest structure instead of the COSE Sig_structure or Mac_structure. This means that a digest may need to be calculated more than once, however this is necessary to ensure that removing a signature from a manifest does not break dependencies due to missing ‘body_protected’ and ‘body_signed’ elements. This is also necessary to support the trusted intermediary use case, where an intermediary re-signs the Manifest, removing the original signature, potentially with a different algorithm, or trading COSE_Sign for COSE_Mac.</t>

<t>The suit-dependency-prefix element contains a SUIT_Component_Identifier. This specifies the scope at which the dependency operates. This allows the dependency to be forwarded on to a component that is capable of parsing its own manifests. It also allows one manifest to be deployed to multiple dependent devices without those devices needing consistent component hierarchy. This element is OPTIONAL.</t>

</section>
<section anchor="suitcomponent" title="SUIT_Component">

<t>The SUIT_Component describes an image that is uniquely defined by the current manifest. It consists of three elemnts: the component identifier that represents a component that will be affected by this manifest. This excludes components that are affected by dependencies. The following CDDL describes the SUIT_Component.</t>

<figure><artwork><![CDATA[
SUIT_Component = {
    suit-component-identifier => SUIT_Component_Identifier,
    ? suit-component-size => uint,
    ? suit-component-digest => Digest,
}
]]></artwork></figure>

<t>Because suit-component-size and suit-component-digest can be dependent on installation offset, they cannot be exclusively contained in SUIT_Component. However, since these are security critical parameters, these parameters are updated to match the contents of suit-components prior to processing suit-common. If absent, these are set to Zero and NULL, respectively. This enforces that the manifest defining a component is the only manifest that can describe its contents.</t>

</section>
<section anchor="suitcomponentreference" title="SUIT_Component_Reference">

<t>The SUIT_Component_Reference describes an image that is defined by another manifest. This is useful for overriding the behaviour of another manifest, for example by directing the recipient to look at a different URI for the image or by changing the expected format, such as when a gateway performs decryption on behalf of a constrained device. The following CDDL describes the SUIT_Component_Reference.</t>

<figure><artwork><![CDATA[
SUIT_Component_Reference = {
    suit-component-identifier => SUIT_Component_Identifier,
    suit-component-dependency-index => uint
}
]]></artwork></figure>

</section>
<section anchor="secparameters" title="Manifest Parameters">

<t>Many conditions and directives require additional information. That information is contained within parameters that can be set in a consistent way. Parameters MUST only be:</t>

<figure><artwork><![CDATA[
1. Integers
2. Byte strings
3. Booleans
]]></artwork></figure>

<t>This allows reduction of manifest size and replacement of parameters from one manifest to the next. Byte strings MAY contain CBOR-encoded objects.</t>

<t>The defined manifest parameters are described below.</t>

<texttable>
      <ttcol align='left'>Parameter Code</ttcol>
      <ttcol align='left'>CBOR Type</ttcol>
      <ttcol align='left'>Default</ttcol>
      <ttcol align='left'>Scope</ttcol>
      <ttcol align='left'>Name</ttcol>
      <ttcol align='left'>Description</ttcol>
      <c>1</c>
      <c>boolean</c>
      <c>1</c>
      <c>Global</c>
      <c>Strict Order</c>
      <c>Requires that the manifest is processed in a strictly linear fashion. Set to 0 to enable parallel handling of manifest directives.</c>
      <c>2</c>
      <c>boolean</c>
      <c>0</c>
      <c>Global</c>
      <c>Coerce Condition Failure</c>
      <c>Coerces the success code of a command segment to success even when aborted due to a condition failure.</c>
      <c>3</c>
      <c>bstr</c>
      <c>nil</c>
      <c>Component/Global</c>
      <c>Vendor ID</c>
      <c>A RFC4122 UUID representing the vendor of the device or component</c>
      <c>4</c>
      <c>bstr</c>
      <c>nil</c>
      <c>Component/Global</c>
      <c>Class ID</c>
      <c>A RFC4122 UUID representing the class of the device or component</c>
      <c>5</c>
      <c>bstr</c>
      <c>nil</c>
      <c>Component/Global</c>
      <c>Device ID</c>
      <c>A RFC4122 UUID representing the device or component</c>
      <c>6</c>
      <c>bstr</c>
      <c>nil</c>
      <c>Component/Dependency</c>
      <c>URI List</c>
      <c>A CBOR encoded list of ranked URIs</c>
      <c>7</c>
      <c>bstr</c>
      <c>nil</c>
      <c>Component/Dependency</c>
      <c>Encryption Info</c>
      <c>A COSE object defining the encryption mode of the target</c>
      <c>8</c>
      <c>bstr</c>
      <c>nil</c>
      <c>Component</c>
      <c>Compression Info</c>
      <c>A SUIT_Compression_Info object</c>
      <c>9</c>
      <c>bstr</c>
      <c>nil</c>
      <c>Component</c>
      <c>Unpack Info</c>
      <c>A SUIT_Unpack_Info object</c>
      <c>10</c>
      <c>int/bstr</c>
      <c>nil</c>
      <c>Component</c>
      <c>Source Component</c>
      <c>A SUIT_Component_Identifier or Component Index</c>
      <c>11</c>
      <c>bstr</c>
      <c>nil</c>
      <c>Component/Dependency</c>
      <c>Image Digest</c>
      <c>A SUIT_Digest</c>
      <c>12</c>
      <c>bstr</c>
      <c>nil</c>
      <c>Component/Dependency</c>
      <c>Image Size</c>
      <c>Integer size</c>
      <c>nint</c>
      <c>int/bstr</c>
      <c>nil</c>
      <c>Custom</c>
      <c>Custom Parameter</c>
      <c>Application-defined parameter</c>
</texttable>

<t>Each parameter contains a Skip/Append flag. Append is an advanced feature that is not available on highly constrained platforms. The mechanism for setting the Append flag is TBD.</t>

<t>CBOR-encoded object parameters are still wrapped in a bstr. This is because it allows a parser that is aggregating parameters to reference the object with a single pointer and traverse it without understanding the contents. This is important for modularisation and division of responsibility within a pull parser. The same consideration does not apply to Conditions and Directives because those elements are invoked with their arguments immediately</t>

<section anchor="suitparameterstrictorder" title="SUIT_Parameter_Strict_Order">

<t>The Strict Order Parameter allows a manifest to govern when directives can be executed out-of-order. This allows for systems that have a sensitivity to order of updates to choose the order in which they are executed. It also allows for more advanced systems to parallelise their handling of updates. Strict Order defaults to True. It MAY be set to False when the order of operations does not matter. When arriving at the end of a command sequence, ALL commands MUST have completed, regardless of the state of SUIT_Parameter_Strict_Order. If SUIT_Parameter_Strict_Order is returned to True, ALL preceding commands MUST complete before the next command is executed.</t>

</section>
<section anchor="suitparametercoerceconditionfailure" title="SUIT_Parameter_Coerce_Condition_Failure">

<t>When executing a command sequence inside SUIT_Run_Sequence and a condition failure occurs, the manifest processor aborts the sequence. If Coerce Condition Failure is True, it returns Success. Otherwise, it returns the original condition failure. SUIT_Parameter_Coerce_Condition_Failure is scoped to the enclosing SUIT_Directive_Run_Sequence. Its value is discarded when SUIT_Directive_Run_Sequence terminates.</t>

</section>
</section>
<section anchor="suitparameterencryptioninfo" title="SUIT_Parameter_Encryption_Info">

<t>Encryption Info defines the mechanism that Fetch or Copy should use to decrypt the data they transfer. SUIT_Parameter_Encryption_Info is encoded as a COSE_Encrypt_Tagged or a COSE_Encrypt0_Tagged, wrapped in a bstr</t>

</section>
<section anchor="suitparametercompressioninfo" title="SUIT_Parameter_Compression_Info">

<t>Compression Info defines any information that is required for a device to perform decompression operations. Typically, this includes the algorithm identifier.</t>

<t>SUIT_Parameter_Compression_Info is defined by the following CDDL:</t>

<figure><artwork type="CDDL"><![CDATA[
SUIT_Compression_Info = {
    suit-compression-algorithm => SUIT_Compression_Algorithms
    ? suit-compression-parameters => bstr
}
suit-compression-algorithm = 1
suit-compression-parameters = 2

SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_gzip
SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_bzip2
SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_deflate
SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_LZ4
SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_lzma

SUIT_Compression_Algorithm_gzip = 1
SUIT_Compression_Algorithm_bzip2 = 2
SUIT_Compression_Algorithm_deflate = 3
SUIT_Compression_Algorithm_lz4 = 4
SUIT_Compression_Algorithm_lzma = 7
]]></artwork></figure>

</section>
<section anchor="suitparameterunpackinfo" title="SUIT_Parameter_Unpack_Info">

<t>SUIT_Unpack_Info defines the information required for a device to interpret a packed format, such as elf, hex, or binary diff. SUIT_Unpack_Info is defined by the following CDDL:</t>

<figure><artwork type="CDDL"><![CDATA[
SUIT_Unpack_Info = {
    suit-unpack-algorithm => SUIT_Unpack_Algorithms
    ? suit-unpack-parameters => bstr
}
suit-unpack-algorithm  = 1
suit-unpack-parameters = 2

SUIT_Unpack_Algorithms //= SUIT_Unpack_Algorithm_Delta
SUIT_Unpack_Algorithms //= SUIT_Unpack_Algorithm_Hex
SUIT_Unpack_Algorithms //= SUIT_Unpack_Algorithm_Elf

SUIT_Unpack_Algorithm_Delta = 1
SUIT_Unpack_Algorithm_Hex = 2
SUIT_Unpack_Algorithm_Elf = 3
]]></artwork></figure>

</section>
<section anchor="suitparameters-cddl" title="SUIT_Parameters CDDL">

<t>The following CDDL describes all SUIT_Parameters.</t>

<figure><artwork type="CDDL"><![CDATA[
SUIT_Parameters //= SUIT_Parameter_Strict_Order
SUIT_Parameters //= SUIT_Parameter_Coerce_Condition_Failure
SUIT_Parameters //= SUIT_Parameter_Vendor_ID
SUIT_Parameters //= SUIT_Parameter_Class_ID
SUIT_Parameters //= SUIT_Parameter_Device_ID
SUIT_Parameters //= SUIT_Parameter_URI_List
SUIT_Parameters //= SUIT_Parameter_Encryption_Info
SUIT_Parameters //= SUIT_Parameter_Compression_Info
SUIT_Parameters //= SUIT_Parameter_Unpack_Info
SUIT_Parameters //= SUIT_Parameter_Source_Component
SUIT_Parameters //= SUIT_Parameter_Image_Digest
SUIT_Parameters //= SUIT_Parameter_Image_Size
SUIT_Parameters //= SUIT_Parameter_Custom

SUIT_Parameter_Strict_Order = (1 => bool)
SUIT_Parameter_Coerce_Condition_Failure = (2 => bool)
SUIT_Parameter_Vendor_ID = (3 => bstr)
SUIT_Parameter_Class_ID = (4 => bstr)
SUIT_Parameter_Device_ID = (5 => bstr)
SUIT_Parameter_URI_List = (6 => bstr .cbor SUIT_URI_List)
SUIT_Parameter_Encryption_Info = (7 => bstr .cbor SUIT_Encryption_Info)
SUIT_Parameter_Compression_Info = (8 => bstr .cbor SUIT_Compression_Info)
SUIT_Parameter_Unpack_Info = (9 => bstr .cbor SUIT_Unpack_Info)
SUIT_Parameter_Source_Component = (10 => bstr .cbor SUIT_Component_Identifier)
SUIT_Parameter_Image_Digest = (11 => bstr .cbor SUIT_Digest)
SUIT_Parameter_Image_Size = (12 => uint)
SUIT_Parameter_Custom = (nint => int/bool/bstr)

SUIT_URI_List = [ + [priority: int, uri: tstr] ]

SUIT_Encryption_Info= COSE_Encrypt_Tagged/COSE_Encrypt0_Tagged
SUIT_Compression_Info = {
    suit-compression-algorithm => SUIT_Compression_Algorithms
    ? suit-compression-parameters => bstr
}
suit-compression-algorithm = 1
suit-compression-parameters = 2

SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_gzip
SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_bzip2
SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_deflate
SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_LZ4
SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_lzma

SUIT_Compression_Algorithm_gzip = 1
SUIT_Compression_Algorithm_bzip2 = 2
SUIT_Compression_Algorithm_deflate = 3
SUIT_Compression_Algorithm_lz4 = 4
SUIT_Compression_Algorithm_lzma = 7

SUIT_Unpack_Info = {
    suit-unpack-algorithm => SUIT_Unpack_Algorithms
    ? suit-unpack-parameters => bstr
}
suit-unpack-algorithm  = 1
suit-unpack-parameters = 2

SUIT_Unpack_Algorithms //= SUIT_Unpack_Algorithm_Delta
SUIT_Unpack_Algorithms //= SUIT_Unpack_Algorithm_Hex
SUIT_Unpack_Algorithms //= SUIT_Unpack_Algorithm_Elf

SUIT_Unpack_Algorithm_Delta = 1
SUIT_Unpack_Algorithm_Hex = 2
SUIT_Unpack_Algorithm_Elf = 3
]]></artwork></figure>

</section>
<section anchor="suitcommandsequence" title="SUIT_Command_Sequence">

<t>A SUIT_Command_Sequence defines a series of actions that the recipient MUST take to accomplish a particular goal. These goals are defined in the manifest and include:</t>

<t><list style="numbers">
  <t>Dependency Resolution</t>
  <t>Payload Fetch</t>
  <t>Payload Installation</t>
  <t>Image Validation</t>
  <t>Image Loading</t>
  <t>Run or Boot</t>
</list></t>

<t>Each of these follows exactly the same structure to ensure that the parser is as simple as possible.</t>

<t>Lists of commands are constructed from two kinds of element:</t>

<t><list style="numbers">
  <t>Conditions that MUST be true–any failure is treated as a failure of the update/load/boot</t>
  <t>Directives that MUST be executed.</t>
</list></t>

<t>The lists of commands are logically structured into sequences of zero or more conditions followed by zero or more directives. The <spanx style="strong">logical</spanx> structure is described by the following CDDL:</t>

<figure><artwork><![CDATA[
Command_Sequence = {
    conditions => [ * Condition],
    directives => [ * Directive]
}
]]></artwork></figure>

<t>This introduces significant complexity in the parser, however, so the structure is flattened to make parsing simpler:</t>

<figure><artwork><![CDATA[
SUIT_Command_Sequence = [ + (SUIT_Condition/SUIT_Directive) ]
]]></artwork></figure>

<t>Each condition and directive is composed of:</t>

<t><list style="numbers">
  <t>A command code identifier</t>
  <t>An argument block</t>
</list></t>

<t>Argument blocks are defined for each type of command.</t>

<t>Many conditions and directives apply to a given component, and these generally grouped together. Therefore, a special command to set the current component index is provided with a matching command to set the current manifest index. This index is a numeric index into the component ID tables defined at the beginning of the document. For the purpose of setting the index, the two component ID tables are considered to be concatenated together.</t>

<t>To facilitate optional conditions, a special directive is provided. It runs a new list of conditions/directives that are contained as an argument to the directive. It also contains a flag that indicates whether or not a failure of a condition should indicate a failure of the update/boot.</t>

</section>
<section anchor="suitcondition" title="SUIT_Condition">

<t>Conditions are used to define mandatory properties of a system in order for an update to be applied. They can be pre-conditions or post-conditons of any directive or series of directives, depending on where they are placed in the list. Conditions include:</t>

<texttable>
      <ttcol align='left'>Condition Code</ttcol>
      <ttcol align='left'>Condition Name</ttcol>
      <ttcol align='left'>Argument Type</ttcol>
      <c>1</c>
      <c>Vendor Identifier</c>
      <c>RFC4122 UUID wrapped in a bstr</c>
      <c>2</c>
      <c>Class Identifier</c>
      <c>RFC4122 UUID wrapped in a bstr</c>
      <c>3</c>
      <c>Device Identifier</c>
      <c>RFC4122 UUID wrapped in a bstr</c>
      <c>4</c>
      <c>Image Match</c>
      <c>SUIT_Digest</c>
      <c>5</c>
      <c>Image Not Match</c>
      <c>SUIT_Digest</c>
      <c>6</c>
      <c>Use Before</c>
      <c>Unsigned Integer timestamp</c>
      <c>7</c>
      <c>Minimum Battery</c>
      <c>Unsigned Integer</c>
      <c>8</c>
      <c>Update Authorised</c>
      <c>Integer</c>
      <c>9</c>
      <c>Version</c>
      <c>List of Integers</c>
      <c>10</c>
      <c>Component Offset</c>
      <c>Unsigned Integer</c>
      <c>nint</c>
      <c>Custom Condition</c>
      <c>bstr</c>
</texttable>

<t>Each condition MUST report a success code on completion. If a condition reports failure, then the current sequence of commands MUST terminate. If a recipient encounters an unknown Condition Code, it MUST report a failure.</t>

<t>Positive Condition numbers are reserved for IANA registration. Negative numbers are reserved for proprietary, application-specific directives.</t>

<section anchor="id-conditions" title="ID Conditions">

<t>There are three identifier-based conditions: SUIT_Condition_Vendor_Identifier, SUIT_Condition_Class_Identifier, and SUIT_Condition_Device_Identifier. Each of these conditions present a RFC 4122 <xref target="RFC4122"/> UUID that MUST be matched by the installing device in order to consider the manifest valid.</t>

<t>These conditions MAY be used with or without an argument. If an argument is supplied, then it must be the RFC 4122 <xref target="RFC4122"/> UUID that must be matched for the condition to succeed. If no argument is supplied, then the recipient uses the ID parameter that has already been set using the Set Parameters directive. If no ID has been set, this condition fails. SUIT_Condition_Class_Identifier and SUIT_Condition_Vendor_Identifier are MANDATORY to implement. SUIT_Condition_Device_Identifier is OPTIONAL to implement.</t>

</section>
<section anchor="suitconditionimagematch" title="SUIT_Condition_Image_Match">

<t>Verify that the current component matches the supplied digest. If no digest is specified, then the digest is verified against the digest specified in the Components list. If no digest is specified and the component is not present in the Components list, the condition fails. SUIT_Condition_Image_Match is MANDATORY to implement.</t>

</section>
<section anchor="suitconditionimagenotmatch" title="SUIT_Condition_Image_Not_Match">

<t>Verify that the current component does not match the supplied digest. If no digest is specified, then the digest is compared against the digest specified in the Components list. If no digest is specified and the component is not present in the Components list, the condition fails. SUIT_Condition_Image_Not_Match is OPTIONAL to implement.</t>

</section>
<section anchor="suitconditionusebefore" title="SUIT_Condition_Use_Before">

<t>Verify that the current time is BEFORE the specified time. SUIT_Condition_Use_Before is used to specify the last time at which an update should be installed. One argument is required, encoded as a POSIX timestamp, that is seconds after 1970-01-01 00:00:00. Timestamp conditions MUST be evaluated in 64 bits, regardless of encoded CBOR size. SUIT_Condition_Use_Before is OPTIONAL to implement.</t>

</section>
<section anchor="suitconditionminimumbattery" title="SUIT_Condition_Minimum_Battery">

<t>SUIT_Condition_Minimum_Battery provides a mechanism to test a device’s battery level before installing an update. This condition is for use in primary-cell applications, where the battery is only ever discharged. For batteries that are charged, SUIT_Directive_Wait_Event is more appropriate, since it defines a “wait” until the battery level is sufficient to install the update. SUIT_Condition_Minimum_Battery is specified in mWh. SUIT_Condition_Minimum_Battery is OPTIONAL to implement.</t>

</section>
<section anchor="suitconditionupdateauthorised" title="SUIT_Condition_Update_Authorised">

<t>Request Authorisation from the application and fail if not authorised. This can allow a user to decline an update. Argument is an integer priority level. Priorities are application defined. SUIT_Condition_Update_Authorised is OPTIONAL to implement.</t>

</section>
<section anchor="suitconditionversion" title="SUIT_Condition_Version">

<t>SUIT_Condition_Version allows comparing versions of firmware. Verifying image digests is preferred to version checks because digests are more precise. The image can be compared as:</t>

<t><list style="symbols">
  <t>Greater</t>
  <t>Greater or Equal</t>
  <t>Equal</t>
  <t>Lesser or Equal</t>
  <t>Lesser</t>
</list></t>

<t>Versions are encoded as a CBOR list of integers. Comparisons are done on each integer in sequence.</t>

<t>The following CDDL describes SUIT_Condition_Version_Argument</t>

<figure><artwork><![CDATA[
SUIT_Condition_Version_Argument = [
    suit-condition-version-comparison: SUIT_Condition_Version_Comparison_Types,
    suit-condition-version-comparison: SUIT_Condition_Version_Comparison_Value
]
SUIT_Condition_Version_Comparison_Types /= SUIT_Condition_Version_Comparison_Greater
SUIT_Condition_Version_Comparison_Types /= SUIT_Condition_Version_Comparison_Greater_Equal
SUIT_Condition_Version_Comparison_Types /= SUIT_Condition_Version_Comparison_Equal
SUIT_Condition_Version_Comparison_Types /= SUIT_Condition_Version_Comparison_Lesser_Equal
SUIT_Condition_Version_Comparison_Types /= SUIT_Condition_Version_Comparison_Lesser
SUIT_Condition_Version_Comparison_Greater = 1
SUIT_Condition_Version_Comparison_Greater_Equal = 2
SUIT_Condition_Version_Comparison_Equal = 3
SUIT_Condition_Version_Comparison_Lesser_Equal = 4
SUIT_Condition_Version_Comparison_Lesser = 5

SUIT_Condition_Version_Comparison_Value = [+int]
]]></artwork></figure>

<t>While the exact encoding of versions is application-defined, semantic versions map directly:</t>

<t><list style="symbols">
  <t>1.2.3 = [1,2,3]</t>
  <t>1.2-rc3 = [1,2,-1,3]</t>
  <t>1.2-beta = [1,2,-2]</t>
  <t>1.2-alpha = [1,2,-3]</t>
  <t>1.2-alpha4 = [1,2,-3,4]</t>
</list></t>

<t>SUIT_Condition_Version is OPTIONAL to implement.</t>

</section>
<section anchor="suitconditioncustom" title="SUIT_Condition_Custom">

<t>SUIT_Condition_Custom describes any proprietary, application specific condition. This is encoded as a negative integer, chosen by the firmware developer, and a bstr that encodes the parameters passed to the system that evaluates the condition matching that integer.
SUIT_Condition_Custom is OPTIONAL to implement.</t>

</section>
<section anchor="identifiers" title="Identifiers">

<t>Many conditions use identifiers to determine whether a manifest matches a given recipient or not. These identifiers are defined to be RFC 4122 <xref target="RFC4122"/> UUIDs. These UUIDs are explicitly NOT human-readable. They are for machine-based matching only.</t>

<t>A device may match any number of UUIDs for vendor or class identifier. This may be relevant to physical or software modules. For example, a device that has an OS and one or more applications might list one Vendor ID for the OS and one or more additional Vendor IDs for the applications. This device might also have a Class ID that must be matched for the OS and one or more Class IDs for the applications.</t>

<t>A more complete example:
A device has the following physical components:
1. A host MCU
2. A WiFi module</t>

<t>This same device has three software modules:
1. An operating system
2. A WiFi module interface driver
3. An application</t>

<t>Suppose that the WiFi module’s firmware has a proprietary update mechanism and doesn’t support manifest processing. This device can report four class IDs:</t>

<t><list style="numbers">
  <t>hardware model/revision</t>
  <t>OS</t>
  <t>WiFi module model/revision</t>
  <t>Application</t>
</list></t>

<t>This allows the OS, WiFi module, and application to be updated independently. To combat possible incompatibilities, the OS class ID can be changed each time the OS has a change to its API.</t>

<t>This approach allows a vendor to target, for example, all devices with a particular WiFi module with an update, which is a very powerful mechanism, particularly when used for security updates.</t>

<section anchor="creating-uuids" title="Creating UUIDs:">

<t>UUIDs MUST be created according to RFC 4122 <xref target="RFC4122"/>. UUIDs SHOULD use versions 3, 4, or 5, as described in RFC4122. Versions 1 and 2 do not provide a tangible benefit over version 4 for this application.</t>

<t>The RECOMMENDED method to create a vendor ID is:
Vendor ID = UUID5(DNS_PREFIX, vendor domain name)</t>

<t>The RECOMMENDED method to create a class ID is:
Class ID = UUID5(Vendor ID, Class-Specific-Information)</t>

<t>Class-specific information is composed of a variety of data, for example:</t>

<t><list style="symbols">
  <t>Model number</t>
  <t>Hardware revision</t>
  <t>Bootloader version (for immutable bootloaders)</t>
</list></t>

</section>
</section>
<section anchor="suitcondition-cddl" title="SUIT_Condition CDDL">

<t>The following CDDL describes SUIT_Condition:</t>

<figure><artwork><![CDATA[
SUIT_Condition //= (nint => bstr)
SUIT_Condition //= SUIT_Condition_Vendor_Identifier
SUIT_Condition //= SUIT_Condition_Class_Identifier
SUIT_Condition //= SUIT_Condition_Device_Identifier
SUIT_Condition //= SUIT_Condition_Image_Match
SUIT_Condition //= SUIT_Condition_Image_Not_Match
SUIT_Condition //= SUIT_Condition_Use_Before
SUIT_Condition //= SUIT_Condition_Minimum_Battery
SUIT_Condition //= SUIT_Condition_Update_Authorised
SUIT_Condition //= SUIT_Condition_Version
SUIT_Condition //= SUIT_Condition_Component_Offset
SUIT_Condition //= SUIT_Condition_Custom

SUIT_Condition_Vendor_Identifier = (1 => bstr .size 16)
SUIT_Condition_Class_Identifier = (2 => bstr .size 16)
SUIT_Condition_Device_Identifier = (3 => bstr .size 16)
SUIT_Condition_Image_Match = (4 => SUIT_Digest)
SUIT_Condition_Image_Not_Match = (5 => SUIT_Digest)
SUIT_Condition_Use_Before = (6 => uint)
SUIT_Condition_Minimum_Battery = (7 => uint)
SUIT_Condition_Update_Authorised = (8 => int)
SUIT_Condition_Version = (9 => SUIT_Condition_Version_Argument)
SUIT_Condition_Component_Offset = (10 => uint)
SUIT_Condition_Custom = (nint => bstr)

SUIT_Condition_Version_Argument = [
    suit-condition-version-comparison: SUIT_Condition_Version_Comparison_Types,
    suit-condition-version-comparison: SUIT_Condition_Version_Comparison_Value
]
SUIT_Condition_Version_Comparison_Types /= SUIT_Condition_Version_Comparison_Greater
SUIT_Condition_Version_Comparison_Types /= SUIT_Condition_Version_Comparison_Greater_Equal
SUIT_Condition_Version_Comparison_Types /= SUIT_Condition_Version_Comparison_Equal
SUIT_Condition_Version_Comparison_Types /= SUIT_Condition_Version_Comparison_Lesser_Equal
SUIT_Condition_Version_Comparison_Types /= SUIT_Condition_Version_Comparison_Lesser

SUIT_Condition_Version_Comparison_Greater = 1
SUIT_Condition_Version_Comparison_Greater_Equal = 2
SUIT_Condition_Version_Comparison_Equal = 3
SUIT_Condition_Version_Comparison_Lesser_Equal = 4
SUIT_Condition_Version_Comparison_Lesser = 5

SUIT_Condition_Version_Comparison_Value = [+int]
]]></artwork></figure>

</section>
</section>
<section anchor="suitdirective" title="SUIT_Directive">

<t>Directives are used to define the behaviour of the recipient. Directives include:</t>

<texttable>
      <ttcol align='left'>Directive Code</ttcol>
      <ttcol align='left'>Directive Name</ttcol>
      <c>11</c>
      <c>Set Component Index</c>
      <c>12</c>
      <c>Set Manifest Index</c>
      <c>13</c>
      <c>Run Sequence</c>
      <c>14</c>
      <c>Run Sequence Conditional</c>
      <c>15</c>
      <c>Process Dependency</c>
      <c>16</c>
      <c>Set Parameters</c>
      <c>17</c>
      <c>Reserved</c>
      <c>18</c>
      <c>Reserved</c>
      <c>19</c>
      <c>Override Parameters</c>
      <c>20</c>
      <c>Fetch</c>
      <c>21</c>
      <c>Copy</c>
      <c>22</c>
      <c>Run</c>
      <c>23</c>
      <c>Wait</c>
</texttable>

<t>When a Recipient executes a Directive, it MUST report a success code. If the Directive reports failure, then the current Command Sequence MUST terminate.</t>

<section anchor="suitdirectivesetcomponentindex" title="SUIT_Directive_Set_Component_Index">

<t>Set Component Index defines the component to which successive directives and conditions will apply. The supplied argument MUST be either a boolean or an unsigned integer index into the concatenation of suit-components and suit-dependency-components. If the following directives apply to ALL components, then the boolean value “True” is used instead of an index. True does not apply to dependency components. If the following directives apply to NO components, then the boolean value “False” is used. When SUIT_Directive_Set_Manifest_Index is used, SUIT_Directive_Set_Component_Index = False is implied. When SUIT_Directive_Set_Component_Index is used, SUIT_Directive_Set_Manifest_Index = False is implied.</t>

<t>The following CDDL describes the argument to SUIT_Directive_Set_Component_Index.</t>

<figure><artwork><![CDATA[
SUIT_Directive_Set_Component_Index_Argument = uint/bool
]]></artwork></figure>

</section>
<section anchor="suitdirectivesetmanifestindex" title="SUIT_Directive_Set_Manifest_Index">

<t>Set Manifest Index defines the manifest to which successive directives and conditions will apply. The supplied argument MUST be either a boolean or an unsigned integer index into the dependencies. If the following directives apply to ALL dependencies, then the boolean value “True” is used instead of an index. If the following directives apply to NO dependencies, then the boolean value “False” is used. When SUIT_Directive_Set_Component_Index is used, SUIT_Directive_Set_Manifest_Index = False is implied. When SUIT_Directive_Set_Manifest_Index is used, SUIT_Directive_Set_Component_Index = False is implied.</t>

<t>Typical operations that require SUIT_Directive_Set_Manifest_Index include setting a source URI, invoking “Fetch,” or invoking “Process Dependency” for an individual dependency.</t>

<t>The following CDDL describes the argument to SUIT_Directive_Set_Manifest_Index.</t>

<figure><artwork><![CDATA[
SUIT_Directive_Set_Manifest_Index_Argument = uint/bool
]]></artwork></figure>

</section>
<section anchor="suitdirectiverunsequence" title="SUIT_Directive_Run_Sequence">

<t>To enable conditional commands, and to allow several strictly ordered sequences to be executed out-of-order, SUIT_Run_Sequence allows the manifest processor to execute its argument as a SUIT_Command_Sequence. The argument must be wrapped in a bstr.</t>

<t>When a sequence is executed, any failure of a condition causes immediate termination of the sequence.</t>

<t>The following CDDL describes the SUIT_Run_Sequence argument.</t>

<figure><artwork><![CDATA[
SUIT_Directive_Run_Sequence_Argument = bstr .cbor SUIT_Command_Sequence
]]></artwork></figure>

<t>When SUIT_Directive_Run_Sequence completes, it forwards the last status code that occurred in the sequence. If the Coerce on Condition Failure parameter is true, then SUIT_Directive_Run_Sequence only fails when a directive in the argument sequence fails.</t>

<t>SUIT_Parameter_Coerce_Condition_Failure defaults to False when SUIT_Directive_Run_Sequence begins. Its value is discarded when SUIT_Directive_Run_Sequence terminates.</t>

</section>
<section anchor="suitdirectiverunsequenceconditional" title="SUIT_Directive_Run_Sequence_Conditional">

<t>This command is exactly the same as SUIT_Directive_Run_Sequence, except that it initialises Coerce on Condition Failure to True.</t>

<t>SUIT_Parameter_Coerce_Condition_Failure defaults to True when SUIT_Directive_Run_Sequence_Conditional begins. Its value is discarded when SUIT_Directive_Run_Sequence_Conditional terminates.</t>

</section>
<section anchor="suitdirectiveprocessdependency" title="SUIT_Directive_Process_Dependency">

<t>Execute the commands in the common section of the current dependency, followed by the commands in the equivalent section of the current dependency. For example, if the current section is “fetch payload,” this will execute “common” in the current dependency, then “fetch payload” in the current dependency. Once this is complete, the command following SUIT_Directive_Process_Dependency will be processed.</t>

<t>If the current dependency is False, this directive has no effect. If the current dependency is True, then this directive applies to all dependencies. If the current section is “common,” this directive MUST have no effect.</t>

<t>When SUIT_Process_Dependency completes, it forwards the last status code that occurred in the dependency.</t>

<t>The argument to SUIT_Directive_Process_Dependency is defined in the following CDDL.</t>

<figure><artwork><![CDATA[
SUIT_Directive_Process_Dependency_Argument = nil
]]></artwork></figure>

</section>
<section anchor="suitdirectivesetparameters" title="SUIT_Directive_Set_Parameters">

<t>SUIT_Directive_Set_Parameters allows the manifest to configure behaviour of future directives by changing parameters that are read by those directives. When dependencies are used, SUIT_Directive_Set_Parameters also allows a manifest to modify the behaviour of its dependencies.</t>

<t>Available parameters are defined in <xref target="secparameters"/>.</t>

<t>If a parameter is already set, SUIT_Directive_Set_Parameters will skip setting the parameter to its argument. This provides the core of the override mechanism, allowing dependent manifests to change the behaviour of a manifest.</t>

<t>The argument to SUIT_Directive_Set_Parameters is defined in the following CDDL.</t>

<figure><artwork><![CDATA[
SUIT_Directive_Set_Parameters_Argument = {+ SUIT_Parameters}
]]></artwork></figure>

<t>N.B.: A directive code is reserved for an optimisation: a way to set a parameter to the contents of another parameter, optionally with another component ID.</t>

</section>
<section anchor="suitdirectivesetparameterstateappend" title="SUIT_Directive_Set_Parameter_State_Append">

<t>This command is reserved for future use. It will provide a mechanism to override the “set if unset” logic of SUIT_Directive_Set_Parameters on a per-parameter basis. This will allow certain parameters to be treated as lists, rather than fixed values. This enables a feature for an advanced device to fail over from URIs defined in one manifest to those defined in another.</t>

</section>
<section anchor="suitdirectiveoverrideparameters" title="SUIT_Directive_Override_Parameters">

<t>SUIT_Directive_Override_Parameters replaces any listed parameters that are already set with the values that are provided in its argument. This allows a manifest to prevent replacement of critical parameters.</t>

<t>Available parameters are defined in <xref target="secparameters"/>.</t>

<t>The argument to SUIT_Directive_Override_Parameters is defined in the following CDDL.</t>

<figure><artwork><![CDATA[
SUIT_Directive_Override_Parameters_Argument = {+ SUIT_Parameters}
]]></artwork></figure>

</section>
<section anchor="suitdirectivefetch" title="SUIT_Directive_Fetch">

<t>SUIT_Directive_Fetch instructs the manifest processor to obtain one or more manifests or payloads, as specified by the manifest index and component index, respectively.</t>

<t>SUIT_Directive_Fetch can target one or more manifests and one or more payloads. SUIT_Directive_Fetch retrieves each component and each manifest listed in component-index and manifest-index, respectively. If component-index or manifest-index is True, instead of an integer, then all current manifest components/manifests are fetched. The current manifest’s dependent-components are not automatically fetched. In order to pre-fetch these, they MUST be specified in a component-index integer.</t>

<t>SUIT_Directive_Fetch typically takes no arguments unless one is needed to modify fetch behaviour. If an argument is needed, it must be wrapped in a bstr.</t>

<t>SUIT_Directive_Fetch reads the URI List parameter to find the source of the fetch it performs.</t>

<t>The behaviour of SUIT_Directive_Fetch can be modified by setting one or more of SUIT_Parameter_Encryption_Info, SUIT_Parameter_Compression_Info, SUIT_Parameter_Unpack_Info. These three parameters each activate and configure a processing step that can be applied to the data that is transferred during SUIT_Directive_Fetch.</t>

<t>The argument to SUIT_Directive_Fetch is defined in the following CDDL.</t>

<figure><artwork><![CDATA[
SUIT_Directive_Fetch_Argument = nil/bstr
]]></artwork></figure>

</section>
<section anchor="suitdirectivecopy" title="SUIT_Directive_Copy">

<t>SUIT_Directive_Copy instructs the manifest processor to obtain one or more payloads, as specified by the component index. SUIT_Directive_Copy retrieves each component listed in component-index, respectively. If component-index is True, instead of an integer, then all current manifest components are copied. The current manifest’s dependent-components are not automatically copied. In order to copy these, they MUST be specified in a component-index integer.</t>

<t>The behaviour of SUIT_Directive_Copy can be modified by setting one or more of SUIT_Parameter_Encryption_Info, SUIT_Parameter_Compression_Info, SUIT_Parameter_Unpack_Info. These three parameters each activate and configure a processing step that can be applied to the data that is transferred during SUIT_Directive_Copy.</t>

<t><spanx style="strong">N.B.</spanx> Fetch and Copy are very similar. Merging them into one command may be appropriate.</t>

<t>SUIT_Directive_Copy reads its source from SUIT_Parameter_Source_Component.</t>

<t>The argument to SUIT_Directive_Copy is defined in the following CDDL.</t>

<figure><artwork><![CDATA[
SUIT_Directive_Copy_Argument = nil
]]></artwork></figure>

</section>
<section anchor="suitdirectiverun" title="SUIT_Directive_Run">

<t>SUIT_Directive_Run directs the manifest processor to transfer execution to the current Component Index. When this is invoked, the manifest processor MAY be unloaded and execution continues in the Component Index. Arguments provided to Run are forwarded to the executable code located in Component Index, in an application-specific way. For example, this could form the Linux Kernel Command Line if booting a linux device.</t>

<t>If the executable code at Component Index is constructed in such a way that it does not unload the manifest processor, then the manifest processor may resume execution after the executable completes. This allows the manifest processor to invoke suitable helpers and to verify them with image conditions.</t>

<t>The argument to SUIT_Directive_Run is defined in the following CDDL.</t>

<figure><artwork><![CDATA[
SUIT_Directive_Run_Argument = nil/bstr
]]></artwork></figure>

</section>
<section anchor="suitdirectivewait" title="SUIT_Directive_Wait">

<t>SUIT_Directive_Wait directs the manifest processor to pause until a specified event occurs. Some possible events include:</t>

<t><list style="numbers">
  <t>Authorisation</t>
  <t>External Power</t>
  <t>Network availability</t>
  <t>Other Device Firmware Version</t>
  <t>Time</t>
  <t>Time of Day</t>
  <t>Day of Week</t>
</list></t>

<t>The following CDDL defines the encoding of these events.</t>

<figure><artwork><![CDATA[
SUIT_Directive_Wait_Argument = {
    SUIT_Wait_Events
}
SUIT_Wait_Events //= (1 => SUIT_Wait_Event_Argument_Authorisation)
SUIT_Wait_Events //= (2 => SUIT_Wait_Event_Argument_Power)
SUIT_Wait_Events //= (3 => SUIT_Wait_Event_Argument_Network)
SUIT_Wait_Events //= (4 => SUIT_Wait_Event_Argument_Other_Device_Version)
SUIT_Wait_Events //= (5 => SUIT_Wait_Event_Argument_Time)
SUIT_Wait_Events //= (6 => SUIT_Wait_Event_Argument_Time_Of_Day)
SUIT_Wait_Events //= (7 => SUIT_Wait_Event_Argument_Day_Of_Week)


SUIT_Wait_Event_Argument_Authorisation = int ; priority
SUIT_Wait_Event_Argument_Power = int ; Power Level
SUIT_Wait_Event_Argument_Network = int ; Network State
SUIT_Wait_Event_Argument_Other_Device_Version = [
    other-device: bstr,
    other-device-version: [+int]
]
SUIT_Wait_Event_Argument_Time = uint ; Timestamp
SUIT_Wait_Event_Argument_Time_Of_Day = uint ; Time of Day (seconds since 00:00:00)
SUIT_Wait_Event_Argument_Day_Of_Week = uint ; Days since Sunday


]]></artwork></figure>

</section>
<section anchor="suitdirective-cddl" title="SUIT_Directive CDDL">

<t>The following CDDL describes SUIT_Directive:</t>

<figure><artwork><![CDATA[
SUIT_Directive //= SUIT_Directive_Set_Component_Index
SUIT_Directive //= SUIT_Directive_Set_Manifest_Index
SUIT_Directive //= SUIT_Directive_Run_Sequence
SUIT_Directive //= SUIT_Directive_Run_Sequence_Conditional
SUIT_Directive //= SUIT_Directive_Process_Dependency
SUIT_Directive //= SUIT_Directive_Set_Parameters
SUIT_Directive //= SUIT_Directive_Override_Parameters
SUIT_Directive //= SUIT_Directive_Fetch
SUIT_Directive //= SUIT_Directive_Copy
SUIT_Directive //= SUIT_Directive_Run
SUIT_Directive //= SUIT_Directive_Wait

SUIT_Directive_Set_Component_Index = (11 => uint/bool)
SUIT_Directive_Set_Manifest_Index = (12 => uint/bool)
SUIT_Directive_Run_Sequence = (13 => bstr .cbor SUIT_Command_Sequence)
SUIT_Directive_Run_Sequence_Conditional = (14 => bstr .cbor SUIT_Command_Sequence)
SUIT_Directive_Process_Dependency = (15 => nil)
SUIT_Directive_Set_Parameters = (16 => {+ SUIT_Parameters})
SUIT_Directive_Override_Parameters = (19 => {+ SUIT_Parameters})
SUIT_Directive_Fetch = (20 => nil/bstr)
SUIT_Directive_Copy = (21 => nil/bstr)
SUIT_Directive_Run = (22 => nil/bstr)
SUIT_Directive_Wait = (23 => { + SUIT_Wait_Events })

SUIT_Wait_Events //= (1 => SUIT_Wait_Event_Argument_Authorisation)
SUIT_Wait_Events //= (2 => SUIT_Wait_Event_Argument_Power)
SUIT_Wait_Events //= (3 => SUIT_Wait_Event_Argument_Network)
SUIT_Wait_Events //= (4 => SUIT_Wait_Event_Argument_Other_Device_Version)
SUIT_Wait_Events //= (5 => SUIT_Wait_Event_Argument_Time)
SUIT_Wait_Events //= (6 => SUIT_Wait_Event_Argument_Time_Of_Day)
SUIT_Wait_Events //= (7 => SUIT_Wait_Event_Argument_Day_Of_Week)


SUIT_Wait_Event_Argument_Authorisation = int ; priority
SUIT_Wait_Event_Argument_Power = int ; Power Level
SUIT_Wait_Event_Argument_Network = int ; Network State
SUIT_Wait_Event_Argument_Other_Device_Version = [
    other-device: bstr,
    other-device-version: [+int]
]
SUIT_Wait_Event_Argument_Time = uint ; Timestamp
SUIT_Wait_Event_Argument_Time_Of_Day = uint ; Time of Day (seconds since 00:00:00)
SUIT_Wait_Event_Argument_Day_Of_Week = uint ; Days since Sunday

]]></artwork></figure>

</section>
</section>
</section>
<section anchor="dependency-processing" title="Dependency processing">

<t>Dependencies need careful handling on constrained systems. A dependency tree that is too deep can cause recursive handling to overflow stack space. Systems that parse all dependencies into an object tree can easily fill up available memory. Too many dependencies can overrun available storage space.</t>

<t>The dependency handling system in this document is designed to address as many of these problems as possible.</t>

<t>Dependencies MAY be addressed in one of three ways:</t>

<t><list style="numbers">
  <t>Iterate by component</t>
  <t>Iterate by manifest</t>
  <t>Out-of-order</t>
</list></t>

<t>Because each manifest has a list of components and a list of components defined by its dependencies, it is possible for the manifest processor to handle one component at a time, traversing the manifest tree once for each listed component. This, however consumes significant processing power.</t>

<t>Alternatively, it is possible for a device with sufficient memory to accumulate all parameters for all listed component IDs. This will naturally consume more memory, but it allows the device to process the manifests in a single pass.</t>

<t>It is expected that the simplest and most power sensitive devices will use option 2, with a fixed maximum number of components.</t>

<t>Advanced devices may make use of the Strict Order parameter and enable parallel processing of some segments, or it may reorder some segments. To perform parallel processing, once the Strict Order parameter is set to False, the device may fork a process for each command until the Strict Order parameter is returned to True or the command sequence ends. Then, it joins all forked processes before continuing processing of commands. To perform out-of-order processing, a similar approach is used, except the device consumes all commands after the Strict Order parameter is set to False, then it sorts these commands into its prefered order, invokes them all, then continues processing.</t>

</section>
<section anchor="access-control-lists" title="Access Control Lists">

<t>To manage permissions in the manifest, there are three models that can be used.</t>

<t>First, the simplest model requires that all manifests are authenticated by a single trusted key. This mode has the advantage that only a root manifest needs to be authenticated, since all of its dependencies have digests included in the root manifest.</t>

<t>This simplest model can be extended by adding key delegation without much increase in complexity.</t>

<t>A second model requires an ACL to be presented to the device, authenticated by a trusted party or stored on the device. This ACL grants access rights for specific component IDs or component ID prefixes to the listed identities or identity groups. Any identity may verify an image digest, but fetching into or fetching from a component ID requires approval from the ACL.</t>

<t>A third model allows a device to provide even more fine-grained controls: The ACL lists the component ID or component ID prefix that an identity may use, and also lists the commands that the identity may use in combination with that component ID.</t>

</section>
<section anchor="secconditional" title="Creating conditional sequences">

<t>For some use cases, it is important to provide a sequence that can fail without terminating an update. For example, a dual-image XIP MCU may require an update that can be placed at one of two offsets. This has two implications, first, the digest of each offset will be different. Second, the image fetched for each offset will have a different URI. Conditional sequences allow this to be resolved in a simple way.</t>

<t>The following JSON representation of a manifest demonstrates how this would be represented. It assumes that the bootloader and manifest processor take care of A/B switching and that the manifest is not aware of this distinction.</t>

<figure><artwork type="JSON"><![CDATA[
{
    "structure-version" : 1,
    "sequence-number" : 7,
    "components" : [
        {
            "component-identifier" : [0],
            "component-size" : [32567],
        },
    ],
    "common" : [
        "set-component-index" : 0,
        "do-sequence" : [
            "condition-component-offset" : "<offset A>",
            "set-parameters": {
                "component-digest" : "<SHA256 A>"
            }
        ],
        "do-sequence" : [
            "condition-component-offset" : "<offset B>",
            "set-parameters": {
                "component-digest" : "<SHA256 A>"
            }
        ]
    ],
    "fetch" : [
        "set-component-index" : 0,
        "do-sequence" : [
            "condition-component-offset" : "<offset A>",
            "set-parameters": {
                "uri-list" : [[0, "<uri-A>"]]
            }
        ],
        "do-sequence" : [
            "condition-component-offset" : "<offset B>",
            "set-parameters": {
                "uri-list" : [[0, "<uri-B>"]]
            }
        ],
        "fetch" : null
    ]
}
]]></artwork></figure>

</section>
<section anchor="manifest-cddl" title="Full CDDL">

<t>In order to create a valid SUIT Manifest document the structure of the corresponding CBOR message MUST adhere to the following CDDL data definition.</t>

<figure><artwork type="CDDL"><![CDATA[
SUIT_Outer_Wrapper = {
    suit-authentication-wrapper => bstr .cbor SUIT_Authentication_Wrapper / nil,
    suit-manifest               => bstr .cbor SUIT_Manifest,
    suit-dependency-resolution  => bstr .cbor SUIT_Command_Sequence,
    suit-payload-fetch          => bstr .cbor SUIT_Command_Sequence,
    suit-install                => bstr .cbor SUIT_Command_Sequence,
    suit-text                   => bstr .cbor SUIT_Text_Map,
    suit-coswid                 => bstr .cbor concise-software-identity
}
suit-authentication-wrapper = 1
suit-manifest = 2
suit-dependency-resolution = 7
suit-payload-fetch = 8
suit-install = 9
suit-text = 13
suit-coswid = 14

SUIT_Authentication_Wrapper = [ * (
    COSE_Mac_Tagged /
    COSE_Sign_Tagged /
    COSE_Mac0_Tagged /
    COSE_Sign1_Tagged)]


COSE_Mac_Tagged = any
COSE_Sign_Tagged = any
COSE_Mac0_Tagged = any
COSE_Sign1_Tagged = any
COSE_Encrypt_Tagged = any
COSE_Encrypt0_Tagged = any

SUIT_Digest = [
  suit-digest-algorithm-id : $suit-digest-algorithm-ids,
  suit-digest-bytes : bytes,
  ? suit-digest-parameters : any
]

; Named Information Hash Algorithm Identifiers
suit-digest-algorithm-ids /= algorithm-id-sha256
suit-digest-algorithm-ids /= algorithm-id-sha256-128
suit-digest-algorithm-ids /= algorithm-id-sha256-120
suit-digest-algorithm-ids /= algorithm-id-sha256-96
suit-digest-algorithm-ids /= algorithm-id-sha256-64
suit-digest-algorithm-ids /= algorithm-id-sha256-32
suit-digest-algorithm-ids /= algorithm-id-sha384
suit-digest-algorithm-ids /= algorithm-id-sha512
suit-digest-algorithm-ids /= algorithm-id-sha3-224
suit-digest-algorithm-ids /= algorithm-id-sha3-256
suit-digest-algorithm-ids /= algorithm-id-sha3-384
suit-digest-algorithm-ids /= algorithm-id-sha3-512

SUIT_Manifest = {
    suit-manifest-version         => 1,
    suit-manifest-sequence-number => uint,
    ? suit-dependencies           => [ + SUIT_Dependency ],
    ? suit-components             => [ + SUIT_Component ],
    ? suit-dependency-components  => [ + SUIT_Component_Reference ],
    ? suit-common                 => bstr .cbor SUIT_Command_Sequence,
    ? suit-dependency-resolution  => SUIT_Digest / bstr .cbor SUIT_Command_Sequence,
    ? suit-payload-fetch          => SUIT_Digest / bstr .cbor SUIT_Command_Sequence,
    ? suit-install                => SUIT_Digest / bstr .cbor SUIT_Command_Sequence
    ? suit-validate               => bstr .cbor SUIT_Command_Sequence
    ? suit-load                   => bstr .cbor SUIT_Command_Sequence
    ? suit-run                    => bstr .cbor SUIT_Command_Sequence
    ? suit-text-info              => SUIT_Digest / bstr .cbor SUIT_Text_Map
    ? suit-coswid                 => SUIT_Digest / bstr .cbor concise-software-identity
}

suit-manifest-version = 1
suit-manifest-sequence-number = 2
suit-dependencies = 3
suit-components = 4
suit-dependency-components = 5
suit-common = 6
suit-dependency-resolution = 7
suit-payload-fetch = 8
suit-install = 9
suit-validate = 10
suit-load = 11
suit-run = 12
suit-text-info = 13
suit-coswid = 14

concise-software-identity = any

SUIT_Dependency = {
    suit-dependency-digest => SUIT_Digest,
    suit-dependency-prefix => SUIT_Component_Identifier,
}

suit-dependency-digest = 1
suit-dependency-prefix = 2

SUIT_Component_Identifier =  [* bstr]

SUIT_Component = {
    suit-component-identifier => SUIT_Component_Identifier,
    ? suit-component-size => uint,
    ? suit-component-digest => SUIT_Digest,
}

suit-component-identifier = 1
suit-component-size = 2
suit-component-digest = 3

SUIT_Component_Reference = {
    suit-component-identifier => SUIT_Component_Identifier,
    suit-component-dependency-index => uint
}

suit-component-dependency-index = 2

SUIT_Command_Sequence = [ + { SUIT_Condition // SUIT_Directive // SUIT_Command_Custom} ]

SUIT_Command_Custom = (nint => bstr)

SUIT_Condition //= (SUIT_Condition_Vendor_Identifier => RFC4122_UUID) ; SUIT_Condition_Vendor_Identifier
SUIT_Condition //= (2 => RFC4122_UUID) ; SUIT_Condition_Class_Identifier
SUIT_Condition //= (3 => RFC4122_UUID) ; SUIT_Condition_Device_Identifier
SUIT_Condition //= (4 => SUIT_Digest) ; SUIT_Condition_Image_Match
SUIT_Condition //= (5 => SUIT_Digest) ; SUIT_Condition_Image_Not_Match
SUIT_Condition //= (6 => uint) ; SUIT_Condition_Use_Before
SUIT_Condition //= (7 => uint) ; SUIT_Condition_Minimum_Battery
SUIT_Condition //= (8 => int) ;  SUIT_Condition_Update_Authorised
SUIT_Condition //= (9 => SUIT_Condition_Version_Argument) ; SUIT_Condition_Version
SUIT_Condition //= (10 => uint) ; SUIT_Condition_Component_Offset
SUIT_Condition //= (nint => bstr) ; SUIT_Condition_Custom

SUIT_Condition_Vendor_Identifier = 1
RFC4122_UUID = bstr .size 16

SUIT_Condition_Version_Argument = [
    suit-condition-version-comparison: SUIT_Condition_Version_Comparison_Types,
    suit-condition-version-comparison: SUIT_Condition_Version_Comparison_Value
]
SUIT_Condition_Version_Comparison_Types /= SUIT_Condition_Version_Comparison_Greater
SUIT_Condition_Version_Comparison_Types /= SUIT_Condition_Version_Comparison_Greater_Equal
SUIT_Condition_Version_Comparison_Types /= SUIT_Condition_Version_Comparison_Equal
SUIT_Condition_Version_Comparison_Types /= SUIT_Condition_Version_Comparison_Lesser_Equal
SUIT_Condition_Version_Comparison_Types /= SUIT_Condition_Version_Comparison_Lesser

SUIT_Condition_Version_Comparison_Greater = 1
SUIT_Condition_Version_Comparison_Greater_Equal = 2
SUIT_Condition_Version_Comparison_Equal = 3
SUIT_Condition_Version_Comparison_Lesser_Equal = 4
SUIT_Condition_Version_Comparison_Lesser = 5

SUIT_Condition_Version_Comparison_Value = [+int]

SUIT_Directive //= (11 => uint/bool) ; SUIT_Directive_Set_Component_Index
SUIT_Directive //= (12 => uint/bool) ; SUIT_Directive_Set_Manifest_Index
SUIT_Directive //= (13 => bstr .cbor SUIT_Command_Sequence) ; SUIT_Directive_Run_Sequence
SUIT_Directive //= (14 => bstr .cbor SUIT_Command_Sequence) ; SUIT_Directive_Run_Sequence_Conditional
SUIT_Directive //= (15 => nil) ; SUIT_Directive_Process_Dependency
SUIT_Directive //= (16 => {+ SUIT_Parameters}) ; SUIT_Directive_Set_Parameters
SUIT_Directive //= (19 => {+ SUIT_Parameters}) ; SUIT_Directive_Override_Parameters
SUIT_Directive //= (20 => nil/bstr) ; SUIT_Directive_Fetch
SUIT_Directive //= (21 => nil/bstr) ; SUIT_Directive_Copy
SUIT_Directive //= (22 => nil/bstr) ; SUIT_Directive_Run
SUIT_Directive //= (23 => { + SUIT_Wait_Events }) ; SUIT_Directive_Wait

SUIT_Wait_Events //= (1 => SUIT_Wait_Event_Argument_Authorisation)
SUIT_Wait_Events //= (2 => SUIT_Wait_Event_Argument_Power)
SUIT_Wait_Events //= (3 => SUIT_Wait_Event_Argument_Network)
SUIT_Wait_Events //= (4 => SUIT_Wait_Event_Argument_Other_Device_Version)
SUIT_Wait_Events //= (5 => SUIT_Wait_Event_Argument_Time)
SUIT_Wait_Events //= (6 => SUIT_Wait_Event_Argument_Time_Of_Day)
SUIT_Wait_Events //= (7 => SUIT_Wait_Event_Argument_Day_Of_Week)


SUIT_Wait_Event_Argument_Authorisation = int ; priority
SUIT_Wait_Event_Argument_Power = int ; Power Level
SUIT_Wait_Event_Argument_Network = int ; Network State
SUIT_Wait_Event_Argument_Other_Device_Version = [
    other-device: bstr,
    other-device-version: [+int]
]
SUIT_Wait_Event_Argument_Time = uint ; Timestamp
SUIT_Wait_Event_Argument_Time_Of_Day = uint ; Time of Day (seconds since 00:00:00)
SUIT_Wait_Event_Argument_Day_Of_Week = uint ; Days since Sunday

SUIT_Parameters //= (1 => bool) ; SUIT_Parameter_Strict_Order
SUIT_Parameters //= (2 => bool) ; SUIT_Parameter_Coerce_Condition_Failure
SUIT_Parameters //= (3 => bstr) ; SUIT_Parameter_Vendor_ID
SUIT_Parameters //= (4 => bstr) ; SUIT_Parameter_Class_ID
SUIT_Parameters //= (5 => bstr) ; SUIT_Parameter_Device_ID
SUIT_Parameters //= (6 => bstr .cbor SUIT_URI_List) ; SUIT_Parameter_URI_List
SUIT_Parameters //= (7 => bstr .cbor SUIT_Encryption_Info) ; SUIT_Parameter_Encryption_Info
SUIT_Parameters //= (8 => bstr .cbor SUIT_Compression_Info) ; SUIT_Parameter_Compression_Info
SUIT_Parameters //= (9 => bstr .cbor SUIT_Unpack_Info) ; SUIT_Parameter_Unpack_Info
SUIT_Parameters //= (10 => bstr .cbor SUIT_Component_Identifier) ; SUIT_Parameter_Source_Component
SUIT_Parameters //= (11 => bstr .cbor SUIT_Digest) ; SUIT_Parameter_Image_Digest
SUIT_Parameters //= (12 => uint) ; SUIT_Parameter_Image_Size
SUIT_Parameters //= (nint => int/bool/bstr) ; SUIT_Parameter_Custom

SUIT_URI_List = [ + [priority: int, uri: tstr] ]

SUIT_Encryption_Info = COSE_Encrypt_Tagged/COSE_Encrypt0_Tagged
SUIT_Compression_Info = {
    suit-compression-algorithm => SUIT_Compression_Algorithms
    ? suit-compression-parameters => bstr
}
suit-compression-algorithm = 1
suit-compression-parameters = 2

SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_gzip
SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_bzip2
SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_lz4
SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_lzma

SUIT_Compression_Algorithm_gzip = 1
SUIT_Compression_Algorithm_bzip2 = 2
SUIT_Compression_Algorithm_deflate = 3
SUIT_Compression_Algorithm_lz4 = 4
SUIT_Compression_Algorithm_lzma = 7

SUIT_Unpack_Info = {
    suit-unpack-algorithm => SUIT_Unpack_Algorithms
    ? suit-unpack-parameters => bstr
}
suit-unpack-algorithm  = 1
suit-unpack-parameters = 2

SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Delta
SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Hex
SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Elf

SUIT_Unpack_Algorithm_Delta = 1
SUIT_Unpack_Algorithm_Hex = 2
SUIT_Unpack_Algorithm_Elf = 3

SUIT_Text_Map = {int => tstr}
]]></artwork></figure>

</section>
<section anchor="examples" title="Examples">

<t>The following examples demonstrate a small subset of the functionality of the manifest. However, despite this, even a simple manifest processor can execute most of these manifests.</t>

<t>None of these examples include authentication. This is provided via RFC 8152 <xref target="RFC8152"/>, and is omitted for clarity.</t>

<section anchor="example-0" title="Example 0:">

<t>Secure boot only.</t>

<t>The following JSON shows the intended behaviour of the manifest.</t>

<figure><artwork type="JSON"><![CDATA[
{
    "structure-version": 1,
    "sequence-number": 1,
    "components": [
        {
            "id": ["Flash",78848],
            "digest": "00112233445566778899aabbccddeeff"
                      "0123456789abcdeffedcba9876543210",
            "size": 34768
        }
    ],
    "run-image": [
        {"directive-set-component": 0},
        {"condition-image": null},
        {"directive-run": null}
    ]
}
]]></artwork></figure>

<t>Converted into the SUIT manifest, this produces:</t>

<figure><artwork><![CDATA[
{
    / auth object / 1 : None
    / manifest / 2 : h'a4010102010481a3018245466c61736843003401021987'
        h'd0038201582000112233445566778899aabbccddeeff0123456789abcdef'
        h'fedcba98765432100c4a83a10b00a104f6a116f6' \
    {
        / structure-version / 1 : 1
        / sequence-number / 2 : 1
        / components / 4 : [
            {
                / component-identifier / 1 : [h'466c617368', h'003401'],
                / component-size / 3 : 34768
                / component-digest / 2 : [
                    / sha-256 / 1,
                    h'00112233445566778899aabbccddeeff0123456789abcdef'
                    h'fedcba9876543210'],
            }
        ],
        / run-image / 12 : [
            {/ set-component-index / 11 : 0}
            {/ condition-image / 4 : None}
            {/ run / 22 : None}
        ],
    }
}
]]></artwork></figure>

<t>Total size of outer wrapper without COSE authentication object: 79</t>

<t>Outer:</t>

<figure><artwork><![CDATA[
a201f6025849a4010102010481a3018245466c61736843003401021987d00382015820
00112233445566778899aabbccddeeff0123456789abcdeffedcba98765432100c4a83
a10b00a104f6a116f6
]]></artwork></figure>

</section>
<section anchor="example-1" title="Example 1:">

<t>Simultaneous download and installation of payload.</t>

<t>The following JSON shows the intended behaviour of the manifest.</t>

<figure><artwork type="JSON"><![CDATA[
{
    "structure-version": 1,
    "sequence-number": 2,
    "components": [
        {
            "id": ["Flash",78848],
            "digest": "00112233445566778899aabbccddeeff"
                      "0123456789abcdeffedcba9876543210",
            "size": 34768
        }
    ],
    "apply-image": [
        {"directive-set-component": 0},
        {"directive-set-var": {
            "uris": [[ 0, "http://example.com/file.bin"]]
        }},
        {"directive-fetch": null}
    ]
}
]]></artwork></figure>

<t>Converted into the SUIT manifest, this produces:</t>

<figure><artwork><![CDATA[
{
    / auth object / 1 : None
    / manifest / 2 : h'a4010102020481a3018245466c61736843003401021987'
        h'd0038201582000112233445566778899aabbccddeeff0123456789abcdef'
        h'fedcba987654321009582d83a10b00a110a1065820818200781b68747470'
        h'3a2f2f6578616d706c652e636f6d2f66696c652e62696ea114f6' \
    {
        / structure-version / 1 : 1
        / sequence-number / 2 : 2
        / components / 4 : [
            {
                / component-identifier / 1 : [h'466c617368', h'003401'],
                / component-size / 3 : 34768
                / component-digest / 2 : [
                    / sha-256 / 1,
                    h'00112233445566778899aabbccddeeff'
                    h'0123456789abcdeffedcba9876543210'
                ],
            }
        ],
        / apply-image / 9 : [
            {/ set-component-index / 11 : 0}
            {/ set-vars / 16 : {
                / uris / 6 : h'818200781b687474703a2f2f6578616d706c'
                    h'652e636f6d2f66696c652e62696e' /
                        [[0, 'http://example.com/file.bin']] /
            }},
            {/ fetch / 20 : None}
        ],
    }
}
]]></artwork></figure>

<t>Total size of outer wrapper without COSE authentication object: 115</t>

<t>Outer:</t>

<figure><artwork><![CDATA[
a201f602586da4010102020481a3018245466c61736843003401021987d00382015820
00112233445566778899aabbccddeeff0123456789abcdeffedcba987654321009582d
83a10b00a110a1065820818200781b687474703a2f2f6578616d706c652e636f6d2f66
696c652e62696ea114f6
]]></artwork></figure>

</section>
<section anchor="example-2" title="Example 2:">

<t>Compatibility test, simultaneous download and installation, and secure boot.</t>

<t>The following JSON shows the intended behaviour of the manifest.</t>

<figure><artwork type="JSON"><![CDATA[
{
    "structure-version": 1,
    "sequence-number": 3,
    "components": [
        {
            "id": [
                "Flash",
                78848
            ],
            "digest": "00112233445566778899aabbccddeeff"
                "0123456789abcdeffedcba9876543210",
            "size": 34768
        }
    ],
    "common": [
        {"condition-vendor-id": "fa6b4a53-d5ad-5fdf-be9d-e663e4d41ffe"},
        {"condition-class-id": "1492af14-2569-5e48-bf42-9b2d51f2ab45"}
    ],
    "apply-image": [
        {"directive-set-component": 0},
        {"directive-set-var": {
            "uris": [[ 0, "http://example.com/file.bin" ]]
        }},
        {"directive-fetch": null}
    ],
    "run-image": [
        {"directive-set-component": 0},
        {"condition-image": null},
        {"directive-run": null}
    ]
}
]]></artwork></figure>

<t>Converted into the SUIT manifest, this produces:</t>

<figure><artwork><![CDATA[
{
    / auth object / 1 : None
    / manifest / 2 : h'a6010102030481a3018245466c61736843003401021987'
        h'd0038201582000112233445566778899aabbccddeeff0123456789abcdef'
        h'fedcba987654321006582782a10150fa6b4a53d5ad5fdfbe9de663e4d41f'
        h'fea102501492af1425695e48bf429b2d51f2ab4509582d83a10b00a110a1'
        h'065820818200781b687474703a2f2f6578616d706c652e636f6d2f66696c'
        h'652e62696ea114f60c4a83a10b00a104f6a116f6' \
    {
        / structure-version / 1 : 1
        / sequence-number / 2 : 3
        / components / 4 : [
            {
                / component-identifier / 1 : [h'466c617368', h'003401'],
                / component-size / 3 : 34768
                / component-digest / 2 : [
                    / sha-256 / 1,
                    h'00112233445566778899aabbccddeeff'
                    h'0123456789abcdeffedcba9876543210'
                ],
            }
        ],
        / common / 6 : [
            {/ vendor-id / 1 : h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' \
                fa6b4a53-d5ad-5fdf-be9d-e663e4d41ffe},
            {/ class-id / 2 : h'1492af1425695e48bf429b2d51f2ab45' \
                1492af14-2569-5e48-bf42-9b2d51f2ab45}
        ],
        / apply-image / 9 : [
            {/ set-component-index / 11 : 0}
            {/ set-vars / 16 : {
                / uris / 6 : h'818200781b687474703a2f2f6578616d706c65'
                    h'2e636f6d2f66696c652e62696e' /
                    [[0, 'http://example.com/file.bin']] /
            }},
            {/ fetch / 20 : None}
        ],
        / run-image / 12 : [
            {/ set-component-index / 11 : 0}
            {/ condition-image / 4 : None}
            {/ run / 22 : None}
        ],
    }
}
]]></artwork></figure>

<t>Total size of outer wrapper without COSE authentication object: 169</t>

<t>Outer:</t>

<figure><artwork><![CDATA[
a201f60258a3a6010102030481a3018245466c61736843003401021987d00382015820
00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210065827
82a10150fa6b4a53d5ad5fdfbe9de663e4d41ffea102501492af1425695e48bf429b2d
51f2ab4509582d83a10b00a110a1065820818200781b687474703a2f2f6578616d706c
652e636f6d2f66696c652e62696ea114f60c4a83a10b00a104f6a116f6
]]></artwork></figure>

</section>
<section anchor="example-3" title="Example 3:">

<t>Compatibility test, simultaneous download and installation, load from external storage, and secure boot.</t>

<t>The following JSON shows the intended behaviour of the manifest.</t>

<figure><artwork type="JSON"><![CDATA[
{
    "structure-version": 1,
    "sequence-number": 4,
    "components": [
        {
            "id": ["Flash",78848],
            "digest": "00112233445566778899aabbccddeeff"
                      "0123456789abcdeffedcba9876543210",
            "size": 34768
        },
        {
            "id": ["RAM",1024],
            "digest": "00112233445566778899aabbccddeeff"
                      "0123456789abcdeffedcba9876543210",
            "size": 34768
        }
    ],
    "common": [
        {"condition-vendor-id": "fa6b4a53-d5ad-5fdf-be9d-e663e4d41ffe"},
        {"condition-class-id": "1492af14-2569-5e48-bf42-9b2d51f2ab45"}
    ],
    "apply-image": [
        {"directive-set-component": 0},
        {"directive-set-var": {
            "uris": [[0, "http://example.com/file.bin"]]
        }},
        {"directive-fetch": null}
    ],
    "run-image": [
        {"directive-set-component": 0},
        {"condition-image": null},
        {"directive-set-component": 1},
        {"directive-set-var": {
            "source-index": 0
        }},
        {"directive-fetch": null},
        {"condition-image": null},
        {"directive-run": null}
    ]
}
]]></artwork></figure>

<t>Converted into the SUIT manifest, this produces:</t>

<figure><artwork><![CDATA[
{
    / auth object / 1 : None
    / manifest / 2 : h'a6010102040482a3018245466c61736843003401021987'
        h'd0038201582000112233445566778899aabbccddeeff0123456789abcdef'
        h'fedcba9876543210a301824352414d420004021987d00382015820001122'
        h'33445566778899aabbccddeeff0123456789abcdeffedcba987654321006'
        h'582782a10150fa6b4a53d5ad5fdfbe9de663e4d41ffea102501492af1425'
        h'695e48bf429b2d51f2ab4509582d83a10b00a110a1065820818200781b68'
        h'7474703a2f2f6578616d706c652e636f6d2f66696c652e62696ea114f60c'
        h'581887a10b00a104f6a10b01a110a10a00a114f6a104f6a116f6' \
    {
        / structure-version / 1 : 1
        / sequence-number / 2 : 4
        / components / 4 : [
            {
                / component-identifier / 1 : [h'466c617368', h'003401'],
                / component-size / 3 : 34768
                / component-digest / 2 : [
                    / sha-256 / 1,
                    h'00112233445566778899aabbccddeeff'
                    h'0123456789abcdeffedcba9876543210'
                ],
            },
            {
                / component-identifier / 1 : [h'52414d', h'0004'],
                / component-size / 3 : 34768
                / component-digest / 2 : [
                    / sha-256 / 1,
                    h'00112233445566778899aabbccddeeff'
                    h'0123456789abcdeffedcba9876543210'
                ],
            }
        ],
        / common / 6 : [
            {/ vendor-id / 1 : h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' \
                fa6b4a53-d5ad-5fdf-be9d-e663e4d41ffe}
            {/ class-id / 2 : h'1492af1425695e48bf429b2d51f2ab45' \
                1492af14-2569-5e48-bf42-9b2d51f2ab45}
        ],
        / apply-image / 9 : [
            {/ set-component-index / 11 : 0}
            {/ set-vars / 16 : {
                / uris / 6 : h'818200781b687474703a2f2f6578616d706c65'
                             h'2e636f6d2f66696c652e62696e' /
                    [[0, 'http://example.com/file.bin']] /
            }},
            {/ fetch / 20 : None}
        ],
        / run-image / 12 : [
            {/ set-component-index / 11 : 0}
            {/ condition-image / 4 : None}
            {/ set-component-index / 11 : 1}
            {/ set-vars / 16 : {
                / source-component / 10 : 0
            }},
            {/ fetch / 20 : None}
            {/ condition-image / 4 : None}
            {/ run / 22 : None}
        ],
    }
}
]]></artwork></figure>

<t>Total size of outer wrapper without COSE authentication object: 235</t>

<t>Outer:</t>

<figure><artwork><![CDATA[
a201f60258e5a6010102040482a3018245466c61736843003401021987d00382015820
00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210a30182
4352414d420004021987d0038201582000112233445566778899aabbccddeeff012345
6789abcdeffedcba987654321006582782a10150fa6b4a53d5ad5fdfbe9de663e4d41f
fea102501492af1425695e48bf429b2d51f2ab4509582d83a10b00a110a10658208182
00781b687474703a2f2f6578616d706c652e636f6d2f66696c652e62696ea114f60c58
1887a10b00a104f6a10b01a110a10a00a114f6a104f6a116f6
]]></artwork></figure>

</section>
<section anchor="example-4" title="Example 4:">

<t>Compatibility test, simultaneous download and installation, load and decompress from external storage, and secure boot.</t>

<t>The following JSON shows the intended behaviour of the manifest.</t>

<figure><artwork type="JSON"><![CDATA[
{
    "structure-version": 1,
    "sequence-number": 5,
    "components": [
        {
            "id": ["Flash",78848],
            "digest": "00112233445566778899aabbccddeeff"
                      "0123456789abcdeffedcba9876543210",
            "size": 34768
        },
        {
            "id": ["RAM",1024],
            "digest": "0123456789abcdeffedcba9876543210"
                      "00112233445566778899aabbccddeeff",
            "size": 34768
        }
    ],
    "common": [
        {"condition-vendor-id": "fa6b4a53-d5ad-5fdf-be9d-e663e4d41ffe"},
        {"condition-class-id": "1492af14-2569-5e48-bf42-9b2d51f2ab45"}
    ],
    "apply-image": [
        {"directive-set-component": 0},
        {"directive-set-var": {
            "uris": [[ 0, "http://example.com/file.bin" ]]
        }},
        {"directive-fetch": null}
    ],
    "load-image": [
        {"directive-set-component": 0},
        {"condition-image": null},
        {"directive-set-component": 1},
        {"directive-set-var": {
            "source-index": 0,
            "compression-info": {
                "algorithm": "gzip"
            }
        }},
        {"directive-copy": null}
    ],
    "run-image": [
        {"condition-image": null},
        {"directive-run": null}
    ]
}
]]></artwork></figure>

<t>Converted into the SUIT manifest, this produces:</t>

<figure><artwork><![CDATA[
{
    / auth object / 1 : None
    / manifest / 2 : h'a7010102050482a3018245466c61736843003401021987'
        h'd0038201582000112233445566778899aabbccddeeff0123456789abcdef'
        h'fedcba9876543210a301824352414d420004021987d00382015820012345'
        h'6789abcdeffedcba987654321000112233445566778899aabbccddeeff06'
        h'582782a10150fa6b4a53d5ad5fdfbe9de663e4d41ffea102501492af1425'
        h'695e48bf429b2d51f2ab4509582d83a10b00a110a1065820818200781b68'
        h'7474703a2f2f6578616d706c652e636f6d2f66696c652e62696ea114f60b'
        h'5585a10b00a104f6a10b01a110a20841f60a00a115f60c4782a104f6a116'
        h'f6' \
    {
        / structure-version / 1 : 1
        / sequence-number / 2 : 5
        / components / 4 : [
            {
                / component-identifier / 1 : [h'466c617368', h'003401'],
                / component-size / 3 : 34768
                / component-digest / 2 : [
                    / sha-256 / 1,
                    h'00112233445566778899aabbccddeeff'
                    h'0123456789abcdeffedcba9876543210'
                ],
            },
            {
                / component-identifier / 1 : [h'52414d', h'0004'],
                / component-size / 3 : 34768
                / component-digest / 2 : [
                    / sha-256 / 1,
                    h'0123456789abcdeffedcba9876543210'
                    h'00112233445566778899aabbccddeeff'
                ],
            }
        ],
        / common / 6 : [
            {/ vendor-id / 1 : h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' \
                fa6b4a53-d5ad-5fdf-be9d-e663e4d41ffe},
            {/ class-id / 2 : h'1492af1425695e48bf429b2d51f2ab45' \
                1492af14-2569-5e48-bf42-9b2d51f2ab45}
        ],
        / apply-image / 9 : [
            {/ set-component-index / 11 : 0}
            {/ set-vars / 16 : {
                / uris / 6 : h'818200781b687474703a2f2f6578616d706c65'
                             h'2e636f6d2f66696c652e62696e' /
                    [[0, 'http://example.com/file.bin']] /
            }},
            {/ fetch / 20 : None}
        ],
        / load-image / 11 : [
            {/ set-component-index / 11 : 0}
            {/ condition-image / 4 : None}
            {/ set-component-index / 11 : 1}
            {/ set-vars / 16 : {
                / unknown / 8 : b'\xf6'
                / source-component / 10 : 0
            }},
            {/ copy / 21 : None}
        ],
        / run-image / 12 : [
            {/ condition-image / 4 : None}
            {/ run / 22 : None}
        ],
    }
}
]]></artwork></figure>

<t>Total size of outer wrapper without COSE authentication object: 240</t>

<t>Outer:</t>

<figure><artwork><![CDATA[
a201f60258eaa7010102050482a3018245466c61736843003401021987d00382015820
00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210a30182
4352414d420004021987d003820158200123456789abcdeffedcba9876543210001122
33445566778899aabbccddeeff06582782a10150fa6b4a53d5ad5fdfbe9de663e4d41f
fea102501492af1425695e48bf429b2d51f2ab4509582d83a10b00a110a10658208182
00781b687474703a2f2f6578616d706c652e636f6d2f66696c652e62696ea114f60b55
85a10b00a104f6a10b01a110a20841f60a00a115f60c4782a104f6a116f6
]]></artwork></figure>

</section>
<section anchor="example-5" title="Example 5:">

<t>Compatibility test, download, installation, and secure boot.</t>

<t>The following JSON shows the intended behaviour of the manifest.</t>

<figure><artwork type="JSON"><![CDATA[
{
    "structure-version": 1,
    "sequence-number": 6,
    "components": [
        {
            "id": [ "ext-Flash", 78848 ],
            "digest": "00112233445566778899aabbccddeeff"
                      "0123456789abcdeffedcba9876543210",
            "size": 34768
        },
        {
            "id": ["Flash",1024],
            "digest": "0123456789abcdeffedcba9876543210"
                      "00112233445566778899aabbccddeeff",
            "size": 34768
        }
    ],
    "common": [
        {"condition-vendor-id": "fa6b4a53-d5ad-5fdf-be9d-e663e4d41ffe"},
        {"condition-class-id": "1492af14-2569-5e48-bf42-9b2d51f2ab45"}
    ],
    "apply-image": [
        {"directive-set-component": 0},
        {"directive-set-var": {
            "uris": [[0, "http://example.com/file.bin"]]
        }},
        {"directive-fetch": null}
    ],
    "load-image": [
        {"directive-run-conditional": [
            {"directive-set-component": 1},
            {"condition-not-image": null},
            {"directive-set-component": 0},
            {"condition-image": null},
            {"directive-set-component": 1},
            {"directive-set-var": {
                "source-index": 0
            }},
            {"directive-fetch": null}
        ]}
    ],
    "run-image": [
        {"directive-set-component": 1},
        {"condition-image": null},
        {"directive-run": null}
    ]
}
]]></artwork></figure>

<t>Converted into the SUIT manifest, this produces:</t>

<figure><artwork><![CDATA[
{
    / auth object / 1 : None
    / manifest / 2 : h'a7010102060482a30182496578742d466c617368430034'
        h'01021987d0038201582000112233445566778899aabbccddeeff01234567'
        h'89abcdeffedcba9876543210a3018245466c617368420004021987d00382'
        h'0158200123456789abcdeffedcba987654321000112233445566778899aa'
        h'bbccddeeff06582782a10150fa6b4a53d5ad5fdfbe9de663e4d41ffea102'
        h'501492af1425695e48bf429b2d51f2ab4509582d83a10b00a110a1065820'
        h'818200781b687474703a2f2f6578616d706c652e636f6d2f66696c652e62'
        h'696ea114f60b581d81a10e581887a10b01a105f6a10b00a104f6a10b01a1'
        h'10a10a00a114f60c4a83a10b01a104f6a116f6' \
    {
        / structure-version / 1 : 1
        / sequence-number / 2 : 6
        / components / 4 : [
            {
                / component-identifier / 1 : [
                    h'6578742d466c617368',
                    h'003401'
                ],
                / component-size / 3 : 34768
                / component-digest / 2 : [
                    / sha-256 / 1,
                    h'00112233445566778899aabbccddeeff'
                    h'0123456789abcdeffedcba9876543210'
                ],
            }
            {
                / component-identifier / 1 : [h'466c617368', h'0004'],
                / component-size / 3 : 34768
                / component-digest / 2 : [
                    / sha-256 / 1,
                    h'0123456789abcdeffedcba9876543210'
                    h'00112233445566778899aabbccddeeff'
                ],
            }
        ],
        / common / 6 : [
            {/ vendor-id / 1 : h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' \
                fa6b4a53-d5ad-5fdf-be9d-e663e4d41ffe}
            {/ class-id / 2 : h'1492af1425695e48bf429b2d51f2ab45' \
                1492af14-2569-5e48-bf42-9b2d51f2ab45}
        ],
        / apply-image / 9 : [
            {/ set-component-index / 11 : 0}
            {/ set-vars / 16 : {
                / uris / 6 : h'818200781b687474703a2f2f6578616d706c65'
                             h'2e636f6d2f66696c652e62696e' /
                    [[0, 'http://example.com/file.bin']] /
            }},
            {/ fetch / 20 : None}
        ],
        / load-image / 11 : [
            / conditional-sequence / 14 : [
                {/ set-component-index / 11 : 1}
                {/ condition-not-image / 5 : None}
                {/ set-component-index / 11 : 0}
                {/ condition-image / 4 : None}
                {/ set-component-index / 11 : 1}
                {/ set-vars / 16 : {
                    / source-component / 10 : 0
                }},
                {/ fetch / 20 : None}
            ],
        ],
        / run-image / 12 : [
            {/ set-component-index / 11 : 1}
            {/ condition-image / 4 : None}
            {/ run / 22 : None}
        ],
    }
}
]]></artwork></figure>

<t>Total size of outer wrapper without COSE authentication object: 258</t>

<t>Outer:</t>

<figure><artwork><![CDATA[
a201f60258fca7010102060482a30182496578742d466c61736843003401021987d003
8201582000112233445566778899aabbccddeeff0123456789abcdeffedcba98765432
10a3018245466c617368420004021987d003820158200123456789abcdeffedcba9876
54321000112233445566778899aabbccddeeff06582782a10150fa6b4a53d5ad5fdfbe
9de663e4d41ffea102501492af1425695e48bf429b2d51f2ab4509582d83a10b00a110
a1065820818200781b687474703a2f2f6578616d706c652e636f6d2f66696c652e6269
6ea114f60b581d81a10e581887a10b01a105f6a10b00a104f6a10b01a110a10a00a114
f60c4a83a10b01a104f6a116f6
]]></artwork></figure>

</section>
<section anchor="example-6" title="Example 6:">

<t>Compatibility test, 2 images, simultaneous download and installation, and secure boot.</t>

<t>The following JSON shows the intended behaviour of the manifest.</t>

<figure><artwork type="JSON"><![CDATA[
{
    "structure-version": 1,
    "sequence-number": 7,
    "components": [
        {
            "id": ["Flash",78848],
            "digest": "00112233445566778899aabbccddeeff"
                      "0123456789abcdeffedcba9876543210",
            "size": 34768
        },
        {
            "id": ["Flash",132096],
            "digest": "0123456789abcdeffedcba9876543210"
                      "00112233445566778899aabbccddeeff",
            "size": 76834
        }
    ],
    "common": [
        {"condition-vendor-id": "fa6b4a53-d5ad-5fdf-be9d-e663e4d41ffe"},
        {"condition-class-id": "1492af14-2569-5e48-bf42-9b2d51f2ab45"}
    ],
    "apply-image": [
        {"directive-set-component": 0},
        {"directive-set-var": {
            "uris": [[ 0, "http://example.com/file1.bin" ]]
        }},
        {"directive-set-component": 1},
        {"directive-set-var": {
            "uris": [[ 0, "http://example.com/file2.bin" ]]
        }},
        {"directive-set-component": true},
        {"directive-fetch": null}
    ],
    "run-image": [
        {"directive-set-component": true},
        {"condition-image": null},
        {"directive-set-component": 0},
        {"directive-run": null}
    ]
}
]]></artwork></figure>

<t>Converted into the SUIT manifest, this produces:</t>

<figure><artwork><![CDATA[
{
    / auth object / 1 : None
    / manifest / 2 : h'a6010102070482a3018245466c61736843003401021987'
        h'd0038201582000112233445566778899aabbccddeeff0123456789abcdef'
        h'fedcba9876543210a3018245466c61736843000402021a00012c22038201'
        h'58200123456789abcdeffedcba987654321000112233445566778899aabb'
        h'ccddeeff06582782a10150fa6b4a53d5ad5fdfbe9de663e4d41ffea10250'
        h'1492af1425695e48bf429b2d51f2ab4509585b86a10b00a110a106582181'
        h'8200781c687474703a2f2f6578616d706c652e636f6d2f66696c65312e62'
        h'696ea10b01a110a1065821818200781c687474703a2f2f6578616d706c65'
        h'2e636f6d2f66696c65322e62696ea10bf5a114f60c4d84a10bf5a104f6a1'
        h'0b00a116f6' \
    {
        / structure-version / 1 : 1
        / sequence-number / 2 : 7
        / components / 4 : [
            {
                / component-identifier / 1 : [h'466c617368', h'003401'],
                / component-size / 3 : 34768
                / component-digest / 2 : [
                    / sha-256 / 1,
                    h'00112233445566778899aabbccddeeff'
                    h'0123456789abcdeffedcba9876543210'
                ],
            }
            {
                / component-identifier / 1 : [h'466c617368', h'000402'],
                / component-size / 3 : 76834
                / component-digest / 2 : [
                    / sha-256 / 1,
                    h'0123456789abcdeffedcba9876543210'
                    h'00112233445566778899aabbccddeeff'
                ],
            }
        ],
        / common / 6 : [
            {/ vendor-id / 1 : h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' \
                fa6b4a53-d5ad-5fdf-be9d-e663e4d41ffe}
            {/ class-id / 2 : h'1492af1425695e48bf429b2d51f2ab45' \
                1492af14-2569-5e48-bf42-9b2d51f2ab45}
        ],
        / apply-image / 9 : [
            {/ set-component-index / 11 : 0}
            {/ set-vars / 16 : {
                / uris / 6 : h'818200781c687474703a2f2f6578616d706c'
                             h'652e636f6d2f66696c65312e62696e' /
                                [[0, 'http://example.com/file1.bin']] /
            }},
            {/ set-component-index / 11 : 1}
            {/ set-vars / 16 : {
                / uris / 6 : h'818200781c687474703a2f2f6578616d706c
                             h'652e636f6d2f66696c65322e62696e' /
                                [[0, 'http://example.com/file2.bin']] /
            }},
            {/ set-component-index / 11 : True}
            {/ fetch / 20 : None}
        ],
        / run-image / 12 : [
            {/ set-component-index / 11 : True}
            {/ condition-image / 4 : None}
            {/ set-component-index / 11 : 0}
            {/ run / 22 : None}
        ],
    }
}
]]></artwork></figure>

<t>Total size of outer wrapper without COSE authentication object: 275</t>

<t>Outer:</t>

<figure><artwork><![CDATA[
a201f60259010ca6010102070482a3018245466c61736843003401021987d003820158
2000112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210a301
8245466c61736843000402021a00012c2203820158200123456789abcdeffedcba9876
54321000112233445566778899aabbccddeeff06582782a10150fa6b4a53d5ad5fdfbe
9de663e4d41ffea102501492af1425695e48bf429b2d51f2ab4509585b86a10b00a110
a1065821818200781c687474703a2f2f6578616d706c652e636f6d2f66696c65312e62
696ea10b01a110a1065821818200781c687474703a2f2f6578616d706c652e636f6d2f
66696c65322e62696ea10bf5a114f60c4d84a10bf5a104f6a10b00a116f6
]]></artwork></figure>

</section>
</section>
<section anchor="iana-considerations" title="IANA Considerations">

<t>Several registries will be required for:</t>

<t><list style="symbols">
  <t>standard Commands</t>
  <t>standard Parameters</t>
  <t>standard Algorithm identifiers</t>
  <t>standard text values</t>
</list></t>

</section>
<section anchor="security-considerations" title="Security Considerations">

<t>This document is about a manifest format describing and protecting firmware images and as such it is part of a larger solution for offering a standardized way of delivering firmware updates to IoT devices. A more detailed discussion about security can be found in the architecture document <xref target="Architecture"/> and in <xref target="Information"/>.</t>

</section>
<section anchor="mailing-list-information" title="Mailing List Information">

<t>The discussion list for this document is located at the e-mail
address <eref target="mailto:suit@ietf.org">suit@ietf.org</eref>. Information on the group and information on how to
subscribe to the list is at <eref target="https://www1.ietf.org/mailman/listinfo/suit">https://www1.ietf.org/mailman/listinfo/suit</eref></t>

<t>Archives of the list can be found at:
<eref target="https://www.ietf.org/mail-archive/web/suit/current/index.html">https://www.ietf.org/mail-archive/web/suit/current/index.html</eref></t>

</section>
<section anchor="acknowledgements" title="Acknowledgements">

<t>We would like to thank the following persons for their support in designing this mechanism:</t>

<t><list style="symbols">
  <t>Milosch Meriac</t>
  <t>Geraint Luff</t>
  <t>Dan Ros</t>
  <t>John-Paul Stanford</t>
  <t>Hugo Vincent</t>
  <t>Carsten Bormann</t>
  <t>Øyvind Rønningstad</t>
  <t>Frank Audun Kvamtrø</t>
  <t>Krzysztof Chruściński</t>
  <t>Andrzej Puzdrowski</t>
  <t>Michael Richardson</t>
  <t>David Brown</t>
  <t>Emmanuel Baccelli</t>
</list></t>

</section>


  </middle>

  <back>

    <references title='Normative References'>





<reference  anchor="RFC4122" target='https://www.rfc-editor.org/info/rfc4122'>
<front>
<title>A Universally Unique IDentifier (UUID) URN Namespace</title>
<author initials='P.' surname='Leach' fullname='P. Leach'><organization /></author>
<author initials='M.' surname='Mealling' fullname='M. Mealling'><organization /></author>
<author initials='R.' surname='Salz' fullname='R. Salz'><organization /></author>
<date year='2005' month='July' />
<abstract><t>This specification defines a Uniform Resource Name namespace for UUIDs (Universally Unique IDentifier), also known as GUIDs (Globally Unique IDentifier).  A UUID is 128 bits long, and can guarantee uniqueness across space and time.  UUIDs were originally used in the Apollo Network Computing System and later in the Open Software Foundation\'s (OSF) Distributed Computing Environment (DCE), and then in Microsoft Windows platforms.</t><t>This specification is derived from the DCE specification with the kind permission of the OSF (now known as The Open Group).  Information from earlier versions of the DCE specification have been incorporated into this document.  [STANDARDS-TRACK]</t></abstract>
</front>
<seriesInfo name='RFC' value='4122'/>
<seriesInfo name='DOI' value='10.17487/RFC4122'/>
</reference>



<reference  anchor="RFC8152" target='https://www.rfc-editor.org/info/rfc8152'>
<front>
<title>CBOR Object Signing and Encryption (COSE)</title>
<author initials='J.' surname='Schaad' fullname='J. Schaad'><organization /></author>
<date year='2017' month='July' />
<abstract><t>Concise Binary Object Representation (CBOR) is a data format designed for small code size and small message size.  There is a need for the ability to have basic security services defined for this data format. This document defines the CBOR Object Signing and Encryption (COSE) protocol.  This specification describes how to create and process signatures, message authentication codes, and encryption using CBOR for serialization.  This specification additionally describes how to represent cryptographic keys using CBOR.</t></abstract>
</front>
<seriesInfo name='RFC' value='8152'/>
<seriesInfo name='DOI' value='10.17487/RFC8152'/>
</reference>



<reference  anchor="RFC2119" target='https://www.rfc-editor.org/info/rfc2119'>
<front>
<title>Key words for use in RFCs to Indicate Requirement Levels</title>
<author initials='S.' surname='Bradner' fullname='S. Bradner'><organization /></author>
<date year='1997' month='March' />
<abstract><t>In many standards track documents several words are used to signify the requirements in the specification.  These words are often capitalized. This document defines these words as they should be interpreted in IETF documents.  This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.</t></abstract>
</front>
<seriesInfo name='BCP' value='14'/>
<seriesInfo name='RFC' value='2119'/>
<seriesInfo name='DOI' value='10.17487/RFC2119'/>
</reference>



<reference  anchor="RFC8174" target='https://www.rfc-editor.org/info/rfc8174'>
<front>
<title>Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words</title>
<author initials='B.' surname='Leiba' fullname='B. Leiba'><organization /></author>
<date year='2017' month='May' />
<abstract><t>RFC 2119 specifies common key words that may be used in protocol  specifications.  This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the  defined special meanings.</t></abstract>
</front>
<seriesInfo name='BCP' value='14'/>
<seriesInfo name='RFC' value='8174'/>
<seriesInfo name='DOI' value='10.17487/RFC8174'/>
</reference>




    </references>

    <references title='Informative References'>





<reference  anchor="RFC6920" target='https://www.rfc-editor.org/info/rfc6920'>
<front>
<title>Naming Things with Hashes</title>
<author initials='S.' surname='Farrell' fullname='S. Farrell'><organization /></author>
<author initials='D.' surname='Kutscher' fullname='D. Kutscher'><organization /></author>
<author initials='C.' surname='Dannewitz' fullname='C. Dannewitz'><organization /></author>
<author initials='B.' surname='Ohlman' fullname='B. Ohlman'><organization /></author>
<author initials='A.' surname='Keranen' fullname='A. Keranen'><organization /></author>
<author initials='P.' surname='Hallam-Baker' fullname='P. Hallam-Baker'><organization /></author>
<date year='2013' month='April' />
<abstract><t>This document defines a set of ways to identify a thing (a digital object in this case) using the output from a hash function.  It specifies a new URI scheme for this purpose, a way to map these to HTTP URLs, and binary and human-speakable formats for these names. The various formats are designed to support, but not require, a strong link to the referenced object, such that the referenced object may be authenticated to the same degree as the reference to it.  The reason for this work is to standardise current uses of hash outputs in URLs and to support new information-centric applications and other uses of hash outputs in protocols.</t></abstract>
</front>
<seriesInfo name='RFC' value='6920'/>
<seriesInfo name='DOI' value='10.17487/RFC6920'/>
</reference>


<reference anchor="Architecture" target="https://tools.ietf.org/html/draft-ietf-suit-architecture-02">
  <front>
    <title>A Firmware Update Architecture for Internet of Things Devices</title>
    <author initials="B." surname="Moran" fullname="Brendan Moran">
      <organization>ARM Limited</organization>
    </author>
    <date year="2019" month="January"/>
  </front>
  <format type="HTML" target="https://tools.ietf.org/html/draft-ietf-suit-architecture-02"/>
</reference>
<reference anchor="Information" target="https://tools.ietf.org/html/draft-ietf-suit-information-model-02">
  <front>
    <title>Firmware Updates for Internet of Things Devices - An Information Model for Manifests</title>
    <author initials="B." surname="Moran" fullname="Brendan Moran">
      <organization>ARM Limited</organization>
    </author>
    <date year="2019" month="January"/>
  </front>
  <format type="HTML" target="https://tools.ietf.org/html/draft-ietf-suit-information-model-02"/>
</reference>
<reference anchor="Behaviour" target="https://datatracker.ietf.org/doc/draft-moran-suit-behavioural-manifest/">
  <front>
    <title>An Information Model for Behavioural Description of Firmware Update and Related Operations</title>
    <author initials="B." surname="Moran" fullname="Brendan Moran">
      <organization>ARM Limited</organization>
    </author>
    <date year="2019" month="March"/>
  </front>
  <format type="HTML" target="https://datatracker.ietf.org/doc/draft-moran-suit-behavioural-manifest/"/>
</reference>


    </references>



  </back>

<!-- ##markdown-source:
H4sIAGjNrV0AA+292XbcWHYo+I6vQDPvaklZEUFGcBDFuiqbmpyypVS2hkr7
prW4EAEECSsCCAMIMpmZ8tP9iF6rX/oz7nN73f/qPZ4BQwyiskpyUR6SAeBM
++yzz553v98PqrSaJSfhm3fP34aPH716Hc6jLJ0mZRWWSZFGs7SMqjTPwmle
zKMqiMbjIrk8CZ+lxfwqKpLwpX7+jD+I80kWzaHHuIimVT9Nqmm/XKZVX/vt
7+0Fk6hKzvPi+iRMs2keBOmiOAkXRXK4f//4bbEsq9He3oO9UQADRDC3ZLIs
0uo6uMqLD+dFvlzwfIMPyTU8ik/C51mVFFlS9Z/goEFQVlEWn0WzPIOJXCdl
sEhPgjAsppMkLqvrmTwNwyqfOH+mWZxklT4o86Iqkmlpfl/PvZ9VkU7Mx5N8
Poe25m2azdLMDpP8XPUBlFUfOhnnM/isn3/7B3gD4JpHi0WanfO3QbSsLvIC
ZtuHt/gvzeDrR4PwZV5EmTxjCD8qkiyOMu9NXpwDnH+hPTsJT4t5+CKdp1US
y/tkHqUz03RATf8+KuYDWEBQG/S7Qfi2nFzk0yRLz72Rv4uyLCmbbzcc/YKa
DyrTfMUMHqXFh4t89os/fpJ9qL/xx35WRMsMey/CN4Ap/vDQejCW1n9fptVg
ar4exEkQBBnhcnqZINa8fvb4YDgayZ/Hw0P4E1A2m9Y+Onow2sM/T4vJBax5
Ui0LegXbHxXnCaDKRVUtypPd3SoHFBjg0RjArHcvqvlst35cIqeXPhwF6ofP
6qk9fe8WMRwlb0g8qeZAhPk0fHsB2FWGT5LLdELYGIYGydZgWBeKwRxev/T2
FqdxEv5jlC2j4joc7Q0f0GOGkQ4Uht+9ffnipnB4rpCHff5k8Ka2k/48j5NZ
DcY1CJdroBr2w9PMnRlADDqlVkohvzrQd8DoUXIRXab50iyiDn+YUFQV0eQD
HCczAhA6GWCOC+IRxtpVNDP3w672KsjeBdZHti3sQjkp0gV9AXtTPx5wGYSv
kxn8GYevFklBXZUyjr8h7VuyclM6tkU35iVisN2WdRtzU+AFQb/fD6NxiZ1U
AaBpGZaLZJJO0wmDMCZgjQFpq4tEZoNQi8zVPwAiZvmAtAyicLzM4lmCn82T
KsJJwhj5suI+FN64LwCd5/lbGAUPRi+8ukjgRZUHU7hdva979CuWA1Tl8GkK
kEqrEC7EWZqUPdq4SXG9qPLzIlrA68DBSWAYciQMcA6pJzN7BsE8jWHGQfAN
UoyqyOPlBFsFwamd75LxY55M4EpKyzmsFeeflCXc5cD8AA/ErEc4TSJLXM3y
aNpxAh9epdVFeLmcZYBd43SWVjD/QfjjRQpAw8nBbmTlAjgKBKEZP51H59yJ
B4qLZF4ms0v4E+aTzrFZlBGooQ22i2bAGMXX4WVUAAJAC1hAlv77ElpEl3DH
ReMZgLdcAjgj3uYX6flFdZXg/weMBJKaJf0q78uf4d0XVy9HL+8RSPNJPoNZ
wmWIkOVJIXBhqsji4AIcCAzCp/++jGaza2eiKY+ZZpPZspQziWjTr+HNJM8u
k2s4lD5AwrtpZnDTx8x7hBL4blkSNsJxxHXAf+xeKV7AwLQ9+CMEAmaOQEm9
3M2JYODc7+GH8+hDEgJzmxTQdZKdA1wYBHDmYHPSKTRfzuBwPG0ZE3rJr3jZ
TFAQ83M4NuksLv1DQmvs4YjjBPYIT8cFnMAsD3Pc4XARFdDhXYJejOMvYDmM
jlGMs4NNT8p74QQwFYhVBUPXMboM88xDU0RPhHoUJ7BbgPKLIr0E3DzHDSQa
wbMW/glBCM0I/5IM5xiH42sX7nESIzDhOXC0sLfAC4d4+O0vYM5LnR98lvOW
2kmd0FnC7iZRiVMk7M4zxCS4Z8/rWwlTKWDyKc4lJRwrl7glKeIkAFNBEcFZ
AwkCthi4y6I57gAlFUS9aRozWJ2BGrhYylhRHKeKLXYezrBJSpsHEgfCYQ6I
ki7g7K+ETsvc3sBlShStDZujykEwmlVYpOUHIHVVes4bZygBiC+NpSDW60kq
CX8QA6u84P1ZZgQ5+FEkQKuAMc4R0/5IJHkG/cF3SyFQYTnJFwkfTmDcYZLz
lDEjyhBA0vwal43bWcwBYRDxymsYYS7YDzgPAlxJJwCWB1DIEM2hFxA+CSBB
8JzhX5bLOUL8QoCABDAhIEyjORDcqGAajO8ugMz1Z3CSGwcjdNnJ8NdfXcb5
40c5CnDbLonSIY4BSOhtjJR0mtMxR4ETGhuJ1nz08WN4lZgLVm4lIGZEBnBX
x7N88qHEBbo3Fm2M098Ebi7oCnC0gtalXA4ei4OPSFyvdQUAews/SZx3bnCQ
eYBXANRFmoc7FdPpgxEArNwpnG/8CRcVEL7YkncCyTyJaB4AfD4PWV7J50s6
NVFJiAD0PONjYid8mRiI9vA7BQ8cY4Si4eMM/J3BIiQQRXiZJld6zSNUUNLW
lZvdukrhGMrRDJG/pRY5NfZbpohrTNWdSV5F1wNiFx6bZfCReQvYm2b5LD+/
ZujC4UW8BcK+8/Ldm7c7Pf5v+P0r+vv10//r3fPXT5/g32++O33xwvwRyBdv
vnv17sUT+5dt+fjVy5dPv3/CjeFp6D0Kdl6e/ssO80U7r354+/zV96cvdkK6
Ll3EjQgCeMLo7C2KhPco8GD/6PEP/9//OzyAPfg/QHwdDYcPAOn4x/Hw/gEi
M4jKPBrRZf4JoLwOgEVLooIgCVCfRIsUqGBJ+1te5FdZiNQcwBl8S7h4Er7J
py5LjthHtK8hUjFb+Pzp22cI4w+4iaTzkSZ0JmFGUREPoPMfoutZHsUoFC/S
ZEIUyOURGQogM8AOwyEGDLtewMWFVPyZy7XimItlAWQrIczCSWP/r5MSUHOS
dA9AZ6JEPKX7wBwKQLEFTw77USFwdT+WNdd7BJFUugHIuE8LmZmwybQAvrWB
oobAu8Q8IeI8iZMyLRArctMtTo935SR85Qxgbwpvbq1Ts32Ep8xIVNcnIZ4V
wAW8FumecDl5OkQKtDI9z5R16YV6C43xIpmkC7rhlR7RnshDHoFvFGhmdrYm
gtD0oackRZbaEXOgLzjrfLHjxlRILEmGQVCCoAjXr1AZMyZdaHh7wqUHkABy
gt08AZozIV0QCqzRRFWmtbYI9aTAzeCx5zAVwl0zDWITbHdMkIiax+k5Tk8u
haQI4JiGqI2CIyt6KTixMO9L4GtK+x2rLhDCJMH0wpenjxllkox2BEbtwQ1F
HOg4KmFr6kMNCM7mpyIXQ0o+FsKL8IWNAMJDzNU0TQoaK3KaK1yK6Epbo2AA
zE8+Z6afjqC8mkeG4XK4MOSSQSQH4kFXVEJsJPEz8A3NDW9qvTO4q0F4OjtH
1LyYO9PDC2lKVx4QM4Qp6vEYpvgXwDSi07bUS5NJbQuIXHYBSYIltsI720k9
fvLkxUkQ/Md//EeAm3v2hLt7GP4UhCTcc//9SCfcT+PwJPxvXe/Knt9ufI1C
wElI/4V3f+e9tbCDT4BfC94HwR/D7yNksFxly3dReeHA7LmFWdA2h3D3Yeg+
6JcX0ejwaJtv+8PR8Zbf7231/YPtpnN0sNXn+6ONP98/3rzrw+EW/fZHo817
hq+32KD9/jaz3u/jvBHFkYY9SdFgAmQG0V+58qD1qfBnKEL1WRhOssu0yDNl
yiMrjYe56vNALo8mFyI9O9QIP4WrH1qWy3HJnIZDbkglgTQGOVokHxO8QtPx
jDgoZG6wR9LmvDRCnRLTklqOEysRTkEQ0hYskNjxRcTmzohcVDlcWbiiSU7s
Ca5c+NIFNCX+2BdREJY/Als0BULCt6ooaFBndo1QjOoyD7GsriwAdAkWwDcv
slg8T7jzlrxa4LhVb5cgSEsRP+tSi3I9MM0S1g/XScI3RfLzgmXpK52pXBU8
VRGZabJ67Sv1Hhf5hyQDTvYqYy7lEGhqsiiBWA4H4Z+TIp0yLTV7UJ9WMPK+
I13ihHVy141v9wfE4c0uCeQJ2v8msD3BwSB8llSETsTg3C3vBYcDII4s7DtP
gx+BKdYlRaqpQO5gBhS2B/ME6ZQ4ZUtXZa3mRrmMZikAgQEC0vcyy/BvVUDg
aZguC9IvVBdFkhiQHJml0rc4n/uD8AVMzT44hiUuM/ubJ2wUFJbLI4zRKZmN
6TEO6Gd3Sh48zCeTJfP/Icm08BAk8fIC1vdHOja2Y5DvHPBeEx86W7Keibkh
vCKTKSI+ag8Mgsnb0rLS4RR3BeZUTYg18uXc8xxkEB/dPYGnqkv3KB1lsfKg
sGWKNYaLF7xvSsYNzYKuCc62qCxQZeKOQDpCo4ggYiAKZOGsGWt+1k+EnRfj
k740jHBgDEuoep2RcpYl8TbR22jPQtR1O1pnPvBGhnDxlIw+JPWhVhR2IQNJ
WjXhrBQjkQrBCv9LZA+IclQgDw50NKuWpCLEHtyxiIRP05+TuD9dZgxkkLAB
RZX+hHeZC7cU6Z6nziYWU0Uvy/grOYrCcZ5XiDAoewiauns4mSE/ztQqLctl
ojoNlF+BspCqGHEkc7TyMBqeXFRZnieo6J+pyChzLEX74mAfcIezNuSL0jnt
AICwQEVrRSwsKehIripyuIHgE9TK4H4pJys4wWppMoXhhRNZmbLMpxWhJc2X
hDNH5OlZhYColeD6I4k7s6etxHuRZZiyx1Q4ktFgHWylIRKsQ5mWyc/QbMZH
yFzMJLBXCoTEmwtsTmyYZ0eHbiAIYwPNgLH5oqaNvIqueXWAphOAG3qOTNIy
QQ0F3mRXqiMUXOLriM8lHUrU9OPhn8J5opseB+iFs/RD4qFOjzfDfEarZxUY
IkKc/xHI1iRalok/aRYo+EDolbMDOwei77y34317B4GWTJZimWu2M1Y+fcDi
LtxPciMwjrEuGYG4gIGQYvtchadna9MR1u+kiIxLCd+ZRjMC10++PCdTAgrB
QC+TyfVkJve+1WeympTubJyzUbWwcgB3tUiiElXaZAwqkhn89LmXAV7k2Pj7
pCIuhS23La2RMgKm2Sve7WSfO2E7fXcfRPqgm0lV7+CgswO2iQGDpzws3xXm
YiDSLsT6kHv5YYZU5SU1bJkE8ArCAyD5XFRRxoe6bt4Z4M1vTYatq1Fu8zr8
P+lvlN0mDQChIYhX47IwA2Qj1vVfZ6xcoB2vbe5xTLXWDzZaXMeC4HziCQZS
TPIAn5qSMBtZkQWwIWVIqmVHMqhwI+v8rcHuHhpTiA26wNvVNJMbdc5aoOBt
Hl4yN+ZNTyaEu5v0WJFK53iOhjHkcvKii71WsUII5IRVbpY4NNic0vY/XZJR
1hjgLIAQvTICG55hl+9t4alYWAiRkqAiPXguNJt0WaxssgTSEiujCfWsCShW
oEW8rFBXH6k2hK+8/AqukeXMNa0LZU0LWg2qmY1xndXE/lwrouvMpigd7PH9
ofenEdQ8uho5OjrVGiLkEuA44fW/oT0RLhnyCpCOXD5J1ZhoakZTgVy+ZgjZ
vnPSP46BdZgi4HEmwPmLXhAOa5koREljFIXCxcGIQDbOl4SjBel05MZii9dV
TqItmt7Reqb4SdYboLx40+KMTR9o1P25QrwFBEFbWUi2sh7tGBAzHBBWbTDJ
ucnFKGOcAq717g/jJdnKl9bjhiyYCeO+f0RJFuErw0xKfFQIQAI2EX3QkRKu
IrmY5j1jzB4XaONFnC+A0ckXsFyjR0XezLJKZCxe4EFLYtZ9ogoMjsWMjRvL
qp9P+4zXLofFwr0jpFw7RmeADiHkLHF48kfXRgdolI/CuND1DLxLzz+6RmmP
vARwXojAcNiuWSBRTwSGPNEwjy1myi0snW8JZKRzv02zy5xPCPr2sqFjwkpo
9MmMZ6gRpIESQEzyE4h81TTzKomnog5f5qLBrRlMafcQv8hkfo6CAcykQoNP
T9hIEbpSMSrzPIWLhvMGQqrY+ZQ99I4qob8KDipJsD3fatprUpVoZdiUHRNd
u4Bj7qOOZckshAx/GunO2PtJh7IuMDFypGxBrIx8n2d9vgRUlGEgmAsFT68c
IKQm+VXGMi+xY0g9shCOFF096AdCint4x71coLIWye5FMvnQQ02+9brwLlsR
OQDKT6xMTtsvR+UyKhG5zd6QTHmVzGaD8IlzWRiIM+MMJAh4w4oYWLme9HCj
I1SSOWII3aORoxPoKU/NKKoWJ319p3R2gWSkWCT1tHAoOR7PpCL65ZoHHgmP
TnKNo/vG08bYYJwtaMniJKT+ac6KSXogdUbkOI0Rg/JvTScjsrGZ0XJS46Df
1blcikR1aRvgv/mC2V8Q/Jas+piDYMriE7tMIBNcGkLC8liV50xH7aFQEdWg
6enjF0ZUjuCOHLMfH2vzSU+JIH2s9ixHze/NgiQx665Et4OjPFKOJ6qsvYPu
YGAwEaHZ4FJdC/hIy8p3JsJEvEhoAgCRx3rRsysJe8QgcWFlmoecg/C0tnpu
wi4SLtb8YDdDPRnkViitEsOj7yJYygm04o2RYibAmRI5tDyICp/+nJifF8rG
k1feVTgskY4dRmRpVNCGiTXMg9Ci5DJxiKzLcS3gtBNNEjYqii9RmoitvtXy
Usj2Ad+HSh7CjqesTCqDR23SrSspwkY7+u1JhRotPLnmGdK7smeOXtX0fZHu
gB0BWhxbTzXoYSK8D2wZs+iWsriCJ2/chNncHVoGtBvshPpn3daOB2FykSaX
cqUneEyFs0O8cD4l9Yrqm1FxZKyYZa6GZZg44SesO09EjUSz9xXVTe8WOk90
7GviTGm2oh1m7PplpQ9jUpVZdogUAwsRZ0NEG4KCiDV8gFA7iYq4Y3xmAwty
4Jrl2TnZhPFER8W13RF7G6qWJK1cJQ96niHrp5hUV/wAVpzj+SL2ga5r9t1L
fo6QsPVwdIysgVX/gigxT0WLLfbpdMqvSZBi7DLb6bBfIv+KjwixDlGL8IIC
pZwLGmQegeRjN4qcFQQTYIB5cyhfEpmLnhJGEY50Fk34CnAtwqoFgs/q+jOD
geiQQ8eIxapx4lNjviDcTq3ClB3AYPsP2FTMohh54zE6/WLEYmutp4uxYH19
oiBhcbbgtndloEewI/d2j8M/QP/i6cSq5LEDuoGhN3DUi/NVfbw8/RevqcqT
ZhYGMefIYa3rTqbkTYZIoeMBJgrdBUA/Ttl3hi9gs5nsHoCWRcCcIR1FMZks
iJrJthnG2B4Q+P5DkiyERePuIwEl/qEHkncQrRstrYCzzcfIfZRsxcjOCRtx
M++ShyC5YqIpgNxq8fYb9kf79wZkCSJ/Z1gLIIHKeGoHYk8v+lmiVyrygVU4
9JW17F0ttIahOCNeDZ4Y/XBSFHnhbA4RAzryywy4d/LBxQeoccRNgOv4B500
zGycsCjYmCVCvbgUheXz0+9PUcxAbZwYhL9PziOvE2PiQqmJ2ZxrVWQRe66R
EtaiwsMhT/LkyQsKA+FuLq4XcMSI2yH2Cd+aLVZPUbUlCTLBJZwvRBP++NWb
p67nDoc0nr3RLs7QHYOxUXzcykD/oMOOyg6kBdfsMdNjxFPSOE4zoMW98CL5
GW7fPvAxIN0CBZpN9R1d0r3wh6cvw0lSVMy3QkvCmR+TcfgWLbE9EwbKl980
PV8qeNntRl3AwiliLVkLUCMBwgCILhLoCTzGiWg45M5kU5Qrl5BoBAixiCYf
VAvqNIlzvFgxHpAX1pg37YI3d2mzyWiD8LsWQLEWo335G/UaBG/4nrX7Jm4G
MYnPTIHh0FRiIQyvQAzh+4Q3CVAqieaN6ZH71mxKGgphScLzaFGqGU/YbLgg
QQAr4ApOOHYnh+HzDPE7Q9ZVPLZZIFSZnPkBYH37jipEbiyaozc11xUja+VA
S2Q7OoAoGhaGGB0MvX2dj1C1gOKsP0H0Q567LAvM2IQttEy0Ry5QBFs8KbwB
BG/eqR85uoYVUTJZBxut55g6V/as85saD2dX0TVxomgFJTmL7KaZo4ZVn1Cf
k8GgI8Q43WEU6+Hogrw4S5qbbEyR+hSpAFvy+D4k72w1G15dJGQogi5pki2z
Yal/lsZrtkpkB5L9iIMUFQgpf+C7C71tRWhJqybTa/3x9DgI2NAAzpCrRDHT
Ptcr1iW4+6QfFeqTQoJWWqrStiSSZIyqyi0rJ3WCqkkySIIIj9I3XcakhmF9
Z+dYwmnCqUNCCQCLVZOBC1P9eMTKGWGkdB0qk5PChrAlmlakpXMMMUJkvenL
1YdeK2xUhZcIQba3mUuCo4oSnF7HAuprJY8I9hSUSVIMaJ+PARnkWnp3+yb7
hwYatnevavsz6cq6FxX6XMT0s+eoJ1amdXytfTW5ZHs6+WjkhVBX0byxejH1
vHDI1mGyF5h7N/z1m5a4jqYPVcp6eqI0yvfISkrVfMLDYnJx7UaO0BZhZyDj
wg5cFWiQKigWVF44vDtCxf1i5JtZTQQptHyMdAyOj+u/ad5DuxcpCxOel5O+
37fv9aoy7w6a79groqWfwwEpXEgjyE0mqlSF2yVWjbFtcORoFD2/oNeJmDBI
t79ZZ/cNdrKX0Cd1cmycvKJPnsgD8crSLbSf77Z8PdwTj601nw3Zj2vNV4gi
KPPu2pnbl7DPwHb++PxJ4/V+10Z0D3dQB3f3p4c1oHZ/ecTTD2Q/O2ZLm+TE
lD22fODd8h58/vjHt9wfbMUbkqZ+cDz2gKV+5Z0+uipYiGLVStNXXUIz0cum
RR2SO6RehB9PPUyxz4k1R7NaBf3RZ1Z2lVceYWBxSWZDxJ40ASLwkV6dJThv
PoVCi6KZdWFZs/ueo1woOV43to465pbmS5lpJhIgEnZqASvYQCed4mUO5M5x
cCeAn/0oHzwMf6Xt4QwPHsHraycP/8QTG0zGeWFweMU/GufU68wMuBtm6axn
xzSg8v95Y5rLwWlnTRJ955DU2tFERPN89kY8Y51O9G7lY9Mx+LpONO505QrW
dUJ5aeD/kgKtXqs6wVN5hneL03qSl1dp3Gjvt+YjHHwMVu51OAz8fXkYjoIV
EH8Y3g9aYPkwPA486DwMHwRmpTjMfuBMHR8cBMEqxHkY/hR+G95Faf3sZTQ5
exudn8MJ2SX5/exNep6ZR5vgqPaz19LRUJ7de89O8+uJAzFYYz136vmIsEfv
JLSLov6OdRBkA3VcoMmnzrP18hn2g7RsJLY0kwmxnGksQsJwNVNGOR2Q24mr
5ya+V10mV2GHiYONzA08NBFo/nzbmSfL8Xd60Cijze4JnjdtWN98xmp/9zmw
l/mzl66avsUuhnYcjgOGDdtB/z0AhZFvdsi0xz3VRyYdR/vQNHPP27k1Pox2
Ab0ykutcPH5NJLfnocoTWLUtFPJKNlSSnjze3iP3PVTLRUU8Q9Ec2acoQx0E
2tlVhwpPUXfDN6Iw7agypDHEuIpCbstdIq4254ggHMgA3yma5o5IumoxA0wL
4ps30ESNQtxFFNfRyjUQcbgZzZPV7yqTV2vAJ1Pk0DvRE2J4MveFwfHLGVqH
fbronAWDZkZMUQWJfyvbYAUTE6witbqCeUZuFMUIbMa66/jSddPkXsvlJio0
X6D0GUELK2NKqUd4s6aWDRYZBamJfavBifXqweUgkem7jx8VmHQXWEDCnmEf
F0v4so9pBSL29e2MzUWIEeQkOKhlGmiJcuCOX6fkgs8RuPBMJyM3kbOvj/OM
jM5vVH1uDfKqTWGtmdjorPHMRsumU8JdVk+wFtmgy6/fuFBpeKy7qDNRqdIk
/TGxm8pixs46kS03MZqsCJFlsdwbqduKKOQbihg3frIqk9kUVQ6RiS6SZujT
a6+CetxO5IhpGqIr9tgkRj/clR+QRdvt8WhAplaVAo11R72xrQGQbwD0nLUj
iBe91XzZLSov8uUstvHAtA9+hGg4LaLzOTslsme4d2U57PVLyzf92uRy+wp2
h0UbtnDDfQV0X/YHvlvCDc6f/l3t8COt8HjGn8I/iFbGipLvvbYOwMOOttYP
5X37sNdeL61Nz6zU3hh/7oBha6a5OZeaFCD6qN3t+usWCD6tv27ZYOP+3O5U
ibY91NxeSFPQ/LdlL8WyuX3b90JyD1L4zQFEAtDLaOGjE9HuDeFsJKGg/XA2
hKDmcWwIRXgGH4ZGqDHn4mF40BCfvNeHgXsgHoZHn1XaMhgDa9oL7PbDT1kj
7iP8GgW1/WgX0UgeeiNaVrgIZ7FRJRvKJ35EkocpYlugvU/Ig8vRGdNdlXgR
ApSHyvqVq3LZpFRgLzBL8WkiA8dvSmaGd7aTtoWMzSpS0LA2UK7HHiotjggY
OYoEbI7OtcsyQc94+taKhJPJcnHNUlC5iCYmi5IzeeYu2VNH2YH2vBrGS9Jd
OinDCJCnRREx1yMhwbpm5bTtp+zSkmr6pAhzzvUBdlfoT8QwLNyMGNZrXi1V
ZA3jbpELHydJxiOKYSfpuN7U1sD3pD7lbFKOXKoeABJY5ouBf5ZWQ81ip910
R5IOuqYD8svp909O3756/S+t866fb4KhsdFyUj2207JBvEr7BTAI42jyAXiX
JapAbVDbRTJblH5eQgtXSqxIMhAHwFvHTVnlTpHn1Y5j4siMyzEb/SS83nxA
Uoq4wtb4M3JHVLFLj1gj1IT7s5hQF/Wa0lhzoBnGjPA4lJNFnKNrnxGMxHWI
nTEU9dhP9t3bx+ynWEXzBUezo4a61GDTRndrd9Hd9ibBTl1NRp1hEmmeFs3e
KK6bLYc9itpHjJsaOk0Mu0Cg7l2pocTxoIWJg/loLinMt+YE+MQcDbJMywvo
pbrCg+hcI8ahx+WeW6dBiTzXNPT9wY3v0YdkUfGmkJdmQpCjUI9W5r11eNFs
u1ptEkxd9zaKNujs1vHwlRSFtkezsHrSG8dDq82BkiO0XNbe9YGuX+lNrLGs
chvSEO3CrFy+usJNvknqhqh9/iKeqITu59NRkmB1Zl1wkEldqWNifadkEqqU
rG3coCE2OLgqd1sVYuxoRWmpfOpkvCMavRC8GmfzekNwO+JFG+BvBgb3FKwB
S+fEndPscnm0pFbemG5DCe0xDrESBEM3z7WohDRayMn3wb6kRtJVBwIdU86J
xmWY1CCaC0TDAkhFMud42nOidZo14FqNYCY8526ZJKzccZ5+/EjMBbFDLsa7
9kay0fPMUVtRA04dbO3M8GZQTN0wSQ2Ra7OwtkGQQabuNwi2d6+fl56yw7kU
emx/5WS9ba8RtE6KkbaP7hilWxO3/LWbq433p/U2kYtJ4ehLDdvDLx/LMTa+
U+RVZ29F1Ic5BLlMXGw0eliVUtTfRAM80yljGYc5SvYh9hkjt35XYamq+ZaE
FxjDfhmJL35L7KuNbIDTVCXoG8/OaewET0naqui8TmLbIVhHVV3b9sC1aXMN
dLsQkoOb2ftGnZgkeyzCub4kjCddyOcUvWFduNg3vtkAMdXxubNTqi+yvn4j
cG4PANPU0dGV5M44tUmV7I5wXgUyd7VB6pJyCTEhs2F/XuZd5/kgbMzeso7h
83qkjOqI3fPGSSGFv3OOLc1F7BULShNhb5Vigzac1J9dH2e+gcBKq8qBAjx1
Dboj6la4La0skM1L3Iw/Jux0DbUUXJNUR5KJCySgKOMQfz5n5LD1+vRlL7Tp
v0Oba1u71QjNONEciQi2OKFcxwmFxA1Cb6F1lEQNx/brx1a6hIFVeXkRG2oo
EF//1KYqOlH1B4t0y2zH+icZZTsGZJPobjlaaaDus+5u13twzUXW8tHo05m7
C5vwFTLPHqtG7qsmE7/j6tqyBteCw/oiyQZ3bpjqJWW/xj1V5qts4zTJSUo9
MJHgEH2SUcnAKPbFgYkhanJVpKD61BlM2MzT1yiJvsN8bzYxOwFnat98Uxcp
xcHBkTFtrH09cNExcm3Ch7YaLXwTUmNsEwbjpr+07z0DhsOFCIQf/slTb7V+
Cgd0mv5sPrV8uzWk9YKPrFQ0SpnmUBZK1UXSxjXZnR6bzTbXo3IGLWZaNq1b
1/G617On1nQsYjYhRSW+AeGb9PzM03Gis0A90sjLp+1kVSXvXTYJO1OwEWA5
2hXCi/xKPMyY6TGBfvWIYBP+FjnJ+SQ9lbUvaoTkGPirD/69IgGvFHEM3dwZ
5/H1mUnMf4cuUX7IYY53jC7UsmSkCvOmKCG+BDPNLGwz0hfXpgSB5jwkp3Pn
PRxNHK/09qXnRfsB5FPg3FC8sHl2TdkGzUvlZpwxHssUwQ+sIt0+xreDSK16
f2Aa7TY8FTxXValzM3Tivaap9VCbHUBQPDWpvdyzz2yxqRNh4zedjxiLRMkr
eQdyT7VgvN0lZQb5ExecnQPvkavM8TcwSk0ZzbswNKX3YpZfMwKbZIbmYmow
3RxJpE8R83FkSXjC0NOZGr9tWbGj4W6hswbKNqmWo5hxnQaELzEJw5V4aPrh
DuUVAUMmKvctpoDEWVG9uU4NlBxKEwLR2I12bQT5F3gpRJKficVyc163a/B8
/e5mV8NjR+Vl7gMLQO86MOO7d+VqMu9Z67Q16f3abNv2E3vd6E0jF4ZJJtHS
pXF2afQjaliLn3ktZ2g+nZZJJWpPGyZGoC+B87GcH3MDNdiF3zGVVqtRZRRz
JrWF8eWwOSl68p2TpcImGeOThRn2XO6lNE5ADjIYlZETMOboVkiSicYleTu5
M6Oz/D+SIifIff/uxYselR5hZm9mDiBqc0wKRk8korPDd45zBhi9vAwVoYmZ
Mtk2OYu7aD1aDrRV87UdbUcJuOKQO2c7ynyvKntniXUPST7e/0VqslX5Sapq
HXgRn5yJoXDKYXk2tlmef6gnPXv3+rmRCXjWlFzKzzdp9HWsUHNT11AU1jlg
ypVNA+ULTBktYDbVMjGNkPptaYQFeiu1cPbkc9CN+lG2Ny8r9YWCKGVwfayc
VCPkbmVP2EfK23rtxEAQ8ts4iLZk927YEsCslqMiLR3aIBHni1quEy32k1Q2
GarcfFj3xJ0w6c7p8IyTk0BDk55L8LgGIj3CLGSY+DA7LzWE5FGez5DXlOA7
ubwpd4OGiFtPLyWYcEPNookpLeZMnHjH+tWPSJGBRObPgMx7KjiiFbrPxt3Y
hErwGdbzaNM/+KTPSdmPAQzQygAmfIzG4t/Yxv0W88/+Fj5JphGqin4L3xAP
9Rsl0acXploPFqP7reX/giF8N2aIwV/46x9m+Rh2+zeMRksnVfiKtAK/ha81
m3mTAJK2VWx7RnOZUuwb503TpMzop0AA3GO+XbOLcBY0k/7J3SKLk4Ng5E12
z53s4zwB6uzkCXsWpTPk/fWVcJlLzvlDNnetGyXGBHZyI2adP6K8NkxixpS1
zWTDsQcHVkbjDIJ9nBw62vyGYR40rhzaXTPLP8PZxSwBT+DvU63pGr57Bw8M
j6RE75K/1QJDbKmQFMzM6x1sMOLjWQQr2WjACX26YrzDDcaTDKUbDdg2xlH3
GI58/hvdGxQSiMPQadCzpuayIsowmBuNFsH9DXt9aoqRUAgjd44iroQvmZue
biX78VzQicQ70lkGx51Dyt+iwLMDmYtA3lCki4wcPFjV3TvSVtd64odeJ0M8
MnBZ7Hb29IY8g71Hp903FAUh2JRdeB8Fw+GGsKa4WvVRM8Pw72A42qqXN0jH
f9Prgch6APtUtS4XpG8g6eYPS1thEk4WDqXShjiL/7n57cm6H9LF7immdQUm
ZRadD0L5kRI/ZvJead5yZc0o8lyLZSKvsiKJlkgzNqaPrDVi0kTMc8bHvt8+
eoIZQ5r3UP2+4ZCBRvyO5Q2bmZMik/lRc7qdnxeU6MRLe8dZ6ZQdIn6YZyCq
CFEeL3LSdbC7QhFx8cu0MnLzEra7oIJb9fprbXme2AAbo95Lna2YublM1RWL
SgsC7yHp3YRd8XJaSugJ3qTEpsSJJoIw6bXQLoMrfOxzUU8sF2UTc6Pgn7iZ
mzjHYGzqBaYYZnkuWfLTuUSVzq6RpfumHpPOV/MZXc0iF7iXtUVps10u93KO
DL7cbA7Lp76LbBDwE5L6ehdCPMoHWKpjlLhgZZQwR3Jfsj0BwK1JLykxZJ5L
Ljd+7SZzZyO7TqChgDGWdXOczCRyw0WkJluvy05oymofTjFzTtT+bbFMXB8t
EQyfwQQSWzvALMlJR2sQYk5pRTXPZIHFTVEorOS2iOsMhzhNh6cvXtjMktal
Tct3xPXQJWJkKsqBMV2FGSTyrnjPOcmAHkkZFgQBzwZTDqpyyp2XTsn19so4
kIUXlZZ2+1oxl5mxM3NkzoRPk4ogjrtHA1Coq8DoZurx9TKzZixT28vnybg8
SNmZ6pa4Ot+7jkDWyUsiUSUYpZUArgzfMLM4CF+hXHyVlv5rTy/b5Bo3BQ+5
sSJ3H6v4AbOd5aTkkHtTzrEHGURoSqrCtSVsrA4h9IqGIXttcpr3oLmNllEi
BgOuxhrn5MWK2Ch0JBZc04ZYh8W1ungRlcxVcGf2EEN9iCpw9UBE6NXTCDUj
WiK1QEl5LR85gZP+Cw2D7TWvwLal1zk0uGLr3JwuHkXstjKNtlCTW5HIc9Jx
TLwOrXEqR/bEFpKJWhQhFrVUlhuI5a17ATUVUdXQhnCNOPozaGdSG4oOeWvr
c3maDm1rqrqVdf2ntndYCYmu0CDujlE0fKGrk3AUNNdg54ElxLpfn53/ki5u
0HwMzUc3aA+7hOaxG/Tw4n8c3KD17Jd5tAp8BB/ag3VAoI1Yv1IKK1k5oQOK
MlkzZ4odUfVY7TQ4YpIszRWcXDLmnuTOE2zToEehpBOrKy0pxxalxENVp02D
N2jKbVufTLexdyjZoanlPEqL9qMorbpPYaNbewJb2prD1xg03FXMq786e5LM
qmj7Zt+BLLp1o6ezaccMeRoWt9vGs0jd1jHhcjsSlryDq/0Y0AOq1mxQ336n
R7PIDqlhg+87ebUN2rKm6+z5k40GQs3Tht+ygmnDj9+9fn6GWqJNvq2zNBsB
qMYKbDIlh95ssmekkHEMvBu0cTOWbf496lA2WjSpTRpchSdYPAzvDolU5Pns
XpP/6OBxodWos5VBKPxsX+lQs3NBJfzqoPMrg0T42WHnZ4o++NVRW3inftBo
WWdMoYP7bR3UvmuBVYPTunvcEWjqfdhci3cz3H3Quhz7TaN9HRFpj/e6plLX
FDa687LqYVfDtq74fUdjUvph05EawZrgYxUffETaQPiM1IGAX7u84YG3jZRo
5w/hT2RKpuLhaJsPl0V6Elbw/fvwvbSo7dvDNkljt03IuGWgbxnor5SBvuUw
vzoOs+7wjQmGWl9YlYVTlWlF3hDSBlLybzSHTkgviPGZntMp5orX8DyqiivW
bVPo3tPLkfqQtRmcqMWx87w20T9O+ldWJGEeFn3g5nfELCxsHPqziXSg6sn0
DHNdAo+NiVUwnyXcN4/yvKpX65N8qV5FUbIIWG/XmvtpdeHVly21/I2bRz8I
XqgXndGuSnAZ92tKRFzl4YcUX8OnYjxg0DgWBxpWszVB86Tfp3TsVm9YUXkY
0YgZ1ejUCSfZRejhtUh1qx37hde5o9hFQWXWuohZfi4xAl4NLspPKzFv2OYX
9Lcy2dPsahjiLO563zhuAGSY+fZbGenbb13v5NJ1nuiWmIMG/ispc+ZCWV2+
tbCWLC6OxUS+MAB7bx26STVXFTlWDPGr+U5sFrzULUhsnJx7XFMj8deF5LxK
MvWI+5AYz1VGseLEd0aqLw8Zm7vyUha06yuA74WS848OgdVVe55BWlc8p8Je
U0bHU6OrJ78Kq3xEdDrNjGGLI1WBCHm/fbJgchtRdWWLXoO1LkvGHmfKlCkj
2tNAaFs0Gb48L/IlK9TPKeMDIRZXFOnZbNVmaYTClecd63j7kS8W+8FwTmax
cJLvomNIaevGiUKBXtSkqT1GIVWcoDyI9CgTC4AdHeQYCnyx2iIhRZSRLhMb
GOnUTbaIZ+J0p8WjKUFF5VSWjFFDRQ4NV3nrWEqz0DRqffjzDJNfZOK7KZCl
sqTTaILmVrJbSdSTl8TYgtzDNoUoGeeKZaa1NZt5kJ08vtY12DqlRWyKV9wT
KNqwHmNudOz6ZEuXekya1qOeyt6lqa4VSiwbJvd4F/GVQrH2zpYO0LBgcd0p
GiLVyhCdMEEhVghDE0Gl17bWajMhXRwy5VT1G0vlXKnLc20zNCR954BBM8CN
Sh5JqjuKvTIbRC4IyjBY+PfEy5hQL5OYBmPhJV87wwHgRnpXmuUCrAlO/d7M
A/FxM6QEneGCumeb+ltZj5XffJ+kpsVnZJ2mtmi177g+bdHswHiwvCQf5988
J5hD8/b7vGr9Ar2l3sHhfcTmWPQEkuJb6gpjUoqQD9RLTMe6nIePyFJ93dKA
/JbeMaJwnWxKqW98a8gRSdPT/GayshvHTHIxskqCV+RR3jaOuOeIhG739Tcx
vNUuIUnMQkE0Uc2NL1O7dKpu3k5DblPq2ZMy8y75NfZll5dhBleNoNKr5X/R
ykipb4imLLMPGcaO+OhKdmB/3sZZMDClhWwbtz7QJxUV8hpx0cOkojo1rdWF
XM9KMtUDitpTSExeoXk1MNjDXut9rutpKcVJjXQZbZ11Zq5/IYo65wO8HWsf
qZ7OCR3yOXSHWGkYcEQ5Z+nUUc5Z/OvjRz6BHj9LV7PlEyUSgpMTcFoIJyRW
LzpfZuFyJQQqfzLiREIUmzgBrJBqQu/NJcR45VxKKdcIRsosmJraVDs49Jq1
6ae6NptyWLFM/VvpQsUEnasG94U+KvyLj2A06wVnMyPNMG/ptWbKwu+Vm0Cv
X0er7N65NAXo0MmxVYlt23eXKAfrUKgNgxqISAht80f4adHWoZ8bfuU3dZxd
bHvWUxLhDoI/c1V2IyY2mUjeNHVU5o2QUEkFlI3X1Og5d6vsWy6BgkzPOXIy
XsEb01IvYEOuS7mLO8cyCYW8OBeuMmOC8Fu67NWQsH0/HXD5ST42hTRck5tD
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
66klcZIUHjOEc/WLKTsuclAB1g5PCuLn3tCh5UY8UfGbslep21hS4ZkO0J9o
4Ab+O7vAvqbE4fPpL7Am36X6L0idO7R11lW1//jm1ffoEMnUwsSbOY6TMbBs
JGJhHP+FDnOlWdxNWykCBawZ3YgG92x6J88ZzmWkkWNC2Q5HPt19FJaw9XxY
Obu+9GQdBSVm/CpS124O2QEUmUjOLhAtcWkBG5p2TLU2FaV3wpNw2JOXAsc+
s3n46r68suwePmWJHf/9av7yP+vb3I3UYE/q0rV8iYl86Jv90eHRfee7j/zn
ezuFOc/XDo9ey/2J75WCX+zZXnbivK8L8xtLr5pCxnbD2Icf7/x3wcTTP+3U
FoAjW3lg56QGitoi+XBwl2++O4WVYpdei4/m1/vPPftHf9HZe7tGR/ur2rRl
kfbxDqFxf9rrQX/4CDp7//7L3rCOmT/acOZmq7LlbMabqKUivwmfwTO2Z/36
jfHJncQxXnSeK5nJBIhVh0iraVMZGK0LscSmcKQG4OUFOtQhhNB2hkncgYCW
VHgM/dGimGss5C3uDux0RQqN1FI+NsqReu7VEt2ZfiTv1cKvCewwgrgxV/pN
01Bx6n1pettFvbyTlsrQZ/9fS4cKGaexk5WkMAVlWxvXzSZOJ+IPKX7Hq2aw
ohOtCrF+GSs6qYDZr/fQ3slb+BIAsvDye8ENGK9pjAlf0jLpazbZvjJ5Wpy5
a3+1QrPZLkz7tGIPsLx0C3QfhseBB6+H4YPArh2G2Q/c1cCDA1Hjd+DTQyrY
epfgQOXZX0YTqcwe7tqnb9LzrOUxfLzX8fVQnt97D2JwveeHGI8SNHp2Hrs9
174etjz3C823vKl1pjatc94LpJy8G/TEFteGDQYi9d+63lGCOPfl+Bo5tpOQ
/osv/8577Sj1TmgeAJw/UuoqrANos4J+F5UXoSll7SX47pwKJjVzH/TLiwhu
z60b9Iej409ptLd9owefMLujg+3b7I+2a7N/vOUgh8NtR+iPRluOAU223c39
/tYr2e/jWgLvxvCvMHMja2pZh1QOW26mfo3VV8eAnlv13tP9eNT3J7UvOxar
915bx8oQdrS1vp/v24e99nppbXr2mjSBKDM3xp87YNj67mrOpXYZu7Rqd7tO
uy/nG3TafVlv16nb5yXXpE+2B6LbC/noNv9t2Qta/W7eC97IfUz1vCWUlDfx
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
PIomk2Q2S4P/H99wGem+nAEA

-->

</rfc>

