idnits 2.17.00 (12 Aug 2021) /tmp/idnits37480/draft-ietf-suit-manifest-14.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 1 instance 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 (July 12, 2021) is 312 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) -- Looks like a reference, but probably isn't: '1' on line 2511 -- Looks like a reference, but probably isn't: '2' on line 2511 -- Looks like a reference, but probably isn't: '3' on line 2482 == Missing Reference: '-1' is mentioned on line 2511, but not defined == Missing Reference: '-2' is mentioned on line 2484, but not defined == Missing Reference: '-3' is mentioned on line 2488, but not defined -- Looks like a reference, but probably isn't: '4' on line 2488 -- Looks like a reference, but probably isn't: '0' on line 2511 ** Downref: Normative reference to an Informational draft: draft-ietf-cose-hash-algs (ref. 'I-D.ietf-cose-hash-algs') -- No information found for draft-ietf-cbor-tags-oid - is the name correct? == Outdated reference: A later version (-21) exists of draft-ietf-sacm-coswid-17 == Outdated reference: draft-ietf-suit-architecture has been published as RFC 9019 == Outdated reference: draft-ietf-suit-information-model has been published as RFC 9124 == Outdated reference: A later version (-17) exists of draft-ietf-teep-architecture-14 Summary: 1 error (**), 0 flaws (~~), 9 warnings (==), 8 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: January 13, 2022 H. Birkholz 6 Fraunhofer SIT 7 K. Zandberg 8 Inria 9 July 12, 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-14 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 January 13, 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 50 (https://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 61 2. Conventions and Terminology . . . . . . . . . . . . . . . . . 6 62 3. How to use this Document . . . . . . . . . . . . . . . . . . 8 63 4. Background . . . . . . . . . . . . . . . . . . . . . . . . . 9 64 4.1. IoT Firmware Update Constraints . . . . . . . . . . . . . 9 65 4.2. SUIT Workflow Model . . . . . . . . . . . . . . . . . . . 10 66 5. Metadata Structure Overview . . . . . . . . . . . . . . . . . 11 67 5.1. Envelope . . . . . . . . . . . . . . . . . . . . . . . . 12 68 5.2. Delegation Chains . . . . . . . . . . . . . . . . . . . . 13 69 5.3. Authentication Block . . . . . . . . . . . . . . . . . . 13 70 5.4. Manifest . . . . . . . . . . . . . . . . . . . . . . . . 13 71 5.4.1. Critical Metadata . . . . . . . . . . . . . . . . . . 14 72 5.4.2. Common . . . . . . . . . . . . . . . . . . . . . . . 14 73 5.4.3. Command Sequences . . . . . . . . . . . . . . . . . . 14 74 5.4.4. Integrity Check Values . . . . . . . . . . . . . . . 15 75 5.4.5. Human-Readable Text . . . . . . . . . . . . . . . . . 15 76 5.5. Severable Elements . . . . . . . . . . . . . . . . . . . 15 77 5.6. Integrated Dependencies and Payloads . . . . . . . . . . 16 78 6. Manifest Processor Behavior . . . . . . . . . . . . . . . . . 16 79 6.1. Manifest Processor Setup . . . . . . . . . . . . . . . . 16 80 6.2. Required Checks . . . . . . . . . . . . . . . . . . . . . 17 81 6.2.1. Minimizing Signature Verifications . . . . . . . . . 19 82 6.3. Interpreter Fundamental Properties . . . . . . . . . . . 20 83 6.4. Abstract Machine Description . . . . . . . . . . . . . . 20 84 6.5. Special Cases of Component Index and Dependency Index . . 23 85 6.6. Serialized Processing Interpreter . . . . . . . . . . . . 24 86 6.7. Parallel Processing Interpreter . . . . . . . . . . . . . 25 87 6.8. Processing Dependencies . . . . . . . . . . . . . . . . . 25 88 6.9. Multiple Manifest Processors . . . . . . . . . . . . . . 26 89 7. Creating Manifests . . . . . . . . . . . . . . . . . . . . . 27 90 7.1. Compatibility Check Template . . . . . . . . . . . . . . 28 91 7.2. Trusted Invocation Template . . . . . . . . . . . . . . . 28 92 7.3. Component Download Template . . . . . . . . . . . . . . . 28 93 7.4. Install Template . . . . . . . . . . . . . . . . . . . . 29 94 7.5. Install and Transform Template . . . . . . . . . . . . . 30 95 7.6. Integrated Payload Template . . . . . . . . . . . . . . . 31 96 7.7. Load from Nonvolatile Storage Template . . . . . . . . . 31 97 7.8. Load & Decompress from Nonvolatile Storage Template . . . 31 98 7.9. Dependency Template . . . . . . . . . . . . . . . . . . . 32 99 7.9.1. Composite Manifests . . . . . . . . . . . . . . . . . 33 100 7.10. Encrypted Manifest Template . . . . . . . . . . . . . . . 33 101 7.11. A/B Image Template . . . . . . . . . . . . . . . . . . . 34 102 8. Metadata Structure . . . . . . . . . . . . . . . . . . . . . 35 103 8.1. Encoding Considerations . . . . . . . . . . . . . . . . . 35 104 8.2. Envelope . . . . . . . . . . . . . . . . . . . . . . . . 36 105 8.3. Delegation Chains . . . . . . . . . . . . . . . . . . . . 36 106 8.4. Authenticated Manifests . . . . . . . . . . . . . . . . . 36 107 8.5. Encrypted Manifests . . . . . . . . . . . . . . . . . . . 37 108 8.6. Manifest . . . . . . . . . . . . . . . . . . . . . . . . 37 109 8.6.1. suit-manifest-version . . . . . . . . . . . . . . . . 38 110 8.6.2. suit-manifest-sequence-number . . . . . . . . . . . . 38 111 8.6.3. suit-reference-uri . . . . . . . . . . . . . . . . . 38 112 8.6.4. suit-text . . . . . . . . . . . . . . . . . . . . . . 38 113 8.7. text-version-required . . . . . . . . . . . . . . . . . . 40 114 8.7.1. suit-coswid . . . . . . . . . . . . . . . . . . . . . 41 115 8.7.2. suit-common . . . . . . . . . . . . . . . . . . . . . 41 116 8.7.3. SUIT_Command_Sequence . . . . . . . . . . . . . . . . 43 117 8.7.4. Reporting Policy . . . . . . . . . . . . . . . . . . 45 118 8.7.5. SUIT_Parameters . . . . . . . . . . . . . . . . . . . 46 119 8.7.6. SUIT_Condition . . . . . . . . . . . . . . . . . . . 57 120 8.7.7. SUIT_Directive . . . . . . . . . . . . . . . . . . . 61 121 8.7.8. suit-directive-unlink . . . . . . . . . . . . . . . . 68 122 8.7.9. Integrity Check Values . . . . . . . . . . . . . . . 69 123 8.8. Severable Elements . . . . . . . . . . . . . . . . . . . 69 124 9. Access Control Lists . . . . . . . . . . . . . . . . . . . . 70 125 10. SUIT Digest Container . . . . . . . . . . . . . . . . . . . . 70 126 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 71 127 11.1. SUIT Commands . . . . . . . . . . . . . . . . . . . . . 71 128 11.2. SUIT Parameters . . . . . . . . . . . . . . . . . . . . 73 129 11.3. SUIT Text Values . . . . . . . . . . . . . . . . . . . . 75 130 11.4. SUIT Component Text Values . . . . . . . . . . . . . . . 75 131 11.5. SUIT Algorithm Identifiers . . . . . . . . . . . . . . . 75 132 11.5.1. SUIT Compression Algorithm Identifiers . . . . . . . 75 133 11.5.2. Unpack Algorithms . . . . . . . . . . . . . . . . . 76 134 12. Security Considerations . . . . . . . . . . . . . . . . . . . 76 135 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 76 136 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 77 137 14.1. Normative References . . . . . . . . . . . . . . . . . . 77 138 14.2. Informative References . . . . . . . . . . . . . . . . . 78 139 Appendix A. A. Full CDDL . . . . . . . . . . . . . . . . . . . . 80 140 Appendix B. B. Examples . . . . . . . . . . . . . . . . . . . . 89 141 B.1. Example 0: Secure Boot . . . . . . . . . . . . . . . . . 90 142 B.2. Example 1: Simultaneous Download and Installation of 143 Payload . . . . . . . . . . . . . . . . . . . . . . . . . 92 145 B.3. Example 2: Simultaneous Download, Installation, Secure 146 Boot, Severed Fields . . . . . . . . . . . . . . . . . . 94 147 B.4. Example 3: A/B images . . . . . . . . . . . . . . . . . . 98 148 B.5. Example 4: Load and Decompress from External Storage . . 101 149 B.6. Example 5: Two Images . . . . . . . . . . . . . . . . . . 104 150 Appendix C. C. Design Rational . . . . . . . . . . . . . . . . . 107 151 C.1. C.1 Design Rationale: Envelope . . . . . . . . . . . . . 108 152 C.2. C.2 Byte String Wrappers . . . . . . . . . . . . . . . . 109 153 Appendix D. D. Implementation Conformance Matrix . . . . . . . . 109 154 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 113 156 1. Introduction 158 A firmware update mechanism is an essential security feature for IoT 159 devices to deal with vulnerabilities. While the transport of 160 firmware images to the devices themselves is important there are 161 already various techniques available. Equally important is the 162 inclusion of metadata about the conveyed firmware image (in the form 163 of a manifest) and the use of a security wrapper to provide end-to- 164 end security protection to detect modifications and (optionally) to 165 make reverse engineering more difficult. End-to-end security allows 166 the author, who builds the firmware image, to be sure that no other 167 party (including potential adversaries) can install firmware updates 168 on IoT devices without adequate privileges. For confidentiality 169 protected firmware images it is additionally required to encrypt the 170 firmware image. Starting security protection at the author is a risk 171 mitigation technique so firmware images and manifests can be stored 172 on untrusted repositories; it also reduces the scope of a compromise 173 of any repository or intermediate system to be no worse than a denial 174 of service. 176 A manifest is a bundle of metadata describing one or more code or 177 data payloads and how to: 179 - Obtain any dependencies 181 - Obtain the payload(s) 183 - Install them 185 - Verify them 187 - Load them into memory 189 - Invoke them 191 This specification defines the SUIT manifest format and it is 192 intended to meet several goals: 194 - Meet the requirements defined in 195 [I-D.ietf-suit-information-model]. 197 - Simple to parse on a constrained node 199 - Simple to process on a constrained node 201 - Compact encoding 203 - Comprehensible by an intermediate system 205 - Expressive enough to enable advanced use cases on advanced nodes 207 - Extensible 209 The SUIT manifest can be used for a variety of purposes throughout 210 its lifecycle, such as: 212 - a Firmware Author to reason about releasing a firmware. 214 - a Network Operator to reason about compatibility of a firmware. 216 - a Device Operator to reason about the impact of a firmware. 218 - the Device Operator to manage distribution of firmware to devices. 220 - a Plant Manager to reason about timing and acceptance of firmware 221 updates. 223 - a device to reason about the authority & authenticity of a 224 firmware prior to installation. 226 - a device to reason about the applicability of a firmware. 228 - a device to reason about the installation of a firmware. 230 - a device to reason about the authenticity & encoding of a firmware 231 at boot. 233 Each of these uses happens at a different stage of the manifest 234 lifecycle, so each has different requirements. 236 It is assumed that the reader is familiar with the high-level 237 firmware update architecture [I-D.ietf-suit-architecture] and the 238 threats, requirements, and user stories in 239 [I-D.ietf-suit-information-model]. 241 The design of this specification is based on an observation that the 242 vast majority of operations that a device can perform during an 243 update or Trusted Invocation are composed of a small group of 244 operations: 246 - Copy some data from one place to another 248 - Transform some data 250 - Digest some data and compare to an expected value 252 - Compare some system parameters to an expected value 254 - Run some code 256 In this document, these operations are called commands. Commands are 257 classed as either conditions or directives. Conditions have no side- 258 effects, while directives do have side-effects. Conceptually, a 259 sequence of commands is like a script but the used language is 260 tailored to software updates and Trusted Invocation. 262 The available commands support simple steps, such as copying a 263 firmware image from one place to another, checking that a firmware 264 image is correct, verifying that the specified firmware is the 265 correct firmware for the device, or unpacking a firmware. By using 266 these steps in different orders and changing the parameters they use, 267 a broad range of use cases can be supported. The SUIT manifest uses 268 this observation to optimize metadata for consumption by constrained 269 devices. 271 While the SUIT manifest is informed by and optimized for firmware 272 update and Trusted Invocation use cases, there is nothing in the 273 [I-D.ietf-suit-information-model] that restricts its use to only 274 those use cases. Other use cases include the management of trusted 275 applications (TAs) in a Trusted Execution Environment (TEE), as 276 discussed in [I-D.ietf-teep-architecture]. 278 2. Conventions and Terminology 280 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 281 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 282 "OPTIONAL" in this document are to be interpreted as described in 283 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 284 capitals, as shown here. 286 Additionally, the following terminology is used throughout this 287 document: 289 - SUIT: Software Update for the Internet of Things, also the IETF 290 working group for this standard. 292 - Payload: A piece of information to be delivered. Typically 293 Firmware for the purposes of SUIT. 295 - Resource: A piece of information that is used to construct a 296 payload. 298 - Manifest: A manifest is a bundle of metadata about the firmware 299 for an IoT device, where to find the firmware, and the devices to 300 which it applies. 302 - Envelope: A container with the manifest, an authentication wrapper 303 with cryptographic information protecting the manifest, 304 authorization information, and severable elements (see: TBD). 306 - Update: One or more manifests that describe one or more payloads. 308 - Update Authority: The owner of a cryptographic key used to sign 309 updates, trusted by Recipients. 311 - Recipient: The system, typically an IoT device, that receives and 312 processes a manifest. 314 - Manifest Processor: A component of the Recipient that consumes 315 Manifests and executes the commands in the Manifest. 317 - Component: An updatable logical block of the Firmware, Software, 318 configuration, or data of the Recipient. 320 - Component Set: A group of interdependent Components that must be 321 updated simultaneously. 323 - Command: A Condition or a Directive. 325 - Condition: A test for a property of the Recipient or its 326 Components. 328 - Directive: An action for the Recipient to perform. 330 - Trusted Invocation: A process by which a system ensures that only 331 trusted code is executed, for example secure boot or launching a 332 Trusted Application. 334 - A/B images: Dividing a Recipient's storage into two or more 335 bootable images, at different offsets, such that the active image 336 can write to the inactive image(s). 338 - Record: The result of a Command and any metadata about it. 340 - Report: A list of Records. 342 - Procedure: The process of invoking one or more sequences of 343 commands. 345 - Update Procedure: A procedure that updates a Recipient by fetching 346 dependencies and images, and installing them. 348 - Invocation Procedure: A procedure in which a Recipient verifies 349 dependencies and images, loading images, and invokes one or more 350 image. 352 - Software: Instructions and data that allow a Recipient to perform 353 a useful function. 355 - Firmware: Software that is typically changed infrequently, stored 356 in nonvolatile memory, and small enough to apply to [RFC7228] 357 Class 0-2 devices. 359 - Image: Information that a Recipient uses to perform its function, 360 typically firmware/software, configuration, or resource data such 361 as text or images. Also, a Payload, once installed is an Image. 363 - Slot: One of several possible storage locations for a given 364 Component, typically used in A/B image systems 366 - Abort: An event in which the Manifest Processor immediately halts 367 execution of the current Procedure. It creates a Record of an 368 error condition. 370 3. How to use this Document 372 This specification covers five aspects of firmware update: 374 - Section 4 describes the device constraints, use cases, and design 375 principles that informed the structure of the manifest. 377 - Section 5 gives a general overview of the metadata structure to 378 inform the following sections 380 - Section 6 describes what actions a Manifest processor should take. 382 - Section 7 describes the process of creating a Manifest. 384 - Section 8 specifies the content of the Envelope and the Manifest. 386 To implement an updatable device, see Section 6 and Section 8. To 387 implement a tool that generates updates, see Section 7 and Section 8. 389 The IANA consideration section, see Section 11, provides instructions 390 to IANA to create several registries. This section also provides the 391 CBOR labels for the structures defined in this document. 393 The complete CDDL description is provided in Appendix A, examples are 394 given in Appendix B and a design rational is offered in Appendix C. 395 Finally, Appendix D gives a summarize of the mandatory-to-implement 396 features of this specification. 398 4. Background 400 Distributing software updates to diverse devices with diverse trust 401 anchors in a coordinated system presents unique challenges. Devices 402 have a broad set of constraints, requiring different metadata to make 403 appropriate decisions. There may be many actors in production IoT 404 systems, each of whom has some authority. Distributing firmware in 405 such a multi-party environment presents additional challenges. Each 406 party requires a different subset of data. Some data may not be 407 accessible to all parties. Multiple signatures may be required from 408 parties with different authorities. This topic is covered in more 409 depth in [I-D.ietf-suit-architecture]. The security aspects are 410 described in [I-D.ietf-suit-information-model]. 412 4.1. IoT Firmware Update Constraints 414 The various constraints of IoT devices and the range of use cases 415 that need to be supported create a broad set of requirements. For 416 example, devices with: 418 - limited processing power and storage may require a simple 419 representation of metadata. 421 - bandwidth constraints may require firmware compression or partial 422 update support. 424 - bootloader complexity constraints may require simple selection 425 between two bootable images. 427 - small internal storage may require external storage support. 429 - multiple microcontrollers may require coordinated update of all 430 applications. 432 - large storage and complex functionality may require parallel 433 update of many software components. 435 - extra information may need to be conveyed in the manifest in the 436 earlier stages of the device lifecycle before those data items are 437 stripped when the manifest is delivered to a constrained device. 439 Supporting the requirements introduced by the constraints on IoT 440 devices requires the flexibility to represent a diverse set of 441 possible metadata, but also requires that the encoding is kept 442 simple. 444 4.2. SUIT Workflow Model 446 There are several fundamental assumptions that inform the model of 447 Update Procedure workflow: 449 - Compatibility must be checked before any other operation is 450 performed. 452 - All dependency manifests should be present before any payload is 453 fetched. 455 - In some applications, payloads must be fetched and validated prior 456 to installation. 458 There are several fundamental assumptions that inform the model of 459 the Invocation Procedure workflow: 461 - Compatibility must be checked before any other operation is 462 performed. 464 - All dependencies and payloads must be validated prior to loading. 466 - All loaded images must be validated prior to execution. 468 Based on these assumptions, the manifest is structured to work with a 469 pull parser, where each section of the manifest is used in sequence. 470 The expected workflow for a Recipient installing an update can be 471 broken down into five steps: 473 1. Verify the signature of the manifest. 475 2. Verify the applicability of the manifest. 477 3. Resolve dependencies. 479 4. Fetch payload(s). 481 5. Install payload(s). 483 When installation is complete, similar information can be used for 484 validating and running images in a further three steps: 486 1. Verify image(s). 488 2. Load image(s). 490 3. Run image(s). 492 If verification and running is implemented in a bootloader, then the 493 bootloader MUST also verify the signature of the manifest and the 494 applicability of the manifest in order to implement secure boot 495 workflows. The bootloader may add its own authentication, e.g. a 496 Message Authentication Code (MAC), to the manifest in order to 497 prevent further verifications. 499 When multiple manifests are used for an update, each manifest's steps 500 occur in a lockstep fashion; all manifests have dependency resolution 501 performed before any manifest performs a payload fetch, etc. 503 5. Metadata Structure Overview 505 This section provides a high level overview of the manifest 506 structure. The full description of the manifest structure is in 507 Section 8.6 509 The manifest is structured from several key components: 511 1. The Envelope (see Section 5.1) contains Delegation Chains, the 512 Authentication Block, the Manifest, any Severable Elements, and 513 any Integrated Payloads or Dependencies. 515 2. Delegation Chains (see Section 5.2) allow a Recipient to work 516 from one of its Trust Anchors to an authority of the 517 Authentication Block. 519 3. The Authentication Block (see Section 5.3) contains a list of 520 signatures or MACs of the manifest.. 522 4. The Manifest (see Section 5.4) contains all critical, non- 523 severable metadata that the Recipient requires. It is further 524 broken down into: 526 1. Critical metadata, such as sequence number. 528 2. Common metadata, including lists of dependencies and affected 529 components. 531 3. Command sequences, directing the Recipient how to install and 532 use the payload(s). 534 4. Integrity check values for severable elements. 536 5. Severable elements (see Section 5.5). 538 6. Integrated dependencies (see Section 5.6). 540 7. Integrated payloads (see Section 5.6). 542 The diagram below illustrates the hierarchy of the Envelope. 544 +-------------------------+ 545 | Envelope | 546 +-------------------------+ 547 | Delegation Chains | 548 | Authentication Block | 549 | Manifest --------------> +------------------------------+ 550 | Severable Elements | | Manifest | 551 | Human-Readable Text | +------------------------------+ 552 | COSWID | | Structure Version | 553 | Integrated Dependencies | | Sequence Number | 554 | Integrated Payloads | | Reference to Full Manifest | 555 +-------------------------+ +------ Common Structure | 556 | +---- Command Sequences | 557 +-------------------------+ | | | Digests of Envelope Elements | 558 | Common Structure | <--+ | +------------------------------+ 559 +-------------------------+ | 560 | Dependencies | +-> +-----------------------+ 561 | Components IDs | | Command Sequence | 562 | Common Command Sequence ---------> +-----------------------+ 563 +-------------------------+ | List of ( pairs of ( | 564 | * command code | 565 | * argument / | 566 | reporting policy | 567 | )) | 568 +-----------------------+ 570 5.1. Envelope 572 The SUIT Envelope is a container that encloses Delegation Chains, the 573 Authentication Block, the Manifest, any Severable Elements, and any 574 integrated payloads or dependencies. The Envelope is used instead of 575 conventional cryptographic envelopes, such as COSE_Envelope because 576 it allows modular processing, severing of elements, and integrated 577 payloads in a way that would add substantial complexity with existing 578 solutions. See Appendix C.1 for a description of the reasoning for 579 this. 581 See Section 8.2 for more detail. 583 5.2. Delegation Chains 585 Delegation Chains allow a Recipient to establish a chain of trust 586 from a Trust Anchor to the signer of a manifest by validating 587 delegation claims. Each delegation claim is a [RFC8392] CBOR Web 588 Tokens (CWTs). The first claim in each list is signed by a Trust 589 Anchor. Each subsequent claim in a list is signed by the public key 590 claimed in the preceding list element. The last element in each list 591 claims a public key that can be used to verify a signature in the 592 Authentication Block (Section 5.3). 594 See Section 8.3 for more detail. 596 5.3. Authentication Block 598 The Authentication Block contains a bstr-wrapped SUIT Digest 599 Container, see Section 10, and one or more [RFC8152] CBOR Object 600 Signing and Encryption (COSE) authentication blocks. These blocks 601 are one of: 603 - COSE_Sign_Tagged 605 - COSE_Sign1_Tagged 607 - COSE_Mac_Tagged 609 - COSE_Mac0_Tagged 611 Each of these objects is used in detached payload mode. The payload 612 is the bstr-wrapped SUIT_Digest. 614 See Section 8.4 for more detail. 616 5.4. Manifest 618 The Manifest contains most metadata about one or more images. The 619 Manifest is divided into Critical Metadata, Common Metadata, Command 620 Sequences, and Integrity Check Values. 622 See Section 8.6 for more detail. 624 5.4.1. Critical Metadata 626 Some metadata needs to be accessed before the manifest is processed. 627 This metadata can be used to determine which manifest is newest and 628 whether the structure version is supported. It also MAY provide a 629 URI for obtaining a canonical copy of the manifest and Envelope. 631 See Section 8.6.1, Section 8.6.2, and Section 8.6.3 for more detail. 633 5.4.2. Common 635 Some metadata is used repeatedly and in more than one command 636 sequence. In order to reduce the size of the manifest, this metadata 637 is collected into the Common section. Common is composed of three 638 parts: a list of dependencies, a list of components referenced by the 639 manifest, and a command sequence to execute prior to each other 640 command sequence. The common command sequence is typically used to 641 set commonly used values and perform compatibility checks. The 642 common command sequence MUST NOT have any side-effects outside of 643 setting parameter values. 645 See Section 8.7.2, and Section 8.7.2.1 for more detail. 647 5.4.3. Command Sequences 649 Command sequences provide the instructions that a Recipient requires 650 in order to install or use an image. These sequences tell a device 651 to set parameter values, test system parameters, copy data from one 652 place to another, transform data, digest data, and run code. 654 Command sequences are broken up into three groups: Common Command 655 Sequence (see Section 5.4.2), update commands, and secure boot 656 commands. 658 Update Command Sequences are: Dependency Resolution, Payload Fetch, 659 and Payload Installation. An Update Procedure is the complete set of 660 each Update Command Sequence, each preceded by the Common Command 661 Sequence. 663 Invocation Command Sequences are: System Validation, Image Loading, 664 and Image Invocation. A Invocation Procedure is the complete set of 665 each Invocation Command Sequence, each preceded by the Common Command 666 Sequence. 668 Command Sequences are grouped into these sets to ensure that there is 669 common coordination between dependencies and dependents on when to 670 execute each command. 672 See Section 8.7.3 for more detail. 674 5.4.4. Integrity Check Values 676 To enable Section 5.5, there needs to be a mechanism to verify 677 integrity of any metadata outside the manifest. Integrity Check 678 Values are used to verify the integrity of metadata that is not 679 contained in the manifest. This MAY include Severable Command 680 Sequences, Concise Software Identifiers (CoSWID 681 [I-D.ietf-sacm-coswid]), or Text data. Integrated Dependencies and 682 Integrated Payloads are integrity-checked using Command Sequences, so 683 they do not have Integrity Check Values present in the Manifest. 685 See Section 8.7.9 for more detail. 687 5.4.5. Human-Readable Text 689 Text is typically a Severable Element (Section 5.5). It contains all 690 the text that describes the update. Because text is explicitly for 691 human consumption, it is all grouped together so that it can be 692 Severed easily. The text section has space both for describing the 693 manifest as a whole and for describing each individual component. 695 See Section 8.6.4 for more detail. 697 5.5. Severable Elements 699 Severable Elements are elements of the Envelope (Section 5.1) that 700 have Integrity Check Values (Section 5.4.4) in the Manifest 701 (Section 5.4). 703 Because of this organisation, these elements can be discarded or 704 "Severed" from the Envelope without changing the signature of the 705 Manifest. This allows savings based on the size of the Envelope in 706 several scenarios, for example: 708 - A management system severs the Text and CoSWID sections before 709 sending an Envelope to a constrained Recipient, which saves 710 Recipient bandwidth. 712 - A Recipient severs the Installation section after installing the 713 Update, which saves storage space. 715 See Section 8.8 for more detail. 717 5.6. Integrated Dependencies and Payloads 719 In some cases, it is beneficial to include a dependency or a payload 720 in the Envelope of a manifest. For example: 722 - When an update is delivered via a comparatively unconstrained 723 medium, such as a removable mass storage device, it may be 724 beneficial to bundle updates into single files. 726 - When a manifest requires encryption, it must be referenced as a 727 dependency, so a trivial manifest may be used to enclose the 728 encrypted manifest. The encrypted manifest may be contained in 729 the dependent manifest's envelope. 731 - When a manifest transports a small payload, such as an encrypted 732 key, that payload may be placed in the manifest's envelope. 734 See Section 7.9.1, Section 8.5 for more detail. 736 6. Manifest Processor Behavior 738 This section describes the behavior of the manifest processor and 739 focuses primarily on interpreting commands in the manifest. However, 740 there are several other important behaviors of the manifest 741 processor: encoding version detection, rollback protection, and 742 authenticity verification are chief among these. 744 6.1. Manifest Processor Setup 746 Prior to executing any command sequence, the manifest processor or 747 its host application MUST inspect the manifest version field and fail 748 when it encounters an unsupported encoding version. Next, the 749 manifest processor or its host application MUST extract the manifest 750 sequence number and perform a rollback check using this sequence 751 number. The exact logic of rollback protection may vary by 752 application, but it has the following properties: 754 - Whenever the manifest processor can choose between several 755 manifests, it MUST select the latest valid, authentic manifest. 757 - If the latest valid, authentic manifest fails, it MAY select the 758 next latest valid, authentic manifest, according to application- 759 specific policy. 761 Here, valid means that a manifest has a supported encoding version 762 and it has not been excluded for other reasons. Reasons for 763 excluding typically involve first executing the manifest and may 764 include: 766 - Test failed (e.g. Vendor ID/Class ID). 768 - Unsupported command encountered. 770 - Unsupported parameter encountered. 772 - Unsupported Component Identifier encountered. 774 - Payload not available. 776 - Dependency not available. 778 - Application crashed when executed. 780 - Watchdog timeout occurred. 782 - Dependency or Payload verification failed. 784 - Missing component from a set. 786 - Required parameter not supplied. 788 These failure reasons MAY be combined with retry mechanisms prior to 789 marking a manifest as invalid. 791 Selecting an older manifest in the event of failure of the latest 792 valid manifest is a robustness mechanism that is necessary for 793 supporting the requirements in [I-D.ietf-suit-architecture], section 794 3.5. It may not be appropriate for all applications. In particular 795 Trusted Execution Environments MAY require a failure to invoke a new 796 installation, rather than a rollback approach. See 797 [I-D.ietf-suit-information-model], Section 4.2.1 for more discussion 798 on the security considerations that apply to rollback. 800 Following these initial tests, the manifest processor clears all 801 parameter storage. This ensures that the manifest processor begins 802 without any leaked data. 804 6.2. Required Checks 806 The RECOMMENDED process is to verify the signature of the manifest 807 prior to parsing/executing any section of the manifest. This guards 808 the parser against arbitrary input by unauthenticated third parties, 809 but it costs extra energy when a Recipient receives an incompatible 810 manifest. 812 When validating authenticity of manifests, the manifest processor MAY 813 use an ACL (see Section 9) to determine the extent of the rights 814 conferred by that authenticity. Where a device supports only one 815 level of access, it MAY choose to skip signature verification of 816 dependencies, since they are referenced by digest. Where a device 817 supports more than one trusted party, it MAY choose to defer the 818 verification of signatures of dependencies until the list of affected 819 components is known so that it can skip redundant signature 820 verifications. For example, a dependency signed by the same author 821 as the dependent does not require a signature verification. 822 Similarly, if the signer of the dependent has full rights to the 823 device, according to the ACL, then no signature verification is 824 necessary on the dependency. 826 Once a valid, authentic manifest has been selected, the manifest 827 processor MUST examine the component list and verify that its maximum 828 number of components is not exceeded and that each listed component 829 is supported. 831 For each listed component, the manifest processor MUST provide 832 storage for the supported parameters. If the manifest processor does 833 not have sufficient temporary storage to process the parameters for 834 all components, it MAY process components serially for each command 835 sequence. See Section 6.6 for more details. 837 The manifest processor SHOULD check that the common sequence contains 838 at least Check Vendor Identifier command and at least one Check Class 839 Identifier command. 841 Because the common sequence contains Check Vendor Identifier and 842 Check Class Identifier command(s), no custom commands are permitted 843 in the common sequence. This ensures that any custom commands are 844 only executed by devices that understand them. 846 If the manifest contains more than one component and/or dependency, 847 each command sequence MUST begin with a Set Component Index or Set 848 Dependency Index command. 850 If a dependency is specified, then the manifest processor MUST 851 perform the following checks: 853 1. At the beginning of each section in the dependent: all previous 854 sections of each dependency have been executed. 856 2. At the end of each section in the dependent: The corresponding 857 section in each dependency has been executed. 859 If the interpreter does not support dependencies and a manifest 860 specifies a dependency, then the interpreter MUST reject the 861 manifest. 863 If a Recipient supports groups of interdependent components (a 864 Component Set), then it SHOULD verify that all Components in the 865 Component Set are specified by one update, that is: a single manifest 866 and all its dependencies that together: 868 1. have sufficient permissions imparted by their signatures 870 2. specify a digest and a payload for every Component in the 871 Component Set. 873 The single dependent manifest is sometimes called a Root Manifest. 875 6.2.1. Minimizing Signature Verifications 877 Signature verification can be energy and time expensive on a 878 constrained device. MAC verification is typically unaffected by 879 these concerns. A Recipient MAY choose to parse and execute only the 880 SUIT_Common section of the manifest prior to signature verification, 881 if all of the below apply: 883 - The Authentication Block contains a COSE_Sign_Tagged or 884 COSE_Sign1_Tagged 886 - The Recipient receives manifests over an unauthenticated channel, 887 exposing it to more inauthentic or incompatible manifests, and 889 - The Recipient has a power budget that makes signature verification 890 undesirable 892 The guidelines in Creating Manifests (Section 7) require that the 893 common section contains the applicability checks, so this section is 894 sufficient for applicability verification. The parser MUST restrict 895 acceptable commands to conditions and the following directives: 896 Override Parameters, Set Parameters, Try Each, and Run Sequence ONLY. 897 The manifest parser MUST NOT execute any command with side-effects 898 outside the parser (for example, Run, Copy, Swap, or Fetch commands) 899 prior to authentication and any such command MUST Abort. The Common 900 Sequence MUST be executed again in its entirety after authenticity 901 validation. 903 When executing Common prior to authenticity validation, the Manifest 904 Processor MUST evaluate the integrity of the manifest using the 905 SUIT_Digest present in the authentication block. 907 Alternatively, a Recipient MAY rely on network infrastructure to 908 filter inapplicable manifests. 910 6.3. Interpreter Fundamental Properties 912 The interpreter has a small set of design goals: 914 1. Executing an update MUST either result in an error, or a 915 verifiably correct system state. 917 2. Executing a Trusted Invocation MUST either result in an error, or 918 an invoked image. 920 3. Executing the same manifest on multiple Recipients MUST result in 921 the same system state. 923 NOTE: when using A/B images, the manifest functions as two (or more) 924 logical manifests, each of which applies to a system in a particular 925 starting state. With that provision, design goal 3 holds. 927 6.4. Abstract Machine Description 929 The heart of the manifest is the list of commands, which are 930 processed by a Manifest Processor-a form of interpreter. This 931 Manifest Processor can be modeled as a simple abstract machine. This 932 machine consists of several data storage locations that are modified 933 by commands. 935 There are two types of commands, namely those that modify state 936 (directives) and those that perform tests (conditions). Parameters 937 are used as the inputs to commands. Some directives offer control 938 flow operations. Directives target a specific component or 939 dependency. A dependency is another SUIT_Envelope that describes 940 additional components. Dependencies are identified by digest, but 941 referenced in commands by Dependency Index, the index into the array 942 of Dependencies. A component is a unit of code or data that can be 943 targeted by an update. Components are identified by Component 944 Identifiers, but referenced in commands by Component Index; Component 945 Identifiers are arrays of binary strings and a Component Index is an 946 index into the array of Component Identifiers. 948 Conditions MUST NOT have any side-effects other than informing the 949 interpreter of success or failure. The Interpreter does not Abort if 950 the Soft Failure flag (Section 8.7.5.23) is set when a Condition 951 reports failure. 953 Directives MAY have side-effects in the parameter table, the 954 interpreter state, or the current component. The Interpreter MUST 955 Abort if a Directive reports failure regardless of the Soft Failure 956 flag. 958 To simplify the logic describing the command semantics, the object 959 "current" is used. It represents the component identified by the 960 Component Index or the dependency identified by the Dependency Index: 962 current := components\[component-index\] 963 if component-index is not false 964 else dependencies\[dependency-index\] 966 As a result, Set Component Index is described as current := 967 components[arg]. The actual operation performed for Set Component 968 Index is described by the following pseudocode, however, because of 969 the definition of current (above), these are semantically equivalent. 971 component-index := arg 972 dependency-index := false 974 Similarly, Set Dependency Index is semantically equivalent to current 975 := dependencies[arg] 977 The following table describes the behavior of each command. "params" 978 represents the parameters for the current component or dependency. 979 Most commands operate on either a component or a dependency. Setting 980 the Component Index clears the Dependency Index. Setting the 981 Dependency Index clears the Component Index. 983 +-------------------+-----------------------------------------------+ 984 | Command Name | Semantic of the Operation | 985 +-------------------+-----------------------------------------------+ 986 | Check Vendor | assert(binary-match(current, | 987 | Identifier | current.params[vendor-id])) | 988 | | | 989 | Check Class | assert(binary-match(current, | 990 | Identifier | current.params[class-id])) | 991 | | | 992 | Verify Image | assert(binary-match(digest(current), | 993 | | current.params[digest])) | 994 | | | 995 | Set Component | current := components[arg] | 996 | Index | | 997 | | | 998 | Override | current.params[k] := v for-each k,v in arg | 999 | Parameters | | 1000 | | | 1001 | Set Dependency | current := dependencies[arg] | 1002 | Index | | 1003 | | | 1004 | Set Parameters | current.params[k] := v if not k in params | 1005 | | for-each k,v in arg | 1006 | | | 1007 | Process | exec(current[common]); exec(current[current- | 1008 | Dependency | segment]) | 1009 | | | 1010 | Run | run(current) | 1011 | | | 1012 | Fetch | store(current, fetch(current.params[uri])) | 1013 | | | 1014 | Use Before | assert(now() < arg) | 1015 | | | 1016 | Check Component | assert(current.slot-index == arg) | 1017 | Slot | | 1018 | | | 1019 | Check Device | assert(binary-match(current, | 1020 | Identifier | current.params[device-id])) | 1021 | | | 1022 | Check Image Not | assert(not binary-match(digest(current), | 1023 | Match | current.params[digest])) | 1024 | | | 1025 | Check Minimum | assert(battery >= arg) | 1026 | Battery | | 1027 | | | 1028 | Check Update | assert(isAuthorized()) | 1029 | Authorized | | 1030 | | | 1031 | Check Version | assert(version_check(current, arg)) | 1032 | | | 1033 | Abort | assert(0) | 1034 | | | 1035 | Try Each | try-each-done if exec(seq) is not error for- | 1036 | | each seq in arg | 1037 | | | 1038 | Copy | store(current, current.params[src-component]) | 1039 | | | 1040 | Swap | swap(current, current.params[src-component]) | 1041 | | | 1042 | Wait For Event | until event(arg), wait | 1043 | | | 1044 | Run Sequence | exec(arg) | 1045 | | | 1046 | Run with | run(current, arg) | 1047 | Arguments | | 1048 | | | 1049 | Unlink | unlink(current) | 1050 +-------------------+-----------------------------------------------+ 1052 6.5. Special Cases of Component Index and Dependency Index 1054 Component Index and Dependency Index can each take on one of three 1055 types: 1057 1. Integer 1059 2. Array of integers 1061 3. True 1063 Integers MUST always be supported by Set Component Index and Set 1064 Dependency Index. Arrays of integers MUST be supported by Set 1065 Component Index and Set Dependency Index if the Recipient supports 3 1066 or more components or 3 or more dependencies, respectively. True 1067 MUST be supported by Set Component Index and Set Dependency Index if 1068 the Recipient supports 2 or more components or 2 or more 1069 dependencies, respectively. Each of these operates on the list of 1070 components or list of dependencies declared in the manifest. 1072 Integer indices are the default case as described in the previous 1073 section. An array of integers represents a list of the components 1074 (Set Component Index) or a list of dependencies (Set Dependency 1075 Index) to which each subsequent command applies. The value True 1076 replaces the list of component indices or dependency indices with the 1077 full list of components or the full list of dependencies, 1078 respectively, as defined in the manifest. 1080 When a command is executed, it either 1. operates on the component or 1081 dependency identified by the component index or dependency index if 1082 that index is an integer, or 2. it operates on each component or 1083 dependency identified by an array of indicies, or 3. it operates on 1084 every component or every dependency if the index is the boolean True. 1085 This is described by the following pseudocode: 1087 if component-index is true: 1088 current-list = components 1089 else if component-index is array: 1090 current-list = [ components[idx] for idx in component-index ] 1091 else if component-index is integer: 1092 current-list = [ components[component-index] ] 1093 else if dependency-index is true: 1094 current-list = dependencies 1095 else if dependency-index is array: 1096 current-list = [ dependencies[idx] for idx in dependency-index ] 1097 else: 1098 current-list = [ dependencies[dependency-index] ] 1099 for current in current-list: 1100 cmd(current) 1102 Try Each and Run Sequence are affected in the same way as other 1103 commands: they are invoked once for each possible Component or 1104 Dependency. This means that the sequences that are arguments to Try 1105 Each and Run Sequence are NOT invoked with Component Index = True or 1106 Dependency Index = True, nor are they invoked with array indices. 1107 They are only invoked with integer indices. The interpreter loops 1108 over the whole sequence, setting the Component Index or Dependency 1109 Index to each index in turn. 1111 6.6. Serialized Processing Interpreter 1113 In highly constrained devices, where storage for parameters is 1114 limited, the manifest processor MAY handle one component at a time, 1115 traversing the manifest tree once for each listed component. In this 1116 mode, the interpreter ignores any commands executed while the 1117 component index is not the current component. This reduces the 1118 overall volatile storage required to process the update so that the 1119 only limit on number of components is the size of the manifest. 1120 However, this approach requires additional processing power. 1122 In order to operate in this mode, the manifest processor loops on 1123 each section for every supported component, simply ignoring commands 1124 when the current component is not selected. 1126 When a serialized Manifest Processor encounters a component or 1127 dependency index of True, it does not ignore any commands. It 1128 applies them to the current component or dependency on each 1129 iteration. 1131 6.7. Parallel Processing Interpreter 1133 Advanced Recipients MAY make use of the Strict Order parameter and 1134 enable parallel processing of some Command Sequences, or it may 1135 reorder some Command Sequences. To perform parallel processing, once 1136 the Strict Order parameter is set to False, the Recipient may issue 1137 each or every command concurrently until the Strict Order parameter 1138 is returned to True or the Command Sequence ends. Then, it waits for 1139 all issued commands to complete before continuing processing of 1140 commands. To perform out-of-order processing, a similar approach is 1141 used, except the Recipient consumes all commands after the Strict 1142 Order parameter is set to False, then it sorts these commands into 1143 its preferred order, invokes them all, then continues processing. 1145 Under each of these scenarios the parallel processing MUST halt until 1146 all issued commands have completed: 1148 - Set Parameters. 1150 - Override Parameters. 1152 - Set Strict Order = True. 1154 - Set Dependency Index. 1156 - Set Component Index. 1158 To perform more useful parallel operations, a manifest author may 1159 collect sequences of commands in a Run Sequence command. Then, each 1160 of these sequences MAY be run in parallel. Each sequence defaults to 1161 Strict Order = True. To isolate each sequence from each other 1162 sequence, each sequence MUST begin with a Set Component Index or Set 1163 Dependency Index directive with the following exception: when the 1164 index is either True or an array of indices, the Set Component Index 1165 or Set Dependency Index is implied. Any further Set Component Index 1166 directives MUST cause an Abort. This allows the interpreter that 1167 issues Run Sequence commands to check that the first element is 1168 correct, then issue the sequence to a parallel execution context to 1169 handle the remainder of the sequence. 1171 6.8. Processing Dependencies 1173 As described in Section 6.2, each manifest must invoke each of its 1174 dependencies sections from the corresponding section of the 1175 dependent. Any changes made to parameters by the dependency persist 1176 in the dependent. 1178 When a Process Dependency command is encountered, the interpreter 1179 loads the dependency identified by the Current Dependency Index. The 1180 interpreter first executes the common-sequence section of the 1181 identified dependency, then it executes the section of the dependency 1182 that corresponds to the currently executing section of the dependent. 1184 If the specified dependency does not contain the current section, 1185 Process Dependency succeeds immediately. 1187 The Manifest Processor MUST also support a Dependency Index of True, 1188 which applies to every dependency, as described in Section 6.5 1190 The interpreter also performs the checks described in Section 6.2 to 1191 ensure that the dependent is processing the dependency correctly. 1193 6.9. Multiple Manifest Processors 1195 When a system has multiple security domains, each domain might 1196 require independent verification of authenticity or security 1197 policies. Security domains might be divided by separation technology 1198 such as Arm TrustZone, Intel SGX, or another TEE technology. 1199 Security domains might also be divided into separate processors and 1200 memory spaces, with a communication interface between them. 1202 For example, an application processor may have an attached 1203 communications module that contains a processor. The communications 1204 module might require metadata signed by a specific Trust Authority 1205 for regulatory approval. This may be a different Trust Authority 1206 than the application processor. 1208 When there are two or more security domains (see 1209 [I-D.ietf-teep-architecture]), a manifest processor might be required 1210 in each. The first manifest processor is the normal manifest 1211 processor as described for the Recipient in Section 6.4. The second 1212 manifest processor only executes sections when the first manifest 1213 processor requests it. An API interface is provided from the second 1214 manifest processor to the first. This allows the first manifest 1215 processor to request a limited set of operations from the second. 1216 These operations are limited to: setting parameters, inserting an 1217 Envelope, invoking a Manifest Command Sequence. The second manifest 1218 processor declares a prefix to the first, which tells the first 1219 manifest processor when it should delegate to the second. These 1220 rules are enforced by underlying separation of privilege 1221 infrastructure, such as TEEs, or physical separation. 1223 When the first manifest processor encounters a dependency prefix, 1224 that informs the first manifest processor that it should provide the 1225 second manifest processor with the corresponding dependency Envelope. 1227 This is done when the dependency is fetched. The second manifest 1228 processor immediately verifies any authentication information in the 1229 dependency Envelope. When a parameter is set for any component that 1230 matches the prefix, this parameter setting is passed to the second 1231 manifest processor via an API. As the first manifest processor works 1232 through the Procedure (set of command sequences) it is executing, 1233 each time it sees a Process Dependency command that is associated 1234 with the prefix declared by the second manifest processor, it uses 1235 the API to ask the second manifest processor to invoke that 1236 dependency section instead. 1238 This mechanism ensures that the two or more manifest processors do 1239 not need to trust each other, except in a very limited case. When 1240 parameter setting across security domains is used, it must be very 1241 carefully considered. Only parameters that do not have an effect on 1242 security properties should be allowed. The dependency manifest MAY 1243 control which parameters are allowed to be set by using the Override 1244 Parameters directive. The second manifest processor MAY also control 1245 which parameters may be set by the first manifest processor by means 1246 of an ACL that lists the allowed parameters. For example, a URI may 1247 be set by a dependent without a substantial impact on the security 1248 properties of the manifest. 1250 7. Creating Manifests 1252 Manifests are created using tools for constructing COSE structures, 1253 calculating cryptographic values and compiling desired system state 1254 into a sequence of operations required to achieve that state. The 1255 process of constructing COSE structures and the calculation of 1256 cryptographic values is covered in [RFC8152]. 1258 Compiling desired system state into a sequence of operations can be 1259 accomplished in many ways. Several templates are provided below to 1260 cover common use-cases. These templates can be combined to produce 1261 more complex behavior. 1263 The author MUST ensure that all parameters consumed by a command are 1264 set prior to invoking that command. Where Component Index = True or 1265 Dependency Index = True, this means that the parameters consumed by 1266 each command MUST have been set for each Component or Dependency, 1267 respectively. 1269 This section details a set of templates for creating manifests. 1270 These templates explain which parameters, commands, and orders of 1271 commands are necessary to achieve a stated goal. 1273 NOTE: On systems that support only a single component and no 1274 dependencies, Set Component Index has no effect and can be omitted. 1276 NOTE: *A digest MUST always be set using Override Parameters, since 1277 this prevents a less-privileged dependent from replacing the digest.* 1279 7.1. Compatibility Check Template 1281 The goal of the compatibility check template ensure that Recipients 1282 only install compatible images. 1284 In this template all information is contained in the common sequence 1285 and the following sequence of commands is used: 1287 - Set Component Index directive (see Section 8.7.7.1) 1289 - Set Parameters directive (see Section 8.7.7.5) for Vendor ID and 1290 Class ID (see Section 8.7.5) 1292 - Check Vendor Identifier condition (see Section 8.7.5.2) 1294 - Check Class Identifier condition (see Section 8.7.5.2) 1296 7.2. Trusted Invocation Template 1298 The goal of the Trusted Invocation template is to ensure that only 1299 authorized code is invoked; such as in Secure Boot or when a Trusted 1300 Application is loaded into a TEE. 1302 The following commands are placed into the common sequence: 1304 - Set Component Index directive (see Section 8.7.7.1) 1306 - Override Parameters directive (see Section 8.7.7.6) for Image 1307 Digest and Image Size (see Section 8.7.5) 1309 Then, the run sequence contains the following commands: 1311 - Set Component Index directive (see Section 8.7.7.1) 1313 - Check Image Match condition (see Section 8.7.6.2) 1315 - Run directive (see Section 8.7.7.12) 1317 7.3. Component Download Template 1319 The goal of the Component Download template is to acquire and store 1320 an image. 1322 The following commands are placed into the common sequence: 1324 - Set Component Index directive (see Section 8.7.7.1) 1326 - Override Parameters directive (see Section 8.7.7.6) for Image 1327 Digest and Image Size (see Section 8.7.5) 1329 Then, the install sequence contains the following commands: 1331 - Set Component Index directive (see Section 8.7.7.1) 1333 - Set Parameters directive (see Section 8.7.7.5) for URI (see 1334 Section 8.7.5.13) 1336 - Fetch directive (see Section 8.7.7.7) 1338 - Check Image Match condition (see Section 8.7.6.2) 1340 The Fetch directive needs the URI parameter to be set to determine 1341 where the image is retrieved from. Additionally, the destination of 1342 where the component shall be stored has to be configured. The URI is 1343 configured via the Set Parameters directive while the destination is 1344 configured via the Set Component Index directive. 1346 Optionally, the Set Parameters directive in the install sequence MAY 1347 also contain Encryption Info (see Section 8.7.5.10), Compression Info 1348 (see Section 8.7.5.11), or Unpack Info (see Section 8.7.5.12) to 1349 perform simultaneous download and decryption, decompression, or 1350 unpacking, respectively. 1352 7.4. Install Template 1354 The goal of the Install template is to use an image already stored in 1355 an identified component to copy into a second component. 1357 This template is typically used with the Component Download template, 1358 however a modification to that template is required: the Component 1359 Download operations are moved from the Payload Install sequence to 1360 the Payload Fetch sequence. 1362 Then, the install sequence contains the following commands: 1364 - Set Component Index directive (see Section 8.7.7.1) 1366 - Set Parameters directive (see Section 8.7.7.5) for Source 1367 Component (see Section 8.7.5.14) 1369 - Copy directive (see Section 8.7.7.9) 1371 - Check Image Match condition (see Section 8.7.6.2) 1373 7.5. Install and Transform Template 1375 The goal of the Install and Transform template is to use an image 1376 already stored in an identified component to decompress, decrypt, or 1377 unpack at time of installation. 1379 This template is typically used with the Component Download template, 1380 however a modification to that template is required: all Component 1381 Download operations are moved from the common sequence and the 1382 install sequence to the fetch sequence. The Component Download 1383 template targets a download component identifier, while the Install 1384 and Transform template uses an install component identifier. In- 1385 place unpacking, decompression, and decryption is complex and 1386 vulnerable to power failure. Therefore, these identifiers SHOULD be 1387 different; in-place installation SHOULD NOT be used without 1388 establishing guarantees of robustness to power failure. 1390 The following commands are placed into the common sequence: 1392 - Set Component Index directive for install component identifier 1393 (see Section 8.7.7.1) 1395 - Override Parameters directive (see Section 8.7.7.6) for Image 1396 Digest and Image Size (see Section 8.7.5) 1398 Then, the install sequence contains the following commands: 1400 - Set Component Index directive for install component identifier 1401 (see Section 8.7.7.1) 1403 - Set Parameters directive (see Section 8.7.7.5) for: 1405 o Source Component for download component identifier (see 1406 Section 8.7.5.14) 1408 o Encryption Info (see Section 8.7.5.10) 1410 o Compression Info (see Section 8.7.5.11) 1412 o Unpack Info (see Section 8.7.5.12) 1414 - Copy directive (see Section 8.7.7.9) 1416 - Check Image Match condition (see Section 8.7.6.2) 1418 7.6. Integrated Payload Template 1420 The goal of the Integrated Payload template is to install a payload 1421 that is included in the manifest envelope. It is identical to the 1422 Component Download template (Section 7.3) except that it places an 1423 added restriction on the URI passed to the Set Parameters directive. 1425 An implementer MAY choose to place a payload in the envelope of a 1426 manifest. The payload envelope key MAY be a positive or negative 1427 integer. The payload envelope key MUST NOT be a value between 0 and 1428 24 and it MUST NOT be used by any other envelope element in the 1429 manifest. The payload MUST be serialized in a bstr element. 1431 The URI for a payload enclosed in this way MUST be expressed as a 1432 fragment-only reference, as defined in [RFC3986], Section 4.4. The 1433 fragment identifier is the stringified envelope key of the payload. 1434 For example, an envelope that contains a payload a key 42 would use a 1435 URI "#42", key -73 would use a URI "#-73". 1437 7.7. Load from Nonvolatile Storage Template 1439 The goal of the Load from Nonvolatile Storage template is to load an 1440 image from a non-volatile component into a volatile component, for 1441 example loading a firmware image from external Flash into RAM. 1443 The following commands are placed into the load sequence: 1445 - Set Component Index directive (see Section 8.7.7.1) 1447 - Set Parameters directive (see Section 8.7.7.5) for Component Index 1448 (see Section 8.7.5) 1450 - Copy directive (see Section 8.7.7.9) 1452 As outlined in Section 6.4, the Copy directive needs a source and a 1453 destination to be configured. The source is configured via Component 1454 Index (with the Set Parameters directive) and the destination is 1455 configured via the Set Component Index directive. 1457 7.8. Load & Decompress from Nonvolatile Storage Template 1459 The goal of the Load & Decompress from Nonvolatile Storage template 1460 is to load an image from a non-volatile component into a volatile 1461 component, decompressing on-the-fly, for example loading a firmware 1462 image from external Flash into RAM. 1464 The following commands are placed into the load sequence: 1466 - Set Component Index directive (see Section 8.7.7.1) 1468 - Set Parameters directive (see Section 8.7.7.5) for Source 1469 Component Index and Compression Info (see Section 8.7.5) 1471 - Copy directive (see Section 8.7.7.9) 1473 This template is similar to Section 7.7 but additionally performs 1474 decompression. Hence, the only difference is in setting the 1475 Compression Info parameter. 1477 This template can be modified for decryption or unpacking by adding 1478 Decryption Info or Unpack Info to the Set Parameters directive. 1480 7.9. Dependency Template 1482 The goal of the Dependency template is to obtain, verify, and process 1483 a dependency manifest as appropriate. 1485 The following commands are placed into the dependency resolution 1486 sequence: 1488 - Set Dependency Index directive (see Section 8.7.7.2) 1490 - Set Parameters directive (see Section 8.7.7.5) for URI (see 1491 Section 8.7.5) 1493 - Fetch directive (see Section 8.7.7.7) 1495 - Check Image Match condition (see Section 8.7.6.2) 1497 - Process Dependency directive (see Section 8.7.7.4) 1499 Then, the validate sequence contains the following operations: 1501 - Set Dependency Index directive (see Section 8.7.7.2) 1503 - Check Image Match condition (see Section 8.7.6.2) 1505 - Process Dependency directive (see Section 8.7.7.4) 1507 NOTE: Any changes made to parameters in a dependency persist in the 1508 dependent. 1510 7.9.1. Composite Manifests 1512 An implementer MAY choose to place a dependency's envelope in the 1513 envelope of its dependent. The dependent envelope key for the 1514 dependency envelope MUST NOT be a value between 0 and 24 and it MUST 1515 NOT be used by any other envelope element in the dependent manifest. 1517 The URI for a dependency enclosed in this way MUST be expressed as a 1518 fragment-only reference, as defined in [RFC3986], Section 4.4. The 1519 fragment identifier is the stringified envelope key of the 1520 dependency. For example, an envelope that contains a dependency at 1521 key 42 would use a URI "#42", key -73 would use a URI "#-73". 1523 7.10. Encrypted Manifest Template 1525 The goal of the Encrypted Manifest template is to fetch and decrypt a 1526 manifest so that it can be used as a dependency. To use an encrypted 1527 manifest, create a plaintext dependent, and add the encrypted 1528 manifest as a dependency. The dependent can include very little 1529 information. 1531 The following operations are placed into the dependency resolution 1532 block: 1534 - Set Dependency Index directive (see Section 8.7.7.2) 1536 - Set Parameters directive (see Section 8.7.7.5) for 1538 o URI (see Section 8.7.5) 1540 o Encryption Info (see Section 8.7.5) 1542 - Fetch directive (see Section 8.7.7.7) 1544 - Check Image Match condition (see Section 8.7.6.2) 1546 - Process Dependency directive (see Section 8.7.7.4) 1548 Then, the validate block contains the following operations: 1550 - Set Dependency Index directive (see Section 8.7.7.2) 1552 - Check Image Match condition (see Section 8.7.6.2) 1554 - Process Dependency directive (see Section 8.7.7.4) 1556 A plaintext manifest and its encrypted dependency may also form a 1557 composite manifest (Section 7.9.1). 1559 7.11. A/B Image Template 1561 The goal of the A/B Image Template is to acquire, validate, and 1562 invoke one of two images, based on a test. 1564 The following commands are placed in the common block: 1566 - Set Component Index directive (see Section 8.7.7.1) 1568 - Try Each 1570 o First Sequence: 1572 * Override Parameters directive (see Section 8.7.7.6, 1573 Section 8.7.5) for Slot A 1575 * Check Slot Condition (see Section 8.7.6.5) 1577 * Override Parameters directive (see Section 8.7.7.6) for 1578 Image Digest A and Image Size A (see Section 8.7.5) 1580 o Second Sequence: 1582 * Override Parameters directive (see Section 8.7.7.6, 1583 Section 8.7.5) for Slot B 1585 * Check Slot Condition (see Section 8.7.6.5) 1587 * Override Parameters directive (see Section 8.7.7.6) for 1588 Image Digest B and Image Size B (see Section 8.7.5) 1590 The following commands are placed in the fetch block or install block 1592 - Set Component Index directive (see Section 8.7.7.1) 1594 - Try Each 1596 o First Sequence: 1598 * Override Parameters directive (see Section 8.7.7.6, 1599 Section 8.7.5) for Slot A 1601 * Check Slot Condition (see Section 8.7.6.5) 1603 * Set Parameters directive (see Section 8.7.7.6) for URI A 1604 (see Section 8.7.5) 1606 o Second Sequence: 1608 * Override Parameters directive (see Section 8.7.7.6, 1609 Section 8.7.5) for Slot B 1611 * Check Slot Condition (see Section 8.7.6.5) 1613 * Set Parameters directive (see Section 8.7.7.6) for URI B 1614 (see Section 8.7.5) 1616 - Fetch 1618 If Trusted Invocation (Section 7.2) is used, only the run sequence is 1619 added to this template, since the common sequence is populated by 1620 this template. 1622 NOTE: Any test can be used to select between images, Check Slot 1623 Condition is used in this template because it is a typical test for 1624 execute-in-place devices. 1626 8. Metadata Structure 1628 The metadata for SUIT updates is composed of several primary 1629 constituent parts: the Envelope, Delegation Chains, Authentication 1630 Information, Manifest, and Severable Elements. 1632 For a diagram of the metadata structure, see Section 5. 1634 8.1. Encoding Considerations 1636 The map indices in the envelope encoding are reset to 1 for each map 1637 within the structure. This is to keep the indices as small as 1638 possible. The goal is to keep the index objects to single bytes 1639 (CBOR positive integers 1-23). 1641 Wherever enumerations are used, they are started at 1. This allows 1642 detection of several common software errors that are caused by 1643 uninitialized variables. Positive numbers in enumerations are 1644 reserved for IANA registration. Negative numbers are used to 1645 identify application-specific values, as described in Section 11. 1647 All elements of the envelope must be wrapped in a bstr to minimize 1648 the complexity of the code that evaluates the cryptographic integrity 1649 of the element and to ensure correct serialization for integrity and 1650 authenticity checks. 1652 8.2. Envelope 1654 The Envelope contains each of the other primary constituent parts of 1655 the SUIT metadata. It allows for modular processing of the manifest 1656 by ordering components in the expected order of processing. 1658 The Envelope is encoded as a CBOR Map. Each element of the Envelope 1659 is enclosed in a bstr, which allows computation of a message digest 1660 against known bounds. 1662 8.3. Delegation Chains 1664 The suit-delegation element MAY carry one or more CBOR Web Tokens 1665 (CWTs) [RFC8392], with [RFC8747] cnf claims. They can be used to 1666 perform enhanced authorization decisions. The CWTs are arranged into 1667 a list of lists. Each list starts with a CWT authorized by a Trust 1668 Anchor, and finishes with a key used to authenticate the Manifest 1669 (see Section 8.4). This allows an Update Authority to delegate from 1670 a long term Trust Anchor, down through intermediaries, to a delegate 1671 without any out-of-band provisioning of Trust Anchors or intermediary 1672 keys. 1674 A Recipient MAY choose to cache intermediaries and/or delegates. If 1675 an Update Distributor knows that a targeted Recipient has cached some 1676 intermediaries or delegates, it MAY choose to strip any cached 1677 intermediaries or delegates from the Delegation Chains in order to 1678 reduce bandwidth and energy. 1680 8.4. Authenticated Manifests 1682 The suit-authentication-wrapper contains a list containing a SUIT 1683 Digest Container (see Section 10) and one or more cryptographic 1684 authentication wrappers for the Manifest. These blocks are 1685 implemented as COSE_Mac_Tagged or COSE_Sign_Tagged structures. Each 1686 of these blocks contains a SUIT_Digest of the Manifest. This enables 1687 modular processing of the manifest. The COSE_Mac_Tagged and 1688 COSE_Sign_Tagged blocks are described in RFC 8152 [RFC8152]. The 1689 suit-authentication-wrapper MUST come before any element in the 1690 SUIT_Envelope, except for the OPTIONAL suit-delegation, regardless of 1691 canonical encoding of CBOR. All validators MUST reject any 1692 SUIT_Envelope that begins with any element other than a suit- 1693 authentication-wrapper or suit-delegation. 1695 A SUIT_Envelope that has not had authentication information added 1696 MUST still contain the suit-authentication-wrapper element, but the 1697 content MUST be a list containing only the SUIT_Digest. 1699 A signing application MUST verify the suit-manifest element against 1700 the SUIT_Digest prior to signing. 1702 8.5. Encrypted Manifests 1704 To use an encrypted manifest, it must be a dependency of a plaintext 1705 manifest. This allows fine-grained control of what information is 1706 accessible to intermediate systems for the purposes of management, 1707 while still preserving the confidentiality of the manifest contents. 1708 This also means that a Recipient can process an encrypted manifest in 1709 the same way as an encrypted payload, allowing code reuse. 1711 A template for using an encrypted manifest is covered in Encrypted 1712 Manifest Template (Section 7.10). 1714 8.6. Manifest 1716 The manifest contains: 1718 - a version number (see Section 8.6.1) 1720 - a sequence number (see Section 8.6.2) 1722 - a reference URI (see Section 8.6.3) 1724 - a common structure with information that is shared between command 1725 sequences (see Section 8.7.2) 1727 - one or more lists of commands that the Recipient should perform 1728 (see Section 8.7.3) 1730 - a reference to the full manifest (see Section 8.6.3) 1732 - human-readable text describing the manifest found in the 1733 SUIT_Envelope (see Section 8.6.4) 1735 - a Concise Software Identifier (CoSWID) found in the SUIT_Envelope 1736 (see Section 8.7.1) 1738 The CoSWID, Text section, or any Command Sequence of the Update 1739 Procedure (Dependency Resolution, Image Fetch, Image Installation) 1740 can be either a CBOR structure or a SUIT_Digest. In each of these 1741 cases, the SUIT_Digest provides for a severable element. Severable 1742 elements are RECOMMENDED to implement. In particular, the human- 1743 readable text SHOULD be severable, since most useful text elements 1744 occupy more space than a SUIT_Digest, but are not needed by the 1745 Recipient. Because SUIT_Digest is a CBOR Array and each severable 1746 element is a CBOR bstr, it is straight-forward for a Recipient to 1747 determine whether an element has been severed. The key used for a 1748 severable element is the same in the SUIT_Manifest and in the 1749 SUIT_Envelope so that a Recipient can easily identify the correct 1750 data in the envelope. See Section 8.7.9 for more detail. 1752 8.6.1. suit-manifest-version 1754 The suit-manifest-version indicates the version of serialization used 1755 to encode the manifest. Version 1 is the version described in this 1756 document. suit-manifest-version is REQUIRED to implement. 1758 8.6.2. suit-manifest-sequence-number 1760 The suit-manifest-sequence-number is a monotonically increasing anti- 1761 rollback counter. It also helps Recipients to determine which in a 1762 set of manifests is the "root" manifest in a given update. Each 1763 manifest MUST have a sequence number higher than each of its 1764 dependencies. Each Recipient MUST reject any manifest that has a 1765 sequence number lower than its current sequence number. For 1766 convenience, an implementer MAY use a UTC timestamp in seconds as the 1767 sequence number. suit-manifest-sequence-number is REQUIRED to 1768 implement. 1770 8.6.3. suit-reference-uri 1772 suit-reference-uri is a text string that encodes a URI where a full 1773 version of this manifest can be found. This is convenient for 1774 allowing management systems to show the severed elements of a 1775 manifest when this URI is reported by a Recipient after installation. 1777 8.6.4. suit-text 1779 suit-text SHOULD be a severable element. suit-text is a map 1780 containing two different types of pair: 1782 - integer => text 1784 - SUIT_Component_Identifier => map 1786 Each SUIT_Component_Identifier => map entry contains a map of integer 1787 => text values. All SUIT_Component_Identifiers present in suit-text 1788 MUST also be present in suit-common (Section 8.7.2) or the suit- 1789 common of a dependency. 1791 suit-text contains all the human-readable information that describes 1792 any and all parts of the manifest, its payload(s) and its 1793 resource(s). The text section is typically severable, allowing 1794 manifests to be distributed without the text, since end-nodes do not 1795 require text. The meaning of each field is described below. 1797 Each section MAY be present. If present, each section MUST be as 1798 described. Negative integer IDs are reserved for application- 1799 specific text values. 1801 The following table describes the text fields available in suit-text: 1803 +--------------------------------+----------------------------------+ 1804 | CDDL Structure | Description | 1805 +--------------------------------+----------------------------------+ 1806 | suit-text-manifest-description | Free text description of the | 1807 | | manifest | 1808 | | | 1809 | suit-text-update-description | Free text description of the | 1810 | | update | 1811 | | | 1812 | suit-text-manifest-json-source | The JSON-formatted document that | 1813 | | was used to create the manifest | 1814 | | | 1815 | suit-text-manifest-yaml-source | The YAML ([YAML])-formatted | 1816 | | document that was used to create | 1817 | | the manifest | 1818 +--------------------------------+----------------------------------+ 1820 The following table describes the text fields available in each map 1821 identified by a SUIT_Component_Identifier. 1823 +---------------------------------+---------------------------------+ 1824 | CDDL Structure | Description | 1825 +---------------------------------+---------------------------------+ 1826 | suit-text-vendor-name | Free text vendor name | 1827 | | | 1828 | suit-text-model-name | Free text model name | 1829 | | | 1830 | suit-text-vendor-domain | The domain used to create the | 1831 | | vendor-id condition | 1832 | | | 1833 | suit-text-model-info | The information used to create | 1834 | | the class-id condition | 1835 | | | 1836 | suit-text-component-description | Free text description of each | 1837 | | component in the manifest | 1838 | | | 1839 | suit-text-component-version | A free text representation of | 1840 | | the component version | 1841 | | | 1842 | suit-text-version-required | A free text expression of the | 1843 | | required version number | 1844 +---------------------------------+---------------------------------+ 1846 suit-text is OPTIONAL to implement. 1848 8.7. text-version-required 1850 suit-text-version-required is used to represent a version-based 1851 dependency on suit-parameter-version as described in Section 8.7.5.18 1852 and Section 8.7.6.8. To describe a version dependency, a Manifest 1853 Author SHOULD populate the suit-text map with a 1854 SUIT_Component_Identifier key for the dependency component, and place 1855 in the corresponding map a suit-text-version-required key with a free 1856 text expression that is representative of the version constraints 1857 placed on the dependency. This text SHOULD be expressive enough that 1858 a device operator can be expected to understand the dependency. This 1859 is a free text field and there are no specific formatting rules. 1861 By way of example only, to express a dependency on a component "['x', 1862 'y']", where the version should be any v1.x later than v1.2.5, but 1863 not v2.0 or above, the author would add the following structure to 1864 the suit-text element. Note that this text is in cbor-diag notation. 1866 [h'78',h'79'] : { 1867 7 : ">=1.2.5,<2" 1868 } 1870 8.7.1. suit-coswid 1872 suit-coswid contains a Concise Software Identifier (CoSWID) as 1873 defined in [I-D.ietf-sacm-coswid]. This element SHOULD be made 1874 severable so that it can be discarded by the Recipient or an 1875 intermediary if it is not required by the Recipient. 1877 suit-coswid typically requires no processing by the Recipient. 1878 However all Recipients MUST NOT fail if a suit-coswid is present. 1880 8.7.2. suit-common 1882 suit-common encodes all the information that is shared between each 1883 of the command sequences, including: suit-dependencies, suit- 1884 components, and suit-common-sequence. suit-common is REQUIRED to 1885 implement. 1887 suit-dependencies is a list of Section 8.7.2.1 blocks that specify 1888 manifests that must be present before the current manifest can be 1889 processed. suit-dependencies is OPTIONAL to implement. 1891 suit-components is a list of SUIT_Component_Identifier 1892 (Section 8.7.2.2) blocks that specify the component identifiers that 1893 will be affected by the content of the current manifest. suit- 1894 components is REQUIRED to implement; at least one manifest in a 1895 dependency tree MUST contain a suit-components block. 1897 suit-common-sequence is a SUIT_Command_Sequence to execute prior to 1898 executing any other command sequence. Typical actions in suit- 1899 common-sequence include setting expected Recipient identity and image 1900 digests when they are conditional (see Section 8.7.7.3 and 1901 Section 7.11 for more information on conditional sequences). suit- 1902 common-sequence is RECOMMENDED to implement. It is REQUIRED if the 1903 optimizations described in Section 6.2.1 will be used. Whenever a 1904 parameter or Try Each command is required by more than one Command 1905 Sequence, placing that parameter or command in suit-common-sequence 1906 results in a smaller encoding. 1908 8.7.2.1. Dependencies 1910 SUIT_Dependency specifies a manifest that describes a dependency of 1911 the current manifest. The Manifest is identified, but the Recipient 1912 should expect an Envelope when it acquires the dependency. This is 1913 because the Manifest is the one invariant element of the Envelope, 1914 where other elements may change by countersigning, adding 1915 authentication blocks, or severing elements. 1917 The suit-dependency-digest specifies the dependency manifest uniquely 1918 by identifying a particular Manifest structure. This is identical to 1919 the digest that would be present as the payload of any suit- 1920 authentication-block in the dependency's Envelope. The digest is 1921 calculated over the Manifest structure instead of the COSE 1922 Sig_structure or Mac_structure. This is necessary to ensure that 1923 removing a signature from a manifest does not break dependencies due 1924 to missing signature elements. This is also necessary to support the 1925 trusted intermediary use case, where an intermediary re-signs the 1926 Manifest, removing the original signature, potentially with a 1927 different algorithm, or trading COSE_Sign for COSE_Mac. 1929 The suit-dependency-prefix element contains a 1930 SUIT_Component_Identifier (see Section 8.7.2.2). This specifies the 1931 scope at which the dependency operates. This allows the dependency 1932 to be forwarded on to a component that is capable of parsing its own 1933 manifests. It also allows one manifest to be deployed to multiple 1934 dependent Recipients without those Recipients needing consistent 1935 component hierarchy. This element is OPTIONAL for Recipients to 1936 implement. 1938 A dependency prefix can be used with a component identifier. This 1939 allows complex systems to understand where dependencies need to be 1940 applied. The dependency prefix can be used in one of two ways. The 1941 first simply prepends the prefix to all Component Identifiers in the 1942 dependency. 1944 A dependency prefix can also be used to indicate when a dependency 1945 manifest needs to be processed by a secondary manifest processor, as 1946 described in Section 6.9. 1948 8.7.2.2. SUIT_Component_Identifier 1950 A component is a unit of code or data that can be targeted by an 1951 update. To facilitate composite devices, components are identified 1952 by a list of CBOR byte strings, which allows construction of 1953 hierarchical component structures. A dependency MAY declare a prefix 1954 to the components defined in the dependency manifest. Components are 1955 identified by Component Identifiers, but referenced in commands by 1956 Component Index; Component Identifiers are arrays of binary strings 1957 and a Component Index is an index into the array of Component 1958 Identifiers. 1960 A Component Identifier can be trivial, such as the simple array 1961 [h'00']. It can also represent a filesystem path by encoding each 1962 segment of the path as an element in the list. For example, the path 1963 "/usr/bin/env" would encode to ['usr','bin','env']. 1965 This hierarchical construction allows a component identifier to 1966 identify any part of a complex, multi-component system. 1968 8.7.3. SUIT_Command_Sequence 1970 A SUIT_Command_Sequence defines a series of actions that the 1971 Recipient MUST take to accomplish a particular goal. These goals are 1972 defined in the manifest and include: 1974 1. Dependency Resolution: suit-dependency-resolution is a 1975 SUIT_Command_Sequence to execute in order to perform dependency 1976 resolution. Typical actions include configuring URIs of 1977 dependency manifests, fetching dependency manifests, and 1978 validating dependency manifests' contents. suit-dependency- 1979 resolution is REQUIRED to implement and to use when suit- 1980 dependencies is present. 1982 2. Payload Fetch: suit-payload-fetch is a SUIT_Command_Sequence to 1983 execute in order to obtain a payload. Some manifests may include 1984 these actions in the suit-install section instead if they operate 1985 in a streaming installation mode. This is particularly relevant 1986 for constrained devices without any temporary storage for staging 1987 the update. suit-payload-fetch is OPTIONAL to implement. 1989 3. Payload Installation: suit-install is a SUIT_Command_Sequence to 1990 execute in order to install a payload. Typical actions include 1991 verifying a payload stored in temporary storage, copying a staged 1992 payload from temporary storage, and unpacking a payload. suit- 1993 install is OPTIONAL to implement. 1995 4. Image Validation: suit-validate is a SUIT_Command_Sequence to 1996 execute in order to validate that the result of applying the 1997 update is correct. Typical actions involve image validation and 1998 manifest validation. suit-validate is REQUIRED to implement. If 1999 the manifest contains dependencies, one process-dependency 2000 invocation per dependency or one process-dependency invocation 2001 targeting all dependencies SHOULD be present in validate. 2003 5. Image Loading: suit-load is a SUIT_Command_Sequence to execute in 2004 order to prepare a payload for execution. Typical actions 2005 include copying an image from permanent storage into RAM, 2006 optionally including actions such as decryption or decompression. 2007 suit-load is OPTIONAL to implement. 2009 6. Run or Boot: suit-run is a SUIT_Command_Sequence to execute in 2010 order to run an image. suit-run typically contains a single 2011 instruction: either the "run" directive for the invocable 2012 manifest or the "process dependencies" directive for any 2013 dependents of the invocable manifest. suit-run is OPTIONAL to 2014 implement. 2016 Goals 1,2,3 form the Update Procedure. Goals 4,5,6 form the 2017 Invocation Procedure. 2019 Each Command Sequence follows exactly the same structure to ensure 2020 that the parser is as simple as possible. 2022 Lists of commands are constructed from two kinds of element: 2024 1. Conditions that MUST be true and any failure is treated as a 2025 failure of the update/load/invocation 2027 2. Directives that MUST be executed. 2029 Each condition is composed of: 2031 1. A command code identifier 2033 2. A SUIT_Reporting_Policy (Section 8.7.4) 2035 Each directive is composed of: 2037 1. A command code identifier 2039 2. An argument block or a SUIT_Reporting_Policy (Section 8.7.4) 2041 Argument blocks are consumed only by flow-control directives: 2043 - Set Component/Dependency Index 2045 - Set/Override Parameters 2047 - Try Each 2049 - Run Sequence 2051 Reporting policies provide a hint to the manifest processor of 2052 whether to add the success or failure of a command to any report that 2053 it generates. 2055 Many conditions and directives apply to a given component, and these 2056 generally grouped together. Therefore, a special command to set the 2057 current component index is provided with a matching command to set 2058 the current dependency index. This index is a numeric index into the 2059 Component Identifier tables defined at the beginning of the manifest. 2061 For the purpose of setting the index, the two Component Identifier 2062 tables are considered to be concatenated together. 2064 To facilitate optional conditions, a special directive, suit- 2065 directive-try-each (Section 8.7.7.3), is provided. It runs several 2066 new lists of conditions/directives, one after another, that are 2067 contained as an argument to the directive. By default, it assumes 2068 that a failure of a condition should not indicate a failure of the 2069 update/invocation, but a parameter is provided to override this 2070 behavior. See suit-parameter-soft-failure (Section 8.7.5.23). 2072 8.7.4. Reporting Policy 2074 To facilitate construction of Reports that describe the success, or 2075 failure of a given Procedure, each command is given a Reporting 2076 Policy. This is an integer bitfield that follows the command and 2077 indicates what the Recipient should do with the Record of executing 2078 the command. The options are summarized in the table below. 2080 +-----------------------------+-------------------------------------+ 2081 | Policy | Description | 2082 +-----------------------------+-------------------------------------+ 2083 | suit-send-record-on-success | Record when the command succeeds | 2084 | | | 2085 | suit-send-record-on-failure | Record when the command fails | 2086 | | | 2087 | suit-send-sysinfo-success | Add system information when the | 2088 | | command succeeds | 2089 | | | 2090 | suit-send-sysinfo-failure | Add system information when the | 2091 | | command fails | 2092 +-----------------------------+-------------------------------------+ 2094 Any or all of these policies may be enabled at once. 2096 At the completion of each command, a Manifest Processor MAY forward 2097 information about the command to a Reporting Engine, which is 2098 responsible for reporting boot or update status to a third party. 2099 The Reporting Engine is entirely implementation-defined, the 2100 reporting policy simply facilitates the Reporting Engine's interface 2101 to the SUIT Manifest Processor. 2103 The information elements provided to the Reporting Engine are: 2105 - The reporting policy 2107 - The result of the command 2108 - The values of parameters consumed by the command 2110 - The system information consumed by the command 2112 Together, these elements are called a Record. A group of Records is 2113 a Report. 2115 If the component index is set to True or an array when a command is 2116 executed with a non-zero reporting policy, then the Reporting Engine 2117 MUST receive one Record for each Component, in the order expressed in 2118 the Components list or the component index array. If the dependency 2119 index is set to True or an array when a command is executed with a 2120 non-zero reporting policy, then the Reporting Engine MUST receive one 2121 Record for each Dependency, in the order expressed in the 2122 Dependencies list or the component index array, respectively. 2124 This specification does not define a particular format of Records or 2125 Reports. This specification only defines hints to the Reporting 2126 Engine for which Records it should aggregate into the Report. The 2127 Reporting Engine MAY choose to ignore these hints and apply its own 2128 policy instead. 2130 When used in a Invocation Procedure, the report MAY form the basis of 2131 an attestation report. When used in an Update Process, the report 2132 MAY form the basis for one or more log entries. 2134 8.7.5. SUIT_Parameters 2136 Many conditions and directives require additional information. That 2137 information is contained within parameters that can be set in a 2138 consistent way. This allows reduction of manifest size and 2139 replacement of parameters from one manifest to the next. 2141 Most parameters are scoped to a specific component. This means that 2142 setting a parameter for one component has no effect on the parameters 2143 of any other component. The only exceptions to this are two Manifest 2144 Processor parameters: Strict Order and Soft Failure. 2146 The defined manifest parameters are described below. 2148 +----------------+----------------------------------+---------------+ 2149 | Name | CDDL Structure | Reference | 2150 +----------------+----------------------------------+---------------+ 2151 | Vendor ID | suit-parameter-vendor-identifier | Section 8.7.5 | 2152 | | | .3 | 2153 | | | | 2154 | Class ID | suit-parameter-class-identifier | Section 8.7.5 | 2155 | | | .4 | 2156 | | | | 2157 | Device ID | suit-parameter-device-identifier | Section 8.7.5 | 2158 | | | .5 | 2159 | | | | 2160 | Image Digest | suit-parameter-image-digest | Section 8.7.5 | 2161 | | | .6 | 2162 | | | | 2163 | Image Size | suit-parameter-image-size | Section 8.7.5 | 2164 | | | .7 | 2165 | | | | 2166 | Use Before | suit-parameter-use-before | Section 8.7.5 | 2167 | | | .8 | 2168 | | | | 2169 | Component Slot | suit-parameter-component-slot | Section 8.7.5 | 2170 | | | .9 | 2171 | | | | 2172 | Encryption | suit-parameter-encryption-info | Section 8.7.5 | 2173 | Info | | .10 | 2174 | | | | 2175 | Compression | suit-parameter-compression-info | Section 8.7.5 | 2176 | Info | | .11 | 2177 | | | | 2178 | Unpack Info | suit-parameter-unpack-info | Section 8.7.5 | 2179 | | | .12 | 2180 | | | | 2181 | URI | suit-parameter-uri | Section 8.7.5 | 2182 | | | .13 | 2183 | | | | 2184 | Source | suit-parameter-source-component | Section 8.7.5 | 2185 | Component | | .14 | 2186 | | | | 2187 | Run Args | suit-parameter-run-args | Section 8.7.5 | 2188 | | | .15 | 2189 | | | | 2190 | Minimum | suit-parameter-minimum-battery | Section 8.7.5 | 2191 | Battery | | .16 | 2192 | | | | 2193 | Update | suit-parameter-update-priority | Section 8.7.5 | 2194 | Priority | | .17 | 2195 | | | | 2196 | Version | suit-parameter-version | Section 8.7.5 | 2197 | | | .18 | 2198 | | | | 2199 | Wait Info | suit-parameter-wait-info | Section 8.7.5 | 2200 | | | .19 | 2201 | | | | 2202 | URI List | suit-parameter-uri-list | Section 8.7.5 | 2203 | | | .20 | 2204 | | | | 2205 | Fetch | suit-parameter-fetch-arguments | Section 8.7.5 | 2206 | Arguments | | .21 | 2207 | | | | 2208 | Strict Order | suit-parameter-strict-order | Section 8.7.5 | 2209 | | | .22 | 2210 | | | | 2211 | Soft Failure | suit-parameter-soft-failure | Section 8.7.5 | 2212 | | | .23 | 2213 | | | | 2214 | Custom | suit-parameter-custom | Section 8.7.5 | 2215 | | | .24 | 2216 +----------------+----------------------------------+---------------+ 2218 CBOR-encoded object parameters are still wrapped in a bstr. This is 2219 because it allows a parser that is aggregating parameters to 2220 reference the object with a single pointer and traverse it without 2221 understanding the contents. This is important for modularization and 2222 division of responsibility within a pull parser. The same 2223 consideration does not apply to Directives because those elements are 2224 invoked with their arguments immediately 2226 8.7.5.1. CBOR PEN UUID Namespace Identifier 2228 The CBOR PEN UUID Namespace Identifier is constructed as follows: 2230 It uses the OID Namespace as a starting point, then uses the CBOR OID 2231 encoding for the IANA PEN OID (1.3.6.1.4.1): 2233 D8 DE # tag(111) 2234 45 # bytes(5) 2235 2B 06 01 04 01 # X.690 Clause 8.19 2236 # 1.3 6 1 4 1 show component encoding 2238 Computing a type 5 UUID from these produces: 2240 NAMESPACE_CBOR_PEN = UUID5(NAMESPACE_OID, h'D86F452B06010401') 2241 NAMESPACE_CBOR_PEN = 08cfcc43-47d9-5696-85b1-9c738465760e 2243 8.7.5.2. Constructing UUIDs 2245 Several conditions use identifiers to determine whether a manifest 2246 matches a given Recipient or not. These identifiers are defined to 2247 be RFC 4122 [RFC4122] UUIDs. These UUIDs are not human-readable and 2248 are therefore used for machine-based processing only. 2250 A Recipient MAY match any number of UUIDs for vendor or class 2251 identifier. This may be relevant to physical or software modules. 2253 For example, a Recipient that has an OS and one or more applications 2254 might list one Vendor ID for the OS and one or more additional Vendor 2255 IDs for the applications. This Recipient might also have a Class ID 2256 that must be matched for the OS and one or more Class IDs for the 2257 applications. 2259 Identifiers are used for compatibility checks. They MUST NOT be used 2260 as assertions of identity. They are evaluated by identifier 2261 conditions (Section 8.7.6.1). 2263 A more complete example: Imagine a device has the following physical 2264 components: 1. A host MCU 2. A WiFi module 2266 This same device has three software modules: 1. An operating system 2267 2. A WiFi module interface driver 3. An application 2269 Suppose that the WiFi module's firmware has a proprietary update 2270 mechanism and doesn't support manifest processing. This device can 2271 report four class IDs: 2273 1. Hardware model/revision 2275 2. OS 2277 3. WiFi module model/revision 2279 4. Application 2281 This allows the OS, WiFi module, and application to be updated 2282 independently. To combat possible incompatibilities, the OS class ID 2283 can be changed each time the OS has a change to its API. 2285 This approach allows a vendor to target, for example, all devices 2286 with a particular WiFi module with an update, which is a very 2287 powerful mechanism, particularly when used for security updates. 2289 UUIDs MUST be created according to RFC 4122 [RFC4122]. UUIDs SHOULD 2290 use versions 3, 4, or 5, as described in RFC4122. Versions 1 and 2 2291 do not provide a tangible benefit over version 4 for this 2292 application. 2294 The RECOMMENDED method to create a vendor ID is: 2296 Vendor ID = UUID5(DNS_PREFIX, vendor domain name) 2298 If the Vendor ID is a UUID, the RECOMMENDED method to create a Class 2299 ID is: 2301 Class ID = UUID5(Vendor ID, Class-Specific-Information) 2303 If the Vendor ID is a CBOR PEN (see Section 8.7.5.3), the RECOMMENDED 2304 method to create a Class ID is: 2306 Class ID = UUID5( 2307 UUID5(NAMESPACE_CBOR_PEN, CBOR_PEN), 2308 Class-Specific-Information) 2310 Class-specific-information is composed of a variety of data, for 2311 example: 2313 - Model number. 2315 - Hardware revision. 2317 - Bootloader version (for immutable bootloaders). 2319 8.7.5.3. suit-parameter-vendor-identifier 2321 suit-parameter-vendor-identifier may be presented in one of two ways: 2323 - A Private Enterprise Number 2325 - A byte string containing a UUID ([RFC4122]) 2327 Private Enterprise Numbers are encoded as a relative OID, according 2328 to the definition in [I-D.ietf-cbor-tags-oid]. All PENs are relative 2329 to the IANA PEN: 1.3.6.1.4.1. 2331 8.7.5.4. suit-parameter-class-identifier 2333 A RFC 4122 UUID representing the class of the device or component. 2334 The UUID is encoded as a 16 byte bstr, containing the raw bytes of 2335 the UUID. It MUST be constructed as described in Section 8.7.5.2 2337 8.7.5.5. suit-parameter-device-identifier 2339 A RFC 4122 UUID representing the specific device or component. The 2340 UUID is encoded as a 16 byte bstr, containing the raw bytes of the 2341 UUID. It MUST be constructed as described in Section 8.7.5.2 2343 8.7.5.6. suit-parameter-image-digest 2345 A fingerprint computed over the component itself, encoded in the 2346 SUIT_Digest Section 10 structure. The SUIT_Digest is wrapped in a 2347 bstr, as required in Section 8.7.5. 2349 8.7.5.7. suit-parameter-image-size 2351 The size of the firmware image in bytes. This size is encoded as a 2352 positive integer. 2354 8.7.5.8. suit-parameter-use-before 2356 An expiry date for the use of the manifest encoded as the positive 2357 integer number of seconds since 1970-01-01. Implementations that use 2358 this parameter MUST use a 64-bit internal representation of the 2359 integer. 2361 8.7.5.9. suit-parameter-component-slot 2363 This parameter sets the slot index of a component. Some components 2364 support multiple possible Slots (offsets into a storage area). This 2365 parameter describes the intended Slot to use, identified by its index 2366 into the component's storage area. This slot MUST be encoded as a 2367 positive integer. 2369 8.7.5.10. suit-parameter-encryption-info 2371 Encryption Info defines the keys and algorithm information Fetch or 2372 Copy has to use to decrypt the confidentiality protected data. 2373 SUIT_Parameter_Encryption_Info is encoded as a COSE_Encrypt_Tagged 2374 structure wrapped in a bstr. A separate document will profile the 2375 COSE specification for use of manifest and firmware encrytion. 2377 8.7.5.11. suit-parameter-compression-info 2379 SUIT_Compression_Info defines any information that is required for a 2380 Recipient to perform decompression operations. SUIT_Compression_Info 2381 is a map containing this data. The only element defined for the map 2382 in this specification is the suit-compression-algorithm. This 2383 document defines the following suit-compression-algorithm's: ZLIB 2384 [RFC1950], Brotli [RFC7932], and ZSTD [RFC8878]. 2386 Additional suit-compression-algorithm's can be registered through the 2387 IANA-maintained registry. If such a format requires more data than 2388 an algorithm identifier, one or more new elements MUST be introduced 2389 by specifying an element for SUIT_Compression_Info-extensions. 2391 8.7.5.12. suit-parameter-unpack-info 2393 SUIT_Unpack_Info defines the information required for a Recipient to 2394 interpret a packed format. This document defines the use of the 2395 following binary encodings: Intel HEX [HEX], Motorola S-record 2397 [SREC], Executable and Linkable Format (ELF) [ELF], and Common Object 2398 File Format (COFF) [COFF]. 2400 Additional packing formats can be registered through the IANA- 2401 maintained registry. 2403 8.7.5.13. suit-parameter-uri 2405 A URI from which to fetch a resource, encoded as a text string. CBOR 2406 Tag 32 is not used because the meaning of the text string is 2407 unambiguous in this context. 2409 8.7.5.14. suit-parameter-source-component 2411 This parameter sets the source component to be used with either suit- 2412 directive-copy (Section 8.7.7.9) or with suit-directive-swap 2413 (Section 8.7.7.13). The current Component, as set by suit-directive- 2414 set-component-index defines the destination, and suit-parameter- 2415 source-component defines the source. 2417 8.7.5.15. suit-parameter-run-args 2419 This parameter contains an encoded set of arguments for suit- 2420 directive-run (Section 8.7.7.10). The arguments MUST be provided as 2421 an implementation-defined bstr. 2423 8.7.5.16. suit-parameter-minimum-battery 2425 This parameter sets the minimum battery level in mWh. This parameter 2426 is encoded as a positive integer. Used with suit-condition-minimum- 2427 battery (Section 8.7.6.6). 2429 8.7.5.17. suit-parameter-update-priority 2431 This parameter sets the priority of the update. This parameter is 2432 encoded as an integer. It is used along with suit-condition-update- 2433 authorized (Section 8.7.6.7) to ask an application for permission to 2434 initiate an update. This does not constitute a privilege inversion 2435 because an explicit request for authorization has been provided by 2436 the Update Authority in the form of the suit-condition-update- 2437 authorized command. 2439 Applications MAY define their own meanings for the update priority. 2440 For example, critical reliability & vulnerability fixes MAY be given 2441 negative numbers, while bug fixes MAY be given small positive 2442 numbers, and feature additions MAY be given larger positive numbers, 2443 which allows an application to make an informed decision about 2444 whether and when to allow an update to proceed. 2446 8.7.5.18. suit-parameter-version 2448 Indicates allowable versions for the specified component. Allowable 2449 versions can be specified, either with a list or with range matching. 2450 This parameter is compared with version asserted by the current 2451 component when suit-condition-version (Section 8.7.6.8) is invoked. 2452 The current component may assert the current version in many ways, 2453 including storage in a parameter storage database, in a metadata 2454 object, or in a known location within the component itself. 2456 The component version can be compared as: 2458 - Greater. 2460 - Greater or Equal. 2462 - Equal. 2464 - Lesser or Equal. 2466 - Lesser. 2468 Versions are encoded as a CBOR list of integers. Comparisons are 2469 done on each integer in sequence. Comparison stops after all 2470 integers in the list defined by the manifest have been consumed OR 2471 after a non-equal match has occurred. For example, if the manifest 2472 defines a comparison, "Equal [1]", then this will match all version 2473 sequences starting with 1. If a manifest defines both "Greater or 2474 Equal [1,0]" and "Lesser [1,10]", then it will match versions 1.0.x 2475 up to, but not including 1.10. 2477 While the exact encoding of versions is application-defined, semantic 2478 versions map conveniently. For example, 2480 - 1.2.3 = [1,2,3]. 2482 - 1.2-rc3 = [1,2,-1,3]. 2484 - 1.2-beta = [1,2,-2]. 2486 - 1.2-alpha = [1,2,-3]. 2488 - 1.2-alpha4 = [1,2,-3,4]. 2490 suit-condition-version is OPTIONAL to implement. 2492 Versions SHOULD be provided as follows: 2494 1. The first integer represents the major number. This indicates 2495 breaking changes to the component. 2497 2. The second integer represents the minor number. This is 2498 typically reserved for new features or large, non-breaking 2499 changes. 2501 3. The third integer is the patch version. This is typically 2502 reserved for bug fixes. 2504 4. The fourth integer is the build number. 2506 Where Alpha (-3), Beta (-2), and Release Candidate (-1) are used, 2507 they are inserted as a negative number between Minor and Patch 2508 numbers. This allows these releases to compare correctly with final 2509 releases. For example, Version 2.0, RC1 should be lower than Version 2510 2.0.0 and higher than any Version 1.x. By encoding RC as -1, this 2511 works correctly: [2,0,-1,1] compares as lower than [2,0,0]. 2512 Similarly, beta (-2) is lower than RC and alpha (-3) is lower than 2513 RC. 2515 8.7.5.19. suit-parameter-wait-info 2517 suit-directive-wait (Section 8.7.7.11) directs the manifest processor 2518 to pause until a specified event occurs. The suit-parameter-wait- 2519 info encodes the parameters needed for the directive. 2521 The exact implementation of the pause is implementation-defined. For 2522 example, this could be done by blocking on a semaphore, registering 2523 an event handler and suspending the manifest processor, polling for a 2524 notification, or aborting the update entirely, then restarting when a 2525 notification is received. 2527 suit-parameter-wait-info is encoded as a map of wait events. When 2528 ALL wait events are satisfied, the Manifest Processor continues. The 2529 wait events currently defined are described in the following table. 2531 +------------------------------+---------+--------------------------+ 2532 | Name | Encodin | Description | 2533 | | g | | 2534 +------------------------------+---------+--------------------------+ 2535 | suit-wait-event- | int | Same as suit-parameter- | 2536 | authorization | | update-priority | 2537 | | | | 2538 | suit-wait-event-power | int | Wait until power state | 2539 | | | | 2540 | suit-wait-event-network | int | Wait until network state | 2541 | | | | 2542 | suit-wait-event-other- | See | Wait for other device to | 2543 | device-version | below | match version | 2544 | | | | 2545 | suit-wait-event-time | uint | Wait until time (seconds | 2546 | | | since 1970-01-01) | 2547 | | | | 2548 | suit-wait-event-time-of-day | uint | Wait until seconds since | 2549 | | | 00:00:00 | 2550 | | | | 2551 | suit-wait-event-time-of-day- | uint | Wait until seconds since | 2552 | utc | | 00:00:00 UTC | 2553 | | | | 2554 | suit-wait-event-day-of-week | uint | Wait until days since | 2555 | | | Sunday | 2556 | | | | 2557 | suit-wait-event-day-of-week- | uint | Wait until days since | 2558 | utc | | Sunday UTC | 2559 +------------------------------+---------+--------------------------+ 2561 suit-wait-event-other-device-version reuses the encoding of suit- 2562 parameter-version-match. It is encoded as a sequence that contains 2563 an implementation-defined bstr identifier for the other device, and a 2564 list of one or more SUIT_Parameter_Version_Match. 2566 8.7.5.20. suit-parameter-uri-list 2568 Indicates a list of URIs from which to fetch a resource. The URI 2569 list is encoded as a list of text string, in priority order. CBOR 2570 Tag 32 is not used because the meaning of the text string is 2571 unambiguous in this context. The Recipient should attempt to fetch 2572 the resource from each URI in turn, ruling out each, in order, if the 2573 resource is inaccessible or it is otherwise undesirable to fetch from 2574 that URI. suit-parameter-uri-list is consumed by suit-directive- 2575 fetch-uri-list (Section 8.7.7.8). 2577 8.7.5.21. suit-parameter-fetch-arguments 2579 An implementation-defined set of arguments to suit-directive-fetch 2580 (Section 8.7.7.7). Arguments are encoded in a bstr. 2582 8.7.5.22. suit-parameter-strict-order 2584 The Strict Order Parameter allows a manifest to govern when 2585 directives can be executed out-of-order. This allows for systems 2586 that have a sensitivity to order of updates to choose the order in 2587 which they are executed. It also allows for more advanced systems to 2588 parallelize their handling of updates. Strict Order defaults to 2589 True. It MAY be set to False when the order of operations does not 2590 matter. When arriving at the end of a command sequence, ALL commands 2591 MUST have completed, regardless of the state of 2592 SUIT_Parameter_Strict_Order. SUIT_Process_Dependency must preserve 2593 and restore the state of SUIT_Parameter_Strict_Order. If 2594 SUIT_Parameter_Strict_Order is returned to True, ALL preceding 2595 commands MUST complete before the next command is executed. 2597 See Section 6.7 for behavioral description of Strict Order. 2599 8.7.5.23. suit-parameter-soft-failure 2601 When executing a command sequence inside suit-directive-try-each 2602 (Section 8.7.7.3) or suit-directive-run-sequence (Section 8.7.7.12) 2603 and a condition failure occurs, the manifest processor aborts the 2604 sequence. For suit-directive-try-each, if Soft Failure is True, the 2605 next sequence in Try Each is invoked, otherwise suit-directive-try- 2606 each fails with the condition failure code. In suit-directive-run- 2607 sequence, if Soft Failure is True the suit-directive-run-sequence 2608 simply halts with no side-effects and the Manifest Processor 2609 continues with the following command, otherwise, the suit-directive- 2610 run-sequence fails with the condition failure code. 2612 suit-parameter-soft-failure is scoped to the enclosing 2613 SUIT_Command_Sequence. Its value is discarded when 2614 SUIT_Command_Sequence terminates. It MUST NOT be set outside of 2615 suit-directive-try-each or suit-directive-run-sequence. 2617 When suit-directive-try-each is invoked, Soft Failure defaults to 2618 True. An Update Author may choose to set Soft Failure to False if 2619 they require a failed condition in a sequence to force an Abort. 2621 When suit-directive-run-sequence is invoked, Soft Failure defaults to 2622 False. An Update Author may choose to make failures soft within a 2623 suit-directive-run-sequence. 2625 8.7.5.24. suit-parameter-custom 2627 This parameter is an extension point for any proprietary, application 2628 specific conditions and directives. It MUST NOT be used in the 2629 common sequence. This effectively scopes each custom command to a 2630 particular Vendor Identifier/Class Identifier pair. 2632 8.7.6. SUIT_Condition 2634 Conditions are used to define mandatory properties of a system in 2635 order for an update to be applied. They can be pre-conditions or 2636 post-conditions of any directive or series of directives, depending 2637 on where they are placed in the list. All Conditions specify a 2638 Reporting Policy as described Section 8.7.4. Conditions include: 2640 +----------------+----------------------------------+---------------+ 2641 | Name | CDDL Structure | Reference | 2642 +----------------+----------------------------------+---------------+ 2643 | Vendor | suit-condition-vendor-identifier | Section 8.7.6 | 2644 | Identifier | | .1 | 2645 | | | | 2646 | Class | suit-condition-class-identifier | Section 8.7.6 | 2647 | Identifier | | .1 | 2648 | | | | 2649 | Device | suit-condition-device-identifier | Section 8.7.6 | 2650 | Identifier | | .1 | 2651 | | | | 2652 | Image Match | suit-condition-image-match | Section 8.7.6 | 2653 | | | .2 | 2654 | | | | 2655 | Image Not | suit-condition-image-not-match | Section 8.7.6 | 2656 | Match | | .3 | 2657 | | | | 2658 | Use Before | suit-condition-use-before | Section 8.7.6 | 2659 | | | .4 | 2660 | | | | 2661 | Component Slot | suit-condition-component-slot | Section 8.7.6 | 2662 | | | .5 | 2663 | | | | 2664 | Minimum | suit-condition-minimum-battery | Section 8.7.6 | 2665 | Battery | | .6 | 2666 | | | | 2667 | Update | suit-condition-update-authorized | Section 8.7.6 | 2668 | Authorized | | .7 | 2669 | | | | 2670 | Version | suit-condition-version | Section 8.7.6 | 2671 | | | .8 | 2672 | | | | 2673 | Abort | suit-condition-abort | Section 8.7.6 | 2674 | | | .9 | 2675 | | | | 2676 | Custom | suit-condition-custom | Section 8.7.6 | 2677 | Condition | | .10 | 2678 +----------------+----------------------------------+---------------+ 2680 The abstract description of these conditions is defined in 2681 Section 6.4. 2683 Conditions compare parameters against properties of the system. 2684 These properties may be asserted in many different ways, including: 2685 calculation on-demand, volatile definition in memory, static 2686 definition within the manifest processor, storage in known location 2687 within an image, storage within a key storage system, storage in One- 2688 Time-Programmable memory, inclusion in mask ROM, or inclusion as a 2689 register in hardware. Some of these assertion methods are global in 2690 scope, such as a hardware register, some are scoped to an individual 2691 component, such as storage at a known location in an image, and some 2692 assertion methods can be either global or component-scope, based on 2693 implementation. 2695 Each condition MUST report a result code on completion. If a 2696 condition reports failure, then the current sequence of commands MUST 2697 terminate. A subsequent command or command sequence MAY continue 2698 executing if suit-parameter-soft-failure (Section 8.7.5.23) is set. 2699 If a condition requires additional information, this MUST be 2700 specified in one or more parameters before the condition is executed. 2701 If a Recipient attempts to process a condition that expects 2702 additional information and that information has not been set, it MUST 2703 report a failure. If a Recipient encounters an unknown condition, it 2704 MUST report a failure. 2706 Condition labels in the positive number range are reserved for IANA 2707 registration while those in the negative range are custom conditions 2708 reserved for proprietary definition by the author of a manifest 2709 processor. See Section 11 for more details. 2711 8.7.6.1. suit-condition-vendor-identifier, suit-condition-class- 2712 identifier, and suit-condition-device-identifier 2714 There are three identifier-based conditions: suit-condition-vendor- 2715 identifier, suit-condition-class-identifier, and suit-condition- 2716 device-identifier. Each of these conditions match a RFC 4122 2717 [RFC4122] UUID that MUST have already been set as a parameter. The 2718 installing Recipient MUST match the specified UUID in order to 2719 consider the manifest valid. These identifiers are scoped by 2720 component in the manifest. Each component MAY match more than one 2721 identifier. Care is needed to ensure that manifests correctly 2722 identify their targets using these conditions. Using only a generic 2723 class ID for a device-specific firmware could result in matching 2724 devices that are not compatible. 2726 The Recipient uses the ID parameter that has already been set using 2727 the Set Parameters directive. If no ID has been set, this condition 2728 fails. suit-condition-class-identifier and suit-condition-vendor- 2729 identifier are REQUIRED to implement. suit-condition-device- 2730 identifier is OPTIONAL to implement. 2732 Each identifier condition compares the corresponding identifier 2733 parameter to a parameter asserted to the Manifest Processor by the 2734 Recipient. Identifiers MUST be known to the Manifest Processor in 2735 order to evaluate compatibility. 2737 8.7.6.2. suit-condition-image-match 2739 Verify that the current component matches the suit-parameter-image- 2740 digest (Section 8.7.5.6) for the current component. The digest is 2741 verified against the digest specified in the Component's parameters 2742 list. If no digest is specified, the condition fails. suit- 2743 condition-image-match is REQUIRED to implement. 2745 8.7.6.3. suit-condition-image-not-match 2747 Verify that the current component does not match the suit-parameter- 2748 image-digest (Section 8.7.5.6). If no digest is specified, the 2749 condition fails. suit-condition-image-not-match is OPTIONAL to 2750 implement. 2752 8.7.6.4. suit-condition-use-before 2754 Verify that the current time is BEFORE the specified time. suit- 2755 condition-use-before is used to specify the last time at which an 2756 update should be installed. The recipient evaluates the current time 2757 against the suit-parameter-use-before parameter (Section 8.7.5.8), 2758 which must have already been set as a parameter, encoded as seconds 2759 after 1970-01-01 00:00:00 UTC. Timestamp conditions MUST be 2760 evaluated in 64 bits, regardless of encoded CBOR size. suit- 2761 condition-use-before is OPTIONAL to implement. 2763 8.7.6.5. suit-condition-component-slot 2765 Verify that the slot index of the current component matches the slot 2766 index set in suit-parameter-component-slot (Section 8.7.5.9). This 2767 condition allows a manifest to select between several images to match 2768 a target slot. 2770 8.7.6.6. suit-condition-minimum-battery 2772 suit-condition-minimum-battery provides a mechanism to test a 2773 Recipient's battery level before installing an update. This 2774 condition is primarily for use in primary-cell applications, where 2775 the battery is only ever discharged. For batteries that are charged, 2776 suit-directive-wait is more appropriate, since it defines a "wait" 2777 until the battery level is sufficient to install the update. suit- 2778 condition-minimum-battery is specified in mWh. suit-condition- 2779 minimum-battery is OPTIONAL to implement. suit-condition-minimum- 2780 battery consumes suit-parameter-minimum-battery (Section 8.7.5.16). 2782 8.7.6.7. suit-condition-update-authorized 2784 Request Authorization from the application and fail if not 2785 authorized. This can allow a user to decline an update. suit- 2786 parameter-update-priority (Section 8.7.5.17) provides an integer 2787 priority level that the application can use to determine whether or 2788 not to authorize the update. Priorities are application defined. 2789 suit-condition-update-authorized is OPTIONAL to implement. 2791 8.7.6.8. suit-condition-version 2793 suit-condition-version allows comparing versions of firmware. 2794 Verifying image digests is preferred to version checks because 2795 digests are more precise. suit-condition-version examines a 2796 component's version against the version info specified in suit- 2797 parameter-version (Section 8.7.5.18) 2799 8.7.6.9. suit-condition-abort 2801 Unconditionally fail. This operation is typically used in 2802 conjunction with suit-directive-try-each (Section 8.7.7.3). 2804 8.7.6.10. suit-condition-custom 2806 suit-condition-custom describes any proprietary, application specific 2807 condition. This is encoded as a negative integer, chosen by the 2808 firmware developer. If additional information must be provided to 2809 the condition, it should be encoded in a custom parameter (a nint) as 2810 described in Section 8.7.5. SUIT_Condition_Custom is OPTIONAL to 2811 implement. 2813 8.7.7. SUIT_Directive 2815 Directives are used to define the behavior of the recipient. 2816 Directives include: 2818 +---------------+-------------------------------------+-------------+ 2819 | Name | CDDL Structure | Reference | 2820 +---------------+-------------------------------------+-------------+ 2821 | Set Component | suit-directive-set-component-index | Section 8.7 | 2822 | Index | | .7.1 | 2823 | | | | 2824 | Set | suit-directive-set-dependency-index | Section 8.7 | 2825 | Dependency | | .7.2 | 2826 | Index | | | 2827 | | | | 2828 | Try Each | suit-directive-try-each | Section 8.7 | 2829 | | | .7.3 | 2830 | | | | 2831 | Process | suit-directive-process-dependency | Section 8.7 | 2832 | Dependency | | .7.4 | 2833 | | | | 2834 | Set | suit-directive-set-parameters | Section 8.7 | 2835 | Parameters | | .7.5 | 2836 | | | | 2837 | Override | suit-directive-override-parameters | Section 8.7 | 2838 | Parameters | | .7.6 | 2839 | | | | 2840 | Fetch | suit-directive-fetch | Section 8.7 | 2841 | | | .7.7 | 2842 | | | | 2843 | Fetch URI | suit-directive-fetch-uri-list | Section 8.7 | 2844 | list | | .7.8 | 2845 | | | | 2846 | Copy | suit-directive-copy | Section 8.7 | 2847 | | | .7.9 | 2848 | | | | 2849 | Run | suit-directive-run | Section 8.7 | 2850 | | | .7.10 | 2851 | | | | 2852 | Wait For | suit-directive-wait | Section 8.7 | 2853 | Event | | .7.11 | 2854 | | | | 2855 | Run Sequence | suit-directive-run-sequence | Section 8.7 | 2856 | | | .7.12 | 2857 | | | | 2858 | Swap | suit-directive-swap | Section 8.7 | 2859 | | | .7.13 | 2860 | | | | 2861 | Unlink | suit-directive-unlink | Section 8.7 | 2862 | | | .8 | 2863 +---------------+-------------------------------------+-------------+ 2865 The abstract description of these commands is defined in Section 6.4. 2867 When a Recipient executes a Directive, it MUST report a result code. 2868 If the Directive reports failure, then the current Command Sequence 2869 MUST be terminated. 2871 8.7.7.1. suit-directive-set-component-index 2873 Set Component Index defines the component to which successive 2874 directives and conditions will apply. The supplied argument MUST be 2875 one of three types: 2877 1. An unsigned integer (REQUIRED to implement in parser) 2879 2. A boolean (REQUIRED to implement in parser ONLY IF 2 or more 2880 components supported) 2882 3. An array of unsigned integers (REQUIRED to implement in parser 2883 ONLY IF 3 or more components supported) 2885 If the following commands apply to ONE component, an unsigned integer 2886 index into the component list is used. If the following commands 2887 apply to ALL components, then the boolean value "True" is used 2888 instead of an index. If the following commands apply to more than 2889 one, but not all components, then an array of unsigned integer 2890 indices into the component list is used. See Section 6.5 for more 2891 details. 2893 If the following commands apply to NO components, then the boolean 2894 value "False" is used. When suit-directive-set-dependency-index is 2895 used, suit-directive-set-component-index = False is implied. When 2896 suit-directive-set-component-index is used, suit-directive-set- 2897 dependency-index = False is implied. 2899 If component index is set to True when a command is invoked, then the 2900 command applies to all components, in the order they appear in suit- 2901 common-components. When the Manifest Processor invokes a command 2902 while the component index is set to True, it must execute the command 2903 once for each possible component index, ensuring that the command 2904 receives the parameters corresponding to that component index. 2906 8.7.7.2. suit-directive-set-dependency-index 2908 Set Dependency Index defines the manifest to which successive 2909 directives and conditions will apply. The supplied argument MUST be 2910 either a boolean or an unsigned integer index into the dependencies, 2911 or an array of unsigned integer indices into the list of 2912 dependencies. If the following directives apply to ALL dependencies, 2913 then the boolean value "True" is used instead of an index. If the 2914 following directives apply to NO dependencies, then the boolean value 2915 "False" is used. When suit-directive-set-component-index is used, 2916 suit-directive-set-dependency-index = False is implied. When suit- 2917 directive-set-dependency-index is used, suit-directive-set-component- 2918 index = False is implied. 2920 If dependency index is set to True when a command is invoked, then 2921 the command applies to all dependencies, in the order they appear in 2922 suit-common-components. When the Manifest Processor invokes a 2923 command while the dependency index is set to True, the Manifest 2924 Processor MUST execute the command once for each possible dependency 2925 index, ensuring that the command receives the parameters 2926 corresponding to that dependency index. If the dependency index is 2927 set to an array of unsigned integers, then the Manifest Processor 2928 MUST execute the command once for each listed dependency index, 2929 ensuring that the command receives the parameters corresponding to 2930 that dependency index. 2932 See Section 6.5 for more details. 2934 Typical operations that require suit-directive-set-dependency-index 2935 include setting a source URI or Encryption Information, invoking 2936 "Fetch," or invoking "Process Dependency" for an individual 2937 dependency. 2939 8.7.7.3. suit-directive-try-each 2941 This command runs several SUIT_Command_Sequence instances, one after 2942 another, in a strict order. Use this command to implement a "try/ 2943 catch-try/catch" sequence. Manifest processors MAY implement this 2944 command. 2946 suit-parameter-soft-failure (Section 8.7.5.23) is initialized to True 2947 at the beginning of each sequence. If one sequence aborts due to a 2948 condition failure, the next is started. If no sequence completes 2949 without condition failure, then suit-directive-try-each returns an 2950 error. If a particular application calls for all sequences to fail 2951 and still continue, then an empty sequence (nil) can be added to the 2952 Try Each Argument. 2954 The argument to suit-directive-try-each is a list of 2955 SUIT_Command_Sequence. suit-directive-try-each does not specify a 2956 reporting policy. 2958 8.7.7.4. suit-directive-process-dependency 2960 Execute the commands in the common section of the current dependency, 2961 followed by the commands in the equivalent section of the current 2962 dependency. For example, if the current section is "fetch payload," 2963 this will execute "common" in the current dependency, then "fetch 2964 payload" in the current dependency. Once this is complete, the 2965 command following suit-directive-process-dependency will be 2966 processed. 2968 If the current dependency is False, this directive has no effect. If 2969 the current dependency is True, then this directive applies to all 2970 dependencies. If the current section is "common," then the command 2971 sequence MUST be terminated with an error. 2973 When SUIT_Process_Dependency completes, it forwards the last status 2974 code that occurred in the dependency. 2976 8.7.7.5. suit-directive-set-parameters 2978 suit-directive-set-parameters allows the manifest to configure 2979 behavior of future directives by changing parameters that are read by 2980 those directives. When dependencies are used, suit-directive-set- 2981 parameters also allows a manifest to modify the behavior of its 2982 dependencies. 2984 Available parameters are defined in Section 8.7.5. 2986 If a parameter is already set, suit-directive-set-parameters will 2987 skip setting the parameter to its argument. This provides the core 2988 of the override mechanism, allowing dependent manifests to change the 2989 behavior of a manifest. 2991 suit-directive-set-parameters does not specify a reporting policy. 2993 8.7.7.6. suit-directive-override-parameters 2995 suit-directive-override-parameters replaces any listed parameters 2996 that are already set with the values that are provided in its 2997 argument. This allows a manifest to prevent replacement of critical 2998 parameters. 3000 Available parameters are defined in Section 8.7.5. 3002 suit-directive-override-parameters does not specify a reporting 3003 policy. 3005 8.7.7.7. suit-directive-fetch 3007 suit-directive-fetch instructs the manifest processor to obtain one 3008 or more manifests or payloads, as specified by the manifest index and 3009 component index, respectively. 3011 suit-directive-fetch can target one or more manifests and one or more 3012 payloads. suit-directive-fetch retrieves each component and each 3013 manifest listed in component-index and dependency-index, 3014 respectively. If component-index or dependency-index is True, 3015 instead of an integer, then all current manifest components/manifests 3016 are fetched. The current manifest's dependent-components are not 3017 automatically fetched. In order to pre-fetch these, they MUST be 3018 specified in a component-index integer. 3020 suit-directive-fetch typically takes no arguments unless one is 3021 needed to modify fetch behavior. If an argument is needed, it must 3022 be wrapped in a bstr and set in suit-parameter-fetch-arguments. 3024 suit-directive-fetch reads the URI parameter to find the source of 3025 the fetch it performs. 3027 The behavior of suit-directive-fetch can be modified by setting one 3028 or more of SUIT_Parameter_Encryption_Info, 3029 SUIT_Parameter_Compression_Info, SUIT_Parameter_Unpack_Info. These 3030 three parameters each activate and configure a processing step that 3031 can be applied to the data that is transferred during suit-directive- 3032 fetch. 3034 8.7.7.8. suit-directive-fetch-uri-list 3036 suit-directive-fetch-uri-list uses the same semantics as suit- 3037 directive-fetch (Section 8.7.7.7), except that it iterates over the 3038 URI List (Section 8.7.5.20) to select a URI to fetch from. 3040 8.7.7.9. suit-directive-copy 3042 suit-directive-copy instructs the manifest processor to obtain one or 3043 more payloads, as specified by the component index. As described in 3044 Section 6.5 component index may be a single integer, a list of 3045 integers, or True. suit-directive-copy retrieves each component 3046 specified by the current component-index, respectively. The current 3047 manifest's dependent-components are not automatically copied. In 3048 order to copy these, they MUST be specified in a component-index 3049 integer. 3051 The behavior of suit-directive-copy can be modified by setting one or 3052 more of SUIT_Parameter_Encryption_Info, 3053 SUIT_Parameter_Compression_Info, SUIT_Parameter_Unpack_Info. These 3054 three parameters each activate and configure a processing step that 3055 can be applied to the data that is transferred during suit-directive- 3056 copy. 3058 suit-directive-copy reads its source from suit-parameter-source- 3059 component (Section 8.7.5.14). 3061 If either the source component parameter or the source component 3062 itself is absent, this command fails. 3064 8.7.7.10. suit-directive-run 3066 suit-directive-run directs the manifest processor to transfer 3067 execution to the current Component Index. When this is invoked, the 3068 manifest processor MAY be unloaded and execution continues in the 3069 Component Index. Arguments are provided to suit-directive-run 3070 through suit-parameter-run-arguments (Section 8.7.5.15) and are 3071 forwarded to the executable code located in Component Index in an 3072 application-specific way. For example, this could form the Linux 3073 Kernel Command Line if booting a Linux device. 3075 If the executable code at Component Index is constructed in such a 3076 way that it does not unload the manifest processor, then the manifest 3077 processor may resume execution after the executable completes. This 3078 allows the manifest processor to invoke suitable helpers and to 3079 verify them with image conditions. 3081 8.7.7.11. suit-directive-wait 3083 suit-directive-wait directs the manifest processor to pause until a 3084 specified event occurs. Some possible events include: 3086 1. Authorization 3088 2. External Power 3090 3. Network availability 3092 4. Other Device Firmware Version 3094 5. Time 3096 6. Time of Day 3098 7. Day of Week 3100 8.7.7.12. suit-directive-run-sequence 3102 To enable conditional commands, and to allow several strictly ordered 3103 sequences to be executed out-of-order, suit-directive-run-sequence 3104 allows the manifest processor to execute its argument as a 3105 SUIT_Command_Sequence. The argument must be wrapped in a bstr. 3107 When a sequence is executed, any failure of a condition causes 3108 immediate termination of the sequence. 3110 When suit-directive-run-sequence completes, it forwards the last 3111 status code that occurred in the sequence. If the Soft Failure 3112 parameter is true, then suit-directive-run-sequence only fails when a 3113 directive in the argument sequence fails. 3115 suit-parameter-soft-failure (Section 8.7.5.23) defaults to False when 3116 suit-directive-run-sequence begins. Its value is discarded when 3117 suit-directive-run-sequence terminates. 3119 8.7.7.13. suit-directive-swap 3121 suit-directive-swap instructs the manifest processor to move the 3122 source to the destination and the destination to the source 3123 simultaneously. Swap has nearly identical semantics to suit- 3124 directive-copy except that suit-directive-swap replaces the source 3125 with the current contents of the destination in an application- 3126 defined way. As with suit-directive-copy, if the source component is 3127 missing, this command fails. 3129 If SUIT_Parameter_Compression_Info or SUIT_Parameter_Encryption_Info 3130 are present, they MUST be handled in a symmetric way, so that the 3131 source is decompressed into the destination and the destination is 3132 compressed into the source. The source is decrypted into the 3133 destination and the destination is encrypted into the source. suit- 3134 directive-swap is OPTIONAL to implement. 3136 8.7.8. suit-directive-unlink 3138 suit-directive-unlink marks the current component as unused in the 3139 current manifest. This can be used to remove temporary storage or 3140 remove components that are no longer needed. Example use cases: 3142 - Temporary storage for encrypted download 3144 - Temporary storage for verifying decompressed file before writing 3145 to flash 3147 - Removing Trusted Service no longer needed by Trusted Application 3149 Once the current Command Sequence is complete, the manifest 3150 processors checks each marked component to see whether any other 3151 manifests have referenced it. Those marked components with no other 3152 references are deleted. The manifest processor MAY choose to ignore 3153 a Unlink directive depending on device policy. 3155 suit-directive-unlink is OPTIONAL to implement in manifest 3156 processors. 3158 8.7.9. Integrity Check Values 3160 When the CoSWID, Text section, or any Command Sequence of the Update 3161 Procedure is made severable, it is moved to the Envelope and replaced 3162 with a SUIT_Digest. The SUIT_Digest is computed over the entire bstr 3163 enclosing the Manifest element that has been moved to the Envelope. 3164 Each element that is made severable from the Manifest is placed in 3165 the Envelope. The keys for the envelope elements have the same 3166 values as the keys for the manifest elements. 3168 Each Integrity Check Value covers the corresponding Envelope Element 3169 as described in Section 8.8. 3171 8.8. Severable Elements 3173 Because the manifest can be used by different actors at different 3174 times, some parts of the manifest can be removed or "Severed" without 3175 affecting later stages of the lifecycle. Severing of information is 3176 achieved by separating that information from the signed container so 3177 that removing it does not affect the signature. This means that 3178 ensuring integrity of severable parts of the manifest is a 3179 requirement for the signed portion of the manifest. Severing some 3180 parts makes it possible to discard parts of the manifest that are no 3181 longer necessary. This is important because it allows the storage 3182 used by the manifest to be greatly reduced. For example, no text 3183 size limits are needed if text is removed from the manifest prior to 3184 delivery to a constrained device. 3186 Elements are made severable by removing them from the manifest, 3187 encoding them in a bstr, and placing a SUIT_Digest of the bstr in the 3188 manifest so that they can still be authenticated. The SUIT_Digest 3189 typically consumes 4 bytes more than the size of the raw digest, 3190 therefore elements smaller than (Digest Bits)/8 + 4 SHOULD NOT be 3191 severable. Elements larger than (Digest Bits)/8 + 4 MAY be 3192 severable, while elements that are much larger than (Digest Bits)/8 + 3193 4 SHOULD be severable. 3195 Because of this, all command sequences in the manifest are encoded in 3196 a bstr so that there is a single code path needed for all command 3197 sequences. 3199 9. Access Control Lists 3201 To manage permissions in the manifest, there are three models that 3202 can be used. 3204 First, the simplest model requires that all manifests are 3205 authenticated by a single trusted key. This mode has the advantage 3206 that only a root manifest needs to be authenticated, since all of its 3207 dependencies have digests included in the root manifest. 3209 This simplest model can be extended by adding key delegation without 3210 much increase in complexity. 3212 A second model requires an ACL to be presented to the Recipient, 3213 authenticated by a trusted party or stored on the Recipient. This 3214 ACL grants access rights for specific component IDs or Component 3215 Identifier prefixes to the listed identities or identity groups. Any 3216 identity can verify an image digest, but fetching into or fetching 3217 from a Component Identifier requires approval from the ACL. 3219 A third model allows a Recipient to provide even more fine-grained 3220 controls: The ACL lists the Component Identifier or Component 3221 Identifier prefix that an identity can use, and also lists the 3222 commands and parameters that the identity can use in combination with 3223 that Component Identifier. 3225 10. SUIT Digest Container 3227 The SUIT digest is a CBOR List containing two elements: an algorithm 3228 identifier and a bstr containing the bytes of the digest. Some forms 3229 of digest may require additional parameters. These can be added 3230 following the digest. 3232 The values of the algorithm identifier are defined by 3233 [I-D.ietf-cose-hash-algs]. The following algorithms MUST be 3234 implemented by all Manifest Processors: 3236 - SHA-256 (-16) 3238 The following algorithms MAY be implemented in a Manifest Processor: 3240 - SHAKE128 (-18) 3242 - SHA-384 (-43) 3244 - SHA-512 (-44) 3246 - SHAKE256 (-45) 3248 11. IANA Considerations 3250 IANA is requested to: 3252 - allocate CBOR tag 107 in the CBOR Tags registry for the SUIT 3253 Envelope. 3255 - allocate CBOR tag 1070 in the CBOR Tags registry for the SUIT 3256 Manifest. 3258 - allocate media type application/suit-envelope in the Media Types 3259 registry. 3261 - setup several registries as described below. 3263 IANA is requested to setup a registry for SUIT manifests. Several 3264 registries defined in the subsections below need to be created. 3266 For each registry, values 0-23 are Standards Action, 24-255 are IETF 3267 Review, 256-65535 are Expert Review, and 65536 or greater are First 3268 Come First Served. 3270 Negative values -23 to 0 are Experimental Use, -24 and lower are 3271 Private Use. 3273 11.1. SUIT Commands 3275 +-------+------------+-----------------------------------+----------+ 3276 | Label | Name | Reference | | 3277 +-------+------------+-----------------------------------+----------+ 3278 | 1 | Vendor | Section 8.7.6.1 | | 3279 | | Identifier | | | 3280 | | | | | 3281 | 2 | Class | Section 8.7.6.1 | | 3282 | | Identifier | | | 3283 | | | | | 3284 | 3 | Image | Section 8.7.6.2 | | 3285 | | Match | | | 3286 | | | | | 3287 | 4 | Use Before | Section 8.7.6.4 | | 3288 | | | | | 3289 | 5 | Component | Section 8.7.6.5 | | 3290 | | Slot | | | 3291 | | | | | 3292 | 12 | Set | Section 8.7.7.1 | | 3293 | | Component | | | 3294 | | Index | | | 3295 | | | | | 3296 | 13 | Set | Section 8.7.7.2 | | 3297 | | Dependency | | | 3298 | | Index | | | 3299 | | | | | 3300 | 14 | Abort | | | 3301 | | | | | 3302 | 15 | Try Each | Section 8.7.7.3 | | 3303 | | | | | 3304 | 16 | Reserved | | | 3305 | | | | | 3306 | 17 | Reserved | | | 3307 | | | | | 3308 | 18 | Process | suit-directive-process-dependency | Section | 3309 | | Dependency | | 8.7.7.4 | 3310 | | | | | 3311 | 19 | Set | Section 8.7.7.5 | | 3312 | | Parameters | | | 3313 | | | | | 3314 | 20 | Override | Section 8.7.7.6 | | 3315 | | Parameters | | | 3316 | | | | | 3317 | 21 | Fetch | Section 8.7.7.7 | | 3318 | | | | | 3319 | 22 | Copy | Section 8.7.7.9 | | 3320 | | | | | 3321 | 23 | Run | Section 8.7.7.10 | | 3322 | | | | | 3323 | 24 | Device | Section 8.7.6.1 | | 3324 | | Identifier | | | 3325 | | | | | 3326 | 25 | Image Not | Section 8.7.6.3 | | 3327 | | Match | | | 3328 | | | | | 3329 | 26 | Minimum | Section 8.7.6.6 | | 3330 | | Battery | | | 3331 | | | | | 3332 | 27 | Update | Section 8.7.6.7 | | 3333 | | Authorized | | | 3334 | | | | | 3335 | 28 | Version | Section 8.7.6.8 | | 3336 | | | | | 3337 | 29 | Wait For | Section 8.7.7.11 | | 3338 | | Event | | | 3339 | | | | | 3340 | 30 | Fetch URI | Section 8.7.7.8 | | 3341 | | List | | | 3342 | | | | | 3343 | 31 | Swap | Section 8.7.7.13 | | 3344 | | | | | 3345 | 32 | Run | Section 8.7.7.12 | | 3346 | | Sequence | | | 3347 | | | | | 3348 | 33 | Unlink | Section 8.7.8 | | 3349 | | | | | 3350 | nint | Custom | Section 8.7.6.10 | | 3351 | | Condition | | | 3352 +-------+------------+-----------------------------------+----------+ 3354 11.2. SUIT Parameters 3355 +-------+------------------+---------------------------+ 3356 | Label | Name | Reference | 3357 +-------+------------------+---------------------------+ 3358 | 1 | Vendor ID | Section 8.7.5.3 | 3359 | | | | 3360 | 2 | Class ID | Section 8.7.5.4 | 3361 | | | | 3362 | 3 | Image Digest | Section 8.7.5.6 | 3363 | | | | 3364 | 4 | Use Before | Section 8.7.5.8 | 3365 | | | | 3366 | 5 | Component Slot | Section 8.7.5.9 | 3367 | | | | 3368 | 12 | Strict Order | Section 8.7.5.22 | 3369 | | | | 3370 | 13 | Soft Failure | Section 8.7.5.23 | 3371 | | | | 3372 | 14 | Image Size | Section 8.7.5.7 | 3373 | | | | 3374 | 18 | Encryption Info | Section 8.7.5.10 | 3375 | | | | 3376 | 19 | Compression Info | Section 8.7.5.11 | 3377 | | | | 3378 | 20 | Unpack Info | Section 8.7.5.12 | 3379 | | | | 3380 | 21 | URI | Section 8.7.5.13 | 3381 | | | | 3382 | 22 | Source Component | Section 8.7.5.14 | 3383 | | | | 3384 | 23 | Run Args | Section 8.7.5.15 | 3385 | | | | 3386 | 24 | Device ID | Section 8.7.5.5 | 3387 | | | | 3388 | 26 | Minimum Battery | Section 8.7.5.16 | 3389 | | | | 3390 | 27 | Update Priority | Section 8.7.5.17 | 3391 | | | | 3392 | 28 | Version | {{suit-parameter-version} | 3393 | | | | 3394 | 29 | Wait Info | Section 8.7.5.19 | 3395 | | | | 3396 | 30 | URI List | Section 8.7.5.20 | 3397 | | | | 3398 | nint | Custom | Section 8.7.5.24 | 3399 +-------+------------------+---------------------------+ 3401 11.3. SUIT Text Values 3403 +-------+----------------------+---------------+ 3404 | Label | Name | Reference | 3405 +-------+----------------------+---------------+ 3406 | 1 | Manifest Description | Section 8.6.4 | 3407 | | | | 3408 | 2 | Update Description | Section 8.6.4 | 3409 | | | | 3410 | 3 | Manifest JSON Source | Section 8.6.4 | 3411 | | | | 3412 | 4 | Manifest YAML Source | Section 8.6.4 | 3413 | | | | 3414 | nint | Custom | Section 8.6.4 | 3415 +-------+----------------------+---------------+ 3417 11.4. SUIT Component Text Values 3419 +-------+----------------------------+---------------+ 3420 | Label | Name | Reference | 3421 +-------+----------------------------+---------------+ 3422 | 1 | Vendor Name | Section 8.6.4 | 3423 | | | | 3424 | 2 | Model Name | Section 8.6.4 | 3425 | | | | 3426 | 3 | Vendor Domain | Section 8.6.4 | 3427 | | | | 3428 | 4 | Model Info | Section 8.6.4 | 3429 | | | | 3430 | 5 | Component Description | Section 8.6.4 | 3431 | | | | 3432 | 6 | Component Version | Section 8.6.4 | 3433 | | | | 3434 | 7 | Component Version Required | Section 8.6.4 | 3435 | | | | 3436 | nint | Custom | Section 8.6.4 | 3437 +-------+----------------------------+---------------+ 3439 11.5. SUIT Algorithm Identifiers 3441 11.5.1. SUIT Compression Algorithm Identifiers 3442 +-------+--------+------------------+ 3443 | Label | Name | Reference | 3444 +-------+--------+------------------+ 3445 | 1 | zlib | Section 8.7.5.11 | 3446 | | | | 3447 | 2 | Brotli | Section 8.7.5.11 | 3448 | | | | 3449 | 3 | zstd | Section 8.7.5.11 | 3450 +-------+--------+------------------+ 3452 11.5.2. Unpack Algorithms 3454 +-------+------+------------------+ 3455 | Label | Name | Reference | 3456 +-------+------+------------------+ 3457 | 1 | HEX | Section 8.7.5.12 | 3458 | | | | 3459 | 2 | ELF | Section 8.7.5.12 | 3460 | | | | 3461 | 3 | COFF | Section 8.7.5.12 | 3462 | | | | 3463 | 4 | SREC | Section 8.7.5.12 | 3464 +-------+------+------------------+ 3466 12. Security Considerations 3468 This document is about a manifest format protecting and describing 3469 how to retrieve, install, and invoke firmware images and as such it 3470 is part of a larger solution for delivering firmware updates to IoT 3471 devices. A detailed security treatment can be found in the 3472 architecture [I-D.ietf-suit-architecture] and in the information 3473 model [I-D.ietf-suit-information-model] documents. 3475 13. Acknowledgements 3477 We would like to thank the following persons for their support in 3478 designing this mechanism: 3480 - Milosch Meriac 3482 - Geraint Luff 3484 - Dan Ros 3486 - John-Paul Stanford 3488 - Hugo Vincent 3489 - Carsten Bormann 3491 - Oeyvind Roenningstad 3493 - Frank Audun Kvamtroe 3495 - Krzysztof Chruściński 3497 - Andrzej Puzdrowski 3499 - Michael Richardson 3501 - David Brown 3503 - Emmanuel Baccelli 3505 14. References 3507 14.1. Normative References 3509 [I-D.ietf-cose-hash-algs] 3510 Schaad, J., "CBOR Object Signing and Encryption (COSE): 3511 Hash Algorithms", draft-ietf-cose-hash-algs-09 (work in 3512 progress), September 2020. 3514 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3515 Requirement Levels", BCP 14, RFC 2119, 3516 DOI 10.17487/RFC2119, March 1997, 3517 . 3519 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3520 Resource Identifier (URI): Generic Syntax", STD 66, 3521 RFC 3986, DOI 10.17487/RFC3986, January 2005, 3522 . 3524 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 3525 Unique IDentifier (UUID) URN Namespace", RFC 4122, 3526 DOI 10.17487/RFC4122, July 2005, 3527 . 3529 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 3530 RFC 8152, DOI 10.17487/RFC8152, July 2017, 3531 . 3533 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3534 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3535 May 2017, . 3537 14.2. Informative References 3539 [COFF] Wikipedia, ., "Common Object File Format (COFF)", 2020, 3540 . 3542 [ELF] Wikipedia, ., "Executable and Linkable Format (ELF)", 3543 2020, . 3546 [HEX] Wikipedia, ., "Intel HEX", 2020, 3547 . 3549 [I-D.ietf-cbor-tags-oid] 3550 Bormann, C., "Concise Binary Object Representation (CBOR) 3551 Tags for Object Identifiers", draft-ietf-cbor-tags-oid-06 3552 (work in progress), March 2021. 3554 [I-D.ietf-sacm-coswid] 3555 Birkholz, H., Fitzgerald-McKay, J., Schmidt, C., and D. 3556 Waltermire, "Concise Software Identification Tags", draft- 3557 ietf-sacm-coswid-17 (work in progress), February 2021. 3559 [I-D.ietf-suit-architecture] 3560 Moran, B., Tschofenig, H., Brown, D., and M. Meriac, "A 3561 Firmware Update Architecture for Internet of Things", 3562 draft-ietf-suit-architecture-16 (work in progress), 3563 January 2021. 3565 [I-D.ietf-suit-information-model] 3566 Moran, B., Tschofenig, H., and H. Birkholz, "A Manifest 3567 Information Model for Firmware Updates in IoT Devices", 3568 draft-ietf-suit-information-model-11 (work in progress), 3569 April 2021. 3571 [I-D.ietf-teep-architecture] 3572 Pei, M., Tschofenig, H., Thaler, D., and D. Wheeler, 3573 "Trusted Execution Environment Provisioning (TEEP) 3574 Architecture", draft-ietf-teep-architecture-14 (work in 3575 progress), February 2021. 3577 [RFC1950] Deutsch, P. and J-L. Gailly, "ZLIB Compressed Data Format 3578 Specification version 3.3", RFC 1950, 3579 DOI 10.17487/RFC1950, May 1996, 3580 . 3582 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 3583 Constrained-Node Networks", RFC 7228, 3584 DOI 10.17487/RFC7228, May 2014, 3585 . 3587 [RFC7932] Alakuijala, J. and Z. Szabadka, "Brotli Compressed Data 3588 Format", RFC 7932, DOI 10.17487/RFC7932, July 2016, 3589 . 3591 [RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, 3592 "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, 3593 May 2018, . 3595 [RFC8747] Jones, M., Seitz, L., Selander, G., Erdtman, S., and H. 3596 Tschofenig, "Proof-of-Possession Key Semantics for CBOR 3597 Web Tokens (CWTs)", RFC 8747, DOI 10.17487/RFC8747, March 3598 2020, . 3600 [RFC8878] Collet, Y. and M. Kucherawy, Ed., "Zstandard Compression 3601 and the 'application/zstd' Media Type", RFC 8878, 3602 DOI 10.17487/RFC8878, February 2021, 3603 . 3605 [SREC] Wikipedia, ., "SREC (file format)", 2020, 3606 . 3608 [YAML] "YAML Ain't Markup Language", 2020, . 3610 Appendix A. A. Full CDDL 3612 In order to create a valid SUIT Manifest document the structure of 3613 the corresponding CBOR message MUST adhere to the following CDDL data 3614 definition. 3616 To be valid, the following CDDL MUST have the COSE CDDL appended to 3617 it. The COSE CDDL can be obtained by following the directions in 3618 [RFC8152], section 1.4. 3620 SUIT_Envelope_Tagged = #6.107(SUIT_Envelope) 3621 SUIT_Envelope = { 3622 ? suit-delegation => bstr .cbor SUIT_Delegation, 3623 suit-authentication-wrapper => bstr .cbor SUIT_Authentication, 3624 suit-manifest => bstr .cbor SUIT_Manifest, 3625 SUIT_Severable_Manifest_Members, 3626 * SUIT_Integrated_Payload, 3627 * SUIT_Integrated_Dependency, 3628 * $$SUIT_Envelope_Extensions, 3629 * (int => bstr) 3630 } 3632 SUIT_Delegation = [ + [ + bstr .cbor CWT ] ] 3634 CWT = SUIT_Authentication_Block 3636 SUIT_Authentication = [ 3637 bstr .cbor SUIT_Digest, 3638 * bstr .cbor SUIT_Authentication_Block 3639 ] 3641 SUIT_Digest = [ 3642 suit-digest-algorithm-id : suit-cose-hash-algs, 3643 suit-digest-bytes : bstr, 3644 * $$SUIT_Digest-extensions 3645 ] 3647 SUIT_Authentication_Block /= COSE_Mac_Tagged 3648 SUIT_Authentication_Block /= COSE_Sign_Tagged 3649 SUIT_Authentication_Block /= COSE_Mac0_Tagged 3650 SUIT_Authentication_Block /= COSE_Sign1_Tagged 3652 SUIT_Severable_Manifest_Members = ( 3653 ? suit-dependency-resolution => bstr .cbor SUIT_Command_Sequence, 3654 ? suit-payload-fetch => bstr .cbor SUIT_Command_Sequence, 3655 ? suit-install => bstr .cbor SUIT_Command_Sequence, 3656 ? suit-text => bstr .cbor SUIT_Text_Map, 3657 ? suit-coswid => bstr .cbor concise-software-identity, 3658 * $$SUIT_severable-members-extensions, 3659 ) 3661 SUIT_Integrated_Payload = (suit-integrated-payload-key => bstr) 3662 SUIT_Integrated_Dependency = ( 3663 suit-integrated-dependency-key => bstr .cbor SUIT_Envelope 3664 ) 3665 suit-integrated-payload-key = nint / uint .ge 24 3666 suit-integrated-dependency-key = suit-integrated-payload-key 3668 SUIT_Manifest_Tagged = #6.1070(SUIT_Manifest) 3670 SUIT_Manifest = { 3671 suit-manifest-version => 1, 3672 suit-manifest-sequence-number => uint, 3673 suit-common => bstr .cbor SUIT_Common, 3674 ? suit-reference-uri => tstr, 3675 SUIT_Severable_Members_Choice, 3676 SUIT_Unseverable_Members, 3677 * $$SUIT_Manifest_Extensions, 3678 } 3680 SUIT_Unseverable_Members = ( 3681 ? suit-validate => bstr .cbor SUIT_Command_Sequence, 3682 ? suit-load => bstr .cbor SUIT_Command_Sequence, 3683 ? suit-run => bstr .cbor SUIT_Command_Sequence, 3684 * $$unseverable-manifest-member-extensions, 3685 ) 3687 SUIT_Severable_Members_Choice = ( 3688 ? suit-dependency-resolution => \ 3689 bstr .cbor SUIT_Command_Sequence / SUIT_Digest, 3690 ? suit-payload-fetch => \ 3691 bstr .cbor SUIT_Command_Sequence / SUIT_Digest, 3692 ? suit-install => bstr .cbor SUIT_Command_Sequence / SUIT_Digest, 3693 ? suit-text => bstr .cbor SUIT_Command_Sequence / SUIT_Digest, 3694 ? suit-coswid => bstr .cbor SUIT_Command_Sequence / SUIT_Digest, 3695 * $$severable-manifest-members-choice-extensions 3696 ) 3698 SUIT_Common = { 3699 ? suit-dependencies => SUIT_Dependencies, 3700 ? suit-components => SUIT_Components, 3701 ? suit-common-sequence => bstr .cbor SUIT_Common_Sequence, 3702 * $$SUIT_Common-extensions, 3703 } 3705 SUIT_Dependencies = [ + SUIT_Dependency ] 3706 SUIT_Components = [ + SUIT_Component_Identifier ] 3708 concise-software-identity = any 3710 SUIT_Dependency = { 3711 suit-dependency-digest => SUIT_Digest, 3712 ? suit-dependency-prefix => SUIT_Component_Identifier, 3713 * $$SUIT_Dependency-extensions, 3714 } 3716 ;REQUIRED to implement: 3717 suit-cose-hash-algs /= cose-alg-sha-256 3719 ;OPTIONAL to implement: 3720 suit-cose-hash-algs /= cose-alg-shake128 3721 suit-cose-hash-algs /= cose-alg-sha-384 3722 suit-cose-hash-algs /= cose-alg-sha-512 3723 suit-cose-hash-algs /= cose-alg-shake256 3725 SUIT_Component_Identifier = [* bstr] 3727 SUIT_Common_Sequence = [ 3728 + ( SUIT_Condition // SUIT_Common_Commands ) 3729 ] 3731 SUIT_Common_Commands //= (suit-directive-set-component-index, IndexArg) 3732 SUIT_Common_Commands //= (suit-directive-set-dependency-index, IndexArg) 3733 SUIT_Common_Commands //= (suit-directive-run-sequence, 3734 bstr .cbor SUIT_Command_Sequence) 3735 SUIT_Common_Commands //= (suit-directive-try-each, 3736 SUIT_Directive_Try_Each_Argument) 3737 SUIT_Common_Commands //= (suit-directive-set-parameters, 3738 {+ SUIT_Parameters}) 3739 SUIT_Common_Commands //= (suit-directive-override-parameters, 3740 {+ SUIT_Parameters}) 3742 IndexArg /= uint 3743 IndexArg /= bool 3744 IndexArg /= [+uint] 3746 SUIT_Command_Sequence = [ + ( 3747 SUIT_Condition // SUIT_Directive // SUIT_Command_Custom 3748 ) ] 3750 SUIT_Command_Custom = (suit-command-custom, bstr/tstr/int/nil) 3751 SUIT_Condition //= (suit-condition-vendor-identifier, SUIT_Rep_Policy) 3752 SUIT_Condition //= (suit-condition-class-identifier, SUIT_Rep_Policy) 3753 SUIT_Condition //= (suit-condition-device-identifier, SUIT_Rep_Policy) 3754 SUIT_Condition //= (suit-condition-image-match, SUIT_Rep_Policy) 3755 SUIT_Condition //= (suit-condition-image-not-match, SUIT_Rep_Policy) 3756 SUIT_Condition //= (suit-condition-use-before, SUIT_Rep_Policy) 3757 SUIT_Condition //= (suit-condition-minimum-battery, SUIT_Rep_Policy) 3758 SUIT_Condition //= (suit-condition-update-authorized, SUIT_Rep_Policy) 3759 SUIT_Condition //= (suit-condition-version, SUIT_Rep_Policy) 3760 SUIT_Condition //= (suit-condition-component-slot, SUIT_Rep_Policy) 3761 SUIT_Condition //= (suit-condition-abort, SUIT_Rep_Policy) 3763 SUIT_Directive //= (suit-directive-set-component-index, IndexArg) 3764 SUIT_Directive //= (suit-directive-set-dependency-index, IndexArg) 3765 SUIT_Directive //= (suit-directive-run-sequence, 3766 bstr .cbor SUIT_Command_Sequence) 3767 SUIT_Directive //= (suit-directive-try-each, 3768 SUIT_Directive_Try_Each_Argument) 3769 SUIT_Directive //= (suit-directive-process-dependency, SUIT_Rep_Policy) 3770 SUIT_Directive //= (suit-directive-set-parameters, 3771 {+ SUIT_Parameters}) 3772 SUIT_Directive //= (suit-directive-override-parameters, 3773 {+ SUIT_Parameters}) 3774 SUIT_Directive //= (suit-directive-fetch, SUIT_Rep_Policy) 3775 SUIT_Directive //= (suit-directive-copy, SUIT_Rep_Policy) 3776 SUIT_Directive //= (suit-directive-swap, SUIT_Rep_Policy) 3777 SUIT_Directive //= (suit-directive-run, SUIT_Rep_Policy) 3778 SUIT_Directive //= (suit-directive-wait, SUIT_Rep_Policy) 3779 SUIT_Directive //= (suit-directive-fetch-uri-list, SUIT_Rep_Policy) 3780 SUIT_Directive //= (suit-directive-unlink, SUIT_Rep_Policy) 3782 SUIT_Directive_Try_Each_Argument = [ 3783 2* bstr .cbor SUIT_Command_Sequence, 3784 ?nil 3785 ] 3787 SUIT_Rep_Policy = uint .bits suit-reporting-bits 3789 suit-reporting-bits = &( 3790 suit-send-record-success : 0, 3791 suit-send-record-failure : 1, 3792 suit-send-sysinfo-success : 2, 3793 suit-send-sysinfo-failure : 3 3794 ) 3796 SUIT_Wait_Event = { + SUIT_Wait_Events } 3798 SUIT_Wait_Events //= (suit-wait-event-authorization => int) 3799 SUIT_Wait_Events //= (suit-wait-event-power => int) 3800 SUIT_Wait_Events //= (suit-wait-event-network => int) 3801 SUIT_Wait_Events //= (suit-wait-event-other-device-version 3802 => SUIT_Wait_Event_Argument_Other_Device_Version) 3803 SUIT_Wait_Events //= (suit-wait-event-time => uint); Timestamp 3804 SUIT_Wait_Events //= (suit-wait-event-time-of-day 3805 => uint); Time of Day (seconds since 00:00:00) 3806 SUIT_Wait_Events //= (suit-wait-event-day-of-week 3807 => uint); Days since Sunday 3809 SUIT_Wait_Event_Argument_Other_Device_Version = [ 3810 other-device: bstr, 3811 other-device-version: [ + SUIT_Parameter_Version_Match ] 3812 ] 3814 SUIT_Parameters //= (suit-parameter-vendor-identifier => 3815 (RFC4122_UUID / cbor-pen)) 3816 cbor-pen = #6.112(bstr) 3818 SUIT_Parameters //= (suit-parameter-class-identifier => RFC4122_UUID) 3819 SUIT_Parameters //= (suit-parameter-image-digest 3820 => bstr .cbor SUIT_Digest) 3821 SUIT_Parameters //= (suit-parameter-image-size => uint) 3822 SUIT_Parameters //= (suit-parameter-use-before => uint) 3823 SUIT_Parameters //= (suit-parameter-component-slot => uint) 3825 SUIT_Parameters //= (suit-parameter-encryption-info 3826 => bstr .cbor SUIT_Encryption_Info) 3827 SUIT_Parameters //= (suit-parameter-compression-info 3828 => bstr .cbor SUIT_Compression_Info) 3829 SUIT_Parameters //= (suit-parameter-unpack-info 3830 => bstr .cbor SUIT_Unpack_Info) 3832 SUIT_Parameters //= (suit-parameter-uri => tstr) 3833 SUIT_Parameters //= (suit-parameter-source-component => uint) 3834 SUIT_Parameters //= (suit-parameter-run-args => bstr) 3836 SUIT_Parameters //= (suit-parameter-device-identifier => RFC4122_UUID) 3837 SUIT_Parameters //= (suit-parameter-minimum-battery => uint) 3838 SUIT_Parameters //= (suit-parameter-update-priority => uint) 3839 SUIT_Parameters //= (suit-parameter-version => 3840 SUIT_Parameter_Version_Match) 3841 SUIT_Parameters //= (suit-parameter-wait-info => 3842 bstr .cbor SUIT_Wait_Event) 3844 SUIT_Parameters //= (suit-parameter-custom => int/bool/tstr/bstr) 3846 SUIT_Parameters //= (suit-parameter-strict-order => bool) 3847 SUIT_Parameters //= (suit-parameter-soft-failure => bool) 3849 SUIT_Parameters //= (suit-parameter-uri-list => 3850 bstr .cbor SUIT_URI_List) 3852 RFC4122_UUID = bstr .size 16 3854 SUIT_Parameter_Version_Match = [ 3855 suit-condition-version-comparison-type: 3856 SUIT_Condition_Version_Comparison_Types, 3857 suit-condition-version-comparison-value: 3858 SUIT_Condition_Version_Comparison_Value 3859 ] 3860 SUIT_Condition_Version_Comparison_Types /= 3861 suit-condition-version-comparison-greater 3862 SUIT_Condition_Version_Comparison_Types /= 3863 suit-condition-version-comparison-greater-equal 3864 SUIT_Condition_Version_Comparison_Types /= 3865 suit-condition-version-comparison-equal 3866 SUIT_Condition_Version_Comparison_Types /= 3867 suit-condition-version-comparison-lesser-equal 3868 SUIT_Condition_Version_Comparison_Types /= 3869 suit-condition-version-comparison-lesser 3871 suit-condition-version-comparison-greater = 1 3872 suit-condition-version-comparison-greater-equal = 2 3873 suit-condition-version-comparison-equal = 3 3874 suit-condition-version-comparison-lesser-equal = 4 3875 suit-condition-version-comparison-lesser = 5 3877 SUIT_Condition_Version_Comparison_Value = [+int] 3879 SUIT_Encryption_Info = COSE_Encrypt_Tagged/COSE_Encrypt0_Tagged 3880 SUIT_Compression_Info = { 3881 suit-compression-algorithm => SUIT_Compression_Algorithms, 3882 * $$SUIT_Compression_Info-extensions, 3883 } 3885 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_zlib 3886 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_brotli 3887 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_zstd 3889 SUIT_Compression_Algorithm_zlib = 1 3890 SUIT_Compression_Algorithm_brotli = 2 3891 SUIT_Compression_Algorithm_zstd = 3 3893 SUIT_Unpack_Info = { 3894 suit-unpack-algorithm => SUIT_Unpack_Algorithms, 3895 * $$SUIT_Unpack_Info-extensions, 3897 } 3898 SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Hex 3899 SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Elf 3900 SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Coff 3901 SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Srec 3903 SUIT_Unpack_Algorithm_Hex = 1 3904 SUIT_Unpack_Algorithm_Elf = 2 3905 SUIT_Unpack_Algorithm_Coff = 3 3906 SUIT_Unpack_Algorithm_Srec = 4 3908 SUIT_URI_List = [+ tstr ] 3910 SUIT_Text_Map = { 3911 SUIT_Text_Keys, 3912 * SUIT_Component_Identifier => { 3913 SUIT_Text_Component_Keys 3914 } 3915 } 3917 SUIT_Text_Component_Keys = ( 3918 ? suit-text-vendor-name => tstr, 3919 ? suit-text-model-name => tstr, 3920 ? suit-text-vendor-domain => tstr, 3921 ? suit-text-model-info => tstr, 3922 ? suit-text-component-description => tstr, 3923 ? suit-text-component-version => tstr, 3924 ? suit-text-version-required => tstr, 3925 * $$suit-text-component-key-extensions 3926 ) 3928 SUIT_Text_Keys = ( 3929 ? suit-text-manifest-description => tstr, 3930 ? suit-text-update-description => tstr, 3931 ? suit-text-manifest-json-source => tstr, 3932 ? suit-text-manifest-yaml-source => tstr, 3933 * $$suit-text-key-extensions 3934 ) 3936 suit-delegation = 1 3937 suit-authentication-wrapper = 2 3938 suit-manifest = 3 3940 ;REQUIRED to implement: 3941 cose-alg-sha-256 = -16 3943 ;OPTIONAL to implement: 3944 cose-alg-shake128 = -18 3945 cose-alg-sha-384 = -43 3946 cose-alg-sha-512 = -44 3947 cose-alg-shake256 = -45 3949 suit-manifest-version = 1 3950 suit-manifest-sequence-number = 2 3951 suit-common = 3 3952 suit-reference-uri = 4 3953 suit-dependency-resolution = 7 3954 suit-payload-fetch = 8 3955 suit-install = 9 3956 suit-validate = 10 3957 suit-load = 11 3958 suit-run = 12 3959 suit-text = 13 3960 suit-coswid = 14 3962 suit-dependencies = 1 3963 suit-components = 2 3964 suit-common-sequence = 4 3966 suit-dependency-digest = 1 3967 suit-dependency-prefix = 2 3969 suit-command-custom = nint 3971 suit-condition-vendor-identifier = 1 3972 suit-condition-class-identifier = 2 3973 suit-condition-image-match = 3 3974 suit-condition-use-before = 4 3975 suit-condition-component-slot = 5 3977 suit-condition-abort = 14 3978 suit-condition-device-identifier = 24 3979 suit-condition-image-not-match = 25 3980 suit-condition-minimum-battery = 26 3981 suit-condition-update-authorized = 27 3982 suit-condition-version = 28 3984 suit-directive-set-component-index = 12 3985 suit-directive-set-dependency-index = 13 3986 suit-directive-try-each = 15 3987 suit-directive-process-dependency = 18 3988 suit-directive-set-parameters = 19 3989 suit-directive-override-parameters = 20 3990 suit-directive-fetch = 21 3991 suit-directive-copy = 22 3992 suit-directive-run = 23 3993 suit-directive-wait = 29 3994 suit-directive-fetch-uri-list = 30 3995 suit-directive-swap = 31 3996 suit-directive-run-sequence = 32 3997 suit-directive-unlink = 33 3999 suit-wait-event-authorization = 1 4000 suit-wait-event-power = 2 4001 suit-wait-event-network = 3 4002 suit-wait-event-other-device-version = 4 4003 suit-wait-event-time = 5 4004 suit-wait-event-time-of-day = 6 4005 suit-wait-event-day-of-week = 7 4007 suit-parameter-vendor-identifier = 1 4008 suit-parameter-class-identifier = 2 4009 suit-parameter-image-digest = 3 4010 suit-parameter-use-before = 4 4011 suit-parameter-component-slot = 5 4013 suit-parameter-strict-order = 12 4014 suit-parameter-soft-failure = 13 4015 suit-parameter-image-size = 14 4017 suit-parameter-encryption-info = 18 4018 suit-parameter-compression-info = 19 4019 suit-parameter-unpack-info = 20 4020 suit-parameter-uri = 21 4021 suit-parameter-source-component = 22 4022 suit-parameter-run-args = 23 4024 suit-parameter-device-identifier = 24 4025 suit-parameter-minimum-battery = 26 4026 suit-parameter-update-priority = 27 4027 suit-parameter-version = 28 4028 suit-parameter-wait-info = 29 4029 suit-parameter-uri-list = 30 4031 suit-parameter-custom = nint 4033 suit-compression-algorithm = 1 4035 suit-unpack-algorithm = 1 4037 suit-text-manifest-description = 1 4038 suit-text-update-description = 2 4039 suit-text-manifest-json-source = 3 4040 suit-text-manifest-yaml-source = 4 4041 suit-text-vendor-name = 1 4042 suit-text-model-name = 2 4043 suit-text-vendor-domain = 3 4044 suit-text-model-info = 4 4045 suit-text-component-description = 5 4046 suit-text-component-version = 6 4047 suit-text-version-required = 7 4049 Appendix B. B. Examples 4051 The following examples demonstrate a small subset of the 4052 functionality of the manifest. Even a simple manifest processor can 4053 execute most of these manifests. 4055 The examples are signed using the following ECDSA secp256r1 key: 4057 -----BEGIN PRIVATE KEY----- 4058 MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgApZYjZCUGLM50VBC 4059 CjYStX+09jGmnyJPrpDLTz/hiXOhRANCAASEloEarguqq9JhVxie7NomvqqL8Rtv 4060 P+bitWWchdvArTsfKktsCYExwKNtrNHXi9OB3N+wnAUtszmR23M4tKiW 4061 -----END PRIVATE KEY----- 4063 The corresponding public key can be used to verify these examples: 4065 -----BEGIN PUBLIC KEY----- 4066 MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEhJaBGq4LqqvSYVcYnuzaJr6qi/Eb 4067 bz/m4rVlnIXbwK07HypLbAmBMcCjbazR14vTgdzfsJwFLbM5kdtzOLSolg== 4068 -----END PUBLIC KEY----- 4070 Each example uses SHA256 as the digest function. 4072 Note that reporting policies are declared for each non-flow-control 4073 command in these examples. The reporting policies used in the 4074 examples are described in the following tables. 4076 +-----------------------------+----------+ 4077 | Policy | Label | 4078 +-----------------------------+----------+ 4079 | suit-send-record-on-success | Rec-Pass | 4080 | | | 4081 | suit-send-record-on-failure | Rec-Fail | 4082 | | | 4083 | suit-send-sysinfo-success | Sys-Pass | 4084 | | | 4085 | suit-send-sysinfo-failure | Sys-Fail | 4086 +-----------------------------+----------+ 4088 +----------------------------+--------+---------+---------+---------+ 4089 | Command | Sys- | Sys- | Rec- | Rec- | 4090 | | Fail | Pass | Fail | Pass | 4091 +----------------------------+--------+---------+---------+---------+ 4092 | suit-condition-vendor- | 1 | 1 | 1 | 1 | 4093 | identifier | | | | | 4094 | | | | | | 4095 | suit-condition-class- | 1 | 1 | 1 | 1 | 4096 | identifier | | | | | 4097 | | | | | | 4098 | suit-condition-image-match | 1 | 1 | 1 | 1 | 4099 | | | | | | 4100 | suit-condition-component- | 0 | 1 | 0 | 1 | 4101 | slot | | | | | 4102 | | | | | | 4103 | suit-directive-fetch | 0 | 0 | 1 | 0 | 4104 | | | | | | 4105 | suit-directive-copy | 0 | 0 | 1 | 0 | 4106 | | | | | | 4107 | suit-directive-run | 0 | 0 | 1 | 0 | 4108 +----------------------------+--------+---------+---------+---------+ 4110 B.1. Example 0: Secure Boot 4112 This example covers the following templates: 4114 - Compatibility Check (Section 7.1) 4116 - Secure Boot (Section 7.2) 4118 It also serves as the minimum example. 4120 107({ 4121 / authentication-wrapper / 2:<<[ 4122 digest: <<[ 4123 / algorithm-id / -16 / "sha256" /, 4124 / digest-bytes / 4125 h'a6c4590ac53043a98e8c4106e1e31b305516d7cf0a655eddfac6d45c810e036a' 4126 ]>>, 4127 signature: <<18([ 4128 / protected / <<{ 4129 / alg / 1:-7 / "ES256" /, 4130 }>>, 4131 / unprotected / { 4132 }, 4133 / payload / F6 / nil /, 4134 / signature / h'd11a2dd9610fb62a707335f58407922570 4135 9f96e8117e7eeed98a2f207d05c8ecfba1755208f6abea977b8a6efe3bc2ca3215e119 4136 3be201467d052b42db6b7287' 4137 ])>> 4138 ] 4139 ]>>, 4140 / manifest / 3:<<{ 4141 / manifest-version / 1:1, 4142 / manifest-sequence-number / 2:0, 4143 / common / 3:<<{ 4144 / components / 2:[ 4145 [h'00'] 4146 ], 4147 / common-sequence / 4:<<[ 4148 / directive-override-parameters / 20,{ 4149 / vendor-id / 4150 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 4151 be9d-e663e4d41ffe /, 4152 / class-id / 4153 2:h'1492af1425695e48bf429b2d51f2ab45' / 4154 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 4155 / image-digest / 3:<<[ 4156 / algorithm-id / -16 / "sha256" /, 4157 / digest-bytes / 4158 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 4159 ]>>, 4160 / image-size / 14:34768, 4161 } , 4162 / condition-vendor-identifier / 1,15 , 4163 / condition-class-identifier / 2,15 4164 ]>>, 4165 }>>, 4166 / validate / 10:<<[ 4167 / condition-image-match / 3,15 4168 ]>>, 4169 / run / 12:<<[ 4170 / directive-run / 23,2 4171 ]>>, 4172 }>>, 4173 }) 4175 Total size of Envelope without COSE authentication object: 161 4177 Envelope: 4179 d86ba2025827815824822f5820a6c4590ac53043a98e8c4106e1e31b3055 4180 16d7cf0a655eddfac6d45c810e036a035871a50101020003585fa2028181 4181 41000458568614a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492 4182 af1425695e48bf429b2d51f2ab45035824822f5820001122334455667788 4183 99aabbccddeeff0123456789abcdeffedcba98765432100e1987d0010f02 4184 0f0a4382030f0c43821702 4186 Total size of Envelope with COSE authentication object: 237 4188 Envelope with COSE authentication object: 4190 d86ba2025873825824822f5820a6c4590ac53043a98e8c4106e1e31b3055 4191 16d7cf0a655eddfac6d45c810e036a584ad28443a10126a0f65840d11a2d 4192 d9610fb62a707335f584079225709f96e8117e7eeed98a2f207d05c8ecfb 4193 a1755208f6abea977b8a6efe3bc2ca3215e1193be201467d052b42db6b72 4194 87035871a50101020003585fa202818141000458568614a40150fa6b4a53 4195 d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab45 4196 035824822f582000112233445566778899aabbccddeeff0123456789abcd 4197 effedcba98765432100e1987d0010f020f0a4382030f0c43821702 4199 B.2. Example 1: Simultaneous Download and Installation of Payload 4201 This example covers the following templates: 4203 - Compatibility Check (Section 7.1) 4205 - Firmware Download (Section 7.3) 4207 Simultaneous download and installation of payload. No secure boot is 4208 present in this example to demonstrate a download-only manifest. 4210 107({ 4211 / authentication-wrapper / 2:<<[ 4212 digest: <<[ 4213 / algorithm-id / -16 / "sha256" /, 4214 / digest-bytes / 4215 h'60c61d6eb7a1aaeddc49ce8157a55cff0821537eeee77a4ded44155b03045132' 4216 ]>>, 4217 signature: <<18([ 4218 / protected / <<{ 4219 / alg / 1:-7 / "ES256" /, 4220 }>>, 4221 / unprotected / { 4222 }, 4223 / payload / F6 / nil /, 4224 / signature / h'5249dacaf0ffc8326931b09586eb7e3769 4225 e71a0e6a40ad8153db4980db9b05bd1742ddb46085fa11e62b65a79895c12ac7abe266 4226 8ccc5afdd74466aed7bca389' 4227 ])>> 4228 ] 4229 ]>>, 4230 / manifest / 3:<<{ 4231 / manifest-version / 1:1, 4232 / manifest-sequence-number / 2:1, 4233 / common / 3:<<{ 4234 / components / 2:[ 4235 [h'00'] 4236 ], 4237 / common-sequence / 4:<<[ 4238 / directive-override-parameters / 20,{ 4239 / vendor-id / 4240 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 4241 be9d-e663e4d41ffe /, 4242 / class-id / 4243 2:h'1492af1425695e48bf429b2d51f2ab45' / 4244 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 4245 / image-digest / 3:<<[ 4246 / algorithm-id / -16 / "sha256" /, 4247 / digest-bytes / 4248 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 4249 ]>>, 4250 / image-size / 14:34768, 4251 } , 4252 / condition-vendor-identifier / 1,15 , 4253 / condition-class-identifier / 2,15 4254 ]>>, 4255 }>>, 4256 / install / 9:<<[ 4257 / directive-set-parameters / 19,{ 4258 / uri / 21:'http://example.com/file.bin', 4259 } , 4260 / directive-fetch / 21,2 , 4261 / condition-image-match / 3,15 4262 ]>>, 4263 / validate / 10:<<[ 4264 / condition-image-match / 3,15 4265 ]>>, 4266 }>>, 4267 }) 4269 Total size of Envelope without COSE authentication object: 196 4271 Envelope: 4273 d86ba2025827815824822f582060c61d6eb7a1aaeddc49ce8157a55cff08 4274 21537eeee77a4ded44155b03045132035894a50101020103585fa2028181 4275 41000458568614a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492 4276 af1425695e48bf429b2d51f2ab45035824822f5820001122334455667788 4277 99aabbccddeeff0123456789abcdeffedcba98765432100e1987d0010f02 4278 0f0958258613a115781b687474703a2f2f6578616d706c652e636f6d2f66 4279 696c652e62696e1502030f0a4382030f 4281 Total size of Envelope with COSE authentication object: 272 4283 Envelope with COSE authentication object: 4285 d86ba2025873825824822f582060c61d6eb7a1aaeddc49ce8157a55cff08 4286 21537eeee77a4ded44155b03045132584ad28443a10126a0f658405249da 4287 caf0ffc8326931b09586eb7e3769e71a0e6a40ad8153db4980db9b05bd17 4288 42ddb46085fa11e62b65a79895c12ac7abe2668ccc5afdd74466aed7bca3 4289 89035894a50101020103585fa202818141000458568614a40150fa6b4a53 4290 d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab45 4291 035824822f582000112233445566778899aabbccddeeff0123456789abcd 4292 effedcba98765432100e1987d0010f020f0958258613a115781b68747470 4293 3a2f2f6578616d706c652e636f6d2f66696c652e62696e1502030f0a4382 4294 030f 4296 B.3. Example 2: Simultaneous Download, Installation, Secure Boot, 4297 Severed Fields 4299 This example covers the following templates: 4301 - Compatibility Check (Section 7.1) 4303 - Secure Boot (Section 7.2) 4305 - Firmware Download (Section 7.3) 4307 This example also demonstrates severable elements (Section 5.5), and 4308 text (Section 8.6.4). 4310 107({ 4311 / authentication-wrapper / 2:<<[ 4312 digest: <<[ 4313 / algorithm-id / -16 / "sha256" /, 4314 / digest-bytes / 4315 h'e45dcdb2074b951f1c88b866469939c2a83ed433a31fc7dfcb3f63955bd943ec' 4316 ]>>, 4317 signature: <<18([ 4318 / protected / <<{ 4319 / alg / 1:-7 / "ES256" /, 4320 }>>, 4321 / unprotected / { 4322 }, 4323 / payload / F6 / nil /, 4324 / signature / h'b4fd3a6a18fe1062573488cf24ac96ef9f 4325 30ac746696e50be96533b356b8156e4332587fe6f4e8743ae525d72005fddd4c1213d5 4326 5a8061b2ce67b83640f4777c' 4327 ])>> 4328 ] 4329 ]>>, 4330 / manifest / 3:<<{ 4331 / manifest-version / 1:1, 4332 / manifest-sequence-number / 2:2, 4333 / common / 3:<<{ 4334 / components / 2:[ 4335 [h'00'] 4336 ], 4337 / common-sequence / 4:<<[ 4338 / directive-override-parameters / 20,{ 4339 / vendor-id / 4340 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 4341 be9d-e663e4d41ffe /, 4342 / class-id / 4343 2:h'1492af1425695e48bf429b2d51f2ab45' / 4344 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 4345 / image-digest / 3:<<[ 4346 / algorithm-id / -16 / "sha256" /, 4347 / digest-bytes / 4348 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 4349 ]>>, 4350 / image-size / 14:34768, 4351 } , 4352 / condition-vendor-identifier / 1,15 , 4353 / condition-class-identifier / 2,15 4354 ]>>, 4355 }>>, 4356 / install / 9:[ 4357 / algorithm-id / -16 / "sha256" /, 4358 / digest-bytes / 4359 h'3ee96dc79641970ae46b929ccf0b72ba9536dd846020dbdc9f949d84ea0e18d2' 4360 ], 4361 / validate / 10:<<[ 4362 / condition-image-match / 3,15 4363 ]>>, 4364 / run / 12:<<[ 4365 / directive-run / 23,2 4366 ]>>, 4367 / text / 13:[ 4368 / algorithm-id / -16 / "sha256" /, 4369 / digest-bytes / 4370 h'2bfc4d0cc6680be7dd9f5ca30aa2bb5d1998145de33d54101b80e2ca49faf918' 4371 ], 4372 }>>, 4373 / install / 9:<<[ 4374 / directive-set-parameters / 19,{ 4375 / uri / 4376 21:'http://example.com/very/long/path/to/file/file.bin', 4377 } , 4378 / directive-fetch / 21,2 , 4379 / condition-image-match / 3,15 4380 ]>>, 4381 / text / 13:<<{ 4382 [h'00']:{ 4383 / vendor-domain / 3:'arm.com', 4384 / component-description / 5:'This component is a 4385 demonstration. The digest is a sample pattern, not a real one.', 4386 } 4387 }>>, 4388 }) 4390 Total size of the Envelope without COSE authentication object or 4391 Severable Elements: 235 4393 Envelope: 4395 d86ba2025827815824822f5820e45dcdb2074b951f1c88b866469939c2a8 4396 3ed433a31fc7dfcb3f63955bd943ec0358bba70101020203585fa2028181 4397 41000458568614a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492 4398 af1425695e48bf429b2d51f2ab45035824822f5820001122334455667788 4399 99aabbccddeeff0123456789abcdeffedcba98765432100e1987d0010f02 4400 0f09822f58203ee96dc79641970ae46b929ccf0b72ba9536dd846020dbdc 4401 9f949d84ea0e18d20a4382030f0c438217020d822f58202bfc4d0cc6680b 4402 e7dd9f5ca30aa2bb5d1998145de33d54101b80e2ca49faf918 4404 Total size of the Envelope with COSE authentication object but 4405 without Severable Elements: 311 4407 Envelope: 4409 d86ba2025873825824822f5820e45dcdb2074b951f1c88b866469939c2a8 4410 3ed433a31fc7dfcb3f63955bd943ec584ad28443a10126a0f65840b4fd3a 4411 6a18fe1062573488cf24ac96ef9f30ac746696e50be96533b356b8156e43 4412 32587fe6f4e8743ae525d72005fddd4c1213d55a8061b2ce67b83640f477 4413 7c0358bba70101020203585fa202818141000458568614a40150fa6b4a53 4414 d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab45 4415 035824822f582000112233445566778899aabbccddeeff0123456789abcd 4416 effedcba98765432100e1987d0010f020f09822f58203ee96dc79641970a 4417 e46b929ccf0b72ba9536dd846020dbdc9f949d84ea0e18d20a4382030f0c 4418 438217020d822f58202bfc4d0cc6680be7dd9f5ca30aa2bb5d1998145de3 4419 3d54101b80e2ca49faf918 4421 Total size of Envelope with COSE authentication object and Severable 4422 Elements: 894 4424 Envelope with COSE authentication object: 4426 d86ba4025873825824822f5820e45dcdb2074b951f1c88b866469939c2a8 4427 3ed433a31fc7dfcb3f63955bd943ec584ad28443a10126a0f65840b4fd3a 4428 6a18fe1062573488cf24ac96ef9f30ac746696e50be96533b356b8156e43 4429 32587fe6f4e8743ae525d72005fddd4c1213d55a8061b2ce67b83640f477 4430 7c0358bba70101020203585fa202818141000458568614a40150fa6b4a53 4431 d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab45 4432 035824822f582000112233445566778899aabbccddeeff0123456789abcd 4433 effedcba98765432100e1987d0010f020f09822f58203ee96dc79641970a 4434 e46b929ccf0b72ba9536dd846020dbdc9f949d84ea0e18d20a4382030f0c 4435 438217020d822f58202bfc4d0cc6680be7dd9f5ca30aa2bb5d1998145de3 4436 3d54101b80e2ca49faf91809583c8613a1157832687474703a2f2f657861 4437 6d706c652e636f6d2f766572792f6c6f6e672f706174682f746f2f66696c 4438 652f66696c652e62696e1502030f0d590204a20179019d2323204578616d 4439 706c6520323a2053696d756c74616e656f757320446f776e6c6f61642c20 4440 496e7374616c6c6174696f6e2c2053656375726520426f6f742c20536576 4441 65726564204669656c64730a0a2020202054686973206578616d706c6520 4442 636f766572732074686520666f6c6c6f77696e672074656d706c61746573 4443 3a0a202020200a202020202a20436f6d7061746962696c69747920436865 4444 636b20287b7b74656d706c6174652d636f6d7061746962696c6974792d63 4445 6865636b7d7d290a202020202a2053656375726520426f6f7420287b7b74 4446 656d706c6174652d7365637572652d626f6f747d7d290a202020202a2046 4447 69726d7761726520446f776e6c6f616420287b7b6669726d776172652d64 4448 6f776e6c6f61642d74656d706c6174657d7d290a202020200a2020202054 4449 686973206578616d706c6520616c736f2064656d6f6e7374726174657320 4450 736576657261626c6520656c656d656e747320287b7b6f76722d73657665 4451 7261626c657d7d292c20616e64207465787420287b7b6d616e6966657374 4452 2d6469676573742d746578747d7d292e814100a2036761726d2e636f6d05 4453 78525468697320636f6d706f6e656e7420697320612064656d6f6e737472 4454 6174696f6e2e205468652064696765737420697320612073616d706c6520 4455 7061747465726e2c206e6f742061207265616c206f6e652e 4457 B.4. Example 3: A/B images 4459 This example covers the following templates: 4461 - Compatibility Check (Section 7.1) 4463 - Secure Boot (Section 7.2) 4465 - Firmware Download (Section 7.3) 4467 - A/B Image Template (Section 7.11) 4469 107({ 4470 / authentication-wrapper / 2:<<[ 4471 digest: <<[ 4472 / algorithm-id / -16 / "sha256" /, 4473 / digest-bytes / 4474 h'7c9b3cb72c262608a42f944d59d659ff2b801c78af44def51b8ff51e9f45721b' 4475 ]>>, 4476 signature: <<18([ 4477 / protected / <<{ 4478 / alg / 1:-7 / "ES256" /, 4479 }>>, 4480 / unprotected / { 4481 }, 4482 / payload / F6 / nil /, 4483 / signature / h'e33d618df0ad21e609529ab1a876afb231 4484 faff1d6a3189b5360324c2794250b87cf00cf83be50ea17dc721ca85393cd8e839a066 4485 d5dec0ad87a903ab31ea9afa' 4486 ])>> 4487 ] 4488 ]>>, 4489 / manifest / 3:<<{ 4490 / manifest-version / 1:1, 4491 / manifest-sequence-number / 2:3, 4492 / common / 3:<<{ 4493 / components / 2:[ 4494 [h'00'] 4495 ], 4496 / common-sequence / 4:<<[ 4497 / directive-override-parameters / 20,{ 4498 / vendor-id / 4499 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 4500 be9d-e663e4d41ffe /, 4501 / class-id / 4502 2:h'1492af1425695e48bf429b2d51f2ab45' / 4503 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 4504 } , 4505 / directive-try-each / 15,[ 4506 <<[ 4507 / directive-override-parameters / 20,{ 4508 / offset / 5:33792, 4509 } , 4510 / condition-component-offset / 5,5 , 4511 / directive-override-parameters / 20,{ 4512 / image-digest / 3:<<[ 4513 / algorithm-id / -16 / "sha256" /, 4514 / digest-bytes / 4515 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 4516 ]>>, 4517 / image-size / 14:34768, 4518 } 4519 ]>> , 4520 <<[ 4521 / directive-override-parameters / 20,{ 4522 / offset / 5:541696, 4523 } , 4524 / condition-component-offset / 5,5 , 4525 / directive-override-parameters / 20,{ 4526 / image-digest / 3:<<[ 4527 / algorithm-id / -16 / "sha256" /, 4528 / digest-bytes / 4529 h'0123456789abcdeffedcba987654321000112233445566778899aabbccddeeff' 4530 ]>>, 4531 / image-size / 14:76834, 4532 } 4533 ]>> 4534 ] , 4535 / condition-vendor-identifier / 1,15 , 4536 / condition-class-identifier / 2,15 4537 ]>>, 4538 }>>, 4539 / install / 9:<<[ 4540 / directive-try-each / 15,[ 4541 <<[ 4542 / directive-set-parameters / 19,{ 4543 / offset / 5:33792, 4544 } , 4545 / condition-component-offset / 5,5 , 4546 / directive-set-parameters / 19,{ 4547 / uri / 21:'http://example.com/file1.bin', 4548 } 4549 ]>> , 4550 <<[ 4551 / directive-set-parameters / 19,{ 4552 / offset / 5:541696, 4554 } , 4555 / condition-component-offset / 5,5 , 4556 / directive-set-parameters / 19,{ 4557 / uri / 21:'http://example.com/file2.bin', 4558 } 4559 ]>> 4560 ] , 4561 / directive-fetch / 21,2 , 4562 / condition-image-match / 3,15 4563 ]>>, 4564 / validate / 10:<<[ 4565 / condition-image-match / 3,15 4566 ]>>, 4567 }>>, 4568 }) 4570 Total size of Envelope without COSE authentication object: 332 4572 Envelope: 4574 d86ba2025827815824822f58207c9b3cb72c262608a42f944d59d659ff2b 4575 801c78af44def51b8ff51e9f45721b0359011ba5010102030358aaa20281 4576 8141000458a18814a20150fa6b4a53d5ad5fdfbe9de663e4d41ffe025014 4577 92af1425695e48bf429b2d51f2ab450f8258368614a105198400050514a2 4578 035824822f582000112233445566778899aabbccddeeff0123456789abcd 4579 effedcba98765432100e1987d0583a8614a1051a00084400050514a20358 4580 24822f58200123456789abcdeffedcba9876543210001122334455667788 4581 99aabbccddeeff0e1a00012c22010f020f095861860f82582a8613a10519 4582 8400050513a115781c687474703a2f2f6578616d706c652e636f6d2f6669 4583 6c65312e62696e582c8613a1051a00084400050513a115781c687474703a 4584 2f2f6578616d706c652e636f6d2f66696c65322e62696e1502030f0a4382 4585 030f 4587 Total size of Envelope with COSE authentication object: 408 4589 Envelope with COSE authentication object: 4591 d86ba2025873825824822f58207c9b3cb72c262608a42f944d59d659ff2b 4592 801c78af44def51b8ff51e9f45721b584ad28443a10126a0f65840e33d61 4593 8df0ad21e609529ab1a876afb231faff1d6a3189b5360324c2794250b87c 4594 f00cf83be50ea17dc721ca85393cd8e839a066d5dec0ad87a903ab31ea9a 4595 fa0359011ba5010102030358aaa202818141000458a18814a20150fa6b4a 4596 53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab 4597 450f8258368614a105198400050514a2035824822f582000112233445566 4598 778899aabbccddeeff0123456789abcdeffedcba98765432100e1987d058 4599 3a8614a1051a00084400050514a2035824822f58200123456789abcdeffe 4600 dcba987654321000112233445566778899aabbccddeeff0e1a00012c2201 4601 0f020f095861860f82582a8613a105198400050513a115781c687474703a 4602 2f2f6578616d706c652e636f6d2f66696c65312e62696e582c8613a1051a 4603 00084400050513a115781c687474703a2f2f6578616d706c652e636f6d2f 4604 66696c65322e62696e1502030f0a4382030f 4606 B.5. Example 4: Load and Decompress from External Storage 4608 This example covers the following templates: 4610 - Compatibility Check (Section 7.1) 4612 - Secure Boot (Section 7.2) 4614 - Firmware Download (Section 7.3) 4616 - Install (Section 7.4) 4618 - Load & Decompress (Section 7.8) 4620 107({ 4621 / authentication-wrapper / 2:<<[ 4622 digest: <<[ 4623 / algorithm-id / -16 / "sha256" /, 4624 / digest-bytes / 4625 h'15736702a00f510805dcf89d6913a2cfb417ed414faa760f974d6755c68ba70a' 4626 ]>>, 4627 signature: <<18([ 4628 / protected / <<{ 4629 / alg / 1:-7 / "ES256" /, 4630 }>>, 4631 / unprotected / { 4632 }, 4633 / payload / F6 / nil /, 4634 / signature / h'3ada2532326d512132c388677798c24ffd 4635 cc979bfae2a26b19c8c8bbf511fd7dd85f1501662c1a9e1976b759c4019bab44ba5434 4636 efb45d3868aedbca593671f3' 4637 ])>> 4638 ] 4640 ]>>, 4641 / manifest / 3:<<{ 4642 / manifest-version / 1:1, 4643 / manifest-sequence-number / 2:4, 4644 / common / 3:<<{ 4645 / components / 2:[ 4646 [h'00'] , 4647 [h'02'] , 4648 [h'01'] 4649 ], 4650 / common-sequence / 4:<<[ 4651 / directive-set-component-index / 12,0 , 4652 / directive-override-parameters / 20,{ 4653 / vendor-id / 4654 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 4655 be9d-e663e4d41ffe /, 4656 / class-id / 4657 2:h'1492af1425695e48bf429b2d51f2ab45' / 4658 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 4659 / image-digest / 3:<<[ 4660 / algorithm-id / -16 / "sha256" /, 4661 / digest-bytes / 4662 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 4663 ]>>, 4664 / image-size / 14:34768, 4665 } , 4666 / condition-vendor-identifier / 1,15 , 4667 / condition-class-identifier / 2,15 4668 ]>>, 4669 }>>, 4670 / payload-fetch / 8:<<[ 4671 / directive-set-component-index / 12,1 , 4672 / directive-set-parameters / 19,{ 4673 / uri / 21:'http://example.com/file.bin', 4674 } , 4675 / directive-fetch / 21,2 , 4676 / condition-image-match / 3,15 4677 ]>>, 4678 / install / 9:<<[ 4679 / directive-set-component-index / 12,0 , 4680 / directive-set-parameters / 19,{ 4681 / source-component / 22:1 / [h'02'] /, 4682 } , 4683 / directive-copy / 22,2 , 4684 / condition-image-match / 3,15 4685 ]>>, 4686 / validate / 10:<<[ 4687 / directive-set-component-index / 12,0 , 4688 / condition-image-match / 3,15 4689 ]>>, 4690 / load / 11:<<[ 4691 / directive-set-component-index / 12,2 , 4692 / directive-set-parameters / 19,{ 4693 / image-digest / 3:<<[ 4694 / algorithm-id / -16 / "sha256" /, 4695 / digest-bytes / 4696 h'0123456789abcdeffedcba987654321000112233445566778899aabbccddeeff' 4697 ]>>, 4698 / image-size / 14:76834, 4699 / source-component / 22:0 / [h'00'] /, 4700 / compression-info / 19:<<{ 4701 / compression-algorithm / 1:1 / "gzip" /, 4702 }>>, 4703 } , 4704 / directive-copy / 22,2 , 4705 / condition-image-match / 3,15 4706 ]>>, 4707 / run / 12:<<[ 4708 / directive-set-component-index / 12,2 , 4709 / directive-run / 23,2 4710 ]>>, 4711 }>>, 4712 }) 4714 Total size of Envelope without COSE authentication object: 292 4716 Envelope: 4718 d86ba2025827815824822f582015736702a00f510805dcf89d6913a2cfb4 4719 17ed414faa760f974d6755c68ba70a0358f4a801010204035867a2028381 4720 4100814102814101045858880c0014a40150fa6b4a53d5ad5fdfbe9de663 4721 e4d41ffe02501492af1425695e48bf429b2d51f2ab45035824822f582000 4722 112233445566778899aabbccddeeff0123456789abcdeffedcba98765432 4723 100e1987d0010f020f085827880c0113a115781b687474703a2f2f657861 4724 6d706c652e636f6d2f66696c652e62696e1502030f094b880c0013a11601 4725 1602030f0a45840c00030f0b583d880c0213a4035824822f582001234567 4726 89abcdeffedcba987654321000112233445566778899aabbccddeeff0e1a 4727 00012c221343a1010116001602030f0c45840c021702 4729 Total size of Envelope with COSE authentication object: 368 4731 Envelope with COSE authentication object: 4733 d86ba2025873825824822f582015736702a00f510805dcf89d6913a2cfb4 4734 17ed414faa760f974d6755c68ba70a584ad28443a10126a0f658403ada25 4735 32326d512132c388677798c24ffdcc979bfae2a26b19c8c8bbf511fd7dd8 4736 5f1501662c1a9e1976b759c4019bab44ba5434efb45d3868aedbca593671 4737 f30358f4a801010204035867a20283814100814102814101045858880c00 4738 14a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48 4739 bf429b2d51f2ab45035824822f582000112233445566778899aabbccddee 4740 ff0123456789abcdeffedcba98765432100e1987d0010f020f085827880c 4741 0113a115781b687474703a2f2f6578616d706c652e636f6d2f66696c652e 4742 62696e1502030f094b880c0013a116011602030f0a45840c00030f0b583d 4743 880c0213a4035824822f58200123456789abcdeffedcba98765432100011 4744 2233445566778899aabbccddeeff0e1a00012c221343a101011600160203 4745 0f0c45840c021702 4747 B.6. Example 5: Two Images 4749 This example covers the following templates: 4751 - Compatibility Check (Section 7.1) 4753 - Secure Boot (Section 7.2) 4755 - Firmware Download (Section 7.3) 4757 Furthermore, it shows using these templates with two images. 4759 107({ 4760 / authentication-wrapper / 2:<<[ 4761 digest: <<[ 4762 / algorithm-id / -16 / "sha256" /, 4763 / digest-bytes / 4764 h'd1e73f16e4126007bc4d804cd33b0209fbab34728e60ee8c00f3387126748dd2' 4765 ]>>, 4766 signature: <<18([ 4767 / protected / <<{ 4768 / alg / 1:-7 / "ES256" /, 4769 }>>, 4770 / unprotected / { 4771 }, 4772 / payload / F6 / nil /, 4773 / signature / h'b7ae0a46a28f02e25cda6d9a255bbaf863 4774 30141831fae5a78012d648bc6cee55102e0f1890bdeacc3adaa4fae0560f83a45eecae 4775 65cabce642f56d84ab97ef8d' 4776 ])>> 4777 ] 4778 ]>>, 4779 / manifest / 3:<<{ 4780 / manifest-version / 1:1, 4781 / manifest-sequence-number / 2:5, 4782 / common / 3:<<{ 4783 / components / 2:[ 4784 [h'00'] , 4785 [h'01'] 4786 ], 4787 / common-sequence / 4:<<[ 4788 / directive-set-component-index / 12,0 , 4789 / directive-override-parameters / 20,{ 4790 / vendor-id / 4791 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 4792 be9d-e663e4d41ffe /, 4793 / class-id / 4794 2:h'1492af1425695e48bf429b2d51f2ab45' / 4795 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 4796 / image-digest / 3:<<[ 4797 / algorithm-id / -16 / "sha256" /, 4798 / digest-bytes / 4799 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 4800 ]>>, 4801 / image-size / 14:34768, 4802 } , 4803 / condition-vendor-identifier / 1,15 , 4804 / condition-class-identifier / 2,15 , 4805 / directive-set-component-index / 12,1 , 4806 / directive-override-parameters / 20,{ 4807 / image-digest / 3:<<[ 4808 / algorithm-id / -16 / "sha256" /, 4809 / digest-bytes / 4810 h'0123456789abcdeffedcba987654321000112233445566778899aabbccddeeff' 4811 ]>>, 4812 / image-size / 14:76834, 4813 } 4814 ]>>, 4815 }>>, 4816 / install / 9:<<[ 4817 / directive-set-component-index / 12,0 , 4818 / directive-set-parameters / 19,{ 4819 / uri / 21:'http://example.com/file1.bin', 4820 } , 4821 / directive-fetch / 21,2 , 4822 / condition-image-match / 3,15 , 4823 / directive-set-component-index / 12,1 , 4824 / directive-set-parameters / 19,{ 4825 / uri / 21:'http://example.com/file2.bin', 4826 } , 4827 / directive-fetch / 21,2 , 4828 / condition-image-match / 3,15 4830 ]>>, 4831 / validate / 10:<<[ 4832 / directive-set-component-index / 12,0 , 4833 / condition-image-match / 3,15 , 4834 / directive-set-component-index / 12,1 , 4835 / condition-image-match / 3,15 4836 ]>>, 4837 / run / 12:<<[ 4838 / directive-set-component-index / 12,0 , 4839 / directive-run / 23,2 4840 ]>>, 4841 }>>, 4842 }) 4844 Total size of Envelope without COSE authentication object: 306 4846 Envelope: 4848 d86ba2025827815824822f5820d1e73f16e4126007bc4d804cd33b0209fb 4849 ab34728e60ee8c00f3387126748dd203590101a601010205035895a20282 4850 8141008141010458898c0c0014a40150fa6b4a53d5ad5fdfbe9de663e4d4 4851 1ffe02501492af1425695e48bf429b2d51f2ab45035824822f5820001122 4852 33445566778899aabbccddeeff0123456789abcdeffedcba98765432100e 4853 1987d0010f020f0c0114a2035824822f58200123456789abcdeffedcba98 4854 7654321000112233445566778899aabbccddeeff0e1a00012c2209584f90 4855 0c0013a115781c687474703a2f2f6578616d706c652e636f6d2f66696c65 4856 312e62696e1502030f0c0113a115781c687474703a2f2f6578616d706c65 4857 2e636f6d2f66696c65322e62696e1502030f0a49880c00030f0c01030f0c 4858 45840c001702 4860 Total size of Envelope with COSE authentication object: 382 4862 Envelope with COSE authentication object: 4864 d86ba2025873825824822f5820d1e73f16e4126007bc4d804cd33b0209fb 4865 ab34728e60ee8c00f3387126748dd2584ad28443a10126a0f65840b7ae0a 4866 46a28f02e25cda6d9a255bbaf86330141831fae5a78012d648bc6cee5510 4867 2e0f1890bdeacc3adaa4fae0560f83a45eecae65cabce642f56d84ab97ef 4868 8d03590101a601010205035895a202828141008141010458898c0c0014a4 4869 0150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf42 4870 9b2d51f2ab45035824822f582000112233445566778899aabbccddeeff01 4871 23456789abcdeffedcba98765432100e1987d0010f020f0c0114a2035824 4872 822f58200123456789abcdeffedcba987654321000112233445566778899 4873 aabbccddeeff0e1a00012c2209584f900c0013a115781c687474703a2f2f 4874 6578616d706c652e636f6d2f66696c65312e62696e1502030f0c0113a115 4875 781c687474703a2f2f6578616d706c652e636f6d2f66696c65322e62696e 4876 1502030f0a49880c00030f0c01030f0c45840c001702 4878 Appendix C. C. Design Rational 4880 In order to provide flexible behavior to constrained devices, while 4881 still allowing more powerful devices to use their full capabilities, 4882 the SUIT manifest encodes the required behavior of a Recipient 4883 device. Behavior is encoded as a specialized byte code, contained in 4884 a CBOR list. This promotes a flat encoding, which simplifies the 4885 parser. The information encoded by this byte code closely matches 4886 the operations that a device will perform, which promotes ease of 4887 processing. The core operations used by most update and trusted 4888 invocation operations are represented in the byte code. The byte 4889 code can be extended by registering new operations. 4891 The specialized byte code approach gives benefits equivalent to those 4892 provided by a scripting language or conventional byte code, with two 4893 substantial differences. First, the language is extremely high 4894 level, consisting of only the operations that a device may perform 4895 during update and trusted invocation of a firmware image. Second, 4896 the language specifies linear behavior, without reverse branches. 4897 Conditional processing is supported, and parallel and out-of-order 4898 processing may be performed by sufficiently capable devices. 4900 By structuring the data in this way, the manifest processor becomes a 4901 very simple engine that uses a pull parser to interpret the manifest. 4902 This pull parser invokes a series of command handlers that evaluate a 4903 Condition or execute a Directive. Most data is structured in a 4904 highly regular pattern, which simplifies the parser. 4906 The results of this allow a Recipient to implement a very small 4907 parser for constrained applications. If needed, such a parser also 4908 allows the Recipient to perform complex updates with reduced 4909 overhead. Conditional execution of commands allows a simple device 4910 to perform important decisions at validation-time. 4912 Dependency handling is vastly simplified as well. Dependencies 4913 function like subroutines of the language. When a manifest has a 4914 dependency, it can invoke that dependency's commands and modify their 4915 behavior by setting parameters. Because some parameters come with 4916 security implications, the dependencies also have a mechanism to 4917 reject modifications to parameters on a fine-grained level. 4919 Developing a robust permissions system works in this model too. The 4920 Recipient can use a simple ACL that is a table of Identities and 4921 Component Identifier permissions to ensure that operations on 4922 components fail unless they are permitted by the ACL. This table can 4923 be further refined with individual parameters and commands. 4925 Capability reporting is similarly simplified. A Recipient can report 4926 the Commands, Parameters, Algorithms, and Component Identifiers that 4927 it supports. This is sufficiently precise for a manifest author to 4928 create a manifest that the Recipient can accept. 4930 The simplicity of design in the Recipient due to all of these 4931 benefits allows even a highly constrained platform to use advanced 4932 update capabilities. 4934 C.1. C.1 Design Rationale: Envelope 4936 The Envelope is used instead of a COSE structure for several reasons: 4938 1. This enables the use of Severable Elements (Section 8.8) 4940 2. This enables modular processing of manifests, particularly with 4941 large signatures. 4943 3. This enables multiple authentication schemes. 4945 4. This allows integrity verification by a dependent to be 4946 unaffected by adding or removing authentication structures. 4948 Modular processing is important because it allows a Manifest 4949 Processor to iterate forward over an Envelope, processing Delegation 4950 Chains and Authentication Blocks, retaining only intermediate values, 4951 without any need to seek forward and backwards in a stream until it 4952 gets to the Manifest itself. This allows the use of large, Post- 4953 Quantum signatures without requiring retention of the signature 4954 itself, or seeking forward and back. 4956 Four authentication objects are supported by the Envelope: 4958 - COSE_Sign_Tagged 4960 - COSE_Sign1_Tagged 4962 - COSE_Mac_Tagged 4964 - COSE_Mac0_Tagged 4966 The SUIT Envelope allows an Update Authority or intermediary to mix 4967 and match any number of different authentication blocks it wants 4968 without any concern for modifying the integrity of another 4969 authentication block. This also allows the addition or removal of an 4970 authentication blocks without changing the integrity check of the 4971 Manifest, which is important for dependency handling. See 4972 Section 6.2 4974 C.2. C.2 Byte String Wrappers 4976 Byte string wrappers are used in several places in the suit manifest. 4977 The primary reason for wrappers it to limit the parser extent when 4978 invoked at different times, with a possible loss of context. 4980 The elements of the suit envelope are wrapped both to set the extents 4981 used by the parser and to simplify integrity checks by clearly 4982 defining the length of each element. 4984 The common block is re-parsed in order to find components identifiers 4985 from their indices, to find dependency prefixes and digests from 4986 their identifiers, and to find the common sequence. The common 4987 sequence is wrapped so that it matches other sequences, simplifying 4988 the code path. 4990 A severed SUIT command sequence will appear in the envelope, so it 4991 must be wrapped as with all envelope elements. For consistency, 4992 command sequences are also wrapped in the manifest. This also allows 4993 the parser to discern the difference between a command sequence and a 4994 SUIT_Digest. 4996 Parameters that are structured types (arrays and maps) are also 4997 wrapped in a bstr. This is so that parser extents can be set 4998 correctly using only a reference to the beginning of the parameter. 4999 This enables a parser to store a simple list of references to 5000 parameters that can be retrieved when needed. 5002 Appendix D. D. Implementation Conformance Matrix 5004 This section summarizes the functionality a minimal manifest 5005 processor implementation needs to offer to claim conformance to this 5006 specification, in the absence of an application profile standard 5007 specifying otherwise. 5009 The subsequent table shows the conditions. 5011 +-------------------+------------------+----------------+ 5012 | Name | Reference | Implementation | 5013 +-------------------+------------------+----------------+ 5014 | Vendor Identifier | Section 8.7.5.2 | REQUIRED | 5015 | | | | 5016 | Class Identifier | Section 8.7.5.2 | REQUIRED | 5017 | | | | 5018 | Device Identifier | Section 8.7.5.2 | OPTIONAL | 5019 | | | | 5020 | Image Match | Section 8.7.6.2 | REQUIRED | 5021 | | | | 5022 | Image Not Match | Section 8.7.6.3 | OPTIONAL | 5023 | | | | 5024 | Use Before | Section 8.7.6.4 | OPTIONAL | 5025 | | | | 5026 | Component Slot | Section 8.7.6.5 | OPTIONAL | 5027 | | | | 5028 | Abort | Section 8.7.6.9 | OPTIONAL | 5029 | | | | 5030 | Minimum Battery | Section 8.7.6.6 | OPTIONAL | 5031 | | | | 5032 | Update Authorized | Section 8.7.6.7 | OPTIONAL | 5033 | | | | 5034 | Version | Section 8.7.6.8 | OPTIONAL | 5035 | | | | 5036 | Custom Condition | Section 8.7.6.10 | OPTIONAL | 5037 +-------------------+------------------+----------------+ 5039 The subsequent table shows the directives. 5041 +-------------------+----------------+------------------------------+ 5042 | Name | Reference | Implementation | 5043 +-------------------+----------------+------------------------------+ 5044 | Set Component | Section 8.7.7. | REQUIRED if more than one | 5045 | Index | 1 | component | 5046 | | | | 5047 | Set Dependency | Section 8.7.7. | REQUIRED if dependencies | 5048 | Index | 2 | used | 5049 | | | | 5050 | Try Each | Section 8.7.7. | OPTIONAL | 5051 | | 3 | | 5052 | | | | 5053 | Process | Section 8.7.7. | OPTIONAL | 5054 | Dependency | 4 | | 5055 | | | | 5056 | Set Parameters | Section 8.7.7. | OPTIONAL | 5057 | | 5 | | 5058 | | | | 5059 | Override | Section 8.7.7. | REQUIRED | 5060 | Parameters | 6 | | 5061 | | | | 5062 | Fetch | Section 8.7.7. | REQUIRED for Updater | 5063 | | 7 | | 5064 | | | | 5065 | Copy | Section 8.7.7. | OPTIONAL | 5066 | | 9 | | 5067 | | | | 5068 | Run | Section 8.7.7. | REQUIRED for Bootloader | 5069 | | 10 | | 5070 | | | | 5071 | Wait For Event | Section 8.7.7. | OPTIONAL | 5072 | | 11 | | 5073 | | | | 5074 | Run Sequence | Section 8.7.7. | OPTIONAL | 5075 | | 12 | | 5076 | | | | 5077 | Swap | Section 8.7.7. | OPTIONAL | 5078 | | 13 | | 5079 | | | | 5080 | Fetch URI List | Section 8.7.7. | OPTIONAL | 5081 | | 8 | | 5082 | | | | 5083 | Unlink | Section 8.7.8 | OPTIONAL | 5084 +-------------------+----------------+------------------------------+ 5086 The subsequent table shows the parameters. 5088 +------------------+------------------+----------------------+ 5089 | Name | Reference | Implementation | 5090 +------------------+------------------+----------------------+ 5091 | Vendor ID | Section 8.7.5.3 | REQUIRED | 5092 | | | | 5093 | Class ID | Section 8.7.5.4 | REQUIRED | 5094 | | | | 5095 | Image Digest | Section 8.7.5.6 | REQUIRED | 5096 | | | | 5097 | Image Size | Section 8.7.5.7 | REQUIRED | 5098 | | | | 5099 | Use Before | Section 8.7.5.8 | RECOMMENDED | 5100 | | | | 5101 | Component Slot | Section 8.7.5.9 | OPTIONAL | 5102 | | | | 5103 | Encryption Info | Section 8.7.5.10 | RECOMMENDED | 5104 | | | | 5105 | Compression Info | Section 8.7.5.11 | RECOMMENDED | 5106 | | | | 5107 | Unpack Info | Section 8.7.5.12 | RECOMMENDED | 5108 | | | | 5109 | URI | Section 8.7.5.13 | REQUIRED for Updater | 5110 | | | | 5111 | Source Component | Section 8.7.5.14 | OPTIONAL | 5112 | | | | 5113 | Run Args | Section 8.7.5.15 | OPTIONAL | 5114 | | | | 5115 | Device ID | Section 8.7.5.5 | OPTIONAL | 5116 | | | | 5117 | Minimum Battery | Section 8.7.5.16 | OPTIONAL | 5118 | | | | 5119 | Update Priority | Section 8.7.5.17 | OPTIONAL | 5120 | | | | 5121 | Version Match | Section 8.7.5.18 | OPTIONAL | 5122 | | | | 5123 | Wait Info | Section 8.7.5.19 | OPTIONAL | 5124 | | | | 5125 | URI List | Section 8.7.5.20 | OPTIONAL | 5126 | | | | 5127 | Strict Order | Section 8.7.5.22 | OPTIONAL | 5128 | | | | 5129 | Soft Failure | Section 8.7.5.23 | OPTIONAL | 5130 | | | | 5131 | Custom | Section 8.7.5.24 | OPTIONAL | 5132 +------------------+------------------+----------------------+ 5134 Authors' Addresses 5136 Brendan Moran 5137 Arm Limited 5139 EMail: Brendan.Moran@arm.com 5141 Hannes Tschofenig 5142 Arm Limited 5144 EMail: hannes.tschofenig@arm.com 5146 Henk Birkholz 5147 Fraunhofer SIT 5149 EMail: henk.birkholz@sit.fraunhofer.de 5151 Koen Zandberg 5152 Inria 5154 EMail: koen.zandberg@inria.fr