idnits 2.17.00 (12 Aug 2021) /tmp/idnits43026/draft-ietf-suit-manifest-08.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 20 instances of too long lines in the document, the longest one being 7 characters in excess of 72. == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 12, 2020) is 677 days in the past. Is this intentional? 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 3184 -- Looks like a reference, but probably isn't: '2' on line 2192 -- Looks like a reference, but probably isn't: '3' on line 2163 == Missing Reference: '-1' is mentioned on line 2192, but not defined == Missing Reference: '-2' is mentioned on line 2165, but not defined == Missing Reference: '-3' is mentioned on line 2169, but not defined -- Looks like a reference, but probably isn't: '4' on line 2169 -- Looks like a reference, but probably isn't: '0' on line 2192 == 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-11 == Outdated reference: draft-kucherawy-rfc8478bis has been published as RFC 8878 Summary: 1 error (**), 0 flaws (~~), 9 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 SUIT B. Moran 3 Internet-Draft H. Tschofenig 4 Intended status: Standards Track Arm Limited 5 Expires: January 13, 2021 H. Birkholz 6 Fraunhofer SIT 7 K. Zandberg 8 Inria 9 July 12, 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-08 15 Abstract 17 This specification describes the format of a manifest. A manifest is 18 a bundle of metadata about the firmware for an IoT device, where to 19 find the firmware, the devices to which it applies, and cryptographic 20 information protecting the manifest. Firmware updates and secure 21 boot both tend to use sequences of common operations, so the manifest 22 encodes those sequences of operations, rather than declaring the 23 metadata. The manifest also serves as a building block for secure 24 boot. 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at https://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on January 13, 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 . . . . . . . . . . . . . . . . . . . . 12 69 5.3. Authentication Block . . . . . . . . . . . . . . . . . . 13 70 5.4. Manifest . . . . . . . . . . . . . . . . . . . . . . . . 13 71 5.4.1. Critical Metadata . . . . . . . . . . . . . . . . . . 13 72 5.4.2. Common . . . . . . . . . . . . . . . . . . . . . . . 13 73 5.4.3. Command Sequences . . . . . . . . . . . . . . . . . . 14 74 5.4.4. Integrity Check Values . . . . . . . . . . . . . . . 14 75 5.4.5. Human-Readable Text . . . . . . . . . . . . . . . . . 14 76 5.5. Severable Elements . . . . . . . . . . . . . . . . . . . 15 77 5.6. Integrated Dependencies and Payloads . . . . . . . . . . 15 78 6. Interpreter Behavior . . . . . . . . . . . . . . . . . . . . 15 79 6.1. Interpreter Setup . . . . . . . . . . . . . . . . . . . . 16 80 6.2. Required Checks . . . . . . . . . . . . . . . . . . . . . 17 81 6.2.1. Minimizing Signature Verifications . . . . . . . . . 18 82 6.3. Interpreter Fundamental Properties . . . . . . . . . . . 18 83 6.4. Abstract Machine Description . . . . . . . . . . . . . . 19 84 6.5. Serialized Processing Interpreter . . . . . . . . . . . . 21 85 6.6. Parallel Processing Interpreter . . . . . . . . . . . . . 21 86 6.7. Processing Dependencies . . . . . . . . . . . . . . . . . 22 87 6.8. Multiple Manifest Processors . . . . . . . . . . . . . . 22 88 7. Creating Manifests . . . . . . . . . . . . . . . . . . . . . 23 89 7.1. Compatibility Check Template . . . . . . . . . . . . . . 24 90 7.2. Secure Boot Template . . . . . . . . . . . . . . . . . . 24 91 7.3. Firmware Download Template . . . . . . . . . . . . . . . 25 92 7.4. Install Template . . . . . . . . . . . . . . . . . . . . 25 93 7.5. Integrated Payload Template . . . . . . . . . . . . . . . 26 94 7.6. Load from Nonvolatile Storage Template . . . . . . . . . 26 95 7.7. Load & Decompress from Nonvolatile Storage Template . . . 26 96 7.8. Dependency Template . . . . . . . . . . . . . . . . . . . 27 97 7.8.1. Composite Manifests . . . . . . . . . . . . . . . . . 27 98 7.9. Encrypted Manifest Template . . . . . . . . . . . . . . . 28 99 7.10. A/B Image Template . . . . . . . . . . . . . . . . . . . 28 100 8. Metadata Structure . . . . . . . . . . . . . . . . . . . . . 29 101 8.1. Encoding Considerations . . . . . . . . . . . . . . . . . 30 102 8.2. Envelope . . . . . . . . . . . . . . . . . . . . . . . . 30 103 8.3. Delegation Chains . . . . . . . . . . . . . . . . . . . . 30 104 8.4. Authenticated Manifests . . . . . . . . . . . . . . . . . 31 105 8.5. Encrypted Manifests . . . . . . . . . . . . . . . . . . . 31 106 8.6. Manifest . . . . . . . . . . . . . . . . . . . . . . . . 31 107 8.6.1. suit-manifest-version . . . . . . . . . . . . . . . . 32 108 8.6.2. suit-manifest-sequence-number . . . . . . . . . . . . 32 109 8.6.3. suit-reference-uri . . . . . . . . . . . . . . . . . 32 110 8.6.4. suit-text . . . . . . . . . . . . . . . . . . . . . . 33 111 8.7. text-version-required . . . . . . . . . . . . . . . . . . 34 112 8.7.1. suit-coswid . . . . . . . . . . . . . . . . . . . . . 34 113 8.7.2. suit-common . . . . . . . . . . . . . . . . . . . . . 35 114 8.7.3. SUIT_Command_Sequence . . . . . . . . . . . . . . . . 36 115 8.7.4. Reporting Policy . . . . . . . . . . . . . . . . . . 39 116 8.7.5. SUIT_Parameters . . . . . . . . . . . . . . . . . . . 40 117 8.7.6. SUIT_Condition . . . . . . . . . . . . . . . . . . . 50 118 8.7.7. SUIT_Directive . . . . . . . . . . . . . . . . . . . 54 119 8.7.8. Integrity Check Values . . . . . . . . . . . . . . . 60 120 8.8. Severable Elements . . . . . . . . . . . . . . . . . . . 61 121 9. Access Control Lists . . . . . . . . . . . . . . . . . . . . 61 122 10. SUIT Digest Container . . . . . . . . . . . . . . . . . . . . 62 123 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 62 124 11.1. SUIT Commands . . . . . . . . . . . . . . . . . . . . . 63 125 11.2. SUIT Parameters . . . . . . . . . . . . . . . . . . . . 64 126 11.3. SUIT Text Values . . . . . . . . . . . . . . . . . . . . 66 127 11.4. SUIT Component Text Values . . . . . . . . . . . . . . . 66 128 11.5. SUIT Algorithm Identifiers . . . . . . . . . . . . . . . 66 129 11.5.1. SUIT Digest Algorithm Identifiers . . . . . . . . . 66 130 11.5.2. SUIT Compression Algorithm Identifiers . . . . . . . 67 131 11.5.3. Unpack Algorithms . . . . . . . . . . . . . . . . . 67 132 12. Security Considerations . . . . . . . . . . . . . . . . . . . 68 133 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 68 134 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 68 135 14.1. Normative References . . . . . . . . . . . . . . . . . . 68 136 14.2. Informative References . . . . . . . . . . . . . . . . . 69 137 14.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 70 138 A. Full CDDL . . . . . . . . . . . . . . . . . . . . . . . . . . 71 139 B. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 140 B.1. Example 0: Secure Boot . . . . . . . . . . . . . . . . . 82 141 B.2. Example 1: Simultaneous Download and Installation of 142 Payload . . . . . . . . . . . . . . . . . . . . . . . . . 84 143 B.3. Example 2: Simultaneous Download, Installation, Secure 144 Boot, Severed Fields . . . . . . . . . . . . . . . . . . 87 145 B.4. Example 3: A/B images . . . . . . . . . . . . . . . . . . 91 146 B.5. Example 4: Load and Decompress from External Storage . . 95 147 B.6. Example 5: Two Images . . . . . . . . . . . . . . . . . . 99 148 C. Design Rational . . . . . . . . . . . . . . . . . . . . . . . 102 149 C.1. C.1 Design Rationale: Envelope . . . . . . . . . . . . . 103 150 C.2. C.2 Byte String Wrappers . . . . . . . . . . . . . . . . 104 151 D. Implementation Conformance Matrix . . . . . . . . . . . . . . 105 152 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 108 154 1. Introduction 156 A firmware update mechanism is an essential security feature for IoT 157 devices to deal with vulnerabilities. While the transport of 158 firmware images to the devices themselves is important there are 159 already various techniques available. Equally important is the 160 inclusion of metadata about the conveyed firmware image (in the form 161 of a manifest) and the use of a security wrapper to provide end-to- 162 end security protection to detect modifications and (optionally) to 163 make reverse engineering more difficult. End-to-end security allows 164 the author, who builds the firmware image, to be sure that no other 165 party (including potential adversaries) can install firmware updates 166 on IoT devices without adequate privileges. For confidentiality 167 protected firmware images it is additionally required to encrypt the 168 firmware image. Starting security protection at the author is a risk 169 mitigation technique so firmware images and manifests can be stored 170 on untrusted repositories; it also reduces the scope of a compromise 171 of any repository or intermediate system to be no worse than a denial 172 of service. 174 A manifest is a bundle of metadata about the firmware for an IoT 175 device, where to find the firmware, the devices to which it applies, 176 and cryptographic information protecting the manifest. 178 This specification defines the SUIT manifest format and it is 179 intended to meet several goals: 181 - Meet the requirements defined in 182 [I-D.ietf-suit-information-model]. 184 - Simple to parse on a constrained node 186 - Simple to process on a constrained node 188 - Compact encoding 190 - Comprehensible by an intermediate system 191 - Expressive enough to enable advanced use cases on advanced nodes 193 - Extensible 195 The SUIT manifest can be used for a variety of purposes throughout 196 its lifecycle, such as: 198 - the Firmware Author to reason about releasing a firmware. 200 - the Network Operator to reason about compatibility of a firmware. 202 - the Device Operator to reason about the impact of a firmware. 204 - the Device Operator to manage distribution of firmware to devices. 206 - the Plant Manager to reason about timing and acceptance of 207 firmware updates. 209 - the device to reason about the authority & authenticity of a 210 firmware prior to installation. 212 - the device to reason about the applicability of a firmware. 214 - the device to reason about the installation of a firmware. 216 - the device to reason about the authenticity & encoding of a 217 firmware at boot. 219 Each of these uses happens at a different stage of the manifest 220 lifecycle, so each has different requirements. 222 It is assumed that the reader is familiar with the high-level 223 firmware update architecture [I-D.ietf-suit-architecture] and the 224 threats, requirements, and user stories in 225 [I-D.ietf-suit-information-model]. 227 The design of this specification is based on an observation that the 228 vast majority of operations that a device can perform during an 229 update or secure boot are composed of a small group of operations: 231 - Copy some data from one place to another 233 - Transform some data 235 - Digest some data and compare to an expected value 237 - Compare some system parameters to an expected value 238 - Run some code 240 In the SUIT manifest specification, these operations are called 241 commands. Commands are classed as either conditions or directives. 242 Conditions have no side-effects, while directives do have side- 243 effects. Conceptually, a sequence of commands is like a script but 244 the used language is tailored to software updates and secure boot. 246 The available commands support simple steps, such as copying a 247 firmware image from one place to another, checking that a firmware 248 image is correct, verifying that the specified firmware is the 249 correct firmware for the device, or unpacking a firmware. By using 250 these steps in different orders and changing the parameters they use, 251 a broad range of use cases can be supported. The SUIT manifest uses 252 this observation to optimize metadata for consumption by constrained 253 devices. 255 While the SUIT manifest is informed by and optimized for firmware 256 update and secure boot use cases, there is nothing in the 257 [I-D.ietf-suit-information-model] that restricts its use to only 258 those use cases. Other use cases include the management of trusted 259 applications in a Trusted Execution Environment (TEE), see 260 [I-D.ietf-teep-architecture]. 262 2. Conventions and Terminology 264 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 265 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 266 "OPTIONAL" in this document are to be interpreted as described in 267 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 268 capitals, as shown here. 270 The following terminology is used throughout this document: 272 - SUIT: Software Update for the Internet of Things, also the IETF 273 working group for this standard. 275 - Payload: A piece of information to be delivered. Typically 276 Firmware for the purposes of SUIT. 278 - Resource: A piece of information that is used to construct a 279 payload. 281 - Manifest: A manifest is a bundle of metadata about the firmware 282 for an IoT device, where to find the firmware, and the devices to 283 which it applies. 285 - Envelope: A container with the manifest, an authentication wrapper 286 with cryptographic information protecting the manifest, 287 authorization information, and severed fields. 289 - Update: One or more manifests that describe one or more payloads. 291 - Update Authority: The owner of a cryptographic key used to sign 292 updates, trusted by Recipients. 294 - Recipient: The system, typically an IoT device, that receives and 295 processes a manifest. 297 - Manifest Processor: A component of the Recipient that consumes 298 Manifests and executes the commands in the Manifest. 300 - Component: An updatable logical block of the Firmware, Software, 301 configuration, or data of the Recipient. 303 - Component Set: A group of interdependent Components that must be 304 updated simultaneously. 306 - Command: A Condition or a Directive. 308 - Condition: A test for a property of the Recipient or its 309 Components. 311 - Directive: An action for the Recipient to perform. 313 - Trusted Execution: A process by which a system ensures that only 314 trusted code is executed, for example secure boot. 316 - A/B images: Dividing a Recipient's storage into two or more 317 bootable images, at different offsets, such that the active image 318 can write to the inactive image(s). 320 - Record: The result of a Command and any metadata about it. 322 - Report: A list of Records. 324 - Procedure: The process of invoking one or more sequences of 325 commands. 327 - Update Procedure: A procedure that updates a Recipient by fetching 328 dependencies, software images, and installing them. 330 - Boot Procedure: A procedure that boots a Recipient by verifying 331 dependencies and images, loading images, and invoking one or more 332 image. 334 - Software: Instructions and data that allow a Recipient to perform 335 a useful function. 337 - Firmware: Instructions and data that allow a Recipient to perform 338 a useful function. Typically, changed infrequently, stored in 339 nonvolatile memory, and small enough to apply to [RFC7228] Class 340 0-2 devices. 342 - Image: Information that a Recipient uses to perform its function, 343 typically firmware/software, configuration, or resource data such 344 as text or images. Also, a Payload, once installed is an Image. 346 - Slot: One of several possible storage locations for a given 347 Component, typically used in A/B image systems 349 - Abort: The Manifest Processor immediately halts execution of the 350 current Procedure. It creates a Record of an error condition. 352 3. How to use this Document 354 This specification covers five aspects of firmware update: 356 - Section 4 describes the device constraints, use cases, and design 357 principles that informed the structure of the manifest. 359 - Section 5 gives a general overview of the metadata structure to 360 inform the following sections 362 - Section 6 describes what actions a Manifest processor should take. 364 - Section 7 describes the process of creating a Manifest. 366 - Section 8 specifies the content of the Envelope and the Manifest. 368 To implement an updatable device, see Section 6 and Section 8. To 369 implement a tool that generates updates, see Section 7 and Section 8. 371 The IANA consideration section, see Section 11, provides instructions 372 to IANA to create several registries. This section also provides the 373 CBOR labels for the structures defined in this document. 375 The complete CDDL description is provided in [full-cddl], examples 376 are given in [examples] and a design rational is offered in 377 [design-rationale]. Finally, [implementation-matrix] gives a 378 summarize of the mandatory-to-implement features of this 379 specification. 381 4. Background 383 Distributing firmware updates to diverse devices with diverse trust 384 anchors in a coordinated system presents unique challenges. Devices 385 have a broad set of constraints, requiring different metadata to make 386 appropriate decisions. There may be many actors in production IoT 387 systems, each of whom has some authority. Distributing firmware in 388 such a multi-party environment presents additional challenges. Each 389 party requires a different subset of data. Some data may not be 390 accessible to all parties. Multiple signatures may be required from 391 parties with different authorities. This topic is covered in more 392 depth in [I-D.ietf-suit-architecture]. The security aspects are 393 described in [I-D.ietf-suit-information-model]. 395 4.1. IoT Firmware Update Constraints 397 The various constraints of IoT devices and the range of use cases 398 that need to be supported create a broad set of urequirements. For 399 example, devices with: 401 - limited processing power and storage may require a simple 402 representation of metadata. 404 - bandwidth constraints may require firmware compression or partial 405 update support. 407 - bootloader complexity constraints may require simple selection 408 between two bootable images. 410 - small internal storage may require external storage support. 412 - multiple microcontrollers may require coordinated update of all 413 applications. 415 - large storage and complex functionality may require parallel 416 update of many software components. 418 - extra information may need to be conveyed in the manifest in the 419 earlier stages of the device lifecycle before those data items are 420 stripped when the manifest is delivery to a constrained device. 422 Supporting the requirements introduced by the constraints on IoT 423 devices requires the flexibility to represent a diverse set of 424 possible metadata, but also requires that the encoding is kept 425 simple. 427 4.2. SUIT Workflow Model 429 There are several fundamental assumptions that inform the model of 430 Update Procedure workflow: 432 - Compatibility must be checked before any other operation is 433 performed. 435 - All dependency manifests should be present before any payload is 436 fetched. 438 - In some applications, payloads must be fetched and validated prior 439 to installation. 441 There are several fundamental assumptions that inform the model of 442 the Boot Procedure workflow: 444 - Compatibility must be checked before any other operation is 445 performed. 447 - All dependencies and payloads must be validated prior to loading. 449 - All loaded images must be validated prior to execution. 451 Based on these assumptions, the manifest is structured to work with a 452 pull parser, where each section of the manifest is used in sequence. 453 The expected workflow for a Recipient installing an update can be 454 broken down into five steps: 456 1. Verify the signature of the manifest. 458 2. Verify the applicability of the manifest. 460 3. Resolve dependencies. 462 4. Fetch payload(s). 464 5. Install payload(s). 466 When installation is complete, similar information can be used for 467 validating and running images in a further three steps: 469 1. Verify image(s). 471 2. Load image(s). 473 3. Run image(s). 475 If verification and running is implemented in a bootloader, then the 476 bootloader MUST also verify the signature of the manifest and the 477 applicability of the manifest in order to implement secure boot 478 workflows. The bootloader may add its own authentication, e.g. a 479 MAC, to the manifest in order to prevent further verifications. 481 When multiple manifests are used for an update, each manifest's steps 482 occur in a lockstep fashion; all manifests have dependency resolution 483 performed before any manifest performs a payload fetch, etc. 485 5. Metadata Structure Overview 487 This section provides a high level overview of the manifest 488 structure. The full description of the manifest structure is in 489 Section 8.6 491 The manifest is structured from several key components: 493 1. The Envelope (see Section 5.1) contains Delegation Chains, the 494 Authentication Block, the Manifest, any Severable Elements, and 495 any Integrated Payloads or Dependencies. 497 2. Delegation Chains (see Section 5.2) allow a Recipient to work 498 from one of its Trust Anchors to an authority of the 499 Authentication Block. 501 3. The Authentication Block (see Section 5.3) contains a list of 502 signatures or MACs of the manifest.. 504 4. The Manifest (see Section 5.4) contains all critical, non- 505 severable metadata that the Recipient requires. It is further 506 broken down into: 508 1. Critical metadata, such as sequence number. 510 2. Common metadata, including lists of dependencies and affected 511 components. 513 3. Command sequences, directing the Recipient how to install and 514 use the payload(s). 516 4. Integrity check values for severable fields. 518 5. Severable fields (see Section 5.5). 520 6. Integrated dependencies (see Section 5.6). 522 7. Integrated payloads (see Section 5.6). 524 The diagram below illustrates the hierarchy of the Envelope. 526 +-------------------------+ 527 | Envelope | 528 +-------------------------+ 529 | Delegation Chains | 530 | Authentication Block | 531 | Manifest ------------> +------------------------------+ 532 | Severable Elements | | Manifest | 533 | Human-Readable Text | +------------------------------+ 534 | COSWID | | Structure Version | 535 | Integrated Dependencies | | Sequence Number | 536 | Integrated Payloads | | Reference to Full Manifest | 537 +-------------------------+ +------ Common Structure | 538 | +---- Commands | 539 +-----------------------+ | | | Digests of Envelope Elements | 540 | Common Structure | <--+ | +------------------------------+ 541 +-----------------------+ | 542 | Dependencies | +-> +-----------------------+ 543 | Components IDs | | Commands | 544 | Common Commands ---------------> +-----------------------+ 545 +-----------------------+ | List of ( pairs of ( | 546 | * command code | 547 | * argument | 548 | )) | 549 +-----------------------+ 551 5.1. Envelope 553 The SUIT Envelope is a container that encloses Delegation Chains, the 554 Authentication Block, the Manifest, any Severable Elements, and any 555 integrated payloads or dependencies. The Envelope is used instead of 556 conventional cryptographic envelopes, such as COSE_Envelope because 557 it allows modular processing, severing of elements, and integrated 558 payloads in a way that would add substantial complexity with existing 559 solutions. See Appendix C.1 for a description of the reasoning for 560 this. 562 See Section 8.2 for more detail. 564 5.2. Delegation Chains 566 Delegation Chains allow a Recipient to validate intermediate Update 567 Authorities against long-term a Trust Anchor. These are lists of 568 CWTs, where the first in the list is signed by a Trust Anchor. 570 See Section 8.3 for more detail. 572 5.3. Authentication Block 574 The Authentication Block contains one or more COSE authentication 575 blocks. These blocks are one of: 577 - COSE_Sign_Tagged 579 - COSE_Sign1_Tagged 581 - COSE_Mac_Tagged 583 - COSE_Mac0_Tagged 585 The payload element in each of these COSE elements is a SUIT_Digest 586 Section 10. 588 See Section 8.4 for more detail. 590 5.4. Manifest 592 The Manifest contains most metadata about one or more images. The 593 Manifest is divided into Critical Metadata, Common Metadata, Command 594 Sequences, and Integrity Check Values. 596 See Section 8.6 for more detail. 598 5.4.1. Critical Metadata 600 Some metadata needs to be accessed before the manifest is processed. 601 This metadata can be used to determine which the newest manifest is 602 and whether the structure version is supported. It also MAY provide 603 a URI for obtaining a canonical copy of the manifest and Envelope. 605 See Section 8.6.1, Section 8.6.2, Section 8.6.3 for more detail. 607 5.4.2. Common 609 Some metadata is used repeatedly and in more than one command 610 sequence. In order to reduce the size of the manifest, this metadata 611 is collected into the Common section. Common is composed of three 612 parts: a list of dependencies, a list of components referenced by the 613 manifest, and a command sequence to execute prior to each other 614 command sequence. The common command sequence is typically used to 615 set commonly used values and perform compatibility checks. The 616 common command sequence MUST NOT have any side-effects outside of 617 setting parameter values. 619 See Section 8.7.2, Section 8.7.2.1 for more detail. 621 5.4.3. Command Sequences 623 Command sequences provide the instructions that a Recipient requires 624 in order to install or use an image. These sequences tell a device 625 to set parameter values, test system parameters, copy data from one 626 place to another, transform data, digest data, and run code. 628 Command sequences are broken up into three groups: Common Command 629 Sequence (see Section 5.4.2), update commands, and secure boot 630 commands. 632 Update Command Sequences are: Dependency Resolution, Payload Fetch, 633 and Payload Installation. An Update Procedure is the complete set of 634 each Update Command Sequence, each preceded by the Common Command 635 Sequence. 637 Boot Command Sequences are: System Validation, Image Loading, and 638 Image Invocation. A Boot Procedure is the complete set of each Boot 639 Command Sequence, each preceded by the Common Command Sequence. 641 Command Sequences are grouped into these sets to ensure that there is 642 common coordination between dependencies and dependents on when to 643 execute each command. 645 See Section 8.7.3 for more detail. 647 5.4.4. Integrity Check Values 649 To enable Section 5.5, there needs to be a mechanism to verify 650 integrity of any metadata outside the manifest. Integrity Check 651 Values are used to verify the integrity of metadata that is not 652 contained in the manifest. This MAY include Severable Command 653 Sequences, CoSWID, or Text data. Integrated Dependencies and 654 Integrated Payloads are integrity-checked using Command Sequences, so 655 they do not have Integrity Check Values present in the Manifest. 657 See Section 8.7.8 for more detail. 659 5.4.5. Human-Readable Text 661 Text is typically a Severable Element (Section 5.5). It contains all 662 the text that describes the update. Because text is explicitly for 663 human consumption, it is all grouped together so that it can be 664 Severed easily. The text section has space both for describing the 665 manifest as a whole and for describing each individual component. 667 See Section 8.6.4 for more detail. 669 5.5. Severable Elements 671 Severable Elements are elements of the Envelope (Section 5.1) that 672 have Integrity Check Values (Section 5.4.4) in the Manifest 673 (Section 5.4). 675 Because of this organisation, these elements can be discarded or 676 "Severed" from the Envelope without changing the signature of the 677 Manifest. This allows savings based on the size of the Envelope in 678 several scenarios, for example: 680 - A management system Severs the Text and CoSWID sections before 681 sending an Envelope to a constrained Recipient, which saves 682 Recipient bandwidth. 684 - A Recipient Severs the Installation section after installing the 685 Update, which saves storage space. 687 See Section 8.8 for more detail. 689 5.6. Integrated Dependencies and Payloads 691 In some cases, it is beneficial to include a dependency or a payload 692 in the Envelope of a manifest. For example: 694 - When an update is delivered via a comparatively unconstrained 695 medium, such as a removable mass storage device, it may be 696 beneficial to bundle updates into single files. 698 - When a manifest requires encryption, it must be referenced as a 699 dependency, so a trivial manifest may be used to enclose the 700 encrypted manifest. The encrypted manifest may be contained in 701 the dependent manifest's envelope. 703 - When a manifest transports a small payload, such as an encrypted 704 key, that payload may be placed in the manifest's envelope. 706 See Section 7.8.1, Section 8.5 for more detail. 708 6. Interpreter Behavior 710 This section describes the behavior of the manifest interpreter and 711 focuses primarily on interpreting commands in the manifest. However, 712 there are several other important behaviors of the interpreter: 713 encoding version detection, rollback protection, and authenticity 714 verification are chief among these. 716 6.1. Interpreter Setup 718 Prior to executing any command sequence, the interpreter or its host 719 application MUST inspect the manifest version field and fail when it 720 encounters an unsupported encoding version. Next, the interpreter or 721 its host application MUST extract the manifest sequence number and 722 perform a rollback check using this sequence number. The exact logic 723 of rollback protection may vary by application, but it has the 724 following properties: 726 - Whenever the interpreter can choose between several manifests, it 727 MUST select the latest valid, authentic manifest. 729 - If the latest valid, authentic manifest fails, it MAY select the 730 next latest valid, authentic manifest. 732 Here, valid means that a manifest has a supported encoding version 733 and it has not been excluded for other reasons. Reasons for 734 excluding typically involve first executing the manifest and may 735 include: 737 - Test failed (e.g. Vendor ID/Class ID). 739 - Unsupported command encountered. 741 - Unsupported parameter encountered. 743 - Unsupported component ID encountered. 745 - Payload not available. 747 - Dependency not available. 749 - Application crashed when executed. 751 - Watchdog timeout occurred. 753 - Dependency or Payload verification failed. 755 - Missing component from a set. 757 These failure reasons MAY be combined with retry mechanisms prior to 758 marking a manifest as invalid. 760 Following these initial tests, the interpreter clears all parameter 761 storage. This ensures that the interpreter begins without any leaked 762 data. 764 6.2. Required Checks 766 The RECOMMENDED process is to verify the signature of the manifest 767 prior to parsing/executing any section of the manifest. This guards 768 the parser against arbitrary input by unauthenticated third parties, 769 but it costs extra energy when a Recipient receives an incompatible 770 manifest. 772 When validating authenticity of manifests, the interpreter MAY use an 773 ACL (see Section 9) to determine the extent of the rights conferred 774 by that authenticity. Where a device supports only one level of 775 access, it MAY choose to skip signature verification of dependencies, 776 since they are referenced by digest. Where a device supports more 777 than one trusted party, it MAY choose to defer the verification of 778 signatures of dependencies until the list of affected components is 779 known so that it can skip redundant signature verifications. For 780 example, a dependency signed by the same author as the dependent does 781 not require a signature verification. Similarly, if the signer of 782 the dependent has full rights to the device, according to the ACL, 783 then no signature verification is necessary on the dependency. 785 Once a valid, authentic manifest has been selected, the interpreter 786 MUST examine the component list and verify that its maximum number of 787 components is not exceeded and that each listed component ID is 788 supported. 790 For each listed component, the interpreter MUST provide storage for 791 the supported parameters. If the interpreter does not have 792 sufficient temporary storage to process the parameters for all 793 components, it MAY process components serially for each command 794 sequence. See Section 6.5 for more details. 796 The interpreter SHOULD check that the common section contains at 797 least one vendor ID check and at least one class ID check. 799 If the manifest contains more than one component, each command 800 sequence MUST begin with a Set Current Component command. 802 If a dependency is specified, then the interpreter MUST perform the 803 following checks: 805 1. At the beginning of each section in the dependent: all previous 806 sections of each dependency have been executed. 808 2. At the end of each section in the dependent: The corresponding 809 section in each dependency has been executed. 811 If the interpreter does not support dependencies and a manifest 812 specifies a dependency, then the interpreter MUST reject the 813 manifest. 815 If a Recipient supports groups of interdependent components (a 816 Component Set), then it SHOULD require that all Components in the 817 Component Set are specified by one manifest and its dependencies. 818 This manifest is called the Root Manifest. 820 6.2.1. Minimizing Signature Verifications 822 Signature verification can be energy and time expensive on a 823 constrained device. MAC verification is typically unaffected by 824 these concerns. A Recipient MAY choose to parse and execute only the 825 SUIT_Common section of the manifest prior to signature verification, 826 if all of the below apply: 828 - The Authentication Block contains a COSE_Sign_Tagged or 829 COSE_Sign1_Tagged 831 - The Recipient can receive many incompatible or inapplicable 832 manifests, and 834 - The Recipient has a power budget that makes signature verification 835 undesirable 837 The guidelines in Creating Manifests (Section 7) require that the 838 common section contains the applicability checks, so this section is 839 sufficient for applicability verification. The parser MUST restrict 840 acceptable commands to: Conditions, Override Parameters, Set 841 Parameters, Try-Each, and Run Sequence ONLY. The manifest parser 842 MUST NOT execute any command with side-effects outside the parser 843 (for example, Run, Copy, Swap, or Fetch commands) prior to 844 authentication and any such command MUST Abort. The Common Sequence 845 MUST be executed again in its entirety after authenticity validation. 847 When executing Common prior to authenticity validation, the Manifest 848 Processor MUST evaluate the integrity of the manifest using the 849 SUIT_Digest present in the authentication block. 851 Alternatively, a Recipient MAY rely on network infrastructure to 852 filter inapplicable manifests. 854 6.3. Interpreter Fundamental Properties 856 The interpreter has a small set of design goals: 858 1. Executing an update MUST either result in an error, or a 859 verifiably correct system state. 861 2. Executing a secure boot MUST either result in an error, or a 862 booted system. 864 3. Executing the same manifest on multiple Recipients MUST result in 865 the same system state. 867 NOTE: when using A/B images, the manifest functions as two (or more) 868 logical manifests, each of which applies to a system in a particular 869 starting state. With that provision, design goal 3 holds. 871 6.4. Abstract Machine Description 873 The heart of the manifest is the list of commands, which are 874 processed by an interpreter. This interpreter can be modeled as a 875 simple abstract machine. This machine consists of several data 876 storage locations that are modified by commands. 878 There are two types of commands, namely those that modify state 879 (directives) and those that perform tests (conditions). Parameters 880 are used as the inputs to commands. Some directives offer control 881 flow operations. Directives target a specific component or 882 dependency. A dependency is another SUIT_Envelope that describes 883 additional components. Dependencies are identified by digest, but 884 referenced in commands by Dependency Index, the index into the array 885 of Dependencies. A component is a unit of code or data that can be 886 targeted by an update. Components are identified by Component 887 Identifiers, i.e. arrays of binary strings, but referenced in 888 commands by Component Index, the index into the array of Component 889 Identifiers. 891 Conditions MUST NOT have any side-effects other than informing the 892 interpreter of success or failure. The Interpreter does not Abort if 893 the Soft Failure flag is set when a Condition reports failure. 895 Directives MAY have side-effects in the parameter table, the 896 interpreter state, or the current component. The Interpreter MUST 897 Abort if a Directive reports failure regardless of the Soft Failure 898 flag. 900 The following table describes the behavior of each command. "params" 901 represents the parameters for the current component or dependency. 902 Most commands operate on either a component or a dependency. Setting 903 the Component Index clears the Dependency Index. Setting the 904 Dependency Index clears the Component Index. 906 +-------------------+-----------------------------------------------+ 907 | Command Name | Semantic of the Operation | 908 +-------------------+-----------------------------------------------+ 909 | Check Vendor | assert(binary-match(current, | 910 | Identifier | current.params[vendor-id])) | 911 | | | 912 | Check Class | assert(binary-match(current, | 913 | Identifier | current.params[class-id])) | 914 | | | 915 | Verify Image | assert(binary-match(digest(current), | 916 | | current.params[digest])) | 917 | | | 918 | Set Component | current := components[arg] | 919 | Index | | 920 | | | 921 | Override | current.params[k] := v for k,v in arg | 922 | Parameters | | 923 | | | 924 | Set Dependency | current := dependencies[arg] | 925 | Index | | 926 | | | 927 | Set Parameters | current.params[k] := v if not k in params for | 928 | | k,v in arg | 929 | | | 930 | Process | exec(current[common]); exec(current[current- | 931 | Dependency | segment]) | 932 | | | 933 | Run | run(current) | 934 | | | 935 | Fetch | store(current, fetch(current.params[uri])) | 936 | | | 937 | Use Before | assert(now() < arg) | 938 | | | 939 | Check Component | assert(offsetof(current) == arg) | 940 | Offset | | 941 | | | 942 | Check Device | assert(binary-match(current, | 943 | Identifier | current.params[device-id])) | 944 | | | 945 | Check Image Not | assert(not binary-match(digest(current), | 946 | Match | current.params[digest])) | 947 | | | 948 | Check Minimum | assert(battery >= arg) | 949 | Battery | | 950 | | | 951 | Check Update | assert(isAuthorized()) | 952 | Authorized | | 953 | | | 954 | Check Version | assert(version_check(current, arg)) | 955 | | | 956 | Abort | assert(0) | 957 | | | 958 | Try Each | break if exec(seq) is not error for-each seq | 959 | | in arg | 960 | | | 961 | Copy | store(current, current.params[src-component]) | 962 | | | 963 | Swap | swap(current, current.params[src-component]) | 964 | | | 965 | Wait For Event | until event(arg), wait | 966 | | | 967 | Run Sequence | exec(arg) | 968 | | | 969 | Run with | run(current, arg) | 970 | Arguments | | 971 +-------------------+-----------------------------------------------+ 973 6.5. Serialized Processing Interpreter 975 In highly constrained devices, where storage for parameters is 976 limited, the manifest processor MAY handle one component at a time, 977 traversing the manifest tree once for each listed component. In this 978 mode, the interpreter ignores any commands executed while the 979 component index is not the current component. This reduces the 980 overall volatile storage required to process the update so that the 981 only limit on number of components is the size of the manifest. 982 However, this approach requires additional processing power. 984 In order to operate in this mode, the manifest processor loops on 985 each section for every supported component, simply ignoring commands 986 when the current component is not selected. 988 6.6. Parallel Processing Interpreter 990 Advanced Recipients MAY make use of the Strict Order parameter and 991 enable parallel processing of some Command Sequences, or it may 992 reorder some Command Sequences. To perform parallel processing, once 993 the Strict Order parameter is set to False, the Recipient may fork a 994 process for each command until the Strict Order parameter is returned 995 to True or the Command Sequence ends. Then, it joins all forked 996 processes before continuing processing of commands. To perform out- 997 of-order processing, a similar approach is used, except the Recipient 998 consumes all commands after the Strict Order parameter is set to 999 False, then it sorts these commands into its preferred order, invokes 1000 them all, then continues processing. 1002 Under each of these scenarios the parallel processing must halt: 1004 - Set Parameters. 1006 - Override Parameters. 1008 - Set Strict Order = True. 1010 - Set Dependency Index. 1012 - Set Component Index. 1014 To perform more useful parallel operations, sequences of commands may 1015 be collected in a suit-directive-run-sequence. Then, each of these 1016 sequences may be run in parallel. Each sequence defaults to Strict 1017 Order = True. To isolate each sequence from each other sequence, 1018 each sequence MUST begin with a Set Component Index directive. The 1019 interpreter MUST track each Set Component Index directive, and cause 1020 an Abort if more than one Set Component Index directive targets the 1021 same Component Index. When Strict Order = False, each suit- 1022 directive-run-sequence MUST begin with a Set Component Index 1023 directive. Any further Set Component Index directives MUST cause an 1024 Abort. This allows the interpreter that forks suit-directive-run- 1025 sequence processes to check that the first element is correct, then 1026 fork a process to handle the remainder of the sequence. 1028 6.7. Processing Dependencies 1030 As described in Section 6.2, each manifest must invoke each of its 1031 dependencies sections from the corresponding section of the 1032 dependent. Any changes made to parameters by the dependency persist 1033 in the dependent. 1035 When a Process Dependency command is encountered, the interpreter 1036 loads the dependency identified by the Current Dependency Index. The 1037 interpreter first executes the common-sequence section of the 1038 identified dependency, then it executes the section of the dependency 1039 that corresponds to the currently executing section of the dependent. 1041 The interpreter also performs the checks described in Section 6.2 to 1042 ensure that the dependent is processing the dependency correctly. 1044 6.8. Multiple Manifest Processors 1046 When a system has multiple security domains they MAY require 1047 independent verification of authenticity or security policies. 1048 Security domains may be divided by separation technology such as Arm 1049 TrustZone, or Intel SGX. Security domains may also be divided into 1050 separate processors and memory spaces, with a communication interface 1051 between them. 1053 For example, an application processor may have an attached 1054 communications module that contains a processor. The communications 1055 module may require metadata signed by a specific Trust Authority for 1056 regulatory approval. This may be a different Trust Authority than 1057 the application processor. 1059 When there are two or more security domains, a manifest processor MAY 1060 be required in each. The first manifest processor is the normal 1061 manifest processor as described for the Recipient in Abstract 1062 Machine. The second manifest processor only executes sections when 1063 the first manifest processor requests it. An API interface is 1064 provided from the second manifest processor to the first. This 1065 allows the first manifest processor to request a limited set of 1066 operations from the second. These operations are limited to: setting 1067 parameters, inserting an Envelope, invoking a Manifest Command 1068 Sequence. The second manifest processor declares a prefix to the 1069 first, which tells the first manifest processor when it should 1070 delegate to the second. These rules are enforced by underlying 1071 separation of privilege infrastructure, such as TEEs, or physical 1072 separation. 1074 When the first manifest processor encounters a dependency prefix, 1075 that informs the first manifest processor that it should provide the 1076 second manifest processor with the corresponding dependency Envelope. 1077 This is done when the dependency is fetched. The second manifest 1078 processor immediately verifies any authentication information in the 1079 dependency Envelope. When a parameter is set for any component that 1080 matches the prefix, this parameter setting is passed to the second 1081 manifest processor via an API. As the first manifest processor works 1082 through the Procedure (set of command sequences) it is executing, 1083 each time it sees a Process Dependency command that is associated 1084 with the prefix declared by the second manifest processor, it uses 1085 the API to ask the second manifest processor to invoke that 1086 dependency section instead. 1088 7. Creating Manifests 1090 Manifests are created using tools for constructing COSE structures, 1091 calculating cryptographic values and compiling desired system state 1092 into a sequence of operations required to achieve that state. The 1093 process of constructing COSE structures and the calculation of 1094 cryptographic values is covered in [RFC8152]. 1096 Compiling desired system state into a sequence of operations can be 1097 accomplished in many ways. Several templates are provided below to 1098 cover common use-cases. These templates can be combined to produce 1099 more complex behavior. 1101 NOTE: On systems that support only a single component, Set Current 1102 Component has no effect and can be omitted. 1104 NOTE: *A digest MUST always be set using Override Parameters, since 1105 this prevents a less-privileged dependent from replacing the digest.* 1107 7.1. Compatibility Check Template 1109 The compatibility check ensures that Recipients only install 1110 compatible images. In this template all information is contained in 1111 the common block and the following sequence of operations are used: 1113 - Set Component Index directive (see Section 8.7.7.1) 1115 - Set Parameters directive (see Section 8.7.7.6) for Vendor ID and 1116 Class ID (see Section 8.7.5) 1118 - Check Vendor Identifier condition (see Section 8.7.5.1) 1120 - Check Class Identifier condication (see Section 8.7.5.1) 1122 7.2. Secure Boot Template 1124 This template performs a secure boot operation. 1126 The following operations are placed into the common block: 1128 - Set Component Index directive (see Section 8.7.7.1) 1130 - Override Parameters directive (see Section 8.7.7.7) for Image 1131 Digest and Image Size (see Section 8.7.5) 1133 Then, the run block contains the following operations: 1135 - Set Component Index directive (see Section 8.7.7.1) 1137 - Check Image Match condition (see Section 8.7.6.2) 1139 - Run directive (see Section 8.7.7.13) 1141 According to Section 6.4, the Run directive applies to the component 1142 referenced by the current Component Index. Hence, the Set Component 1143 Index directive has to be used to target a specific component. 1145 7.3. Firmware Download Template 1147 This template triggers the download of firmware. 1149 The following operations are placed into the common block: 1151 - Set Component Index directive (see Section 8.7.7.1) 1153 - Override Parameters directive (see Section 8.7.7.7) for Image 1154 Digest and Image Size (see Section 8.7.5) 1156 Then, the install block contains the following operations: 1158 - Set Component Index directive (see Section 8.7.7.1) 1160 - Set Parameters directive (see Section 8.7.7.6) for URI (see 1161 Section 8.7.5.12) 1163 - Fetch directive (see Section 8.7.7.8) 1165 - Check Image Match condition (see Section 8.7.6.2) 1167 The Fetch directive needs the URI parameter to be set to determine 1168 where the image is retrieved from. Additionally, the destination of 1169 where the component shall be stored has to be configured. The URI is 1170 configured via the Set Parameters directive while the destination is 1171 configured via the Set Component Index directive. 1173 7.4. Install Template 1175 This template modifies the Firmware Download template and adds an 1176 additional sequence. The Firmware Download operations are moved from 1177 the Payload Install sequence to the Payload Fetch sequence. 1179 Then, the Install sequence contains the following operations: 1181 - Set Component Index directive (see Section 8.7.7.1) 1183 - Set Parameters directive (see Section 8.7.7.6) for Source 1184 Component (see Section 8.7.5.13) 1186 - Copy directive (see Section 8.7.7.10) 1188 - Check Image Match condition (see Section 8.7.6.2) 1190 7.5. Integrated Payload Template 1192 This template triggers the installation of a payload included in the 1193 manifest envelope. It is identical to Section 7.3 except that it 1194 places an added restriction on the URI passed to the Set Parameters 1195 directive. 1197 An implementor MAY choose to place a payload in the envelope of a 1198 manifest. The payload envelope key MAY be a positive or negative 1199 integer. The payload envelope key MUST NOT be a value between 0 and 1200 24 and it MUST NOT be used by any other envelope element in the 1201 manifest. The payload MUST be serialized in a bstr element. 1203 The URI for a payload enclosed in this way MUST be expressed as a 1204 fragment-only reference, as defined in [RFC3986], Section 4.4. The 1205 fragment identifier is the stringified envelope key of the payload. 1206 For example, an envelope that contains a payload a key 42 would use a 1207 URI "#42", key -73 would use a URI "#-73". 1209 7.6. Load from Nonvolatile Storage Template 1211 This directive loads an firmware image from external storage. 1213 The following operations are placed into the load block: 1215 - Set Component Index directive (see Section 8.7.7.1) 1217 - Set Parameters directive (see Section 8.7.7.6) for Component Index 1218 (see Section 8.7.5) 1220 - Copy directive (see Section 8.7.7.10) 1222 As outlined in Section 6.4, the Copy directive needs a source and a 1223 destination to be configured. The source is configured via Component 1224 Index (with the Set Parameters directive) and the destination is 1225 configured via the Set Component Index directive. 1227 7.7. Load & Decompress from Nonvolatile Storage Template 1229 The following operations are placed into the load block: 1231 - Set Component Index directive (see Section 8.7.7.1) 1233 - Set Parameters directive (see Section 8.7.7.6) for Source 1234 Component Index and Compression Info (see Section 8.7.5) 1236 - Copy directive (see Section 8.7.7.10) 1237 This template is similar to Section 7.6 but additionally performs 1238 decompression. Hence, the only difference is in setting the 1239 Compression Info parameter. 1241 7.8. Dependency Template 1243 The following operations are placed into the dependency resolution 1244 block: 1246 - Set Dependency Index directive (see Section 8.7.7.2) 1248 - Set Parameters directive (see Section 8.7.7.6) for URI (see 1249 Section 8.7.5) 1251 - Fetch directive (see Section 8.7.7.8) 1253 - Check Image Match condition (see Section 8.7.6.2) 1255 - Process Dependency directive (see Section 8.7.7.5) 1257 Then, the validate block contains the following operations: 1259 - Set Dependency Index directive (see Section 8.7.7.2) 1261 - Check Image Match condition (see Section 8.7.6.2) 1263 - Process Dependency directive (see Section 8.7.7.5) 1265 NOTE: Any changes made to parameters in a dependency persist in the 1266 dependent. 1268 7.8.1. Composite Manifests 1270 An implementor MAY choose to place a dependency's envelope in the 1271 envelope of its dependent. The dependent envelope key for the 1272 dependency envelope MUST NOT be a value between 0 and 24 and it MUST 1273 NOT be used by any other envelope element in the dependent manifest. 1275 The URI for a dependency enclosed in this way MUST be expressed as a 1276 fragment-only reference, as defined in [RFC3986], Section 4.4. The 1277 fragment identifier is the stringified envelope key of the 1278 dependency. For example, an envelope that contains a dependency at 1279 key 42 would use a URI "#42", key -73 would use a URI "#-73". 1281 7.9. Encrypted Manifest Template 1283 To use an encrypted manifest, create a plaintext dependent, and add 1284 the encrypted manifest as a dependency. The dependent can include 1285 very little information. 1287 The following operations are placed into the dependency resolution 1288 block: 1290 - Set Dependency Index directive (see Section 8.7.7.2) 1292 - Set Parameters directive (see Section 8.7.7.6) for 1294 o URI (see Section 8.7.5) 1296 o Encryption Info (see Section 8.7.5) 1298 - Fetch directive (see Section 8.7.7.8) 1300 - Check Image Match condition (see Section 8.7.6.2) 1302 - Process Dependency directive (see Section 8.7.7.5) 1304 Then, the validate block contains the following operations: 1306 - Set Dependency Index directive (see Section 8.7.7.2) 1308 - Check Image Match condition (see Section 8.7.6.2) 1310 - Process Dependency directive (see Section 8.7.7.5) 1312 A plaintext manifest and its encrypted dependency may also form a 1313 composite manifest (Section 7.8.1). 1315 7.10. A/B Image Template 1317 The following operations are placed in the common block: 1319 - Set Component Index directive (see Section 8.7.7.1) 1321 - Try Each 1323 o First Sequence: 1325 * Override Parameters directive (see Section 8.7.7.7, 1326 Section 8.7.5) for Offset A 1328 * Check Offset Condition (see Section 8.7.6.5) 1329 * Override Parameters directive (see Section 8.7.7.7) for 1330 Image Digest A and Image Size A (see Section 8.7.5) 1332 o Second Sequence: 1334 * Override Parameters directive (see Section 8.7.7.7, 1335 Section 8.7.5) for Offset B 1337 * Check Offset Condition (see Section 8.7.6.5) 1339 * Override Parameters directive (see Section 8.7.7.7) for 1340 Image Digest B and Image Size B (see Section 8.7.5) 1342 The following operations are placed in the fetch block or install 1343 block 1345 - Set Component Index directive (see Section 8.7.7.1) 1347 - Try Each 1349 o First Sequence: 1351 * Override Parameters directive (see Section 8.7.7.7, 1352 Section 8.7.5) for Offset A 1354 * Check Offset Condition (see Section 8.7.6.5) 1356 * Set Parameters directive (see Section 8.7.7.7) for URI A 1357 (see Section 8.7.5) 1359 o Second Sequence: 1361 * Override Parameters directive (see Section 8.7.7.7, 1362 Section 8.7.5) for Offset B 1364 * Check Offset Condition (see Section 8.7.6.5) 1366 * Set Parameters directive (see Section 8.7.7.7) for URI B 1367 (see Section 8.7.5) 1369 - Fetch 1371 8. Metadata Structure 1373 The metadata for SUIT updates is composed of several primary 1374 constituent parts: the Envelope, Delegation Chains, Authentication 1375 Information, Manifest, and Severable Elements. 1377 For a diagram of the metadata structure, see Section 5. 1379 8.1. Encoding Considerations 1381 The map indices in the envelope encoding are reset to 1 for each map 1382 within the structure. This is to keep the indices as small as 1383 possible. The goal is to keep the index objects to single bytes 1384 (CBOR positive integers 1-23). 1386 Wherever enumerations are used, they are started at 1. This allows 1387 detection of several common software errors that are caused by 1388 uninitialised variables. Positive numbers in enumerations are 1389 reserved for IANA registration. Negative numbers are used to 1390 identify application-specific implementations. 1392 All elements of the envelope must be wrapped in a bstr to minimize 1393 the complexity of the code that evaluates the cryptographic integrity 1394 of the element and to ensure correct serialization for integrity and 1395 authenticity checks. 1397 8.2. Envelope 1399 The Envelope contains each of the other primary constituent parts of 1400 the SUIT metadata. It allows for modular processing of the manifest 1401 by ordering components in the expected order of processing. 1403 The Envelope is encoded as a CBOR Map. Each element of the Envelope 1404 is enclosed in a bstr, which allows computation of a message digest 1405 against known bounds. 1407 8.3. Delegation Chains 1409 The suit-delegation field MAY carry one or more CBOR Web Tokens 1410 (CWTs) [RFC8392], with [RFC8747] cnf claims. They can be used to 1411 perform enhanced authorization decisions. The CWTs are arranged into 1412 a list of lists. Each list starts with CWT authorized by a Trust 1413 Anchor, and finishes with a key used to authenticate the Manifest 1414 (see Section 8.4). This allows an Update Authority to delegate from 1415 a long term Trust Anchor, down through intermediaries, to a delegate 1416 without any out-of-band updates Trust Anchors. 1418 A Recipient MAY choose to cache intermediaries and/or delegates. If 1419 an Update Distributor knows that a targeted Recipient has cached some 1420 intermediaries or delegates, it MAY choose to strip any cached 1421 intermediaries or delegates from the Delegation Chains in order to 1422 reduce bandwidth and energy. 1424 8.4. Authenticated Manifests 1426 The suit-authentication-wrapper contains a list of one or more 1427 cryptographic authentication wrappers for the Manifest. These are 1428 implemented as COSE_Mac_Tagged or COSE_Sign_Tagged blocks. Each of 1429 these blocks contains a SUIT_Digest of the Manifest. This enables 1430 modular processing of the manifest. The COSE_Mac_Tagged and 1431 COSE_Sign_Tagged blocks are described in RFC 8152 [RFC8152]. The 1432 suit-authentication-wrapper MUST come before any element in the 1433 SUIT_Envelope, except for the OPTIONAL suit-delegation, regardless of 1434 canonical encoding of CBOR. All validators MUST reject any 1435 SUIT_Envelope that begins with any element other than a suit- 1436 authentication-wrapper or suit-delegation. 1438 A SUIT_Envelope that has not had authentication information added 1439 MUST still contain the suit-authentication-wrapper element, but the 1440 content MUST be an empty list. 1442 8.5. Encrypted Manifests 1444 To use an encrypted manifest, it must be a dependency of a plaintext 1445 manifest. This allows fine-grained control of what information is 1446 accessible to intermediate systems for the purposes of management, 1447 while still preserving the confidentiality of the manifest contents. 1448 This also means that a Recipient can process an encrypted manifest in 1449 the same way as an encrypted payload, allowing code reuse. 1451 A template for using an encrypted manifest is covered in Encrypted 1452 Manifest Template (Section 7.9). 1454 8.6. Manifest 1456 The manifest contains: 1458 - a version number (see Section 8.6.1) 1460 - a sequence number (see Section 8.6.2) 1462 - a reference URI (see Section 8.6.3) 1464 - a common structure with information that is shared between command 1465 sequences (see Section 8.7.2) 1467 - one or more lists of commands that the Recipient should perform 1468 (see Section 8.7.3) 1470 - a reference to the full manifest (see Section 8.6.3) 1471 - human-readable text describing the manifest found in the 1472 SUIT_Envelope (see Section 8.6.4) 1474 - a Concise Software Identifier found in the SUIT_Envelope (see 1475 Section 8.7.1) 1477 The CoSWID, Text section, or any Command Sequence of the Update 1478 Procedure (Dependency Resolution, Image Fetch, Image Installation) 1479 can be either a CBOR structure or a SUIT_Digest. In each of these 1480 cases, the SUIT_Digest provides for a severable field. Severable 1481 fields are RECOMMENDED to implement. In particular, the human- 1482 readable text SHOULD be severable, since most useful text elements 1483 occupy more space than a SUIT_Digest, but are not needed by the 1484 Recipient. Because SUIT_Digest is a CBOR Array and each severable 1485 element is a CBOR bstr, it is straight-forward for a Recipient to 1486 determine whether an element has been severed. The key used for a 1487 severable element is the same in the SUIT_Manifest and in the 1488 SUIT_Envelope so that a Recipient can easily identify the correct 1489 data in the envelope. See Section 8.7.8 for more detail. 1491 8.6.1. suit-manifest-version 1493 The suit-manifest-version indicates the version of serialization used 1494 to encode the manifest. Version 1 is the version described in this 1495 document. suit-manifest-version is REQUIRED to implement. 1497 8.6.2. suit-manifest-sequence-number 1499 The suit-manifest-sequence-number is a monotonically increasing anti- 1500 rollback counter. It also helps Recipients to determine which in a 1501 set of manifests is the "root" manifest in a given update. Each 1502 manifest MUST have a sequence number higher than each of its 1503 dependencies. Each Recipient MUST reject any manifest that has a 1504 sequence number lower than its current sequence number. It MAY be 1505 convenient to use a UTC timestamp in seconds as the sequence number. 1506 suit-manifest-sequence-number is REQUIRED to implement. 1508 8.6.3. suit-reference-uri 1510 suit-reference-uri is a text string that encodes a URI where a full 1511 version of this manifest can be found. This is convenient for 1512 allowing management systems to show the severed elements of a 1513 manifest when this URI is reported by a Recipient after installation. 1515 8.6.4. suit-text 1517 suit-text SHOULD be a severable element. suit-text is a map of pairs. 1518 It MAY contain two different types of pair: 1520 - integer => text mappings 1522 - SUIT_Component_Identifier => map mappings 1524 Each SUIT_Component_Identifier => map entry contains a map of integer 1525 => text values. All SUIT_Component_Identifiers present in suit-text 1526 MUST also be present in suit-common (Section 8.7.2) or the suit- 1527 common of a dependency. 1529 suit-text contains all the human-readable information that describes 1530 any and all parts of the manifest, its payload(s) and its 1531 resource(s). The text section is typically severable, allowing 1532 manifests to be distributed without the text, since end-nodes do not 1533 require text. The meaning of each field is described below. 1535 Each section MAY be present. If present, each section MUST be as 1536 described. Negative integer IDs are reserved for application- 1537 specific text values. 1539 The following table describes the text fields available in suit-text: 1541 +--------------------------------+----------------------------------+ 1542 | CDDL Structure | Description | 1543 +--------------------------------+----------------------------------+ 1544 | suit-text-manifest-description | Free text description of the | 1545 | | manifest | 1546 | | | 1547 | suit-text-update-description | Free text description of the | 1548 | | update | 1549 | | | 1550 | suit-text-manifest-json-source | The JSON-formatted document that | 1551 | | was used to create the manifest | 1552 | | | 1553 | suit-text-manifest-yaml-source | The yaml-formatted document that | 1554 | | was used to create the manifest | 1555 +--------------------------------+----------------------------------+ 1557 The following table describes the text fields available in each map 1558 identified by a SUIT_Component_Identifier. 1560 +---------------------------------+---------------------------------+ 1561 | CDDL Structure | Description | 1562 +---------------------------------+---------------------------------+ 1563 | suit-text-vendor-name | Free text vendor name | 1564 | | | 1565 | suit-text-model-name | Free text model name | 1566 | | | 1567 | suit-text-vendor-domain | The domain used to create the | 1568 | | vendor-id condition | 1569 | | | 1570 | suit-text-model-info | The information used to create | 1571 | | the class-id condition | 1572 | | | 1573 | suit-text-component-description | Free text description of each | 1574 | | component in the manifest | 1575 | | | 1576 | suit-text-component-version | A text version number | 1577 | | | 1578 | suit-text-version-required | A text expression of the | 1579 | | required version number | 1580 +---------------------------------+---------------------------------+ 1582 suit-text is OPTIONAL to implement. 1584 8.7. text-version-required 1586 suit-text-version-required is used to represent a version-based 1587 dependency on suit-parameter-version as described in Section 8.7.5.17 1588 and Section 8.7.6.8. To describe a version dependency, a Manifest 1589 Author should populate the suit-text map with a 1590 SUIT_Component_Identifier key for the dependency component, and place 1591 in the corresponding map a suit-text-version-required key with a text 1592 expression that is representative of the version constraints placed 1593 on the dependency. 1595 For example, to express a dependency on a component "['x', 'y']", 1596 where the version should be any v1.x later than v1.2.5, but not v2.0 1597 or above, the author would add the following structure to the suit- 1598 text element. Note that this text is in cbor-diag notation. 1600 " [h'78',h'79'] : { 7 : ">=1.2.5,<2" } " 1602 8.7.1. suit-coswid 1604 suit-coswid contains a Concise Software Identifier. This element 1605 SHOULD be made severable so that it can be discarded by the Recipient 1606 or an intermediary if it is not required by the Recipient. 1608 suit-coswid is OPTIONAL to implement. 1610 8.7.2. suit-common 1612 suit-common encodes all the information that is shared between each 1613 of the command sequences, including: suit-dependencies, suit- 1614 components, and suit-common-sequence. suit-common is REQUIRED to 1615 implement. 1617 suit-dependencies is a list of Section 8.7.2.1 blocks that specify 1618 manifests that must be present before the current manifest can be 1619 processed. suit-dependencies is OPTIONAL to implement. 1621 suit-components is a list of SUIT_Component_Identifier 1622 (Section 8.7.2.2) blocks that specify the component identifiers that 1623 will be affected by the content of the current manifest. suit- 1624 components is REQUIRED to implement; at least one manifest in a 1625 dependency tree MUST contain a suit-components block. 1627 suit-common-sequence is a SUIT_Command_Sequence to execute prior to 1628 executing any other command sequence. Typical actions in suit- 1629 common-sequence include setting expected Recipient identity and image 1630 digests when they are conditional (see Section 8.7.7.4 and 1631 Section 7.10 for more information on conditional sequences). suit- 1632 common-sequence is RECOMMENDED to implement. It is REQUIRED if the 1633 optimizations described in Section 6.2.1 will be used. Whenever a 1634 parameter or try-each is required by more than one Command Sequence, 1635 suit-common-sequence results in a smaller encoding. 1637 8.7.2.1. Dependencies 1639 SUIT_Dependency specifies a manifest that describes a dependency of 1640 the current manifest. The Manifest is identified, however the 1641 Recipient should expect an Envelope when it acquires the dependency. 1642 This is because the Manifest is the one invariant element of the 1643 Envelope, where other elements may change by countersigning, adding 1644 authentication blocks, or severing elements. 1646 The suit-dependency-digest specifies the dependency manifest uniquely 1647 by identifying a particular Manifest structure. This is identical to 1648 the digest that would be present as the payload of any suit- 1649 authentication-block in the dependency's Envelope. The digest is 1650 calculated over the Manifest structure instead of the COSE 1651 Sig_structure or Mac_structure. This is necessary to ensure that 1652 removing a signature from a manifest does not break dependencies due 1653 to missing signature elements. This is also necessary to support the 1654 trusted intermediary use case, where an intermediary re-signs the 1655 Manifest, removing the original signature, potentially with a 1656 different algorithm, or trading COSE_Sign for COSE_Mac. 1658 The suit-dependency-prefix element contains a 1659 SUIT_Component_Identifier (see Section 8.7.2.2). This specifies the 1660 scope at which the dependency operates. This allows the dependency 1661 to be forwarded on to a component that is capable of parsing its own 1662 manifests. It also allows one manifest to be deployed to multiple 1663 dependent Recipients without those Recipients needing consistent 1664 component hierarchy. This element is OPTIONAL. 1666 A dependency prefix can be used with a component identifier. This 1667 allows complex systems to understand where dependencies need to be 1668 applied. The dependency prefix can be used in one of two ways. The 1669 first simply prepends the prefix to all Component Identifiers in the 1670 dependency. 1672 A dependency prefix can also be used to indicate when a dependency 1673 manifest needs to be processed by a secondary manifest processor, as 1674 described in Section 6.8. 1676 8.7.2.2. SUIT_Component_Identifier 1678 A component is a unit of code or data that can be targeted by an 1679 update. To facilitate composite devices, components are identified 1680 by a list of CBOR byte strings, which allows construction of 1681 hierarchical component structures. A dependency MAY declare a prefix 1682 to the components defined in the dependency manifest. Components are 1683 identified by Component Identifiers, i.e. arrays of binary strings, 1684 but referenced in commands 1686 A Component Identifier can be trivial, such as the simple array 1687 [h'00']. It can also represent a filesystem path by encoding each 1688 segment of the path as an element in the list. For example, the path 1689 "/usr/bin/env" would encode to ['usr','bin','env']. 1691 This hierarchical construction allows a component identifier to 1692 identify any part of a complex, multi-component system. 1694 8.7.3. SUIT_Command_Sequence 1696 A SUIT_Command_Sequence defines a series of actions that the 1697 Recipient MUST take to accomplish a particular goal. These goals are 1698 defined in the manifest and include: 1700 1. Dependency Resolution: suit-dependency-resolution is a 1701 SUIT_Command_Sequence to execute in order to perform dependency 1702 resolution. Typical actions include configuring URIs of 1703 dependency manifests, fetching dependency manifests, and 1704 validating dependency manifests' contents. suit-dependency- 1705 resolution is REQUIRED to implement and to use when suit- 1706 dependencies is present. 1708 2. Payload Fetch: suit-payload-fetch is a SUIT_Command_Sequence to 1709 execute in order to obtain a payload. Some manifests may include 1710 these actions in the suit-install section instead if they operate 1711 in a streaming installation mode. This is particularly relevant 1712 for constrained devices without any temporary storage for staging 1713 the update. suit-payload-fetch is OPTIONAL to implement. 1715 3. Payload Installation: suit-install is a SUIT_Command_Sequence to 1716 execute in order to install a payload. Typical actions include 1717 verifying a payload stored in temporary storage, copying a staged 1718 payload from temporary storage, and unpacking a payload. suit- 1719 install is OPTIONAL to implement. 1721 4. Image Validation: suit-validate is a SUIT_Command_Sequence to 1722 execute in order to validate that the result of applying the 1723 update is correct. Typical actions involve image validation and 1724 manifest validation. suit-validate is REQUIRED to implement. If 1725 the manifest contains dependencies, one process-dependency 1726 invocation per dependency or one process-dependency invocation 1727 targeting all dependencies SHOULD be present in validate. 1729 5. Image Loading: suit-load is a SUIT_Command_Sequence to execute in 1730 order to prepare a payload for execution. Typical actions 1731 include copying an image from permanent storage into RAM, 1732 optionally including actions such as decryption or decompression. 1733 suit-load is OPTIONAL to implement. 1735 6. Run or Boot: suit-run is a SUIT_Command_Sequence to execute in 1736 order to run an image. suit-run typically contains a single 1737 instruction: either the "run" directive for the bootable manifest 1738 or the "process dependencies" directive for any dependents of the 1739 bootable manifest. suit-run is OPTIONAL to implement. Only one 1740 manifest in an update may contain the "run" directive. 1742 Goals 1,2,3 form the Update Procedure. Goals 4,5,6 form the Boot 1743 Procedure. 1745 Each Command Sequence follows exactly the same structure to ensure 1746 that the parser is as simple as possible. 1748 Lists of commands are constructed from two kinds of element: 1750 1. Conditions that MUST be true-any failure is treated as a failure 1751 of the update/load/boot 1753 2. Directives that MUST be executed. 1755 Each condition is a command code identifier, followed by a 1756 SUIT_Reporting_Policy (Section 8.7.4). 1758 Each directive is composed of: 1760 1. A command code identifier 1762 2. An argument block or a reporting policy 1764 Argument blocks are consumed only by flow-control directives: 1766 - Set Component/Dependency Index 1768 - Set/Override Parameters 1770 - Try Each 1772 - Run Sequence 1774 Reporting policies provide a hint to the manifest processor of 1775 whether or not to add the success or failure of a command to any 1776 report that it generates. 1778 Many conditions and directives apply to a given component, and these 1779 generally grouped together. Therefore, a special command to set the 1780 current component index is provided with a matching command to set 1781 the current dependency index. This index is a numeric index into the 1782 component ID tables defined at the beginning of the document. For 1783 the purpose of setting the index, the two component ID tables are 1784 considered to be concatenated together. 1786 To facilitate optional conditions, a special directive, 1787 Section 8.7.7.4, is provided. It runs several new lists of 1788 conditions/directives, one after another, that are contained as an 1789 argument to the directive. By default, it assumes that a failure of 1790 a condition should not indicate a failure of the update/boot, but a 1791 parameter is provided to override this behavior. See 1792 Section 8.7.5.22. 1794 8.7.4. Reporting Policy 1796 TODO: Records, bitfield 1798 To facilitate construction of Reports that describe the success, or 1799 failure of a given Procedure, each command is given a Reporting 1800 Policy. This is an integer bitfield that follows the command and 1801 indicates what the Recipient should do with the Record of executing 1802 the command. The options are summarized in the table below. 1804 +-----------------------------+-------------------------------------+ 1805 | Policy | Description | 1806 +-----------------------------+-------------------------------------+ 1807 | suit-send-record-on-success | Record when the command succeeds | 1808 | | | 1809 | suit-send-record-on-failure | Record when the command fails | 1810 | | | 1811 | suit-send-sysinfo-success | Add system information when the | 1812 | | command succeeds | 1813 | | | 1814 | suit-send-sysinfo-failure | Add system information when the | 1815 | | command fails | 1816 +-----------------------------+-------------------------------------+ 1818 Any or all of these policies may be enabled at once. 1820 SUIT does NOT REQUIRE a particular format of Records or Reports. 1821 SUIT only defines hints to the Reporting engine for which Records it 1822 should aggregate into the Report. 1824 An OPTIONAL Record format, SUIT_Record is defined in [full-cddl]. It 1825 is encoded as a map, with the following elements. 1827 +---------------------------------+---------------------------------+ 1828 | Element | Description | 1829 +---------------------------------+---------------------------------+ 1830 | suit-record-success | The boolean or integer success | 1831 | | or failure code of the command. | 1832 | | | 1833 | suit-record-component-id | The current component when the | 1834 | | record was generated. | 1835 | | | 1836 | suit-record-dependency-id | The current dependency digest | 1837 | | when the record was generated. | 1838 | | | 1839 | suit-record-command-sequence-id | The label of the Command | 1840 | | Sequence that was executing | 1841 | | when the record was generated. | 1842 | | | 1843 | suit-record-command-id | The label of the command that | 1844 | | was in progress when the record | 1845 | | was generated. | 1846 | | | 1847 | suit-record-params | The set of parameters that was | 1848 | | consumed by the current | 1849 | | command. | 1850 | | | 1851 | suit-record-actual | The value against which a suit- | 1852 | | condition compared a parameter. | 1853 +---------------------------------+---------------------------------+ 1855 In Secure Boot operations, the Reporting engine MAY aggregate the 1856 Records produced in a Procedure into the evidence used for an 1857 attestation report. 1859 8.7.5. SUIT_Parameters 1861 Many conditions and directives require additional information. That 1862 information is contained within parameters that can be set in a 1863 consistent way. This allows reduction of manifest size and 1864 replacement of parameters from one manifest to the next. 1866 Most parameters are scoped to a specific component. This means that 1867 setting a parameter for one component has no effect on the parameters 1868 of any other component. The only exceptions to this are two Manifest 1869 Processor parameters: Strict Order and Soft Failure. 1871 The defined manifest parameters are described below. 1873 +----------------+----------------------------------+---------------+ 1874 | Name | CDDL Structure | Reference | 1875 +----------------+----------------------------------+---------------+ 1876 | Vendor ID | suit-parameter-vendor-identifier | Section 8.7.5 | 1877 | | | .2 | 1878 | | | | 1879 | Class ID | suit-parameter-class-identifier | Section 8.7.5 | 1880 | | | .3 | 1881 | | | | 1882 | Image Digest | suit-parameter-image-digest | Section 8.7.5 | 1883 | | | .5 | 1884 | | | | 1885 | Image Size | suit-parameter-image-size | Section 8.7.5 | 1886 | | | .6 | 1887 | | | | 1888 | Use Before | suit-parameter-use-before | Section 8.7.5 | 1889 | | | .7 | 1890 | | | | 1891 | Component | suit-parameter-component-offset | Section 8.7.5 | 1892 | Offset | | .8 | 1893 | | | | 1894 | Encryption | suit-parameter-encryption-info | Section 8.7.5 | 1895 | Info | | .9 | 1896 | | | | 1897 | Compression | suit-parameter-compression-info | Section 8.7.5 | 1898 | Info | | .10 | 1899 | | | | 1900 | Unpack Info | suit-parameter-unpack-info | Section 8.7.5 | 1901 | | | .11 | 1902 | | | | 1903 | URI | suit-parameter-uri | Section 8.7.5 | 1904 | | | .12 | 1905 | | | | 1906 | Source | suit-parameter-source-component | Section 8.7.5 | 1907 | Component | | .13 | 1908 | | | | 1909 | Run Args | suit-parameter-run-args | Section 8.7.5 | 1910 | | | .14 | 1911 | | | | 1912 | Device ID | suit-parameter-device-identifier | Section 8.7.5 | 1913 | | | .4 | 1914 | | | | 1915 | Minimum | suit-parameter-minimum-battery | Section 8.7.5 | 1916 | Battery | | .15 | 1917 | | | | 1918 | Update | suit-parameter-update-priority | Section 8.7.5 | 1919 | Priority | | .16 | 1920 | | | | 1921 | Version | suit-parameter-version | Section 8.7.5 | 1922 | | | .17 | 1923 | | | | 1924 | Wait Info | suit-parameter-wait-info | Section 8.7.5 | 1925 | | | .18 | 1926 | | | | 1927 | URI List | suit-parameter-uri-list | Section 8.7.5 | 1928 | | | .19 | 1929 | | | | 1930 | Fetch | suit-parameter-fetch-arguments | Section 8.7.5 | 1931 | Arguments | | .20 | 1932 | | | | 1933 | Strict Order | suit-parameter-strict-order | Section 8.7.5 | 1934 | | | .21 | 1935 | | | | 1936 | Soft Failure | suit-parameter-soft-failure | Section 8.7.5 | 1937 | | | .22 | 1938 | | | | 1939 | Custom | suit-parameter-custom | Section 8.7.5 | 1940 | | | .23 | 1941 +----------------+----------------------------------+---------------+ 1943 CBOR-encoded object parameters are still wrapped in a bstr. This is 1944 because it allows a parser that is aggregating parameters to 1945 reference the object with a single pointer and traverse it without 1946 understanding the contents. This is important for modularization and 1947 division of responsibility within a pull parser. The same 1948 consideration does not apply to Directives because those elements are 1949 invoked with their arguments immediately 1951 8.7.5.1. Constructing Identifiers 1953 Several conditions use identifiers to determine whether a manifest 1954 matches a given Recipient or not. These identifiers are defined to 1955 be RFC 4122 [RFC4122] UUIDs. These UUIDs are not human-readable and 1956 are therefore used for machine-based processing only. 1958 A Recipient MAY match any number of UUIDs for vendor or class 1959 identifier. This may be relevant to physical or software modules. 1960 For example, a Recipient that has an OS and one or more applications 1961 might list one Vendor ID for the OS and one or more additional Vendor 1962 IDs for the applications. This Recipient might also have a Class ID 1963 that must be matched for the OS and one or more Class IDs for the 1964 applications. 1966 Identifiers are used for compatibility checks. They MUST NOT be used 1967 as assertions of identity. They are evaluated by identifier 1968 conditions (Section 8.7.6.1). 1970 A more complete example: Imagine a device has the following physical 1971 components: 1. A host MCU 2. A WiFi module 1973 This same device has three software modules: 1. An operating system 1974 2. A WiFi module interface driver 3. An application 1976 Suppose that the WiFi module's firmware has a proprietary update 1977 mechanism and doesn't support manifest processing. This device can 1978 report four class IDs: 1980 1. Hardware model/revision 1982 2. OS 1984 3. WiFi module model/revision 1986 4. Application 1988 This allows the OS, WiFi module, and application to be updated 1989 independently. To combat possible incompatibilities, the OS class ID 1990 can be changed each time the OS has a change to its API. 1992 This approach allows a vendor to target, for example, all devices 1993 with a particular WiFi module with an update, which is a very 1994 powerful mechanism, particularly when used for security updates. 1996 UUIDs MUST be created according to RFC 4122 [RFC4122]. UUIDs SHOULD 1997 use versions 3, 4, or 5, as described in RFC4122. Versions 1 and 2 1998 do not provide a tangible benefit over version 4 for this 1999 application. 2001 The RECOMMENDED method to create a vendor ID is: Vendor ID = 2002 UUID5(DNS_PREFIX, vendor domain name) 2004 The RECOMMENDED method to create a class ID is: Class ID = 2005 UUID5(Vendor ID, Class-Specific-Information) 2007 Class-specific information is composed of a variety of data, for 2008 example: 2010 - Model number. 2012 - Hardware revision. 2014 - Bootloader version (for immutable bootloaders). 2016 8.7.5.2. suit-parameter-vendor-identifier 2018 A RFC 4122 UUID representing the vendor of the device or component. 2019 The UUID is encoded as a 16 byte bstr, containing the raw bytes of 2020 the UUID. It MUST be constructed as described in Section 8.7.5.1 2022 8.7.5.3. suit-parameter-class-identifier 2024 A RFC 4122 UUID representing the class of the device or component. 2025 The UUID is encoded as a 16 byte bstr, containing the raw bytes of 2026 the UUID. It MUST be constructed as described in Section 8.7.5.1 2028 8.7.5.4. suit-parameter-device-identifier 2030 A RFC 4122 UUID representing the specific device or component. The 2031 UUID is encoded as a 16 byte bstr, containing the raw bytes of the 2032 UUID. It MUST be constructed as described in Section 8.7.5.1 2034 8.7.5.5. suit-parameter-image-digest 2036 A fingerprint computed over the component itself, encoded in the 2037 Section 10 structure. The SUIT_Digest is wrapped in a bstr, as 2038 required in Section 8.7.5. 2040 8.7.5.6. suit-parameter-image-size 2042 The size of the firmware image in bytes. This size is encoded as a 2043 positive integer. 2045 8.7.5.7. suit-parameter-use-before 2047 An expiry date for the use of the manifest encoded as a POSIX 2048 timestamp; a positive integer. Implementations that use this 2049 parameter MUST use a 64-bit internal representation of the integer. 2051 8.7.5.8. suit-parameter-component-offset 2053 This parameter sets the offset in a component. Some components 2054 support multiple possible Slots (offsets into a storage area). This 2055 parameter describes the intended Slot to use, identified by its 2056 offset into the component's storage area. This offset MUST be 2057 encoded as a positive integer. 2059 8.7.5.9. suit-parameter-encryption-info 2061 Encryption Info defines the mechanism that Fetch or Copy should use 2062 to decrypt the data they transfer. SUIT_Parameter_Encryption_Info is 2063 encoded as a COSE_Encrypt_Tagged or a COSE_Encrypt0_Tagged, wrapped 2064 in a bstr. 2066 8.7.5.10. suit-parameter-compression-info 2068 Compression Info defines any information that is required for a 2069 Recipient to perform decompression operations. Typically, this 2070 includes the algorithm identifier. This document defines the use of 2071 ZLIB [RFC1950], Brotli [RFC7932], and ZSTD 2072 [I-D.kucherawy-rfc8478bis]. 2074 Additional compression formats can be registered through the IANA- 2075 maintained registry. 2077 8.7.5.11. suit-parameter-unpack-info 2079 SUIT_Unpack_Info defines the information required for a Recipient to 2080 interpret a packed format. This document defines the use of the 2081 following binary encodings: Intel HEX [HEX], Motorola S-record 2082 [SREC], Executable and Linkable Format (ELF) [ELF], and Common Object 2083 File Format (COFF) [COFF]. 2085 Additional packing formats can be registered through the IANA- 2086 maintained registry. 2088 8.7.5.12. suit-parameter-uri 2090 A URI from which to fetch a resource. 2092 8.7.5.13. suit-parameter-source-component 2094 This parameter sets the source component to be used with either 2095 Section 8.7.7.10 or with Section 8.7.7.14. The current Component, as 2096 set by suit-directive-set-component-index defines the destination, 2097 and suit-parameter-source-component defines the source. 2099 8.7.5.14. suit-parameter-run-args 2101 This parameter contains an encoded set of arguments for 2102 Section 8.7.7.11. The arguments MUST be provided as an 2103 implementation-defined bstr. 2105 8.7.5.15. suit-parameter-minimum-battery 2107 This parameter sets the minimum battery level in mWh. This parameter 2108 is encoded as a positive integer. Used with Section 8.7.6.6. 2110 8.7.5.16. suit-parameter-update-priority 2112 This parameter sets the priority of the update. This parameter is 2113 encoded as an integer. It is used along with suit-condition-update- 2114 authorized [1] to ask an application for permission to initiate an 2115 update. This does not constitute a privilege inversion because an 2116 explicit request for authorization has been provided by the Update 2117 Authority in the form of the suit-condition-update-authorized 2118 command. 2120 Applications MAY define their own meanings for the update priority. 2121 For example, critical reliability & vulnerability fixes MAY be given 2122 negative numbers, while bug fixes MAY be given small positive 2123 numbers, and feature additions MAY be given larger positive numbers, 2124 which allows an application to make an informed decision about 2125 whether and when to allow an update to proceed. 2127 8.7.5.17. suit-parameter-version 2129 Indicates allowable versions for the specified component. Allowable 2130 versions can be specified, either with a list or with range matching. 2131 This parameter is compared with version asserted by the current 2132 component when Section 8.7.6.8 is invoked. The current component may 2133 assert the current version in many ways, including storage in a 2134 parameter storage database, in a metadata object, or in a known 2135 location within the component itself. 2137 The component version can be compared as: 2139 - Greater. 2141 - Greater or Equal. 2143 - Equal. 2145 - Lesser or Equal. 2147 - Lesser. 2149 Versions are encoded as a CBOR list of integers. Comparisons are 2150 done on each integer in sequence. Comparison stops after all 2151 integers in the list defined by the manifest have been consumed OR 2152 after a non-equal match has occurred. For example, if the manifest 2153 defines a comparison, "Equal [1]", then this will match all version 2154 sequences starting with 1. If a manifest defines both "Greater or 2155 Equal [1,0]" and "Lesser [1,10]", then it will match versions 1.0.x 2156 up to, but not including 1.10. 2158 While the exact encoding of versions is application-defined, semantic 2159 versions map conveniently. For example, 2161 - 1.2.3 = [1,2,3]. 2163 - 1.2-rc3 = [1,2,-1,3]. 2165 - 1.2-beta = [1,2,-2]. 2167 - 1.2-alpha = [1,2,-3]. 2169 - 1.2-alpha4 = [1,2,-3,4]. 2171 suit-condition-version is OPTIONAL to implement. 2173 Versions SHOULD be provided as follows: 2175 1. The first integer represents the major number. This indicates 2176 breaking changes to the component. 2178 2. The second integer represents the minor number. This is 2179 typically reserved for new features or large, non-breaking 2180 changes. 2182 3. The third integer is the patch version. This is typically 2183 reserved for bug fixes. 2185 4. The fourth integer is the build number. 2187 Where Alpha (-3), Beta (-2), and Release Candidate (-1) are used, 2188 they are inserted as a negative number between Minor and Patch 2189 numbers. This allows these releases to compare correctly with final 2190 releases. For example, Version 2.0, RC1 should be lower than Version 2191 2.0.0 and higher than any Version 1.x. By encoding RC as -1, this 2192 works correctly: [2,0,-1,1] compares as lower than [2,0,0]. 2193 Similarly, beta (-2) is lower than RC and alpha (-3) is lower than 2194 RC. 2196 8.7.5.18. suit-parameter-wait-info 2198 suit-directive-wait Section 8.7.7.12 directs the manifest processor 2199 to pause until a specified event occurs. The suit-parameter-wait- 2200 info encodes the parameters needed for the directive. 2202 The exact implementation of the pause is implementation-defined. For 2203 example, this could be done by blocking on a semaphore, registering 2204 an event handler and suspending the manifest processor, polling for a 2205 notification, or aborting the update entirely, then restarting when a 2206 notification is received. 2208 suit-parameter-wait-info is encoded as a map of wait events. When 2209 ALL wait events are satisfied, the Manifest Processor continues. The 2210 wait events currently defined are described in the following table. 2212 +--------------------------------------+----------+-----------------+ 2213 | Name | Encoding | Description | 2214 +--------------------------------------+----------+-----------------+ 2215 | suit-wait-event-authorization | int | Same as Section | 2216 | | | 8.7.5.16 | 2217 | | | | 2218 | suit-wait-event-power | int | Wait until | 2219 | | | power state | 2220 | | | | 2221 | suit-wait-event-network | int | Wait until | 2222 | | | network state | 2223 | | | | 2224 | suit-wait-event-other-device-version | See | Wait for other | 2225 | | below | device to match | 2226 | | | version | 2227 | | | | 2228 | suit-wait-event-time | uint | Wait until time | 2229 | | | (POSIX | 2230 | | | timestamp) | 2231 | | | | 2232 | suit-wait-event-time-of-day | uint | Wait until | 2233 | | | seconds since | 2234 | | | 00:00:00 | 2235 | | | | 2236 | suit-wait-event-day-of-week | uint | Wait until days | 2237 | | | since Sunday | 2238 +--------------------------------------+----------+-----------------+ 2240 suit-wait-event-other-device-version reuses the encoding of suit- 2241 parameter-version-match. It is encoded as a sequence that contains 2242 an implementation-defined bstr identifier for the other device, and a 2243 list of one or more SUIT_Parameter_Version_Match. 2245 8.7.5.19. suit-parameter-uri-list 2247 Indicates a list of URIs from which to fetch a resource. The URI 2248 list is encoded as a list of tstr, in priority order. The Recipient 2249 should attempt to fetch the resource from each URI in turn, ruling 2250 out each, in order, if the resource is inaccessible or it is 2251 otherwise undesirable to fetch from that URI. suit-parameter-uri-list 2252 is consumed by Section 8.7.7.9. 2254 8.7.5.20. suit-parameter-fetch-arguments 2256 An implementation-defined set of arguments to Section 8.7.7.8. 2257 Arguments are encoded in a bstr. 2259 8.7.5.21. suit-parameter-strict-order 2261 The Strict Order Parameter allows a manifest to govern when 2262 directives can be executed out-of-order. This allows for systems 2263 that have a sensitivity to order of updates to choose the order in 2264 which they are executed. It also allows for more advanced systems to 2265 parallelize their handling of updates. Strict Order defaults to 2266 True. It MAY be set to False when the order of operations does not 2267 matter. When arriving at the end of a command sequence, ALL commands 2268 MUST have completed, regardless of the state of 2269 SUIT_Parameter_Strict_Order. If SUIT_Parameter_Strict_Order is 2270 returned to True, ALL preceding commands MUST complete before the 2271 next command is executed. 2273 See Section 6.6 for behavioral description of Strict Order. 2275 8.7.5.22. suit-parameter-soft-failure 2277 When executing a command sequence inside Section 8.7.7.4 or 2278 Section 8.7.7.13 and a condition failure occurs, the manifest 2279 processor aborts the sequence. For suit-directive-try-each, if Soft 2280 Failure is True, the next sequence in Try Each is invoked, otherwise 2281 suit-directive-try-each fails with the condition failure code. In 2282 suit-directive-run-sequence, if Soft Failure is True the suit- 2283 directive-run-sequence simply halts with no side-effects and the 2284 Manifest Processor continues with the following command, otherwise, 2285 the suit-directive-run-sequence fails with the condition failure 2286 code. 2288 suit-parameter-soft-failure is scoped to the enclosing 2289 SUIT_Command_Sequence. Its value is discarded when 2290 SUIT_Command_Sequence terminates. It MUST NOT be set outside of 2291 suit-directive-try-each or suit-directive-run-sequence. 2293 When suit-directive-try-each is invoked, Soft Failure defaults to 2294 True. An Update Author may choose to set Soft Failure to False if 2295 they require a failed condition in a sequence to force an Abort. 2297 When suit-directive-run-sequence is invoked, Soft Failure defaults to 2298 False. An Update Author may choose to make failures soft within a 2299 suit-directive-run-sequence. 2301 8.7.5.23. suit-parameter-custom 2303 This parameter is an extension point for any proprietary, application 2304 specific conditions and directives. 2306 8.7.6. SUIT_Condition 2308 Conditions are used to define mandatory properties of a system in 2309 order for an update to be applied. They can be pre-conditions or 2310 post-conditions of any directive or series of directives, depending 2311 on where they are placed in the list. All Conditions specify a 2312 Reporting Policy as described Section 8.7.4. Conditions include: 2314 +----------------+----------------------------------+---------------+ 2315 | Name | CDDL Structure | Reference | 2316 +----------------+----------------------------------+---------------+ 2317 | Vendor | suit-condition-vendor-identifier | Section 8.7.6 | 2318 | Identifier | | .1 | 2319 | | | | 2320 | Class | suit-condition-class-identifier | Section 8.7.6 | 2321 | Identifier | | .1 | 2322 | | | | 2323 | Device | suit-condition-device-identifier | Section 8.7.6 | 2324 | Identifier | | .1 | 2325 | | | | 2326 | Image Match | suit-condition-image-match | Section 8.7.6 | 2327 | | | .2 | 2328 | | | | 2329 | Image Not | suit-condition-image-not-match | Section 8.7.6 | 2330 | Match | | .3 | 2331 | | | | 2332 | Use Before | suit-condition-use-before | Section 8.7.6 | 2333 | | | .4 | 2334 | | | | 2335 | Component | suit-condition-component-offset | Section 8.7.6 | 2336 | Offset | | .5 | 2337 | | | | 2338 | Minimum | suit-condition-minimum-battery | Section 8.7.6 | 2339 | Battery | | .6 | 2340 | | | | 2341 | Update | suit-condition-update-authorized | Section 8.7.6 | 2342 | Authorized | | .7 | 2343 | | | | 2344 | Version | suit-condition-version | Section 8.7.6 | 2345 | | | .8 | 2346 | | | | 2347 | Custom | SUIT_Condition_Custom | Section 8.7.6 | 2348 | Condition | | .9 | 2349 +----------------+----------------------------------+---------------+ 2351 The abstract description of these conditions is defined in 2352 Section 6.4. 2354 Conditions compare parameters against properties of the system. 2355 These properties may be asserted in many different ways, including: 2356 calculation on-demand, volatile definition in memory, static 2357 definition within the manifest processor, storage in known location 2358 within an image, storage within a key storage system, storage in One- 2359 Time-Programmable memory, inclusion in mask ROM, or inclusion as a 2360 register in hardware. Some of these assertion methods are global in 2361 scope, such as a hardware register, some are scoped to an individual 2362 component, such as storage at a known location in an image, and some 2363 assertion methods can be either global or component-scope, based on 2364 implementation. 2366 Each condition MUST report a result code on completion. If a 2367 condition reports failure, then the current sequence of commands MUST 2368 terminate. A subsequent command or command sequence MAY continue 2369 executing if Section 8.7.5.22 is set. If a condition requires 2370 additional information, this MUST be specified in one or more 2371 parameters before the condition is executed. If a Recipient attempts 2372 to process a condition that expects additional information and that 2373 information has not been set, it MUST report a failure. If a 2374 Recipient encounters an unknown condition, it MUST report a failure. 2376 Condition labels in the positive number range are reserved for IANA 2377 registration while those in the negative range are custom conditions 2378 reserved for proprietary use. See Section 11 for more details. 2380 8.7.6.1. suit-condition-vendor-identifier, suit-condition-class- 2381 identifier, and suit-condition-device-identifier 2383 There are three identifier-based conditions: suit-condition-vendor- 2384 identifier, suit-condition-class-identifier, and suit-condition- 2385 device-identifier. Each of these conditions match a RFC 4122 2386 [RFC4122] UUID that MUST have already been set as a parameter. The 2387 installing Recipient MUST match the specified UUID in order to 2388 consider the manifest valid. These identifiers are scoped by 2389 component in the manifest. The Recipient MAY treat them as scoped by 2390 component or as global identifiers. 2392 The Recipient uses the ID parameter that has already been set using 2393 the Set Parameters directive. If no ID has been set, this condition 2394 fails. suit-condition-class-identifier and suit-condition-vendor- 2395 identifier are REQUIRED to implement. suit-condition-device- 2396 identifier is OPTIONAL to implement. 2398 Each identifier condition compares the corresponding identifier 2399 parameter to a parameter asserted to the Manifest Processor by the 2400 Recipient. Identifiers MUST be known to the Manifest Processor in 2401 order to evaluate compatibility. 2403 Globally-scoped identifiers MUST match, regardless of current 2404 component index. Component-scoped identifiers match only when the 2405 current component index resolves to the component associated with the 2406 component-scoped identifier. 2408 8.7.6.2. suit-condition-image-match 2410 Verify that the current component matches the Section 8.7.5.5 for the 2411 current component. The digest is verified against the digest 2412 specified in the Component's parameters list. If no digest is 2413 specified, the condition fails. suit-condition-image-match is 2414 REQUIRED to implement. 2416 8.7.6.3. suit-condition-image-not-match 2418 Verify that the current component does not match the Section 8.7.5.5. 2419 If no digest is specified, the condition fails. suit-condition-image- 2420 not-match is OPTIONAL to implement. 2422 8.7.6.4. suit-condition-use-before 2424 Verify that the current time is BEFORE the specified time. suit- 2425 condition-use-before is used to specify the last time at which an 2426 update should be installed. The recipient evaluates the current time 2427 against the suit-parameter-use-before parameter (Section 8.7.5.7), 2428 which must have already been set as a parameter, encoded as a POSIX 2429 timestamp, that is seconds after 1970-01-01 00:00:00. Timestamp 2430 conditions MUST be evaluated in 64 bits, regardless of encoded CBOR 2431 size. suit-condition-use-before is OPTIONAL to implement. 2433 8.7.6.5. suit-condition-component-offset 2435 Verify that the offset of the current component matches the offset 2436 set in Section 8.7.5.8. This condition allows a manifest to select 2437 between several images to match a target offset. 2439 8.7.6.6. suit-condition-minimum-battery 2441 suit-condition-minimum-battery provides a mechanism to test a 2442 Recipient's battery level before installing an update. This 2443 condition is primarily for use in primary-cell applications, where 2444 the battery is only ever discharged. For batteries that are charged, 2445 suit-directive-wait is more appropriate, since it defines a "wait" 2446 until the battery level is sufficient to install the update. suit- 2447 condition-minimum-battery is specified in mWh. suit-condition- 2448 minimum-battery is OPTIONAL to implement. suit-condition-minimum- 2449 battery consumes Section 8.7.5.15. 2451 8.7.6.7. suit-condition-update-authorized 2453 Request Authorization from the application and fail if not 2454 authorized. This can allow a user to decline an update. 2455 Section 8.7.5.16 provides an integer priority level that the 2456 application can use to determine whether or not to authorize the 2457 update. Priorities are application defined. suit-condition-update- 2458 authorized is OPTIONAL to implement. 2460 8.7.6.8. suit-condition-version 2462 suit-condition-version allows comparing versions of firmware. 2463 Verifying image digests is preferred to version checks because 2464 digests are more precise. suit-condition-version examines a 2465 component's version against the version info specified in 2466 Section 8.7.5.17 2468 8.7.6.9. SUIT_Condition_Custom 2470 SUIT_Condition_Custom describes any proprietary, application specific 2471 condition. This is encoded as a negative integer, chosen by the 2472 firmware developer. If additional information must be provided to 2473 the condition, it should be encoded in a custom parameter (a nint) as 2474 described in Section 8.7.5. SUIT_Condition_Custom is OPTIONAL to 2475 implement. 2477 8.7.7. SUIT_Directive 2479 Directives are used to define the behavior of the recipient. 2480 Directives include: 2482 +---------------+-------------------------------------+-------------+ 2483 | Name | CDDL Structure | Reference | 2484 +---------------+-------------------------------------+-------------+ 2485 | Set Component | suit-directive-set-component-index | Section 8.7 | 2486 | Index | | .7.1 | 2487 | | | | 2488 | Set | suit-directive-set-dependency-index | Section 8.7 | 2489 | Dependency | | .7.2 | 2490 | Index | | | 2491 | | | | 2492 | Abort | suit-directive-abort | Section 8.7 | 2493 | | | .7.3 | 2494 | | | | 2495 | Try Each | suit-directive-try-each | Section 8.7 | 2496 | | | .7.4 | 2497 | | | | 2498 | Process | suit-directive-process-dependency | Section 8.7 | 2499 | Dependency | | .7.5 | 2500 | | | | 2501 | Set | suit-directive-set-parameters | Section 8.7 | 2502 | Parameters | | .7.6 | 2503 | | | | 2504 | Override | suit-directive-override-parameters | Section 8.7 | 2505 | Parameters | | .7.7 | 2506 | | | | 2507 | Fetch | suit-directive-fetch | Section 8.7 | 2508 | | | .7.8 | 2509 | | | | 2510 | Copy | suit-directive-copy | Section 8.7 | 2511 | | | .7.10 | 2512 | | | | 2513 | Run | suit-directive-run | Section 8.7 | 2514 | | | .7.11 | 2515 | | | | 2516 | Wait For | suit-directive-wait | Section 8.7 | 2517 | Event | | .7.12 | 2518 | | | | 2519 | Run Sequence | suit-directive-run-sequence | Section 8.7 | 2520 | | | .7.13 | 2521 | | | | 2522 | Swap | suit-directive-swap | Section 8.7 | 2523 | | | .7.14 | 2524 | | | | 2525 | Fetch URI | suit-directive-fetch-uri-list | Section 8.7 | 2526 | list | | .7.9 | 2527 +---------------+-------------------------------------+-------------+ 2529 The abstract description of these commands is defined in Section 6.4. 2531 When a Recipient executes a Directive, it MUST report a result code. 2532 If the Directive reports failure, then the current Command Sequence 2533 MUST terminate. 2535 8.7.7.1. suit-directive-set-component-index 2537 Set Component Index defines the component to which successive 2538 directives and conditions will apply. The supplied argument MUST be 2539 either a boolean or an unsigned integer index into suit-components. 2540 If the following directives apply to ALL components, then the boolean 2541 value "True" is used instead of an index. If the following 2542 directives apply to NO components, then the boolean value "False" is 2543 used. When suit-directive-set-dependency-index is used, suit- 2544 directive-set-component-index = False is implied. When suit- 2545 directive-set-component-index is used, suit-directive-set-dependency- 2546 index = False is implied. 2548 8.7.7.2. suit-directive-set-dependency-index 2550 Set Dependency Index defines the manifest to which successive 2551 directives and conditions will apply. The supplied argument MUST be 2552 either a boolean or an unsigned integer index into the dependencies. 2553 If the following directives apply to ALL dependencies, then the 2554 boolean value "True" is used instead of an index. If the following 2555 directives apply to NO dependencies, then the boolean value "False" 2556 is used. When suit-directive-set-component-index is used, suit- 2557 directive-set-dependency-index = False is implied. When suit- 2558 directive-set-dependency-index is used, suit-directive-set-component- 2559 index = False is implied. 2561 Typical operations that require suit-directive-set-dependency-index 2562 include setting a source URI or Encryption Information, invoking 2563 "Fetch," or invoking "Process Dependency" for an individual 2564 dependency. 2566 8.7.7.3. suit-directive-abort 2568 Unconditionally fail. This operation is typically used in 2569 conjunction with suit-directive-try-each. 2571 8.7.7.4. suit-directive-try-each 2573 This command runs several SUIT_Command_Sequence, one after another, 2574 in a strict order. Use this command to implement a "try/catch-try/ 2575 catch" sequence. Manifest processors MAY implement this command. 2577 Section 8.7.5.22 is initialized to True at the beginning of each 2578 sequence. If one sequence aborts due to a condition failure, the 2579 next is started. If no sequence completes without condition failure, 2580 then suit-directive-try-each returns an error. If a particular 2581 application calls for all sequences to fail and still continue, then 2582 an empty sequence (nil) can be added to the Try Each Argument. 2584 The argument to suit-directive-try-each is a list of 2585 SUIT_Command_Sequence. suit-directive-try-each does not specify a 2586 reporting policy. 2588 8.7.7.5. suit-directive-process-dependency 2590 Execute the commands in the common section of the current dependency, 2591 followed by the commands in the equivalent section of the current 2592 dependency. For example, if the current section is "fetch payload," 2593 this will execute "common" in the current dependency, then "fetch 2594 payload" in the current dependency. Once this is complete, the 2595 command following suit-directive-process-dependency will be 2596 processed. 2598 If the current dependency is False, this directive has no effect. If 2599 the current dependency is True, then this directive applies to all 2600 dependencies. If the current section is "common," this directive 2601 MUST have no effect. 2603 When SUIT_Process_Dependency completes, it forwards the last status 2604 code that occurred in the dependency. 2606 8.7.7.6. suit-directive-set-parameters 2608 suit-directive-set-parameters allows the manifest to configure 2609 behavior of future directives by changing parameters that are read by 2610 those directives. When dependencies are used, suit-directive-set- 2611 parameters also allows a manifest to modify the behavior of its 2612 dependencies. 2614 Available parameters are defined in Section 8.7.5. 2616 If a parameter is already set, suit-directive-set-parameters will 2617 skip setting the parameter to its argument. This provides the core 2618 of the override mechanism, allowing dependent manifests to change the 2619 behavior of a manifest. 2621 suit-directive-set-parameters does not specify a reporting policy. 2623 8.7.7.7. suit-directive-override-parameters 2625 suit-directive-override-parameters replaces any listed parameters 2626 that are already set with the values that are provided in its 2627 argument. This allows a manifest to prevent replacement of critical 2628 parameters. 2630 Available parameters are defined in Section 8.7.5. 2632 suit-directive-override-parameters does not specify a reporting 2633 policy. 2635 8.7.7.8. suit-directive-fetch 2637 suit-directive-fetch instructs the manifest processor to obtain one 2638 or more manifests or payloads, as specified by the manifest index and 2639 component index, respectively. 2641 suit-directive-fetch can target one or more manifests and one or more 2642 payloads. suit-directive-fetch retrieves each component and each 2643 manifest listed in component-index and dependency-index, 2644 respectively. If component-index or dependency-index is True, 2645 instead of an integer, then all current manifest components/manifests 2646 are fetched. The current manifest's dependent-components are not 2647 automatically fetched. In order to pre-fetch these, they MUST be 2648 specified in a component-index integer. 2650 suit-directive-fetch typically takes no arguments unless one is 2651 needed to modify fetch behavior. If an argument is needed, it must 2652 be wrapped in a bstr and set in suit-parameter-fetch-arguments. 2654 suit-directive-fetch reads the URI parameter to find the source of 2655 the fetch it performs. 2657 The behavior of suit-directive-fetch can be modified by setting one 2658 or more of SUIT_Parameter_Encryption_Info, 2659 SUIT_Parameter_Compression_Info, SUIT_Parameter_Unpack_Info. These 2660 three parameters each activate and configure a processing step that 2661 can be applied to the data that is transferred during suit-directive- 2662 fetch. 2664 8.7.7.9. suit-directive-fetch-uri-list 2666 suit-directive-fetch-uri-list uses the same semantics as 2667 Section 8.7.7.8, however it iterates over the URI List 2668 (Section 8.7.5.19) to select a URI to fetch from. 2670 8.7.7.10. suit-directive-copy 2672 suit-directive-copy instructs the manifest processor to obtain one or 2673 more payloads, as specified by the component index. suit-directive- 2674 copy retrieves each component listed in component-index, 2675 respectively. If component-index is True, instead of an integer, 2676 then all current manifest components are copied. The current 2677 manifest's dependent-components are not automatically copied. In 2678 order to copy these, they MUST be specified in a component-index 2679 integer. 2681 The behavior of suit-directive-copy can be modified by setting one or 2682 more of SUIT_Parameter_Encryption_Info, 2683 SUIT_Parameter_Compression_Info, SUIT_Parameter_Unpack_Info. These 2684 three parameters each activate and configure a processing step that 2685 can be applied to the data that is transferred during suit-directive- 2686 copy. 2688 suit-directive-copy reads its source from Section 8.7.5.13. 2690 8.7.7.11. suit-directive-run 2692 suit-directive-run directs the manifest processor to transfer 2693 execution to the current Component Index. When this is invoked, the 2694 manifest processor MAY be unloaded and execution continues in the 2695 Component Index. Arguments are provided to suit-directive-run 2696 through suit-parameter-run-arguments (Section 8.7.5.14) and are 2697 forwarded to the executable code located in Component Index in an 2698 application-specific way. For example, this could form the Linux 2699 Kernel Command Line if booting a Linux device. 2701 If the executable code at Component Index is constructed in such a 2702 way that it does not unload the manifest processor, then the manifest 2703 processor may resume execution after the executable completes. This 2704 allows the manifest processor to invoke suitable helpers and to 2705 verify them with image conditions. 2707 8.7.7.12. suit-directive-wait 2709 suit-directive-wait directs the manifest processor to pause until a 2710 specified event occurs. Some possible events include: 2712 1. Authorization 2714 2. External Power 2716 3. Network availability 2717 4. Other Device Firmware Version 2719 5. Time 2721 6. Time of Day 2723 7. Day of Week 2725 8.7.7.13. suit-directive-run-sequence 2727 To enable conditional commands, and to allow several strictly ordered 2728 sequences to be executed out-of-order, suit-directive-run-sequence 2729 allows the manifest processor to execute its argument as a 2730 SUIT_Command_Sequence. The argument must be wrapped in a bstr. 2732 When a sequence is executed, any failure of a condition causes 2733 immediate termination of the sequence. 2735 When suit-directive-run-sequence completes, it forwards the last 2736 status code that occurred in the sequence. If the Soft Failure 2737 parameter is true, then suit-directive-run-sequence only fails when a 2738 directive in the argument sequence fails. 2740 Section 8.7.5.22 defaults to False when suit-directive-run-sequence 2741 begins. Its value is discarded when suit-directive-run-sequence 2742 terminates. 2744 8.7.7.14. suit-directive-swap 2746 suit-directive-swap instructs the manifest processor to move the 2747 source to the destination and the destination to the source 2748 simultaneously. Swap has nearly identical semantics to suit- 2749 directive-copy except that suit-directive-swap replaces the source 2750 with the current contents of the destination in an application- 2751 defined way. If SUIT_Parameter_Compression_Info or 2752 SUIT_Parameter_Encryption_Info are present, they MUST be handled in a 2753 symmetric way, so that the source is decompressed into the 2754 destination and the destination is compressed into the source. The 2755 source is decrypted into the destination and the destination is 2756 encrypted into the source. suit-directive-swap is OPTIONAL to 2757 implement. 2759 8.7.8. Integrity Check Values 2761 When the CoSWID, Text section, or any Command Sequence of the Update 2762 Procedure is made severable, it is moved to the Envelope and replaced 2763 with a SUIT_Digest. The SUIT_Digest is computed over the entire bstr 2764 enclosing the Manifest element that has been moved to the Envelope. 2766 Each element that is made severable from the Manifest is placed in 2767 the Envelope with an identical key, so that it matches the key of the 2768 corresponding Integrity Check Value. 2770 Each Integrity Check Value covers the corresponding Envelope Element 2771 as described in Section 8.8. 2773 8.8. Severable Elements 2775 Because the manifest can be used by different actors at different 2776 times, some parts of the manifest can be removed or "Severed" without 2777 affecting later stages of the lifecycle. Severing of information is 2778 achieved by separating that information from the signed container so 2779 that removing it does not affect the signature. This means that 2780 ensuring integrity of severable parts of the manifest is a 2781 requirement for the signed portion of the manifest. Severing some 2782 parts makes it possible to discard parts of the manifest that are no 2783 longer necessary. This is important because it allows the storage 2784 used by the manifest to be greatly reduced. For example, no text 2785 size limits are needed if text is removed from the manifest prior to 2786 delivery to a constrained device. 2788 Elements are made severable by removing them from the manifest, 2789 encoding them in a bstr, and placing a SUIT_Digest of the bstr in the 2790 manifest so that they can still be authenticated. The SUIT_Digest 2791 typically consumes 4 bytes more than the size of the raw digest, 2792 therefore elements smaller than (Digest Bits)/8 + 4 SHOULD NOT be 2793 severable. Elements larger than (Digest Bits)/8 + 4 MAY be 2794 severable, while elements that are much larger than (Digest Bits)/8 + 2795 4 SHOULD be severable. 2797 Because of this, all command sequences in the manifest are encoded in 2798 a bstr so that there is a single code path needed for all command 2799 sequences. 2801 9. Access Control Lists 2803 To manage permissions in the manifest, there are three models that 2804 can be used. 2806 First, the simplest model requires that all manifests are 2807 authenticated by a single trusted key. This mode has the advantage 2808 that only a root manifest needs to be authenticated, since all of its 2809 dependencies have digests included in the root manifest. 2811 This simplest model can be extended by adding key delegation without 2812 much increase in complexity. 2814 A second model requires an ACL to be presented to the Recipient, 2815 authenticated by a trusted party or stored on the Recipient. This 2816 ACL grants access rights for specific component IDs or component ID 2817 prefixes to the listed identities or identity groups. Any identity 2818 may verify an image digest, but fetching into or fetching from a 2819 component ID requires approval from the ACL. 2821 A third model allows a Recipient to provide even more fine-grained 2822 controls: The ACL lists the component ID or component ID prefix that 2823 an identity may use, and also lists the commands that the identity 2824 may use in combination with that component ID. 2826 10. SUIT Digest Container 2828 RFC 8152 [RFC8152] provides containers for signature, MAC, and 2829 encryption, but no basic digest container. The container needed for 2830 a digest requires a type identifier and a container for the raw 2831 digest data. Some forms of digest may require additional parameters. 2832 These can be added following the digest. 2834 The SUIT digest is a CBOR List containing two elements: a suit- 2835 digest-algorithm-id and a bstr containing the bytes of the digest. 2837 11. IANA Considerations 2839 IANA is requested to: 2841 - allocate a CBOR tag for the SUIT Envelope and another for the SUIT 2842 Manifest. 2844 - allocate a media type for suit: application/suit-envelope 2846 - setup several registries as described below 2848 IANA is requested to setup a registry for SUIT manifests. Several 2849 registries defined in the subsections below need to be created. 2851 For each registry, values 0-23 are Standards Action, 24-255 are IETF 2852 Review, 256-65535 are Expert Review, and 65536 or greater are First 2853 Come First Served. 2855 Negative values -23 to 0 are Experimental Use, -24 and lower are 2856 Private Use. 2858 11.1. SUIT Commands 2860 +-------+----------------------+ 2861 | Label | Name | 2862 +-------+----------------------+ 2863 | 1 | Vendor Identifier | 2864 | | | 2865 | 2 | Class Identifier | 2866 | | | 2867 | 3 | Image Match | 2868 | | | 2869 | 4 | Use Before | 2870 | | | 2871 | 5 | Component Offset | 2872 | | | 2873 | 12 | Set Component Index | 2874 | | | 2875 | 13 | Set Dependency Index | 2876 | | | 2877 | 14 | Abort | 2878 | | | 2879 | 15 | Try Each | 2880 | | | 2881 | 16 | Reserved | 2882 | | | 2883 | 17 | Reserved | 2884 | | | 2885 | 18 | Process Dependency | 2886 | | | 2887 | 19 | Set Parameters | 2888 | | | 2889 | 20 | Override Parameters | 2890 | | | 2891 | 21 | Fetch | 2892 | | | 2893 | 22 | Copy | 2894 | | | 2895 | 23 | Run | 2896 | | | 2897 | 24 | Device Identifier | 2898 | | | 2899 | 25 | Image Not Match | 2900 | | | 2901 | 26 | Minimum Battery | 2902 | | | 2903 | 27 | Update Authorized | 2904 | | | 2905 | 28 | Version | 2906 | | | 2907 | 29 | Wait For Event | 2908 | | | 2909 | 30 | Fetch URI List | 2910 | | | 2911 | 31 | Swap | 2912 | | | 2913 | 32 | Run Sequence | 2914 | | | 2915 | nint | Custom Condition | 2916 +-------+----------------------+ 2918 11.2. SUIT Parameters 2919 +-------+------------------+ 2920 | Label | Name | 2921 +-------+------------------+ 2922 | 1 | Vendor ID | 2923 | | | 2924 | 2 | Class ID | 2925 | | | 2926 | 3 | Image Digest | 2927 | | | 2928 | 4 | Use Before | 2929 | | | 2930 | 5 | Component Offset | 2931 | | | 2932 | 12 | Strict Order | 2933 | | | 2934 | 13 | Soft Failure | 2935 | | | 2936 | 14 | Image Size | 2937 | | | 2938 | 18 | Encryption Info | 2939 | | | 2940 | 19 | Compression Info | 2941 | | | 2942 | 20 | Unpack Info | 2943 | | | 2944 | 21 | URI | 2945 | | | 2946 | 22 | Source Component | 2947 | | | 2948 | 23 | Run Args | 2949 | | | 2950 | 24 | Device ID | 2951 | | | 2952 | 26 | Minimum Battery | 2953 | | | 2954 | 27 | Update Priority | 2955 | | | 2956 | 28 | Version | 2957 | | | 2958 | 29 | Wait Info | 2959 | | | 2960 | 30 | URI List | 2961 | | | 2962 | 31 | Component Index | 2963 | | | 2964 | nint | Custom | 2965 +-------+------------------+ 2967 11.3. SUIT Text Values 2969 +-------+----------------------+ 2970 | Label | Name | 2971 +-------+----------------------+ 2972 | 1 | Manifest Description | 2973 | | | 2974 | 2 | Update Description | 2975 | | | 2976 | 3 | Manifest JSON Source | 2977 | | | 2978 | 4 | Manifest YAML Source | 2979 | | | 2980 | nint | Custom | 2981 +-------+----------------------+ 2983 11.4. SUIT Component Text Values 2985 +-------+----------------------------+ 2986 | Label | Name | 2987 +-------+----------------------------+ 2988 | 1 | Vendor Name | 2989 | | | 2990 | 2 | Model Name | 2991 | | | 2992 | 3 | Vendor Domain | 2993 | | | 2994 | 4 | Model Info | 2995 | | | 2996 | 5 | Component Description | 2997 | | | 2998 | 6 | Component Version | 2999 | | | 3000 | 7 | Component Version Required | 3001 | | | 3002 | nint | Custom | 3003 +-------+----------------------------+ 3005 11.5. SUIT Algorithm Identifiers 3007 11.5.1. SUIT Digest Algorithm Identifiers 3008 +-------+----------+ 3009 | Label | Name | 3010 +-------+----------+ 3011 | 1 | SHA224 | 3012 | | | 3013 | 2 | SHA256 | 3014 | | | 3015 | 3 | SHA384 | 3016 | | | 3017 | 4 | SHA512 | 3018 | | | 3019 | 5 | SHA3-224 | 3020 | | | 3021 | 6 | SHA3-256 | 3022 | | | 3023 | 7 | SHA3-384 | 3024 | | | 3025 | 8 | SHA3-512 | 3026 +-------+----------+ 3028 11.5.2. SUIT Compression Algorithm Identifiers 3030 +-------+--------+ 3031 | Label | Name | 3032 +-------+--------+ 3033 | 1 | zlib | 3034 | | | 3035 | 2 | Brotli | 3036 | | | 3037 | 3 | zstd | 3038 +-------+--------+ 3040 11.5.3. Unpack Algorithms 3042 +-------+------+ 3043 | Label | Name | 3044 +-------+------+ 3045 | 1 | HEX | 3046 | | | 3047 | 2 | ELF | 3048 | | | 3049 | 3 | COFF | 3050 | | | 3051 | 4 | SREC | 3052 +-------+------+ 3054 12. Security Considerations 3056 This document is about a manifest format describing and protecting 3057 firmware images and as such it is part of a larger solution for 3058 offering a standardized way of delivering firmware updates to IoT 3059 devices. A detailed security treatment can be found in the 3060 architecture [I-D.ietf-suit-architecture] and in the information 3061 model [I-D.ietf-suit-information-model] documents. 3063 13. Acknowledgements 3065 We would like to thank the following persons for their support in 3066 designing this mechanism: 3068 - Milosch Meriac 3070 - Geraint Luff 3072 - Dan Ros 3074 - John-Paul Stanford 3076 - Hugo Vincent 3078 - Carsten Bormann 3080 - Oeyvind Roenningstad 3082 - Frank Audun Kvamtroe 3084 - Krzysztof Chruściński 3086 - Andrzej Puzdrowski 3088 - Michael Richardson 3090 - David Brown 3092 - Emmanuel Baccelli 3094 14. References 3096 14.1. Normative References 3098 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3099 Requirement Levels", BCP 14, RFC 2119, 3100 DOI 10.17487/RFC2119, March 1997, 3101 . 3103 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3104 Resource Identifier (URI): Generic Syntax", STD 66, 3105 RFC 3986, DOI 10.17487/RFC3986, January 2005, 3106 . 3108 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 3109 Unique IDentifier (UUID) URN Namespace", RFC 4122, 3110 DOI 10.17487/RFC4122, July 2005, 3111 . 3113 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 3114 RFC 8152, DOI 10.17487/RFC8152, July 2017, 3115 . 3117 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3118 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3119 May 2017, . 3121 14.2. Informative References 3123 [COFF] Wikipedia, ., "Common Object File Format (COFF)", 2020, 3124 . 3126 [ELF] Wikipedia, ., "Executable and Linkable Format (ELF)", 3127 2020, . 3130 [HEX] Wikipedia, ., "Intel HEX", 2020, 3131 . 3133 [I-D.ietf-suit-architecture] 3134 Moran, B., Tschofenig, H., Brown, D., and M. Meriac, "A 3135 Firmware Update Architecture for Internet of Things", 3136 draft-ietf-suit-architecture-11 (work in progress), May 3137 2020. 3139 [I-D.ietf-suit-information-model] 3140 Moran, B., Tschofenig, H., and H. Birkholz, "An 3141 Information Model for Firmware Updates in IoT Devices", 3142 draft-ietf-suit-information-model-07 (work in progress), 3143 June 2020. 3145 [I-D.ietf-teep-architecture] 3146 Pei, M., Tschofenig, H., Thaler, D., and D. Wheeler, 3147 "Trusted Execution Environment Provisioning (TEEP) 3148 Architecture", draft-ietf-teep-architecture-11 (work in 3149 progress), July 2020. 3151 [I-D.kucherawy-rfc8478bis] 3152 Collet, Y. and M. Kucherawy, "Zstandard Compression and 3153 the application/zstd Media Type", draft-kucherawy- 3154 rfc8478bis-05 (work in progress), April 2020. 3156 [RFC1950] Deutsch, P. and J-L. Gailly, "ZLIB Compressed Data Format 3157 Specification version 3.3", RFC 1950, 3158 DOI 10.17487/RFC1950, May 1996, 3159 . 3161 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 3162 Constrained-Node Networks", RFC 7228, 3163 DOI 10.17487/RFC7228, May 2014, 3164 . 3166 [RFC7932] Alakuijala, J. and Z. Szabadka, "Brotli Compressed Data 3167 Format", RFC 7932, DOI 10.17487/RFC7932, July 2016, 3168 . 3170 [RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, 3171 "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, 3172 May 2018, . 3174 [RFC8747] Jones, M., Seitz, L., Selander, G., Erdtman, S., and H. 3175 Tschofenig, "Proof-of-Possession Key Semantics for CBOR 3176 Web Tokens (CWTs)", RFC 8747, DOI 10.17487/RFC8747, March 3177 2020, . 3179 [SREC] Wikipedia, ., "SREC (file format)", 2020, 3180 . 3182 14.3. URIs 3184 [1] suit-condition-update-authorized 3186 A. Full CDDL 3188 In order to create a valid SUIT Manifest document the structure of 3189 the corresponding CBOR message MUST adhere to the following CDDL data 3190 definition. 3192 SUIT_Envelope = { 3193 ? suit-delegation => bstr .cbor SUIT_Delegation, 3194 ? suit-authentication-wrapper => bstr .cbor SUIT_Authentication, 3195 suit-manifest => bstr .cbor SUIT_Manifest, 3196 SUIT_Severable_Manifest_Members, 3197 * $$SUIT_Envelope_Extensions, 3198 (int => bstr) 3199 } 3201 SUIT_Delegation = [ + [ + bstr .cbor CWT ] ] 3203 CWT = SUIT_Authentication_Block 3205 SUIT_Authentication = [ + bstr .cbor SUIT_Authentication_Block ] 3207 SUIT_Authentication_Block /= COSE_Mac_Tagged 3208 SUIT_Authentication_Block /= COSE_Sign_Tagged 3209 SUIT_Authentication_Block /= COSE_Mac0_Tagged 3210 SUIT_Authentication_Block /= COSE_Sign1_Tagged 3212 SUIT_Severable_Manifest_Members = ( 3213 ? suit-dependency-resolution => bstr .cbor SUIT_Command_Sequence, 3214 ? suit-payload-fetch => bstr .cbor SUIT_Command_Sequence, 3215 ? suit-install => bstr .cbor SUIT_Command_Sequence, 3216 ? suit-text => bstr .cbor SUIT_Text_Map, 3217 ? suit-coswid => bstr .cbor concise-software-identity, 3218 * $$SUIT_severable-members-extensions, 3219 ) 3221 COSE_Mac_Tagged = any 3222 COSE_Sign_Tagged = any 3223 COSE_Mac0_Tagged = any 3224 COSE_Sign1_Tagged = any 3225 COSE_Encrypt_Tagged = any 3226 COSE_Encrypt0_Tagged = any 3228 SUIT_Digest = [ 3229 suit-digest-algorithm-id : suit-digest-algorithm-ids, 3230 suit-digest-bytes : bstr, 3231 * $$SUIT_Digest-extensions 3232 ] 3233 ; Named Information Hash Algorithm Identifiers 3234 suit-digest-algorithm-ids /= algorithm-id-sha224 3235 suit-digest-algorithm-ids /= algorithm-id-sha256 3236 suit-digest-algorithm-ids /= algorithm-id-sha384 3237 suit-digest-algorithm-ids /= algorithm-id-sha512 3238 suit-digest-algorithm-ids /= algorithm-id-sha3-224 3239 suit-digest-algorithm-ids /= algorithm-id-sha3-256 3240 suit-digest-algorithm-ids /= algorithm-id-sha3-384 3241 suit-digest-algorithm-ids /= algorithm-id-sha3-512 3243 algorithm-id-sha224 = 1 3244 algorithm-id-sha256 = 2 3245 algorithm-id-sha384 = 3 3246 algorithm-id-sha512 = 4 3247 algorithm-id-sha3-224 = 5 3248 algorithm-id-sha3-256 = 6 3249 algorithm-id-sha3-384 = 7 3250 algorithm-id-sha3-512 = 8 3252 SUIT_Manifest = { 3253 suit-manifest-version => 1, 3254 suit-manifest-sequence-number => uint, 3255 suit-common => bstr .cbor SUIT_Common, 3256 ? suit-reference-uri => tstr, 3257 SUIT_Severable_Members, 3258 SUIT_Severable_Members_Digests, 3259 SUIT_Unseverable_Members, 3260 * $$SUIT_Manifest_Extensions, 3261 } 3263 SUIT_Unseverable_Members = ( 3264 ? suit-validate => bstr .cbor SUIT_Command_Sequence, 3265 ? suit-load => bstr .cbor SUIT_Command_Sequence, 3266 ? suit-run => bstr .cbor SUIT_Command_Sequence, 3267 * $$unserverble-manifest-member-extensions, 3268 ) 3270 SUIT_Severable_Members_Digests = ( 3271 ? suit-dependency-resolution-digest => SUIT_Digest, 3272 ? suit-payload-fetch-digest => SUIT_Digest, 3273 ? suit-install-digest => SUIT_Digest, 3274 ? suit-text-digest => SUIT_Digest, 3275 ? suit-coswid-digest => SUIT_Digest, 3276 * $$severable-manifest-members-digests-extensions 3277 ) 3279 SUIT_Common = { 3280 ? suit-dependencies => SUIT_Dependencies, 3281 ? suit-components => SUIT_Components, 3282 ? suit-common-sequence => bstr .cbor SUIT_Common_Sequence, 3283 * $$SUIT_Common-extensions, 3284 } 3286 SUIT_Dependencies = [ + SUIT_Dependency ] 3287 SUIT_Components = [ + SUIT_Component_Identifier ] 3289 concise-software-identity = any 3291 SUIT_Dependency = { 3292 suit-dependency-digest => SUIT_Digest, 3293 ? suit-dependency-prefix => SUIT_Component_Identifier, 3294 * $$SUIT_Dependency-extensions, 3295 } 3297 SUIT_Component_Identifier = [* bstr] 3299 SUIT_Component_Reference = { 3300 suit-component-identifier => SUIT_Component_Identifier, 3301 suit-component-dependency-index => uint 3302 } 3304 SUIT_Common_Sequence = [ 3305 + ( SUIT_Condition // SUIT_Common_Commands ) 3306 ] 3308 SUIT_Common_Commands //= (suit-directive-set-component-index, uint/bool) 3309 SUIT_Common_Commands //= (suit-directive-set-dependency-index, uint/bool) 3310 SUIT_Common_Commands //= (suit-directive-run-sequence, 3311 bstr .cbor SUIT_Command_Sequence) 3312 SUIT_Common_Commands //= (suit-directive-try-each, 3313 SUIT_Directive_Try_Each_Argument) 3314 SUIT_Common_Commands //= (suit-directive-set-parameters, 3315 {+ SUIT_Parameters}) 3316 SUIT_Common_Commands //= (suit-directive-override-parameters, 3317 {+ SUIT_Parameters}) 3319 SUIT_Command_Sequence = [ + ( 3320 SUIT_Condition // SUIT_Directive // SUIT_Command_Custom 3321 ) ] 3323 SUIT_Command_Custom = (suit-command-custom, bstr/tstr/int/nil) 3324 SUIT_Condition //= (suit-condition-vendor-identifier, SUIT_Reporting_Policy) 3325 SUIT_Condition //= (suit-condition-class-identifier, SUIT_Reporting_Policy) 3326 SUIT_Condition //= (suit-condition-device-identifier, SUIT_Reporting_Policy) 3327 SUIT_Condition //= (suit-condition-image-match, SUIT_Reporting_Policy) 3328 SUIT_Condition //= (suit-condition-image-not-match, SUIT_Reporting_Policy) 3329 SUIT_Condition //= (suit-condition-use-before, SUIT_Reporting_Policy) 3330 SUIT_Condition //= (suit-condition-minimum-battery, SUIT_Reporting_Policy) 3331 SUIT_Condition //= (suit-condition-update-authorized, SUIT_Reporting_Policy) 3332 SUIT_Condition //= (suit-condition-version, SUIT_Reporting_Policy) 3333 SUIT_Condition //= (suit-condition-component-offset, SUIT_Reporting_Policy) 3335 SUIT_Directive //= (suit-directive-set-component-index, uint/bool) 3336 SUIT_Directive //= (suit-directive-set-dependency-index, uint/bool) 3337 SUIT_Directive //= (suit-directive-run-sequence, 3338 bstr .cbor SUIT_Command_Sequence) 3339 SUIT_Directive //= (suit-directive-try-each, 3340 SUIT_Directive_Try_Each_Argument) 3341 SUIT_Directive //= (suit-directive-process-dependency, SUIT_Reporting_Policy) 3342 SUIT_Directive //= (suit-directive-set-parameters, 3343 {+ SUIT_Parameters}) 3344 SUIT_Directive //= (suit-directive-override-parameters, 3345 {+ SUIT_Parameters}) 3346 SUIT_Directive //= (suit-directive-fetch, SUIT_Reporting_Policy) 3347 SUIT_Directive //= (suit-directive-copy, SUIT_Reporting_Policy) 3348 SUIT_Directive //= (suit-directive-swap, SUIT_Reporting_Policy) 3349 SUIT_Directive //= (suit-directive-run, SUIT_Reporting_Policy) 3350 SUIT_Directive //= (suit-directive-wait, SUIT_Reporting_Policy) 3351 SUIT_Directive //= (suit-directive-abort, SUIT_Reporting_Policy) 3352 SUIT_Directive //= (suit-directive-fetch-uri-list, SUIT_Reporting_Policy) 3354 SUIT_Directive_Try_Each_Argument = [ 3355 + bstr .cbor SUIT_Command_Sequence, 3356 nil / bstr .cbor SUIT_Command_Sequence 3357 ] 3359 SUIT_Reporting_Policy = uint .bits suit-reporting-bits 3361 suit-reporting-bits = &( 3362 suit-send-record-success : 0, 3363 suit-send-record-failure : 1, 3364 suit-send-sysinfo-success : 2, 3365 suit-send-sysinfo-failure : 3 3366 ) 3368 SUIT_Command_ID /= suit-command-custom 3369 SUIT_Command_ID /= suit-condition-vendor-identifier 3370 SUIT_Command_ID /= suit-condition-class-identifier 3371 SUIT_Command_ID /= suit-condition-image-match 3372 SUIT_Command_ID /= suit-condition-use-before 3373 SUIT_Command_ID /= suit-condition-component-offset 3374 SUIT_Command_ID /= suit-condition-device-identifier 3375 SUIT_Command_ID /= suit-condition-image-not-match 3376 SUIT_Command_ID /= suit-condition-minimum-battery 3377 SUIT_Command_ID /= suit-condition-update-authorized 3378 SUIT_Command_ID /= suit-condition-version 3379 SUIT_Command_ID /= suit-directive-set-component-index 3380 SUIT_Command_ID /= suit-directive-set-dependency-index 3381 SUIT_Command_ID /= suit-directive-abort 3382 SUIT_Command_ID /= suit-directive-try-each 3383 ;SUIT_Command_ID /= suit-directive-do-each 3384 ;SUIT_Command_ID /= suit-directive-map-filter 3385 SUIT_Command_ID /= suit-directive-process-dependency 3386 SUIT_Command_ID /= suit-directive-set-parameters 3387 SUIT_Command_ID /= suit-directive-override-parameters 3388 SUIT_Command_ID /= suit-directive-fetch 3389 SUIT_Command_ID /= suit-directive-copy 3390 SUIT_Command_ID /= suit-directive-run 3391 SUIT_Command_ID /= suit-directive-wait 3392 SUIT_Command_ID /= suit-directive-run-sequence 3393 SUIT_Command_ID /= suit-directive-swap 3394 SUIT_Command_ID /= suit-directive-fetch-uri-list 3396 suit-record = { 3397 suit-record-success => bool/int, 3398 ? suit-record-component-id => SUIT_Component_ID, 3399 ? suit-record-dependency-id => SUIT_Digest, 3400 ? suit-record-command-sequence-id => ( 3401 suit-common-sequence / 3402 suit-dependency-resolution / 3403 suit-payload-fetch / 3404 suit-install / 3405 suit-validate / 3406 suit-load / 3407 suit-run / 3408 * $$suit-command-sequence-list-extensions 3409 ), 3410 ? suit-record-interpeter-offset => uint, 3411 ? suit-record-command-id => SUIT_Command_ID, 3412 ? suit-record-params => SUIT_Parameters, 3413 ? suit-record-actual => SUIT_Parameters, 3414 * $$suit-record-extensions 3415 } 3417 SUIT_Wait_Event = { + SUIT_Wait_Events } 3419 SUIT_Wait_Events //= (suit-wait-event-authorization => int) 3420 SUIT_Wait_Events //= (suit-wait-event-power => int) 3421 SUIT_Wait_Events //= (suit-wait-event-network => int) 3422 SUIT_Wait_Events //= (suit-wait-event-other-device-version 3423 => SUIT_Wait_Event_Argument_Other_Device_Version) 3424 SUIT_Wait_Events //= (suit-wait-event-time => uint); Timestamp 3425 SUIT_Wait_Events //= (suit-wait-event-time-of-day 3426 => uint); Time of Day (seconds since 00:00:00) 3427 SUIT_Wait_Events //= (suit-wait-event-day-of-week 3428 => uint); Days since Sunday 3430 SUIT_Wait_Event_Argument_Other_Device_Version = [ 3431 other-device: bstr, 3432 other-device-version: [ + SUIT_Parameter_Version_Match ] 3433 ] 3435 SUIT_Parameters //= (suit-parameter-vendor-identifier => RFC4122_UUID) 3436 SUIT_Parameters //= (suit-parameter-class-identifier => RFC4122_UUID) 3437 SUIT_Parameters //= (suit-parameter-image-digest 3438 => bstr .cbor SUIT_Digest) 3439 SUIT_Parameters //= (suit-parameter-image-size => uint) 3440 SUIT_Parameters //= (suit-parameter-use-before => uint) 3441 SUIT_Parameters //= (suit-parameter-component-offset => uint) 3443 SUIT_Parameters //= (suit-parameter-encryption-info 3444 => bstr .cbor SUIT_Encryption_Info) 3445 SUIT_Parameters //= (suit-parameter-compression-info 3446 => bstr .cbor SUIT_Compression_Info) 3447 SUIT_Parameters //= (suit-parameter-unpack-info 3448 => bstr .cbor SUIT_Unpack_Info) 3450 SUIT_Parameters //= (suit-parameter-uri => tstr) 3451 SUIT_Parameters //= (suit-parameter-source-component => uint) 3452 SUIT_Parameters //= (suit-parameter-run-args => bstr) 3454 SUIT_Parameters //= (suit-parameter-device-identifier => RFC4122_UUID) 3455 SUIT_Parameters //= (suit-parameter-minimum-battery => uint) 3456 SUIT_Parameters //= (suit-parameter-update-priority => uint) 3457 SUIT_Parameters //= (suit-parameter-version => 3458 SUIT_Parameter_Version_Match) 3459 SUIT_Parameters //= (suit-parameter-wait-info => 3460 bstr .cbor SUIT_Wait_Event) 3462 SUIT_Parameters //= (suit-parameter-custom => int/bool/tstr/bstr) 3464 SUIT_Parameters //= (suit-parameter-strict-order => bool) 3465 SUIT_Parameters //= (suit-parameter-soft-failure => bool) 3467 SUIT_Parameters //= (suit-parameter-uri-list => 3468 bstr .cbor SUIT_URI_List) 3470 RFC4122_UUID = bstr .size 16 3471 SUIT_Parameter_Version_Match = [ 3472 suit-condition-version-comparison-type: 3473 SUIT_Condition_Version_Comparison_Types, 3474 suit-condition-version-comparison-value: 3475 SUIT_Condition_Version_Comparison_Value 3476 ] 3477 SUIT_Condition_Version_Comparison_Types /= 3478 suit-condition-version-comparison-greater 3479 SUIT_Condition_Version_Comparison_Types /= 3480 suit-condition-version-comparison-greater-equal 3481 SUIT_Condition_Version_Comparison_Types /= 3482 suit-condition-version-comparison-equal 3483 SUIT_Condition_Version_Comparison_Types /= 3484 suit-condition-version-comparison-lesser-equal 3485 SUIT_Condition_Version_Comparison_Types /= 3486 suit-condition-version-comparison-lesser 3488 suit-condition-version-comparison-greater = 1 3489 suit-condition-version-comparison-greater-equal = 2 3490 suit-condition-version-comparison-equal = 3 3491 suit-condition-version-comparison-lesser-equal = 4 3492 suit-condition-version-comparison-lesser = 5 3494 SUIT_Condition_Version_Comparison_Value = [+int] 3496 SUIT_Encryption_Info = COSE_Encrypt_Tagged/COSE_Encrypt0_Tagged 3497 SUIT_Compression_Info = { 3498 suit-compression-algorithm => SUIT_Compression_Algorithms, 3499 * $$SUIT_Compression_Info-extensions, 3500 } 3502 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_zlib 3503 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_brotli 3504 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_zstd 3506 SUIT_Compression_Algorithm_zlib = 1 3507 SUIT_Compression_Algorithm_brotli = 2 3508 SUIT_Compression_Algorithm_zstd = 3 3510 SUIT_Unpack_Info = { 3511 suit-unpack-algorithm => SUIT_Unpack_Algorithms, 3512 * $$SUIT_Unpack_Info-extensions, 3514 } 3516 SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Hex 3517 SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Elf 3518 SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Coff 3519 SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Srec 3521 SUIT_Unpack_Algorithm_Hex = 1 3522 SUIT_Unpack_Algorithm_Elf = 2 3523 SUIT_Unpack_Algorithm_Coff = 3 3524 SUIT_Unpack_Algorithm_Srec = 4 3526 SUIT_URI_List = [+ tstr ] 3528 SUIT_Text_Map = { 3529 ? suit-text-components => 3530 [ 3531 + { 3532 1 => SUIT_Component_Identifier 3533 SUIT_Text_Component_Keys 3534 } 3535 ], 3536 SUIT_Text_Keys 3537 } 3539 SUIT_Text_Component_Keys = ( 3540 ? suit-text-vendor-name => tstr, 3541 ? suit-text-model-name => tstr, 3542 ? suit-text-vendor-domain => tstr, 3543 ? suit-text-model-info => tstr, 3544 ? suit-text-component-description => tstr, 3545 ? suit-text-component-version => tstr, 3546 ? suit-text-version-required => tstr, 3547 * $$suit-text-component-key-extensions 3548 ) 3550 SUIT_Text_Keys = ( 3551 ? suit-text-manifest-description => tstr, 3552 ? suit-text-update-description => tstr, 3553 ? suit-text-manifest-json-source => tstr, 3554 ? suit-text-manifest-yaml-source => tstr, 3555 * $$suit-text-key-extensions 3556 ) 3558 suit-delegation = 1 3559 suit-authentication-wrapper = 2 3560 suit-manifest = 3 3562 suit-manifest-version = 1 3563 suit-manifest-sequence-number = 2 3564 suit-common = 3 3565 suit-reference-uri = 4 3566 suit-dependency-resolution = 7 3567 suit-payload-fetch = 8 3568 suit-install = 9 3569 suit-validate = 10 3570 suit-load = 11 3571 suit-run = 12 3572 suit-text = 13 3573 suit-coswid = 14 3575 suit-dependencies = 1 3576 suit-components = 2 3577 suit-dependency-components = 3 3578 suit-common-sequence = 4 3580 suit-dependency-digest = 1 3581 suit-dependency-prefix = 2 3583 suit-component-identifier = 1 3584 suit-component-dependency-index = 2 3586 suit-command-custom = nint 3588 suit-condition-vendor-identifier = 1 3589 suit-condition-class-identifier = 2 3590 suit-condition-image-match = 3 3591 suit-condition-use-before = 4 3592 suit-condition-component-offset = 5 3594 suit-condition-device-identifier = 24 3595 suit-condition-image-not-match = 25 3596 suit-condition-minimum-battery = 26 3597 suit-condition-update-authorized = 27 3598 suit-condition-version = 28 3600 suit-directive-set-component-index = 12 3601 suit-directive-set-dependency-index = 13 3602 suit-directive-abort = 14 3603 suit-directive-try-each = 15 3604 ;suit-directive-do-each = 16 ; TBD 3605 ;suit-directive-map-filter = 17 ; TBD 3606 suit-directive-process-dependency = 18 3607 suit-directive-set-parameters = 19 3608 suit-directive-override-parameters = 20 3609 suit-directive-fetch = 21 3610 suit-directive-copy = 22 3611 suit-directive-run = 23 3613 suit-directive-wait = 29 3614 suit-directive-fetch-uri-list = 30 3615 suit-directive-swap = 31 3616 suit-directive-run-sequence = 32 3618 suit-wait-event-authorization = 1 3619 suit-wait-event-power = 2 3620 suit-wait-event-network = 3 3621 suit-wait-event-other-device-version = 4 3622 suit-wait-event-time = 5 3623 suit-wait-event-time-of-day = 6 3624 suit-wait-event-day-of-week = 7 3626 suit-parameter-vendor-identifier = 1 3627 suit-parameter-class-identifier = 2 3628 suit-parameter-image-digest = 3 3629 suit-parameter-use-before = 4 3630 suit-parameter-component-offset = 5 3632 suit-parameter-strict-order = 12 3633 suit-parameter-soft-failure = 13 3634 suit-parameter-image-size = 14 3636 suit-parameter-encryption-info = 18 3637 suit-parameter-compression-info = 19 3638 suit-parameter-unpack-info = 20 3639 suit-parameter-uri = 21 3640 suit-parameter-source-component = 22 3641 suit-parameter-run-args = 23 3643 suit-parameter-device-identifier = 24 3644 suit-parameter-minimum-battery = 26 3645 suit-parameter-update-priority = 27 3646 suit-parameter-version = 28 3647 suit-parameter-wait-info = 29 3648 suit-parameter-uri-list = 30 3650 suit-parameter-custom = nint 3652 suit-compression-algorithm = 1 3653 suit-compression-parameters = 2 3655 suit-unpack-algorithm = 1 3656 suit-unpack-parameters = 2 3658 suit-text-manifest-description = 1 3659 suit-text-update-description = 2 3660 suit-text-manifest-json-source = 3 3661 suit-text-manifest-yaml-source = 4 3662 suit-text-vendor-name = 1 3663 suit-text-model-name = 2 3664 suit-text-vendor-domain = 3 3665 suit-text-model-info = 4 3666 suit-text-component-description = 5 3667 suit-text-component-version = 6 3668 suit-text-version-required = 7 3670 B. Examples 3672 The following examples demonstrate a small subset of the 3673 functionality of the manifest. However, despite this, even a simple 3674 manifest processor can execute most of these manifests. 3676 The examples are signed using the following ECDSA secp256r1 key: 3678 -----BEGIN PRIVATE KEY----- 3679 MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgApZYjZCUGLM50VBC 3680 CjYStX+09jGmnyJPrpDLTz/hiXOhRANCAASEloEarguqq9JhVxie7NomvqqL8Rtv 3681 P+bitWWchdvArTsfKktsCYExwKNtrNHXi9OB3N+wnAUtszmR23M4tKiW 3682 -----END PRIVATE KEY----- 3684 The corresponding public key can be used to verify these examples: 3686 -----BEGIN PUBLIC KEY----- 3687 MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEhJaBGq4LqqvSYVcYnuzaJr6qi/Eb 3688 bz/m4rVlnIXbwK07HypLbAmBMcCjbazR14vTgdzfsJwFLbM5kdtzOLSolg== 3689 -----END PUBLIC KEY----- 3691 Each example uses SHA256 as the digest function. 3693 Note that reporting policies are declared for each non-flow-control 3694 command in these examples. The reporting policies used in the 3695 examples are described in the following tables. 3697 +-----------------------------+----------+ 3698 | Policy | Label | 3699 +-----------------------------+----------+ 3700 | suit-send-record-on-success | Rec-Pass | 3701 | | | 3702 | suit-send-record-on-failure | Rec-Fail | 3703 | | | 3704 | suit-send-sysinfo-success | Sys-Pass | 3705 | | | 3706 | suit-send-sysinfo-failure | Sys-Fail | 3707 +-----------------------------+----------+ 3709 +----------------------------+--------+---------+---------+---------+ 3710 | Command | Sys- | Sys- | Rec- | Rec- | 3711 | | Fail | Pass | Fail | Pass | 3712 +----------------------------+--------+---------+---------+---------+ 3713 | suit-condition-vendor- | 1 | 1 | 1 | 1 | 3714 | identifier | | | | | 3715 | | | | | | 3716 | suit-condition-class- | 1 | 1 | 1 | 1 | 3717 | identifier | | | | | 3718 | | | | | | 3719 | suit-condition-image-match | 1 | 1 | 1 | 1 | 3720 | | | | | | 3721 | suit-condition-component- | 0 | 1 | 0 | 1 | 3722 | offset | | | | | 3723 | | | | | | 3724 | suit-directive-fetch | 0 | 0 | 1 | 0 | 3725 | | | | | | 3726 | suit-directive-copy | 0 | 0 | 1 | 0 | 3727 | | | | | | 3728 | suit-directive-run | 0 | 0 | 1 | 0 | 3729 +----------------------------+--------+---------+---------+---------+ 3731 B.1. Example 0: Secure Boot 3733 This example covers the following templates: 3735 - Compatibility Check (Section 7.1) 3737 - Secure Boot (Section 7.2) 3739 It also serves as the minimum example. 3741 { 3742 / authentication-wrapper / 2:h'81588fd28443a10126a0584482025840356 3743 3303937656636346266336262396234393465373165316632343138656566386434363 3744 6636339303266363339613835356563396166336539656464623939584093347ceebc1 3745 209a2d660bfbbe78e461079f1952c614e1ae8f734ff0ea438110d056c1a0cce6b0599d 3746 b54e6704847de49efe60e9a7b821215d83368a2c8c7c088' / [ 3747 h'd28443a10126a05844820258403563303937656636346266336262396234 3748 3934653731653166323431386565663864343636636339303266363339613835356563 3749 396166336539656464623939584093347ceebc1209a2d660bfbbe78e461079f1952c61 3750 4e1ae8f734ff0ea438110d056c1a0cce6b0599db54e6704847de49efe60e9a7b821215 3751 d83368a2c8c7c088' / 18([ 3752 / protected / h'a10126' / { 3753 / alg / 1:-7 / "ES256" /, 3754 } /, 3755 / unprotected / { 3756 }, 3757 / payload / h'8202584035633039376566363462663362623962 3758 3439346537316531663234313865656638643436366363393032663633396138353565 3759 63396166336539656464623939' / [ 3760 / algorithm-id / 2 / "sha256" /, 3761 / digest-bytes / h'3563303937656636346266336262396 3762 2343934653731653166323431386565663864343636636339303266363339613835356 3763 563396166336539656464623939' 3764 ] /, 3765 / signature / h'93347ceebc1209a2d660bfbbe78e461079f195 3766 2c614e1ae8f734ff0ea438110d056c1a0cce6b0599db54e6704847de49efe60e9a7b82 3767 1215d83368a2c8c7c088' 3768 ]) / 3769 ] /, 3770 / manifest / 3:h'a50101020003585fa202818141000458568614a40150fa6b4 3771 a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab450358248 3772 202582000112233445566778899aabbccddeeff0123456789abcdeffedcba987654321 3773 00e1987d0010f020f0a4382030f0c43821702' / { 3774 / manifest-version / 1:1, 3775 / manifest-sequence-number / 2:0, 3776 / common / 3:h'a202818141000458568614a40150fa6b4a53d5ad5fdfbe9 3777 de663e4d41ffe02501492af1425695e48bf429b2d51f2ab45035824820258200011223 3778 3445566778899aabbccddeeff0123456789abcdeffedcba98765432100e1987d0010f0 3779 20f' / { 3780 / components / 2:[ 3781 [h'00'] 3782 ], 3783 / common-sequence / 4:h'8614a40150fa6b4a53d5ad5fdfbe9de663 3784 e4d41ffe02501492af1425695e48bf429b2d51f2ab4503582482025820001122334455 3785 66778899aabbccddeeff0123456789abcdeffedcba98765432100e1987d0010f020f' 3786 / [ 3787 / directive-override-parameters / 20,{ 3788 / vendor-id / 3789 1:h'"fa6b4a53d5ad5fdfbe9de663e4d41ffe"' / fa6b4a53-d5ad-5fdf- 3790 be9d-e663e4d41ffe /, 3791 / class-id / 3792 2:h'"1492af1425695e48bf429b2d51f2ab45"' / 3793 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 3794 / image-digest / 3:h'8202582000112233445566778899a 3795 abbccddeeff0123456789abcdeffedcba9876543210' / [ 3796 / algorithm-id / 2 / "sha256" /, 3797 / digest-bytes / 3798 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 3799 ] /, 3800 / image-size / 14:34768, 3801 } , 3802 / condition-vendor-identifier / 1,15 , 3803 / condition-class-identifier / 2,15 3804 ] /, 3806 } /, 3807 / validate / 10:h'82030f' / [ 3808 / condition-image-match / 3,15 3809 ] /, 3810 / run / 12:h'821702' / [ 3811 / directive-run / 23,2 3812 ] /, 3813 } /, 3814 } 3816 Total size of Envelope without COSE authentication object: 117 3818 Envelope: 3820 a1035871a50101020003585fa202818141000458568614a40150fa6b4a53 3821 d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab45 3822 0358248202582000112233445566778899aabbccddeeff0123456789abcd 3823 effedcba98765432100e1987d0010f020f0a4382030f0c43821702 3825 Total size of Envelope with COSE authentication object: 266 3827 Envelope with COSE authentication object: 3829 a202589281588fd28443a10126a058448202584035633039376566363462 3830 663362623962343934653731653166323431386565663864343636636339 3831 303266363339613835356563396166336539656464623939584093347cee 3832 bc1209a2d660bfbbe78e461079f1952c614e1ae8f734ff0ea438110d056c 3833 1a0cce6b0599db54e6704847de49efe60e9a7b821215d83368a2c8c7c088 3834 035871a50101020003585fa202818141000458568614a40150fa6b4a53d5 3835 ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab4503 3836 58248202582000112233445566778899aabbccddeeff0123456789abcdef 3837 fedcba98765432100e1987d0010f020f0a4382030f0c43821702 3839 B.2. Example 1: Simultaneous Download and Installation of Payload 3841 This example covers the following templates: 3843 - Compatibility Check (Section 7.1) 3845 - Firmware Download (Section 7.3) 3847 Simultaneous download and installation of payload. No secure boot is 3848 present in this example to demonstrate a download-only manifest. 3850 { 3851 / authentication-wrapper / 2:h'81588fd28443a10126a0584482025840393 3852 8376565633835666139396664333164333332333831623938313066393062303563326 3853 530643466323834613666343231313230376564303066666637353058404931df82e15 3854 3bf1e3af5a59800216d8a47c33a37839e7d63d9f526fd369aa8359daae18f7619c9591 3855 23e7f7f928ee92a9893afedd35d06a936d6ed3d5843bf2a' / [ 3856 h'd28443a10126a05844820258403938376565633835666139396664333164 3857 3333323338316239383130663930623035633265306434663238346136663432313132 3858 30376564303066666637353058404931df82e153bf1e3af5a59800216d8a47c33a3783 3859 9e7d63d9f526fd369aa8359daae18f7619c959123e7f7f928ee92a9893afedd35d06a9 3860 36d6ed3d5843bf2a' / 18([ 3861 / protected / h'a10126' / { 3862 / alg / 1:-7 / "ES256" /, 3863 } /, 3864 / unprotected / { 3865 }, 3866 / payload / h'8202584039383765656338356661393966643331 3867 6433333233383162393831306639306230356332653064346632383461366634323131 3868 32303765643030666666373530' / [ 3869 / algorithm-id / 2 / "sha256" /, 3870 / digest-bytes / h'3938376565633835666139396664333 3871 1643333323338316239383130663930623035633265306434663238346136663432313 3872 132303765643030666666373530' 3873 ] /, 3874 / signature / h'4931df82e153bf1e3af5a59800216d8a47c33a 3875 37839e7d63d9f526fd369aa8359daae18f7619c959123e7f7f928ee92a9893afedd35d 3876 06a936d6ed3d5843bf2a' 3877 ]) / 3878 ] /, 3879 / manifest / 3:h'a50101020103585fa202818141000458568614a40150fa6b4 3880 a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab450358248 3881 202582000112233445566778899aabbccddeeff0123456789abcdeffedcba987654321 3882 00e1987d0010f020f0958258613a115781b687474703a2f2f6578616d706c652e636f6 3883 d2f66696c652e62696e1502030f0a4382030f' / { 3884 / manifest-version / 1:1, 3885 / manifest-sequence-number / 2:1, 3886 / common / 3:h'a202818141000458568614a40150fa6b4a53d5ad5fdfbe9 3887 de663e4d41ffe02501492af1425695e48bf429b2d51f2ab45035824820258200011223 3888 3445566778899aabbccddeeff0123456789abcdeffedcba98765432100e1987d0010f0 3889 20f' / { 3890 / components / 2:[ 3891 [h'00'] 3892 ], 3893 / common-sequence / 4:h'8614a40150fa6b4a53d5ad5fdfbe9de663 3894 e4d41ffe02501492af1425695e48bf429b2d51f2ab4503582482025820001122334455 3895 66778899aabbccddeeff0123456789abcdeffedcba98765432100e1987d0010f020f' 3896 / [ 3897 / directive-override-parameters / 20,{ 3898 / vendor-id / 3899 1:h'"fa6b4a53d5ad5fdfbe9de663e4d41ffe"' / fa6b4a53-d5ad-5fdf- 3900 be9d-e663e4d41ffe /, 3901 / class-id / 3903 2:h'"1492af1425695e48bf429b2d51f2ab45"' / 3904 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 3905 / image-digest / 3:h'8202582000112233445566778899a 3906 abbccddeeff0123456789abcdeffedcba9876543210' / [ 3907 / algorithm-id / 2 / "sha256" /, 3908 / digest-bytes / 3909 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 3910 ] /, 3911 / image-size / 14:34768, 3912 } , 3913 / condition-vendor-identifier / 1,15 , 3914 / condition-class-identifier / 2,15 3915 ] /, 3916 } /, 3917 / install / 9:h'8613a115781b687474703a2f2f6578616d706c652e636f 3918 6d2f66696c652e62696e1502030f' / [ 3919 / directive-set-parameters / 19,{ 3920 / uri / 21:'http://example.com/file.bin', 3921 } , 3922 / directive-fetch / 21,2 , 3923 / condition-image-match / 3,15 3924 ] /, 3925 / validate / 10:h'82030f' / [ 3926 / condition-image-match / 3,15 3927 ] /, 3928 } /, 3929 } 3931 Total size of Envelope without COSE authentication object: 152 3933 Envelope: 3935 a1035894a50101020103585fa202818141000458568614a40150fa6b4a53 3936 d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab45 3937 0358248202582000112233445566778899aabbccddeeff0123456789abcd 3938 effedcba98765432100e1987d0010f020f0958258613a115781b68747470 3939 3a2f2f6578616d706c652e636f6d2f66696c652e62696e1502030f0a4382 3940 030f 3942 Total size of Envelope with COSE authentication object: 301 3944 Envelope with COSE authentication object: 3946 a202589281588fd28443a10126a058448202584039383765656338356661 3947 393966643331643333323338316239383130663930623035633265306434 3948 66323834613666343231313230376564303066666637353058404931df82 3949 e153bf1e3af5a59800216d8a47c33a37839e7d63d9f526fd369aa8359daa 3950 e18f7619c959123e7f7f928ee92a9893afedd35d06a936d6ed3d5843bf2a 3951 035894a50101020103585fa202818141000458568614a40150fa6b4a53d5 3952 ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab4503 3953 58248202582000112233445566778899aabbccddeeff0123456789abcdef 3954 fedcba98765432100e1987d0010f020f0958258613a115781b687474703a 3955 2f2f6578616d706c652e636f6d2f66696c652e62696e1502030f0a438203 3956 0f 3958 B.3. Example 2: Simultaneous Download, Installation, Secure Boot, 3959 Severed Fields 3961 This example covers the following templates: 3963 - Compatibility Check (Section 7.1) 3965 - Secure Boot (Section 7.2) 3967 - Firmware Download (Section 7.3) 3969 This example also demonstrates severable elements (Section 5.5), and 3970 text (Section 8.6.4). 3972 { 3973 / authentication-wrapper / 2:h'81588fd28443a10126a0584482025840373 3974 5363835353739613833626162643731656338656632326661343961633837336637386 3975 13730386134336136373465373832616433306236353938643137615840faca70796c3 3976 19ce6dae69690a64ced3ab91b9bb7f3e9a5004122d629d2816216a870448424ce4410d 3977 658b80215185e32d8ec6feb15c7275d64437c36418463e4' / [ 3978 h'd28443a10126a05844820258403735363835353739613833626162643731 3979 6563386566323266613439616338373366373861373038613433613637346537383261 3980 6433306236353938643137615840faca70796c319ce6dae69690a64ced3ab91b9bb7f3 3981 e9a5004122d629d2816216a870448424ce4410d658b80215185e32d8ec6feb15c7275d 3982 64437c36418463e4' / 18([ 3983 / protected / h'a10126' / { 3984 / alg / 1:-7 / "ES256" /, 3985 } /, 3986 / unprotected / { 3987 }, 3988 / payload / h'8202584037353638353537396138336261626437 3989 3165633865663232666134396163383733663738613730386134336136373465373832 3990 61643330623635393864313761' / [ 3991 / algorithm-id / 2 / "sha256" /, 3992 / digest-bytes / h'3735363835353739613833626162643 3993 7316563386566323266613439616338373366373861373038613433613637346537383 3994 261643330623635393864313761' 3995 ] /, 3996 / signature / h'faca70796c319ce6dae69690a64ced3ab91b9b 3997 b7f3e9a5004122d629d2816216a870448424ce4410d658b80215185e32d8ec6feb15c7 3998 275d64437c36418463e4' 3999 ]) / 4000 ] /, 4001 / manifest / 3:h'a70101020203585fa202818141000458568614a40150fa6b4 4002 a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab450358248 4003 202582000112233445566778899aabbccddeeff0123456789abcdeffedcba987654321 4004 00e1987d0010f020f09820258203ee96dc79641970ae46b929ccf0b72ba9536dd84602 4005 0dbdc9f949d84ea0e18d20a4382030f0c438217020d8202582023f48b2e2838650f43c 4006 144234aee18401ffe3cce4733b23881c3a8ae2d2b66e8' / { 4007 / manifest-version / 1:1, 4008 / manifest-sequence-number / 2:2, 4009 / common / 3:h'a202818141000458568614a40150fa6b4a53d5ad5fdfbe9 4010 de663e4d41ffe02501492af1425695e48bf429b2d51f2ab45035824820258200011223 4011 3445566778899aabbccddeeff0123456789abcdeffedcba98765432100e1987d0010f0 4012 20f' / { 4013 / components / 2:[ 4014 [h'00'] 4015 ], 4016 / common-sequence / 4:h'8614a40150fa6b4a53d5ad5fdfbe9de663 4017 e4d41ffe02501492af1425695e48bf429b2d51f2ab4503582482025820001122334455 4018 66778899aabbccddeeff0123456789abcdeffedcba98765432100e1987d0010f020f' 4019 / [ 4020 / directive-override-parameters / 20,{ 4021 / vendor-id / 4022 1:h'"fa6b4a53d5ad5fdfbe9de663e4d41ffe"' / fa6b4a53-d5ad-5fdf- 4023 be9d-e663e4d41ffe /, 4024 / class-id / 4025 2:h'"1492af1425695e48bf429b2d51f2ab45"' / 4026 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 4027 / image-digest / 3:h'8202582000112233445566778899a 4028 abbccddeeff0123456789abcdeffedcba9876543210' / [ 4029 / algorithm-id / 2 / "sha256" /, 4030 / digest-bytes / 4031 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 4032 ] /, 4033 / image-size / 14:34768, 4034 } , 4035 / condition-vendor-identifier / 1,15 , 4036 / condition-class-identifier / 2,15 4037 ] /, 4038 } /, 4039 / install / 9:[ 4040 / algorithm-id / 2 / "sha256" /, 4041 / digest-bytes / 4043 h'3ee96dc79641970ae46b929ccf0b72ba9536dd846020dbdc9f949d84ea0e18d2' 4044 ], 4045 / validate / 10:h'82030f' / [ 4046 / condition-image-match / 3,15 4047 ] /, 4048 / run / 12:h'821702' / [ 4049 / directive-run / 23,2 4050 ] /, 4051 / text / 13:[ 4052 / algorithm-id / 2 / "sha256" /, 4053 / digest-bytes / 4054 h'23f48b2e2838650f43c144234aee18401ffe3cce4733b23881c3a8ae2d2b66e8' 4055 ], 4056 } /, 4057 / install / 9:h'8613a1157832687474703a2f2f6578616d706c652e636f6d2f 4058 766572792f6c6f6e672f706174682f746f2f66696c652f66696c652e62696e1502030f 4059 ' / [ 4060 / directive-set-parameters / 19,{ 4061 / uri / 4062 21:'http://example.com/very/long/path/to/file/file.bin', 4063 } , 4064 / directive-fetch / 21,2 , 4065 / condition-image-match / 3,15 4066 ] /, 4067 / text / 13:h'a1814100a2036761726d2e636f6d0578525468697320636f6d70 4068 6f6e656e7420697320612064656d6f6e7374726174696f6e2e20546865206469676573 4069 7420697320612073616d706c65207061747465726e2c206e6f742061207265616c206f 4070 6e652e' / { 4071 [h'00']:{ 4072 / vendor-domain / 3:'arm.com', 4073 / component-description / 5:'This component is a 4074 demonstration. The digest is a sample pattern, not a real one.', 4075 } 4076 } /, 4077 } 4079 Total size of the Envelope without COSE authentication object or 4080 Severable Elements: 191 4082 Envelope: 4084 a10358bba70101020203585fa202818141000458568614a40150fa6b4a53 4085 d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab45 4086 0358248202582000112233445566778899aabbccddeeff0123456789abcd 4087 effedcba98765432100e1987d0010f020f09820258203ee96dc79641970a 4088 e46b929ccf0b72ba9536dd846020dbdc9f949d84ea0e18d20a4382030f0c 4089 438217020d8202582023f48b2e2838650f43c144234aee18401ffe3cce47 4090 33b23881c3a8ae2d2b66e8 4091 Total size of the Envelope with COSE authentication object but 4092 without Severable Elements: 340 4094 Envelope: 4096 a202589281588fd28443a10126a058448202584037353638353537396138 4097 336261626437316563386566323266613439616338373366373861373038 4098 6134336136373465373832616433306236353938643137615840faca7079 4099 6c319ce6dae69690a64ced3ab91b9bb7f3e9a5004122d629d2816216a870 4100 448424ce4410d658b80215185e32d8ec6feb15c7275d64437c36418463e4 4101 0358bba70101020203585fa202818141000458568614a40150fa6b4a53d5 4102 ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab4503 4103 58248202582000112233445566778899aabbccddeeff0123456789abcdef 4104 fedcba98765432100e1987d0010f020f09820258203ee96dc79641970ae4 4105 6b929ccf0b72ba9536dd846020dbdc9f949d84ea0e18d20a4382030f0c43 4106 8217020d8202582023f48b2e2838650f43c144234aee18401ffe3cce4733 4107 b23881c3a8ae2d2b66e8 4109 Total size of Envelope with COSE authentication object: 923 4111 Envelope with COSE authentication object: 4113 a402589281588fd28443a10126a058448202584037353638353537396138 4114 336261626437316563386566323266613439616338373366373861373038 4115 6134336136373465373832616433306236353938643137615840faca7079 4116 6c319ce6dae69690a64ced3ab91b9bb7f3e9a5004122d629d2816216a870 4117 448424ce4410d658b80215185e32d8ec6feb15c7275d64437c36418463e4 4118 0358bba70101020203585fa202818141000458568614a40150fa6b4a53d5 4119 ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab4503 4120 58248202582000112233445566778899aabbccddeeff0123456789abcdef 4121 fedcba98765432100e1987d0010f020f09820258203ee96dc79641970ae4 4122 6b929ccf0b72ba9536dd846020dbdc9f949d84ea0e18d20a4382030f0c43 4123 8217020d8202582023f48b2e2838650f43c144234aee18401ffe3cce4733 4124 b23881c3a8ae2d2b66e809583c8613a1157832687474703a2f2f6578616d 4125 706c652e636f6d2f766572792f6c6f6e672f706174682f746f2f66696c65 4126 2f66696c652e62696e1502030f0d590204a20179019d2323204578616d70 4127 6c6520323a2053696d756c74616e656f757320446f776e6c6f61642c2049 4128 6e7374616c6c6174696f6e2c2053656375726520426f6f742c2053657665 4129 726564204669656c64730a0a2020202054686973206578616d706c652063 4130 6f766572732074686520666f6c6c6f77696e672074656d706c617465733a 4131 0a202020200a202020202a20436f6d7061746962696c6974792043686563 4132 6b20287b7b74656d706c6174652d636f6d7061746962696c6974792d6368 4133 65636b7d7d290a202020202a2053656375726520426f6f7420287b7b7465 4134 6d706c6174652d7365637572652d626f6f747d7d290a202020202a204669 4135 726d7761726520446f776e6c6f616420287b7b6669726d776172652d646f 4136 776e6c6f61642d74656d706c6174657d7d290a202020200a202020205468 4137 6973206578616d706c6520616c736f2064656d6f6e737472617465732073 4138 6576657261626c6520656c656d656e747320287b7b6f76722d7365766572 4139 61626c657d7d292c20616e64207465787420287b7b6d616e69666573742d 4140 6469676573742d746578747d7d292e814100a2036761726d2e636f6d0578 4141 525468697320636f6d706f6e656e7420697320612064656d6f6e73747261 4142 74696f6e2e205468652064696765737420697320612073616d706c652070 4143 61747465726e2c206e6f742061207265616c206f6e652e 4145 B.4. Example 3: A/B images 4147 This example covers the following templates: 4149 - Compatibility Check (Section 7.1) 4151 - Secure Boot (Section 7.2) 4153 - Firmware Download (Section 7.3) 4155 - A/B Image Template (Section 7.10) 4157 { 4158 / authentication-wrapper / 2:h'81588fd28443a10126a0584482025840616 4159 5306331656136383963393830306138343335353066333837393662366664626435326 4160 1306337386265356432363031316438653738346461343364343763584010222ddbce4 4161 e82a85f6ec7b72db34d7c5be8d2e822e4b2d099a4cf1d08aa2174c56c2e93bf20c785b 4162 ca298900208d92d352faf86e6cddc902a726bbc443c21ff' / [ 4163 h'd28443a10126a05844820258406165306331656136383963393830306138 4164 3433353530663338373936623666646264353261306337386265356432363031316438 4165 653738346461343364343763584010222ddbce4e82a85f6ec7b72db34d7c5be8d2e822 4166 e4b2d099a4cf1d08aa2174c56c2e93bf20c785bca298900208d92d352faf86e6cddc90 4167 2a726bbc443c21ff' / 18([ 4168 / protected / h'a10126' / { 4169 / alg / 1:-7 / "ES256" /, 4170 } /, 4171 / unprotected / { 4172 }, 4173 / payload / h'8202584061653063316561363839633938303061 4174 3834333535306633383739366236666462643532613063373862653564323630313164 4175 38653738346461343364343763' / [ 4176 / algorithm-id / 2 / "sha256" /, 4177 / digest-bytes / h'6165306331656136383963393830306 4178 1383433353530663338373936623666646264353261306337386265356432363031316 4179 438653738346461343364343763' 4180 ] /, 4181 / signature / h'10222ddbce4e82a85f6ec7b72db34d7c5be8d2 4182 e822e4b2d099a4cf1d08aa2174c56c2e93bf20c785bca298900208d92d352faf86e6cd 4183 dc902a726bbc443c21ff' 4184 ]) / 4185 ] /, 4186 / manifest / 3:h'a5010102030358aaa202818141000458a18814a20150fa6b4 4187 a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab450f82583 4188 68614a105198400050514a20358248202582000112233445566778899aabbccddeeff0 4189 123456789abcdeffedcba98765432100e1987d0583a8614a1051a00084400050514a20 4190 35824820258200123456789abcdeffedcba987654321000112233445566778899aabbc 4191 cddeeff0e1a00012c22010f020f095861860f82582a8613a105198400050513a115781 4192 c687474703a2f2f6578616d706c652e636f6d2f66696c65312e62696e582c8613a1051 4193 a00084400050513a115781c687474703a2f2f6578616d706c652e636f6d2f66696c653 4194 22e62696e1502030f0a4382030f' / { 4195 / manifest-version / 1:1, 4196 / manifest-sequence-number / 2:3, 4197 / common / 3:h'a202818141000458a18814a20150fa6b4a53d5ad5fdfbe9 4198 de663e4d41ffe02501492af1425695e48bf429b2d51f2ab450f8258368614a10519840 4199 0050514a20358248202582000112233445566778899aabbccddeeff0123456789abcde 4200 ffedcba98765432100e1987d0583a8614a1051a00084400050514a2035824820258200 4201 123456789abcdeffedcba987654321000112233445566778899aabbccddeeff0e1a000 4202 12c22010f020f' / { 4203 / components / 2:[ 4204 [h'00'] 4205 ], 4206 / common-sequence / 4:h'8814a20150fa6b4a53d5ad5fdfbe9de663 4207 e4d41ffe02501492af1425695e48bf429b2d51f2ab450f8258368614a1051984000505 4208 14a20358248202582000112233445566778899aabbccddeeff0123456789abcdeffedc 4209 ba98765432100e1987d0583a8614a1051a00084400050514a203582482025820012345 4210 6789abcdeffedcba987654321000112233445566778899aabbccddeeff0e1a00012c22 4211 010f020f' / [ 4212 / directive-override-parameters / 20,{ 4213 / vendor-id / 4214 1:h'"fa6b4a53d5ad5fdfbe9de663e4d41ffe"' / fa6b4a53-d5ad-5fdf- 4215 be9d-e663e4d41ffe /, 4216 / class-id / 4217 2:h'"1492af1425695e48bf429b2d51f2ab45"' / 4218 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 4219 } , 4220 / directive-try-each / 15,[ 4221 h'8614a105198400050514a203582482025820001122334455 4222 66778899aabbccddeeff0123456789abcdeffedcba98765432100e1987d0' / [ 4223 / directive-override-parameters / 20,{ 4224 / offset / 5:33792, 4225 } , 4226 / condition-component-offset / 5,5 , 4227 / directive-override-parameters / 20,{ 4228 / image-digest / 3:h'820258200011223344556 4229 6778899aabbccddeeff0123456789abcdeffedcba9876543210' / [ 4230 / algorithm-id / 2 / "sha256" /, 4231 / digest-bytes / 4232 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 4233 ] /, 4234 / image-size / 14:34768, 4235 } 4236 ] / , 4237 h'8614a1051a00084400050514a20358248202582001234567 4238 89abcdeffedcba987654321000112233445566778899aabbccddeeff0e1a00012c22' 4239 / [ 4240 / directive-override-parameters / 20,{ 4241 / offset / 5:541696, 4242 } , 4243 / condition-component-offset / 5,5 , 4244 / directive-override-parameters / 20,{ 4245 / image-digest / 3:h'820258200123456789abc 4246 deffedcba987654321000112233445566778899aabbccddeeff' / [ 4247 / algorithm-id / 2 / "sha256" /, 4248 / digest-bytes / 4249 h'0123456789abcdeffedcba987654321000112233445566778899aabbccddeeff' 4250 ] /, 4251 / image-size / 14:76834, 4252 } 4253 ] / 4254 ] , 4255 / condition-vendor-identifier / 1,15 , 4256 / condition-class-identifier / 2,15 4258 ] /, 4259 } /, 4260 / install / 9:h'860f82582a8613a105198400050513a115781c68747470 4261 3a2f2f6578616d706c652e636f6d2f66696c65312e62696e582c8613a1051a00084400 4262 050513a115781c687474703a2f2f6578616d706c652e636f6d2f66696c65322e62696e 4263 1502030f' / [ 4264 / directive-try-each / 15,[ 4265 h'8613a105198400050513a115781c687474703a2f2f6578616d70 4266 6c652e636f6d2f66696c65312e62696e' / [ 4267 / directive-set-parameters / 19,{ 4268 / offset / 5:33792, 4269 } , 4270 / condition-component-offset / 5,5 , 4271 / directive-set-parameters / 19,{ 4272 / uri / 21:'http://example.com/file1.bin', 4273 } 4274 ] / , 4275 h'8613a1051a00084400050513a115781c687474703a2f2f657861 4276 6d706c652e636f6d2f66696c65322e62696e' / [ 4277 / directive-set-parameters / 19,{ 4278 / offset / 5:541696, 4279 } , 4280 / condition-component-offset / 5,5 , 4281 / directive-set-parameters / 19,{ 4282 / uri / 21:'http://example.com/file2.bin', 4283 } 4284 ] / 4285 ] , 4286 / directive-fetch / 21,2 , 4287 / condition-image-match / 3,15 4288 ] /, 4289 / validate / 10:h'82030f' / [ 4290 / condition-image-match / 3,15 4291 ] /, 4292 } /, 4293 } 4295 Total size of Envelope without COSE authentication object: 288 4297 Envelope: 4299 a10359011ba5010102030358aaa202818141000458a18814a20150fa6b4a 4300 53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab 4301 450f8258368614a105198400050514a20358248202582000112233445566 4302 778899aabbccddeeff0123456789abcdeffedcba98765432100e1987d058 4303 3a8614a1051a00084400050514a2035824820258200123456789abcdeffe 4304 dcba987654321000112233445566778899aabbccddeeff0e1a00012c2201 4305 0f020f095861860f82582a8613a105198400050513a115781c687474703a 4306 2f2f6578616d706c652e636f6d2f66696c65312e62696e582c8613a1051a 4307 00084400050513a115781c687474703a2f2f6578616d706c652e636f6d2f 4308 66696c65322e62696e1502030f0a4382030f 4310 Total size of Envelope with COSE authentication object: 437 4312 Envelope with COSE authentication object: 4314 a202589281588fd28443a10126a058448202584061653063316561363839 4315 633938303061383433353530663338373936623666646264353261306337 4316 386265356432363031316438653738346461343364343763584010222ddb 4317 ce4e82a85f6ec7b72db34d7c5be8d2e822e4b2d099a4cf1d08aa2174c56c 4318 2e93bf20c785bca298900208d92d352faf86e6cddc902a726bbc443c21ff 4319 0359011ba5010102030358aaa202818141000458a18814a20150fa6b4a53 4320 d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab45 4321 0f8258368614a105198400050514a2035824820258200011223344556677 4322 8899aabbccddeeff0123456789abcdeffedcba98765432100e1987d0583a 4323 8614a1051a00084400050514a2035824820258200123456789abcdeffedc 4324 ba987654321000112233445566778899aabbccddeeff0e1a00012c22010f 4325 020f095861860f82582a8613a105198400050513a115781c687474703a2f 4326 2f6578616d706c652e636f6d2f66696c65312e62696e582c8613a1051a00 4327 084400050513a115781c687474703a2f2f6578616d706c652e636f6d2f66 4328 696c65322e62696e1502030f0a4382030f 4330 B.5. Example 4: Load and Decompress from External Storage 4332 This example covers the following templates: 4334 - Compatibility Check (Section 7.1) 4336 - Secure Boot (Section 7.2) 4338 - Firmware Download (Section 7.3) 4340 - Install (Section 7.4) 4342 - Load & Decompress (Section 7.7) 4344 { 4345 / authentication-wrapper / 2:h'81588fd28443a10126a0584482025840346 4346 2346337633863306664613736633963393539316139646231363039313865326233633 4347 93661353862306135653439383466643465386639333539613932385840d7063361f65 4348 3d57e63691e1bd9c856058c773b94e488bff58d599c45277788e90eb92fbef666f584e 4349 8d35b3b20ceef50a69b94dcff12beee92e426a06ea31320' / [ 4350 h'd28443a10126a05844820258403462346337633863306664613736633963 4351 3935393161396462313630393138653262336339366135386230613565343938346664 4352 3465386639333539613932385840d7063361f653d57e63691e1bd9c856058c773b94e4 4353 88bff58d599c45277788e90eb92fbef666f584e8d35b3b20ceef50a69b94dcff12beee 4354 92e426a06ea31320' / 18([ 4355 / protected / h'a10126' / { 4356 / alg / 1:-7 / "ES256" /, 4357 } /, 4358 / unprotected / { 4359 }, 4360 / payload / h'8202584034623463376338633066646137366339 4361 6339353931613964623136303931386532623363393661353862306135653439383466 4362 64346538663933353961393238' / [ 4363 / algorithm-id / 2 / "sha256" /, 4364 / digest-bytes / h'3462346337633863306664613736633 4365 9633935393161396462313630393138653262336339366135386230613565343938346 4366 664346538663933353961393238' 4367 ] /, 4368 / signature / h'd7063361f653d57e63691e1bd9c856058c773b 4369 94e488bff58d599c45277788e90eb92fbef666f584e8d35b3b20ceef50a69b94dcff12 4370 beee92e426a06ea31320' 4371 ]) / 4372 ] /, 4373 / manifest / 3:h'a801010204035867a20283814100814102814101045858880 4374 c0014a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2 4375 d51f2ab450358248202582000112233445566778899aabbccddeeff0123456789abcde 4376 ffedcba98765432100e1987d0010f020f085827880c0113a115781b687474703a2f2f6 4377 578616d706c652e636f6d2f66696c652e62696e1502030f094b880c0013a1160116020 4378 30f0a45840c00030f0b583a880c0213a4035824820258200123456789abcdeffedcba9 4379 87654321000112233445566778899aabbccddeeff0e1a00012c22130116001602030f0 4380 c45840c021702' / { 4381 / manifest-version / 1:1, 4382 / manifest-sequence-number / 2:4, 4383 / common / 3:h'a20283814100814102814101045858880c0014a40150fa6 4384 b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab4503582 4385 48202582000112233445566778899aabbccddeeff0123456789abcdeffedcba9876543 4386 2100e1987d0010f020f' / { 4387 / components / 2:[ 4388 [h'00'] , 4389 [h'02'] , 4390 [h'01'] 4391 ], 4392 / common-sequence / 4:h'880c0014a40150fa6b4a53d5ad5fdfbe9d 4393 e663e4d41ffe02501492af1425695e48bf429b2d51f2ab450358248202582000112233 4394 445566778899aabbccddeeff0123456789abcdeffedcba98765432100e1987d0010f02 4395 0f' / [ 4396 / directive-set-component-index / 12,0 , 4397 / directive-override-parameters / 20,{ 4398 / vendor-id / 4399 1:h'"fa6b4a53d5ad5fdfbe9de663e4d41ffe"' / fa6b4a53-d5ad-5fdf- 4400 be9d-e663e4d41ffe /, 4401 / class-id / 4402 2:h'"1492af1425695e48bf429b2d51f2ab45"' / 4403 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 4404 / image-digest / 3:h'8202582000112233445566778899a 4405 abbccddeeff0123456789abcdeffedcba9876543210' / [ 4406 / algorithm-id / 2 / "sha256" /, 4407 / digest-bytes / 4408 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 4409 ] /, 4410 / image-size / 14:34768, 4411 } , 4412 / condition-vendor-identifier / 1,15 , 4413 / condition-class-identifier / 2,15 4414 ] /, 4415 } /, 4416 / payload-fetch / 8:h'880c0113a115781b687474703a2f2f6578616d70 4417 6c652e636f6d2f66696c652e62696e1502030f' / [ 4418 / directive-set-component-index / 12,1 , 4419 / directive-set-parameters / 19,{ 4420 / uri / 21:'http://example.com/file.bin', 4421 } , 4422 / directive-fetch / 21,2 , 4423 / condition-image-match / 3,15 4424 ] /, 4425 / install / 9:h'880c0013a116011602030f' / [ 4426 / directive-set-component-index / 12,0 , 4427 / directive-set-parameters / 19,{ 4428 / source-component / 22:1 / [h'02'] /, 4429 } , 4430 / directive-copy / 22,2 , 4431 / condition-image-match / 3,15 4432 ] /, 4433 / validate / 10:h'840c00030f' / [ 4434 / directive-set-component-index / 12,0 , 4435 / condition-image-match / 3,15 4436 ] /, 4437 / load / 11:h'880c0213a4035824820258200123456789abcdeffedcba98 4438 7654321000112233445566778899aabbccddeeff0e1a00012c22130116001602030f' 4439 / [ 4440 / directive-set-component-index / 12,2 , 4441 / directive-set-parameters / 19,{ 4442 / image-digest / 3:h'820258200123456789abcdeffedcba987 4444 654321000112233445566778899aabbccddeeff' / [ 4445 / algorithm-id / 2 / "sha256" /, 4446 / digest-bytes / 4447 h'0123456789abcdeffedcba987654321000112233445566778899aabbccddeeff' 4448 ] /, 4449 / image-size / 14:76834, 4450 / source-component / 22:0 / [h'00'] /, 4451 / compression-info / 19:1 / "gzip" /, 4452 } , 4453 / directive-copy / 22,2 , 4454 / condition-image-match / 3,15 4455 ] /, 4456 / run / 12:h'840c021702' / [ 4457 / directive-set-component-index / 12,2 , 4458 / directive-run / 23,2 4459 ] /, 4460 } /, 4461 } 4463 Total size of Envelope without COSE authentication object: 245 4465 Envelope: 4467 a10358f1a801010204035867a20283814100814102814101045858880c00 4468 14a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48 4469 bf429b2d51f2ab450358248202582000112233445566778899aabbccddee 4470 ff0123456789abcdeffedcba98765432100e1987d0010f020f085827880c 4471 0113a115781b687474703a2f2f6578616d706c652e636f6d2f66696c652e 4472 62696e1502030f094b880c0013a116011602030f0a45840c00030f0b583a 4473 880c0213a4035824820258200123456789abcdeffedcba98765432100011 4474 2233445566778899aabbccddeeff0e1a00012c22130116001602030f0c45 4475 840c021702 4477 Total size of Envelope with COSE authentication object: 394 4479 Envelope with COSE authentication object: 4481 a202589281588fd28443a10126a058448202584034623463376338633066 4482 646137366339633935393161396462313630393138653262336339366135 4483 3862306135653439383466643465386639333539613932385840d7063361 4484 f653d57e63691e1bd9c856058c773b94e488bff58d599c45277788e90eb9 4485 2fbef666f584e8d35b3b20ceef50a69b94dcff12beee92e426a06ea31320 4486 0358f1a801010204035867a20283814100814102814101045858880c0014 4487 a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf 4488 429b2d51f2ab450358248202582000112233445566778899aabbccddeeff 4489 0123456789abcdeffedcba98765432100e1987d0010f020f085827880c01 4490 13a115781b687474703a2f2f6578616d706c652e636f6d2f66696c652e62 4491 696e1502030f094b880c0013a116011602030f0a45840c00030f0b583a88 4492 0c0213a4035824820258200123456789abcdeffedcba9876543210001122 4493 33445566778899aabbccddeeff0e1a00012c22130116001602030f0c4584 4494 0c021702 4496 B.6. Example 5: Two Images 4498 This example covers the following templates: 4500 - Compatibility Check (Section 7.1) 4502 - Secure Boot (Section 7.2) 4504 - Firmware Download (Section 7.3) 4506 Furthermore, it shows using these templates with two images. 4508 { 4509 / authentication-wrapper / 2:h'81588fd28443a10126a0584482025840323 4510 1306231323835306332333930393164386538326330653965393130363632623638616 4511 33834323435386136343138653333663637303165643538333432635840b5b8cb30c2b 4512 bb646c4d32426d72768668d6d6af54c26ac46c4020ca37ada47b9468340b4d0b2ddd15 4513 db824a7e6b0bc233e753940dfb7131fa145ddc456da3cf6' / [ 4514 h'd28443a10126a05844820258403231306231323835306332333930393164 4515 3865383263306539653931303636326236386163383432343538613634313865333366 4516 3637303165643538333432635840b5b8cb30c2bbb646c4d32426d72768668d6d6af54c 4517 26ac46c4020ca37ada47b9468340b4d0b2ddd15db824a7e6b0bc233e753940dfb7131f 4518 a145ddc456da3cf6' / 18([ 4519 / protected / h'a10126' / { 4520 / alg / 1:-7 / "ES256" /, 4521 } /, 4522 / unprotected / { 4523 }, 4524 / payload / h'8202584032313062313238353063323339303931 4525 6438653832633065396539313036363262363861633834323435386136343138653333 4526 66363730316564353833343263' / [ 4527 / algorithm-id / 2 / "sha256" /, 4528 / digest-bytes / h'3231306231323835306332333930393 4530 1643865383263306539653931303636326236386163383432343538613634313865333 4531 366363730316564353833343263' 4532 ] /, 4533 / signature / h'b5b8cb30c2bbb646c4d32426d72768668d6d6a 4534 f54c26ac46c4020ca37ada47b9468340b4d0b2ddd15db824a7e6b0bc233e753940dfb7 4535 131fa145ddc456da3cf6' 4536 ]) / 4537 ] /, 4538 / manifest / 3:h'a601010205035895a202828141008141010458898c0c0014a 4539 40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2a 4540 b450358248202582000112233445566778899aabbccddeeff0123456789abcdeffedcb 4541 a98765432100e1987d0010f020f0c0114a2035824820258200123456789abcdeffedcb 4542 a987654321000112233445566778899aabbccddeeff0e1a00012c2209584f900c0013a 4543 115781c687474703a2f2f6578616d706c652e636f6d2f66696c65312e62696e1502030 4544 f0c0113a115781c687474703a2f2f6578616d706c652e636f6d2f66696c65322e62696 4545 e1502030f0a49880c00030f0c01030f0c47860c0017021702' / { 4546 / manifest-version / 1:1, 4547 / manifest-sequence-number / 2:5, 4548 / common / 3:h'a202828141008141010458898c0c0014a40150fa6b4a53d 4549 5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab4503582482025 4550 82000112233445566778899aabbccddeeff0123456789abcdeffedcba98765432100e1 4551 987d0010f020f0c0114a2035824820258200123456789abcdeffedcba9876543210001 4552 12233445566778899aabbccddeeff0e1a00012c22' / { 4553 / components / 2:[ 4554 [h'00'] , 4555 [h'01'] 4556 ], 4557 / common-sequence / 4:h'8c0c0014a40150fa6b4a53d5ad5fdfbe9d 4558 e663e4d41ffe02501492af1425695e48bf429b2d51f2ab450358248202582000112233 4559 445566778899aabbccddeeff0123456789abcdeffedcba98765432100e1987d0010f02 4560 0f0c0114a2035824820258200123456789abcdeffedcba987654321000112233445566 4561 778899aabbccddeeff0e1a00012c22' / [ 4562 / directive-set-component-index / 12,0 , 4563 / directive-override-parameters / 20,{ 4564 / vendor-id / 4565 1:h'"fa6b4a53d5ad5fdfbe9de663e4d41ffe"' / fa6b4a53-d5ad-5fdf- 4566 be9d-e663e4d41ffe /, 4567 / class-id / 4568 2:h'"1492af1425695e48bf429b2d51f2ab45"' / 4569 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 4570 / image-digest / 3:h'8202582000112233445566778899a 4571 abbccddeeff0123456789abcdeffedcba9876543210' / [ 4572 / algorithm-id / 2 / "sha256" /, 4573 / digest-bytes / 4574 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 4575 ] /, 4576 / image-size / 14:34768, 4577 } , 4578 / condition-vendor-identifier / 1,15 , 4579 / condition-class-identifier / 2,15 , 4580 / directive-set-component-index / 12,1 , 4581 / directive-override-parameters / 20,{ 4582 / image-digest / 3:h'820258200123456789abcdeffedcb 4583 a987654321000112233445566778899aabbccddeeff' / [ 4584 / algorithm-id / 2 / "sha256" /, 4585 / digest-bytes / 4586 h'0123456789abcdeffedcba987654321000112233445566778899aabbccddeeff' 4587 ] /, 4588 / image-size / 14:76834, 4589 } 4590 ] /, 4591 } /, 4592 / install / 9:h'900c0013a115781c687474703a2f2f6578616d706c652e 4593 636f6d2f66696c65312e62696e1502030f0c0113a115781c687474703a2f2f6578616d 4594 706c652e636f6d2f66696c65322e62696e1502030f' / [ 4595 / directive-set-component-index / 12,0 , 4596 / directive-set-parameters / 19,{ 4597 / uri / 21:'http://example.com/file1.bin', 4598 } , 4599 / directive-fetch / 21,2 , 4600 / condition-image-match / 3,15 , 4601 / directive-set-component-index / 12,1 , 4602 / directive-set-parameters / 19,{ 4603 / uri / 21:'http://example.com/file2.bin', 4604 } , 4605 / directive-fetch / 21,2 , 4606 / condition-image-match / 3,15 4607 ] /, 4608 / validate / 10:h'880c00030f0c01030f' / [ 4609 / directive-set-component-index / 12,0 , 4610 / condition-image-match / 3,15 , 4611 / directive-set-component-index / 12,1 , 4612 / condition-image-match / 3,15 4613 ] /, 4614 / run / 12:h'860c0017021702' / [ 4615 / directive-set-component-index / 12,0 , 4616 / directive-run / 23,2 , 4617 / directive-run / 23,2 4618 ] /, 4619 } /, 4620 } 4622 Total size of Envelope without COSE authentication object: 264 4624 Envelope: 4626 a103590103a601010205035895a202828141008141010458898c0c0014a4 4627 0150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf42 4628 9b2d51f2ab450358248202582000112233445566778899aabbccddeeff01 4629 23456789abcdeffedcba98765432100e1987d0010f020f0c0114a2035824 4630 820258200123456789abcdeffedcba987654321000112233445566778899 4631 aabbccddeeff0e1a00012c2209584f900c0013a115781c687474703a2f2f 4632 6578616d706c652e636f6d2f66696c65312e62696e1502030f0c0113a115 4633 781c687474703a2f2f6578616d706c652e636f6d2f66696c65322e62696e 4634 1502030f0a49880c00030f0c01030f0c47860c0017021702 4636 Total size of Envelope with COSE authentication object: 413 4638 Envelope with COSE authentication object: 4640 a202589281588fd28443a10126a058448202584032313062313238353063 4641 323339303931643865383263306539653931303636326236386163383432 4642 3435386136343138653333663637303165643538333432635840b5b8cb30 4643 c2bbb646c4d32426d72768668d6d6af54c26ac46c4020ca37ada47b94683 4644 40b4d0b2ddd15db824a7e6b0bc233e753940dfb7131fa145ddc456da3cf6 4645 03590103a601010205035895a202828141008141010458898c0c0014a401 4646 50fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b 4647 2d51f2ab450358248202582000112233445566778899aabbccddeeff0123 4648 456789abcdeffedcba98765432100e1987d0010f020f0c0114a203582482 4649 0258200123456789abcdeffedcba987654321000112233445566778899aa 4650 bbccddeeff0e1a00012c2209584f900c0013a115781c687474703a2f2f65 4651 78616d706c652e636f6d2f66696c65312e62696e1502030f0c0113a11578 4652 1c687474703a2f2f6578616d706c652e636f6d2f66696c65322e62696e15 4653 02030f0a49880c00030f0c01030f0c47860c0017021702 4655 C. Design Rational 4657 In order to provide flexible behavior to constrained devices, while 4658 still allowing more powerful devices to use their full capabilities, 4659 the SUIT manifest encodes the required behavior of a Recipient 4660 device. Behavior is encoded as a specialized byte code, contained in 4661 a CBOR list. This promotes a flat encoding, which simplifies the 4662 parser. The information encoded by this byte code closely matches 4663 the operations that a device will perform, which promotes ease of 4664 processing. The core operations used by most update and trusted 4665 execution operations are represented in the byte code. The byte code 4666 can be extended by registering new operations. 4668 The specialized byte code approach gives benefits equivalent to those 4669 provided by a scripting language or conventional byte code, with two 4670 substantial differences. First, the language is extremely high 4671 level, consisting of only the operations that a device may perform 4672 during update and trusted execution of a firmware image. Second, the 4673 language specifies linear behavior, without reverse branches. 4675 Conditional processing is supported, and parallel and out-of-order 4676 processing may be performed by sufficiently capable devices. 4678 By structuring the data in this way, the manifest processor becomes a 4679 very simple engine that uses a pull parser to interpret the manifest. 4680 This pull parser invokes a series of command handlers that evaluate a 4681 Condition or execute a Directive. Most data is structured in a 4682 highly regular pattern, which simplifies the parser. 4684 The results of this allow a Recipient to implement a very small 4685 parser for constrained applications. If needed, such a parser also 4686 allows the Recipient to perform complex updates with reduced 4687 overhead. Conditional execution of commands allows a simple device 4688 to perform important decisions at validation-time. 4690 Dependency handling is vastly simplified as well. Dependencies 4691 function like subroutines of the language. When a manifest has a 4692 dependency, it can invoke that dependency's commands and modify their 4693 behavior by setting parameters. Because some parameters come with 4694 security implications, the dependencies also have a mechanism to 4695 reject modifications to parameters on a fine-grained level. 4697 Developing a robust permissions system works in this model too. The 4698 Recipient can use a simple ACL that is a table of Identities and 4699 Component Identifier permissions to ensure that operations on 4700 components fail unless they are permitted by the ACL. This table can 4701 be further refined with individual parameters and commands. 4703 Capability reporting is similarly simplified. A Recipient can report 4704 the Commands, Parameters, Algorithms, and Component Identifiers that 4705 it supports. This is sufficiently precise for a manifest author to 4706 create a manifest that the Recipient can accept. 4708 The simplicity of design in the Recipient due to all of these 4709 benefits allows even a highly constrained platform to use advanced 4710 update capabilities. 4712 C.1. C.1 Design Rationale: Envelope 4714 The Envelope is used instead of a COSE structure for several reasons: 4716 1. This enables the use of Severable Elements (Section 8.8) 4718 2. This enables modular processing of manifests, particularly with 4719 large signatures. 4721 3. This enables multiple authentication schemes. 4723 4. This allows integrity verification by a dependent to be 4724 unaffected by adding or removing authentication structures. 4726 Modular processing is important because it allows a Manifest 4727 Processor to iterate forward over an Envelope, processing Delegation 4728 Chains and Authentication Blocks, retaining only intermediate values, 4729 without any need to seek forward and backwards in a stream until it 4730 gets to the Manifest itself. This allows the use of large, Post- 4731 Quantum signatures without requiring retention of the signature 4732 itself, or seeking forward and back. 4734 Four authentication objects are supported by the Envelope: 4736 - COSE_Sign_Tagged 4738 - COSE_Sign1_Tagged 4740 - COSE_Mac_Tagged 4742 - COSE_Mac0_Tagged 4744 The SUIT Envelope allows an Update Authority or intermediary to mix 4745 and match any number of different authentication blocks it wants 4746 without any concern for modifying the integrity of another 4747 authentication block. This also allows the addition or removal of an 4748 authentication blocks without changing the integrity check of the 4749 Manifest, which is important for dependency handling. See 4750 Section 6.2 4752 C.2. C.2 Byte String Wrappers 4754 Byte string wrappers are used in several places in the suit manifest. 4755 The primary reason for wrappers it to limit the parser extent when 4756 invoked at different times, with a possible loss of context. 4758 The elements of the suit envelope are wrapped both to set the extents 4759 used by the parser and to simplify integrity checks by clearly 4760 defining the length of each element. 4762 The common block is re-parsed in order to find components identifiers 4763 from their indices, to find dependency prefixes and digests from 4764 their identifiers, and to find the common sequence. The common 4765 sequence is wrapped so that it matches other sequences, simplifying 4766 the code path. 4768 A severed SUIT command sequence will appear in the envelope, so it 4769 must be wrapped as with all envelope elements. For consistency, 4770 command sequences are also wrapped in the manifest. This also allows 4771 the parser to discern the difference between a command sequence and a 4772 SUIT_Digest. 4774 Parameters that are structured types (arrays and maps) are also 4775 wrapped in a bstr. This is so that parser extents can be set 4776 correctly using only a reference to the beginning of the parameter. 4777 This enables a parser to store a simple list of references to 4778 parameters that can be retrieved when needed. 4780 D. Implementation Conformance Matrix 4782 This section summarizes the functionality a minimal implementation 4783 needs to offer to claim conformance to this specification, in the 4784 absence of an application profile standard specifying otherwise. 4786 The subsequent table shows the conditions. 4788 +-------------------+-----------------+----------------+ 4789 | Name | Reference | Implementation | 4790 +-------------------+-----------------+----------------+ 4791 | Vendor Identifier | Section 8.7.5.1 | REQUIRED | 4792 | | | | 4793 | Class Identifier | Section 8.7.5.1 | REQUIRED | 4794 | | | | 4795 | Device Identifier | Section 8.7.5.1 | OPTIONAL | 4796 | | | | 4797 | Image Match | Section 8.7.6.2 | REQUIRED | 4798 | | | | 4799 | Image Not Match | Section 8.7.6.3 | OPTIONAL | 4800 | | | | 4801 | Use Before | Section 8.7.6.4 | OPTIONAL | 4802 | | | | 4803 | Component Offset | Section 8.7.6.5 | OPTIONAL | 4804 | | | | 4805 | Minimum Battery | Section 8.7.6.6 | OPTIONAL | 4806 | | | | 4807 | Update Authorized | Section 8.7.6.7 | OPTIONAL | 4808 | | | | 4809 | Version | Section 8.7.6.8 | OPTIONAL | 4810 | | | | 4811 | Custom Condition | Section 8.7.6.9 | OPTIONAL | 4812 +-------------------+-----------------+----------------+ 4814 The subsequent table shows the directives. 4816 +-------------------+----------------+------------------------------+ 4817 | Name | Reference | Implementation | 4818 +-------------------+----------------+------------------------------+ 4819 | Set Component | Section 8.7.7. | REQUIRED if more than one | 4820 | Index | 1 | component | 4821 | | | | 4822 | Set Dependency | Section 8.7.7. | REQUIRED if dependencies | 4823 | Index | 2 | used | 4824 | | | | 4825 | Abort | Section 8.7.7. | OPTIONAL | 4826 | | 3 | | 4827 | | | | 4828 | Try Each | Section 8.7.7. | OPTIONAL | 4829 | | 4 | | 4830 | | | | 4831 | Process | Section 8.7.7. | OPTIONAL | 4832 | Dependency | 5 | | 4833 | | | | 4834 | Set Parameters | Section 8.7.7. | OPTIONAL | 4835 | | 6 | | 4836 | | | | 4837 | Override | Section 8.7.7. | REQUIRED | 4838 | Parameters | 7 | | 4839 | | | | 4840 | Fetch | Section 8.7.7. | REQUIRED for Updater | 4841 | | 8 | | 4842 | | | | 4843 | Copy | Section 8.7.7. | OPTIONAL | 4844 | | 10 | | 4845 | | | | 4846 | Run | Section 8.7.7. | REQUIRED for Bootloader | 4847 | | 11 | | 4848 | | | | 4849 | Wait For Event | Section 8.7.7. | OPTIONAL | 4850 | | 12 | | 4851 | | | | 4852 | Run Sequence | Section 8.7.7. | OPTIONAL | 4853 | | 13 | | 4854 | | | | 4855 | Swap | Section 8.7.7. | OPTIONAL | 4856 | | 14 | | 4857 | | | | 4858 | Fetch URI List | Section 8.7.7. | OPTIONAL | 4859 | | 9 | | 4860 +-------------------+----------------+------------------------------+ 4862 The subsequent table shows the parameters. 4864 +------------------+------------------+----------------------+ 4865 | Name | Reference | Implementation | 4866 +------------------+------------------+----------------------+ 4867 | Vendor ID | Section 8.7.5.2 | REQUIRED | 4868 | | | | 4869 | Class ID | Section 8.7.5.3 | REQUIRED | 4870 | | | | 4871 | Image Digest | Section 8.7.5.5 | REQUIRED | 4872 | | | | 4873 | Image Size | Section 8.7.5.6 | REQUIRED | 4874 | | | | 4875 | Use Before | Section 8.7.5.7 | RECOMMENDED | 4876 | | | | 4877 | Component Offset | Section 8.7.5.8 | OPTIONAL | 4878 | | | | 4879 | Encryption Info | Section 8.7.5.9 | RECOMMENDED | 4880 | | | | 4881 | Compression Info | Section 8.7.5.10 | RECOMMENDED | 4882 | | | | 4883 | Unpack Info | Section 8.7.5.11 | RECOMMENDED | 4884 | | | | 4885 | URI | Section 8.7.5.12 | REQUIRED for Updater | 4886 | | | | 4887 | Source Component | Section 8.7.5.13 | OPTIONAL | 4888 | | | | 4889 | Run Args | Section 8.7.5.14 | OPTIONAL | 4890 | | | | 4891 | Device ID | Section 8.7.5.4 | OPTIONAL | 4892 | | | | 4893 | Minimum Battery | Section 8.7.5.15 | OPTIONAL | 4894 | | | | 4895 | Update Priority | Section 8.7.5.16 | OPTIONAL | 4896 | | | | 4897 | Version Match | Section 8.7.5.17 | OPTIONAL | 4898 | | | | 4899 | Wait Info | Section 8.7.5.18 | OPTIONAL | 4900 | | | | 4901 | URI List | Section 8.7.5.19 | OPTIONAL | 4902 | | | | 4903 | Strict Order | Section 8.7.5.21 | OPTIONAL | 4904 | | | | 4905 | Soft Failure | Section 8.7.5.22 | OPTIONAL | 4906 | | | | 4907 | Custom | Section 8.7.5.23 | OPTIONAL | 4908 +------------------+------------------+----------------------+ 4910 Authors' Addresses 4912 Brendan Moran 4913 Arm Limited 4915 EMail: Brendan.Moran@arm.com 4917 Hannes Tschofenig 4918 Arm Limited 4920 EMail: hannes.tschofenig@arm.com 4922 Henk Birkholz 4923 Fraunhofer SIT 4925 EMail: henk.birkholz@sit.fraunhofer.de 4927 Koen Zandberg 4928 Inria 4930 EMail: koen.zandberg@inria.fr