idnits 2.17.1 draft-ietf-suit-manifest-17.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 13 instances of too long lines in the document, the longest one being 3 characters in excess of 72. == There are 21 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (28 April 2022) is 728 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 8152 (Obsoleted by RFC 9052, RFC 9053) ** Downref: Normative reference to an Informational RFC: RFC 9019 ** Downref: Normative reference to an Informational RFC: RFC 9124 == Outdated reference: A later version (-19) exists of draft-ietf-suit-firmware-encryption-04 == Outdated reference: A later version (-08) exists of draft-ietf-suit-report-01 == Outdated reference: A later version (-06) exists of draft-ietf-suit-trust-domains-00 == Outdated reference: A later version (-06) exists of draft-ietf-suit-update-management-00 == Outdated reference: A later version (-19) exists of draft-ietf-teep-architecture-17 Summary: 4 errors (**), 0 flaws (~~), 7 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 SUIT B. Moran 3 Internet-Draft H. Tschofenig 4 Intended status: Standards Track Arm Limited 5 Expires: 30 October 2022 H. Birkholz 6 Fraunhofer SIT 7 K. Zandberg 8 Inria 9 28 April 2022 11 A Concise Binary Object Representation (CBOR)-based Serialization Format 12 for the Software Updates for Internet of Things (SUIT) Manifest 13 draft-ietf-suit-manifest-17 15 Abstract 17 This specification describes the format of a manifest. A manifest is 18 a bundle of metadata about code/data obtained by a recipient (chiefly 19 the firmware for an IoT device), where to find the that code/data, 20 the devices to which it applies, and cryptographic information 21 protecting the manifest. Software updates and Trusted Invocation 22 both tend to use sequences of common operations, so the manifest 23 encodes those sequences of operations, rather than declaring the 24 metadata. 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at https://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on 30 October 2022. 43 Copyright Notice 45 Copyright (c) 2022 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 50 license-info) in effect on the date of publication of this document. 51 Please review these documents carefully, as they describe your rights 52 and restrictions with respect to this document. Code Components 53 extracted from this document must include Revised BSD License text as 54 described in Section 4.e of the Trust Legal Provisions and are 55 provided without warranty as described in the Revised BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 60 2. Conventions and Terminology . . . . . . . . . . . . . . . . . 6 61 3. How to use this Document . . . . . . . . . . . . . . . . . . 8 62 4. Background . . . . . . . . . . . . . . . . . . . . . . . . . 9 63 4.1. IoT Firmware Update Constraints . . . . . . . . . . . . . 9 64 4.2. SUIT Workflow Model . . . . . . . . . . . . . . . . . . . 10 65 5. Metadata Structure Overview . . . . . . . . . . . . . . . . . 11 66 5.1. Envelope . . . . . . . . . . . . . . . . . . . . . . . . 12 67 5.2. Authentication Block . . . . . . . . . . . . . . . . . . 13 68 5.3. Manifest . . . . . . . . . . . . . . . . . . . . . . . . 13 69 5.3.1. Critical Metadata . . . . . . . . . . . . . . . . . . 13 70 5.3.2. Common . . . . . . . . . . . . . . . . . . . . . . . 13 71 5.3.3. Command Sequences . . . . . . . . . . . . . . . . . . 14 72 5.3.4. Integrity Check Values . . . . . . . . . . . . . . . 14 73 5.3.5. Human-Readable Text . . . . . . . . . . . . . . . . . 14 74 5.4. Severable Elements . . . . . . . . . . . . . . . . . . . 15 75 5.5. Integrated Payloads . . . . . . . . . . . . . . . . . . . 15 76 6. Manifest Processor Behavior . . . . . . . . . . . . . . . . . 15 77 6.1. Manifest Processor Setup . . . . . . . . . . . . . . . . 16 78 6.2. Required Checks . . . . . . . . . . . . . . . . . . . . 17 79 6.2.1. Minimizing Signature Verifications . . . . . . . . . 18 80 6.3. Interpreter Fundamental Properties . . . . . . . . . . . 18 81 6.4. Abstract Machine Description . . . . . . . . . . . . . . 19 82 6.5. Special Cases of Component Index . . . . . . . . . . . . 21 83 6.6. Serialized Processing Interpreter . . . . . . . . . . . . 22 84 6.7. Parallel Processing Interpreter . . . . . . . . . . . . . 22 85 7. Creating Manifests . . . . . . . . . . . . . . . . . . . . . 23 86 7.1. Compatibility Check Template . . . . . . . . . . . . . . 23 87 7.2. Trusted Invocation Template . . . . . . . . . . . . . . . 24 88 7.3. Component Download Template . . . . . . . . . . . . . . . 24 89 7.4. Install Template . . . . . . . . . . . . . . . . . . . . 25 90 7.5. Integrated Payload Template . . . . . . . . . . . . . . . 25 91 7.6. Load from Nonvolatile Storage Template . . . . . . . . . 26 92 7.7. A/B Image Template . . . . . . . . . . . . . . . . . . . 26 93 8. Metadata Structure . . . . . . . . . . . . . . . . . . . . . 28 94 8.1. Encoding Considerations . . . . . . . . . . . . . . . . . 28 95 8.2. Envelope . . . . . . . . . . . . . . . . . . . . . . . . 28 96 8.3. Authenticated Manifests . . . . . . . . . . . . . . . . . 29 97 8.4. Manifest . . . . . . . . . . . . . . . . . . . . . . . . 29 98 8.4.1. suit-manifest-version . . . . . . . . . . . . . . . . 30 99 8.4.2. suit-manifest-sequence-number . . . . . . . . . . . . 30 100 8.4.3. suit-reference-uri . . . . . . . . . . . . . . . . . 30 101 8.4.4. suit-text . . . . . . . . . . . . . . . . . . . . . . 31 102 8.4.5. suit-common . . . . . . . . . . . . . . . . . . . . . 32 103 8.4.6. SUIT_Command_Sequence . . . . . . . . . . . . . . . . 33 104 8.4.7. Reporting Policy . . . . . . . . . . . . . . . . . . 35 105 8.4.8. SUIT_Parameters . . . . . . . . . . . . . . . . . . . 36 106 8.4.9. SUIT_Condition . . . . . . . . . . . . . . . . . . . 42 107 8.4.10. SUIT_Directive . . . . . . . . . . . . . . . . . . . 45 108 8.4.11. Integrity Check Values . . . . . . . . . . . . . . . 50 109 8.5. Severable Elements . . . . . . . . . . . . . . . . . . . 50 110 9. Access Control Lists . . . . . . . . . . . . . . . . . . . . 50 111 10. SUIT Digest Container . . . . . . . . . . . . . . . . . . . . 51 112 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 51 113 11.1. SUIT Commands . . . . . . . . . . . . . . . . . . . . . 52 114 11.2. SUIT Parameters . . . . . . . . . . . . . . . . . . . . 53 115 11.3. SUIT Text Values . . . . . . . . . . . . . . . . . . . . 54 116 11.4. SUIT Component Text Values . . . . . . . . . . . . . . 55 117 12. Security Considerations . . . . . . . . . . . . . . . . . . . 55 118 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 55 119 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 56 120 14.1. Normative References . . . . . . . . . . . . . . . . . . 56 121 14.2. Informative References . . . . . . . . . . . . . . . . . 57 122 Appendix A. A. Full CDDL . . . . . . . . . . . . . . . . . . . 58 123 Appendix B. B. Examples . . . . . . . . . . . . . . . . . . . . 64 124 B.1. Example 0: Secure Boot . . . . . . . . . . . . . . . . . 65 125 B.2. Example 1: Simultaneous Download and Installation of 126 Payload . . . . . . . . . . . . . . . . . . . . . . . . . 67 127 B.3. Example 2: Simultaneous Download, Installation, Secure 128 Boot, Severed Fields . . . . . . . . . . . . . . . . . . 69 129 B.4. Example 3: A/B images . . . . . . . . . . . . . . . . . . 73 130 B.5. Example 4: Load from External Storage . . . . . . . . . . 76 131 B.6. Example 5: Two Images . . . . . . . . . . . . . . . . . . 79 132 Appendix C. C. Design Rational . . . . . . . . . . . . . . . . 82 133 C.1. C.1 Design Rationale: Envelope . . . . . . . . . . . . . 83 134 C.2. C.2 Byte String Wrappers . . . . . . . . . . . . . . . . 84 135 Appendix D. D. Implementation Conformance Matrix . . . . . . . 85 136 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 87 138 1. Introduction 140 A firmware update mechanism is an essential security feature for IoT 141 devices to deal with vulnerabilities. While the transport of 142 firmware images to the devices themselves is important there are 143 already various techniques available. Equally important is the 144 inclusion of metadata about the conveyed firmware image (in the form 145 of a manifest) and the use of a security wrapper to provide end-to- 146 end security protection to detect modifications and (optionally) to 147 make reverse engineering more difficult. End-to-end security allows 148 the author, who builds the firmware image, to be sure that no other 149 party (including potential adversaries) can install firmware updates 150 on IoT devices without adequate privileges. For confidentiality 151 protected firmware images it is additionally required to encrypt the 152 firmware image. Starting security protection at the author is a risk 153 mitigation technique so firmware images and manifests can be stored 154 on untrusted repositories; it also reduces the scope of a compromise 155 of any repository or intermediate system to be no worse than a denial 156 of service. 158 A manifest is a bundle of metadata describing one or more code or 159 data payloads and how to: 161 * Obtain any dependencies 163 * Obtain the payload(s) 165 * Install them 167 * Verify them 169 * Load them into memory 171 * Invoke them 173 This specification defines the SUIT manifest format and it is 174 intended to meet several goals: 176 * Meet the requirements defined in [RFC9124]. 178 * Simple to parse on a constrained node 180 * Simple to process on a constrained node 182 * Compact encoding 184 * Comprehensible by an intermediate system 185 * Expressive enough to enable advanced use cases on advanced nodes 187 * Extensible 189 The SUIT manifest can be used for a variety of purposes throughout 190 its lifecycle, such as: 192 * a Firmware Author to reason about releasing a firmware. 194 * a Network Operator to reason about compatibility of a firmware. 196 * a Device Operator to reason about the impact of a firmware. 198 * the Device Operator to manage distribution of firmware to devices. 200 * a Plant Manager to reason about timing and acceptance of firmware 201 updates. 203 * a device to reason about the authority & authenticity of a 204 firmware prior to installation. 206 * a device to reason about the applicability of a firmware. 208 * a device to reason about the installation of a firmware. 210 * a device to reason about the authenticity & encoding of a firmware 211 at boot. 213 Each of these uses happens at a different stage of the manifest 214 lifecycle, so each has different requirements. 216 It is assumed that the reader is familiar with the high-level 217 firmware update architecture [RFC9019] and the threats, requirements, 218 and user stories in [RFC9124]. 220 The design of this specification is based on an observation that the 221 vast majority of operations that a device can perform during an 222 update or Trusted Invocation are composed of a small group of 223 operations: 225 * Copy some data from one place to another 227 * Transform some data 229 * Digest some data and compare to an expected value 231 * Compare some system parameters to an expected value 232 * Run some code 234 In this document, these operations are called commands. Commands are 235 classed as either conditions or directives. Conditions have no side- 236 effects, while directives do have side-effects. Conceptually, a 237 sequence of commands is like a script but the language is tailored to 238 software updates and Trusted Invocation. 240 The available commands support simple steps, such as copying a 241 firmware image from one place to another, checking that a firmware 242 image is correct, verifying that the specified firmware is the 243 correct firmware for the device, or unpacking a firmware. By using 244 these steps in different orders and changing the parameters they use, 245 a broad range of use cases can be supported. The SUIT manifest uses 246 this observation to optimize metadata for consumption by constrained 247 devices. 249 While the SUIT manifest is informed by and optimized for firmware 250 update and Trusted Invocation use cases, there is nothing in the SUIT 251 Information Model ([RFC9124]) that restricts its use to only those 252 use cases. Other use cases include the management of trusted 253 applications (TAs) in a Trusted Execution Environment (TEE), as 254 discussed in [I-D.ietf-teep-architecture]. 256 2. Conventions and Terminology 258 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 259 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 260 "OPTIONAL" in this document are to be interpreted as described in 261 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 262 capitals, as shown here. 264 Additionally, the following terminology is used throughout this 265 document: 267 * SUIT: Software Update for the Internet of Things, also the IETF 268 working group for this standard. 270 * Payload: A piece of information to be delivered. Typically 271 Firmware for the purposes of SUIT. 273 * Resource: A piece of information that is used to construct a 274 payload. 276 * Manifest: A manifest is a bundle of metadata about the firmware 277 for an IoT device, where to find the firmware, and the devices to 278 which it applies. 280 * Envelope: A container with the manifest, an authentication wrapper 281 with cryptographic information protecting the manifest, 282 authorization information, and severable elements. 284 * Update: One or more manifests that describe one or more payloads. 286 * Update Authority: The owner of a cryptographic key used to sign 287 updates, trusted by Recipients. 289 * Recipient: The system, typically an IoT device, that receives and 290 processes a manifest. 292 * Manifest Processor: A component of the Recipient that consumes 293 Manifests and executes the commands in the Manifest. 295 * Component: An updatable logical block of the Firmware, Software, 296 configuration, or data of the Recipient. 298 * Component Set: A group of interdependent Components that must be 299 updated simultaneously. 301 * Command: A Condition or a Directive. 303 * Condition: A test for a property of the Recipient or its 304 Components. 306 * Directive: An action for the Recipient to perform. 308 * Trusted Invocation: A process by which a system ensures that only 309 trusted code is executed, for example secure boot or launching a 310 Trusted Application. 312 * A/B images: Dividing a Recipient's storage into two or more 313 bootable images, at different offsets, such that the active image 314 can write to the inactive image(s). 316 * Record: The result of a Command and any metadata about it. 318 * Report: A list of Records. 320 * Procedure: The process of invoking one or more sequences of 321 commands. 323 * Update Procedure: A procedure that updates a Recipient by fetching 324 dependencies and images, and installing them. 326 * Invocation Procedure: A procedure in which a Recipient verifies 327 dependencies and images, loading images, and invokes one or more 328 image. 330 * Software: Instructions and data that allow a Recipient to perform 331 a useful function. 333 * Firmware: Software that is typically changed infrequently, stored 334 in nonvolatile memory, and small enough to apply to [RFC7228] 335 Class 0-2 devices. 337 * Image: Information that a Recipient uses to perform its function, 338 typically firmware/software, configuration, or resource data such 339 as text or images. Also, a Payload, once installed is an Image. 341 * Slot: One of several possible storage locations for a given 342 Component, typically used in A/B image systems 344 * Abort: An event in which the Manifest Processor immediately halts 345 execution of the current Procedure. It creates a Record of an 346 error condition. 348 3. How to use this Document 350 This specification covers five aspects of firmware update: 352 * Section 4 describes the device constraints, use cases, and design 353 principles that informed the structure of the manifest. 355 * Section 5 gives a general overview of the metadata structure to 356 inform the following sections 358 * Section 6 describes what actions a Manifest processor should take. 360 * Section 7 describes the process of creating a Manifest. 362 * Section 8 specifies the content of the Envelope and the Manifest. 364 To implement an updatable device, see Section 6 and Section 8. To 365 implement a tool that generates updates, see Section 7 and Section 8. 367 The IANA consideration section, see Section 11, provides instructions 368 to IANA to create several registries. This section also provides the 369 CBOR labels for the structures defined in this document. 371 The complete CDDL description is provided in Appendix A, examples are 372 given in Appendix B and a design rational is offered in Appendix C. 373 Finally, Appendix D gives a summarize of the mandatory-to-implement 374 features of this specification. 376 This specification covers the core features of SUIT. Additional 377 specifications describe functionality of advanced use cases, such as: 379 * Firmware Encryption is covered in 380 [I-D.ietf-suit-firmware-encryption] 382 * Update Management is covered in [I-D.ietf-suit-update-management] 384 * Features, such as dependencies, key delegation, multiple 385 processors, required by the use of multiple trust domains are 386 covered in [I-D.ietf-suit-trust-domains] 388 * Secure reporting of the update status is covered in 389 [I-D.ietf-suit-report] 391 * Compression of firmware images 393 4. Background 395 Distributing software updates to diverse devices with diverse trust 396 anchors in a coordinated system presents unique challenges. Devices 397 have a broad set of constraints, requiring different metadata to make 398 appropriate decisions. There may be many actors in production IoT 399 systems, each of whom has some authority. Distributing firmware in 400 such a multi-party environment presents additional challenges. Each 401 party requires a different subset of data. Some data may not be 402 accessible to all parties. Multiple signatures may be required from 403 parties with different authorities. This topic is covered in more 404 depth in [RFC9019]. The security aspects are described in [RFC9124]. 406 4.1. IoT Firmware Update Constraints 408 The various constraints of IoT devices and the range of use cases 409 that need to be supported create a broad set of requirements. For 410 example, devices with: 412 * limited processing power and storage may require a simple 413 representation of metadata. 415 * bandwidth constraints may require firmware compression or partial 416 update support. 418 * bootloader complexity constraints may require simple selection 419 between two bootable images. 421 * small internal storage may require external storage support. 423 * multiple microcontrollers may require coordinated update of all 424 applications. 426 * large storage and complex functionality may require parallel 427 update of many software components. 429 * extra information may need to be conveyed in the manifest in the 430 earlier stages of the device lifecycle before those data items are 431 stripped when the manifest is delivered to a constrained device. 433 Supporting the requirements introduced by the constraints on IoT 434 devices requires the flexibility to represent a diverse set of 435 possible metadata, but also requires that the encoding is kept 436 simple. 438 4.2. SUIT Workflow Model 440 There are several fundamental assumptions that inform the model of 441 Update Procedure workflow: 443 * Compatibility must be checked before any other operation is 444 performed. 446 * In some applications, payloads must be fetched and validated prior 447 to installation. 449 There are several fundamental assumptions that inform the model of 450 the Invocation Procedure workflow: 452 * Compatibility must be checked before any other operation is 453 performed. 455 * All payloads must be validated prior to loading. 457 * All loaded images must be validated prior to execution. 459 Based on these assumptions, the manifest is structured to work with a 460 pull parser, where each section of the manifest is used in sequence. 461 The expected workflow for a Recipient installing an update can be 462 broken down into five steps: 464 1. Verify the signature of the manifest. 466 2. Verify the applicability of the manifest. 468 3. Fetch payload(s). 470 4. Install payload(s). 472 When installation is complete, similar information can be used for 473 validating and running images in a further three steps: 475 1. Verify image(s). 477 2. Load image(s). 479 3. Run image(s). 481 If verification and running is implemented in a bootloader, then the 482 bootloader MUST also verify the signature of the manifest and the 483 applicability of the manifest in order to implement secure boot 484 workflows. The bootloader may add its own authentication, e.g. a 485 Message Authentication Code (MAC), to the manifest in order to 486 prevent further verifications. 488 5. Metadata Structure Overview 490 This section provides a high level overview of the manifest 491 structure. The full description of the manifest structure is in 492 Section 8.4 494 The manifest is structured from several key components: 496 1. The Envelope (see Section 5.1) contains the Authentication Block, 497 the Manifest, any Severable Elements, and any Integrated 498 Payloads. 500 2. The Authentication Block (see Section 5.2) contains a list of 501 signatures or MACs of the manifest.. 503 3. The Manifest (see Section 5.3) contains all critical, non- 504 severable metadata that the Recipient requires. It is further 505 broken down into: 507 1. Critical metadata, such as sequence number. 509 2. Common metadata, such as affected components. 511 3. Command sequences, directing the Recipient how to install and 512 use the payload(s). 514 4. Integrity check values for severable elements. 516 4. Severable elements (see Section 5.4). 518 5. Integrated payloads (see Section 5.5). 520 The diagram below illustrates the hierarchy of the Envelope. 522 +-------------------------+ 523 | Envelope | 524 +-------------------------+ 525 | Authentication Block | 526 | Manifest --------------> +------------------------------+ 527 | Severable Elements | | Manifest | 528 | Human-Readable Text | +------------------------------+ 529 | Integrated Payloads | | Structure Version | 530 +-------------------------+ | Sequence Number | 531 | Reference to Full Manifest | 532 +------ Common Structure | 533 | +---- Command Sequences | 534 +-------------------------+ | | | Digests of Envelope Elements | 535 | Common Structure | <--+ | +------------------------------+ 536 +-------------------------+ | 537 | Components IDs | +-> +-----------------------+ 538 | Common Command Sequence ---------> | Command Sequence | 539 +-------------------------+ +-----------------------+ 540 | List of ( pairs of ( | 541 | * command code | 542 | * argument / | 543 | reporting policy | 544 | )) | 545 +-----------------------+ 547 5.1. Envelope 549 The SUIT Envelope is a container that encloses the Authentication 550 Block, the Manifest, any Severable Elements, and any integrated 551 payloads. The Envelope is used instead of conventional cryptographic 552 envelopes, such as COSE_Envelope because it allows modular 553 processing, severing of elements, and integrated payloads in a way 554 that would add substantial complexity with existing solutions. See 555 Appendix C.1 for a description of the reasoning for this. 557 See Section 8.2 for more detail. 559 5.2. Authentication Block 561 The Authentication Block contains a bstr-wrapped SUIT Digest 562 Container, see Section 10, and one or more [RFC8152] CBOR Object 563 Signing and Encryption (COSE) authentication blocks. These blocks 564 are one of: 566 * COSE_Sign_Tagged 568 * COSE_Sign1_Tagged 570 * COSE_Mac_Tagged 572 * COSE_Mac0_Tagged 574 Each of these objects is used in detached payload mode. The payload 575 is the bstr-wrapped SUIT_Digest. 577 See Section 8.3 for more detail. 579 5.3. Manifest 581 The Manifest contains most metadata about one or more images. The 582 Manifest is divided into Critical Metadata, Common Metadata, Command 583 Sequences, and Integrity Check Values. 585 See Section 8.4 for more detail. 587 5.3.1. Critical Metadata 589 Some metadata needs to be accessed before the manifest is processed. 590 This metadata can be used to determine which manifest is newest and 591 whether the structure version is supported. It also MAY provide a 592 URI for obtaining a canonical copy of the manifest and Envelope. 594 See Section 8.4.1, Section 8.4.2, and Section 8.4.3 for more detail. 596 5.3.2. Common 598 Some metadata is used repeatedly and in more than one command 599 sequence. In order to reduce the size of the manifest, this metadata 600 is collected into the Common section. Common is composed of two 601 parts: a list of components referenced by the manifest, and a command 602 sequence to execute prior to each other command sequence. The common 603 command sequence is typically used to set commonly used values and 604 perform compatibility checks. The common command sequence MUST NOT 605 have any side-effects outside of setting parameter values. 607 See Section 8.4.5 for more detail. 609 5.3.3. Command Sequences 611 Command sequences provide the instructions that a Recipient requires 612 in order to install or use an image. These sequences tell a device 613 to set parameter values, test system parameters, copy data from one 614 place to another, transform data, digest data, and run code. 616 Command sequences are broken up into three groups: Common Command 617 Sequence (see Section 5.3.2), update commands, and secure boot 618 commands. 620 Update Command Sequences are: Payload Fetch, and Payload 621 Installation. An Update Procedure is the complete set of each Update 622 Command Sequence, each preceded by the Common Command Sequence. 624 Invocation Command Sequences are: System Validation, Image Loading, 625 and Image Invocation. An Invocation Procedure is the complete set of 626 each Invocation Command Sequence, each preceded by the Common Command 627 Sequence. 629 Command Sequences are grouped into these sets to ensure that there is 630 common coordination between dependencies and dependents on when to 631 execute each command (dependencies are not defined in this 632 specification). 634 See Section 8.4.6 for more detail. 636 5.3.4. Integrity Check Values 638 To enable Section 5.4, there needs to be a mechanism to verify 639 integrity of any metadata outside the manifest. Integrity Check 640 Values are used to verify the integrity of metadata that is not 641 contained in the manifest. This MAY include Severable Command 642 Sequences, or Text data. Integrated Payloads are integrity-checked 643 using Command Sequences, so they do not have Integrity Check Values 644 present in the Manifest. 646 See Section 8.4.11 for more detail. 648 5.3.5. Human-Readable Text 650 Text is typically a Severable Element (Section 5.4). It contains all 651 the text that describes the update. Because text is explicitly for 652 human consumption, it is all grouped together so that it can be 653 Severed easily. The text section has space both for describing the 654 manifest as a whole and for describing each individual component. 656 See Section 8.4.4 for more detail. 658 5.4. Severable Elements 660 Severable Elements are elements of the Envelope (Section 5.1) that 661 have Integrity Check Values (Section 5.3.4) in the Manifest 662 (Section 5.3). 664 Because of this organisation, these elements can be discarded or 665 "Severed" from the Envelope without changing the signature of the 666 Manifest. This allows savings based on the size of the Envelope in 667 several scenarios, for example: 669 * A management system severs the Text sections before sending an 670 Envelope to a constrained Recipient, which saves Recipient 671 bandwidth. 673 * A Recipient severs the Installation section after installing the 674 Update, which saves storage space. 676 See Section 8.5 for more detail. 678 5.5. Integrated Payloads 680 In some cases, it is beneficial to include a payload in the Envelope 681 of a manifest. For example: 683 * When an update is delivered via a comparatively unconstrained 684 medium, such as a removable mass storage device, it may be 685 beneficial to bundle updates into single files. 687 * When a manifest transports a small payload, such as an encrypted 688 key, that payload may be placed in the manifest's envelope. 690 See Section 7.5 for more detail. 692 6. Manifest Processor Behavior 694 This section describes the behavior of the manifest processor and 695 focuses primarily on interpreting commands in the manifest. However, 696 there are several other important behaviors of the manifest 697 processor: encoding version detection, rollback protection, and 698 authenticity verification are chief among these. 700 6.1. Manifest Processor Setup 702 Prior to executing any command sequence, the manifest processor or 703 its host application MUST inspect the manifest version field and fail 704 when it encounters an unsupported encoding version. Next, the 705 manifest processor or its host application MUST extract the manifest 706 sequence number and perform a rollback check using this sequence 707 number. The exact logic of rollback protection may vary by 708 application, but it has the following properties: 710 * Whenever the manifest processor can choose between several 711 manifests, it MUST select the latest valid, authentic manifest. 713 * If the latest valid, authentic manifest fails, it MAY select the 714 next latest valid, authentic manifest, according to application- 715 specific policy. 717 Here, valid means that a manifest has a supported encoding version 718 and it has not been excluded for other reasons. Reasons for 719 excluding typically involve first executing the manifest and may 720 include: 722 * Test failed (e.g. Vendor ID/Class ID). 724 * Unsupported command encountered. 726 * Unsupported parameter encountered. 728 * Unsupported Component Identifier encountered. 730 * Payload not available. 732 * Application crashed when executed. 734 * Watchdog timeout occurred. 736 * Payload verification failed. 738 * Missing required component from a Component Set. 740 * Required parameter not supplied. 742 These failure reasons MAY be combined with retry mechanisms prior to 743 marking a manifest as invalid. 745 Selecting an older manifest in the event of failure of the latest 746 valid manifest is a robustness mechanism that is necessary for 747 supporting the requirements in [RFC9019], section 3.5. It may not be 748 appropriate for all applications. In particular Trusted Execution 749 Environments MAY require a failure to invoke a new installation, 750 rather than a rollback approach. See [RFC9124], Section 4.2.1 for 751 more discussion on the security considerations that apply to 752 rollback. 754 Following these initial tests, the manifest processor clears all 755 parameter storage. This ensures that the manifest processor begins 756 without any leaked data. 758 6.2. Required Checks 760 The RECOMMENDED process is to verify the signature of the manifest 761 prior to parsing/executing any section of the manifest. This guards 762 the parser against arbitrary input by unauthenticated third parties, 763 but it costs extra energy when a Recipient receives an incompatible 764 manifest. 766 When validating authenticity of manifests, the manifest processor MAY 767 use an ACL (see Section 9) to determine the extent of the rights 768 conferred by that authenticity. 770 Once a valid, authentic manifest has been selected, the manifest 771 processor MUST examine the component list and verify that its maximum 772 number of components is not exceeded and that each listed component 773 is supported. 775 For each listed component, the manifest processor MUST provide 776 storage for the supported parameters. If the manifest processor does 777 not have sufficient temporary storage to process the parameters for 778 all components, it MAY process components serially for each command 779 sequence. See Section 6.6 for more details. 781 The manifest processor SHOULD check that the common sequence contains 782 at least Check Vendor Identifier command and at least one Check Class 783 Identifier command. 785 Because the common sequence contains Check Vendor Identifier and 786 Check Class Identifier command(s), no custom commands are permitted 787 in the common sequence. This ensures that any custom commands are 788 only executed by devices that understand them. 790 If the manifest contains more than one component, each command 791 sequence MUST begin with a Set Component Index. 793 If a Recipient supports groups of interdependent components (a 794 Component Set), then it SHOULD verify that all Components in the 795 Component Set are specified by one update, that is the manifest: 797 1. has sufficient permissions imparted by its signatures 799 2. specifies a digest and a payload for every Component in the 800 Component Set. 802 6.2.1. Minimizing Signature Verifications 804 Signature verification can be energy and time expensive on a 805 constrained device. MAC verification is typically unaffected by 806 these concerns. A Recipient MAY choose to parse and execute only the 807 SUIT_Common section of the manifest prior to signature verification, 808 if all of the below apply: 810 * The Authentication Block contains a COSE_Sign_Tagged or 811 COSE_Sign1_Tagged 813 * The Recipient receives manifests over an unauthenticated channel, 814 exposing it to more inauthentic or incompatible manifests, and 816 * The Recipient has a power budget that makes signature verification 817 undesirable 819 When executing Common prior to authenticity validation, the Manifest 820 Processor MUST first evaluate the integrity of the manifest using the 821 SUIT_Digest present in the authentication block. 823 The guidelines in Creating Manifests (Section 7) require that the 824 common section contains the applicability checks, so this section is 825 sufficient for applicability verification. The parser MUST restrict 826 acceptable commands to conditions and the following directives: 827 Override Parameters, Set Parameters, Try Each, and Run Sequence ONLY. 828 The manifest parser MUST NOT execute any command with side-effects 829 outside the parser (for example, Run, Copy, Swap, or Fetch commands) 830 prior to authentication and any such command MUST Abort. The Common 831 Sequence MUST be executed again, in its entirety, after authenticity 832 validation. 834 A Recipient MAY rely on network infrastructure to filter inapplicable 835 manifests. 837 6.3. Interpreter Fundamental Properties 839 The interpreter has a small set of design goals: 841 1. Executing an update MUST either result in an error, or a 842 verifiably correct system state. 844 2. Executing a Trusted Invocation MUST either result in an error, or 845 an invoked image. 847 3. Executing the same manifest on multiple Recipients MUST result in 848 the same system state. 850 NOTE: when using A/B images, the manifest functions as two (or more) 851 logical manifests, each of which applies to a system in a particular 852 starting state. With that provision, design goal 3 holds. 854 6.4. Abstract Machine Description 856 The heart of the manifest is the list of commands, which are 857 processed by a Manifest Processor--a form of interpreter. This 858 Manifest Processor can be modeled as a simple abstract machine. This 859 machine consists of several data storage locations that are modified 860 by commands. 862 There are two types of commands, namely those that modify state 863 (directives) and those that perform tests (conditions). Parameters 864 are used as the inputs to commands. Some directives offer control 865 flow operations. Directives target a specific component. A 866 component is a unit of code or data that can be targeted by an 867 update. Components are identified by Component Identifiers, but 868 referenced in commands by Component Index; Component Identifiers are 869 arrays of binary strings and a Component Index is an index into the 870 array of Component Identifiers. 872 Conditions MUST NOT have any side-effects other than informing the 873 interpreter of success or failure. The Interpreter does not Abort if 874 the Soft Failure flag (Section 8.4.8.14) is set when a Condition 875 reports failure. 877 Directives MAY have side-effects in the parameter table, the 878 interpreter state, or the current component. The Interpreter MUST 879 Abort if a Directive reports failure regardless of the Soft Failure 880 flag. 882 To simplify the logic describing the command semantics, the object 883 "current" is used. It represents the component identified by the 884 Component Index: 886 current := components\[component-index\] 888 As a result, Set Component Index is described as current := 889 components[arg]. 891 The following table describes the behavior of each command. "params" 892 represents the parameters for the current component. Most commands 893 operate on a component. 895 +=========================+======================================+ 896 | Command Name | Semantic of the Operation | 897 +=========================+======================================+ 898 | Check Vendor Identifier | assert(binary-match(current, | 899 | | current.params[vendor-id])) | 900 +-------------------------+--------------------------------------+ 901 | Check Class Identifier | assert(binary-match(current, | 902 | | current.params[class-id])) | 903 +-------------------------+--------------------------------------+ 904 | Verify Image | assert(binary-match(digest(current), | 905 | | current.params[digest])) | 906 +-------------------------+--------------------------------------+ 907 | Set Component Index | current := components[arg] | 908 +-------------------------+--------------------------------------+ 909 | Override Parameters | current.params[k] := v for-each k,v | 910 | | in arg | 911 +-------------------------+--------------------------------------+ 912 | Set Parameters | current.params[k] := v if not k in | 913 | | params for-each k,v in arg | 914 +-------------------------+--------------------------------------+ 915 | Run | run(current) | 916 +-------------------------+--------------------------------------+ 917 | Fetch | store(current, | 918 | | fetch(current.params[uri])) | 919 +-------------------------+--------------------------------------+ 920 | Use Before | assert(now() < arg) | 921 +-------------------------+--------------------------------------+ 922 | Check Component Slot | assert(current.slot-index == arg) | 923 +-------------------------+--------------------------------------+ 924 | Check Device Identifier | assert(binary-match(current, | 925 | | current.params[device-id])) | 926 +-------------------------+--------------------------------------+ 927 | Abort | assert(0) | 928 +-------------------------+--------------------------------------+ 929 | Try Each | try-each-done if exec(seq) is not | 930 | | error for-each seq in arg | 931 +-------------------------+--------------------------------------+ 932 | Copy | store(current, current.params[src- | 933 | | component]) | 934 +-------------------------+--------------------------------------+ 935 | Swap | swap(current, current.params[src- | 936 | | component]) | 937 +-------------------------+--------------------------------------+ 938 | Run Sequence | exec(arg) | 939 +-------------------------+--------------------------------------+ 940 | Run with Arguments | run(current, arg) | 941 +-------------------------+--------------------------------------+ 943 Table 1 945 6.5. Special Cases of Component Index 947 Component Index can take on one of three types: 949 1. Integer 951 2. Array of integers 953 3. True 955 Integers MUST always be supported by Set Component Index. Arrays of 956 integers MUST be supported by Set Component Index if the Recipient 957 supports 3 or more components. True MUST be supported by Set 958 Component Index if the Recipient supports 2 or more components. Each 959 of these operates on the list of components declared in the manifest. 961 Integer indices are the default case as described in the previous 962 section. An array of integers represents a list of the components 963 (Set Component Index) to which each subsequent command applies. The 964 value True replaces the list of component indices with the full list 965 of components, as defined in the manifest. 967 When a command is executed, it either 1. operates on the component 968 identified by the component index if that index is an integer, or 2. 969 it operates on each component identified by an array of indicies, or 970 3. it operates on every component if the index is the boolean True. 971 This is described by the following pseudocode: 973 if component-index is true: 974 current-list = components 975 else if component-index is array: 976 current-list = [ components[idx] for idx in component-index ] 977 else: 978 current-list = [ components[component-index] ] 979 for current in current-list: 980 cmd(current) 982 Try Each and Run Sequence are affected in the same way as other 983 commands: they are invoked once for each possible Component. This 984 means that the sequences that are arguments to Try Each and Run 985 Sequence are NOT invoked with Component Index = True, nor are they 986 invoked with array indices. They are only invoked with integer 987 indices. The interpreter loops over the whole sequence, setting the 988 Component Index to each index in turn. 990 6.6. Serialized Processing Interpreter 992 In highly constrained devices, where storage for parameters is 993 limited, the manifest processor MAY handle one component at a time, 994 traversing the manifest tree once for each listed component. In this 995 mode, the interpreter ignores any commands executed while the 996 component index is not the current component. This reduces the 997 overall volatile storage required to process the update so that the 998 only limit on number of components is the size of the manifest. 999 However, this approach requires additional processing power. 1001 In order to operate in this mode, the manifest processor loops on 1002 each section for every supported component, simply ignoring commands 1003 when the current component is not selected. 1005 When a serialized Manifest Processor encounters a component index of 1006 True, it does not ignore any commands. It applies them to the 1007 current component on each iteration. 1009 6.7. Parallel Processing Interpreter 1011 Advanced Recipients MAY make use of the Strict Order parameter and 1012 enable parallel processing of some Command Sequences, or it may 1013 reorder some Command Sequences. To perform parallel processing, once 1014 the Strict Order parameter is set to False, the Recipient may issue 1015 each or every command concurrently until the Strict Order parameter 1016 is returned to True or the Command Sequence ends. Then, it waits for 1017 all issued commands to complete before continuing processing of 1018 commands. To perform out-of-order processing, a similar approach is 1019 used, except the Recipient consumes all commands after the Strict 1020 Order parameter is set to False, then it sorts these commands into 1021 its preferred order, invokes them all, then continues processing. 1023 When the manifest processor encounters any of these scenarios the 1024 parallel processing MUST halt until all issued commands have 1025 completed: 1027 * Set Parameters. 1029 * Override Parameters. 1031 * Set Strict Order = True. 1033 * Set Component Index. 1035 To perform more useful parallel operations, a manifest author may 1036 collect sequences of commands in a Run Sequence command. Then, each 1037 of these sequences MAY be run in parallel. Each sequence defaults to 1038 Strict Order = True. To isolate each sequence from each other 1039 sequence, each sequence MUST begin with a Set Component Index 1040 directive with the following exception: when the index is either True 1041 or an array of indices, the Set Component Index is implied. Any 1042 further Set Component Index directives MUST cause an Abort. This 1043 allows the interpreter that issues Run Sequence commands to check 1044 that the first element is correct, then issue the sequence to a 1045 parallel execution context to handle the remainder of the sequence. 1047 7. Creating Manifests 1049 Manifests are created using tools for constructing COSE structures, 1050 calculating cryptographic values and compiling desired system state 1051 into a sequence of operations required to achieve that state. The 1052 process of constructing COSE structures and the calculation of 1053 cryptographic values is covered in [RFC8152]. 1055 Compiling desired system state into a sequence of operations can be 1056 accomplished in many ways. Several templates are provided below to 1057 cover common use-cases. These templates can be combined to produce 1058 more complex behavior. 1060 The author MUST ensure that all parameters consumed by a command are 1061 set prior to invoking that command. Where Component Index = True, 1062 this means that the parameters consumed by each command MUST have 1063 been set for each Component. 1065 This section details a set of templates for creating manifests. 1066 These templates explain which parameters, commands, and orders of 1067 commands are necessary to achieve a stated goal. 1069 NOTE: On systems that support only a single component, Set Component 1070 Index has no effect and can be omitted. 1072 NOTE: *A digest MUST always be set using Override Parameters.* 1074 7.1. Compatibility Check Template 1076 The goal of the compatibility check template ensure that Recipients 1077 only install compatible images. 1079 In this template all information is contained in the common sequence 1080 and the following sequence of commands is used: 1082 * Set Component Index directive (see Section 8.4.10.1) 1084 * Override Parameters directive (see Section 8.4.10.3) for Vendor ID 1085 and Class ID (see Section 8.4.8) 1087 * Check Vendor Identifier condition (see Section 8.4.8.2) 1089 * Check Class Identifier condition (see Section 8.4.8.2) 1091 7.2. Trusted Invocation Template 1093 The goal of the Trusted Invocation template is to ensure that only 1094 authorized code is invoked; such as in Secure Boot or when a Trusted 1095 Application is loaded into a TEE. 1097 The following commands are placed into the common sequence: 1099 * Set Component Index directive (see Section 8.4.10.1) 1101 * Override Parameters directive (see Section 8.4.10.3) for Image 1102 Digest and Image Size (see Section 8.4.8) 1104 The system validation sequence contains the following commands: 1106 * Set Component Index directive (see Section 8.4.10.1) 1108 * Check Image Match condition (see Section 8.4.9.2) 1110 Then, the run sequence contains the following commands: 1112 * Set Component Index directive (see Section 8.4.10.1) 1114 * Run directive (see Section 8.4.10.7) 1116 7.3. Component Download Template 1118 The goal of the Component Download template is to acquire and store 1119 an image. 1121 The following commands are placed into the common sequence: 1123 * Set Component Index directive (see Section 8.4.10.1) 1125 * Override Parameters directive (see Section 8.4.10.3) for Image 1126 Digest and Image Size (see Section 8.4.8) 1128 Then, the install sequence contains the following commands: 1130 * Set Component Index directive (see Section 8.4.10.1) 1132 * Override Parameters directive (see Section 8.4.10.3) for URI (see 1133 Section 8.4.8.9) 1135 * Fetch directive (see Section 8.4.10.4) 1137 * Check Image Match condition (see Section 8.4.9.2) 1139 The Fetch directive needs the URI parameter to be set to determine 1140 where the image is retrieved from. Additionally, the destination of 1141 where the component shall be stored has to be configured. The URI is 1142 configured via the Set Parameters directive while the destination is 1143 configured via the Set Component Index directive. 1145 7.4. Install Template 1147 The goal of the Install template is to use an image already stored in 1148 an identified component to copy into a second component. 1150 This template is typically used with the Component Download template, 1151 however a modification to that template is required: the Component 1152 Download operations are moved from the Payload Install sequence to 1153 the Payload Fetch sequence. 1155 Then, the install sequence contains the following commands: 1157 * Set Component Index directive (see Section 8.4.10.1) 1159 * Override Parameters directive (see Section 8.4.10.3) for Source 1160 Component (see Section 8.4.8.10) 1162 * Copy directive (see Section 8.4.10.5) 1164 * Check Image Match condition (see Section 8.4.9.2) 1166 7.5. Integrated Payload Template 1168 The goal of the Integrated Payload template is to install a payload 1169 that is included in the manifest envelope. It is identical to the 1170 Component Download template (Section 7.3). 1172 An implementer MAY choose to place a payload in the envelope of a 1173 manifest. The payload envelope key MUST be a string. The payload 1174 MUST be serialized in a bstr element. 1176 The URI for a payload enclosed in this way MAY be expressed as a 1177 fragment-only reference, as defined in [RFC3986], Section 4.4. 1179 A distributor MAY choose to pre-fetch a payload and add it to the 1180 manifest envelope, using the URI as the key. 1182 7.6. Load from Nonvolatile Storage Template 1184 The goal of the Load from Nonvolatile Storage template is to load an 1185 image from a non-volatile component into a volatile component, for 1186 example loading a firmware image from external Flash into RAM. 1188 The following commands are placed into the load sequence: 1190 * Set Component Index directive (see Section 8.4.10.1) 1192 * Override Parameters directive (see Section 8.4.10.3) for Source 1193 Component (see Section 8.4.8) 1195 * Copy directive (see Section 8.4.10.5) 1197 As outlined in Section 6.4, the Copy directive needs a source and a 1198 destination to be configured. The source is configured via Component 1199 Index (with the Set Parameters directive) and the destination is 1200 configured via the Set Component Index directive. 1202 7.7. A/B Image Template 1204 The goal of the A/B Image Template is to acquire, validate, and 1205 invoke one of two images, based on a test. 1207 The following commands are placed in the common block: 1209 * Set Component Index directive (see Section 8.4.10.1) 1211 * Try Each 1213 - First Sequence: 1215 o Override Parameters directive (see Section 8.4.10.3, 1216 Section 8.4.8) for Slot A 1218 o Check Slot Condition (see Section 8.4.9.3) 1220 o Override Parameters directive (see Section 8.4.10.3) for 1221 Image Digest A and Image Size A (see Section 8.4.8) 1223 - Second Sequence: 1225 o Override Parameters directive (see Section 8.4.10.3, 1226 Section 8.4.8) for Slot B 1228 o Check Slot Condition (see Section 8.4.9.3) 1230 o Override Parameters directive (see Section 8.4.10.3) for 1231 Image Digest B and Image Size B (see Section 8.4.8) 1233 The following commands are placed in the fetch block or install block 1235 * Set Component Index directive (see Section 8.4.10.1) 1237 * Try Each 1239 - First Sequence: 1241 o Override Parameters directive (see Section 8.4.10.3, 1242 Section 8.4.8) for Slot A 1244 o Check Slot Condition (see Section 8.4.9.3) 1246 o Set Parameters directive (see Section 8.4.10.3) for URI A 1247 (see Section 8.4.8) 1249 - Second Sequence: 1251 o Override Parameters directive (see Section 8.4.10.3, 1252 Section 8.4.8) for Slot B 1254 o Check Slot Condition (see Section 8.4.9.3) 1256 o Set Parameters directive (see Section 8.4.10.3) for URI B 1257 (see Section 8.4.8) 1259 * Fetch 1261 If Trusted Invocation (Section 7.2) is used, only the run sequence is 1262 added to this template, since the common sequence is populated by 1263 this template: 1265 * Set Component Index directive (see Section 8.4.10.1) 1267 * Try Each 1269 - First Sequence: 1271 o Override Parameters directive (see Section 8.4.10.3, 1272 Section 8.4.8) for Slot A 1274 o Check Slot Condition (see Section 8.4.9.3) 1276 - Second Sequence: 1278 o Override Parameters directive (see Section 8.4.10.3, 1279 Section 8.4.8) for Slot B 1281 o Check Slot Condition (see Section 8.4.9.3) 1283 * Run 1285 NOTE: Any test can be used to select between images, Check Slot 1286 Condition is used in this template because it is a typical test for 1287 execute-in-place devices. 1289 8. Metadata Structure 1291 The metadata for SUIT updates is composed of several primary 1292 constituent parts: the Envelope, Authentication Information, 1293 Manifest, and Severable Elements. 1295 For a diagram of the metadata structure, see Section 5. 1297 8.1. Encoding Considerations 1299 The map indices in the envelope encoding are reset to 1 for each map 1300 within the structure. This is to keep the indices as small as 1301 possible. The goal is to keep the index objects to single bytes 1302 (CBOR positive integers 1-23). 1304 Wherever enumerations are used, they are started at 1. This allows 1305 detection of several common software errors that are caused by 1306 uninitialized variables. Positive numbers in enumerations are 1307 reserved for IANA registration. Negative numbers are used to 1308 identify application-specific values, as described in Section 11. 1310 All elements of the envelope must be wrapped in a bstr to minimize 1311 the complexity of the code that evaluates the cryptographic integrity 1312 of the element and to ensure correct serialization for integrity and 1313 authenticity checks. 1315 8.2. Envelope 1317 The Envelope contains each of the other primary constituent parts of 1318 the SUIT metadata. It allows for modular processing of the manifest 1319 by ordering components in the expected order of processing. 1321 The Envelope is encoded as a CBOR Map. Each element of the Envelope 1322 is enclosed in a bstr, which allows computation of a message digest 1323 against known bounds. 1325 8.3. Authenticated Manifests 1327 The suit-authentication-wrapper contains a SUIT Digest Container (see 1328 Section 10) and one or more SUIT Authentication Blocks. The 1329 SUIT_Digest carries the result of computing the indicated hash 1330 algorithm over the suit-manifest element. A signing application MUST 1331 verify the suit-manifest element against the SUIT_Digest prior to 1332 signing. A SUIT Authentication Block is implemented as 1333 COSE_Mac_Tagged, COSE_Mac0_Tagged, COSE_Sign_Tagged or 1334 COSE_Sign1_Tagged structures with detached payloads, as described in 1335 RFC 8152 [RFC8152]. 1337 For COSE_Sign and COSE_Sign1 a special signature structure (called 1338 Sig_structure) has to be created onto which the selected digital 1339 signature algorithm is applied to, see Section 4.4 of [RFC8152] for 1340 details. This specification requires Sig_structure to be populated 1341 as follows: * The external_aad field MUST be set to a zero-length 1342 binary string (i.e. there is no external additional authenticated 1343 data). * The payload field contains the SUIT_Digest wrapped in a 1344 bstr, as per the requirements in Section 4.4 of RFC 8152. All other 1345 fields in the Sig_structure are populated as described in Section 4.4 1346 of [RFC8152]. 1348 Likewise, Section 6.3 of [RFC8152] describes the details for 1349 computing a MAC and the fields of the MAC_structure need to be 1350 populated. The rules for external_aad and the payload fields 1351 described in the paragraph above also apply to this structure. 1353 The suit-authentication-wrapper MUST come before the suit-manifest 1354 element, regardless of canonical encoding of CBOR. 1356 A SUIT_Envelope that has not had authentication information added 1357 MUST still contain the suit-authentication-wrapper element, but the 1358 content MUST be a list containing only the SUIT_Digest. 1360 8.4. Manifest 1362 The manifest contains: 1364 * a version number (see Section 8.4.1) 1366 * a sequence number (see Section 8.4.2) 1368 * a reference URI (see Section 8.4.3) 1369 * a common structure with information that is shared between command 1370 sequences (see Section 8.4.5) 1372 * one or more lists of commands that the Recipient should perform 1373 (see Section 8.4.6) 1375 * a reference to the full manifest (see Section 8.4.3) 1377 * human-readable text describing the manifest found in the 1378 SUIT_Envelope (see Section 8.4.4) 1380 The Text section, or any Command Sequence of the Update Procedure 1381 (Image Fetch, Image Installation) can be either a CBOR structure or a 1382 SUIT_Digest. In each of these cases, the SUIT_Digest provides for a 1383 severable element. Severable elements are RECOMMENDED to implement. 1384 In particular, the human-readable text SHOULD be severable, since 1385 most useful text elements occupy more space than a SUIT_Digest, but 1386 are not needed by the Recipient. Because SUIT_Digest is a CBOR Array 1387 and each severable element is a CBOR bstr, it is straight-forward for 1388 a Recipient to determine whether an element has been severed. The 1389 key used for a severable element is the same in the SUIT_Manifest and 1390 in the SUIT_Envelope so that a Recipient can easily identify the 1391 correct data in the envelope. See Section 8.4.11 for more detail. 1393 8.4.1. suit-manifest-version 1395 The suit-manifest-version indicates the version of serialization used 1396 to encode the manifest. Version 1 is the version described in this 1397 document. suit-manifest-version is REQUIRED to implement. 1399 8.4.2. suit-manifest-sequence-number 1401 The suit-manifest-sequence-number is a monotonically increasing anti- 1402 rollback counter. Each Recipient MUST reject any manifest that has a 1403 sequence number lower than its current sequence number. For 1404 convenience, an implementer MAY use a UTC timestamp in seconds as the 1405 sequence number. suit-manifest-sequence-number is REQUIRED to 1406 implement. 1408 8.4.3. suit-reference-uri 1410 suit-reference-uri is a text string that encodes a URI where a full 1411 version of this manifest can be found. This is convenient for 1412 allowing management systems to show the severed elements of a 1413 manifest when this URI is reported by a Recipient after installation. 1415 8.4.4. suit-text 1417 suit-text SHOULD be a severable element. suit-text is a map 1418 containing two different types of pair: 1420 * integer => text 1422 * SUIT_Component_Identifier => map 1424 Each SUIT_Component_Identifier => map entry contains a map of integer 1425 => text values. All SUIT_Component_Identifiers present in suit-text 1426 MUST also be present in suit-common (Section 8.4.5). 1428 suit-text contains all the human-readable information that describes 1429 any and all parts of the manifest, its payload(s) and its 1430 resource(s). The text section is typically severable, allowing 1431 manifests to be distributed without the text, since end-nodes do not 1432 require text. The meaning of each field is described below. 1434 Each section MAY be present. If present, each section MUST be as 1435 described. Negative integer IDs are reserved for application- 1436 specific text values. 1438 The following table describes the text fields available in suit-text: 1440 +================================+==================================+ 1441 | CDDL Structure | Description | 1442 +================================+==================================+ 1443 | suit-text-manifest-description | Free text description of | 1444 | | the manifest | 1445 +--------------------------------+----------------------------------+ 1446 | suit-text-update-description | Free text description of | 1447 | | the update | 1448 +--------------------------------+----------------------------------+ 1449 | suit-text-manifest-json-source | The JSON-formatted document | 1450 | | that was used to create the | 1451 | | manifest | 1452 +--------------------------------+----------------------------------+ 1453 | suit-text-manifest-yaml-source | The YAML ([YAML])-formatted | 1454 | | document that was used to | 1455 | | create the manifest | 1456 +--------------------------------+----------------------------------+ 1458 Table 2 1460 The following table describes the text fields available in each map 1461 identified by a SUIT_Component_Identifier. 1463 +=================================+===============================+ 1464 | CDDL Structure | Description | 1465 +=================================+===============================+ 1466 | suit-text-vendor-name | Free text vendor name | 1467 +---------------------------------+-------------------------------+ 1468 | suit-text-model-name | Free text model name | 1469 +---------------------------------+-------------------------------+ 1470 | suit-text-vendor-domain | The domain used to create the | 1471 | | vendor-id condition | 1472 +---------------------------------+-------------------------------+ 1473 | suit-text-model-info | The information used to | 1474 | | create the class-id condition | 1475 +---------------------------------+-------------------------------+ 1476 | suit-text-component-description | Free text description of each | 1477 | | component in the manifest | 1478 +---------------------------------+-------------------------------+ 1479 | suit-text-component-version | A free text representation of | 1480 | | the component version | 1481 +---------------------------------+-------------------------------+ 1483 Table 3 1485 suit-text is OPTIONAL to implement. 1487 8.4.5. suit-common 1489 suit-common encodes all the information that is shared between each 1490 of the command sequences, including: suit-components, and suit- 1491 common-sequence. suit-common is REQUIRED to implement. 1493 suit-components is a list of SUIT_Component_Identifier 1494 (Section 8.4.5.1) blocks that specify the component identifiers that 1495 will be affected by the content of the current manifest. suit- 1496 components is REQUIRED to implement. 1498 suit-common-sequence is a SUIT_Command_Sequence to execute prior to 1499 executing any other command sequence. Typical actions in suit- 1500 common-sequence include setting expected Recipient identity and image 1501 digests when they are conditional (see Section 8.4.10.2 and 1502 Section 7.7 for more information on conditional sequences). suit- 1503 common-sequence is RECOMMENDED to implement. It is REQUIRED if the 1504 optimizations described in Section 6.2.1 will be used. Whenever a 1505 parameter or Try Each command is required by more than one Command 1506 Sequence, placing that parameter or command in suit-common-sequence 1507 results in a smaller encoding. 1509 8.4.5.1. SUIT_Component_Identifier 1511 A component is a unit of code or data that can be targeted by an 1512 update. To facilitate composite devices, components are identified 1513 by a list of CBOR byte strings, which allows construction of 1514 hierarchical component structures. Components are identified by 1515 Component Identifiers, but referenced in commands by Component Index; 1516 Component Identifiers are arrays of binary strings and a Component 1517 Index is an index into the array of Component Identifiers. 1519 A Component Identifier can be trivial, such as the simple array 1520 [h'00']. It can also represent a filesystem path by encoding each 1521 segment of the path as an element in the list. For example, the path 1522 "/usr/bin/env" would encode to ['usr','bin','env']. 1524 This hierarchical construction allows a component identifier to 1525 identify any part of a complex, multi-component system. 1527 8.4.6. SUIT_Command_Sequence 1529 A SUIT_Command_Sequence defines a series of actions that the 1530 Recipient MUST take to accomplish a particular goal. These goals are 1531 defined in the manifest and include: 1533 1. Payload Fetch: suit-payload-fetch is a SUIT_Command_Sequence to 1534 execute in order to obtain a payload. Some manifests may include 1535 these actions in the suit-install section instead if they operate 1536 in a streaming installation mode. This is particularly relevant 1537 for constrained devices without any temporary storage for staging 1538 the update. suit-payload-fetch is OPTIONAL to implement. 1540 2. Payload Installation: suit-install is a SUIT_Command_Sequence to 1541 execute in order to install a payload. Typical actions include 1542 verifying a payload stored in temporary storage, copying a staged 1543 payload from temporary storage, and unpacking a payload. suit- 1544 install is OPTIONAL to implement. 1546 3. Image Validation: suit-validate is a SUIT_Command_Sequence to 1547 execute in order to validate that the result of applying the 1548 update is correct. Typical actions involve image validation. 1549 suit-validate is REQUIRED to implement. 1551 4. Image Loading: suit-load is a SUIT_Command_Sequence to execute in 1552 order to prepare a payload for execution. Typical actions 1553 include copying an image from permanent storage into RAM, 1554 optionally including actions such as decryption or decompression. 1555 suit-load is OPTIONAL to implement. 1557 5. Run or Boot: suit-run is a SUIT_Command_Sequence to execute in 1558 order to run an image. suit-run typically contains a single 1559 instruction: the "run" directive. suit-run is OPTIONAL to 1560 implement. 1562 Goals 1,2 form the Update Procedure. Goals 4,5,6 form the Invocation 1563 Procedure. 1565 Each Command Sequence follows exactly the same structure to ensure 1566 that the parser is as simple as possible. 1568 Lists of commands are constructed from two kinds of element: 1570 1. Conditions that MUST be true and any failure is treated as a 1571 failure of the update/load/invocation 1573 2. Directives that MUST be executed. 1575 Each condition is composed of: 1577 1. A command code identifier 1579 2. A SUIT_Reporting_Policy (Section 8.4.7) 1581 Each directive is composed of: 1583 1. A command code identifier 1585 2. An argument block or a SUIT_Reporting_Policy (Section 8.4.7) 1587 Argument blocks are consumed only by flow-control directives: 1589 * Set Component Index 1591 * Set/Override Parameters 1593 * Try Each 1595 * Run Sequence 1597 Reporting policies provide a hint to the manifest processor of 1598 whether to add the success or failure of a command to any report that 1599 it generates. 1601 Many conditions and directives apply to a given component, and these 1602 generally grouped together. Therefore, a special command to set the 1603 current component index is provided. This index is a numeric index 1604 into the Component Identifier table defined at the beginning of the 1605 manifest. 1607 To facilitate optional conditions, a special directive, suit- 1608 directive-try-each (Section 8.4.10.2), is provided. It runs several 1609 new lists of conditions/directives, one after another, that are 1610 contained as an argument to the directive. By default, it assumes 1611 that a failure of a condition should not indicate a failure of the 1612 update/invocation, but a parameter is provided to override this 1613 behavior. See suit-parameter-soft-failure (Section 8.4.8.14). 1615 8.4.7. Reporting Policy 1617 To facilitate construction of Reports that describe the success or 1618 failure of a given Procedure, each command is given a Reporting 1619 Policy. This is an integer bitfield that follows the command and 1620 indicates what the Recipient should do with the Record of executing 1621 the command. The options are summarized in the table below. 1623 +=============================+==================================+ 1624 | Policy | Description | 1625 +=============================+==================================+ 1626 | suit-send-record-on-success | Record when the command succeeds | 1627 +-----------------------------+----------------------------------+ 1628 | suit-send-record-on-failure | Record when the command fails | 1629 +-----------------------------+----------------------------------+ 1630 | suit-send-sysinfo-success | Add system information when the | 1631 | | command succeeds | 1632 +-----------------------------+----------------------------------+ 1633 | suit-send-sysinfo-failure | Add system information when the | 1634 | | command fails | 1635 +-----------------------------+----------------------------------+ 1637 Table 4 1639 Any or all of these policies may be enabled at once. 1641 At the completion of each command, a Manifest Processor MAY forward 1642 information about the command to a Reporting Engine, which is 1643 responsible for reporting boot or update status to a third party. 1644 The Reporting Engine is entirely implementation-defined, the 1645 reporting policy simply facilitates the Reporting Engine's interface 1646 to the SUIT Manifest Processor. 1648 The information elements provided to the Reporting Engine are: 1650 * The reporting policy 1652 * The result of the command 1654 * The values of parameters consumed by the command 1656 * The system information consumed by the command 1658 Together, these elements are called a Record. A group of Records is 1659 a Report. 1661 If the component index is set to True or an array when a command is 1662 executed with a non-zero reporting policy, then the Reporting Engine 1663 MUST receive one Record for each Component, in the order expressed in 1664 the Components list or the component index array. 1666 This specification does not define a particular format of Records or 1667 Reports. This specification only defines hints to the Reporting 1668 Engine for which Records it should aggregate into the Report. The 1669 Reporting Engine MAY choose to ignore these hints and apply its own 1670 policy instead. 1672 When used in a Invocation Procedure, the report MAY form the basis of 1673 an attestation report. When used in an Update Process, the report 1674 MAY form the basis for one or more log entries. 1676 8.4.8. SUIT_Parameters 1678 Many conditions and directives require additional information. That 1679 information is contained within parameters that can be set in a 1680 consistent way. This allows reuse of parameters between commands, 1681 thus reducing manifest size. 1683 Most parameters are scoped to a specific component. This means that 1684 setting a parameter for one component has no effect on the parameters 1685 of any other component. The only exceptions to this are two Manifest 1686 Processor parameters: Strict Order and Soft Failure. 1688 The defined manifest parameters are described below. 1690 +==============+==================================+=================+ 1691 | Name | CDDL Structure | Reference | 1692 +==============+==================================+=================+ 1693 | Vendor ID | suit-parameter-vendor-identifier | Section 8.4.8.3 | 1694 +--------------+----------------------------------+-----------------+ 1695 | Class ID | suit-parameter-class-identifier | Section 8.4.8.4 | 1696 +--------------+----------------------------------+-----------------+ 1697 | Device ID | suit-parameter-device-identifier | Section 8.4.8.5 | 1698 +--------------+----------------------------------+-----------------+ 1699 | Image | suit-parameter-image-digest | Section 8.4.8.6 | 1700 | Digest | | | 1701 +--------------+----------------------------------+-----------------+ 1702 | Image | suit-parameter-image-size | Section 8.4.8.7 | 1703 | Size | | | 1704 +--------------+----------------------------------+-----------------+ 1705 | Component | suit-parameter-component-slot | Section 8.4.8.8 | 1706 | Slot | | | 1707 +--------------+----------------------------------+-----------------+ 1708 | URI | suit-parameter-uri | Section 8.4.8.9 | 1709 +--------------+----------------------------------+-----------------+ 1710 | Source | suit-parameter-source-component | Section | 1711 | Component | | 8.4.8.10 | 1712 +--------------+----------------------------------+-----------------+ 1713 | Run Args | suit-parameter-run-args | Section | 1714 | | | 8.4.8.11 | 1715 +--------------+----------------------------------+-----------------+ 1716 | Fetch | suit-parameter-fetch-arguments | Section | 1717 | Arguments | | 8.4.8.12 | 1718 +--------------+----------------------------------+-----------------+ 1719 | Strict | suit-parameter-strict-order | Section | 1720 | Order | | 8.4.8.13 | 1721 +--------------+----------------------------------+-----------------+ 1722 | Soft | suit-parameter-soft-failure | Section | 1723 | Failure | | 8.4.8.14 | 1724 +--------------+----------------------------------+-----------------+ 1725 | Custom | suit-parameter-custom | Section | 1726 | | | 8.4.8.15 | 1727 +--------------+----------------------------------+-----------------+ 1729 Table 5 1731 CBOR-encoded object parameters are still wrapped in a bstr. This is 1732 because it allows a parser that is aggregating parameters to 1733 reference the object with a single pointer and traverse it without 1734 understanding the contents. This is important for modularization and 1735 division of responsibility within a pull parser. The same 1736 consideration does not apply to Directives because those elements are 1737 invoked with their arguments immediately. 1739 8.4.8.1. CBOR PEN UUID Namespace Identifier 1741 The CBOR PEN UUID Namespace Identifier is constructed as follows: 1743 It uses the OID Namespace as a starting point, then uses the CBOR 1744 absolute OID encoding for the IANA PEN OID (1.3.6.1.4.1): 1746 D8 6F # tag(111) 1747 45 # bytes(5) 1748 # Absolute OID encoding of IANA Private Enterprise Number: 1749 # 1.3. 6. 1. 4. 1 1750 2B 06 01 04 01 # X.690 Clause 8.19 1752 Computing a type 5 UUID from these produces: 1754 NAMESPACE_CBOR_PEN = UUID5(NAMESPACE_OID, h'D86F452B06010401') 1755 NAMESPACE_CBOR_PEN = 47fbdabb-f2e4-55f0-bb39-3620c2f6df4e 1757 8.4.8.2. Constructing UUIDs 1759 Several conditions use identifiers to determine whether a manifest 1760 matches a given Recipient or not. These identifiers are defined to 1761 be RFC 4122 [RFC4122] UUIDs. These UUIDs are not human-readable and 1762 are therefore used for machine-based processing only. 1764 A Recipient MAY match any number of UUIDs for vendor or class 1765 identifier. This may be relevant to physical or software modules. 1766 For example, a Recipient that has an OS and one or more applications 1767 might list one Vendor ID for the OS and one or more additional Vendor 1768 IDs for the applications. This Recipient might also have a Class ID 1769 that must be matched for the OS and one or more Class IDs for the 1770 applications. 1772 Identifiers are used for compatibility checks. They MUST NOT be used 1773 as assertions of identity. They are evaluated by identifier 1774 conditions (Section 8.4.9.1). 1776 A more complete example: Imagine a device has the following physical 1777 components: 1. A host MCU 2. A WiFi module 1779 This same device has three software modules: 1. An operating system 1780 2. A WiFi module interface driver 3. An application 1782 Suppose that the WiFi module's firmware has a proprietary update 1783 mechanism and doesn't support manifest processing. This device can 1784 report four class IDs: 1786 1. Hardware model/revision 1787 2. OS 1789 3. WiFi module model/revision 1791 4. Application 1793 This allows the OS, WiFi module, and application to be updated 1794 independently. To combat possible incompatibilities, the OS class ID 1795 can be changed each time the OS has a change to its API. 1797 This approach allows a vendor to target, for example, all devices 1798 with a particular WiFi module with an update, which is a very 1799 powerful mechanism, particularly when used for security updates. 1801 UUIDs MUST be created according to RFC 4122 [RFC4122]. UUIDs SHOULD 1802 use versions 3, 4, or 5, as described in RFC4122. Versions 1 and 2 1803 do not provide a tangible benefit over version 4 for this 1804 application. 1806 The RECOMMENDED method to create a vendor ID is: 1808 Vendor ID = UUID5(DNS_PREFIX, vendor domain name) 1810 If the Vendor ID is a UUID, the RECOMMENDED method to create a Class 1811 ID is: 1813 Class ID = UUID5(Vendor ID, Class-Specific-Information) 1815 If the Vendor ID is a CBOR PEN (see Section 8.4.8.3), the RECOMMENDED 1816 method to create a Class ID is: 1818 Class ID = UUID5( 1819 UUID5(NAMESPACE_CBOR_PEN, CBOR_PEN), 1820 Class-Specific-Information) 1822 Class-specific-information is composed of a variety of data, for 1823 example: 1825 * Model number. 1827 * Hardware revision. 1829 * Bootloader version (for immutable bootloaders). 1831 8.4.8.3. suit-parameter-vendor-identifier 1833 suit-parameter-vendor-identifier may be presented in one of two ways: 1835 * A Private Enterprise Number 1837 * A byte string containing a UUID ([RFC4122]) 1839 Private Enterprise Numbers are encoded as a relative OID, according 1840 to the definition in [I-D.ietf-cbor-tags-oid]. All PENs are relative 1841 to the IANA PEN: 1.3.6.1.4.1. 1843 8.4.8.4. suit-parameter-class-identifier 1845 A RFC 4122 UUID representing the class of the device or component. 1846 The UUID is encoded as a 16 byte bstr, containing the raw bytes of 1847 the UUID. It MUST be constructed as described in Section 8.4.8.2 1849 8.4.8.5. suit-parameter-device-identifier 1851 A RFC 4122 UUID representing the specific device or component. The 1852 UUID is encoded as a 16 byte bstr, containing the raw bytes of the 1853 UUID. It MUST be constructed as described in Section 8.4.8.2 1855 8.4.8.6. suit-parameter-image-digest 1857 A fingerprint computed over the component itself, encoded in the 1858 SUIT_Digest Section 10 structure. The SUIT_Digest is wrapped in a 1859 bstr, as required in Section 8.4.8. 1861 8.4.8.7. suit-parameter-image-size 1863 The size of the firmware image in bytes. This size is encoded as a 1864 positive integer. 1866 8.4.8.8. suit-parameter-component-slot 1868 This parameter sets the slot index of a component. Some components 1869 support multiple possible Slots (offsets into a storage area). This 1870 parameter describes the intended Slot to use, identified by its index 1871 into the component's storage area. This slot MUST be encoded as a 1872 positive integer. 1874 8.4.8.9. suit-parameter-uri 1876 A URI Reference ([RFC3986]) from which to fetch a resource, encoded 1877 as a text string. CBOR Tag 32 is not used because the meaning of the 1878 text string is unambiguous in this context. 1880 8.4.8.10. suit-parameter-source-component 1882 This parameter sets the source component to be used with either suit- 1883 directive-copy (Section 8.4.10.5) or with suit-directive-swap 1884 (Section 8.4.10.8). The current Component, as set by suit-directive- 1885 set-component-index defines the destination, and suit-parameter- 1886 source-component defines the source. 1888 8.4.8.11. suit-parameter-run-args 1890 This parameter contains an encoded set of arguments for suit- 1891 directive-run (Section 8.4.10.6). The arguments MUST be provided as 1892 an implementation-defined bstr. 1894 8.4.8.12. suit-parameter-fetch-arguments 1896 An implementation-defined set of arguments to suit-directive-fetch 1897 (Section 8.4.10.4). Arguments are encoded in a bstr. 1899 8.4.8.13. suit-parameter-strict-order 1901 The Strict Order Parameter allows a manifest to govern when 1902 directives can be executed out-of-order. This allows for systems 1903 that have a sensitivity to order of updates to choose the order in 1904 which they are executed. It also allows for more advanced systems to 1905 parallelize their handling of updates. Strict Order defaults to 1906 True. It MAY be set to False when the order of operations does not 1907 matter. When arriving at the end of a command sequence, ALL commands 1908 MUST have completed, regardless of the state of 1909 SUIT_Parameter_Strict_Order. If SUIT_Parameter_Strict_Order is 1910 returned to True, ALL preceding commands MUST complete before the 1911 next command is executed. 1913 See Section 6.7 for behavioral description of Strict Order. 1915 8.4.8.14. suit-parameter-soft-failure 1917 When executing a command sequence inside suit-directive-try-each 1918 (Section 8.4.10.2) or suit-directive-run-sequence (Section 8.4.10.7) 1919 and a condition failure occurs, the manifest processor aborts the 1920 sequence. For suit-directive-try-each, if Soft Failure is True, the 1921 next sequence in Try Each is invoked, otherwise suit-directive-try- 1922 each fails with the condition failure code. In suit-directive-run- 1923 sequence, if Soft Failure is True the suit-directive-run-sequence 1924 simply halts with no side-effects and the Manifest Processor 1925 continues with the following command, otherwise, the suit-directive- 1926 run-sequence fails with the condition failure code. 1928 suit-parameter-soft-failure is scoped to the enclosing 1929 SUIT_Command_Sequence. Its value is discarded when 1930 SUIT_Command_Sequence terminates. It MUST NOT be set outside of 1931 suit-directive-try-each or suit-directive-run-sequence. 1933 When suit-directive-try-each is invoked, Soft Failure defaults to 1934 True. An Update Author may choose to set Soft Failure to False if 1935 they require a failed condition in a sequence to force an Abort. 1937 When suit-directive-run-sequence is invoked, Soft Failure defaults to 1938 False. An Update Author may choose to make failures soft within a 1939 suit-directive-run-sequence. 1941 8.4.8.15. suit-parameter-custom 1943 This parameter is an extension point for any proprietary, application 1944 specific conditions and directives. It MUST NOT be used in the 1945 common sequence. This effectively scopes each custom command to a 1946 particular Vendor Identifier/Class Identifier pair. 1948 8.4.9. SUIT_Condition 1950 Conditions are used to define mandatory properties of a system in 1951 order for an update to be applied. They can be pre-conditions or 1952 post-conditions of any directive or series of directives, depending 1953 on where they are placed in the list. All Conditions specify a 1954 Reporting Policy as described Section 8.4.7. Conditions include: 1956 +===================+==================================+===========+ 1957 | Name | CDDL Structure | Reference | 1958 +===================+==================================+===========+ 1959 | Vendor Identifier | suit-condition-vendor-identifier | Section | 1960 | | | 8.4.9.1 | 1961 +-------------------+----------------------------------+-----------+ 1962 | Class Identifier | suit-condition-class-identifier | Section | 1963 | | | 8.4.9.1 | 1964 +-------------------+----------------------------------+-----------+ 1965 | Device Identifier | suit-condition-device-identifier | Section | 1966 | | | 8.4.9.1 | 1967 +-------------------+----------------------------------+-----------+ 1968 | Image Match | suit-condition-image-match | Section | 1969 | | | 8.4.9.2 | 1970 +-------------------+----------------------------------+-----------+ 1971 | Component Slot | suit-condition-component-slot | Section | 1972 | | | 8.4.9.3 | 1973 +-------------------+----------------------------------+-----------+ 1974 | Abort | suit-condition-abort | Section | 1975 | | | 8.4.9.4 | 1976 +-------------------+----------------------------------+-----------+ 1977 | Custom Condition | suit-condition-custom | Section | 1978 | | | 8.4.9.5 | 1979 +-------------------+----------------------------------+-----------+ 1981 Table 6 1983 The abstract description of these conditions is defined in 1984 Section 6.4. 1986 Conditions compare parameters against properties of the system. 1987 These properties may be asserted in many different ways, including: 1988 calculation on-demand, volatile definition in memory, static 1989 definition within the manifest processor, storage in known location 1990 within an image, storage within a key storage system, storage in One- 1991 Time-Programmable memory, inclusion in mask ROM, or inclusion as a 1992 register in hardware. Some of these assertion methods are global in 1993 scope, such as a hardware register, some are scoped to an individual 1994 component, such as storage at a known location in an image, and some 1995 assertion methods can be either global or component-scope, based on 1996 implementation. 1998 Each condition MUST report a result code on completion. If a 1999 condition reports failure, then the current sequence of commands MUST 2000 terminate. A subsequent command or command sequence MAY continue 2001 executing if suit-parameter-soft-failure (Section 8.4.8.14) is set. 2002 If a condition requires additional information, this MUST be 2003 specified in one or more parameters before the condition is executed. 2005 If a Recipient attempts to process a condition that expects 2006 additional information and that information has not been set, it MUST 2007 report a failure. If a Recipient encounters an unknown condition, it 2008 MUST report a failure. 2010 Condition labels in the positive number range are reserved for IANA 2011 registration while those in the negative range are custom conditions 2012 reserved for proprietary definition by the author of a manifest 2013 processor. See Section 11 for more details. 2015 8.4.9.1. suit-condition-vendor-identifier, suit-condition-class- 2016 identifier, and suit-condition-device-identifier 2018 There are three identifier-based conditions: suit-condition-vendor- 2019 identifier, suit-condition-class-identifier, and suit-condition- 2020 device-identifier. Each of these conditions match a RFC 4122 2021 [RFC4122] UUID that MUST have already been set as a parameter. The 2022 installing Recipient MUST match the specified UUID in order to 2023 consider the manifest valid. These identifiers are scoped by 2024 component in the manifest. Each component MAY match more than one 2025 identifier. Care is needed to ensure that manifests correctly 2026 identify their targets using these conditions. Using only a generic 2027 class ID for a device-specific firmware could result in matching 2028 devices that are not compatible. 2030 The Recipient uses the ID parameter that has already been set using 2031 the Set Parameters directive. If no ID has been set, this condition 2032 fails. suit-condition-class-identifier and suit-condition-vendor- 2033 identifier are REQUIRED to implement. suit-condition-device- 2034 identifier is OPTIONAL to implement. 2036 Each identifier condition compares the corresponding identifier 2037 parameter to a parameter asserted to the Manifest Processor by the 2038 Recipient. Identifiers MUST be known to the Manifest Processor in 2039 order to evaluate compatibility. 2041 8.4.9.2. suit-condition-image-match 2043 Verify that the current component matches the suit-parameter-image- 2044 digest (Section 8.4.8.6) for the current component. The digest is 2045 verified against the digest specified in the Component's parameters 2046 list. If no digest is specified, the condition fails. suit- 2047 condition-image-match is REQUIRED to implement. 2049 8.4.9.3. suit-condition-component-slot 2051 Verify that the slot index of the current component matches the slot 2052 index set in suit-parameter-component-slot (Section 8.4.8.8). This 2053 condition allows a manifest to select between several images to match 2054 a target slot. 2056 8.4.9.4. suit-condition-abort 2058 Unconditionally fail. This operation is typically used in 2059 conjunction with suit-directive-try-each (Section 8.4.10.2). 2061 8.4.9.5. suit-condition-custom 2063 suit-condition-custom describes any proprietary, application specific 2064 condition. This is encoded as a negative integer, chosen by the 2065 firmware developer. If additional information must be provided to 2066 the condition, it should be encoded in a custom parameter (a nint) as 2067 described in Section 8.4.8. SUIT_Condition_Custom is OPTIONAL to 2068 implement. 2070 8.4.10. SUIT_Directive 2072 Directives are used to define the behavior of the recipient. 2073 Directives include: 2075 +===============+====================================+===========+ 2076 | Name | CDDL Structure | Reference | 2077 +===============+====================================+===========+ 2078 | Set Component | suit-directive-set-component-index | Section | 2079 | Index | | 8.4.10.1 | 2080 +---------------+------------------------------------+-----------+ 2081 | Try Each | suit-directive-try-each | Section | 2082 | | | 8.4.10.2 | 2083 +---------------+------------------------------------+-----------+ 2084 | Override | suit-directive-override-parameters | Section | 2085 | Parameters | | 8.4.10.3 | 2086 +---------------+------------------------------------+-----------+ 2087 | Fetch | suit-directive-fetch | Section | 2088 | | | 8.4.10.4 | 2089 +---------------+------------------------------------+-----------+ 2090 | Copy | suit-directive-copy | Section | 2091 | | | 8.4.10.5 | 2092 +---------------+------------------------------------+-----------+ 2093 | Run | suit-directive-run | Section | 2094 | | | 8.4.10.6 | 2095 +---------------+------------------------------------+-----------+ 2096 | Run Sequence | suit-directive-run-sequence | Section | 2097 | | | 8.4.10.7 | 2098 +---------------+------------------------------------+-----------+ 2099 | Swap | suit-directive-swap | Section | 2100 | | | 8.4.10.8 | 2101 +---------------+------------------------------------+-----------+ 2103 Table 7 2105 The abstract description of these commands is defined in Section 6.4. 2107 When a Recipient executes a Directive, it MUST report a result code. 2108 If the Directive reports failure, then the current Command Sequence 2109 MUST be terminated. 2111 8.4.10.1. suit-directive-set-component-index 2113 Set Component Index defines the component to which successive 2114 directives and conditions will apply. The supplied argument MUST be 2115 one of three types: 2117 1. An unsigned integer (REQUIRED to implement in parser) 2119 2. A boolean (REQUIRED to implement in parser ONLY IF 2 or more 2120 components supported) 2122 3. An array of unsigned integers (REQUIRED to implement in parser 2123 ONLY IF 3 or more components supported) 2125 If the following commands apply to ONE component, an unsigned integer 2126 index into the component list is used. If the following commands 2127 apply to ALL components, then the boolean value "True" is used 2128 instead of an index. If the following commands apply to more than 2129 one, but not all components, then an array of unsigned integer 2130 indices into the component list is used. See Section 6.5 for more 2131 details. 2133 If component index is set to True when a command is invoked, then the 2134 command applies to all components, in the order they appear in suit- 2135 common-components. When the Manifest Processor invokes a command 2136 while the component index is set to True, it must execute the command 2137 once for each possible component index, ensuring that the command 2138 receives the parameters corresponding to that component index. 2140 8.4.10.2. suit-directive-try-each 2142 This command runs several SUIT_Command_Sequence instances, one after 2143 another, in a strict order. Use this command to implement a "try/ 2144 catch-try/catch" sequence. Manifest processors MAY implement this 2145 command. 2147 suit-parameter-soft-failure (Section 8.4.8.14) is initialized to True 2148 at the beginning of each sequence. If one sequence aborts due to a 2149 condition failure, the next is started. If no sequence completes 2150 without condition failure, then suit-directive-try-each returns an 2151 error. If a particular application calls for all sequences to fail 2152 and still continue, then an empty sequence (nil) can be added to the 2153 Try Each Argument. 2155 The argument to suit-directive-try-each is a list of 2156 SUIT_Command_Sequence. suit-directive-try-each does not specify a 2157 reporting policy. 2159 8.4.10.3. suit-directive-override-parameters 2161 suit-directive-override-parameters replaces any listed parameters 2162 that are already set with the values that are provided in its 2163 argument. This allows a manifest to prevent replacement of critical 2164 parameters. 2166 Available parameters are defined in Section 8.4.8. 2168 suit-directive-override-parameters does not specify a reporting 2169 policy. 2171 8.4.10.4. suit-directive-fetch 2173 suit-directive-fetch instructs the manifest processor to obtain one 2174 or more manifests or payloads, as specified by the manifest index and 2175 component index, respectively. 2177 suit-directive-fetch can target one or more payloads. suit-directive- 2178 fetch retrieves each component listed in component-index. If 2179 component-index is True, instead of an integer, then all current 2180 manifest components are fetched. If component-index is an array, 2181 then all listed components are fetched. 2183 suit-directive-fetch typically takes no arguments unless one is 2184 needed to modify fetch behavior. If an argument is needed, it must 2185 be wrapped in a bstr and set in suit-parameter-fetch-arguments. 2187 suit-directive-fetch reads the URI parameter to find the source of 2188 the fetch it performs. 2190 8.4.10.5. suit-directive-copy 2192 suit-directive-copy instructs the manifest processor to obtain one or 2193 more payloads, as specified by the component index. As described in 2194 Section 6.5 component index may be a single integer, a list of 2195 integers, or True. suit-directive-copy retrieves each component 2196 specified by the current component-index, respectively. 2198 suit-directive-copy reads its source from suit-parameter-source- 2199 component (Section 8.4.8.10). 2201 If either the source component parameter or the source component 2202 itself is absent, this command fails. 2204 8.4.10.6. suit-directive-run 2206 suit-directive-run directs the manifest processor to transfer 2207 execution to the current Component Index. When this is invoked, the 2208 manifest processor MAY be unloaded and execution continues in the 2209 Component Index. Arguments are provided to suit-directive-run 2210 through suit-parameter-run-arguments (Section 8.4.8.11) and are 2211 forwarded to the executable code located in Component Index in an 2212 application-specific way. For example, this could form the Linux 2213 Kernel Command Line if booting a Linux device. 2215 If the executable code at Component Index is constructed in such a 2216 way that it does not unload the manifest processor, then the manifest 2217 processor may resume execution after the executable completes. This 2218 allows the manifest processor to invoke suitable helpers and to 2219 verify them with image conditions. 2221 8.4.10.7. suit-directive-run-sequence 2223 To enable conditional commands, and to allow several strictly ordered 2224 sequences to be executed out-of-order, suit-directive-run-sequence 2225 allows the manifest processor to execute its argument as a 2226 SUIT_Command_Sequence. The argument must be wrapped in a bstr. 2228 When a sequence is executed, any failure of a condition causes 2229 immediate termination of the sequence. 2231 When suit-directive-run-sequence completes, it forwards the last 2232 status code that occurred in the sequence. If the Soft Failure 2233 parameter is true, then suit-directive-run-sequence only fails when a 2234 directive in the argument sequence fails. 2236 suit-parameter-soft-failure (Section 8.4.8.14) defaults to False when 2237 suit-directive-run-sequence begins. Its value is discarded when 2238 suit-directive-run-sequence terminates. 2240 8.4.10.8. suit-directive-swap 2242 suit-directive-swap instructs the manifest processor to move the 2243 source to the destination and the destination to the source 2244 simultaneously. Swap has nearly identical semantics to suit- 2245 directive-copy except that suit-directive-swap replaces the source 2246 with the current contents of the destination in an application- 2247 defined way. As with suit-directive-copy, if the source component is 2248 missing, this command fails. 2250 If SUIT_Parameter_Compression_Info or SUIT_Parameter_Encryption_Info 2251 are present, they MUST be handled in a symmetric way, so that the 2252 source is decompressed into the destination and the destination is 2253 compressed into the source. The source is decrypted into the 2254 destination and the destination is encrypted into the source. suit- 2255 directive-swap is OPTIONAL to implement. 2257 8.4.11. Integrity Check Values 2259 When the Text section or any Command Sequence of the Update Procedure 2260 is made severable, it is moved to the Envelope and replaced with a 2261 SUIT_Digest. The SUIT_Digest is computed over the entire bstr 2262 enclosing the Manifest element that has been moved to the Envelope. 2263 Each element that is made severable from the Manifest is placed in 2264 the Envelope. The keys for the envelope elements have the same 2265 values as the keys for the manifest elements. 2267 Each Integrity Check Value covers the corresponding Envelope Element 2268 as described in Section 8.5. 2270 8.5. Severable Elements 2272 Because the manifest can be used by different actors at different 2273 times, some parts of the manifest can be removed or "Severed" without 2274 affecting later stages of the lifecycle. Severing of information is 2275 achieved by separating that information from the signed container so 2276 that removing it does not affect the signature. This means that 2277 ensuring integrity of severable parts of the manifest is a 2278 requirement for the signed portion of the manifest. Severing some 2279 parts makes it possible to discard parts of the manifest that are no 2280 longer necessary. This is important because it allows the storage 2281 used by the manifest to be greatly reduced. For example, no text 2282 size limits are needed if text is removed from the manifest prior to 2283 delivery to a constrained device. 2285 Elements are made severable by removing them from the manifest, 2286 encoding them in a bstr, and placing a SUIT_Digest of the bstr in the 2287 manifest so that they can still be authenticated. The SUIT_Digest 2288 typically consumes 4 bytes more than the size of the raw digest, 2289 therefore elements smaller than (Digest Bits)/8 + 4 SHOULD NOT be 2290 severable. Elements larger than (Digest Bits)/8 + 4 MAY be 2291 severable, while elements that are much larger than (Digest Bits)/8 + 2292 4 SHOULD be severable. 2294 Because of this, all command sequences in the manifest are encoded in 2295 a bstr so that there is a single code path needed for all command 2296 sequences. 2298 9. Access Control Lists 2300 To manage permissions in the manifest, there are three models that 2301 can be used. 2303 First, the simplest model requires that all manifests are 2304 authenticated by a single trusted key. This mode has the advantage 2305 that only a root manifest needs to be authenticated, since all of its 2306 dependencies have digests included in the root manifest. 2308 This simplest model can be extended by adding key delegation without 2309 much increase in complexity. 2311 A second model requires an ACL to be presented to the Recipient, 2312 authenticated by a trusted party or stored on the Recipient. This 2313 ACL grants access rights for specific component IDs or Component 2314 Identifier prefixes to the listed identities or identity groups. Any 2315 identity can verify an image digest, but fetching into or fetching 2316 from a Component Identifier requires approval from the ACL. 2318 A third model allows a Recipient to provide even more fine-grained 2319 controls: The ACL lists the Component Identifier or Component 2320 Identifier prefix that an identity can use, and also lists the 2321 commands and parameters that the identity can use in combination with 2322 that Component Identifier. 2324 10. SUIT Digest Container 2326 The SUIT digest is a CBOR List containing two elements: an algorithm 2327 identifier and a bstr containing the bytes of the digest. Some forms 2328 of digest may require additional parameters. These can be added 2329 following the digest. 2331 The values of the algorithm identifier are defined by 2332 [I-D.ietf-cose-hash-algs]. The following algorithms MUST be 2333 implemented by all Manifest Processors: 2335 * SHA-256 (-16) 2337 The following algorithms MAY be implemented in a Manifest Processor: 2339 * SHAKE128 (-18) 2341 * SHA-384 (-43) 2343 * SHA-512 (-44) 2345 * SHAKE256 (-45) 2347 11. IANA Considerations 2349 IANA is requested to: 2351 * allocate CBOR tag 107 in the CBOR Tags registry for the SUIT 2352 Envelope. 2354 * allocate CBOR tag 1070 in the CBOR Tags registry for the SUIT 2355 Manifest. 2357 * allocate media type application/suit-envelope in the Media Types 2358 registry. 2360 * setup several registries as described below. 2362 IANA is requested to setup a registry for SUIT manifests. Several 2363 registries defined in the subsections below need to be created. 2365 For each registry, values 0-23 are Standards Action, 24-255 are IETF 2366 Review, 256-65535 are Expert Review, and 65536 or greater are First 2367 Come First Served. 2369 Negative values -23 to 0 are Experimental Use, -24 and lower are 2370 Private Use. 2372 11.1. SUIT Commands 2374 +=======+=====================+==================+ 2375 | Label | Name | Reference | 2376 +=======+=====================+==================+ 2377 | 1 | Vendor Identifier | Section 8.4.9.1 | 2378 +-------+---------------------+------------------+ 2379 | 2 | Class Identifier | Section 8.4.9.1 | 2380 +-------+---------------------+------------------+ 2381 | 3 | Image Match | Section 8.4.9.2 | 2382 +-------+---------------------+------------------+ 2383 | 4 | Reserved | | 2384 +-------+---------------------+------------------+ 2385 | 5 | Component Slot | Section 8.4.9.3 | 2386 +-------+---------------------+------------------+ 2387 | 12 | Set Component Index | Section 8.4.10.1 | 2388 +-------+---------------------+------------------+ 2389 | 13 | Reserved | | 2390 +-------+---------------------+------------------+ 2391 | 14 | Abort | | 2392 +-------+---------------------+------------------+ 2393 | 15 | Try Each | Section 8.4.10.2 | 2394 +-------+---------------------+------------------+ 2395 | 16 | Reserved | | 2396 +-------+---------------------+------------------+ 2397 | 17 | Reserved | | 2398 +-------+---------------------+------------------+ 2399 | 18 | Reserved | | 2400 +-------+---------------------+------------------+ 2401 | 19 | Reserved | | 2402 +-------+---------------------+------------------+ 2403 | 20 | Override Parameters | Section 8.4.10.3 | 2404 +-------+---------------------+------------------+ 2405 | 21 | Fetch | Section 8.4.10.4 | 2406 +-------+---------------------+------------------+ 2407 | 22 | Copy | Section 8.4.10.5 | 2408 +-------+---------------------+------------------+ 2409 | 23 | Run | Section 8.4.10.6 | 2410 +-------+---------------------+------------------+ 2411 | 24 | Device Identifier | Section 8.4.9.1 | 2412 +-------+---------------------+------------------+ 2413 | 25 | Reserved | | 2414 +-------+---------------------+------------------+ 2415 | 26 | Reserved | | 2416 +-------+---------------------+------------------+ 2417 | 27 | Reserved | | 2418 +-------+---------------------+------------------+ 2419 | 28 | Reserved | | 2420 +-------+---------------------+------------------+ 2421 | 29 | Reserved | | 2422 +-------+---------------------+------------------+ 2423 | 30 | Reserved | | 2424 +-------+---------------------+------------------+ 2425 | 31 | Swap | Section 8.4.10.8 | 2426 +-------+---------------------+------------------+ 2427 | 32 | Run Sequence | Section 8.4.10.7 | 2428 +-------+---------------------+------------------+ 2429 | 33 | Reserved | | 2430 +-------+---------------------+------------------+ 2431 | nint | Custom Condition | Section 8.4.9.5 | 2432 +-------+---------------------+------------------+ 2434 Table 8 2436 11.2. SUIT Parameters 2438 +=======+==================+==================+ 2439 | Label | Name | Reference | 2440 +=======+==================+==================+ 2441 | 1 | Vendor ID | Section 8.4.8.3 | 2442 +-------+------------------+------------------+ 2443 | 2 | Class ID | Section 8.4.8.4 | 2444 +-------+------------------+------------------+ 2445 | 3 | Image Digest | Section 8.4.8.6 | 2446 +-------+------------------+------------------+ 2447 | 4 | Reserved | | 2448 +-------+------------------+------------------+ 2449 | 5 | Component Slot | Section 8.4.8.8 | 2450 +-------+------------------+------------------+ 2451 | 12 | Strict Order | Section 8.4.8.13 | 2452 +-------+------------------+------------------+ 2453 | 13 | Soft Failure | Section 8.4.8.14 | 2454 +-------+------------------+------------------+ 2455 | 14 | Image Size | Section 8.4.8.7 | 2456 +-------+------------------+------------------+ 2457 | 18 | Reserved | | 2458 +-------+------------------+------------------+ 2459 | 19 | Reserved | | 2460 +-------+------------------+------------------+ 2461 | 20 | Reserved | | 2462 +-------+------------------+------------------+ 2463 | 21 | URI | Section 8.4.8.9 | 2464 +-------+------------------+------------------+ 2465 | 22 | Source Component | Section 8.4.8.10 | 2466 +-------+------------------+------------------+ 2467 | 23 | Run Args | Section 8.4.8.11 | 2468 +-------+------------------+------------------+ 2469 | 24 | Device ID | Section 8.4.8.5 | 2470 +-------+------------------+------------------+ 2471 | 26 | Reserved | | 2472 +-------+------------------+------------------+ 2473 | 27 | Reserved | | 2474 +-------+------------------+------------------+ 2475 | 28 | Reserved | | 2476 +-------+------------------+------------------+ 2477 | 29 | Reserved | | 2478 +-------+------------------+------------------+ 2479 | 30 | Reserved | | 2480 +-------+------------------+------------------+ 2481 | nint | Custom | Section 8.4.8.15 | 2482 +-------+------------------+------------------+ 2484 Table 9 2486 11.3. SUIT Text Values 2488 +=======+======================+===============+ 2489 | Label | Name | Reference | 2490 +=======+======================+===============+ 2491 | 1 | Manifest Description | Section 8.4.4 | 2492 +-------+----------------------+---------------+ 2493 | 2 | Update Description | Section 8.4.4 | 2494 +-------+----------------------+---------------+ 2495 | 3 | Manifest JSON Source | Section 8.4.4 | 2496 +-------+----------------------+---------------+ 2497 | 4 | Manifest YAML Source | Section 8.4.4 | 2498 +-------+----------------------+---------------+ 2499 | nint | Custom | Section 8.4.4 | 2500 +-------+----------------------+---------------+ 2502 Table 10 2504 11.4. SUIT Component Text Values 2506 +=======+============================+===============+ 2507 | Label | Name | Reference | 2508 +=======+============================+===============+ 2509 | 1 | Vendor Name | Section 8.4.4 | 2510 +-------+----------------------------+---------------+ 2511 | 2 | Model Name | Section 8.4.4 | 2512 +-------+----------------------------+---------------+ 2513 | 3 | Vendor Domain | Section 8.4.4 | 2514 +-------+----------------------------+---------------+ 2515 | 4 | Model Info | Section 8.4.4 | 2516 +-------+----------------------------+---------------+ 2517 | 5 | Component Description | Section 8.4.4 | 2518 +-------+----------------------------+---------------+ 2519 | 6 | Component Version | Section 8.4.4 | 2520 +-------+----------------------------+---------------+ 2521 | 7 | Component Version Required | Section 8.4.4 | 2522 +-------+----------------------------+---------------+ 2523 | nint | Custom | Section 8.4.4 | 2524 +-------+----------------------------+---------------+ 2526 Table 11 2528 12. Security Considerations 2530 This document is about a manifest format protecting and describing 2531 how to retrieve, install, and invoke firmware images and as such it 2532 is part of a larger solution for delivering firmware updates to IoT 2533 devices. A detailed security treatment can be found in the 2534 architecture [RFC9019] and in the information model [RFC9124] 2535 documents. 2537 13. Acknowledgements 2539 We would like to thank the following persons for their support in 2540 designing this mechanism: 2542 * Milosch Meriac 2543 * Geraint Luff 2545 * Dan Ros 2547 * John-Paul Stanford 2549 * Hugo Vincent 2551 * Carsten Bormann 2553 * Oeyvind Roenningstad 2555 * Frank Audun Kvamtroe 2557 * Krzysztof Chruściński 2559 * Andrzej Puzdrowski 2561 * Michael Richardson 2563 * David Brown 2565 * Emmanuel Baccelli 2567 14. References 2569 14.1. Normative References 2571 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2572 Requirement Levels", BCP 14, RFC 2119, 2573 DOI 10.17487/RFC2119, March 1997, 2574 . 2576 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2577 Resource Identifier (URI): Generic Syntax", STD 66, 2578 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2579 . 2581 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 2582 Unique IDentifier (UUID) URN Namespace", RFC 4122, 2583 DOI 10.17487/RFC4122, July 2005, 2584 . 2586 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 2587 RFC 8152, DOI 10.17487/RFC8152, July 2017, 2588 . 2590 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2591 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2592 May 2017, . 2594 [RFC9019] Moran, B., Tschofenig, H., Brown, D., and M. Meriac, "A 2595 Firmware Update Architecture for Internet of Things", 2596 RFC 9019, DOI 10.17487/RFC9019, April 2021, 2597 . 2599 [RFC9124] Moran, B., Tschofenig, H., and H. Birkholz, "A Manifest 2600 Information Model for Firmware Updates in Internet of 2601 Things (IoT) Devices", RFC 9124, DOI 10.17487/RFC9124, 2602 January 2022, . 2604 14.2. Informative References 2606 [I-D.ietf-cbor-tags-oid] 2607 Bormann, C., "Concise Binary Object Representation (CBOR) 2608 Tags for Object Identifiers", Work in Progress, Internet- 2609 Draft, draft-ietf-cbor-tags-oid-08, 21 May 2021, 2610 . 2613 [I-D.ietf-cose-hash-algs] 2614 Schaad, J., "CBOR Object Signing and Encryption (COSE): 2615 Hash Algorithms", Work in Progress, Internet-Draft, draft- 2616 ietf-cose-hash-algs-09, 14 September 2020, 2617 . 2620 [I-D.ietf-suit-firmware-encryption] 2621 Tschofenig, H., Housley, R., and B. Moran, "Firmware 2622 Encryption with SUIT Manifests", Work in Progress, 2623 Internet-Draft, draft-ietf-suit-firmware-encryption-04, 20 2624 April 2022, . 2627 [I-D.ietf-suit-report] 2628 Moran, B. and H. Birkholz, "Secure Reporting of Update 2629 Status", Work in Progress, Internet-Draft, draft-ietf- 2630 suit-report-01, 12 January 2022, 2631 . 2634 [I-D.ietf-suit-trust-domains] 2635 Moran, B., "SUIT Manifest Extensions for Multiple Trust 2636 Domains", Work in Progress, Internet-Draft, draft-ietf- 2637 suit-trust-domains-00, 7 March 2022, 2638 . 2641 [I-D.ietf-suit-update-management] 2642 Moran, B., "Update Management Extensions for Software 2643 Updates for Internet of Things (SUIT) Manifests", Work in 2644 Progress, Internet-Draft, draft-ietf-suit-update- 2645 management-00, 7 March 2022, 2646 . 2649 [I-D.ietf-teep-architecture] 2650 Pei, M., Tschofenig, H., Thaler, D., and D. Wheeler, 2651 "Trusted Execution Environment Provisioning (TEEP) 2652 Architecture", Work in Progress, Internet-Draft, draft- 2653 ietf-teep-architecture-17, 19 April 2022, 2654 . 2657 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 2658 Constrained-Node Networks", RFC 7228, 2659 DOI 10.17487/RFC7228, May 2014, 2660 . 2662 [YAML] "YAML Ain't Markup Language", 2020, . 2664 Appendix A. A. Full CDDL 2666 In order to create a valid SUIT Manifest document the structure of 2667 the corresponding CBOR message MUST adhere to the following CDDL data 2668 definition. 2670 To be valid, the following CDDL MUST have the COSE CDDL appended to 2671 it. The COSE CDDL can be obtained by following the directions in 2672 [RFC8152], Section 1.3. 2674 SUIT_Envelope_Tagged = #6.107(SUIT_Envelope) 2675 SUIT_Envelope = { 2676 suit-authentication-wrapper => bstr .cbor SUIT_Authentication, 2677 suit-manifest => bstr .cbor SUIT_Manifest, 2678 SUIT_Severable_Manifest_Members, 2679 * SUIT_Integrated_Payload, 2680 * $$SUIT_Envelope_Extensions, 2681 * (int => bstr) 2683 } 2685 SUIT_Authentication = [ 2686 bstr .cbor SUIT_Digest, 2687 * bstr .cbor SUIT_Authentication_Block 2688 ] 2690 SUIT_Digest = [ 2691 suit-digest-algorithm-id : suit-cose-hash-algs, 2692 suit-digest-bytes : bstr, 2693 * $$SUIT_Digest-extensions 2694 ] 2696 SUIT_Authentication_Block /= COSE_Mac_Tagged 2697 SUIT_Authentication_Block /= COSE_Sign_Tagged 2698 SUIT_Authentication_Block /= COSE_Mac0_Tagged 2699 SUIT_Authentication_Block /= COSE_Sign1_Tagged 2701 SUIT_Severable_Manifest_Members = ( 2702 ? suit-payload-fetch => bstr .cbor SUIT_Command_Sequence, 2703 ? suit-install => bstr .cbor SUIT_Command_Sequence, 2704 ? suit-text => bstr .cbor SUIT_Text_Map, 2705 * $$SUIT_severable-members-extensions, 2706 ) 2708 SUIT_Integrated_Payload = (suit-integrated-payload-key => bstr) 2709 suit-integrated-payload-key = tstr 2711 SUIT_Manifest_Tagged = #6.1070(SUIT_Manifest) 2713 SUIT_Manifest = { 2714 suit-manifest-version => 1, 2715 suit-manifest-sequence-number => uint, 2716 suit-common => bstr .cbor SUIT_Common, 2717 ? suit-reference-uri => tstr, 2718 SUIT_Severable_Members_Choice, 2719 SUIT_Unseverable_Members, 2720 * $$SUIT_Manifest_Extensions, 2721 } 2723 SUIT_Unseverable_Members = ( 2724 ? suit-validate => bstr .cbor SUIT_Command_Sequence, 2725 ? suit-load => bstr .cbor SUIT_Command_Sequence, 2726 ? suit-run => bstr .cbor SUIT_Command_Sequence, 2727 * $$unseverable-manifest-member-extensions, 2728 ) 2730 SUIT_Severable_Members_Choice = ( 2731 ? suit-payload-fetch => 2732 bstr .cbor SUIT_Command_Sequence / SUIT_Digest, 2733 ? suit-install => bstr .cbor SUIT_Command_Sequence / SUIT_Digest, 2734 ? suit-text => bstr .cbor SUIT_Command_Sequence / SUIT_Digest, 2735 * $$severable-manifest-members-choice-extensions 2736 ) 2738 SUIT_Common = { 2739 ? suit-components => SUIT_Components, 2740 ? suit-common-sequence => bstr .cbor SUIT_Common_Sequence, 2741 * $$SUIT_Common-extensions, 2742 } 2744 SUIT_Components = [ + SUIT_Component_Identifier ] 2746 SUIT_Dependency = { 2747 suit-dependency-digest => SUIT_Digest, 2748 ? suit-dependency-prefix => SUIT_Component_Identifier, 2749 * $$SUIT_Dependency-extensions, 2750 } 2752 ;REQUIRED to implement: 2753 suit-cose-hash-algs /= cose-alg-sha-256 2755 ;OPTIONAL to implement: 2756 suit-cose-hash-algs /= cose-alg-shake128 2757 suit-cose-hash-algs /= cose-alg-sha-384 2758 suit-cose-hash-algs /= cose-alg-sha-512 2759 suit-cose-hash-algs /= cose-alg-shake256 2761 SUIT_Component_Identifier = [* bstr] 2763 SUIT_Common_Sequence = [ 2764 + ( SUIT_Condition // SUIT_Common_Commands ) 2765 ] 2767 SUIT_Common_Commands //= (suit-directive-set-component-index, IndexArg) 2768 SUIT_Common_Commands //= (suit-directive-run-sequence, 2769 bstr .cbor SUIT_Command_Sequence) 2770 SUIT_Common_Commands //= (suit-directive-try-each, 2771 SUIT_Directive_Try_Each_Argument) 2772 SUIT_Common_Commands //= (suit-directive-override-parameters, 2773 {+ SUIT_Parameters}) 2775 IndexArg /= uint 2776 IndexArg /= bool 2777 IndexArg /= [+uint] 2778 SUIT_Command_Sequence = [ + ( 2779 SUIT_Condition // SUIT_Directive // SUIT_Command_Custom 2780 ) ] 2782 SUIT_Command_Custom = (suit-command-custom, bstr/tstr/int/nil) 2783 SUIT_Condition //= (suit-condition-vendor-identifier, SUIT_Rep_Policy) 2784 SUIT_Condition //= (suit-condition-class-identifier, SUIT_Rep_Policy) 2785 SUIT_Condition //= (suit-condition-device-identifier, SUIT_Rep_Policy) 2786 SUIT_Condition //= (suit-condition-image-match, SUIT_Rep_Policy) 2787 SUIT_Condition //= (suit-condition-component-slot, SUIT_Rep_Policy) 2788 SUIT_Condition //= (suit-condition-abort, SUIT_Rep_Policy) 2790 SUIT_Directive //= (suit-directive-set-component-index, IndexArg) 2791 SUIT_Directive //= (suit-directive-run-sequence, 2792 bstr .cbor SUIT_Command_Sequence) 2793 SUIT_Directive //= (suit-directive-try-each, 2794 SUIT_Directive_Try_Each_Argument) 2795 SUIT_Directive //= (suit-directive-process-dependency, SUIT_Rep_Policy) 2796 SUIT_Directive //= (suit-directive-override-parameters, 2797 {+ SUIT_Parameters}) 2798 SUIT_Directive //= (suit-directive-fetch, SUIT_Rep_Policy) 2799 SUIT_Directive //= (suit-directive-copy, SUIT_Rep_Policy) 2800 SUIT_Directive //= (suit-directive-swap, SUIT_Rep_Policy) 2801 SUIT_Directive //= (suit-directive-run, SUIT_Rep_Policy) 2803 SUIT_Directive_Try_Each_Argument = [ 2804 2* bstr .cbor SUIT_Command_Sequence, 2805 ?nil 2806 ] 2808 SUIT_Rep_Policy = uint .bits suit-reporting-bits 2810 suit-reporting-bits = &( 2811 suit-send-record-success : 0, 2812 suit-send-record-failure : 1, 2813 suit-send-sysinfo-success : 2, 2814 suit-send-sysinfo-failure : 3 2815 ) 2817 SUIT_Parameters //= (suit-parameter-vendor-identifier => 2818 (RFC4122_UUID / cbor-pen)) 2819 cbor-pen = #6.112(bstr) 2821 SUIT_Parameters //= (suit-parameter-class-identifier => RFC4122_UUID) 2822 SUIT_Parameters //= (suit-parameter-image-digest 2823 => bstr .cbor SUIT_Digest) 2824 SUIT_Parameters //= (suit-parameter-image-size => uint) 2825 SUIT_Parameters //= (suit-parameter-component-slot => uint) 2826 SUIT_Parameters //= (suit-parameter-uri => tstr) 2827 SUIT_Parameters //= (suit-parameter-source-component => uint) 2828 SUIT_Parameters //= (suit-parameter-run-args => bstr) 2830 SUIT_Parameters //= (suit-parameter-device-identifier => RFC4122_UUID) 2832 SUIT_Parameters //= (suit-parameter-custom => int/bool/tstr/bstr) 2834 SUIT_Parameters //= (suit-parameter-strict-order => bool) 2835 SUIT_Parameters //= (suit-parameter-soft-failure => bool) 2837 RFC4122_UUID = bstr .size 16 2839 SUIT_Text_Map = { 2840 SUIT_Text_Keys, 2841 * SUIT_Component_Identifier => { 2842 SUIT_Text_Component_Keys 2843 } 2844 } 2846 SUIT_Text_Component_Keys = ( 2847 ? suit-text-vendor-name => tstr, 2848 ? suit-text-model-name => tstr, 2849 ? suit-text-vendor-domain => tstr, 2850 ? suit-text-model-info => tstr, 2851 ? suit-text-component-description => tstr, 2852 ? suit-text-component-version => tstr, 2853 * $$suit-text-component-key-extensions 2854 ) 2856 SUIT_Text_Keys = ( 2857 ? suit-text-manifest-description => tstr, 2858 ? suit-text-update-description => tstr, 2859 ? suit-text-manifest-json-source => tstr, 2860 ? suit-text-manifest-yaml-source => tstr, 2861 * $$suit-text-key-extensions 2862 ) 2864 suit-authentication-wrapper = 2 2865 suit-manifest = 3 2867 ;REQUIRED to implement: 2868 cose-alg-sha-256 = -16 2870 ;OPTIONAL to implement: 2871 cose-alg-shake128 = -18 2872 cose-alg-sha-384 = -43 2873 cose-alg-sha-512 = -44 2874 cose-alg-shake256 = -45 2876 suit-manifest-version = 1 2877 suit-manifest-sequence-number = 2 2878 suit-common = 3 2879 suit-reference-uri = 4 2880 suit-payload-fetch = 8 2881 suit-install = 9 2882 suit-validate = 10 2883 suit-load = 11 2884 suit-run = 12 2885 suit-text = 13 2887 suit-components = 2 2888 suit-common-sequence = 4 2890 suit-command-custom = nint 2892 suit-condition-vendor-identifier = 1 2893 suit-condition-class-identifier = 2 2894 suit-condition-image-match = 3 2895 suit-condition-component-slot = 5 2897 suit-condition-abort = 14 2898 suit-condition-device-identifier = 24 2900 suit-directive-set-component-index = 12 2901 suit-directive-try-each = 15 2902 suit-directive-override-parameters = 20 2903 suit-directive-fetch = 21 2904 suit-directive-copy = 22 2905 suit-directive-run = 23 2907 suit-directive-swap = 31 2908 suit-directive-run-sequence = 32 2910 suit-parameter-vendor-identifier = 1 2911 suit-parameter-class-identifier = 2 2912 suit-parameter-image-digest = 3 2913 suit-parameter-component-slot = 5 2915 suit-parameter-strict-order = 12 2916 suit-parameter-soft-failure = 13 2917 suit-parameter-image-size = 14 2919 suit-parameter-uri = 21 2920 suit-parameter-source-component = 22 2921 suit-parameter-run-args = 23 2922 suit-parameter-device-identifier = 24 2924 suit-parameter-custom = nint 2926 suit-text-manifest-description = 1 2927 suit-text-update-description = 2 2928 suit-text-manifest-json-source = 3 2929 suit-text-manifest-yaml-source = 4 2931 suit-text-vendor-name = 1 2932 suit-text-model-name = 2 2933 suit-text-vendor-domain = 3 2934 suit-text-model-info = 4 2935 suit-text-component-description = 5 2936 suit-text-component-version = 6 2938 Appendix B. B. Examples 2940 The following examples demonstrate a small subset of the 2941 functionality of the manifest. Even a simple manifest processor can 2942 execute most of these manifests. 2944 The examples are signed using the following ECDSA secp256r1 key: 2946 -----BEGIN PRIVATE KEY----- 2947 MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgApZYjZCUGLM50VBC 2948 CjYStX+09jGmnyJPrpDLTz/hiXOhRANCAASEloEarguqq9JhVxie7NomvqqL8Rtv 2949 P+bitWWchdvArTsfKktsCYExwKNtrNHXi9OB3N+wnAUtszmR23M4tKiW 2950 -----END PRIVATE KEY----- 2952 The corresponding public key can be used to verify these examples: 2954 -----BEGIN PUBLIC KEY----- 2955 MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEhJaBGq4LqqvSYVcYnuzaJr6qi/Eb 2956 bz/m4rVlnIXbwK07HypLbAmBMcCjbazR14vTgdzfsJwFLbM5kdtzOLSolg== 2957 -----END PUBLIC KEY----- 2959 Each example uses SHA256 as the digest function. 2961 Note that reporting policies are declared for each non-flow-control 2962 command in these examples. The reporting policies used in the 2963 examples are described in the following tables. 2965 +=============================+==========+ 2966 | Policy | Label | 2967 +=============================+==========+ 2968 | suit-send-record-on-success | Rec-Pass | 2969 +-----------------------------+----------+ 2970 | suit-send-record-on-failure | Rec-Fail | 2971 +-----------------------------+----------+ 2972 | suit-send-sysinfo-success | Sys-Pass | 2973 +-----------------------------+----------+ 2974 | suit-send-sysinfo-failure | Sys-Fail | 2975 +-----------------------------+----------+ 2977 Table 12 2979 +===================+==========+==========+==========+==========+ 2980 | Command | Sys-Fail | Sys-Pass | Rec-Fail | Rec-Pass | 2981 +===================+==========+==========+==========+==========+ 2982 | suit-condition- | 1 | 1 | 1 | 1 | 2983 | vendor-identifier | | | | | 2984 +-------------------+----------+----------+----------+----------+ 2985 | suit-condition- | 1 | 1 | 1 | 1 | 2986 | class-identifier | | | | | 2987 +-------------------+----------+----------+----------+----------+ 2988 | suit-condition- | 1 | 1 | 1 | 1 | 2989 | image-match | | | | | 2990 +-------------------+----------+----------+----------+----------+ 2991 | suit-condition- | 0 | 1 | 0 | 1 | 2992 | component-slot | | | | | 2993 +-------------------+----------+----------+----------+----------+ 2994 | suit-directive- | 0 | 0 | 1 | 0 | 2995 | fetch | | | | | 2996 +-------------------+----------+----------+----------+----------+ 2997 | suit-directive- | 0 | 0 | 1 | 0 | 2998 | copy | | | | | 2999 +-------------------+----------+----------+----------+----------+ 3000 | suit-directive- | 0 | 0 | 1 | 0 | 3001 | run | | | | | 3002 +-------------------+----------+----------+----------+----------+ 3004 Table 13 3006 B.1. Example 0: Secure Boot 3008 This example covers the following templates: 3010 * Compatibility Check (Section 7.1) 3012 * Secure Boot (Section 7.2) 3013 It also serves as the minimum example. 3015 107({ 3016 / authentication-wrapper / 2:<<[ 3017 digest: <<[ 3018 / algorithm-id / -16 / "sha256" /, 3019 / digest-bytes / 3020 h'a6c4590ac53043a98e8c4106e1e31b305516d7cf0a655eddfac6d45c810e036a' 3021 ]>>, 3022 signature: <<18([ 3023 / protected / <<{ 3024 / alg / 1:-7 / "ES256" /, 3025 }>>, 3026 / unprotected / { 3027 }, 3028 / payload / F6 / nil /, 3029 / signature / h'd11a2dd9610fb62a707335f58407922570 3030 9f96e8117e7eeed98a2f207d05c8ecfba1755208f6abea977b8a6efe3bc2ca3215e119 3031 3be201467d052b42db6b7287' 3032 ])>> 3033 ] 3034 ]>>, 3035 / manifest / 3:<<{ 3036 / manifest-version / 1:1, 3037 / manifest-sequence-number / 2:0, 3038 / common / 3:<<{ 3039 / components / 2:[ 3040 [h'00'] 3041 ], 3042 / common-sequence / 4:<<[ 3043 / directive-override-parameters / 20,{ 3044 / vendor-id / 3045 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 3046 be9d-e663e4d41ffe /, 3047 / class-id / 3048 2:h'1492af1425695e48bf429b2d51f2ab45' / 3049 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 3050 / image-digest / 3:<<[ 3051 / algorithm-id / -16 / "sha256" /, 3052 / digest-bytes / 3053 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 3054 ]>>, 3055 / image-size / 14:34768, 3056 } , 3057 / condition-vendor-identifier / 1,15 , 3058 / condition-class-identifier / 2,15 3059 ]>>, 3060 }>>, 3061 / validate / 10:<<[ 3062 / condition-image-match / 3,15 3063 ]>>, 3064 / run / 12:<<[ 3065 / directive-run / 23,2 3066 ]>>, 3067 }>>, 3068 }) 3070 Total size of Envelope without COSE authentication object: 161 3072 Envelope: 3074 d86ba2025827815824822f5820a6c4590ac53043a98e8c4106e1e31b3055 3075 16d7cf0a655eddfac6d45c810e036a035871a50101020003585fa2028181 3076 41000458568614a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492 3077 af1425695e48bf429b2d51f2ab45035824822f5820001122334455667788 3078 99aabbccddeeff0123456789abcdeffedcba98765432100e1987d0010f02 3079 0f0a4382030f0c43821702 3081 Total size of Envelope with COSE authentication object: 237 3083 Envelope with COSE authentication object: 3085 d86ba2025873825824822f5820a6c4590ac53043a98e8c4106e1e31b3055 3086 16d7cf0a655eddfac6d45c810e036a584ad28443a10126a0f65840d11a2d 3087 d9610fb62a707335f584079225709f96e8117e7eeed98a2f207d05c8ecfb 3088 a1755208f6abea977b8a6efe3bc2ca3215e1193be201467d052b42db6b72 3089 87035871a50101020003585fa202818141000458568614a40150fa6b4a53 3090 d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab45 3091 035824822f582000112233445566778899aabbccddeeff0123456789abcd 3092 effedcba98765432100e1987d0010f020f0a4382030f0c43821702 3094 B.2. Example 1: Simultaneous Download and Installation of Payload 3096 This example covers the following templates: 3098 * Compatibility Check (Section 7.1) 3100 * Firmware Download (Section 7.3) 3102 Simultaneous download and installation of payload. No secure boot is 3103 present in this example to demonstrate a download-only manifest. 3105 107({ 3106 / authentication-wrapper / 2:<<[ 3107 digest: <<[ 3108 / algorithm-id / -16 / "sha256" /, 3109 / digest-bytes / 3110 h'60c61d6eb7a1aaeddc49ce8157a55cff0821537eeee77a4ded44155b03045132' 3111 ]>>, 3112 signature: <<18([ 3113 / protected / <<{ 3114 / alg / 1:-7 / "ES256" /, 3115 }>>, 3116 / unprotected / { 3117 }, 3118 / payload / F6 / nil /, 3119 / signature / h'5249dacaf0ffc8326931b09586eb7e3769 3120 e71a0e6a40ad8153db4980db9b05bd1742ddb46085fa11e62b65a79895c12ac7abe266 3121 8ccc5afdd74466aed7bca389' 3122 ])>> 3123 ] 3124 ]>>, 3125 / manifest / 3:<<{ 3126 / manifest-version / 1:1, 3127 / manifest-sequence-number / 2:1, 3128 / common / 3:<<{ 3129 / components / 2:[ 3130 [h'00'] 3131 ], 3132 / common-sequence / 4:<<[ 3133 / directive-override-parameters / 20,{ 3134 / vendor-id / 3135 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 3136 be9d-e663e4d41ffe /, 3137 / class-id / 3138 2:h'1492af1425695e48bf429b2d51f2ab45' / 3139 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 3140 / image-digest / 3:<<[ 3141 / algorithm-id / -16 / "sha256" /, 3142 / digest-bytes / 3143 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 3144 ]>>, 3145 / image-size / 14:34768, 3146 } , 3147 / condition-vendor-identifier / 1,15 , 3148 / condition-class-identifier / 2,15 3149 ]>>, 3150 }>>, 3151 / install / 9:<<[ 3152 / directive-set-parameters / 19,{ 3153 / uri / 21:'http://example.com/file.bin', 3154 } , 3155 / directive-fetch / 21,2 , 3156 / condition-image-match / 3,15 3157 ]>>, 3158 / validate / 10:<<[ 3159 / condition-image-match / 3,15 3160 ]>>, 3161 }>>, 3162 }) 3164 Total size of Envelope without COSE authentication object: 196 3166 Envelope: 3168 d86ba2025827815824822f582060c61d6eb7a1aaeddc49ce8157a55cff08 3169 21537eeee77a4ded44155b03045132035894a50101020103585fa2028181 3170 41000458568614a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492 3171 af1425695e48bf429b2d51f2ab45035824822f5820001122334455667788 3172 99aabbccddeeff0123456789abcdeffedcba98765432100e1987d0010f02 3173 0f0958258613a115781b687474703a2f2f6578616d706c652e636f6d2f66 3174 696c652e62696e1502030f0a4382030f 3176 Total size of Envelope with COSE authentication object: 272 3178 Envelope with COSE authentication object: 3180 d86ba2025873825824822f582060c61d6eb7a1aaeddc49ce8157a55cff08 3181 21537eeee77a4ded44155b03045132584ad28443a10126a0f658405249da 3182 caf0ffc8326931b09586eb7e3769e71a0e6a40ad8153db4980db9b05bd17 3183 42ddb46085fa11e62b65a79895c12ac7abe2668ccc5afdd74466aed7bca3 3184 89035894a50101020103585fa202818141000458568614a40150fa6b4a53 3185 d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab45 3186 035824822f582000112233445566778899aabbccddeeff0123456789abcd 3187 effedcba98765432100e1987d0010f020f0958258613a115781b68747470 3188 3a2f2f6578616d706c652e636f6d2f66696c652e62696e1502030f0a4382 3189 030f 3191 B.3. Example 2: Simultaneous Download, Installation, Secure Boot, 3192 Severed Fields 3194 This example covers the following templates: 3196 * Compatibility Check (Section 7.1) 3198 * Secure Boot (Section 7.2) 3200 * Firmware Download (Section 7.3) 3201 This example also demonstrates severable elements (Section 5.4), and 3202 text (Section 8.4.4). 3204 107({ 3205 / authentication-wrapper / 2:<<[ 3206 digest: <<[ 3207 / algorithm-id / -16 / "sha256" /, 3208 / digest-bytes / 3209 h'e45dcdb2074b951f1c88b866469939c2a83ed433a31fc7dfcb3f63955bd943ec' 3210 ]>>, 3211 signature: <<18([ 3212 / protected / <<{ 3213 / alg / 1:-7 / "ES256" /, 3214 }>>, 3215 / unprotected / { 3216 }, 3217 / payload / F6 / nil /, 3218 / signature / h'b4fd3a6a18fe1062573488cf24ac96ef9f 3219 30ac746696e50be96533b356b8156e4332587fe6f4e8743ae525d72005fddd4c1213d5 3220 5a8061b2ce67b83640f4777c' 3221 ])>> 3222 ] 3223 ]>>, 3224 / manifest / 3:<<{ 3225 / manifest-version / 1:1, 3226 / manifest-sequence-number / 2:2, 3227 / common / 3:<<{ 3228 / components / 2:[ 3229 [h'00'] 3230 ], 3231 / common-sequence / 4:<<[ 3232 / directive-override-parameters / 20,{ 3233 / vendor-id / 3234 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 3235 be9d-e663e4d41ffe /, 3236 / class-id / 3237 2:h'1492af1425695e48bf429b2d51f2ab45' / 3238 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 3239 / image-digest / 3:<<[ 3240 / algorithm-id / -16 / "sha256" /, 3241 / digest-bytes / 3242 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 3243 ]>>, 3244 / image-size / 14:34768, 3245 } , 3246 / condition-vendor-identifier / 1,15 , 3247 / condition-class-identifier / 2,15 3248 ]>>, 3250 }>>, 3251 / install / 9:[ 3252 / algorithm-id / -16 / "sha256" /, 3253 / digest-bytes / 3254 h'3ee96dc79641970ae46b929ccf0b72ba9536dd846020dbdc9f949d84ea0e18d2' 3255 ], 3256 / validate / 10:<<[ 3257 / condition-image-match / 3,15 3258 ]>>, 3259 / run / 12:<<[ 3260 / directive-run / 23,2 3261 ]>>, 3262 / text / 13:[ 3263 / algorithm-id / -16 / "sha256" /, 3264 / digest-bytes / 3265 h'2bfc4d0cc6680be7dd9f5ca30aa2bb5d1998145de33d54101b80e2ca49faf918' 3266 ], 3267 }>>, 3268 / install / 9:<<[ 3269 / directive-set-parameters / 19,{ 3270 / uri / 3271 21:'http://example.com/very/long/path/to/file/file.bin', 3272 } , 3273 / directive-fetch / 21,2 , 3274 / condition-image-match / 3,15 3275 ]>>, 3276 / text / 13:<<{ 3277 [h'00']:{ 3278 / vendor-domain / 3:'arm.com', 3279 / component-description / 5:'This component is a 3280 demonstration. The digest is a sample pattern, not a real one.', 3281 } 3282 }>>, 3283 }) 3285 Total size of the Envelope without COSE authentication object or 3286 Severable Elements: 235 3288 Envelope: 3290 d86ba2025827815824822f5820e45dcdb2074b951f1c88b866469939c2a8 3291 3ed433a31fc7dfcb3f63955bd943ec0358bba70101020203585fa2028181 3292 41000458568614a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492 3293 af1425695e48bf429b2d51f2ab45035824822f5820001122334455667788 3294 99aabbccddeeff0123456789abcdeffedcba98765432100e1987d0010f02 3295 0f09822f58203ee96dc79641970ae46b929ccf0b72ba9536dd846020dbdc 3296 9f949d84ea0e18d20a4382030f0c438217020d822f58202bfc4d0cc6680b 3297 e7dd9f5ca30aa2bb5d1998145de33d54101b80e2ca49faf918 3298 Total size of the Envelope with COSE authentication object but 3299 without Severable Elements: 311 3301 Envelope: 3303 d86ba2025873825824822f5820e45dcdb2074b951f1c88b866469939c2a8 3304 3ed433a31fc7dfcb3f63955bd943ec584ad28443a10126a0f65840b4fd3a 3305 6a18fe1062573488cf24ac96ef9f30ac746696e50be96533b356b8156e43 3306 32587fe6f4e8743ae525d72005fddd4c1213d55a8061b2ce67b83640f477 3307 7c0358bba70101020203585fa202818141000458568614a40150fa6b4a53 3308 d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab45 3309 035824822f582000112233445566778899aabbccddeeff0123456789abcd 3310 effedcba98765432100e1987d0010f020f09822f58203ee96dc79641970a 3311 e46b929ccf0b72ba9536dd846020dbdc9f949d84ea0e18d20a4382030f0c 3312 438217020d822f58202bfc4d0cc6680be7dd9f5ca30aa2bb5d1998145de3 3313 3d54101b80e2ca49faf918 3315 Total size of Envelope with COSE authentication object and Severable 3316 Elements: 894 3318 Envelope with COSE authentication object: 3320 d86ba4025873825824822f5820e45dcdb2074b951f1c88b866469939c2a8 3321 3ed433a31fc7dfcb3f63955bd943ec584ad28443a10126a0f65840b4fd3a 3322 6a18fe1062573488cf24ac96ef9f30ac746696e50be96533b356b8156e43 3323 32587fe6f4e8743ae525d72005fddd4c1213d55a8061b2ce67b83640f477 3324 7c0358bba70101020203585fa202818141000458568614a40150fa6b4a53 3325 d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab45 3326 035824822f582000112233445566778899aabbccddeeff0123456789abcd 3327 effedcba98765432100e1987d0010f020f09822f58203ee96dc79641970a 3328 e46b929ccf0b72ba9536dd846020dbdc9f949d84ea0e18d20a4382030f0c 3329 438217020d822f58202bfc4d0cc6680be7dd9f5ca30aa2bb5d1998145de3 3330 3d54101b80e2ca49faf91809583c8613a1157832687474703a2f2f657861 3331 6d706c652e636f6d2f766572792f6c6f6e672f706174682f746f2f66696c 3332 652f66696c652e62696e1502030f0d590204a20179019d2323204578616d 3333 706c6520323a2053696d756c74616e656f757320446f776e6c6f61642c20 3334 496e7374616c6c6174696f6e2c2053656375726520426f6f742c20536576 3335 65726564204669656c64730a0a2020202054686973206578616d706c6520 3336 636f766572732074686520666f6c6c6f77696e672074656d706c61746573 3337 3a0a202020200a202020202a20436f6d7061746962696c69747920436865 3338 636b20287b7b74656d706c6174652d636f6d7061746962696c6974792d63 3339 6865636b7d7d290a202020202a2053656375726520426f6f7420287b7b74 3340 656d706c6174652d7365637572652d626f6f747d7d290a202020202a2046 3341 69726d7761726520446f776e6c6f616420287b7b6669726d776172652d64 3342 6f776e6c6f61642d74656d706c6174657d7d290a202020200a2020202054 3343 686973206578616d706c6520616c736f2064656d6f6e7374726174657320 3344 736576657261626c6520656c656d656e747320287b7b6f76722d73657665 3345 7261626c657d7d292c20616e64207465787420287b7b6d616e6966657374 3346 2d6469676573742d746578747d7d292e814100a2036761726d2e636f6d05 3347 78525468697320636f6d706f6e656e7420697320612064656d6f6e737472 3348 6174696f6e2e205468652064696765737420697320612073616d706c6520 3349 7061747465726e2c206e6f742061207265616c206f6e652e 3351 B.4. Example 3: A/B images 3353 This example covers the following templates: 3355 * Compatibility Check (Section 7.1) 3357 * Secure Boot (Section 7.2) 3359 * Firmware Download (Section 7.3) 3361 * A/B Image Template (Section 7.7) 3363 107({ 3364 / authentication-wrapper / 2:<<[ 3365 digest: <<[ 3366 / algorithm-id / -16 / "sha256" /, 3367 / digest-bytes / 3368 h'7c9b3cb72c262608a42f944d59d659ff2b801c78af44def51b8ff51e9f45721b' 3369 ]>>, 3370 signature: <<18([ 3371 / protected / <<{ 3372 / alg / 1:-7 / "ES256" /, 3373 }>>, 3374 / unprotected / { 3375 }, 3376 / payload / F6 / nil /, 3377 / signature / h'e33d618df0ad21e609529ab1a876afb231 3378 faff1d6a3189b5360324c2794250b87cf00cf83be50ea17dc721ca85393cd8e839a066 3379 d5dec0ad87a903ab31ea9afa' 3380 ])>> 3381 ] 3382 ]>>, 3383 / manifest / 3:<<{ 3384 / manifest-version / 1:1, 3385 / manifest-sequence-number / 2:3, 3386 / common / 3:<<{ 3387 / components / 2:[ 3388 [h'00'] 3389 ], 3390 / common-sequence / 4:<<[ 3391 / directive-override-parameters / 20,{ 3392 / vendor-id / 3393 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 3394 be9d-e663e4d41ffe /, 3395 / class-id / 3396 2:h'1492af1425695e48bf429b2d51f2ab45' / 3397 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 3398 } , 3399 / directive-try-each / 15,[ 3400 <<[ 3401 / directive-override-parameters / 20,{ 3402 / offset / 5:33792, 3403 } , 3404 / condition-component-offset / 5,5 , 3405 / directive-override-parameters / 20,{ 3406 / image-digest / 3:<<[ 3407 / algorithm-id / -16 / "sha256" /, 3408 / digest-bytes / 3409 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 3410 ]>>, 3411 / image-size / 14:34768, 3412 } 3413 ]>> , 3414 <<[ 3415 / directive-override-parameters / 20,{ 3416 / offset / 5:541696, 3417 } , 3418 / condition-component-offset / 5,5 , 3419 / directive-override-parameters / 20,{ 3420 / image-digest / 3:<<[ 3421 / algorithm-id / -16 / "sha256" /, 3422 / digest-bytes / 3423 h'0123456789abcdeffedcba987654321000112233445566778899aabbccddeeff' 3424 ]>>, 3425 / image-size / 14:76834, 3426 } 3427 ]>> 3428 ] , 3429 / condition-vendor-identifier / 1,15 , 3430 / condition-class-identifier / 2,15 3431 ]>>, 3432 }>>, 3433 / install / 9:<<[ 3434 / directive-try-each / 15,[ 3435 <<[ 3436 / directive-set-parameters / 19,{ 3437 / offset / 5:33792, 3438 } , 3439 / condition-component-offset / 5,5 , 3440 / directive-set-parameters / 19,{ 3441 / uri / 21:'http://example.com/file1.bin', 3442 } 3443 ]>> , 3444 <<[ 3445 / directive-set-parameters / 19,{ 3446 / offset / 5:541696, 3447 } , 3448 / condition-component-offset / 5,5 , 3449 / directive-set-parameters / 19,{ 3450 / uri / 21:'http://example.com/file2.bin', 3451 } 3452 ]>> 3453 ] , 3454 / directive-fetch / 21,2 , 3455 / condition-image-match / 3,15 3456 ]>>, 3457 / validate / 10:<<[ 3458 / condition-image-match / 3,15 3460 ]>>, 3461 }>>, 3462 }) 3464 Total size of Envelope without COSE authentication object: 332 3466 Envelope: 3468 d86ba2025827815824822f58207c9b3cb72c262608a42f944d59d659ff2b 3469 801c78af44def51b8ff51e9f45721b0359011ba5010102030358aaa20281 3470 8141000458a18814a20150fa6b4a53d5ad5fdfbe9de663e4d41ffe025014 3471 92af1425695e48bf429b2d51f2ab450f8258368614a105198400050514a2 3472 035824822f582000112233445566778899aabbccddeeff0123456789abcd 3473 effedcba98765432100e1987d0583a8614a1051a00084400050514a20358 3474 24822f58200123456789abcdeffedcba9876543210001122334455667788 3475 99aabbccddeeff0e1a00012c22010f020f095861860f82582a8613a10519 3476 8400050513a115781c687474703a2f2f6578616d706c652e636f6d2f6669 3477 6c65312e62696e582c8613a1051a00084400050513a115781c687474703a 3478 2f2f6578616d706c652e636f6d2f66696c65322e62696e1502030f0a4382 3479 030f 3481 Total size of Envelope with COSE authentication object: 408 3483 Envelope with COSE authentication object: 3485 d86ba2025873825824822f58207c9b3cb72c262608a42f944d59d659ff2b 3486 801c78af44def51b8ff51e9f45721b584ad28443a10126a0f65840e33d61 3487 8df0ad21e609529ab1a876afb231faff1d6a3189b5360324c2794250b87c 3488 f00cf83be50ea17dc721ca85393cd8e839a066d5dec0ad87a903ab31ea9a 3489 fa0359011ba5010102030358aaa202818141000458a18814a20150fa6b4a 3490 53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab 3491 450f8258368614a105198400050514a2035824822f582000112233445566 3492 778899aabbccddeeff0123456789abcdeffedcba98765432100e1987d058 3493 3a8614a1051a00084400050514a2035824822f58200123456789abcdeffe 3494 dcba987654321000112233445566778899aabbccddeeff0e1a00012c2201 3495 0f020f095861860f82582a8613a105198400050513a115781c687474703a 3496 2f2f6578616d706c652e636f6d2f66696c65312e62696e582c8613a1051a 3497 00084400050513a115781c687474703a2f2f6578616d706c652e636f6d2f 3498 66696c65322e62696e1502030f0a4382030f 3500 B.5. Example 4: Load from External Storage 3502 This example covers the following templates: 3504 * Compatibility Check (Section 7.1) 3506 * Secure Boot (Section 7.2) 3507 * Firmware Download (Section 7.3) 3509 * Install (Section 7.4) 3511 * Load (Section 7.6) 3513 107({ 3514 / authentication-wrapper / 2:<<[ 3515 digest: <<[ 3516 / algorithm-id / -16 / "sha256" /, 3517 / digest-bytes / 3518 h'15736702a00f510805dcf89d6913a2cfb417ed414faa760f974d6755c68ba70a' 3519 ]>>, 3520 signature: <<18([ 3521 / protected / <<{ 3522 / alg / 1:-7 / "ES256" /, 3523 }>>, 3524 / unprotected / { 3525 }, 3526 / payload / F6 / nil /, 3527 / signature / h'3ada2532326d512132c388677798c24ffd 3528 cc979bfae2a26b19c8c8bbf511fd7dd85f1501662c1a9e1976b759c4019bab44ba5434 3529 efb45d3868aedbca593671f3' 3530 ])>> 3531 ] 3532 ]>>, 3533 / manifest / 3:<<{ 3534 / manifest-version / 1:1, 3535 / manifest-sequence-number / 2:4, 3536 / common / 3:<<{ 3537 / components / 2:[ 3538 [h'00'] , 3539 [h'02'] , 3540 [h'01'] 3541 ], 3542 / common-sequence / 4:<<[ 3543 / directive-set-component-index / 12,0 , 3544 / directive-override-parameters / 20,{ 3545 / vendor-id / 3546 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 3547 be9d-e663e4d41ffe /, 3548 / class-id / 3549 2:h'1492af1425695e48bf429b2d51f2ab45' / 3550 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 3551 / image-digest / 3:<<[ 3552 / algorithm-id / -16 / "sha256" /, 3553 / digest-bytes / 3554 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 3555 ]>>, 3556 / image-size / 14:34768, 3557 } , 3558 / condition-vendor-identifier / 1,15 , 3559 / condition-class-identifier / 2,15 3560 ]>>, 3561 }>>, 3562 / payload-fetch / 8:<<[ 3563 / directive-set-component-index / 12,1 , 3564 / directive-set-parameters / 19,{ 3565 / uri / 21:'http://example.com/file.bin', 3566 } , 3567 / directive-fetch / 21,2 , 3568 / condition-image-match / 3,15 3569 ]>>, 3570 / install / 9:<<[ 3571 / directive-set-component-index / 12,0 , 3572 / directive-set-parameters / 19,{ 3573 / source-component / 22:1 / [h'02'] /, 3574 } , 3575 / directive-copy / 22,2 , 3576 / condition-image-match / 3,15 3577 ]>>, 3578 / validate / 10:<<[ 3579 / directive-set-component-index / 12,0 , 3580 / condition-image-match / 3,15 3581 ]>>, 3582 / load / 11:<<[ 3583 / directive-set-component-index / 12,2 , 3584 / directive-set-parameters / 19,{ 3585 / image-digest / 3:<<[ 3586 / algorithm-id / -16 / "sha256" /, 3587 / digest-bytes / 3588 h'0123456789abcdeffedcba987654321000112233445566778899aabbccddeeff' 3589 ]>>, 3590 / image-size / 14:76834, 3591 / source-component / 22:0 / [h'00'] /, 3592 / compression-info / 19:<<{ 3593 / compression-algorithm / 1:1 / "gzip" /, 3594 }>>, 3595 } , 3596 / directive-copy / 22,2 , 3597 / condition-image-match / 3,15 3598 ]>>, 3599 / run / 12:<<[ 3600 / directive-set-component-index / 12,2 , 3601 / directive-run / 23,2 3602 ]>>, 3604 }>>, 3605 }) 3607 Total size of Envelope without COSE authentication object: 292 3609 Envelope: 3611 d86ba2025827815824822f582015736702a00f510805dcf89d6913a2cfb4 3612 17ed414faa760f974d6755c68ba70a0358f4a801010204035867a2028381 3613 4100814102814101045858880c0014a40150fa6b4a53d5ad5fdfbe9de663 3614 e4d41ffe02501492af1425695e48bf429b2d51f2ab45035824822f582000 3615 112233445566778899aabbccddeeff0123456789abcdeffedcba98765432 3616 100e1987d0010f020f085827880c0113a115781b687474703a2f2f657861 3617 6d706c652e636f6d2f66696c652e62696e1502030f094b880c0013a11601 3618 1602030f0a45840c00030f0b583d880c0213a4035824822f582001234567 3619 89abcdeffedcba987654321000112233445566778899aabbccddeeff0e1a 3620 00012c221343a1010116001602030f0c45840c021702 3622 Total size of Envelope with COSE authentication object: 368 3624 Envelope with COSE authentication object: 3626 d86ba2025873825824822f582015736702a00f510805dcf89d6913a2cfb4 3627 17ed414faa760f974d6755c68ba70a584ad28443a10126a0f658403ada25 3628 32326d512132c388677798c24ffdcc979bfae2a26b19c8c8bbf511fd7dd8 3629 5f1501662c1a9e1976b759c4019bab44ba5434efb45d3868aedbca593671 3630 f30358f4a801010204035867a20283814100814102814101045858880c00 3631 14a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48 3632 bf429b2d51f2ab45035824822f582000112233445566778899aabbccddee 3633 ff0123456789abcdeffedcba98765432100e1987d0010f020f085827880c 3634 0113a115781b687474703a2f2f6578616d706c652e636f6d2f66696c652e 3635 62696e1502030f094b880c0013a116011602030f0a45840c00030f0b583d 3636 880c0213a4035824822f58200123456789abcdeffedcba98765432100011 3637 2233445566778899aabbccddeeff0e1a00012c221343a101011600160203 3638 0f0c45840c021702 3640 B.6. Example 5: Two Images 3642 This example covers the following templates: 3644 * Compatibility Check (Section 7.1) 3646 * Secure Boot (Section 7.2) 3648 * Firmware Download (Section 7.3) 3650 Furthermore, it shows using these templates with two images. 3652 107({ 3653 / authentication-wrapper / 2:<<[ 3654 digest: <<[ 3655 / algorithm-id / -16 / "sha256" /, 3656 / digest-bytes / 3657 h'd1e73f16e4126007bc4d804cd33b0209fbab34728e60ee8c00f3387126748dd2' 3658 ]>>, 3659 signature: <<18([ 3660 / protected / <<{ 3661 / alg / 1:-7 / "ES256" /, 3662 }>>, 3663 / unprotected / { 3664 }, 3665 / payload / F6 / nil /, 3666 / signature / h'b7ae0a46a28f02e25cda6d9a255bbaf863 3667 30141831fae5a78012d648bc6cee55102e0f1890bdeacc3adaa4fae0560f83a45eecae 3668 65cabce642f56d84ab97ef8d' 3669 ])>> 3670 ] 3671 ]>>, 3672 / manifest / 3:<<{ 3673 / manifest-version / 1:1, 3674 / manifest-sequence-number / 2:5, 3675 / common / 3:<<{ 3676 / components / 2:[ 3677 [h'00'] , 3678 [h'01'] 3679 ], 3680 / common-sequence / 4:<<[ 3681 / directive-set-component-index / 12,0 , 3682 / directive-override-parameters / 20,{ 3683 / vendor-id / 3684 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 3685 be9d-e663e4d41ffe /, 3686 / class-id / 3687 2:h'1492af1425695e48bf429b2d51f2ab45' / 3688 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 3689 / image-digest / 3:<<[ 3690 / algorithm-id / -16 / "sha256" /, 3691 / digest-bytes / 3692 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 3693 ]>>, 3694 / image-size / 14:34768, 3695 } , 3696 / condition-vendor-identifier / 1,15 , 3697 / condition-class-identifier / 2,15 , 3698 / directive-set-component-index / 12,1 , 3699 / directive-override-parameters / 20,{ 3700 / image-digest / 3:<<[ 3701 / algorithm-id / -16 / "sha256" /, 3702 / digest-bytes / 3703 h'0123456789abcdeffedcba987654321000112233445566778899aabbccddeeff' 3704 ]>>, 3705 / image-size / 14:76834, 3706 } 3707 ]>>, 3708 }>>, 3709 / install / 9:<<[ 3710 / directive-set-component-index / 12,0 , 3711 / directive-set-parameters / 19,{ 3712 / uri / 21:'http://example.com/file1.bin', 3713 } , 3714 / directive-fetch / 21,2 , 3715 / condition-image-match / 3,15 , 3716 / directive-set-component-index / 12,1 , 3717 / directive-set-parameters / 19,{ 3718 / uri / 21:'http://example.com/file2.bin', 3719 } , 3720 / directive-fetch / 21,2 , 3721 / condition-image-match / 3,15 3722 ]>>, 3723 / validate / 10:<<[ 3724 / directive-set-component-index / 12,0 , 3725 / condition-image-match / 3,15 , 3726 / directive-set-component-index / 12,1 , 3727 / condition-image-match / 3,15 3728 ]>>, 3729 / run / 12:<<[ 3730 / directive-set-component-index / 12,0 , 3731 / directive-run / 23,2 3732 ]>>, 3733 }>>, 3734 }) 3736 Total size of Envelope without COSE authentication object: 306 3738 Envelope: 3740 d86ba2025827815824822f5820d1e73f16e4126007bc4d804cd33b0209fb 3741 ab34728e60ee8c00f3387126748dd203590101a601010205035895a20282 3742 8141008141010458898c0c0014a40150fa6b4a53d5ad5fdfbe9de663e4d4 3743 1ffe02501492af1425695e48bf429b2d51f2ab45035824822f5820001122 3744 33445566778899aabbccddeeff0123456789abcdeffedcba98765432100e 3745 1987d0010f020f0c0114a2035824822f58200123456789abcdeffedcba98 3746 7654321000112233445566778899aabbccddeeff0e1a00012c2209584f90 3747 0c0013a115781c687474703a2f2f6578616d706c652e636f6d2f66696c65 3748 312e62696e1502030f0c0113a115781c687474703a2f2f6578616d706c65 3749 2e636f6d2f66696c65322e62696e1502030f0a49880c00030f0c01030f0c 3750 45840c001702 3752 Total size of Envelope with COSE authentication object: 382 3754 Envelope with COSE authentication object: 3756 d86ba2025873825824822f5820d1e73f16e4126007bc4d804cd33b0209fb 3757 ab34728e60ee8c00f3387126748dd2584ad28443a10126a0f65840b7ae0a 3758 46a28f02e25cda6d9a255bbaf86330141831fae5a78012d648bc6cee5510 3759 2e0f1890bdeacc3adaa4fae0560f83a45eecae65cabce642f56d84ab97ef 3760 8d03590101a601010205035895a202828141008141010458898c0c0014a4 3761 0150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf42 3762 9b2d51f2ab45035824822f582000112233445566778899aabbccddeeff01 3763 23456789abcdeffedcba98765432100e1987d0010f020f0c0114a2035824 3764 822f58200123456789abcdeffedcba987654321000112233445566778899 3765 aabbccddeeff0e1a00012c2209584f900c0013a115781c687474703a2f2f 3766 6578616d706c652e636f6d2f66696c65312e62696e1502030f0c0113a115 3767 781c687474703a2f2f6578616d706c652e636f6d2f66696c65322e62696e 3768 1502030f0a49880c00030f0c01030f0c45840c001702 3770 Appendix C. C. Design Rational 3772 In order to provide flexible behavior to constrained devices, while 3773 still allowing more powerful devices to use their full capabilities, 3774 the SUIT manifest encodes the required behavior of a Recipient 3775 device. Behavior is encoded as a specialized byte code, contained in 3776 a CBOR list. This promotes a flat encoding, which simplifies the 3777 parser. The information encoded by this byte code closely matches 3778 the operations that a device will perform, which promotes ease of 3779 processing. The core operations used by most update and trusted 3780 invocation operations are represented in the byte code. The byte 3781 code can be extended by registering new operations. 3783 The specialized byte code approach gives benefits equivalent to those 3784 provided by a scripting language or conventional byte code, with two 3785 substantial differences. First, the language is extremely high 3786 level, consisting of only the operations that a device may perform 3787 during update and trusted invocation of a firmware image. Second, 3788 the language specifies linear behavior, without reverse branches. 3789 Conditional processing is supported, and parallel and out-of-order 3790 processing may be performed by sufficiently capable devices. 3792 By structuring the data in this way, the manifest processor becomes a 3793 very simple engine that uses a pull parser to interpret the manifest. 3794 This pull parser invokes a series of command handlers that evaluate a 3795 Condition or execute a Directive. Most data is structured in a 3796 highly regular pattern, which simplifies the parser. 3798 The results of this allow a Recipient to implement a very small 3799 parser for constrained applications. If needed, such a parser also 3800 allows the Recipient to perform complex updates with reduced 3801 overhead. Conditional execution of commands allows a simple device 3802 to perform important decisions at validation-time. 3804 Dependency handling is vastly simplified as well. Dependencies 3805 function like subroutines of the language. When a manifest has a 3806 dependency, it can invoke that dependency's commands and modify their 3807 behavior by setting parameters. Because some parameters come with 3808 security implications, the dependencies also have a mechanism to 3809 reject modifications to parameters on a fine-grained level. 3811 Developing a robust permissions system works in this model too. The 3812 Recipient can use a simple ACL that is a table of Identities and 3813 Component Identifier permissions to ensure that operations on 3814 components fail unless they are permitted by the ACL. This table can 3815 be further refined with individual parameters and commands. 3817 Capability reporting is similarly simplified. A Recipient can report 3818 the Commands, Parameters, Algorithms, and Component Identifiers that 3819 it supports. This is sufficiently precise for a manifest author to 3820 create a manifest that the Recipient can accept. 3822 The simplicity of design in the Recipient due to all of these 3823 benefits allows even a highly constrained platform to use advanced 3824 update capabilities. 3826 C.1. C.1 Design Rationale: Envelope 3828 The Envelope is used instead of a COSE structure for several reasons: 3830 1. This enables the use of Severable Elements (Section 8.5) 3832 2. This enables modular processing of manifests, particularly with 3833 large signatures. 3835 3. This enables multiple authentication schemes. 3837 4. This allows integrity verification by a dependent to be 3838 unaffected by adding or removing authentication structures. 3840 Modular processing is important because it allows a Manifest 3841 Processor to iterate forward over an Envelope, processing Delegation 3842 Chains and Authentication Blocks, retaining only intermediate values, 3843 without any need to seek forward and backwards in a stream until it 3844 gets to the Manifest itself. This allows the use of large, Post- 3845 Quantum signatures without requiring retention of the signature 3846 itself, or seeking forward and back. 3848 Four authentication objects are supported by the Envelope: 3850 * COSE_Sign_Tagged 3852 * COSE_Sign1_Tagged 3854 * COSE_Mac_Tagged 3856 * COSE_Mac0_Tagged 3858 The SUIT Envelope allows an Update Authority or intermediary to mix 3859 and match any number of different authentication blocks it wants 3860 without any concern for modifying the integrity of another 3861 authentication block. This also allows the addition or removal of an 3862 authentication blocks without changing the integrity check of the 3863 Manifest, which is important for dependency handling. See 3864 Section 6.2 3866 C.2. C.2 Byte String Wrappers 3868 Byte string wrappers are used in several places in the suit manifest. 3869 The primary reason for wrappers it to limit the parser extent when 3870 invoked at different times, with a possible loss of context. 3872 The elements of the suit envelope are wrapped both to set the extents 3873 used by the parser and to simplify integrity checks by clearly 3874 defining the length of each element. 3876 The common block is re-parsed in order to find components identifiers 3877 from their indices, to find dependency prefixes and digests from 3878 their identifiers, and to find the common sequence. The common 3879 sequence is wrapped so that it matches other sequences, simplifying 3880 the code path. 3882 A severed SUIT command sequence will appear in the envelope, so it 3883 must be wrapped as with all envelope elements. For consistency, 3884 command sequences are also wrapped in the manifest. This also allows 3885 the parser to discern the difference between a command sequence and a 3886 SUIT_Digest. 3888 Parameters that are structured types (arrays and maps) are also 3889 wrapped in a bstr. This is so that parser extents can be set 3890 correctly using only a reference to the beginning of the parameter. 3891 This enables a parser to store a simple list of references to 3892 parameters that can be retrieved when needed. 3894 Appendix D. D. Implementation Conformance Matrix 3896 This section summarizes the functionality a minimal manifest 3897 processor implementation needs to offer to claim conformance to this 3898 specification, in the absence of an application profile standard 3899 specifying otherwise. 3901 The subsequent table shows the conditions. 3903 +===================+=================+================+ 3904 | Name | Reference | Implementation | 3905 +===================+=================+================+ 3906 | Vendor Identifier | Section 8.4.8.2 | REQUIRED | 3907 +-------------------+-----------------+----------------+ 3908 | Class Identifier | Section 8.4.8.2 | REQUIRED | 3909 +-------------------+-----------------+----------------+ 3910 | Device Identifier | Section 8.4.8.2 | OPTIONAL | 3911 +-------------------+-----------------+----------------+ 3912 | Image Match | Section 8.4.9.2 | REQUIRED | 3913 +-------------------+-----------------+----------------+ 3914 | Component Slot | Section 8.4.9.3 | OPTIONAL | 3915 +-------------------+-----------------+----------------+ 3916 | Abort | Section 8.4.9.4 | OPTIONAL | 3917 +-------------------+-----------------+----------------+ 3918 | Custom Condition | Section 8.4.9.5 | OPTIONAL | 3919 +-------------------+-----------------+----------------+ 3921 Table 14 3923 The subsequent table shows the directives. 3925 +=====================+==================+====================+ 3926 | Name | Reference | Implementation | 3927 +=====================+==================+====================+ 3928 | Set Component Index | Section 8.4.10.1 | REQUIRED if more | 3929 | | | than one component | 3930 +---------------------+------------------+--------------------+ 3931 | Try Each | Section 8.4.10.2 | OPTIONAL | 3932 +---------------------+------------------+--------------------+ 3933 | Override Parameters | Section 8.4.10.3 | REQUIRED | 3934 +---------------------+------------------+--------------------+ 3935 | Fetch | Section 8.4.10.4 | REQUIRED for | 3936 | | | Updater | 3937 +---------------------+------------------+--------------------+ 3938 | Copy | Section 8.4.10.5 | OPTIONAL | 3939 +---------------------+------------------+--------------------+ 3940 | Run | Section 8.4.10.6 | REQUIRED for | 3941 | | | Bootloader | 3942 +---------------------+------------------+--------------------+ 3943 | Run Sequence | Section 8.4.10.7 | OPTIONAL | 3944 +---------------------+------------------+--------------------+ 3945 | Swap | Section 8.4.10.8 | OPTIONAL | 3946 +---------------------+------------------+--------------------+ 3948 Table 15 3950 The subsequent table shows the parameters. 3952 +==================+==================+======================+ 3953 | Name | Reference | Implementation | 3954 +==================+==================+======================+ 3955 | Vendor ID | Section 8.4.8.3 | REQUIRED | 3956 +------------------+------------------+----------------------+ 3957 | Class ID | Section 8.4.8.4 | REQUIRED | 3958 +------------------+------------------+----------------------+ 3959 | Image Digest | Section 8.4.8.6 | REQUIRED | 3960 +------------------+------------------+----------------------+ 3961 | Image Size | Section 8.4.8.7 | REQUIRED | 3962 +------------------+------------------+----------------------+ 3963 | Component Slot | Section 8.4.8.8 | OPTIONAL | 3964 +------------------+------------------+----------------------+ 3965 | URI | Section 8.4.8.9 | REQUIRED for Updater | 3966 +------------------+------------------+----------------------+ 3967 | Source Component | Section 8.4.8.10 | OPTIONAL | 3968 +------------------+------------------+----------------------+ 3969 | Run Args | Section 8.4.8.11 | OPTIONAL | 3970 +------------------+------------------+----------------------+ 3971 | Device ID | Section 8.4.8.5 | OPTIONAL | 3972 +------------------+------------------+----------------------+ 3973 | Strict Order | Section 8.4.8.13 | OPTIONAL | 3974 +------------------+------------------+----------------------+ 3975 | Soft Failure | Section 8.4.8.14 | OPTIONAL | 3976 +------------------+------------------+----------------------+ 3977 | Custom | Section 8.4.8.15 | OPTIONAL | 3978 +------------------+------------------+----------------------+ 3980 Table 16 3982 Authors' Addresses 3984 Brendan Moran 3985 Arm Limited 3986 Email: Brendan.Moran@arm.com 3988 Hannes Tschofenig 3989 Arm Limited 3990 Email: hannes.tschofenig@arm.com 3992 Henk Birkholz 3993 Fraunhofer SIT 3994 Email: henk.birkholz@sit.fraunhofer.de 3995 Koen Zandberg 3996 Inria 3997 Email: koen.zandberg@inria.fr