idnits 2.17.1 draft-ietf-suit-manifest-12.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (February 22, 2021) is 1158 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '1' on line 2504 -- Looks like a reference, but probably isn't: '2' on line 2504 -- Looks like a reference, but probably isn't: '3' on line 2475 == Missing Reference: '-1' is mentioned on line 2504, but not defined == Missing Reference: '-2' is mentioned on line 2477, but not defined == Missing Reference: '-3' is mentioned on line 2481, but not defined -- Looks like a reference, but probably isn't: '4' on line 2481 -- Looks like a reference, but probably isn't: '0' on line 2504 ** Obsolete normative reference: RFC 8152 (Obsoleted by RFC 9052, RFC 9053) == Outdated reference: A later version (-08) exists of draft-ietf-cbor-tags-oid-04 == Outdated reference: A later version (-24) exists of draft-ietf-sacm-coswid-16 == Outdated reference: A later version (-16) exists of draft-ietf-suit-architecture-15 == Outdated reference: A later version (-13) exists of draft-ietf-suit-information-model-08 == Outdated reference: A later version (-19) exists of draft-ietf-teep-architecture-13 Summary: 1 error (**), 0 flaws (~~), 10 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 SUIT B. Moran 3 Internet-Draft H. Tschofenig 4 Intended status: Standards Track Arm Limited 5 Expires: August 26, 2021 H. Birkholz 6 Fraunhofer SIT 7 K. Zandberg 8 Inria 9 February 22, 2021 11 A Concise Binary Object Representation (CBOR)-based Serialization Format 12 for the Software Updates for Internet of Things (SUIT) Manifest 13 draft-ietf-suit-manifest-12 15 Abstract 17 This specification describes the format of a manifest. A manifest is 18 a bundle of metadata about code/data obtained by a recipient (chiefly 19 the firmware for an IoT device), where to find the that code/data, 20 the devices to which it applies, and cryptographic information 21 protecting the manifest. Software updates and Trusted Invocation 22 both tend to use sequences of common operations, so the manifest 23 encodes those sequences of operations, rather than declaring the 24 metadata. 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at https://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on August 26, 2021. 43 Copyright Notice 45 Copyright (c) 2021 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (https://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 61 2. Conventions and Terminology . . . . . . . . . . . . . . . . . 6 62 3. How to use this Document . . . . . . . . . . . . . . . . . . 8 63 4. Background . . . . . . . . . . . . . . . . . . . . . . . . . 9 64 4.1. IoT Firmware Update Constraints . . . . . . . . . . . . . 9 65 4.2. SUIT Workflow Model . . . . . . . . . . . . . . . . . . . 10 66 5. Metadata Structure Overview . . . . . . . . . . . . . . . . . 11 67 5.1. Envelope . . . . . . . . . . . . . . . . . . . . . . . . 13 68 5.2. Delegation Chains . . . . . . . . . . . . . . . . . . . . 13 69 5.3. Authentication Block . . . . . . . . . . . . . . . . . . 13 70 5.4. Manifest . . . . . . . . . . . . . . . . . . . . . . . . 14 71 5.4.1. Critical Metadata . . . . . . . . . . . . . . . . . . 14 72 5.4.2. Common . . . . . . . . . . . . . . . . . . . . . . . 14 73 5.4.3. Command Sequences . . . . . . . . . . . . . . . . . . 14 74 5.4.4. Integrity Check Values . . . . . . . . . . . . . . . 15 75 5.4.5. Human-Readable Text . . . . . . . . . . . . . . . . . 15 76 5.5. Severable Elements . . . . . . . . . . . . . . . . . . . 15 77 5.6. Integrated Dependencies and Payloads . . . . . . . . . . 16 78 6. Manifest Processor Behavior . . . . . . . . . . . . . . . . . 16 79 6.1. Manifest Processor Setup . . . . . . . . . . . . . . . . 16 80 6.2. Required Checks . . . . . . . . . . . . . . . . . . . . . 17 81 6.2.1. Minimizing Signature Verifications . . . . . . . . . 19 82 6.3. Interpreter Fundamental Properties . . . . . . . . . . . 20 83 6.4. Abstract Machine Description . . . . . . . . . . . . . . 20 84 6.5. Special Cases of Component Index and Dependency Index . . 23 85 6.6. Serialized Processing Interpreter . . . . . . . . . . . . 24 86 6.7. Parallel Processing Interpreter . . . . . . . . . . . . . 25 87 6.8. Processing Dependencies . . . . . . . . . . . . . . . . . 25 88 6.9. Multiple Manifest Processors . . . . . . . . . . . . . . 26 89 7. Creating Manifests . . . . . . . . . . . . . . . . . . . . . 27 90 7.1. Compatibility Check Template . . . . . . . . . . . . . . 28 91 7.2. Trusted Invocation Template . . . . . . . . . . . . . . . 28 92 7.3. Component Download Template . . . . . . . . . . . . . . . 28 93 7.4. Install Template . . . . . . . . . . . . . . . . . . . . 29 94 7.5. Install and Transform Template . . . . . . . . . . . . . 30 95 7.6. Integrated Payload Template . . . . . . . . . . . . . . . 31 96 7.7. Load from Nonvolatile Storage Template . . . . . . . . . 31 97 7.8. Load & Decompress from Nonvolatile Storage Template . . . 31 98 7.9. Dependency Template . . . . . . . . . . . . . . . . . . . 32 99 7.9.1. Composite Manifests . . . . . . . . . . . . . . . . . 33 100 7.10. Encrypted Manifest Template . . . . . . . . . . . . . . . 33 101 7.11. A/B Image Template . . . . . . . . . . . . . . . . . . . 34 102 8. Metadata Structure . . . . . . . . . . . . . . . . . . . . . 35 103 8.1. Encoding Considerations . . . . . . . . . . . . . . . . . 35 104 8.2. Envelope . . . . . . . . . . . . . . . . . . . . . . . . 36 105 8.3. Delegation Chains . . . . . . . . . . . . . . . . . . . . 36 106 8.4. Authenticated Manifests . . . . . . . . . . . . . . . . . 36 107 8.5. Encrypted Manifests . . . . . . . . . . . . . . . . . . . 37 108 8.6. Manifest . . . . . . . . . . . . . . . . . . . . . . . . 37 109 8.6.1. suit-manifest-version . . . . . . . . . . . . . . . . 38 110 8.6.2. suit-manifest-sequence-number . . . . . . . . . . . . 38 111 8.6.3. suit-reference-uri . . . . . . . . . . . . . . . . . 38 112 8.6.4. suit-text . . . . . . . . . . . . . . . . . . . . . . 38 113 8.7. text-version-required . . . . . . . . . . . . . . . . . . 40 114 8.7.1. suit-coswid . . . . . . . . . . . . . . . . . . . . . 40 115 8.7.2. suit-common . . . . . . . . . . . . . . . . . . . . . 40 116 8.7.3. SUIT_Command_Sequence . . . . . . . . . . . . . . . . 42 117 8.7.4. Reporting Policy . . . . . . . . . . . . . . . . . . 44 118 8.7.5. SUIT_Parameters . . . . . . . . . . . . . . . . . . . 46 119 8.7.6. SUIT_Condition . . . . . . . . . . . . . . . . . . . 56 120 8.7.7. SUIT_Directive . . . . . . . . . . . . . . . . . . . 60 121 8.7.8. suit-directive-garbage-collect . . . . . . . . . . . 67 122 8.7.9. Integrity Check Values . . . . . . . . . . . . . . . 68 123 8.8. Severable Elements . . . . . . . . . . . . . . . . . . . 68 124 9. Access Control Lists . . . . . . . . . . . . . . . . . . . . 69 125 10. SUIT Digest Container . . . . . . . . . . . . . . . . . . . . 69 126 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 69 127 11.1. SUIT Commands . . . . . . . . . . . . . . . . . . . . . 70 128 11.2. SUIT Parameters . . . . . . . . . . . . . . . . . . . . 72 129 11.3. SUIT Text Values . . . . . . . . . . . . . . . . . . . . 73 130 11.4. SUIT Component Text Values . . . . . . . . . . . . . . . 73 131 11.5. SUIT Algorithm Identifiers . . . . . . . . . . . . . . . 73 132 11.5.1. SUIT Digest Algorithm Identifiers . . . . . . . . . 73 133 11.5.2. SUIT Compression Algorithm Identifiers . . . . . . . 74 134 11.5.3. Unpack Algorithms . . . . . . . . . . . . . . . . . 74 135 12. Security Considerations . . . . . . . . . . . . . . . . . . . 75 136 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 75 137 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 75 138 14.1. Normative References . . . . . . . . . . . . . . . . . . 75 139 14.2. Informative References . . . . . . . . . . . . . . . . . 76 140 Appendix A. A. Full CDDL . . . . . . . . . . . . . . . . . . . . 78 141 Appendix B. B. Examples . . . . . . . . . . . . . . . . . . . . 87 142 B.1. Example 0: Secure Boot . . . . . . . . . . . . . . . . . 88 143 B.2. Example 1: Simultaneous Download and Installation of 144 Payload . . . . . . . . . . . . . . . . . . . . . . . . . 90 145 B.3. Example 2: Simultaneous Download, Installation, Secure 146 Boot, Severed Fields . . . . . . . . . . . . . . . . . . 92 147 B.4. Example 3: A/B images . . . . . . . . . . . . . . . . . . 96 148 B.5. Example 4: Load and Decompress from External Storage . . 99 149 B.6. Example 5: Two Images . . . . . . . . . . . . . . . . . . 102 150 Appendix C. C. Design Rational . . . . . . . . . . . . . . . . . 105 151 C.1. C.1 Design Rationale: Envelope . . . . . . . . . . . . . 106 152 C.2. C.2 Byte String Wrappers . . . . . . . . . . . . . . . . 107 153 Appendix D. D. Implementation Conformance Matrix . . . . . . . . 107 154 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 111 156 1. Introduction 158 A firmware update mechanism is an essential security feature for IoT 159 devices to deal with vulnerabilities. While the transport of 160 firmware images to the devices themselves is important there are 161 already various techniques available. Equally important is the 162 inclusion of metadata about the conveyed firmware image (in the form 163 of a manifest) and the use of a security wrapper to provide end-to- 164 end security protection to detect modifications and (optionally) to 165 make reverse engineering more difficult. End-to-end security allows 166 the author, who builds the firmware image, to be sure that no other 167 party (including potential adversaries) can install firmware updates 168 on IoT devices without adequate privileges. For confidentiality 169 protected firmware images it is additionally required to encrypt the 170 firmware image. Starting security protection at the author is a risk 171 mitigation technique so firmware images and manifests can be stored 172 on untrusted repositories; it also reduces the scope of a compromise 173 of any repository or intermediate system to be no worse than a denial 174 of service. 176 A manifest is a bundle of metadata describing one or more code or 177 data payloads and how to: 179 - Obtain any dependencies 181 - Obtain the payload(s) 183 - Install them 185 - Verify them 187 - Load them into memory 189 - Invoke them 190 This specification defines the SUIT manifest format and it is 191 intended to meet several goals: 193 - Meet the requirements defined in 194 [I-D.ietf-suit-information-model]. 196 - Simple to parse on a constrained node 198 - Simple to process on a constrained node 200 - Compact encoding 202 - Comprehensible by an intermediate system 204 - Expressive enough to enable advanced use cases on advanced nodes 206 - Extensible 208 The SUIT manifest can be used for a variety of purposes throughout 209 its lifecycle, such as: 211 - a Firmware Author to reason about releasing a firmware. 213 - a Network Operator to reason about compatibility of a firmware. 215 - a Device Operator to reason about the impact of a firmware. 217 - the Device Operator to manage distribution of firmware to devices. 219 - a Plant Manager to reason about timing and acceptance of firmware 220 updates. 222 - a device to reason about the authority & authenticity of a 223 firmware prior to installation. 225 - a device to reason about the applicability of a firmware. 227 - a device to reason about the installation of a firmware. 229 - a device to reason about the authenticity & encoding of a firmware 230 at boot. 232 Each of these uses happens at a different stage of the manifest 233 lifecycle, so each has different requirements. 235 It is assumed that the reader is familiar with the high-level 236 firmware update architecture [I-D.ietf-suit-architecture] and the 237 threats, requirements, and user stories in 238 [I-D.ietf-suit-information-model]. 240 The design of this specification is based on an observation that the 241 vast majority of operations that a device can perform during an 242 update or Trusted Invocation are composed of a small group of 243 operations: 245 - Copy some data from one place to another 247 - Transform some data 249 - Digest some data and compare to an expected value 251 - Compare some system parameters to an expected value 253 - Run some code 255 In this document, these operations are called commands. Commands are 256 classed as either conditions or directives. Conditions have no side- 257 effects, while directives do have side-effects. Conceptually, a 258 sequence of commands is like a script but the used language is 259 tailored to software updates and Trusted Invocation. 261 The available commands support simple steps, such as copying a 262 firmware image from one place to another, checking that a firmware 263 image is correct, verifying that the specified firmware is the 264 correct firmware for the device, or unpacking a firmware. By using 265 these steps in different orders and changing the parameters they use, 266 a broad range of use cases can be supported. The SUIT manifest uses 267 this observation to optimize metadata for consumption by constrained 268 devices. 270 While the SUIT manifest is informed by and optimized for firmware 271 update and Trusted Invocation use cases, there is nothing in the 272 [I-D.ietf-suit-information-model] that restricts its use to only 273 those use cases. Other use cases include the management of trusted 274 applications (TAs) in a Trusted Execution Environment (TEE), as 275 discussed in [I-D.ietf-teep-architecture]. 277 2. Conventions and Terminology 279 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 280 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 281 "OPTIONAL" in this document are to be interpreted as described in 282 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 283 capitals, as shown here. 285 Additionally, the following terminology is used throughout this 286 document: 288 - SUIT: Software Update for the Internet of Things, also the IETF 289 working group for this standard. 291 - Payload: A piece of information to be delivered. Typically 292 Firmware for the purposes of SUIT. 294 - Resource: A piece of information that is used to construct a 295 payload. 297 - Manifest: A manifest is a bundle of metadata about the firmware 298 for an IoT device, where to find the firmware, and the devices to 299 which it applies. 301 - Envelope: A container with the manifest, an authentication wrapper 302 with cryptographic information protecting the manifest, 303 authorization information, and severable elements (see: TBD). 305 - Update: One or more manifests that describe one or more payloads. 307 - Update Authority: The owner of a cryptographic key used to sign 308 updates, trusted by Recipients. 310 - Recipient: The system, typically an IoT device, that receives and 311 processes a manifest. 313 - Manifest Processor: A component of the Recipient that consumes 314 Manifests and executes the commands in the Manifest. 316 - Component: An updatable logical block of the Firmware, Software, 317 configuration, or data of the Recipient. 319 - Component Set: A group of interdependent Components that must be 320 updated simultaneously. 322 - Command: A Condition or a Directive. 324 - Condition: A test for a property of the Recipient or its 325 Components. 327 - Directive: An action for the Recipient to perform. 329 - Trusted Invocation: A process by which a system ensures that only 330 trusted code is executed, for example secure boot or launching a 331 Trusted Application. 333 - A/B images: Dividing a Recipient's storage into two or more 334 bootable images, at different offsets, such that the active image 335 can write to the inactive image(s). 337 - Record: The result of a Command and any metadata about it. 339 - Report: A list of Records. 341 - Procedure: The process of invoking one or more sequences of 342 commands. 344 - Update Procedure: A procedure that updates a Recipient by fetching 345 dependencies and images, and installing them. 347 - Invocation Procedure: A procedure in which a Recipient verifies 348 dependencies and images, loading images, and invokes one or more 349 image. 351 - Software: Instructions and data that allow a Recipient to perform 352 a useful function. 354 - Firmware: Software that is typically changed infrequently, stored 355 in nonvolatile memory, and small enough to apply to [RFC7228] 356 Class 0-2 devices. 358 - Image: Information that a Recipient uses to perform its function, 359 typically firmware/software, configuration, or resource data such 360 as text or images. Also, a Payload, once installed is an Image. 362 - Slot: One of several possible storage locations for a given 363 Component, typically used in A/B image systems 365 - Abort: An event in which the Manifest Processor immediately halts 366 execution of the current Procedure. It creates a Record of an 367 error condition. 369 3. How to use this Document 371 This specification covers five aspects of firmware update: 373 - Section 4 describes the device constraints, use cases, and design 374 principles that informed the structure of the manifest. 376 - Section 5 gives a general overview of the metadata structure to 377 inform the following sections 379 - Section 6 describes what actions a Manifest processor should take. 381 - Section 7 describes the process of creating a Manifest. 383 - Section 8 specifies the content of the Envelope and the Manifest. 385 To implement an updatable device, see Section 6 and Section 8. To 386 implement a tool that generates updates, see Section 7 and Section 8. 388 The IANA consideration section, see Section 11, provides instructions 389 to IANA to create several registries. This section also provides the 390 CBOR labels for the structures defined in this document. 392 The complete CDDL description is provided in Appendix A, examples are 393 given in Appendix B and a design rational is offered in Appendix C. 394 Finally, Appendix D gives a summarize of the mandatory-to-implement 395 features of this specification. 397 4. Background 399 Distributing software updates to diverse devices with diverse trust 400 anchors in a coordinated system presents unique challenges. Devices 401 have a broad set of constraints, requiring different metadata to make 402 appropriate decisions. There may be many actors in production IoT 403 systems, each of whom has some authority. Distributing firmware in 404 such a multi-party environment presents additional challenges. Each 405 party requires a different subset of data. Some data may not be 406 accessible to all parties. Multiple signatures may be required from 407 parties with different authorities. This topic is covered in more 408 depth in [I-D.ietf-suit-architecture]. The security aspects are 409 described in [I-D.ietf-suit-information-model]. 411 4.1. IoT Firmware Update Constraints 413 The various constraints of IoT devices and the range of use cases 414 that need to be supported create a broad set of requirements. For 415 example, devices with: 417 - limited processing power and storage may require a simple 418 representation of metadata. 420 - bandwidth constraints may require firmware compression or partial 421 update support. 423 - bootloader complexity constraints may require simple selection 424 between two bootable images. 426 - small internal storage may require external storage support. 428 - multiple microcontrollers may require coordinated update of all 429 applications. 431 - large storage and complex functionality may require parallel 432 update of many software components. 434 - extra information may need to be conveyed in the manifest in the 435 earlier stages of the device lifecycle before those data items are 436 stripped when the manifest is delivered to a constrained device. 438 Supporting the requirements introduced by the constraints on IoT 439 devices requires the flexibility to represent a diverse set of 440 possible metadata, but also requires that the encoding is kept 441 simple. 443 4.2. SUIT Workflow Model 445 There are several fundamental assumptions that inform the model of 446 Update Procedure workflow: 448 - Compatibility must be checked before any other operation is 449 performed. 451 - All dependency manifests should be present before any payload is 452 fetched. 454 - In some applications, payloads must be fetched and validated prior 455 to installation. 457 There are several fundamental assumptions that inform the model of 458 the Invocation Procedure workflow: 460 - Compatibility must be checked before any other operation is 461 performed. 463 - All dependencies and payloads must be validated prior to loading. 465 - All loaded images must be validated prior to execution. 467 Based on these assumptions, the manifest is structured to work with a 468 pull parser, where each section of the manifest is used in sequence. 469 The expected workflow for a Recipient installing an update can be 470 broken down into five steps: 472 1. Verify the signature of the manifest. 474 2. Verify the applicability of the manifest. 476 3. Resolve dependencies. 478 4. Fetch payload(s). 480 5. Install payload(s). 482 When installation is complete, similar information can be used for 483 validating and running images in a further three steps: 485 1. Verify image(s). 487 2. Load image(s). 489 3. Run image(s). 491 If verification and running is implemented in a bootloader, then the 492 bootloader MUST also verify the signature of the manifest and the 493 applicability of the manifest in order to implement secure boot 494 workflows. The bootloader may add its own authentication, e.g. a 495 Message Authentication Code (MAC), to the manifest in order to 496 prevent further verifications. 498 When multiple manifests are used for an update, each manifest's steps 499 occur in a lockstep fashion; all manifests have dependency resolution 500 performed before any manifest performs a payload fetch, etc. 502 5. Metadata Structure Overview 504 This section provides a high level overview of the manifest 505 structure. The full description of the manifest structure is in 506 Section 8.6 508 The manifest is structured from several key components: 510 1. The Envelope (see Section 5.1) contains Delegation Chains, the 511 Authentication Block, the Manifest, any Severable Elements, and 512 any Integrated Payloads or Dependencies. 514 2. Delegation Chains (see Section 5.2) allow a Recipient to work 515 from one of its Trust Anchors to an authority of the 516 Authentication Block. 518 3. The Authentication Block (see Section 5.3) contains a list of 519 signatures or MACs of the manifest.. 521 4. The Manifest (see Section 5.4) contains all critical, non- 522 severable metadata that the Recipient requires. It is further 523 broken down into: 525 1. Critical metadata, such as sequence number. 527 2. Common metadata, including lists of dependencies and affected 528 components. 530 3. Command sequences, directing the Recipient how to install and 531 use the payload(s). 533 4. Integrity check values for severable elements. 535 5. Severable elements (see Section 5.5). 537 6. Integrated dependencies (see Section 5.6). 539 7. Integrated payloads (see Section 5.6). 541 The diagram below illustrates the hierarchy of the Envelope. 543 +-------------------------+ 544 | Envelope | 545 +-------------------------+ 546 | Delegation Chains | 547 | Authentication Block | 548 | Manifest --------------> +------------------------------+ 549 | Severable Elements | | Manifest | 550 | Human-Readable Text | +------------------------------+ 551 | COSWID | | Structure Version | 552 | Integrated Dependencies | | Sequence Number | 553 | Integrated Payloads | | Reference to Full Manifest | 554 +-------------------------+ +------ Common Structure | 555 | +---- Command Sequences | 556 +-------------------------+ | | | Digests of Envelope Elements | 557 | Common Structure | <--+ | +------------------------------+ 558 +-------------------------+ | 559 | Dependencies | +-> +-----------------------+ 560 | Components IDs | | Command Sequence | 561 | Common Command Sequence ---------> +-----------------------+ 562 +-------------------------+ | List of ( pairs of ( | 563 | * command code | 564 | * argument / | 565 | reporting policy | 566 | )) | 567 +-----------------------+ 569 5.1. Envelope 571 The SUIT Envelope is a container that encloses Delegation Chains, the 572 Authentication Block, the Manifest, any Severable Elements, and any 573 integrated payloads or dependencies. The Envelope is used instead of 574 conventional cryptographic envelopes, such as COSE_Envelope because 575 it allows modular processing, severing of elements, and integrated 576 payloads in a way that would add substantial complexity with existing 577 solutions. See Appendix C.1 for a description of the reasoning for 578 this. 580 See Section 8.2 for more detail. 582 5.2. Delegation Chains 584 Delegation Chains allow a Recipient to establish a chain of trust 585 from a Trust Anchor to the signer of a manifest by validating 586 delegation claims. Each delegation claim is a [RFC8392] CBOR Web 587 Tokens (CWTs). The first claim in each list is signed by a Trust 588 Anchor. Each subsequent claim in a list is signed by the public key 589 claimed in the preceding list element. The last element in each list 590 claims a public key that can be used to verify a signature in the 591 Authentication Block (Section 5.3). 593 See Section 8.3 for more detail. 595 5.3. Authentication Block 597 The Authentication Block contains a bstr-wrapped Section 10 and one 598 or more [RFC8152] CBOR Object Signing and Encryption (COSE) 599 authentication blocks. These blocks are one of: 601 - COSE_Sign_Tagged 603 - COSE_Sign1_Tagged 605 - COSE_Mac_Tagged 607 - COSE_Mac0_Tagged 609 Each of these objects is used in detached payload mode. The payload 610 is the bstr-wrapped SUIT_Digest. 612 See Section 8.4 for more detail. 614 5.4. Manifest 616 The Manifest contains most metadata about one or more images. The 617 Manifest is divided into Critical Metadata, Common Metadata, Command 618 Sequences, and Integrity Check Values. 620 See Section 8.6 for more detail. 622 5.4.1. Critical Metadata 624 Some metadata needs to be accessed before the manifest is processed. 625 This metadata can be used to determine which manifest is newest and 626 whether the structure version is supported. It also MAY provide a 627 URI for obtaining a canonical copy of the manifest and Envelope. 629 See Section 8.6.1, Section 8.6.2, and Section 8.6.3 for more detail. 631 5.4.2. Common 633 Some metadata is used repeatedly and in more than one command 634 sequence. In order to reduce the size of the manifest, this metadata 635 is collected into the Common section. Common is composed of three 636 parts: a list of dependencies, a list of components referenced by the 637 manifest, and a command sequence to execute prior to each other 638 command sequence. The common command sequence is typically used to 639 set commonly used values and perform compatibility checks. The 640 common command sequence MUST NOT have any side-effects outside of 641 setting parameter values. 643 See Section 8.7.2, and Section 8.7.2.1 for more detail. 645 5.4.3. Command Sequences 647 Command sequences provide the instructions that a Recipient requires 648 in order to install or use an image. These sequences tell a device 649 to set parameter values, test system parameters, copy data from one 650 place to another, transform data, digest data, and run code. 652 Command sequences are broken up into three groups: Common Command 653 Sequence (see Section 5.4.2), update commands, and secure boot 654 commands. 656 Update Command Sequences are: Dependency Resolution, Payload Fetch, 657 and Payload Installation. An Update Procedure is the complete set of 658 each Update Command Sequence, each preceded by the Common Command 659 Sequence. 661 Invocation Command Sequences are: System Validation, Image Loading, 662 and Image Invocation. A Invocation Procedure is the complete set of 663 each Invocation Command Sequence, each preceded by the Common Command 664 Sequence. 666 Command Sequences are grouped into these sets to ensure that there is 667 common coordination between dependencies and dependents on when to 668 execute each command. 670 See Section 8.7.3 for more detail. 672 5.4.4. Integrity Check Values 674 To enable Section 5.5, there needs to be a mechanism to verify 675 integrity of any metadata outside the manifest. Integrity Check 676 Values are used to verify the integrity of metadata that is not 677 contained in the manifest. This MAY include Severable Command 678 Sequences, Concise Software Identifiers (CoSWID 679 [I-D.ietf-sacm-coswid]), or Text data. Integrated Dependencies and 680 Integrated Payloads are integrity-checked using Command Sequences, so 681 they do not have Integrity Check Values present in the Manifest. 683 See Section 8.7.9 for more detail. 685 5.4.5. Human-Readable Text 687 Text is typically a Severable Element (Section 5.5). It contains all 688 the text that describes the update. Because text is explicitly for 689 human consumption, it is all grouped together so that it can be 690 Severed easily. The text section has space both for describing the 691 manifest as a whole and for describing each individual component. 693 See Section 8.6.4 for more detail. 695 5.5. Severable Elements 697 Severable Elements are elements of the Envelope (Section 5.1) that 698 have Integrity Check Values (Section 5.4.4) in the Manifest 699 (Section 5.4). 701 Because of this organisation, these elements can be discarded or 702 "Severed" from the Envelope without changing the signature of the 703 Manifest. This allows savings based on the size of the Envelope in 704 several scenarios, for example: 706 - A management system severs the Text and CoSWID sections before 707 sending an Envelope to a constrained Recipient, which saves 708 Recipient bandwidth. 710 - A Recipient severs the Installation section after installing the 711 Update, which saves storage space. 713 See Section 8.8 for more detail. 715 5.6. Integrated Dependencies and Payloads 717 In some cases, it is beneficial to include a dependency or a payload 718 in the Envelope of a manifest. For example: 720 - When an update is delivered via a comparatively unconstrained 721 medium, such as a removable mass storage device, it may be 722 beneficial to bundle updates into single files. 724 - When a manifest requires encryption, it must be referenced as a 725 dependency, so a trivial manifest may be used to enclose the 726 encrypted manifest. The encrypted manifest may be contained in 727 the dependent manifest's envelope. 729 - When a manifest transports a small payload, such as an encrypted 730 key, that payload may be placed in the manifest's envelope. 732 See Section 7.9.1, Section 8.5 for more detail. 734 6. Manifest Processor Behavior 736 This section describes the behavior of the manifest processor and 737 focuses primarily on interpreting commands in the manifest. However, 738 there are several other important behaviors of the manifest 739 processor: encoding version detection, rollback protection, and 740 authenticity verification are chief among these. 742 6.1. Manifest Processor Setup 744 Prior to executing any command sequence, the manifest processor or 745 its host application MUST inspect the manifest version field and fail 746 when it encounters an unsupported encoding version. Next, the 747 manifest processor or its host application MUST extract the manifest 748 sequence number and perform a rollback check using this sequence 749 number. The exact logic of rollback protection may vary by 750 application, but it has the following properties: 752 - Whenever the manifest processor can choose between several 753 manifests, it MUST select the latest valid, authentic manifest. 755 - If the latest valid, authentic manifest fails, it MAY select the 756 next latest valid, authentic manifest, according to application- 757 specific policy. 759 Here, valid means that a manifest has a supported encoding version 760 and it has not been excluded for other reasons. Reasons for 761 excluding typically involve first executing the manifest and may 762 include: 764 - Test failed (e.g. Vendor ID/Class ID). 766 - Unsupported command encountered. 768 - Unsupported parameter encountered. 770 - Unsupported Component Identifier encountered. 772 - Payload not available. 774 - Dependency not available. 776 - Application crashed when executed. 778 - Watchdog timeout occurred. 780 - Dependency or Payload verification failed. 782 - Missing component from a set. 784 - Required parameter not supplied. 786 These failure reasons MAY be combined with retry mechanisms prior to 787 marking a manifest as invalid. 789 Selecting an older manifest in the event of failure of the latest 790 valid manifest is a robustness mechanism that is necessary for 791 supporting the requirements in [I-D.ietf-suit-architecture], section 792 3.5. It may not be appropriate for all applications. In particular 793 Trusted Execution Environments MAY require a failure to invoke a new 794 installation, rather than a rollback approach. See 795 [I-D.ietf-suit-information-model], Section 4.2.1 for more discussion 796 on the security considerations that apply to rollback. 798 Following these initial tests, the manifest processor clears all 799 parameter storage. This ensures that the manifest processor begins 800 without any leaked data. 802 6.2. Required Checks 804 The RECOMMENDED process is to verify the signature of the manifest 805 prior to parsing/executing any section of the manifest. This guards 806 the parser against arbitrary input by unauthenticated third parties, 807 but it costs extra energy when a Recipient receives an incompatible 808 manifest. 810 When validating authenticity of manifests, the manifest processor MAY 811 use an ACL (see Section 9) to determine the extent of the rights 812 conferred by that authenticity. Where a device supports only one 813 level of access, it MAY choose to skip signature verification of 814 dependencies, since they are referenced by digest. Where a device 815 supports more than one trusted party, it MAY choose to defer the 816 verification of signatures of dependencies until the list of affected 817 components is known so that it can skip redundant signature 818 verifications. For example, a dependency signed by the same author 819 as the dependent does not require a signature verification. 820 Similarly, if the signer of the dependent has full rights to the 821 device, according to the ACL, then no signature verification is 822 necessary on the dependency. 824 Once a valid, authentic manifest has been selected, the manifest 825 processor MUST examine the component list and verify that its maximum 826 number of components is not exceeded and that each listed component 827 is supported. 829 For each listed component, the manifest processor MUST provide 830 storage for the supported parameters. If the manifest processor does 831 not have sufficient temporary storage to process the parameters for 832 all components, it MAY process components serially for each command 833 sequence. See Section 6.6 for more details. 835 The manifest processor SHOULD check that the common sequence contains 836 at least Check Vendor Identifier command and at least one Check Class 837 Identifier command. 839 Because the common sequence contains Check Vendor Identifier and 840 Check Class Identifier command(s), no custom commands are permitted 841 in the common sequence. This ensures that any custom commands are 842 only executed by devices that understand them. 844 If the manifest contains more than one component and/or dependency, 845 each command sequence MUST begin with a Set Component Index or Set 846 Dependency Index command. 848 If a dependency is specified, then the manifest processor MUST 849 perform the following checks: 851 1. At the beginning of each section in the dependent: all previous 852 sections of each dependency have been executed. 854 2. At the end of each section in the dependent: The corresponding 855 section in each dependency has been executed. 857 If the interpreter does not support dependencies and a manifest 858 specifies a dependency, then the interpreter MUST reject the 859 manifest. 861 If a Recipient supports groups of interdependent components (a 862 Component Set), then it SHOULD verify that all Components in the 863 Component Set are specified by one update, that is: a single manifest 864 and all its dependencies that together: 866 1. have sufficient permissions imparted by their signatures 868 2. specify a digest and a payload for every Component in the 869 Component Set. 871 The single dependent manifest is sometimes called a Root Manifest. 873 6.2.1. Minimizing Signature Verifications 875 Signature verification can be energy and time expensive on a 876 constrained device. MAC verification is typically unaffected by 877 these concerns. A Recipient MAY choose to parse and execute only the 878 SUIT_Common section of the manifest prior to signature verification, 879 if all of the below apply: 881 - The Authentication Block contains a COSE_Sign_Tagged or 882 COSE_Sign1_Tagged 884 - The Recipient receives manifests over an unauthenticated channel, 885 exposing it to more inauthentic or incompatible manifests, and 887 - The Recipient has a power budget that makes signature verification 888 undesirable 890 The guidelines in Creating Manifests (Section 7) require that the 891 common section contains the applicability checks, so this section is 892 sufficient for applicability verification. The parser MUST restrict 893 acceptable commands to conditions and the following directives: 894 Override Parameters, Set Parameters, Try Each, and Run Sequence ONLY. 895 The manifest parser MUST NOT execute any command with side-effects 896 outside the parser (for example, Run, Copy, Swap, or Fetch commands) 897 prior to authentication and any such command MUST Abort. The Common 898 Sequence MUST be executed again in its entirety after authenticity 899 validation. 901 When executing Common prior to authenticity validation, the Manifest 902 Processor MUST evaluate the integrity of the manifest using the 903 SUIT_Digest present in the authentication block. 905 Alternatively, a Recipient MAY rely on network infrastructure to 906 filter inapplicable manifests. 908 6.3. Interpreter Fundamental Properties 910 The interpreter has a small set of design goals: 912 1. Executing an update MUST either result in an error, or a 913 verifiably correct system state. 915 2. Executing a Trusted Invocation MUST either result in an error, or 916 an invoked image. 918 3. Executing the same manifest on multiple Recipients MUST result in 919 the same system state. 921 NOTE: when using A/B images, the manifest functions as two (or more) 922 logical manifests, each of which applies to a system in a particular 923 starting state. With that provision, design goal 3 holds. 925 6.4. Abstract Machine Description 927 The heart of the manifest is the list of commands, which are 928 processed by a Manifest Processor-a form of interpreter. This 929 Manifest Processor can be modeled as a simple abstract machine. This 930 machine consists of several data storage locations that are modified 931 by commands. 933 There are two types of commands, namely those that modify state 934 (directives) and those that perform tests (conditions). Parameters 935 are used as the inputs to commands. Some directives offer control 936 flow operations. Directives target a specific component or 937 dependency. A dependency is another SUIT_Envelope that describes 938 additional components. Dependencies are identified by digest, but 939 referenced in commands by Dependency Index, the index into the array 940 of Dependencies. A component is a unit of code or data that can be 941 targeted by an update. Components are identified by Component 942 Identifiers, but referenced in commands by Component Index; Component 943 Identifiers are arrays of binary strings and a Component Index is an 944 index into the array of Component Identifiers. 946 Conditions MUST NOT have any side-effects other than informing the 947 interpreter of success or failure. The Interpreter does not Abort if 948 the Soft Failure flag (Section 8.7.5.23) is set when a Condition 949 reports failure. 951 Directives MAY have side-effects in the parameter table, the 952 interpreter state, or the current component. The Interpreter MUST 953 Abort if a Directive reports failure regardless of the Soft Failure 954 flag. 956 To simplify the logic describing the command semantics, the object 957 "current" is used. It represents the component identified by the 958 Component Index or the dependency identified by the Dependency Index: 960 current := components\[component-index\] 961 if component-index is not false 962 else dependencies\[dependency-index\] 964 As a result, Set Component Index is described as current := 965 components[arg]. The actual operation performed for Set Component 966 Index is described by the following pseudocode, however, because of 967 the definition of current (above), these are semantically equivalent. 969 component-index := arg 970 dependency-index := false 972 Similarly, Set Dependency Index is semantically equivalent to current 973 := dependencies[arg] 975 The following table describes the behavior of each command. "params" 976 represents the parameters for the current component or dependency. 977 Most commands operate on either a component or a dependency. Setting 978 the Component Index clears the Dependency Index. Setting the 979 Dependency Index clears the Component Index. 981 +-------------------+-----------------------------------------------+ 982 | Command Name | Semantic of the Operation | 983 +-------------------+-----------------------------------------------+ 984 | Check Vendor | assert(binary-match(current, | 985 | Identifier | current.params[vendor-id])) | 986 | | | 987 | Check Class | assert(binary-match(current, | 988 | Identifier | current.params[class-id])) | 989 | | | 990 | Verify Image | assert(binary-match(digest(current), | 991 | | current.params[digest])) | 992 | | | 993 | Set Component | current := components[arg] | 994 | Index | | 995 | | | 996 | Override | current.params[k] := v for-each k,v in arg | 997 | Parameters | | 998 | | | 999 | Set Dependency | current := dependencies[arg] | 1000 | Index | | 1001 | | | 1002 | Set Parameters | current.params[k] := v if not k in params | 1003 | | for-each k,v in arg | 1004 | | | 1005 | Process | exec(current[common]); exec(current[current- | 1006 | Dependency | segment]) | 1007 | | | 1008 | Run | run(current) | 1009 | | | 1010 | Fetch | store(current, fetch(current.params[uri])) | 1011 | | | 1012 | Use Before | assert(now() < arg) | 1013 | | | 1014 | Check Component | assert(offsetof(current) == arg) | 1015 | Offset | | 1016 | | | 1017 | Check Device | assert(binary-match(current, | 1018 | Identifier | current.params[device-id])) | 1019 | | | 1020 | Check Image Not | assert(not binary-match(digest(current), | 1021 | Match | current.params[digest])) | 1022 | | | 1023 | Check Minimum | assert(battery >= arg) | 1024 | Battery | | 1025 | | | 1026 | Check Update | assert(isAuthorized()) | 1027 | Authorized | | 1028 | | | 1029 | Check Version | assert(version_check(current, arg)) | 1030 | | | 1031 | Abort | assert(0) | 1032 | | | 1033 | Try Each | try-each-done if exec(seq) is not error for- | 1034 | | each seq in arg | 1035 | | | 1036 | Copy | store(current, current.params[src-component]) | 1037 | | | 1038 | Swap | swap(current, current.params[src-component]) | 1039 | | | 1040 | Wait For Event | until event(arg), wait | 1041 | | | 1042 | Run Sequence | exec(arg) | 1043 | | | 1044 | Run with | run(current, arg) | 1045 | Arguments | | 1046 | | | 1047 | Garbage Collect | garbage-collect(current) | 1048 +-------------------+-----------------------------------------------+ 1050 6.5. Special Cases of Component Index and Dependency Index 1052 Component Index and Dependency Index can each take on one of three 1053 types: 1055 1. Integer 1057 2. Array of integers 1059 3. True 1061 Integers MUST always be supported by Set Component Index and Set 1062 Dependency Index. Arrays of integers MUST be supported by Set 1063 Component Index and Set Dependency Index if the Recipient supports 3 1064 or more components or 3 or more dependencies, respectively. True 1065 MUST be supported by Set Component Index and Set Dependency Index if 1066 the Recipient supports 2 or more components or 2 or more 1067 dependencies, respectively. Each of these operates on the list of 1068 components or list of dependencies declared in the manifest. 1070 Integer indices are the default case as described in the previous 1071 section. An array of integers represents a list of the components 1072 (Set Component Index) or a list of dependencies (Set Dependency 1073 Index) to which each subsequent command applies. The value True 1074 replaces the list of component indices or dependency indices with the 1075 full list of components or the full list of dependencies, 1076 respectively, as defined in the manifest. 1078 When a command is executed, it either 1. operates on the component or 1079 dependency identified by the component index or dependency index if 1080 that index is an integer, or 2. it operates on each component or 1081 dependency identified by an array of indicies, or 3. it operates on 1082 every component or every dependency if the index is the boolean True. 1083 This is described by the following pseudocode: 1085 if component-index is true: 1086 current-list = components 1087 else if component-index is array: 1088 current-list = [ components[idx] for idx in component-index ] 1089 else if component-index is integer: 1090 current-list = [ components[component-index] ] 1091 else if dependency-index is true: 1092 current-list = dependencies 1093 else if dependency-index is array: 1094 current-list = [ dependencies[idx] for idx in dependency-index ] 1095 else: 1096 current-list = [ dependencies[dependency-index] ] 1097 for current in current-list: 1098 cmd(current) 1100 Try Each and Run Sequence are affected in the same way as other 1101 commands: they are invoked once for each possible Component or 1102 Dependency. This means that the sequences that are arguments to Try 1103 Each and Run Sequence are NOT invoked with Component Index = True or 1104 Dependency Index = True, nor are they invoked with array indices. 1105 They are only invoked with integer indices. The interpreter loops 1106 over the whole sequence, setting the Component Index or Dependency 1107 Index to each index in turn. 1109 6.6. Serialized Processing Interpreter 1111 In highly constrained devices, where storage for parameters is 1112 limited, the manifest processor MAY handle one component at a time, 1113 traversing the manifest tree once for each listed component. In this 1114 mode, the interpreter ignores any commands executed while the 1115 component index is not the current component. This reduces the 1116 overall volatile storage required to process the update so that the 1117 only limit on number of components is the size of the manifest. 1118 However, this approach requires additional processing power. 1120 In order to operate in this mode, the manifest processor loops on 1121 each section for every supported component, simply ignoring commands 1122 when the current component is not selected. 1124 When a serialized Manifest Processor encounters a component or 1125 dependency index of True, it does not ignore any commands. It 1126 applies them to the current component or dependency on each 1127 iteration. 1129 6.7. Parallel Processing Interpreter 1131 Advanced Recipients MAY make use of the Strict Order parameter and 1132 enable parallel processing of some Command Sequences, or it may 1133 reorder some Command Sequences. To perform parallel processing, once 1134 the Strict Order parameter is set to False, the Recipient may issue 1135 each or every command concurrently until the Strict Order parameter 1136 is returned to True or the Command Sequence ends. Then, it waits for 1137 all issued commands to complete before continuing processing of 1138 commands. To perform out-of-order processing, a similar approach is 1139 used, except the Recipient consumes all commands after the Strict 1140 Order parameter is set to False, then it sorts these commands into 1141 its preferred order, invokes them all, then continues processing. 1143 Under each of these scenarios the parallel processing MUST halt until 1144 all issued commands have completed: 1146 - Set Parameters. 1148 - Override Parameters. 1150 - Set Strict Order = True. 1152 - Set Dependency Index. 1154 - Set Component Index. 1156 To perform more useful parallel operations, a manifest author may 1157 collect sequences of commands in a Run Sequence command. Then, each 1158 of these sequences MAY be run in parallel. Each sequence defaults to 1159 Strict Order = True. To isolate each sequence from each other 1160 sequence, each sequence MUST begin with a Set Component Index or Set 1161 Dependency Index directive with the following exception: when the 1162 index is either True or an array of indices, the Set Component Index 1163 or Set Dependency Index is implied. Any further Set Component Index 1164 directives MUST cause an Abort. This allows the interpreter that 1165 issues Run Sequence commands to check that the first element is 1166 correct, then issue the sequence to a parallel execution context to 1167 handle the remainder of the sequence. 1169 6.8. Processing Dependencies 1171 As described in Section 6.2, each manifest must invoke each of its 1172 dependencies sections from the corresponding section of the 1173 dependent. Any changes made to parameters by the dependency persist 1174 in the dependent. 1176 When a Process Dependency command is encountered, the interpreter 1177 loads the dependency identified by the Current Dependency Index. The 1178 interpreter first executes the common-sequence section of the 1179 identified dependency, then it executes the section of the dependency 1180 that corresponds to the currently executing section of the dependent. 1182 If the specified dependency does not contain the current section, 1183 Process Dependency succeeds immediately. 1185 The Manifest Processor MUST also support a Dependency Index of True, 1186 which applies to every dependency, as described in Section 6.5 1188 The interpreter also performs the checks described in Section 6.2 to 1189 ensure that the dependent is processing the dependency correctly. 1191 6.9. Multiple Manifest Processors 1193 When a system has multiple security domains, each domain might 1194 require independent verification of authenticity or security 1195 policies. Security domains might be divided by separation technology 1196 such as Arm TrustZone, Intel SGX, or another TEE technology. 1197 Security domains might also be divided into separate processors and 1198 memory spaces, with a communication interface between them. 1200 For example, an application processor may have an attached 1201 communications module that contains a processor. The communications 1202 module might require metadata signed by a specific Trust Authority 1203 for regulatory approval. This may be a different Trust Authority 1204 than the application processor. 1206 When there are two or more security domains (see 1207 [I-D.ietf-teep-architecture]), a manifest processor might be required 1208 in each. The first manifest processor is the normal manifest 1209 processor as described for the Recipient in Section 6.4. The second 1210 manifest processor only executes sections when the first manifest 1211 processor requests it. An API interface is provided from the second 1212 manifest processor to the first. This allows the first manifest 1213 processor to request a limited set of operations from the second. 1214 These operations are limited to: setting parameters, inserting an 1215 Envelope, invoking a Manifest Command Sequence. The second manifest 1216 processor declares a prefix to the first, which tells the first 1217 manifest processor when it should delegate to the second. These 1218 rules are enforced by underlying separation of privilege 1219 infrastructure, such as TEEs, or physical separation. 1221 When the first manifest processor encounters a dependency prefix, 1222 that informs the first manifest processor that it should provide the 1223 second manifest processor with the corresponding dependency Envelope. 1225 This is done when the dependency is fetched. The second manifest 1226 processor immediately verifies any authentication information in the 1227 dependency Envelope. When a parameter is set for any component that 1228 matches the prefix, this parameter setting is passed to the second 1229 manifest processor via an API. As the first manifest processor works 1230 through the Procedure (set of command sequences) it is executing, 1231 each time it sees a Process Dependency command that is associated 1232 with the prefix declared by the second manifest processor, it uses 1233 the API to ask the second manifest processor to invoke that 1234 dependency section instead. 1236 This mechanism ensures that the two or more manifest processors do 1237 not need to trust each other, except in a very limited case. When 1238 parameter setting across security domains is used, it must be very 1239 carefully considered. Only parameters that do not have an effect on 1240 security properties should be allowed. The dependency manifest MAY 1241 control which parameters are allowed to be set by using the Override 1242 Parameters directive. The second manifest processor MAY also control 1243 which parameters may be set by the first manifest processor by means 1244 of an ACL that lists the allowed parameters. For example, a URI may 1245 be set by a dependent without a substantial impact on the security 1246 properties of the manifest. 1248 7. Creating Manifests 1250 Manifests are created using tools for constructing COSE structures, 1251 calculating cryptographic values and compiling desired system state 1252 into a sequence of operations required to achieve that state. The 1253 process of constructing COSE structures and the calculation of 1254 cryptographic values is covered in [RFC8152]. 1256 Compiling desired system state into a sequence of operations can be 1257 accomplished in many ways. Several templates are provided below to 1258 cover common use-cases. These templates can be combined to produce 1259 more complex behavior. 1261 The author MUST ensure that all parameters consumed by a command are 1262 set prior to invoking that command. Where Component Index = True or 1263 Dependency Index = True, this means that the parameters consumed by 1264 each command MUST have been set for each Component or Dependency, 1265 respectively. 1267 This section details a set of templates for creating manifests. 1268 These templates explain which parameters, commands, and orders of 1269 commands are necessary to achieve a stated goal. 1271 NOTE: On systems that support only a single component and no 1272 dependencies, Set Component Index has no effect and can be omitted. 1274 NOTE: *A digest MUST always be set using Override Parameters, since 1275 this prevents a less-privileged dependent from replacing the digest.* 1277 7.1. Compatibility Check Template 1279 The goal of the compatibility check template ensure that Recipients 1280 only install compatible images. 1282 In this template all information is contained in the common sequence 1283 and the following sequence of commands is used: 1285 - Set Component Index directive (see Section 8.7.7.1) 1287 - Set Parameters directive (see Section 8.7.7.5) for Vendor ID and 1288 Class ID (see Section 8.7.5) 1290 - Check Vendor Identifier condition (see Section 8.7.5.2) 1292 - Check Class Identifier condition (see Section 8.7.5.2) 1294 7.2. Trusted Invocation Template 1296 The goal of the Trusted Invocation template is to ensure that only 1297 authorized code is invoked; such as in Secure Boot or when a Trusted 1298 Application is loaded into a TEE. 1300 The following commands are placed into the common sequence: 1302 - Set Component Index directive (see Section 8.7.7.1) 1304 - Override Parameters directive (see Section 8.7.7.6) for Image 1305 Digest and Image Size (see Section 8.7.5) 1307 Then, the run sequence contains the following commands: 1309 - Set Component Index directive (see Section 8.7.7.1) 1311 - Check Image Match condition (see Section 8.7.6.2) 1313 - Run directive (see Section 8.7.7.12) 1315 7.3. Component Download Template 1317 The goal of the Component Download template is to acquire and store 1318 an image. 1320 The following commands are placed into the common sequence: 1322 - Set Component Index directive (see Section 8.7.7.1) 1324 - Override Parameters directive (see Section 8.7.7.6) for Image 1325 Digest and Image Size (see Section 8.7.5) 1327 Then, the install sequence contains the following commands: 1329 - Set Component Index directive (see Section 8.7.7.1) 1331 - Set Parameters directive (see Section 8.7.7.5) for URI (see 1332 Section 8.7.5.13) 1334 - Fetch directive (see Section 8.7.7.7) 1336 - Check Image Match condition (see Section 8.7.6.2) 1338 The Fetch directive needs the URI parameter to be set to determine 1339 where the image is retrieved from. Additionally, the destination of 1340 where the component shall be stored has to be configured. The URI is 1341 configured via the Set Parameters directive while the destination is 1342 configured via the Set Component Index directive. 1344 Optionally, the Set Parameters directive in the install sequence MAY 1345 also contain Encryption Info (see Section 8.7.5.10), Compression Info 1346 (see Section 8.7.5.11), or Unpack Info (see Section 8.7.5.12) to 1347 perform simultaneous download and decryption, decompression, or 1348 unpacking, respectively. 1350 7.4. Install Template 1352 The goal of the Install template is to use an image already stored in 1353 an identified component to copy into a second component. 1355 This template is typically used with the Component Download template, 1356 however a modification to that template is required: the Component 1357 Download operations are moved from the Payload Install sequence to 1358 the Payload Fetch sequence. 1360 Then, the install sequence contains the following commands: 1362 - Set Component Index directive (see Section 8.7.7.1) 1364 - Set Parameters directive (see Section 8.7.7.5) for Source 1365 Component (see Section 8.7.5.14) 1367 - Copy directive (see Section 8.7.7.9) 1369 - Check Image Match condition (see Section 8.7.6.2) 1371 7.5. Install and Transform Template 1373 The goal of the Install and Transform template is to use an image 1374 already stored in an identified component to decompress, decrypt, or 1375 unpack at time of installation. 1377 This template is typically used with the Component Download template, 1378 however a modification to that template is required: all Component 1379 Download operations are moved from the common sequence and the 1380 install sequence to the fetch sequence. The Component Download 1381 template targets a download component identifier, while the Install 1382 and Transform template uses an install component identifier. In- 1383 place unpacking, decompression, and decryption is complex and 1384 vulnerable to power failure. Therefore, these identifiers SHOULD be 1385 different; in-place installation SHOULD NOT be used without 1386 establishing guarantees of robustness to power failure. 1388 The following commands are placed into the common sequence: 1390 - Set Component Index directive for install component identifier 1391 (see Section 8.7.7.1) 1393 - Override Parameters directive (see Section 8.7.7.6) for Image 1394 Digest and Image Size (see Section 8.7.5) 1396 Then, the install sequence contains the following commands: 1398 - Set Component Index directive for install component identifier 1399 (see Section 8.7.7.1) 1401 - Set Parameters directive (see Section 8.7.7.5) for: 1403 o Source Component for download component identifier (see 1404 Section 8.7.5.14) 1406 o Encryption Info (see Section 8.7.5.10) 1408 o Compression Info (see Section 8.7.5.11) 1410 o Unpack Info (see Section 8.7.5.12) 1412 - Copy directive (see Section 8.7.7.9) 1414 - Check Image Match condition (see Section 8.7.6.2) 1416 7.6. Integrated Payload Template 1418 The goal of the Integrated Payload template is to install a payload 1419 that is included in the manifest envelope. It is identical to the 1420 Component Download template (Section 7.3) except that it places an 1421 added restriction on the URI passed to the Set Parameters directive. 1423 An implementer MAY choose to place a payload in the envelope of a 1424 manifest. The payload envelope key MAY be a positive or negative 1425 integer. The payload envelope key MUST NOT be a value between 0 and 1426 24 and it MUST NOT be used by any other envelope element in the 1427 manifest. The payload MUST be serialized in a bstr element. 1429 The URI for a payload enclosed in this way MUST be expressed as a 1430 fragment-only reference, as defined in [RFC3986], Section 4.4. The 1431 fragment identifier is the stringified envelope key of the payload. 1432 For example, an envelope that contains a payload a key 42 would use a 1433 URI "#42", key -73 would use a URI "#-73". 1435 7.7. Load from Nonvolatile Storage Template 1437 The goal of the Load from Nonvolatile Storage template is to load an 1438 image from a non-volatile component into a volatile component, for 1439 example loading a firmware image from external Flash into RAM. 1441 The following commands are placed into the load sequence: 1443 - Set Component Index directive (see Section 8.7.7.1) 1445 - Set Parameters directive (see Section 8.7.7.5) for Component Index 1446 (see Section 8.7.5) 1448 - Copy directive (see Section 8.7.7.9) 1450 As outlined in Section 6.4, the Copy directive needs a source and a 1451 destination to be configured. The source is configured via Component 1452 Index (with the Set Parameters directive) and the destination is 1453 configured via the Set Component Index directive. 1455 7.8. Load & Decompress from Nonvolatile Storage Template 1457 The goal of the Load & Decompress from Nonvolatile Storage template 1458 is to load an image from a non-volatile component into a volatile 1459 component, decompressing on-the-fly, for example loading a firmware 1460 image from external Flash into RAM. 1462 The following commands are placed into the load sequence: 1464 - Set Component Index directive (see Section 8.7.7.1) 1466 - Set Parameters directive (see Section 8.7.7.5) for Source 1467 Component Index and Compression Info (see Section 8.7.5) 1469 - Copy directive (see Section 8.7.7.9) 1471 This template is similar to Section 7.7 but additionally performs 1472 decompression. Hence, the only difference is in setting the 1473 Compression Info parameter. 1475 This template can be modified for decryption or unpacking by adding 1476 Decryption Info or Unpack Info to the Set Parameters directive. 1478 7.9. Dependency Template 1480 The goal of the Dependency template is to obtain, verify, and process 1481 a dependency manifest as appropriate. 1483 The following commands are placed into the dependency resolution 1484 sequence: 1486 - Set Dependency Index directive (see Section 8.7.7.2) 1488 - Set Parameters directive (see Section 8.7.7.5) for URI (see 1489 Section 8.7.5) 1491 - Fetch directive (see Section 8.7.7.7) 1493 - Check Image Match condition (see Section 8.7.6.2) 1495 - Process Dependency directive (see Section 8.7.7.4) 1497 Then, the validate sequence contains the following operations: 1499 - Set Dependency Index directive (see Section 8.7.7.2) 1501 - Check Image Match condition (see Section 8.7.6.2) 1503 - Process Dependency directive (see Section 8.7.7.4) 1505 NOTE: Any changes made to parameters in a dependency persist in the 1506 dependent. 1508 7.9.1. Composite Manifests 1510 An implementer MAY choose to place a dependency's envelope in the 1511 envelope of its dependent. The dependent envelope key for the 1512 dependency envelope MUST NOT be a value between 0 and 24 and it MUST 1513 NOT be used by any other envelope element in the dependent manifest. 1515 The URI for a dependency enclosed in this way MUST be expressed as a 1516 fragment-only reference, as defined in [RFC3986], Section 4.4. The 1517 fragment identifier is the stringified envelope key of the 1518 dependency. For example, an envelope that contains a dependency at 1519 key 42 would use a URI "#42", key -73 would use a URI "#-73". 1521 7.10. Encrypted Manifest Template 1523 The goal of the Encrypted Manifest template is to fetch and decrypt a 1524 manifest so that it can be used as a dependency. To use an encrypted 1525 manifest, create a plaintext dependent, and add the encrypted 1526 manifest as a dependency. The dependent can include very little 1527 information. 1529 The following operations are placed into the dependency resolution 1530 block: 1532 - Set Dependency Index directive (see Section 8.7.7.2) 1534 - Set Parameters directive (see Section 8.7.7.5) for 1536 o URI (see Section 8.7.5) 1538 o Encryption Info (see Section 8.7.5) 1540 - Fetch directive (see Section 8.7.7.7) 1542 - Check Image Match condition (see Section 8.7.6.2) 1544 - Process Dependency directive (see Section 8.7.7.4) 1546 Then, the validate block contains the following operations: 1548 - Set Dependency Index directive (see Section 8.7.7.2) 1550 - Check Image Match condition (see Section 8.7.6.2) 1552 - Process Dependency directive (see Section 8.7.7.4) 1554 A plaintext manifest and its encrypted dependency may also form a 1555 composite manifest (Section 7.9.1). 1557 7.11. A/B Image Template 1559 The goal of the A/B Image Template is to acquire, validate, and 1560 invoke one of two images, based on a test. 1562 The following commands are placed in the common block: 1564 - Set Component Index directive (see Section 8.7.7.1) 1566 - Try Each 1568 o First Sequence: 1570 * Override Parameters directive (see Section 8.7.7.6, 1571 Section 8.7.5) for Offset A 1573 * Check Offset Condition (see Section 8.7.6.5) 1575 * Override Parameters directive (see Section 8.7.7.6) for 1576 Image Digest A and Image Size A (see Section 8.7.5) 1578 o Second Sequence: 1580 * Override Parameters directive (see Section 8.7.7.6, 1581 Section 8.7.5) for Offset B 1583 * Check Offset Condition (see Section 8.7.6.5) 1585 * Override Parameters directive (see Section 8.7.7.6) for 1586 Image Digest B and Image Size B (see Section 8.7.5) 1588 The following commands are placed in the fetch block or install block 1590 - Set Component Index directive (see Section 8.7.7.1) 1592 - Try Each 1594 o First Sequence: 1596 * Override Parameters directive (see Section 8.7.7.6, 1597 Section 8.7.5) for Offset A 1599 * Check Offset Condition (see Section 8.7.6.5) 1601 * Set Parameters directive (see Section 8.7.7.6) for URI A 1602 (see Section 8.7.5) 1604 o Second Sequence: 1606 * Override Parameters directive (see Section 8.7.7.6, 1607 Section 8.7.5) for Offset B 1609 * Check Offset Condition (see Section 8.7.6.5) 1611 * Set Parameters directive (see Section 8.7.7.6) for URI B 1612 (see Section 8.7.5) 1614 - Fetch 1616 If Trusted Invocation (Section 7.2) is used, only the run sequence is 1617 added to this template, since the common sequence is populated by 1618 this template. 1620 NOTE: Any test can be used to select between images, Check Offset 1621 Condition is used in this template because it is a typical test for 1622 execute-in-place devices. 1624 8. Metadata Structure 1626 The metadata for SUIT updates is composed of several primary 1627 constituent parts: the Envelope, Delegation Chains, Authentication 1628 Information, Manifest, and Severable Elements. 1630 For a diagram of the metadata structure, see Section 5. 1632 8.1. Encoding Considerations 1634 The map indices in the envelope encoding are reset to 1 for each map 1635 within the structure. This is to keep the indices as small as 1636 possible. The goal is to keep the index objects to single bytes 1637 (CBOR positive integers 1-23). 1639 Wherever enumerations are used, they are started at 1. This allows 1640 detection of several common software errors that are caused by 1641 uninitialized variables. Positive numbers in enumerations are 1642 reserved for IANA registration. Negative numbers are used to 1643 identify application-specific values, as described in Section 11. 1645 All elements of the envelope must be wrapped in a bstr to minimize 1646 the complexity of the code that evaluates the cryptographic integrity 1647 of the element and to ensure correct serialization for integrity and 1648 authenticity checks. 1650 8.2. Envelope 1652 The Envelope contains each of the other primary constituent parts of 1653 the SUIT metadata. It allows for modular processing of the manifest 1654 by ordering components in the expected order of processing. 1656 The Envelope is encoded as a CBOR Map. Each element of the Envelope 1657 is enclosed in a bstr, which allows computation of a message digest 1658 against known bounds. 1660 8.3. Delegation Chains 1662 The suit-delegation element MAY carry one or more CBOR Web Tokens 1663 (CWTs) [RFC8392], with [RFC8747] cnf claims. They can be used to 1664 perform enhanced authorization decisions. The CWTs are arranged into 1665 a list of lists. Each list starts with a CWT authorized by a Trust 1666 Anchor, and finishes with a key used to authenticate the Manifest 1667 (see Section 8.4). This allows an Update Authority to delegate from 1668 a long term Trust Anchor, down through intermediaries, to a delegate 1669 without any out-of-band provisioning of Trust Anchors or intermediary 1670 keys. 1672 A Recipient MAY choose to cache intermediaries and/or delegates. If 1673 an Update Distributor knows that a targeted Recipient has cached some 1674 intermediaries or delegates, it MAY choose to strip any cached 1675 intermediaries or delegates from the Delegation Chains in order to 1676 reduce bandwidth and energy. 1678 8.4. Authenticated Manifests 1680 The suit-authentication-wrapper contains a list containing a 1681 Section 10 and one or more cryptographic authentication wrappers for 1682 the Manifest. These are implemented as COSE_Mac_Tagged or 1683 COSE_Sign_Tagged blocks. Each of these blocks contains a SUIT_Digest 1684 of the Manifest. This enables modular processing of the manifest. 1685 The COSE_Mac_Tagged and COSE_Sign_Tagged blocks are described in RFC 1686 8152 [RFC8152]. The suit-authentication-wrapper MUST come before any 1687 element in the SUIT_Envelope, except for the OPTIONAL suit- 1688 delegation, regardless of canonical encoding of CBOR. All validators 1689 MUST reject any SUIT_Envelope that begins with any element other than 1690 a suit-authentication-wrapper or suit-delegation. 1692 A SUIT_Envelope that has not had authentication information added 1693 MUST still contain the suit-authentication-wrapper element, but the 1694 content MUST be a list containing only the SUIT_Digest. 1696 A signing application MUST verify the suit-manifest element against 1697 the SUIT_Digest prior to signing. 1699 8.5. Encrypted Manifests 1701 To use an encrypted manifest, it must be a dependency of a plaintext 1702 manifest. This allows fine-grained control of what information is 1703 accessible to intermediate systems for the purposes of management, 1704 while still preserving the confidentiality of the manifest contents. 1705 This also means that a Recipient can process an encrypted manifest in 1706 the same way as an encrypted payload, allowing code reuse. 1708 A template for using an encrypted manifest is covered in Encrypted 1709 Manifest Template (Section 7.10). 1711 8.6. Manifest 1713 The manifest contains: 1715 - a version number (see Section 8.6.1) 1717 - a sequence number (see Section 8.6.2) 1719 - a reference URI (see Section 8.6.3) 1721 - a common structure with information that is shared between command 1722 sequences (see Section 8.7.2) 1724 - one or more lists of commands that the Recipient should perform 1725 (see Section 8.7.3) 1727 - a reference to the full manifest (see Section 8.6.3) 1729 - human-readable text describing the manifest found in the 1730 SUIT_Envelope (see Section 8.6.4) 1732 - a Concise Software Identifier (CoSWID) found in the SUIT_Envelope 1733 (see Section 8.7.1) 1735 The CoSWID, Text section, or any Command Sequence of the Update 1736 Procedure (Dependency Resolution, Image Fetch, Image Installation) 1737 can be either a CBOR structure or a SUIT_Digest. In each of these 1738 cases, the SUIT_Digest provides for a severable element. Severable 1739 elements are RECOMMENDED to implement. In particular, the human- 1740 readable text SHOULD be severable, since most useful text elements 1741 occupy more space than a SUIT_Digest, but are not needed by the 1742 Recipient. Because SUIT_Digest is a CBOR Array and each severable 1743 element is a CBOR bstr, it is straight-forward for a Recipient to 1744 determine whether an element has been severed. The key used for a 1745 severable element is the same in the SUIT_Manifest and in the 1746 SUIT_Envelope so that a Recipient can easily identify the correct 1747 data in the envelope. See Section 8.7.9 for more detail. 1749 8.6.1. suit-manifest-version 1751 The suit-manifest-version indicates the version of serialization used 1752 to encode the manifest. Version 1 is the version described in this 1753 document. suit-manifest-version is REQUIRED to implement. 1755 8.6.2. suit-manifest-sequence-number 1757 The suit-manifest-sequence-number is a monotonically increasing anti- 1758 rollback counter. It also helps Recipients to determine which in a 1759 set of manifests is the "root" manifest in a given update. Each 1760 manifest MUST have a sequence number higher than each of its 1761 dependencies. Each Recipient MUST reject any manifest that has a 1762 sequence number lower than its current sequence number. For 1763 convenience, an implementer MAY use a UTC timestamp in seconds as the 1764 sequence number. suit-manifest-sequence-number is REQUIRED to 1765 implement. 1767 8.6.3. suit-reference-uri 1769 suit-reference-uri is a text string that encodes a URI where a full 1770 version of this manifest can be found. This is convenient for 1771 allowing management systems to show the severed elements of a 1772 manifest when this URI is reported by a Recipient after installation. 1774 8.6.4. suit-text 1776 suit-text SHOULD be a severable element. suit-text is a map 1777 containing two different types of pair: 1779 - integer => text 1781 - SUIT_Component_Identifier => map 1783 Each SUIT_Component_Identifier => map entry contains a map of integer 1784 => text values. All SUIT_Component_Identifiers present in suit-text 1785 MUST also be present in suit-common (Section 8.7.2) or the suit- 1786 common of a dependency. 1788 suit-text contains all the human-readable information that describes 1789 any and all parts of the manifest, its payload(s) and its 1790 resource(s). The text section is typically severable, allowing 1791 manifests to be distributed without the text, since end-nodes do not 1792 require text. The meaning of each field is described below. 1794 Each section MAY be present. If present, each section MUST be as 1795 described. Negative integer IDs are reserved for application- 1796 specific text values. 1798 The following table describes the text fields available in suit-text: 1800 +--------------------------------+----------------------------------+ 1801 | CDDL Structure | Description | 1802 +--------------------------------+----------------------------------+ 1803 | suit-text-manifest-description | Free text description of the | 1804 | | manifest | 1805 | | | 1806 | suit-text-update-description | Free text description of the | 1807 | | update | 1808 | | | 1809 | suit-text-manifest-json-source | The JSON-formatted document that | 1810 | | was used to create the manifest | 1811 | | | 1812 | suit-text-manifest-yaml-source | The YAML ([YAML])-formatted | 1813 | | document that was used to create | 1814 | | the manifest | 1815 +--------------------------------+----------------------------------+ 1817 The following table describes the text fields available in each map 1818 identified by a SUIT_Component_Identifier. 1820 +---------------------------------+---------------------------------+ 1821 | CDDL Structure | Description | 1822 +---------------------------------+---------------------------------+ 1823 | suit-text-vendor-name | Free text vendor name | 1824 | | | 1825 | suit-text-model-name | Free text model name | 1826 | | | 1827 | suit-text-vendor-domain | The domain used to create the | 1828 | | vendor-id condition | 1829 | | | 1830 | suit-text-model-info | The information used to create | 1831 | | the class-id condition | 1832 | | | 1833 | suit-text-component-description | Free text description of each | 1834 | | component in the manifest | 1835 | | | 1836 | suit-text-component-version | A free text representation of | 1837 | | the component version | 1838 | | | 1839 | suit-text-version-required | A free text expression of the | 1840 | | required version number | 1841 +---------------------------------+---------------------------------+ 1842 suit-text is OPTIONAL to implement. 1844 8.7. text-version-required 1846 suit-text-version-required is used to represent a version-based 1847 dependency on suit-parameter-version as described in Section 8.7.5.18 1848 and Section 8.7.6.8. To describe a version dependency, a Manifest 1849 Author SHOULD populate the suit-text map with a 1850 SUIT_Component_Identifier key for the dependency component, and place 1851 in the corresponding map a suit-text-version-required key with a free 1852 text expression that is representative of the version constraints 1853 placed on the dependency. This text SHOULD be expressive enough that 1854 a device operator can be expected to understand the dependency. This 1855 is a free text field and there are no specific formatting rules. 1857 By way of example only, to express a dependency on a component "['x', 1858 'y']", where the version should be any v1.x later than v1.2.5, but 1859 not v2.0 or above, the author would add the following structure to 1860 the suit-text element. Note that this text is in cbor-diag notation. 1862 [h'78',h'79'] : { 1863 7 : ">=1.2.5,<2" 1864 } 1866 8.7.1. suit-coswid 1868 suit-coswid contains a Concise Software Identifier (CoSWID) as 1869 defined in [I-D.ietf-sacm-coswid]. This element SHOULD be made 1870 severable so that it can be discarded by the Recipient or an 1871 intermediary if it is not required by the Recipient. 1873 suit-coswid typically requires no processing by the Recipient. 1874 However all Recipients MUST NOT fail if a suit-coswid is present. 1876 8.7.2. suit-common 1878 suit-common encodes all the information that is shared between each 1879 of the command sequences, including: suit-dependencies, suit- 1880 components, and suit-common-sequence. suit-common is REQUIRED to 1881 implement. 1883 suit-dependencies is a list of Section 8.7.2.1 blocks that specify 1884 manifests that must be present before the current manifest can be 1885 processed. suit-dependencies is OPTIONAL to implement. 1887 suit-components is a list of SUIT_Component_Identifier 1888 (Section 8.7.2.2) blocks that specify the component identifiers that 1889 will be affected by the content of the current manifest. suit- 1890 components is REQUIRED to implement; at least one manifest in a 1891 dependency tree MUST contain a suit-components block. 1893 suit-common-sequence is a SUIT_Command_Sequence to execute prior to 1894 executing any other command sequence. Typical actions in suit- 1895 common-sequence include setting expected Recipient identity and image 1896 digests when they are conditional (see Section 8.7.7.3 and 1897 Section 7.11 for more information on conditional sequences). suit- 1898 common-sequence is RECOMMENDED to implement. It is REQUIRED if the 1899 optimizations described in Section 6.2.1 will be used. Whenever a 1900 parameter or Try Each command is required by more than one Command 1901 Sequence, placing that parameter or commamd in suit-common-sequence 1902 results in a smaller encoding. 1904 8.7.2.1. Dependencies 1906 SUIT_Dependency specifies a manifest that describes a dependency of 1907 the current manifest. The Manifest is identified, but the Recipient 1908 should expect an Envelope when it acquires the dependency. This is 1909 because the Manifest is the one invariant element of the Envelope, 1910 where other elements may change by countersigning, adding 1911 authentication blocks, or severing elements. 1913 The suit-dependency-digest specifies the dependency manifest uniquely 1914 by identifying a particular Manifest structure. This is identical to 1915 the digest that would be present as the payload of any suit- 1916 authentication-block in the dependency's Envelope. The digest is 1917 calculated over the Manifest structure instead of the COSE 1918 Sig_structure or Mac_structure. This is necessary to ensure that 1919 removing a signature from a manifest does not break dependencies due 1920 to missing signature elements. This is also necessary to support the 1921 trusted intermediary use case, where an intermediary re-signs the 1922 Manifest, removing the original signature, potentially with a 1923 different algorithm, or trading COSE_Sign for COSE_Mac. 1925 The suit-dependency-prefix element contains a 1926 SUIT_Component_Identifier (see Section 8.7.2.2). This specifies the 1927 scope at which the dependency operates. This allows the dependency 1928 to be forwarded on to a component that is capable of parsing its own 1929 manifests. It also allows one manifest to be deployed to multiple 1930 dependent Recipients without those Recipients needing consistent 1931 component hierarchy. This element is OPTIONAL for Recipients to 1932 implement. 1934 A dependency prefix can be used with a component identifier. This 1935 allows complex systems to understand where dependencies need to be 1936 applied. The dependency prefix can be used in one of two ways. The 1937 first simply prepends the prefix to all Component Identifiers in the 1938 dependency. 1940 A dependency prefix can also be used to indicate when a dependency 1941 manifest needs to be processed by a secondary manifest processor, as 1942 described in Section 6.9. 1944 8.7.2.2. SUIT_Component_Identifier 1946 A component is a unit of code or data that can be targeted by an 1947 update. To facilitate composite devices, components are identified 1948 by a list of CBOR byte strings, which allows construction of 1949 hierarchical component structures. A dependency MAY declare a prefix 1950 to the components defined in the dependency manifest. Components are 1951 identified by Component Identifiers, but referenced in commands by 1952 Component Index; Component Identifiers are arrays of binary strings 1953 and a Component Index is an index into the array of Component 1954 Identifiers. 1956 A Component Identifier can be trivial, such as the simple array 1957 [h'00']. It can also represent a filesystem path by encoding each 1958 segment of the path as an element in the list. For example, the path 1959 "/usr/bin/env" would encode to ['usr','bin','env']. 1961 This hierarchical construction allows a component identifier to 1962 identify any part of a complex, multi-component system. 1964 8.7.3. SUIT_Command_Sequence 1966 A SUIT_Command_Sequence defines a series of actions that the 1967 Recipient MUST take to accomplish a particular goal. These goals are 1968 defined in the manifest and include: 1970 1. Dependency Resolution: suit-dependency-resolution is a 1971 SUIT_Command_Sequence to execute in order to perform dependency 1972 resolution. Typical actions include configuring URIs of 1973 dependency manifests, fetching dependency manifests, and 1974 validating dependency manifests' contents. suit-dependency- 1975 resolution is REQUIRED to implement and to use when suit- 1976 dependencies is present. 1978 2. Payload Fetch: suit-payload-fetch is a SUIT_Command_Sequence to 1979 execute in order to obtain a payload. Some manifests may include 1980 these actions in the suit-install section instead if they operate 1981 in a streaming installation mode. This is particularly relevant 1982 for constrained devices without any temporary storage for staging 1983 the update. suit-payload-fetch is OPTIONAL to implement. 1985 3. Payload Installation: suit-install is a SUIT_Command_Sequence to 1986 execute in order to install a payload. Typical actions include 1987 verifying a payload stored in temporary storage, copying a staged 1988 payload from temporary storage, and unpacking a payload. suit- 1989 install is OPTIONAL to implement. 1991 4. Image Validation: suit-validate is a SUIT_Command_Sequence to 1992 execute in order to validate that the result of applying the 1993 update is correct. Typical actions involve image validation and 1994 manifest validation. suit-validate is REQUIRED to implement. If 1995 the manifest contains dependencies, one process-dependency 1996 invocation per dependency or one process-dependency invocation 1997 targeting all dependencies SHOULD be present in validate. 1999 5. Image Loading: suit-load is a SUIT_Command_Sequence to execute in 2000 order to prepare a payload for execution. Typical actions 2001 include copying an image from permanent storage into RAM, 2002 optionally including actions such as decryption or decompression. 2003 suit-load is OPTIONAL to implement. 2005 6. Run or Boot: suit-run is a SUIT_Command_Sequence to execute in 2006 order to run an image. suit-run typically contains a single 2007 instruction: either the "run" directive for the invocable 2008 manifest or the "process dependencies" directive for any 2009 dependents of the invocable manifest. suit-run is OPTIONAL to 2010 implement. 2012 Goals 1,2,3 form the Update Procedure. Goals 4,5,6 form the 2013 Invocation Procedure. 2015 Each Command Sequence follows exactly the same structure to ensure 2016 that the parser is as simple as possible. 2018 Lists of commands are constructed from two kinds of element: 2020 1. Conditions that MUST be true and any failure is treated as a 2021 failure of the update/load/invocation 2023 2. Directives that MUST be executed. 2025 Each condition is composed of: 2027 1. A command code identifier 2029 2. A SUIT_Reporting_Policy (Section 8.7.4) 2031 Each directive is composed of: 2033 1. A command code identifier 2035 2. An argument block or a SUIT_Reporting_Policy (Section 8.7.4) 2037 Argument blocks are consumed only by flow-control directives: 2039 - Set Component/Dependency Index 2041 - Set/Override Parameters 2043 - Try Each 2045 - Run Sequence 2047 Reporting policies provide a hint to the manifest processor of 2048 whether to add the success or failure of a command to any report that 2049 it generates. 2051 Many conditions and directives apply to a given component, and these 2052 generally grouped together. Therefore, a special command to set the 2053 current component index is provided with a matching command to set 2054 the current dependency index. This index is a numeric index into the 2055 Component Identifier tables defined at the beginning of the manifest. 2056 For the purpose of setting the index, the two Component Identifier 2057 tables are considered to be concatenated together. 2059 To facilitate optional conditions, a special directive, suit- 2060 directive-try-each (Section 8.7.7.3), is provided. It runs several 2061 new lists of conditions/directives, one after another, that are 2062 contained as an argument to the directive. By default, it assumes 2063 that a failure of a condition should not indicate a failure of the 2064 update/invocation, but a parameter is provided to override this 2065 behavior. See suit-parameter-soft-failure (Section 8.7.5.23). 2067 8.7.4. Reporting Policy 2069 To facilitate construction of Reports that describe the success, or 2070 failure of a given Procedure, each command is given a Reporting 2071 Policy. This is an integer bitfield that follows the command and 2072 indicates what the Recipient should do with the Record of executing 2073 the command. The options are summarized in the table below. 2075 +-----------------------------+-------------------------------------+ 2076 | Policy | Description | 2077 +-----------------------------+-------------------------------------+ 2078 | suit-send-record-on-success | Record when the command succeeds | 2079 | | | 2080 | suit-send-record-on-failure | Record when the command fails | 2081 | | | 2082 | suit-send-sysinfo-success | Add system information when the | 2083 | | command succeeds | 2084 | | | 2085 | suit-send-sysinfo-failure | Add system information when the | 2086 | | command fails | 2087 +-----------------------------+-------------------------------------+ 2089 Any or all of these policies may be enabled at once. 2091 At the completion of each command, a Manifest Processor MAY forward 2092 information about the command to a Reporting Engine, which is 2093 responsible for reporting boot or update status to a third party. 2094 The Reporting Engine is entirely implementation-defined, the 2095 reporting policy simply facilitates the Reporting Engine's interface 2096 to the SUIT Manifest Processor. 2098 The information elements provided to the Reporting Engine are: 2100 - The reporting policy 2102 - The result of the command 2104 - The values of parameters consumed by the command 2106 - The system information consumed by the command 2108 Together, these elements are called a Record. A group of Records is 2109 a Report. 2111 If the component index is set to True or an array when a command is 2112 executed with a non-zero reporting policy, then the Reporting Engine 2113 MUST receive one Record for each Component, in the order expressed in 2114 the Components list or the component index array. If the dependency 2115 index is set to True or an array when a command is executed with a 2116 non-zero reporting policy, then the Reporting Engine MUST receive one 2117 Record for each Dependency, in the order expressed in the 2118 Dependencies list or the component index array, respectively. 2120 This specification does not define a particular format of Records or 2121 Reports. This specification only defines hints to the Reporting 2122 Engine for which Records it should aggregate into the Report. The 2123 Reporting Engine MAY choose to ignore these hints and apply its own 2124 policy instead. 2126 When used in a Invocation Procedure, the report MAY form the basis of 2127 an attestation report. When used in an Update Process, the report 2128 MAY form the basis for one or more log entries. 2130 8.7.5. SUIT_Parameters 2132 Many conditions and directives require additional information. That 2133 information is contained within parameters that can be set in a 2134 consistent way. This allows reduction of manifest size and 2135 replacement of parameters from one manifest to the next. 2137 Most parameters are scoped to a specific component. This means that 2138 setting a parameter for one component has no effect on the parameters 2139 of any other component. The only exceptions to this are two Manifest 2140 Processor parameters: Strict Order and Soft Failure. 2142 The defined manifest parameters are described below. 2144 +----------------+----------------------------------+---------------+ 2145 | Name | CDDL Structure | Reference | 2146 +----------------+----------------------------------+---------------+ 2147 | Vendor ID | suit-parameter-vendor-identifier | Section 8.7.5 | 2148 | | | .3 | 2149 | | | | 2150 | Class ID | suit-parameter-class-identifier | Section 8.7.5 | 2151 | | | .4 | 2152 | | | | 2153 | Device ID | suit-parameter-device-identifier | Section 8.7.5 | 2154 | | | .5 | 2155 | | | | 2156 | Image Digest | suit-parameter-image-digest | Section 8.7.5 | 2157 | | | .6 | 2158 | | | | 2159 | Image Size | suit-parameter-image-size | Section 8.7.5 | 2160 | | | .7 | 2161 | | | | 2162 | Use Before | suit-parameter-use-before | Section 8.7.5 | 2163 | | | .8 | 2164 | | | | 2165 | Component | suit-parameter-component-offset | Section 8.7.5 | 2166 | Offset | | .9 | 2167 | | | | 2168 | Encryption | suit-parameter-encryption-info | Section 8.7.5 | 2169 | Info | | .10 | 2170 | | | | 2171 | Compression | suit-parameter-compression-info | Section 8.7.5 | 2172 | Info | | .11 | 2173 | | | | 2174 | Unpack Info | suit-parameter-unpack-info | Section 8.7.5 | 2175 | | | .12 | 2176 | | | | 2177 | URI | suit-parameter-uri | Section 8.7.5 | 2178 | | | .13 | 2179 | | | | 2180 | Source | suit-parameter-source-component | Section 8.7.5 | 2181 | Component | | .14 | 2182 | | | | 2183 | Run Args | suit-parameter-run-args | Section 8.7.5 | 2184 | | | .15 | 2185 | | | | 2186 | Minimum | suit-parameter-minimum-battery | Section 8.7.5 | 2187 | Battery | | .16 | 2188 | | | | 2189 | Update | suit-parameter-update-priority | Section 8.7.5 | 2190 | Priority | | .17 | 2191 | | | | 2192 | Version | suit-parameter-version | Section 8.7.5 | 2193 | | | .18 | 2194 | | | | 2195 | Wait Info | suit-parameter-wait-info | Section 8.7.5 | 2196 | | | .19 | 2197 | | | | 2198 | URI List | suit-parameter-uri-list | Section 8.7.5 | 2199 | | | .20 | 2200 | | | | 2201 | Fetch | suit-parameter-fetch-arguments | Section 8.7.5 | 2202 | Arguments | | .21 | 2203 | | | | 2204 | Strict Order | suit-parameter-strict-order | Section 8.7.5 | 2205 | | | .22 | 2206 | | | | 2207 | Soft Failure | suit-parameter-soft-failure | Section 8.7.5 | 2208 | | | .23 | 2209 | | | | 2210 | Custom | suit-parameter-custom | Section 8.7.5 | 2211 | | | .24 | 2212 +----------------+----------------------------------+---------------+ 2214 CBOR-encoded object parameters are still wrapped in a bstr. This is 2215 because it allows a parser that is aggregating parameters to 2216 reference the object with a single pointer and traverse it without 2217 understanding the contents. This is important for modularization and 2218 division of responsibility within a pull parser. The same 2219 consideration does not apply to Directives because those elements are 2220 invoked with their arguments immediately 2222 8.7.5.1. CBOR PEN UUID Namespace Identifier 2224 The CBOR PEN UUID Namespace Identifier is constructed as follows: 2226 It uses the OID Namespace as a starting point, then uses the CBOR OID 2227 encoding for the IANA PEN OID (1.3.6.1.4.1): 2229 D8 DE # tag(111) 2230 45 # bytes(5) 2231 2B 06 01 04 01 # X.690 Clause 8.19 2232 # 1.3 6 1 4 1 show component encoding 2234 Computing a type 5 UUID from these produces: 2236 NAMESPACE_CBOR_PEN = UUID5(NAMESPACE_OID, h'D86F452B06010401') 2237 NAMESPACE_CBOR_PEN = 08cfcc43-47d9-5696-85b1-9c738465760e 2239 8.7.5.2. Constructing UUIDs 2241 Several conditions use identifiers to determine whether a manifest 2242 matches a given Recipient or not. These identifiers are defined to 2243 be RFC 4122 [RFC4122] UUIDs. These UUIDs are not human-readable and 2244 are therefore used for machine-based processing only. 2246 A Recipient MAY match any number of UUIDs for vendor or class 2247 identifier. This may be relevant to physical or software modules. 2248 For example, a Recipient that has an OS and one or more applications 2249 might list one Vendor ID for the OS and one or more additional Vendor 2250 IDs for the applications. This Recipient might also have a Class ID 2251 that must be matched for the OS and one or more Class IDs for the 2252 applications. 2254 Identifiers are used for compatibility checks. They MUST NOT be used 2255 as assertions of identity. They are evaluated by identifier 2256 conditions (Section 8.7.6.1). 2258 A more complete example: Imagine a device has the following physical 2259 components: 1. A host MCU 2. A WiFi module 2261 This same device has three software modules: 1. An operating system 2262 2. A WiFi module interface driver 3. An application 2264 Suppose that the WiFi module's firmware has a proprietary update 2265 mechanism and doesn't support manifest processing. This device can 2266 report four class IDs: 2268 1. Hardware model/revision 2270 2. OS 2272 3. WiFi module model/revision 2274 4. Application 2276 This allows the OS, WiFi module, and application to be updated 2277 independently. To combat possible incompatibilities, the OS class ID 2278 can be changed each time the OS has a change to its API. 2280 This approach allows a vendor to target, for example, all devices 2281 with a particular WiFi module with an update, which is a very 2282 powerful mechanism, particularly when used for security updates. 2284 UUIDs MUST be created according to RFC 4122 [RFC4122]. UUIDs SHOULD 2285 use versions 3, 4, or 5, as described in RFC4122. Versions 1 and 2 2286 do not provide a tangible benefit over version 4 for this 2287 application. 2289 The RECOMMENDED method to create a vendor ID is: 2291 Vendor ID = UUID5(DNS_PREFIX, vendor domain name) 2293 If the Vendor ID is a UUID, the RECOMMENDED method to create a Class 2294 ID is: 2296 Class ID = UUID5(Vendor ID, Class-Specific-Information) 2298 If the Vendor ID is a CBOR PEN (see Section 8.7.5.3), the RECOMMENDED 2299 method to create a Class ID is: 2301 Class ID = UUID5( 2302 UUID5(NAMESPACE_CBOR_PEN, CBOR_PEN), 2303 Class-Specific-Information) 2305 Class-specific-information is composed of a variety of data, for 2306 example: 2308 - Model number. 2310 - Hardware revision. 2312 - Bootloader version (for immutable bootloaders). 2314 8.7.5.3. suit-parameter-vendor-identifier 2316 suit-parameter-vendor-identifier may be presented in one of two ways: 2318 - A Private Enterprise Number 2320 - A byte string containing a UUID ([RFC4122]) 2322 Private Enterprise Numbers are encoded as a relative OID, according 2323 to the definition in [I-D.ietf-cbor-tags-oid]. All PENs are relative 2324 to the IANA PEN: 1.3.6.1.4.1. 2326 8.7.5.4. suit-parameter-class-identifier 2328 A RFC 4122 UUID representing the class of the device or component. 2329 The UUID is encoded as a 16 byte bstr, containing the raw bytes of 2330 the UUID. It MUST be constructed as described in Section 8.7.5.2 2332 8.7.5.5. suit-parameter-device-identifier 2334 A RFC 4122 UUID representing the specific device or component. The 2335 UUID is encoded as a 16 byte bstr, containing the raw bytes of the 2336 UUID. It MUST be constructed as described in Section 8.7.5.2 2338 8.7.5.6. suit-parameter-image-digest 2340 A fingerprint computed over the component itself, encoded in the 2341 SUIT_Digest Section 10 structure. The SUIT_Digest is wrapped in a 2342 bstr, as required in Section 8.7.5. 2344 8.7.5.7. suit-parameter-image-size 2346 The size of the firmware image in bytes. This size is encoded as a 2347 positive integer. 2349 8.7.5.8. suit-parameter-use-before 2351 An expiry date for the use of the manifest encoded as the positive 2352 integer number of seconds since 1970-01-01. Implementations that use 2353 this parameter MUST use a 64-bit internal representation of the 2354 integer. 2356 8.7.5.9. suit-parameter-component-offset 2358 This parameter sets the offset in a component. Some components 2359 support multiple possible Slots (offsets into a storage area). This 2360 parameter describes the intended Slot to use, identified by its 2361 offset into the component's storage area. This offset MUST be 2362 encoded as a positive integer. 2364 8.7.5.10. suit-parameter-encryption-info 2366 Encryption Info defines the mechanism that Fetch or Copy should use 2367 to decrypt the data they transfer. SUIT_Parameter_Encryption_Info is 2368 encoded as a COSE_Encrypt_Tagged or a COSE_Encrypt0_Tagged, wrapped 2369 in a bstr. 2371 8.7.5.11. suit-parameter-compression-info 2373 SUIT_Compression_Info defines any information that is required for a 2374 Recipient to perform decompression operations. SUIT_Compression_Info 2375 is a map containing this data. The only element defined for the map 2376 in this specification is the suit-compression-algorithm. This 2377 document defines the following suit-compression-algorithm's: ZLIB 2378 [RFC1950], Brotli [RFC7932], and ZSTD [I-D.kucherawy-rfc8478bis]. 2380 Additional suit-compression-algorithm's can be registered through the 2381 IANA-maintained registry. If such a format requires more data than 2382 an algorithm identifier, one or more new elements MUST be introduced 2383 by specifying an element for SUIT_Compression_Info-extensions. 2385 8.7.5.12. suit-parameter-unpack-info 2387 SUIT_Unpack_Info defines the information required for a Recipient to 2388 interpret a packed format. This document defines the use of the 2389 following binary encodings: Intel HEX [HEX], Motorola S-record 2390 [SREC], Executable and Linkable Format (ELF) [ELF], and Common Object 2391 File Format (COFF) [COFF]. 2393 Additional packing formats can be registered through the IANA- 2394 maintained registry. 2396 8.7.5.13. suit-parameter-uri 2398 A URI from which to fetch a resource, encoded as a text string. CBOR 2399 Tag 32 is not used because the meaning of the text string is 2400 unambiguous in this context. 2402 8.7.5.14. suit-parameter-source-component 2404 This parameter sets the source component to be used with either suit- 2405 directive-copy (Section 8.7.7.9) or with suit-directive-swap 2406 (Section 8.7.7.13). The current Component, as set by suit-directive- 2407 set-component-index defines the destination, and suit-parameter- 2408 source-component defines the source. 2410 8.7.5.15. suit-parameter-run-args 2412 This parameter contains an encoded set of arguments for suit- 2413 directive-run (Section 8.7.7.10). The arguments MUST be provided as 2414 an implementation-defined bstr. 2416 8.7.5.16. suit-parameter-minimum-battery 2418 This parameter sets the minimum battery level in mWh. This parameter 2419 is encoded as a positive integer. Used with suit-condition-minimum- 2420 battery (Section 8.7.6.6). 2422 8.7.5.17. suit-parameter-update-priority 2424 This parameter sets the priority of the update. This parameter is 2425 encoded as an integer. It is used along with suit-condition-update- 2426 authorized (Section 8.7.6.7) to ask an application for permission to 2427 initiate an update. This does not constitute a privilege inversion 2428 because an explicit request for authorization has been provided by 2429 the Update Authority in the form of the suit-condition-update- 2430 authorized command. 2432 Applications MAY define their own meanings for the update priority. 2433 For example, critical reliability & vulnerability fixes MAY be given 2434 negative numbers, while bug fixes MAY be given small positive 2435 numbers, and feature additions MAY be given larger positive numbers, 2436 which allows an application to make an informed decision about 2437 whether and when to allow an update to proceed. 2439 8.7.5.18. suit-parameter-version 2441 Indicates allowable versions for the specified component. Allowable 2442 versions can be specified, either with a list or with range matching. 2443 This parameter is compared with version asserted by the current 2444 component when suit-condition-version (Section 8.7.6.8) is invoked. 2445 The current component may assert the current version in many ways, 2446 including storage in a parameter storage database, in a metadata 2447 object, or in a known location within the component itself. 2449 The component version can be compared as: 2451 - Greater. 2453 - Greater or Equal. 2455 - Equal. 2457 - Lesser or Equal. 2459 - Lesser. 2461 Versions are encoded as a CBOR list of integers. Comparisons are 2462 done on each integer in sequence. Comparison stops after all 2463 integers in the list defined by the manifest have been consumed OR 2464 after a non-equal match has occurred. For example, if the manifest 2465 defines a comparison, "Equal [1]", then this will match all version 2466 sequences starting with 1. If a manifest defines both "Greater or 2467 Equal [1,0]" and "Lesser [1,10]", then it will match versions 1.0.x 2468 up to, but not including 1.10. 2470 While the exact encoding of versions is application-defined, semantic 2471 versions map conveniently. For example, 2473 - 1.2.3 = [1,2,3]. 2475 - 1.2-rc3 = [1,2,-1,3]. 2477 - 1.2-beta = [1,2,-2]. 2479 - 1.2-alpha = [1,2,-3]. 2481 - 1.2-alpha4 = [1,2,-3,4]. 2483 suit-condition-version is OPTIONAL to implement. 2485 Versions SHOULD be provided as follows: 2487 1. The first integer represents the major number. This indicates 2488 breaking changes to the component. 2490 2. The second integer represents the minor number. This is 2491 typically reserved for new features or large, non-breaking 2492 changes. 2494 3. The third integer is the patch version. This is typically 2495 reserved for bug fixes. 2497 4. The fourth integer is the build number. 2499 Where Alpha (-3), Beta (-2), and Release Candidate (-1) are used, 2500 they are inserted as a negative number between Minor and Patch 2501 numbers. This allows these releases to compare correctly with final 2502 releases. For example, Version 2.0, RC1 should be lower than Version 2503 2.0.0 and higher than any Version 1.x. By encoding RC as -1, this 2504 works correctly: [2,0,-1,1] compares as lower than [2,0,0]. 2505 Similarly, beta (-2) is lower than RC and alpha (-3) is lower than 2506 RC. 2508 8.7.5.19. suit-parameter-wait-info 2510 suit-directive-wait (Section 8.7.7.11) directs the manifest processor 2511 to pause until a specified event occurs. The suit-parameter-wait- 2512 info encodes the parameters needed for the directive. 2514 The exact implementation of the pause is implementation-defined. For 2515 example, this could be done by blocking on a semaphore, registering 2516 an event handler and suspending the manifest processor, polling for a 2517 notification, or aborting the update entirely, then restarting when a 2518 notification is received. 2520 suit-parameter-wait-info is encoded as a map of wait events. When 2521 ALL wait events are satisfied, the Manifest Processor continues. The 2522 wait events currently defined are described in the following table. 2524 +------------------------------+---------+--------------------------+ 2525 | Name | Encodin | Description | 2526 | | g | | 2527 +------------------------------+---------+--------------------------+ 2528 | suit-wait-event- | int | Same as suit-parameter- | 2529 | authorization | | update-priority | 2530 | | | | 2531 | suit-wait-event-power | int | Wait until power state | 2532 | | | | 2533 | suit-wait-event-network | int | Wait until network state | 2534 | | | | 2535 | suit-wait-event-other- | See | Wait for other device to | 2536 | device-version | below | match version | 2537 | | | | 2538 | suit-wait-event-time | uint | Wait until time (seconds | 2539 | | | since 1970-01-01) | 2540 | | | | 2541 | suit-wait-event-time-of-day | uint | Wait until seconds since | 2542 | | | 00:00:00 | 2543 | | | | 2544 | suit-wait-event-time-of-day- | uint | Wait until seconds since | 2545 | utc | | 00:00:00 UTC | 2546 | | | | 2547 | suit-wait-event-day-of-week | uint | Wait until days since | 2548 | | | Sunday | 2549 | | | | 2550 | suit-wait-event-day-of-week- | uint | Wait until days since | 2551 | utc | | Sunday UTC | 2552 +------------------------------+---------+--------------------------+ 2554 suit-wait-event-other-device-version reuses the encoding of suit- 2555 parameter-version-match. It is encoded as a sequence that contains 2556 an implementation-defined bstr identifier for the other device, and a 2557 list of one or more SUIT_Parameter_Version_Match. 2559 8.7.5.20. suit-parameter-uri-list 2561 Indicates a list of URIs from which to fetch a resource. The URI 2562 list is encoded as a list of text string, in priority order. CBOR 2563 Tag 32 is not used because the meaning of the text string is 2564 unambiguous in this context. The Recipient should attempt to fetch 2565 the resource from each URI in turn, ruling out each, in order, if the 2566 resource is inaccessible or it is otherwise undesirable to fetch from 2567 that URI. suit-parameter-uri-list is consumed by suit-directive- 2568 fetch-uri-list (Section 8.7.7.8). 2570 8.7.5.21. suit-parameter-fetch-arguments 2572 An implementation-defined set of arguments to suit-directive-fetch 2573 (Section 8.7.7.7). Arguments are encoded in a bstr. 2575 8.7.5.22. suit-parameter-strict-order 2577 The Strict Order Parameter allows a manifest to govern when 2578 directives can be executed out-of-order. This allows for systems 2579 that have a sensitivity to order of updates to choose the order in 2580 which they are executed. It also allows for more advanced systems to 2581 parallelize their handling of updates. Strict Order defaults to 2582 True. It MAY be set to False when the order of operations does not 2583 matter. When arriving at the end of a command sequence, ALL commands 2584 MUST have completed, regardless of the state of 2585 SUIT_Parameter_Strict_Order. SUIT_Process_Dependency must preserve 2586 and restore the state of SUIT_Parameter_Strict_Order. If 2587 SUIT_Parameter_Strict_Order is returned to True, ALL preceding 2588 commands MUST complete before the next command is executed. 2590 See Section 6.7 for behavioral description of Strict Order. 2592 8.7.5.23. suit-parameter-soft-failure 2594 When executing a command sequence inside suit-directive-try-each 2595 (Section 8.7.7.3) or suit-directive-run-sequence (Section 8.7.7.12) 2596 and a condition failure occurs, the manifest processor aborts the 2597 sequence. For suit-directive-try-each, if Soft Failure is True, the 2598 next sequence in Try Each is invoked, otherwise suit-directive-try- 2599 each fails with the condition failure code. In suit-directive-run- 2600 sequence, if Soft Failure is True the suit-directive-run-sequence 2601 simply halts with no side-effects and the Manifest Processor 2602 continues with the following command, otherwise, the suit-directive- 2603 run-sequence fails with the condition failure code. 2605 suit-parameter-soft-failure is scoped to the enclosing 2606 SUIT_Command_Sequence. Its value is discarded when 2607 SUIT_Command_Sequence terminates. It MUST NOT be set outside of 2608 suit-directive-try-each or suit-directive-run-sequence. 2610 When suit-directive-try-each is invoked, Soft Failure defaults to 2611 True. An Update Author may choose to set Soft Failure to False if 2612 they require a failed condition in a sequence to force an Abort. 2614 When suit-directive-run-sequence is invoked, Soft Failure defaults to 2615 False. An Update Author may choose to make failures soft within a 2616 suit-directive-run-sequence. 2618 8.7.5.24. suit-parameter-custom 2620 This parameter is an extension point for any proprietary, application 2621 specific conditions and directives. It MUST NOT be used in the 2622 common sequence. This effectively scopes each custom command to a 2623 particular Vendor Identifier/Class Identifier pair. 2625 8.7.6. SUIT_Condition 2627 Conditions are used to define mandatory properties of a system in 2628 order for an update to be applied. They can be pre-conditions or 2629 post-conditions of any directive or series of directives, depending 2630 on where they are placed in the list. All Conditions specify a 2631 Reporting Policy as described Section 8.7.4. Conditions include: 2633 +----------------+----------------------------------+---------------+ 2634 | Name | CDDL Structure | Reference | 2635 +----------------+----------------------------------+---------------+ 2636 | Vendor | suit-condition-vendor-identifier | Section 8.7.6 | 2637 | Identifier | | .1 | 2638 | | | | 2639 | Class | suit-condition-class-identifier | Section 8.7.6 | 2640 | Identifier | | .1 | 2641 | | | | 2642 | Device | suit-condition-device-identifier | Section 8.7.6 | 2643 | Identifier | | .1 | 2644 | | | | 2645 | Image Match | suit-condition-image-match | Section 8.7.6 | 2646 | | | .2 | 2647 | | | | 2648 | Image Not | suit-condition-image-not-match | Section 8.7.6 | 2649 | Match | | .3 | 2650 | | | | 2651 | Use Before | suit-condition-use-before | Section 8.7.6 | 2652 | | | .4 | 2653 | | | | 2654 | Component | suit-condition-component-offset | Section 8.7.6 | 2655 | Offset | | .5 | 2656 | | | | 2657 | Minimum | suit-condition-minimum-battery | Section 8.7.6 | 2658 | Battery | | .6 | 2659 | | | | 2660 | Update | suit-condition-update-authorized | Section 8.7.6 | 2661 | Authorized | | .7 | 2662 | | | | 2663 | Version | suit-condition-version | Section 8.7.6 | 2664 | | | .8 | 2665 | | | | 2666 | Abort | suit-condition-abort | Section 8.7.6 | 2667 | | | .9 | 2668 | | | | 2669 | Custom | suit-condition-custom | Section 8.7.6 | 2670 | Condition | | .10 | 2671 +----------------+----------------------------------+---------------+ 2673 The abstract description of these conditions is defined in 2674 Section 6.4. 2676 Conditions compare parameters against properties of the system. 2677 These properties may be asserted in many different ways, including: 2678 calculation on-demand, volatile definition in memory, static 2679 definition within the manifest processor, storage in known location 2680 within an image, storage within a key storage system, storage in One- 2681 Time-Programmable memory, inclusion in mask ROM, or inclusion as a 2682 register in hardware. Some of these assertion methods are global in 2683 scope, such as a hardware register, some are scoped to an individual 2684 component, such as storage at a known location in an image, and some 2685 assertion methods can be either global or component-scope, based on 2686 implementation. 2688 Each condition MUST report a result code on completion. If a 2689 condition reports failure, then the current sequence of commands MUST 2690 terminate. A subsequent command or command sequence MAY continue 2691 executing if suit-parameter-soft-failure (Section 8.7.5.23) is set. 2692 If a condition requires additional information, this MUST be 2693 specified in one or more parameters before the condition is executed. 2694 If a Recipient attempts to process a condition that expects 2695 additional information and that information has not been set, it MUST 2696 report a failure. If a Recipient encounters an unknown condition, it 2697 MUST report a failure. 2699 Condition labels in the positive number range are reserved for IANA 2700 registration while those in the negative range are custom conditions 2701 reserved for proprietary definition by the author of a manifest 2702 processor. See Section 11 for more details. 2704 8.7.6.1. suit-condition-vendor-identifier, suit-condition-class- 2705 identifier, and suit-condition-device-identifier 2707 There are three identifier-based conditions: suit-condition-vendor- 2708 identifier, suit-condition-class-identifier, and suit-condition- 2709 device-identifier. Each of these conditions match a RFC 4122 2710 [RFC4122] UUID that MUST have already been set as a parameter. The 2711 installing Recipient MUST match the specified UUID in order to 2712 consider the manifest valid. These identifiers are scoped by 2713 component in the manifest. Each component MAY match more than one 2714 identifier. Care is needed to ensure that manifests correctly 2715 identify their targets using these conditions. Using only a generic 2716 class ID for a device-specific firmware could result in matching 2717 devices that are not compatible. 2719 The Recipient uses the ID parameter that has already been set using 2720 the Set Parameters directive. If no ID has been set, this condition 2721 fails. suit-condition-class-identifier and suit-condition-vendor- 2722 identifier are REQUIRED to implement. suit-condition-device- 2723 identifier is OPTIONAL to implement. 2725 Each identifier condition compares the corresponding identifier 2726 parameter to a parameter asserted to the Manifest Processor by the 2727 Recipient. Identifiers MUST be known to the Manifest Processor in 2728 order to evaluate compatibility. 2730 8.7.6.2. suit-condition-image-match 2732 Verify that the current component matches the suit-parameter-image- 2733 digest (Section 8.7.5.6) for the current component. The digest is 2734 verified against the digest specified in the Component's parameters 2735 list. If no digest is specified, the condition fails. suit- 2736 condition-image-match is REQUIRED to implement. 2738 8.7.6.3. suit-condition-image-not-match 2740 Verify that the current component does not match the suit-parameter- 2741 image-digest (Section 8.7.5.6). If no digest is specified, the 2742 condition fails. suit-condition-image-not-match is OPTIONAL to 2743 implement. 2745 8.7.6.4. suit-condition-use-before 2747 Verify that the current time is BEFORE the specified time. suit- 2748 condition-use-before is used to specify the last time at which an 2749 update should be installed. The recipient evaluates the current time 2750 against the suit-parameter-use-before parameter (Section 8.7.5.8), 2751 which must have already been set as a parameter, encoded as seconds 2752 after 1970-01-01 00:00:00 UTC. Timestamp conditions MUST be 2753 evaluated in 64 bits, regardless of encoded CBOR size. suit- 2754 condition-use-before is OPTIONAL to implement. 2756 8.7.6.5. suit-condition-component-offset 2758 Verify that the offset of the current component matches the offset 2759 set in suit-parameter-component-offset (Section 8.7.5.9). This 2760 condition allows a manifest to select between several images to match 2761 a target offset. 2763 8.7.6.6. suit-condition-minimum-battery 2765 suit-condition-minimum-battery provides a mechanism to test a 2766 Recipient's battery level before installing an update. This 2767 condition is primarily for use in primary-cell applications, where 2768 the battery is only ever discharged. For batteries that are charged, 2769 suit-directive-wait is more appropriate, since it defines a "wait" 2770 until the battery level is sufficient to install the update. suit- 2771 condition-minimum-battery is specified in mWh. suit-condition- 2772 minimum-battery is OPTIONAL to implement. suit-condition-minimum- 2773 battery consumes suit-parameter-minimum-battery (Section 8.7.5.16). 2775 8.7.6.7. suit-condition-update-authorized 2777 Request Authorization from the application and fail if not 2778 authorized. This can allow a user to decline an update. suit- 2779 parameter-update-priority (Section 8.7.5.17) provides an integer 2780 priority level that the application can use to determine whether or 2781 not to authorize the update. Priorities are application defined. 2782 suit-condition-update-authorized is OPTIONAL to implement. 2784 8.7.6.8. suit-condition-version 2786 suit-condition-version allows comparing versions of firmware. 2787 Verifying image digests is preferred to version checks because 2788 digests are more precise. suit-condition-version examines a 2789 component's version against the version info specified in suit- 2790 parameter-version (Section 8.7.5.18) 2792 8.7.6.9. suit-condition-abort 2794 Unconditionally fail. This operation is typically used in 2795 conjunction with suit-directive-try-each (Section 8.7.7.3). 2797 8.7.6.10. suit-condition-custom 2799 suit-condition-custom describes any proprietary, application specific 2800 condition. This is encoded as a negative integer, chosen by the 2801 firmware developer. If additional information must be provided to 2802 the condition, it should be encoded in a custom parameter (a nint) as 2803 described in Section 8.7.5. SUIT_Condition_Custom is OPTIONAL to 2804 implement. 2806 8.7.7. SUIT_Directive 2808 Directives are used to define the behavior of the recipient. 2809 Directives include: 2811 +---------------+-------------------------------------+-------------+ 2812 | Name | CDDL Structure | Reference | 2813 +---------------+-------------------------------------+-------------+ 2814 | Set Component | suit-directive-set-component-index | Section 8.7 | 2815 | Index | | .7.1 | 2816 | | | | 2817 | Set | suit-directive-set-dependency-index | Section 8.7 | 2818 | Dependency | | .7.2 | 2819 | Index | | | 2820 | | | | 2821 | Try Each | suit-directive-try-each | Section 8.7 | 2822 | | | .7.3 | 2823 | | | | 2824 | Process | suit-directive-process-dependency | Section 8.7 | 2825 | Dependency | | .7.4 | 2826 | | | | 2827 | Set | suit-directive-set-parameters | Section 8.7 | 2828 | Parameters | | .7.5 | 2829 | | | | 2830 | Override | suit-directive-override-parameters | Section 8.7 | 2831 | Parameters | | .7.6 | 2832 | | | | 2833 | Fetch | suit-directive-fetch | Section 8.7 | 2834 | | | .7.7 | 2835 | | | | 2836 | Fetch URI | suit-directive-fetch-uri-list | Section 8.7 | 2837 | list | | .7.8 | 2838 | | | | 2839 | Copy | suit-directive-copy | Section 8.7 | 2840 | | | .7.9 | 2841 | | | | 2842 | Run | suit-directive-run | Section 8.7 | 2843 | | | .7.10 | 2844 | | | | 2845 | Wait For | suit-directive-wait | Section 8.7 | 2846 | Event | | .7.11 | 2847 | | | | 2848 | Run Sequence | suit-directive-run-sequence | Section 8.7 | 2849 | | | .7.12 | 2850 | | | | 2851 | Swap | suit-directive-swap | Section 8.7 | 2852 | | | .7.13 | 2853 | | | | 2854 | Garbage | suit-directive-garbage-collect | Section 8.7 | 2855 | Collect | | .8 | 2856 +---------------+-------------------------------------+-------------+ 2858 The abstract description of these commands is defined in Section 6.4. 2860 When a Recipient executes a Directive, it MUST report a result code. 2861 If the Directive reports failure, then the current Command Sequence 2862 MUST be terminated. 2864 8.7.7.1. suit-directive-set-component-index 2866 Set Component Index defines the component to which successive 2867 directives and conditions will apply. The supplied argument MUST be 2868 one of three types: 2870 1. An unsigned integer (REQUIRED to implement in parser) 2872 2. A boolean (REQUIRED to implement in parser ONLY IF 2 or more 2873 components supported) 2875 3. An array of unsigned integers (REQUIRED to implement in parser 2876 ONLY IF 3 or more components supported) 2878 If the following commands apply to ONE component, an unsigned integer 2879 index into the component list is used. If the following commands 2880 apply to ALL components, then the boolean value "True" is used 2881 instead of an index. If the following commands apply to more than 2882 one, but not all components, then an array of unsigned integer 2883 indices into the component list is used. See Section 6.5 for more 2884 details. 2886 If the following commands apply to NO components, then the boolean 2887 value "False" is used. When suit-directive-set-dependency-index is 2888 used, suit-directive-set-component-index = False is implied. When 2889 suit-directive-set-component-index is used, suit-directive-set- 2890 dependency-index = False is implied. 2892 If component index is set to True when a command is invoked, then the 2893 command applies to all components, in the order they appear in suit- 2894 common-components. When the Manifest Processor invokes a command 2895 while the component index is set to True, it must execute the command 2896 once for each possible component index, ensuring that the command 2897 receives the parameters corresponding to that component index. 2899 8.7.7.2. suit-directive-set-dependency-index 2901 Set Dependency Index defines the manifest to which successive 2902 directives and conditions will apply. The supplied argument MUST be 2903 either a boolean or an unsigned integer index into the dependencies, 2904 or an array of unsigned integer indices into the list of 2905 dependencies. If the following directives apply to ALL dependencies, 2906 then the boolean value "True" is used instead of an index. If the 2907 following directives apply to NO dependencies, then the boolean value 2908 "False" is used. When suit-directive-set-component-index is used, 2909 suit-directive-set-dependency-index = False is implied. When suit- 2910 directive-set-dependency-index is used, suit-directive-set-component- 2911 index = False is implied. 2913 If dependency index is set to True when a command is invoked, then 2914 the command applies to all dependencies, in the order they appear in 2915 suit-common-components. When the Manifest Processor invokes a 2916 command while the dependency index is set to True, the Manifest 2917 Processor MUST execute the command once for each possible dependency 2918 index, ensuring that the command receives the parameters 2919 corresponding to that dependency index. If the dependency index is 2920 set to an array of unsigned integers, then the Manifest Processor 2921 MUST execute the command once for each listed dependency index, 2922 ensuring that the command receives the parameters corresponding to 2923 that dependency index. 2925 See Section 6.5 for more details. 2927 Typical operations that require suit-directive-set-dependency-index 2928 include setting a source URI or Encryption Information, invoking 2929 "Fetch," or invoking "Process Dependency" for an individual 2930 dependency. 2932 8.7.7.3. suit-directive-try-each 2934 This command runs several SUIT_Command_Sequence instances, one after 2935 another, in a strict order. Use this command to implement a "try/ 2936 catch-try/catch" sequence. Manifest processors MAY implement this 2937 command. 2939 suit-parameter-soft-failure (Section 8.7.5.23) is initialized to True 2940 at the beginning of each sequence. If one sequence aborts due to a 2941 condition failure, the next is started. If no sequence completes 2942 without condition failure, then suit-directive-try-each returns an 2943 error. If a particular application calls for all sequences to fail 2944 and still continue, then an empty sequence (nil) can be added to the 2945 Try Each Argument. 2947 The argument to suit-directive-try-each is a list of 2948 SUIT_Command_Sequence. suit-directive-try-each does not specify a 2949 reporting policy. 2951 8.7.7.4. suit-directive-process-dependency 2953 Execute the commands in the common section of the current dependency, 2954 followed by the commands in the equivalent section of the current 2955 dependency. For example, if the current section is "fetch payload," 2956 this will execute "common" in the current dependency, then "fetch 2957 payload" in the current dependency. Once this is complete, the 2958 command following suit-directive-process-dependency will be 2959 processed. 2961 If the current dependency is False, this directive has no effect. If 2962 the current dependency is True, then this directive applies to all 2963 dependencies. If the current section is "common," then the command 2964 sequence MUST be terminated with an error. 2966 When SUIT_Process_Dependency completes, it forwards the last status 2967 code that occurred in the dependency. 2969 8.7.7.5. suit-directive-set-parameters 2971 suit-directive-set-parameters allows the manifest to configure 2972 behavior of future directives by changing parameters that are read by 2973 those directives. When dependencies are used, suit-directive-set- 2974 parameters also allows a manifest to modify the behavior of its 2975 dependencies. 2977 Available parameters are defined in Section 8.7.5. 2979 If a parameter is already set, suit-directive-set-parameters will 2980 skip setting the parameter to its argument. This provides the core 2981 of the override mechanism, allowing dependent manifests to change the 2982 behavior of a manifest. 2984 suit-directive-set-parameters does not specify a reporting policy. 2986 8.7.7.6. suit-directive-override-parameters 2988 suit-directive-override-parameters replaces any listed parameters 2989 that are already set with the values that are provided in its 2990 argument. This allows a manifest to prevent replacement of critical 2991 parameters. 2993 Available parameters are defined in Section 8.7.5. 2995 suit-directive-override-parameters does not specify a reporting 2996 policy. 2998 8.7.7.7. suit-directive-fetch 3000 suit-directive-fetch instructs the manifest processor to obtain one 3001 or more manifests or payloads, as specified by the manifest index and 3002 component index, respectively. 3004 suit-directive-fetch can target one or more manifests and one or more 3005 payloads. suit-directive-fetch retrieves each component and each 3006 manifest listed in component-index and dependency-index, 3007 respectively. If component-index or dependency-index is True, 3008 instead of an integer, then all current manifest components/manifests 3009 are fetched. The current manifest's dependent-components are not 3010 automatically fetched. In order to pre-fetch these, they MUST be 3011 specified in a component-index integer. 3013 suit-directive-fetch typically takes no arguments unless one is 3014 needed to modify fetch behavior. If an argument is needed, it must 3015 be wrapped in a bstr and set in suit-parameter-fetch-arguments. 3017 suit-directive-fetch reads the URI parameter to find the source of 3018 the fetch it performs. 3020 The behavior of suit-directive-fetch can be modified by setting one 3021 or more of SUIT_Parameter_Encryption_Info, 3022 SUIT_Parameter_Compression_Info, SUIT_Parameter_Unpack_Info. These 3023 three parameters each activate and configure a processing step that 3024 can be applied to the data that is transferred during suit-directive- 3025 fetch. 3027 8.7.7.8. suit-directive-fetch-uri-list 3029 suit-directive-fetch-uri-list uses the same semantics as suit- 3030 directive-fetch (Section 8.7.7.7), except that it iterates over the 3031 URI List (Section 8.7.5.20) to select a URI to fetch from. 3033 8.7.7.9. suit-directive-copy 3035 suit-directive-copy instructs the manifest processor to obtain one or 3036 more payloads, as specified by the component index. As described in 3037 Section 6.5 component index may be a single integer, a list of 3038 integers, or True. suit-directive-copy retrieves each component 3039 specified by the current component-index, respectively. The current 3040 manifest's dependent-components are not automatically copied. In 3041 order to copy these, they MUST be specified in a component-index 3042 integer. 3044 The behavior of suit-directive-copy can be modified by setting one or 3045 more of SUIT_Parameter_Encryption_Info, 3046 SUIT_Parameter_Compression_Info, SUIT_Parameter_Unpack_Info. These 3047 three parameters each activate and configure a processing step that 3048 can be applied to the data that is transferred during suit-directive- 3049 copy. 3051 suit-directive-copy reads its source from suit-parameter-source- 3052 component (Section 8.7.5.14). 3054 If either the source component parameter or the source component 3055 itself is absent, this command fails. 3057 8.7.7.10. suit-directive-run 3059 suit-directive-run directs the manifest processor to transfer 3060 execution to the current Component Index. When this is invoked, the 3061 manifest processor MAY be unloaded and execution continues in the 3062 Component Index. Arguments are provided to suit-directive-run 3063 through suit-parameter-run-arguments (Section 8.7.5.15) and are 3064 forwarded to the executable code located in Component Index in an 3065 application-specific way. For example, this could form the Linux 3066 Kernel Command Line if booting a Linux device. 3068 If the executable code at Component Index is constructed in such a 3069 way that it does not unload the manifest processor, then the manifest 3070 processor may resume execution after the executable completes. This 3071 allows the manifest processor to invoke suitable helpers and to 3072 verify them with image conditions. 3074 8.7.7.11. suit-directive-wait 3076 suit-directive-wait directs the manifest processor to pause until a 3077 specified event occurs. Some possible events include: 3079 1. Authorization 3081 2. External Power 3083 3. Network availability 3085 4. Other Device Firmware Version 3087 5. Time 3089 6. Time of Day 3091 7. Day of Week 3093 8.7.7.12. suit-directive-run-sequence 3095 To enable conditional commands, and to allow several strictly ordered 3096 sequences to be executed out-of-order, suit-directive-run-sequence 3097 allows the manifest processor to execute its argument as a 3098 SUIT_Command_Sequence. The argument must be wrapped in a bstr. 3100 When a sequence is executed, any failure of a condition causes 3101 immediate termination of the sequence. 3103 When suit-directive-run-sequence completes, it forwards the last 3104 status code that occurred in the sequence. If the Soft Failure 3105 parameter is true, then suit-directive-run-sequence only fails when a 3106 directive in the argument sequence fails. 3108 suit-parameter-soft-failure (Section 8.7.5.23) defaults to False when 3109 suit-directive-run-sequence begins. Its value is discarded when 3110 suit-directive-run-sequence terminates. 3112 8.7.7.13. suit-directive-swap 3114 suit-directive-swap instructs the manifest processor to move the 3115 source to the destination and the destination to the source 3116 simultaneously. Swap has nearly identical semantics to suit- 3117 directive-copy except that suit-directive-swap replaces the source 3118 with the current contents of the destination in an application- 3119 defined way. As with suit-directive-copy, if the source component is 3120 missing, this command fails. 3122 If SUIT_Parameter_Compression_Info or SUIT_Parameter_Encryption_Info 3123 are present, they MUST be handled in a symmetric way, so that the 3124 source is decompressed into the destination and the destination is 3125 compressed into the source. The source is decrypted into the 3126 destination and the destination is encrypted into the source. suit- 3127 directive-swap is OPTIONAL to implement. 3129 8.7.8. suit-directive-garbage-collect 3131 suit-directive-garbage-collect marks the current component as unused 3132 in the current manifest. This can be used to remove temporary 3133 storage or remove components that are no longer needed. Example use 3134 cases: 3136 - Temporary storage for encrypted download 3138 - Temporary storage for verifying decompressed file before writing 3139 to flash 3141 - Removing Trusted Service no longer needed by Trusted Application 3143 Once the current Command Sequence is complete, the manifest 3144 processors checks each marked component to see whether any other 3145 manifests have referenced it. Those marked components with no other 3146 references are deleted. The manifest processor MAY choose to ignore 3147 a Garbage Collect directive depending on device policy. 3149 suit-directive-garbage-collect is OPTIONAL to implement in manifest 3150 processors. 3152 8.7.9. Integrity Check Values 3154 When the CoSWID, Text section, or any Command Sequence of the Update 3155 Procedure is made severable, it is moved to the Envelope and replaced 3156 with a SUIT_Digest. The SUIT_Digest is computed over the entire bstr 3157 enclosing the Manifest element that has been moved to the Envelope. 3158 Each element that is made severable from the Manifest is placed in 3159 the Envelope. The keys for the envelope elements have the same 3160 values as the keys for the manifest elements. 3162 Each Integrity Check Value covers the corresponding Envelope Element 3163 as described in Section 8.8. 3165 8.8. Severable Elements 3167 Because the manifest can be used by different actors at different 3168 times, some parts of the manifest can be removed or "Severed" without 3169 affecting later stages of the lifecycle. Severing of information is 3170 achieved by separating that information from the signed container so 3171 that removing it does not affect the signature. This means that 3172 ensuring integrity of severable parts of the manifest is a 3173 requirement for the signed portion of the manifest. Severing some 3174 parts makes it possible to discard parts of the manifest that are no 3175 longer necessary. This is important because it allows the storage 3176 used by the manifest to be greatly reduced. For example, no text 3177 size limits are needed if text is removed from the manifest prior to 3178 delivery to a constrained device. 3180 Elements are made severable by removing them from the manifest, 3181 encoding them in a bstr, and placing a SUIT_Digest of the bstr in the 3182 manifest so that they can still be authenticated. The SUIT_Digest 3183 typically consumes 4 bytes more than the size of the raw digest, 3184 therefore elements smaller than (Digest Bits)/8 + 4 SHOULD NOT be 3185 severable. Elements larger than (Digest Bits)/8 + 4 MAY be 3186 severable, while elements that are much larger than (Digest Bits)/8 + 3187 4 SHOULD be severable. 3189 Because of this, all command sequences in the manifest are encoded in 3190 a bstr so that there is a single code path needed for all command 3191 sequences. 3193 9. Access Control Lists 3195 To manage permissions in the manifest, there are three models that 3196 can be used. 3198 First, the simplest model requires that all manifests are 3199 authenticated by a single trusted key. This mode has the advantage 3200 that only a root manifest needs to be authenticated, since all of its 3201 dependencies have digests included in the root manifest. 3203 This simplest model can be extended by adding key delegation without 3204 much increase in complexity. 3206 A second model requires an ACL to be presented to the Recipient, 3207 authenticated by a trusted party or stored on the Recipient. This 3208 ACL grants access rights for specific component IDs or Component 3209 Identifier prefixes to the listed identities or identity groups. Any 3210 identity can verify an image digest, but fetching into or fetching 3211 from a Component Identifier requires approval from the ACL. 3213 A third model allows a Recipient to provide even more fine-grained 3214 controls: The ACL lists the Component Identifier or Component 3215 Identifier prefix that an identity can use, and also lists the 3216 commands and parameters that the identity can use in combination with 3217 that Component Identifier. 3219 10. SUIT Digest Container 3221 RFC 8152 [RFC8152] provides containers for signature, MAC, and 3222 encryption, but no basic digest container. The container needed for 3223 a digest requires a type identifier and a container for the raw 3224 digest data. Some forms of digest may require additional parameters. 3225 These can be added following the digest. 3227 The SUIT digest is a CBOR List containing two elements: a suit- 3228 digest-algorithm-id and a bstr containing the bytes of the digest. 3230 11. IANA Considerations 3232 IANA is requested to: 3234 - allocate CBOR tag 107 in the CBOR Tags registry for the SUIT 3235 Envelope. 3237 - allocate CBOR tag 1070 in the CBOR Tags registry for the SUIT 3238 Manifest. 3240 - allocate media type application/suit-envelope in the Media Types 3241 registry. 3243 - setup several registries as described below. 3245 IANA is requested to setup a registry for SUIT manifests. Several 3246 registries defined in the subsections below need to be created. 3248 For each registry, values 0-23 are Standards Action, 24-255 are IETF 3249 Review, 256-65535 are Expert Review, and 65536 or greater are First 3250 Come First Served. 3252 Negative values -23 to 0 are Experimental Use, -24 and lower are 3253 Private Use. 3255 11.1. SUIT Commands 3257 +-------+------------+-----------------------------------+----------+ 3258 | Label | Name | Reference | | 3259 +-------+------------+-----------------------------------+----------+ 3260 | 1 | Vendor | Section 8.7.6.1 | | 3261 | | Identifier | | | 3262 | | | | | 3263 | 2 | Class | Section 8.7.6.1 | | 3264 | | Identifier | | | 3265 | | | | | 3266 | 3 | Image | Section 8.7.6.2 | | 3267 | | Match | | | 3268 | | | | | 3269 | 4 | Use Before | Section 8.7.6.4 | | 3270 | | | | | 3271 | 5 | Component | Section 8.7.6.5 | | 3272 | | Offset | | | 3273 | | | | | 3274 | 12 | Set | Section 8.7.7.1 | | 3275 | | Component | | | 3276 | | Index | | | 3277 | | | | | 3278 | 13 | Set | Section 8.7.7.2 | | 3279 | | Dependency | | | 3280 | | Index | | | 3281 | | | | | 3282 | 14 | Abort | | | 3283 | | | | | 3284 | 15 | Try Each | Section 8.7.7.3 | | 3285 | | | | | 3286 | 16 | Reserved | | | 3287 | | | | | 3288 | 17 | Reserved | | | 3289 | | | | | 3290 | 18 | Process | suit-directive-process-dependency | Section | 3291 | | Dependency | | 8.7.7.4 | 3292 | | | | | 3293 | 19 | Set | Section 8.7.7.5 | | 3294 | | Parameters | | | 3295 | | | | | 3296 | 20 | Override | Section 8.7.7.6 | | 3297 | | Parameters | | | 3298 | | | | | 3299 | 21 | Fetch | Section 8.7.7.7 | | 3300 | | | | | 3301 | 22 | Copy | Section 8.7.7.9 | | 3302 | | | | | 3303 | 23 | Run | Section 8.7.7.10 | | 3304 | | | | | 3305 | 24 | Device | Section 8.7.6.1 | | 3306 | | Identifier | | | 3307 | | | | | 3308 | 25 | Image Not | Section 8.7.6.3 | | 3309 | | Match | | | 3310 | | | | | 3311 | 26 | Minimum | Section 8.7.6.6 | | 3312 | | Battery | | | 3313 | | | | | 3314 | 27 | Update | Section 8.7.6.7 | | 3315 | | Authorized | | | 3316 | | | | | 3317 | 28 | Version | Section 8.7.6.8 | | 3318 | | | | | 3319 | 29 | Wait For | Section 8.7.7.11 | | 3320 | | Event | | | 3321 | | | | | 3322 | 30 | Fetch URI | Section 8.7.7.8 | | 3323 | | List | | | 3324 | | | | | 3325 | 31 | Swap | Section 8.7.7.13 | | 3326 | | | | | 3327 | 32 | Run | Section 8.7.7.12 | | 3328 | | Sequence | | | 3329 | | | | | 3330 | 33 | Garbage | Section 8.7.8 | | 3331 | | Collect | | | 3332 | | | | | 3333 | nint | Custom | Section 8.7.6.10 | | 3334 | | Condition | | | 3335 +-------+------------+-----------------------------------+----------+ 3337 11.2. SUIT Parameters 3339 +-------+------------------+---------------------------+ 3340 | Label | Name | Reference | 3341 +-------+------------------+---------------------------+ 3342 | 1 | Vendor ID | Section 8.7.5.3 | 3343 | | | | 3344 | 2 | Class ID | Section 8.7.5.4 | 3345 | | | | 3346 | 3 | Image Digest | Section 8.7.5.6 | 3347 | | | | 3348 | 4 | Use Before | Section 8.7.5.8 | 3349 | | | | 3350 | 5 | Component Offset | Section 8.7.5.9 | 3351 | | | | 3352 | 12 | Strict Order | Section 8.7.5.22 | 3353 | | | | 3354 | 13 | Soft Failure | Section 8.7.5.23 | 3355 | | | | 3356 | 14 | Image Size | Section 8.7.5.7 | 3357 | | | | 3358 | 18 | Encryption Info | Section 8.7.5.10 | 3359 | | | | 3360 | 19 | Compression Info | Section 8.7.5.11 | 3361 | | | | 3362 | 20 | Unpack Info | Section 8.7.5.12 | 3363 | | | | 3364 | 21 | URI | Section 8.7.5.13 | 3365 | | | | 3366 | 22 | Source Component | Section 8.7.5.14 | 3367 | | | | 3368 | 23 | Run Args | Section 8.7.5.15 | 3369 | | | | 3370 | 24 | Device ID | Section 8.7.5.5 | 3371 | | | | 3372 | 26 | Minimum Battery | Section 8.7.5.16 | 3373 | | | | 3374 | 27 | Update Priority | Section 8.7.5.17 | 3375 | | | | 3376 | 28 | Version | {{suit-parameter-version} | 3377 | | | | 3378 | 29 | Wait Info | Section 8.7.5.19 | 3379 | | | | 3380 | 30 | URI List | Section 8.7.5.20 | 3381 | | | | 3382 | nint | Custom | Section 8.7.5.24 | 3383 +-------+------------------+---------------------------+ 3385 11.3. SUIT Text Values 3387 +-------+----------------------+---------------+ 3388 | Label | Name | Reference | 3389 +-------+----------------------+---------------+ 3390 | 1 | Manifest Description | Section 8.6.4 | 3391 | | | | 3392 | 2 | Update Description | Section 8.6.4 | 3393 | | | | 3394 | 3 | Manifest JSON Source | Section 8.6.4 | 3395 | | | | 3396 | 4 | Manifest YAML Source | Section 8.6.4 | 3397 | | | | 3398 | nint | Custom | Section 8.6.4 | 3399 +-------+----------------------+---------------+ 3401 11.4. SUIT Component Text Values 3403 +-------+----------------------------+---------------+ 3404 | Label | Name | Reference | 3405 +-------+----------------------------+---------------+ 3406 | 1 | Vendor Name | Section 8.6.4 | 3407 | | | | 3408 | 2 | Model Name | Section 8.6.4 | 3409 | | | | 3410 | 3 | Vendor Domain | Section 8.6.4 | 3411 | | | | 3412 | 4 | Model Info | Section 8.6.4 | 3413 | | | | 3414 | 5 | Component Description | Section 8.6.4 | 3415 | | | | 3416 | 6 | Component Version | Section 8.6.4 | 3417 | | | | 3418 | 7 | Component Version Required | Section 8.6.4 | 3419 | | | | 3420 | nint | Custom | Section 8.6.4 | 3421 +-------+----------------------------+---------------+ 3423 11.5. SUIT Algorithm Identifiers 3425 11.5.1. SUIT Digest Algorithm Identifiers 3426 +-------+----------+------------+ 3427 | Label | Name | | 3428 +-------+----------+------------+ 3429 | 1 | SHA224 | Section 10 | 3430 | | | | 3431 | 2 | SHA256 | Section 10 | 3432 | | | | 3433 | 3 | SHA384 | Section 10 | 3434 | | | | 3435 | 4 | SHA512 | Section 10 | 3436 | | | | 3437 | 5 | SHA3-224 | Section 10 | 3438 | | | | 3439 | 6 | SHA3-256 | Section 10 | 3440 | | | | 3441 | 7 | SHA3-384 | Section 10 | 3442 | | | | 3443 | 8 | SHA3-512 | Section 10 | 3444 +-------+----------+------------+ 3446 11.5.2. SUIT Compression Algorithm Identifiers 3448 +-------+--------+------------------+ 3449 | Label | Name | Reference | 3450 +-------+--------+------------------+ 3451 | 1 | zlib | Section 8.7.5.11 | 3452 | | | | 3453 | 2 | Brotli | Section 8.7.5.11 | 3454 | | | | 3455 | 3 | zstd | Section 8.7.5.11 | 3456 +-------+--------+------------------+ 3458 11.5.3. Unpack Algorithms 3460 +-------+------+------------------+ 3461 | Label | Name | Reference | 3462 +-------+------+------------------+ 3463 | 1 | HEX | Section 8.7.5.12 | 3464 | | | | 3465 | 2 | ELF | Section 8.7.5.12 | 3466 | | | | 3467 | 3 | COFF | Section 8.7.5.12 | 3468 | | | | 3469 | 4 | SREC | Section 8.7.5.12 | 3470 +-------+------+------------------+ 3472 12. Security Considerations 3474 This document is about a manifest format protecting and describing 3475 how to retrieve, install, and invoke firmware images and as such it 3476 is part of a larger solution for delivering firmware updates to IoT 3477 devices. A detailed security treatment can be found in the 3478 architecture [I-D.ietf-suit-architecture] and in the information 3479 model [I-D.ietf-suit-information-model] documents. 3481 13. Acknowledgements 3483 We would like to thank the following persons for their support in 3484 designing this mechanism: 3486 - Milosch Meriac 3488 - Geraint Luff 3490 - Dan Ros 3492 - John-Paul Stanford 3494 - Hugo Vincent 3496 - Carsten Bormann 3498 - Oeyvind Roenningstad 3500 - Frank Audun Kvamtroe 3502 - Krzysztof Chruściński 3504 - Andrzej Puzdrowski 3506 - Michael Richardson 3508 - David Brown 3510 - Emmanuel Baccelli 3512 14. References 3514 14.1. Normative References 3516 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3517 Requirement Levels", BCP 14, RFC 2119, 3518 DOI 10.17487/RFC2119, March 1997, 3519 . 3521 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3522 Resource Identifier (URI): Generic Syntax", STD 66, 3523 RFC 3986, DOI 10.17487/RFC3986, January 2005, 3524 . 3526 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 3527 Unique IDentifier (UUID) URN Namespace", RFC 4122, 3528 DOI 10.17487/RFC4122, July 2005, 3529 . 3531 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 3532 RFC 8152, DOI 10.17487/RFC8152, July 2017, 3533 . 3535 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3536 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3537 May 2017, . 3539 14.2. Informative References 3541 [COFF] Wikipedia, ., "Common Object File Format (COFF)", 2020, 3542 . 3544 [ELF] Wikipedia, ., "Executable and Linkable Format (ELF)", 3545 2020, . 3548 [HEX] Wikipedia, ., "Intel HEX", 2020, 3549 . 3551 [I-D.ietf-cbor-tags-oid] 3552 Bormann, C. and S. Leonard, "Concise Binary Object 3553 Representation (CBOR) Tags for Object Identifiers", draft- 3554 ietf-cbor-tags-oid-04 (work in progress), January 2021. 3556 [I-D.ietf-sacm-coswid] 3557 Birkholz, H., Fitzgerald-McKay, J., Schmidt, C., and D. 3558 Waltermire, "Concise Software Identification Tags", draft- 3559 ietf-sacm-coswid-16 (work in progress), November 2020. 3561 [I-D.ietf-suit-architecture] 3562 Moran, B., Tschofenig, H., Brown, D., and M. Meriac, "A 3563 Firmware Update Architecture for Internet of Things", 3564 draft-ietf-suit-architecture-15 (work in progress), 3565 January 2021. 3567 [I-D.ietf-suit-information-model] 3568 Moran, B., Tschofenig, H., and H. Birkholz, "An 3569 Information Model for Firmware Updates in IoT Devices", 3570 draft-ietf-suit-information-model-08 (work in progress), 3571 October 2020. 3573 [I-D.ietf-teep-architecture] 3574 Pei, M., Tschofenig, H., Thaler, D., and D. Wheeler, 3575 "Trusted Execution Environment Provisioning (TEEP) 3576 Architecture", draft-ietf-teep-architecture-13 (work in 3577 progress), November 2020. 3579 [I-D.kucherawy-rfc8478bis] 3580 Collet, Y. and M. Kucherawy, "Zstandard Compression and 3581 the application/zstd Media Type", draft-kucherawy- 3582 rfc8478bis-06 (work in progress), December 2020. 3584 [RFC1950] Deutsch, P. and J-L. Gailly, "ZLIB Compressed Data Format 3585 Specification version 3.3", RFC 1950, 3586 DOI 10.17487/RFC1950, May 1996, 3587 . 3589 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 3590 Constrained-Node Networks", RFC 7228, 3591 DOI 10.17487/RFC7228, May 2014, 3592 . 3594 [RFC7932] Alakuijala, J. and Z. Szabadka, "Brotli Compressed Data 3595 Format", RFC 7932, DOI 10.17487/RFC7932, July 2016, 3596 . 3598 [RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, 3599 "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, 3600 May 2018, . 3602 [RFC8747] Jones, M., Seitz, L., Selander, G., Erdtman, S., and H. 3603 Tschofenig, "Proof-of-Possession Key Semantics for CBOR 3604 Web Tokens (CWTs)", RFC 8747, DOI 10.17487/RFC8747, March 3605 2020, . 3607 [SREC] Wikipedia, ., "SREC (file format)", 2020, 3608 . 3610 [YAML] "YAML Ain't Markup Language", 2020, . 3612 Appendix A. A. Full CDDL 3614 In order to create a valid SUIT Manifest document the structure of 3615 the corresponding CBOR message MUST adhere to the following CDDL data 3616 definition. 3618 SUIT_Envelope_Tagged = #6.48(SUIT_Envelope) 3619 SUIT_Envelope = { 3620 ? suit-delegation => bstr .cbor SUIT_Delegation, 3621 suit-authentication-wrapper => bstr .cbor SUIT_Authentication, 3622 suit-manifest => bstr .cbor SUIT_Manifest, 3623 SUIT_Severable_Manifest_Members, 3624 * SUIT_Integrated_Payload, 3625 * SUIT_Integrated_Dependency, 3626 * $$SUIT_Envelope_Extensions, 3627 * (int => bstr) 3628 } 3630 SUIT_Delegation = [ + [ + bstr .cbor CWT ] ] 3632 CWT = SUIT_Authentication_Block 3634 SUIT_Authentication = [ 3635 bstr .cbor SUIT_Digest, 3636 * bstr .cbor SUIT_Authentication_Block 3637 ] 3639 SUIT_Digest = [ 3640 suit-digest-algorithm-id : suit-digest-algorithm-ids, 3641 suit-digest-bytes : bstr, 3642 * $$SUIT_Digest-extensions 3643 ] 3645 ; Named Information Hash Algorithm Identifiers 3646 suit-digest-algorithm-ids /= algorithm-id-sha224 3647 suit-digest-algorithm-ids /= algorithm-id-sha256 3648 suit-digest-algorithm-ids /= algorithm-id-sha384 3649 suit-digest-algorithm-ids /= algorithm-id-sha512 3650 suit-digest-algorithm-ids /= algorithm-id-sha3-224 3651 suit-digest-algorithm-ids /= algorithm-id-sha3-256 3652 suit-digest-algorithm-ids /= algorithm-id-sha3-384 3653 suit-digest-algorithm-ids /= algorithm-id-sha3-512 3655 SUIT_Authentication_Block /= COSE_Mac_Tagged 3656 SUIT_Authentication_Block /= COSE_Sign_Tagged 3657 SUIT_Authentication_Block /= COSE_Mac0_Tagged 3658 SUIT_Authentication_Block /= COSE_Sign1_Tagged 3659 COSE_Mac_Tagged = any 3660 COSE_Sign_Tagged = any 3661 COSE_Mac0_Tagged = any 3662 COSE_Sign1_Tagged = any 3663 COSE_Encrypt_Tagged = any 3664 COSE_Encrypt0_Tagged = any 3666 SUIT_Severable_Manifest_Members = ( 3667 ? suit-dependency-resolution => bstr .cbor SUIT_Command_Sequence, 3668 ? suit-payload-fetch => bstr .cbor SUIT_Command_Sequence, 3669 ? suit-install => bstr .cbor SUIT_Command_Sequence, 3670 ? suit-text => bstr .cbor SUIT_Text_Map, 3671 ? suit-coswid => bstr .cbor concise-software-identity, 3672 * $$SUIT_severable-members-extensions, 3673 ) 3675 SUIT_Integrated_Payload = (suit-integrated-payload-key => bstr) 3676 SUIT_Integrated_Dependency = ( 3677 suit-integrated-payload-key => bstr .cbor SUIT_Envelope 3678 ) 3679 suit-integrated-payload-key = nint / uint .ge 24 3681 SUIT_Manifest_Tagged = #6.480(SUIT_Manifest) 3683 SUIT_Manifest = { 3684 suit-manifest-version => 1, 3685 suit-manifest-sequence-number => uint, 3686 suit-common => bstr .cbor SUIT_Common, 3687 ? suit-reference-uri => tstr, 3688 SUIT_Severable_Manifest_Members, 3689 SUIT_Severable_Members_Digests, 3690 SUIT_Unseverable_Members, 3691 * $$SUIT_Manifest_Extensions, 3692 } 3694 SUIT_Unseverable_Members = ( 3695 ? suit-validate => bstr .cbor SUIT_Command_Sequence, 3696 ? suit-load => bstr .cbor SUIT_Command_Sequence, 3697 ? suit-run => bstr .cbor SUIT_Command_Sequence, 3698 * $$unserverble-manifest-member-extensions, 3699 ) 3701 SUIT_Severable_Members_Digests = ( 3702 ? suit-dependency-resolution => SUIT_Digest, 3703 ? suit-payload-fetch => SUIT_Digest, 3704 ? suit-install => SUIT_Digest, 3705 ? suit-text => SUIT_Digest, 3706 ? suit-coswid => SUIT_Digest, 3707 * $$severable-manifest-members-digests-extensions 3708 ) 3710 SUIT_Common = { 3711 ? suit-dependencies => SUIT_Dependencies, 3712 ? suit-components => SUIT_Components, 3713 ? suit-common-sequence => bstr .cbor SUIT_Common_Sequence, 3714 * $$SUIT_Common-extensions, 3715 } 3717 SUIT_Dependencies = [ + SUIT_Dependency ] 3718 SUIT_Components = [ + SUIT_Component_Identifier ] 3720 concise-software-identity = any 3722 SUIT_Dependency = { 3723 suit-dependency-digest => SUIT_Digest, 3724 ? suit-dependency-prefix => SUIT_Component_Identifier, 3725 * $$SUIT_Dependency-extensions, 3726 } 3728 SUIT_Component_Identifier = [* bstr] 3730 SUIT_Common_Sequence = [ 3731 + ( SUIT_Condition // SUIT_Common_Commands ) 3732 ] 3734 SUIT_Common_Commands //= (suit-directive-set-component-index, IndexArg) 3735 SUIT_Common_Commands //= (suit-directive-set-dependency-index, IndexArg) 3736 SUIT_Common_Commands //= (suit-directive-run-sequence, 3737 bstr .cbor SUIT_Command_Sequence) 3738 SUIT_Common_Commands //= (suit-directive-try-each, 3739 SUIT_Directive_Try_Each_Argument) 3740 SUIT_Common_Commands //= (suit-directive-set-parameters, 3741 {+ SUIT_Parameters}) 3742 SUIT_Common_Commands //= (suit-directive-override-parameters, 3743 {+ SUIT_Parameters}) 3745 IndexArg /= uint 3746 IndexArg /= bool 3747 IndexArg /= [+uint] 3749 SUIT_Command_Sequence = [ + ( 3750 SUIT_Condition // SUIT_Directive // SUIT_Command_Custom 3751 ) ] 3753 SUIT_Command_Custom = (suit-command-custom, bstr/tstr/int/nil) 3754 SUIT_Condition //= (suit-condition-vendor-identifier, SUIT_Rep_Policy) 3755 SUIT_Condition //= (suit-condition-class-identifier, SUIT_Rep_Policy) 3756 SUIT_Condition //= (suit-condition-device-identifier, SUIT_Rep_Policy) 3757 SUIT_Condition //= (suit-condition-image-match, SUIT_Rep_Policy) 3758 SUIT_Condition //= (suit-condition-image-not-match, SUIT_Rep_Policy) 3759 SUIT_Condition //= (suit-condition-use-before, SUIT_Rep_Policy) 3760 SUIT_Condition //= (suit-condition-minimum-battery, SUIT_Rep_Policy) 3761 SUIT_Condition //= (suit-condition-update-authorized, SUIT_Rep_Policy) 3762 SUIT_Condition //= (suit-condition-version, SUIT_Rep_Policy) 3763 SUIT_Condition //= (suit-condition-component-offset, SUIT_Rep_Policy) 3764 SUIT_Condition //= (suit-condition-abort, SUIT_Rep_Policy) 3766 SUIT_Directive //= (suit-directive-set-component-index, IndexArg) 3767 SUIT_Directive //= (suit-directive-set-dependency-index, IndexArg) 3768 SUIT_Directive //= (suit-directive-run-sequence, 3769 bstr .cbor SUIT_Command_Sequence) 3770 SUIT_Directive //= (suit-directive-try-each, 3771 SUIT_Directive_Try_Each_Argument) 3772 SUIT_Directive //= (suit-directive-process-dependency, SUIT_Rep_Policy) 3773 SUIT_Directive //= (suit-directive-set-parameters, 3774 {+ SUIT_Parameters}) 3775 SUIT_Directive //= (suit-directive-override-parameters, 3776 {+ SUIT_Parameters}) 3777 SUIT_Directive //= (suit-directive-fetch, SUIT_Rep_Policy) 3778 SUIT_Directive //= (suit-directive-copy, SUIT_Rep_Policy) 3779 SUIT_Directive //= (suit-directive-swap, SUIT_Rep_Policy) 3780 SUIT_Directive //= (suit-directive-run, SUIT_Rep_Policy) 3781 SUIT_Directive //= (suit-directive-wait, SUIT_Rep_Policy) 3782 SUIT_Directive //= (suit-directive-fetch-uri-list, SUIT_Rep_Policy) 3783 SUIT_Directive //= (suit-directive-garbage-collect, SUIT_Rep_Policy) 3785 SUIT_Directive_Try_Each_Argument = [ 3786 + bstr .cbor SUIT_Command_Sequence, 3787 nil / bstr .cbor SUIT_Command_Sequence 3788 ] 3790 SUIT_Rep_Policy = uint .bits suit-reporting-bits 3792 suit-reporting-bits = &( 3793 suit-send-record-success : 0, 3794 suit-send-record-failure : 1, 3795 suit-send-sysinfo-success : 2, 3796 suit-send-sysinfo-failure : 3 3797 ) 3799 SUIT_Wait_Event = { + SUIT_Wait_Events } 3801 SUIT_Wait_Events //= (suit-wait-event-authorization => int) 3802 SUIT_Wait_Events //= (suit-wait-event-power => int) 3803 SUIT_Wait_Events //= (suit-wait-event-network => int) 3804 SUIT_Wait_Events //= (suit-wait-event-other-device-version 3805 => SUIT_Wait_Event_Argument_Other_Device_Version) 3806 SUIT_Wait_Events //= (suit-wait-event-time => uint); Timestamp 3807 SUIT_Wait_Events //= (suit-wait-event-time-of-day 3808 => uint); Time of Day (seconds since 00:00:00) 3809 SUIT_Wait_Events //= (suit-wait-event-day-of-week 3810 => uint); Days since Sunday 3812 SUIT_Wait_Event_Argument_Other_Device_Version = [ 3813 other-device: bstr, 3814 other-device-version: [ + SUIT_Parameter_Version_Match ] 3815 ] 3817 SUIT_Parameters //= (suit-parameter-vendor-identifier => 3818 (RFC4122_UUID / cbor-pen)) 3819 cbor-pen = #6.112(bstr) 3821 SUIT_Parameters //= (suit-parameter-class-identifier => RFC4122_UUID) 3822 SUIT_Parameters //= (suit-parameter-image-digest 3823 => bstr .cbor SUIT_Digest) 3824 SUIT_Parameters //= (suit-parameter-image-size => uint) 3825 SUIT_Parameters //= (suit-parameter-use-before => uint) 3826 SUIT_Parameters //= (suit-parameter-component-offset => uint) 3828 SUIT_Parameters //= (suit-parameter-encryption-info 3829 => bstr .cbor SUIT_Encryption_Info) 3830 SUIT_Parameters //= (suit-parameter-compression-info 3831 => bstr .cbor SUIT_Compression_Info) 3832 SUIT_Parameters //= (suit-parameter-unpack-info 3833 => bstr .cbor SUIT_Unpack_Info) 3835 SUIT_Parameters //= (suit-parameter-uri => tstr) 3836 SUIT_Parameters //= (suit-parameter-source-component => uint) 3837 SUIT_Parameters //= (suit-parameter-run-args => bstr) 3839 SUIT_Parameters //= (suit-parameter-device-identifier => RFC4122_UUID) 3840 SUIT_Parameters //= (suit-parameter-minimum-battery => uint) 3841 SUIT_Parameters //= (suit-parameter-update-priority => uint) 3842 SUIT_Parameters //= (suit-parameter-version => 3843 SUIT_Parameter_Version_Match) 3844 SUIT_Parameters //= (suit-parameter-wait-info => 3845 bstr .cbor SUIT_Wait_Event) 3847 SUIT_Parameters //= (suit-parameter-custom => int/bool/tstr/bstr) 3849 SUIT_Parameters //= (suit-parameter-strict-order => bool) 3850 SUIT_Parameters //= (suit-parameter-soft-failure => bool) 3851 SUIT_Parameters //= (suit-parameter-uri-list => 3852 bstr .cbor SUIT_URI_List) 3854 RFC4122_UUID = bstr .size 16 3856 SUIT_Parameter_Version_Match = [ 3857 suit-condition-version-comparison-type: 3858 SUIT_Condition_Version_Comparison_Types, 3859 suit-condition-version-comparison-value: 3860 SUIT_Condition_Version_Comparison_Value 3861 ] 3862 SUIT_Condition_Version_Comparison_Types /= 3863 suit-condition-version-comparison-greater 3864 SUIT_Condition_Version_Comparison_Types /= 3865 suit-condition-version-comparison-greater-equal 3866 SUIT_Condition_Version_Comparison_Types /= 3867 suit-condition-version-comparison-equal 3868 SUIT_Condition_Version_Comparison_Types /= 3869 suit-condition-version-comparison-lesser-equal 3870 SUIT_Condition_Version_Comparison_Types /= 3871 suit-condition-version-comparison-lesser 3873 suit-condition-version-comparison-greater = 1 3874 suit-condition-version-comparison-greater-equal = 2 3875 suit-condition-version-comparison-equal = 3 3876 suit-condition-version-comparison-lesser-equal = 4 3877 suit-condition-version-comparison-lesser = 5 3879 SUIT_Condition_Version_Comparison_Value = [+int] 3881 SUIT_Encryption_Info = COSE_Encrypt_Tagged/COSE_Encrypt0_Tagged 3882 SUIT_Compression_Info = { 3883 suit-compression-algorithm => SUIT_Compression_Algorithms, 3884 * $$SUIT_Compression_Info-extensions, 3885 } 3887 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_zlib 3888 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_brotli 3889 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_zstd 3891 SUIT_Compression_Algorithm_zlib = 1 3892 SUIT_Compression_Algorithm_brotli = 2 3893 SUIT_Compression_Algorithm_zstd = 3 3895 SUIT_Unpack_Info = { 3896 suit-unpack-algorithm => SUIT_Unpack_Algorithms, 3897 * $$SUIT_Unpack_Info-extensions, 3899 } 3901 SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Hex 3902 SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Elf 3903 SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Coff 3904 SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Srec 3906 SUIT_Unpack_Algorithm_Hex = 1 3907 SUIT_Unpack_Algorithm_Elf = 2 3908 SUIT_Unpack_Algorithm_Coff = 3 3909 SUIT_Unpack_Algorithm_Srec = 4 3911 SUIT_URI_List = [+ tstr ] 3913 SUIT_Text_Map = { 3914 * SUIT_Component_Identifier => { 3915 SUIT_Text_Component_Keys 3916 }, 3917 SUIT_Text_Keys 3918 } 3920 SUIT_Text_Component_Keys = ( 3921 ? suit-text-vendor-name => tstr, 3922 ? suit-text-model-name => tstr, 3923 ? suit-text-vendor-domain => tstr, 3924 ? suit-text-model-info => tstr, 3925 ? suit-text-component-description => tstr, 3926 ? suit-text-component-version => tstr, 3927 ? suit-text-version-required => tstr, 3928 * $$suit-text-component-key-extensions 3929 ) 3931 SUIT_Text_Keys = ( 3932 ? suit-text-manifest-description => tstr, 3933 ? suit-text-update-description => tstr, 3934 ? suit-text-manifest-json-source => tstr, 3935 ? suit-text-manifest-yaml-source => tstr, 3936 * $$suit-text-key-extensions 3937 ) 3939 suit-delegation = 1 3940 suit-authentication-wrapper = 2 3941 suit-manifest = 3 3943 algorithm-id-sha224 = 1 3944 algorithm-id-sha256 = 2 3945 algorithm-id-sha384 = 3 3946 algorithm-id-sha512 = 4 3947 algorithm-id-sha3-224 = 5 3948 algorithm-id-sha3-256 = 6 3949 algorithm-id-sha3-384 = 7 3950 algorithm-id-sha3-512 = 8 3952 suit-manifest-version = 1 3953 suit-manifest-sequence-number = 2 3954 suit-common = 3 3955 suit-reference-uri = 4 3956 suit-dependency-resolution = 7 3957 suit-payload-fetch = 8 3958 suit-install = 9 3959 suit-validate = 10 3960 suit-load = 11 3961 suit-run = 12 3962 suit-text = 13 3963 suit-coswid = 14 3965 suit-dependencies = 1 3966 suit-components = 2 3967 suit-common-sequence = 4 3969 suit-dependency-digest = 1 3970 suit-dependency-prefix = 2 3972 suit-command-custom = nint 3974 suit-condition-vendor-identifier = 1 3975 suit-condition-class-identifier = 2 3976 suit-condition-image-match = 3 3977 suit-condition-use-before = 4 3978 suit-condition-component-offset = 5 3980 suit-condition-abort = 14 3981 suit-condition-device-identifier = 24 3982 suit-condition-image-not-match = 25 3983 suit-condition-minimum-battery = 26 3984 suit-condition-update-authorized = 27 3985 suit-condition-version = 28 3987 suit-directive-set-component-index = 12 3988 suit-directive-set-dependency-index = 13 3989 suit-directive-try-each = 15 3990 suit-directive-process-dependency = 18 3991 suit-directive-set-parameters = 19 3992 suit-directive-override-parameters = 20 3993 suit-directive-fetch = 21 3994 suit-directive-copy = 22 3995 suit-directive-run = 23 3997 suit-directive-wait = 29 3998 suit-directive-fetch-uri-list = 30 3999 suit-directive-swap = 31 4000 suit-directive-run-sequence = 32 4001 suit-directive-garbage-collect = 33 4003 suit-wait-event-authorization = 1 4004 suit-wait-event-power = 2 4005 suit-wait-event-network = 3 4006 suit-wait-event-other-device-version = 4 4007 suit-wait-event-time = 5 4008 suit-wait-event-time-of-day = 6 4009 suit-wait-event-day-of-week = 7 4011 suit-parameter-vendor-identifier = 1 4012 suit-parameter-class-identifier = 2 4013 suit-parameter-image-digest = 3 4014 suit-parameter-use-before = 4 4015 suit-parameter-component-offset = 5 4017 suit-parameter-strict-order = 12 4018 suit-parameter-soft-failure = 13 4019 suit-parameter-image-size = 14 4021 suit-parameter-encryption-info = 18 4022 suit-parameter-compression-info = 19 4023 suit-parameter-unpack-info = 20 4024 suit-parameter-uri = 21 4025 suit-parameter-source-component = 22 4026 suit-parameter-run-args = 23 4028 suit-parameter-device-identifier = 24 4029 suit-parameter-minimum-battery = 26 4030 suit-parameter-update-priority = 27 4031 suit-parameter-version = 28 4032 suit-parameter-wait-info = 29 4033 suit-parameter-uri-list = 30 4035 suit-parameter-custom = nint 4037 suit-compression-algorithm = 1 4039 suit-unpack-algorithm = 1 4041 suit-text-manifest-description = 1 4042 suit-text-update-description = 2 4043 suit-text-manifest-json-source = 3 4044 suit-text-manifest-yaml-source = 4 4046 suit-text-vendor-name = 1 4047 suit-text-model-name = 2 4048 suit-text-vendor-domain = 3 4049 suit-text-model-info = 4 4050 suit-text-component-description = 5 4051 suit-text-component-version = 6 4052 suit-text-version-required = 7 4054 Appendix B. B. Examples 4056 The following examples demonstrate a small subset of the 4057 functionality of the manifest. Even a simple manifest processor can 4058 execute most of these manifests. 4060 The examples are signed using the following ECDSA secp256r1 key: 4062 -----BEGIN PRIVATE KEY----- 4063 MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgApZYjZCUGLM50VBC 4064 CjYStX+09jGmnyJPrpDLTz/hiXOhRANCAASEloEarguqq9JhVxie7NomvqqL8Rtv 4065 P+bitWWchdvArTsfKktsCYExwKNtrNHXi9OB3N+wnAUtszmR23M4tKiW 4066 -----END PRIVATE KEY----- 4068 The corresponding public key can be used to verify these examples: 4070 -----BEGIN PUBLIC KEY----- 4071 MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEhJaBGq4LqqvSYVcYnuzaJr6qi/Eb 4072 bz/m4rVlnIXbwK07HypLbAmBMcCjbazR14vTgdzfsJwFLbM5kdtzOLSolg== 4073 -----END PUBLIC KEY----- 4075 Each example uses SHA256 as the digest function. 4077 Note that reporting policies are declared for each non-flow-control 4078 command in these examples. The reporting policies used in the 4079 examples are described in the following tables. 4081 +-----------------------------+----------+ 4082 | Policy | Label | 4083 +-----------------------------+----------+ 4084 | suit-send-record-on-success | Rec-Pass | 4085 | | | 4086 | suit-send-record-on-failure | Rec-Fail | 4087 | | | 4088 | suit-send-sysinfo-success | Sys-Pass | 4089 | | | 4090 | suit-send-sysinfo-failure | Sys-Fail | 4091 +-----------------------------+----------+ 4093 +----------------------------+--------+---------+---------+---------+ 4094 | Command | Sys- | Sys- | Rec- | Rec- | 4095 | | Fail | Pass | Fail | Pass | 4096 +----------------------------+--------+---------+---------+---------+ 4097 | suit-condition-vendor- | 1 | 1 | 1 | 1 | 4098 | identifier | | | | | 4099 | | | | | | 4100 | suit-condition-class- | 1 | 1 | 1 | 1 | 4101 | identifier | | | | | 4102 | | | | | | 4103 | suit-condition-image-match | 1 | 1 | 1 | 1 | 4104 | | | | | | 4105 | suit-condition-component- | 0 | 1 | 0 | 1 | 4106 | offset | | | | | 4107 | | | | | | 4108 | suit-directive-fetch | 0 | 0 | 1 | 0 | 4109 | | | | | | 4110 | suit-directive-copy | 0 | 0 | 1 | 0 | 4111 | | | | | | 4112 | suit-directive-run | 0 | 0 | 1 | 0 | 4113 +----------------------------+--------+---------+---------+---------+ 4115 B.1. Example 0: Secure Boot 4117 This example covers the following templates: 4119 - Compatibility Check (Section 7.1) 4121 - Secure Boot (Section 7.2) 4123 It also serves as the minimum example. 4125 { 4126 / authentication-wrapper / 2:bstr .cbor ([ 4127 digest: bstr .cbor ([ 4128 / algorithm-id / 2 / "sha256" /, 4129 / digest-bytes / 4130 h'5c097ef64bf3bb9b494e71e1f2418eef8d466cc902f639a855ec9af3e9eddb99' 4131 ]), 4132 signature: bstr .cbor (18([ 4133 / protected / bstr .cbor ({ 4134 / alg / 1:-7 / "ES256" /, 4135 }), 4136 / unprotected / { 4137 }, 4138 / payload / F6 / nil /, 4139 / signature / h'a19fd1f23b17beed321cece7423dfb48c457b8 4140 f1f6ac83577a3c10c6773f6f3a7902376b59540920b6c5f57bac5fc8543d8f5d3d974f 4141 aa2e6d03daa534b443a7' 4142 ])) 4143 ] 4144 ]), 4145 / manifest / 3:bstr .cbor ({ 4146 / manifest-version / 1:1, 4147 / manifest-sequence-number / 2:0, 4148 / common / 3:bstr .cbor ({ 4149 / components / 2:[ 4150 [h'00'] 4151 ], 4152 / common-sequence / 4:bstr .cbor ([ 4153 / directive-override-parameters / 20,{ 4154 / vendor-id / 4155 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 4156 be9d-e663e4d41ffe /, 4157 / class-id / 2:h'1492af1425695e48bf429b2d51f2ab45' 4158 / 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 4159 / image-digest / 3:bstr .cbor ([ 4160 / algorithm-id / 2 / "sha256" /, 4161 / digest-bytes / 4162 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 4163 ]), 4164 / image-size / 14:34768, 4165 } , 4166 / condition-vendor-identifier / 1,15 , 4167 / condition-class-identifier / 2,15 4168 ]), 4169 }), 4170 / validate / 10:bstr .cbor ([ 4171 / condition-image-match / 3,15 4172 ]), 4173 / run / 12:bstr .cbor ([ 4174 / directive-run / 23,2 4175 ]), 4176 }), 4178 } 4180 Total size of Envelope without COSE authentication object: 159 4182 Envelope: 4184 a2025827815824820258205c097ef64bf3bb9b494e71e1f2418eef8d466c 4185 c902f639a855ec9af3e9eddb99035871a50101020003585fa20281814100 4186 0458568614a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af14 4187 25695e48bf429b2d51f2ab450358248202582000112233445566778899aa 4188 bbccddeeff0123456789abcdeffedcba98765432100e1987d0010f020f0a 4189 4382030f0c43821702 4191 Total size of Envelope with COSE authentication object: 235 4193 Envelope with COSE authentication object: 4195 a2025873825824820258205c097ef64bf3bb9b494e71e1f2418eef8d466c 4196 c902f639a855ec9af3e9eddb99584ad28443a10126a0f65840a19fd1f23b 4197 17beed321cece7423dfb48c457b8f1f6ac83577a3c10c6773f6f3a790237 4198 6b59540920b6c5f57bac5fc8543d8f5d3d974faa2e6d03daa534b443a703 4199 5871a50101020003585fa202818141000458568614a40150fa6b4a53d5ad 4200 5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab450358 4201 248202582000112233445566778899aabbccddeeff0123456789abcdeffe 4202 dcba98765432100e1987d0010f020f0a4382030f0c43821702 4204 B.2. Example 1: Simultaneous Download and Installation of Payload 4206 This example covers the following templates: 4208 - Compatibility Check (Section 7.1) 4210 - Firmware Download (Section 7.3) 4212 Simultaneous download and installation of payload. No secure boot is 4213 present in this example to demonstrate a download-only manifest. 4215 { 4216 / authentication-wrapper / 2:bstr .cbor ([ 4217 digest: bstr .cbor ([ 4218 / algorithm-id / 2 / "sha256" /, 4219 / digest-bytes / 4220 h'987eec85fa99fd31d332381b9810f90b05c2e0d4f284a6f4211207ed00fff750' 4221 ]), 4222 signature: bstr .cbor (18([ 4223 / protected / bstr .cbor ({ 4224 / alg / 1:-7 / "ES256" /, 4225 }), 4226 / unprotected / { 4227 }, 4228 / payload / F6 / nil /, 4229 / signature / h'0008d2678ddda1afd6846cb9272f539a789e4c 4230 ed4c874774e58dbe4cf1607e755668029ad6383d4e14c72083ba43002fe3f5cda48859 4231 90c9b59135976b80ebc9' 4232 ])) 4233 ] 4234 ]), 4235 / manifest / 3:bstr .cbor ({ 4236 / manifest-version / 1:1, 4237 / manifest-sequence-number / 2:1, 4238 / common / 3:bstr .cbor ({ 4239 / components / 2:[ 4240 [h'00'] 4241 ], 4242 / common-sequence / 4:bstr .cbor ([ 4243 / directive-override-parameters / 20,{ 4244 / vendor-id / 4245 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 4246 be9d-e663e4d41ffe /, 4247 / class-id / 2:h'1492af1425695e48bf429b2d51f2ab45' 4248 / 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 4249 / image-digest / 3:bstr .cbor ([ 4250 / algorithm-id / 2 / "sha256" /, 4251 / digest-bytes / 4252 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 4253 ]), 4254 / image-size / 14:34768, 4255 } , 4256 / condition-vendor-identifier / 1,15 , 4257 / condition-class-identifier / 2,15 4258 ]), 4259 }), 4260 / install / 9:bstr .cbor ([ 4261 / directive-set-parameters / 19,{ 4262 / uri / 21:'http://example.com/file.bin', 4263 } , 4264 / directive-fetch / 21,2 , 4265 / condition-image-match / 3,15 4266 ]), 4267 / validate / 10:bstr .cbor ([ 4268 / condition-image-match / 3,15 4269 ]), 4270 }), 4271 } 4273 Total size of Envelope without COSE authentication object: 194 4274 Envelope: 4276 a202582781582482025820987eec85fa99fd31d332381b9810f90b05c2e0 4277 d4f284a6f4211207ed00fff750035894a50101020103585fa20281814100 4278 0458568614a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af14 4279 25695e48bf429b2d51f2ab450358248202582000112233445566778899aa 4280 bbccddeeff0123456789abcdeffedcba98765432100e1987d0010f020f09 4281 58258613a115781b687474703a2f2f6578616d706c652e636f6d2f66696c 4282 652e62696e1502030f0a4382030f 4284 Total size of Envelope with COSE authentication object: 270 4286 Envelope with COSE authentication object: 4288 a202587382582482025820987eec85fa99fd31d332381b9810f90b05c2e0 4289 d4f284a6f4211207ed00fff750584ad28443a10126a0f658400008d2678d 4290 dda1afd6846cb9272f539a789e4ced4c874774e58dbe4cf1607e75566802 4291 9ad6383d4e14c72083ba43002fe3f5cda4885990c9b59135976b80ebc903 4292 5894a50101020103585fa202818141000458568614a40150fa6b4a53d5ad 4293 5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab450358 4294 248202582000112233445566778899aabbccddeeff0123456789abcdeffe 4295 dcba98765432100e1987d0010f020f0958258613a115781b687474703a2f 4296 2f6578616d706c652e636f6d2f66696c652e62696e1502030f0a4382030f 4298 B.3. Example 2: Simultaneous Download, Installation, Secure Boot, 4299 Severed Fields 4301 This example covers the following templates: 4303 - Compatibility Check (Section 7.1) 4305 - Secure Boot (Section 7.2) 4307 - Firmware Download (Section 7.3) 4309 This example also demonstrates severable elements (Section 5.5), and 4310 text (Section 8.6.4). 4312 { 4313 / authentication-wrapper / 2:bstr .cbor ([ 4314 digest: bstr .cbor ([ 4315 / algorithm-id / 2 / "sha256" /, 4316 / digest-bytes / 4317 h'78fa7652e377d31dcd7e95730c885ef13b6ee394d586410aa5fd0aca1f299d34' 4318 ]), 4319 signature: bstr .cbor (18([ 4320 / protected / bstr .cbor ({ 4321 / alg / 1:-7 / "ES256" /, 4323 }), 4324 / unprotected / { 4325 }, 4326 / payload / F6 / nil /, 4327 / signature / h'1aa5bf99688b5d6a1211fd9c99bdd409b64cd6 4328 add316ff87029a81faf682f93c5fb94863eebdfd17a6fcfed729ffa9735a624ce7edb5 4329 65cba26ff7a5bd6a779d' 4330 ])) 4331 ] 4332 ]), 4333 / manifest / 3:bstr .cbor ({ 4334 / manifest-version / 1:1, 4335 / manifest-sequence-number / 2:2, 4336 / common / 3:bstr .cbor ({ 4337 / components / 2:[ 4338 [h'00'] 4339 ], 4340 / common-sequence / 4:bstr .cbor ([ 4341 / directive-override-parameters / 20,{ 4342 / vendor-id / 4343 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 4344 be9d-e663e4d41ffe /, 4345 / class-id / 2:h'1492af1425695e48bf429b2d51f2ab45' 4346 / 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 4347 / image-digest / 3:bstr .cbor ([ 4348 / algorithm-id / 2 / "sha256" /, 4349 / digest-bytes / 4350 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 4351 ]), 4352 / image-size / 14:34768, 4353 } , 4354 / condition-vendor-identifier / 1,15 , 4355 / condition-class-identifier / 2,15 4356 ]), 4357 }), 4358 / install / 9:[ 4359 / algorithm-id / 2 / "sha256" /, 4360 / digest-bytes / 4361 h'3ee96dc79641970ae46b929ccf0b72ba9536dd846020dbdc9f949d84ea0e18d2' 4362 ], 4363 / validate / 10:bstr .cbor ([ 4364 / condition-image-match / 3,15 4365 ]), 4366 / run / 12:bstr .cbor ([ 4367 / directive-run / 23,2 4368 ]), 4369 / text / 13:[ 4370 / algorithm-id / 2 / "sha256" /, 4371 / digest-bytes / 4372 h'2bfc4d0cc6680be7dd9f5ca30aa2bb5d1998145de33d54101b80e2ca49faf918' 4373 ], 4374 }), 4375 / install / 9:bstr .cbor ([ 4376 / directive-set-parameters / 19,{ 4377 / uri / 4378 21:'http://example.com/very/long/path/to/file/file.bin', 4379 } , 4380 / directive-fetch / 21,2 , 4381 / condition-image-match / 3,15 4382 ]), 4383 / text / 13:bstr .cbor ({ 4384 [h'00']:{ 4385 / vendor-domain / 3:'arm.com', 4386 / component-description / 5:'This component is a 4387 demonstration. The digest is a sample pattern, not a real one.', 4388 } 4389 }), 4390 } 4392 Total size of the Envelope without COSE authentication object or 4393 Severable Elements: 233 4395 Envelope: 4397 a20258278158248202582078fa7652e377d31dcd7e95730c885ef13b6ee3 4398 94d586410aa5fd0aca1f299d340358bba70101020203585fa20281814100 4399 0458568614a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af14 4400 25695e48bf429b2d51f2ab450358248202582000112233445566778899aa 4401 bbccddeeff0123456789abcdeffedcba98765432100e1987d0010f020f09 4402 820258203ee96dc79641970ae46b929ccf0b72ba9536dd846020dbdc9f94 4403 9d84ea0e18d20a4382030f0c438217020d820258202bfc4d0cc6680be7dd 4404 9f5ca30aa2bb5d1998145de33d54101b80e2ca49faf918 4406 Total size of the Envelope with COSE authentication object but 4407 without Severable Elements: 309 4409 Envelope: 4411 a20258738258248202582078fa7652e377d31dcd7e95730c885ef13b6ee3 4412 94d586410aa5fd0aca1f299d34584ad28443a10126a0f658401aa5bf9968 4413 8b5d6a1211fd9c99bdd409b64cd6add316ff87029a81faf682f93c5fb948 4414 63eebdfd17a6fcfed729ffa9735a624ce7edb565cba26ff7a5bd6a779d03 4415 58bba70101020203585fa202818141000458568614a40150fa6b4a53d5ad 4416 5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab450358 4417 248202582000112233445566778899aabbccddeeff0123456789abcdeffe 4418 dcba98765432100e1987d0010f020f09820258203ee96dc79641970ae46b 4419 929ccf0b72ba9536dd846020dbdc9f949d84ea0e18d20a4382030f0c4382 4420 17020d820258202bfc4d0cc6680be7dd9f5ca30aa2bb5d1998145de33d54 4421 101b80e2ca49faf918 4423 Total size of Envelope with COSE authentication object and Severable 4424 Elements: 892 4426 Envelope with COSE authentication object: 4428 a40258738258248202582078fa7652e377d31dcd7e95730c885ef13b6ee3 4429 94d586410aa5fd0aca1f299d34584ad28443a10126a0f658401aa5bf9968 4430 8b5d6a1211fd9c99bdd409b64cd6add316ff87029a81faf682f93c5fb948 4431 63eebdfd17a6fcfed729ffa9735a624ce7edb565cba26ff7a5bd6a779d03 4432 58bba70101020203585fa202818141000458568614a40150fa6b4a53d5ad 4433 5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab450358 4434 248202582000112233445566778899aabbccddeeff0123456789abcdeffe 4435 dcba98765432100e1987d0010f020f09820258203ee96dc79641970ae46b 4436 929ccf0b72ba9536dd846020dbdc9f949d84ea0e18d20a4382030f0c4382 4437 17020d820258202bfc4d0cc6680be7dd9f5ca30aa2bb5d1998145de33d54 4438 101b80e2ca49faf91809583c8613a1157832687474703a2f2f6578616d70 4439 6c652e636f6d2f766572792f6c6f6e672f706174682f746f2f66696c652f 4440 66696c652e62696e1502030f0d590204a20179019d2323204578616d706c 4441 6520323a2053696d756c74616e656f757320446f776e6c6f61642c20496e 4442 7374616c6c6174696f6e2c2053656375726520426f6f742c205365766572 4443 6564204669656c64730a0a2020202054686973206578616d706c6520636f 4444 766572732074686520666f6c6c6f77696e672074656d706c617465733a0a 4445 202020200a202020202a20436f6d7061746962696c69747920436865636b 4446 20287b7b74656d706c6174652d636f6d7061746962696c6974792d636865 4447 636b7d7d290a202020202a2053656375726520426f6f7420287b7b74656d 4448 706c6174652d7365637572652d626f6f747d7d290a202020202a20466972 4449 6d7761726520446f776e6c6f616420287b7b6669726d776172652d646f77 4450 6e6c6f61642d74656d706c6174657d7d290a202020200a20202020546869 4451 73206578616d706c6520616c736f2064656d6f6e73747261746573207365 4452 76657261626c6520656c656d656e747320287b7b6f76722d736576657261 4453 626c657d7d292c20616e64207465787420287b7b6d616e69666573742d64 4454 69676573742d746578747d7d292e814100a2036761726d2e636f6d057852 4455 5468697320636f6d706f6e656e7420697320612064656d6f6e7374726174 4456 696f6e2e205468652064696765737420697320612073616d706c65207061 4457 747465726e2c206e6f742061207265616c206f6e652e 4459 B.4. Example 3: A/B images 4461 This example covers the following templates: 4463 - Compatibility Check (Section 7.1) 4465 - Secure Boot (Section 7.2) 4467 - Firmware Download (Section 7.3) 4469 - A/B Image Template (Section 7.11) 4471 { 4472 / authentication-wrapper / 2:bstr .cbor ([ 4473 digest: bstr .cbor ([ 4474 / algorithm-id / 2 / "sha256" /, 4475 / digest-bytes / 4476 h'ae0c1ea689c9800a843550f38796b6fdbd52a0c78be5d26011d8e784da43d47c' 4477 ]), 4478 signature: bstr .cbor (18([ 4479 / protected / bstr .cbor ({ 4480 / alg / 1:-7 / "ES256" /, 4481 }), 4482 / unprotected / { 4483 }, 4484 / payload / F6 / nil /, 4485 / signature / h'1296c87d168bb857495e6551730f9d6d3a6d81 4486 ad6c908c72fbc52ddcb2e8011d20d217b3f1c028374eecbda5d2ca26d047270b397dca 4487 a91a48a7c78cf376004e' 4488 ])) 4489 ] 4490 ]), 4491 / manifest / 3:bstr .cbor ({ 4492 / manifest-version / 1:1, 4493 / manifest-sequence-number / 2:3, 4494 / common / 3:bstr .cbor ({ 4495 / components / 2:[ 4496 [h'00'] 4497 ], 4498 / common-sequence / 4:bstr .cbor ([ 4499 / directive-override-parameters / 20,{ 4500 / vendor-id / 4501 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 4502 be9d-e663e4d41ffe /, 4503 / class-id / 2:h'1492af1425695e48bf429b2d51f2ab45' 4504 / 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 4505 } , 4506 / directive-try-each / 15,[ 4507 bstr .cbor ([ 4508 / directive-override-parameters / 20,{ 4509 / offset / 5:33792, 4510 } , 4511 / condition-component-offset / 5,5 , 4512 / directive-override-parameters / 20,{ 4513 / image-digest / 3:bstr .cbor ([ 4514 / algorithm-id / 2 / "sha256" /, 4515 / digest-bytes / 4516 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 4517 ]), 4518 / image-size / 14:34768, 4519 } 4520 ]) , 4521 bstr .cbor ([ 4522 / directive-override-parameters / 20,{ 4523 / offset / 5:541696, 4524 } , 4525 / condition-component-offset / 5,5 , 4526 / directive-override-parameters / 20,{ 4527 / image-digest / 3:bstr .cbor ([ 4528 / algorithm-id / 2 / "sha256" /, 4529 / digest-bytes / 4530 h'0123456789abcdeffedcba987654321000112233445566778899aabbccddeeff' 4531 ]), 4532 / image-size / 14:76834, 4533 } 4534 ]) 4535 ] , 4536 / condition-vendor-identifier / 1,15 , 4537 / condition-class-identifier / 2,15 4538 ]), 4539 }), 4540 / install / 9:bstr .cbor ([ 4541 / directive-try-each / 15,[ 4542 bstr .cbor ([ 4543 / directive-set-parameters / 19,{ 4544 / offset / 5:33792, 4545 } , 4546 / condition-component-offset / 5,5 , 4547 / directive-set-parameters / 19,{ 4548 / uri / 21:'http://example.com/file1.bin', 4549 } 4550 ]) , 4551 bstr .cbor ([ 4552 / directive-set-parameters / 19,{ 4553 / offset / 5:541696, 4554 } , 4555 / condition-component-offset / 5,5 , 4556 / directive-set-parameters / 19,{ 4557 / uri / 21:'http://example.com/file2.bin', 4558 } 4559 ]) 4560 ] , 4561 / directive-fetch / 21,2 , 4562 / condition-image-match / 3,15 4563 ]), 4564 / validate / 10:bstr .cbor ([ 4565 / condition-image-match / 3,15 4566 ]), 4567 }), 4568 } 4570 Total size of Envelope without COSE authentication object: 330 4572 Envelope: 4574 a202582781582482025820ae0c1ea689c9800a843550f38796b6fdbd52a0 4575 c78be5d26011d8e784da43d47c0359011ba5010102030358aaa202818141 4576 000458a18814a20150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af 4577 1425695e48bf429b2d51f2ab450f8258368614a105198400050514a20358 4578 248202582000112233445566778899aabbccddeeff0123456789abcdeffe 4579 dcba98765432100e1987d0583a8614a1051a00084400050514a203582482 4580 0258200123456789abcdeffedcba987654321000112233445566778899aa 4581 bbccddeeff0e1a00012c22010f020f095861860f82582a8613a105198400 4582 050513a115781c687474703a2f2f6578616d706c652e636f6d2f66696c65 4583 312e62696e582c8613a1051a00084400050513a115781c687474703a2f2f 4584 6578616d706c652e636f6d2f66696c65322e62696e1502030f0a4382030f 4586 Total size of Envelope with COSE authentication object: 406 4588 Envelope with COSE authentication object: 4590 a202587382582482025820ae0c1ea689c9800a843550f38796b6fdbd52a0 4591 c78be5d26011d8e784da43d47c584ad28443a10126a0f658401296c87d16 4592 8bb857495e6551730f9d6d3a6d81ad6c908c72fbc52ddcb2e8011d20d217 4593 b3f1c028374eecbda5d2ca26d047270b397dcaa91a48a7c78cf376004e03 4594 59011ba5010102030358aaa202818141000458a18814a20150fa6b4a53d5 4595 ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab450f 4596 8258368614a105198400050514a203582482025820001122334455667788 4597 99aabbccddeeff0123456789abcdeffedcba98765432100e1987d0583a86 4598 14a1051a00084400050514a2035824820258200123456789abcdeffedcba 4599 987654321000112233445566778899aabbccddeeff0e1a00012c22010f02 4600 0f095861860f82582a8613a105198400050513a115781c687474703a2f2f 4601 6578616d706c652e636f6d2f66696c65312e62696e582c8613a1051a0008 4602 4400050513a115781c687474703a2f2f6578616d706c652e636f6d2f6669 4603 6c65322e62696e1502030f0a4382030f 4605 B.5. Example 4: Load and Decompress from External Storage 4607 This example covers the following templates: 4609 - Compatibility Check (Section 7.1) 4611 - Secure Boot (Section 7.2) 4613 - Firmware Download (Section 7.3) 4615 - Install (Section 7.4) 4617 - Load & Decompress (Section 7.8) 4619 { 4620 / authentication-wrapper / 2:bstr .cbor ([ 4621 digest: bstr .cbor ([ 4622 / algorithm-id / 2 / "sha256" /, 4623 / digest-bytes / 4624 h'4b4c7c8c0fda76c9c9591a9db160918e2b3c96a58b0a5e4984fd4e8f9359a928' 4625 ]), 4626 signature: bstr .cbor (18([ 4627 / protected / bstr .cbor ({ 4628 / alg / 1:-7 / "ES256" /, 4629 }), 4630 / unprotected / { 4631 }, 4632 / payload / F6 / nil /, 4633 / signature / h'd88c4953fe5a0399e69ab37fe654d1f1b957a4 4634 4a46fde3e9cffdf0cdaa0456ddce9f08bc2a59895ffd70adce0e4aee8690645dcd4b7b 4635 77d401bd91e35aa115d2' 4636 ])) 4637 ] 4639 ]), 4640 / manifest / 3:bstr .cbor ({ 4641 / manifest-version / 1:1, 4642 / manifest-sequence-number / 2:4, 4643 / common / 3:bstr .cbor ({ 4644 / components / 2:[ 4645 [h'00'] , 4646 [h'02'] , 4647 [h'01'] 4648 ], 4649 / common-sequence / 4:bstr .cbor ([ 4650 / directive-set-component-index / 12,0 , 4651 / directive-override-parameters / 20,{ 4652 / vendor-id / 4653 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 4654 be9d-e663e4d41ffe /, 4655 / class-id / 2:h'1492af1425695e48bf429b2d51f2ab45' 4656 / 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 4657 / image-digest / 3:bstr .cbor ([ 4658 / algorithm-id / 2 / "sha256" /, 4659 / digest-bytes / 4660 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 4661 ]), 4662 / image-size / 14:34768, 4663 } , 4664 / condition-vendor-identifier / 1,15 , 4665 / condition-class-identifier / 2,15 4666 ]), 4667 }), 4668 / payload-fetch / 8:bstr .cbor ([ 4669 / directive-set-component-index / 12,1 , 4670 / directive-set-parameters / 19,{ 4671 / uri / 21:'http://example.com/file.bin', 4672 } , 4673 / directive-fetch / 21,2 , 4674 / condition-image-match / 3,15 4675 ]), 4676 / install / 9:bstr .cbor ([ 4677 / directive-set-component-index / 12,0 , 4678 / directive-set-parameters / 19,{ 4679 / source-component / 22:1 / [h'02'] /, 4680 } , 4681 / directive-copy / 22,2 , 4682 / condition-image-match / 3,15 4683 ]), 4684 / validate / 10:bstr .cbor ([ 4685 / directive-set-component-index / 12,0 , 4686 / condition-image-match / 3,15 4688 ]), 4689 / load / 11:bstr .cbor ([ 4690 / directive-set-component-index / 12,2 , 4691 / directive-set-parameters / 19,{ 4692 / image-digest / 3:bstr .cbor ([ 4693 / algorithm-id / 2 / "sha256" /, 4694 / digest-bytes / 4695 h'0123456789abcdeffedcba987654321000112233445566778899aabbccddeeff' 4696 ]), 4697 / image-size / 14:76834, 4698 / source-component / 22:0 / [h'00'] /, 4699 / compression-info / 19:1 / "gzip" /, 4700 } , 4701 / directive-copy / 22,2 , 4702 / condition-image-match / 3,15 4703 ]), 4704 / run / 12:bstr .cbor ([ 4705 / directive-set-component-index / 12,2 , 4706 / directive-run / 23,2 4707 ]), 4708 }), 4709 } 4711 Total size of Envelope without COSE authentication object: 287 4713 Envelope: 4715 a2025827815824820258204b4c7c8c0fda76c9c9591a9db160918e2b3c96 4716 a58b0a5e4984fd4e8f9359a9280358f1a801010204035867a20283814100 4717 814102814101045858880c0014a40150fa6b4a53d5ad5fdfbe9de663e4d4 4718 1ffe02501492af1425695e48bf429b2d51f2ab4503582482025820001122 4719 33445566778899aabbccddeeff0123456789abcdeffedcba98765432100e 4720 1987d0010f020f085827880c0113a115781b687474703a2f2f6578616d70 4721 6c652e636f6d2f66696c652e62696e1502030f094b880c0013a116011602 4722 030f0a45840c00030f0b583a880c0213a4035824820258200123456789ab 4723 cdeffedcba987654321000112233445566778899aabbccddeeff0e1a0001 4724 2c22130116001602030f0c45840c021702 4726 Total size of Envelope with COSE authentication object: 363 4728 Envelope with COSE authentication object: 4730 a2025873825824820258204b4c7c8c0fda76c9c9591a9db160918e2b3c96 4731 a58b0a5e4984fd4e8f9359a928584ad28443a10126a0f65840d88c4953fe 4732 5a0399e69ab37fe654d1f1b957a44a46fde3e9cffdf0cdaa0456ddce9f08 4733 bc2a59895ffd70adce0e4aee8690645dcd4b7b77d401bd91e35aa115d203 4734 58f1a801010204035867a20283814100814102814101045858880c0014a4 4735 0150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf42 4736 9b2d51f2ab450358248202582000112233445566778899aabbccddeeff01 4737 23456789abcdeffedcba98765432100e1987d0010f020f085827880c0113 4738 a115781b687474703a2f2f6578616d706c652e636f6d2f66696c652e6269 4739 6e1502030f094b880c0013a116011602030f0a45840c00030f0b583a880c 4740 0213a4035824820258200123456789abcdeffedcba987654321000112233 4741 445566778899aabbccddeeff0e1a00012c22130116001602030f0c45840c 4742 021702 4744 B.6. Example 5: Two Images 4746 This example covers the following templates: 4748 - Compatibility Check (Section 7.1) 4750 - Secure Boot (Section 7.2) 4752 - Firmware Download (Section 7.3) 4754 Furthermore, it shows using these templates with two images. 4756 { 4757 / authentication-wrapper / 2:bstr .cbor ([ 4758 digest: bstr .cbor ([ 4759 / algorithm-id / 2 / "sha256" /, 4760 / digest-bytes / 4761 h'de7c7927a15bd2eda59cab1512875f17c9f1e9e23885ce1ac6d671eefcefa37a' 4762 ]), 4763 signature: bstr .cbor (18([ 4764 / protected / bstr .cbor ({ 4765 / alg / 1:-7 / "ES256" /, 4766 }), 4767 / unprotected / { 4768 }, 4769 / payload / F6 / nil /, 4770 / signature / h'8f5919c05ef786366ab4899db27a2e7412ef72 4771 480372437757b1c1c9f8b2ed2a677a88db17fcfbb47d178c9e5620f14ac68a314ceabc 4772 d20cbf54fbe89b8e83ad' 4773 ])) 4774 ] 4775 ]), 4776 / manifest / 3:bstr .cbor ({ 4777 / manifest-version / 1:1, 4778 / manifest-sequence-number / 2:5, 4779 / common / 3:bstr .cbor ({ 4780 / components / 2:[ 4781 [h'00'] , 4782 [h'01'] 4783 ], 4784 / common-sequence / 4:bstr .cbor ([ 4785 / directive-set-component-index / 12,0 , 4786 / directive-override-parameters / 20,{ 4787 / vendor-id / 4788 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 4789 be9d-e663e4d41ffe /, 4790 / class-id / 2:h'1492af1425695e48bf429b2d51f2ab45' 4791 / 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 4792 / image-digest / 3:bstr .cbor ([ 4793 / algorithm-id / 2 / "sha256" /, 4794 / digest-bytes / 4795 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 4796 ]), 4797 / image-size / 14:34768, 4798 } , 4799 / condition-vendor-identifier / 1,15 , 4800 / condition-class-identifier / 2,15 , 4801 / directive-set-component-index / 12,1 , 4802 / directive-override-parameters / 20,{ 4803 / image-digest / 3:bstr .cbor ([ 4804 / algorithm-id / 2 / "sha256" /, 4805 / digest-bytes / 4806 h'0123456789abcdeffedcba987654321000112233445566778899aabbccddeeff' 4807 ]), 4808 / image-size / 14:76834, 4809 } 4810 ]), 4811 }), 4812 / install / 9:bstr .cbor ([ 4813 / directive-set-component-index / 12,0 , 4814 / directive-set-parameters / 19,{ 4815 / uri / 21:'http://example.com/file1.bin', 4816 } , 4817 / directive-fetch / 21,2 , 4818 / condition-image-match / 3,15 , 4819 / directive-set-component-index / 12,1 , 4820 / directive-set-parameters / 19,{ 4821 / uri / 21:'http://example.com/file2.bin', 4822 } , 4823 / directive-fetch / 21,2 , 4824 / condition-image-match / 3,15 4825 ]), 4826 / validate / 10:bstr .cbor ([ 4827 / directive-set-component-index / 12,0 , 4828 / condition-image-match / 3,15 , 4829 / directive-set-component-index / 12,1 , 4830 / condition-image-match / 3,15 4831 ]), 4832 / run / 12:bstr .cbor ([ 4833 / directive-set-component-index / 12,0 , 4834 / directive-run / 23,2 4835 ]), 4836 }), 4837 } 4839 Total size of Envelope without COSE authentication object: 304 4841 Envelope: 4843 a202582781582482025820de7c7927a15bd2eda59cab1512875f17c9f1e9 4844 e23885ce1ac6d671eefcefa37a03590101a601010205035895a202828141 4845 008141010458898c0c0014a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe 4846 02501492af1425695e48bf429b2d51f2ab45035824820258200011223344 4847 5566778899aabbccddeeff0123456789abcdeffedcba98765432100e1987 4848 d0010f020f0c0114a2035824820258200123456789abcdeffedcba987654 4849 321000112233445566778899aabbccddeeff0e1a00012c2209584f900c00 4850 13a115781c687474703a2f2f6578616d706c652e636f6d2f66696c65312e 4851 62696e1502030f0c0113a115781c687474703a2f2f6578616d706c652e63 4852 6f6d2f66696c65322e62696e1502030f0a49880c00030f0c01030f0c4584 4853 0c001702 4855 Total size of Envelope with COSE authentication object: 380 4857 Envelope with COSE authentication object: 4859 a202587382582482025820de7c7927a15bd2eda59cab1512875f17c9f1e9 4860 e23885ce1ac6d671eefcefa37a584ad28443a10126a0f658408f5919c05e 4861 f786366ab4899db27a2e7412ef72480372437757b1c1c9f8b2ed2a677a88 4862 db17fcfbb47d178c9e5620f14ac68a314ceabcd20cbf54fbe89b8e83ad03 4863 590101a601010205035895a202828141008141010458898c0c0014a40150 4864 fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d 4865 51f2ab450358248202582000112233445566778899aabbccddeeff012345 4866 6789abcdeffedcba98765432100e1987d0010f020f0c0114a20358248202 4867 58200123456789abcdeffedcba987654321000112233445566778899aabb 4868 ccddeeff0e1a00012c2209584f900c0013a115781c687474703a2f2f6578 4869 616d706c652e636f6d2f66696c65312e62696e1502030f0c0113a115781c 4870 687474703a2f2f6578616d706c652e636f6d2f66696c65322e62696e1502 4871 030f0a49880c00030f0c01030f0c45840c001702 4873 Appendix C. C. Design Rational 4875 In order to provide flexible behavior to constrained devices, while 4876 still allowing more powerful devices to use their full capabilities, 4877 the SUIT manifest encodes the required behavior of a Recipient 4878 device. Behavior is encoded as a specialized byte code, contained in 4879 a CBOR list. This promotes a flat encoding, which simplifies the 4880 parser. The information encoded by this byte code closely matches 4881 the operations that a device will perform, which promotes ease of 4882 processing. The core operations used by most update and trusted 4883 invocation operations are represented in the byte code. The byte 4884 code can be extended by registering new operations. 4886 The specialized byte code approach gives benefits equivalent to those 4887 provided by a scripting language or conventional byte code, with two 4888 substantial differences. First, the language is extremely high 4889 level, consisting of only the operations that a device may perform 4890 during update and trusted invocation of a firmware image. Second, 4891 the language specifies linear behavior, without reverse branches. 4892 Conditional processing is supported, and parallel and out-of-order 4893 processing may be performed by sufficiently capable devices. 4895 By structuring the data in this way, the manifest processor becomes a 4896 very simple engine that uses a pull parser to interpret the manifest. 4897 This pull parser invokes a series of command handlers that evaluate a 4898 Condition or execute a Directive. Most data is structured in a 4899 highly regular pattern, which simplifies the parser. 4901 The results of this allow a Recipient to implement a very small 4902 parser for constrained applications. If needed, such a parser also 4903 allows the Recipient to perform complex updates with reduced 4904 overhead. Conditional execution of commands allows a simple device 4905 to perform important decisions at validation-time. 4907 Dependency handling is vastly simplified as well. Dependencies 4908 function like subroutines of the language. When a manifest has a 4909 dependency, it can invoke that dependency's commands and modify their 4910 behavior by setting parameters. Because some parameters come with 4911 security implications, the dependencies also have a mechanism to 4912 reject modifications to parameters on a fine-grained level. 4914 Developing a robust permissions system works in this model too. The 4915 Recipient can use a simple ACL that is a table of Identities and 4916 Component Identifier permissions to ensure that operations on 4917 components fail unless they are permitted by the ACL. This table can 4918 be further refined with individual parameters and commands. 4920 Capability reporting is similarly simplified. A Recipient can report 4921 the Commands, Parameters, Algorithms, and Component Identifiers that 4922 it supports. This is sufficiently precise for a manifest author to 4923 create a manifest that the Recipient can accept. 4925 The simplicity of design in the Recipient due to all of these 4926 benefits allows even a highly constrained platform to use advanced 4927 update capabilities. 4929 C.1. C.1 Design Rationale: Envelope 4931 The Envelope is used instead of a COSE structure for several reasons: 4933 1. This enables the use of Severable Elements (Section 8.8) 4935 2. This enables modular processing of manifests, particularly with 4936 large signatures. 4938 3. This enables multiple authentication schemes. 4940 4. This allows integrity verification by a dependent to be 4941 unaffected by adding or removing authentication structures. 4943 Modular processing is important because it allows a Manifest 4944 Processor to iterate forward over an Envelope, processing Delegation 4945 Chains and Authentication Blocks, retaining only intermediate values, 4946 without any need to seek forward and backwards in a stream until it 4947 gets to the Manifest itself. This allows the use of large, Post- 4948 Quantum signatures without requiring retention of the signature 4949 itself, or seeking forward and back. 4951 Four authentication objects are supported by the Envelope: 4953 - COSE_Sign_Tagged 4955 - COSE_Sign1_Tagged 4957 - COSE_Mac_Tagged 4959 - COSE_Mac0_Tagged 4961 The SUIT Envelope allows an Update Authority or intermediary to mix 4962 and match any number of different authentication blocks it wants 4963 without any concern for modifying the integrity of another 4964 authentication block. This also allows the addition or removal of an 4965 authentication blocks without changing the integrity check of the 4966 Manifest, which is important for dependency handling. See 4967 Section 6.2 4969 C.2. C.2 Byte String Wrappers 4971 Byte string wrappers are used in several places in the suit manifest. 4972 The primary reason for wrappers it to limit the parser extent when 4973 invoked at different times, with a possible loss of context. 4975 The elements of the suit envelope are wrapped both to set the extents 4976 used by the parser and to simplify integrity checks by clearly 4977 defining the length of each element. 4979 The common block is re-parsed in order to find components identifiers 4980 from their indices, to find dependency prefixes and digests from 4981 their identifiers, and to find the common sequence. The common 4982 sequence is wrapped so that it matches other sequences, simplifying 4983 the code path. 4985 A severed SUIT command sequence will appear in the envelope, so it 4986 must be wrapped as with all envelope elements. For consistency, 4987 command sequences are also wrapped in the manifest. This also allows 4988 the parser to discern the difference between a command sequence and a 4989 SUIT_Digest. 4991 Parameters that are structured types (arrays and maps) are also 4992 wrapped in a bstr. This is so that parser extents can be set 4993 correctly using only a reference to the beginning of the parameter. 4994 This enables a parser to store a simple list of references to 4995 parameters that can be retrieved when needed. 4997 Appendix D. D. Implementation Conformance Matrix 4999 This section summarizes the functionality a minimal manifest 5000 processor implementation needs to offer to claim conformance to this 5001 specification, in the absence of an application profile standard 5002 specifying otherwise. 5004 The subsequent table shows the conditions. 5006 +-------------------+------------------+----------------+ 5007 | Name | Reference | Implementation | 5008 +-------------------+------------------+----------------+ 5009 | Vendor Identifier | Section 8.7.5.2 | REQUIRED | 5010 | | | | 5011 | Class Identifier | Section 8.7.5.2 | REQUIRED | 5012 | | | | 5013 | Device Identifier | Section 8.7.5.2 | OPTIONAL | 5014 | | | | 5015 | Image Match | Section 8.7.6.2 | REQUIRED | 5016 | | | | 5017 | Image Not Match | Section 8.7.6.3 | OPTIONAL | 5018 | | | | 5019 | Use Before | Section 8.7.6.4 | OPTIONAL | 5020 | | | | 5021 | Component Offset | Section 8.7.6.5 | OPTIONAL | 5022 | | | | 5023 | Abort | Section 8.7.6.9 | OPTIONAL | 5024 | | | | 5025 | Minimum Battery | Section 8.7.6.6 | OPTIONAL | 5026 | | | | 5027 | Update Authorized | Section 8.7.6.7 | OPTIONAL | 5028 | | | | 5029 | Version | Section 8.7.6.8 | OPTIONAL | 5030 | | | | 5031 | Custom Condition | Section 8.7.6.10 | OPTIONAL | 5032 +-------------------+------------------+----------------+ 5034 The subsequent table shows the directives. 5036 +-------------------+----------------+------------------------------+ 5037 | Name | Reference | Implementation | 5038 +-------------------+----------------+------------------------------+ 5039 | Set Component | Section 8.7.7. | REQUIRED if more than one | 5040 | Index | 1 | component | 5041 | | | | 5042 | Set Dependency | Section 8.7.7. | REQUIRED if dependencies | 5043 | Index | 2 | used | 5044 | | | | 5045 | Try Each | Section 8.7.7. | OPTIONAL | 5046 | | 3 | | 5047 | | | | 5048 | Process | Section 8.7.7. | OPTIONAL | 5049 | Dependency | 4 | | 5050 | | | | 5051 | Set Parameters | Section 8.7.7. | OPTIONAL | 5052 | | 5 | | 5053 | | | | 5054 | Override | Section 8.7.7. | REQUIRED | 5055 | Parameters | 6 | | 5056 | | | | 5057 | Fetch | Section 8.7.7. | REQUIRED for Updater | 5058 | | 7 | | 5059 | | | | 5060 | Copy | Section 8.7.7. | OPTIONAL | 5061 | | 9 | | 5062 | | | | 5063 | Run | Section 8.7.7. | REQUIRED for Bootloader | 5064 | | 10 | | 5065 | | | | 5066 | Wait For Event | Section 8.7.7. | OPTIONAL | 5067 | | 11 | | 5068 | | | | 5069 | Run Sequence | Section 8.7.7. | OPTIONAL | 5070 | | 12 | | 5071 | | | | 5072 | Swap | Section 8.7.7. | OPTIONAL | 5073 | | 13 | | 5074 | | | | 5075 | Fetch URI List | Section 8.7.7. | OPTIONAL | 5076 | | 8 | | 5077 | | | | 5078 | Garbage Collect | Section 8.7.8 | OPTIONAL | 5079 +-------------------+----------------+------------------------------+ 5081 The subsequent table shows the parameters. 5083 +------------------+------------------+----------------------+ 5084 | Name | Reference | Implementation | 5085 +------------------+------------------+----------------------+ 5086 | Vendor ID | Section 8.7.5.3 | REQUIRED | 5087 | | | | 5088 | Class ID | Section 8.7.5.4 | REQUIRED | 5089 | | | | 5090 | Image Digest | Section 8.7.5.6 | REQUIRED | 5091 | | | | 5092 | Image Size | Section 8.7.5.7 | REQUIRED | 5093 | | | | 5094 | Use Before | Section 8.7.5.8 | RECOMMENDED | 5095 | | | | 5096 | Component Offset | Section 8.7.5.9 | OPTIONAL | 5097 | | | | 5098 | Encryption Info | Section 8.7.5.10 | RECOMMENDED | 5099 | | | | 5100 | Compression Info | Section 8.7.5.11 | RECOMMENDED | 5101 | | | | 5102 | Unpack Info | Section 8.7.5.12 | RECOMMENDED | 5103 | | | | 5104 | URI | Section 8.7.5.13 | REQUIRED for Updater | 5105 | | | | 5106 | Source Component | Section 8.7.5.14 | OPTIONAL | 5107 | | | | 5108 | Run Args | Section 8.7.5.15 | OPTIONAL | 5109 | | | | 5110 | Device ID | Section 8.7.5.5 | OPTIONAL | 5111 | | | | 5112 | Minimum Battery | Section 8.7.5.16 | OPTIONAL | 5113 | | | | 5114 | Update Priority | Section 8.7.5.17 | OPTIONAL | 5115 | | | | 5116 | Version Match | Section 8.7.5.18 | OPTIONAL | 5117 | | | | 5118 | Wait Info | Section 8.7.5.19 | OPTIONAL | 5119 | | | | 5120 | URI List | Section 8.7.5.20 | OPTIONAL | 5121 | | | | 5122 | Strict Order | Section 8.7.5.22 | OPTIONAL | 5123 | | | | 5124 | Soft Failure | Section 8.7.5.23 | OPTIONAL | 5125 | | | | 5126 | Custom | Section 8.7.5.24 | OPTIONAL | 5127 +------------------+------------------+----------------------+ 5129 Authors' Addresses 5131 Brendan Moran 5132 Arm Limited 5134 EMail: Brendan.Moran@arm.com 5136 Hannes Tschofenig 5137 Arm Limited 5139 EMail: hannes.tschofenig@arm.com 5141 Henk Birkholz 5142 Fraunhofer SIT 5144 EMail: henk.birkholz@sit.fraunhofer.de 5146 Koen Zandberg 5147 Inria 5149 EMail: koen.zandberg@inria.fr