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