idnits 2.17.1 draft-ietf-suit-manifest-11.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 (December 08, 2020) is 1235 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 2503 -- Looks like a reference, but probably isn't: '2' on line 2503 -- Looks like a reference, but probably isn't: '3' on line 2474 == Missing Reference: '-1' is mentioned on line 2503, but not defined == Missing Reference: '-2' is mentioned on line 2476, but not defined == Missing Reference: '-3' is mentioned on line 2480, but not defined -- Looks like a reference, but probably isn't: '4' on line 2480 -- Looks like a reference, but probably isn't: '0' on line 2503 ** Obsolete normative reference: RFC 8152 (Obsoleted by RFC 9052, RFC 9053) == Outdated reference: A later version (-08) exists of draft-ietf-cbor-tags-oid-03 == Outdated reference: A later version (-24) exists of draft-ietf-sacm-coswid-16 == Outdated reference: A later version (-16) exists of draft-ietf-suit-architecture-14 == Outdated reference: A later version (-13) exists of draft-ietf-suit-information-model-08 == Outdated reference: A later version (-19) exists of draft-ietf-teep-architecture-13 == Outdated reference: A later version (-06) exists of draft-kucherawy-rfc8478bis-05 Summary: 1 error (**), 0 flaws (~~), 11 warnings (==), 7 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: June 11, 2021 H. Birkholz 6 Fraunhofer SIT 7 K. Zandberg 8 Inria 9 December 08, 2020 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-11 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 June 11, 2021. 43 Copyright Notice 45 Copyright (c) 2020 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 . . . . . . . . . . . . . . . . . . . . . 40 115 8.7.2. suit-common . . . . . . . . . . . . . . . . . . . . . 40 116 8.7.3. SUIT_Command_Sequence . . . . . . . . . . . . . . . . 42 117 8.7.4. Reporting Policy . . . . . . . . . . . . . . . . . . 44 118 8.7.5. SUIT_Parameters . . . . . . . . . . . . . . . . . . . 46 119 8.7.6. SUIT_Condition . . . . . . . . . . . . . . . . . . . 56 120 8.7.7. SUIT_Directive . . . . . . . . . . . . . . . . . . . 60 121 8.7.8. Integrity Check Values . . . . . . . . . . . . . . . 67 122 8.8. Severable Elements . . . . . . . . . . . . . . . . . . . 67 123 9. Access Control Lists . . . . . . . . . . . . . . . . . . . . 68 124 10. SUIT Digest Container . . . . . . . . . . . . . . . . . . . . 69 125 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 69 126 11.1. SUIT Commands . . . . . . . . . . . . . . . . . . . . . 69 127 11.2. SUIT Parameters . . . . . . . . . . . . . . . . . . . . 71 128 11.3. SUIT Text Values . . . . . . . . . . . . . . . . . . . . 73 129 11.4. SUIT Component Text Values . . . . . . . . . . . . . . . 73 130 11.5. SUIT Algorithm Identifiers . . . . . . . . . . . . . . . 73 131 11.5.1. SUIT Digest Algorithm Identifiers . . . . . . . . . 73 132 11.5.2. SUIT Compression Algorithm Identifiers . . . . . . . 74 133 11.5.3. Unpack Algorithms . . . . . . . . . . . . . . . . . 74 134 12. Security Considerations . . . . . . . . . . . . . . . . . . . 75 135 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 75 136 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 75 137 14.1. Normative References . . . . . . . . . . . . . . . . . . 75 138 14.2. Informative References . . . . . . . . . . . . . . . . . 76 139 Appendix A. A. Full CDDL . . . . . . . . . . . . . . . . . . . . 78 140 Appendix B. B. Examples . . . . . . . . . . . . . . . . . . . . 87 141 B.1. Example 0: Secure Boot . . . . . . . . . . . . . . . . . 88 142 B.2. Example 1: Simultaneous Download and Installation of 143 Payload . . . . . . . . . . . . . . . . . . . . . . . . . 90 145 B.3. Example 2: Simultaneous Download, Installation, Secure 146 Boot, Severed Fields . . . . . . . . . . . . . . . . . . 92 147 B.4. Example 3: A/B images . . . . . . . . . . . . . . . . . . 96 148 B.5. Example 4: Load and Decompress from External Storage . . 99 149 B.6. Example 5: Two Images . . . . . . . . . . . . . . . . . . 102 150 Appendix C. C. Design Rational . . . . . . . . . . . . . . . . . 105 151 C.1. C.1 Design Rationale: Envelope . . . . . . . . . . . . . 106 152 C.2. C.2 Byte String Wrappers . . . . . . . . . . . . . . . . 107 153 Appendix D. D. Implementation Conformance Matrix . . . . . . . . 108 154 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 111 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 Section 10 and one 599 or more [RFC8152] CBOR Object Signing and Encryption (COSE) 600 authentication blocks. These blocks are one of: 602 - COSE_Sign_Tagged 604 - COSE_Sign1_Tagged 606 - COSE_Mac_Tagged 608 - COSE_Mac0_Tagged 610 Each of these objects is used in detached payload mode. The payload 611 is the bstr-wrapped SUIT_Digest. 613 See Section 8.4 for more detail. 615 5.4. Manifest 617 The Manifest contains most metadata about one or more images. The 618 Manifest is divided into Critical Metadata, Common Metadata, Command 619 Sequences, and Integrity Check Values. 621 See Section 8.6 for more detail. 623 5.4.1. Critical Metadata 625 Some metadata needs to be accessed before the manifest is processed. 626 This metadata can be used to determine which manifest is newest and 627 whether the structure version is supported. It also MAY provide a 628 URI for obtaining a canonical copy of the manifest and Envelope. 630 See Section 8.6.1, Section 8.6.2, and Section 8.6.3 for more detail. 632 5.4.2. Common 634 Some metadata is used repeatedly and in more than one command 635 sequence. In order to reduce the size of the manifest, this metadata 636 is collected into the Common section. Common is composed of three 637 parts: a list of dependencies, a list of components referenced by the 638 manifest, and a command sequence to execute prior to each other 639 command sequence. The common command sequence is typically used to 640 set commonly used values and perform compatibility checks. The 641 common command sequence MUST NOT have any side-effects outside of 642 setting parameter values. 644 See Section 8.7.2, and Section 8.7.2.1 for more detail. 646 5.4.3. Command Sequences 648 Command sequences provide the instructions that a Recipient requires 649 in order to install or use an image. These sequences tell a device 650 to set parameter values, test system parameters, copy data from one 651 place to another, transform data, digest data, and run code. 653 Command sequences are broken up into three groups: Common Command 654 Sequence (see Section 5.4.2), update commands, and secure boot 655 commands. 657 Update Command Sequences are: Dependency Resolution, Payload Fetch, 658 and Payload Installation. An Update Procedure is the complete set of 659 each Update Command Sequence, each preceded by the Common Command 660 Sequence. 662 Invocation Command Sequences are: System Validation, Image Loading, 663 and Image Invocation. A Invocation Procedure is the complete set of 664 each Invocation Command Sequence, each preceded by the Common Command 665 Sequence. 667 Command Sequences are grouped into these sets to ensure that there is 668 common coordination between dependencies and dependents on when to 669 execute each command. 671 See Section 8.7.3 for more detail. 673 5.4.4. Integrity Check Values 675 To enable Section 5.5, there needs to be a mechanism to verify 676 integrity of any metadata outside the manifest. Integrity Check 677 Values are used to verify the integrity of metadata that is not 678 contained in the manifest. This MAY include Severable Command 679 Sequences, Concise Software Identifiers (CoSWID 680 [I-D.ietf-sacm-coswid]), or Text data. Integrated Dependencies and 681 Integrated Payloads are integrity-checked using Command Sequences, so 682 they do not have Integrity Check Values present in the Manifest. 684 See Section 8.7.8 for more detail. 686 5.4.5. Human-Readable Text 688 Text is typically a Severable Element (Section 5.5). It contains all 689 the text that describes the update. Because text is explicitly for 690 human consumption, it is all grouped together so that it can be 691 Severed easily. The text section has space both for describing the 692 manifest as a whole and for describing each individual component. 694 See Section 8.6.4 for more detail. 696 5.5. Severable Elements 698 Severable Elements are elements of the Envelope (Section 5.1) that 699 have Integrity Check Values (Section 5.4.4) in the Manifest 700 (Section 5.4). 702 Because of this organisation, these elements can be discarded or 703 "Severed" from the Envelope without changing the signature of the 704 Manifest. This allows savings based on the size of the Envelope in 705 several scenarios, for example: 707 - A management system severs the Text and CoSWID sections before 708 sending an Envelope to a constrained Recipient, which saves 709 Recipient bandwidth. 711 - A Recipient severs the Installation section after installing the 712 Update, which saves storage space. 714 See Section 8.8 for more detail. 716 5.6. Integrated Dependencies and Payloads 718 In some cases, it is beneficial to include a dependency or a payload 719 in the Envelope of a manifest. For example: 721 - When an update is delivered via a comparatively unconstrained 722 medium, such as a removable mass storage device, it may be 723 beneficial to bundle updates into single files. 725 - When a manifest requires encryption, it must be referenced as a 726 dependency, so a trivial manifest may be used to enclose the 727 encrypted manifest. The encrypted manifest may be contained in 728 the dependent manifest's envelope. 730 - When a manifest transports a small payload, such as an encrypted 731 key, that payload may be placed in the manifest's envelope. 733 See Section 7.9.1, Section 8.5 for more detail. 735 6. Manifest Processor Behavior 737 This section describes the behavior of the manifest processor and 738 focuses primarily on interpreting commands in the manifest. However, 739 there are several other important behaviors of the manifest 740 processor: encoding version detection, rollback protection, and 741 authenticity verification are chief among these. 743 6.1. Manifest Processor Setup 745 Prior to executing any command sequence, the manifest processor or 746 its host application MUST inspect the manifest version field and fail 747 when it encounters an unsupported encoding version. Next, the 748 manifest processor or its host application MUST extract the manifest 749 sequence number and perform a rollback check using this sequence 750 number. The exact logic of rollback protection may vary by 751 application, but it has the following properties: 753 - Whenever the manifest processor can choose between several 754 manifests, it MUST select the latest valid, authentic manifest. 756 - If the latest valid, authentic manifest fails, it MAY select the 757 next latest valid, authentic manifest, according to application- 758 specific policy. 760 Here, valid means that a manifest has a supported encoding version 761 and it has not been excluded for other reasons. Reasons for 762 excluding typically involve first executing the manifest and may 763 include: 765 - Test failed (e.g. Vendor ID/Class ID). 767 - Unsupported command encountered. 769 - Unsupported parameter encountered. 771 - Unsupported Component Identifier encountered. 773 - Payload not available. 775 - Dependency not available. 777 - Application crashed when executed. 779 - Watchdog timeout occurred. 781 - Dependency or Payload verification failed. 783 - Missing component from a set. 785 - Required parameter not supplied. 787 These failure reasons MAY be combined with retry mechanisms prior to 788 marking a manifest as invalid. 790 Selecting an older manifest in the event of failure of the latest 791 valid manifest is a robustness mechanism that is necessary for 792 supporting the requirements in [I-D.ietf-suit-architecture], section 793 3.5. It may not be appropriate for all applications. In particular 794 Trusted Execution Environments MAY require a failure to invoke a new 795 installation, rather than a rollback approach. See 796 [I-D.ietf-suit-information-model], Section 4.2.1 for more discussion 797 on the security considerations that apply to rollback. 799 Following these initial tests, the manifest processor clears all 800 parameter storage. This ensures that the manifest processor begins 801 without any leaked data. 803 6.2. Required Checks 805 The RECOMMENDED process is to verify the signature of the manifest 806 prior to parsing/executing any section of the manifest. This guards 807 the parser against arbitrary input by unauthenticated third parties, 808 but it costs extra energy when a Recipient receives an incompatible 809 manifest. 811 When validating authenticity of manifests, the manifest processor MAY 812 use an ACL (see Section 9) to determine the extent of the rights 813 conferred by that authenticity. Where a device supports only one 814 level of access, it MAY choose to skip signature verification of 815 dependencies, since they are referenced by digest. Where a device 816 supports more than one trusted party, it MAY choose to defer the 817 verification of signatures of dependencies until the list of affected 818 components is known so that it can skip redundant signature 819 verifications. For example, a dependency signed by the same author 820 as the dependent does not require a signature verification. 821 Similarly, if the signer of the dependent has full rights to the 822 device, according to the ACL, then no signature verification is 823 necessary on the dependency. 825 Once a valid, authentic manifest has been selected, the manifest 826 processor MUST examine the component list and verify that its maximum 827 number of components is not exceeded and that each listed component 828 is supported. 830 For each listed component, the manifest processor MUST provide 831 storage for the supported parameters. If the manifest processor does 832 not have sufficient temporary storage to process the parameters for 833 all components, it MAY process components serially for each command 834 sequence. See Section 6.6 for more details. 836 The manifest processor SHOULD check that the common sequence contains 837 at least Check Vendor Identifier command and at least one Check Class 838 Identifier command. 840 Because the common sequence contains Check Vendor Identifier and 841 Check Class Identifier command(s), no custom commands are permitted 842 in the common sequence. This ensures that any custom commands are 843 only executed by devices that understand them. 845 If the manifest contains more than one component and/or dependency, 846 each command sequence MUST begin with a Set Component Index or Set 847 Dependency Index command. 849 If a dependency is specified, then the manifest processor MUST 850 perform the following checks: 852 1. At the beginning of each section in the dependent: all previous 853 sections of each dependency have been executed. 855 2. At the end of each section in the dependent: The corresponding 856 section in each dependency has been executed. 858 If the interpreter does not support dependencies and a manifest 859 specifies a dependency, then the interpreter MUST reject the 860 manifest. 862 If a Recipient supports groups of interdependent components (a 863 Component Set), then it SHOULD verify that all Components in the 864 Component Set are specified by one update, that is: a single manifest 865 and all its dependencies that together: 867 1. have sufficient permissions imparted by their signatures 869 2. specify a digest and a payload for every Component in the 870 Component Set. 872 The single dependent manifest is sometimes called a Root Manifest. 874 6.2.1. Minimizing Signature Verifications 876 Signature verification can be energy and time expensive on a 877 constrained device. MAC verification is typically unaffected by 878 these concerns. A Recipient MAY choose to parse and execute only the 879 SUIT_Common section of the manifest prior to signature verification, 880 if all of the below apply: 882 - The Authentication Block contains a COSE_Sign_Tagged or 883 COSE_Sign1_Tagged 885 - The Recipient receives manifests over an unauthenticated channel, 886 exposing it to more inauthentic or incompatible manifests, and 888 - The Recipient has a power budget that makes signature verification 889 undesirable 891 The guidelines in Creating Manifests (Section 7) require that the 892 common section contains the applicability checks, so this section is 893 sufficient for applicability verification. The parser MUST restrict 894 acceptable commands to conditions and the following directives: 895 Override Parameters, Set Parameters, Try Each, and Run Sequence ONLY. 896 The manifest parser MUST NOT execute any command with side-effects 897 outside the parser (for example, Run, Copy, Swap, or Fetch commands) 898 prior to authentication and any such command MUST Abort. The Common 899 Sequence MUST be executed again in its entirety after authenticity 900 validation. 902 When executing Common prior to authenticity validation, the Manifest 903 Processor MUST evaluate the integrity of the manifest using the 904 SUIT_Digest present in the authentication block. 906 Alternatively, a Recipient MAY rely on network infrastructure to 907 filter inapplicable manifests. 909 6.3. Interpreter Fundamental Properties 911 The interpreter has a small set of design goals: 913 1. Executing an update MUST either result in an error, or a 914 verifiably correct system state. 916 2. Executing a Trusted Invocation MUST either result in an error, or 917 an invoked image. 919 3. Executing the same manifest on multiple Recipients MUST result in 920 the same system state. 922 NOTE: when using A/B images, the manifest functions as two (or more) 923 logical manifests, each of which applies to a system in a particular 924 starting state. With that provision, design goal 3 holds. 926 6.4. Abstract Machine Description 928 The heart of the manifest is the list of commands, which are 929 processed by a Manifest Processor-a form of interpreter. This 930 Manifest Processor can be modeled as a simple abstract machine. This 931 machine consists of several data storage locations that are modified 932 by commands. 934 There are two types of commands, namely those that modify state 935 (directives) and those that perform tests (conditions). Parameters 936 are used as the inputs to commands. Some directives offer control 937 flow operations. Directives target a specific component or 938 dependency. A dependency is another SUIT_Envelope that describes 939 additional components. Dependencies are identified by digest, but 940 referenced in commands by Dependency Index, the index into the array 941 of Dependencies. A component is a unit of code or data that can be 942 targeted by an update. Components are identified by Component 943 Identifiers, but referenced in commands by Component Index; Component 944 Identifiers are arrays of binary strings and a Component Index is an 945 index into the array of Component Identifiers. 947 Conditions MUST NOT have any side-effects other than informing the 948 interpreter of success or failure. The Interpreter does not Abort if 949 the Soft Failure flag (Section 8.7.5.23) is set when a Condition 950 reports failure. 952 Directives MAY have side-effects in the parameter table, the 953 interpreter state, or the current component. The Interpreter MUST 954 Abort if a Directive reports failure regardless of the Soft Failure 955 flag. 957 To simplify the logic describing the command semantics, the object 958 "current" is used. It represents the component identified by the 959 Component Index or the dependency identified by the Dependency Index: 961 current := components\[component-index\] 962 if component-index is not false 963 else dependencies\[dependency-index\] 965 As a result, Set Component Index is described as current := 966 components[arg]. The actual operation performed for Set Component 967 Index is described by the following pseudocode, however, because of 968 the definition of current (above), these are semantically equivalent. 970 component-index := arg 971 dependency-index := false 973 Similarly, Set Dependency Index is semantically equivalent to current 974 := dependencies[arg] 976 The following table describes the behavior of each command. "params" 977 represents the parameters for the current component or dependency. 978 Most commands operate on either a component or a dependency. Setting 979 the Component Index clears the Dependency Index. Setting the 980 Dependency Index clears the Component Index. 982 +-------------------+-----------------------------------------------+ 983 | Command Name | Semantic of the Operation | 984 +-------------------+-----------------------------------------------+ 985 | Check Vendor | assert(binary-match(current, | 986 | Identifier | current.params[vendor-id])) | 987 | | | 988 | Check Class | assert(binary-match(current, | 989 | Identifier | current.params[class-id])) | 990 | | | 991 | Verify Image | assert(binary-match(digest(current), | 992 | | current.params[digest])) | 993 | | | 994 | Set Component | current := components[arg] | 995 | Index | | 996 | | | 997 | Override | current.params[k] := v for-each k,v in arg | 998 | Parameters | | 999 | | | 1000 | Set Dependency | current := dependencies[arg] | 1001 | Index | | 1002 | | | 1003 | Set Parameters | current.params[k] := v if not k in params | 1004 | | for-each k,v in arg | 1005 | | | 1006 | Process | exec(current[common]); exec(current[current- | 1007 | Dependency | segment]) | 1008 | | | 1009 | Run | run(current) | 1010 | | | 1011 | Fetch | store(current, fetch(current.params[uri])) | 1012 | | | 1013 | Use Before | assert(now() < arg) | 1014 | | | 1015 | Check Component | assert(offsetof(current) == arg) | 1016 | Offset | | 1017 | | | 1018 | Check Device | assert(binary-match(current, | 1019 | Identifier | current.params[device-id])) | 1020 | | | 1021 | Check Image Not | assert(not binary-match(digest(current), | 1022 | Match | current.params[digest])) | 1023 | | | 1024 | Check Minimum | assert(battery >= arg) | 1025 | Battery | | 1026 | | | 1027 | Check Update | assert(isAuthorized()) | 1028 | Authorized | | 1029 | | | 1030 | Check Version | assert(version_check(current, arg)) | 1031 | | | 1032 | Abort | assert(0) | 1033 | | | 1034 | Try Each | try-each-done if exec(seq) is not error for- | 1035 | | each seq in arg | 1036 | | | 1037 | Copy | store(current, current.params[src-component]) | 1038 | | | 1039 | Swap | swap(current, current.params[src-component]) | 1040 | | | 1041 | Wait For Event | until event(arg), wait | 1042 | | | 1043 | Run Sequence | exec(arg) | 1044 | | | 1045 | Run with | run(current, arg) | 1046 | Arguments | | 1047 +-------------------+-----------------------------------------------+ 1049 6.5. Special Cases of Component Index and Dependency Index 1051 Component Index and Dependency Index can each take on one of three 1052 types: 1054 1. Integer 1056 2. Array of integers 1058 3. True 1060 Integers MUST always be supported by Set Component Index and Set 1061 Dependency Index. Arrays of integers MUST be supported by Set 1062 Component Index and Set Dependency Index if the Recipient supports 3 1063 or more components or 3 or more dependencies, respectively. True 1064 MUST be supported by Set Component Index and Set Dependency Index if 1065 the Recipient supports 2 or more components or 2 or more 1066 dependencies, respectively. Each of these operates on the list of 1067 components or list of dependencies declared in the manifest. 1069 Integer indices are the default case as described in the previous 1070 section. An array of integers represents a list of the components 1071 (Set Component Index) or a list of dependencies (Set Dependency 1072 Index) to which each subsequent command applies. The value True 1073 replaces the list of component indices or dependency indices with the 1074 full list of components or the full list of dependencies, 1075 respectively, as defined in the manifest. 1077 When a command is executed, it either 1. operates on the component or 1078 dependency identified by the component index or dependency index if 1079 that index is an integer, or 2. it operates on each component or 1080 dependency identified by an array of indicies, or 3. it operates on 1081 every component or every dependency if the index is the boolean True. 1082 This is described by the following pseudocode: 1084 if component-index is true: 1085 current-list = components 1086 else if component-index is array: 1087 current-list = [ components[idx] for idx in component-index ] 1088 else if component-index is integer: 1089 current-list = [ components[component-index] ] 1090 else if dependency-index is true: 1091 current-list = dependencies 1092 else if dependency-index is array: 1093 current-list = [ dependencies[idx] for idx in dependency-index ] 1094 else: 1095 current-list = [ dependencies[dependency-index] ] 1096 for current in current-list: 1097 cmd(current) 1099 Try Each and Run Sequence are affected in the same way as other 1100 commands: they are invoked once for each possible Component or 1101 Dependency. This means that the sequences that are arguments to Try 1102 Each and Run Sequence are NOT invoked with Component Index = True or 1103 Dependency Index = True, nor are they invoked with array indices. 1104 They are only invoked with integer indices. The interpreter loops 1105 over the whole sequence, setting the Component Index or Dependency 1106 Index to each index in turn. 1108 6.6. Serialized Processing Interpreter 1110 In highly constrained devices, where storage for parameters is 1111 limited, the manifest processor MAY handle one component at a time, 1112 traversing the manifest tree once for each listed component. In this 1113 mode, the interpreter ignores any commands executed while the 1114 component index is not the current component. This reduces the 1115 overall volatile storage required to process the update so that the 1116 only limit on number of components is the size of the manifest. 1117 However, this approach requires additional processing power. 1119 In order to operate in this mode, the manifest processor loops on 1120 each section for every supported component, simply ignoring commands 1121 when the current component is not selected. 1123 When a serialized Manifest Processor encounters a component or 1124 dependency index of True, it does not ignore any commands. It 1125 applies them to the current component or dependency on each 1126 iteration. 1128 6.7. Parallel Processing Interpreter 1130 Advanced Recipients MAY make use of the Strict Order parameter and 1131 enable parallel processing of some Command Sequences, or it may 1132 reorder some Command Sequences. To perform parallel processing, once 1133 the Strict Order parameter is set to False, the Recipient may issue 1134 each or every command concurrently until the Strict Order parameter 1135 is returned to True or the Command Sequence ends. Then, it waits for 1136 all issued commands to complete before continuing processing of 1137 commands. To perform out-of-order processing, a similar approach is 1138 used, except the Recipient consumes all commands after the Strict 1139 Order parameter is set to False, then it sorts these commands into 1140 its preferred order, invokes them all, then continues processing. 1142 Under each of these scenarios the parallel processing MUST halt until 1143 all issued commands have completed: 1145 - Set Parameters. 1147 - Override Parameters. 1149 - Set Strict Order = True. 1151 - Set Dependency Index. 1153 - Set Component Index. 1155 To perform more useful parallel operations, a manifest author may 1156 collect sequences of commands in a Run Sequence command. Then, each 1157 of these sequences MAY be run in parallel. Each sequence defaults to 1158 Strict Order = True. To isolate each sequence from each other 1159 sequence, each sequence MUST begin with a Set Component Index or Set 1160 Dependency Index directive with the following exception: when the 1161 index is either True or an array of indices, the Set Component Index 1162 or Set Dependency Index is implied. Any further Set Component Index 1163 directives MUST cause an Abort. This allows the interpreter that 1164 issues Run Sequence commands to check that the first element is 1165 correct, then issue the sequence to a parallel execution context to 1166 handle the remainder of the sequence. 1168 6.8. Processing Dependencies 1170 As described in Section 6.2, each manifest must invoke each of its 1171 dependencies sections from the corresponding section of the 1172 dependent. Any changes made to parameters by the dependency persist 1173 in the dependent. 1175 When a Process Dependency command is encountered, the interpreter 1176 loads the dependency identified by the Current Dependency Index. The 1177 interpreter first executes the common-sequence section of the 1178 identified dependency, then it executes the section of the dependency 1179 that corresponds to the currently executing section of the dependent. 1181 If the specified dependency does not contain the current section, 1182 Process Dependency succeeds immediately. 1184 The Manifest Processor MUST also support a Dependency Index of True, 1185 which applies to every dependency, as described in Section 6.5 1187 The interpreter also performs the checks described in Section 6.2 to 1188 ensure that the dependent is processing the dependency correctly. 1190 6.9. Multiple Manifest Processors 1192 When a system has multiple security domains, each domain might 1193 require independent verification of authenticity or security 1194 policies. Security domains might be divided by separation technology 1195 such as Arm TrustZone, Intel SGX, or another TEE technology. 1196 Security domains might also be divided into separate processors and 1197 memory spaces, with a communication interface between them. 1199 For example, an application processor may have an attached 1200 communications module that contains a processor. The communications 1201 module might require metadata signed by a specific Trust Authority 1202 for regulatory approval. This may be a different Trust Authority 1203 than the application processor. 1205 When there are two or more security domains (see 1206 [I-D.ietf-teep-architecture]), a manifest processor might be required 1207 in each. The first manifest processor is the normal manifest 1208 processor as described for the Recipient in Section 6.4. The second 1209 manifest processor only executes sections when the first manifest 1210 processor requests it. An API interface is provided from the second 1211 manifest processor to the first. This allows the first manifest 1212 processor to request a limited set of operations from the second. 1213 These operations are limited to: setting parameters, inserting an 1214 Envelope, invoking a Manifest Command Sequence. The second manifest 1215 processor declares a prefix to the first, which tells the first 1216 manifest processor when it should delegate to the second. These 1217 rules are enforced by underlying separation of privilege 1218 infrastructure, such as TEEs, or physical separation. 1220 When the first manifest processor encounters a dependency prefix, 1221 that informs the first manifest processor that it should provide the 1222 second manifest processor with the corresponding dependency Envelope. 1224 This is done when the dependency is fetched. The second manifest 1225 processor immediately verifies any authentication information in the 1226 dependency Envelope. When a parameter is set for any component that 1227 matches the prefix, this parameter setting is passed to the second 1228 manifest processor via an API. As the first manifest processor works 1229 through the Procedure (set of command sequences) it is executing, 1230 each time it sees a Process Dependency command that is associated 1231 with the prefix declared by the second manifest processor, it uses 1232 the API to ask the second manifest processor to invoke that 1233 dependency section instead. 1235 This mechanism ensures that the two or more manifest processors do 1236 not need to trust each other, except in a very limited case. When 1237 parameter setting across security domains is used, it must be very 1238 carefully considered. Only parameters that do not have an effect on 1239 security properties should be allowed. The dependency manifest MAY 1240 control which parameters are allowed to be set by using the Override 1241 Parameters directive. The second manifest processor MAY also control 1242 which parameters may be set by the first manifest processor by means 1243 of an ACL that lists the allowed parameters. For example, a URI may 1244 be set by a dependent without a substantial impact on the security 1245 properties of the manifest. 1247 7. Creating Manifests 1249 Manifests are created using tools for constructing COSE structures, 1250 calculating cryptographic values and compiling desired system state 1251 into a sequence of operations required to achieve that state. The 1252 process of constructing COSE structures and the calculation of 1253 cryptographic values is covered in [RFC8152]. 1255 Compiling desired system state into a sequence of operations can be 1256 accomplished in many ways. Several templates are provided below to 1257 cover common use-cases. These templates can be combined to produce 1258 more complex behavior. 1260 The author MUST ensure that all parameters consumed by a command are 1261 set prior to invoking that command. Where Component Index = True or 1262 Dependency Index = True, this means that the parameters consumed by 1263 each command MUST have been set for each Component or Dependency, 1264 respectively. 1266 This section details a set of templates for creating manifests. 1267 These templates explain which parameters, commands, and orders of 1268 commands are necessary to achieve a stated goal. 1270 NOTE: On systems that support only a single component and no 1271 dependencies, Set Component Index has no effect and can be omitted. 1273 NOTE: *A digest MUST always be set using Override Parameters, since 1274 this prevents a less-privileged dependent from replacing the digest.* 1276 7.1. Compatibility Check Template 1278 The goal of the compatibility check template ensure that Recipients 1279 only install compatible images. 1281 In this template all information is contained in the common sequence 1282 and the following sequence of commands is used: 1284 - Set Component Index directive (see Section 8.7.7.1) 1286 - Set Parameters directive (see Section 8.7.7.5) for Vendor ID and 1287 Class ID (see Section 8.7.5) 1289 - Check Vendor Identifier condition (see Section 8.7.5.2) 1291 - Check Class Identifier condition (see Section 8.7.5.2) 1293 7.2. Trusted Invocation Template 1295 The goal of the Trusted Invocation template is to ensure that only 1296 authorized code is invoked; such as in Secure Boot or when a Trusted 1297 Application is loaded into a TEE. 1299 The following commands are placed into the common sequence: 1301 - Set Component Index directive (see Section 8.7.7.1) 1303 - Override Parameters directive (see Section 8.7.7.6) for Image 1304 Digest and Image Size (see Section 8.7.5) 1306 Then, the run sequence contains the following commands: 1308 - Set Component Index directive (see Section 8.7.7.1) 1310 - Check Image Match condition (see Section 8.7.6.2) 1312 - Run directive (see Section 8.7.7.12) 1314 7.3. Component Download Template 1316 The goal of the Component Download template is to acquire and store 1317 an image. 1319 The following commands are placed into the common sequence: 1321 - Set Component Index directive (see Section 8.7.7.1) 1323 - Override Parameters directive (see Section 8.7.7.6) for Image 1324 Digest and Image Size (see Section 8.7.5) 1326 Then, the install sequence contains the following commands: 1328 - Set Component Index directive (see Section 8.7.7.1) 1330 - Set Parameters directive (see Section 8.7.7.5) for URI (see 1331 Section 8.7.5.13) 1333 - Fetch directive (see Section 8.7.7.7) 1335 - Check Image Match condition (see Section 8.7.6.2) 1337 The Fetch directive needs the URI parameter to be set to determine 1338 where the image is retrieved from. Additionally, the destination of 1339 where the component shall be stored has to be configured. The URI is 1340 configured via the Set Parameters directive while the destination is 1341 configured via the Set Component Index directive. 1343 Optionally, the Set Parameters directive in the install sequence MAY 1344 also contain Encryption Info (see Section 8.7.5.10), Compression Info 1345 (see Section 8.7.5.11), or Unpack Info (see Section 8.7.5.12) to 1346 perform simultaneous download and decryption, decompression, or 1347 unpacking, respectively. 1349 7.4. Install Template 1351 The goal of the Install template is to use an image already stored in 1352 an identified component to copy into a second component. 1354 This template is typically used with the Component Download template, 1355 however a modification to that template is required: the Component 1356 Download operations are moved from the Payload Install sequence to 1357 the Payload Fetch sequence. 1359 Then, the install sequence contains the following commands: 1361 - Set Component Index directive (see Section 8.7.7.1) 1363 - Set Parameters directive (see Section 8.7.7.5) for Source 1364 Component (see Section 8.7.5.14) 1366 - Copy directive (see Section 8.7.7.9) 1368 - Check Image Match condition (see Section 8.7.6.2) 1370 7.5. Install and Transform Template 1372 The goal of the Install and Transform template is to use an image 1373 already stored in an identified component to decompress, decrypt, or 1374 unpack at time of installation. 1376 This template is typically used with the Component Download template, 1377 however a modification to that template is required: all Component 1378 Download operations are moved from the common sequence and the 1379 install sequence to the fetch sequence. The Component Download 1380 template targets a download component identifier, while the Install 1381 and Transform template uses an install component identifier. In- 1382 place unpacking, decompression, and decryption is complex and 1383 vulnerable to power failure. Therefore, these identifiers SHOULD be 1384 different; in-place installation SHOULD NOT be used without 1385 establishing guarantees of robustness to power failure. 1387 The following commands are placed into the common sequence: 1389 - Set Component Index directive for install component identifier 1390 (see Section 8.7.7.1) 1392 - Override Parameters directive (see Section 8.7.7.6) for Image 1393 Digest and Image Size (see Section 8.7.5) 1395 Then, the install sequence contains the following commands: 1397 - Set Component Index directive for install component identifier 1398 (see Section 8.7.7.1) 1400 - Set Parameters directive (see Section 8.7.7.5) for: 1402 o Source Component for download component identifier (see 1403 Section 8.7.5.14) 1405 o Encryption Info (see Section 8.7.5.10) 1407 o Compression Info (see Section 8.7.5.11) 1409 o Unpack Info (see Section 8.7.5.12) 1411 - Copy directive (see Section 8.7.7.9) 1413 - Check Image Match condition (see Section 8.7.6.2) 1415 7.6. Integrated Payload Template 1417 The goal of the Integrated Payload template is to install a payload 1418 that is included in the manifest envelope. It is identical to the 1419 Component Download template (Section 7.3) except that it places an 1420 added restriction on the URI passed to the Set Parameters directive. 1422 An implementer MAY choose to place a payload in the envelope of a 1423 manifest. The payload envelope key MAY be a positive or negative 1424 integer. The payload envelope key MUST NOT be a value between 0 and 1425 24 and it MUST NOT be used by any other envelope element in the 1426 manifest. The payload MUST be serialized in a bstr element. 1428 The URI for a payload enclosed in this way MUST be expressed as a 1429 fragment-only reference, as defined in [RFC3986], Section 4.4. The 1430 fragment identifier is the stringified envelope key of the payload. 1431 For example, an envelope that contains a payload a key 42 would use a 1432 URI "#42", key -73 would use a URI "#-73". 1434 7.7. Load from Nonvolatile Storage Template 1436 The goal of the Load from Nonvolatile Storage template is to load an 1437 image from a non-volatile component into a volatile component, for 1438 example loading a firmware image from external Flash into RAM. 1440 The following commands are placed into the load sequence: 1442 - Set Component Index directive (see Section 8.7.7.1) 1444 - Set Parameters directive (see Section 8.7.7.5) for Component Index 1445 (see Section 8.7.5) 1447 - Copy directive (see Section 8.7.7.9) 1449 As outlined in Section 6.4, the Copy directive needs a source and a 1450 destination to be configured. The source is configured via Component 1451 Index (with the Set Parameters directive) and the destination is 1452 configured via the Set Component Index directive. 1454 7.8. Load & Decompress from Nonvolatile Storage Template 1456 The goal of the Load & Decompress from Nonvolatile Storage template 1457 is to load an image from a non-volatile component into a volatile 1458 component, decompressing on-the-fly, for example loading a firmware 1459 image from external Flash into RAM. 1461 The following commands are placed into the load sequence: 1463 - Set Component Index directive (see Section 8.7.7.1) 1465 - Set Parameters directive (see Section 8.7.7.5) for Source 1466 Component Index and Compression Info (see Section 8.7.5) 1468 - Copy directive (see Section 8.7.7.9) 1470 This template is similar to Section 7.7 but additionally performs 1471 decompression. Hence, the only difference is in setting the 1472 Compression Info parameter. 1474 This template can be modified for decryption or unpacking by adding 1475 Decryption Info or Unpack Info to the Set Parameters directive. 1477 7.9. Dependency Template 1479 The goal of the Dependency template is to obtain, verify, and process 1480 a dependency manifest as appropriate. 1482 The following commands are placed into the dependency resolution 1483 sequence: 1485 - Set Dependency Index directive (see Section 8.7.7.2) 1487 - Set Parameters directive (see Section 8.7.7.5) for URI (see 1488 Section 8.7.5) 1490 - Fetch directive (see Section 8.7.7.7) 1492 - Check Image Match condition (see Section 8.7.6.2) 1494 - Process Dependency directive (see Section 8.7.7.4) 1496 Then, the validate sequence contains the following operations: 1498 - Set Dependency Index directive (see Section 8.7.7.2) 1500 - Check Image Match condition (see Section 8.7.6.2) 1502 - Process Dependency directive (see Section 8.7.7.4) 1504 NOTE: Any changes made to parameters in a dependency persist in the 1505 dependent. 1507 7.9.1. Composite Manifests 1509 An implementer MAY choose to place a dependency's envelope in the 1510 envelope of its dependent. The dependent envelope key for the 1511 dependency envelope MUST NOT be a value between 0 and 24 and it MUST 1512 NOT be used by any other envelope element in the dependent manifest. 1514 The URI for a dependency enclosed in this way MUST be expressed as a 1515 fragment-only reference, as defined in [RFC3986], Section 4.4. The 1516 fragment identifier is the stringified envelope key of the 1517 dependency. For example, an envelope that contains a dependency at 1518 key 42 would use a URI "#42", key -73 would use a URI "#-73". 1520 7.10. Encrypted Manifest Template 1522 The goal of the Encrypted Manifest template is to fetch and decrypt a 1523 manifest so that it can be used as a dependency. To use an encrypted 1524 manifest, create a plaintext dependent, and add the encrypted 1525 manifest as a dependency. The dependent can include very little 1526 information. 1528 The following operations are placed into the dependency resolution 1529 block: 1531 - Set Dependency Index directive (see Section 8.7.7.2) 1533 - Set Parameters directive (see Section 8.7.7.5) for 1535 o URI (see Section 8.7.5) 1537 o Encryption Info (see Section 8.7.5) 1539 - Fetch directive (see Section 8.7.7.7) 1541 - Check Image Match condition (see Section 8.7.6.2) 1543 - Process Dependency directive (see Section 8.7.7.4) 1545 Then, the validate block contains the following operations: 1547 - Set Dependency Index directive (see Section 8.7.7.2) 1549 - Check Image Match condition (see Section 8.7.6.2) 1551 - Process Dependency directive (see Section 8.7.7.4) 1553 A plaintext manifest and its encrypted dependency may also form a 1554 composite manifest (Section 7.9.1). 1556 7.11. A/B Image Template 1558 The goal of the A/B Image Template is to acquire, validate, and 1559 invoke one of two images, based on a test. 1561 The following commands are placed in the common block: 1563 - Set Component Index directive (see Section 8.7.7.1) 1565 - Try Each 1567 o First Sequence: 1569 * Override Parameters directive (see Section 8.7.7.6, 1570 Section 8.7.5) for Offset A 1572 * Check Offset Condition (see Section 8.7.6.5) 1574 * Override Parameters directive (see Section 8.7.7.6) for 1575 Image Digest A and Image Size A (see Section 8.7.5) 1577 o Second Sequence: 1579 * Override Parameters directive (see Section 8.7.7.6, 1580 Section 8.7.5) for Offset B 1582 * Check Offset Condition (see Section 8.7.6.5) 1584 * Override Parameters directive (see Section 8.7.7.6) for 1585 Image Digest B and Image Size B (see Section 8.7.5) 1587 The following commands are placed in the fetch block or install block 1589 - Set Component Index directive (see Section 8.7.7.1) 1591 - Try Each 1593 o First Sequence: 1595 * Override Parameters directive (see Section 8.7.7.6, 1596 Section 8.7.5) for Offset A 1598 * Check Offset Condition (see Section 8.7.6.5) 1600 * Set Parameters directive (see Section 8.7.7.6) for URI A 1601 (see Section 8.7.5) 1603 o Second Sequence: 1605 * Override Parameters directive (see Section 8.7.7.6, 1606 Section 8.7.5) for Offset B 1608 * Check Offset Condition (see Section 8.7.6.5) 1610 * Set Parameters directive (see Section 8.7.7.6) for URI B 1611 (see Section 8.7.5) 1613 - Fetch 1615 If Trusted Invocation (Section 7.2) is used, only the run sequence is 1616 added to this template, since the common sequence is populated by 1617 this template. 1619 NOTE: Any test can be used to select between images, Check Offset 1620 Condition is used in this template because it is a typical test for 1621 execute-in-place devices. 1623 8. Metadata Structure 1625 The metadata for SUIT updates is composed of several primary 1626 constituent parts: the Envelope, Delegation Chains, Authentication 1627 Information, Manifest, and Severable Elements. 1629 For a diagram of the metadata structure, see Section 5. 1631 8.1. Encoding Considerations 1633 The map indices in the envelope encoding are reset to 1 for each map 1634 within the structure. This is to keep the indices as small as 1635 possible. The goal is to keep the index objects to single bytes 1636 (CBOR positive integers 1-23). 1638 Wherever enumerations are used, they are started at 1. This allows 1639 detection of several common software errors that are caused by 1640 uninitialized variables. Positive numbers in enumerations are 1641 reserved for IANA registration. Negative numbers are used to 1642 identify application-specific values, as described in Section 11. 1644 All elements of the envelope must be wrapped in a bstr to minimize 1645 the complexity of the code that evaluates the cryptographic integrity 1646 of the element and to ensure correct serialization for integrity and 1647 authenticity checks. 1649 8.2. Envelope 1651 The Envelope contains each of the other primary constituent parts of 1652 the SUIT metadata. It allows for modular processing of the manifest 1653 by ordering components in the expected order of processing. 1655 The Envelope is encoded as a CBOR Map. Each element of the Envelope 1656 is enclosed in a bstr, which allows computation of a message digest 1657 against known bounds. 1659 8.3. Delegation Chains 1661 The suit-delegation element MAY carry one or more CBOR Web Tokens 1662 (CWTs) [RFC8392], with [RFC8747] cnf claims. They can be used to 1663 perform enhanced authorization decisions. The CWTs are arranged into 1664 a list of lists. Each list starts with a CWT authorized by a Trust 1665 Anchor, and finishes with a key used to authenticate the Manifest 1666 (see Section 8.4). This allows an Update Authority to delegate from 1667 a long term Trust Anchor, down through intermediaries, to a delegate 1668 without any out-of-band provisioning of Trust Anchors or intermediary 1669 keys. 1671 A Recipient MAY choose to cache intermediaries and/or delegates. If 1672 an Update Distributor knows that a targeted Recipient has cached some 1673 intermediaries or delegates, it MAY choose to strip any cached 1674 intermediaries or delegates from the Delegation Chains in order to 1675 reduce bandwidth and energy. 1677 8.4. Authenticated Manifests 1679 The suit-authentication-wrapper contains a list containing a 1680 Section 10 and one or more cryptographic authentication wrappers for 1681 the Manifest. These are implemented as COSE_Mac_Tagged or 1682 COSE_Sign_Tagged blocks. Each of these blocks contains a SUIT_Digest 1683 of the Manifest. This enables modular processing of the manifest. 1684 The COSE_Mac_Tagged and COSE_Sign_Tagged blocks are described in RFC 1685 8152 [RFC8152]. The suit-authentication-wrapper MUST come before any 1686 element in the SUIT_Envelope, except for the OPTIONAL suit- 1687 delegation, regardless of canonical encoding of CBOR. All validators 1688 MUST reject any SUIT_Envelope that begins with any element other than 1689 a suit-authentication-wrapper or suit-delegation. 1691 A SUIT_Envelope that has not had authentication information added 1692 MUST still contain the suit-authentication-wrapper element, but the 1693 content MUST be a list containing only the SUIT_Digest. 1695 A signing application MUST verify the suit-manifest element against 1696 the SUIT_Digest prior to signing. 1698 8.5. Encrypted Manifests 1700 To use an encrypted manifest, it must be a dependency of a plaintext 1701 manifest. This allows fine-grained control of what information is 1702 accessible to intermediate systems for the purposes of management, 1703 while still preserving the confidentiality of the manifest contents. 1704 This also means that a Recipient can process an encrypted manifest in 1705 the same way as an encrypted payload, allowing code reuse. 1707 A template for using an encrypted manifest is covered in Encrypted 1708 Manifest Template (Section 7.10). 1710 8.6. Manifest 1712 The manifest contains: 1714 - a version number (see Section 8.6.1) 1716 - a sequence number (see Section 8.6.2) 1718 - a reference URI (see Section 8.6.3) 1720 - a common structure with information that is shared between command 1721 sequences (see Section 8.7.2) 1723 - one or more lists of commands that the Recipient should perform 1724 (see Section 8.7.3) 1726 - a reference to the full manifest (see Section 8.6.3) 1728 - human-readable text describing the manifest found in the 1729 SUIT_Envelope (see Section 8.6.4) 1731 - a Concise Software Identifier (CoSWID) found in the SUIT_Envelope 1732 (see Section 8.7.1) 1734 The CoSWID, Text section, or any Command Sequence of the Update 1735 Procedure (Dependency Resolution, Image Fetch, Image Installation) 1736 can be either a CBOR structure or a SUIT_Digest. In each of these 1737 cases, the SUIT_Digest provides for a severable element. Severable 1738 elements are RECOMMENDED to implement. In particular, the human- 1739 readable text SHOULD be severable, since most useful text elements 1740 occupy more space than a SUIT_Digest, but are not needed by the 1741 Recipient. Because SUIT_Digest is a CBOR Array and each severable 1742 element is a CBOR bstr, it is straight-forward for a Recipient to 1743 determine whether an element has been severed. The key used for a 1744 severable element is the same in the SUIT_Manifest and in the 1745 SUIT_Envelope so that a Recipient can easily identify the correct 1746 data in the envelope. See Section 8.7.8 for more detail. 1748 8.6.1. suit-manifest-version 1750 The suit-manifest-version indicates the version of serialization used 1751 to encode the manifest. Version 1 is the version described in this 1752 document. suit-manifest-version is REQUIRED to implement. 1754 8.6.2. suit-manifest-sequence-number 1756 The suit-manifest-sequence-number is a monotonically increasing anti- 1757 rollback counter. It also helps Recipients to determine which in a 1758 set of manifests is the "root" manifest in a given update. Each 1759 manifest MUST have a sequence number higher than each of its 1760 dependencies. Each Recipient MUST reject any manifest that has a 1761 sequence number lower than its current sequence number. For 1762 convenience, an implementer MAY use a UTC timestamp in seconds as the 1763 sequence number. suit-manifest-sequence-number is REQUIRED to 1764 implement. 1766 8.6.3. suit-reference-uri 1768 suit-reference-uri is a text string that encodes a URI where a full 1769 version of this manifest can be found. This is convenient for 1770 allowing management systems to show the severed elements of a 1771 manifest when this URI is reported by a Recipient after installation. 1773 8.6.4. suit-text 1775 suit-text SHOULD be a severable element. suit-text is a map 1776 containing two different types of pair: 1778 - integer => text 1780 - SUIT_Component_Identifier => map 1782 Each SUIT_Component_Identifier => map entry contains a map of integer 1783 => text values. All SUIT_Component_Identifiers present in suit-text 1784 MUST also be present in suit-common (Section 8.7.2) or the suit- 1785 common of a dependency. 1787 suit-text contains all the human-readable information that describes 1788 any and all parts of the manifest, its payload(s) and its 1789 resource(s). The text section is typically severable, allowing 1790 manifests to be distributed without the text, since end-nodes do not 1791 require text. The meaning of each field is described below. 1793 Each section MAY be present. If present, each section MUST be as 1794 described. Negative integer IDs are reserved for application- 1795 specific text values. 1797 The following table describes the text fields available in suit-text: 1799 +--------------------------------+----------------------------------+ 1800 | CDDL Structure | Description | 1801 +--------------------------------+----------------------------------+ 1802 | suit-text-manifest-description | Free text description of the | 1803 | | manifest | 1804 | | | 1805 | suit-text-update-description | Free text description of the | 1806 | | update | 1807 | | | 1808 | suit-text-manifest-json-source | The JSON-formatted document that | 1809 | | was used to create the manifest | 1810 | | | 1811 | suit-text-manifest-yaml-source | The YAML ([YAML])-formatted | 1812 | | document that was used to create | 1813 | | the manifest | 1814 +--------------------------------+----------------------------------+ 1816 The following table describes the text fields available in each map 1817 identified by a SUIT_Component_Identifier. 1819 +---------------------------------+---------------------------------+ 1820 | CDDL Structure | Description | 1821 +---------------------------------+---------------------------------+ 1822 | suit-text-vendor-name | Free text vendor name | 1823 | | | 1824 | suit-text-model-name | Free text model name | 1825 | | | 1826 | suit-text-vendor-domain | The domain used to create the | 1827 | | vendor-id condition | 1828 | | | 1829 | suit-text-model-info | The information used to create | 1830 | | the class-id condition | 1831 | | | 1832 | suit-text-component-description | Free text description of each | 1833 | | component in the manifest | 1834 | | | 1835 | suit-text-component-version | A free text representation of | 1836 | | the component version | 1837 | | | 1838 | suit-text-version-required | A free text expression of the | 1839 | | required version number | 1840 +---------------------------------+---------------------------------+ 1841 suit-text is OPTIONAL to implement. 1843 8.7. text-version-required 1845 suit-text-version-required is used to represent a version-based 1846 dependency on suit-parameter-version as described in Section 8.7.5.18 1847 and Section 8.7.6.8. To describe a version dependency, a Manifest 1848 Author SHOULD populate the suit-text map with a 1849 SUIT_Component_Identifier key for the dependency component, and place 1850 in the corresponding map a suit-text-version-required key with a free 1851 text expression that is representative of the version constraints 1852 placed on the dependency. This text SHOULD be expressive enough that 1853 a device operator can be expected to understand the dependency. This 1854 is a free text field and there are no specific formatting rules. 1856 By way of example only, to express a dependency on a component "['x', 1857 'y']", where the version should be any v1.x later than v1.2.5, but 1858 not v2.0 or above, the author would add the following structure to 1859 the suit-text element. Note that this text is in cbor-diag notation. 1861 [h'78',h'79'] : { 1862 7 : ">=1.2.5,<2" 1863 } 1865 8.7.1. suit-coswid 1867 suit-coswid contains a Concise Software Identifier (CoSWID) as 1868 defined in [I-D.ietf-sacm-coswid]. This element SHOULD be made 1869 severable so that it can be discarded by the Recipient or an 1870 intermediary if it is not required by the Recipient. 1872 suit-coswid typically requires no processing by the Recipient. 1873 However all Recipients MUST NOT fail if a suit-coswid is present. 1875 8.7.2. suit-common 1877 suit-common encodes all the information that is shared between each 1878 of the command sequences, including: suit-dependencies, suit- 1879 components, and suit-common-sequence. suit-common is REQUIRED to 1880 implement. 1882 suit-dependencies is a list of Section 8.7.2.1 blocks that specify 1883 manifests that must be present before the current manifest can be 1884 processed. suit-dependencies is OPTIONAL to implement. 1886 suit-components is a list of SUIT_Component_Identifier 1887 (Section 8.7.2.2) blocks that specify the component identifiers that 1888 will be affected by the content of the current manifest. suit- 1889 components is REQUIRED to implement; at least one manifest in a 1890 dependency tree MUST contain a suit-components block. 1892 suit-common-sequence is a SUIT_Command_Sequence to execute prior to 1893 executing any other command sequence. Typical actions in suit- 1894 common-sequence include setting expected Recipient identity and image 1895 digests when they are conditional (see Section 8.7.7.3 and 1896 Section 7.11 for more information on conditional sequences). suit- 1897 common-sequence is RECOMMENDED to implement. It is REQUIRED if the 1898 optimizations described in Section 6.2.1 will be used. Whenever a 1899 parameter or Try Each command is required by more than one Command 1900 Sequence, placing that parameter or commamd in suit-common-sequence 1901 results in a smaller encoding. 1903 8.7.2.1. Dependencies 1905 SUIT_Dependency specifies a manifest that describes a dependency of 1906 the current manifest. The Manifest is identified, but the Recipient 1907 should expect an Envelope when it acquires the dependency. This is 1908 because the Manifest is the one invariant element of the Envelope, 1909 where other elements may change by countersigning, adding 1910 authentication blocks, or severing elements. 1912 The suit-dependency-digest specifies the dependency manifest uniquely 1913 by identifying a particular Manifest structure. This is identical to 1914 the digest that would be present as the payload of any suit- 1915 authentication-block in the dependency's Envelope. The digest is 1916 calculated over the Manifest structure instead of the COSE 1917 Sig_structure or Mac_structure. This is necessary to ensure that 1918 removing a signature from a manifest does not break dependencies due 1919 to missing signature elements. This is also necessary to support the 1920 trusted intermediary use case, where an intermediary re-signs the 1921 Manifest, removing the original signature, potentially with a 1922 different algorithm, or trading COSE_Sign for COSE_Mac. 1924 The suit-dependency-prefix element contains a 1925 SUIT_Component_Identifier (see Section 8.7.2.2). This specifies the 1926 scope at which the dependency operates. This allows the dependency 1927 to be forwarded on to a component that is capable of parsing its own 1928 manifests. It also allows one manifest to be deployed to multiple 1929 dependent Recipients without those Recipients needing consistent 1930 component hierarchy. This element is OPTIONAL for Recipients to 1931 implement. 1933 A dependency prefix can be used with a component identifier. This 1934 allows complex systems to understand where dependencies need to be 1935 applied. The dependency prefix can be used in one of two ways. The 1936 first simply prepends the prefix to all Component Identifiers in the 1937 dependency. 1939 A dependency prefix can also be used to indicate when a dependency 1940 manifest needs to be processed by a secondary manifest processor, as 1941 described in Section 6.9. 1943 8.7.2.2. SUIT_Component_Identifier 1945 A component is a unit of code or data that can be targeted by an 1946 update. To facilitate composite devices, components are identified 1947 by a list of CBOR byte strings, which allows construction of 1948 hierarchical component structures. A dependency MAY declare a prefix 1949 to the components defined in the dependency manifest. Components are 1950 identified by Component Identifiers, but referenced in commands by 1951 Component Index; Component Identifiers are arrays of binary strings 1952 and a Component Index is an index into the array of Component 1953 Identifiers. 1955 A Component Identifier can be trivial, such as the simple array 1956 [h'00']. It can also represent a filesystem path by encoding each 1957 segment of the path as an element in the list. For example, the path 1958 "/usr/bin/env" would encode to ['usr','bin','env']. 1960 This hierarchical construction allows a component identifier to 1961 identify any part of a complex, multi-component system. 1963 8.7.3. SUIT_Command_Sequence 1965 A SUIT_Command_Sequence defines a series of actions that the 1966 Recipient MUST take to accomplish a particular goal. These goals are 1967 defined in the manifest and include: 1969 1. Dependency Resolution: suit-dependency-resolution is a 1970 SUIT_Command_Sequence to execute in order to perform dependency 1971 resolution. Typical actions include configuring URIs of 1972 dependency manifests, fetching dependency manifests, and 1973 validating dependency manifests' contents. suit-dependency- 1974 resolution is REQUIRED to implement and to use when suit- 1975 dependencies is present. 1977 2. Payload Fetch: suit-payload-fetch is a SUIT_Command_Sequence to 1978 execute in order to obtain a payload. Some manifests may include 1979 these actions in the suit-install section instead if they operate 1980 in a streaming installation mode. This is particularly relevant 1981 for constrained devices without any temporary storage for staging 1982 the update. suit-payload-fetch is OPTIONAL to implement. 1984 3. Payload Installation: suit-install is a SUIT_Command_Sequence to 1985 execute in order to install a payload. Typical actions include 1986 verifying a payload stored in temporary storage, copying a staged 1987 payload from temporary storage, and unpacking a payload. suit- 1988 install is OPTIONAL to implement. 1990 4. Image Validation: suit-validate is a SUIT_Command_Sequence to 1991 execute in order to validate that the result of applying the 1992 update is correct. Typical actions involve image validation and 1993 manifest validation. suit-validate is REQUIRED to implement. If 1994 the manifest contains dependencies, one process-dependency 1995 invocation per dependency or one process-dependency invocation 1996 targeting all dependencies SHOULD be present in validate. 1998 5. Image Loading: suit-load is a SUIT_Command_Sequence to execute in 1999 order to prepare a payload for execution. Typical actions 2000 include copying an image from permanent storage into RAM, 2001 optionally including actions such as decryption or decompression. 2002 suit-load is OPTIONAL to implement. 2004 6. Run or Boot: suit-run is a SUIT_Command_Sequence to execute in 2005 order to run an image. suit-run typically contains a single 2006 instruction: either the "run" directive for the invocable 2007 manifest or the "process dependencies" directive for any 2008 dependents of the invocable manifest. suit-run is OPTIONAL to 2009 implement. 2011 Goals 1,2,3 form the Update Procedure. Goals 4,5,6 form the 2012 Invocation Procedure. 2014 Each Command Sequence follows exactly the same structure to ensure 2015 that the parser is as simple as possible. 2017 Lists of commands are constructed from two kinds of element: 2019 1. Conditions that MUST be true and any failure is treated as a 2020 failure of the update/load/invocation 2022 2. Directives that MUST be executed. 2024 Each condition is composed of: 2026 1. A command code identifier 2028 2. A SUIT_Reporting_Policy (Section 8.7.4) 2030 Each directive is composed of: 2032 1. A command code identifier 2034 2. An argument block or a SUIT_Reporting_Policy (Section 8.7.4) 2036 Argument blocks are consumed only by flow-control directives: 2038 - Set Component/Dependency Index 2040 - Set/Override Parameters 2042 - Try Each 2044 - Run Sequence 2046 Reporting policies provide a hint to the manifest processor of 2047 whether to add the success or failure of a command to any report that 2048 it generates. 2050 Many conditions and directives apply to a given component, and these 2051 generally grouped together. Therefore, a special command to set the 2052 current component index is provided with a matching command to set 2053 the current dependency index. This index is a numeric index into the 2054 Component Identifier tables defined at the beginning of the manifest. 2055 For the purpose of setting the index, the two Component Identifier 2056 tables are considered to be concatenated together. 2058 To facilitate optional conditions, a special directive, suit- 2059 directive-try-each (Section 8.7.7.3), is provided. It runs several 2060 new lists of conditions/directives, one after another, that are 2061 contained as an argument to the directive. By default, it assumes 2062 that a failure of a condition should not indicate a failure of the 2063 update/invocation, but a parameter is provided to override this 2064 behavior. See suit-parameter-soft-failure (Section 8.7.5.23). 2066 8.7.4. Reporting Policy 2068 To facilitate construction of Reports that describe the success, or 2069 failure of a given Procedure, each command is given a Reporting 2070 Policy. This is an integer bitfield that follows the command and 2071 indicates what the Recipient should do with the Record of executing 2072 the command. The options are summarized in the table below. 2074 +-----------------------------+-------------------------------------+ 2075 | Policy | Description | 2076 +-----------------------------+-------------------------------------+ 2077 | suit-send-record-on-success | Record when the command succeeds | 2078 | | | 2079 | suit-send-record-on-failure | Record when the command fails | 2080 | | | 2081 | suit-send-sysinfo-success | Add system information when the | 2082 | | command succeeds | 2083 | | | 2084 | suit-send-sysinfo-failure | Add system information when the | 2085 | | command fails | 2086 +-----------------------------+-------------------------------------+ 2088 Any or all of these policies may be enabled at once. 2090 At the completion of each command, a Manifest Processor MAY forward 2091 information about the command to a Reporting Engine, which is 2092 responsible for reporting boot or update status to a third party. 2093 The Reporting Engine is entirely implementation-defined, the 2094 reporting policy simply facilitates the Reporting Engine's interface 2095 to the SUIT Manifest Processor. 2097 The information elements provided to the Reporting Engine are: 2099 - The reporting policy 2101 - The result of the command 2103 - The values of parameters consumed by the command 2105 - The system information consumed by the command 2107 Together, these elements are called a Record. A group of Records is 2108 a Report. 2110 If the component index is set to True or an array when a command is 2111 executed with a non-zero reporting policy, then the Reporting Engine 2112 MUST receive one Record for each Component, in the order expressed in 2113 the Components list or the component index array. If the dependency 2114 index is set to True or an array when a command is executed with a 2115 non-zero reporting policy, then the Reporting Engine MUST receive one 2116 Record for each Dependency, in the order expressed in the 2117 Dependencies list or the component index array, respectively. 2119 This specification does not define a particular format of Records or 2120 Reports. This specification only defines hints to the Reporting 2121 Engine for which Records it should aggregate into the Report. The 2122 Reporting Engine MAY choose to ignore these hints and apply its own 2123 policy instead. 2125 When used in a Invocation Procedure, the report MAY form the basis of 2126 an attestation report. When used in an Update Process, the report 2127 MAY form the basis for one or more log entries. 2129 8.7.5. SUIT_Parameters 2131 Many conditions and directives require additional information. That 2132 information is contained within parameters that can be set in a 2133 consistent way. This allows reduction of manifest size and 2134 replacement of parameters from one manifest to the next. 2136 Most parameters are scoped to a specific component. This means that 2137 setting a parameter for one component has no effect on the parameters 2138 of any other component. The only exceptions to this are two Manifest 2139 Processor parameters: Strict Order and Soft Failure. 2141 The defined manifest parameters are described below. 2143 +----------------+----------------------------------+---------------+ 2144 | Name | CDDL Structure | Reference | 2145 +----------------+----------------------------------+---------------+ 2146 | Vendor ID | suit-parameter-vendor-identifier | Section 8.7.5 | 2147 | | | .3 | 2148 | | | | 2149 | Class ID | suit-parameter-class-identifier | Section 8.7.5 | 2150 | | | .4 | 2151 | | | | 2152 | Device ID | suit-parameter-device-identifier | Section 8.7.5 | 2153 | | | .5 | 2154 | | | | 2155 | Image Digest | suit-parameter-image-digest | Section 8.7.5 | 2156 | | | .6 | 2157 | | | | 2158 | Image Size | suit-parameter-image-size | Section 8.7.5 | 2159 | | | .7 | 2160 | | | | 2161 | Use Before | suit-parameter-use-before | Section 8.7.5 | 2162 | | | .8 | 2163 | | | | 2164 | Component | suit-parameter-component-offset | Section 8.7.5 | 2165 | Offset | | .9 | 2166 | | | | 2167 | Encryption | suit-parameter-encryption-info | Section 8.7.5 | 2168 | Info | | .10 | 2169 | | | | 2170 | Compression | suit-parameter-compression-info | Section 8.7.5 | 2171 | Info | | .11 | 2172 | | | | 2173 | Unpack Info | suit-parameter-unpack-info | Section 8.7.5 | 2174 | | | .12 | 2175 | | | | 2176 | URI | suit-parameter-uri | Section 8.7.5 | 2177 | | | .13 | 2178 | | | | 2179 | Source | suit-parameter-source-component | Section 8.7.5 | 2180 | Component | | .14 | 2181 | | | | 2182 | Run Args | suit-parameter-run-args | Section 8.7.5 | 2183 | | | .15 | 2184 | | | | 2185 | Minimum | suit-parameter-minimum-battery | Section 8.7.5 | 2186 | Battery | | .16 | 2187 | | | | 2188 | Update | suit-parameter-update-priority | Section 8.7.5 | 2189 | Priority | | .17 | 2190 | | | | 2191 | Version | suit-parameter-version | Section 8.7.5 | 2192 | | | .18 | 2193 | | | | 2194 | Wait Info | suit-parameter-wait-info | Section 8.7.5 | 2195 | | | .19 | 2196 | | | | 2197 | URI List | suit-parameter-uri-list | Section 8.7.5 | 2198 | | | .20 | 2199 | | | | 2200 | Fetch | suit-parameter-fetch-arguments | Section 8.7.5 | 2201 | Arguments | | .21 | 2202 | | | | 2203 | Strict Order | suit-parameter-strict-order | Section 8.7.5 | 2204 | | | .22 | 2205 | | | | 2206 | Soft Failure | suit-parameter-soft-failure | Section 8.7.5 | 2207 | | | .23 | 2208 | | | | 2209 | Custom | suit-parameter-custom | Section 8.7.5 | 2210 | | | .24 | 2211 +----------------+----------------------------------+---------------+ 2213 CBOR-encoded object parameters are still wrapped in a bstr. This is 2214 because it allows a parser that is aggregating parameters to 2215 reference the object with a single pointer and traverse it without 2216 understanding the contents. This is important for modularization and 2217 division of responsibility within a pull parser. The same 2218 consideration does not apply to Directives because those elements are 2219 invoked with their arguments immediately 2221 8.7.5.1. CBOR PEN UUID Namespace Identifier 2223 The CBOR PEN UUID Namespace Identifier is constructed as follows: 2225 It uses the OID Namespace as a starting point, then uses the CBOR OID 2226 encoding for the IANA PEN OID (1.3.6.1.4.1): 2228 D8 DE # tag(111) 2229 45 # bytes(5) 2230 2B 06 01 04 01 # X.690 Clause 8.19 2231 # 1.3 6 1 4 1 show component encoding 2233 Computing a type 5 UUID from these produces: 2235 NAMESPACE_CBOR_PEN = UUID5(NAMESPACE_OID, h'D86F452B06010401') 2236 NAMESPACE_CBOR_PEN = 08cfcc43-47d9-5696-85b1-9c738465760e 2238 8.7.5.2. Constructing UUIDs 2240 Several conditions use identifiers to determine whether a manifest 2241 matches a given Recipient or not. These identifiers are defined to 2242 be RFC 4122 [RFC4122] UUIDs. These UUIDs are not human-readable and 2243 are therefore used for machine-based processing only. 2245 A Recipient MAY match any number of UUIDs for vendor or class 2246 identifier. This may be relevant to physical or software modules. 2247 For example, a Recipient that has an OS and one or more applications 2248 might list one Vendor ID for the OS and one or more additional Vendor 2249 IDs for the applications. This Recipient might also have a Class ID 2250 that must be matched for the OS and one or more Class IDs for the 2251 applications. 2253 Identifiers are used for compatibility checks. They MUST NOT be used 2254 as assertions of identity. They are evaluated by identifier 2255 conditions (Section 8.7.6.1). 2257 A more complete example: Imagine a device has the following physical 2258 components: 1. A host MCU 2. A WiFi module 2260 This same device has three software modules: 1. An operating system 2261 2. A WiFi module interface driver 3. An application 2263 Suppose that the WiFi module's firmware has a proprietary update 2264 mechanism and doesn't support manifest processing. This device can 2265 report four class IDs: 2267 1. Hardware model/revision 2269 2. OS 2271 3. WiFi module model/revision 2273 4. Application 2275 This allows the OS, WiFi module, and application to be updated 2276 independently. To combat possible incompatibilities, the OS class ID 2277 can be changed each time the OS has a change to its API. 2279 This approach allows a vendor to target, for example, all devices 2280 with a particular WiFi module with an update, which is a very 2281 powerful mechanism, particularly when used for security updates. 2283 UUIDs MUST be created according to RFC 4122 [RFC4122]. UUIDs SHOULD 2284 use versions 3, 4, or 5, as described in RFC4122. Versions 1 and 2 2285 do not provide a tangible benefit over version 4 for this 2286 application. 2288 The RECOMMENDED method to create a vendor ID is: 2290 Vendor ID = UUID5(DNS_PREFIX, vendor domain name) 2292 If the Vendor ID is a UUID, the RECOMMENDED method to create a Class 2293 ID is: 2295 Class ID = UUID5(Vendor ID, Class-Specific-Information) 2297 If the Vendor ID is a CBOR PEN (see Section 8.7.5.3), the RECOMMENDED 2298 method to create a Class ID is: 2300 Class ID = UUID5( 2301 UUID5(NAMESPACE_CBOR_PEN, CBOR_PEN), 2302 Class-Specific-Information) 2304 Class-specific-information is composed of a variety of data, for 2305 example: 2307 - Model number. 2309 - Hardware revision. 2311 - Bootloader version (for immutable bootloaders). 2313 8.7.5.3. suit-parameter-vendor-identifier 2315 suit-parameter-vendor-identifier may be presented in one of two ways: 2317 - A Private Enterprise Number 2319 - A byte string containing a UUID ([RFC4122]) 2321 Private Enterprise Numbers are encoded as a relative OID, according 2322 to the definition in [I-D.ietf-cbor-tags-oid]. All PENs are relative 2323 to the IANA PEN: 1.3.6.1.4.1. 2325 8.7.5.4. suit-parameter-class-identifier 2327 A RFC 4122 UUID representing the class of the device or component. 2328 The UUID is encoded as a 16 byte bstr, containing the raw bytes of 2329 the UUID. It MUST be constructed as described in Section 8.7.5.2 2331 8.7.5.5. suit-parameter-device-identifier 2333 A RFC 4122 UUID representing the specific device or component. The 2334 UUID is encoded as a 16 byte bstr, containing the raw bytes of the 2335 UUID. It MUST be constructed as described in Section 8.7.5.2 2337 8.7.5.6. suit-parameter-image-digest 2339 A fingerprint computed over the component itself, encoded in the 2340 SUIT_Digest Section 10 structure. The SUIT_Digest is wrapped in a 2341 bstr, as required in Section 8.7.5. 2343 8.7.5.7. suit-parameter-image-size 2345 The size of the firmware image in bytes. This size is encoded as a 2346 positive integer. 2348 8.7.5.8. suit-parameter-use-before 2350 An expiry date for the use of the manifest encoded as the positive 2351 integer number of seconds since 1970-01-01. Implementations that use 2352 this parameter MUST use a 64-bit internal representation of the 2353 integer. 2355 8.7.5.9. suit-parameter-component-offset 2357 This parameter sets the offset in a component. Some components 2358 support multiple possible Slots (offsets into a storage area). This 2359 parameter describes the intended Slot to use, identified by its 2360 offset into the component's storage area. This offset MUST be 2361 encoded as a positive integer. 2363 8.7.5.10. suit-parameter-encryption-info 2365 Encryption Info defines the mechanism that Fetch or Copy should use 2366 to decrypt the data they transfer. SUIT_Parameter_Encryption_Info is 2367 encoded as a COSE_Encrypt_Tagged or a COSE_Encrypt0_Tagged, wrapped 2368 in a bstr. 2370 8.7.5.11. suit-parameter-compression-info 2372 SUIT_Compression_Info defines any information that is required for a 2373 Recipient to perform decompression operations. SUIT_Compression_Info 2374 is a map containing this data. The only element defined for the map 2375 in this specification is the suit-compression-algorithm. This 2376 document defines the following suit-compression-algorithm's: ZLIB 2377 [RFC1950], Brotli [RFC7932], and ZSTD [I-D.kucherawy-rfc8478bis]. 2379 Additional suit-compression-algorithm's can be registered through the 2380 IANA-maintained registry. If such a format requires more data than 2381 an algorithm identifier, one or more new elements MUST be introduced 2382 by specifying an element for SUIT_Compression_Info-extensions. 2384 8.7.5.12. suit-parameter-unpack-info 2386 SUIT_Unpack_Info defines the information required for a Recipient to 2387 interpret a packed format. This document defines the use of the 2388 following binary encodings: Intel HEX [HEX], Motorola S-record 2389 [SREC], Executable and Linkable Format (ELF) [ELF], and Common Object 2390 File Format (COFF) [COFF]. 2392 Additional packing formats can be registered through the IANA- 2393 maintained registry. 2395 8.7.5.13. suit-parameter-uri 2397 A URI from which to fetch a resource, encoded as a text string. CBOR 2398 Tag 32 is not used because the meaning of the text string is 2399 unambiguous in this context. 2401 8.7.5.14. suit-parameter-source-component 2403 This parameter sets the source component to be used with either suit- 2404 directive-copy (Section 8.7.7.9) or with suit-directive-swap 2405 (Section 8.7.7.13). The current Component, as set by suit-directive- 2406 set-component-index defines the destination, and suit-parameter- 2407 source-component defines the source. 2409 8.7.5.15. suit-parameter-run-args 2411 This parameter contains an encoded set of arguments for suit- 2412 directive-run (Section 8.7.7.10). The arguments MUST be provided as 2413 an implementation-defined bstr. 2415 8.7.5.16. suit-parameter-minimum-battery 2417 This parameter sets the minimum battery level in mWh. This parameter 2418 is encoded as a positive integer. Used with suit-condition-minimum- 2419 battery (Section 8.7.6.6). 2421 8.7.5.17. suit-parameter-update-priority 2423 This parameter sets the priority of the update. This parameter is 2424 encoded as an integer. It is used along with suit-condition-update- 2425 authorized (Section 8.7.6.7) to ask an application for permission to 2426 initiate an update. This does not constitute a privilege inversion 2427 because an explicit request for authorization has been provided by 2428 the Update Authority in the form of the suit-condition-update- 2429 authorized command. 2431 Applications MAY define their own meanings for the update priority. 2432 For example, critical reliability & vulnerability fixes MAY be given 2433 negative numbers, while bug fixes MAY be given small positive 2434 numbers, and feature additions MAY be given larger positive numbers, 2435 which allows an application to make an informed decision about 2436 whether and when to allow an update to proceed. 2438 8.7.5.18. suit-parameter-version 2440 Indicates allowable versions for the specified component. Allowable 2441 versions can be specified, either with a list or with range matching. 2442 This parameter is compared with version asserted by the current 2443 component when suit-condition-version (Section 8.7.6.8) is invoked. 2444 The current component may assert the current version in many ways, 2445 including storage in a parameter storage database, in a metadata 2446 object, or in a known location within the component itself. 2448 The component version can be compared as: 2450 - Greater. 2452 - Greater or Equal. 2454 - Equal. 2456 - Lesser or Equal. 2458 - Lesser. 2460 Versions are encoded as a CBOR list of integers. Comparisons are 2461 done on each integer in sequence. Comparison stops after all 2462 integers in the list defined by the manifest have been consumed OR 2463 after a non-equal match has occurred. For example, if the manifest 2464 defines a comparison, "Equal [1]", then this will match all version 2465 sequences starting with 1. If a manifest defines both "Greater or 2466 Equal [1,0]" and "Lesser [1,10]", then it will match versions 1.0.x 2467 up to, but not including 1.10. 2469 While the exact encoding of versions is application-defined, semantic 2470 versions map conveniently. For example, 2472 - 1.2.3 = [1,2,3]. 2474 - 1.2-rc3 = [1,2,-1,3]. 2476 - 1.2-beta = [1,2,-2]. 2478 - 1.2-alpha = [1,2,-3]. 2480 - 1.2-alpha4 = [1,2,-3,4]. 2482 suit-condition-version is OPTIONAL to implement. 2484 Versions SHOULD be provided as follows: 2486 1. The first integer represents the major number. This indicates 2487 breaking changes to the component. 2489 2. The second integer represents the minor number. This is 2490 typically reserved for new features or large, non-breaking 2491 changes. 2493 3. The third integer is the patch version. This is typically 2494 reserved for bug fixes. 2496 4. The fourth integer is the build number. 2498 Where Alpha (-3), Beta (-2), and Release Candidate (-1) are used, 2499 they are inserted as a negative number between Minor and Patch 2500 numbers. This allows these releases to compare correctly with final 2501 releases. For example, Version 2.0, RC1 should be lower than Version 2502 2.0.0 and higher than any Version 1.x. By encoding RC as -1, this 2503 works correctly: [2,0,-1,1] compares as lower than [2,0,0]. 2504 Similarly, beta (-2) is lower than RC and alpha (-3) is lower than 2505 RC. 2507 8.7.5.19. suit-parameter-wait-info 2509 suit-directive-wait (Section 8.7.7.11) directs the manifest processor 2510 to pause until a specified event occurs. The suit-parameter-wait- 2511 info encodes the parameters needed for the directive. 2513 The exact implementation of the pause is implementation-defined. For 2514 example, this could be done by blocking on a semaphore, registering 2515 an event handler and suspending the manifest processor, polling for a 2516 notification, or aborting the update entirely, then restarting when a 2517 notification is received. 2519 suit-parameter-wait-info is encoded as a map of wait events. When 2520 ALL wait events are satisfied, the Manifest Processor continues. The 2521 wait events currently defined are described in the following table. 2523 +------------------------------+---------+--------------------------+ 2524 | Name | Encodin | Description | 2525 | | g | | 2526 +------------------------------+---------+--------------------------+ 2527 | suit-wait-event- | int | Same as suit-parameter- | 2528 | authorization | | update-priority | 2529 | | | | 2530 | suit-wait-event-power | int | Wait until power state | 2531 | | | | 2532 | suit-wait-event-network | int | Wait until network state | 2533 | | | | 2534 | suit-wait-event-other- | See | Wait for other device to | 2535 | device-version | below | match version | 2536 | | | | 2537 | suit-wait-event-time | uint | Wait until time (seconds | 2538 | | | since 1970-01-01) | 2539 | | | | 2540 | suit-wait-event-time-of-day | uint | Wait until seconds since | 2541 | | | 00:00:00 | 2542 | | | | 2543 | suit-wait-event-time-of-day- | uint | Wait until seconds since | 2544 | utc | | 00:00:00 UTC | 2545 | | | | 2546 | suit-wait-event-day-of-week | uint | Wait until days since | 2547 | | | Sunday | 2548 | | | | 2549 | suit-wait-event-day-of-week- | uint | Wait until days since | 2550 | utc | | Sunday UTC | 2551 +------------------------------+---------+--------------------------+ 2553 suit-wait-event-other-device-version reuses the encoding of suit- 2554 parameter-version-match. It is encoded as a sequence that contains 2555 an implementation-defined bstr identifier for the other device, and a 2556 list of one or more SUIT_Parameter_Version_Match. 2558 8.7.5.20. suit-parameter-uri-list 2560 Indicates a list of URIs from which to fetch a resource. The URI 2561 list is encoded as a list of text string, in priority order. CBOR 2562 Tag 32 is not used because the meaning of the text string is 2563 unambiguous in this context. The Recipient should attempt to fetch 2564 the resource from each URI in turn, ruling out each, in order, if the 2565 resource is inaccessible or it is otherwise undesirable to fetch from 2566 that URI. suit-parameter-uri-list is consumed by suit-directive- 2567 fetch-uri-list (Section 8.7.7.8). 2569 8.7.5.21. suit-parameter-fetch-arguments 2571 An implementation-defined set of arguments to suit-directive-fetch 2572 (Section 8.7.7.7). Arguments are encoded in a bstr. 2574 8.7.5.22. suit-parameter-strict-order 2576 The Strict Order Parameter allows a manifest to govern when 2577 directives can be executed out-of-order. This allows for systems 2578 that have a sensitivity to order of updates to choose the order in 2579 which they are executed. It also allows for more advanced systems to 2580 parallelize their handling of updates. Strict Order defaults to 2581 True. It MAY be set to False when the order of operations does not 2582 matter. When arriving at the end of a command sequence, ALL commands 2583 MUST have completed, regardless of the state of 2584 SUIT_Parameter_Strict_Order. SUIT_Process_Dependency must preserve 2585 and restore the state of SUIT_Parameter_Strict_Order. If 2586 SUIT_Parameter_Strict_Order is returned to True, ALL preceding 2587 commands MUST complete before the next command is executed. 2589 See Section 6.7 for behavioral description of Strict Order. 2591 8.7.5.23. suit-parameter-soft-failure 2593 When executing a command sequence inside suit-directive-try-each 2594 (Section 8.7.7.3) or suit-directive-run-sequence (Section 8.7.7.12) 2595 and a condition failure occurs, the manifest processor aborts the 2596 sequence. For suit-directive-try-each, if Soft Failure is True, the 2597 next sequence in Try Each is invoked, otherwise suit-directive-try- 2598 each fails with the condition failure code. In suit-directive-run- 2599 sequence, if Soft Failure is True the suit-directive-run-sequence 2600 simply halts with no side-effects and the Manifest Processor 2601 continues with the following command, otherwise, the suit-directive- 2602 run-sequence fails with the condition failure code. 2604 suit-parameter-soft-failure is scoped to the enclosing 2605 SUIT_Command_Sequence. Its value is discarded when 2606 SUIT_Command_Sequence terminates. It MUST NOT be set outside of 2607 suit-directive-try-each or suit-directive-run-sequence. 2609 When suit-directive-try-each is invoked, Soft Failure defaults to 2610 True. An Update Author may choose to set Soft Failure to False if 2611 they require a failed condition in a sequence to force an Abort. 2613 When suit-directive-run-sequence is invoked, Soft Failure defaults to 2614 False. An Update Author may choose to make failures soft within a 2615 suit-directive-run-sequence. 2617 8.7.5.24. suit-parameter-custom 2619 This parameter is an extension point for any proprietary, application 2620 specific conditions and directives. It MUST NOT be used in the 2621 common sequence. This effectively scopes each custom command to a 2622 particular Vendor Identifier/Class Identifier pair. 2624 8.7.6. SUIT_Condition 2626 Conditions are used to define mandatory properties of a system in 2627 order for an update to be applied. They can be pre-conditions or 2628 post-conditions of any directive or series of directives, depending 2629 on where they are placed in the list. All Conditions specify a 2630 Reporting Policy as described Section 8.7.4. Conditions include: 2632 +----------------+----------------------------------+---------------+ 2633 | Name | CDDL Structure | Reference | 2634 +----------------+----------------------------------+---------------+ 2635 | Vendor | suit-condition-vendor-identifier | Section 8.7.6 | 2636 | Identifier | | .1 | 2637 | | | | 2638 | Class | suit-condition-class-identifier | Section 8.7.6 | 2639 | Identifier | | .1 | 2640 | | | | 2641 | Device | suit-condition-device-identifier | Section 8.7.6 | 2642 | Identifier | | .1 | 2643 | | | | 2644 | Image Match | suit-condition-image-match | Section 8.7.6 | 2645 | | | .2 | 2646 | | | | 2647 | Image Not | suit-condition-image-not-match | Section 8.7.6 | 2648 | Match | | .3 | 2649 | | | | 2650 | Use Before | suit-condition-use-before | Section 8.7.6 | 2651 | | | .4 | 2652 | | | | 2653 | Component | suit-condition-component-offset | Section 8.7.6 | 2654 | Offset | | .5 | 2655 | | | | 2656 | Minimum | suit-condition-minimum-battery | Section 8.7.6 | 2657 | Battery | | .6 | 2658 | | | | 2659 | Update | suit-condition-update-authorized | Section 8.7.6 | 2660 | Authorized | | .7 | 2661 | | | | 2662 | Version | suit-condition-version | Section 8.7.6 | 2663 | | | .8 | 2664 | | | | 2665 | Abort | suit-condition-abort | Section 8.7.6 | 2666 | | | .9 | 2667 | | | | 2668 | Custom | suit-condition-custom | Section 8.7.6 | 2669 | Condition | | .10 | 2670 +----------------+----------------------------------+---------------+ 2672 The abstract description of these conditions is defined in 2673 Section 6.4. 2675 Conditions compare parameters against properties of the system. 2676 These properties may be asserted in many different ways, including: 2677 calculation on-demand, volatile definition in memory, static 2678 definition within the manifest processor, storage in known location 2679 within an image, storage within a key storage system, storage in One- 2680 Time-Programmable memory, inclusion in mask ROM, or inclusion as a 2681 register in hardware. Some of these assertion methods are global in 2682 scope, such as a hardware register, some are scoped to an individual 2683 component, such as storage at a known location in an image, and some 2684 assertion methods can be either global or component-scope, based on 2685 implementation. 2687 Each condition MUST report a result code on completion. If a 2688 condition reports failure, then the current sequence of commands MUST 2689 terminate. A subsequent command or command sequence MAY continue 2690 executing if suit-parameter-soft-failure (Section 8.7.5.23) is set. 2691 If a condition requires additional information, this MUST be 2692 specified in one or more parameters before the condition is executed. 2693 If a Recipient attempts to process a condition that expects 2694 additional information and that information has not been set, it MUST 2695 report a failure. If a Recipient encounters an unknown condition, it 2696 MUST report a failure. 2698 Condition labels in the positive number range are reserved for IANA 2699 registration while those in the negative range are custom conditions 2700 reserved for proprietary definition by the author of a manifest 2701 processor. See Section 11 for more details. 2703 8.7.6.1. suit-condition-vendor-identifier, suit-condition-class- 2704 identifier, and suit-condition-device-identifier 2706 There are three identifier-based conditions: suit-condition-vendor- 2707 identifier, suit-condition-class-identifier, and suit-condition- 2708 device-identifier. Each of these conditions match a RFC 4122 2709 [RFC4122] UUID that MUST have already been set as a parameter. The 2710 installing Recipient MUST match the specified UUID in order to 2711 consider the manifest valid. These identifiers are scoped by 2712 component in the manifest. Each component MAY match more than one 2713 identifier. Care is needed to ensure that manifests correctly 2714 identify their targets using these conditions. Using only a generic 2715 class ID for a device-specific firmware could result in matching 2716 devices that are not compatible. 2718 The Recipient uses the ID parameter that has already been set using 2719 the Set Parameters directive. If no ID has been set, this condition 2720 fails. suit-condition-class-identifier and suit-condition-vendor- 2721 identifier are REQUIRED to implement. suit-condition-device- 2722 identifier is OPTIONAL to implement. 2724 Each identifier condition compares the corresponding identifier 2725 parameter to a parameter asserted to the Manifest Processor by the 2726 Recipient. Identifiers MUST be known to the Manifest Processor in 2727 order to evaluate compatibility. 2729 8.7.6.2. suit-condition-image-match 2731 Verify that the current component matches the suit-parameter-image- 2732 digest (Section 8.7.5.6) for the current component. The digest is 2733 verified against the digest specified in the Component's parameters 2734 list. If no digest is specified, the condition fails. suit- 2735 condition-image-match is REQUIRED to implement. 2737 8.7.6.3. suit-condition-image-not-match 2739 Verify that the current component does not match the suit-parameter- 2740 image-digest (Section 8.7.5.6). If no digest is specified, the 2741 condition fails. suit-condition-image-not-match is OPTIONAL to 2742 implement. 2744 8.7.6.4. suit-condition-use-before 2746 Verify that the current time is BEFORE the specified time. suit- 2747 condition-use-before is used to specify the last time at which an 2748 update should be installed. The recipient evaluates the current time 2749 against the suit-parameter-use-before parameter (Section 8.7.5.8), 2750 which must have already been set as a parameter, encoded as seconds 2751 after 1970-01-01 00:00:00 UTC. Timestamp conditions MUST be 2752 evaluated in 64 bits, regardless of encoded CBOR size. suit- 2753 condition-use-before is OPTIONAL to implement. 2755 8.7.6.5. suit-condition-component-offset 2757 Verify that the offset of the current component matches the offset 2758 set in suit-parameter-component-offset (Section 8.7.5.9). This 2759 condition allows a manifest to select between several images to match 2760 a target offset. 2762 8.7.6.6. suit-condition-minimum-battery 2764 suit-condition-minimum-battery provides a mechanism to test a 2765 Recipient's battery level before installing an update. This 2766 condition is primarily for use in primary-cell applications, where 2767 the battery is only ever discharged. For batteries that are charged, 2768 suit-directive-wait is more appropriate, since it defines a "wait" 2769 until the battery level is sufficient to install the update. suit- 2770 condition-minimum-battery is specified in mWh. suit-condition- 2771 minimum-battery is OPTIONAL to implement. suit-condition-minimum- 2772 battery consumes suit-parameter-minimum-battery (Section 8.7.5.16). 2774 8.7.6.7. suit-condition-update-authorized 2776 Request Authorization from the application and fail if not 2777 authorized. This can allow a user to decline an update. suit- 2778 parameter-update-priority (Section 8.7.5.17) provides an integer 2779 priority level that the application can use to determine whether or 2780 not to authorize the update. Priorities are application defined. 2781 suit-condition-update-authorized is OPTIONAL to implement. 2783 8.7.6.8. suit-condition-version 2785 suit-condition-version allows comparing versions of firmware. 2786 Verifying image digests is preferred to version checks because 2787 digests are more precise. suit-condition-version examines a 2788 component's version against the version info specified in suit- 2789 parameter-version (Section 8.7.5.18) 2791 8.7.6.9. suit-condition-abort 2793 Unconditionally fail. This operation is typically used in 2794 conjunction with suit-directive-try-each (Section 8.7.7.3). 2796 8.7.6.10. suit-condition-custom 2798 suit-condition-custom describes any proprietary, application specific 2799 condition. This is encoded as a negative integer, chosen by the 2800 firmware developer. If additional information must be provided to 2801 the condition, it should be encoded in a custom parameter (a nint) as 2802 described in Section 8.7.5. SUIT_Condition_Custom is OPTIONAL to 2803 implement. 2805 8.7.7. SUIT_Directive 2807 Directives are used to define the behavior of the recipient. 2808 Directives include: 2810 +---------------+-------------------------------------+-------------+ 2811 | Name | CDDL Structure | Reference | 2812 +---------------+-------------------------------------+-------------+ 2813 | Set Component | suit-directive-set-component-index | Section 8.7 | 2814 | Index | | .7.1 | 2815 | | | | 2816 | Set | suit-directive-set-dependency-index | Section 8.7 | 2817 | Dependency | | .7.2 | 2818 | Index | | | 2819 | | | | 2820 | Try Each | suit-directive-try-each | Section 8.7 | 2821 | | | .7.3 | 2822 | | | | 2823 | Process | suit-directive-process-dependency | Section 8.7 | 2824 | Dependency | | .7.4 | 2825 | | | | 2826 | Set | suit-directive-set-parameters | Section 8.7 | 2827 | Parameters | | .7.5 | 2828 | | | | 2829 | Override | suit-directive-override-parameters | Section 8.7 | 2830 | Parameters | | .7.6 | 2831 | | | | 2832 | Fetch | suit-directive-fetch | Section 8.7 | 2833 | | | .7.7 | 2834 | | | | 2835 | Fetch URI | suit-directive-fetch-uri-list | Section 8.7 | 2836 | list | | .7.8 | 2837 | | | | 2838 | Copy | suit-directive-copy | Section 8.7 | 2839 | | | .7.9 | 2840 | | | | 2841 | Run | suit-directive-run | Section 8.7 | 2842 | | | .7.10 | 2843 | | | | 2844 | Wait For | suit-directive-wait | Section 8.7 | 2845 | Event | | .7.11 | 2846 | | | | 2847 | Run Sequence | suit-directive-run-sequence | Section 8.7 | 2848 | | | .7.12 | 2849 | | | | 2850 | Swap | suit-directive-swap | Section 8.7 | 2851 | | | .7.13 | 2852 +---------------+-------------------------------------+-------------+ 2854 The abstract description of these commands is defined in Section 6.4. 2856 When a Recipient executes a Directive, it MUST report a result code. 2857 If the Directive reports failure, then the current Command Sequence 2858 MUST be terminated. 2860 8.7.7.1. suit-directive-set-component-index 2862 Set Component Index defines the component to which successive 2863 directives and conditions will apply. The supplied argument MUST be 2864 one of three types: 2866 1. An unsigned integer (REQUIRED to implement in parser) 2868 2. A boolean (REQUIRED to implement in parser ONLY IF 2 or more 2869 components supported) 2871 3. An array of unsigned integers (REQUIRED to implement in parser 2872 ONLY IF 3 or more components supported) 2874 If the following commands apply to ONE component, an unsigned integer 2875 index into the component list is used. If the following commands 2876 apply to ALL components, then the boolean value "True" is used 2877 instead of an index. If the following commands apply to more than 2878 one, but not all components, then an array of unsigned integer 2879 indices into the component list is used. See Section 6.5 for more 2880 details. 2882 If the following commands apply to NO components, then the boolean 2883 value "False" is used. When suit-directive-set-dependency-index is 2884 used, suit-directive-set-component-index = False is implied. When 2885 suit-directive-set-component-index is used, suit-directive-set- 2886 dependency-index = False is implied. 2888 If component index is set to True when a command is invoked, then the 2889 command applies to all components, in the order they appear in suit- 2890 common-components. When the Manifest Processor invokes a command 2891 while the component index is set to True, it must execute the command 2892 once for each possible component index, ensuring that the command 2893 receives the parameters corresponding to that component index. 2895 8.7.7.2. suit-directive-set-dependency-index 2897 Set Dependency Index defines the manifest to which successive 2898 directives and conditions will apply. The supplied argument MUST be 2899 either a boolean or an unsigned integer index into the dependencies, 2900 or an array of unsigned integer indices into the list of 2901 dependencies. If the following directives apply to ALL dependencies, 2902 then the boolean value "True" is used instead of an index. If the 2903 following directives apply to NO dependencies, then the boolean value 2904 "False" is used. When suit-directive-set-component-index is used, 2905 suit-directive-set-dependency-index = False is implied. When suit- 2906 directive-set-dependency-index is used, suit-directive-set-component- 2907 index = False is implied. 2909 If dependency index is set to True when a command is invoked, then 2910 the command applies to all dependencies, in the order they appear in 2911 suit-common-components. When the Manifest Processor invokes a 2912 command while the dependency index is set to True, the Manifest 2913 Processor MUST execute the command once for each possible dependency 2914 index, ensuring that the command receives the parameters 2915 corresponding to that dependency index. If the dependency index is 2916 set to an array of unsigned integers, then the Manifest Processor 2917 MUST execute the command once for each listed dependency index, 2918 ensuring that the command receives the parameters corresponding to 2919 that dependency index. 2921 See Section 6.5 for more details. 2923 Typical operations that require suit-directive-set-dependency-index 2924 include setting a source URI or Encryption Information, invoking 2925 "Fetch," or invoking "Process Dependency" for an individual 2926 dependency. 2928 8.7.7.3. suit-directive-try-each 2930 This command runs several SUIT_Command_Sequence instances, one after 2931 another, in a strict order. Use this command to implement a "try/ 2932 catch-try/catch" sequence. Manifest processors MAY implement this 2933 command. 2935 suit-parameter-soft-failure (Section 8.7.5.23) is initialized to True 2936 at the beginning of each sequence. If one sequence aborts due to a 2937 condition failure, the next is started. If no sequence completes 2938 without condition failure, then suit-directive-try-each returns an 2939 error. If a particular application calls for all sequences to fail 2940 and still continue, then an empty sequence (nil) can be added to the 2941 Try Each Argument. 2943 The argument to suit-directive-try-each is a list of 2944 SUIT_Command_Sequence. suit-directive-try-each does not specify a 2945 reporting policy. 2947 8.7.7.4. suit-directive-process-dependency 2949 Execute the commands in the common section of the current dependency, 2950 followed by the commands in the equivalent section of the current 2951 dependency. For example, if the current section is "fetch payload," 2952 this will execute "common" in the current dependency, then "fetch 2953 payload" in the current dependency. Once this is complete, the 2954 command following suit-directive-process-dependency will be 2955 processed. 2957 If the current dependency is False, this directive has no effect. If 2958 the current dependency is True, then this directive applies to all 2959 dependencies. If the current section is "common," then the command 2960 sequence MUST be terminated with an error. 2962 When SUIT_Process_Dependency completes, it forwards the last status 2963 code that occurred in the dependency. 2965 8.7.7.5. suit-directive-set-parameters 2967 suit-directive-set-parameters allows the manifest to configure 2968 behavior of future directives by changing parameters that are read by 2969 those directives. When dependencies are used, suit-directive-set- 2970 parameters also allows a manifest to modify the behavior of its 2971 dependencies. 2973 Available parameters are defined in Section 8.7.5. 2975 If a parameter is already set, suit-directive-set-parameters will 2976 skip setting the parameter to its argument. This provides the core 2977 of the override mechanism, allowing dependent manifests to change the 2978 behavior of a manifest. 2980 suit-directive-set-parameters does not specify a reporting policy. 2982 8.7.7.6. suit-directive-override-parameters 2984 suit-directive-override-parameters replaces any listed parameters 2985 that are already set with the values that are provided in its 2986 argument. This allows a manifest to prevent replacement of critical 2987 parameters. 2989 Available parameters are defined in Section 8.7.5. 2991 suit-directive-override-parameters does not specify a reporting 2992 policy. 2994 8.7.7.7. suit-directive-fetch 2996 suit-directive-fetch instructs the manifest processor to obtain one 2997 or more manifests or payloads, as specified by the manifest index and 2998 component index, respectively. 3000 suit-directive-fetch can target one or more manifests and one or more 3001 payloads. suit-directive-fetch retrieves each component and each 3002 manifest listed in component-index and dependency-index, 3003 respectively. If component-index or dependency-index is True, 3004 instead of an integer, then all current manifest components/manifests 3005 are fetched. The current manifest's dependent-components are not 3006 automatically fetched. In order to pre-fetch these, they MUST be 3007 specified in a component-index integer. 3009 suit-directive-fetch typically takes no arguments unless one is 3010 needed to modify fetch behavior. If an argument is needed, it must 3011 be wrapped in a bstr and set in suit-parameter-fetch-arguments. 3013 suit-directive-fetch reads the URI parameter to find the source of 3014 the fetch it performs. 3016 The behavior of suit-directive-fetch can be modified by setting one 3017 or more of SUIT_Parameter_Encryption_Info, 3018 SUIT_Parameter_Compression_Info, SUIT_Parameter_Unpack_Info. These 3019 three parameters each activate and configure a processing step that 3020 can be applied to the data that is transferred during suit-directive- 3021 fetch. 3023 8.7.7.8. suit-directive-fetch-uri-list 3025 suit-directive-fetch-uri-list uses the same semantics as suit- 3026 directive-fetch (Section 8.7.7.7), except that it iterates over the 3027 URI List (Section 8.7.5.20) to select a URI to fetch from. 3029 8.7.7.9. suit-directive-copy 3031 suit-directive-copy instructs the manifest processor to obtain one or 3032 more payloads, as specified by the component index. As described in 3033 Section 6.5 component index may be a single integer, a list of 3034 integers, or True. suit-directive-copy retrieves each component 3035 specified by the current component-index, respectively. The current 3036 manifest's dependent-components are not automatically copied. In 3037 order to copy these, they MUST be specified in a component-index 3038 integer. 3040 The behavior of suit-directive-copy can be modified by setting one or 3041 more of SUIT_Parameter_Encryption_Info, 3042 SUIT_Parameter_Compression_Info, SUIT_Parameter_Unpack_Info. These 3043 three parameters each activate and configure a processing step that 3044 can be applied to the data that is transferred during suit-directive- 3045 copy. 3047 suit-directive-copy reads its source from suit-parameter-source- 3048 component (Section 8.7.5.14). 3050 If either the source component parameter or the source component 3051 itself is absent, this command fails. 3053 8.7.7.10. suit-directive-run 3055 suit-directive-run directs the manifest processor to transfer 3056 execution to the current Component Index. When this is invoked, the 3057 manifest processor MAY be unloaded and execution continues in the 3058 Component Index. Arguments are provided to suit-directive-run 3059 through suit-parameter-run-arguments (Section 8.7.5.15) and are 3060 forwarded to the executable code located in Component Index in an 3061 application-specific way. For example, this could form the Linux 3062 Kernel Command Line if booting a Linux device. 3064 If the executable code at Component Index is constructed in such a 3065 way that it does not unload the manifest processor, then the manifest 3066 processor may resume execution after the executable completes. This 3067 allows the manifest processor to invoke suitable helpers and to 3068 verify them with image conditions. 3070 8.7.7.11. suit-directive-wait 3072 suit-directive-wait directs the manifest processor to pause until a 3073 specified event occurs. Some possible events include: 3075 1. Authorization 3077 2. External Power 3079 3. Network availability 3081 4. Other Device Firmware Version 3083 5. Time 3085 6. Time of Day 3087 7. Day of Week 3089 8.7.7.12. suit-directive-run-sequence 3091 To enable conditional commands, and to allow several strictly ordered 3092 sequences to be executed out-of-order, suit-directive-run-sequence 3093 allows the manifest processor to execute its argument as a 3094 SUIT_Command_Sequence. The argument must be wrapped in a bstr. 3096 When a sequence is executed, any failure of a condition causes 3097 immediate termination of the sequence. 3099 When suit-directive-run-sequence completes, it forwards the last 3100 status code that occurred in the sequence. If the Soft Failure 3101 parameter is true, then suit-directive-run-sequence only fails when a 3102 directive in the argument sequence fails. 3104 suit-parameter-soft-failure (Section 8.7.5.23) defaults to False when 3105 suit-directive-run-sequence begins. Its value is discarded when 3106 suit-directive-run-sequence terminates. 3108 8.7.7.13. suit-directive-swap 3110 suit-directive-swap instructs the manifest processor to move the 3111 source to the destination and the destination to the source 3112 simultaneously. Swap has nearly identical semantics to suit- 3113 directive-copy except that suit-directive-swap replaces the source 3114 with the current contents of the destination in an application- 3115 defined way. As with suit-directive-copy, if the source component is 3116 missing, this command fails. 3118 If SUIT_Parameter_Compression_Info or SUIT_Parameter_Encryption_Info 3119 are present, they MUST be handled in a symmetric way, so that the 3120 source is decompressed into the destination and the destination is 3121 compressed into the source. The source is decrypted into the 3122 destination and the destination is encrypted into the source. suit- 3123 directive-swap is OPTIONAL to implement. 3125 8.7.8. Integrity Check Values 3127 When the CoSWID, Text section, or any Command Sequence of the Update 3128 Procedure is made severable, it is moved to the Envelope and replaced 3129 with a SUIT_Digest. The SUIT_Digest is computed over the entire bstr 3130 enclosing the Manifest element that has been moved to the Envelope. 3131 Each element that is made severable from the Manifest is placed in 3132 the Envelope. The keys for the envelope elements have the same 3133 values as the keys for the manifest elements. 3135 Each Integrity Check Value covers the corresponding Envelope Element 3136 as described in Section 8.8. 3138 8.8. Severable Elements 3140 Because the manifest can be used by different actors at different 3141 times, some parts of the manifest can be removed or "Severed" without 3142 affecting later stages of the lifecycle. Severing of information is 3143 achieved by separating that information from the signed container so 3144 that removing it does not affect the signature. This means that 3145 ensuring integrity of severable parts of the manifest is a 3146 requirement for the signed portion of the manifest. Severing some 3147 parts makes it possible to discard parts of the manifest that are no 3148 longer necessary. This is important because it allows the storage 3149 used by the manifest to be greatly reduced. For example, no text 3150 size limits are needed if text is removed from the manifest prior to 3151 delivery to a constrained device. 3153 Elements are made severable by removing them from the manifest, 3154 encoding them in a bstr, and placing a SUIT_Digest of the bstr in the 3155 manifest so that they can still be authenticated. The SUIT_Digest 3156 typically consumes 4 bytes more than the size of the raw digest, 3157 therefore elements smaller than (Digest Bits)/8 + 4 SHOULD NOT be 3158 severable. Elements larger than (Digest Bits)/8 + 4 MAY be 3159 severable, while elements that are much larger than (Digest Bits)/8 + 3160 4 SHOULD be severable. 3162 Because of this, all command sequences in the manifest are encoded in 3163 a bstr so that there is a single code path needed for all command 3164 sequences. 3166 9. Access Control Lists 3168 To manage permissions in the manifest, there are three models that 3169 can be used. 3171 First, the simplest model requires that all manifests are 3172 authenticated by a single trusted key. This mode has the advantage 3173 that only a root manifest needs to be authenticated, since all of its 3174 dependencies have digests included in the root manifest. 3176 This simplest model can be extended by adding key delegation without 3177 much increase in complexity. 3179 A second model requires an ACL to be presented to the Recipient, 3180 authenticated by a trusted party or stored on the Recipient. This 3181 ACL grants access rights for specific component IDs or Component 3182 Identifier prefixes to the listed identities or identity groups. Any 3183 identity can verify an image digest, but fetching into or fetching 3184 from a Component Identifier requires approval from the ACL. 3186 A third model allows a Recipient to provide even more fine-grained 3187 controls: The ACL lists the Component Identifier or Component 3188 Identifier prefix that an identity can use, and also lists the 3189 commands and parameters that the identity can use in combination with 3190 that Component Identifier. 3192 10. SUIT Digest Container 3194 RFC 8152 [RFC8152] provides containers for signature, MAC, and 3195 encryption, but no basic digest container. The container needed for 3196 a digest requires a type identifier and a container for the raw 3197 digest data. Some forms of digest may require additional parameters. 3198 These can be added following the digest. 3200 The SUIT digest is a CBOR List containing two elements: a suit- 3201 digest-algorithm-id and a bstr containing the bytes of the digest. 3203 11. IANA Considerations 3205 IANA is requested to: 3207 - allocate CBOR tag 48 in the CBOR Tags registry for the SUIT 3208 Envelope. 3210 - allocate CBOR tag 480 in the CBOR Tags registry for the SUIT 3211 Manifest. 3213 - allocate media type application/suit-envelope in the Media Types 3214 registry. 3216 - setup several registries as described below. 3218 IANA is requested to setup a registry for SUIT manifests. Several 3219 registries defined in the subsections below need to be created. 3221 For each registry, values 0-23 are Standards Action, 24-255 are IETF 3222 Review, 256-65535 are Expert Review, and 65536 or greater are First 3223 Come First Served. 3225 Negative values -23 to 0 are Experimental Use, -24 and lower are 3226 Private Use. 3228 11.1. SUIT Commands 3230 +-------+------------+-----------------------------------+----------+ 3231 | Label | Name | Reference | | 3232 +-------+------------+-----------------------------------+----------+ 3233 | 1 | Vendor | Section 8.7.6.1 | | 3234 | | Identifier | | | 3235 | | | | | 3236 | 2 | Class | Section 8.7.6.1 | | 3237 | | Identifier | | | 3238 | | | | | 3239 | 3 | Image | Section 8.7.6.2 | | 3240 | | Match | | | 3241 | | | | | 3242 | 4 | Use Before | Section 8.7.6.4 | | 3243 | | | | | 3244 | 5 | Component | Section 8.7.6.5 | | 3245 | | Offset | | | 3246 | | | | | 3247 | 12 | Set | Section 8.7.7.1 | | 3248 | | Component | | | 3249 | | Index | | | 3250 | | | | | 3251 | 13 | Set | Section 8.7.7.2 | | 3252 | | Dependency | | | 3253 | | Index | | | 3254 | | | | | 3255 | 14 | Abort | | | 3256 | | | | | 3257 | 15 | Try Each | Section 8.7.7.3 | | 3258 | | | | | 3259 | 16 | Reserved | | | 3260 | | | | | 3261 | 17 | Reserved | | | 3262 | | | | | 3263 | 18 | Process | suit-directive-process-dependency | Section | 3264 | | Dependency | | 8.7.7.4 | 3265 | | | | | 3266 | 19 | Set | Section 8.7.7.5 | | 3267 | | Parameters | | | 3268 | | | | | 3269 | 20 | Override | Section 8.7.7.6 | | 3270 | | Parameters | | | 3271 | | | | | 3272 | 21 | Fetch | Section 8.7.7.7 | | 3273 | | | | | 3274 | 22 | Copy | Section 8.7.7.9 | | 3275 | | | | | 3276 | 23 | Run | Section 8.7.7.10 | | 3277 | | | | | 3278 | 24 | Device | Section 8.7.6.1 | | 3279 | | Identifier | | | 3280 | | | | | 3281 | 25 | Image Not | Section 8.7.6.3 | | 3282 | | Match | | | 3283 | | | | | 3284 | 26 | Minimum | Section 8.7.6.6 | | 3285 | | Battery | | | 3286 | | | | | 3287 | 27 | Update | Section 8.7.6.7 | | 3288 | | Authorized | | | 3289 | | | | | 3290 | 28 | Version | Section 8.7.6.8 | | 3291 | | | | | 3292 | 29 | Wait For | Section 8.7.7.11 | | 3293 | | Event | | | 3294 | | | | | 3295 | 30 | Fetch URI | Section 8.7.7.8 | | 3296 | | List | | | 3297 | | | | | 3298 | 31 | Swap | Section 8.7.7.13 | | 3299 | | | | | 3300 | 32 | Run | Section 8.7.7.12 | | 3301 | | Sequence | | | 3302 | | | | | 3303 | nint | Custom | Section 8.7.6.10 | | 3304 | | Condition | | | 3305 +-------+------------+-----------------------------------+----------+ 3307 11.2. SUIT Parameters 3308 +-------+------------------+---------------------------+ 3309 | Label | Name | Reference | 3310 +-------+------------------+---------------------------+ 3311 | 1 | Vendor ID | Section 8.7.5.3 | 3312 | | | | 3313 | 2 | Class ID | Section 8.7.5.4 | 3314 | | | | 3315 | 3 | Image Digest | Section 8.7.5.6 | 3316 | | | | 3317 | 4 | Use Before | Section 8.7.5.8 | 3318 | | | | 3319 | 5 | Component Offset | Section 8.7.5.9 | 3320 | | | | 3321 | 12 | Strict Order | Section 8.7.5.22 | 3322 | | | | 3323 | 13 | Soft Failure | Section 8.7.5.23 | 3324 | | | | 3325 | 14 | Image Size | Section 8.7.5.7 | 3326 | | | | 3327 | 18 | Encryption Info | Section 8.7.5.10 | 3328 | | | | 3329 | 19 | Compression Info | Section 8.7.5.11 | 3330 | | | | 3331 | 20 | Unpack Info | Section 8.7.5.12 | 3332 | | | | 3333 | 21 | URI | Section 8.7.5.13 | 3334 | | | | 3335 | 22 | Source Component | Section 8.7.5.14 | 3336 | | | | 3337 | 23 | Run Args | Section 8.7.5.15 | 3338 | | | | 3339 | 24 | Device ID | Section 8.7.5.5 | 3340 | | | | 3341 | 26 | Minimum Battery | Section 8.7.5.16 | 3342 | | | | 3343 | 27 | Update Priority | Section 8.7.5.17 | 3344 | | | | 3345 | 28 | Version | {{suit-parameter-version} | 3346 | | | | 3347 | 29 | Wait Info | Section 8.7.5.19 | 3348 | | | | 3349 | 30 | URI List | Section 8.7.5.20 | 3350 | | | | 3351 | nint | Custom | Section 8.7.5.24 | 3352 +-------+------------------+---------------------------+ 3354 11.3. SUIT Text Values 3356 +-------+----------------------+---------------+ 3357 | Label | Name | Reference | 3358 +-------+----------------------+---------------+ 3359 | 1 | Manifest Description | Section 8.6.4 | 3360 | | | | 3361 | 2 | Update Description | Section 8.6.4 | 3362 | | | | 3363 | 3 | Manifest JSON Source | Section 8.6.4 | 3364 | | | | 3365 | 4 | Manifest YAML Source | Section 8.6.4 | 3366 | | | | 3367 | nint | Custom | Section 8.6.4 | 3368 +-------+----------------------+---------------+ 3370 11.4. SUIT Component Text Values 3372 +-------+----------------------------+---------------+ 3373 | Label | Name | Reference | 3374 +-------+----------------------------+---------------+ 3375 | 1 | Vendor Name | Section 8.6.4 | 3376 | | | | 3377 | 2 | Model Name | Section 8.6.4 | 3378 | | | | 3379 | 3 | Vendor Domain | Section 8.6.4 | 3380 | | | | 3381 | 4 | Model Info | Section 8.6.4 | 3382 | | | | 3383 | 5 | Component Description | Section 8.6.4 | 3384 | | | | 3385 | 6 | Component Version | Section 8.6.4 | 3386 | | | | 3387 | 7 | Component Version Required | Section 8.6.4 | 3388 | | | | 3389 | nint | Custom | Section 8.6.4 | 3390 +-------+----------------------------+---------------+ 3392 11.5. SUIT Algorithm Identifiers 3394 11.5.1. SUIT Digest Algorithm Identifiers 3395 +-------+----------+------------+ 3396 | Label | Name | | 3397 +-------+----------+------------+ 3398 | 1 | SHA224 | Section 10 | 3399 | | | | 3400 | 2 | SHA256 | Section 10 | 3401 | | | | 3402 | 3 | SHA384 | Section 10 | 3403 | | | | 3404 | 4 | SHA512 | Section 10 | 3405 | | | | 3406 | 5 | SHA3-224 | Section 10 | 3407 | | | | 3408 | 6 | SHA3-256 | Section 10 | 3409 | | | | 3410 | 7 | SHA3-384 | Section 10 | 3411 | | | | 3412 | 8 | SHA3-512 | Section 10 | 3413 +-------+----------+------------+ 3415 11.5.2. SUIT Compression Algorithm Identifiers 3417 +-------+--------+------------------+ 3418 | Label | Name | Reference | 3419 +-------+--------+------------------+ 3420 | 1 | zlib | Section 8.7.5.11 | 3421 | | | | 3422 | 2 | Brotli | Section 8.7.5.11 | 3423 | | | | 3424 | 3 | zstd | Section 8.7.5.11 | 3425 +-------+--------+------------------+ 3427 11.5.3. Unpack Algorithms 3429 +-------+------+------------------+ 3430 | Label | Name | Reference | 3431 +-------+------+------------------+ 3432 | 1 | HEX | Section 8.7.5.12 | 3433 | | | | 3434 | 2 | ELF | Section 8.7.5.12 | 3435 | | | | 3436 | 3 | COFF | Section 8.7.5.12 | 3437 | | | | 3438 | 4 | SREC | Section 8.7.5.12 | 3439 +-------+------+------------------+ 3441 12. Security Considerations 3443 This document is about a manifest format protecting and describing 3444 how to retrieve, install, and invoke firmware images and as such it 3445 is part of a larger solution for delivering firmware updates to IoT 3446 devices. A detailed security treatment can be found in the 3447 architecture [I-D.ietf-suit-architecture] and in the information 3448 model [I-D.ietf-suit-information-model] documents. 3450 13. Acknowledgements 3452 We would like to thank the following persons for their support in 3453 designing this mechanism: 3455 - Milosch Meriac 3457 - Geraint Luff 3459 - Dan Ros 3461 - John-Paul Stanford 3463 - Hugo Vincent 3465 - Carsten Bormann 3467 - Oeyvind Roenningstad 3469 - Frank Audun Kvamtroe 3471 - Krzysztof Chruściński 3473 - Andrzej Puzdrowski 3475 - Michael Richardson 3477 - David Brown 3479 - Emmanuel Baccelli 3481 14. References 3483 14.1. Normative References 3485 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3486 Requirement Levels", BCP 14, RFC 2119, 3487 DOI 10.17487/RFC2119, March 1997, 3488 . 3490 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3491 Resource Identifier (URI): Generic Syntax", STD 66, 3492 RFC 3986, DOI 10.17487/RFC3986, January 2005, 3493 . 3495 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 3496 Unique IDentifier (UUID) URN Namespace", RFC 4122, 3497 DOI 10.17487/RFC4122, July 2005, 3498 . 3500 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 3501 RFC 8152, DOI 10.17487/RFC8152, July 2017, 3502 . 3504 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3505 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3506 May 2017, . 3508 14.2. Informative References 3510 [COFF] Wikipedia, ., "Common Object File Format (COFF)", 2020, 3511 . 3513 [ELF] Wikipedia, ., "Executable and Linkable Format (ELF)", 3514 2020, . 3517 [HEX] Wikipedia, ., "Intel HEX", 2020, 3518 . 3520 [I-D.ietf-cbor-tags-oid] 3521 Bormann, C. and S. Leonard, "Concise Binary Object 3522 Representation (CBOR) Tags for Object Identifiers", draft- 3523 ietf-cbor-tags-oid-03 (work in progress), November 2020. 3525 [I-D.ietf-sacm-coswid] 3526 Birkholz, H., Fitzgerald-McKay, J., Schmidt, C., and D. 3527 Waltermire, "Concise Software Identification Tags", draft- 3528 ietf-sacm-coswid-16 (work in progress), November 2020. 3530 [I-D.ietf-suit-architecture] 3531 Moran, B., Tschofenig, H., Brown, D., and M. Meriac, "A 3532 Firmware Update Architecture for Internet of Things", 3533 draft-ietf-suit-architecture-14 (work in progress), 3534 October 2020. 3536 [I-D.ietf-suit-information-model] 3537 Moran, B., Tschofenig, H., and H. Birkholz, "An 3538 Information Model for Firmware Updates in IoT Devices", 3539 draft-ietf-suit-information-model-08 (work in progress), 3540 October 2020. 3542 [I-D.ietf-teep-architecture] 3543 Pei, M., Tschofenig, H., Thaler, D., and D. Wheeler, 3544 "Trusted Execution Environment Provisioning (TEEP) 3545 Architecture", draft-ietf-teep-architecture-13 (work in 3546 progress), November 2020. 3548 [I-D.kucherawy-rfc8478bis] 3549 Collet, Y. and M. Kucherawy, "Zstandard Compression and 3550 the application/zstd Media Type", draft-kucherawy- 3551 rfc8478bis-05 (work in progress), April 2020. 3553 [RFC1950] Deutsch, P. and J-L. Gailly, "ZLIB Compressed Data Format 3554 Specification version 3.3", RFC 1950, 3555 DOI 10.17487/RFC1950, May 1996, 3556 . 3558 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 3559 Constrained-Node Networks", RFC 7228, 3560 DOI 10.17487/RFC7228, May 2014, 3561 . 3563 [RFC7932] Alakuijala, J. and Z. Szabadka, "Brotli Compressed Data 3564 Format", RFC 7932, DOI 10.17487/RFC7932, July 2016, 3565 . 3567 [RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, 3568 "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, 3569 May 2018, . 3571 [RFC8747] Jones, M., Seitz, L., Selander, G., Erdtman, S., and H. 3572 Tschofenig, "Proof-of-Possession Key Semantics for CBOR 3573 Web Tokens (CWTs)", RFC 8747, DOI 10.17487/RFC8747, March 3574 2020, . 3576 [SREC] Wikipedia, ., "SREC (file format)", 2020, 3577 . 3579 [YAML] "YAML Ain't Markup Language", 2020, . 3581 Appendix A. A. Full CDDL 3583 In order to create a valid SUIT Manifest document the structure of 3584 the corresponding CBOR message MUST adhere to the following CDDL data 3585 definition. 3587 SUIT_Envelope_Tagged = #6.48(SUIT_Envelope) 3588 SUIT_Envelope = { 3589 ? suit-delegation => bstr .cbor SUIT_Delegation, 3590 suit-authentication-wrapper => bstr .cbor SUIT_Authentication, 3591 suit-manifest => bstr .cbor SUIT_Manifest, 3592 SUIT_Severable_Manifest_Members, 3593 * SUIT_Integrated_Payload, 3594 * SUIT_Integrated_Dependency, 3595 * $$SUIT_Envelope_Extensions, 3596 * (int => bstr) 3597 } 3599 SUIT_Delegation = [ + [ + bstr .cbor CWT ] ] 3601 CWT = SUIT_Authentication_Block 3603 SUIT_Authentication = [ 3604 bstr .cbor SUIT_Digest, 3605 * bstr .cbor SUIT_Authentication_Block 3606 ] 3608 SUIT_Digest = [ 3609 suit-digest-algorithm-id : suit-digest-algorithm-ids, 3610 suit-digest-bytes : bstr, 3611 * $$SUIT_Digest-extensions 3612 ] 3614 ; Named Information Hash Algorithm Identifiers 3615 suit-digest-algorithm-ids /= algorithm-id-sha224 3616 suit-digest-algorithm-ids /= algorithm-id-sha256 3617 suit-digest-algorithm-ids /= algorithm-id-sha384 3618 suit-digest-algorithm-ids /= algorithm-id-sha512 3619 suit-digest-algorithm-ids /= algorithm-id-sha3-224 3620 suit-digest-algorithm-ids /= algorithm-id-sha3-256 3621 suit-digest-algorithm-ids /= algorithm-id-sha3-384 3622 suit-digest-algorithm-ids /= algorithm-id-sha3-512 3624 SUIT_Authentication_Block /= COSE_Mac_Tagged 3625 SUIT_Authentication_Block /= COSE_Sign_Tagged 3626 SUIT_Authentication_Block /= COSE_Mac0_Tagged 3627 SUIT_Authentication_Block /= COSE_Sign1_Tagged 3628 COSE_Mac_Tagged = any 3629 COSE_Sign_Tagged = any 3630 COSE_Mac0_Tagged = any 3631 COSE_Sign1_Tagged = any 3632 COSE_Encrypt_Tagged = any 3633 COSE_Encrypt0_Tagged = any 3635 SUIT_Severable_Manifest_Members = ( 3636 ? suit-dependency-resolution => bstr .cbor SUIT_Command_Sequence, 3637 ? suit-payload-fetch => bstr .cbor SUIT_Command_Sequence, 3638 ? suit-install => bstr .cbor SUIT_Command_Sequence, 3639 ? suit-text => bstr .cbor SUIT_Text_Map, 3640 ? suit-coswid => bstr .cbor concise-software-identity, 3641 * $$SUIT_severable-members-extensions, 3642 ) 3644 SUIT_Integrated_Payload = (suit-integrated-payload-key => bstr) 3645 SUIT_Integrated_Dependency = ( 3646 suit-integrated-payload-key => bstr .cbor SUIT_Envelope 3647 ) 3648 suit-integrated-payload-key = nint / uint .ge 24 3650 SUIT_Manifest_Tagged = #6.480(SUIT_Manifest) 3652 SUIT_Manifest = { 3653 suit-manifest-version => 1, 3654 suit-manifest-sequence-number => uint, 3655 suit-common => bstr .cbor SUIT_Common, 3656 ? suit-reference-uri => tstr, 3657 SUIT_Severable_Manifest_Members, 3658 SUIT_Severable_Members_Digests, 3659 SUIT_Unseverable_Members, 3660 * $$SUIT_Manifest_Extensions, 3661 } 3663 SUIT_Unseverable_Members = ( 3664 ? suit-validate => bstr .cbor SUIT_Command_Sequence, 3665 ? suit-load => bstr .cbor SUIT_Command_Sequence, 3666 ? suit-run => bstr .cbor SUIT_Command_Sequence, 3667 * $$unserverble-manifest-member-extensions, 3668 ) 3670 SUIT_Severable_Members_Digests = ( 3671 ? suit-dependency-resolution => SUIT_Digest, 3672 ? suit-payload-fetch => SUIT_Digest, 3673 ? suit-install => SUIT_Digest, 3674 ? suit-text => SUIT_Digest, 3675 ? suit-coswid => SUIT_Digest, 3676 * $$severable-manifest-members-digests-extensions 3677 ) 3679 SUIT_Common = { 3680 ? suit-dependencies => SUIT_Dependencies, 3681 ? suit-components => SUIT_Components, 3682 ? suit-common-sequence => bstr .cbor SUIT_Common_Sequence, 3683 * $$SUIT_Common-extensions, 3684 } 3686 SUIT_Dependencies = [ + SUIT_Dependency ] 3687 SUIT_Components = [ + SUIT_Component_Identifier ] 3689 concise-software-identity = any 3691 SUIT_Dependency = { 3692 suit-dependency-digest => SUIT_Digest, 3693 ? suit-dependency-prefix => SUIT_Component_Identifier, 3694 * $$SUIT_Dependency-extensions, 3695 } 3697 SUIT_Component_Identifier = [* bstr] 3699 SUIT_Common_Sequence = [ 3700 + ( SUIT_Condition // SUIT_Common_Commands ) 3701 ] 3703 SUIT_Common_Commands //= (suit-directive-set-component-index, IndexArg) 3704 SUIT_Common_Commands //= (suit-directive-set-dependency-index, IndexArg) 3705 SUIT_Common_Commands //= (suit-directive-run-sequence, 3706 bstr .cbor SUIT_Command_Sequence) 3707 SUIT_Common_Commands //= (suit-directive-try-each, 3708 SUIT_Directive_Try_Each_Argument) 3709 SUIT_Common_Commands //= (suit-directive-set-parameters, 3710 {+ SUIT_Parameters}) 3711 SUIT_Common_Commands //= (suit-directive-override-parameters, 3712 {+ SUIT_Parameters}) 3714 IndexArg /= uint 3715 IndexArg /= bool 3716 IndexArg /= [+uint] 3718 SUIT_Command_Sequence = [ + ( 3719 SUIT_Condition // SUIT_Directive // SUIT_Command_Custom 3720 ) ] 3722 SUIT_Command_Custom = (suit-command-custom, bstr/tstr/int/nil) 3723 SUIT_Condition //= (suit-condition-vendor-identifier, SUIT_Rep_Policy) 3724 SUIT_Condition //= (suit-condition-class-identifier, SUIT_Rep_Policy) 3725 SUIT_Condition //= (suit-condition-device-identifier, SUIT_Rep_Policy) 3726 SUIT_Condition //= (suit-condition-image-match, SUIT_Rep_Policy) 3727 SUIT_Condition //= (suit-condition-image-not-match, SUIT_Rep_Policy) 3728 SUIT_Condition //= (suit-condition-use-before, SUIT_Rep_Policy) 3729 SUIT_Condition //= (suit-condition-minimum-battery, SUIT_Rep_Policy) 3730 SUIT_Condition //= (suit-condition-update-authorized, SUIT_Rep_Policy) 3731 SUIT_Condition //= (suit-condition-version, SUIT_Rep_Policy) 3732 SUIT_Condition //= (suit-condition-component-offset, SUIT_Rep_Policy) 3733 SUIT_Condition //= (suit-condition-abort, SUIT_Rep_Policy) 3735 SUIT_Directive //= (suit-directive-set-component-index, IndexArg) 3736 SUIT_Directive //= (suit-directive-set-dependency-index, IndexArg) 3737 SUIT_Directive //= (suit-directive-run-sequence, 3738 bstr .cbor SUIT_Command_Sequence) 3739 SUIT_Directive //= (suit-directive-try-each, 3740 SUIT_Directive_Try_Each_Argument) 3741 SUIT_Directive //= (suit-directive-process-dependency, SUIT_Rep_Policy) 3742 SUIT_Directive //= (suit-directive-set-parameters, 3743 {+ SUIT_Parameters}) 3744 SUIT_Directive //= (suit-directive-override-parameters, 3745 {+ SUIT_Parameters}) 3746 SUIT_Directive //= (suit-directive-fetch, SUIT_Rep_Policy) 3747 SUIT_Directive //= (suit-directive-copy, SUIT_Rep_Policy) 3748 SUIT_Directive //= (suit-directive-swap, SUIT_Rep_Policy) 3749 SUIT_Directive //= (suit-directive-run, SUIT_Rep_Policy) 3750 SUIT_Directive //= (suit-directive-wait, SUIT_Rep_Policy) 3751 SUIT_Directive //= (suit-directive-fetch-uri-list, SUIT_Rep_Policy) 3753 SUIT_Directive_Try_Each_Argument = [ 3754 + bstr .cbor SUIT_Command_Sequence, 3755 nil / bstr .cbor SUIT_Command_Sequence 3756 ] 3758 SUIT_Rep_Policy = uint .bits suit-reporting-bits 3760 suit-reporting-bits = &( 3761 suit-send-record-success : 0, 3762 suit-send-record-failure : 1, 3763 suit-send-sysinfo-success : 2, 3764 suit-send-sysinfo-failure : 3 3765 ) 3767 SUIT_Wait_Event = { + SUIT_Wait_Events } 3769 SUIT_Wait_Events //= (suit-wait-event-authorization => int) 3770 SUIT_Wait_Events //= (suit-wait-event-power => int) 3771 SUIT_Wait_Events //= (suit-wait-event-network => int) 3772 SUIT_Wait_Events //= (suit-wait-event-other-device-version 3773 => SUIT_Wait_Event_Argument_Other_Device_Version) 3774 SUIT_Wait_Events //= (suit-wait-event-time => uint); Timestamp 3775 SUIT_Wait_Events //= (suit-wait-event-time-of-day 3776 => uint); Time of Day (seconds since 00:00:00) 3777 SUIT_Wait_Events //= (suit-wait-event-day-of-week 3778 => uint); Days since Sunday 3780 SUIT_Wait_Event_Argument_Other_Device_Version = [ 3781 other-device: bstr, 3782 other-device-version: [ + SUIT_Parameter_Version_Match ] 3783 ] 3785 SUIT_Parameters //= (suit-parameter-vendor-identifier => 3786 (RFC4122_UUID / cbor-pen)) 3787 cbor-pen = #6.112(bstr) 3789 SUIT_Parameters //= (suit-parameter-class-identifier => RFC4122_UUID) 3790 SUIT_Parameters //= (suit-parameter-image-digest 3791 => bstr .cbor SUIT_Digest) 3792 SUIT_Parameters //= (suit-parameter-image-size => uint) 3793 SUIT_Parameters //= (suit-parameter-use-before => uint) 3794 SUIT_Parameters //= (suit-parameter-component-offset => uint) 3796 SUIT_Parameters //= (suit-parameter-encryption-info 3797 => bstr .cbor SUIT_Encryption_Info) 3798 SUIT_Parameters //= (suit-parameter-compression-info 3799 => bstr .cbor SUIT_Compression_Info) 3800 SUIT_Parameters //= (suit-parameter-unpack-info 3801 => bstr .cbor SUIT_Unpack_Info) 3803 SUIT_Parameters //= (suit-parameter-uri => tstr) 3804 SUIT_Parameters //= (suit-parameter-source-component => uint) 3805 SUIT_Parameters //= (suit-parameter-run-args => bstr) 3807 SUIT_Parameters //= (suit-parameter-device-identifier => RFC4122_UUID) 3808 SUIT_Parameters //= (suit-parameter-minimum-battery => uint) 3809 SUIT_Parameters //= (suit-parameter-update-priority => uint) 3810 SUIT_Parameters //= (suit-parameter-version => 3811 SUIT_Parameter_Version_Match) 3812 SUIT_Parameters //= (suit-parameter-wait-info => 3813 bstr .cbor SUIT_Wait_Event) 3815 SUIT_Parameters //= (suit-parameter-custom => int/bool/tstr/bstr) 3817 SUIT_Parameters //= (suit-parameter-strict-order => bool) 3818 SUIT_Parameters //= (suit-parameter-soft-failure => bool) 3819 SUIT_Parameters //= (suit-parameter-uri-list => 3820 bstr .cbor SUIT_URI_List) 3822 RFC4122_UUID = bstr .size 16 3824 SUIT_Parameter_Version_Match = [ 3825 suit-condition-version-comparison-type: 3826 SUIT_Condition_Version_Comparison_Types, 3827 suit-condition-version-comparison-value: 3828 SUIT_Condition_Version_Comparison_Value 3829 ] 3830 SUIT_Condition_Version_Comparison_Types /= 3831 suit-condition-version-comparison-greater 3832 SUIT_Condition_Version_Comparison_Types /= 3833 suit-condition-version-comparison-greater-equal 3834 SUIT_Condition_Version_Comparison_Types /= 3835 suit-condition-version-comparison-equal 3836 SUIT_Condition_Version_Comparison_Types /= 3837 suit-condition-version-comparison-lesser-equal 3838 SUIT_Condition_Version_Comparison_Types /= 3839 suit-condition-version-comparison-lesser 3841 suit-condition-version-comparison-greater = 1 3842 suit-condition-version-comparison-greater-equal = 2 3843 suit-condition-version-comparison-equal = 3 3844 suit-condition-version-comparison-lesser-equal = 4 3845 suit-condition-version-comparison-lesser = 5 3847 SUIT_Condition_Version_Comparison_Value = [+int] 3849 SUIT_Encryption_Info = COSE_Encrypt_Tagged/COSE_Encrypt0_Tagged 3850 SUIT_Compression_Info = { 3851 suit-compression-algorithm => SUIT_Compression_Algorithms, 3852 * $$SUIT_Compression_Info-extensions, 3853 } 3855 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_zlib 3856 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_brotli 3857 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_zstd 3859 SUIT_Compression_Algorithm_zlib = 1 3860 SUIT_Compression_Algorithm_brotli = 2 3861 SUIT_Compression_Algorithm_zstd = 3 3863 SUIT_Unpack_Info = { 3864 suit-unpack-algorithm => SUIT_Unpack_Algorithms, 3865 * $$SUIT_Unpack_Info-extensions, 3867 } 3869 SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Hex 3870 SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Elf 3871 SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Coff 3872 SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Srec 3874 SUIT_Unpack_Algorithm_Hex = 1 3875 SUIT_Unpack_Algorithm_Elf = 2 3876 SUIT_Unpack_Algorithm_Coff = 3 3877 SUIT_Unpack_Algorithm_Srec = 4 3879 SUIT_URI_List = [+ tstr ] 3881 SUIT_Text_Map = { 3882 * SUIT_Component_Identifier => { 3883 SUIT_Text_Component_Keys 3884 }, 3885 SUIT_Text_Keys 3886 } 3888 SUIT_Text_Component_Keys = ( 3889 ? suit-text-vendor-name => tstr, 3890 ? suit-text-model-name => tstr, 3891 ? suit-text-vendor-domain => tstr, 3892 ? suit-text-model-info => tstr, 3893 ? suit-text-component-description => tstr, 3894 ? suit-text-component-version => tstr, 3895 ? suit-text-version-required => tstr, 3896 * $$suit-text-component-key-extensions 3897 ) 3899 SUIT_Text_Keys = ( 3900 ? suit-text-manifest-description => tstr, 3901 ? suit-text-update-description => tstr, 3902 ? suit-text-manifest-json-source => tstr, 3903 ? suit-text-manifest-yaml-source => tstr, 3904 * $$suit-text-key-extensions 3905 ) 3907 suit-delegation = 1 3908 suit-authentication-wrapper = 2 3909 suit-manifest = 3 3911 algorithm-id-sha224 = 1 3912 algorithm-id-sha256 = 2 3913 algorithm-id-sha384 = 3 3914 algorithm-id-sha512 = 4 3915 algorithm-id-sha3-224 = 5 3916 algorithm-id-sha3-256 = 6 3917 algorithm-id-sha3-384 = 7 3918 algorithm-id-sha3-512 = 8 3920 suit-manifest-version = 1 3921 suit-manifest-sequence-number = 2 3922 suit-common = 3 3923 suit-reference-uri = 4 3924 suit-dependency-resolution = 7 3925 suit-payload-fetch = 8 3926 suit-install = 9 3927 suit-validate = 10 3928 suit-load = 11 3929 suit-run = 12 3930 suit-text = 13 3931 suit-coswid = 14 3933 suit-dependencies = 1 3934 suit-components = 2 3935 suit-common-sequence = 4 3937 suit-dependency-digest = 1 3938 suit-dependency-prefix = 2 3940 suit-command-custom = nint 3942 suit-condition-vendor-identifier = 1 3943 suit-condition-class-identifier = 2 3944 suit-condition-image-match = 3 3945 suit-condition-use-before = 4 3946 suit-condition-component-offset = 5 3948 suit-condition-abort = 14 3949 suit-condition-device-identifier = 24 3950 suit-condition-image-not-match = 25 3951 suit-condition-minimum-battery = 26 3952 suit-condition-update-authorized = 27 3953 suit-condition-version = 28 3955 suit-directive-set-component-index = 12 3956 suit-directive-set-dependency-index = 13 3957 suit-directive-try-each = 15 3958 ;suit-directive-do-each = 16 ; TBD 3959 ;suit-directive-map-filter = 17 ; TBD 3960 suit-directive-process-dependency = 18 3961 suit-directive-set-parameters = 19 3962 suit-directive-override-parameters = 20 3963 suit-directive-fetch = 21 3964 suit-directive-copy = 22 3965 suit-directive-run = 23 3967 suit-directive-wait = 29 3968 suit-directive-fetch-uri-list = 30 3969 suit-directive-swap = 31 3970 suit-directive-run-sequence = 32 3972 suit-wait-event-authorization = 1 3973 suit-wait-event-power = 2 3974 suit-wait-event-network = 3 3975 suit-wait-event-other-device-version = 4 3976 suit-wait-event-time = 5 3977 suit-wait-event-time-of-day = 6 3978 suit-wait-event-day-of-week = 7 3980 suit-parameter-vendor-identifier = 1 3981 suit-parameter-class-identifier = 2 3982 suit-parameter-image-digest = 3 3983 suit-parameter-use-before = 4 3984 suit-parameter-component-offset = 5 3986 suit-parameter-strict-order = 12 3987 suit-parameter-soft-failure = 13 3988 suit-parameter-image-size = 14 3990 suit-parameter-encryption-info = 18 3991 suit-parameter-compression-info = 19 3992 suit-parameter-unpack-info = 20 3993 suit-parameter-uri = 21 3994 suit-parameter-source-component = 22 3995 suit-parameter-run-args = 23 3997 suit-parameter-device-identifier = 24 3998 suit-parameter-minimum-battery = 26 3999 suit-parameter-update-priority = 27 4000 suit-parameter-version = 28 4001 suit-parameter-wait-info = 29 4002 suit-parameter-uri-list = 30 4004 suit-parameter-custom = nint 4006 suit-compression-algorithm = 1 4008 suit-unpack-algorithm = 1 4010 suit-text-manifest-description = 1 4011 suit-text-update-description = 2 4012 suit-text-manifest-json-source = 3 4013 suit-text-manifest-yaml-source = 4 4015 suit-text-vendor-name = 1 4016 suit-text-model-name = 2 4017 suit-text-vendor-domain = 3 4018 suit-text-model-info = 4 4019 suit-text-component-description = 5 4020 suit-text-component-version = 6 4021 suit-text-version-required = 7 4023 Appendix B. B. Examples 4025 The following examples demonstrate a small subset of the 4026 functionality of the manifest. Even a simple manifest processor can 4027 execute most of these manifests. 4029 The examples are signed using the following ECDSA secp256r1 key: 4031 -----BEGIN PRIVATE KEY----- 4032 MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgApZYjZCUGLM50VBC 4033 CjYStX+09jGmnyJPrpDLTz/hiXOhRANCAASEloEarguqq9JhVxie7NomvqqL8Rtv 4034 P+bitWWchdvArTsfKktsCYExwKNtrNHXi9OB3N+wnAUtszmR23M4tKiW 4035 -----END PRIVATE KEY----- 4037 The corresponding public key can be used to verify these examples: 4039 -----BEGIN PUBLIC KEY----- 4040 MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEhJaBGq4LqqvSYVcYnuzaJr6qi/Eb 4041 bz/m4rVlnIXbwK07HypLbAmBMcCjbazR14vTgdzfsJwFLbM5kdtzOLSolg== 4042 -----END PUBLIC KEY----- 4044 Each example uses SHA256 as the digest function. 4046 Note that reporting policies are declared for each non-flow-control 4047 command in these examples. The reporting policies used in the 4048 examples are described in the following tables. 4050 +-----------------------------+----------+ 4051 | Policy | Label | 4052 +-----------------------------+----------+ 4053 | suit-send-record-on-success | Rec-Pass | 4054 | | | 4055 | suit-send-record-on-failure | Rec-Fail | 4056 | | | 4057 | suit-send-sysinfo-success | Sys-Pass | 4058 | | | 4059 | suit-send-sysinfo-failure | Sys-Fail | 4060 +-----------------------------+----------+ 4062 +----------------------------+--------+---------+---------+---------+ 4063 | Command | Sys- | Sys- | Rec- | Rec- | 4064 | | Fail | Pass | Fail | Pass | 4065 +----------------------------+--------+---------+---------+---------+ 4066 | suit-condition-vendor- | 1 | 1 | 1 | 1 | 4067 | identifier | | | | | 4068 | | | | | | 4069 | suit-condition-class- | 1 | 1 | 1 | 1 | 4070 | identifier | | | | | 4071 | | | | | | 4072 | suit-condition-image-match | 1 | 1 | 1 | 1 | 4073 | | | | | | 4074 | suit-condition-component- | 0 | 1 | 0 | 1 | 4075 | offset | | | | | 4076 | | | | | | 4077 | suit-directive-fetch | 0 | 0 | 1 | 0 | 4078 | | | | | | 4079 | suit-directive-copy | 0 | 0 | 1 | 0 | 4080 | | | | | | 4081 | suit-directive-run | 0 | 0 | 1 | 0 | 4082 +----------------------------+--------+---------+---------+---------+ 4084 B.1. Example 0: Secure Boot 4086 This example covers the following templates: 4088 - Compatibility Check (Section 7.1) 4090 - Secure Boot (Section 7.2) 4092 It also serves as the minimum example. 4094 { 4095 / authentication-wrapper / 2:bstr .cbor ({ digest: bstr 4096 .cbor ([ 4097 / algorithm-id / 2 / "sha256" /, 4098 / digest-bytes / 4099 h'5c097ef64bf3bb9b494e71e1f2418eef8d466cc902f639a855ec9af3e9eddb99' 4100 ]) signatures: [ 4101 bstr .cbor (18([ 4102 / protected / bstr .cbor ({ 4103 / alg / 1:-7 / "ES256" /, 4104 }), 4105 / unprotected / { 4106 }, 4107 / payload / bstr .cbor ([ 4108 / algorithm-id / 2 / "sha256" /, 4109 / digest-bytes / 4110 h'5c097ef64bf3bb9b494e71e1f2418eef8d466cc902f639a855ec9af3e9eddb99' 4111 ]), 4112 / signature / h'60f5c3d03a3aa759bfef2ef0f5f97a93b1 4113 f5e741f7463f4385af88513a5c2957bea2d6c4cfddd03392a267aab0fc0fd515560ed5 4114 8e33fad26ac32a024c5a7143' 4115 ])) 4116 ] 4117 }), 4118 / manifest / 3:bstr .cbor ({ 4119 / manifest-version / 1:1, 4120 / manifest-sequence-number / 2:0, 4121 / common / 3:bstr .cbor ({ 4122 / components / 2:[ 4123 [h'00'] 4124 ], 4125 / common-sequence / 4:bstr .cbor ([ 4126 / directive-override-parameters / 20,{ 4127 / vendor-id / 4128 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 4129 be9d-e663e4d41ffe /, 4130 / class-id / 2:h'1492af1425695e48bf429b2d51f2ab45' 4131 / 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 4132 / image-digest / 3:bstr .cbor ([ 4133 / algorithm-id / 2 / "sha256" /, 4134 / digest-bytes / 4135 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 4136 ]), 4137 / image-size / 14:34768, 4138 } , 4139 / condition-vendor-identifier / 1,15 , 4140 / condition-class-identifier / 2,15 4141 ]), 4142 }), 4143 / validate / 10:bstr .cbor ([ 4144 / condition-image-match / 3,15 4145 ]), 4146 / run / 12:bstr .cbor ([ 4147 / directive-run / 23,2 4148 ]), 4149 }), 4150 } 4152 Total size of Envelope without COSE authentication object: 159 4154 Envelope: 4156 a2025827815824820258205c097ef64bf3bb9b494e71e1f2418eef8d466c 4157 c902f639a855ec9af3e9eddb99035871a50101020003585fa20281814100 4158 0458568614a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af14 4159 25695e48bf429b2d51f2ab450358248202582000112233445566778899aa 4160 bbccddeeff0123456789abcdeffedcba98765432100e1987d0010f020f0a 4161 4382030f0c43821702 4163 Total size of Envelope with COSE authentication object: 272 4165 Envelope with COSE authentication object: 4167 a2025898825824820258205c097ef64bf3bb9b494e71e1f2418eef8d466c 4168 c902f639a855ec9af3e9eddb99586fd28443a10126a05824820258205c09 4169 7ef64bf3bb9b494e71e1f2418eef8d466cc902f639a855ec9af3e9eddb99 4170 584060f5c3d03a3aa759bfef2ef0f5f97a93b1f5e741f7463f4385af8851 4171 3a5c2957bea2d6c4cfddd03392a267aab0fc0fd515560ed58e33fad26ac3 4172 2a024c5a7143035871a50101020003585fa202818141000458568614a401 4173 50fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b 4174 2d51f2ab450358248202582000112233445566778899aabbccddeeff0123 4175 456789abcdeffedcba98765432100e1987d0010f020f0a4382030f0c4382 4176 1702 4178 B.2. Example 1: Simultaneous Download and Installation of Payload 4180 This example covers the following templates: 4182 - Compatibility Check (Section 7.1) 4184 - Firmware Download (Section 7.3) 4186 Simultaneous download and installation of payload. No secure boot is 4187 present in this example to demonstrate a download-only manifest. 4189 { 4190 / authentication-wrapper / 2:bstr .cbor ({ digest: bstr 4191 .cbor ([ 4192 / algorithm-id / 2 / "sha256" /, 4193 / digest-bytes / 4195 h'987eec85fa99fd31d332381b9810f90b05c2e0d4f284a6f4211207ed00fff750' 4196 ]) signatures: [ 4197 bstr .cbor (18([ 4198 / protected / bstr .cbor ({ 4199 / alg / 1:-7 / "ES256" /, 4200 }), 4201 / unprotected / { 4202 }, 4203 / payload / bstr .cbor ([ 4204 / algorithm-id / 2 / "sha256" /, 4205 / digest-bytes / 4206 h'987eec85fa99fd31d332381b9810f90b05c2e0d4f284a6f4211207ed00fff750' 4207 ]), 4208 / signature / h'750141d65b4f20a88dc70c6785a67e0f4f 4209 085aead83ba2289d6e37271508cc91e0a0592f5c940c2257c9c0b26403c0ba4477f2ce 4210 37b60089fe02cde7911d1c15' 4211 ])) 4212 ] 4213 }), 4214 / manifest / 3:bstr .cbor ({ 4215 / manifest-version / 1:1, 4216 / manifest-sequence-number / 2:1, 4217 / common / 3:bstr .cbor ({ 4218 / components / 2:[ 4219 [h'00'] 4220 ], 4221 / common-sequence / 4:bstr .cbor ([ 4222 / directive-override-parameters / 20,{ 4223 / vendor-id / 4224 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 4225 be9d-e663e4d41ffe /, 4226 / class-id / 2:h'1492af1425695e48bf429b2d51f2ab45' 4227 / 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 4228 / image-digest / 3:bstr .cbor ([ 4229 / algorithm-id / 2 / "sha256" /, 4230 / digest-bytes / 4231 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 4232 ]), 4233 / image-size / 14:34768, 4234 } , 4235 / condition-vendor-identifier / 1,15 , 4236 / condition-class-identifier / 2,15 4237 ]), 4238 }), 4239 / install / 9:bstr .cbor ([ 4240 / directive-set-parameters / 19,{ 4241 / uri / 21:'http://example.com/file.bin', 4242 } , 4243 / directive-fetch / 21,2 , 4244 / condition-image-match / 3,15 4245 ]), 4246 / validate / 10:bstr .cbor ([ 4247 / condition-image-match / 3,15 4248 ]), 4249 }), 4250 } 4252 Total size of Envelope without COSE authentication object: 194 4254 Envelope: 4256 a202582781582482025820987eec85fa99fd31d332381b9810f90b05c2e0 4257 d4f284a6f4211207ed00fff750035894a50101020103585fa20281814100 4258 0458568614a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af14 4259 25695e48bf429b2d51f2ab450358248202582000112233445566778899aa 4260 bbccddeeff0123456789abcdeffedcba98765432100e1987d0010f020f09 4261 58258613a115781b687474703a2f2f6578616d706c652e636f6d2f66696c 4262 652e62696e1502030f0a4382030f 4264 Total size of Envelope with COSE authentication object: 307 4266 Envelope with COSE authentication object: 4268 a202589882582482025820987eec85fa99fd31d332381b9810f90b05c2e0 4269 d4f284a6f4211207ed00fff750586fd28443a10126a0582482025820987e 4270 ec85fa99fd31d332381b9810f90b05c2e0d4f284a6f4211207ed00fff750 4271 5840750141d65b4f20a88dc70c6785a67e0f4f085aead83ba2289d6e3727 4272 1508cc91e0a0592f5c940c2257c9c0b26403c0ba4477f2ce37b60089fe02 4273 cde7911d1c15035894a50101020103585fa202818141000458568614a401 4274 50fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b 4275 2d51f2ab450358248202582000112233445566778899aabbccddeeff0123 4276 456789abcdeffedcba98765432100e1987d0010f020f0958258613a11578 4277 1b687474703a2f2f6578616d706c652e636f6d2f66696c652e62696e1502 4278 030f0a4382030f 4280 B.3. Example 2: Simultaneous Download, Installation, Secure Boot, 4281 Severed Fields 4283 This example covers the following templates: 4285 - Compatibility Check (Section 7.1) 4287 - Secure Boot (Section 7.2) 4289 - Firmware Download (Section 7.3) 4290 This example also demonstrates severable elements (Section 5.5), and 4291 text (Section 8.6.4). 4293 { 4294 / authentication-wrapper / 2:bstr .cbor ({ digest: bstr 4295 .cbor ([ 4296 / algorithm-id / 2 / "sha256" /, 4297 / digest-bytes / 4298 h'75685579a83babd71ec8ef22fa49ac873f78a708a43a674e782ad30b6598d17a' 4299 ]) signatures: [ 4300 bstr .cbor (18([ 4301 / protected / bstr .cbor ({ 4302 / alg / 1:-7 / "ES256" /, 4303 }), 4304 / unprotected / { 4305 }, 4306 / payload / bstr .cbor ([ 4307 / algorithm-id / 2 / "sha256" /, 4308 / digest-bytes / 4309 h'75685579a83babd71ec8ef22fa49ac873f78a708a43a674e782ad30b6598d17a' 4310 ]), 4311 / signature / h'861b9bfb449125742baa648bc9d148cba4 4312 5519cca8efecf705c2165ecdecaeba8b6ce2131284e66708788d741e8779d5973fa8e2 4313 5da49eb203c81920719da949' 4314 ])) 4315 ] 4316 }), 4317 / manifest / 3:bstr .cbor ({ 4318 / manifest-version / 1:1, 4319 / manifest-sequence-number / 2:2, 4320 / common / 3:bstr .cbor ({ 4321 / components / 2:[ 4322 [h'00'] 4323 ], 4324 / common-sequence / 4:bstr .cbor ([ 4325 / directive-override-parameters / 20,{ 4326 / vendor-id / 4327 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 4328 be9d-e663e4d41ffe /, 4329 / class-id / 2:h'1492af1425695e48bf429b2d51f2ab45' 4330 / 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 4331 / image-digest / 3:bstr .cbor ([ 4332 / algorithm-id / 2 / "sha256" /, 4333 / digest-bytes / 4334 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 4335 ]), 4336 / image-size / 14:34768, 4337 } , 4338 / condition-vendor-identifier / 1,15 , 4339 / condition-class-identifier / 2,15 4340 ]), 4341 }), 4342 / install / 9:[ 4343 / algorithm-id / 2 / "sha256" /, 4344 / digest-bytes / 4345 h'3ee96dc79641970ae46b929ccf0b72ba9536dd846020dbdc9f949d84ea0e18d2' 4346 ], 4347 / validate / 10:bstr .cbor ([ 4348 / condition-image-match / 3,15 4349 ]), 4350 / run / 12:bstr .cbor ([ 4351 / directive-run / 23,2 4352 ]), 4353 / text / 13:[ 4354 / algorithm-id / 2 / "sha256" /, 4355 / digest-bytes / 4356 h'23f48b2e2838650f43c144234aee18401ffe3cce4733b23881c3a8ae2d2b66e8' 4357 ], 4358 }), 4359 / install / 9:bstr .cbor ([ 4360 / directive-set-parameters / 19,{ 4361 / uri / 4362 21:'http://example.com/very/long/path/to/file/file.bin', 4363 } , 4364 / directive-fetch / 21,2 , 4365 / condition-image-match / 3,15 4366 ]), 4367 / text / 13:bstr .cbor ({ 4368 [h'00']:{ 4369 / vendor-domain / 3:'arm.com', 4370 / component-description / 5:'This component is a 4371 demonstration. The digest is a sample pattern, not a real one.', 4372 } 4373 }), 4374 } 4376 Total size of the Envelope without COSE authentication object or 4377 Severable Elements: 233 4379 Envelope: 4381 a20258278158248202582075685579a83babd71ec8ef22fa49ac873f78a7 4382 08a43a674e782ad30b6598d17a0358bba70101020203585fa20281814100 4383 0458568614a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af14 4384 25695e48bf429b2d51f2ab450358248202582000112233445566778899aa 4385 bbccddeeff0123456789abcdeffedcba98765432100e1987d0010f020f09 4386 820258203ee96dc79641970ae46b929ccf0b72ba9536dd846020dbdc9f94 4387 9d84ea0e18d20a4382030f0c438217020d8202582023f48b2e2838650f43 4388 c144234aee18401ffe3cce4733b23881c3a8ae2d2b66e8 4390 Total size of the Envelope with COSE authentication object but 4391 without Severable Elements: 346 4393 Envelope: 4395 a20258988258248202582075685579a83babd71ec8ef22fa49ac873f78a7 4396 08a43a674e782ad30b6598d17a586fd28443a10126a05824820258207568 4397 5579a83babd71ec8ef22fa49ac873f78a708a43a674e782ad30b6598d17a 4398 5840861b9bfb449125742baa648bc9d148cba45519cca8efecf705c2165e 4399 cdecaeba8b6ce2131284e66708788d741e8779d5973fa8e25da49eb203c8 4400 1920719da9490358bba70101020203585fa202818141000458568614a401 4401 50fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b 4402 2d51f2ab450358248202582000112233445566778899aabbccddeeff0123 4403 456789abcdeffedcba98765432100e1987d0010f020f09820258203ee96d 4404 c79641970ae46b929ccf0b72ba9536dd846020dbdc9f949d84ea0e18d20a 4405 4382030f0c438217020d8202582023f48b2e2838650f43c144234aee1840 4406 1ffe3cce4733b23881c3a8ae2d2b66e8 4408 Total size of Envelope with COSE authentication object: 929 4410 Envelope with COSE authentication object: 4412 a40258988258248202582075685579a83babd71ec8ef22fa49ac873f78a7 4413 08a43a674e782ad30b6598d17a586fd28443a10126a05824820258207568 4414 5579a83babd71ec8ef22fa49ac873f78a708a43a674e782ad30b6598d17a 4415 5840861b9bfb449125742baa648bc9d148cba45519cca8efecf705c2165e 4416 cdecaeba8b6ce2131284e66708788d741e8779d5973fa8e25da49eb203c8 4417 1920719da9490358bba70101020203585fa202818141000458568614a401 4418 50fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b 4419 2d51f2ab450358248202582000112233445566778899aabbccddeeff0123 4420 456789abcdeffedcba98765432100e1987d0010f020f09820258203ee96d 4421 c79641970ae46b929ccf0b72ba9536dd846020dbdc9f949d84ea0e18d20a 4422 4382030f0c438217020d8202582023f48b2e2838650f43c144234aee1840 4423 1ffe3cce4733b23881c3a8ae2d2b66e809583c8613a1157832687474703a 4424 2f2f6578616d706c652e636f6d2f766572792f6c6f6e672f706174682f74 4425 6f2f66696c652f66696c652e62696e1502030f0d590204a20179019d2323 4426 204578616d706c6520323a2053696d756c74616e656f757320446f776e6c 4427 6f61642c20496e7374616c6c6174696f6e2c2053656375726520426f6f74 4428 2c2053657665726564204669656c64730a0a202020205468697320657861 4429 6d706c6520636f766572732074686520666f6c6c6f77696e672074656d70 4430 6c617465733a0a202020200a202020202a20436f6d7061746962696c6974 4431 7920436865636b20287b7b74656d706c6174652d636f6d7061746962696c 4432 6974792d636865636b7d7d290a202020202a2053656375726520426f6f74 4433 20287b7b74656d706c6174652d7365637572652d626f6f747d7d290a2020 4434 20202a204669726d7761726520446f776e6c6f616420287b7b6669726d77 4435 6172652d646f776e6c6f61642d74656d706c6174657d7d290a202020200a 4436 2020202054686973206578616d706c6520616c736f2064656d6f6e737472 4437 6174657320736576657261626c6520656c656d656e747320287b7b6f7672 4438 2d736576657261626c657d7d292c20616e64207465787420287b7b6d616e 4439 69666573742d6469676573742d746578747d7d292e814100a2036761726d 4440 2e636f6d0578525468697320636f6d706f6e656e7420697320612064656d 4441 6f6e7374726174696f6e2e20546865206469676573742069732061207361 4442 6d706c65207061747465726e2c206e6f742061207265616c206f6e652e 4444 B.4. Example 3: A/B images 4446 This example covers the following templates: 4448 - Compatibility Check (Section 7.1) 4450 - Secure Boot (Section 7.2) 4452 - Firmware Download (Section 7.3) 4454 - A/B Image Template (Section 7.11) 4456 { 4457 / authentication-wrapper / 2:bstr .cbor ({ digest: bstr 4458 .cbor ([ 4459 / algorithm-id / 2 / "sha256" /, 4460 / digest-bytes / 4461 h'ae0c1ea689c9800a843550f38796b6fdbd52a0c78be5d26011d8e784da43d47c' 4462 ]) signatures: [ 4463 bstr .cbor (18([ 4464 / protected / bstr .cbor ({ 4465 / alg / 1:-7 / "ES256" /, 4466 }), 4467 / unprotected / { 4468 }, 4469 / payload / bstr .cbor ([ 4470 / algorithm-id / 2 / "sha256" /, 4471 / digest-bytes / 4472 h'ae0c1ea689c9800a843550f38796b6fdbd52a0c78be5d26011d8e784da43d47c' 4473 ]), 4474 / signature / h'359960bae5a7de2457c8f48d3250d96d1a 4475 f2d36e08764b62d76f8a3f3041774b150b2c835bb1b2d7b1b2e629e1f08cc3b1b48fce 4476 bb8fb38182c116161e02b33f' 4477 ])) 4478 ] 4479 }), 4480 / manifest / 3:bstr .cbor ({ 4481 / manifest-version / 1:1, 4482 / manifest-sequence-number / 2:3, 4483 / common / 3:bstr .cbor ({ 4484 / components / 2:[ 4485 [h'00'] 4486 ], 4487 / common-sequence / 4:bstr .cbor ([ 4488 / directive-override-parameters / 20,{ 4489 / vendor-id / 4490 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 4491 be9d-e663e4d41ffe /, 4492 / class-id / 2:h'1492af1425695e48bf429b2d51f2ab45' 4493 / 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 4494 } , 4495 / directive-try-each / 15,[ 4496 bstr .cbor ([ 4497 / directive-override-parameters / 20,{ 4498 / offset / 5:33792, 4499 } , 4500 / condition-component-offset / 5,5 , 4501 / directive-override-parameters / 20,{ 4502 / image-digest / 3:bstr .cbor ([ 4503 / algorithm-id / 2 / "sha256" /, 4504 / digest-bytes / 4505 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 4506 ]), 4507 / image-size / 14:34768, 4509 } 4510 ]) , 4511 bstr .cbor ([ 4512 / directive-override-parameters / 20,{ 4513 / offset / 5:541696, 4514 } , 4515 / condition-component-offset / 5,5 , 4516 / directive-override-parameters / 20,{ 4517 / image-digest / 3:bstr .cbor ([ 4518 / algorithm-id / 2 / "sha256" /, 4519 / digest-bytes / 4520 h'0123456789abcdeffedcba987654321000112233445566778899aabbccddeeff' 4521 ]), 4522 / image-size / 14:76834, 4523 } 4524 ]) 4525 ] , 4526 / condition-vendor-identifier / 1,15 , 4527 / condition-class-identifier / 2,15 4528 ]), 4529 }), 4530 / install / 9:bstr .cbor ([ 4531 / directive-try-each / 15,[ 4532 bstr .cbor ([ 4533 / directive-set-parameters / 19,{ 4534 / offset / 5:33792, 4535 } , 4536 / condition-component-offset / 5,5 , 4537 / directive-set-parameters / 19,{ 4538 / uri / 21:'http://example.com/file1.bin', 4539 } 4540 ]) , 4541 bstr .cbor ([ 4542 / directive-set-parameters / 19,{ 4543 / offset / 5:541696, 4544 } , 4545 / condition-component-offset / 5,5 , 4546 / directive-set-parameters / 19,{ 4547 / uri / 21:'http://example.com/file2.bin', 4548 } 4549 ]) 4550 ] , 4551 / directive-fetch / 21,2 , 4552 / condition-image-match / 3,15 4553 ]), 4554 / validate / 10:bstr .cbor ([ 4555 / condition-image-match / 3,15 4556 ]), 4558 }), 4559 } 4561 Total size of Envelope without COSE authentication object: 330 4563 Envelope: 4565 a202582781582482025820ae0c1ea689c9800a843550f38796b6fdbd52a0 4566 c78be5d26011d8e784da43d47c0359011ba5010102030358aaa202818141 4567 000458a18814a20150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af 4568 1425695e48bf429b2d51f2ab450f8258368614a105198400050514a20358 4569 248202582000112233445566778899aabbccddeeff0123456789abcdeffe 4570 dcba98765432100e1987d0583a8614a1051a00084400050514a203582482 4571 0258200123456789abcdeffedcba987654321000112233445566778899aa 4572 bbccddeeff0e1a00012c22010f020f095861860f82582a8613a105198400 4573 050513a115781c687474703a2f2f6578616d706c652e636f6d2f66696c65 4574 312e62696e582c8613a1051a00084400050513a115781c687474703a2f2f 4575 6578616d706c652e636f6d2f66696c65322e62696e1502030f0a4382030f 4577 Total size of Envelope with COSE authentication object: 443 4579 Envelope with COSE authentication object: 4581 a202589882582482025820ae0c1ea689c9800a843550f38796b6fdbd52a0 4582 c78be5d26011d8e784da43d47c586fd28443a10126a0582482025820ae0c 4583 1ea689c9800a843550f38796b6fdbd52a0c78be5d26011d8e784da43d47c 4584 5840359960bae5a7de2457c8f48d3250d96d1af2d36e08764b62d76f8a3f 4585 3041774b150b2c835bb1b2d7b1b2e629e1f08cc3b1b48fcebb8fb38182c1 4586 16161e02b33f0359011ba5010102030358aaa202818141000458a18814a2 4587 0150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf42 4588 9b2d51f2ab450f8258368614a105198400050514a2035824820258200011 4589 2233445566778899aabbccddeeff0123456789abcdeffedcba9876543210 4590 0e1987d0583a8614a1051a00084400050514a20358248202582001234567 4591 89abcdeffedcba987654321000112233445566778899aabbccddeeff0e1a 4592 00012c22010f020f095861860f82582a8613a105198400050513a115781c 4593 687474703a2f2f6578616d706c652e636f6d2f66696c65312e62696e582c 4594 8613a1051a00084400050513a115781c687474703a2f2f6578616d706c65 4595 2e636f6d2f66696c65322e62696e1502030f0a4382030f 4597 B.5. Example 4: Load and Decompress from External Storage 4599 This example covers the following templates: 4601 - Compatibility Check (Section 7.1) 4603 - Secure Boot (Section 7.2) 4605 - Firmware Download (Section 7.3) 4606 - Install (Section 7.4) 4608 - Load & Decompress (Section 7.8) 4610 { 4611 / authentication-wrapper / 2:bstr .cbor ({ digest: bstr 4612 .cbor ([ 4613 / algorithm-id / 2 / "sha256" /, 4614 / digest-bytes / 4615 h'4b4c7c8c0fda76c9c9591a9db160918e2b3c96a58b0a5e4984fd4e8f9359a928' 4616 ]) signatures: [ 4617 bstr .cbor (18([ 4618 / protected / bstr .cbor ({ 4619 / alg / 1:-7 / "ES256" /, 4620 }), 4621 / unprotected / { 4622 }, 4623 / payload / bstr .cbor ([ 4624 / algorithm-id / 2 / "sha256" /, 4625 / digest-bytes / 4626 h'4b4c7c8c0fda76c9c9591a9db160918e2b3c96a58b0a5e4984fd4e8f9359a928' 4627 ]), 4628 / signature / h'd721cb3415f27cfeb8ef066bb6312ba758 4629 32b57410a0c700de71cf8004ea23b9dd3c912a99fab111e9b8f2cc55c7dffcc37012de 4630 cf72e44f69b3d3db8cc98cb6' 4631 ])) 4632 ] 4633 }), 4634 / manifest / 3:bstr .cbor ({ 4635 / manifest-version / 1:1, 4636 / manifest-sequence-number / 2:4, 4637 / common / 3:bstr .cbor ({ 4638 / components / 2:[ 4639 [h'00'] , 4640 [h'02'] , 4641 [h'01'] 4642 ], 4643 / common-sequence / 4:bstr .cbor ([ 4644 / directive-set-component-index / 12,0 , 4645 / directive-override-parameters / 20,{ 4646 / vendor-id / 4647 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 4648 be9d-e663e4d41ffe /, 4649 / class-id / 2:h'1492af1425695e48bf429b2d51f2ab45' 4650 / 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 4651 / image-digest / 3:bstr .cbor ([ 4652 / algorithm-id / 2 / "sha256" /, 4653 / digest-bytes / 4655 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 4656 ]), 4657 / image-size / 14:34768, 4658 } , 4659 / condition-vendor-identifier / 1,15 , 4660 / condition-class-identifier / 2,15 4661 ]), 4662 }), 4663 / payload-fetch / 8:bstr .cbor ([ 4664 / directive-set-component-index / 12,1 , 4665 / directive-set-parameters / 19,{ 4666 / uri / 21:'http://example.com/file.bin', 4667 } , 4668 / directive-fetch / 21,2 , 4669 / condition-image-match / 3,15 4670 ]), 4671 / install / 9:bstr .cbor ([ 4672 / directive-set-component-index / 12,0 , 4673 / directive-set-parameters / 19,{ 4674 / source-component / 22:1 / [h'02'] /, 4675 } , 4676 / directive-copy / 22,2 , 4677 / condition-image-match / 3,15 4678 ]), 4679 / validate / 10:bstr .cbor ([ 4680 / directive-set-component-index / 12,0 , 4681 / condition-image-match / 3,15 4682 ]), 4683 / load / 11:bstr .cbor ([ 4684 / directive-set-component-index / 12,2 , 4685 / directive-set-parameters / 19,{ 4686 / image-digest / 3:bstr .cbor ([ 4687 / algorithm-id / 2 / "sha256" /, 4688 / digest-bytes / 4689 h'0123456789abcdeffedcba987654321000112233445566778899aabbccddeeff' 4690 ]), 4691 / image-size / 14:76834, 4692 / source-component / 22:0 / [h'00'] /, 4693 / compression-info / 19:1 / "gzip" /, 4694 } , 4695 / directive-copy / 22,2 , 4696 / condition-image-match / 3,15 4697 ]), 4698 / run / 12:bstr .cbor ([ 4699 / directive-set-component-index / 12,2 , 4700 / directive-run / 23,2 4701 ]), 4702 }), 4704 } 4706 Total size of Envelope without COSE authentication object: 287 4708 Envelope: 4710 a2025827815824820258204b4c7c8c0fda76c9c9591a9db160918e2b3c96 4711 a58b0a5e4984fd4e8f9359a9280358f1a801010204035867a20283814100 4712 814102814101045858880c0014a40150fa6b4a53d5ad5fdfbe9de663e4d4 4713 1ffe02501492af1425695e48bf429b2d51f2ab4503582482025820001122 4714 33445566778899aabbccddeeff0123456789abcdeffedcba98765432100e 4715 1987d0010f020f085827880c0113a115781b687474703a2f2f6578616d70 4716 6c652e636f6d2f66696c652e62696e1502030f094b880c0013a116011602 4717 030f0a45840c00030f0b583a880c0213a4035824820258200123456789ab 4718 cdeffedcba987654321000112233445566778899aabbccddeeff0e1a0001 4719 2c22130116001602030f0c45840c021702 4721 Total size of Envelope with COSE authentication object: 400 4723 Envelope with COSE authentication object: 4725 a2025898825824820258204b4c7c8c0fda76c9c9591a9db160918e2b3c96 4726 a58b0a5e4984fd4e8f9359a928586fd28443a10126a05824820258204b4c 4727 7c8c0fda76c9c9591a9db160918e2b3c96a58b0a5e4984fd4e8f9359a928 4728 5840d721cb3415f27cfeb8ef066bb6312ba75832b57410a0c700de71cf80 4729 04ea23b9dd3c912a99fab111e9b8f2cc55c7dffcc37012decf72e44f69b3 4730 d3db8cc98cb60358f1a801010204035867a2028381410081410281410104 4731 5858880c0014a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af 4732 1425695e48bf429b2d51f2ab450358248202582000112233445566778899 4733 aabbccddeeff0123456789abcdeffedcba98765432100e1987d0010f020f 4734 085827880c0113a115781b687474703a2f2f6578616d706c652e636f6d2f 4735 66696c652e62696e1502030f094b880c0013a116011602030f0a45840c00 4736 030f0b583a880c0213a4035824820258200123456789abcdeffedcba9876 4737 54321000112233445566778899aabbccddeeff0e1a00012c221301160016 4738 02030f0c45840c021702 4740 B.6. Example 5: Two Images 4742 This example covers the following templates: 4744 - Compatibility Check (Section 7.1) 4746 - Secure Boot (Section 7.2) 4748 - Firmware Download (Section 7.3) 4750 Furthermore, it shows using these templates with two images. 4752 { 4753 / authentication-wrapper / 2:bstr .cbor ({ digest: bstr 4754 .cbor ([ 4755 / algorithm-id / 2 / "sha256" /, 4756 / digest-bytes / 4757 h'de7c7927a15bd2eda59cab1512875f17c9f1e9e23885ce1ac6d671eefcefa37a' 4758 ]) signatures: [ 4759 bstr .cbor (18([ 4760 / protected / bstr .cbor ({ 4761 / alg / 1:-7 / "ES256" /, 4762 }), 4763 / unprotected / { 4764 }, 4765 / payload / bstr .cbor ([ 4766 / algorithm-id / 2 / "sha256" /, 4767 / digest-bytes / 4768 h'de7c7927a15bd2eda59cab1512875f17c9f1e9e23885ce1ac6d671eefcefa37a' 4769 ]), 4770 / signature / h'e71e332c985fb0479f296685669d05348b 4771 cdba8e186f25a5418f4682ea168df61661f54bf48f964577225ed455b22d277dd94de8 4772 7c57f1baceedd6719f3d56ec' 4773 ])) 4774 ] 4775 }), 4776 / manifest / 3:bstr .cbor ({ 4777 / manifest-version / 1:1, 4778 / manifest-sequence-number / 2:5, 4779 / common / 3:bstr .cbor ({ 4780 / components / 2:[ 4781 [h'00'] , 4782 [h'01'] 4783 ], 4784 / common-sequence / 4:bstr .cbor ([ 4785 / directive-set-component-index / 12,0 , 4786 / directive-override-parameters / 20,{ 4787 / vendor-id / 4788 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 4789 be9d-e663e4d41ffe /, 4790 / class-id / 2:h'1492af1425695e48bf429b2d51f2ab45' 4791 / 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 4792 / image-digest / 3:bstr .cbor ([ 4793 / algorithm-id / 2 / "sha256" /, 4794 / digest-bytes / 4795 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 4796 ]), 4797 / image-size / 14:34768, 4798 } , 4799 / condition-vendor-identifier / 1,15 , 4800 / condition-class-identifier / 2,15 , 4801 / directive-set-component-index / 12,1 , 4802 / directive-override-parameters / 20,{ 4803 / image-digest / 3:bstr .cbor ([ 4804 / algorithm-id / 2 / "sha256" /, 4805 / digest-bytes / 4806 h'0123456789abcdeffedcba987654321000112233445566778899aabbccddeeff' 4807 ]), 4808 / image-size / 14:76834, 4809 } 4810 ]), 4811 }), 4812 / install / 9:bstr .cbor ([ 4813 / directive-set-component-index / 12,0 , 4814 / directive-set-parameters / 19,{ 4815 / uri / 21:'http://example.com/file1.bin', 4816 } , 4817 / directive-fetch / 21,2 , 4818 / condition-image-match / 3,15 , 4819 / directive-set-component-index / 12,1 , 4820 / directive-set-parameters / 19,{ 4821 / uri / 21:'http://example.com/file2.bin', 4822 } , 4823 / directive-fetch / 21,2 , 4824 / condition-image-match / 3,15 4825 ]), 4826 / validate / 10:bstr .cbor ([ 4827 / directive-set-component-index / 12,0 , 4828 / condition-image-match / 3,15 , 4829 / directive-set-component-index / 12,1 , 4830 / condition-image-match / 3,15 4831 ]), 4832 / run / 12:bstr .cbor ([ 4833 / directive-set-component-index / 12,0 , 4834 / directive-run / 23,2 4835 ]), 4836 }), 4837 } 4839 Total size of Envelope without COSE authentication object: 304 4841 Envelope: 4843 a202582781582482025820de7c7927a15bd2eda59cab1512875f17c9f1e9 4844 e23885ce1ac6d671eefcefa37a03590101a601010205035895a202828141 4845 008141010458898c0c0014a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe 4846 02501492af1425695e48bf429b2d51f2ab45035824820258200011223344 4847 5566778899aabbccddeeff0123456789abcdeffedcba98765432100e1987 4848 d0010f020f0c0114a2035824820258200123456789abcdeffedcba987654 4849 321000112233445566778899aabbccddeeff0e1a00012c2209584f900c00 4850 13a115781c687474703a2f2f6578616d706c652e636f6d2f66696c65312e 4851 62696e1502030f0c0113a115781c687474703a2f2f6578616d706c652e63 4852 6f6d2f66696c65322e62696e1502030f0a49880c00030f0c01030f0c4584 4853 0c001702 4855 Total size of Envelope with COSE authentication object: 417 4857 Envelope with COSE authentication object: 4859 a202589882582482025820de7c7927a15bd2eda59cab1512875f17c9f1e9 4860 e23885ce1ac6d671eefcefa37a586fd28443a10126a0582482025820de7c 4861 7927a15bd2eda59cab1512875f17c9f1e9e23885ce1ac6d671eefcefa37a 4862 5840e71e332c985fb0479f296685669d05348bcdba8e186f25a5418f4682 4863 ea168df61661f54bf48f964577225ed455b22d277dd94de87c57f1baceed 4864 d6719f3d56ec03590101a601010205035895a20282814100814101045889 4865 8c0c0014a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425 4866 695e48bf429b2d51f2ab450358248202582000112233445566778899aabb 4867 ccddeeff0123456789abcdeffedcba98765432100e1987d0010f020f0c01 4868 14a2035824820258200123456789abcdeffedcba98765432100011223344 4869 5566778899aabbccddeeff0e1a00012c2209584f900c0013a115781c6874 4870 74703a2f2f6578616d706c652e636f6d2f66696c65312e62696e1502030f 4871 0c0113a115781c687474703a2f2f6578616d706c652e636f6d2f66696c65 4872 322e62696e1502030f0a49880c00030f0c01030f0c45840c001702 4874 Appendix C. C. Design Rational 4876 In order to provide flexible behavior to constrained devices, while 4877 still allowing more powerful devices to use their full capabilities, 4878 the SUIT manifest encodes the required behavior of a Recipient 4879 device. Behavior is encoded as a specialized byte code, contained in 4880 a CBOR list. This promotes a flat encoding, which simplifies the 4881 parser. The information encoded by this byte code closely matches 4882 the operations that a device will perform, which promotes ease of 4883 processing. The core operations used by most update and trusted 4884 invocation operations are represented in the byte code. The byte 4885 code can be extended by registering new operations. 4887 The specialized byte code approach gives benefits equivalent to those 4888 provided by a scripting language or conventional byte code, with two 4889 substantial differences. First, the language is extremely high 4890 level, consisting of only the operations that a device may perform 4891 during update and trusted invocation of a firmware image. Second, 4892 the language specifies linear behavior, without reverse branches. 4893 Conditional processing is supported, and parallel and out-of-order 4894 processing may be performed by sufficiently capable devices. 4896 By structuring the data in this way, the manifest processor becomes a 4897 very simple engine that uses a pull parser to interpret the manifest. 4898 This pull parser invokes a series of command handlers that evaluate a 4899 Condition or execute a Directive. Most data is structured in a 4900 highly regular pattern, which simplifies the parser. 4902 The results of this allow a Recipient to implement a very small 4903 parser for constrained applications. If needed, such a parser also 4904 allows the Recipient to perform complex updates with reduced 4905 overhead. Conditional execution of commands allows a simple device 4906 to perform important decisions at validation-time. 4908 Dependency handling is vastly simplified as well. Dependencies 4909 function like subroutines of the language. When a manifest has a 4910 dependency, it can invoke that dependency's commands and modify their 4911 behavior by setting parameters. Because some parameters come with 4912 security implications, the dependencies also have a mechanism to 4913 reject modifications to parameters on a fine-grained level. 4915 Developing a robust permissions system works in this model too. The 4916 Recipient can use a simple ACL that is a table of Identities and 4917 Component Identifier permissions to ensure that operations on 4918 components fail unless they are permitted by the ACL. This table can 4919 be further refined with individual parameters and commands. 4921 Capability reporting is similarly simplified. A Recipient can report 4922 the Commands, Parameters, Algorithms, and Component Identifiers that 4923 it supports. This is sufficiently precise for a manifest author to 4924 create a manifest that the Recipient can accept. 4926 The simplicity of design in the Recipient due to all of these 4927 benefits allows even a highly constrained platform to use advanced 4928 update capabilities. 4930 C.1. C.1 Design Rationale: Envelope 4932 The Envelope is used instead of a COSE structure for several reasons: 4934 1. This enables the use of Severable Elements (Section 8.8) 4936 2. This enables modular processing of manifests, particularly with 4937 large signatures. 4939 3. This enables multiple authentication schemes. 4941 4. This allows integrity verification by a dependent to be 4942 unaffected by adding or removing authentication structures. 4944 Modular processing is important because it allows a Manifest 4945 Processor to iterate forward over an Envelope, processing Delegation 4946 Chains and Authentication Blocks, retaining only intermediate values, 4947 without any need to seek forward and backwards in a stream until it 4948 gets to the Manifest itself. This allows the use of large, Post- 4949 Quantum signatures without requiring retention of the signature 4950 itself, or seeking forward and back. 4952 Four authentication objects are supported by the Envelope: 4954 - COSE_Sign_Tagged 4956 - COSE_Sign1_Tagged 4958 - COSE_Mac_Tagged 4960 - COSE_Mac0_Tagged 4962 The SUIT Envelope allows an Update Authority or intermediary to mix 4963 and match any number of different authentication blocks it wants 4964 without any concern for modifying the integrity of another 4965 authentication block. This also allows the addition or removal of an 4966 authentication blocks without changing the integrity check of the 4967 Manifest, which is important for dependency handling. See 4968 Section 6.2 4970 C.2. C.2 Byte String Wrappers 4972 Byte string wrappers are used in several places in the suit manifest. 4973 The primary reason for wrappers it to limit the parser extent when 4974 invoked at different times, with a possible loss of context. 4976 The elements of the suit envelope are wrapped both to set the extents 4977 used by the parser and to simplify integrity checks by clearly 4978 defining the length of each element. 4980 The common block is re-parsed in order to find components identifiers 4981 from their indices, to find dependency prefixes and digests from 4982 their identifiers, and to find the common sequence. The common 4983 sequence is wrapped so that it matches other sequences, simplifying 4984 the code path. 4986 A severed SUIT command sequence will appear in the envelope, so it 4987 must be wrapped as with all envelope elements. For consistency, 4988 command sequences are also wrapped in the manifest. This also allows 4989 the parser to discern the difference between a command sequence and a 4990 SUIT_Digest. 4992 Parameters that are structured types (arrays and maps) are also 4993 wrapped in a bstr. This is so that parser extents can be set 4994 correctly using only a reference to the beginning of the parameter. 4995 This enables a parser to store a simple list of references to 4996 parameters that can be retrieved when needed. 4998 Appendix D. D. Implementation Conformance Matrix 5000 This section summarizes the functionality a minimal implementation 5001 needs to offer to claim conformance to this specification, in the 5002 absence of an application profile standard specifying otherwise. 5004 The subsequent table shows the conditions. 5006 +-------------------+------------------+----------------+ 5007 | Name | Reference | Implementation | 5008 +-------------------+------------------+----------------+ 5009 | Vendor Identifier | Section 8.7.5.2 | REQUIRED | 5010 | | | | 5011 | Class Identifier | Section 8.7.5.2 | REQUIRED | 5012 | | | | 5013 | Device Identifier | Section 8.7.5.2 | OPTIONAL | 5014 | | | | 5015 | Image Match | Section 8.7.6.2 | REQUIRED | 5016 | | | | 5017 | Image Not Match | Section 8.7.6.3 | OPTIONAL | 5018 | | | | 5019 | Use Before | Section 8.7.6.4 | OPTIONAL | 5020 | | | | 5021 | Component Offset | Section 8.7.6.5 | OPTIONAL | 5022 | | | | 5023 | Abort | Section 8.7.6.9 | OPTIONAL | 5024 | | | | 5025 | Minimum Battery | Section 8.7.6.6 | OPTIONAL | 5026 | | | | 5027 | Update Authorized | Section 8.7.6.7 | OPTIONAL | 5028 | | | | 5029 | Version | Section 8.7.6.8 | OPTIONAL | 5030 | | | | 5031 | Custom Condition | Section 8.7.6.10 | OPTIONAL | 5032 +-------------------+------------------+----------------+ 5034 The subsequent table shows the directives. 5036 +-------------------+----------------+------------------------------+ 5037 | Name | Reference | Implementation | 5038 +-------------------+----------------+------------------------------+ 5039 | Set Component | Section 8.7.7. | REQUIRED if more than one | 5040 | Index | 1 | component | 5041 | | | | 5042 | Set Dependency | Section 8.7.7. | REQUIRED if dependencies | 5043 | Index | 2 | used | 5044 | | | | 5045 | Try Each | Section 8.7.7. | OPTIONAL | 5046 | | 3 | | 5047 | | | | 5048 | Process | Section 8.7.7. | OPTIONAL | 5049 | Dependency | 4 | | 5050 | | | | 5051 | Set Parameters | Section 8.7.7. | OPTIONAL | 5052 | | 5 | | 5053 | | | | 5054 | Override | Section 8.7.7. | REQUIRED | 5055 | Parameters | 6 | | 5056 | | | | 5057 | Fetch | Section 8.7.7. | REQUIRED for Updater | 5058 | | 7 | | 5059 | | | | 5060 | Copy | Section 8.7.7. | OPTIONAL | 5061 | | 9 | | 5062 | | | | 5063 | Run | Section 8.7.7. | REQUIRED for Bootloader | 5064 | | 10 | | 5065 | | | | 5066 | Wait For Event | Section 8.7.7. | OPTIONAL | 5067 | | 11 | | 5068 | | | | 5069 | Run Sequence | Section 8.7.7. | OPTIONAL | 5070 | | 12 | | 5071 | | | | 5072 | Swap | Section 8.7.7. | OPTIONAL | 5073 | | 13 | | 5074 | | | | 5075 | Fetch URI List | Section 8.7.7. | OPTIONAL | 5076 | | 8 | | 5077 +-------------------+----------------+------------------------------+ 5079 The subsequent table shows the parameters. 5081 +------------------+------------------+----------------------+ 5082 | Name | Reference | Implementation | 5083 +------------------+------------------+----------------------+ 5084 | Vendor ID | Section 8.7.5.3 | REQUIRED | 5085 | | | | 5086 | Class ID | Section 8.7.5.4 | REQUIRED | 5087 | | | | 5088 | Image Digest | Section 8.7.5.6 | REQUIRED | 5089 | | | | 5090 | Image Size | Section 8.7.5.7 | REQUIRED | 5091 | | | | 5092 | Use Before | Section 8.7.5.8 | RECOMMENDED | 5093 | | | | 5094 | Component Offset | Section 8.7.5.9 | OPTIONAL | 5095 | | | | 5096 | Encryption Info | Section 8.7.5.10 | RECOMMENDED | 5097 | | | | 5098 | Compression Info | Section 8.7.5.11 | RECOMMENDED | 5099 | | | | 5100 | Unpack Info | Section 8.7.5.12 | RECOMMENDED | 5101 | | | | 5102 | URI | Section 8.7.5.13 | REQUIRED for Updater | 5103 | | | | 5104 | Source Component | Section 8.7.5.14 | OPTIONAL | 5105 | | | | 5106 | Run Args | Section 8.7.5.15 | OPTIONAL | 5107 | | | | 5108 | Device ID | Section 8.7.5.5 | OPTIONAL | 5109 | | | | 5110 | Minimum Battery | Section 8.7.5.16 | OPTIONAL | 5111 | | | | 5112 | Update Priority | Section 8.7.5.17 | OPTIONAL | 5113 | | | | 5114 | Version Match | Section 8.7.5.18 | OPTIONAL | 5115 | | | | 5116 | Wait Info | Section 8.7.5.19 | OPTIONAL | 5117 | | | | 5118 | URI List | Section 8.7.5.20 | OPTIONAL | 5119 | | | | 5120 | Strict Order | Section 8.7.5.22 | OPTIONAL | 5121 | | | | 5122 | Soft Failure | Section 8.7.5.23 | OPTIONAL | 5123 | | | | 5124 | Custom | Section 8.7.5.24 | OPTIONAL | 5125 +------------------+------------------+----------------------+ 5127 Authors' Addresses 5129 Brendan Moran 5130 Arm Limited 5132 EMail: Brendan.Moran@arm.com 5134 Hannes Tschofenig 5135 Arm Limited 5137 EMail: hannes.tschofenig@arm.com 5139 Henk Birkholz 5140 Fraunhofer SIT 5142 EMail: henk.birkholz@sit.fraunhofer.de 5144 Koen Zandberg 5145 Inria 5147 EMail: koen.zandberg@inria.fr