idnits 2.17.00 (12 Aug 2021) /tmp/idnits56111/draft-ietf-suit-manifest-16.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 (26 October 2021) is 206 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) == Outdated reference: draft-ietf-suit-information-model has been published as RFC 9124 ** Downref: Normative reference to an Informational draft: draft-ietf-suit-information-model (ref. 'I-D.ietf-suit-information-model') ** Downref: Normative reference to an Informational RFC: RFC 9019 == Outdated reference: draft-ietf-cbor-tags-oid has been published as RFC 9090 == Outdated reference: A later version (-04) exists of draft-ietf-suit-firmware-encryption-02 == Outdated reference: A later version (-17) exists of draft-ietf-teep-architecture-15 Summary: 3 errors (**), 0 flaws (~~), 6 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: 29 April 2022 H. Birkholz 6 Fraunhofer SIT 7 K. Zandberg 8 Inria 9 26 October 2021 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-16 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 29 April 2022. 43 Copyright Notice 45 Copyright (c) 2021 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 Simplified BSD License text 54 as described in Section 4.e of the Trust Legal Provisions and are 55 provided without warranty as described in the Simplified 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 . . . . . . . . . . . . . . . . . . 12 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 . . . . . . . . . . . . . . . . . . . . . . 30 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 . . . . . . . 84 136 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 86 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 177 [I-D.ietf-suit-information-model]. 179 * Simple to parse on a constrained node 181 * Simple to process on a constrained node 183 * Compact encoding 185 * Comprehensible by an intermediate system 186 * Expressive enough to enable advanced use cases on advanced nodes 188 * Extensible 190 The SUIT manifest can be used for a variety of purposes throughout 191 its lifecycle, such as: 193 * a Firmware Author to reason about releasing a firmware. 195 * a Network Operator to reason about compatibility of a firmware. 197 * a Device Operator to reason about the impact of a firmware. 199 * the Device Operator to manage distribution of firmware to devices. 201 * a Plant Manager to reason about timing and acceptance of firmware 202 updates. 204 * a device to reason about the authority & authenticity of a 205 firmware prior to installation. 207 * a device to reason about the applicability of a firmware. 209 * a device to reason about the installation of a firmware. 211 * a device to reason about the authenticity & encoding of a firmware 212 at boot. 214 Each of these uses happens at a different stage of the manifest 215 lifecycle, so each has different requirements. 217 It is assumed that the reader is familiar with the high-level 218 firmware update architecture [RFC9019] and the threats, requirements, 219 and user stories in [I-D.ietf-suit-information-model]. 221 The design of this specification is based on an observation that the 222 vast majority of operations that a device can perform during an 223 update or Trusted Invocation are composed of a small group of 224 operations: 226 * Copy some data from one place to another 228 * Transform some data 230 * Digest some data and compare to an expected value 232 * Compare some system parameters to an expected value 233 * Run some code 235 In this document, these operations are called commands. Commands are 236 classed as either conditions or directives. Conditions have no side- 237 effects, while directives do have side-effects. Conceptually, a 238 sequence of commands is like a script but the language is tailored to 239 software updates and Trusted Invocation. 241 The available commands support simple steps, such as copying a 242 firmware image from one place to another, checking that a firmware 243 image is correct, verifying that the specified firmware is the 244 correct firmware for the device, or unpacking a firmware. By using 245 these steps in different orders and changing the parameters they use, 246 a broad range of use cases can be supported. The SUIT manifest uses 247 this observation to optimize metadata for consumption by constrained 248 devices. 250 While the SUIT manifest is informed by and optimized for firmware 251 update and Trusted Invocation use cases, there is nothing in the SUIT 252 Information Model ([I-D.ietf-suit-information-model]) that restricts 253 its use to only those use cases. Other use cases include the 254 management of trusted applications (TAs) in a Trusted Execution 255 Environment (TEE), as discussed in [I-D.ietf-teep-architecture]. 257 2. Conventions and Terminology 259 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 260 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 261 "OPTIONAL" in this document are to be interpreted as described in 262 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 263 capitals, as shown here. 265 Additionally, the following terminology is used throughout this 266 document: 268 * SUIT: Software Update for the Internet of Things, also the IETF 269 working group for this standard. 271 * Payload: A piece of information to be delivered. Typically 272 Firmware for the purposes of SUIT. 274 * Resource: A piece of information that is used to construct a 275 payload. 277 * Manifest: A manifest is a bundle of metadata about the firmware 278 for an IoT device, where to find the firmware, and the devices to 279 which it applies. 281 * Envelope: A container with the manifest, an authentication wrapper 282 with cryptographic information protecting the manifest, 283 authorization information, and severable elements (see: TBD). 285 * Update: One or more manifests that describe one or more payloads. 287 * Update Authority: The owner of a cryptographic key used to sign 288 updates, trusted by Recipients. 290 * Recipient: The system, typically an IoT device, that receives and 291 processes a manifest. 293 * Manifest Processor: A component of the Recipient that consumes 294 Manifests and executes the commands in the Manifest. 296 * Component: An updatable logical block of the Firmware, Software, 297 configuration, or data of the Recipient. 299 * Component Set: A group of interdependent Components that must be 300 updated simultaneously. 302 * Command: A Condition or a Directive. 304 * Condition: A test for a property of the Recipient or its 305 Components. 307 * Directive: An action for the Recipient to perform. 309 * Trusted Invocation: A process by which a system ensures that only 310 trusted code is executed, for example secure boot or launching a 311 Trusted Application. 313 * A/B images: Dividing a Recipient's storage into two or more 314 bootable images, at different offsets, such that the active image 315 can write to the inactive image(s). 317 * Record: The result of a Command and any metadata about it. 319 * Report: A list of Records. 321 * Procedure: The process of invoking one or more sequences of 322 commands. 324 * Update Procedure: A procedure that updates a Recipient by fetching 325 dependencies and images, and installing them. 327 * Invocation Procedure: A procedure in which a Recipient verifies 328 dependencies and images, loading images, and invokes one or more 329 image. 331 * Software: Instructions and data that allow a Recipient to perform 332 a useful function. 334 * Firmware: Software that is typically changed infrequently, stored 335 in nonvolatile memory, and small enough to apply to [RFC7228] 336 Class 0-2 devices. 338 * Image: Information that a Recipient uses to perform its function, 339 typically firmware/software, configuration, or resource data such 340 as text or images. Also, a Payload, once installed is an Image. 342 * Slot: One of several possible storage locations for a given 343 Component, typically used in A/B image systems 345 * Abort: An event in which the Manifest Processor immediately halts 346 execution of the current Procedure. It creates a Record of an 347 error condition. 349 3. How to use this Document 351 This specification covers five aspects of firmware update: 353 * Section 4 describes the device constraints, use cases, and design 354 principles that informed the structure of the manifest. 356 * Section 5 gives a general overview of the metadata structure to 357 inform the following sections 359 * Section 6 describes what actions a Manifest processor should take. 361 * Section 7 describes the process of creating a Manifest. 363 * Section 8 specifies the content of the Envelope and the Manifest. 365 To implement an updatable device, see Section 6 and Section 8. To 366 implement a tool that generates updates, see Section 7 and Section 8. 368 The IANA consideration section, see Section 11, provides instructions 369 to IANA to create several registries. This section also provides the 370 CBOR labels for the structures defined in this document. 372 The complete CDDL description is provided in Appendix A, examples are 373 given in Appendix B and a design rational is offered in Appendix C. 374 Finally, Appendix D gives a summarize of the mandatory-to-implement 375 features of this specification. 377 This specification covers the core features of SUIT. Additional 378 specifications will cover advanced use cases and update management 379 needs: 381 * Firmware Encryption is covered in 382 [I-D.ietf-suit-firmware-encryption] 384 * Update Management is covered in (TBD) 386 * Multiple Trust Domains (dependencies, key delegation, multiple 387 processors, TEEs, etc.) are covered in (TBD) 389 * Update Compression is covered in (TBD) 391 4. Background 393 Distributing software updates to diverse devices with diverse trust 394 anchors in a coordinated system presents unique challenges. Devices 395 have a broad set of constraints, requiring different metadata to make 396 appropriate decisions. There may be many actors in production IoT 397 systems, each of whom has some authority. Distributing firmware in 398 such a multi-party environment presents additional challenges. Each 399 party requires a different subset of data. Some data may not be 400 accessible to all parties. Multiple signatures may be required from 401 parties with different authorities. This topic is covered in more 402 depth in [RFC9019]. The security aspects are described in 403 [I-D.ietf-suit-information-model]. 405 4.1. IoT Firmware Update Constraints 407 The various constraints of IoT devices and the range of use cases 408 that need to be supported create a broad set of requirements. For 409 example, devices with: 411 * limited processing power and storage may require a simple 412 representation of metadata. 414 * bandwidth constraints may require firmware compression or partial 415 update support. 417 * bootloader complexity constraints may require simple selection 418 between two bootable images. 420 * small internal storage may require external storage support. 422 * multiple microcontrollers may require coordinated update of all 423 applications. 425 * large storage and complex functionality may require parallel 426 update of many software components. 428 * extra information may need to be conveyed in the manifest in the 429 earlier stages of the device lifecycle before those data items are 430 stripped when the manifest is delivered to a constrained device. 432 Supporting the requirements introduced by the constraints on IoT 433 devices requires the flexibility to represent a diverse set of 434 possible metadata, but also requires that the encoding is kept 435 simple. 437 4.2. SUIT Workflow Model 439 There are several fundamental assumptions that inform the model of 440 Update Procedure workflow: 442 * Compatibility must be checked before any other operation is 443 performed. 445 * In some applications, payloads must be fetched and validated prior 446 to installation. 448 There are several fundamental assumptions that inform the model of 449 the Invocation Procedure workflow: 451 * Compatibility must be checked before any other operation is 452 performed. 454 * All payloads must be validated prior to loading. 456 * All loaded images must be validated prior to execution. 458 Based on these assumptions, the manifest is structured to work with a 459 pull parser, where each section of the manifest is used in sequence. 460 The expected workflow for a Recipient installing an update can be 461 broken down into five steps: 463 1. Verify the signature of the manifest. 465 2. Verify the applicability of the manifest. 467 3. Fetch payload(s). 469 4. Install payload(s). 471 When installation is complete, similar information can be used for 472 validating and running images in a further three steps: 474 1. Verify image(s). 476 2. Load image(s). 478 3. Run image(s). 480 If verification and running is implemented in a bootloader, then the 481 bootloader MUST also verify the signature of the manifest and the 482 applicability of the manifest in order to implement secure boot 483 workflows. The bootloader may add its own authentication, e.g. a 484 Message Authentication Code (MAC), to the manifest in order to 485 prevent further verifications. 487 5. Metadata Structure Overview 489 This section provides a high level overview of the manifest 490 structure. The full description of the manifest structure is in 491 Section 8.4 493 The manifest is structured from several key components: 495 1. The Envelope (see Section 5.1) contains the Authentication Block, 496 the Manifest, any Severable Elements, and any Integrated 497 Payloads. 499 2. The Authentication Block (see Section 5.2) contains a list of 500 signatures or MACs of the manifest.. 502 3. The Manifest (see Section 5.3) contains all critical, non- 503 severable metadata that the Recipient requires. It is further 504 broken down into: 506 1. Critical metadata, such as sequence number. 508 2. Common metadata, such as affected components. 510 3. Command sequences, directing the Recipient how to install and 511 use the payload(s). 513 4. Integrity check values for severable elements. 515 4. Severable elements (see Section 5.4). 517 5. Integrated payloads (see Section 5.5). 519 The diagram below illustrates the hierarchy of the Envelope. 521 +-------------------------+ 522 | Envelope | 523 +-------------------------+ 524 | Authentication Block | 525 | Manifest --------------> +------------------------------+ 526 | Severable Elements | | Manifest | 527 | Human-Readable Text | +------------------------------+ 528 | Integrated Payloads | | Structure Version | 529 +-------------------------+ | Sequence Number | 530 | Reference to Full Manifest | 531 +------ Common Structure | 532 | +---- Command Sequences | 533 +-------------------------+ | | | Digests of Envelope Elements | 534 | Common Structure | <--+ | +------------------------------+ 535 +-------------------------+ | 536 | Components IDs | +-> +-----------------------+ 537 | Common Command Sequence ---------> | Command Sequence | 538 +-------------------------+ +-----------------------+ 539 | List of ( pairs of ( | 540 | * command code | 541 | * argument / | 542 | reporting policy | 543 | )) | 544 +-----------------------+ 546 5.1. Envelope 548 The SUIT Envelope is a container that encloses the Authentication 549 Block, the Manifest, any Severable Elements, and any integrated 550 payloads. The Envelope is used instead of conventional cryptographic 551 envelopes, such as COSE_Envelope because it allows modular 552 processing, severing of elements, and integrated payloads in a way 553 that would add substantial complexity with existing solutions. See 554 Appendix C.1 for a description of the reasoning for this. 556 See Section 8.2 for more detail. 558 5.2. Authentication Block 560 The Authentication Block contains a bstr-wrapped SUIT Digest 561 Container, see Section 10, and one or more [RFC8152] CBOR Object 562 Signing and Encryption (COSE) authentication blocks. These blocks 563 are one of: 565 * COSE_Sign_Tagged 567 * COSE_Sign1_Tagged 569 * COSE_Mac_Tagged 571 * COSE_Mac0_Tagged 573 Each of these objects is used in detached payload mode. The payload 574 is the bstr-wrapped SUIT_Digest. 576 See Section 8.3 for more detail. 578 5.3. Manifest 580 The Manifest contains most metadata about one or more images. The 581 Manifest is divided into Critical Metadata, Common Metadata, Command 582 Sequences, and Integrity Check Values. 584 See Section 8.4 for more detail. 586 5.3.1. Critical Metadata 588 Some metadata needs to be accessed before the manifest is processed. 589 This metadata can be used to determine which manifest is newest and 590 whether the structure version is supported. It also MAY provide a 591 URI for obtaining a canonical copy of the manifest and Envelope. 593 See Section 8.4.1, Section 8.4.2, and Section 8.4.3 for more detail. 595 5.3.2. Common 597 Some metadata is used repeatedly and in more than one command 598 sequence. In order to reduce the size of the manifest, this metadata 599 is collected into the Common section. Common is composed of two 600 parts: a list of components referenced by the manifest, and a command 601 sequence to execute prior to each other command sequence. The common 602 command sequence is typically used to set commonly used values and 603 perform compatibility checks. The common command sequence MUST NOT 604 have any side-effects outside of setting parameter values. 606 See Section 8.4.5 for more detail. 608 5.3.3. Command Sequences 610 Command sequences provide the instructions that a Recipient requires 611 in order to install or use an image. These sequences tell a device 612 to set parameter values, test system parameters, copy data from one 613 place to another, transform data, digest data, and run code. 615 Command sequences are broken up into three groups: Common Command 616 Sequence (see Section 5.3.2), update commands, and secure boot 617 commands. 619 Update Command Sequences are: Payload Fetch, and Payload 620 Installation. An Update Procedure is the complete set of each Update 621 Command Sequence, each preceded by the Common Command Sequence. 623 Invocation Command Sequences are: System Validation, Image Loading, 624 and Image Invocation. An Invocation Procedure is the complete set of 625 each Invocation Command Sequence, each preceded by the Common Command 626 Sequence. 628 Command Sequences are grouped into these sets to ensure that there is 629 common coordination between dependencies and dependents on when to 630 execute each command (dependencies are not defined in this 631 specification). 633 See Section 8.4.6 for more detail. 635 5.3.4. Integrity Check Values 637 To enable Section 5.4, there needs to be a mechanism to verify 638 integrity of any metadata outside the manifest. Integrity Check 639 Values are used to verify the integrity of metadata that is not 640 contained in the manifest. This MAY include Severable Command 641 Sequences, or Text data. Integrated Payloads are integrity-checked 642 using Command Sequences, so they do not have Integrity Check Values 643 present in the Manifest. 645 See Section 8.4.11 for more detail. 647 5.3.5. Human-Readable Text 649 Text is typically a Severable Element (Section 5.4). It contains all 650 the text that describes the update. Because text is explicitly for 651 human consumption, it is all grouped together so that it can be 652 Severed easily. The text section has space both for describing the 653 manifest as a whole and for describing each individual component. 655 See Section 8.4.4 for more detail. 657 5.4. Severable Elements 659 Severable Elements are elements of the Envelope (Section 5.1) that 660 have Integrity Check Values (Section 5.3.4) in the Manifest 661 (Section 5.3). 663 Because of this organisation, these elements can be discarded or 664 "Severed" from the Envelope without changing the signature of the 665 Manifest. This allows savings based on the size of the Envelope in 666 several scenarios, for example: 668 * A management system severs the Text sections before sending an 669 Envelope to a constrained Recipient, which saves Recipient 670 bandwidth. 672 * A Recipient severs the Installation section after installing the 673 Update, which saves storage space. 675 See Section 8.5 for more detail. 677 5.5. Integrated Payloads 679 In some cases, it is beneficial to include a payload in the Envelope 680 of a manifest. For example: 682 * When an update is delivered via a comparatively unconstrained 683 medium, such as a removable mass storage device, it may be 684 beneficial to bundle updates into single files. 686 * When a manifest transports a small payload, such as an encrypted 687 key, that payload may be placed in the manifest's envelope. 689 See Section 7.5 for more detail. 691 6. Manifest Processor Behavior 693 This section describes the behavior of the manifest processor and 694 focuses primarily on interpreting commands in the manifest. However, 695 there are several other important behaviors of the manifest 696 processor: encoding version detection, rollback protection, and 697 authenticity verification are chief among these. 699 6.1. Manifest Processor Setup 701 Prior to executing any command sequence, the manifest processor or 702 its host application MUST inspect the manifest version field and fail 703 when it encounters an unsupported encoding version. Next, the 704 manifest processor or its host application MUST extract the manifest 705 sequence number and perform a rollback check using this sequence 706 number. The exact logic of rollback protection may vary by 707 application, but it has the following properties: 709 * Whenever the manifest processor can choose between several 710 manifests, it MUST select the latest valid, authentic manifest. 712 * If the latest valid, authentic manifest fails, it MAY select the 713 next latest valid, authentic manifest, according to application- 714 specific policy. 716 Here, valid means that a manifest has a supported encoding version 717 and it has not been excluded for other reasons. Reasons for 718 excluding typically involve first executing the manifest and may 719 include: 721 * Test failed (e.g. Vendor ID/Class ID). 723 * Unsupported command encountered. 725 * Unsupported parameter encountered. 727 * Unsupported Component Identifier encountered. 729 * Payload not available. 731 * Application crashed when executed. 733 * Watchdog timeout occurred. 735 * Payload verification failed. 737 * Missing required component from a Component Set. 739 * Required parameter not supplied. 741 These failure reasons MAY be combined with retry mechanisms prior to 742 marking a manifest as invalid. 744 Selecting an older manifest in the event of failure of the latest 745 valid manifest is a robustness mechanism that is necessary for 746 supporting the requirements in [RFC9019], section 3.5. It may not be 747 appropriate for all applications. In particular Trusted Execution 748 Environments MAY require a failure to invoke a new installation, 749 rather than a rollback approach. See 750 [I-D.ietf-suit-information-model], Section 4.2.1 for more discussion 751 on the security considerations that apply to rollback. 753 Following these initial tests, the manifest processor clears all 754 parameter storage. This ensures that the manifest processor begins 755 without any leaked data. 757 6.2. Required Checks 759 The RECOMMENDED process is to verify the signature of the manifest 760 prior to parsing/executing any section of the manifest. This guards 761 the parser against arbitrary input by unauthenticated third parties, 762 but it costs extra energy when a Recipient receives an incompatible 763 manifest. 765 When validating authenticity of manifests, the manifest processor MAY 766 use an ACL (see Section 9) to determine the extent of the rights 767 conferred by that authenticity. 769 Once a valid, authentic manifest has been selected, the manifest 770 processor MUST examine the component list and verify that its maximum 771 number of components is not exceeded and that each listed component 772 is supported. 774 For each listed component, the manifest processor MUST provide 775 storage for the supported parameters. If the manifest processor does 776 not have sufficient temporary storage to process the parameters for 777 all components, it MAY process components serially for each command 778 sequence. See Section 6.6 for more details. 780 The manifest processor SHOULD check that the common sequence contains 781 at least Check Vendor Identifier command and at least one Check Class 782 Identifier command. 784 Because the common sequence contains Check Vendor Identifier and 785 Check Class Identifier command(s), no custom commands are permitted 786 in the common sequence. This ensures that any custom commands are 787 only executed by devices that understand them. 789 If the manifest contains more than one component, each command 790 sequence MUST begin with a Set Component Index. 792 If a Recipient supports groups of interdependent components (a 793 Component Set), then it SHOULD verify that all Components in the 794 Component Set are specified by one update, that is the manifest: 796 1. has sufficient permissions imparted by its signatures 798 2. specifies a digest and a payload for every Component in the 799 Component Set. 801 6.2.1. Minimizing Signature Verifications 803 Signature verification can be energy and time expensive on a 804 constrained device. MAC verification is typically unaffected by 805 these concerns. A Recipient MAY choose to parse and execute only the 806 SUIT_Common section of the manifest prior to signature verification, 807 if all of the below apply: 809 * The Authentication Block contains a COSE_Sign_Tagged or 810 COSE_Sign1_Tagged 812 * The Recipient receives manifests over an unauthenticated channel, 813 exposing it to more inauthentic or incompatible manifests, and 815 * The Recipient has a power budget that makes signature verification 816 undesirable 818 When executing Common prior to authenticity validation, the Manifest 819 Processor MUST first evaluate the integrity of the manifest using the 820 SUIT_Digest present in the authentication block. 822 The guidelines in Creating Manifests (Section 7) require that the 823 common section contains the applicability checks, so this section is 824 sufficient for applicability verification. The parser MUST restrict 825 acceptable commands to conditions and the following directives: 826 Override Parameters, Set Parameters, Try Each, and Run Sequence ONLY. 827 The manifest parser MUST NOT execute any command with side-effects 828 outside the parser (for example, Run, Copy, Swap, or Fetch commands) 829 prior to authentication and any such command MUST Abort. The Common 830 Sequence MUST be executed again, in its entirety, after authenticity 831 validation. 833 A Recipient MAY rely on network infrastructure to filter inapplicable 834 manifests. 836 6.3. Interpreter Fundamental Properties 838 The interpreter has a small set of design goals: 840 1. Executing an update MUST either result in an error, or a 841 verifiably correct system state. 843 2. Executing a Trusted Invocation MUST either result in an error, or 844 an invoked image. 846 3. Executing the same manifest on multiple Recipients MUST result in 847 the same system state. 849 NOTE: when using A/B images, the manifest functions as two (or more) 850 logical manifests, each of which applies to a system in a particular 851 starting state. With that provision, design goal 3 holds. 853 6.4. Abstract Machine Description 855 The heart of the manifest is the list of commands, which are 856 processed by a Manifest Processor--a form of interpreter. This 857 Manifest Processor can be modeled as a simple abstract machine. This 858 machine consists of several data storage locations that are modified 859 by commands. 861 There are two types of commands, namely those that modify state 862 (directives) and those that perform tests (conditions). Parameters 863 are used as the inputs to commands. Some directives offer control 864 flow operations. Directives target a specific component. A 865 component is a unit of code or data that can be targeted by an 866 update. Components are identified by Component Identifiers, but 867 referenced in commands by Component Index; Component Identifiers are 868 arrays of binary strings and a Component Index is an index into the 869 array of Component Identifiers. 871 Conditions MUST NOT have any side-effects other than informing the 872 interpreter of success or failure. The Interpreter does not Abort if 873 the Soft Failure flag (Section 8.4.8.14) is set when a Condition 874 reports failure. 876 Directives MAY have side-effects in the parameter table, the 877 interpreter state, or the current component. The Interpreter MUST 878 Abort if a Directive reports failure regardless of the Soft Failure 879 flag. 881 To simplify the logic describing the command semantics, the object 882 "current" is used. It represents the component identified by the 883 Component Index: 885 current := components\[component-index\] 887 As a result, Set Component Index is described as current := 888 components[arg]. 890 The following table describes the behavior of each command. "params" 891 represents the parameters for the current component. Most commands 892 operate on a component. 894 +=========================+======================================+ 895 | Command Name | Semantic of the Operation | 896 +=========================+======================================+ 897 | Check Vendor Identifier | assert(binary-match(current, | 898 | | current.params[vendor-id])) | 899 +-------------------------+--------------------------------------+ 900 | Check Class Identifier | assert(binary-match(current, | 901 | | current.params[class-id])) | 902 +-------------------------+--------------------------------------+ 903 | Verify Image | assert(binary-match(digest(current), | 904 | | current.params[digest])) | 905 +-------------------------+--------------------------------------+ 906 | Set Component Index | current := components[arg] | 907 +-------------------------+--------------------------------------+ 908 | Override Parameters | current.params[k] := v for-each k,v | 909 | | in arg | 910 +-------------------------+--------------------------------------+ 911 | Set Parameters | current.params[k] := v if not k in | 912 | | params for-each k,v in arg | 913 +-------------------------+--------------------------------------+ 914 | Run | run(current) | 915 +-------------------------+--------------------------------------+ 916 | Fetch | store(current, | 917 | | fetch(current.params[uri])) | 918 +-------------------------+--------------------------------------+ 919 | Use Before | assert(now() < arg) | 920 +-------------------------+--------------------------------------+ 921 | Check Component Slot | assert(current.slot-index == arg) | 922 +-------------------------+--------------------------------------+ 923 | Check Device Identifier | assert(binary-match(current, | 924 | | current.params[device-id])) | 925 +-------------------------+--------------------------------------+ 926 | Abort | assert(0) | 927 +-------------------------+--------------------------------------+ 928 | Try Each | try-each-done if exec(seq) is not | 929 | | error for-each seq in arg | 930 +-------------------------+--------------------------------------+ 931 | Copy | store(current, current.params[src- | 932 | | component]) | 933 +-------------------------+--------------------------------------+ 934 | Swap | swap(current, current.params[src- | 935 | | component]) | 936 +-------------------------+--------------------------------------+ 937 | Run Sequence | exec(arg) | 938 +-------------------------+--------------------------------------+ 939 | Run with Arguments | run(current, arg) | 940 +-------------------------+--------------------------------------+ 942 Table 1 944 6.5. Special Cases of Component Index 946 Component Index can take on one of three types: 948 1. Integer 950 2. Array of integers 952 3. True 954 Integers MUST always be supported by Set Component Index. Arrays of 955 integers MUST be supported by Set Component Index if the Recipient 956 supports 3 or more components. True MUST be supported by Set 957 Component Index if the Recipient supports 2 or more components. Each 958 of these operates on the list of components declared in the manifest. 960 Integer indices are the default case as described in the previous 961 section. An array of integers represents a list of the components 962 (Set Component Index) to which each subsequent command applies. The 963 value True replaces the list of component indices with the full list 964 of components, as defined in the manifest. 966 When a command is executed, it either 1. operates on the component 967 identified by the component index if that index is an integer, or 2. 968 it operates on each component identified by an array of indicies, or 969 3. it operates on every component if the index is the boolean True. 970 This is described by the following pseudocode: 972 if component-index is true: 973 current-list = components 974 else if component-index is array: 975 current-list = [ components[idx] for idx in component-index ] 976 else: 977 current-list = [ components[component-index] ] 978 for current in current-list: 979 cmd(current) 981 Try Each and Run Sequence are affected in the same way as other 982 commands: they are invoked once for each possible Component. This 983 means that the sequences that are arguments to Try Each and Run 984 Sequence are NOT invoked with Component Index = True, nor are they 985 invoked with array indices. They are only invoked with integer 986 indices. The interpreter loops over the whole sequence, setting the 987 Component Index to each index in turn. 989 6.6. Serialized Processing Interpreter 991 In highly constrained devices, where storage for parameters is 992 limited, the manifest processor MAY handle one component at a time, 993 traversing the manifest tree once for each listed component. In this 994 mode, the interpreter ignores any commands executed while the 995 component index is not the current component. This reduces the 996 overall volatile storage required to process the update so that the 997 only limit on number of components is the size of the manifest. 998 However, this approach requires additional processing power. 1000 In order to operate in this mode, the manifest processor loops on 1001 each section for every supported component, simply ignoring commands 1002 when the current component is not selected. 1004 When a serialized Manifest Processor encounters a component index of 1005 True, it does not ignore any commands. It applies them to the 1006 current component on each iteration. 1008 6.7. Parallel Processing Interpreter 1010 Advanced Recipients MAY make use of the Strict Order parameter and 1011 enable parallel processing of some Command Sequences, or it may 1012 reorder some Command Sequences. To perform parallel processing, once 1013 the Strict Order parameter is set to False, the Recipient may issue 1014 each or every command concurrently until the Strict Order parameter 1015 is returned to True or the Command Sequence ends. Then, it waits for 1016 all issued commands to complete before continuing processing of 1017 commands. To perform out-of-order processing, a similar approach is 1018 used, except the Recipient consumes all commands after the Strict 1019 Order parameter is set to False, then it sorts these commands into 1020 its preferred order, invokes them all, then continues processing. 1022 When the manifest processor encounters any of these scenarios the 1023 parallel processing MUST halt until all issued commands have 1024 completed: 1026 * Set Parameters. 1028 * Override Parameters. 1030 * Set Strict Order = True. 1032 * Set Component Index. 1034 To perform more useful parallel operations, a manifest author may 1035 collect sequences of commands in a Run Sequence command. Then, each 1036 of these sequences MAY be run in parallel. Each sequence defaults to 1037 Strict Order = True. To isolate each sequence from each other 1038 sequence, each sequence MUST begin with a Set Component Index 1039 directive with the following exception: when the index is either True 1040 or an array of indices, the Set Component Index is implied. Any 1041 further Set Component Index directives MUST cause an Abort. This 1042 allows the interpreter that issues Run Sequence commands to check 1043 that the first element is correct, then issue the sequence to a 1044 parallel execution context to handle the remainder of the sequence. 1046 7. Creating Manifests 1048 Manifests are created using tools for constructing COSE structures, 1049 calculating cryptographic values and compiling desired system state 1050 into a sequence of operations required to achieve that state. The 1051 process of constructing COSE structures and the calculation of 1052 cryptographic values is covered in [RFC8152]. 1054 Compiling desired system state into a sequence of operations can be 1055 accomplished in many ways. Several templates are provided below to 1056 cover common use-cases. These templates can be combined to produce 1057 more complex behavior. 1059 The author MUST ensure that all parameters consumed by a command are 1060 set prior to invoking that command. Where Component Index = True, 1061 this means that the parameters consumed by each command MUST have 1062 been set for each Component. 1064 This section details a set of templates for creating manifests. 1065 These templates explain which parameters, commands, and orders of 1066 commands are necessary to achieve a stated goal. 1068 NOTE: On systems that support only a single component, Set Component 1069 Index has no effect and can be omitted. 1071 NOTE: *A digest MUST always be set using Override Parameters.* 1073 7.1. Compatibility Check Template 1075 The goal of the compatibility check template ensure that Recipients 1076 only install compatible images. 1078 In this template all information is contained in the common sequence 1079 and the following sequence of commands is used: 1081 * Set Component Index directive (see Section 8.4.10.1) 1083 * Override Parameters directive (see Section 8.4.10.3) for Vendor ID 1084 and Class ID (see Section 8.4.8) 1086 * Check Vendor Identifier condition (see Section 8.4.8.2) 1088 * Check Class Identifier condition (see Section 8.4.8.2) 1090 7.2. Trusted Invocation Template 1092 The goal of the Trusted Invocation template is to ensure that only 1093 authorized code is invoked; such as in Secure Boot or when a Trusted 1094 Application is loaded into a TEE. 1096 The following commands are placed into the common sequence: 1098 * Set Component Index directive (see Section 8.4.10.1) 1100 * Override Parameters directive (see Section 8.4.10.3) for Image 1101 Digest and Image Size (see Section 8.4.8) 1103 The system validation sequence contains the following commands: 1105 * Set Component Index directive (see Section 8.4.10.1) 1107 * Check Image Match condition (see Section 8.4.9.2) 1109 Then, the run sequence contains the following commands: 1111 * Set Component Index directive (see Section 8.4.10.1) 1113 * Run directive (see Section 8.4.10.7) 1115 7.3. Component Download Template 1117 The goal of the Component Download template is to acquire and store 1118 an image. 1120 The following commands are placed into the common sequence: 1122 * Set Component Index directive (see Section 8.4.10.1) 1124 * Override Parameters directive (see Section 8.4.10.3) for Image 1125 Digest and Image Size (see Section 8.4.8) 1127 Then, the install sequence contains the following commands: 1129 * Set Component Index directive (see Section 8.4.10.1) 1131 * Override Parameters directive (see Section 8.4.10.3) for URI (see 1132 Section 8.4.8.9) 1134 * Fetch directive (see Section 8.4.10.4) 1136 * Check Image Match condition (see Section 8.4.9.2) 1138 The Fetch directive needs the URI parameter to be set to determine 1139 where the image is retrieved from. Additionally, the destination of 1140 where the component shall be stored has to be configured. The URI is 1141 configured via the Set Parameters directive while the destination is 1142 configured via the Set Component Index directive. 1144 7.4. Install Template 1146 The goal of the Install template is to use an image already stored in 1147 an identified component to copy into a second component. 1149 This template is typically used with the Component Download template, 1150 however a modification to that template is required: the Component 1151 Download operations are moved from the Payload Install sequence to 1152 the Payload Fetch sequence. 1154 Then, the install sequence contains the following commands: 1156 * Set Component Index directive (see Section 8.4.10.1) 1158 * Override Parameters directive (see Section 8.4.10.3) for Source 1159 Component (see Section 8.4.8.10) 1161 * Copy directive (see Section 8.4.10.5) 1163 * Check Image Match condition (see Section 8.4.9.2) 1165 7.5. Integrated Payload Template 1167 The goal of the Integrated Payload template is to install a payload 1168 that is included in the manifest envelope. It is identical to the 1169 Component Download template (Section 7.3). 1171 An implementer MAY choose to place a payload in the envelope of a 1172 manifest. The payload envelope key MUST be a string. The payload 1173 MUST be serialized in a bstr element. 1175 The URI for a payload enclosed in this way MAY be expressed as a 1176 fragment-only reference, as defined in [RFC3986], Section 4.4. 1178 A distributor MAY choose to pre-fetch a payload and add it to the 1179 manifest envelope, using the URI as the key. 1181 7.6. Load from Nonvolatile Storage Template 1183 The goal of the Load from Nonvolatile Storage template is to load an 1184 image from a non-volatile component into a volatile component, for 1185 example loading a firmware image from external Flash into RAM. 1187 The following commands are placed into the load sequence: 1189 * Set Component Index directive (see Section 8.4.10.1) 1191 * Override Parameters directive (see Section 8.4.10.3) for Source 1192 Component (see Section 8.4.8) 1194 * Copy directive (see Section 8.4.10.5) 1196 As outlined in Section 6.4, the Copy directive needs a source and a 1197 destination to be configured. The source is configured via Component 1198 Index (with the Set Parameters directive) and the destination is 1199 configured via the Set Component Index directive. 1201 7.7. A/B Image Template 1203 The goal of the A/B Image Template is to acquire, validate, and 1204 invoke one of two images, based on a test. 1206 The following commands are placed in the common block: 1208 * Set Component Index directive (see Section 8.4.10.1) 1210 * Try Each 1212 - First Sequence: 1214 o Override Parameters directive (see Section 8.4.10.3, 1215 Section 8.4.8) for Slot A 1217 o Check Slot Condition (see Section 8.4.9.3) 1219 o Override Parameters directive (see Section 8.4.10.3) for 1220 Image Digest A and Image Size A (see Section 8.4.8) 1222 - Second Sequence: 1224 o Override Parameters directive (see Section 8.4.10.3, 1225 Section 8.4.8) for Slot B 1227 o Check Slot Condition (see Section 8.4.9.3) 1229 o Override Parameters directive (see Section 8.4.10.3) for 1230 Image Digest B and Image Size B (see Section 8.4.8) 1232 The following commands are placed in the fetch block or install block 1234 * Set Component Index directive (see Section 8.4.10.1) 1236 * Try Each 1238 - First Sequence: 1240 o Override Parameters directive (see Section 8.4.10.3, 1241 Section 8.4.8) for Slot A 1243 o Check Slot Condition (see Section 8.4.9.3) 1245 o Set Parameters directive (see Section 8.4.10.3) for URI A 1246 (see Section 8.4.8) 1248 - Second Sequence: 1250 o Override Parameters directive (see Section 8.4.10.3, 1251 Section 8.4.8) for Slot B 1253 o Check Slot Condition (see Section 8.4.9.3) 1255 o Set Parameters directive (see Section 8.4.10.3) for URI B 1256 (see Section 8.4.8) 1258 * Fetch 1260 If Trusted Invocation (Section 7.2) is used, only the run sequence is 1261 added to this template, since the common sequence is populated by 1262 this template: 1264 * Set Component Index directive (see Section 8.4.10.1) 1266 * Try Each 1268 - First Sequence: 1270 o Override Parameters directive (see Section 8.4.10.3, 1271 Section 8.4.8) for Slot A 1273 o Check Slot Condition (see Section 8.4.9.3) 1275 - Second Sequence: 1277 o Override Parameters directive (see Section 8.4.10.3, 1278 Section 8.4.8) for Slot B 1280 o Check Slot Condition (see Section 8.4.9.3) 1282 * Run 1284 NOTE: Any test can be used to select between images, Check Slot 1285 Condition is used in this template because it is a typical test for 1286 execute-in-place devices. 1288 8. Metadata Structure 1290 The metadata for SUIT updates is composed of several primary 1291 constituent parts: the Envelope, Authentication Information, 1292 Manifest, and Severable Elements. 1294 For a diagram of the metadata structure, see Section 5. 1296 8.1. Encoding Considerations 1298 The map indices in the envelope encoding are reset to 1 for each map 1299 within the structure. This is to keep the indices as small as 1300 possible. The goal is to keep the index objects to single bytes 1301 (CBOR positive integers 1-23). 1303 Wherever enumerations are used, they are started at 1. This allows 1304 detection of several common software errors that are caused by 1305 uninitialized variables. Positive numbers in enumerations are 1306 reserved for IANA registration. Negative numbers are used to 1307 identify application-specific values, as described in Section 11. 1309 All elements of the envelope must be wrapped in a bstr to minimize 1310 the complexity of the code that evaluates the cryptographic integrity 1311 of the element and to ensure correct serialization for integrity and 1312 authenticity checks. 1314 8.2. Envelope 1316 The Envelope contains each of the other primary constituent parts of 1317 the SUIT metadata. It allows for modular processing of the manifest 1318 by ordering components in the expected order of processing. 1320 The Envelope is encoded as a CBOR Map. Each element of the Envelope 1321 is enclosed in a bstr, which allows computation of a message digest 1322 against known bounds. 1324 8.3. Authenticated Manifests 1326 The suit-authentication-wrapper contains a list containing a SUIT 1327 Digest Container (see Section 10) and one or more cryptographic 1328 authentication wrappers for the Manifest. These blocks are 1329 implemented as COSE_Mac_Tagged or COSE_Sign_Tagged structures with 1330 null payloads, indicating that the payload to be used is the SUIT 1331 Digest Container. This enables modular processing of the manifest. 1332 The COSE_Mac_Tagged and COSE_Sign_Tagged blocks are described in RFC 1333 8152 [RFC8152]. The suit-authentication-wrapper MUST come before any 1334 element in the SUIT_Envelope, regardless of canonical encoding of 1335 CBOR. All validators MUST reject any SUIT_Envelope that begins with 1336 any element other than a suit-authentication-wrapper (NOTE: key 1337 delegation MAY relax this requirement to include a delegation 1338 structure as well). 1340 A SUIT_Envelope that has not had authentication information added 1341 MUST still contain the suit-authentication-wrapper element, but the 1342 content MUST be a list containing only the SUIT_Digest. 1344 A signing application MUST verify the suit-manifest element against 1345 the SUIT_Digest prior to signing. 1347 8.4. Manifest 1349 The manifest contains: 1351 * a version number (see Section 8.4.1) 1353 * a sequence number (see Section 8.4.2) 1355 * a reference URI (see Section 8.4.3) 1357 * a common structure with information that is shared between command 1358 sequences (see Section 8.4.5) 1360 * one or more lists of commands that the Recipient should perform 1361 (see Section 8.4.6) 1363 * a reference to the full manifest (see Section 8.4.3) 1365 * human-readable text describing the manifest found in the 1366 SUIT_Envelope (see Section 8.4.4) 1368 The Text section, or any Command Sequence of the Update Procedure 1369 (Image Fetch, Image Installation) can be either a CBOR structure or a 1370 SUIT_Digest. In each of these cases, the SUIT_Digest provides for a 1371 severable element. Severable elements are RECOMMENDED to implement. 1372 In particular, the human-readable text SHOULD be severable, since 1373 most useful text elements occupy more space than a SUIT_Digest, but 1374 are not needed by the Recipient. Because SUIT_Digest is a CBOR Array 1375 and each severable element is a CBOR bstr, it is straight-forward for 1376 a Recipient to determine whether an element has been severed. The 1377 key used for a severable element is the same in the SUIT_Manifest and 1378 in the SUIT_Envelope so that a Recipient can easily identify the 1379 correct data in the envelope. See Section 8.4.11 for more detail. 1381 8.4.1. suit-manifest-version 1383 The suit-manifest-version indicates the version of serialization used 1384 to encode the manifest. Version 1 is the version described in this 1385 document. suit-manifest-version is REQUIRED to implement. 1387 8.4.2. suit-manifest-sequence-number 1389 The suit-manifest-sequence-number is a monotonically increasing anti- 1390 rollback counter. Each Recipient MUST reject any manifest that has a 1391 sequence number lower than its current sequence number. For 1392 convenience, an implementer MAY use a UTC timestamp in seconds as the 1393 sequence number. suit-manifest-sequence-number is REQUIRED to 1394 implement. 1396 8.4.3. suit-reference-uri 1398 suit-reference-uri is a text string that encodes a URI where a full 1399 version of this manifest can be found. This is convenient for 1400 allowing management systems to show the severed elements of a 1401 manifest when this URI is reported by a Recipient after installation. 1403 8.4.4. suit-text 1405 suit-text SHOULD be a severable element. suit-text is a map 1406 containing two different types of pair: 1408 * integer => text 1410 * SUIT_Component_Identifier => map 1412 Each SUIT_Component_Identifier => map entry contains a map of integer 1413 => text values. All SUIT_Component_Identifiers present in suit-text 1414 MUST also be present in suit-common (Section 8.4.5). 1416 suit-text contains all the human-readable information that describes 1417 any and all parts of the manifest, its payload(s) and its 1418 resource(s). The text section is typically severable, allowing 1419 manifests to be distributed without the text, since end-nodes do not 1420 require text. The meaning of each field is described below. 1422 Each section MAY be present. If present, each section MUST be as 1423 described. Negative integer IDs are reserved for application- 1424 specific text values. 1426 The following table describes the text fields available in suit-text: 1428 +================================+==================================+ 1429 | CDDL Structure | Description | 1430 +================================+==================================+ 1431 | suit-text-manifest-description | Free text description of | 1432 | | the manifest | 1433 +--------------------------------+----------------------------------+ 1434 | suit-text-update-description | Free text description of | 1435 | | the update | 1436 +--------------------------------+----------------------------------+ 1437 | suit-text-manifest-json-source | The JSON-formatted document | 1438 | | that was used to create the | 1439 | | manifest | 1440 +--------------------------------+----------------------------------+ 1441 | suit-text-manifest-yaml-source | The YAML ([YAML])-formatted | 1442 | | document that was used to | 1443 | | create the manifest | 1444 +--------------------------------+----------------------------------+ 1446 Table 2 1448 The following table describes the text fields available in each map 1449 identified by a SUIT_Component_Identifier. 1451 +=================================+===============================+ 1452 | CDDL Structure | Description | 1453 +=================================+===============================+ 1454 | suit-text-vendor-name | Free text vendor name | 1455 +---------------------------------+-------------------------------+ 1456 | suit-text-model-name | Free text model name | 1457 +---------------------------------+-------------------------------+ 1458 | suit-text-vendor-domain | The domain used to create the | 1459 | | vendor-id condition | 1460 +---------------------------------+-------------------------------+ 1461 | suit-text-model-info | The information used to | 1462 | | create the class-id condition | 1463 +---------------------------------+-------------------------------+ 1464 | suit-text-component-description | Free text description of each | 1465 | | component in the manifest | 1466 +---------------------------------+-------------------------------+ 1467 | suit-text-component-version | A free text representation of | 1468 | | the component version | 1469 +---------------------------------+-------------------------------+ 1471 Table 3 1473 suit-text is OPTIONAL to implement. 1475 8.4.5. suit-common 1477 suit-common encodes all the information that is shared between each 1478 of the command sequences, including: suit-components, and suit- 1479 common-sequence. suit-common is REQUIRED to implement. 1481 suit-components is a list of SUIT_Component_Identifier 1482 (Section 8.4.5.1) blocks that specify the component identifiers that 1483 will be affected by the content of the current manifest. suit- 1484 components is REQUIRED to implement. 1486 suit-common-sequence is a SUIT_Command_Sequence to execute prior to 1487 executing any other command sequence. Typical actions in suit- 1488 common-sequence include setting expected Recipient identity and image 1489 digests when they are conditional (see Section 8.4.10.2 and 1490 Section 7.7 for more information on conditional sequences). suit- 1491 common-sequence is RECOMMENDED to implement. It is REQUIRED if the 1492 optimizations described in Section 6.2.1 will be used. Whenever a 1493 parameter or Try Each command is required by more than one Command 1494 Sequence, placing that parameter or command in suit-common-sequence 1495 results in a smaller encoding. 1497 8.4.5.1. SUIT_Component_Identifier 1499 A component is a unit of code or data that can be targeted by an 1500 update. To facilitate composite devices, components are identified 1501 by a list of CBOR byte strings, which allows construction of 1502 hierarchical component structures. Components are identified by 1503 Component Identifiers, but referenced in commands by Component Index; 1504 Component Identifiers are arrays of binary strings and a Component 1505 Index is an index into the array of Component Identifiers. 1507 A Component Identifier can be trivial, such as the simple array 1508 [h'00']. It can also represent a filesystem path by encoding each 1509 segment of the path as an element in the list. For example, the path 1510 "/usr/bin/env" would encode to ['usr','bin','env']. 1512 This hierarchical construction allows a component identifier to 1513 identify any part of a complex, multi-component system. 1515 8.4.6. SUIT_Command_Sequence 1517 A SUIT_Command_Sequence defines a series of actions that the 1518 Recipient MUST take to accomplish a particular goal. These goals are 1519 defined in the manifest and include: 1521 1. Payload Fetch: suit-payload-fetch is a SUIT_Command_Sequence to 1522 execute in order to obtain a payload. Some manifests may include 1523 these actions in the suit-install section instead if they operate 1524 in a streaming installation mode. This is particularly relevant 1525 for constrained devices without any temporary storage for staging 1526 the update. suit-payload-fetch is OPTIONAL to implement. 1528 2. Payload Installation: suit-install is a SUIT_Command_Sequence to 1529 execute in order to install a payload. Typical actions include 1530 verifying a payload stored in temporary storage, copying a staged 1531 payload from temporary storage, and unpacking a payload. suit- 1532 install is OPTIONAL to implement. 1534 3. Image Validation: suit-validate is a SUIT_Command_Sequence to 1535 execute in order to validate that the result of applying the 1536 update is correct. Typical actions involve image validation. 1537 suit-validate is REQUIRED to implement. 1539 4. Image Loading: suit-load is a SUIT_Command_Sequence to execute in 1540 order to prepare a payload for execution. Typical actions 1541 include copying an image from permanent storage into RAM, 1542 optionally including actions such as decryption or decompression. 1543 suit-load is OPTIONAL to implement. 1545 5. Run or Boot: suit-run is a SUIT_Command_Sequence to execute in 1546 order to run an image. suit-run typically contains a single 1547 instruction: the "run" directive. suit-run is OPTIONAL to 1548 implement. 1550 Goals 1,2 form the Update Procedure. Goals 4,5,6 form the Invocation 1551 Procedure. 1553 Each Command Sequence follows exactly the same structure to ensure 1554 that the parser is as simple as possible. 1556 Lists of commands are constructed from two kinds of element: 1558 1. Conditions that MUST be true and any failure is treated as a 1559 failure of the update/load/invocation 1561 2. Directives that MUST be executed. 1563 Each condition is composed of: 1565 1. A command code identifier 1567 2. A SUIT_Reporting_Policy (Section 8.4.7) 1569 Each directive is composed of: 1571 1. A command code identifier 1573 2. An argument block or a SUIT_Reporting_Policy (Section 8.4.7) 1575 Argument blocks are consumed only by flow-control directives: 1577 * Set Component Index 1579 * Set/Override Parameters 1581 * Try Each 1583 * Run Sequence 1585 Reporting policies provide a hint to the manifest processor of 1586 whether to add the success or failure of a command to any report that 1587 it generates. 1589 Many conditions and directives apply to a given component, and these 1590 generally grouped together. Therefore, a special command to set the 1591 current component index is provided. This index is a numeric index 1592 into the Component Identifier table defined at the beginning of the 1593 manifest. 1595 To facilitate optional conditions, a special directive, suit- 1596 directive-try-each (Section 8.4.10.2), is provided. It runs several 1597 new lists of conditions/directives, one after another, that are 1598 contained as an argument to the directive. By default, it assumes 1599 that a failure of a condition should not indicate a failure of the 1600 update/invocation, but a parameter is provided to override this 1601 behavior. See suit-parameter-soft-failure (Section 8.4.8.14). 1603 8.4.7. Reporting Policy 1605 To facilitate construction of Reports that describe the success or 1606 failure of a given Procedure, each command is given a Reporting 1607 Policy. This is an integer bitfield that follows the command and 1608 indicates what the Recipient should do with the Record of executing 1609 the command. The options are summarized in the table below. 1611 +=============================+==================================+ 1612 | Policy | Description | 1613 +=============================+==================================+ 1614 | suit-send-record-on-success | Record when the command succeeds | 1615 +-----------------------------+----------------------------------+ 1616 | suit-send-record-on-failure | Record when the command fails | 1617 +-----------------------------+----------------------------------+ 1618 | suit-send-sysinfo-success | Add system information when the | 1619 | | command succeeds | 1620 +-----------------------------+----------------------------------+ 1621 | suit-send-sysinfo-failure | Add system information when the | 1622 | | command fails | 1623 +-----------------------------+----------------------------------+ 1625 Table 4 1627 Any or all of these policies may be enabled at once. 1629 At the completion of each command, a Manifest Processor MAY forward 1630 information about the command to a Reporting Engine, which is 1631 responsible for reporting boot or update status to a third party. 1632 The Reporting Engine is entirely implementation-defined, the 1633 reporting policy simply facilitates the Reporting Engine's interface 1634 to the SUIT Manifest Processor. 1636 The information elements provided to the Reporting Engine are: 1638 * The reporting policy 1640 * The result of the command 1642 * The values of parameters consumed by the command 1644 * The system information consumed by the command 1646 Together, these elements are called a Record. A group of Records is 1647 a Report. 1649 If the component index is set to True or an array when a command is 1650 executed with a non-zero reporting policy, then the Reporting Engine 1651 MUST receive one Record for each Component, in the order expressed in 1652 the Components list or the component index array. 1654 This specification does not define a particular format of Records or 1655 Reports. This specification only defines hints to the Reporting 1656 Engine for which Records it should aggregate into the Report. The 1657 Reporting Engine MAY choose to ignore these hints and apply its own 1658 policy instead. 1660 When used in a Invocation Procedure, the report MAY form the basis of 1661 an attestation report. When used in an Update Process, the report 1662 MAY form the basis for one or more log entries. 1664 8.4.8. SUIT_Parameters 1666 Many conditions and directives require additional information. That 1667 information is contained within parameters that can be set in a 1668 consistent way. This allows reuse of parameters between commands, 1669 thus reducing manifest size. 1671 Most parameters are scoped to a specific component. This means that 1672 setting a parameter for one component has no effect on the parameters 1673 of any other component. The only exceptions to this are two Manifest 1674 Processor parameters: Strict Order and Soft Failure. 1676 The defined manifest parameters are described below. 1678 +==============+==================================+=================+ 1679 | Name | CDDL Structure | Reference | 1680 +==============+==================================+=================+ 1681 | Vendor ID | suit-parameter-vendor-identifier | Section 8.4.8.3 | 1682 +--------------+----------------------------------+-----------------+ 1683 | Class ID | suit-parameter-class-identifier | Section 8.4.8.4 | 1684 +--------------+----------------------------------+-----------------+ 1685 | Device ID | suit-parameter-device-identifier | Section 8.4.8.5 | 1686 +--------------+----------------------------------+-----------------+ 1687 | Image | suit-parameter-image-digest | Section 8.4.8.6 | 1688 | Digest | | | 1689 +--------------+----------------------------------+-----------------+ 1690 | Image | suit-parameter-image-size | Section 8.4.8.7 | 1691 | Size | | | 1692 +--------------+----------------------------------+-----------------+ 1693 | Component | suit-parameter-component-slot | Section 8.4.8.8 | 1694 | Slot | | | 1695 +--------------+----------------------------------+-----------------+ 1696 | URI | suit-parameter-uri | Section 8.4.8.9 | 1697 +--------------+----------------------------------+-----------------+ 1698 | Source | suit-parameter-source-component | Section | 1699 | Component | | 8.4.8.10 | 1700 +--------------+----------------------------------+-----------------+ 1701 | Run Args | suit-parameter-run-args | Section | 1702 | | | 8.4.8.11 | 1703 +--------------+----------------------------------+-----------------+ 1704 | Fetch | suit-parameter-fetch-arguments | Section | 1705 | Arguments | | 8.4.8.12 | 1706 +--------------+----------------------------------+-----------------+ 1707 | Strict | suit-parameter-strict-order | Section | 1708 | Order | | 8.4.8.13 | 1709 +--------------+----------------------------------+-----------------+ 1710 | Soft | suit-parameter-soft-failure | Section | 1711 | Failure | | 8.4.8.14 | 1712 +--------------+----------------------------------+-----------------+ 1713 | Custom | suit-parameter-custom | Section | 1714 | | | 8.4.8.15 | 1715 +--------------+----------------------------------+-----------------+ 1717 Table 5 1719 CBOR-encoded object parameters are still wrapped in a bstr. This is 1720 because it allows a parser that is aggregating parameters to 1721 reference the object with a single pointer and traverse it without 1722 understanding the contents. This is important for modularization and 1723 division of responsibility within a pull parser. The same 1724 consideration does not apply to Directives because those elements are 1725 invoked with their arguments immediately. 1727 8.4.8.1. CBOR PEN UUID Namespace Identifier 1729 The CBOR PEN UUID Namespace Identifier is constructed as follows: 1731 It uses the OID Namespace as a starting point, then uses the CBOR OID 1732 encoding for the IANA PEN OID (1.3.6.1.4.1): 1734 D8 6F # tag(111) 1735 45 # bytes(5) 1736 # Absolute OID encoding of IANA Private Enterprise Number: 1737 # 1.3. 6. 1. 4. 1 1738 2B 06 01 04 01 # X.690 Clause 8.19 1740 Computing a type 5 UUID from these produces: 1742 NAMESPACE_CBOR_PEN = UUID5(NAMESPACE_OID, h'D86F452B06010401') 1743 NAMESPACE_CBOR_PEN = 47fbdabb-f2e4-55f0-bb39-3620c2f6df4e 1745 8.4.8.2. Constructing UUIDs 1747 Several conditions use identifiers to determine whether a manifest 1748 matches a given Recipient or not. These identifiers are defined to 1749 be RFC 4122 [RFC4122] UUIDs. These UUIDs are not human-readable and 1750 are therefore used for machine-based processing only. 1752 A Recipient MAY match any number of UUIDs for vendor or class 1753 identifier. This may be relevant to physical or software modules. 1754 For example, a Recipient that has an OS and one or more applications 1755 might list one Vendor ID for the OS and one or more additional Vendor 1756 IDs for the applications. This Recipient might also have a Class ID 1757 that must be matched for the OS and one or more Class IDs for the 1758 applications. 1760 Identifiers are used for compatibility checks. They MUST NOT be used 1761 as assertions of identity. They are evaluated by identifier 1762 conditions (Section 8.4.9.1). 1764 A more complete example: Imagine a device has the following physical 1765 components: 1. A host MCU 2. A WiFi module 1767 This same device has three software modules: 1. An operating system 1768 2. A WiFi module interface driver 3. An application 1770 Suppose that the WiFi module's firmware has a proprietary update 1771 mechanism and doesn't support manifest processing. This device can 1772 report four class IDs: 1774 1. Hardware model/revision 1775 2. OS 1777 3. WiFi module model/revision 1779 4. Application 1781 This allows the OS, WiFi module, and application to be updated 1782 independently. To combat possible incompatibilities, the OS class ID 1783 can be changed each time the OS has a change to its API. 1785 This approach allows a vendor to target, for example, all devices 1786 with a particular WiFi module with an update, which is a very 1787 powerful mechanism, particularly when used for security updates. 1789 UUIDs MUST be created according to RFC 4122 [RFC4122]. UUIDs SHOULD 1790 use versions 3, 4, or 5, as described in RFC4122. Versions 1 and 2 1791 do not provide a tangible benefit over version 4 for this 1792 application. 1794 The RECOMMENDED method to create a vendor ID is: 1796 Vendor ID = UUID5(DNS_PREFIX, vendor domain name) 1798 If the Vendor ID is a UUID, the RECOMMENDED method to create a Class 1799 ID is: 1801 Class ID = UUID5(Vendor ID, Class-Specific-Information) 1803 If the Vendor ID is a CBOR PEN (see Section 8.4.8.3), the RECOMMENDED 1804 method to create a Class ID is: 1806 Class ID = UUID5( 1807 UUID5(NAMESPACE_CBOR_PEN, CBOR_PEN), 1808 Class-Specific-Information) 1810 Class-specific-information is composed of a variety of data, for 1811 example: 1813 * Model number. 1815 * Hardware revision. 1817 * Bootloader version (for immutable bootloaders). 1819 8.4.8.3. suit-parameter-vendor-identifier 1821 suit-parameter-vendor-identifier may be presented in one of two ways: 1823 * A Private Enterprise Number 1825 * A byte string containing a UUID ([RFC4122]) 1827 Private Enterprise Numbers are encoded as a relative OID, according 1828 to the definition in [I-D.ietf-cbor-tags-oid]. All PENs are relative 1829 to the IANA PEN: 1.3.6.1.4.1. 1831 8.4.8.4. suit-parameter-class-identifier 1833 A RFC 4122 UUID representing the class of the device or component. 1834 The UUID is encoded as a 16 byte bstr, containing the raw bytes of 1835 the UUID. It MUST be constructed as described in Section 8.4.8.2 1837 8.4.8.5. suit-parameter-device-identifier 1839 A RFC 4122 UUID representing the specific device or component. The 1840 UUID is encoded as a 16 byte bstr, containing the raw bytes of the 1841 UUID. It MUST be constructed as described in Section 8.4.8.2 1843 8.4.8.6. suit-parameter-image-digest 1845 A fingerprint computed over the component itself, encoded in the 1846 SUIT_Digest Section 10 structure. The SUIT_Digest is wrapped in a 1847 bstr, as required in Section 8.4.8. 1849 8.4.8.7. suit-parameter-image-size 1851 The size of the firmware image in bytes. This size is encoded as a 1852 positive integer. 1854 8.4.8.8. suit-parameter-component-slot 1856 This parameter sets the slot index of a component. Some components 1857 support multiple possible Slots (offsets into a storage area). This 1858 parameter describes the intended Slot to use, identified by its index 1859 into the component's storage area. This slot MUST be encoded as a 1860 positive integer. 1862 8.4.8.9. suit-parameter-uri 1864 A URI Reference ([RFC3986]) from which to fetch a resource, encoded 1865 as a text string. CBOR Tag 32 is not used because the meaning of the 1866 text string is unambiguous in this context. 1868 8.4.8.10. suit-parameter-source-component 1870 This parameter sets the source component to be used with either suit- 1871 directive-copy (Section 8.4.10.5) or with suit-directive-swap 1872 (Section 8.4.10.8). The current Component, as set by suit-directive- 1873 set-component-index defines the destination, and suit-parameter- 1874 source-component defines the source. 1876 8.4.8.11. suit-parameter-run-args 1878 This parameter contains an encoded set of arguments for suit- 1879 directive-run (Section 8.4.10.6). The arguments MUST be provided as 1880 an implementation-defined bstr. 1882 8.4.8.12. suit-parameter-fetch-arguments 1884 An implementation-defined set of arguments to suit-directive-fetch 1885 (Section 8.4.10.4). Arguments are encoded in a bstr. 1887 8.4.8.13. suit-parameter-strict-order 1889 The Strict Order Parameter allows a manifest to govern when 1890 directives can be executed out-of-order. This allows for systems 1891 that have a sensitivity to order of updates to choose the order in 1892 which they are executed. It also allows for more advanced systems to 1893 parallelize their handling of updates. Strict Order defaults to 1894 True. It MAY be set to False when the order of operations does not 1895 matter. When arriving at the end of a command sequence, ALL commands 1896 MUST have completed, regardless of the state of 1897 SUIT_Parameter_Strict_Order. If SUIT_Parameter_Strict_Order is 1898 returned to True, ALL preceding commands MUST complete before the 1899 next command is executed. 1901 See Section 6.7 for behavioral description of Strict Order. 1903 8.4.8.14. suit-parameter-soft-failure 1905 When executing a command sequence inside suit-directive-try-each 1906 (Section 8.4.10.2) or suit-directive-run-sequence (Section 8.4.10.7) 1907 and a condition failure occurs, the manifest processor aborts the 1908 sequence. For suit-directive-try-each, if Soft Failure is True, the 1909 next sequence in Try Each is invoked, otherwise suit-directive-try- 1910 each fails with the condition failure code. In suit-directive-run- 1911 sequence, if Soft Failure is True the suit-directive-run-sequence 1912 simply halts with no side-effects and the Manifest Processor 1913 continues with the following command, otherwise, the suit-directive- 1914 run-sequence fails with the condition failure code. 1916 suit-parameter-soft-failure is scoped to the enclosing 1917 SUIT_Command_Sequence. Its value is discarded when 1918 SUIT_Command_Sequence terminates. It MUST NOT be set outside of 1919 suit-directive-try-each or suit-directive-run-sequence. 1921 When suit-directive-try-each is invoked, Soft Failure defaults to 1922 True. An Update Author may choose to set Soft Failure to False if 1923 they require a failed condition in a sequence to force an Abort. 1925 When suit-directive-run-sequence is invoked, Soft Failure defaults to 1926 False. An Update Author may choose to make failures soft within a 1927 suit-directive-run-sequence. 1929 8.4.8.15. suit-parameter-custom 1931 This parameter is an extension point for any proprietary, application 1932 specific conditions and directives. It MUST NOT be used in the 1933 common sequence. This effectively scopes each custom command to a 1934 particular Vendor Identifier/Class Identifier pair. 1936 8.4.9. SUIT_Condition 1938 Conditions are used to define mandatory properties of a system in 1939 order for an update to be applied. They can be pre-conditions or 1940 post-conditions of any directive or series of directives, depending 1941 on where they are placed in the list. All Conditions specify a 1942 Reporting Policy as described Section 8.4.7. Conditions include: 1944 +===================+==================================+===========+ 1945 | Name | CDDL Structure | Reference | 1946 +===================+==================================+===========+ 1947 | Vendor Identifier | suit-condition-vendor-identifier | Section | 1948 | | | 8.4.9.1 | 1949 +-------------------+----------------------------------+-----------+ 1950 | Class Identifier | suit-condition-class-identifier | Section | 1951 | | | 8.4.9.1 | 1952 +-------------------+----------------------------------+-----------+ 1953 | Device Identifier | suit-condition-device-identifier | Section | 1954 | | | 8.4.9.1 | 1955 +-------------------+----------------------------------+-----------+ 1956 | Image Match | suit-condition-image-match | Section | 1957 | | | 8.4.9.2 | 1958 +-------------------+----------------------------------+-----------+ 1959 | Component Slot | suit-condition-component-slot | Section | 1960 | | | 8.4.9.3 | 1961 +-------------------+----------------------------------+-----------+ 1962 | Abort | suit-condition-abort | Section | 1963 | | | 8.4.9.4 | 1964 +-------------------+----------------------------------+-----------+ 1965 | Custom Condition | suit-condition-custom | Section | 1966 | | | 8.4.9.5 | 1967 +-------------------+----------------------------------+-----------+ 1969 Table 6 1971 The abstract description of these conditions is defined in 1972 Section 6.4. 1974 Conditions compare parameters against properties of the system. 1975 These properties may be asserted in many different ways, including: 1976 calculation on-demand, volatile definition in memory, static 1977 definition within the manifest processor, storage in known location 1978 within an image, storage within a key storage system, storage in One- 1979 Time-Programmable memory, inclusion in mask ROM, or inclusion as a 1980 register in hardware. Some of these assertion methods are global in 1981 scope, such as a hardware register, some are scoped to an individual 1982 component, such as storage at a known location in an image, and some 1983 assertion methods can be either global or component-scope, based on 1984 implementation. 1986 Each condition MUST report a result code on completion. If a 1987 condition reports failure, then the current sequence of commands MUST 1988 terminate. A subsequent command or command sequence MAY continue 1989 executing if suit-parameter-soft-failure (Section 8.4.8.14) is set. 1990 If a condition requires additional information, this MUST be 1991 specified in one or more parameters before the condition is executed. 1993 If a Recipient attempts to process a condition that expects 1994 additional information and that information has not been set, it MUST 1995 report a failure. If a Recipient encounters an unknown condition, it 1996 MUST report a failure. 1998 Condition labels in the positive number range are reserved for IANA 1999 registration while those in the negative range are custom conditions 2000 reserved for proprietary definition by the author of a manifest 2001 processor. See Section 11 for more details. 2003 8.4.9.1. suit-condition-vendor-identifier, suit-condition-class- 2004 identifier, and suit-condition-device-identifier 2006 There are three identifier-based conditions: suit-condition-vendor- 2007 identifier, suit-condition-class-identifier, and suit-condition- 2008 device-identifier. Each of these conditions match a RFC 4122 2009 [RFC4122] UUID that MUST have already been set as a parameter. The 2010 installing Recipient MUST match the specified UUID in order to 2011 consider the manifest valid. These identifiers are scoped by 2012 component in the manifest. Each component MAY match more than one 2013 identifier. Care is needed to ensure that manifests correctly 2014 identify their targets using these conditions. Using only a generic 2015 class ID for a device-specific firmware could result in matching 2016 devices that are not compatible. 2018 The Recipient uses the ID parameter that has already been set using 2019 the Set Parameters directive. If no ID has been set, this condition 2020 fails. suit-condition-class-identifier and suit-condition-vendor- 2021 identifier are REQUIRED to implement. suit-condition-device- 2022 identifier is OPTIONAL to implement. 2024 Each identifier condition compares the corresponding identifier 2025 parameter to a parameter asserted to the Manifest Processor by the 2026 Recipient. Identifiers MUST be known to the Manifest Processor in 2027 order to evaluate compatibility. 2029 8.4.9.2. suit-condition-image-match 2031 Verify that the current component matches the suit-parameter-image- 2032 digest (Section 8.4.8.6) for the current component. The digest is 2033 verified against the digest specified in the Component's parameters 2034 list. If no digest is specified, the condition fails. suit- 2035 condition-image-match is REQUIRED to implement. 2037 8.4.9.3. suit-condition-component-slot 2039 Verify that the slot index of the current component matches the slot 2040 index set in suit-parameter-component-slot (Section 8.4.8.8). This 2041 condition allows a manifest to select between several images to match 2042 a target slot. 2044 8.4.9.4. suit-condition-abort 2046 Unconditionally fail. This operation is typically used in 2047 conjunction with suit-directive-try-each (Section 8.4.10.2). 2049 8.4.9.5. suit-condition-custom 2051 suit-condition-custom describes any proprietary, application specific 2052 condition. This is encoded as a negative integer, chosen by the 2053 firmware developer. If additional information must be provided to 2054 the condition, it should be encoded in a custom parameter (a nint) as 2055 described in Section 8.4.8. SUIT_Condition_Custom is OPTIONAL to 2056 implement. 2058 8.4.10. SUIT_Directive 2060 Directives are used to define the behavior of the recipient. 2061 Directives include: 2063 +===============+====================================+===========+ 2064 | Name | CDDL Structure | Reference | 2065 +===============+====================================+===========+ 2066 | Set Component | suit-directive-set-component-index | Section | 2067 | Index | | 8.4.10.1 | 2068 +---------------+------------------------------------+-----------+ 2069 | Try Each | suit-directive-try-each | Section | 2070 | | | 8.4.10.2 | 2071 +---------------+------------------------------------+-----------+ 2072 | Override | suit-directive-override-parameters | Section | 2073 | Parameters | | 8.4.10.3 | 2074 +---------------+------------------------------------+-----------+ 2075 | Fetch | suit-directive-fetch | Section | 2076 | | | 8.4.10.4 | 2077 +---------------+------------------------------------+-----------+ 2078 | Copy | suit-directive-copy | Section | 2079 | | | 8.4.10.5 | 2080 +---------------+------------------------------------+-----------+ 2081 | Run | suit-directive-run | Section | 2082 | | | 8.4.10.6 | 2083 +---------------+------------------------------------+-----------+ 2084 | Run Sequence | suit-directive-run-sequence | Section | 2085 | | | 8.4.10.7 | 2086 +---------------+------------------------------------+-----------+ 2087 | Swap | suit-directive-swap | Section | 2088 | | | 8.4.10.8 | 2089 +---------------+------------------------------------+-----------+ 2091 Table 7 2093 The abstract description of these commands is defined in Section 6.4. 2095 When a Recipient executes a Directive, it MUST report a result code. 2096 If the Directive reports failure, then the current Command Sequence 2097 MUST be terminated. 2099 8.4.10.1. suit-directive-set-component-index 2101 Set Component Index defines the component to which successive 2102 directives and conditions will apply. The supplied argument MUST be 2103 one of three types: 2105 1. An unsigned integer (REQUIRED to implement in parser) 2107 2. A boolean (REQUIRED to implement in parser ONLY IF 2 or more 2108 components supported) 2110 3. An array of unsigned integers (REQUIRED to implement in parser 2111 ONLY IF 3 or more components supported) 2113 If the following commands apply to ONE component, an unsigned integer 2114 index into the component list is used. If the following commands 2115 apply to ALL components, then the boolean value "True" is used 2116 instead of an index. If the following commands apply to more than 2117 one, but not all components, then an array of unsigned integer 2118 indices into the component list is used. See Section 6.5 for more 2119 details. 2121 If component index is set to True when a command is invoked, then the 2122 command applies to all components, in the order they appear in suit- 2123 common-components. When the Manifest Processor invokes a command 2124 while the component index is set to True, it must execute the command 2125 once for each possible component index, ensuring that the command 2126 receives the parameters corresponding to that component index. 2128 8.4.10.2. suit-directive-try-each 2130 This command runs several SUIT_Command_Sequence instances, one after 2131 another, in a strict order. Use this command to implement a "try/ 2132 catch-try/catch" sequence. Manifest processors MAY implement this 2133 command. 2135 suit-parameter-soft-failure (Section 8.4.8.14) is initialized to True 2136 at the beginning of each sequence. If one sequence aborts due to a 2137 condition failure, the next is started. If no sequence completes 2138 without condition failure, then suit-directive-try-each returns an 2139 error. If a particular application calls for all sequences to fail 2140 and still continue, then an empty sequence (nil) can be added to the 2141 Try Each Argument. 2143 The argument to suit-directive-try-each is a list of 2144 SUIT_Command_Sequence. suit-directive-try-each does not specify a 2145 reporting policy. 2147 8.4.10.3. suit-directive-override-parameters 2149 suit-directive-override-parameters replaces any listed parameters 2150 that are already set with the values that are provided in its 2151 argument. This allows a manifest to prevent replacement of critical 2152 parameters. 2154 Available parameters are defined in Section 8.4.8. 2156 suit-directive-override-parameters does not specify a reporting 2157 policy. 2159 8.4.10.4. suit-directive-fetch 2161 suit-directive-fetch instructs the manifest processor to obtain one 2162 or more manifests or payloads, as specified by the manifest index and 2163 component index, respectively. 2165 suit-directive-fetch can target one or more payloads. suit-directive- 2166 fetch retrieves each component listed in component-index. If 2167 component-index is True, instead of an integer, then all current 2168 manifest components are fetched. If component-index is an array, 2169 then all listed components are fetched. 2171 suit-directive-fetch typically takes no arguments unless one is 2172 needed to modify fetch behavior. If an argument is needed, it must 2173 be wrapped in a bstr and set in suit-parameter-fetch-arguments. 2175 suit-directive-fetch reads the URI parameter to find the source of 2176 the fetch it performs. 2178 8.4.10.5. suit-directive-copy 2180 suit-directive-copy instructs the manifest processor to obtain one or 2181 more payloads, as specified by the component index. As described in 2182 Section 6.5 component index may be a single integer, a list of 2183 integers, or True. suit-directive-copy retrieves each component 2184 specified by the current component-index, respectively. 2186 suit-directive-copy reads its source from suit-parameter-source- 2187 component (Section 8.4.8.10). 2189 If either the source component parameter or the source component 2190 itself is absent, this command fails. 2192 8.4.10.6. suit-directive-run 2194 suit-directive-run directs the manifest processor to transfer 2195 execution to the current Component Index. When this is invoked, the 2196 manifest processor MAY be unloaded and execution continues in the 2197 Component Index. Arguments are provided to suit-directive-run 2198 through suit-parameter-run-arguments (Section 8.4.8.11) and are 2199 forwarded to the executable code located in Component Index in an 2200 application-specific way. For example, this could form the Linux 2201 Kernel Command Line if booting a Linux device. 2203 If the executable code at Component Index is constructed in such a 2204 way that it does not unload the manifest processor, then the manifest 2205 processor may resume execution after the executable completes. This 2206 allows the manifest processor to invoke suitable helpers and to 2207 verify them with image conditions. 2209 8.4.10.7. suit-directive-run-sequence 2211 To enable conditional commands, and to allow several strictly ordered 2212 sequences to be executed out-of-order, suit-directive-run-sequence 2213 allows the manifest processor to execute its argument as a 2214 SUIT_Command_Sequence. The argument must be wrapped in a bstr. 2216 When a sequence is executed, any failure of a condition causes 2217 immediate termination of the sequence. 2219 When suit-directive-run-sequence completes, it forwards the last 2220 status code that occurred in the sequence. If the Soft Failure 2221 parameter is true, then suit-directive-run-sequence only fails when a 2222 directive in the argument sequence fails. 2224 suit-parameter-soft-failure (Section 8.4.8.14) defaults to False when 2225 suit-directive-run-sequence begins. Its value is discarded when 2226 suit-directive-run-sequence terminates. 2228 8.4.10.8. suit-directive-swap 2230 suit-directive-swap instructs the manifest processor to move the 2231 source to the destination and the destination to the source 2232 simultaneously. Swap has nearly identical semantics to suit- 2233 directive-copy except that suit-directive-swap replaces the source 2234 with the current contents of the destination in an application- 2235 defined way. As with suit-directive-copy, if the source component is 2236 missing, this command fails. 2238 If SUIT_Parameter_Compression_Info or SUIT_Parameter_Encryption_Info 2239 are present, they MUST be handled in a symmetric way, so that the 2240 source is decompressed into the destination and the destination is 2241 compressed into the source. The source is decrypted into the 2242 destination and the destination is encrypted into the source. suit- 2243 directive-swap is OPTIONAL to implement. 2245 8.4.11. Integrity Check Values 2247 When the Text section or any Command Sequence of the Update Procedure 2248 is made severable, it is moved to the Envelope and replaced with a 2249 SUIT_Digest. The SUIT_Digest is computed over the entire bstr 2250 enclosing the Manifest element that has been moved to the Envelope. 2251 Each element that is made severable from the Manifest is placed in 2252 the Envelope. The keys for the envelope elements have the same 2253 values as the keys for the manifest elements. 2255 Each Integrity Check Value covers the corresponding Envelope Element 2256 as described in Section 8.5. 2258 8.5. Severable Elements 2260 Because the manifest can be used by different actors at different 2261 times, some parts of the manifest can be removed or "Severed" without 2262 affecting later stages of the lifecycle. Severing of information is 2263 achieved by separating that information from the signed container so 2264 that removing it does not affect the signature. This means that 2265 ensuring integrity of severable parts of the manifest is a 2266 requirement for the signed portion of the manifest. Severing some 2267 parts makes it possible to discard parts of the manifest that are no 2268 longer necessary. This is important because it allows the storage 2269 used by the manifest to be greatly reduced. For example, no text 2270 size limits are needed if text is removed from the manifest prior to 2271 delivery to a constrained device. 2273 Elements are made severable by removing them from the manifest, 2274 encoding them in a bstr, and placing a SUIT_Digest of the bstr in the 2275 manifest so that they can still be authenticated. The SUIT_Digest 2276 typically consumes 4 bytes more than the size of the raw digest, 2277 therefore elements smaller than (Digest Bits)/8 + 4 SHOULD NOT be 2278 severable. Elements larger than (Digest Bits)/8 + 4 MAY be 2279 severable, while elements that are much larger than (Digest Bits)/8 + 2280 4 SHOULD be severable. 2282 Because of this, all command sequences in the manifest are encoded in 2283 a bstr so that there is a single code path needed for all command 2284 sequences. 2286 9. Access Control Lists 2288 To manage permissions in the manifest, there are three models that 2289 can be used. 2291 First, the simplest model requires that all manifests are 2292 authenticated by a single trusted key. This mode has the advantage 2293 that only a root manifest needs to be authenticated, since all of its 2294 dependencies have digests included in the root manifest. 2296 This simplest model can be extended by adding key delegation without 2297 much increase in complexity. 2299 A second model requires an ACL to be presented to the Recipient, 2300 authenticated by a trusted party or stored on the Recipient. This 2301 ACL grants access rights for specific component IDs or Component 2302 Identifier prefixes to the listed identities or identity groups. Any 2303 identity can verify an image digest, but fetching into or fetching 2304 from a Component Identifier requires approval from the ACL. 2306 A third model allows a Recipient to provide even more fine-grained 2307 controls: The ACL lists the Component Identifier or Component 2308 Identifier prefix that an identity can use, and also lists the 2309 commands and parameters that the identity can use in combination with 2310 that Component Identifier. 2312 10. SUIT Digest Container 2314 The SUIT digest is a CBOR List containing two elements: an algorithm 2315 identifier and a bstr containing the bytes of the digest. Some forms 2316 of digest may require additional parameters. These can be added 2317 following the digest. 2319 The values of the algorithm identifier are defined by 2320 [I-D.ietf-cose-hash-algs]. The following algorithms MUST be 2321 implemented by all Manifest Processors: 2323 * SHA-256 (-16) 2325 The following algorithms MAY be implemented in a Manifest Processor: 2327 * SHAKE128 (-18) 2329 * SHA-384 (-43) 2331 * SHA-512 (-44) 2333 * SHAKE256 (-45) 2335 11. IANA Considerations 2337 IANA is requested to: 2339 * allocate CBOR tag 107 in the CBOR Tags registry for the SUIT 2340 Envelope. 2342 * allocate CBOR tag 1070 in the CBOR Tags registry for the SUIT 2343 Manifest. 2345 * allocate media type application/suit-envelope in the Media Types 2346 registry. 2348 * setup several registries as described below. 2350 IANA is requested to setup a registry for SUIT manifests. Several 2351 registries defined in the subsections below need to be created. 2353 For each registry, values 0-23 are Standards Action, 24-255 are IETF 2354 Review, 256-65535 are Expert Review, and 65536 or greater are First 2355 Come First Served. 2357 Negative values -23 to 0 are Experimental Use, -24 and lower are 2358 Private Use. 2360 11.1. SUIT Commands 2362 +=======+=====================+==================+ 2363 | Label | Name | Reference | 2364 +=======+=====================+==================+ 2365 | 1 | Vendor Identifier | Section 8.4.9.1 | 2366 +-------+---------------------+------------------+ 2367 | 2 | Class Identifier | Section 8.4.9.1 | 2368 +-------+---------------------+------------------+ 2369 | 3 | Image Match | Section 8.4.9.2 | 2370 +-------+---------------------+------------------+ 2371 | 4 | Reserved | | 2372 +-------+---------------------+------------------+ 2373 | 5 | Component Slot | Section 8.4.9.3 | 2374 +-------+---------------------+------------------+ 2375 | 12 | Set Component Index | Section 8.4.10.1 | 2376 +-------+---------------------+------------------+ 2377 | 13 | Reserved | | 2378 +-------+---------------------+------------------+ 2379 | 14 | Abort | | 2380 +-------+---------------------+------------------+ 2381 | 15 | Try Each | Section 8.4.10.2 | 2382 +-------+---------------------+------------------+ 2383 | 16 | Reserved | | 2384 +-------+---------------------+------------------+ 2385 | 17 | Reserved | | 2386 +-------+---------------------+------------------+ 2387 | 18 | Reserved | | 2388 +-------+---------------------+------------------+ 2389 | 19 | Reserved | | 2390 +-------+---------------------+------------------+ 2391 | 20 | Override Parameters | Section 8.4.10.3 | 2392 +-------+---------------------+------------------+ 2393 | 21 | Fetch | Section 8.4.10.4 | 2394 +-------+---------------------+------------------+ 2395 | 22 | Copy | Section 8.4.10.5 | 2396 +-------+---------------------+------------------+ 2397 | 23 | Run | Section 8.4.10.6 | 2398 +-------+---------------------+------------------+ 2399 | 24 | Device Identifier | Section 8.4.9.1 | 2400 +-------+---------------------+------------------+ 2401 | 25 | Reserved | | 2402 +-------+---------------------+------------------+ 2403 | 26 | Reserved | | 2404 +-------+---------------------+------------------+ 2405 | 27 | Reserved | | 2406 +-------+---------------------+------------------+ 2407 | 28 | Reserved | | 2408 +-------+---------------------+------------------+ 2409 | 29 | Reserved | | 2410 +-------+---------------------+------------------+ 2411 | 30 | Reserved | | 2412 +-------+---------------------+------------------+ 2413 | 31 | Swap | Section 8.4.10.8 | 2414 +-------+---------------------+------------------+ 2415 | 32 | Run Sequence | Section 8.4.10.7 | 2416 +-------+---------------------+------------------+ 2417 | 33 | Reserved | | 2418 +-------+---------------------+------------------+ 2419 | nint | Custom Condition | Section 8.4.9.5 | 2420 +-------+---------------------+------------------+ 2422 Table 8 2424 11.2. SUIT Parameters 2426 +=======+==================+==================+ 2427 | Label | Name | Reference | 2428 +=======+==================+==================+ 2429 | 1 | Vendor ID | Section 8.4.8.3 | 2430 +-------+------------------+------------------+ 2431 | 2 | Class ID | Section 8.4.8.4 | 2432 +-------+------------------+------------------+ 2433 | 3 | Image Digest | Section 8.4.8.6 | 2434 +-------+------------------+------------------+ 2435 | 4 | Reserved | | 2436 +-------+------------------+------------------+ 2437 | 5 | Component Slot | Section 8.4.8.8 | 2438 +-------+------------------+------------------+ 2439 | 12 | Strict Order | Section 8.4.8.13 | 2440 +-------+------------------+------------------+ 2441 | 13 | Soft Failure | Section 8.4.8.14 | 2442 +-------+------------------+------------------+ 2443 | 14 | Image Size | Section 8.4.8.7 | 2444 +-------+------------------+------------------+ 2445 | 18 | Reserved | | 2446 +-------+------------------+------------------+ 2447 | 19 | Reserved | | 2448 +-------+------------------+------------------+ 2449 | 20 | Reserved | | 2450 +-------+------------------+------------------+ 2451 | 21 | URI | Section 8.4.8.9 | 2452 +-------+------------------+------------------+ 2453 | 22 | Source Component | Section 8.4.8.10 | 2454 +-------+------------------+------------------+ 2455 | 23 | Run Args | Section 8.4.8.11 | 2456 +-------+------------------+------------------+ 2457 | 24 | Device ID | Section 8.4.8.5 | 2458 +-------+------------------+------------------+ 2459 | 26 | Reserved | | 2460 +-------+------------------+------------------+ 2461 | 27 | Reserved | | 2462 +-------+------------------+------------------+ 2463 | 28 | Reserved | | 2464 +-------+------------------+------------------+ 2465 | 29 | Reserved | | 2466 +-------+------------------+------------------+ 2467 | 30 | Reserved | | 2468 +-------+------------------+------------------+ 2469 | nint | Custom | Section 8.4.8.15 | 2470 +-------+------------------+------------------+ 2472 Table 9 2474 11.3. SUIT Text Values 2476 +=======+======================+===============+ 2477 | Label | Name | Reference | 2478 +=======+======================+===============+ 2479 | 1 | Manifest Description | Section 8.4.4 | 2480 +-------+----------------------+---------------+ 2481 | 2 | Update Description | Section 8.4.4 | 2482 +-------+----------------------+---------------+ 2483 | 3 | Manifest JSON Source | Section 8.4.4 | 2484 +-------+----------------------+---------------+ 2485 | 4 | Manifest YAML Source | Section 8.4.4 | 2486 +-------+----------------------+---------------+ 2487 | nint | Custom | Section 8.4.4 | 2488 +-------+----------------------+---------------+ 2490 Table 10 2492 11.4. SUIT Component Text Values 2494 +=======+============================+===============+ 2495 | Label | Name | Reference | 2496 +=======+============================+===============+ 2497 | 1 | Vendor Name | Section 8.4.4 | 2498 +-------+----------------------------+---------------+ 2499 | 2 | Model Name | Section 8.4.4 | 2500 +-------+----------------------------+---------------+ 2501 | 3 | Vendor Domain | Section 8.4.4 | 2502 +-------+----------------------------+---------------+ 2503 | 4 | Model Info | Section 8.4.4 | 2504 +-------+----------------------------+---------------+ 2505 | 5 | Component Description | Section 8.4.4 | 2506 +-------+----------------------------+---------------+ 2507 | 6 | Component Version | Section 8.4.4 | 2508 +-------+----------------------------+---------------+ 2509 | 7 | Component Version Required | Section 8.4.4 | 2510 +-------+----------------------------+---------------+ 2511 | nint | Custom | Section 8.4.4 | 2512 +-------+----------------------------+---------------+ 2514 Table 11 2516 12. Security Considerations 2518 This document is about a manifest format protecting and describing 2519 how to retrieve, install, and invoke firmware images and as such it 2520 is part of a larger solution for delivering firmware updates to IoT 2521 devices. A detailed security treatment can be found in the 2522 architecture [RFC9019] and in the information model 2523 [I-D.ietf-suit-information-model] documents. 2525 13. Acknowledgements 2527 We would like to thank the following persons for their support in 2528 designing this mechanism: 2530 * Milosch Meriac 2531 * Geraint Luff 2533 * Dan Ros 2535 * John-Paul Stanford 2537 * Hugo Vincent 2539 * Carsten Bormann 2541 * Oeyvind Roenningstad 2543 * Frank Audun Kvamtroe 2545 * Krzysztof Chruściński 2547 * Andrzej Puzdrowski 2549 * Michael Richardson 2551 * David Brown 2553 * Emmanuel Baccelli 2555 14. References 2557 14.1. Normative References 2559 [I-D.ietf-suit-information-model] 2560 Moran, B., Tschofenig, H., and H. Birkholz, "A Manifest 2561 Information Model for Firmware Updates in IoT Devices", 2562 Work in Progress, Internet-Draft, draft-ietf-suit- 2563 information-model-13, 8 July 2021, 2564 . 2567 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2568 Requirement Levels", BCP 14, RFC 2119, 2569 DOI 10.17487/RFC2119, March 1997, 2570 . 2572 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2573 Resource Identifier (URI): Generic Syntax", STD 66, 2574 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2575 . 2577 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 2578 Unique IDentifier (UUID) URN Namespace", RFC 4122, 2579 DOI 10.17487/RFC4122, July 2005, 2580 . 2582 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 2583 RFC 8152, DOI 10.17487/RFC8152, July 2017, 2584 . 2586 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2587 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2588 May 2017, . 2590 [RFC9019] Moran, B., Tschofenig, H., Brown, D., and M. Meriac, "A 2591 Firmware Update Architecture for Internet of Things", 2592 RFC 9019, DOI 10.17487/RFC9019, April 2021, 2593 . 2595 14.2. Informative References 2597 [I-D.ietf-cbor-tags-oid] 2598 Bormann, C., "Concise Binary Object Representation (CBOR) 2599 Tags for Object Identifiers", Work in Progress, Internet- 2600 Draft, draft-ietf-cbor-tags-oid-08, 21 May 2021, 2601 . 2604 [I-D.ietf-cose-hash-algs] 2605 Schaad, J., "CBOR Object Signing and Encryption (COSE): 2606 Hash Algorithms", Work in Progress, Internet-Draft, draft- 2607 ietf-cose-hash-algs-09, 14 September 2020, 2608 . 2611 [I-D.ietf-suit-firmware-encryption] 2612 Tschofenig, H., Housley, R., and B. Moran, "Firmware 2613 Encryption with SUIT Manifests", Work in Progress, 2614 Internet-Draft, draft-ietf-suit-firmware-encryption-02, 25 2615 October 2021, . 2618 [I-D.ietf-teep-architecture] 2619 Pei, M., Tschofenig, H., Thaler, D., and D. Wheeler, 2620 "Trusted Execution Environment Provisioning (TEEP) 2621 Architecture", Work in Progress, Internet-Draft, draft- 2622 ietf-teep-architecture-15, 12 July 2021, 2623 . 2626 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 2627 Constrained-Node Networks", RFC 7228, 2628 DOI 10.17487/RFC7228, May 2014, 2629 . 2631 [YAML] "YAML Ain't Markup Language", 2020, . 2633 Appendix A. A. Full CDDL 2635 In order to create a valid SUIT Manifest document the structure of 2636 the corresponding CBOR message MUST adhere to the following CDDL data 2637 definition. 2639 To be valid, the following CDDL MUST have the COSE CDDL appended to 2640 it. The COSE CDDL can be obtained by following the directions in 2641 [RFC8152], section 1.4. 2643 SUIT_Envelope_Tagged = #6.107(SUIT_Envelope) 2644 SUIT_Envelope = { 2645 ? suit-delegation => bstr .cbor SUIT_Delegation, 2646 suit-authentication-wrapper => bstr .cbor SUIT_Authentication, 2647 suit-manifest => bstr .cbor SUIT_Manifest, 2648 SUIT_Severable_Manifest_Members, 2649 * SUIT_Integrated_Payload, 2650 * $$SUIT_Envelope_Extensions, 2651 * (int => bstr) 2652 } 2654 SUIT_Authentication = [ 2655 bstr .cbor SUIT_Digest, 2656 * bstr .cbor SUIT_Authentication_Block 2657 ] 2659 SUIT_Digest = [ 2660 suit-digest-algorithm-id : suit-cose-hash-algs, 2661 suit-digest-bytes : bstr, 2662 * $$SUIT_Digest-extensions 2663 ] 2665 SUIT_Authentication_Block /= COSE_Mac_Tagged 2666 SUIT_Authentication_Block /= COSE_Sign_Tagged 2667 SUIT_Authentication_Block /= COSE_Mac0_Tagged 2668 SUIT_Authentication_Block /= COSE_Sign1_Tagged 2670 SUIT_Severable_Manifest_Members = ( 2671 ? suit-payload-fetch => bstr .cbor SUIT_Command_Sequence, 2672 ? suit-install => bstr .cbor SUIT_Command_Sequence, 2673 ? suit-text => bstr .cbor SUIT_Text_Map, 2674 * $$SUIT_severable-members-extensions, 2675 ) 2677 SUIT_Integrated_Payload = (suit-integrated-payload-key => bstr) 2678 suit-integrated-payload-key = tstr 2680 SUIT_Manifest_Tagged = #6.1070(SUIT_Manifest) 2682 SUIT_Manifest = { 2683 suit-manifest-version => 1, 2684 suit-manifest-sequence-number => uint, 2685 suit-common => bstr .cbor SUIT_Common, 2686 ? suit-reference-uri => tstr, 2687 SUIT_Severable_Members_Choice, 2688 SUIT_Unseverable_Members, 2689 * $$SUIT_Manifest_Extensions, 2690 } 2692 SUIT_Unseverable_Members = ( 2693 ? suit-validate => bstr .cbor SUIT_Command_Sequence, 2694 ? suit-load => bstr .cbor SUIT_Command_Sequence, 2695 ? suit-run => bstr .cbor SUIT_Command_Sequence, 2696 * $$unseverable-manifest-member-extensions, 2697 ) 2699 SUIT_Severable_Members_Choice = ( 2700 ? suit-payload-fetch => \ 2701 bstr .cbor SUIT_Command_Sequence / SUIT_Digest, 2702 ? suit-install => bstr .cbor SUIT_Command_Sequence / SUIT_Digest, 2703 ? suit-text => bstr .cbor SUIT_Command_Sequence / SUIT_Digest, 2704 * $$severable-manifest-members-choice-extensions 2705 ) 2707 SUIT_Common = { 2708 ? suit-components => SUIT_Components, 2709 ? suit-common-sequence => bstr .cbor SUIT_Common_Sequence, 2710 * $$SUIT_Common-extensions, 2711 } 2713 SUIT_Components = [ + SUIT_Component_Identifier ] 2715 SUIT_Dependency = { 2716 suit-dependency-digest => SUIT_Digest, 2717 ? suit-dependency-prefix => SUIT_Component_Identifier, 2718 * $$SUIT_Dependency-extensions, 2719 } 2721 ;REQUIRED to implement: 2723 suit-cose-hash-algs /= cose-alg-sha-256 2725 ;OPTIONAL to implement: 2726 suit-cose-hash-algs /= cose-alg-shake128 2727 suit-cose-hash-algs /= cose-alg-sha-384 2728 suit-cose-hash-algs /= cose-alg-sha-512 2729 suit-cose-hash-algs /= cose-alg-shake256 2731 SUIT_Component_Identifier = [* bstr] 2733 SUIT_Common_Sequence = [ 2734 + ( SUIT_Condition // SUIT_Common_Commands ) 2735 ] 2737 SUIT_Common_Commands //= (suit-directive-set-component-index, IndexArg) 2738 SUIT_Common_Commands //= (suit-directive-run-sequence, 2739 bstr .cbor SUIT_Command_Sequence) 2740 SUIT_Common_Commands //= (suit-directive-try-each, 2741 SUIT_Directive_Try_Each_Argument) 2742 SUIT_Common_Commands //= (suit-directive-override-parameters, 2743 {+ SUIT_Parameters}) 2745 IndexArg /= uint 2746 IndexArg /= bool 2747 IndexArg /= [+uint] 2749 SUIT_Command_Sequence = [ + ( 2750 SUIT_Condition // SUIT_Directive // SUIT_Command_Custom 2751 ) ] 2753 SUIT_Command_Custom = (suit-command-custom, bstr/tstr/int/nil) 2754 SUIT_Condition //= (suit-condition-vendor-identifier, SUIT_Rep_Policy) 2755 SUIT_Condition //= (suit-condition-class-identifier, SUIT_Rep_Policy) 2756 SUIT_Condition //= (suit-condition-device-identifier, SUIT_Rep_Policy) 2757 SUIT_Condition //= (suit-condition-image-match, SUIT_Rep_Policy) 2758 SUIT_Condition //= (suit-condition-component-slot, SUIT_Rep_Policy) 2759 SUIT_Condition //= (suit-condition-abort, SUIT_Rep_Policy) 2761 SUIT_Directive //= (suit-directive-set-component-index, IndexArg) 2762 SUIT_Directive //= (suit-directive-run-sequence, 2763 bstr .cbor SUIT_Command_Sequence) 2764 SUIT_Directive //= (suit-directive-try-each, 2765 SUIT_Directive_Try_Each_Argument) 2766 SUIT_Directive //= (suit-directive-process-dependency, SUIT_Rep_Policy) 2767 SUIT_Directive //= (suit-directive-override-parameters, 2768 {+ SUIT_Parameters}) 2769 SUIT_Directive //= (suit-directive-fetch, SUIT_Rep_Policy) 2770 SUIT_Directive //= (suit-directive-copy, SUIT_Rep_Policy) 2771 SUIT_Directive //= (suit-directive-swap, SUIT_Rep_Policy) 2772 SUIT_Directive //= (suit-directive-run, SUIT_Rep_Policy) 2774 SUIT_Directive_Try_Each_Argument = [ 2775 2* bstr .cbor SUIT_Command_Sequence, 2776 ?nil 2777 ] 2779 SUIT_Rep_Policy = uint .bits suit-reporting-bits 2781 suit-reporting-bits = &( 2782 suit-send-record-success : 0, 2783 suit-send-record-failure : 1, 2784 suit-send-sysinfo-success : 2, 2785 suit-send-sysinfo-failure : 3 2786 ) 2788 SUIT_Parameters //= (suit-parameter-vendor-identifier => 2789 (RFC4122_UUID / cbor-pen)) 2790 cbor-pen = #6.112(bstr) 2792 SUIT_Parameters //= (suit-parameter-class-identifier => RFC4122_UUID) 2793 SUIT_Parameters //= (suit-parameter-image-digest 2794 => bstr .cbor SUIT_Digest) 2795 SUIT_Parameters //= (suit-parameter-image-size => uint) 2796 SUIT_Parameters //= (suit-parameter-component-slot => uint) 2798 SUIT_Parameters //= (suit-parameter-uri => tstr) 2799 SUIT_Parameters //= (suit-parameter-source-component => uint) 2800 SUIT_Parameters //= (suit-parameter-run-args => bstr) 2802 SUIT_Parameters //= (suit-parameter-device-identifier => RFC4122_UUID) 2804 SUIT_Parameters //= (suit-parameter-custom => int/bool/tstr/bstr) 2806 SUIT_Parameters //= (suit-parameter-strict-order => bool) 2807 SUIT_Parameters //= (suit-parameter-soft-failure => bool) 2809 RFC4122_UUID = bstr .size 16 2811 SUIT_Text_Map = { 2812 SUIT_Text_Keys, 2813 * SUIT_Component_Identifier => { 2814 SUIT_Text_Component_Keys 2815 } 2816 } 2818 SUIT_Text_Component_Keys = ( 2819 ? suit-text-vendor-name => tstr, 2820 ? suit-text-model-name => tstr, 2821 ? suit-text-vendor-domain => tstr, 2822 ? suit-text-model-info => tstr, 2823 ? suit-text-component-description => tstr, 2824 ? suit-text-component-version => tstr, 2825 * $$suit-text-component-key-extensions 2826 ) 2828 SUIT_Text_Keys = ( 2829 ? suit-text-manifest-description => tstr, 2830 ? suit-text-update-description => tstr, 2831 ? suit-text-manifest-json-source => tstr, 2832 ? suit-text-manifest-yaml-source => tstr, 2833 * $$suit-text-key-extensions 2834 ) 2836 suit-authentication-wrapper = 2 2837 suit-manifest = 3 2839 ;REQUIRED to implement: 2840 cose-alg-sha-256 = -16 2842 ;OPTIONAL to implement: 2843 cose-alg-shake128 = -18 2844 cose-alg-sha-384 = -43 2845 cose-alg-sha-512 = -44 2846 cose-alg-shake256 = -45 2848 suit-manifest-version = 1 2849 suit-manifest-sequence-number = 2 2850 suit-common = 3 2851 suit-reference-uri = 4 2852 suit-payload-fetch = 8 2853 suit-install = 9 2854 suit-validate = 10 2855 suit-load = 11 2856 suit-run = 12 2857 suit-text = 13 2859 suit-components = 2 2860 suit-common-sequence = 4 2862 suit-command-custom = nint 2864 suit-condition-vendor-identifier = 1 2865 suit-condition-class-identifier = 2 2866 suit-condition-image-match = 3 2867 suit-condition-component-slot = 5 2869 suit-condition-abort = 14 2870 suit-condition-device-identifier = 24 2872 suit-directive-set-component-index = 12 2873 suit-directive-try-each = 15 2874 suit-directive-override-parameters = 20 2875 suit-directive-fetch = 21 2876 suit-directive-copy = 22 2877 suit-directive-run = 23 2879 suit-directive-swap = 31 2880 suit-directive-run-sequence = 32 2882 suit-parameter-vendor-identifier = 1 2883 suit-parameter-class-identifier = 2 2884 suit-parameter-image-digest = 3 2885 suit-parameter-component-slot = 5 2887 suit-parameter-strict-order = 12 2888 suit-parameter-soft-failure = 13 2889 suit-parameter-image-size = 14 2891 suit-parameter-uri = 21 2892 suit-parameter-source-component = 22 2893 suit-parameter-run-args = 23 2895 suit-parameter-device-identifier = 24 2897 suit-parameter-custom = nint 2899 suit-text-manifest-description = 1 2900 suit-text-update-description = 2 2901 suit-text-manifest-json-source = 3 2902 suit-text-manifest-yaml-source = 4 2904 suit-text-vendor-name = 1 2905 suit-text-model-name = 2 2906 suit-text-vendor-domain = 3 2907 suit-text-model-info = 4 2908 suit-text-component-description = 5 2909 suit-text-component-version = 6 2911 Appendix B. B. Examples 2913 The following examples demonstrate a small subset of the 2914 functionality of the manifest. Even a simple manifest processor can 2915 execute most of these manifests. 2917 The examples are signed using the following ECDSA secp256r1 key: 2919 -----BEGIN PRIVATE KEY----- 2920 MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgApZYjZCUGLM50VBC 2921 CjYStX+09jGmnyJPrpDLTz/hiXOhRANCAASEloEarguqq9JhVxie7NomvqqL8Rtv 2922 P+bitWWchdvArTsfKktsCYExwKNtrNHXi9OB3N+wnAUtszmR23M4tKiW 2923 -----END PRIVATE KEY----- 2925 The corresponding public key can be used to verify these examples: 2927 -----BEGIN PUBLIC KEY----- 2928 MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEhJaBGq4LqqvSYVcYnuzaJr6qi/Eb 2929 bz/m4rVlnIXbwK07HypLbAmBMcCjbazR14vTgdzfsJwFLbM5kdtzOLSolg== 2930 -----END PUBLIC KEY----- 2932 Each example uses SHA256 as the digest function. 2934 Note that reporting policies are declared for each non-flow-control 2935 command in these examples. The reporting policies used in the 2936 examples are described in the following tables. 2938 +=============================+==========+ 2939 | Policy | Label | 2940 +=============================+==========+ 2941 | suit-send-record-on-success | Rec-Pass | 2942 +-----------------------------+----------+ 2943 | suit-send-record-on-failure | Rec-Fail | 2944 +-----------------------------+----------+ 2945 | suit-send-sysinfo-success | Sys-Pass | 2946 +-----------------------------+----------+ 2947 | suit-send-sysinfo-failure | Sys-Fail | 2948 +-----------------------------+----------+ 2950 Table 12 2952 +===================+==========+==========+==========+==========+ 2953 | Command | Sys-Fail | Sys-Pass | Rec-Fail | Rec-Pass | 2954 +===================+==========+==========+==========+==========+ 2955 | suit-condition- | 1 | 1 | 1 | 1 | 2956 | vendor-identifier | | | | | 2957 +-------------------+----------+----------+----------+----------+ 2958 | suit-condition- | 1 | 1 | 1 | 1 | 2959 | class-identifier | | | | | 2960 +-------------------+----------+----------+----------+----------+ 2961 | suit-condition- | 1 | 1 | 1 | 1 | 2962 | image-match | | | | | 2963 +-------------------+----------+----------+----------+----------+ 2964 | suit-condition- | 0 | 1 | 0 | 1 | 2965 | component-slot | | | | | 2966 +-------------------+----------+----------+----------+----------+ 2967 | suit-directive- | 0 | 0 | 1 | 0 | 2968 | fetch | | | | | 2969 +-------------------+----------+----------+----------+----------+ 2970 | suit-directive- | 0 | 0 | 1 | 0 | 2971 | copy | | | | | 2972 +-------------------+----------+----------+----------+----------+ 2973 | suit-directive- | 0 | 0 | 1 | 0 | 2974 | run | | | | | 2975 +-------------------+----------+----------+----------+----------+ 2977 Table 13 2979 B.1. Example 0: Secure Boot 2981 This example covers the following templates: 2983 * Compatibility Check (Section 7.1) 2985 * Secure Boot (Section 7.2) 2987 It also serves as the minimum example. 2989 107({ 2990 / authentication-wrapper / 2:<<[ 2991 digest: <<[ 2992 / algorithm-id / -16 / "sha256" /, 2993 / digest-bytes / 2994 h'a6c4590ac53043a98e8c4106e1e31b305516d7cf0a655eddfac6d45c810e036a' 2995 ]>>, 2996 signature: <<18([ 2997 / protected / <<{ 2998 / alg / 1:-7 / "ES256" /, 2999 }>>, 3000 / unprotected / { 3001 }, 3002 / payload / F6 / nil /, 3003 / signature / h'd11a2dd9610fb62a707335f58407922570 3004 9f96e8117e7eeed98a2f207d05c8ecfba1755208f6abea977b8a6efe3bc2ca3215e119 3005 3be201467d052b42db6b7287' 3006 ])>> 3007 ] 3008 ]>>, 3009 / manifest / 3:<<{ 3010 / manifest-version / 1:1, 3011 / manifest-sequence-number / 2:0, 3012 / common / 3:<<{ 3013 / components / 2:[ 3014 [h'00'] 3015 ], 3016 / common-sequence / 4:<<[ 3017 / directive-override-parameters / 20,{ 3018 / vendor-id / 3019 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 3020 be9d-e663e4d41ffe /, 3021 / class-id / 3022 2:h'1492af1425695e48bf429b2d51f2ab45' / 3023 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 3024 / image-digest / 3:<<[ 3025 / algorithm-id / -16 / "sha256" /, 3026 / digest-bytes / 3027 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 3028 ]>>, 3029 / image-size / 14:34768, 3030 } , 3031 / condition-vendor-identifier / 1,15 , 3032 / condition-class-identifier / 2,15 3033 ]>>, 3034 }>>, 3035 / validate / 10:<<[ 3036 / condition-image-match / 3,15 3037 ]>>, 3038 / run / 12:<<[ 3039 / directive-run / 23,2 3040 ]>>, 3041 }>>, 3042 }) 3044 Total size of Envelope without COSE authentication object: 161 3046 Envelope: 3048 d86ba2025827815824822f5820a6c4590ac53043a98e8c4106e1e31b3055 3049 16d7cf0a655eddfac6d45c810e036a035871a50101020003585fa2028181 3050 41000458568614a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492 3051 af1425695e48bf429b2d51f2ab45035824822f5820001122334455667788 3052 99aabbccddeeff0123456789abcdeffedcba98765432100e1987d0010f02 3053 0f0a4382030f0c43821702 3055 Total size of Envelope with COSE authentication object: 237 3057 Envelope with COSE authentication object: 3059 d86ba2025873825824822f5820a6c4590ac53043a98e8c4106e1e31b3055 3060 16d7cf0a655eddfac6d45c810e036a584ad28443a10126a0f65840d11a2d 3061 d9610fb62a707335f584079225709f96e8117e7eeed98a2f207d05c8ecfb 3062 a1755208f6abea977b8a6efe3bc2ca3215e1193be201467d052b42db6b72 3063 87035871a50101020003585fa202818141000458568614a40150fa6b4a53 3064 d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab45 3065 035824822f582000112233445566778899aabbccddeeff0123456789abcd 3066 effedcba98765432100e1987d0010f020f0a4382030f0c43821702 3068 B.2. Example 1: Simultaneous Download and Installation of Payload 3070 This example covers the following templates: 3072 * Compatibility Check (Section 7.1) 3074 * Firmware Download (Section 7.3) 3076 Simultaneous download and installation of payload. No secure boot is 3077 present in this example to demonstrate a download-only manifest. 3079 107({ 3080 / authentication-wrapper / 2:<<[ 3081 digest: <<[ 3082 / algorithm-id / -16 / "sha256" /, 3083 / digest-bytes / 3084 h'60c61d6eb7a1aaeddc49ce8157a55cff0821537eeee77a4ded44155b03045132' 3085 ]>>, 3086 signature: <<18([ 3087 / protected / <<{ 3088 / alg / 1:-7 / "ES256" /, 3089 }>>, 3090 / unprotected / { 3091 }, 3092 / payload / F6 / nil /, 3093 / signature / h'5249dacaf0ffc8326931b09586eb7e3769 3094 e71a0e6a40ad8153db4980db9b05bd1742ddb46085fa11e62b65a79895c12ac7abe266 3095 8ccc5afdd74466aed7bca389' 3096 ])>> 3097 ] 3098 ]>>, 3099 / manifest / 3:<<{ 3100 / manifest-version / 1:1, 3101 / manifest-sequence-number / 2:1, 3102 / common / 3:<<{ 3103 / components / 2:[ 3104 [h'00'] 3105 ], 3106 / common-sequence / 4:<<[ 3107 / directive-override-parameters / 20,{ 3108 / vendor-id / 3109 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 3110 be9d-e663e4d41ffe /, 3111 / class-id / 3112 2:h'1492af1425695e48bf429b2d51f2ab45' / 3113 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 3114 / image-digest / 3:<<[ 3115 / algorithm-id / -16 / "sha256" /, 3116 / digest-bytes / 3117 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 3118 ]>>, 3119 / image-size / 14:34768, 3120 } , 3121 / condition-vendor-identifier / 1,15 , 3122 / condition-class-identifier / 2,15 3123 ]>>, 3124 }>>, 3125 / install / 9:<<[ 3126 / directive-set-parameters / 19,{ 3127 / uri / 21:'http://example.com/file.bin', 3128 } , 3129 / directive-fetch / 21,2 , 3130 / condition-image-match / 3,15 3131 ]>>, 3132 / validate / 10:<<[ 3133 / condition-image-match / 3,15 3134 ]>>, 3135 }>>, 3136 }) 3138 Total size of Envelope without COSE authentication object: 196 3140 Envelope: 3142 d86ba2025827815824822f582060c61d6eb7a1aaeddc49ce8157a55cff08 3143 21537eeee77a4ded44155b03045132035894a50101020103585fa2028181 3144 41000458568614a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492 3145 af1425695e48bf429b2d51f2ab45035824822f5820001122334455667788 3146 99aabbccddeeff0123456789abcdeffedcba98765432100e1987d0010f02 3147 0f0958258613a115781b687474703a2f2f6578616d706c652e636f6d2f66 3148 696c652e62696e1502030f0a4382030f 3150 Total size of Envelope with COSE authentication object: 272 3152 Envelope with COSE authentication object: 3154 d86ba2025873825824822f582060c61d6eb7a1aaeddc49ce8157a55cff08 3155 21537eeee77a4ded44155b03045132584ad28443a10126a0f658405249da 3156 caf0ffc8326931b09586eb7e3769e71a0e6a40ad8153db4980db9b05bd17 3157 42ddb46085fa11e62b65a79895c12ac7abe2668ccc5afdd74466aed7bca3 3158 89035894a50101020103585fa202818141000458568614a40150fa6b4a53 3159 d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab45 3160 035824822f582000112233445566778899aabbccddeeff0123456789abcd 3161 effedcba98765432100e1987d0010f020f0958258613a115781b68747470 3162 3a2f2f6578616d706c652e636f6d2f66696c652e62696e1502030f0a4382 3163 030f 3165 B.3. Example 2: Simultaneous Download, Installation, Secure Boot, 3166 Severed Fields 3168 This example covers the following templates: 3170 * Compatibility Check (Section 7.1) 3172 * Secure Boot (Section 7.2) 3174 * Firmware Download (Section 7.3) 3176 This example also demonstrates severable elements (Section 5.4), and 3177 text (Section 8.4.4). 3179 107({ 3180 / authentication-wrapper / 2:<<[ 3181 digest: <<[ 3182 / algorithm-id / -16 / "sha256" /, 3183 / digest-bytes / 3184 h'e45dcdb2074b951f1c88b866469939c2a83ed433a31fc7dfcb3f63955bd943ec' 3185 ]>>, 3186 signature: <<18([ 3187 / protected / <<{ 3188 / alg / 1:-7 / "ES256" /, 3189 }>>, 3190 / unprotected / { 3191 }, 3192 / payload / F6 / nil /, 3193 / signature / h'b4fd3a6a18fe1062573488cf24ac96ef9f 3194 30ac746696e50be96533b356b8156e4332587fe6f4e8743ae525d72005fddd4c1213d5 3195 5a8061b2ce67b83640f4777c' 3196 ])>> 3197 ] 3198 ]>>, 3199 / manifest / 3:<<{ 3200 / manifest-version / 1:1, 3201 / manifest-sequence-number / 2:2, 3202 / common / 3:<<{ 3203 / components / 2:[ 3204 [h'00'] 3205 ], 3206 / common-sequence / 4:<<[ 3207 / directive-override-parameters / 20,{ 3208 / vendor-id / 3209 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 3210 be9d-e663e4d41ffe /, 3211 / class-id / 3212 2:h'1492af1425695e48bf429b2d51f2ab45' / 3213 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 3214 / image-digest / 3:<<[ 3215 / algorithm-id / -16 / "sha256" /, 3216 / digest-bytes / 3217 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 3218 ]>>, 3219 / image-size / 14:34768, 3220 } , 3221 / condition-vendor-identifier / 1,15 , 3222 / condition-class-identifier / 2,15 3223 ]>>, 3224 }>>, 3225 / install / 9:[ 3226 / algorithm-id / -16 / "sha256" /, 3227 / digest-bytes / 3228 h'3ee96dc79641970ae46b929ccf0b72ba9536dd846020dbdc9f949d84ea0e18d2' 3229 ], 3230 / validate / 10:<<[ 3231 / condition-image-match / 3,15 3232 ]>>, 3233 / run / 12:<<[ 3234 / directive-run / 23,2 3235 ]>>, 3236 / text / 13:[ 3237 / algorithm-id / -16 / "sha256" /, 3238 / digest-bytes / 3239 h'2bfc4d0cc6680be7dd9f5ca30aa2bb5d1998145de33d54101b80e2ca49faf918' 3240 ], 3241 }>>, 3242 / install / 9:<<[ 3243 / directive-set-parameters / 19,{ 3244 / uri / 3245 21:'http://example.com/very/long/path/to/file/file.bin', 3246 } , 3247 / directive-fetch / 21,2 , 3248 / condition-image-match / 3,15 3249 ]>>, 3250 / text / 13:<<{ 3251 [h'00']:{ 3252 / vendor-domain / 3:'arm.com', 3253 / component-description / 5:'This component is a 3254 demonstration. The digest is a sample pattern, not a real one.', 3255 } 3256 }>>, 3257 }) 3259 Total size of the Envelope without COSE authentication object or 3260 Severable Elements: 235 3262 Envelope: 3264 d86ba2025827815824822f5820e45dcdb2074b951f1c88b866469939c2a8 3265 3ed433a31fc7dfcb3f63955bd943ec0358bba70101020203585fa2028181 3266 41000458568614a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492 3267 af1425695e48bf429b2d51f2ab45035824822f5820001122334455667788 3268 99aabbccddeeff0123456789abcdeffedcba98765432100e1987d0010f02 3269 0f09822f58203ee96dc79641970ae46b929ccf0b72ba9536dd846020dbdc 3270 9f949d84ea0e18d20a4382030f0c438217020d822f58202bfc4d0cc6680b 3271 e7dd9f5ca30aa2bb5d1998145de33d54101b80e2ca49faf918 3273 Total size of the Envelope with COSE authentication object but 3274 without Severable Elements: 311 3276 Envelope: 3278 d86ba2025873825824822f5820e45dcdb2074b951f1c88b866469939c2a8 3279 3ed433a31fc7dfcb3f63955bd943ec584ad28443a10126a0f65840b4fd3a 3280 6a18fe1062573488cf24ac96ef9f30ac746696e50be96533b356b8156e43 3281 32587fe6f4e8743ae525d72005fddd4c1213d55a8061b2ce67b83640f477 3282 7c0358bba70101020203585fa202818141000458568614a40150fa6b4a53 3283 d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab45 3284 035824822f582000112233445566778899aabbccddeeff0123456789abcd 3285 effedcba98765432100e1987d0010f020f09822f58203ee96dc79641970a 3286 e46b929ccf0b72ba9536dd846020dbdc9f949d84ea0e18d20a4382030f0c 3287 438217020d822f58202bfc4d0cc6680be7dd9f5ca30aa2bb5d1998145de3 3288 3d54101b80e2ca49faf918 3290 Total size of Envelope with COSE authentication object and Severable 3291 Elements: 894 3293 Envelope with COSE authentication object: 3295 d86ba4025873825824822f5820e45dcdb2074b951f1c88b866469939c2a8 3296 3ed433a31fc7dfcb3f63955bd943ec584ad28443a10126a0f65840b4fd3a 3297 6a18fe1062573488cf24ac96ef9f30ac746696e50be96533b356b8156e43 3298 32587fe6f4e8743ae525d72005fddd4c1213d55a8061b2ce67b83640f477 3299 7c0358bba70101020203585fa202818141000458568614a40150fa6b4a53 3300 d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab45 3301 035824822f582000112233445566778899aabbccddeeff0123456789abcd 3302 effedcba98765432100e1987d0010f020f09822f58203ee96dc79641970a 3303 e46b929ccf0b72ba9536dd846020dbdc9f949d84ea0e18d20a4382030f0c 3304 438217020d822f58202bfc4d0cc6680be7dd9f5ca30aa2bb5d1998145de3 3305 3d54101b80e2ca49faf91809583c8613a1157832687474703a2f2f657861 3306 6d706c652e636f6d2f766572792f6c6f6e672f706174682f746f2f66696c 3307 652f66696c652e62696e1502030f0d590204a20179019d2323204578616d 3308 706c6520323a2053696d756c74616e656f757320446f776e6c6f61642c20 3309 496e7374616c6c6174696f6e2c2053656375726520426f6f742c20536576 3310 65726564204669656c64730a0a2020202054686973206578616d706c6520 3311 636f766572732074686520666f6c6c6f77696e672074656d706c61746573 3312 3a0a202020200a202020202a20436f6d7061746962696c69747920436865 3313 636b20287b7b74656d706c6174652d636f6d7061746962696c6974792d63 3314 6865636b7d7d290a202020202a2053656375726520426f6f7420287b7b74 3315 656d706c6174652d7365637572652d626f6f747d7d290a202020202a2046 3316 69726d7761726520446f776e6c6f616420287b7b6669726d776172652d64 3317 6f776e6c6f61642d74656d706c6174657d7d290a202020200a2020202054 3318 686973206578616d706c6520616c736f2064656d6f6e7374726174657320 3319 736576657261626c6520656c656d656e747320287b7b6f76722d73657665 3320 7261626c657d7d292c20616e64207465787420287b7b6d616e6966657374 3321 2d6469676573742d746578747d7d292e814100a2036761726d2e636f6d05 3322 78525468697320636f6d706f6e656e7420697320612064656d6f6e737472 3323 6174696f6e2e205468652064696765737420697320612073616d706c6520 3324 7061747465726e2c206e6f742061207265616c206f6e652e 3326 B.4. Example 3: A/B images 3328 This example covers the following templates: 3330 * Compatibility Check (Section 7.1) 3332 * Secure Boot (Section 7.2) 3334 * Firmware Download (Section 7.3) 3336 * A/B Image Template (Section 7.7) 3338 107({ 3339 / authentication-wrapper / 2:<<[ 3340 digest: <<[ 3341 / algorithm-id / -16 / "sha256" /, 3342 / digest-bytes / 3343 h'7c9b3cb72c262608a42f944d59d659ff2b801c78af44def51b8ff51e9f45721b' 3344 ]>>, 3345 signature: <<18([ 3346 / protected / <<{ 3347 / alg / 1:-7 / "ES256" /, 3348 }>>, 3349 / unprotected / { 3350 }, 3351 / payload / F6 / nil /, 3352 / signature / h'e33d618df0ad21e609529ab1a876afb231 3353 faff1d6a3189b5360324c2794250b87cf00cf83be50ea17dc721ca85393cd8e839a066 3354 d5dec0ad87a903ab31ea9afa' 3355 ])>> 3356 ] 3357 ]>>, 3358 / manifest / 3:<<{ 3359 / manifest-version / 1:1, 3360 / manifest-sequence-number / 2:3, 3361 / common / 3:<<{ 3362 / components / 2:[ 3363 [h'00'] 3364 ], 3365 / common-sequence / 4:<<[ 3366 / directive-override-parameters / 20,{ 3367 / vendor-id / 3368 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 3369 be9d-e663e4d41ffe /, 3370 / class-id / 3371 2:h'1492af1425695e48bf429b2d51f2ab45' / 3372 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 3373 } , 3374 / directive-try-each / 15,[ 3375 <<[ 3376 / directive-override-parameters / 20,{ 3377 / offset / 5:33792, 3378 } , 3379 / condition-component-offset / 5,5 , 3380 / directive-override-parameters / 20,{ 3381 / image-digest / 3:<<[ 3382 / algorithm-id / -16 / "sha256" /, 3383 / digest-bytes / 3384 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 3385 ]>>, 3386 / image-size / 14:34768, 3387 } 3388 ]>> , 3389 <<[ 3390 / directive-override-parameters / 20,{ 3391 / offset / 5:541696, 3392 } , 3393 / condition-component-offset / 5,5 , 3394 / directive-override-parameters / 20,{ 3395 / image-digest / 3:<<[ 3396 / algorithm-id / -16 / "sha256" /, 3397 / digest-bytes / 3398 h'0123456789abcdeffedcba987654321000112233445566778899aabbccddeeff' 3399 ]>>, 3400 / image-size / 14:76834, 3401 } 3402 ]>> 3403 ] , 3404 / condition-vendor-identifier / 1,15 , 3405 / condition-class-identifier / 2,15 3406 ]>>, 3407 }>>, 3408 / install / 9:<<[ 3409 / directive-try-each / 15,[ 3410 <<[ 3411 / directive-set-parameters / 19,{ 3412 / offset / 5:33792, 3413 } , 3414 / condition-component-offset / 5,5 , 3415 / directive-set-parameters / 19,{ 3416 / uri / 21:'http://example.com/file1.bin', 3417 } 3418 ]>> , 3419 <<[ 3420 / directive-set-parameters / 19,{ 3421 / offset / 5:541696, 3423 } , 3424 / condition-component-offset / 5,5 , 3425 / directive-set-parameters / 19,{ 3426 / uri / 21:'http://example.com/file2.bin', 3427 } 3428 ]>> 3429 ] , 3430 / directive-fetch / 21,2 , 3431 / condition-image-match / 3,15 3432 ]>>, 3433 / validate / 10:<<[ 3434 / condition-image-match / 3,15 3435 ]>>, 3436 }>>, 3437 }) 3439 Total size of Envelope without COSE authentication object: 332 3441 Envelope: 3443 d86ba2025827815824822f58207c9b3cb72c262608a42f944d59d659ff2b 3444 801c78af44def51b8ff51e9f45721b0359011ba5010102030358aaa20281 3445 8141000458a18814a20150fa6b4a53d5ad5fdfbe9de663e4d41ffe025014 3446 92af1425695e48bf429b2d51f2ab450f8258368614a105198400050514a2 3447 035824822f582000112233445566778899aabbccddeeff0123456789abcd 3448 effedcba98765432100e1987d0583a8614a1051a00084400050514a20358 3449 24822f58200123456789abcdeffedcba9876543210001122334455667788 3450 99aabbccddeeff0e1a00012c22010f020f095861860f82582a8613a10519 3451 8400050513a115781c687474703a2f2f6578616d706c652e636f6d2f6669 3452 6c65312e62696e582c8613a1051a00084400050513a115781c687474703a 3453 2f2f6578616d706c652e636f6d2f66696c65322e62696e1502030f0a4382 3454 030f 3456 Total size of Envelope with COSE authentication object: 408 3458 Envelope with COSE authentication object: 3460 d86ba2025873825824822f58207c9b3cb72c262608a42f944d59d659ff2b 3461 801c78af44def51b8ff51e9f45721b584ad28443a10126a0f65840e33d61 3462 8df0ad21e609529ab1a876afb231faff1d6a3189b5360324c2794250b87c 3463 f00cf83be50ea17dc721ca85393cd8e839a066d5dec0ad87a903ab31ea9a 3464 fa0359011ba5010102030358aaa202818141000458a18814a20150fa6b4a 3465 53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab 3466 450f8258368614a105198400050514a2035824822f582000112233445566 3467 778899aabbccddeeff0123456789abcdeffedcba98765432100e1987d058 3468 3a8614a1051a00084400050514a2035824822f58200123456789abcdeffe 3469 dcba987654321000112233445566778899aabbccddeeff0e1a00012c2201 3470 0f020f095861860f82582a8613a105198400050513a115781c687474703a 3471 2f2f6578616d706c652e636f6d2f66696c65312e62696e582c8613a1051a 3472 00084400050513a115781c687474703a2f2f6578616d706c652e636f6d2f 3473 66696c65322e62696e1502030f0a4382030f 3475 B.5. Example 4: Load from External Storage 3477 This example covers the following templates: 3479 * Compatibility Check (Section 7.1) 3481 * Secure Boot (Section 7.2) 3483 * Firmware Download (Section 7.3) 3485 * Install (Section 7.4) 3487 * Load (Section 7.6) 3489 107({ 3490 / authentication-wrapper / 2:<<[ 3491 digest: <<[ 3492 / algorithm-id / -16 / "sha256" /, 3493 / digest-bytes / 3494 h'15736702a00f510805dcf89d6913a2cfb417ed414faa760f974d6755c68ba70a' 3495 ]>>, 3496 signature: <<18([ 3497 / protected / <<{ 3498 / alg / 1:-7 / "ES256" /, 3499 }>>, 3500 / unprotected / { 3501 }, 3502 / payload / F6 / nil /, 3503 / signature / h'3ada2532326d512132c388677798c24ffd 3504 cc979bfae2a26b19c8c8bbf511fd7dd85f1501662c1a9e1976b759c4019bab44ba5434 3505 efb45d3868aedbca593671f3' 3506 ])>> 3507 ] 3509 ]>>, 3510 / manifest / 3:<<{ 3511 / manifest-version / 1:1, 3512 / manifest-sequence-number / 2:4, 3513 / common / 3:<<{ 3514 / components / 2:[ 3515 [h'00'] , 3516 [h'02'] , 3517 [h'01'] 3518 ], 3519 / common-sequence / 4:<<[ 3520 / directive-set-component-index / 12,0 , 3521 / directive-override-parameters / 20,{ 3522 / vendor-id / 3523 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 3524 be9d-e663e4d41ffe /, 3525 / class-id / 3526 2:h'1492af1425695e48bf429b2d51f2ab45' / 3527 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 3528 / image-digest / 3:<<[ 3529 / algorithm-id / -16 / "sha256" /, 3530 / digest-bytes / 3531 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 3532 ]>>, 3533 / image-size / 14:34768, 3534 } , 3535 / condition-vendor-identifier / 1,15 , 3536 / condition-class-identifier / 2,15 3537 ]>>, 3538 }>>, 3539 / payload-fetch / 8:<<[ 3540 / directive-set-component-index / 12,1 , 3541 / directive-set-parameters / 19,{ 3542 / uri / 21:'http://example.com/file.bin', 3543 } , 3544 / directive-fetch / 21,2 , 3545 / condition-image-match / 3,15 3546 ]>>, 3547 / install / 9:<<[ 3548 / directive-set-component-index / 12,0 , 3549 / directive-set-parameters / 19,{ 3550 / source-component / 22:1 / [h'02'] /, 3551 } , 3552 / directive-copy / 22,2 , 3553 / condition-image-match / 3,15 3554 ]>>, 3555 / validate / 10:<<[ 3556 / directive-set-component-index / 12,0 , 3557 / condition-image-match / 3,15 3558 ]>>, 3559 / load / 11:<<[ 3560 / directive-set-component-index / 12,2 , 3561 / directive-set-parameters / 19,{ 3562 / image-digest / 3:<<[ 3563 / algorithm-id / -16 / "sha256" /, 3564 / digest-bytes / 3565 h'0123456789abcdeffedcba987654321000112233445566778899aabbccddeeff' 3566 ]>>, 3567 / image-size / 14:76834, 3568 / source-component / 22:0 / [h'00'] /, 3569 / compression-info / 19:<<{ 3570 / compression-algorithm / 1:1 / "gzip" /, 3571 }>>, 3572 } , 3573 / directive-copy / 22,2 , 3574 / condition-image-match / 3,15 3575 ]>>, 3576 / run / 12:<<[ 3577 / directive-set-component-index / 12,2 , 3578 / directive-run / 23,2 3579 ]>>, 3580 }>>, 3581 }) 3583 Total size of Envelope without COSE authentication object: 292 3585 Envelope: 3587 d86ba2025827815824822f582015736702a00f510805dcf89d6913a2cfb4 3588 17ed414faa760f974d6755c68ba70a0358f4a801010204035867a2028381 3589 4100814102814101045858880c0014a40150fa6b4a53d5ad5fdfbe9de663 3590 e4d41ffe02501492af1425695e48bf429b2d51f2ab45035824822f582000 3591 112233445566778899aabbccddeeff0123456789abcdeffedcba98765432 3592 100e1987d0010f020f085827880c0113a115781b687474703a2f2f657861 3593 6d706c652e636f6d2f66696c652e62696e1502030f094b880c0013a11601 3594 1602030f0a45840c00030f0b583d880c0213a4035824822f582001234567 3595 89abcdeffedcba987654321000112233445566778899aabbccddeeff0e1a 3596 00012c221343a1010116001602030f0c45840c021702 3598 Total size of Envelope with COSE authentication object: 368 3600 Envelope with COSE authentication object: 3602 d86ba2025873825824822f582015736702a00f510805dcf89d6913a2cfb4 3603 17ed414faa760f974d6755c68ba70a584ad28443a10126a0f658403ada25 3604 32326d512132c388677798c24ffdcc979bfae2a26b19c8c8bbf511fd7dd8 3605 5f1501662c1a9e1976b759c4019bab44ba5434efb45d3868aedbca593671 3606 f30358f4a801010204035867a20283814100814102814101045858880c00 3607 14a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48 3608 bf429b2d51f2ab45035824822f582000112233445566778899aabbccddee 3609 ff0123456789abcdeffedcba98765432100e1987d0010f020f085827880c 3610 0113a115781b687474703a2f2f6578616d706c652e636f6d2f66696c652e 3611 62696e1502030f094b880c0013a116011602030f0a45840c00030f0b583d 3612 880c0213a4035824822f58200123456789abcdeffedcba98765432100011 3613 2233445566778899aabbccddeeff0e1a00012c221343a101011600160203 3614 0f0c45840c021702 3616 B.6. Example 5: Two Images 3618 This example covers the following templates: 3620 * Compatibility Check (Section 7.1) 3622 * Secure Boot (Section 7.2) 3624 * Firmware Download (Section 7.3) 3626 Furthermore, it shows using these templates with two images. 3628 107({ 3629 / authentication-wrapper / 2:<<[ 3630 digest: <<[ 3631 / algorithm-id / -16 / "sha256" /, 3632 / digest-bytes / 3633 h'd1e73f16e4126007bc4d804cd33b0209fbab34728e60ee8c00f3387126748dd2' 3634 ]>>, 3635 signature: <<18([ 3636 / protected / <<{ 3637 / alg / 1:-7 / "ES256" /, 3638 }>>, 3639 / unprotected / { 3640 }, 3641 / payload / F6 / nil /, 3642 / signature / h'b7ae0a46a28f02e25cda6d9a255bbaf863 3643 30141831fae5a78012d648bc6cee55102e0f1890bdeacc3adaa4fae0560f83a45eecae 3644 65cabce642f56d84ab97ef8d' 3645 ])>> 3646 ] 3647 ]>>, 3648 / manifest / 3:<<{ 3649 / manifest-version / 1:1, 3650 / manifest-sequence-number / 2:5, 3651 / common / 3:<<{ 3652 / components / 2:[ 3653 [h'00'] , 3654 [h'01'] 3655 ], 3656 / common-sequence / 4:<<[ 3657 / directive-set-component-index / 12,0 , 3658 / directive-override-parameters / 20,{ 3659 / vendor-id / 3660 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 3661 be9d-e663e4d41ffe /, 3662 / class-id / 3663 2:h'1492af1425695e48bf429b2d51f2ab45' / 3664 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 3665 / image-digest / 3:<<[ 3666 / algorithm-id / -16 / "sha256" /, 3667 / digest-bytes / 3668 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 3669 ]>>, 3670 / image-size / 14:34768, 3671 } , 3672 / condition-vendor-identifier / 1,15 , 3673 / condition-class-identifier / 2,15 , 3674 / directive-set-component-index / 12,1 , 3675 / directive-override-parameters / 20,{ 3676 / image-digest / 3:<<[ 3677 / algorithm-id / -16 / "sha256" /, 3678 / digest-bytes / 3679 h'0123456789abcdeffedcba987654321000112233445566778899aabbccddeeff' 3680 ]>>, 3681 / image-size / 14:76834, 3682 } 3683 ]>>, 3684 }>>, 3685 / install / 9:<<[ 3686 / directive-set-component-index / 12,0 , 3687 / directive-set-parameters / 19,{ 3688 / uri / 21:'http://example.com/file1.bin', 3689 } , 3690 / directive-fetch / 21,2 , 3691 / condition-image-match / 3,15 , 3692 / directive-set-component-index / 12,1 , 3693 / directive-set-parameters / 19,{ 3694 / uri / 21:'http://example.com/file2.bin', 3695 } , 3696 / directive-fetch / 21,2 , 3697 / condition-image-match / 3,15 3699 ]>>, 3700 / validate / 10:<<[ 3701 / directive-set-component-index / 12,0 , 3702 / condition-image-match / 3,15 , 3703 / directive-set-component-index / 12,1 , 3704 / condition-image-match / 3,15 3705 ]>>, 3706 / run / 12:<<[ 3707 / directive-set-component-index / 12,0 , 3708 / directive-run / 23,2 3709 ]>>, 3710 }>>, 3711 }) 3713 Total size of Envelope without COSE authentication object: 306 3715 Envelope: 3717 d86ba2025827815824822f5820d1e73f16e4126007bc4d804cd33b0209fb 3718 ab34728e60ee8c00f3387126748dd203590101a601010205035895a20282 3719 8141008141010458898c0c0014a40150fa6b4a53d5ad5fdfbe9de663e4d4 3720 1ffe02501492af1425695e48bf429b2d51f2ab45035824822f5820001122 3721 33445566778899aabbccddeeff0123456789abcdeffedcba98765432100e 3722 1987d0010f020f0c0114a2035824822f58200123456789abcdeffedcba98 3723 7654321000112233445566778899aabbccddeeff0e1a00012c2209584f90 3724 0c0013a115781c687474703a2f2f6578616d706c652e636f6d2f66696c65 3725 312e62696e1502030f0c0113a115781c687474703a2f2f6578616d706c65 3726 2e636f6d2f66696c65322e62696e1502030f0a49880c00030f0c01030f0c 3727 45840c001702 3729 Total size of Envelope with COSE authentication object: 382 3731 Envelope with COSE authentication object: 3733 d86ba2025873825824822f5820d1e73f16e4126007bc4d804cd33b0209fb 3734 ab34728e60ee8c00f3387126748dd2584ad28443a10126a0f65840b7ae0a 3735 46a28f02e25cda6d9a255bbaf86330141831fae5a78012d648bc6cee5510 3736 2e0f1890bdeacc3adaa4fae0560f83a45eecae65cabce642f56d84ab97ef 3737 8d03590101a601010205035895a202828141008141010458898c0c0014a4 3738 0150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf42 3739 9b2d51f2ab45035824822f582000112233445566778899aabbccddeeff01 3740 23456789abcdeffedcba98765432100e1987d0010f020f0c0114a2035824 3741 822f58200123456789abcdeffedcba987654321000112233445566778899 3742 aabbccddeeff0e1a00012c2209584f900c0013a115781c687474703a2f2f 3743 6578616d706c652e636f6d2f66696c65312e62696e1502030f0c0113a115 3744 781c687474703a2f2f6578616d706c652e636f6d2f66696c65322e62696e 3745 1502030f0a49880c00030f0c01030f0c45840c001702 3747 Appendix C. C. Design Rational 3749 In order to provide flexible behavior to constrained devices, while 3750 still allowing more powerful devices to use their full capabilities, 3751 the SUIT manifest encodes the required behavior of a Recipient 3752 device. Behavior is encoded as a specialized byte code, contained in 3753 a CBOR list. This promotes a flat encoding, which simplifies the 3754 parser. The information encoded by this byte code closely matches 3755 the operations that a device will perform, which promotes ease of 3756 processing. The core operations used by most update and trusted 3757 invocation operations are represented in the byte code. The byte 3758 code can be extended by registering new operations. 3760 The specialized byte code approach gives benefits equivalent to those 3761 provided by a scripting language or conventional byte code, with two 3762 substantial differences. First, the language is extremely high 3763 level, consisting of only the operations that a device may perform 3764 during update and trusted invocation of a firmware image. Second, 3765 the language specifies linear behavior, without reverse branches. 3766 Conditional processing is supported, and parallel and out-of-order 3767 processing may be performed by sufficiently capable devices. 3769 By structuring the data in this way, the manifest processor becomes a 3770 very simple engine that uses a pull parser to interpret the manifest. 3771 This pull parser invokes a series of command handlers that evaluate a 3772 Condition or execute a Directive. Most data is structured in a 3773 highly regular pattern, which simplifies the parser. 3775 The results of this allow a Recipient to implement a very small 3776 parser for constrained applications. If needed, such a parser also 3777 allows the Recipient to perform complex updates with reduced 3778 overhead. Conditional execution of commands allows a simple device 3779 to perform important decisions at validation-time. 3781 Dependency handling is vastly simplified as well. Dependencies 3782 function like subroutines of the language. When a manifest has a 3783 dependency, it can invoke that dependency's commands and modify their 3784 behavior by setting parameters. Because some parameters come with 3785 security implications, the dependencies also have a mechanism to 3786 reject modifications to parameters on a fine-grained level. 3788 Developing a robust permissions system works in this model too. The 3789 Recipient can use a simple ACL that is a table of Identities and 3790 Component Identifier permissions to ensure that operations on 3791 components fail unless they are permitted by the ACL. This table can 3792 be further refined with individual parameters and commands. 3794 Capability reporting is similarly simplified. A Recipient can report 3795 the Commands, Parameters, Algorithms, and Component Identifiers that 3796 it supports. This is sufficiently precise for a manifest author to 3797 create a manifest that the Recipient can accept. 3799 The simplicity of design in the Recipient due to all of these 3800 benefits allows even a highly constrained platform to use advanced 3801 update capabilities. 3803 C.1. C.1 Design Rationale: Envelope 3805 The Envelope is used instead of a COSE structure for several reasons: 3807 1. This enables the use of Severable Elements (Section 8.5) 3809 2. This enables modular processing of manifests, particularly with 3810 large signatures. 3812 3. This enables multiple authentication schemes. 3814 4. This allows integrity verification by a dependent to be 3815 unaffected by adding or removing authentication structures. 3817 Modular processing is important because it allows a Manifest 3818 Processor to iterate forward over an Envelope, processing Delegation 3819 Chains and Authentication Blocks, retaining only intermediate values, 3820 without any need to seek forward and backwards in a stream until it 3821 gets to the Manifest itself. This allows the use of large, Post- 3822 Quantum signatures without requiring retention of the signature 3823 itself, or seeking forward and back. 3825 Four authentication objects are supported by the Envelope: 3827 * COSE_Sign_Tagged 3829 * COSE_Sign1_Tagged 3831 * COSE_Mac_Tagged 3833 * COSE_Mac0_Tagged 3835 The SUIT Envelope allows an Update Authority or intermediary to mix 3836 and match any number of different authentication blocks it wants 3837 without any concern for modifying the integrity of another 3838 authentication block. This also allows the addition or removal of an 3839 authentication blocks without changing the integrity check of the 3840 Manifest, which is important for dependency handling. See 3841 Section 6.2 3843 C.2. C.2 Byte String Wrappers 3845 Byte string wrappers are used in several places in the suit manifest. 3846 The primary reason for wrappers it to limit the parser extent when 3847 invoked at different times, with a possible loss of context. 3849 The elements of the suit envelope are wrapped both to set the extents 3850 used by the parser and to simplify integrity checks by clearly 3851 defining the length of each element. 3853 The common block is re-parsed in order to find components identifiers 3854 from their indices, to find dependency prefixes and digests from 3855 their identifiers, and to find the common sequence. The common 3856 sequence is wrapped so that it matches other sequences, simplifying 3857 the code path. 3859 A severed SUIT command sequence will appear in the envelope, so it 3860 must be wrapped as with all envelope elements. For consistency, 3861 command sequences are also wrapped in the manifest. This also allows 3862 the parser to discern the difference between a command sequence and a 3863 SUIT_Digest. 3865 Parameters that are structured types (arrays and maps) are also 3866 wrapped in a bstr. This is so that parser extents can be set 3867 correctly using only a reference to the beginning of the parameter. 3868 This enables a parser to store a simple list of references to 3869 parameters that can be retrieved when needed. 3871 Appendix D. D. Implementation Conformance Matrix 3873 This section summarizes the functionality a minimal manifest 3874 processor implementation needs to offer to claim conformance to this 3875 specification, in the absence of an application profile standard 3876 specifying otherwise. 3878 The subsequent table shows the conditions. 3880 +===================+=================+================+ 3881 | Name | Reference | Implementation | 3882 +===================+=================+================+ 3883 | Vendor Identifier | Section 8.4.8.2 | REQUIRED | 3884 +-------------------+-----------------+----------------+ 3885 | Class Identifier | Section 8.4.8.2 | REQUIRED | 3886 +-------------------+-----------------+----------------+ 3887 | Device Identifier | Section 8.4.8.2 | OPTIONAL | 3888 +-------------------+-----------------+----------------+ 3889 | Image Match | Section 8.4.9.2 | REQUIRED | 3890 +-------------------+-----------------+----------------+ 3891 | Component Slot | Section 8.4.9.3 | OPTIONAL | 3892 +-------------------+-----------------+----------------+ 3893 | Abort | Section 8.4.9.4 | OPTIONAL | 3894 +-------------------+-----------------+----------------+ 3895 | Custom Condition | Section 8.4.9.5 | OPTIONAL | 3896 +-------------------+-----------------+----------------+ 3898 Table 14 3900 The subsequent table shows the directives. 3902 +=====================+==================+====================+ 3903 | Name | Reference | Implementation | 3904 +=====================+==================+====================+ 3905 | Set Component Index | Section 8.4.10.1 | REQUIRED if more | 3906 | | | than one component | 3907 +---------------------+------------------+--------------------+ 3908 | Try Each | Section 8.4.10.2 | OPTIONAL | 3909 +---------------------+------------------+--------------------+ 3910 | Override Parameters | Section 8.4.10.3 | REQUIRED | 3911 +---------------------+------------------+--------------------+ 3912 | Fetch | Section 8.4.10.4 | REQUIRED for | 3913 | | | Updater | 3914 +---------------------+------------------+--------------------+ 3915 | Copy | Section 8.4.10.5 | OPTIONAL | 3916 +---------------------+------------------+--------------------+ 3917 | Run | Section 8.4.10.6 | REQUIRED for | 3918 | | | Bootloader | 3919 +---------------------+------------------+--------------------+ 3920 | Run Sequence | Section 8.4.10.7 | OPTIONAL | 3921 +---------------------+------------------+--------------------+ 3922 | Swap | Section 8.4.10.8 | OPTIONAL | 3923 +---------------------+------------------+--------------------+ 3925 Table 15 3927 The subsequent table shows the parameters. 3929 +==================+==================+======================+ 3930 | Name | Reference | Implementation | 3931 +==================+==================+======================+ 3932 | Vendor ID | Section 8.4.8.3 | REQUIRED | 3933 +------------------+------------------+----------------------+ 3934 | Class ID | Section 8.4.8.4 | REQUIRED | 3935 +------------------+------------------+----------------------+ 3936 | Image Digest | Section 8.4.8.6 | REQUIRED | 3937 +------------------+------------------+----------------------+ 3938 | Image Size | Section 8.4.8.7 | REQUIRED | 3939 +------------------+------------------+----------------------+ 3940 | Component Slot | Section 8.4.8.8 | OPTIONAL | 3941 +------------------+------------------+----------------------+ 3942 | URI | Section 8.4.8.9 | REQUIRED for Updater | 3943 +------------------+------------------+----------------------+ 3944 | Source Component | Section 8.4.8.10 | OPTIONAL | 3945 +------------------+------------------+----------------------+ 3946 | Run Args | Section 8.4.8.11 | OPTIONAL | 3947 +------------------+------------------+----------------------+ 3948 | Device ID | Section 8.4.8.5 | OPTIONAL | 3949 +------------------+------------------+----------------------+ 3950 | Strict Order | Section 8.4.8.13 | OPTIONAL | 3951 +------------------+------------------+----------------------+ 3952 | Soft Failure | Section 8.4.8.14 | OPTIONAL | 3953 +------------------+------------------+----------------------+ 3954 | Custom | Section 8.4.8.15 | OPTIONAL | 3955 +------------------+------------------+----------------------+ 3957 Table 16 3959 Authors' Addresses 3961 Brendan Moran 3962 Arm Limited 3964 Email: Brendan.Moran@arm.com 3966 Hannes Tschofenig 3967 Arm Limited 3969 Email: hannes.tschofenig@arm.com 3971 Henk Birkholz 3972 Fraunhofer SIT 3974 Email: henk.birkholz@sit.fraunhofer.de 3975 Koen Zandberg 3976 Inria 3978 Email: koen.zandberg@inria.fr