idnits 2.17.00 (12 Aug 2021) /tmp/idnits24124/draft-ietf-suit-manifest-10.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 (November 02, 2020) is 564 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 2491 -- Looks like a reference, but probably isn't: '2' on line 2491 -- Looks like a reference, but probably isn't: '3' on line 2462 == Missing Reference: '-1' is mentioned on line 2491, but not defined == Missing Reference: '-2' is mentioned on line 2464, but not defined == Missing Reference: '-3' is mentioned on line 2468, but not defined -- Looks like a reference, but probably isn't: '4' on line 2468 -- Looks like a reference, but probably isn't: '0' on line 2491 -- No information found for draft-ietf-cbor-tags-oid - is the name correct? == Outdated reference: A later version (-21) exists of draft-ietf-sacm-coswid-15 == Outdated reference: draft-ietf-suit-architecture has been published as RFC 9019 == Outdated reference: draft-ietf-suit-information-model has been published as RFC 9124 == Outdated reference: A later version (-17) exists of draft-ietf-teep-architecture-12 == Outdated reference: draft-kucherawy-rfc8478bis has been published as RFC 8878 Summary: 0 errors (**), 0 flaws (~~), 10 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 SUIT B. Moran 3 Internet-Draft H. Tschofenig 4 Intended status: Standards Track Arm Limited 5 Expires: May 6, 2021 H. Birkholz 6 Fraunhofer SIT 7 K. Zandberg 8 Inria 9 November 02, 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-10 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 May 6, 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 . . . . . . . . . . . 19 83 6.4. Abstract Machine Description . . . . . . . . . . . . . . 20 84 6.5. Special Cases of Component Index and Dependency Index . . 22 85 6.6. Serialized Processing Interpreter . . . . . . . . . . . . 24 86 6.7. Parallel Processing Interpreter . . . . . . . . . . . . . 24 87 6.8. Processing Dependencies . . . . . . . . . . . . . . . . . 25 88 6.9. Multiple Manifest Processors . . . . . . . . . . . . . . 25 89 7. Creating Manifests . . . . . . . . . . . . . . . . . . . . . 27 90 7.1. Compatibility Check Template . . . . . . . . . . . . . . 27 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 . . . . . . . . . . . . . 29 95 7.6. Integrated Payload Template . . . . . . . . . . . . . . . 30 96 7.7. Load from Nonvolatile Storage Template . . . . . . . . . 31 97 7.8. Load & Decompress from Nonvolatile Storage Template . . . 31 98 7.9. Dependency Template . . . . . . . . . . . . . . . . . . . 31 99 7.9.1. Composite Manifests . . . . . . . . . . . . . . . . . 32 100 7.10. Encrypted Manifest Template . . . . . . . . . . . . . . . 32 101 7.11. A/B Image Template . . . . . . . . . . . . . . . . . . . 33 102 8. Metadata Structure . . . . . . . . . . . . . . . . . . . . . 35 103 8.1. Encoding Considerations . . . . . . . . . . . . . . . . . 35 104 8.2. Envelope . . . . . . . . . . . . . . . . . . . . . . . . 35 105 8.3. Delegation Chains . . . . . . . . . . . . . . . . . . . . 35 106 8.4. Authenticated Manifests . . . . . . . . . . . . . . . . . 36 107 8.5. Encrypted Manifests . . . . . . . . . . . . . . . . . . . 36 108 8.6. Manifest . . . . . . . . . . . . . . . . . . . . . . . . 36 109 8.6.1. suit-manifest-version . . . . . . . . . . . . . . . . 37 110 8.6.2. suit-manifest-sequence-number . . . . . . . . . . . . 37 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 . . . . . . . . . . . . . . . . . . . . 68 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, where an update is 865 composed of all the TODO: Wording 867 manifest and its dependencies. This manifest is called the Root 868 Manifest. 870 6.2.1. Minimizing Signature Verifications 872 Signature verification can be energy and time expensive on a 873 constrained device. MAC verification is typically unaffected by 874 these concerns. A Recipient MAY choose to parse and execute only the 875 SUIT_Common section of the manifest prior to signature verification, 876 if all of the below apply: 878 - The Authentication Block contains a COSE_Sign_Tagged or 879 COSE_Sign1_Tagged 881 - The Recipient receives manifests over an unauthenticated channel, 882 exposing it to more inauthentic or incompatible manifests, and 884 - The Recipient has a power budget that makes signature verification 885 undesirable 887 The guidelines in Creating Manifests (Section 7) require that the 888 common section contains the applicability checks, so this section is 889 sufficient for applicability verification. The parser MUST restrict 890 acceptable commands to conditions and the following directives: 891 Override Parameters, Set Parameters, Try Each, and Run Sequence ONLY. 892 The manifest parser MUST NOT execute any command with side-effects 893 outside the parser (for example, Run, Copy, Swap, or Fetch commands) 894 prior to authentication and any such command MUST Abort. The Common 895 Sequence MUST be executed again in its entirety after authenticity 896 validation. 898 When executing Common prior to authenticity validation, the Manifest 899 Processor MUST evaluate the integrity of the manifest using the 900 SUIT_Digest present in the authentication block. 902 Alternatively, a Recipient MAY rely on network infrastructure to 903 filter inapplicable manifests. 905 6.3. Interpreter Fundamental Properties 907 The interpreter has a small set of design goals: 909 1. Executing an update MUST either result in an error, or a 910 verifiably correct system state. 912 2. Executing a Trusted Invocation MUST either result in an error, or 913 an invoked image. 915 3. Executing the same manifest on multiple Recipients MUST result in 916 the same system state. 918 NOTE: when using A/B images, the manifest functions as two (or more) 919 logical manifests, each of which applies to a system in a particular 920 starting state. With that provision, design goal 3 holds. 922 6.4. Abstract Machine Description 924 The heart of the manifest is the list of commands, which are 925 processed by a Manifest Processor-a form of interpreter. This 926 Manifest Processor can be modeled as a simple abstract machine. This 927 machine consists of several data storage locations that are modified 928 by commands. 930 There are two types of commands, namely those that modify state 931 (directives) and those that perform tests (conditions). Parameters 932 are used as the inputs to commands. Some directives offer control 933 flow operations. Directives target a specific component or 934 dependency. A dependency is another SUIT_Envelope that describes 935 additional components. Dependencies are identified by digest, but 936 referenced in commands by Dependency Index, the index into the array 937 of Dependencies. A component is a unit of code or data that can be 938 targeted by an update. Components are identified by Component 939 Identifiers, but referenced in commands by Component Index; Component 940 Identifiers are arrays of binary strings and a Component Index is an 941 index into the array of Component Identifiers. 943 Conditions MUST NOT have any side-effects other than informing the 944 interpreter of success or failure. The Interpreter does not Abort if 945 the Soft Failure flag (Section 8.7.5.23) is set when a Condition 946 reports failure. 948 Directives MAY have side-effects in the parameter table, the 949 interpreter state, or the current component. The Interpreter MUST 950 Abort if a Directive reports failure regardless of the Soft Failure 951 flag. 953 To simplify the logic describing the command semantics, the object 954 "current" is used. It represents the component identified by the 955 Component Index or the dependency identified by the Dependency Index: 957 current := components\[component-index\] 958 if component-index is not false 959 else dependencies\[dependency-index\] 961 As a result, Set Component Index is described as current := 962 components[arg]. The actual operation performed for Set Component 963 Index is described by the following pseudocode, however, because of 964 the definition of current (above), these are semantically equivalent. 966 component-index := arg 967 dependency-index := false 969 Similarly, Set Dependency Index is semantically equivalent to current 970 := dependencies[arg] 972 The following table describes the behavior of each command. "params" 973 represents the parameters for the current component or dependency. 974 Most commands operate on either a component or a dependency. Setting 975 the Component Index clears the Dependency Index. Setting the 976 Dependency Index clears the Component Index. 978 +-------------------+-----------------------------------------------+ 979 | Command Name | Semantic of the Operation | 980 +-------------------+-----------------------------------------------+ 981 | Check Vendor | assert(binary-match(current, | 982 | Identifier | current.params[vendor-id])) | 983 | | | 984 | Check Class | assert(binary-match(current, | 985 | Identifier | current.params[class-id])) | 986 | | | 987 | Verify Image | assert(binary-match(digest(current), | 988 | | current.params[digest])) | 989 | | | 990 | Set Component | current := components[arg] | 991 | Index | | 992 | | | 993 | Override | current.params[k] := v for-each k,v in arg | 994 | Parameters | | 995 | | | 996 | Set Dependency | current := dependencies[arg] | 997 | Index | | 998 | | | 999 | Set Parameters | current.params[k] := v if not k in params | 1000 | | for-each k,v in arg | 1001 | | | 1002 | Process | exec(current[common]); exec(current[current- | 1003 | Dependency | segment]) | 1004 | | | 1005 | Run | run(current) | 1006 | | | 1007 | Fetch | store(current, fetch(current.params[uri])) | 1008 | | | 1009 | Use Before | assert(now() < arg) | 1010 | | | 1011 | Check Component | assert(offsetof(current) == arg) | 1012 | Offset | | 1013 | | | 1014 | Check Device | assert(binary-match(current, | 1015 | Identifier | current.params[device-id])) | 1016 | | | 1017 | Check Image Not | assert(not binary-match(digest(current), | 1018 | Match | current.params[digest])) | 1019 | | | 1020 | Check Minimum | assert(battery >= arg) | 1021 | Battery | | 1022 | | | 1023 | Check Update | assert(isAuthorized()) | 1024 | Authorized | | 1025 | | | 1026 | Check Version | assert(version_check(current, arg)) | 1027 | | | 1028 | Abort | assert(0) | 1029 | | | 1030 | Try Each | try-each-done if exec(seq) is not error for- | 1031 | | each seq in arg | 1032 | | | 1033 | Copy | store(current, current.params[src-component]) | 1034 | | | 1035 | Swap | swap(current, current.params[src-component]) | 1036 | | | 1037 | Wait For Event | until event(arg), wait | 1038 | | | 1039 | Run Sequence | exec(arg) | 1040 | | | 1041 | Run with | run(current, arg) | 1042 | Arguments | | 1043 +-------------------+-----------------------------------------------+ 1045 6.5. Special Cases of Component Index and Dependency Index 1047 Component Index and Dependency Index can each take on one of three 1048 types: 1050 1. Integer 1052 2. Array of integers 1053 3. True 1055 Integers MUST always be supported by Set Component Index and Set 1056 Dependency Index. Arrays of integers MUST be supported by Set 1057 Component Index and Set Dependency Index if the Recipient supports 3 1058 or more components or 3 or more dependencies, respectively. True 1059 MUST be supported by Set Component Index and Set Dependency Index if 1060 the Recipient supports 2 or more components or 2 or more 1061 dependencies, respectively. Each of these operates on the list of 1062 components or list of dependencies declared in the manifest. 1064 Integer indices are the default case as described in the previous 1065 section. An array of integers represents a list of the components 1066 (Set Component Index) or a list of dependencies (Set Dependency 1067 Index) to which each subsequent command applies. The value True 1068 replaces the list of component indices or dependency indices with the 1069 full list of components or the full list of dependencies, 1070 respectively, as defined in the manifest. 1072 When a command is executed, it either 1. operates on the component or 1073 dependency identified by the component index or dependency index if 1074 that index is an integer, or 2. it operates on each component or 1075 dependency identified by an array of indicies, or 3. it operates on 1076 every component or every dependency if the index is the boolean True. 1077 This is described by the following pseudocode: 1079 if component-index is true: 1080 current-list = components 1081 else if component-index is array: 1082 current-list = [ components[idx] for idx in component-index ] 1083 else if component-index is integer: 1084 current-list = [ components[component-index] ] 1085 else if dependency-index is true: 1086 current-list = dependencies 1087 else if dependency-index is array: 1088 current-list = [ dependencies[idx] for idx in dependency-index ] 1089 else: 1090 current-list = [ dependencies[dependency-index] ] 1091 for current in current-list: 1092 cmd(current) 1094 Try Each and Run Sequence are affected in the same way as other 1095 commands: they are invoked once for each possible Component or 1096 Dependency. This means that the sequences that are arguments to Try 1097 Each and Run Sequence are NOT invoked with Component Index = True or 1098 Dependency Index = True, nor are they invoked with array indices. 1099 They are only invoked with integer indices. The interpreter loops 1100 over the whole sequence, setting the Component Index or Dependency 1101 Index to each index in turn. 1103 6.6. Serialized Processing Interpreter 1105 In highly constrained devices, where storage for parameters is 1106 limited, the manifest processor MAY handle one component at a time, 1107 traversing the manifest tree once for each listed component. In this 1108 mode, the interpreter ignores any commands executed while the 1109 component index is not the current component. This reduces the 1110 overall volatile storage required to process the update so that the 1111 only limit on number of components is the size of the manifest. 1112 However, this approach requires additional processing power. 1114 In order to operate in this mode, the manifest processor loops on 1115 each section for every supported component, simply ignoring commands 1116 when the current component is not selected. 1118 When a serialized Manifest Processor encounters a component or 1119 dependency index of True, it does not ignore any commands. It 1120 applies them to the current component or dependency on each 1121 iteration. 1123 6.7. Parallel Processing Interpreter 1125 Advanced Recipients MAY make use of the Strict Order parameter and 1126 enable parallel processing of some Command Sequences, or it may 1127 reorder some Command Sequences. To perform parallel processing, once 1128 the Strict Order parameter is set to False, the Recipient may issue 1129 each or every command concurrently until the Strict Order parameter 1130 is returned to True or the Command Sequence ends. Then, it waits for 1131 all issued commands to complete before continuing processing of 1132 commands. To perform out-of-order processing, a similar approach is 1133 used, except the Recipient consumes all commands after the Strict 1134 Order parameter is set to False, then it sorts these commands into 1135 its preferred order, invokes them all, then continues processing. 1137 Under each of these scenarios the parallel processing MUST halt until 1138 all issued commands have completed: 1140 - Set Parameters. 1142 - Override Parameters. 1144 - Set Strict Order = True. 1146 - Set Dependency Index. 1148 - Set Component Index. 1150 To perform more useful parallel operations, a manifest author may 1151 collect sequences of commands in a Run Sequence command. Then, each 1152 of these sequences MAY be run in parallel. Each sequence defaults to 1153 Strict Order = True. To isolate each sequence from each other 1154 sequence, each sequence MUST begin with a Set Component Index or Set 1155 Dependency Index directive with the following exception: when the 1156 index is either True or an array of indices, the Set Component Index 1157 or Set Dependency Index is implied. Any further Set Component Index 1158 directives MUST cause an Abort. This allows the interpreter that 1159 issues Run Sequence commands to check that the first element is 1160 correct, then issue the sequence to a parallel execution context to 1161 handle the remainder of the sequence. 1163 6.8. Processing Dependencies 1165 As described in Section 6.2, each manifest must invoke each of its 1166 dependencies sections from the corresponding section of the 1167 dependent. Any changes made to parameters by the dependency persist 1168 in the dependent. 1170 When a Process Dependency command is encountered, the interpreter 1171 loads the dependency identified by the Current Dependency Index. The 1172 interpreter first executes the common-sequence section of the 1173 identified dependency, then it executes the section of the dependency 1174 that corresponds to the currently executing section of the dependent. 1176 If the specified dependency does not contain the current section, 1177 Process Dependency succeeds immediately. 1179 The Manifest Processor MUST also support a Dependency Index of True, 1180 which applies to every dependency, as described in Section 6.5 1182 The interpreter also performs the checks described in Section 6.2 to 1183 ensure that the dependent is processing the dependency correctly. 1185 6.9. Multiple Manifest Processors 1187 When a system has multiple security domains, each domain might 1188 require independent verification of authenticity or security 1189 policies. Security domains might be divided by separation technology 1190 such as Arm TrustZone, Intel SGX, or another TEE technology. 1191 Security domains might also be divided into separate processors and 1192 memory spaces, with a communication interface between them. 1194 For example, an application processor may have an attached 1195 communications module that contains a processor. The communications 1196 module might require metadata signed by a specific Trust Authority 1197 for regulatory approval. This may be a different Trust Authority 1198 than the application processor. 1200 When there are two or more security domains (see 1201 [I-D.ietf-teep-architecture]), a manifest processor might be required 1202 in each. The first manifest processor is the normal manifest 1203 processor as described for the Recipient in Section 6.4. The second 1204 manifest processor only executes sections when the first manifest 1205 processor requests it. An API interface is provided from the second 1206 manifest processor to the first. This allows the first manifest 1207 processor to request a limited set of operations from the second. 1208 These operations are limited to: setting parameters, inserting an 1209 Envelope, invoking a Manifest Command Sequence. The second manifest 1210 processor declares a prefix to the first, which tells the first 1211 manifest processor when it should delegate to the second. These 1212 rules are enforced by underlying separation of privilege 1213 infrastructure, such as TEEs, or physical separation. 1215 When the first manifest processor encounters a dependency prefix, 1216 that informs the first manifest processor that it should provide the 1217 second manifest processor with the corresponding dependency Envelope. 1218 This is done when the dependency is fetched. The second manifest 1219 processor immediately verifies any authentication information in the 1220 dependency Envelope. When a parameter is set for any component that 1221 matches the prefix, this parameter setting is passed to the second 1222 manifest processor via an API. As the first manifest processor works 1223 through the Procedure (set of command sequences) it is executing, 1224 each time it sees a Process Dependency command that is associated 1225 with the prefix declared by the second manifest processor, it uses 1226 the API to ask the second manifest processor to invoke that 1227 dependency section instead. 1229 This mechanism ensures that the two or more manifest processors do 1230 not need to trust each other, except in a very limited case. When 1231 parameter setting across security domains is used, it must be very 1232 carefully considered. Only parameters that do not have an effect on 1233 security properties should be allowed. The dependency manifest MAY 1234 control which parameters are allowed to be set by using the Override 1235 Parameters directive. The second manifest processor MAY also control 1236 which parameters may be set by the first manifest processor by means 1237 of an ACL that lists the allowed parameters. For example, a URI may 1238 be set by a dependent without a substantial impact on the security 1239 properties of the manifest. 1241 7. Creating Manifests 1243 Manifests are created using tools for constructing COSE structures, 1244 calculating cryptographic values and compiling desired system state 1245 into a sequence of operations required to achieve that state. The 1246 process of constructing COSE structures and the calculation of 1247 cryptographic values is covered in [RFC8152]. 1249 Compiling desired system state into a sequence of operations can be 1250 accomplished in many ways. Several templates are provided below to 1251 cover common use-cases. These templates can be combined to produce 1252 more complex behavior. 1254 The author MUST ensure that all parameters consumed by a command are 1255 set prior to invoking that command. Where Component Index = True or 1256 Dependency Index = True, this means that the parameters consumed by 1257 each command MUST have been set for each Component or Dependency, 1258 respectively. 1260 This section details a set of templates for creating manifests. 1261 These templates explain which parameters, commands, and orders of 1262 commands are necessary to achieve a stated goal. 1264 NOTE: On systems that support only a single component and no 1265 dependencies, Set Component Index has no effect and can be omitted. 1267 NOTE: *A digest MUST always be set using Override Parameters, since 1268 this prevents a less-privileged dependent from replacing the digest.* 1270 7.1. Compatibility Check Template 1272 The goal of the compatibility check template ensure that Recipients 1273 only install compatible images. 1275 In this template all information is contained in the common sequence 1276 and the following sequence of commands is used: 1278 - Set Component Index directive (see Section 8.7.7.1) 1280 - Set Parameters directive (see Section 8.7.7.5) for Vendor ID and 1281 Class ID (see Section 8.7.5) 1283 - Check Vendor Identifier condition (see Section 8.7.5.2) 1285 - Check Class Identifier condition (see Section 8.7.5.2) 1287 7.2. Trusted Invocation Template 1289 The goal of the Trusted Invocation template is to ensure that only 1290 authorized code is invoked; such as in Secure Boot or when a Trusted 1291 Application is loaded into a TEE. 1293 The following commands are placed into the common sequence: 1295 - Set Component Index directive (see Section 8.7.7.1) 1297 - Override Parameters directive (see Section 8.7.7.6) for Image 1298 Digest and Image Size (see Section 8.7.5) 1300 Then, the run sequence contains the following commands: 1302 - Set Component Index directive (see Section 8.7.7.1) 1304 - Check Image Match condition (see Section 8.7.6.2) 1306 - Run directive (see Section 8.7.7.12) 1308 7.3. Component Download Template 1310 The goal of the Component Download template is to acquire and store 1311 an image. 1313 The following commands are placed into the common sequence: 1315 - Set Component Index directive (see Section 8.7.7.1) 1317 - Override Parameters directive (see Section 8.7.7.6) for Image 1318 Digest and Image Size (see Section 8.7.5) 1320 Then, the install sequence contains the following commands: 1322 - Set Component Index directive (see Section 8.7.7.1) 1324 - Set Parameters directive (see Section 8.7.7.5) for URI (see 1325 Section 8.7.5.13) 1327 - Fetch directive (see Section 8.7.7.7) 1329 - Check Image Match condition (see Section 8.7.6.2) 1331 The Fetch directive needs the URI parameter to be set to determine 1332 where the image is retrieved from. Additionally, the destination of 1333 where the component shall be stored has to be configured. The URI is 1334 configured via the Set Parameters directive while the destination is 1335 configured via the Set Component Index directive. 1337 Optionally, the Set Parameters directive in the install sequence MAY 1338 also contain Encryption Info (see Section 8.7.5.10), Compression Info 1339 (see Section 8.7.5.11), or Unpack Info (see Section 8.7.5.12) to 1340 perform simultaneous download and decryption, decompression, or 1341 unpacking, respectively. 1343 7.4. Install Template 1345 The goal of the Install template is to use an image already stored in 1346 an identified component to copy into a second component. 1348 This template is typically used with the Component Download template, 1349 however a modification to that template is required: the Component 1350 Download operations are moved from the Payload Install sequence to 1351 the Payload Fetch sequence. 1353 Then, the install sequence contains the following commands: 1355 - Set Component Index directive (see Section 8.7.7.1) 1357 - Set Parameters directive (see Section 8.7.7.5) for Source 1358 Component (see Section 8.7.5.14) 1360 - Copy directive (see Section 8.7.7.9) 1362 - Check Image Match condition (see Section 8.7.6.2) 1364 7.5. Install and Transform Template 1366 The goal of the Install and Transform template is to use an image 1367 already stored in an identified component to decompress, decrypt, or 1368 unpack at time of installation. 1370 This template is typically used with the Component Download template, 1371 however a modification to that template is required: all Component 1372 Download operations are moved from the common sequence and the 1373 install sequence to the fetch sequence. The Component Download 1374 template targets a download component identifier, while the Install 1375 and Transform template uses an install component identifier. In- 1376 place unpacking, decompression, and decryption is complex and 1377 vulnerable to power failure. Therefore, these identifiers SHOULD be 1378 different; in-place installation SHOULD NOT be used without 1379 establishing guarantees of robustness to power failure. 1381 The following commands are placed into the common sequence: 1383 - Set Component Index directive for install component identifier 1384 (see Section 8.7.7.1) 1386 - Override Parameters directive (see Section 8.7.7.6) for Image 1387 Digest and Image Size (see Section 8.7.5) 1389 Then, the install sequence contains the following commands: 1391 - Set Component Index directive for install component identifier 1392 (see Section 8.7.7.1) 1394 - Set Parameters directive (see Section 8.7.7.5) for: 1396 o Source Component for download component identifier (see 1397 Section 8.7.5.14) 1399 o Encryption Info (see Section 8.7.5.10) 1401 o Compression Info (see Section 8.7.5.11) 1403 o Unpack Info (see Section 8.7.5.12) 1405 - Copy directive (see Section 8.7.7.9) 1407 - Check Image Match condition (see Section 8.7.6.2) 1409 7.6. Integrated Payload Template 1411 The goal of the Integrated Payload template is to install a payload 1412 that is included in the manifest envelope. It is identical to the 1413 Component Download template (Section 7.3) except that it places an 1414 added restriction on the URI passed to the Set Parameters directive. 1416 An implementer MAY choose to place a payload in the envelope of a 1417 manifest. The payload envelope key MAY be a positive or negative 1418 integer. The payload envelope key MUST NOT be a value between 0 and 1419 24 and it MUST NOT be used by any other envelope element in the 1420 manifest. The payload MUST be serialized in a bstr element. 1422 The URI for a payload enclosed in this way MUST be expressed as a 1423 fragment-only reference, as defined in [RFC3986], Section 4.4. The 1424 fragment identifier is the stringified envelope key of the payload. 1425 For example, an envelope that contains a payload a key 42 would use a 1426 URI "#42", key -73 would use a URI "#-73". 1428 7.7. Load from Nonvolatile Storage Template 1430 The goal of the Load from Nonvolatile Storage template is to load an 1431 image from a non-volatile component into a volatile component, for 1432 example loading a firmware image from external Flash into RAM. 1434 The following commands are placed into the load sequence: 1436 - Set Component Index directive (see Section 8.7.7.1) 1438 - Set Parameters directive (see Section 8.7.7.5) for Component Index 1439 (see Section 8.7.5) 1441 - Copy directive (see Section 8.7.7.9) 1443 As outlined in Section 6.4, the Copy directive needs a source and a 1444 destination to be configured. The source is configured via Component 1445 Index (with the Set Parameters directive) and the destination is 1446 configured via the Set Component Index directive. 1448 7.8. Load & Decompress from Nonvolatile Storage Template 1450 The goal of the Load & Decompress from Nonvolatile Storage template 1451 is to load an image from a non-volatile component into a volatile 1452 component, decompressing on-the-fly, for example loading a firmware 1453 image from external Flash into RAM. 1455 The following commands are placed into the load sequence: 1457 - Set Component Index directive (see Section 8.7.7.1) 1459 - Set Parameters directive (see Section 8.7.7.5) for Source 1460 Component Index and Compression Info (see Section 8.7.5) 1462 - Copy directive (see Section 8.7.7.9) 1464 This template is similar to Section 7.7 but additionally performs 1465 decompression. Hence, the only difference is in setting the 1466 Compression Info parameter. 1468 This template can be modified for decryption or unpacking by adding 1469 Decryption Info or Unpack Info to the Set Parameters directive. 1471 7.9. Dependency Template 1473 The goal of the Dependency template is to obtain, verify, and process 1474 a dependency manifest as appropriate. 1476 The following commands are placed into the dependency resolution 1477 sequence: 1479 - Set Dependency Index directive (see Section 8.7.7.2) 1481 - Set Parameters directive (see Section 8.7.7.5) for URI (see 1482 Section 8.7.5) 1484 - Fetch directive (see Section 8.7.7.7) 1486 - Check Image Match condition (see Section 8.7.6.2) 1488 - Process Dependency directive (see Section 8.7.7.4) 1490 Then, the validate sequence contains the following operations: 1492 - Set Dependency Index directive (see Section 8.7.7.2) 1494 - Check Image Match condition (see Section 8.7.6.2) 1496 - Process Dependency directive (see Section 8.7.7.4) 1498 NOTE: Any changes made to parameters in a dependency persist in the 1499 dependent. 1501 7.9.1. Composite Manifests 1503 An implementer MAY choose to place a dependency's envelope in the 1504 envelope of its dependent. The dependent envelope key for the 1505 dependency envelope MUST NOT be a value between 0 and 24 and it MUST 1506 NOT be used by any other envelope element in the dependent manifest. 1508 The URI for a dependency enclosed in this way MUST be expressed as a 1509 fragment-only reference, as defined in [RFC3986], Section 4.4. The 1510 fragment identifier is the stringified envelope key of the 1511 dependency. For example, an envelope that contains a dependency at 1512 key 42 would use a URI "#42", key -73 would use a URI "#-73". 1514 7.10. Encrypted Manifest Template 1516 The goal of the Encrypted Manifest template is to fetch and decrypt a 1517 manifest so that it can be used as a dependency. To use an encrypted 1518 manifest, create a plaintext dependent, and add the encrypted 1519 manifest as a dependency. The dependent can include very little 1520 information. 1522 The following operations are placed into the dependency resolution 1523 block: 1525 - Set Dependency Index directive (see Section 8.7.7.2) 1527 - Set Parameters directive (see Section 8.7.7.5) for 1529 o URI (see Section 8.7.5) 1531 o Encryption Info (see Section 8.7.5) 1533 - Fetch directive (see Section 8.7.7.7) 1535 - Check Image Match condition (see Section 8.7.6.2) 1537 - Process Dependency directive (see Section 8.7.7.4) 1539 Then, the validate block contains the following operations: 1541 - Set Dependency Index directive (see Section 8.7.7.2) 1543 - Check Image Match condition (see Section 8.7.6.2) 1545 - Process Dependency directive (see Section 8.7.7.4) 1547 A plaintext manifest and its encrypted dependency may also form a 1548 composite manifest (Section 7.9.1). 1550 7.11. A/B Image Template 1552 The goal of the A/B Image Template is to acquire, validate, and 1553 invoke one of two images, based on a test. 1555 The following commands are placed in the common block: 1557 - Set Component Index directive (see Section 8.7.7.1) 1559 - Try Each 1561 o First Sequence: 1563 * Override Parameters directive (see Section 8.7.7.6, 1564 Section 8.7.5) for Offset A 1566 * Check Offset Condition (see Section 8.7.6.5) 1568 * Override Parameters directive (see Section 8.7.7.6) for 1569 Image Digest A and Image Size A (see Section 8.7.5) 1571 o Second Sequence: 1573 * Override Parameters directive (see Section 8.7.7.6, 1574 Section 8.7.5) for Offset B 1576 * Check Offset Condition (see Section 8.7.6.5) 1578 * Override Parameters directive (see Section 8.7.7.6) for 1579 Image Digest B and Image Size B (see Section 8.7.5) 1581 The following commands are placed in the fetch block or install block 1583 - Set Component Index directive (see Section 8.7.7.1) 1585 - Try Each 1587 o First Sequence: 1589 * Override Parameters directive (see Section 8.7.7.6, 1590 Section 8.7.5) for Offset A 1592 * Check Offset Condition (see Section 8.7.6.5) 1594 * Set Parameters directive (see Section 8.7.7.6) for URI A 1595 (see Section 8.7.5) 1597 o Second Sequence: 1599 * Override Parameters directive (see Section 8.7.7.6, 1600 Section 8.7.5) for Offset B 1602 * Check Offset Condition (see Section 8.7.6.5) 1604 * Set Parameters directive (see Section 8.7.7.6) for URI B 1605 (see Section 8.7.5) 1607 - Fetch 1609 If Trusted Invocation (Section 7.2) is used, only the run sequence is 1610 added to this template, since the common sequence is populated by 1611 this template. 1613 NOTE: Any test can be used to select between images, Check Offset 1614 Condition is used in this template because it is a typical test for 1615 execute-in-place devices. 1617 8. Metadata Structure 1619 The metadata for SUIT updates is composed of several primary 1620 constituent parts: the Envelope, Delegation Chains, Authentication 1621 Information, Manifest, and Severable Elements. 1623 For a diagram of the metadata structure, see Section 5. 1625 8.1. Encoding Considerations 1627 The map indices in the envelope encoding are reset to 1 for each map 1628 within the structure. This is to keep the indices as small as 1629 possible. The goal is to keep the index objects to single bytes 1630 (CBOR positive integers 1-23). 1632 Wherever enumerations are used, they are started at 1. This allows 1633 detection of several common software errors that are caused by 1634 uninitialized variables. Positive numbers in enumerations are 1635 reserved for IANA registration. Negative numbers are used to 1636 identify application-specific values, as described in Section 11. 1638 All elements of the envelope must be wrapped in a bstr to minimize 1639 the complexity of the code that evaluates the cryptographic integrity 1640 of the element and to ensure correct serialization for integrity and 1641 authenticity checks. 1643 8.2. Envelope 1645 The Envelope contains each of the other primary constituent parts of 1646 the SUIT metadata. It allows for modular processing of the manifest 1647 by ordering components in the expected order of processing. 1649 The Envelope is encoded as a CBOR Map. Each element of the Envelope 1650 is enclosed in a bstr, which allows computation of a message digest 1651 against known bounds. 1653 8.3. Delegation Chains 1655 The suit-delegation element MAY carry one or more CBOR Web Tokens 1656 (CWTs) [RFC8392], with [RFC8747] cnf claims. They can be used to 1657 perform enhanced authorization decisions. The CWTs are arranged into 1658 a list of lists. Each list starts with a CWT authorized by a Trust 1659 Anchor, and finishes with a key used to authenticate the Manifest 1660 (see Section 8.4). This allows an Update Authority to delegate from 1661 a long term Trust Anchor, down through intermediaries, to a delegate 1662 without any out-of-band provisioning of Trust Anchors or intermediary 1663 keys. 1665 A Recipient MAY choose to cache intermediaries and/or delegates. If 1666 an Update Distributor knows that a targeted Recipient has cached some 1667 intermediaries or delegates, it MAY choose to strip any cached 1668 intermediaries or delegates from the Delegation Chains in order to 1669 reduce bandwidth and energy. 1671 8.4. Authenticated Manifests 1673 The suit-authentication-wrapper contains a list containing a 1674 Section 10 and one or more cryptographic authentication wrappers for 1675 the Manifest. These are implemented as COSE_Mac_Tagged or 1676 COSE_Sign_Tagged blocks. Each of these blocks contains a SUIT_Digest 1677 of the Manifest. This enables modular processing of the manifest. 1678 The COSE_Mac_Tagged and COSE_Sign_Tagged blocks are described in RFC 1679 8152 [RFC8152]. The suit-authentication-wrapper MUST come before any 1680 element in the SUIT_Envelope, except for the OPTIONAL suit- 1681 delegation, regardless of canonical encoding of CBOR. All validators 1682 MUST reject any SUIT_Envelope that begins with any element other than 1683 a suit-authentication-wrapper or suit-delegation. 1685 A SUIT_Envelope that has not had authentication information added 1686 MUST still contain the suit-authentication-wrapper element, but the 1687 content MUST be a list containing only the SUIT_Digest. 1689 A signing application MUST verify the suit-manifest element against 1690 the SUIT_Digest prior to signing. 1692 8.5. Encrypted Manifests 1694 To use an encrypted manifest, it must be a dependency of a plaintext 1695 manifest. This allows fine-grained control of what information is 1696 accessible to intermediate systems for the purposes of management, 1697 while still preserving the confidentiality of the manifest contents. 1698 This also means that a Recipient can process an encrypted manifest in 1699 the same way as an encrypted payload, allowing code reuse. 1701 A template for using an encrypted manifest is covered in Encrypted 1702 Manifest Template (Section 7.10). 1704 8.6. Manifest 1706 The manifest contains: 1708 - a version number (see Section 8.6.1) 1710 - a sequence number (see Section 8.6.2) 1712 - a reference URI (see Section 8.6.3) 1713 - a common structure with information that is shared between command 1714 sequences (see Section 8.7.2) 1716 - one or more lists of commands that the Recipient should perform 1717 (see Section 8.7.3) 1719 - a reference to the full manifest (see Section 8.6.3) 1721 - human-readable text describing the manifest found in the 1722 SUIT_Envelope (see Section 8.6.4) 1724 - a Concise Software Identifier (CoSWID) found in the SUIT_Envelope 1725 (see Section 8.7.1) 1727 The CoSWID, Text section, or any Command Sequence of the Update 1728 Procedure (Dependency Resolution, Image Fetch, Image Installation) 1729 can be either a CBOR structure or a SUIT_Digest. In each of these 1730 cases, the SUIT_Digest provides for a severable element. Severable 1731 elements are RECOMMENDED to implement. In particular, the human- 1732 readable text SHOULD be severable, since most useful text elements 1733 occupy more space than a SUIT_Digest, but are not needed by the 1734 Recipient. Because SUIT_Digest is a CBOR Array and each severable 1735 element is a CBOR bstr, it is straight-forward for a Recipient to 1736 determine whether an element has been severed. The key used for a 1737 severable element is the same in the SUIT_Manifest and in the 1738 SUIT_Envelope so that a Recipient can easily identify the correct 1739 data in the envelope. See Section 8.7.8 for more detail. 1741 8.6.1. suit-manifest-version 1743 The suit-manifest-version indicates the version of serialization used 1744 to encode the manifest. Version 1 is the version described in this 1745 document. suit-manifest-version is REQUIRED to implement. 1747 8.6.2. suit-manifest-sequence-number 1749 The suit-manifest-sequence-number is a monotonically increasing anti- 1750 rollback counter. It also helps Recipients to determine which in a 1751 set of manifests is the "root" manifest in a given update. Each 1752 manifest MUST have a sequence number higher than each of its 1753 dependencies. Each Recipient MUST reject any manifest that has a 1754 sequence number lower than its current sequence number. For 1755 convenience, an implementer MAY use a UTC timestamp in seconds as the 1756 sequence number. suit-manifest-sequence-number is REQUIRED to 1757 implement. 1759 8.6.3. suit-reference-uri 1761 suit-reference-uri is a text string that encodes a URI where a full 1762 version of this manifest can be found. This is convenient for 1763 allowing management systems to show the severed elements of a 1764 manifest when this URI is reported by a Recipient after installation. 1766 8.6.4. suit-text 1768 suit-text SHOULD be a severable element. suit-text is a map 1769 containing two different types of pair: 1771 - integer => text 1773 - SUIT_Component_Identifier => map 1775 Each SUIT_Component_Identifier => map entry contains a map of integer 1776 => text values. All SUIT_Component_Identifiers present in suit-text 1777 MUST also be present in suit-common (Section 8.7.2) or the suit- 1778 common of a dependency. 1780 suit-text contains all the human-readable information that describes 1781 any and all parts of the manifest, its payload(s) and its 1782 resource(s). The text section is typically severable, allowing 1783 manifests to be distributed without the text, since end-nodes do not 1784 require text. The meaning of each field is described below. 1786 Each section MAY be present. If present, each section MUST be as 1787 described. Negative integer IDs are reserved for application- 1788 specific text values. 1790 The following table describes the text fields available in suit-text: 1792 +--------------------------------+----------------------------------+ 1793 | CDDL Structure | Description | 1794 +--------------------------------+----------------------------------+ 1795 | suit-text-manifest-description | Free text description of the | 1796 | | manifest | 1797 | | | 1798 | suit-text-update-description | Free text description of the | 1799 | | update | 1800 | | | 1801 | suit-text-manifest-json-source | The JSON-formatted document that | 1802 | | was used to create the manifest | 1803 | | | 1804 | suit-text-manifest-yaml-source | The YAML ([YAML])-formatted | 1805 | | document that was used to create | 1806 | | the manifest | 1807 +--------------------------------+----------------------------------+ 1809 The following table describes the text fields available in each map 1810 identified by a SUIT_Component_Identifier. 1812 +---------------------------------+---------------------------------+ 1813 | CDDL Structure | Description | 1814 +---------------------------------+---------------------------------+ 1815 | suit-text-vendor-name | Free text vendor name | 1816 | | | 1817 | suit-text-model-name | Free text model name | 1818 | | | 1819 | suit-text-vendor-domain | The domain used to create the | 1820 | | vendor-id condition | 1821 | | | 1822 | suit-text-model-info | The information used to create | 1823 | | the class-id condition | 1824 | | | 1825 | suit-text-component-description | Free text description of each | 1826 | | component in the manifest | 1827 | | | 1828 | suit-text-component-version | A free text representation of | 1829 | | the component version | 1830 | | | 1831 | suit-text-version-required | A free text expression of the | 1832 | | required version number | 1833 +---------------------------------+---------------------------------+ 1835 suit-text is OPTIONAL to implement. 1837 8.7. text-version-required 1839 suit-text-version-required is used to represent a version-based 1840 dependency on suit-parameter-version as described in Section 8.7.5.18 1841 and Section 8.7.6.8. To describe a version dependency, a Manifest 1842 Author SHOULD populate the suit-text map with a 1843 SUIT_Component_Identifier key for the dependency component, and place 1844 in the corresponding map a suit-text-version-required key with a free 1845 text expression that is representative of the version constraints 1846 placed on the dependency. This text SHOULD be expressive enough that 1847 a device operator can be expected to understand the dependency. This 1848 is a free text field and there are no specific formatting rules. 1850 By way of example only, to express a dependency on a component "['x', 1851 'y']", where the version should be any v1.x later than v1.2.5, but 1852 not v2.0 or above, the author would add the following structure to 1853 the suit-text element. Note that this text is in cbor-diag notation. 1855 [h'78',h'79'] : { 1856 7 : ">=1.2.5,<2" 1857 } 1859 8.7.1. suit-coswid 1861 suit-coswid contains a Concise Software Identifier (CoSWID) as 1862 defined in [I-D.ietf-sacm-coswid]. This element SHOULD be made 1863 severable so that it can be discarded by the Recipient or an 1864 intermediary if it is not required by the Recipient. 1866 suit-coswid typically requires no processing by the Recipient. 1867 However all Recipients MUST NOT fail if a suit-coswid is present. 1869 8.7.2. suit-common 1871 suit-common encodes all the information that is shared between each 1872 of the command sequences, including: suit-dependencies, suit- 1873 components, and suit-common-sequence. suit-common is REQUIRED to 1874 implement. 1876 suit-dependencies is a list of Section 8.7.2.1 blocks that specify 1877 manifests that must be present before the current manifest can be 1878 processed. suit-dependencies is OPTIONAL to implement. 1880 suit-components is a list of SUIT_Component_Identifier 1881 (Section 8.7.2.2) blocks that specify the component identifiers that 1882 will be affected by the content of the current manifest. suit- 1883 components is REQUIRED to implement; at least one manifest in a 1884 dependency tree MUST contain a suit-components block. 1886 suit-common-sequence is a SUIT_Command_Sequence to execute prior to 1887 executing any other command sequence. Typical actions in suit- 1888 common-sequence include setting expected Recipient identity and image 1889 digests when they are conditional (see Section 8.7.7.3 and 1890 Section 7.11 for more information on conditional sequences). suit- 1891 common-sequence is RECOMMENDED to implement. It is REQUIRED if the 1892 optimizations described in Section 6.2.1 will be used. Whenever a 1893 parameter or Try Each command is required by more than one Command 1894 Sequence, placing that parameter or commamd in suit-common-sequence 1895 results in a smaller encoding. 1897 8.7.2.1. Dependencies 1899 SUIT_Dependency specifies a manifest that describes a dependency of 1900 the current manifest. The Manifest is identified, but the Recipient 1901 should expect an Envelope when it acquires the dependency. This is 1902 because the Manifest is the one invariant element of the Envelope, 1903 where other elements may change by countersigning, adding 1904 authentication blocks, or severing elements. 1906 The suit-dependency-digest specifies the dependency manifest uniquely 1907 by identifying a particular Manifest structure. This is identical to 1908 the digest that would be present as the payload of any suit- 1909 authentication-block in the dependency's Envelope. The digest is 1910 calculated over the Manifest structure instead of the COSE 1911 Sig_structure or Mac_structure. This is necessary to ensure that 1912 removing a signature from a manifest does not break dependencies due 1913 to missing signature elements. This is also necessary to support the 1914 trusted intermediary use case, where an intermediary re-signs the 1915 Manifest, removing the original signature, potentially with a 1916 different algorithm, or trading COSE_Sign for COSE_Mac. 1918 The suit-dependency-prefix element contains a 1919 SUIT_Component_Identifier (see Section 8.7.2.2). This specifies the 1920 scope at which the dependency operates. This allows the dependency 1921 to be forwarded on to a component that is capable of parsing its own 1922 manifests. It also allows one manifest to be deployed to multiple 1923 dependent Recipients without those Recipients needing consistent 1924 component hierarchy. This element is OPTIONAL for Recipients to 1925 implement. 1927 A dependency prefix can be used with a component identifier. This 1928 allows complex systems to understand where dependencies need to be 1929 applied. The dependency prefix can be used in one of two ways. The 1930 first simply prepends the prefix to all Component Identifiers in the 1931 dependency. 1933 A dependency prefix can also be used to indicate when a dependency 1934 manifest needs to be processed by a secondary manifest processor, as 1935 described in Section 6.9. 1937 8.7.2.2. SUIT_Component_Identifier 1939 A component is a unit of code or data that can be targeted by an 1940 update. To facilitate composite devices, components are identified 1941 by a list of CBOR byte strings, which allows construction of 1942 hierarchical component structures. A dependency MAY declare a prefix 1943 to the components defined in the dependency manifest. Components are 1944 identified by Component Identifiers, but referenced in commands by 1945 Component Index; Component Identifiers are arrays of binary strings 1946 and a Component Index is an index into the array of Component 1947 Identifiers. 1949 A Component Identifier can be trivial, such as the simple array 1950 [h'00']. It can also represent a filesystem path by encoding each 1951 segment of the path as an element in the list. For example, the path 1952 "/usr/bin/env" would encode to ['usr','bin','env']. 1954 This hierarchical construction allows a component identifier to 1955 identify any part of a complex, multi-component system. 1957 8.7.3. SUIT_Command_Sequence 1959 A SUIT_Command_Sequence defines a series of actions that the 1960 Recipient MUST take to accomplish a particular goal. These goals are 1961 defined in the manifest and include: 1963 1. Dependency Resolution: suit-dependency-resolution is a 1964 SUIT_Command_Sequence to execute in order to perform dependency 1965 resolution. Typical actions include configuring URIs of 1966 dependency manifests, fetching dependency manifests, and 1967 validating dependency manifests' contents. suit-dependency- 1968 resolution is REQUIRED to implement and to use when suit- 1969 dependencies is present. 1971 2. Payload Fetch: suit-payload-fetch is a SUIT_Command_Sequence to 1972 execute in order to obtain a payload. Some manifests may include 1973 these actions in the suit-install section instead if they operate 1974 in a streaming installation mode. This is particularly relevant 1975 for constrained devices without any temporary storage for staging 1976 the update. suit-payload-fetch is OPTIONAL to implement. 1978 3. Payload Installation: suit-install is a SUIT_Command_Sequence to 1979 execute in order to install a payload. Typical actions include 1980 verifying a payload stored in temporary storage, copying a staged 1981 payload from temporary storage, and unpacking a payload. suit- 1982 install is OPTIONAL to implement. 1984 4. Image Validation: suit-validate is a SUIT_Command_Sequence to 1985 execute in order to validate that the result of applying the 1986 update is correct. Typical actions involve image validation and 1987 manifest validation. suit-validate is REQUIRED to implement. If 1988 the manifest contains dependencies, one process-dependency 1989 invocation per dependency or one process-dependency invocation 1990 targeting all dependencies SHOULD be present in validate. 1992 5. Image Loading: suit-load is a SUIT_Command_Sequence to execute in 1993 order to prepare a payload for execution. Typical actions 1994 include copying an image from permanent storage into RAM, 1995 optionally including actions such as decryption or decompression. 1996 suit-load is OPTIONAL to implement. 1998 6. Run or Boot: suit-run is a SUIT_Command_Sequence to execute in 1999 order to run an image. suit-run typically contains a single 2000 instruction: either the "run" directive for the invocable 2001 manifest or the "process dependencies" directive for any 2002 dependents of the invocable manifest. suit-run is OPTIONAL to 2003 implement. 2005 Goals 1,2,3 form the Update Procedure. Goals 4,5,6 form the 2006 Invocation Procedure. 2008 Each Command Sequence follows exactly the same structure to ensure 2009 that the parser is as simple as possible. 2011 Lists of commands are constructed from two kinds of element: 2013 1. Conditions that MUST be true and any failure is treated as a 2014 failure of the update/load/invocation 2016 2. Directives that MUST be executed. 2018 Each condition is composed of: 2020 1. A command code identifier 2022 2. A SUIT_Reporting_Policy (Section 8.7.4) 2024 Each directive is composed of: 2026 1. A command code identifier 2028 2. An argument block or a SUIT_Reporting_Policy (Section 8.7.4) 2029 Argument blocks are consumed only by flow-control directives: 2031 - Set Component/Dependency Index 2033 - Set/Override Parameters 2035 - Try Each 2037 - Run Sequence 2039 Reporting policies provide a hint to the manifest processor of 2040 whether to add the success or failure of a command to any report that 2041 it generates. 2043 Many conditions and directives apply to a given component, and these 2044 generally grouped together. Therefore, a special command to set the 2045 current component index is provided with a matching command to set 2046 the current dependency index. This index is a numeric index into the 2047 Component Identifier tables defined at the beginning of the manifest. 2048 For the purpose of setting the index, the two Component Identifier 2049 tables are considered to be concatenated together. 2051 To facilitate optional conditions, a special directive, suit- 2052 directive-try-each (Section 8.7.7.3), is provided. It runs several 2053 new lists of conditions/directives, one after another, that are 2054 contained as an argument to the directive. By default, it assumes 2055 that a failure of a condition should not indicate a failure of the 2056 update/invocation, but a parameter is provided to override this 2057 behavior. See suit-parameter-soft-failure (Section 8.7.5.23). 2059 8.7.4. Reporting Policy 2061 To facilitate construction of Reports that describe the success, or 2062 failure of a given Procedure, each command is given a Reporting 2063 Policy. This is an integer bitfield that follows the command and 2064 indicates what the Recipient should do with the Record of executing 2065 the command. The options are summarized in the table below. 2067 +-----------------------------+-------------------------------------+ 2068 | Policy | Description | 2069 +-----------------------------+-------------------------------------+ 2070 | suit-send-record-on-success | Record when the command succeeds | 2071 | | | 2072 | suit-send-record-on-failure | Record when the command fails | 2073 | | | 2074 | suit-send-sysinfo-success | Add system information when the | 2075 | | command succeeds | 2076 | | | 2077 | suit-send-sysinfo-failure | Add system information when the | 2078 | | command fails | 2079 +-----------------------------+-------------------------------------+ 2081 Any or all of these policies may be enabled at once. 2083 At the completion of each command, a recipient MAY forward that 2084 command's reporting policy, the result of the command, the current 2085 set of parameters, and the system information consumed by the command 2086 to a TODO 2088 several information elements are provided to an implementation 2089 defined subsystem, the Reporting Engine: 2091 - The reporting policies 2093 - The result of the command 2095 - The parameters consumed by the command 2097 - The system information consumed by the command 2099 If the component index is set to True or an array when a command is 2100 executed with a non-zero reporting policy, then the Reporting Engine 2101 MUST receive one Record for each Component, in the order expressed in 2102 the Components list or the component index array, respectively. If 2103 the dependency index is set to True or an array when a command is 2104 executed with a non-zero reporting policy, then the Reporting Engine 2105 MUST receive one Record for each Dependency, in the order expressed 2106 in the Dependencies list or the component index array, respectively. 2108 This specification does define a particular format of Records or 2109 Reports. This specification only defines hints to the Reporting 2110 Engine for which Records it should aggregate into the Report. The 2111 Reporting Engine MAY choose to ignore these hints and apply its own 2112 policy instead. 2114 When used in a Invocation Process, the report MAY form the basis of 2115 an attestation report. When used in an Update Process, the report 2116 MAY form the basis for one or more log entries. 2118 8.7.5. SUIT_Parameters 2120 Many conditions and directives require additional information. That 2121 information is contained within parameters that can be set in a 2122 consistent way. This allows reduction of manifest size and 2123 replacement of parameters from one manifest to the next. 2125 Most parameters are scoped to a specific component. This means that 2126 setting a parameter for one component has no effect on the parameters 2127 of any other component. The only exceptions to this are two Manifest 2128 Processor parameters: Strict Order and Soft Failure. 2130 The defined manifest parameters are described below. 2132 +----------------+----------------------------------+---------------+ 2133 | Name | CDDL Structure | Reference | 2134 +----------------+----------------------------------+---------------+ 2135 | Vendor ID | suit-parameter-vendor-identifier | Section 8.7.5 | 2136 | | | .3 | 2137 | | | | 2138 | Class ID | suit-parameter-class-identifier | Section 8.7.5 | 2139 | | | .4 | 2140 | | | | 2141 | Device ID | suit-parameter-device-identifier | Section 8.7.5 | 2142 | | | .5 | 2143 | | | | 2144 | Image Digest | suit-parameter-image-digest | Section 8.7.5 | 2145 | | | .6 | 2146 | | | | 2147 | Image Size | suit-parameter-image-size | Section 8.7.5 | 2148 | | | .7 | 2149 | | | | 2150 | Use Before | suit-parameter-use-before | Section 8.7.5 | 2151 | | | .8 | 2152 | | | | 2153 | Component | suit-parameter-component-offset | Section 8.7.5 | 2154 | Offset | | .9 | 2155 | | | | 2156 | Encryption | suit-parameter-encryption-info | Section 8.7.5 | 2157 | Info | | .10 | 2158 | | | | 2159 | Compression | suit-parameter-compression-info | Section 8.7.5 | 2160 | Info | | .11 | 2161 | | | | 2162 | Unpack Info | suit-parameter-unpack-info | Section 8.7.5 | 2163 | | | .12 | 2164 | | | | 2165 | URI | suit-parameter-uri | Section 8.7.5 | 2166 | | | .13 | 2167 | | | | 2168 | Source | suit-parameter-source-component | Section 8.7.5 | 2169 | Component | | .14 | 2170 | | | | 2171 | Run Args | suit-parameter-run-args | Section 8.7.5 | 2172 | | | .15 | 2173 | | | | 2174 | Minimum | suit-parameter-minimum-battery | Section 8.7.5 | 2175 | Battery | | .16 | 2176 | | | | 2177 | Update | suit-parameter-update-priority | Section 8.7.5 | 2178 | Priority | | .17 | 2179 | | | | 2180 | Version | suit-parameter-version | Section 8.7.5 | 2181 | | | .18 | 2182 | | | | 2183 | Wait Info | suit-parameter-wait-info | Section 8.7.5 | 2184 | | | .19 | 2185 | | | | 2186 | URI List | suit-parameter-uri-list | Section 8.7.5 | 2187 | | | .20 | 2188 | | | | 2189 | Fetch | suit-parameter-fetch-arguments | Section 8.7.5 | 2190 | Arguments | | .21 | 2191 | | | | 2192 | Strict Order | suit-parameter-strict-order | Section 8.7.5 | 2193 | | | .22 | 2194 | | | | 2195 | Soft Failure | suit-parameter-soft-failure | Section 8.7.5 | 2196 | | | .23 | 2197 | | | | 2198 | Custom | suit-parameter-custom | Section 8.7.5 | 2199 | | | .24 | 2200 +----------------+----------------------------------+---------------+ 2202 CBOR-encoded object parameters are still wrapped in a bstr. This is 2203 because it allows a parser that is aggregating parameters to 2204 reference the object with a single pointer and traverse it without 2205 understanding the contents. This is important for modularization and 2206 division of responsibility within a pull parser. The same 2207 consideration does not apply to Directives because those elements are 2208 invoked with their arguments immediately 2210 8.7.5.1. CBOR PEN UUID Namespace Identifier 2212 The CBOR PEN UUID Namespace Identifier is constructed as follows: 2214 It uses the OID Namespace as a starting point, then uses the CBOR OID 2215 encoding for the IANA PEN OID (1.3.6.1.4.1): 2217 D8 DE # tag(111) 2218 45 # bytes(5) 2219 2B 06 01 04 01 # X.690 Clause 8.19 2220 # 1.3 6 1 4 1 show component encoding 2222 Computing a type 5 UUID from these produces: 2224 NAMESPACE_CBOR_PEN = UUID5(NAMESPACE_OID, h'D86F452B06010401') 2225 NAMESPACE_CBOR_PEN = 08cfcc43-47d9-5696-85b1-9c738465760e 2227 8.7.5.2. Constructing UUIDs 2229 Several conditions use identifiers to determine whether a manifest 2230 matches a given Recipient or not. These identifiers are defined to 2231 be RFC 4122 [RFC4122] UUIDs. These UUIDs are not human-readable and 2232 are therefore used for machine-based processing only. 2234 A Recipient MAY match any number of UUIDs for vendor or class 2235 identifier. This may be relevant to physical or software modules. 2236 For example, a Recipient that has an OS and one or more applications 2237 might list one Vendor ID for the OS and one or more additional Vendor 2238 IDs for the applications. This Recipient might also have a Class ID 2239 that must be matched for the OS and one or more Class IDs for the 2240 applications. 2242 Identifiers are used for compatibility checks. They MUST NOT be used 2243 as assertions of identity. They are evaluated by identifier 2244 conditions (Section 8.7.6.1). 2246 A more complete example: Imagine a device has the following physical 2247 components: 1. A host MCU 2. A WiFi module 2249 This same device has three software modules: 1. An operating system 2250 2. A WiFi module interface driver 3. An application 2252 Suppose that the WiFi module's firmware has a proprietary update 2253 mechanism and doesn't support manifest processing. This device can 2254 report four class IDs: 2256 1. Hardware model/revision 2257 2. OS 2259 3. WiFi module model/revision 2261 4. Application 2263 This allows the OS, WiFi module, and application to be updated 2264 independently. To combat possible incompatibilities, the OS class ID 2265 can be changed each time the OS has a change to its API. 2267 This approach allows a vendor to target, for example, all devices 2268 with a particular WiFi module with an update, which is a very 2269 powerful mechanism, particularly when used for security updates. 2271 UUIDs MUST be created according to RFC 4122 [RFC4122]. UUIDs SHOULD 2272 use versions 3, 4, or 5, as described in RFC4122. Versions 1 and 2 2273 do not provide a tangible benefit over version 4 for this 2274 application. 2276 The RECOMMENDED method to create a vendor ID is: 2278 Vendor ID = UUID5(DNS_PREFIX, vendor domain name) 2280 If the Vendor ID is a UUID, the RECOMMENDED method to create a Class 2281 ID is: 2283 Class ID = UUID5(Vendor ID, Class-Specific-Information) 2285 If the Vendor ID is a CBOR PEN (see Section 8.7.5.3), the RECOMMENDED 2286 method to create a Class ID is: 2288 Class ID = UUID5( 2289 UUID5(NAMESPACE_CBOR_PEN, CBOR_PEN), 2290 Class-Specific-Information) 2292 Class-specific-information is composed of a variety of data, for 2293 example: 2295 - Model number. 2297 - Hardware revision. 2299 - Bootloader version (for immutable bootloaders). 2301 8.7.5.3. suit-parameter-vendor-identifier 2303 suit-parameter-vendor-identifier may be presented in one of two ways: 2305 - A Private Enterprise Number 2307 - A byte string containing a UUID ([RFC4122]) 2309 Private Enterprise Numbers are encoded as a relative OID, according 2310 to the definition in [I-D.ietf-cbor-tags-oid]. All PENs are relative 2311 to the IANA PEN: 1.3.6.1.4.1. 2313 8.7.5.4. suit-parameter-class-identifier 2315 A RFC 4122 UUID representing the class of the device or component. 2316 The UUID is encoded as a 16 byte bstr, containing the raw bytes of 2317 the UUID. It MUST be constructed as described in Section 8.7.5.2 2319 8.7.5.5. suit-parameter-device-identifier 2321 A RFC 4122 UUID representing the specific device or component. The 2322 UUID is encoded as a 16 byte bstr, containing the raw bytes of the 2323 UUID. It MUST be constructed as described in Section 8.7.5.2 2325 8.7.5.6. suit-parameter-image-digest 2327 A fingerprint computed over the component itself, encoded in the 2328 SUIT_Digest Section 10 structure. The SUIT_Digest is wrapped in a 2329 bstr, as required in Section 8.7.5. 2331 8.7.5.7. suit-parameter-image-size 2333 The size of the firmware image in bytes. This size is encoded as a 2334 positive integer. 2336 8.7.5.8. suit-parameter-use-before 2338 An expiry date for the use of the manifest encoded as the positive 2339 integer number of seconds since 1970-01-01. Implementations that use 2340 this parameter MUST use a 64-bit internal representation of the 2341 integer. 2343 8.7.5.9. suit-parameter-component-offset 2345 This parameter sets the offset in a component. Some components 2346 support multiple possible Slots (offsets into a storage area). This 2347 parameter describes the intended Slot to use, identified by its 2348 offset into the component's storage area. This offset MUST be 2349 encoded as a positive integer. 2351 8.7.5.10. suit-parameter-encryption-info 2353 Encryption Info defines the mechanism that Fetch or Copy should use 2354 to decrypt the data they transfer. SUIT_Parameter_Encryption_Info is 2355 encoded as a COSE_Encrypt_Tagged or a COSE_Encrypt0_Tagged, wrapped 2356 in a bstr. 2358 8.7.5.11. suit-parameter-compression-info 2360 SUIT_Compression_Info defines any information that is required for a 2361 Recipient to perform decompression operations. SUIT_Compression_Info 2362 is a map containing this data. The only element defined for the map 2363 in this specification is the suit-compression-algorithm. This 2364 document defines the following suit-compression-algorithm's: ZLIB 2365 [RFC1950], Brotli [RFC7932], and ZSTD [I-D.kucherawy-rfc8478bis]. 2367 Additional suit-compression-algorithm's can be registered through the 2368 IANA-maintained registry. If such a format requires more data than 2369 an algorithm identifier, one or more new elements MUST be introduced 2370 by specifying an element for SUIT_Compression_Info-extensions. 2372 8.7.5.12. suit-parameter-unpack-info 2374 SUIT_Unpack_Info defines the information required for a Recipient to 2375 interpret a packed format. This document defines the use of the 2376 following binary encodings: Intel HEX [HEX], Motorola S-record 2377 [SREC], Executable and Linkable Format (ELF) [ELF], and Common Object 2378 File Format (COFF) [COFF]. 2380 Additional packing formats can be registered through the IANA- 2381 maintained registry. 2383 8.7.5.13. suit-parameter-uri 2385 A URI from which to fetch a resource, encoded as a text string. CBOR 2386 Tag 32 is not used because the meaning of the text string is 2387 unambiguous in this context. 2389 8.7.5.14. suit-parameter-source-component 2391 This parameter sets the source component to be used with either suit- 2392 directive-copy (Section 8.7.7.9) or with suit-directive-swap 2393 (Section 8.7.7.13). The current Component, as set by suit-directive- 2394 set-component-index defines the destination, and suit-parameter- 2395 source-component defines the source. 2397 8.7.5.15. suit-parameter-run-args 2399 This parameter contains an encoded set of arguments for suit- 2400 directive-run (Section 8.7.7.10). The arguments MUST be provided as 2401 an implementation-defined bstr. 2403 8.7.5.16. suit-parameter-minimum-battery 2405 This parameter sets the minimum battery level in mWh. This parameter 2406 is encoded as a positive integer. Used with suit-condition-minimum- 2407 battery (Section 8.7.6.6). 2409 8.7.5.17. suit-parameter-update-priority 2411 This parameter sets the priority of the update. This parameter is 2412 encoded as an integer. It is used along with suit-condition-update- 2413 authorized (Section 8.7.6.7) to ask an application for permission to 2414 initiate an update. This does not constitute a privilege inversion 2415 because an explicit request for authorization has been provided by 2416 the Update Authority in the form of the suit-condition-update- 2417 authorized command. 2419 Applications MAY define their own meanings for the update priority. 2420 For example, critical reliability & vulnerability fixes MAY be given 2421 negative numbers, while bug fixes MAY be given small positive 2422 numbers, and feature additions MAY be given larger positive numbers, 2423 which allows an application to make an informed decision about 2424 whether and when to allow an update to proceed. 2426 8.7.5.18. suit-parameter-version 2428 Indicates allowable versions for the specified component. Allowable 2429 versions can be specified, either with a list or with range matching. 2430 This parameter is compared with version asserted by the current 2431 component when suit-condition-version (Section 8.7.6.8) is invoked. 2432 The current component may assert the current version in many ways, 2433 including storage in a parameter storage database, in a metadata 2434 object, or in a known location within the component itself. 2436 The component version can be compared as: 2438 - Greater. 2440 - Greater or Equal. 2442 - Equal. 2444 - Lesser or Equal. 2446 - Lesser. 2448 Versions are encoded as a CBOR list of integers. Comparisons are 2449 done on each integer in sequence. Comparison stops after all 2450 integers in the list defined by the manifest have been consumed OR 2451 after a non-equal match has occurred. For example, if the manifest 2452 defines a comparison, "Equal [1]", then this will match all version 2453 sequences starting with 1. If a manifest defines both "Greater or 2454 Equal [1,0]" and "Lesser [1,10]", then it will match versions 1.0.x 2455 up to, but not including 1.10. 2457 While the exact encoding of versions is application-defined, semantic 2458 versions map conveniently. For example, 2460 - 1.2.3 = [1,2,3]. 2462 - 1.2-rc3 = [1,2,-1,3]. 2464 - 1.2-beta = [1,2,-2]. 2466 - 1.2-alpha = [1,2,-3]. 2468 - 1.2-alpha4 = [1,2,-3,4]. 2470 suit-condition-version is OPTIONAL to implement. 2472 Versions SHOULD be provided as follows: 2474 1. The first integer represents the major number. This indicates 2475 breaking changes to the component. 2477 2. The second integer represents the minor number. This is 2478 typically reserved for new features or large, non-breaking 2479 changes. 2481 3. The third integer is the patch version. This is typically 2482 reserved for bug fixes. 2484 4. The fourth integer is the build number. 2486 Where Alpha (-3), Beta (-2), and Release Candidate (-1) are used, 2487 they are inserted as a negative number between Minor and Patch 2488 numbers. This allows these releases to compare correctly with final 2489 releases. For example, Version 2.0, RC1 should be lower than Version 2490 2.0.0 and higher than any Version 1.x. By encoding RC as -1, this 2491 works correctly: [2,0,-1,1] compares as lower than [2,0,0]. 2492 Similarly, beta (-2) is lower than RC and alpha (-3) is lower than 2493 RC. 2495 8.7.5.19. suit-parameter-wait-info 2497 suit-directive-wait (Section 8.7.7.11) directs the manifest processor 2498 to pause until a specified event occurs. The suit-parameter-wait- 2499 info encodes the parameters needed for the directive. 2501 The exact implementation of the pause is implementation-defined. For 2502 example, this could be done by blocking on a semaphore, registering 2503 an event handler and suspending the manifest processor, polling for a 2504 notification, or aborting the update entirely, then restarting when a 2505 notification is received. 2507 suit-parameter-wait-info is encoded as a map of wait events. When 2508 ALL wait events are satisfied, the Manifest Processor continues. The 2509 wait events currently defined are described in the following table. 2511 +------------------------------+---------+--------------------------+ 2512 | Name | Encodin | Description | 2513 | | g | | 2514 +------------------------------+---------+--------------------------+ 2515 | suit-wait-event- | int | Same as suit-parameter- | 2516 | authorization | | update-priority | 2517 | | | | 2518 | suit-wait-event-power | int | Wait until power state | 2519 | | | | 2520 | suit-wait-event-network | int | Wait until network state | 2521 | | | | 2522 | suit-wait-event-other- | See | Wait for other device to | 2523 | device-version | below | match version | 2524 | | | | 2525 | suit-wait-event-time | uint | Wait until time (seconds | 2526 | | | since 1970-01-01) | 2527 | | | | 2528 | suit-wait-event-time-of-day | uint | Wait until seconds since | 2529 | | | 00:00:00 | 2530 | | | | 2531 | suit-wait-event-time-of-day- | uint | Wait until seconds since | 2532 | utc | | 00:00:00 UTC | 2533 | | | | 2534 | suit-wait-event-day-of-week | uint | Wait until days since | 2535 | | | Sunday | 2536 | | | | 2537 | suit-wait-event-day-of-week- | uint | Wait until days since | 2538 | utc | | Sunday UTC | 2539 +------------------------------+---------+--------------------------+ 2541 suit-wait-event-other-device-version reuses the encoding of suit- 2542 parameter-version-match. It is encoded as a sequence that contains 2543 an implementation-defined bstr identifier for the other device, and a 2544 list of one or more SUIT_Parameter_Version_Match. 2546 8.7.5.20. suit-parameter-uri-list 2548 Indicates a list of URIs from which to fetch a resource. The URI 2549 list is encoded as a list of text string, in priority order. CBOR 2550 Tag 32 is not used because the meaning of the text string is 2551 unambiguous in this context. The Recipient should attempt to fetch 2552 the resource from each URI in turn, ruling out each, in order, if the 2553 resource is inaccessible or it is otherwise undesirable to fetch from 2554 that URI. suit-parameter-uri-list is consumed by suit-directive- 2555 fetch-uri-list (Section 8.7.7.8). 2557 8.7.5.21. suit-parameter-fetch-arguments 2559 An implementation-defined set of arguments to suit-directive-fetch 2560 (Section 8.7.7.7). Arguments are encoded in a bstr. 2562 8.7.5.22. suit-parameter-strict-order 2564 The Strict Order Parameter allows a manifest to govern when 2565 directives can be executed out-of-order. This allows for systems 2566 that have a sensitivity to order of updates to choose the order in 2567 which they are executed. It also allows for more advanced systems to 2568 parallelize their handling of updates. Strict Order defaults to 2569 True. It MAY be set to False when the order of operations does not 2570 matter. When arriving at the end of a command sequence, ALL commands 2571 MUST have completed, regardless of the state of 2572 SUIT_Parameter_Strict_Order. SUIT_Process_Dependency must preserve 2573 and restore the state of SUIT_Parameter_Strict_Order. If 2574 SUIT_Parameter_Strict_Order is returned to True, ALL preceding 2575 commands MUST complete before the next command is executed. 2577 See Section 6.7 for behavioral description of Strict Order. 2579 8.7.5.23. suit-parameter-soft-failure 2581 When executing a command sequence inside suit-directive-try-each 2582 (Section 8.7.7.3) or suit-directive-run-sequence (Section 8.7.7.12) 2583 and a condition failure occurs, the manifest processor aborts the 2584 sequence. For suit-directive-try-each, if Soft Failure is True, the 2585 next sequence in Try Each is invoked, otherwise suit-directive-try- 2586 each fails with the condition failure code. In suit-directive-run- 2587 sequence, if Soft Failure is True the suit-directive-run-sequence 2588 simply halts with no side-effects and the Manifest Processor 2589 continues with the following command, otherwise, the suit-directive- 2590 run-sequence fails with the condition failure code. 2592 suit-parameter-soft-failure is scoped to the enclosing 2593 SUIT_Command_Sequence. Its value is discarded when 2594 SUIT_Command_Sequence terminates. It MUST NOT be set outside of 2595 suit-directive-try-each or suit-directive-run-sequence. 2597 When suit-directive-try-each is invoked, Soft Failure defaults to 2598 True. An Update Author may choose to set Soft Failure to False if 2599 they require a failed condition in a sequence to force an Abort. 2601 When suit-directive-run-sequence is invoked, Soft Failure defaults to 2602 False. An Update Author may choose to make failures soft within a 2603 suit-directive-run-sequence. 2605 8.7.5.24. suit-parameter-custom 2607 This parameter is an extension point for any proprietary, application 2608 specific conditions and directives. It MUST NOT be used in the 2609 common sequence. This effectively scopes each custom command to a 2610 particular Vendor Identifier/Class Identifier pair. 2612 8.7.6. SUIT_Condition 2614 Conditions are used to define mandatory properties of a system in 2615 order for an update to be applied. They can be pre-conditions or 2616 post-conditions of any directive or series of directives, depending 2617 on where they are placed in the list. All Conditions specify a 2618 Reporting Policy as described Section 8.7.4. Conditions include: 2620 +----------------+----------------------------------+---------------+ 2621 | Name | CDDL Structure | Reference | 2622 +----------------+----------------------------------+---------------+ 2623 | Vendor | suit-condition-vendor-identifier | Section 8.7.6 | 2624 | Identifier | | .1 | 2625 | | | | 2626 | Class | suit-condition-class-identifier | Section 8.7.6 | 2627 | Identifier | | .1 | 2628 | | | | 2629 | Device | suit-condition-device-identifier | Section 8.7.6 | 2630 | Identifier | | .1 | 2631 | | | | 2632 | Image Match | suit-condition-image-match | Section 8.7.6 | 2633 | | | .2 | 2634 | | | | 2635 | Image Not | suit-condition-image-not-match | Section 8.7.6 | 2636 | Match | | .3 | 2637 | | | | 2638 | Use Before | suit-condition-use-before | Section 8.7.6 | 2639 | | | .4 | 2640 | | | | 2641 | Component | suit-condition-component-offset | Section 8.7.6 | 2642 | Offset | | .5 | 2643 | | | | 2644 | Minimum | suit-condition-minimum-battery | Section 8.7.6 | 2645 | Battery | | .6 | 2646 | | | | 2647 | Update | suit-condition-update-authorized | Section 8.7.6 | 2648 | Authorized | | .7 | 2649 | | | | 2650 | Version | suit-condition-version | Section 8.7.6 | 2651 | | | .8 | 2652 | | | | 2653 | Abort | suit-condition-abort | Section 8.7.6 | 2654 | | | .9 | 2655 | | | | 2656 | Custom | suit-condition-custom | Section 8.7.6 | 2657 | Condition | | .10 | 2658 +----------------+----------------------------------+---------------+ 2660 The abstract description of these conditions is defined in 2661 Section 6.4. 2663 Conditions compare parameters against properties of the system. 2664 These properties may be asserted in many different ways, including: 2665 calculation on-demand, volatile definition in memory, static 2666 definition within the manifest processor, storage in known location 2667 within an image, storage within a key storage system, storage in One- 2668 Time-Programmable memory, inclusion in mask ROM, or inclusion as a 2669 register in hardware. Some of these assertion methods are global in 2670 scope, such as a hardware register, some are scoped to an individual 2671 component, such as storage at a known location in an image, and some 2672 assertion methods can be either global or component-scope, based on 2673 implementation. 2675 Each condition MUST report a result code on completion. If a 2676 condition reports failure, then the current sequence of commands MUST 2677 terminate. A subsequent command or command sequence MAY continue 2678 executing if suit-parameter-soft-failure (Section 8.7.5.23) is set. 2679 If a condition requires additional information, this MUST be 2680 specified in one or more parameters before the condition is executed. 2681 If a Recipient attempts to process a condition that expects 2682 additional information and that information has not been set, it MUST 2683 report a failure. If a Recipient encounters an unknown condition, it 2684 MUST report a failure. 2686 Condition labels in the positive number range are reserved for IANA 2687 registration while those in the negative range are custom conditions 2688 reserved for proprietary definition by the author of a manifest 2689 processor. See Section 11 for more details. 2691 8.7.6.1. suit-condition-vendor-identifier, suit-condition-class- 2692 identifier, and suit-condition-device-identifier 2694 There are three identifier-based conditions: suit-condition-vendor- 2695 identifier, suit-condition-class-identifier, and suit-condition- 2696 device-identifier. Each of these conditions match a RFC 4122 2697 [RFC4122] UUID that MUST have already been set as a parameter. The 2698 installing Recipient MUST match the specified UUID in order to 2699 consider the manifest valid. These identifiers are scoped by 2700 component in the manifest. Each component MAY match more than one 2701 identifier. Care is needed to ensure that manifests correctly 2702 identify their targets using these conditions. Using only a generic 2703 class ID for a device-specific firmware could result in matching 2704 devices that are not compatible. 2706 The Recipient uses the ID parameter that has already been set using 2707 the Set Parameters directive. If no ID has been set, this condition 2708 fails. suit-condition-class-identifier and suit-condition-vendor- 2709 identifier are REQUIRED to implement. suit-condition-device- 2710 identifier is OPTIONAL to implement. 2712 Each identifier condition compares the corresponding identifier 2713 parameter to a parameter asserted to the Manifest Processor by the 2714 Recipient. Identifiers MUST be known to the Manifest Processor in 2715 order to evaluate compatibility. 2717 8.7.6.2. suit-condition-image-match 2719 Verify that the current component matches the suit-parameter-image- 2720 digest (Section 8.7.5.6) for the current component. The digest is 2721 verified against the digest specified in the Component's parameters 2722 list. If no digest is specified, the condition fails. suit- 2723 condition-image-match is REQUIRED to implement. 2725 8.7.6.3. suit-condition-image-not-match 2727 Verify that the current component does not match the suit-parameter- 2728 image-digest (Section 8.7.5.6). If no digest is specified, the 2729 condition fails. suit-condition-image-not-match is OPTIONAL to 2730 implement. 2732 8.7.6.4. suit-condition-use-before 2734 Verify that the current time is BEFORE the specified time. suit- 2735 condition-use-before is used to specify the last time at which an 2736 update should be installed. The recipient evaluates the current time 2737 against the suit-parameter-use-before parameter (Section 8.7.5.8), 2738 which must have already been set as a parameter, encoded as seconds 2739 after 1970-01-01 00:00:00 UTC. Timestamp conditions MUST be 2740 evaluated in 64 bits, regardless of encoded CBOR size. suit- 2741 condition-use-before is OPTIONAL to implement. 2743 8.7.6.5. suit-condition-component-offset 2745 Verify that the offset of the current component matches the offset 2746 set in suit-parameter-component-offset (Section 8.7.5.9). This 2747 condition allows a manifest to select between several images to match 2748 a target offset. 2750 8.7.6.6. suit-condition-minimum-battery 2752 suit-condition-minimum-battery provides a mechanism to test a 2753 Recipient's battery level before installing an update. This 2754 condition is primarily for use in primary-cell applications, where 2755 the battery is only ever discharged. For batteries that are charged, 2756 suit-directive-wait is more appropriate, since it defines a "wait" 2757 until the battery level is sufficient to install the update. suit- 2758 condition-minimum-battery is specified in mWh. suit-condition- 2759 minimum-battery is OPTIONAL to implement. suit-condition-minimum- 2760 battery consumes suit-parameter-minimum-battery (Section 8.7.5.16). 2762 8.7.6.7. suit-condition-update-authorized 2764 Request Authorization from the application and fail if not 2765 authorized. This can allow a user to decline an update. suit- 2766 parameter-update-priority (Section 8.7.5.17) provides an integer 2767 priority level that the application can use to determine whether or 2768 not to authorize the update. Priorities are application defined. 2769 suit-condition-update-authorized is OPTIONAL to implement. 2771 8.7.6.8. suit-condition-version 2773 suit-condition-version allows comparing versions of firmware. 2774 Verifying image digests is preferred to version checks because 2775 digests are more precise. suit-condition-version examines a 2776 component's version against the version info specified in suit- 2777 parameter-version (Section 8.7.5.18) 2779 8.7.6.9. suit-condition-abort 2781 Unconditionally fail. This operation is typically used in 2782 conjunction with suit-directive-try-each (Section 8.7.7.3). 2784 8.7.6.10. suit-condition-custom 2786 suit-condition-custom describes any proprietary, application specific 2787 condition. This is encoded as a negative integer, chosen by the 2788 firmware developer. If additional information must be provided to 2789 the condition, it should be encoded in a custom parameter (a nint) as 2790 described in Section 8.7.5. SUIT_Condition_Custom is OPTIONAL to 2791 implement. 2793 8.7.7. SUIT_Directive 2795 Directives are used to define the behavior of the recipient. 2796 Directives include: 2798 +---------------+-------------------------------------+-------------+ 2799 | Name | CDDL Structure | Reference | 2800 +---------------+-------------------------------------+-------------+ 2801 | Set Component | suit-directive-set-component-index | Section 8.7 | 2802 | Index | | .7.1 | 2803 | | | | 2804 | Set | suit-directive-set-dependency-index | Section 8.7 | 2805 | Dependency | | .7.2 | 2806 | Index | | | 2807 | | | | 2808 | Try Each | suit-directive-try-each | Section 8.7 | 2809 | | | .7.3 | 2810 | | | | 2811 | Process | suit-directive-process-dependency | Section 8.7 | 2812 | Dependency | | .7.4 | 2813 | | | | 2814 | Set | suit-directive-set-parameters | Section 8.7 | 2815 | Parameters | | .7.5 | 2816 | | | | 2817 | Override | suit-directive-override-parameters | Section 8.7 | 2818 | Parameters | | .7.6 | 2819 | | | | 2820 | Fetch | suit-directive-fetch | Section 8.7 | 2821 | | | .7.7 | 2822 | | | | 2823 | Fetch URI | suit-directive-fetch-uri-list | Section 8.7 | 2824 | list | | .7.8 | 2825 | | | | 2826 | Copy | suit-directive-copy | Section 8.7 | 2827 | | | .7.9 | 2828 | | | | 2829 | Run | suit-directive-run | Section 8.7 | 2830 | | | .7.10 | 2831 | | | | 2832 | Wait For | suit-directive-wait | Section 8.7 | 2833 | Event | | .7.11 | 2834 | | | | 2835 | Run Sequence | suit-directive-run-sequence | Section 8.7 | 2836 | | | .7.12 | 2837 | | | | 2838 | Swap | suit-directive-swap | Section 8.7 | 2839 | | | .7.13 | 2840 +---------------+-------------------------------------+-------------+ 2842 The abstract description of these commands is defined in Section 6.4. 2844 When a Recipient executes a Directive, it MUST report a result code. 2845 If the Directive reports failure, then the current Command Sequence 2846 MUST be terminated. 2848 8.7.7.1. suit-directive-set-component-index 2850 Set Component Index defines the component to which successive 2851 directives and conditions will apply. The supplied argument MUST be 2852 one of three types: 2854 1. An unsigned integer (REQUIRED to implement in parser) 2856 2. A boolean (REQUIRED to implement in parser ONLY IF 2 or more 2857 components supported) 2859 3. An array of unsigned integers (REQUIRED to implement in parser 2860 ONLY IF 3 or more components supported) 2862 If the following commands apply to ONE component, an unsigned integer 2863 index into the component list is used. If the following commands 2864 apply to ALL components, then the boolean value "True" is used 2865 instead of an index. If the following commands apply to more than 2866 one, but not all components, then an array of unsigned integer 2867 indices into the component list is used. TODO: Component list 2869 If the following commands apply to NO components, then the boolean 2870 value "False" is used. When suit-directive-set-dependency-index is 2871 used, suit-directive-set-component-index = False is implied. When 2872 suit-directive-set-component-index is used, suit-directive-set- 2873 dependency-index = False is implied. 2875 If component index is set to True when a command is invoked, then the 2876 command applies to all components, in the order they appear in suit- 2877 common-components. When the Manifest Processor invokes a command 2878 while the component index is set to True, it must execute the command 2879 once for each possible component index, ensuring that the command 2880 receives the parameters corresponding to that component index. 2882 8.7.7.2. suit-directive-set-dependency-index 2884 Set Dependency Index defines the manifest to which successive 2885 directives and conditions will apply. The supplied argument MUST be 2886 either a boolean or an unsigned integer index into the dependencies. 2887 If the following directives apply to ALL dependencies, then the 2888 boolean value "True" is used instead of an index. If the following 2889 directives apply to NO dependencies, then the boolean value "False" 2890 is used. When suit-directive-set-component-index is used, suit- 2891 directive-set-dependency-index = False is implied. When suit- 2892 directive-set-dependency-index is used, suit-directive-set-component- 2893 index = False is implied. TODO: Component list|Dependency List 2895 If dependency index is set to True when a command is invoked, then 2896 the command applies to all dependencies, in the order they appear in 2897 suit-common-components. When the Manifest Processor invokes a 2898 command while the dependency index is set to True, it must execute 2899 the command once for each possible dependency index, ensuring that 2900 the command receives the parameters corresponding to that dependency 2901 index. 2903 Typical operations that require suit-directive-set-dependency-index 2904 include setting a source URI or Encryption Information, invoking 2905 "Fetch," or invoking "Process Dependency" for an individual 2906 dependency. 2908 8.7.7.3. suit-directive-try-each 2910 This command runs several SUIT_Command_Sequence instances, one after 2911 another, in a strict order. Use this command to implement a "try/ 2912 catch-try/catch" sequence. Manifest processors MAY implement this 2913 command. 2915 suit-parameter-soft-failure (Section 8.7.5.23) is initialized to True 2916 at the beginning of each sequence. If one sequence aborts due to a 2917 condition failure, the next is started. If no sequence completes 2918 without condition failure, then suit-directive-try-each returns an 2919 error. If a particular application calls for all sequences to fail 2920 and still continue, then an empty sequence (nil) can be added to the 2921 Try Each Argument. 2923 The argument to suit-directive-try-each is a list of 2924 SUIT_Command_Sequence. suit-directive-try-each does not specify a 2925 reporting policy. 2927 8.7.7.4. suit-directive-process-dependency 2929 Execute the commands in the common section of the current dependency, 2930 followed by the commands in the equivalent section of the current 2931 dependency. For example, if the current section is "fetch payload," 2932 this will execute "common" in the current dependency, then "fetch 2933 payload" in the current dependency. Once this is complete, the 2934 command following suit-directive-process-dependency will be 2935 processed. 2937 If the current dependency is False, this directive has no effect. If 2938 the current dependency is True, then this directive applies to all 2939 dependencies. If the current section is "common," then the command 2940 sequence MUST be terminated with an error. 2942 When SUIT_Process_Dependency completes, it forwards the last status 2943 code that occurred in the dependency. 2945 8.7.7.5. suit-directive-set-parameters 2947 suit-directive-set-parameters allows the manifest to configure 2948 behavior of future directives by changing parameters that are read by 2949 those directives. When dependencies are used, suit-directive-set- 2950 parameters also allows a manifest to modify the behavior of its 2951 dependencies. 2953 Available parameters are defined in Section 8.7.5. 2955 If a parameter is already set, suit-directive-set-parameters will 2956 skip setting the parameter to its argument. This provides the core 2957 of the override mechanism, allowing dependent manifests to change the 2958 behavior of a manifest. 2960 suit-directive-set-parameters does not specify a reporting policy. 2962 8.7.7.6. suit-directive-override-parameters 2964 suit-directive-override-parameters replaces any listed parameters 2965 that are already set with the values that are provided in its 2966 argument. This allows a manifest to prevent replacement of critical 2967 parameters. 2969 Available parameters are defined in Section 8.7.5. 2971 suit-directive-override-parameters does not specify a reporting 2972 policy. 2974 8.7.7.7. suit-directive-fetch 2976 suit-directive-fetch instructs the manifest processor to obtain one 2977 or more manifests or payloads, as specified by the manifest index and 2978 component index, respectively. 2980 suit-directive-fetch can target one or more manifests and one or more 2981 payloads. suit-directive-fetch retrieves each component and each 2982 manifest listed in component-index and dependency-index, 2983 respectively. If component-index or dependency-index is True, 2984 instead of an integer, then all current manifest components/manifests 2985 are fetched. The current manifest's dependent-components are not 2986 automatically fetched. In order to pre-fetch these, they MUST be 2987 specified in a component-index integer. 2989 suit-directive-fetch typically takes no arguments unless one is 2990 needed to modify fetch behavior. If an argument is needed, it must 2991 be wrapped in a bstr and set in suit-parameter-fetch-arguments. 2993 suit-directive-fetch reads the URI parameter to find the source of 2994 the fetch it performs. 2996 The behavior of suit-directive-fetch can be modified by setting one 2997 or more of SUIT_Parameter_Encryption_Info, 2998 SUIT_Parameter_Compression_Info, SUIT_Parameter_Unpack_Info. These 2999 three parameters each activate and configure a processing step that 3000 can be applied to the data that is transferred during suit-directive- 3001 fetch. 3003 8.7.7.8. suit-directive-fetch-uri-list 3005 suit-directive-fetch-uri-list uses the same semantics as suit- 3006 directive-fetch (Section 8.7.7.7), except that it iterates over the 3007 URI List (Section 8.7.5.20) to select a URI to fetch from. 3009 8.7.7.9. suit-directive-copy 3011 suit-directive-copy instructs the manifest processor to obtain one or 3012 more payloads, as specified by the component index. As described in 3013 Section 6.5 component index may be a single integer, a list of 3014 integers, or True. suit-directive-copy retrieves each component 3015 specified by the current component-index, respectively. The current 3016 manifest's dependent-components are not automatically copied. In 3017 order to copy these, they MUST be specified in a component-index 3018 integer. 3020 The behavior of suit-directive-copy can be modified by setting one or 3021 more of SUIT_Parameter_Encryption_Info, 3022 SUIT_Parameter_Compression_Info, SUIT_Parameter_Unpack_Info. These 3023 three parameters each activate and configure a processing step that 3024 can be applied to the data that is transferred during suit-directive- 3025 copy. 3027 suit-directive-copy reads its source from suit-parameter-source- 3028 component (Section 8.7.5.14). 3030 If either the source component parameter or the source component 3031 itself is absent, this command fails. 3033 8.7.7.10. suit-directive-run 3035 suit-directive-run directs the manifest processor to transfer 3036 execution to the current Component Index. When this is invoked, the 3037 manifest processor MAY be unloaded and execution continues in the 3038 Component Index. Arguments are provided to suit-directive-run 3039 through suit-parameter-run-arguments (Section 8.7.5.15) and are 3040 forwarded to the executable code located in Component Index in an 3041 application-specific way. For example, this could form the Linux 3042 Kernel Command Line if booting a Linux device. 3044 If the executable code at Component Index is constructed in such a 3045 way that it does not unload the manifest processor, then the manifest 3046 processor may resume execution after the executable completes. This 3047 allows the manifest processor to invoke suitable helpers and to 3048 verify them with image conditions. 3050 8.7.7.11. suit-directive-wait 3052 suit-directive-wait directs the manifest processor to pause until a 3053 specified event occurs. Some possible events include: 3055 1. Authorization 3057 2. External Power 3059 3. Network availability 3061 4. Other Device Firmware Version 3063 5. Time 3065 6. Time of Day 3067 7. Day of Week 3069 8.7.7.12. suit-directive-run-sequence 3071 To enable conditional commands, and to allow several strictly ordered 3072 sequences to be executed out-of-order, suit-directive-run-sequence 3073 allows the manifest processor to execute its argument as a 3074 SUIT_Command_Sequence. The argument must be wrapped in a bstr. 3076 When a sequence is executed, any failure of a condition causes 3077 immediate termination of the sequence. 3079 When suit-directive-run-sequence completes, it forwards the last 3080 status code that occurred in the sequence. If the Soft Failure 3081 parameter is true, then suit-directive-run-sequence only fails when a 3082 directive in the argument sequence fails. 3084 suit-parameter-soft-failure (Section 8.7.5.23) defaults to False when 3085 suit-directive-run-sequence begins. Its value is discarded when 3086 suit-directive-run-sequence terminates. 3088 8.7.7.13. suit-directive-swap 3090 suit-directive-swap instructs the manifest processor to move the 3091 source to the destination and the destination to the source 3092 simultaneously. Swap has nearly identical semantics to suit- 3093 directive-copy except that suit-directive-swap replaces the source 3094 with the current contents of the destination in an application- 3095 defined way. As with suit-directive-copy, if the source component is 3096 missing, this command fails. 3098 If SUIT_Parameter_Compression_Info or SUIT_Parameter_Encryption_Info 3099 are present, they MUST be handled in a symmetric way, so that the 3100 source is decompressed into the destination and the destination is 3101 compressed into the source. The source is decrypted into the 3102 destination and the destination is encrypted into the source. suit- 3103 directive-swap is OPTIONAL to implement. 3105 8.7.8. Integrity Check Values 3107 When the CoSWID, Text section, or any Command Sequence of the Update 3108 Procedure is made severable, it is moved to the Envelope and replaced 3109 with a SUIT_Digest. The SUIT_Digest is computed over the entire bstr 3110 enclosing the Manifest element that has been moved to the Envelope. 3111 Each element that is made severable from the Manifest is placed in 3112 the Envelope. The keys for the envelope elements have the same 3113 values as the keys for the manifest elements. 3115 Each Integrity Check Value covers the corresponding Envelope Element 3116 as described in Section 8.8. 3118 8.8. Severable Elements 3120 Because the manifest can be used by different actors at different 3121 times, some parts of the manifest can be removed or "Severed" without 3122 affecting later stages of the lifecycle. Severing of information is 3123 achieved by separating that information from the signed container so 3124 that removing it does not affect the signature. This means that 3125 ensuring integrity of severable parts of the manifest is a 3126 requirement for the signed portion of the manifest. Severing some 3127 parts makes it possible to discard parts of the manifest that are no 3128 longer necessary. This is important because it allows the storage 3129 used by the manifest to be greatly reduced. For example, no text 3130 size limits are needed if text is removed from the manifest prior to 3131 delivery to a constrained device. 3133 Elements are made severable by removing them from the manifest, 3134 encoding them in a bstr, and placing a SUIT_Digest of the bstr in the 3135 manifest so that they can still be authenticated. The SUIT_Digest 3136 typically consumes 4 bytes more than the size of the raw digest, 3137 therefore elements smaller than (Digest Bits)/8 + 4 SHOULD NOT be 3138 severable. Elements larger than (Digest Bits)/8 + 4 MAY be 3139 severable, while elements that are much larger than (Digest Bits)/8 + 3140 4 SHOULD be severable. 3142 Because of this, all command sequences in the manifest are encoded in 3143 a bstr so that there is a single code path needed for all command 3144 sequences. 3146 9. Access Control Lists 3148 To manage permissions in the manifest, there are three models that 3149 can be used. 3151 First, the simplest model requires that all manifests are 3152 authenticated by a single trusted key. This mode has the advantage 3153 that only a root manifest needs to be authenticated, since all of its 3154 dependencies have digests included in the root manifest. 3156 This simplest model can be extended by adding key delegation without 3157 much increase in complexity. 3159 A second model requires an ACL to be presented to the Recipient, 3160 authenticated by a trusted party or stored on the Recipient. This 3161 ACL grants access rights for specific component IDs or Component 3162 Identifier prefixes to the listed identities or identity groups. Any 3163 identity can verify an image digest, but fetching into or fetching 3164 from a Component Identifier requires approval from the ACL. 3166 A third model allows a Recipient to provide even more fine-grained 3167 controls: The ACL lists the Component Identifier or Component 3168 Identifier prefix that an identity can use, and also lists the 3169 commands and parameters that the identity can use in combination with 3170 that Component Identifier. 3172 10. SUIT Digest Container 3174 RFC 8152 [RFC8152] provides containers for signature, MAC, and 3175 encryption, but no basic digest container. The container needed for 3176 a digest requires a type identifier and a container for the raw 3177 digest data. Some forms of digest may require additional parameters. 3178 These can be added following the digest. 3180 The SUIT digest is a CBOR List containing two elements: a suit- 3181 digest-algorithm-id and a bstr containing the bytes of the digest. 3183 11. IANA Considerations 3185 IANA is requested to: 3187 - allocate CBOR tag 48 in the CBOR Tags registry for the SUIT 3188 Envelope. 3190 - allocate CBOR tag 480 in the CBOR Tags registry for the SUIT 3191 Manifest. 3193 - allocate media type application/suit-envelope in the Media Types 3194 registry. 3196 - setup several registries as described below. 3198 IANA is requested to setup a registry for SUIT manifests. Several 3199 registries defined in the subsections below need to be created. 3201 For each registry, values 0-23 are Standards Action, 24-255 are IETF 3202 Review, 256-65535 are Expert Review, and 65536 or greater are First 3203 Come First Served. 3205 Negative values -23 to 0 are Experimental Use, -24 and lower are 3206 Private Use. 3208 11.1. SUIT Commands 3210 +-------+------------+-----------------------------------+----------+ 3211 | Label | Name | Reference | | 3212 +-------+------------+-----------------------------------+----------+ 3213 | 1 | Vendor | Section 8.7.6.1 | | 3214 | | Identifier | | | 3215 | | | | | 3216 | 2 | Class | Section 8.7.6.1 | | 3217 | | Identifier | | | 3218 | | | | | 3219 | 3 | Image | Section 8.7.6.2 | | 3220 | | Match | | | 3221 | | | | | 3222 | 4 | Use Before | Section 8.7.6.4 | | 3223 | | | | | 3224 | 5 | Component | Section 8.7.6.5 | | 3225 | | Offset | | | 3226 | | | | | 3227 | 12 | Set | Section 8.7.7.1 | | 3228 | | Component | | | 3229 | | Index | | | 3230 | | | | | 3231 | 13 | Set | Section 8.7.7.2 | | 3232 | | Dependency | | | 3233 | | Index | | | 3234 | | | | | 3235 | 14 | Abort | | | 3236 | | | | | 3237 | 15 | Try Each | Section 8.7.7.3 | | 3238 | | | | | 3239 | 16 | Reserved | | | 3240 | | | | | 3241 | 17 | Reserved | | | 3242 | | | | | 3243 | 18 | Process | suit-directive-process-dependency | Section | 3244 | | Dependency | | 8.7.7.4 | 3245 | | | | | 3246 | 19 | Set | Section 8.7.7.5 | | 3247 | | Parameters | | | 3248 | | | | | 3249 | 20 | Override | Section 8.7.7.6 | | 3250 | | Parameters | | | 3251 | | | | | 3252 | 21 | Fetch | Section 8.7.7.7 | | 3253 | | | | | 3254 | 22 | Copy | Section 8.7.7.9 | | 3255 | | | | | 3256 | 23 | Run | Section 8.7.7.10 | | 3257 | | | | | 3258 | 24 | Device | Section 8.7.6.1 | | 3259 | | Identifier | | | 3260 | | | | | 3261 | 25 | Image Not | Section 8.7.6.3 | | 3262 | | Match | | | 3263 | | | | | 3264 | 26 | Minimum | Section 8.7.6.6 | | 3265 | | Battery | | | 3266 | | | | | 3267 | 27 | Update | Section 8.7.6.7 | | 3268 | | Authorized | | | 3269 | | | | | 3270 | 28 | Version | Section 8.7.6.8 | | 3271 | | | | | 3272 | 29 | Wait For | Section 8.7.7.11 | | 3273 | | Event | | | 3274 | | | | | 3275 | 30 | Fetch URI | Section 8.7.7.8 | | 3276 | | List | | | 3277 | | | | | 3278 | 31 | Swap | Section 8.7.7.13 | | 3279 | | | | | 3280 | 32 | Run | Section 8.7.7.12 | | 3281 | | Sequence | | | 3282 | | | | | 3283 | nint | Custom | Section 8.7.6.10 | | 3284 | | Condition | | | 3285 +-------+------------+-----------------------------------+----------+ 3287 11.2. SUIT Parameters 3288 +-------+------------------+---------------------------+ 3289 | Label | Name | Reference | 3290 +-------+------------------+---------------------------+ 3291 | 1 | Vendor ID | Section 8.7.5.3 | 3292 | | | | 3293 | 2 | Class ID | Section 8.7.5.4 | 3294 | | | | 3295 | 3 | Image Digest | Section 8.7.5.6 | 3296 | | | | 3297 | 4 | Use Before | Section 8.7.5.8 | 3298 | | | | 3299 | 5 | Component Offset | Section 8.7.5.9 | 3300 | | | | 3301 | 12 | Strict Order | Section 8.7.5.22 | 3302 | | | | 3303 | 13 | Soft Failure | Section 8.7.5.23 | 3304 | | | | 3305 | 14 | Image Size | Section 8.7.5.7 | 3306 | | | | 3307 | 18 | Encryption Info | Section 8.7.5.10 | 3308 | | | | 3309 | 19 | Compression Info | Section 8.7.5.11 | 3310 | | | | 3311 | 20 | Unpack Info | Section 8.7.5.12 | 3312 | | | | 3313 | 21 | URI | Section 8.7.5.13 | 3314 | | | | 3315 | 22 | Source Component | Section 8.7.5.14 | 3316 | | | | 3317 | 23 | Run Args | Section 8.7.5.15 | 3318 | | | | 3319 | 24 | Device ID | Section 8.7.5.5 | 3320 | | | | 3321 | 26 | Minimum Battery | Section 8.7.5.16 | 3322 | | | | 3323 | 27 | Update Priority | Section 8.7.5.17 | 3324 | | | | 3325 | 28 | Version | {{suit-parameter-version} | 3326 | | | | 3327 | 29 | Wait Info | Section 8.7.5.19 | 3328 | | | | 3329 | 30 | URI List | Section 8.7.5.20 | 3330 | | | | 3331 | nint | Custom | Section 8.7.5.24 | 3332 +-------+------------------+---------------------------+ 3334 11.3. SUIT Text Values 3336 +-------+----------------------+---------------+ 3337 | Label | Name | Reference | 3338 +-------+----------------------+---------------+ 3339 | 1 | Manifest Description | Section 8.6.4 | 3340 | | | | 3341 | 2 | Update Description | Section 8.6.4 | 3342 | | | | 3343 | 3 | Manifest JSON Source | Section 8.6.4 | 3344 | | | | 3345 | 4 | Manifest YAML Source | Section 8.6.4 | 3346 | | | | 3347 | nint | Custom | Section 8.6.4 | 3348 +-------+----------------------+---------------+ 3350 11.4. SUIT Component Text Values 3352 +-------+----------------------------+---------------+ 3353 | Label | Name | Reference | 3354 +-------+----------------------------+---------------+ 3355 | 1 | Vendor Name | Section 8.6.4 | 3356 | | | | 3357 | 2 | Model Name | Section 8.6.4 | 3358 | | | | 3359 | 3 | Vendor Domain | Section 8.6.4 | 3360 | | | | 3361 | 4 | Model Info | Section 8.6.4 | 3362 | | | | 3363 | 5 | Component Description | Section 8.6.4 | 3364 | | | | 3365 | 6 | Component Version | Section 8.6.4 | 3366 | | | | 3367 | 7 | Component Version Required | Section 8.6.4 | 3368 | | | | 3369 | nint | Custom | Section 8.6.4 | 3370 +-------+----------------------------+---------------+ 3372 11.5. SUIT Algorithm Identifiers 3374 11.5.1. SUIT Digest Algorithm Identifiers 3375 +-------+----------+------------+ 3376 | Label | Name | | 3377 +-------+----------+------------+ 3378 | 1 | SHA224 | Section 10 | 3379 | | | | 3380 | 2 | SHA256 | Section 10 | 3381 | | | | 3382 | 3 | SHA384 | Section 10 | 3383 | | | | 3384 | 4 | SHA512 | Section 10 | 3385 | | | | 3386 | 5 | SHA3-224 | Section 10 | 3387 | | | | 3388 | 6 | SHA3-256 | Section 10 | 3389 | | | | 3390 | 7 | SHA3-384 | Section 10 | 3391 | | | | 3392 | 8 | SHA3-512 | Section 10 | 3393 +-------+----------+------------+ 3395 11.5.2. SUIT Compression Algorithm Identifiers 3397 +-------+--------+------------------+ 3398 | Label | Name | Reference | 3399 +-------+--------+------------------+ 3400 | 1 | zlib | Section 8.7.5.11 | 3401 | | | | 3402 | 2 | Brotli | Section 8.7.5.11 | 3403 | | | | 3404 | 3 | zstd | Section 8.7.5.11 | 3405 +-------+--------+------------------+ 3407 11.5.3. Unpack Algorithms 3409 +-------+------+------------------+ 3410 | Label | Name | Reference | 3411 +-------+------+------------------+ 3412 | 1 | HEX | Section 8.7.5.12 | 3413 | | | | 3414 | 2 | ELF | Section 8.7.5.12 | 3415 | | | | 3416 | 3 | COFF | Section 8.7.5.12 | 3417 | | | | 3418 | 4 | SREC | Section 8.7.5.12 | 3419 +-------+------+------------------+ 3421 12. Security Considerations 3423 This document is about a manifest format protecting and describing 3424 how to retrieve, install, and invoke firmware images and as such it 3425 is part of a larger solution for delivering firmware updates to IoT 3426 devices. A detailed security treatment can be found in the 3427 architecture [I-D.ietf-suit-architecture] and in the information 3428 model [I-D.ietf-suit-information-model] documents. 3430 13. Acknowledgements 3432 We would like to thank the following persons for their support in 3433 designing this mechanism: 3435 - Milosch Meriac 3437 - Geraint Luff 3439 - Dan Ros 3441 - John-Paul Stanford 3443 - Hugo Vincent 3445 - Carsten Bormann 3447 - Oeyvind Roenningstad 3449 - Frank Audun Kvamtroe 3451 - Krzysztof Chruściński 3453 - Andrzej Puzdrowski 3455 - Michael Richardson 3457 - David Brown 3459 - Emmanuel Baccelli 3461 14. References 3463 14.1. Normative References 3465 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3466 Requirement Levels", BCP 14, RFC 2119, 3467 DOI 10.17487/RFC2119, March 1997, 3468 . 3470 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3471 Resource Identifier (URI): Generic Syntax", STD 66, 3472 RFC 3986, DOI 10.17487/RFC3986, January 2005, 3473 . 3475 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 3476 Unique IDentifier (UUID) URN Namespace", RFC 4122, 3477 DOI 10.17487/RFC4122, July 2005, 3478 . 3480 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 3481 RFC 8152, DOI 10.17487/RFC8152, July 2017, 3482 . 3484 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3485 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3486 May 2017, . 3488 14.2. Informative References 3490 [COFF] Wikipedia, ., "Common Object File Format (COFF)", 2020, 3491 . 3493 [ELF] Wikipedia, ., "Executable and Linkable Format (ELF)", 3494 2020, . 3497 [HEX] Wikipedia, ., "Intel HEX", 2020, 3498 . 3500 [I-D.ietf-cbor-tags-oid] 3501 Bormann, C. and S. Leonard, "Concise Binary Object 3502 Representation (CBOR) Tags for Object Identifiers", draft- 3503 ietf-cbor-tags-oid-02 (work in progress), October 2020. 3505 [I-D.ietf-sacm-coswid] 3506 Birkholz, H., Fitzgerald-McKay, J., Schmidt, C., and D. 3507 Waltermire, "Concise Software Identification Tags", draft- 3508 ietf-sacm-coswid-15 (work in progress), May 2020. 3510 [I-D.ietf-suit-architecture] 3511 Moran, B., Tschofenig, H., Brown, D., and M. Meriac, "A 3512 Firmware Update Architecture for Internet of Things", 3513 draft-ietf-suit-architecture-14 (work in progress), 3514 October 2020. 3516 [I-D.ietf-suit-information-model] 3517 Moran, B., Tschofenig, H., and H. Birkholz, "An 3518 Information Model for Firmware Updates in IoT Devices", 3519 draft-ietf-suit-information-model-08 (work in progress), 3520 October 2020. 3522 [I-D.ietf-teep-architecture] 3523 Pei, M., Tschofenig, H., Thaler, D., and D. Wheeler, 3524 "Trusted Execution Environment Provisioning (TEEP) 3525 Architecture", draft-ietf-teep-architecture-12 (work in 3526 progress), July 2020. 3528 [I-D.kucherawy-rfc8478bis] 3529 Collet, Y. and M. Kucherawy, "Zstandard Compression and 3530 the application/zstd Media Type", draft-kucherawy- 3531 rfc8478bis-05 (work in progress), April 2020. 3533 [RFC1950] Deutsch, P. and J-L. Gailly, "ZLIB Compressed Data Format 3534 Specification version 3.3", RFC 1950, 3535 DOI 10.17487/RFC1950, May 1996, 3536 . 3538 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 3539 Constrained-Node Networks", RFC 7228, 3540 DOI 10.17487/RFC7228, May 2014, 3541 . 3543 [RFC7932] Alakuijala, J. and Z. Szabadka, "Brotli Compressed Data 3544 Format", RFC 7932, DOI 10.17487/RFC7932, July 2016, 3545 . 3547 [RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, 3548 "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, 3549 May 2018, . 3551 [RFC8747] Jones, M., Seitz, L., Selander, G., Erdtman, S., and H. 3552 Tschofenig, "Proof-of-Possession Key Semantics for CBOR 3553 Web Tokens (CWTs)", RFC 8747, DOI 10.17487/RFC8747, March 3554 2020, . 3556 [SREC] Wikipedia, ., "SREC (file format)", 2020, 3557 . 3559 [YAML] "YAML Ain't Markup Language", 2020, . 3561 Appendix A. A. Full CDDL 3563 In order to create a valid SUIT Manifest document the structure of 3564 the corresponding CBOR message MUST adhere to the following CDDL data 3565 definition. 3567 SUIT_Envelope_Tagged = #6.48(SUIT_Envelope) 3568 SUIT_Envelope = { 3569 ? suit-delegation => bstr .cbor SUIT_Delegation, 3570 suit-authentication-wrapper => bstr .cbor SUIT_Authentication, 3571 suit-manifest => bstr .cbor SUIT_Manifest, 3572 SUIT_Severable_Manifest_Members, 3573 * SUIT_Integrated_Payload, 3574 * SUIT_Integrated_Dependency, 3575 * $$SUIT_Envelope_Extensions, 3576 * (int => bstr) 3577 } 3579 SUIT_Delegation = [ + [ + bstr .cbor CWT ] ] 3581 CWT = SUIT_Authentication_Block 3583 SUIT_Authentication = [ 3584 bstr .cbor SUIT_Digest, 3585 * bstr .cbor SUIT_Authentication_Block 3586 ] 3588 SUIT_Digest = [ 3589 suit-digest-algorithm-id : suit-digest-algorithm-ids, 3590 suit-digest-bytes : bstr, 3591 * $$SUIT_Digest-extensions 3592 ] 3594 ; Named Information Hash Algorithm Identifiers 3595 suit-digest-algorithm-ids /= algorithm-id-sha224 3596 suit-digest-algorithm-ids /= algorithm-id-sha256 3597 suit-digest-algorithm-ids /= algorithm-id-sha384 3598 suit-digest-algorithm-ids /= algorithm-id-sha512 3599 suit-digest-algorithm-ids /= algorithm-id-sha3-224 3600 suit-digest-algorithm-ids /= algorithm-id-sha3-256 3601 suit-digest-algorithm-ids /= algorithm-id-sha3-384 3602 suit-digest-algorithm-ids /= algorithm-id-sha3-512 3604 SUIT_Authentication_Block /= COSE_Mac_Tagged 3605 SUIT_Authentication_Block /= COSE_Sign_Tagged 3606 SUIT_Authentication_Block /= COSE_Mac0_Tagged 3607 SUIT_Authentication_Block /= COSE_Sign1_Tagged 3608 COSE_Mac_Tagged = any 3609 COSE_Sign_Tagged = any 3610 COSE_Mac0_Tagged = any 3611 COSE_Sign1_Tagged = any 3612 COSE_Encrypt_Tagged = any 3613 COSE_Encrypt0_Tagged = any 3615 SUIT_Severable_Manifest_Members = ( 3616 ? suit-dependency-resolution => bstr .cbor SUIT_Command_Sequence, 3617 ? suit-payload-fetch => bstr .cbor SUIT_Command_Sequence, 3618 ? suit-install => bstr .cbor SUIT_Command_Sequence, 3619 ? suit-text => bstr .cbor SUIT_Text_Map, 3620 ? suit-coswid => bstr .cbor concise-software-identity, 3621 * $$SUIT_severable-members-extensions, 3622 ) 3624 SUIT_Integrated_Payload = (suit-integrated-payload-key => bstr) 3625 SUIT_Integrated_Dependency = ( 3626 suit-integrated-payload-key => bstr .cbor SUIT_Envelope 3627 ) 3628 suit-integrated-payload-key = nint / uint .ge 24 3630 SUIT_Manifest_Tagged = #6.480(SUIT_Manifest) 3632 SUIT_Manifest = { 3633 suit-manifest-version => 1, 3634 suit-manifest-sequence-number => uint, 3635 suit-common => bstr .cbor SUIT_Common, 3636 ? suit-reference-uri => tstr, 3637 SUIT_Severable_Manifest_Members, 3638 SUIT_Severable_Members_Digests, 3639 SUIT_Unseverable_Members, 3640 * $$SUIT_Manifest_Extensions, 3641 } 3643 SUIT_Unseverable_Members = ( 3644 ? suit-validate => bstr .cbor SUIT_Command_Sequence, 3645 ? suit-load => bstr .cbor SUIT_Command_Sequence, 3646 ? suit-run => bstr .cbor SUIT_Command_Sequence, 3647 * $$unserverble-manifest-member-extensions, 3648 ) 3650 SUIT_Severable_Members_Digests = ( 3651 ? suit-dependency-resolution => SUIT_Digest, 3652 ? suit-payload-fetch => SUIT_Digest, 3653 ? suit-install => SUIT_Digest, 3654 ? suit-text => SUIT_Digest, 3655 ? suit-coswid => SUIT_Digest, 3656 * $$severable-manifest-members-digests-extensions 3657 ) 3659 SUIT_Common = { 3660 ? suit-dependencies => SUIT_Dependencies, 3661 ? suit-components => SUIT_Components, 3662 ? suit-common-sequence => bstr .cbor SUIT_Common_Sequence, 3663 * $$SUIT_Common-extensions, 3664 } 3666 SUIT_Dependencies = [ + SUIT_Dependency ] 3667 SUIT_Components = [ + SUIT_Component_Identifier ] 3669 concise-software-identity = any 3671 SUIT_Dependency = { 3672 suit-dependency-digest => SUIT_Digest, 3673 ? suit-dependency-prefix => SUIT_Component_Identifier, 3674 * $$SUIT_Dependency-extensions, 3675 } 3677 SUIT_Component_Identifier = [* bstr] 3679 SUIT_Common_Sequence = [ 3680 + ( SUIT_Condition // SUIT_Common_Commands ) 3681 ] 3683 SUIT_Common_Commands //= (suit-directive-set-component-index, IndexArg) 3684 SUIT_Common_Commands //= (suit-directive-set-dependency-index, IndexArg) 3685 SUIT_Common_Commands //= (suit-directive-run-sequence, 3686 bstr .cbor SUIT_Command_Sequence) 3687 SUIT_Common_Commands //= (suit-directive-try-each, 3688 SUIT_Directive_Try_Each_Argument) 3689 SUIT_Common_Commands //= (suit-directive-set-parameters, 3690 {+ SUIT_Parameters}) 3691 SUIT_Common_Commands //= (suit-directive-override-parameters, 3692 {+ SUIT_Parameters}) 3694 IndexArg /= uint 3695 IndexArg /= bool 3696 IndexArg /= [+uint] 3698 SUIT_Command_Sequence = [ + ( 3699 SUIT_Condition // SUIT_Directive // SUIT_Command_Custom 3700 ) ] 3702 SUIT_Command_Custom = (suit-command-custom, bstr/tstr/int/nil) 3703 SUIT_Condition //= (suit-condition-vendor-identifier, SUIT_Rep_Policy) 3704 SUIT_Condition //= (suit-condition-class-identifier, SUIT_Rep_Policy) 3705 SUIT_Condition //= (suit-condition-device-identifier, SUIT_Rep_Policy) 3706 SUIT_Condition //= (suit-condition-image-match, SUIT_Rep_Policy) 3707 SUIT_Condition //= (suit-condition-image-not-match, SUIT_Rep_Policy) 3708 SUIT_Condition //= (suit-condition-use-before, SUIT_Rep_Policy) 3709 SUIT_Condition //= (suit-condition-minimum-battery, SUIT_Rep_Policy) 3710 SUIT_Condition //= (suit-condition-update-authorized, SUIT_Rep_Policy) 3711 SUIT_Condition //= (suit-condition-version, SUIT_Rep_Policy) 3712 SUIT_Condition //= (suit-condition-component-offset, SUIT_Rep_Policy) 3713 SUIT_Condition //= (suit-condition-abort, SUIT_Rep_Policy) 3715 SUIT_Directive //= (suit-directive-set-component-index, IndexArg) 3716 SUIT_Directive //= (suit-directive-set-dependency-index, IndexArg) 3717 SUIT_Directive //= (suit-directive-run-sequence, 3718 bstr .cbor SUIT_Command_Sequence) 3719 SUIT_Directive //= (suit-directive-try-each, 3720 SUIT_Directive_Try_Each_Argument) 3721 SUIT_Directive //= (suit-directive-process-dependency, SUIT_Rep_Policy) 3722 SUIT_Directive //= (suit-directive-set-parameters, 3723 {+ SUIT_Parameters}) 3724 SUIT_Directive //= (suit-directive-override-parameters, 3725 {+ SUIT_Parameters}) 3726 SUIT_Directive //= (suit-directive-fetch, SUIT_Rep_Policy) 3727 SUIT_Directive //= (suit-directive-copy, SUIT_Rep_Policy) 3728 SUIT_Directive //= (suit-directive-swap, SUIT_Rep_Policy) 3729 SUIT_Directive //= (suit-directive-run, SUIT_Rep_Policy) 3730 SUIT_Directive //= (suit-directive-wait, SUIT_Rep_Policy) 3731 SUIT_Directive //= (suit-directive-fetch-uri-list, SUIT_Rep_Policy) 3733 SUIT_Directive_Try_Each_Argument = [ 3734 + bstr .cbor SUIT_Command_Sequence, 3735 nil / bstr .cbor SUIT_Command_Sequence 3736 ] 3738 SUIT_Rep_Policy = uint .bits suit-reporting-bits 3740 suit-reporting-bits = &( 3741 suit-send-record-success : 0, 3742 suit-send-record-failure : 1, 3743 suit-send-sysinfo-success : 2, 3744 suit-send-sysinfo-failure : 3 3745 ) 3747 SUIT_Wait_Event = { + SUIT_Wait_Events } 3749 SUIT_Wait_Events //= (suit-wait-event-authorization => int) 3750 SUIT_Wait_Events //= (suit-wait-event-power => int) 3751 SUIT_Wait_Events //= (suit-wait-event-network => int) 3752 SUIT_Wait_Events //= (suit-wait-event-other-device-version 3753 => SUIT_Wait_Event_Argument_Other_Device_Version) 3754 SUIT_Wait_Events //= (suit-wait-event-time => uint); Timestamp 3755 SUIT_Wait_Events //= (suit-wait-event-time-of-day 3756 => uint); Time of Day (seconds since 00:00:00) 3757 SUIT_Wait_Events //= (suit-wait-event-day-of-week 3758 => uint); Days since Sunday 3760 SUIT_Wait_Event_Argument_Other_Device_Version = [ 3761 other-device: bstr, 3762 other-device-version: [ + SUIT_Parameter_Version_Match ] 3763 ] 3765 SUIT_Parameters //= (suit-parameter-vendor-identifier => 3766 (RFC4122_UUID / cbor-pen)) 3767 cbor-pen = #6.112(bstr) 3769 SUIT_Parameters //= (suit-parameter-class-identifier => RFC4122_UUID) 3770 SUIT_Parameters //= (suit-parameter-image-digest 3771 => bstr .cbor SUIT_Digest) 3772 SUIT_Parameters //= (suit-parameter-image-size => uint) 3773 SUIT_Parameters //= (suit-parameter-use-before => uint) 3774 SUIT_Parameters //= (suit-parameter-component-offset => uint) 3776 SUIT_Parameters //= (suit-parameter-encryption-info 3777 => bstr .cbor SUIT_Encryption_Info) 3778 SUIT_Parameters //= (suit-parameter-compression-info 3779 => bstr .cbor SUIT_Compression_Info) 3780 SUIT_Parameters //= (suit-parameter-unpack-info 3781 => bstr .cbor SUIT_Unpack_Info) 3783 SUIT_Parameters //= (suit-parameter-uri => tstr) 3784 SUIT_Parameters //= (suit-parameter-source-component => uint) 3785 SUIT_Parameters //= (suit-parameter-run-args => bstr) 3787 SUIT_Parameters //= (suit-parameter-device-identifier => RFC4122_UUID) 3788 SUIT_Parameters //= (suit-parameter-minimum-battery => uint) 3789 SUIT_Parameters //= (suit-parameter-update-priority => uint) 3790 SUIT_Parameters //= (suit-parameter-version => 3791 SUIT_Parameter_Version_Match) 3792 SUIT_Parameters //= (suit-parameter-wait-info => 3793 bstr .cbor SUIT_Wait_Event) 3795 SUIT_Parameters //= (suit-parameter-custom => int/bool/tstr/bstr) 3797 SUIT_Parameters //= (suit-parameter-strict-order => bool) 3798 SUIT_Parameters //= (suit-parameter-soft-failure => bool) 3799 SUIT_Parameters //= (suit-parameter-uri-list => 3800 bstr .cbor SUIT_URI_List) 3802 RFC4122_UUID = bstr .size 16 3804 SUIT_Parameter_Version_Match = [ 3805 suit-condition-version-comparison-type: 3806 SUIT_Condition_Version_Comparison_Types, 3807 suit-condition-version-comparison-value: 3808 SUIT_Condition_Version_Comparison_Value 3809 ] 3810 SUIT_Condition_Version_Comparison_Types /= 3811 suit-condition-version-comparison-greater 3812 SUIT_Condition_Version_Comparison_Types /= 3813 suit-condition-version-comparison-greater-equal 3814 SUIT_Condition_Version_Comparison_Types /= 3815 suit-condition-version-comparison-equal 3816 SUIT_Condition_Version_Comparison_Types /= 3817 suit-condition-version-comparison-lesser-equal 3818 SUIT_Condition_Version_Comparison_Types /= 3819 suit-condition-version-comparison-lesser 3821 suit-condition-version-comparison-greater = 1 3822 suit-condition-version-comparison-greater-equal = 2 3823 suit-condition-version-comparison-equal = 3 3824 suit-condition-version-comparison-lesser-equal = 4 3825 suit-condition-version-comparison-lesser = 5 3827 SUIT_Condition_Version_Comparison_Value = [+int] 3829 SUIT_Encryption_Info = COSE_Encrypt_Tagged/COSE_Encrypt0_Tagged 3830 SUIT_Compression_Info = { 3831 suit-compression-algorithm => SUIT_Compression_Algorithms, 3832 * $$SUIT_Compression_Info-extensions, 3833 } 3835 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_zlib 3836 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_brotli 3837 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_zstd 3839 SUIT_Compression_Algorithm_zlib = 1 3840 SUIT_Compression_Algorithm_brotli = 2 3841 SUIT_Compression_Algorithm_zstd = 3 3843 SUIT_Unpack_Info = { 3844 suit-unpack-algorithm => SUIT_Unpack_Algorithms, 3845 * $$SUIT_Unpack_Info-extensions, 3847 } 3849 SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Hex 3850 SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Elf 3851 SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Coff 3852 SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Srec 3854 SUIT_Unpack_Algorithm_Hex = 1 3855 SUIT_Unpack_Algorithm_Elf = 2 3856 SUIT_Unpack_Algorithm_Coff = 3 3857 SUIT_Unpack_Algorithm_Srec = 4 3859 SUIT_URI_List = [+ tstr ] 3861 SUIT_Text_Map = { 3862 * SUIT_Component_Identifier => { 3863 SUIT_Text_Component_Keys 3864 }, 3865 SUIT_Text_Keys 3866 } 3868 SUIT_Text_Component_Keys = ( 3869 ? suit-text-vendor-name => tstr, 3870 ? suit-text-model-name => tstr, 3871 ? suit-text-vendor-domain => tstr, 3872 ? suit-text-model-info => tstr, 3873 ? suit-text-component-description => tstr, 3874 ? suit-text-component-version => tstr, 3875 ? suit-text-version-required => tstr, 3876 * $$suit-text-component-key-extensions 3877 ) 3879 SUIT_Text_Keys = ( 3880 ? suit-text-manifest-description => tstr, 3881 ? suit-text-update-description => tstr, 3882 ? suit-text-manifest-json-source => tstr, 3883 ? suit-text-manifest-yaml-source => tstr, 3884 * $$suit-text-key-extensions 3885 ) 3887 suit-delegation = 1 3888 suit-authentication-wrapper = 2 3889 suit-manifest = 3 3891 algorithm-id-sha224 = 1 3892 algorithm-id-sha256 = 2 3893 algorithm-id-sha384 = 3 3894 algorithm-id-sha512 = 4 3895 algorithm-id-sha3-224 = 5 3896 algorithm-id-sha3-256 = 6 3897 algorithm-id-sha3-384 = 7 3898 algorithm-id-sha3-512 = 8 3900 suit-manifest-version = 1 3901 suit-manifest-sequence-number = 2 3902 suit-common = 3 3903 suit-reference-uri = 4 3904 suit-dependency-resolution = 7 3905 suit-payload-fetch = 8 3906 suit-install = 9 3907 suit-validate = 10 3908 suit-load = 11 3909 suit-run = 12 3910 suit-text = 13 3911 suit-coswid = 14 3913 suit-dependencies = 1 3914 suit-components = 2 3915 suit-common-sequence = 4 3917 suit-dependency-digest = 1 3918 suit-dependency-prefix = 2 3920 suit-command-custom = nint 3922 suit-condition-vendor-identifier = 1 3923 suit-condition-class-identifier = 2 3924 suit-condition-image-match = 3 3925 suit-condition-use-before = 4 3926 suit-condition-component-offset = 5 3928 suit-condition-abort = 14 3929 suit-condition-device-identifier = 24 3930 suit-condition-image-not-match = 25 3931 suit-condition-minimum-battery = 26 3932 suit-condition-update-authorized = 27 3933 suit-condition-version = 28 3935 suit-directive-set-component-index = 12 3936 suit-directive-set-dependency-index = 13 3937 suit-directive-try-each = 15 3938 ;suit-directive-do-each = 16 ; TBD 3939 ;suit-directive-map-filter = 17 ; TBD 3940 suit-directive-process-dependency = 18 3941 suit-directive-set-parameters = 19 3942 suit-directive-override-parameters = 20 3943 suit-directive-fetch = 21 3944 suit-directive-copy = 22 3945 suit-directive-run = 23 3947 suit-directive-wait = 29 3948 suit-directive-fetch-uri-list = 30 3949 suit-directive-swap = 31 3950 suit-directive-run-sequence = 32 3952 suit-wait-event-authorization = 1 3953 suit-wait-event-power = 2 3954 suit-wait-event-network = 3 3955 suit-wait-event-other-device-version = 4 3956 suit-wait-event-time = 5 3957 suit-wait-event-time-of-day = 6 3958 suit-wait-event-day-of-week = 7 3960 suit-parameter-vendor-identifier = 1 3961 suit-parameter-class-identifier = 2 3962 suit-parameter-image-digest = 3 3963 suit-parameter-use-before = 4 3964 suit-parameter-component-offset = 5 3966 suit-parameter-strict-order = 12 3967 suit-parameter-soft-failure = 13 3968 suit-parameter-image-size = 14 3970 suit-parameter-encryption-info = 18 3971 suit-parameter-compression-info = 19 3972 suit-parameter-unpack-info = 20 3973 suit-parameter-uri = 21 3974 suit-parameter-source-component = 22 3975 suit-parameter-run-args = 23 3977 suit-parameter-device-identifier = 24 3978 suit-parameter-minimum-battery = 26 3979 suit-parameter-update-priority = 27 3980 suit-parameter-version = 28 3981 suit-parameter-wait-info = 29 3982 suit-parameter-uri-list = 30 3984 suit-parameter-custom = nint 3986 suit-compression-algorithm = 1 3988 suit-unpack-algorithm = 1 3990 suit-text-manifest-description = 1 3991 suit-text-update-description = 2 3992 suit-text-manifest-json-source = 3 3993 suit-text-manifest-yaml-source = 4 3995 suit-text-vendor-name = 1 3996 suit-text-model-name = 2 3997 suit-text-vendor-domain = 3 3998 suit-text-model-info = 4 3999 suit-text-component-description = 5 4000 suit-text-component-version = 6 4001 suit-text-version-required = 7 4003 Appendix B. B. Examples 4005 The following examples demonstrate a small subset of the 4006 functionality of the manifest. Even a simple manifest processor can 4007 execute most of these manifests. 4009 The examples are signed using the following ECDSA secp256r1 key: 4011 -----BEGIN PRIVATE KEY----- 4012 MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgApZYjZCUGLM50VBC 4013 CjYStX+09jGmnyJPrpDLTz/hiXOhRANCAASEloEarguqq9JhVxie7NomvqqL8Rtv 4014 P+bitWWchdvArTsfKktsCYExwKNtrNHXi9OB3N+wnAUtszmR23M4tKiW 4015 -----END PRIVATE KEY----- 4017 The corresponding public key can be used to verify these examples: 4019 -----BEGIN PUBLIC KEY----- 4020 MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEhJaBGq4LqqvSYVcYnuzaJr6qi/Eb 4021 bz/m4rVlnIXbwK07HypLbAmBMcCjbazR14vTgdzfsJwFLbM5kdtzOLSolg== 4022 -----END PUBLIC KEY----- 4024 Each example uses SHA256 as the digest function. 4026 Note that reporting policies are declared for each non-flow-control 4027 command in these examples. The reporting policies used in the 4028 examples are described in the following tables. 4030 +-----------------------------+----------+ 4031 | Policy | Label | 4032 +-----------------------------+----------+ 4033 | suit-send-record-on-success | Rec-Pass | 4034 | | | 4035 | suit-send-record-on-failure | Rec-Fail | 4036 | | | 4037 | suit-send-sysinfo-success | Sys-Pass | 4038 | | | 4039 | suit-send-sysinfo-failure | Sys-Fail | 4040 +-----------------------------+----------+ 4042 +----------------------------+--------+---------+---------+---------+ 4043 | Command | Sys- | Sys- | Rec- | Rec- | 4044 | | Fail | Pass | Fail | Pass | 4045 +----------------------------+--------+---------+---------+---------+ 4046 | suit-condition-vendor- | 1 | 1 | 1 | 1 | 4047 | identifier | | | | | 4048 | | | | | | 4049 | suit-condition-class- | 1 | 1 | 1 | 1 | 4050 | identifier | | | | | 4051 | | | | | | 4052 | suit-condition-image-match | 1 | 1 | 1 | 1 | 4053 | | | | | | 4054 | suit-condition-component- | 0 | 1 | 0 | 1 | 4055 | offset | | | | | 4056 | | | | | | 4057 | suit-directive-fetch | 0 | 0 | 1 | 0 | 4058 | | | | | | 4059 | suit-directive-copy | 0 | 0 | 1 | 0 | 4060 | | | | | | 4061 | suit-directive-run | 0 | 0 | 1 | 0 | 4062 +----------------------------+--------+---------+---------+---------+ 4064 B.1. Example 0: Secure Boot 4066 This example covers the following templates: 4068 - Compatibility Check (Section 7.1) 4070 - Secure Boot (Section 7.2) 4072 It also serves as the minimum example. 4074 { 4075 / authentication-wrapper / 2:bstr .cbor ({ digest: bstr 4076 .cbor ([ 4077 / algorithm-id / 2 / "sha256" /, 4078 / digest-bytes / 4079 h'5c097ef64bf3bb9b494e71e1f2418eef8d466cc902f639a855ec9af3e9eddb99' 4080 ]) signatures: [ 4081 bstr .cbor (18([ 4082 / protected / bstr .cbor ({ 4083 / alg / 1:-7 / "ES256" /, 4084 }), 4085 / unprotected / { 4086 }, 4087 / payload / bstr .cbor ([ 4088 / algorithm-id / 2 / "sha256" /, 4089 / digest-bytes / 4090 h'5c097ef64bf3bb9b494e71e1f2418eef8d466cc902f639a855ec9af3e9eddb99' 4091 ]), 4092 / signature / h'60f5c3d03a3aa759bfef2ef0f5f97a93b1 4093 f5e741f7463f4385af88513a5c2957bea2d6c4cfddd03392a267aab0fc0fd515560ed5 4094 8e33fad26ac32a024c5a7143' 4095 ])) 4096 ] 4097 }), 4098 / manifest / 3:bstr .cbor ({ 4099 / manifest-version / 1:1, 4100 / manifest-sequence-number / 2:0, 4101 / common / 3:bstr .cbor ({ 4102 / components / 2:[ 4103 [h'00'] 4104 ], 4105 / common-sequence / 4:bstr .cbor ([ 4106 / directive-override-parameters / 20,{ 4107 / vendor-id / 4108 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 4109 be9d-e663e4d41ffe /, 4110 / class-id / 2:h'1492af1425695e48bf429b2d51f2ab45' 4111 / 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 4112 / image-digest / 3:bstr .cbor ([ 4113 / algorithm-id / 2 / "sha256" /, 4114 / digest-bytes / 4115 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 4116 ]), 4117 / image-size / 14:34768, 4118 } , 4119 / condition-vendor-identifier / 1,15 , 4120 / condition-class-identifier / 2,15 4121 ]), 4122 }), 4123 / validate / 10:bstr .cbor ([ 4124 / condition-image-match / 3,15 4125 ]), 4126 / run / 12:bstr .cbor ([ 4127 / directive-run / 23,2 4128 ]), 4129 }), 4130 } 4132 Total size of Envelope without COSE authentication object: 159 4134 Envelope: 4136 a2025827815824820258205c097ef64bf3bb9b494e71e1f2418eef8d466c 4137 c902f639a855ec9af3e9eddb99035871a50101020003585fa20281814100 4138 0458568614a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af14 4139 25695e48bf429b2d51f2ab450358248202582000112233445566778899aa 4140 bbccddeeff0123456789abcdeffedcba98765432100e1987d0010f020f0a 4141 4382030f0c43821702 4143 Total size of Envelope with COSE authentication object: 272 4145 Envelope with COSE authentication object: 4147 a2025898825824820258205c097ef64bf3bb9b494e71e1f2418eef8d466c 4148 c902f639a855ec9af3e9eddb99586fd28443a10126a05824820258205c09 4149 7ef64bf3bb9b494e71e1f2418eef8d466cc902f639a855ec9af3e9eddb99 4150 584060f5c3d03a3aa759bfef2ef0f5f97a93b1f5e741f7463f4385af8851 4151 3a5c2957bea2d6c4cfddd03392a267aab0fc0fd515560ed58e33fad26ac3 4152 2a024c5a7143035871a50101020003585fa202818141000458568614a401 4153 50fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b 4154 2d51f2ab450358248202582000112233445566778899aabbccddeeff0123 4155 456789abcdeffedcba98765432100e1987d0010f020f0a4382030f0c4382 4156 1702 4158 B.2. Example 1: Simultaneous Download and Installation of Payload 4160 This example covers the following templates: 4162 - Compatibility Check (Section 7.1) 4164 - Firmware Download (Section 7.3) 4166 Simultaneous download and installation of payload. No secure boot is 4167 present in this example to demonstrate a download-only manifest. 4169 { 4170 / authentication-wrapper / 2:bstr .cbor ({ digest: bstr 4171 .cbor ([ 4172 / algorithm-id / 2 / "sha256" /, 4173 / digest-bytes / 4175 h'987eec85fa99fd31d332381b9810f90b05c2e0d4f284a6f4211207ed00fff750' 4176 ]) signatures: [ 4177 bstr .cbor (18([ 4178 / protected / bstr .cbor ({ 4179 / alg / 1:-7 / "ES256" /, 4180 }), 4181 / unprotected / { 4182 }, 4183 / payload / bstr .cbor ([ 4184 / algorithm-id / 2 / "sha256" /, 4185 / digest-bytes / 4186 h'987eec85fa99fd31d332381b9810f90b05c2e0d4f284a6f4211207ed00fff750' 4187 ]), 4188 / signature / h'750141d65b4f20a88dc70c6785a67e0f4f 4189 085aead83ba2289d6e37271508cc91e0a0592f5c940c2257c9c0b26403c0ba4477f2ce 4190 37b60089fe02cde7911d1c15' 4191 ])) 4192 ] 4193 }), 4194 / manifest / 3:bstr .cbor ({ 4195 / manifest-version / 1:1, 4196 / manifest-sequence-number / 2:1, 4197 / common / 3:bstr .cbor ({ 4198 / components / 2:[ 4199 [h'00'] 4200 ], 4201 / common-sequence / 4:bstr .cbor ([ 4202 / directive-override-parameters / 20,{ 4203 / vendor-id / 4204 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 4205 be9d-e663e4d41ffe /, 4206 / class-id / 2:h'1492af1425695e48bf429b2d51f2ab45' 4207 / 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 4208 / image-digest / 3:bstr .cbor ([ 4209 / algorithm-id / 2 / "sha256" /, 4210 / digest-bytes / 4211 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 4212 ]), 4213 / image-size / 14:34768, 4214 } , 4215 / condition-vendor-identifier / 1,15 , 4216 / condition-class-identifier / 2,15 4217 ]), 4218 }), 4219 / install / 9:bstr .cbor ([ 4220 / directive-set-parameters / 19,{ 4221 / uri / 21:'http://example.com/file.bin', 4222 } , 4223 / directive-fetch / 21,2 , 4224 / condition-image-match / 3,15 4225 ]), 4226 / validate / 10:bstr .cbor ([ 4227 / condition-image-match / 3,15 4228 ]), 4229 }), 4230 } 4232 Total size of Envelope without COSE authentication object: 194 4234 Envelope: 4236 a202582781582482025820987eec85fa99fd31d332381b9810f90b05c2e0 4237 d4f284a6f4211207ed00fff750035894a50101020103585fa20281814100 4238 0458568614a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af14 4239 25695e48bf429b2d51f2ab450358248202582000112233445566778899aa 4240 bbccddeeff0123456789abcdeffedcba98765432100e1987d0010f020f09 4241 58258613a115781b687474703a2f2f6578616d706c652e636f6d2f66696c 4242 652e62696e1502030f0a4382030f 4244 Total size of Envelope with COSE authentication object: 307 4246 Envelope with COSE authentication object: 4248 a202589882582482025820987eec85fa99fd31d332381b9810f90b05c2e0 4249 d4f284a6f4211207ed00fff750586fd28443a10126a0582482025820987e 4250 ec85fa99fd31d332381b9810f90b05c2e0d4f284a6f4211207ed00fff750 4251 5840750141d65b4f20a88dc70c6785a67e0f4f085aead83ba2289d6e3727 4252 1508cc91e0a0592f5c940c2257c9c0b26403c0ba4477f2ce37b60089fe02 4253 cde7911d1c15035894a50101020103585fa202818141000458568614a401 4254 50fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b 4255 2d51f2ab450358248202582000112233445566778899aabbccddeeff0123 4256 456789abcdeffedcba98765432100e1987d0010f020f0958258613a11578 4257 1b687474703a2f2f6578616d706c652e636f6d2f66696c652e62696e1502 4258 030f0a4382030f 4260 B.3. Example 2: Simultaneous Download, Installation, Secure Boot, 4261 Severed Fields 4263 This example covers the following templates: 4265 - Compatibility Check (Section 7.1) 4267 - Secure Boot (Section 7.2) 4269 - Firmware Download (Section 7.3) 4270 This example also demonstrates severable elements (Section 5.5), and 4271 text (Section 8.6.4). 4273 { 4274 / authentication-wrapper / 2:bstr .cbor ({ digest: bstr 4275 .cbor ([ 4276 / algorithm-id / 2 / "sha256" /, 4277 / digest-bytes / 4278 h'75685579a83babd71ec8ef22fa49ac873f78a708a43a674e782ad30b6598d17a' 4279 ]) signatures: [ 4280 bstr .cbor (18([ 4281 / protected / bstr .cbor ({ 4282 / alg / 1:-7 / "ES256" /, 4283 }), 4284 / unprotected / { 4285 }, 4286 / payload / bstr .cbor ([ 4287 / algorithm-id / 2 / "sha256" /, 4288 / digest-bytes / 4289 h'75685579a83babd71ec8ef22fa49ac873f78a708a43a674e782ad30b6598d17a' 4290 ]), 4291 / signature / h'861b9bfb449125742baa648bc9d148cba4 4292 5519cca8efecf705c2165ecdecaeba8b6ce2131284e66708788d741e8779d5973fa8e2 4293 5da49eb203c81920719da949' 4294 ])) 4295 ] 4296 }), 4297 / manifest / 3:bstr .cbor ({ 4298 / manifest-version / 1:1, 4299 / manifest-sequence-number / 2:2, 4300 / common / 3:bstr .cbor ({ 4301 / components / 2:[ 4302 [h'00'] 4303 ], 4304 / common-sequence / 4:bstr .cbor ([ 4305 / directive-override-parameters / 20,{ 4306 / vendor-id / 4307 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 4308 be9d-e663e4d41ffe /, 4309 / class-id / 2:h'1492af1425695e48bf429b2d51f2ab45' 4310 / 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 4311 / image-digest / 3:bstr .cbor ([ 4312 / algorithm-id / 2 / "sha256" /, 4313 / digest-bytes / 4314 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 4315 ]), 4316 / image-size / 14:34768, 4317 } , 4318 / condition-vendor-identifier / 1,15 , 4319 / condition-class-identifier / 2,15 4320 ]), 4321 }), 4322 / install / 9:[ 4323 / algorithm-id / 2 / "sha256" /, 4324 / digest-bytes / 4325 h'3ee96dc79641970ae46b929ccf0b72ba9536dd846020dbdc9f949d84ea0e18d2' 4326 ], 4327 / validate / 10:bstr .cbor ([ 4328 / condition-image-match / 3,15 4329 ]), 4330 / run / 12:bstr .cbor ([ 4331 / directive-run / 23,2 4332 ]), 4333 / text / 13:[ 4334 / algorithm-id / 2 / "sha256" /, 4335 / digest-bytes / 4336 h'23f48b2e2838650f43c144234aee18401ffe3cce4733b23881c3a8ae2d2b66e8' 4337 ], 4338 }), 4339 / install / 9:bstr .cbor ([ 4340 / directive-set-parameters / 19,{ 4341 / uri / 4342 21:'http://example.com/very/long/path/to/file/file.bin', 4343 } , 4344 / directive-fetch / 21,2 , 4345 / condition-image-match / 3,15 4346 ]), 4347 / text / 13:bstr .cbor ({ 4348 [h'00']:{ 4349 / vendor-domain / 3:'arm.com', 4350 / component-description / 5:'This component is a 4351 demonstration. The digest is a sample pattern, not a real one.', 4352 } 4353 }), 4354 } 4356 Total size of the Envelope without COSE authentication object or 4357 Severable Elements: 233 4359 Envelope: 4361 a20258278158248202582075685579a83babd71ec8ef22fa49ac873f78a7 4362 08a43a674e782ad30b6598d17a0358bba70101020203585fa20281814100 4363 0458568614a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af14 4364 25695e48bf429b2d51f2ab450358248202582000112233445566778899aa 4365 bbccddeeff0123456789abcdeffedcba98765432100e1987d0010f020f09 4366 820258203ee96dc79641970ae46b929ccf0b72ba9536dd846020dbdc9f94 4367 9d84ea0e18d20a4382030f0c438217020d8202582023f48b2e2838650f43 4368 c144234aee18401ffe3cce4733b23881c3a8ae2d2b66e8 4370 Total size of the Envelope with COSE authentication object but 4371 without Severable Elements: 346 4373 Envelope: 4375 a20258988258248202582075685579a83babd71ec8ef22fa49ac873f78a7 4376 08a43a674e782ad30b6598d17a586fd28443a10126a05824820258207568 4377 5579a83babd71ec8ef22fa49ac873f78a708a43a674e782ad30b6598d17a 4378 5840861b9bfb449125742baa648bc9d148cba45519cca8efecf705c2165e 4379 cdecaeba8b6ce2131284e66708788d741e8779d5973fa8e25da49eb203c8 4380 1920719da9490358bba70101020203585fa202818141000458568614a401 4381 50fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b 4382 2d51f2ab450358248202582000112233445566778899aabbccddeeff0123 4383 456789abcdeffedcba98765432100e1987d0010f020f09820258203ee96d 4384 c79641970ae46b929ccf0b72ba9536dd846020dbdc9f949d84ea0e18d20a 4385 4382030f0c438217020d8202582023f48b2e2838650f43c144234aee1840 4386 1ffe3cce4733b23881c3a8ae2d2b66e8 4388 Total size of Envelope with COSE authentication object: 929 4390 Envelope with COSE authentication object: 4392 a40258988258248202582075685579a83babd71ec8ef22fa49ac873f78a7 4393 08a43a674e782ad30b6598d17a586fd28443a10126a05824820258207568 4394 5579a83babd71ec8ef22fa49ac873f78a708a43a674e782ad30b6598d17a 4395 5840861b9bfb449125742baa648bc9d148cba45519cca8efecf705c2165e 4396 cdecaeba8b6ce2131284e66708788d741e8779d5973fa8e25da49eb203c8 4397 1920719da9490358bba70101020203585fa202818141000458568614a401 4398 50fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b 4399 2d51f2ab450358248202582000112233445566778899aabbccddeeff0123 4400 456789abcdeffedcba98765432100e1987d0010f020f09820258203ee96d 4401 c79641970ae46b929ccf0b72ba9536dd846020dbdc9f949d84ea0e18d20a 4402 4382030f0c438217020d8202582023f48b2e2838650f43c144234aee1840 4403 1ffe3cce4733b23881c3a8ae2d2b66e809583c8613a1157832687474703a 4404 2f2f6578616d706c652e636f6d2f766572792f6c6f6e672f706174682f74 4405 6f2f66696c652f66696c652e62696e1502030f0d590204a20179019d2323 4406 204578616d706c6520323a2053696d756c74616e656f757320446f776e6c 4407 6f61642c20496e7374616c6c6174696f6e2c2053656375726520426f6f74 4408 2c2053657665726564204669656c64730a0a202020205468697320657861 4409 6d706c6520636f766572732074686520666f6c6c6f77696e672074656d70 4410 6c617465733a0a202020200a202020202a20436f6d7061746962696c6974 4411 7920436865636b20287b7b74656d706c6174652d636f6d7061746962696c 4412 6974792d636865636b7d7d290a202020202a2053656375726520426f6f74 4413 20287b7b74656d706c6174652d7365637572652d626f6f747d7d290a2020 4414 20202a204669726d7761726520446f776e6c6f616420287b7b6669726d77 4415 6172652d646f776e6c6f61642d74656d706c6174657d7d290a202020200a 4416 2020202054686973206578616d706c6520616c736f2064656d6f6e737472 4417 6174657320736576657261626c6520656c656d656e747320287b7b6f7672 4418 2d736576657261626c657d7d292c20616e64207465787420287b7b6d616e 4419 69666573742d6469676573742d746578747d7d292e814100a2036761726d 4420 2e636f6d0578525468697320636f6d706f6e656e7420697320612064656d 4421 6f6e7374726174696f6e2e20546865206469676573742069732061207361 4422 6d706c65207061747465726e2c206e6f742061207265616c206f6e652e 4424 B.4. Example 3: A/B images 4426 This example covers the following templates: 4428 - Compatibility Check (Section 7.1) 4430 - Secure Boot (Section 7.2) 4432 - Firmware Download (Section 7.3) 4434 - A/B Image Template (Section 7.11) 4436 { 4437 / authentication-wrapper / 2:bstr .cbor ({ digest: bstr 4438 .cbor ([ 4439 / algorithm-id / 2 / "sha256" /, 4440 / digest-bytes / 4441 h'ae0c1ea689c9800a843550f38796b6fdbd52a0c78be5d26011d8e784da43d47c' 4442 ]) signatures: [ 4443 bstr .cbor (18([ 4444 / protected / bstr .cbor ({ 4445 / alg / 1:-7 / "ES256" /, 4446 }), 4447 / unprotected / { 4448 }, 4449 / payload / bstr .cbor ([ 4450 / algorithm-id / 2 / "sha256" /, 4451 / digest-bytes / 4452 h'ae0c1ea689c9800a843550f38796b6fdbd52a0c78be5d26011d8e784da43d47c' 4453 ]), 4454 / signature / h'359960bae5a7de2457c8f48d3250d96d1a 4455 f2d36e08764b62d76f8a3f3041774b150b2c835bb1b2d7b1b2e629e1f08cc3b1b48fce 4456 bb8fb38182c116161e02b33f' 4457 ])) 4458 ] 4459 }), 4460 / manifest / 3:bstr .cbor ({ 4461 / manifest-version / 1:1, 4462 / manifest-sequence-number / 2:3, 4463 / common / 3:bstr .cbor ({ 4464 / components / 2:[ 4465 [h'00'] 4466 ], 4467 / common-sequence / 4:bstr .cbor ([ 4468 / directive-override-parameters / 20,{ 4469 / vendor-id / 4470 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 4471 be9d-e663e4d41ffe /, 4472 / class-id / 2:h'1492af1425695e48bf429b2d51f2ab45' 4473 / 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 4474 } , 4475 / directive-try-each / 15,[ 4476 bstr .cbor ([ 4477 / directive-override-parameters / 20,{ 4478 / offset / 5:33792, 4479 } , 4480 / condition-component-offset / 5,5 , 4481 / directive-override-parameters / 20,{ 4482 / image-digest / 3:bstr .cbor ([ 4483 / algorithm-id / 2 / "sha256" /, 4484 / digest-bytes / 4485 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 4486 ]), 4487 / image-size / 14:34768, 4489 } 4490 ]) , 4491 bstr .cbor ([ 4492 / directive-override-parameters / 20,{ 4493 / offset / 5:541696, 4494 } , 4495 / condition-component-offset / 5,5 , 4496 / directive-override-parameters / 20,{ 4497 / image-digest / 3:bstr .cbor ([ 4498 / algorithm-id / 2 / "sha256" /, 4499 / digest-bytes / 4500 h'0123456789abcdeffedcba987654321000112233445566778899aabbccddeeff' 4501 ]), 4502 / image-size / 14:76834, 4503 } 4504 ]) 4505 ] , 4506 / condition-vendor-identifier / 1,15 , 4507 / condition-class-identifier / 2,15 4508 ]), 4509 }), 4510 / install / 9:bstr .cbor ([ 4511 / directive-try-each / 15,[ 4512 bstr .cbor ([ 4513 / directive-set-parameters / 19,{ 4514 / offset / 5:33792, 4515 } , 4516 / condition-component-offset / 5,5 , 4517 / directive-set-parameters / 19,{ 4518 / uri / 21:'http://example.com/file1.bin', 4519 } 4520 ]) , 4521 bstr .cbor ([ 4522 / directive-set-parameters / 19,{ 4523 / offset / 5:541696, 4524 } , 4525 / condition-component-offset / 5,5 , 4526 / directive-set-parameters / 19,{ 4527 / uri / 21:'http://example.com/file2.bin', 4528 } 4529 ]) 4530 ] , 4531 / directive-fetch / 21,2 , 4532 / condition-image-match / 3,15 4533 ]), 4534 / validate / 10:bstr .cbor ([ 4535 / condition-image-match / 3,15 4536 ]), 4538 }), 4539 } 4541 Total size of Envelope without COSE authentication object: 330 4543 Envelope: 4545 a202582781582482025820ae0c1ea689c9800a843550f38796b6fdbd52a0 4546 c78be5d26011d8e784da43d47c0359011ba5010102030358aaa202818141 4547 000458a18814a20150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af 4548 1425695e48bf429b2d51f2ab450f8258368614a105198400050514a20358 4549 248202582000112233445566778899aabbccddeeff0123456789abcdeffe 4550 dcba98765432100e1987d0583a8614a1051a00084400050514a203582482 4551 0258200123456789abcdeffedcba987654321000112233445566778899aa 4552 bbccddeeff0e1a00012c22010f020f095861860f82582a8613a105198400 4553 050513a115781c687474703a2f2f6578616d706c652e636f6d2f66696c65 4554 312e62696e582c8613a1051a00084400050513a115781c687474703a2f2f 4555 6578616d706c652e636f6d2f66696c65322e62696e1502030f0a4382030f 4557 Total size of Envelope with COSE authentication object: 443 4559 Envelope with COSE authentication object: 4561 a202589882582482025820ae0c1ea689c9800a843550f38796b6fdbd52a0 4562 c78be5d26011d8e784da43d47c586fd28443a10126a0582482025820ae0c 4563 1ea689c9800a843550f38796b6fdbd52a0c78be5d26011d8e784da43d47c 4564 5840359960bae5a7de2457c8f48d3250d96d1af2d36e08764b62d76f8a3f 4565 3041774b150b2c835bb1b2d7b1b2e629e1f08cc3b1b48fcebb8fb38182c1 4566 16161e02b33f0359011ba5010102030358aaa202818141000458a18814a2 4567 0150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf42 4568 9b2d51f2ab450f8258368614a105198400050514a2035824820258200011 4569 2233445566778899aabbccddeeff0123456789abcdeffedcba9876543210 4570 0e1987d0583a8614a1051a00084400050514a20358248202582001234567 4571 89abcdeffedcba987654321000112233445566778899aabbccddeeff0e1a 4572 00012c22010f020f095861860f82582a8613a105198400050513a115781c 4573 687474703a2f2f6578616d706c652e636f6d2f66696c65312e62696e582c 4574 8613a1051a00084400050513a115781c687474703a2f2f6578616d706c65 4575 2e636f6d2f66696c65322e62696e1502030f0a4382030f 4577 B.5. Example 4: Load and Decompress from External Storage 4579 This example covers the following templates: 4581 - Compatibility Check (Section 7.1) 4583 - Secure Boot (Section 7.2) 4585 - Firmware Download (Section 7.3) 4586 - Install (Section 7.4) 4588 - Load & Decompress (Section 7.8) 4590 { 4591 / authentication-wrapper / 2:bstr .cbor ({ digest: bstr 4592 .cbor ([ 4593 / algorithm-id / 2 / "sha256" /, 4594 / digest-bytes / 4595 h'4b4c7c8c0fda76c9c9591a9db160918e2b3c96a58b0a5e4984fd4e8f9359a928' 4596 ]) signatures: [ 4597 bstr .cbor (18([ 4598 / protected / bstr .cbor ({ 4599 / alg / 1:-7 / "ES256" /, 4600 }), 4601 / unprotected / { 4602 }, 4603 / payload / bstr .cbor ([ 4604 / algorithm-id / 2 / "sha256" /, 4605 / digest-bytes / 4606 h'4b4c7c8c0fda76c9c9591a9db160918e2b3c96a58b0a5e4984fd4e8f9359a928' 4607 ]), 4608 / signature / h'd721cb3415f27cfeb8ef066bb6312ba758 4609 32b57410a0c700de71cf8004ea23b9dd3c912a99fab111e9b8f2cc55c7dffcc37012de 4610 cf72e44f69b3d3db8cc98cb6' 4611 ])) 4612 ] 4613 }), 4614 / manifest / 3:bstr .cbor ({ 4615 / manifest-version / 1:1, 4616 / manifest-sequence-number / 2:4, 4617 / common / 3:bstr .cbor ({ 4618 / components / 2:[ 4619 [h'00'] , 4620 [h'02'] , 4621 [h'01'] 4622 ], 4623 / common-sequence / 4:bstr .cbor ([ 4624 / directive-set-component-index / 12,0 , 4625 / directive-override-parameters / 20,{ 4626 / vendor-id / 4627 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 4628 be9d-e663e4d41ffe /, 4629 / class-id / 2:h'1492af1425695e48bf429b2d51f2ab45' 4630 / 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 4631 / image-digest / 3:bstr .cbor ([ 4632 / algorithm-id / 2 / "sha256" /, 4633 / digest-bytes / 4635 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 4636 ]), 4637 / image-size / 14:34768, 4638 } , 4639 / condition-vendor-identifier / 1,15 , 4640 / condition-class-identifier / 2,15 4641 ]), 4642 }), 4643 / payload-fetch / 8:bstr .cbor ([ 4644 / directive-set-component-index / 12,1 , 4645 / directive-set-parameters / 19,{ 4646 / uri / 21:'http://example.com/file.bin', 4647 } , 4648 / directive-fetch / 21,2 , 4649 / condition-image-match / 3,15 4650 ]), 4651 / install / 9:bstr .cbor ([ 4652 / directive-set-component-index / 12,0 , 4653 / directive-set-parameters / 19,{ 4654 / source-component / 22:1 / [h'02'] /, 4655 } , 4656 / directive-copy / 22,2 , 4657 / condition-image-match / 3,15 4658 ]), 4659 / validate / 10:bstr .cbor ([ 4660 / directive-set-component-index / 12,0 , 4661 / condition-image-match / 3,15 4662 ]), 4663 / load / 11:bstr .cbor ([ 4664 / directive-set-component-index / 12,2 , 4665 / directive-set-parameters / 19,{ 4666 / image-digest / 3:bstr .cbor ([ 4667 / algorithm-id / 2 / "sha256" /, 4668 / digest-bytes / 4669 h'0123456789abcdeffedcba987654321000112233445566778899aabbccddeeff' 4670 ]), 4671 / image-size / 14:76834, 4672 / source-component / 22:0 / [h'00'] /, 4673 / compression-info / 19:1 / "gzip" /, 4674 } , 4675 / directive-copy / 22,2 , 4676 / condition-image-match / 3,15 4677 ]), 4678 / run / 12:bstr .cbor ([ 4679 / directive-set-component-index / 12,2 , 4680 / directive-run / 23,2 4681 ]), 4682 }), 4684 } 4686 Total size of Envelope without COSE authentication object: 287 4688 Envelope: 4690 a2025827815824820258204b4c7c8c0fda76c9c9591a9db160918e2b3c96 4691 a58b0a5e4984fd4e8f9359a9280358f1a801010204035867a20283814100 4692 814102814101045858880c0014a40150fa6b4a53d5ad5fdfbe9de663e4d4 4693 1ffe02501492af1425695e48bf429b2d51f2ab4503582482025820001122 4694 33445566778899aabbccddeeff0123456789abcdeffedcba98765432100e 4695 1987d0010f020f085827880c0113a115781b687474703a2f2f6578616d70 4696 6c652e636f6d2f66696c652e62696e1502030f094b880c0013a116011602 4697 030f0a45840c00030f0b583a880c0213a4035824820258200123456789ab 4698 cdeffedcba987654321000112233445566778899aabbccddeeff0e1a0001 4699 2c22130116001602030f0c45840c021702 4701 Total size of Envelope with COSE authentication object: 400 4703 Envelope with COSE authentication object: 4705 a2025898825824820258204b4c7c8c0fda76c9c9591a9db160918e2b3c96 4706 a58b0a5e4984fd4e8f9359a928586fd28443a10126a05824820258204b4c 4707 7c8c0fda76c9c9591a9db160918e2b3c96a58b0a5e4984fd4e8f9359a928 4708 5840d721cb3415f27cfeb8ef066bb6312ba75832b57410a0c700de71cf80 4709 04ea23b9dd3c912a99fab111e9b8f2cc55c7dffcc37012decf72e44f69b3 4710 d3db8cc98cb60358f1a801010204035867a2028381410081410281410104 4711 5858880c0014a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af 4712 1425695e48bf429b2d51f2ab450358248202582000112233445566778899 4713 aabbccddeeff0123456789abcdeffedcba98765432100e1987d0010f020f 4714 085827880c0113a115781b687474703a2f2f6578616d706c652e636f6d2f 4715 66696c652e62696e1502030f094b880c0013a116011602030f0a45840c00 4716 030f0b583a880c0213a4035824820258200123456789abcdeffedcba9876 4717 54321000112233445566778899aabbccddeeff0e1a00012c221301160016 4718 02030f0c45840c021702 4720 B.6. Example 5: Two Images 4722 This example covers the following templates: 4724 - Compatibility Check (Section 7.1) 4726 - Secure Boot (Section 7.2) 4728 - Firmware Download (Section 7.3) 4730 Furthermore, it shows using these templates with two images. 4732 { 4733 / authentication-wrapper / 2:bstr .cbor ({ digest: bstr 4734 .cbor ([ 4735 / algorithm-id / 2 / "sha256" /, 4736 / digest-bytes / 4737 h'de7c7927a15bd2eda59cab1512875f17c9f1e9e23885ce1ac6d671eefcefa37a' 4738 ]) signatures: [ 4739 bstr .cbor (18([ 4740 / protected / bstr .cbor ({ 4741 / alg / 1:-7 / "ES256" /, 4742 }), 4743 / unprotected / { 4744 }, 4745 / payload / bstr .cbor ([ 4746 / algorithm-id / 2 / "sha256" /, 4747 / digest-bytes / 4748 h'de7c7927a15bd2eda59cab1512875f17c9f1e9e23885ce1ac6d671eefcefa37a' 4749 ]), 4750 / signature / h'e71e332c985fb0479f296685669d05348b 4751 cdba8e186f25a5418f4682ea168df61661f54bf48f964577225ed455b22d277dd94de8 4752 7c57f1baceedd6719f3d56ec' 4753 ])) 4754 ] 4755 }), 4756 / manifest / 3:bstr .cbor ({ 4757 / manifest-version / 1:1, 4758 / manifest-sequence-number / 2:5, 4759 / common / 3:bstr .cbor ({ 4760 / components / 2:[ 4761 [h'00'] , 4762 [h'01'] 4763 ], 4764 / common-sequence / 4:bstr .cbor ([ 4765 / directive-set-component-index / 12,0 , 4766 / directive-override-parameters / 20,{ 4767 / vendor-id / 4768 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 4769 be9d-e663e4d41ffe /, 4770 / class-id / 2:h'1492af1425695e48bf429b2d51f2ab45' 4771 / 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 4772 / image-digest / 3:bstr .cbor ([ 4773 / algorithm-id / 2 / "sha256" /, 4774 / digest-bytes / 4775 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 4776 ]), 4777 / image-size / 14:34768, 4778 } , 4779 / condition-vendor-identifier / 1,15 , 4780 / condition-class-identifier / 2,15 , 4781 / directive-set-component-index / 12,1 , 4782 / directive-override-parameters / 20,{ 4783 / image-digest / 3:bstr .cbor ([ 4784 / algorithm-id / 2 / "sha256" /, 4785 / digest-bytes / 4786 h'0123456789abcdeffedcba987654321000112233445566778899aabbccddeeff' 4787 ]), 4788 / image-size / 14:76834, 4789 } 4790 ]), 4791 }), 4792 / install / 9:bstr .cbor ([ 4793 / directive-set-component-index / 12,0 , 4794 / directive-set-parameters / 19,{ 4795 / uri / 21:'http://example.com/file1.bin', 4796 } , 4797 / directive-fetch / 21,2 , 4798 / condition-image-match / 3,15 , 4799 / directive-set-component-index / 12,1 , 4800 / directive-set-parameters / 19,{ 4801 / uri / 21:'http://example.com/file2.bin', 4802 } , 4803 / directive-fetch / 21,2 , 4804 / condition-image-match / 3,15 4805 ]), 4806 / validate / 10:bstr .cbor ([ 4807 / directive-set-component-index / 12,0 , 4808 / condition-image-match / 3,15 , 4809 / directive-set-component-index / 12,1 , 4810 / condition-image-match / 3,15 4811 ]), 4812 / run / 12:bstr .cbor ([ 4813 / directive-set-component-index / 12,0 , 4814 / directive-run / 23,2 4815 ]), 4816 }), 4817 } 4819 Total size of Envelope without COSE authentication object: 304 4821 Envelope: 4823 a202582781582482025820de7c7927a15bd2eda59cab1512875f17c9f1e9 4824 e23885ce1ac6d671eefcefa37a03590101a601010205035895a202828141 4825 008141010458898c0c0014a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe 4826 02501492af1425695e48bf429b2d51f2ab45035824820258200011223344 4827 5566778899aabbccddeeff0123456789abcdeffedcba98765432100e1987 4828 d0010f020f0c0114a2035824820258200123456789abcdeffedcba987654 4829 321000112233445566778899aabbccddeeff0e1a00012c2209584f900c00 4830 13a115781c687474703a2f2f6578616d706c652e636f6d2f66696c65312e 4831 62696e1502030f0c0113a115781c687474703a2f2f6578616d706c652e63 4832 6f6d2f66696c65322e62696e1502030f0a49880c00030f0c01030f0c4584 4833 0c001702 4835 Total size of Envelope with COSE authentication object: 417 4837 Envelope with COSE authentication object: 4839 a202589882582482025820de7c7927a15bd2eda59cab1512875f17c9f1e9 4840 e23885ce1ac6d671eefcefa37a586fd28443a10126a0582482025820de7c 4841 7927a15bd2eda59cab1512875f17c9f1e9e23885ce1ac6d671eefcefa37a 4842 5840e71e332c985fb0479f296685669d05348bcdba8e186f25a5418f4682 4843 ea168df61661f54bf48f964577225ed455b22d277dd94de87c57f1baceed 4844 d6719f3d56ec03590101a601010205035895a20282814100814101045889 4845 8c0c0014a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425 4846 695e48bf429b2d51f2ab450358248202582000112233445566778899aabb 4847 ccddeeff0123456789abcdeffedcba98765432100e1987d0010f020f0c01 4848 14a2035824820258200123456789abcdeffedcba98765432100011223344 4849 5566778899aabbccddeeff0e1a00012c2209584f900c0013a115781c6874 4850 74703a2f2f6578616d706c652e636f6d2f66696c65312e62696e1502030f 4851 0c0113a115781c687474703a2f2f6578616d706c652e636f6d2f66696c65 4852 322e62696e1502030f0a49880c00030f0c01030f0c45840c001702 4854 Appendix C. C. Design Rational 4856 In order to provide flexible behavior to constrained devices, while 4857 still allowing more powerful devices to use their full capabilities, 4858 the SUIT manifest encodes the required behavior of a Recipient 4859 device. Behavior is encoded as a specialized byte code, contained in 4860 a CBOR list. This promotes a flat encoding, which simplifies the 4861 parser. The information encoded by this byte code closely matches 4862 the operations that a device will perform, which promotes ease of 4863 processing. The core operations used by most update and trusted 4864 invocation operations are represented in the byte code. The byte 4865 code can be extended by registering new operations. 4867 The specialized byte code approach gives benefits equivalent to those 4868 provided by a scripting language or conventional byte code, with two 4869 substantial differences. First, the language is extremely high 4870 level, consisting of only the operations that a device may perform 4871 during update and trusted invocation of a firmware image. Second, 4872 the language specifies linear behavior, without reverse branches. 4873 Conditional processing is supported, and parallel and out-of-order 4874 processing may be performed by sufficiently capable devices. 4876 By structuring the data in this way, the manifest processor becomes a 4877 very simple engine that uses a pull parser to interpret the manifest. 4878 This pull parser invokes a series of command handlers that evaluate a 4879 Condition or execute a Directive. Most data is structured in a 4880 highly regular pattern, which simplifies the parser. 4882 The results of this allow a Recipient to implement a very small 4883 parser for constrained applications. If needed, such a parser also 4884 allows the Recipient to perform complex updates with reduced 4885 overhead. Conditional execution of commands allows a simple device 4886 to perform important decisions at validation-time. 4888 Dependency handling is vastly simplified as well. Dependencies 4889 function like subroutines of the language. When a manifest has a 4890 dependency, it can invoke that dependency's commands and modify their 4891 behavior by setting parameters. Because some parameters come with 4892 security implications, the dependencies also have a mechanism to 4893 reject modifications to parameters on a fine-grained level. 4895 Developing a robust permissions system works in this model too. The 4896 Recipient can use a simple ACL that is a table of Identities and 4897 Component Identifier permissions to ensure that operations on 4898 components fail unless they are permitted by the ACL. This table can 4899 be further refined with individual parameters and commands. 4901 Capability reporting is similarly simplified. A Recipient can report 4902 the Commands, Parameters, Algorithms, and Component Identifiers that 4903 it supports. This is sufficiently precise for a manifest author to 4904 create a manifest that the Recipient can accept. 4906 The simplicity of design in the Recipient due to all of these 4907 benefits allows even a highly constrained platform to use advanced 4908 update capabilities. 4910 C.1. C.1 Design Rationale: Envelope 4912 The Envelope is used instead of a COSE structure for several reasons: 4914 1. This enables the use of Severable Elements (Section 8.8) 4916 2. This enables modular processing of manifests, particularly with 4917 large signatures. 4919 3. This enables multiple authentication schemes. 4921 4. This allows integrity verification by a dependent to be 4922 unaffected by adding or removing authentication structures. 4924 Modular processing is important because it allows a Manifest 4925 Processor to iterate forward over an Envelope, processing Delegation 4926 Chains and Authentication Blocks, retaining only intermediate values, 4927 without any need to seek forward and backwards in a stream until it 4928 gets to the Manifest itself. This allows the use of large, Post- 4929 Quantum signatures without requiring retention of the signature 4930 itself, or seeking forward and back. 4932 Four authentication objects are supported by the Envelope: 4934 - COSE_Sign_Tagged 4936 - COSE_Sign1_Tagged 4938 - COSE_Mac_Tagged 4940 - COSE_Mac0_Tagged 4942 The SUIT Envelope allows an Update Authority or intermediary to mix 4943 and match any number of different authentication blocks it wants 4944 without any concern for modifying the integrity of another 4945 authentication block. This also allows the addition or removal of an 4946 authentication blocks without changing the integrity check of the 4947 Manifest, which is important for dependency handling. See 4948 Section 6.2 4950 C.2. C.2 Byte String Wrappers 4952 Byte string wrappers are used in several places in the suit manifest. 4953 The primary reason for wrappers it to limit the parser extent when 4954 invoked at different times, with a possible loss of context. 4956 The elements of the suit envelope are wrapped both to set the extents 4957 used by the parser and to simplify integrity checks by clearly 4958 defining the length of each element. 4960 The common block is re-parsed in order to find components identifiers 4961 from their indices, to find dependency prefixes and digests from 4962 their identifiers, and to find the common sequence. The common 4963 sequence is wrapped so that it matches other sequences, simplifying 4964 the code path. 4966 A severed SUIT command sequence will appear in the envelope, so it 4967 must be wrapped as with all envelope elements. For consistency, 4968 command sequences are also wrapped in the manifest. This also allows 4969 the parser to discern the difference between a command sequence and a 4970 SUIT_Digest. 4972 Parameters that are structured types (arrays and maps) are also 4973 wrapped in a bstr. This is so that parser extents can be set 4974 correctly using only a reference to the beginning of the parameter. 4975 This enables a parser to store a simple list of references to 4976 parameters that can be retrieved when needed. 4978 Appendix D. D. Implementation Conformance Matrix 4980 This section summarizes the functionality a minimal implementation 4981 needs to offer to claim conformance to this specification, in the 4982 absence of an application profile standard specifying otherwise. 4984 The subsequent table shows the conditions. 4986 +-------------------+------------------+----------------+ 4987 | Name | Reference | Implementation | 4988 +-------------------+------------------+----------------+ 4989 | Vendor Identifier | Section 8.7.5.2 | REQUIRED | 4990 | | | | 4991 | Class Identifier | Section 8.7.5.2 | REQUIRED | 4992 | | | | 4993 | Device Identifier | Section 8.7.5.2 | OPTIONAL | 4994 | | | | 4995 | Image Match | Section 8.7.6.2 | REQUIRED | 4996 | | | | 4997 | Image Not Match | Section 8.7.6.3 | OPTIONAL | 4998 | | | | 4999 | Use Before | Section 8.7.6.4 | OPTIONAL | 5000 | | | | 5001 | Component Offset | Section 8.7.6.5 | OPTIONAL | 5002 | | | | 5003 | Abort | Section 8.7.6.9 | OPTIONAL | 5004 | | | | 5005 | Minimum Battery | Section 8.7.6.6 | OPTIONAL | 5006 | | | | 5007 | Update Authorized | Section 8.7.6.7 | OPTIONAL | 5008 | | | | 5009 | Version | Section 8.7.6.8 | OPTIONAL | 5010 | | | | 5011 | Custom Condition | Section 8.7.6.10 | OPTIONAL | 5012 +-------------------+------------------+----------------+ 5014 The subsequent table shows the directives. 5016 +-------------------+----------------+------------------------------+ 5017 | Name | Reference | Implementation | 5018 +-------------------+----------------+------------------------------+ 5019 | Set Component | Section 8.7.7. | REQUIRED if more than one | 5020 | Index | 1 | component | 5021 | | | | 5022 | Set Dependency | Section 8.7.7. | REQUIRED if dependencies | 5023 | Index | 2 | used | 5024 | | | | 5025 | Try Each | Section 8.7.7. | OPTIONAL | 5026 | | 3 | | 5027 | | | | 5028 | Process | Section 8.7.7. | OPTIONAL | 5029 | Dependency | 4 | | 5030 | | | | 5031 | Set Parameters | Section 8.7.7. | OPTIONAL | 5032 | | 5 | | 5033 | | | | 5034 | Override | Section 8.7.7. | REQUIRED | 5035 | Parameters | 6 | | 5036 | | | | 5037 | Fetch | Section 8.7.7. | REQUIRED for Updater | 5038 | | 7 | | 5039 | | | | 5040 | Copy | Section 8.7.7. | OPTIONAL | 5041 | | 9 | | 5042 | | | | 5043 | Run | Section 8.7.7. | REQUIRED for Bootloader | 5044 | | 10 | | 5045 | | | | 5046 | Wait For Event | Section 8.7.7. | OPTIONAL | 5047 | | 11 | | 5048 | | | | 5049 | Run Sequence | Section 8.7.7. | OPTIONAL | 5050 | | 12 | | 5051 | | | | 5052 | Swap | Section 8.7.7. | OPTIONAL | 5053 | | 13 | | 5054 | | | | 5055 | Fetch URI List | Section 8.7.7. | OPTIONAL | 5056 | | 8 | | 5057 +-------------------+----------------+------------------------------+ 5059 The subsequent table shows the parameters. 5061 +------------------+------------------+----------------------+ 5062 | Name | Reference | Implementation | 5063 +------------------+------------------+----------------------+ 5064 | Vendor ID | Section 8.7.5.3 | REQUIRED | 5065 | | | | 5066 | Class ID | Section 8.7.5.4 | REQUIRED | 5067 | | | | 5068 | Image Digest | Section 8.7.5.6 | REQUIRED | 5069 | | | | 5070 | Image Size | Section 8.7.5.7 | REQUIRED | 5071 | | | | 5072 | Use Before | Section 8.7.5.8 | RECOMMENDED | 5073 | | | | 5074 | Component Offset | Section 8.7.5.9 | OPTIONAL | 5075 | | | | 5076 | Encryption Info | Section 8.7.5.10 | RECOMMENDED | 5077 | | | | 5078 | Compression Info | Section 8.7.5.11 | RECOMMENDED | 5079 | | | | 5080 | Unpack Info | Section 8.7.5.12 | RECOMMENDED | 5081 | | | | 5082 | URI | Section 8.7.5.13 | REQUIRED for Updater | 5083 | | | | 5084 | Source Component | Section 8.7.5.14 | OPTIONAL | 5085 | | | | 5086 | Run Args | Section 8.7.5.15 | OPTIONAL | 5087 | | | | 5088 | Device ID | Section 8.7.5.5 | OPTIONAL | 5089 | | | | 5090 | Minimum Battery | Section 8.7.5.16 | OPTIONAL | 5091 | | | | 5092 | Update Priority | Section 8.7.5.17 | OPTIONAL | 5093 | | | | 5094 | Version Match | Section 8.7.5.18 | OPTIONAL | 5095 | | | | 5096 | Wait Info | Section 8.7.5.19 | OPTIONAL | 5097 | | | | 5098 | URI List | Section 8.7.5.20 | OPTIONAL | 5099 | | | | 5100 | Strict Order | Section 8.7.5.22 | OPTIONAL | 5101 | | | | 5102 | Soft Failure | Section 8.7.5.23 | OPTIONAL | 5103 | | | | 5104 | Custom | Section 8.7.5.24 | OPTIONAL | 5105 +------------------+------------------+----------------------+ 5107 Authors' Addresses 5109 Brendan Moran 5110 Arm Limited 5112 EMail: Brendan.Moran@arm.com 5114 Hannes Tschofenig 5115 Arm Limited 5117 EMail: hannes.tschofenig@arm.com 5119 Henk Birkholz 5120 Fraunhofer SIT 5122 EMail: henk.birkholz@sit.fraunhofer.de 5124 Koen Zandberg 5125 Inria 5127 EMail: koen.zandberg@inria.fr