idnits 2.17.1 draft-ietf-suit-manifest-05.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 11 instances 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 seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (May 27, 2020) is 1429 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '1' on line 2736 -- Looks like a reference, but probably isn't: '2' on line 2738 -- Looks like a reference, but probably isn't: '3' on line 2740 == Missing Reference: '-1' is mentioned on line 1849, but not defined == Missing Reference: '-2' is mentioned on line 1851, but not defined == Missing Reference: '-3' is mentioned on line 1855, but not defined -- Looks like a reference, but probably isn't: '4' on line 1855 ** Obsolete normative reference: RFC 8152 (Obsoleted by RFC 9052, RFC 9053) == Outdated reference: A later version (-16) exists of draft-ietf-suit-architecture-09 == Outdated reference: A later version (-13) exists of draft-ietf-suit-information-model-05 == Outdated reference: A later version (-19) exists of draft-ietf-teep-architecture-08 == Outdated reference: A later version (-06) exists of draft-kucherawy-rfc8478bis-05 Summary: 1 error (**), 0 flaws (~~), 10 warnings (==), 5 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: November 28, 2020 H. Birkholz 6 Fraunhofer SIT 7 K. Zandberg 8 Inria 9 May 27, 2020 11 A Concise Binary Object Representation (CBOR)-based Serialization Format 12 for the Software Updates for Internet of Things (SUIT) Manifest 13 draft-ietf-suit-manifest-05 15 Abstract 17 This specification describes the format of a manifest. A manifest is 18 a bundle of metadata about the firmware for an IoT device, where to 19 find the firmware, the devices to which it applies, and cryptographic 20 information protecting the manifest. Firmware updates and secure 21 boot both tend to use sequences of common operations, so the manifest 22 encodes those sequences of operations, rather than declaring the 23 metadata. The manifest also serves as a building block for secure 24 boot. 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at https://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on November 28, 2020. 43 Copyright Notice 45 Copyright (c) 2020 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (https://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 This document may contain material from IETF Documents or IETF 59 Contributions published or made publicly available before November 60 10, 2008. The person(s) controlling the copyright in some of this 61 material may not have granted the IETF Trust the right to allow 62 modifications of such material outside the IETF Standards Process. 63 Without obtaining an adequate license from the person(s) controlling 64 the copyright in such materials, this document may not be modified 65 outside the IETF Standards Process, and derivative works of it may 66 not be created outside the IETF Standards Process, except to format 67 it for publication as an RFC or to translate it into languages other 68 than English. 70 Table of Contents 72 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 73 2. Conventions and Terminology . . . . . . . . . . . . . . . . . 6 74 3. How to use this Document . . . . . . . . . . . . . . . . . . 8 75 4. Background . . . . . . . . . . . . . . . . . . . . . . . . . 8 76 4.1. IoT Firmware Update Constraints . . . . . . . . . . . . . 8 77 4.2. Update Workflow Model . . . . . . . . . . . . . . . . . . 9 78 5. Severed Fields . . . . . . . . . . . . . . . . . . . . . . . 10 79 6. Interpreter Behavior . . . . . . . . . . . . . . . . . . . . 11 80 6.1. Interpreter Setup . . . . . . . . . . . . . . . . . . . . 11 81 6.2. Required Checks . . . . . . . . . . . . . . . . . . . . . 12 82 6.3. Interpreter Fundamental Properties . . . . . . . . . . . 13 83 6.4. Abstract Machine Description . . . . . . . . . . . . . . 13 84 6.5. Serialized Processing Interpreter . . . . . . . . . . . . 15 85 6.6. Parallel Processing Interpreter . . . . . . . . . . . . . 15 86 6.7. Processing Dependencies . . . . . . . . . . . . . . . . . 16 87 7. Creating Manifests . . . . . . . . . . . . . . . . . . . . . 16 88 7.1. Compatibility Check Template . . . . . . . . . . . . . . 17 89 7.2. Secure Boot Template . . . . . . . . . . . . . . . . . . 17 90 7.3. Firmware Download Template . . . . . . . . . . . . . . . 18 91 7.4. Load from External Storage Template . . . . . . . . . . . 18 92 7.5. Load & Decompress from External Storage Template . . . . 19 93 7.6. Dependency Template . . . . . . . . . . . . . . . . . . . 19 94 8. Envelope . . . . . . . . . . . . . . . . . . . . . . . . . . 19 95 8.1. Authenticated Manifests . . . . . . . . . . . . . . . . . 20 96 8.2. Encrypted Manifests . . . . . . . . . . . . . . . . . . . 21 97 8.3. Delegation Info . . . . . . . . . . . . . . . . . . . . . 21 98 8.4. Severable Fields . . . . . . . . . . . . . . . . . . . . 21 99 8.5. Human-Readable Text . . . . . . . . . . . . . . . . . . . 21 100 8.6. COSWID . . . . . . . . . . . . . . . . . . . . . . . . . 21 101 8.7. Encoding Considerations . . . . . . . . . . . . . . . . . 21 102 8.8. SUIT_Envelope CDDL . . . . . . . . . . . . . . . . . . . 22 103 9. Manifest . . . . . . . . . . . . . . . . . . . . . . . . . . 23 104 9.1. suit-manifest-version . . . . . . . . . . . . . . . . . . 24 105 9.2. suit-manifest-sequence-number . . . . . . . . . . . . . . 24 106 9.3. suit-common . . . . . . . . . . . . . . . . . . . . . . . 24 107 9.4. suit-reference-uri . . . . . . . . . . . . . . . . . . . 25 108 9.5. SUIT_Command_Sequence . . . . . . . . . . . . . . . . . . 25 109 9.6. suit-text . . . . . . . . . . . . . . . . . . . . . . . . 26 110 9.7. suit-coswid . . . . . . . . . . . . . . . . . . . . . . . 26 111 9.8. SUIT_Manifest CDDL . . . . . . . . . . . . . . . . . . . 26 112 9.9. Dependencies . . . . . . . . . . . . . . . . . . . . . . 27 113 9.10. SUIT_Component_Reference . . . . . . . . . . . . . . . . 28 114 9.11. Parameters . . . . . . . . . . . . . . . . . . . . . . . 28 115 9.11.1. suit-parameter-vendor-identifier . . . . . . . . . . 30 116 9.11.2. suit-parameter-class-identifier . . . . . . . . . . 30 117 9.11.3. suit-parameter-image-digest . . . . . . . . . . . . 30 118 9.11.4. suit-parameter-image-size . . . . . . . . . . . . . 30 119 9.11.5. suit-parameter-use-before . . . . . . . . . . . . . 30 120 9.11.6. suit-parameter-component-offset . . . . . . . . . . 31 121 9.11.7. suit-parameter-encryption-info . . . . . . . . . . . 31 122 9.11.8. suit-parameter-compression-info . . . . . . . . . . 31 123 9.11.9. suit-parameter-unpack-info . . . . . . . . . . . . . 31 124 9.11.10. suit-parameter-uri . . . . . . . . . . . . . . . . . 31 125 9.11.11. suit-parameter-source-component . . . . . . . . . . 31 126 9.11.12. suit-parameter-run-args . . . . . . . . . . . . . . 31 127 9.11.13. suit-parameter-device-identifier . . . . . . . . . . 32 128 9.11.14. suit-parameter-minimum-battery . . . . . . . . . . . 32 129 9.11.15. suit-parameter-update-priority . . . . . . . . . . . 32 130 9.11.16. suit-parameter-version . . . . . . . . . . . . . . . 32 131 9.11.17. suit-parameter-wait-info . . . . . . . . . . . . . . 32 132 9.11.18. suit-parameter-uri-list . . . . . . . . . . . . . . 32 133 9.11.19. suit-parameter-strict-order . . . . . . . . . . . . 32 134 9.11.20. suit-parameter-soft-failure . . . . . . . . . . . . 32 135 9.11.21. suit-parameter-custom . . . . . . . . . . . . . . . 33 136 9.11.22. SUIT_Parameters CDDL . . . . . . . . . . . . . . . . 33 137 9.12. SUIT_Command_Sequence . . . . . . . . . . . . . . . . . . 34 138 9.12.1. SUIT_Condition . . . . . . . . . . . . . . . . . . . 35 139 9.12.2. SUIT_Directive . . . . . . . . . . . . . . . . . . . 41 140 9.12.3. suit-directive-set-component-index . . . . . . . . . 43 141 9.12.4. suit-directive-set-dependency-index . . . . . . . . 43 142 9.12.5. suit-directive-abort . . . . . . . . . . . . . . . . 43 143 9.12.6. suit-directive-try-each . . . . . . . . . . . . . . 44 144 9.12.7. suit-directive-process-dependency . . . . . . . . . 44 145 9.12.8. suit-directive-set-parameters . . . . . . . . . . . 45 146 9.12.9. suit-directive-override-parameters . . . . . . . . . 45 147 9.12.10. suit-directive-fetch . . . . . . . . . . . . . . . . 45 148 9.12.11. suit-directive-copy . . . . . . . . . . . . . . . . 46 149 9.12.12. suit-directive-run . . . . . . . . . . . . . . . . . 47 150 9.12.13. suit-directive-wait . . . . . . . . . . . . . . . . 47 151 9.12.14. suit-directive-run-sequence . . . . . . . . . . . . 48 152 9.12.15. suit-directive-swap . . . . . . . . . . . . . . . . 49 153 9.13. SUIT_Text_Map . . . . . . . . . . . . . . . . . . . . . . 51 154 10. Access Control Lists . . . . . . . . . . . . . . . . . . . . 52 155 11. SUIT Digest Container . . . . . . . . . . . . . . . . . . . . 52 156 12. Creating Conditional Sequences . . . . . . . . . . . . . . . 53 157 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 55 158 13.1. SUIT Directives . . . . . . . . . . . . . . . . . . . . 55 159 13.2. SUIT Conditions . . . . . . . . . . . . . . . . . . . . 56 160 13.3. SUIT Parameters . . . . . . . . . . . . . . . . . . . . 57 161 13.4. SUIT Text Values . . . . . . . . . . . . . . . . . . . . 59 162 13.5. SUIT Algorithm Identifiers . . . . . . . . . . . . . . . 59 163 14. Security Considerations . . . . . . . . . . . . . . . . . . . 59 164 15. Mailing List Information . . . . . . . . . . . . . . . . . . 59 165 16. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 60 166 17. References . . . . . . . . . . . . . . . . . . . . . . . . . 60 167 17.1. Normative References . . . . . . . . . . . . . . . . . . 60 168 17.2. Informative References . . . . . . . . . . . . . . . . . 61 169 17.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 62 170 A. Full CDDL . . . . . . . . . . . . . . . . . . . . . . . . . . 63 171 B. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 172 B.1. Example 0: Secure Boot . . . . . . . . . . . . . . . . . 71 173 B.2. Example 1: Simultaneous Download and Installation of 174 Payload . . . . . . . . . . . . . . . . . . . . . . . . . 73 175 B.3. Example 2: Simultaneous Download, Installation, and 176 Secure Boot . . . . . . . . . . . . . . . . . . . . . . . 76 177 B.4. Example 3: Load from External Storage . . . . . . . . . . 78 178 B.5. Example 4: Load and Decompress from External Storage . . 81 179 B.6. Example 5: Compatibility Test, Download, Installation, 180 and Secure Boot . . . . . . . . . . . . . . . . . . . . . 83 181 B.7. Example 6: Two Images . . . . . . . . . . . . . . . . . . 86 182 C. Design Rational . . . . . . . . . . . . . . . . . . . . . . . 89 183 D. Implementation Confirmance Matrix . . . . . . . . . . . . . . 90 184 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 94 186 1. Introduction 188 A firmware update mechanism is an essential security feature for IoT 189 devices to deal with vulnerabilities. While the transport of 190 firmware images to the devices themselves is important there are 191 already various techniques available. Equally important is the 192 inclusion of metadata about the conveyed firmware image (in the form 193 of a manifest) and the use of a security wrapper to provide end-to- 194 end security protection to detect modifications and (optionally) to 195 make reverse engineering more difficult. End-to-end security allows 196 the author, who builds the firmware image, to be sure that no other 197 party (including potential adversaries) can install firmware updates 198 on IoT devices without adequate privileges. For confidentiality 199 protected firmware images it is additionally required to encrypt the 200 firmware image. Starting security protection at the author is a risk 201 mitigation technique so firmware images and manifests can be stored 202 on untrusted repositories; it also reduces the scope of a compromise 203 of any repository or intermediate system to be no worse than a denial 204 of service. 206 A manifest is a bundle of metadata about the firmware for an IoT 207 device, where to find the firmware, the devices to which it applies, 208 and cryptographic information protecting the manifest. 210 This specification defines the SUIT manifest format and it is 211 intended to meet several goals: 213 - Meet the requirements defined in 214 [I-D.ietf-suit-information-model]. 216 - Simple to parse on a constrained node 218 - Simple to process on a constrained node 220 - Compact encoding 222 - Comprehensible by an intermediate system 224 - Expressive enough to enable advanced use cases on advanced nodes 226 - Extensible 228 The SUIT manifest can be used for a variety of purposes throughout 229 its lifecycle, such as: 231 - the Firmware Author to reason about releasing a firmware. 233 - the Network Operator to reason about compatibility of a firmware. 235 - the Device Operator to reason about the impact of a firmware. 237 - the Device Operator to manage distribution of firmware to devices. 239 - the Plant Manager to reason about timing and acceptance of 240 firmware updates. 242 - the device to reason about the authority & authenticity of a 243 firmware prior to installation. 245 - the device to reason about the applicability of a firmware. 247 - the device to reason about the installation of a firmware. 249 - the device to reason about the authenticity & encoding of a 250 firmware at boot. 252 Each of these uses happens at a different stage of the manifest 253 lifecycle, so each has different requirements. 255 It is assumed that the reader is familiar with the high-level 256 firmware update architecture [I-D.ietf-suit-architecture] and the 257 threats, requirements, and user stories in 258 [I-D.ietf-suit-information-model]. 260 A core concept of the SUIT manifest specification are commands. 261 Commands are either conditions or directives used to define the 262 required behavior. Conceptually, a sequence of commands is like a 263 script but the used language is tailored to software updates and 264 secure boot. 266 The available commands support simple steps, such as copying a 267 firmware image from one place to another, checking that a firmware 268 image is correct, verifying that the specified firmware is the 269 correct firmware for the device, or unpacking a firmware. By using 270 these steps in different orders and changing the parameters they use, 271 a broad range of use cases can be supported. The SUIT manifest uses 272 this observation to heavily optimize metadata for consumption by 273 constrained devices. 275 While the SUIT manifest is informed by and optimized for firmware 276 update and secure boot use cases, there is nothing in the 277 [I-D.ietf-suit-information-model] that restricts its use to only 278 those use cases. Other use cases include the management of trusted 279 applications in a Trusted Execution Environment (TEE), see 280 [I-D.ietf-teep-architecture]. 282 2. Conventions and Terminology 284 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 285 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 286 "OPTIONAL" in this document are to be interpreted as described in 287 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 288 capitals, as shown here. 290 The following terminology is used throughout this document: 292 - SUIT: Software Update for the Internet of Things, the IETF working 293 group for this standard. 295 - Payload: A piece of information to be delivered. Typically 296 Firmware for the purposes of SUIT. 298 - Resource: A piece of information that is used to construct a 299 payload. 301 - Manifest: A manifest is a bundle of metadata about the firmware 302 for an IoT device, where to find the firmware, the devices to 303 which it applies, and cryptographic information protecting the 304 manifest. 306 - Envelope: A container with the manifest, an authentication 307 wrapper, authorization information, and severed fields. 309 - Update: One or more manifests that describe one or more payloads. 311 - Update Authority: The owner of a cryptographic key used to sign 312 updates, trusted by Recipients. 314 - Recipient: The system, typically an IoT device, that receives a 315 manifest. 317 - Command: A Condition or a Directive. 319 - Condition: A test for a property of the Recipient or its 320 components. 322 - Directive: An action for the Recipient to perform. 324 - Trusted Execution: A process by which a system ensures that only 325 trusted code is executed, for example secure boot. 327 - A/B images: Dividing a device's storage into two or more bootable 328 images, at different offsets, such that the active image can write 329 to the inactive image(s). 331 3. How to use this Document 333 This specification covers four aspects of firmware update: 335 - Section 4 describes the device constraints, use cases, and design 336 principles that informed the structure of the manifest. 338 - Section 6 describes what actions a manifest processor should take. 340 - Section 7 describes the process of creating a manifest. 342 - Section 9 specifies the content of the manifest and the envelope. 344 To implement an updatable device, see Section 6 and Section 9. To 345 implement a tool that generates updates, see Section 7 and Section 9. 347 The IANA consideration section, see Section 13, provides instructions 348 to IANA to create several registries. This section also provides the 349 CBOR labels for the structures defined in this document. 351 The complete CDDL description is provided in Appendix A, examples are 352 given in Appendix B and a design rational is offered in Appendix C. 353 Finally, Appendix D gives a summarize of the mandatory-to-implement 354 features of this specification. 356 4. Background 358 Distributing firmware updates to diverse devices with diverse trust 359 anchors in a coordinated system presents unique challenges. Devices 360 have a broad set of constraints, requiring different metadata to make 361 appropriate decisions. There may be many actors in production IoT 362 systems, each of whom has some authority. Distributing firmware in 363 such a multi-party environment presents additional challenges. Each 364 party requires a different subset of data. Some data may not be 365 accessible to all parties. Multiple signatures may be required from 366 parties with different authorities. This topic is covered in more 367 depth in [I-D.ietf-suit-architecture]. The security aspects are 368 described in [I-D.ietf-suit-information-model]. 370 4.1. IoT Firmware Update Constraints 372 The various constraints of IoT devices and the range of use cases 373 that need to be supported create a broad set of urequirements. For 374 example, devices with: 376 - limited processing power and storage may require a simple 377 representation of metadata. 379 - bandwidth constraints may require firmware compression or partial 380 update support. 382 - bootloader complexity constraints may require simple selection 383 between two bootable images. 385 - small internal storage may require external storage support. 387 - multiple microcontrollers may require coordinated update of all 388 applications. 390 - large storage and complex functionality may require parallel 391 update of many software components. 393 - extra information may need to be conveyed in the manifest in the 394 earlier stages of the device lifecycle before those data items are 395 stripped when the manifest is delivery to a constrained device. 397 Supporting the requirements introduced by the constraints on IoT 398 devices requires the flexibility to represent a diverse set of 399 possible metadata, but also requires that the encoding is kept 400 simple. 402 4.2. Update Workflow Model 404 There are several fundamental assumptions that inform the model of 405 the firmware update workflow: 407 - Compatibility must be checked before any other operation is 408 performed. 410 - All dependency manifests should be present before any payload is 411 fetched. 413 - In some applications, payloads must be fetched and validated prior 414 to installation. 416 There are several fundamental assumptions that inform the model of 417 the secure boot workflow: 419 - Compatibility must be checked before any other operation is 420 performed. 422 - All dependencies and payloads must be validated prior to loading. 424 - All loaded images must be validated prior to execution. 426 Based on these assumptions, the manifest is structured to work with a 427 pull parser, where each section of the manifest is used in sequence. 428 The expected workflow for a device installing an update can be broken 429 down into five steps: 431 1. Verify the signature of the manifest. 433 2. Verify the applicability of the manifest. 435 3. Resolve dependencies. 437 4. Fetch payload(s). 439 5. Install payload(s). 441 When installation is complete, similar information can be used for 442 validating and running images in a further three steps: 444 1. Verify image(s). 446 2. Load image(s). 448 3. Run image(s). 450 If verification and running is implemented in a bootloader, then the 451 bootloader must also verify the signature of the manifest and the 452 applicability of the manifest in order to implement secure boot 453 workflows. The bootloader may add its own authentication, e.g. a 454 MAC, to the manifest in order to prevent further verifications. 456 When multiple manifests are used for an update, each manifest's steps 457 occur in a lockstep fashion; all manifests have dependency resolution 458 performed before any manifest performs a payload fetch, etc. 460 5. Severed Fields 462 Because the manifest can be used by different actors at different 463 times, some parts of the manifest can be removed without affecting 464 later stages of the lifecycle. This is called "Severing." Severing 465 of information is achieved by separating that information from the 466 signed container so that removing it does not affect the signature. 467 This means that ensuring authenticity of severable parts of the 468 manifest is a requirement for the signed portion of the manifest. 469 Severing some parts makes it possible to discard parts of the 470 manifest that are no longer necessary. This is important because it 471 allows the storage used by the manifest to be greatly reduced. For 472 example, no text size limits are needed if text is removed from the 473 manifest prior to delivery to a constrained device. 475 Elements are made severable by removing them from the manifest, 476 encoding them in a bstr, and placing a SUIT_Digest of the bstr in the 477 manifest so that they can still be authenticated. The SUIT_Digest 478 typically consumes 4 bytes more than the size of the raw digest, 479 therefore elements smaller than (Digest Bits)/8 + 4 should never be 480 severable. Elements larger than (Digest Bits)/8 + 4 may be 481 severable, while elements that are much larger than (Digest Bits)/8 + 482 4 should be severable. 484 Because of this, all command sequences in the manifest are encoded in 485 a bstr so that there is a single code path needed for all command 486 sequences. 488 6. Interpreter Behavior 490 This section describes the behavior of the manifest interpreter and 491 focuses primarily on interpreting commands in the manifest. However, 492 there are several other important behaviors of the interpreter: 493 encoding version detection, rollback protection, and authenticity 494 verification are chief among these. 496 6.1. Interpreter Setup 498 Prior to executing any command sequence, the interpreter or its host 499 application MUST inspect the manifest version field and fail when it 500 encounters an unsupported encoding version. Next, the interpreter or 501 its host application MUST extract the manifest sequence number and 502 perform a rollback check using this sequence number. The exact logic 503 of rollback protection may vary by application, but it has the 504 following properties: 506 - Whenever the interpreter can choose between several manifests, it 507 MUST select the latest valid, authentic manifest. 509 - If the latest valid, authentic manifest fails, it MAY select the 510 next latest valid, authentic manifest. 512 Here, valid means that a manifest has a supported encoding version 513 and it has not been excluded for other reasons. Reasons for 514 excluding typically involve first executing the manifest and may 515 include: 517 - Test failed (e.g. Vendor ID/Class ID). 519 - Unsupported command encountered. 521 - Unsupported parameter encountered. 523 - Unsupported component ID encountered. 525 - Payload not available. 527 - Dependency not available. 529 - Application crashed when executed. 531 - Watchdog timeout occurred. 533 - Dependency or Payload verification failed. 535 These failure reasons MAY be combined with retry mechanisms prior to 536 marking a manifest as invalid. 538 Following these initial tests, the interpreter clears all parameter 539 storage. This ensures that the interpreter begins without any leaked 540 data. 542 6.2. Required Checks 544 The RECOMMENDED process is to verify the signature of the manifest 545 prior to parsing/executing any section of the manifest. This guards 546 the parser against arbitrary input by unauthenticated third parties, 547 but it costs extra energy when a device receives an incompatible 548 manifest. 550 A device MAY choose to parse and execute only the SUIT_Common section 551 of the manifest prior to signature verification, if - it expects to 552 receive many incompatible manifests, and - it has power budget that 553 makes signature verification undesirable. 555 The guidelines in Creating Manifests (Section 7) require that the 556 common section contains the applicability checks, so this section is 557 sufficient for applicability verification. The manifest parser MUST 558 NOT execute any command with side-effects outside the parser (for 559 example, Run, Copy, Swap, or Fetch commands) prior to authentication 560 and any such command MUST result in an error. 562 Once a valid, authentic manifest has been selected, the interpreter 563 MUST examine the component list and verify that its maximum number of 564 components is not exceeded and that each listed component ID is 565 supported. 567 For each listed component, the interpreter MUST provide storage for 568 the supported parameters. If the interpreter does not have 569 sufficient temporary storage to process the parameters for all 570 components, it MAY process components serially for each command 571 sequence. See Section 6.5 for more details. 573 The interpreter SHOULD check that the common section contains at 574 least one vendor ID check and at least one class ID check. 576 If the manifest contains more than one component, each command 577 sequence MUST begin with a Set Current Component command. 579 If a dependency is specified, then the interpreter MUST perform the 580 following checks: 582 1. At the beginning of each section in the dependent: all previous 583 sections of each dependency have been executed. 585 2. At the end of each section in the dependent: The corresponding 586 section in each dependency has been executed. 588 If the interpreter does not support dependencies and a manifest 589 specifies a dependency, then the interpreter MUST reject the 590 manifest. 592 6.3. Interpreter Fundamental Properties 594 The interpreter has a small set of design goals: 596 1. Executing an update MUST either result in an error, or a 597 verifiably correct system state. 599 2. Executing a secure boot MUST either result in an error, or a 600 booted system. 602 3. Executing the same manifest on multiple devices MUST result in 603 the same system state. 605 NOTE: when using A/B images, the manifest functions as two (or more) 606 logical manifests, each of which applies to a system in a particular 607 starting state. With that provision, design goal 3 holds. 609 6.4. Abstract Machine Description 611 The heart of the manifest is the list of commands, which are 612 processed by an interpreter. This interpreter can be modeled as a 613 simple abstract machine. This machine consists of several data 614 storage locations that are modified by commands. 616 There are two types of commands, namely those that modify state 617 (directives) and those that perform tests (conditions). Parameters 618 are used as the inputs to commands. Some directives offer control 619 flow operations. Directives target a specific component. A 620 component is a unit of code or data that can be targeted by an 621 update. Components are identified by a Component Index, i.e. arrays 622 of binary strings. 624 The following table describes the behavior of each command. "params" 625 represents the parameters for the current component or dependency. 627 +--------------------+----------------------------------------------+ 628 | Command Name | Semantic of the Operation | 629 +--------------------+----------------------------------------------+ 630 | Check Vendor | binary-match(component, params[vendor-id]) | 631 | Identifier | | 632 | | | 633 | Check Class | binary-match(component, params[class-id]) | 634 | Identifier | | 635 | | | 636 | Verify Image | binary-match(digest(component), | 637 | | params[digest]) | 638 | | | 639 | Set Component | component := components[arg] | 640 | Index | | 641 | | | 642 | Override | params[k] := v for k,v in arg | 643 | Parameters | | 644 | | | 645 | Set Dependency | dependency := dependencies[arg] | 646 | Index | | 647 | | | 648 | Set Parameters | params[k] := v if not k in params for k,v in | 649 | | arg | 650 | | | 651 | Process Dependency | exec(dependency[common]); exec(dependency | 652 | | [current-segment]) | 653 | | | 654 | Run | run(component) | 655 | | | 656 | Fetch | store(component, fetch(params[uri])) | 657 | | | 658 | Use Before | assert(now() < arg) | 659 | | | 660 | Check Component | assert(offsetof(component) == arg) | 661 | Offset | | 662 | | | 663 | Check Device | binary-match(component, params[device-id]) | 664 | Identifier | | 665 | | | 666 | Check Image Not | not binary-match(digest(component), | 667 | Match | params[digest]) | 668 | | | 669 | Check Minimum | assert(battery >= arg) | 670 | Battery | | 671 | | | 672 | Check Update | assert(isAuthorized()) | 673 | Authorized | | 674 | | | 675 | Check Version | assert(version_check(component, arg)) | 676 | | | 677 | Abort | assert(0) | 678 | | | 679 | Try Each | break if exec(seq) is not error for seq in | 680 | | arg | 681 | | | 682 | Copy | store(component, params[src-component]) | 683 | | | 684 | Swap | swap(component, params[src-component]) | 685 | | | 686 | Wait For Event | until event(arg), wait | 687 | | | 688 | Run Sequence | exec(arg) | 689 | | | 690 | Run with Arguments | run(component, arg) | 691 +--------------------+----------------------------------------------+ 693 6.5. Serialized Processing Interpreter 695 Because each manifest has a list of components and a list of 696 components defined by its dependencies, it is possible for the 697 manifest processor to handle one component at a time, traversing the 698 manifest tree once for each listed component. In this mode, the 699 interpreter ignores any commands executed while the component index 700 is not the current component. This reduces the overall volatile 701 storage required to process the update so that the only limit on 702 number of components is the size of the manifest. However, this 703 approach requires additional processing power. 705 6.6. Parallel Processing Interpreter 707 Advanced devices may make use of the Strict Order parameter and 708 enable parallel processing of some segments, or it may reorder some 709 segments. To perform parallel processing, once the Strict Order 710 parameter is set to False, the device may fork a process for each 711 command until the Strict Order parameter is returned to True or the 712 command sequence ends. Then, it joins all forked processes before 713 continuing processing of commands. To perform out-of-order 714 processing, a similar approach is used, except the device consumes 715 all commands after the Strict Order parameter is set to False, then 716 it sorts these commands into its preferred order, invokes them all, 717 then continues processing. 719 Under each of these scenarios the parallel processing must halt: 721 - Set Parameters. 723 - Override Parameters. 725 - Set Strict Order = True. 727 - Set Dependency Index. 729 - Set Component Index. 731 To perform more useful parallel operations, sequences of commands may 732 be collected in a suit-directive-run-sequence. Then, each of these 733 sequences may be run in parallel. Each sequence defaults to Strict 734 Order = True. To isolate each sequence from each other sequence, 735 each sequence must declare a single target component. Set Component 736 Index is not permitted inside this sequence. 738 6.7. Processing Dependencies 740 As described in Section 6.2, each manifest must invoke each of its 741 dependencies sections from the corresponding section of the 742 dependent. Any changes made to parameters by the dependency persist 743 in the dependent. 745 When a Process Dependency command is encountered, the interpreter 746 loads the dependency identified by the Current Dependency Index. The 747 interpreter first executes the common-sequence section of the 748 identified dependency, then it executes the section of the dependency 749 that corresponds to the currently executing section of the dependent. 751 The interpreter also performs the checks described in Section 6.2 to 752 ensure that the dependent is processing the dependency correctly. 754 7. Creating Manifests 756 Manifests are created using tools for constructing COSE structures, 757 calculating cryptographic values and compiling desired system state 758 into a sequence of operations required to achieve that state. The 759 process of constructing COSE structures and the calculation of 760 cryptographic values is covered in [RFC8152]. 762 Compiling desired system state into a sequence of operations can be 763 accomplished in many ways. Several templates are provided below to 764 cover common use-cases. These templates can be combined to produce 765 more complex behavior. 767 NOTE: On systems that support only a single component, Set Current 768 Component has no effect and can be omitted. 770 NOTE: A digest should always be set using Override Parameters, since 771 this prevents a less-privileged dependent from replacing the digest. 773 7.1. Compatibility Check Template 775 The compatibility check ensures that devices only install compatible 776 images. In this template all information is contained in the common 777 block and the following sequence of operations are used: 779 - Set Component Index directive (see Section 9.12.3) 781 - Set Parameters directive (see Section 9.12.8) for Vendor ID and 782 Class ID (see Section 9.11) 784 - Check Vendor Identifier condition (see Section 9.12.1.1) 786 - Check Class Identifier condication (see Section 9.12.1.1) 788 7.2. Secure Boot Template 790 This template performs a secure boot operation. 792 The following operations are placed into the common block: 794 - Set Component Index directive (see Section 9.12.3) 796 - Override Parameters directive (see Section 9.12.9) for Image 797 Digest and Image Size (see Section 9.11) 799 Then, the run block contains the following operations: 801 - Set Component Index directive (see Section 9.12.3) 803 - Check Image Match condition (see Section 9.12.1.2) 805 - Run directive (see Section 9.12.14) 807 According to Section 6.4, the Run directive applies to the component 808 referenced by the current Component Index. Hence, the Set Component 809 Index directive has to be used to target a specific component. 811 7.3. Firmware Download Template 813 This template triggers the download of firmware. 815 The following operations are placed into the common block: 817 - Set Component Index directive (see Section 9.12.3) 819 - Override Parameters directive (see Section 9.12.9) for Image 820 Digest and Image Size (see Section 9.11) 822 Then, the install block contains the following operations: 824 - Set Component Index directive (see Section 9.12.3) 826 - Set Parameters directive (see Section 9.12.8) for URI (see 827 Section 9.11) 829 - Fetch directive (see Section 9.12.10) 831 The Fetch directive needs the URI parameter to be set to determine 832 where the image is retrieved from. Additionally, the destination of 833 where the component shall be stored has to be configured. The URI is 834 configured via the Set Parameters directive while the destination is 835 configured via the Set Component Index directive. 837 7.4. Load from External Storage Template 839 This directive loads an firmware image from external storage. 841 The following operations are placed into the load block: 843 - Set Component Index directive (see Section 9.12.3) 845 - Set Parameters directive (see Section 9.12.8) for Component Index 846 (see Section 9.11) 848 - Copy directive (see Section 9.12.11) 850 As outlined in Section 6.4, the Copy directive needs a source and a 851 destination to be configured. The source is configured via Component 852 Index (with the Set Parameters directive) and the destination is 853 configured via the Set Component Index directive. 855 7.5. Load & Decompress from External Storage Template 857 The following operations are placed into the load block: 859 - Set Component Index directive (see Section 9.12.3) 861 - Set Parameters directive (see Section 9.12.8) for Component Index 862 and Compression Info (see Section 9.11) 864 - Copy directive (see Section 9.12.11) 866 This example is similar to the previous case but additionally 867 performs decompression. Hence, the only difference is in setting the 868 Compression Info parameter. 870 7.6. Dependency Template 872 The following operations are placed into the dependency resolution 873 block: 875 - Set Dependency Index directive (see Section 9.12.4) 877 - Set Parameters directive (see Section 9.12.8) for URI (see 878 Section 9.11) 880 - Fetch directive (see Section 9.12.10) 882 - Check Image Match condition (see Section 9.12.1.2) 884 - Process Dependency directive (see Section 9.12.7) 886 Then, the validate block contains the following operations: 888 - Set Dependency Index directive (see Section 9.12.4) 890 - Check Image Match condition (see Section 9.12.1.2) 892 - Process Dependency directive (see Section 9.12.7) 894 NOTE: Any changes made to parameters in a dependency persist in the 895 dependent. 897 8. Envelope 899 The diagram below shows high-level structure of the SUIT manifest 900 embedded in the envelope, the top-level structure. 902 +------------------------+ 903 | Envelope | 904 +------------------------+ 905 | Delegation Info | 906 | Authentication Wrapper | 907 | Plaintext or -+---------> +----------------------------+ 908 | Encrypted Manifest-+ | | Manifest | 909 | Severable Fields | +----------------------------+ 910 | Human-Readable Text | | Version | 911 | COSWID | | Sequence Number | 912 +------------------------+ +----- Common Structure | 913 | +--- Commands | 914 | | | Digest of Enveloped Fields | 915 +-----------------------+ | | | Reference to Full Manifest | 916 | Common Structure | <-+ | +----------------------------+ 917 +-----------------------+ | 918 | Dependencies | +->+-----------------------+ 919 | Components IDs | +->| Commands | 920 | Component References | | +-----------------------+ 921 | Common Commands ------------+ | List of ( pairs of ( | 922 +-----------------------+ | * command code | 923 | * argument | 924 | )) | 925 +----------------------- 927 8.1. Authenticated Manifests 929 The suit-authentication-wrapper contains a list of 1 or more 930 cryptographic authentication wrappers for the core part of the 931 manifest. These are implemented as COSE_Mac_Tagged or 932 COSE_Sign_Tagged blocks. Each of these blocks contains a SUIT_Digest 933 of the manifest. This enables modular processing of the manifest. 934 The COSE_Mac_Tagged and COSE_Sign_Tagged blocks are described in RFC 935 8152 [RFC8152]. The suit-authentication-wrapper MUST come before any 936 element in the SUIT_Envelope, except for the OPTIONAL suit- 937 delegation, regardless of canonical encoding of CBOR. All validators 938 MUST reject any SUIT_Envelope that begins with any element other than 939 a suit-authentication-wrapper or suit-delegation. 941 A SUIT_Envelope that has not had authentication information added 942 MUST still contain the suit-authentication-wrapper element, but the 943 content MUST be nil. 945 For manifests that are only authenticated the envelope MUST contain 946 the plaintext manifest in SUIT_Manifest structure. 948 8.2. Encrypted Manifests 950 For encrypted manifest both a SUIT_Encryption_Wrapper and the 951 ciphertext of a manifest is included in the envelope. 953 When the envelope contains the SUIT_Encryption_Wrapper, the suit- 954 authentication-wrapper MUST authenticate the plaintext of suit- 955 manifest-encrypted. This ensures that the manifest can be stored 956 decrypted and that a recipient MAY convert the suit-manifest- 957 encrypted element to a suit-manifest element. 959 The SUIT_Manifest structure describes the payload(s) to be installed 960 and any dependencies on other manifests. 962 The suit-manifest-encryption-info structure contains information 963 required to decrypt a ciphertext manifest and the suit-manifest- 964 encrypted structure contains the ciphertext. 966 8.3. Delegation Info 968 The suit-delegation field may carry one or multiple CBOR Web Tokens 969 (CWTs). They can be used to perform enhanced authorization 970 decisions. 972 8.4. Severable Fields 974 Each of suit-dependency-resolution, suit-payload-fetch, and suit- 975 payload-installation contain the severable contents of the 976 identically named portions of the manifest, described in Section 9. 978 8.5. Human-Readable Text 980 suit-text contains all the human-readable information that describes 981 any and all parts of the manifest, its payload(s) and its 982 resource(s). 984 8.6. COSWID 986 suit-coswid contains a Concise Software Identifier. This may be 987 discarded by the Recipient if not needed. 989 8.7. Encoding Considerations 991 The map indices in the envelope encoding are reset to 1 for each map 992 within the structure. This is to keep the indices as small as 993 possible. The goal is to keep the index objects to single bytes 994 (CBOR positive integers 1-23). 996 Wherever enumerations are used, they are started at 1. This allows 997 detection of several common software errors that are caused by 998 uninitialised variables. Positive numbers in enumerations are 999 reserved for IANA registration. Negative numbers are used to 1000 identify application-specific implementations. 1002 All elements of the envelope must be wrapped in a bstr to minimize 1003 the complexity of the code that evaluates the cryptographic integrity 1004 of the element and to ensure correct serialization for integrity and 1005 authenticity checks. 1007 8.8. SUIT_Envelope CDDL 1009 CDDL names are hyphenated and CDDL structures follow the convention 1010 adopted in COSE [RFC8152]: SUIT_Structure_Name. 1012 The CDDL that describes the envelope is below. 1014 SUIT_Envelope = { 1015 suit-delegation => bstr .cbor SUIT_Delegation 1016 suit-authentication-wrapper 1017 => bstr .cbor SUIT_Authentication_Wrapper / nil, 1018 $$SUIT_Manifest_Wrapped, 1019 * $$SUIT_Severed_Fields, 1020 } 1022 SUIT_Delegation = [ + [ + CWT ] ] 1024 SUIT_Authentication_Wrapper = [ + bstr .cbor SUIT_Authentication_Block ] 1026 SUIT_Authentication_Block /= COSE_Mac_Tagged 1027 SUIT_Authentication_Block /= COSE_Sign_Tagged 1028 SUIT_Authentication_Block /= COSE_Mac0_Tagged 1029 SUIT_Authentication_Block /= COSE_Sign1_Tagged 1031 $$SUIT_Manifest_Wrapped //= (suit-manifest => bstr .cbor SUIT_Manifest) 1032 $$SUIT_Manifest_Wrapped //= ( 1033 suit-manifest-encryption-info => bstr .cbor SUIT_Encryption_Wrapper, 1034 suit-manifest-encrypted => bstr 1035 ) 1037 SUIT_Encryption_Wrapper = COSE_Encrypt_Tagged / COSE_Encrypt0_Tagged 1039 $$SUIT_Severed_Fields //= ( suit-dependency-resolution => 1040 bstr .cbor SUIT_Command_Sequence) 1041 $$SUIT_Severed_Fields //= (suit-payload-fetch => 1042 bstr .cbor SUIT_Command_Sequence) 1043 $$SUIT_Severed_Fields //= (suit-install => 1044 bstr .cbor SUIT_Command_Sequence) 1045 $$SUIT_Severed_Fields //= (suit-text => 1046 bstr .cbor SUIT_Text_Map) 1047 $$SUIT_Severed_Fields //= (suit-coswid => 1048 bstr .cbor concise-software-identity) 1050 9. Manifest 1052 The manifest contains: 1054 - a version number (see Section 9.1) 1056 - a sequence number (see Section 9.2) 1058 - a common structure with information that is shared between command 1059 sequences (see Section 9.3) 1061 - a list of commands that the Recipient should perform (see 1062 Section 9.5) 1064 - a reference to the full manifest (see Section 9.4) 1066 - a digest of human-readable text describing the manifest found in 1067 the SUIT_Envelope (see Section 9.6) 1069 - a digest of the Concise Software Identifier found in the 1070 SUIT_Envelope (see Section 9.7) 1072 Several fields in the Manifest can be either a CBOR structure or a 1073 SUIT_Digest. In each of these cases, the SUIT_Digest provides for a 1074 severable field. Severable fields are RECOMMENDED to implement. In 1075 particular, the human-readable text SHOULD be severable, since most 1076 useful text elements occupy more space than a SUIT_Digest, but are 1077 not needed by the Recipient. Because SUIT_Digest is a CBOR Array and 1078 each severable element is a CBOR bstr, it is straight-forward for a 1079 Recipient to determine whether an element has been severed. The key 1080 used for a severable element is the same in the SUIT_Manifest and in 1081 the SUIT_Envelope so that a Recipient can easily identify the correct 1082 data in the envelope. 1084 9.1. suit-manifest-version 1086 The suit-manifest-version indicates the version of serialization used 1087 to encode the manifest. Version 1 is the version described in this 1088 document. suit-manifest-version is REQUIRED to implement. 1090 9.2. suit-manifest-sequence-number 1092 The suit-manifest-sequence-number is a monotonically increasing anti- 1093 rollback counter. It also helps devices to determine which in a set 1094 of manifests is the "root" manifest in a given update. Each manifest 1095 MUST have a sequence number higher than each of its dependencies. 1096 Each Recipient MUST reject any manifest that has a sequence number 1097 lower than its current sequence number. It MAY be convenient to use 1098 a UTC timestamp in seconds as the sequence number. suit-manifest- 1099 sequence-number is REQUIRED to implement. 1101 9.3. suit-common 1103 suit-common encodes all the information that is shared between each 1104 of the command sequences, including: suit-dependencies, suit- 1105 components, suit-dependency-components, and suit-common-sequence. 1106 suit-common is REQUIRED to implement. 1108 suit-dependencies is a list of SUIT_Dependency blocks that specify 1109 manifests that must be present before the current manifest can be 1110 processed. suit-dependencies is OPTIONAL to implement. 1112 In order to distinguish between components that are affected by the 1113 current manifest and components that are affected by a dependency, 1114 they are kept in separate lists. Components affected by the current 1115 manifest only list the component identifier. Components affected by 1116 a dependency include the component identifier and the index of the 1117 dependency that defines the component. 1119 suit-components is a list of SUIT_Component blocks that specify the 1120 component identifiers that will be affected by the content of the 1121 current manifest. suit-components is OPTIONAL to implement, but at 1122 least one manifest MUST contain a suit-components block. 1124 suit-dependency-components is a list of SUIT_Component_Reference 1125 blocks that specify component identifiers that will be affected by 1126 the content of a dependency of the current manifest. suit-dependency- 1127 components is OPTIONAL to implement. 1129 suit-common-sequence is a SUIT_Command_Sequence to execute prior to 1130 executing any other command sequence. Typical actions in suit- 1131 common-sequence include setting expected device identity and image 1132 digests when they are conditional (see Section 12 for more 1133 information on conditional sequences). suit-common-sequence is 1134 RECOMMENDED to implement. 1136 9.4. suit-reference-uri 1138 suit-reference-uri is a text string that encodes a URI where a full 1139 version of this manifest can be found. This is convenient for 1140 allowing management systems to show the severed elements of a 1141 manifest when this URI is reported by a device after installation. 1143 9.5. SUIT_Command_Sequence 1145 suit-dependency-resolution is a SUIT_Command_Sequence to execute in 1146 order to perform dependency resolution. Typical actions include 1147 configuring URIs of dependency manifests, fetching dependency 1148 manifests, and validating dependency manifests' contents. suit- 1149 dependency-resolution is REQUIRED to implement and to use when suit- 1150 dependencies is present. 1152 suit-payload-fetch is a SUIT_Command_Sequence to execute in order to 1153 obtain a payload. Some manifests may include these actions in the 1154 suit-install section instead if they operate in a streaming 1155 installation mode. This is particularly relevant for constrained 1156 devices without any temporary storage for staging the update. suit- 1157 payload-fetch is OPTIONAL to implement. 1159 suit-install is a SUIT_Command_Sequence to execute in order to 1160 install a payload. Typical actions include verifying a payload 1161 stored in temporary storage, copying a staged payload from temporary 1162 storage, and unpacking a payload. suit-install is OPTIONAL to 1163 implement. 1165 suit-validate is a SUIT_Command_Sequence to execute in order to 1166 validate that the result of applying the update is correct. Typical 1167 actions involve image validation and manifest validation. suit- 1168 validate is REQUIRED to implement. If the manifest contains 1169 dependencies, one process-dependency invocation per dependency or one 1170 process-dependency invocation targeting all dependencies SHOULD be 1171 present in validate. 1173 suit-load is a SUIT_Command_Sequence to execute in order to prepare a 1174 payload for execution. Typical actions include copying an image from 1175 permanent storage into RAM, optionally including actions such as 1176 decryption or decompression. suit-load is OPTIONAL to implement. 1178 suit-run is a SUIT_Command_Sequence to execute in order to run an 1179 image. suit-run typically contains a single instruction: either the 1180 "run" directive for the bootable manifest or the "process 1181 dependencies" directive for any dependents of the bootable manifest. 1182 suit-run is OPTIONAL to implement. Only one manifest in an update 1183 may contain the "run" directive. 1185 9.6. suit-text 1187 suit-text is a digest that uniquely identifies the content of the 1188 Text that is packaged in the SUIT_Envelope. suit-text is OPTIONAL to 1189 implement. 1191 9.7. suit-coswid 1193 suit-coswid is a digest that uniquely identifies the content of the 1194 concise-software-identifier that is packaged in the SUIT_Envelope. 1195 suit-coswid is OPTIONAL to implement. 1197 9.8. SUIT_Manifest CDDL 1199 The following CDDL fragment defines the manifest. 1201 SUIT_Manifest = { 1202 suit-manifest-version => 1, 1203 suit-manifest-sequence-number => uint, 1204 suit-common => bstr .cbor SUIT_Common, 1205 ? suit-reference-uri => #6.32(tstr), 1206 * $$SUIT_Severable_Command_Sequences, 1207 * $$SUIT_Command_Sequences, 1208 * $$SUIT_Protected_Elements, 1209 } 1211 $$SUIT_Severable_Command_Sequences //= (suit-dependency-resolution => 1212 SUIT_Severable_Command_Segment) 1213 $$SUIT_Severable_Command_Segments //= (suit-payload-fetch => 1214 SUIT_Severable_Command_Sequence) 1215 $$SUIT_Severable_Command_Segments //= (suit-install => 1216 SUIT_Severable_Command_Sequence) 1218 SUIT_Severable_Command_Sequence = 1219 SUIT_Digest / bstr .cbor SUIT_Command_Sequence 1221 $$SUIT_Command_Sequences //= ( suit-validate => 1222 bstr .cbor SUIT_Command_Sequence ) 1223 $$SUIT_Command_Sequences //= ( suit-load => 1224 bstr .cbor SUIT_Command_Sequence ) 1225 $$SUIT_Command_Sequences //= ( suit-run => 1226 bstr .cbor SUIT_Command_Sequence ) 1228 $$SUIT_Protected_Elements //= ( suit-text => SUIT_Digest ) 1229 $$SUIT_Protected_Elements //= ( suit-coswid => SUIT_Digest ) 1231 SUIT_Common = { 1232 ? suit-dependencies => bstr .cbor SUIT_Dependencies, 1233 ? suit-components => bstr .cbor SUIT_Components, 1234 ? suit-dependency-components 1235 => bstr .cbor SUIT_Component_References, 1236 ? suit-common-sequence => bstr .cbor SUIT_Command_Sequence, 1237 } 1239 9.9. Dependencies 1241 SUIT_Dependency specifies a manifest that describes a dependency of 1242 the current manifest. 1244 The following CDDL describes the SUIT_Dependency structure. 1246 SUIT_Dependency = { 1247 suit-dependency-digest => SUIT_Digest, 1248 ? suit-dependency-prefix => SUIT_Component_Identifier, 1249 } 1251 The suit-dependency-digest specifies the dependency manifest uniquely 1252 by identifying a particular Manifest structure. The digest is 1253 calculated over the Manifest structure instead of the COSE 1254 Sig_structure or Mac_structure. This means that a digest may need to 1255 be calculated more than once, however this is necessary to ensure 1256 that removing a signature from a manifest does not break dependencies 1257 due to missing signature elements. This is also necessary to support 1258 the trusted intermediary use case, where an intermediary re-signs the 1259 Manifest, removing the original signature, potentially with a 1260 different algorithm, or trading COSE_Sign for COSE_Mac. 1262 The suit-dependency-prefix element contains a 1263 SUIT_Component_Identifier. This specifies the scope at which the 1264 dependency operates. This allows the dependency to be forwarded on 1265 to a component that is capable of parsing its own manifests. It also 1266 allows one manifest to be deployed to multiple dependent devices 1267 without those devices needing consistent component hierarchy. This 1268 element is OPTIONAL. 1270 9.10. SUIT_Component_Reference 1272 The SUIT_Component_Reference describes an image that is defined by 1273 another manifest. This is useful for overriding the behavior of 1274 another manifest, for example by directing the recipient to look at a 1275 different URI for the image or by changing the expected format, such 1276 as when a gateway performs decryption on behalf of a constrained 1277 device. The following CDDL describes the SUIT_Component_Reference. 1279 SUIT_Component_Reference = { 1280 suit-component-identifier => SUIT_Component_Identifier, 1281 suit-component-dependency-index => uint 1282 } 1284 9.11. Parameters 1286 Many conditions and directives require additional information. That 1287 information is contained within parameters that can be set in a 1288 consistent way. This allows reduction of manifest size and 1289 replacement of parameters from one manifest to the next. 1291 The defined manifest parameters are described below. 1293 +----------------+----------------------------------+---------------+ 1294 | Name | CDDL Structure | Reference | 1295 +----------------+----------------------------------+---------------+ 1296 | Vendor ID | suit-parameter-vendor-identifier | Section | 1297 | | | 9.11.1 | 1298 | | | | 1299 | Class ID | suit-parameter-class-identifier | Section | 1300 | | | 9.11.2 | 1301 | | | | 1302 | Image Digest | suit-parameter-image-digest | Section | 1303 | | | 9.11.3 | 1304 | | | | 1305 | Image Size | suit-parameter-image-size | Section | 1306 | | | 9.11.4 | 1307 | | | | 1308 | Use Before | suit-parameter-use-before | Section | 1309 | | | 9.11.5 | 1310 | | | | 1311 | Component | suit-parameter-component-offset | Section | 1312 | Offset | | 9.11.6 | 1313 | | | | 1314 | Encryption | suit-parameter-encryption-info | Section | 1315 | Info | | 9.11.7 | 1316 | | | | 1317 | Compression | suit-parameter-compression-info | Section | 1318 | Info | | 9.11.8 | 1319 | | | | 1320 | Unpack Info | suit-parameter-unpack-info | Section | 1321 | | | 9.11.9 | 1322 | | | | 1323 | URI | suit-parameter-uri | Section | 1324 | | | 9.11.10 | 1325 | | | | 1326 | Source | suit-parameter-source-component | Section | 1327 | Component | | 9.11.11 | 1328 | | | | 1329 | Run Args | suit-parameter-run-args | Section | 1330 | | | 9.11.12 | 1331 | | | | 1332 | Device ID | suit-parameter-device-identifier | Section | 1333 | | | 9.11.13 | 1334 | | | | 1335 | Minimum | suit-parameter-minimum-battery | Section | 1336 | Battery | | 9.11.14 | 1337 | | | | 1338 | Update | suit-parameter-update-priority | Section | 1339 | Priority | | 9.11.15 | 1340 | | | | 1341 | Version | suit-parameter-version | Section | 1342 | | | 9.11.16 | 1343 | | | | 1344 | Wait Info | suit-parameter-wait-info | Section | 1345 | | | 9.11.17 | 1346 | | | | 1347 | URI List | suit-parameter-uri-list | Section | 1348 | | | 9.11.18 | 1349 | | | | 1350 | Strict Order | suit-parameter-strict-order | Section | 1351 | | | 9.11.19 | 1352 | | | | 1353 | Soft Failure | suit-parameter-soft-failure | Section | 1354 | | | 9.11.20 | 1355 | | | | 1356 | Custom | suit-parameter-custom | Section | 1357 | | | 9.11.21 | 1358 +----------------+----------------------------------+---------------+ 1360 CBOR-encoded object parameters are still wrapped in a bstr. This is 1361 because it allows a parser that is aggregating parameters to 1362 reference the object with a single pointer and traverse it without 1363 understanding the contents. This is important for modularization and 1364 division of responsibility within a pull parser. The same 1365 consideration does not apply to Directives because those elements are 1366 invoked with their arguments immediately 1368 9.11.1. suit-parameter-vendor-identifier 1370 A RFC 4122 UUID representing the vendor of the device or component. 1372 9.11.2. suit-parameter-class-identifier 1374 A RFC 4122 UUID representing the class of the device or component 1376 9.11.3. suit-parameter-image-digest 1378 A fingerprint computed over the image itself encoded in the 1379 SUIT_Digest structure. 1381 9.11.4. suit-parameter-image-size 1383 The size of the firmware image in bytes. 1385 9.11.5. suit-parameter-use-before 1387 An expire date for the use of the manifest encoded as a POSIX 1388 timestamp. 1390 9.11.6. suit-parameter-component-offset 1392 Offset of the component 1394 9.11.7. suit-parameter-encryption-info 1396 Encryption Info defines the mechanism that Fetch or Copy should use 1397 to decrypt the data they transfer. SUIT_Parameter_Encryption_Info is 1398 encoded as a COSE_Encrypt_Tagged or a COSE_Encrypt0_Tagged, wrapped 1399 in a bstr. 1401 9.11.8. suit-parameter-compression-info 1403 Compression Info defines any information that is required for a 1404 device to perform decompression operations. Typically, this includes 1405 the algorithm identifier. This document defines the use of ZLIB 1406 [RFC1950], Brotli [RFC7932], and ZSTD [I-D.kucherawy-rfc8478bis]. 1408 Additional compression formats can be registered through the IANA- 1409 maintained registry. 1411 9.11.9. suit-parameter-unpack-info 1413 SUIT_Unpack_Info defines the information required for a device to 1414 interpret a packed format. This document defines the use of the 1415 following binary encodings: Intel HEX [HEX], Motorola S-record 1416 [SREC], Executable and Linkable Format (ELF) [ELF], and Common Object 1417 File Format (COFF) [COFF]. 1419 Additional packing formats can be registered through the IANA- 1420 maintained registry. 1422 9.11.10. suit-parameter-uri 1424 A URI from which to fetch a resource 1426 9.11.11. suit-parameter-source-component 1428 A Component Index 1430 9.11.12. suit-parameter-run-args 1432 An encoded set of arguments for Run 1434 9.11.13. suit-parameter-device-identifier 1436 A RFC4122 UUID representing the device or component 1438 9.11.14. suit-parameter-minimum-battery 1440 A minimum battery level in mWh 1442 9.11.15. suit-parameter-update-priority 1444 The priority of the update 1446 9.11.16. suit-parameter-version 1448 TBD. 1450 9.11.17. suit-parameter-wait-info 1452 TBD. 1454 9.11.18. suit-parameter-uri-list 1456 TBD. 1458 9.11.19. suit-parameter-strict-order 1460 The Strict Order Parameter allows a manifest to govern when 1461 directives can be executed out-of-order. This allows for systems 1462 that have a sensitivity to order of updates to choose the order in 1463 which they are executed. It also allows for more advanced systems to 1464 parallelize their handling of updates. Strict Order defaults to 1465 True. It MAY be set to False when the order of operations does not 1466 matter. When arriving at the end of a command sequence, ALL commands 1467 MUST have completed, regardless of the state of 1468 SUIT_Parameter_Strict_Order. If SUIT_Parameter_Strict_Order is 1469 returned to True, ALL preceding commands MUST complete before the 1470 next command is executed. 1472 9.11.20. suit-parameter-soft-failure 1474 When executing a command sequence inside SUIT_Directive_Try_Each and 1475 a condition failure occurs, the manifest processor aborts the 1476 sequence. If Soft Failure is True, it returns Success. Otherwise, 1477 it returns the original condition failure. 1478 SUIT_Parameter_Soft_Failure is scoped to the enclosing 1479 SUIT_Command_Sequence. Its value is discarded when 1480 SUIT_Command_Sequence terminates. 1482 9.11.21. suit-parameter-custom 1484 TBD. 1486 9.11.22. SUIT_Parameters CDDL 1488 The following CDDL describes all SUIT_Parameters. 1490 SUIT_Parameters //= (suit-parameter-vendor-identifier => RFC4122_UUID) 1491 SUIT_Parameters //= (suit-parameter-class-identifier => RFC4122_UUID) 1492 SUIT_Parameters //= (suit-parameter-image-digest 1493 => bstr .cbor SUIT_Digest) 1494 SUIT_Parameters //= (suit-parameter-image-size => uint) 1495 SUIT_Parameters //= (suit-parameter-use-before => uint) 1496 SUIT_Parameters //= (suit-parameter-component-offset => uint) 1498 SUIT_Parameters //= (suit-parameter-encryption-info 1499 => bstr .cbor SUIT_Encryption_Info) 1500 SUIT_Parameters //= (suit-parameter-compression-info 1501 => bstr .cbor SUIT_Compression_Info) 1502 SUIT_Parameters //= (suit-parameter-unpack-info 1503 => bstr .cbor SUIT_Unpack_Info) 1505 SUIT_Parameters //= (suit-parameter-uri => tstr) 1506 SUIT_Parameters //= (suit-parameter-source-component => uint) 1507 SUIT_Parameters //= (suit-parameter-run-args => bstr) 1509 SUIT_Parameters //= (suit-parameter-device-identifier => RFC4122_UUID) 1510 SUIT_Parameters //= (suit-parameter-minimum-battery => uint) 1511 SUIT_Parameters //= (suit-parameter-update-priority => uint) 1512 SUIT_Parameters //= (suit-parameter-version => 1513 SUIT_Parameter_Version_Match) 1514 SUIT_Parameters //= (suit-parameter-wait-info => 1515 bstr .cbor SUIT_Wait_Events) 1517 SUIT_Parameters //= (suit-parameter-uri-list 1518 => bstr .cbor SUIT_Component_URI_List) 1519 SUIT_Parameters //= (suit-parameter-custom => int/bool/tstr/bstr) 1521 SUIT_Parameters //= (suit-parameter-strict-order => bool) 1522 SUIT_Parameters //= (suit-parameter-soft-failure => bool) 1524 RFC4122_UUID = bstr .size 16 1526 SUIT_Condition_Version_Comparison_Value = [+int] 1528 SUIT_Encryption_Info = COSE_Encrypt_Tagged/COSE_Encrypt0_Tagged 1529 SUIT_Compression_Info = { 1530 suit-compression-algorithm => SUIT_Compression_Algorithms, 1531 ? suit-compression-parameters => bstr 1532 } 1534 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_zlib 1535 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_brotli 1536 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_zstd 1538 SUIT_Unpack_Info = { 1539 suit-unpack-algorithm => SUIT_Unpack_Algorithms, 1540 ? suit-unpack-parameters => bstr 1541 } 1543 SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Hex 1544 SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Elf 1545 SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Coff 1546 SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Srec 1548 9.12. SUIT_Command_Sequence 1550 A SUIT_Command_Sequence defines a series of actions that the 1551 Recipient MUST take to accomplish a particular goal. These goals are 1552 defined in the manifest and include: 1554 1. Dependency Resolution 1556 2. Payload Fetch 1558 3. Payload Installation 1560 4. Image Validation 1562 5. Image Loading 1564 6. Run or Boot 1566 Each of these follows exactly the same structure to ensure that the 1567 parser is as simple as possible. 1569 Lists of commands are constructed from two kinds of element: 1571 1. Conditions that MUST be true-any failure is treated as a failure 1572 of the update/load/boot 1574 2. Directives that MUST be executed. 1576 The lists of commands are logically structured into sequences of zero 1577 or more conditions followed by zero or more directives. The 1578 *logical* structure is described by the following CDDL: 1580 Command_Sequence = { 1581 conditions => [ * Condition], 1582 directives => [ * Directive] 1583 } 1585 This introduces significant complexity in the parser, however, so the 1586 structure is flattened to make parsing simpler: 1588 SUIT_Command_Sequence = [ + (SUIT_Condition/SUIT_Directive) ] 1590 Each condition is a command code identifier, followed by Nil. Each 1591 directive is composed of: 1593 1. A command code identifier 1595 2. An argument block or Nil 1597 Argument blocks are defined for each type of directive. 1599 Many conditions and directives apply to a given component, and these 1600 generally grouped together. Therefore, a special command to set the 1601 current component index is provided with a matching command to set 1602 the current dependency index. This index is a numeric index into the 1603 component ID tables defined at the beginning of the document. For 1604 the purpose of setting the index, the two component ID tables are 1605 considered to be concatenated together. 1607 To facilitate optional conditions, a special directive is provided. 1608 It runs several new lists of conditions/directives, one after 1609 another, that are contained as an argument to the directive. By 1610 default, it assumes that a failure of a condition should not indicate 1611 a failure of the update/boot, but a parameter is provided to override 1612 this behavior. 1614 9.12.1. SUIT_Condition 1616 Conditions are used to define mandatory properties of a system in 1617 order for an update to be applied. They can be pre-conditions or 1618 post-conditions of any directive or series of directives, depending 1619 on where they are placed in the list. Conditions never take 1620 arguments; conditions should test using parameters instead. 1621 Conditions include: 1623 +----------------+----------------------------------+---------------+ 1624 | Name | CDDL Structure | Reference | 1625 +----------------+----------------------------------+---------------+ 1626 | Vendor | suit-condition-vendor-identifier | Section | 1627 | Identifier | | 9.12.1.1 | 1628 | | | | 1629 | Class | suit-condition-class-identifier | Section | 1630 | Identifier | | 9.12.1.1 | 1631 | | | | 1632 | Device | suit-condition-device-identifier | Section | 1633 | Identifier | | 9.12.1.1 | 1634 | | | | 1635 | Image Match | suit-condition-image-match | Section | 1636 | | | 9.12.1.2 | 1637 | | | | 1638 | Image Not | suit-condition-image-not-match | Section | 1639 | Match | | 9.12.1.3 | 1640 | | | | 1641 | Use Before | suit-condition-use-before | Section | 1642 | | | 9.12.1.4 | 1643 | | | | 1644 | Component | suit-condition-component-offset | Section | 1645 | Offset | | 9.12.1.5 | 1646 | | | | 1647 | Minimum | suit-condition-minimum-battery | Section | 1648 | Battery | | 9.12.1.6 | 1649 | | | | 1650 | Update | suit-condition-update-authorized | Section | 1651 | Authorized | | 9.12.1.7 | 1652 | | | | 1653 | Version | suit-condition-version | Section | 1654 | | | 9.12.1.8 | 1655 | | | | 1656 | Custom | SUIT_Condition_Custom | Section | 1657 | Condition | | 9.12.1.9 | 1658 +----------------+----------------------------------+---------------+ 1660 Each condition MUST report a result code on completion. If a 1661 condition reports failure, then the current sequence of commands MUST 1662 terminate. If a condition requires additional information, this MUST 1663 be specified in one or more parameters before the condition is 1664 executed. If a Recipient attempts to process a condition that 1665 expects additional information and that information has not been set, 1666 it MUST report a failure. If a Recipient encounters an unknown 1667 condition, it MUST report a failure. 1669 Condition labels in the positive number range are reserved for IANA 1670 registration while those in the negative range are custom conditions 1671 reserved for proprietary use. 1673 Several conditions use identifiers to determine whether a manifest 1674 matches a given Recipient or not. These identifiers are defined to 1675 be RFC 4122 [RFC4122] UUIDs. These UUIDs are not human-readable and 1676 are therefore used for machine-based processing only. 1678 A device may match any number of UUIDs for vendor or class 1679 identifier. This may be relevant to physical or software modules. 1680 For example, a device that has an OS and one or more applications 1681 might list one Vendor ID for the OS and one or more additional Vendor 1682 IDs for the applications. This device might also have a Class ID 1683 that must be matched for the OS and one or more Class IDs for the 1684 applications. 1686 A more complete example: Imagine a device has the following physical 1687 components: 1. A host MCU 2. A WiFi module 1689 This same device has three software modules: 1. An operating system 1690 2. A WiFi module interface driver 3. An application 1692 Suppose that the WiFi module's firmware has a proprietary update 1693 mechanism and doesn't support manifest processing. This device can 1694 report four class IDs: 1696 1. hardware model/revision 1698 2. OS 1700 3. WiFi module model/revision 1702 4. Application 1704 This allows the OS, WiFi module, and application to be updated 1705 independently. To combat possible incompatibilities, the OS class ID 1706 can be changed each time the OS has a change to its API. 1708 This approach allows a vendor to target, for example, all devices 1709 with a particular WiFi module with an update, which is a very 1710 powerful mechanism, particularly when used for security updates. 1712 UUIDs MUST be created according to RFC 4122 [RFC4122]. UUIDs SHOULD 1713 use versions 3, 4, or 5, as described in RFC4122. Versions 1 and 2 1714 do not provide a tangible benefit over version 4 for this 1715 application. 1717 The RECOMMENDED method to create a vendor ID is: Vendor ID = 1718 UUID5(DNS_PREFIX, vendor domain name) 1720 The RECOMMENDED method to create a class ID is: Class ID = 1721 UUID5(Vendor ID, Class-Specific-Information) 1723 Class-specific information is composed of a variety of data, for 1724 example: 1726 - Model number. 1728 - Hardware revision. 1730 - Bootloader version (for immutable bootloaders). 1732 9.12.1.1. suit-condition-vendor-identifier, suit-condition-class- 1733 identifier, and suit-condition-device-identifier 1735 There are three identifier-based conditions: suit-condition-vendor- 1736 identifier, suit-condition-class-identifier, and suit-condition- 1737 device-identifier. Each of these conditions match a RFC 4122 1738 [RFC4122] UUID that MUST have already been set as a parameter. The 1739 installing device MUST match the specified UUID in order to consider 1740 the manifest valid. These identifiers MAY be scoped by component. 1742 The Recipient uses the ID parameter that has already been set using 1743 the Set Parameters directive. If no ID has been set, this condition 1744 fails. suit-condition-class-identifier and suit-condition-vendor- 1745 identifier are REQUIRED to implement. suit-condition-device- 1746 identifier is OPTIONAL to implement. 1748 9.12.1.2. suit-condition-image-match 1750 Verify that the current component matches the digest parameter for 1751 the current component. The digest is verified against the digest 1752 specified in the Component's parameters list. If no digest is 1753 specified, the condition fails. suit-condition-image-match is 1754 REQUIRED to implement. 1756 9.12.1.3. suit-condition-image-not-match 1758 Verify that the current component does not match the supplied digest. 1759 If no digest is specified, then the digest is compared against the 1760 digest specified in the Component's parameters list. If no digest is 1761 specified, the condition fails. suit-condition-image-not-match is 1762 OPTIONAL to implement. 1764 9.12.1.4. suit-condition-use-before 1766 Verify that the current time is BEFORE the specified time. suit- 1767 condition-use-before is used to specify the last time at which an 1768 update should be installed. The recipient evaluates the current time 1769 against the suit-parameter-use-before parameter, which must have 1770 already been set as a parameter, encoded as a POSIX timestamp, that 1771 is seconds after 1970-01-01 00:00:00. Timestamp conditions MUST be 1772 evaluated in 64 bits, regardless of encoded CBOR size. suit- 1773 condition-use-before is OPTIONAL to implement. 1775 9.12.1.5. suit-condition-component-offset 1777 TBD. 1779 9.12.1.6. suit-condition-minimum-battery 1781 suit-condition-minimum-battery provides a mechanism to test a 1782 device's battery level before installing an update. This condition 1783 is for use in primary-cell applications, where the battery is only 1784 ever discharged. For batteries that are charged, suit-directive-wait 1785 is more appropriate, since it defines a "wait" until the battery 1786 level is sufficient to install the update. suit-condition-minimum- 1787 battery is specified in mWh. suit-condition-minimum-battery is 1788 OPTIONAL to implement. 1790 9.12.1.7. suit-condition-update-authorized 1792 Request Authorization from the application and fail if not 1793 authorized. This can allow a user to decline an update. Argument is 1794 an integer priority level. Priorities are application defined. suit- 1795 condition-update-authorized is OPTIONAL to implement. 1797 9.12.1.8. suit-condition-version 1799 suit-condition-version allows comparing versions of firmware. 1800 Verifying image digests is preferred to version checks because 1801 digests are more precise. The image can be compared as: 1803 - Greater. 1805 - Greater or Equal. 1807 - Equal. 1809 - Lesser or Equal. 1811 - Lesser. 1813 Versions are encoded as a CBOR list of integers. Comparisons are 1814 done on each integer in sequence. Comparison stops after all 1815 integers in the list defined by the manifest have been consumed OR 1816 after a non-equal match has occurred. For example, if the manifest 1817 defines a comparison, "Equal [1]", then this will match all version 1818 sequences starting with 1. If a manifest defines both "Greater or 1819 Equal [1,0]" and "Lesser [1,10]", then it will match versions 1.0.x 1820 up to, but not including 1.10. 1822 The following CDDL describes SUIT_Condition_Version_Argument 1824 SUIT_Condition_Version_Argument = [ 1825 suit-condition-version-comparison-type: 1826 SUIT_Condition_Version_Comparison_Types, 1827 suit-condition-version-comparison-value: 1828 SUIT_Condition_Version_Comparison_Value 1829 ] 1831 SUIT_Condition_Version_Comparison_Types /= 1832 suit-condition-version-comparison-greater 1833 SUIT_Condition_Version_Comparison_Types /= 1834 suit-condition-version-comparison-greater-equal 1835 SUIT_Condition_Version_Comparison_Types /= 1836 suit-condition-version-comparison-equal 1837 SUIT_Condition_Version_Comparison_Types /= 1838 suit-condition-version-comparison-lesser-equal 1839 SUIT_Condition_Version_Comparison_Types /= 1840 suit-condition-version-comparison-lesser 1842 SUIT_Condition_Version_Comparison_Value = [+int] 1844 While the exact encoding of versions is application-defined, semantic 1845 versions map conveniently. For example, 1847 - 1.2.3 = [1,2,3]. 1849 - 1.2-rc3 = [1,2,-1,3]. 1851 - 1.2-beta = [1,2,-2]. 1853 - 1.2-alpha = [1,2,-3]. 1855 - 1.2-alpha4 = [1,2,-3,4]. 1857 suit-condition-version is OPTIONAL to implement. 1859 9.12.1.9. SUIT_Condition_Custom 1861 SUIT_Condition_Custom describes any proprietary, application specific 1862 condition. This is encoded as a negative integer, chosen by the 1863 firmware developer. If additional information must be provided to 1864 the condition, it should be encoded in a custom parameter (a nint) as 1865 described in Section 9.11. SUIT_Condition_Custom is OPTIONAL to 1866 implement. 1868 9.12.1.10. SUIT_Condition CDDL 1870 The following CDDL describes SUIT_Condition: 1872 SUIT_Condition //= (suit-condition-vendor-identifier, nil) 1873 SUIT_Condition //= (suit-condition-class-identifier, nil) 1874 SUIT_Condition //= (suit-condition-device-identifier, nil) 1875 SUIT_Condition //= (suit-condition-image-match, nil) 1876 SUIT_Condition //= (suit-condition-image-not-match, nil) 1877 SUIT_Condition //= (suit-condition-use-before, nil) 1878 SUIT_Condition //= (suit-condition-component-offset, nil) 1879 SUIT_Condition //= (suit-condition-minimum-battery, nil) 1880 SUIT_Condition //= (suit-condition-update-authorized, nil) 1881 SUIT_Condition //= (suit-condition-version, nil) 1882 SUIT_Condition //= (suit-condition-component-offset, nil) 1884 9.12.2. SUIT_Directive 1886 Directives are used to define the behavior of the recipient. 1887 Directives include: 1889 +---------------+-------------------------------------+-------------+ 1890 | Name | CDDL Structure | Reference | 1891 +---------------+-------------------------------------+-------------+ 1892 | Set Component | suit-directive-set-component-index | Section | 1893 | Index | | 9.12.3 | 1894 | | | | 1895 | Set | suit-directive-set-dependency-index | Section | 1896 | Dependency | | 9.12.4 | 1897 | Index | | | 1898 | | | | 1899 | Abort | suit-directive-abort | Section | 1900 | | | 9.12.5 | 1901 | | | | 1902 | Try Each | suit-directive-try-each | Section | 1903 | | | 9.12.6 | 1904 | | | | 1905 | Process | suit-directive-process-dependency | Section | 1906 | Dependency | | 9.12.7 | 1907 | | | | 1908 | Set | suit-directive-set-parameters | Section | 1909 | Parameters | | 9.12.8 | 1910 | | | | 1911 | Override | suit-directive-override-parameters | Section | 1912 | Parameters | | 9.12.9 | 1913 | | | | 1914 | Fetch | suit-directive-fetch | Section | 1915 | | | 9.12.10 | 1916 | | | | 1917 | Copy | suit-directive-copy | Section | 1918 | | | 9.12.11 | 1919 | | | | 1920 | Run | suit-directive-run | Section | 1921 | | | 9.12.12 | 1922 | | | | 1923 | Wait For | suit-directive-wait | Section | 1924 | Event | | 9.12.13 | 1925 | | | | 1926 | Run Sequence | suit-directive-run-sequence | Section | 1927 | | | 9.12.14 | 1928 | | | | 1929 | Swap | suit-directive-swap | Section | 1930 | | | 9.12.15 | 1931 +---------------+-------------------------------------+-------------+ 1933 When a Recipient executes a Directive, it MUST report a result code. 1934 If the Directive reports failure, then the current Command Sequence 1935 MUST terminate. 1937 9.12.3. suit-directive-set-component-index 1939 Set Component Index defines the component to which successive 1940 directives and conditions will apply. The supplied argument MUST be 1941 either a boolean or an unsigned integer index into the concatenation 1942 of suit-components and suit-dependency-components. If the following 1943 directives apply to ALL components, then the boolean value "True" is 1944 used instead of an index. True does not apply to dependency 1945 components. If the following directives apply to NO components, then 1946 the boolean value "False" is used. When suit-directive-set- 1947 dependency-index is used, suit-directive-set-component-index = False 1948 is implied. When suit-directive-set-component-index is used, suit- 1949 directive-set-dependency-index = False is implied. 1951 The following CDDL describes the argument to suit-directive-set- 1952 component-index. 1954 SUIT_Directive_Set_Component_Index_Argument = uint/bool 1956 9.12.4. suit-directive-set-dependency-index 1958 Set Dependency Index defines the manifest to which successive 1959 directives and conditions will apply. The supplied argument MUST be 1960 either a boolean or an unsigned integer index into the dependencies. 1961 If the following directives apply to ALL dependencies, then the 1962 boolean value "True" is used instead of an index. If the following 1963 directives apply to NO dependencies, then the boolean value "False" 1964 is used. When suit-directive-set-component-index is used, suit- 1965 directive-set-dependency-index = False is implied. When suit- 1966 directive-set-dependency-index is used, suit-directive-set-component- 1967 index = False is implied. 1969 Typical operations that require suit-directive-set-dependency-index 1970 include setting a source URI, invoking "Fetch," or invoking "Process 1971 Dependency" for an individual dependency. 1973 The following CDDL describes the argument to suit-directive-set- 1974 dependency-index. 1976 SUIT_Directive_Set_Manifest_Index_Argument = uint/bool 1978 9.12.5. suit-directive-abort 1980 Unconditionally fail. This operation is typically used in 1981 conjunction with suit-directive-try-each. 1983 9.12.6. suit-directive-try-each 1985 This command runs several SUIT_Command_Sequence, one after another, 1986 in a strict order. Use this command to implement a "try/catch-try/ 1987 catch" sequence. Manifest processors MAY implement this command. 1989 SUIT_Parameter_Soft_Failure is initialized to True at the beginning 1990 of each sequence. If one sequence aborts due to a condition failure, 1991 the next is started. If no sequence completes without condition 1992 failure, then suit-directive-try-each returns an error. If a 1993 particular application calls for all sequences to fail and still 1994 continue, then an empty sequence (nil) can be added to the Try Each 1995 Argument. 1997 The following CDDL describes the SUIT_Try_Each argument. 1999 SUIT_Directive_Try_Each_Argument = [ 2000 + bstr .cbor SUIT_Command_Sequence, 2001 nil / bstr .cbor SUIT_Command_Sequence 2002 ] 2004 9.12.7. suit-directive-process-dependency 2006 Execute the commands in the common section of the current dependency, 2007 followed by the commands in the equivalent section of the current 2008 dependency. For example, if the current section is "fetch payload," 2009 this will execute "common" in the current dependency, then "fetch 2010 payload" in the current dependency. Once this is complete, the 2011 command following suit-directive-process-dependency will be 2012 processed. 2014 If the current dependency is False, this directive has no effect. If 2015 the current dependency is True, then this directive applies to all 2016 dependencies. If the current section is "common," this directive 2017 MUST have no effect. 2019 When SUIT_Process_Dependency completes, it forwards the last status 2020 code that occurred in the dependency. 2022 The argument to suit-directive-process-dependency is defined in the 2023 following CDDL. 2025 SUIT_Directive_Process_Dependency_Argument = nil 2027 9.12.8. suit-directive-set-parameters 2029 suit-directive-set-parameters allows the manifest to configure 2030 behavior of future directives by changing parameters that are read by 2031 those directives. When dependencies are used, suit-directive-set- 2032 parameters also allows a manifest to modify the behavior of its 2033 dependencies. 2035 Available parameters are defined in Section 9.11. 2037 If a parameter is already set, suit-directive-set-parameters will 2038 skip setting the parameter to its argument. This provides the core 2039 of the override mechanism, allowing dependent manifests to change the 2040 behavior of a manifest. 2042 The argument to suit-directive-set-parameters is defined in the 2043 following CDDL. 2045 SUIT_Directive_Set_Parameters_Argument = {+ SUIT_Parameters} 2047 N.B.: A directive code is reserved for an optimization: a way to set 2048 a parameter to the contents of another parameter, optionally with 2049 another component ID. 2051 9.12.9. suit-directive-override-parameters 2053 suit-directive-override-parameters replaces any listed parameters 2054 that are already set with the values that are provided in its 2055 argument. This allows a manifest to prevent replacement of critical 2056 parameters. 2058 Available parameters are defined in Section 9.11. 2060 The argument to suit-directive-override-parameters is defined in the 2061 following CDDL. 2063 SUIT_Directive_Override_Parameters_Argument = {+ SUIT_Parameters} 2065 9.12.10. suit-directive-fetch 2067 suit-directive-fetch instructs the manifest processor to obtain one 2068 or more manifests or payloads, as specified by the manifest index and 2069 component index, respectively. 2071 suit-directive-fetch can target one or more manifests and one or more 2072 payloads. suit-directive-fetch retrieves each component and each 2073 manifest listed in component-index and manifest-index, respectively. 2074 If component-index or manifest-index is True, instead of an integer, 2075 then all current manifest components/manifests are fetched. The 2076 current manifest's dependent-components are not automatically 2077 fetched. In order to pre-fetch these, they MUST be specified in a 2078 component-index integer. 2080 suit-directive-fetch typically takes no arguments unless one is 2081 needed to modify fetch behavior. If an argument is needed, it must 2082 be wrapped in a bstr. 2084 suit-directive-fetch reads the URI or URI List parameter to find the 2085 source of the fetch it performs. 2087 The behavior of suit-directive-fetch can be modified by setting one 2088 or more of SUIT_Parameter_Encryption_Info, 2089 SUIT_Parameter_Compression_Info, SUIT_Parameter_Unpack_Info. These 2090 three parameters each activate and configure a processing step that 2091 can be applied to the data that is transferred during suit-directive- 2092 fetch. 2094 The argument to suit-directive-fetch is defined in the following 2095 CDDL. 2097 SUIT_Directive_Fetch_Argument = nil/bstr 2099 9.12.11. suit-directive-copy 2101 suit-directive-copy instructs the manifest processor to obtain one or 2102 more payloads, as specified by the component index. suit-directive- 2103 copy retrieves each component listed in component-index, 2104 respectively. If component-index is True, instead of an integer, 2105 then all current manifest components are copied. The current 2106 manifest's dependent-components are not automatically copied. In 2107 order to copy these, they MUST be specified in a component-index 2108 integer. 2110 The behavior of suit-directive-copy can be modified by setting one or 2111 more of SUIT_Parameter_Encryption_Info, 2112 SUIT_Parameter_Compression_Info, SUIT_Parameter_Unpack_Info. These 2113 three parameters each activate and configure a processing step that 2114 can be applied to the data that is transferred during suit-directive- 2115 copy. 2117 *N.B.* Fetch and Copy are very similar. Merging them into one 2118 command may be appropriate. 2120 suit-directive-copy reads its source from 2121 SUIT_Parameter_Source_Component. 2123 The argument to suit-directive-copy is defined in the following CDDL. 2125 SUIT_Directive_Copy_Argument = nil 2127 9.12.12. suit-directive-run 2129 suit-directive-run directs the manifest processor to transfer 2130 execution to the current Component Index. When this is invoked, the 2131 manifest processor MAY be unloaded and execution continues in the 2132 Component Index. Arguments provided to Run are forwarded to the 2133 executable code located in Component Index, in an application- 2134 specific way. For example, this could form the Linux Kernel Command 2135 Line if booting a Linux device. 2137 If the executable code at Component Index is constructed in such a 2138 way that it does not unload the manifest processor, then the manifest 2139 processor may resume execution after the executable completes. This 2140 allows the manifest processor to invoke suitable helpers and to 2141 verify them with image conditions. 2143 The argument to suit-directive-run is defined in the following CDDL. 2145 SUIT_Directive_Run_Argument = nil/bstr 2147 9.12.13. suit-directive-wait 2149 suit-directive-wait directs the manifest processor to pause until a 2150 specified event occurs. Some possible events include: 2152 1. Authorization 2154 2. External Power 2156 3. Network availability 2158 4. Other Device Firmware Version 2160 5. Time 2162 6. Time of Day 2164 7. Day of Week 2166 The following CDDL defines the encoding of these events. 2168 SUIT_Wait_Events //= (suit-wait-event-authorization => int) 2169 SUIT_Wait_Events //= (suit-wait-event-power => int) 2170 SUIT_Wait_Events //= (suit-wait-event-network => int) 2171 SUIT_Wait_Events //= (suit-wait-event-other-device-version 2172 => SUIT_Wait_Event_Argument_Other_Device_Version) 2173 SUIT_Wait_Events //= (suit-wait-event-time => uint); Timestamp 2174 SUIT_Wait_Events //= (suit-wait-event-time-of-day 2175 => uint); Time of Day (seconds since 00:00:00) 2176 SUIT_Wait_Events //= (suit-wait-event-day-of-week 2177 => uint); Days since Sunday 2179 SUIT_Wait_Event_Argument_Authorization = int ; priority 2180 SUIT_Wait_Event_Argument_Power = int ; Power Level 2181 SUIT_Wait_Event_Argument_Network = int ; Network State 2182 SUIT_Wait_Event_Argument_Other_Device_Version = [ 2183 other-device: bstr, 2184 other-device-version: [+int] 2185 ] 2186 SUIT_Wait_Event_Argument_Time = uint ; Timestamp 2187 SUIT_Wait_Event_Argument_Time_Of_Day = uint ; Time of Day 2188 ; (seconds since 00:00:00) 2189 SUIT_Wait_Event_Argument_Day_Of_Week = uint ; Days since Sunday 2191 9.12.14. suit-directive-run-sequence 2193 To enable conditional commands, and to allow several strictly ordered 2194 sequences to be executed out-of-order, suit-directive-run-sequence 2195 allows the manifest processor to execute its argument as a 2196 SUIT_Command_Sequence. The argument must be wrapped in a bstr. 2198 When a sequence is executed, any failure of a condition causes 2199 immediate termination of the sequence. 2201 The following CDDL describes the SUIT_Run_Sequence argument. 2203 SUIT_Directive_Run_Sequence_Argument = bstr .cbor SUIT_Command_Sequence 2205 When suit-directive-run-sequence completes, it forwards the last 2206 status code that occurred in the sequence. If the Soft Failure 2207 parameter is true, then suit-directive-run-sequence only fails when a 2208 directive in the argument sequence fails. 2210 SUIT_Parameter_Soft_Failure defaults to False when suit-directive- 2211 run-sequence begins. Its value is discarded when suit-directive-run- 2212 sequence terminates. 2214 9.12.15. suit-directive-swap 2216 suit-directive-swap instructs the manifest processor to move the 2217 source to the destination and the destination to the source 2218 simultaneously. Swap has nearly identical semantics to suit- 2219 directive-copy except that suit-directive-swap replaces the source 2220 with the current contents of the destination in an application- 2221 defined way. If SUIT_Parameter_Compression_Info or 2222 SUIT_Parameter_Encryption_Info are present, they must be handled in a 2223 symmetric way, so that the source is decompressed into the 2224 destination and the destination is compressed into the source. The 2225 source is decrypted into the destination and the destination is 2226 encrypted into the source. suit-directive-swap is OPTIONAL to 2227 implement. 2229 9.12.15.1. SUIT_Directive CDDL 2231 The following CDDL describes SUIT_Directive: 2233 SUIT_Directive //= (suit-directive-set-component-index, uint/bool) 2234 SUIT_Directive //= (suit-directive-set-dependency-index, uint/bool) 2235 SUIT_Directive //= (suit-directive-run-sequence, 2236 bstr .cbor SUIT_Command_Sequence) 2237 SUIT_Directive //= (suit-directive-try-each, 2238 SUIT_Directive_Try_Each_Argument) 2239 SUIT_Directive //= (suit-directive-process-dependency, nil) 2240 SUIT_Directive //= (suit-directive-set-parameters, 2241 {+ SUIT_Parameters}) 2242 SUIT_Directive //= (suit-directive-override-parameters, 2243 {+ SUIT_Parameters}) 2244 SUIT_Directive //= (suit-directive-fetch, nil) 2245 SUIT_Directive //= (suit-directive-copy, nil) 2246 SUIT_Directive //= (suit-directive-run, nil) 2247 SUIT_Directive //= (suit-directive-wait, 2248 { + SUIT_Wait_Events }) 2250 SUIT_Directive_Try_Each_Argument = [ 2251 + bstr .cbor SUIT_Command_Sequence, 2252 nil / bstr .cbor SUIT_Command_Sequence 2253 ] 2255 SUIT_Wait_Events //= (suit-wait-event-authorization => int) 2256 SUIT_Wait_Events //= (suit-wait-event-power => int) 2257 SUIT_Wait_Events //= (suit-wait-event-network => int) 2258 SUIT_Wait_Events //= (suit-wait-event-other-device-version 2259 => SUIT_Wait_Event_Argument_Other_Device_Version) 2260 SUIT_Wait_Events //= (suit-wait-event-time => uint); Timestamp 2261 SUIT_Wait_Events //= (suit-wait-event-time-of-day 2262 => uint); Time of Day (seconds since 00:00:00) 2263 SUIT_Wait_Events //= (suit-wait-event-day-of-week 2264 => uint); Days since Sunday 2266 SUIT_Wait_Event_Argument_Authorization = int ; priority 2267 SUIT_Wait_Event_Argument_Power = int ; Power Level 2268 SUIT_Wait_Event_Argument_Network = int ; Network State 2269 SUIT_Wait_Event_Argument_Other_Device_Version = [ 2270 other-device: bstr, 2271 other-device-version: [+int] 2272 ] 2273 SUIT_Wait_Event_Argument_Time = uint ; Timestamp 2274 SUIT_Wait_Event_Argument_Time_Of_Day = uint ; Time of Day 2275 ; (seconds since 00:00:00) 2276 SUIT_Wait_Event_Argument_Day_Of_Week = uint ; Days since Sunday 2278 9.13. SUIT_Text_Map 2280 The SUIT_Text_Map contains all text descriptions needed for this 2281 manifest. The text section is typically severable, allowing 2282 manifests to be distributed without the text, since end-nodes do not 2283 require text. The meaning of each field is described below. 2285 Each section MAY be present. If present, each section MUST be as 2286 described. Negative integer IDs are reserved for application- 2287 specific text values. 2289 +---------------------------------+---------------------------------+ 2290 | CDDL Structure | Description | 2291 +---------------------------------+---------------------------------+ 2292 | suit-text-manifest-description | Free text description of the | 2293 | | manifest | 2294 | | | 2295 | suit-text-update-description | Free text description of the | 2296 | | update | 2297 | | | 2298 | suit-text-vendor-name | Free text vendor name | 2299 | | | 2300 | suit-text-model-name | Free text model name | 2301 | | | 2302 | suit-text-vendor-domain | The domain used to create the | 2303 | | vendor-id condition | 2304 | | | 2305 | suit-text-model-info | The information used to create | 2306 | | the class-id condition | 2307 | | | 2308 | suit-text-component-description | Free text description of each | 2309 | | component in the manifest | 2310 | | | 2311 | suit-text-manifest-json-source | The JSON-formatted document | 2312 | | that was used to create the | 2313 | | manifest | 2314 | | | 2315 | suit-text-manifest-yaml-source | The yaml-formatted document | 2316 | | that was used to create the | 2317 | | manifest | 2318 | | | 2319 | suit-text-version-dependencies | List of component versions | 2320 | | required by the manifest | 2321 +---------------------------------+---------------------------------+ 2323 10. Access Control Lists 2325 To manage permissions in the manifest, there are three models that 2326 can be used. 2328 First, the simplest model requires that all manifests are 2329 authenticated by a single trusted key. This mode has the advantage 2330 that only a root manifest needs to be authenticated, since all of its 2331 dependencies have digests included in the root manifest. 2333 This simplest model can be extended by adding key delegation without 2334 much increase in complexity. 2336 A second model requires an ACL to be presented to the device, 2337 authenticated by a trusted party or stored on the device. This ACL 2338 grants access rights for specific component IDs or component ID 2339 prefixes to the listed identities or identity groups. Any identity 2340 may verify an image digest, but fetching into or fetching from a 2341 component ID requires approval from the ACL. 2343 A third model allows a device to provide even more fine-grained 2344 controls: The ACL lists the component ID or component ID prefix that 2345 an identity may use, and also lists the commands that the identity 2346 may use in combination with that component ID. 2348 11. SUIT Digest Container 2350 RFC 8152 [RFC8152] provides containers for signature, MAC, and 2351 encryption, but no basic digest container. The container needed for 2352 a digest requires a type identifier and a container for the raw 2353 digest data. Some forms of digest may require additional parameters. 2354 These can be added following the digest. This structure is described 2355 by the following CDDL. 2357 The algorithms listed are sufficient for verifying integrity of 2358 Firmware Updates as of this writing, however this may change over 2359 time. 2361 SUIT_Digest = [ 2362 suit-digest-algorithm-id : $suit-digest-algorithm-ids, 2363 suit-digest-bytes : bytes, 2364 ? suit-digest-parameters : any 2365 ] 2367 digest-algorithm-ids /= algorithm-id-sha224 2368 digest-algorithm-ids /= algorithm-id-sha256 2369 digest-algorithm-ids /= algorithm-id-sha384 2370 digest-algorithm-ids /= algorithm-id-sha512 2371 digest-algorithm-ids /= algorithm-id-sha3-224 2372 digest-algorithm-ids /= algorithm-id-sha3-256 2373 digest-algorithm-ids /= algorithm-id-sha3-384 2374 digest-algorithm-ids /= algorithm-id-sha3-512 2376 algorithm-id-sha224 = 1 2377 algorithm-id-sha256 = 2 2378 algorithm-id-sha384 = 3 2379 algorithm-id-sha512 = 4 2380 algorithm-id-sha3-224 = 5 2381 algorithm-id-sha3-256 = 6 2382 algorithm-id-sha3-384 = 7 2383 algorithm-id-sha3-512 = 8 2385 12. Creating Conditional Sequences 2387 For some use cases, it is important to provide a sequence that can 2388 fail without terminating an update. For example, a dual-image XIP 2389 MCU may require an update that can be placed at one of two offsets. 2390 This has two implications, first, the digest of each offset will be 2391 different. Second, the image fetched for each offset will have a 2392 different URI. Conditional sequences allow this to be resolved in a 2393 simple way. 2395 The following JSON representation of a manifest demonstrates how this 2396 would be represented. It assumes that the bootloader and manifest 2397 processor take care of A/B switching and that the manifest is not 2398 aware of this distinction. 2400 { 2401 "structure-version" : 1, 2402 "sequence-number" : 7, 2403 "common" :{ 2404 "components" : [ 2405 [b'0'] 2406 ], 2407 "common-sequence" : [ 2408 { 2409 "directive-set-var" : { 2410 "size": 32567 2411 }, 2412 }, 2413 { 2414 "try-each" : [ 2415 [ 2416 {"condition-component-offset" : ""}, 2417 { 2418 "directive-set-var": { 2419 "digest" : "" 2420 } 2421 } 2422 ], 2423 [ 2424 {"condition-component-offset" : ""}, 2425 { 2426 "directive-set-var": { 2427 "digest" : "" 2428 } 2429 } 2430 ], 2431 [{ "abort" : null }] 2432 ] 2433 } 2434 ] 2435 } 2436 "fetch" : [ 2437 { 2438 "try-each" : [ 2439 [ 2440 {"condition-component-offset" : ""}, 2441 { 2442 "directive-set-var": { 2443 "uri" : "" 2444 } 2445 } 2446 ], 2447 [ 2448 {"condition-component-offset" : ""}, 2449 { 2450 "directive-set-var": { 2451 "uri" : "" 2452 } 2453 } 2454 ], 2455 [{ "directive-abort" : null }] 2456 ] 2458 }, 2459 "fetch" : null 2460 ] 2461 } 2463 13. IANA Considerations 2465 IANA is requested to setup a registry for SUIT manifests. Several 2466 registries defined in the subsections below need to be created. 2468 For each registry, values 0-23 are Standards Action, 24-255 are IETF 2469 Review, 256-65535 are Expert Review, and 65536 or greater are First 2470 Come First Served. 2472 Negative values -23 to 0 are Experimental Use, -24 and lower are 2473 Private Use. 2475 13.1. SUIT Directives 2476 +-------+----------------------+ 2477 | Label | Name | 2478 +-------+----------------------+ 2479 | 12 | Set Component Index | 2480 | | | 2481 | 13 | Set Dependency Index | 2482 | | | 2483 | 14 | Abort | 2484 | | | 2485 | 15 | Try Each | 2486 | | | 2487 | 16 | Reserved | 2488 | | | 2489 | 17 | Reserved | 2490 | | | 2491 | 18 | Process Dependency | 2492 | | | 2493 | 19 | Set Parameters | 2494 | | | 2495 | 20 | Override Parameters | 2496 | | | 2497 | 21 | Fetch | 2498 | | | 2499 | 22 | Copy | 2500 | | | 2501 | 23 | Run | 2502 | | | 2503 | 29 | Wait For Event | 2504 | | | 2505 | 30 | Run Sequence | 2506 | | | 2507 | 32 | Swap | 2508 +-------+----------------------+ 2510 13.2. SUIT Conditions 2511 +-------+-------------------+ 2512 | Label | Name | 2513 +-------+-------------------+ 2514 | 1 | Vendor Identifier | 2515 | | | 2516 | 2 | Class Identifier | 2517 | | | 2518 | 24 | Device Identifier | 2519 | | | 2520 | 3 | Image Match | 2521 | | | 2522 | 25 | Image Not Match | 2523 | | | 2524 | 4 | Use Before | 2525 | | | 2526 | 5 | Component Offset | 2527 | | | 2528 | 26 | Minimum Battery | 2529 | | | 2530 | 27 | Update Authorized | 2531 | | | 2532 | 28 | Version | 2533 | | | 2534 | nint | Custom Condition | 2535 +-------+-------------------+ 2537 13.3. SUIT Parameters 2538 +-------+------------------+--------------------+ 2539 | Label | Name | | 2540 +-------+------------------+--------------------+ 2541 | 1 | Vendor ID | | 2542 | | | | 2543 | 2 | Class ID | | 2544 | | | | 2545 | 3 | Image Digest | | 2546 | | | | 2547 | 4 | Use Before | | 2548 | | | | 2549 | 5 | Component Offset | | 2550 | | | | 2551 | 12 | Strict Order | | 2552 | | | | 2553 | 13 | Soft Failure | | 2554 | | | | 2555 | 14 | Image Size | | 2556 | | | | 2557 | 18 | Encryption Info | | 2558 | | | | 2559 | 19 | Compression Info | | 2560 | | | | 2561 | 20 | Unpack Info | | 2562 | | | | 2563 | 21 | URI | suit-parameter-uri | 2564 | | | | 2565 | 22 | Source Component | | 2566 | | | | 2567 | 23 | Run Args | | 2568 | | | | 2569 | 24 | Device ID | | 2570 | | | | 2571 | 26 | Minimum Battery | | 2572 | | | | 2573 | 27 | Update Priority | | 2574 | | | | 2575 | 28 | Version | | 2576 | | | | 2577 | 29 | Wait Info | | 2578 | | | | 2579 | 30 | URI List | | 2580 | | | | 2581 | nint | Custom | | 2582 +-------+------------------+--------------------+ 2584 13.4. SUIT Text Values 2586 +-------+--------------------------------+ 2587 | Label | Name | 2588 +-------+--------------------------------+ 2589 | 1 | Manifest Description | 2590 | | | 2591 | 2 | Update Description | 2592 | | | 2593 | 3 | Vendor Name | 2594 | | | 2595 | 4 | Model Name | 2596 | | | 2597 | 5 | Vendor Domain | 2598 | | | 2599 | 6 | Model Info | 2600 | | | 2601 | 7 | Component Description | 2602 | | | 2603 | 8 | Manifest JSON Source | 2604 | | | 2605 | 9 | Manifest YAML Source | 2606 | | | 2607 | 10 | Component Version Dependencies | 2608 +-------+--------------------------------+ 2610 13.5. SUIT Algorithm Identifiers 2612 TBD. 2614 14. Security Considerations 2616 This document is about a manifest format describing and protecting 2617 firmware images and as such it is part of a larger solution for 2618 offering a standardized way of delivering firmware updates to IoT 2619 devices. A detailed discussion about security can be found in the 2620 architecture document [I-D.ietf-suit-architecture] and in 2621 [I-D.ietf-suit-information-model]. 2623 15. Mailing List Information 2625 RFC EDITOR: PLEASE REMOVE THIS SECTION 2627 The discussion list for this document is located at the e-mail 2628 address suit@ietf.org [1]. Information on the group and information 2629 on how to subscribe to the list is at 2630 https://www1.ietf.org/mailman/listinfo/suit [2] 2631 Archives of the list can be found at: https://www.ietf.org/mail- 2632 archive/web/suit/current/index.html [3] 2634 16. Acknowledgements 2636 We would like to thank the following persons for their support in 2637 designing this mechanism: 2639 - Milosch Meriac 2641 - Geraint Luff 2643 - Dan Ros 2645 - John-Paul Stanford 2647 - Hugo Vincent 2649 - Carsten Bormann 2651 - Oeyvind Roenningstad 2653 - Frank Audun Kvamtroe 2655 - Krzysztof Chruściński 2657 - Andrzej Puzdrowski 2659 - Michael Richardson 2661 - David Brown 2663 - Emmanuel Baccelli 2665 17. References 2667 17.1. Normative References 2669 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2670 Requirement Levels", BCP 14, RFC 2119, 2671 DOI 10.17487/RFC2119, March 1997, 2672 . 2674 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 2675 Unique IDentifier (UUID) URN Namespace", RFC 4122, 2676 DOI 10.17487/RFC4122, July 2005, 2677 . 2679 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 2680 RFC 8152, DOI 10.17487/RFC8152, July 2017, 2681 . 2683 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2684 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2685 May 2017, . 2687 17.2. Informative References 2689 [COFF] Wikipedia, ., "Common Object File Format (COFF)", 2020, 2690 . 2692 [ELF] Wikipedia, ., "Executable and Linkable Format (ELF)", 2693 2020, . 2696 [HEX] Wikipedia, ., "Intel HEX", 2020, 2697 . 2699 [I-D.ietf-suit-architecture] 2700 Moran, B., Tschofenig, H., Brown, D., and M. Meriac, "A 2701 Firmware Update Architecture for Internet of Things", 2702 draft-ietf-suit-architecture-09 (work in progress), May 2703 2020. 2705 [I-D.ietf-suit-information-model] 2706 Moran, B., Tschofenig, H., and H. Birkholz, "An 2707 Information Model for Firmware Updates in IoT Devices", 2708 draft-ietf-suit-information-model-05 (work in progress), 2709 January 2020. 2711 [I-D.ietf-teep-architecture] 2712 Pei, M., Tschofenig, H., Thaler, D., and D. Wheeler, 2713 "Trusted Execution Environment Provisioning (TEEP) 2714 Architecture", draft-ietf-teep-architecture-08 (work in 2715 progress), April 2020. 2717 [I-D.kucherawy-rfc8478bis] 2718 Collet, Y. and M. Kucherawy, "Zstandard Compression and 2719 the application/zstd Media Type", draft-kucherawy- 2720 rfc8478bis-05 (work in progress), April 2020. 2722 [RFC1950] Deutsch, P. and J-L. Gailly, "ZLIB Compressed Data Format 2723 Specification version 3.3", RFC 1950, 2724 DOI 10.17487/RFC1950, May 1996, 2725 . 2727 [RFC7932] Alakuijala, J. and Z. Szabadka, "Brotli Compressed Data 2728 Format", RFC 7932, DOI 10.17487/RFC7932, July 2016, 2729 . 2731 [SREC] Wikipedia, ., "SREC (file format)", 2020, 2732 . 2734 17.3. URIs 2736 [1] mailto:suit@ietf.org 2738 [2] https://www1.ietf.org/mailman/listinfo/suit 2740 [3] https://www.ietf.org/mail-archive/web/suit/current/index.html 2742 A. Full CDDL 2744 In order to create a valid SUIT Manifest document the structure of 2745 the corresponding CBOR message MUST adhere to the following CDDL data 2746 definition. 2748 SUIT_Envelope = { 2749 ? suit-delegation => bstr .cbor SUIT_Delegation 2750 ? suit-authentication-wrapper 2751 => bstr .cbor SUIT_Authentication_Wrapper / nil, 2752 $$SUIT_Manifest_Wrapped, 2753 * $$SUIT_Severed_Fields, 2754 } 2756 SUIT_Delegation = [ + [ + CWT ] ] 2758 CWT = SUIT_Authentication_Block 2760 SUIT_Authentication_Wrapper = [ + bstr .cbor SUIT_Authentication_Block ] 2762 SUIT_Authentication_Block /= COSE_Mac_Tagged 2763 SUIT_Authentication_Block /= COSE_Sign_Tagged 2764 SUIT_Authentication_Block /= COSE_Mac0_Tagged 2765 SUIT_Authentication_Block /= COSE_Sign1_Tagged 2767 $$SUIT_Manifest_Wrapped //= (suit-manifest => bstr .cbor SUIT_Manifest) 2768 $$SUIT_Manifest_Wrapped //= ( 2769 suit-manifest-encryption-info => bstr .cbor SUIT_Encryption_Wrapper, 2770 suit-manifest-encrypted => bstr 2771 ) 2773 SUIT_Encryption_Wrapper = COSE_Encrypt_Tagged / COSE_Encrypt0_Tagged 2775 $$SUIT_Severed_Fields //= ( suit-dependency-resolution => 2776 bstr .cbor SUIT_Command_Sequence) 2777 $$SUIT_Severed_Fields //= (suit-payload-fetch => 2778 bstr .cbor SUIT_Command_Sequence) 2779 $$SUIT_Severed_Fields //= (suit-install => 2780 bstr .cbor SUIT_Command_Sequence) 2781 $$SUIT_Severed_Fields //= (suit-text => 2782 bstr .cbor SUIT_Text_Map) 2783 $$SUIT_Severed_Fields //= (suit-coswid => 2784 bstr .cbor concise-software-identity) 2786 COSE_Mac_Tagged = any 2787 COSE_Sign_Tagged = any 2788 COSE_Mac0_Tagged = any 2789 COSE_Sign1_Tagged = any 2790 COSE_Encrypt_Tagged = any 2791 COSE_Encrypt0_Tagged = any 2793 SUIT_Digest = [ 2794 suit-digest-algorithm-id : suit-digest-algorithm-ids, 2795 suit-digest-bytes : bstr, 2796 ? suit-digest-parameters : any 2797 ] 2799 ; Named Information Hash Algorithm Identifiers 2800 suit-digest-algorithm-ids /= algorithm-id-sha224 2801 suit-digest-algorithm-ids /= algorithm-id-sha256 2802 suit-digest-algorithm-ids /= algorithm-id-sha384 2803 suit-digest-algorithm-ids /= algorithm-id-sha512 2804 suit-digest-algorithm-ids /= algorithm-id-sha3-224 2805 suit-digest-algorithm-ids /= algorithm-id-sha3-256 2806 suit-digest-algorithm-ids /= algorithm-id-sha3-384 2807 suit-digest-algorithm-ids /= algorithm-id-sha3-512 2809 algorithm-id-sha224 = 1 2810 algorithm-id-sha256 = 2 2811 algorithm-id-sha384 = 3 2812 algorithm-id-sha512 = 4 2813 algorithm-id-sha3-224 = 5 2814 algorithm-id-sha3-256 = 6 2815 algorithm-id-sha3-384 = 7 2816 algorithm-id-sha3-512 = 8 2818 SUIT_Manifest = { 2819 suit-manifest-version => 1, 2820 suit-manifest-sequence-number => uint, 2821 suit-common => bstr .cbor SUIT_Common, 2822 ? suit-reference-uri => #6.32(tstr), 2823 * $$SUIT_Severable_Command_Sequences, 2824 * $$SUIT_Command_Sequences, 2825 * $$SUIT_Protected_Elements, 2826 } 2828 $$SUIT_Severable_Command_Sequences //= (suit-dependency-resolution => 2829 SUIT_Severable_Command_Sequence) 2830 $$SUIT_Severable_Command_Sequences //= (suit-payload-fetch => 2831 SUIT_Severable_Command_Sequence) 2832 $$SUIT_Severable_Command_Sequences //= (suit-install => 2833 SUIT_Severable_Command_Sequence) 2835 SUIT_Severable_Command_Sequence = 2836 SUIT_Digest / bstr .cbor SUIT_Command_Sequence 2838 $$SUIT_Command_Sequences //= ( suit-validate => 2839 bstr .cbor SUIT_Command_Sequence ) 2840 $$SUIT_Command_Sequences //= ( suit-load => 2841 bstr .cbor SUIT_Command_Sequence ) 2842 $$SUIT_Command_Sequences //= ( suit-run => 2843 bstr .cbor SUIT_Command_Sequence ) 2845 $$SUIT_Protected_Elements //= ( suit-text => SUIT_Digest ) 2846 $$SUIT_Protected_Elements //= ( suit-coswid => SUIT_Digest ) 2848 SUIT_Common = { 2849 ? suit-dependencies => bstr .cbor SUIT_Dependencies, 2850 ? suit-components => bstr .cbor SUIT_Components, 2851 ? suit-dependency-components 2852 => bstr .cbor SUIT_Component_References, 2853 ? suit-common-sequence => bstr .cbor SUIT_Command_Sequence, 2854 } 2856 SUIT_Dependencies = [ + SUIT_Dependency ] 2857 SUIT_Components = [ + SUIT_Component_Identifier ] 2858 SUIT_Component_References = [ + SUIT_Component_Reference ] 2860 concise-software-identity = any 2862 SUIT_Dependency = { 2863 suit-dependency-digest => SUIT_Digest, 2864 suit-dependency-prefix => SUIT_Component_Identifier, 2865 } 2867 SUIT_Component_Identifier = [* bstr] 2869 SUIT_Component_Reference = { 2870 suit-component-identifier => SUIT_Component_Identifier, 2871 suit-component-dependency-index => uint 2872 } 2874 SUIT_Command_Sequence = [ + ( 2875 SUIT_Condition // SUIT_Directive // SUIT_Command_Custom 2876 ) ] 2878 SUIT_Command_Custom = (suit-command-custom, bstr/tstr/int/nil) 2879 SUIT_Condition //= (suit-condition-vendor-identifier, nil) 2880 SUIT_Condition //= (suit-condition-class-identifier, nil) 2881 SUIT_Condition //= (suit-condition-device-identifier, nil) 2882 SUIT_Condition //= (suit-condition-image-match, nil) 2883 SUIT_Condition //= (suit-condition-image-not-match, nil) 2884 SUIT_Condition //= (suit-condition-use-before, nil) 2885 SUIT_Condition //= (suit-condition-minimum-battery, nil) 2886 SUIT_Condition //= (suit-condition-update-authorized, nil) 2887 SUIT_Condition //= (suit-condition-version, nil) 2888 SUIT_Condition //= (suit-condition-component-offset, nil) 2890 SUIT_Directive //= (suit-directive-set-component-index, uint/bool) 2891 SUIT_Directive //= (suit-directive-set-dependency-index, uint/bool) 2892 SUIT_Directive //= (suit-directive-run-sequence, 2893 bstr .cbor SUIT_Command_Sequence) 2894 SUIT_Directive //= (suit-directive-try-each, 2895 SUIT_Directive_Try_Each_Argument) 2896 SUIT_Directive //= (suit-directive-process-dependency, nil) 2897 SUIT_Directive //= (suit-directive-set-parameters, 2898 {+ SUIT_Parameters}) 2899 SUIT_Directive //= (suit-directive-override-parameters, 2900 {+ SUIT_Parameters}) 2901 SUIT_Directive //= (suit-directive-fetch, nil) 2902 SUIT_Directive //= (suit-directive-copy, nil) 2903 SUIT_Directive //= (suit-directive-swap, nil) 2904 SUIT_Directive //= (suit-directive-run, nil) 2905 SUIT_Directive //= (suit-directive-wait, nil) 2906 SUIT_Directive //= (suit-directive-abort, nil) 2908 SUIT_Directive_Try_Each_Argument = [ 2909 + bstr .cbor SUIT_Command_Sequence, 2910 nil / bstr .cbor SUIT_Command_Sequence 2911 ] 2913 SUIT_Wait_Event = { + SUIT_Wait_Events } 2915 SUIT_Wait_Events //= (suit-wait-event-authorization => int) 2916 SUIT_Wait_Events //= (suit-wait-event-power => int) 2917 SUIT_Wait_Events //= (suit-wait-event-network => int) 2918 SUIT_Wait_Events //= (suit-wait-event-other-device-version 2919 => SUIT_Wait_Event_Argument_Other_Device_Version) 2920 SUIT_Wait_Events //= (suit-wait-event-time => uint); Timestamp 2921 SUIT_Wait_Events //= (suit-wait-event-time-of-day 2922 => uint); Time of Day (seconds since 00:00:00) 2923 SUIT_Wait_Events //= (suit-wait-event-day-of-week 2924 => uint); Days since Sunday 2926 SUIT_Wait_Event_Argument_Other_Device_Version = [ 2927 other-device: bstr, 2928 other-device-version: [+int] 2929 ] 2931 SUIT_Parameters //= (suit-parameter-vendor-identifier => RFC4122_UUID) 2932 SUIT_Parameters //= (suit-parameter-class-identifier => RFC4122_UUID) 2933 SUIT_Parameters //= (suit-parameter-image-digest 2934 => bstr .cbor SUIT_Digest) 2935 SUIT_Parameters //= (suit-parameter-image-size => uint) 2936 SUIT_Parameters //= (suit-parameter-use-before => uint) 2937 SUIT_Parameters //= (suit-parameter-component-offset => uint) 2939 SUIT_Parameters //= (suit-parameter-encryption-info 2940 => bstr .cbor SUIT_Encryption_Info) 2941 SUIT_Parameters //= (suit-parameter-compression-info 2942 => bstr .cbor SUIT_Compression_Info) 2943 SUIT_Parameters //= (suit-parameter-unpack-info 2944 => bstr .cbor SUIT_Unpack_Info) 2946 SUIT_Parameters //= (suit-parameter-uri => tstr) 2947 SUIT_Parameters //= (suit-parameter-source-component => uint) 2948 SUIT_Parameters //= (suit-parameter-run-args => bstr) 2950 SUIT_Parameters //= (suit-parameter-device-identifier => RFC4122_UUID) 2951 SUIT_Parameters //= (suit-parameter-minimum-battery => uint) 2952 SUIT_Parameters //= (suit-parameter-update-priority => uint) 2953 SUIT_Parameters //= (suit-parameter-version => 2954 SUIT_Parameter_Version_Match) 2955 SUIT_Parameters //= (suit-parameter-wait-info => 2956 bstr .cbor SUIT_Wait_Event) 2958 SUIT_Parameters //= (suit-parameter-custom => int/bool/tstr/bstr) 2960 SUIT_Parameters //= (suit-parameter-strict-order => bool) 2961 SUIT_Parameters //= (suit-parameter-soft-failure => bool) 2963 RFC4122_UUID = bstr .size 16 2965 SUIT_Parameter_Version_Match = [ 2966 suit-condition-version-comparison-type: 2967 SUIT_Condition_Version_Comparison_Types, 2968 suit-condition-version-comparison-value: 2969 SUIT_Condition_Version_Comparison_Value 2970 ] 2971 SUIT_Condition_Version_Comparison_Types /= 2972 suit-condition-version-comparison-greater 2973 SUIT_Condition_Version_Comparison_Types /= 2974 suit-condition-version-comparison-greater-equal 2975 SUIT_Condition_Version_Comparison_Types /= 2976 suit-condition-version-comparison-equal 2977 SUIT_Condition_Version_Comparison_Types /= 2978 suit-condition-version-comparison-lesser-equal 2979 SUIT_Condition_Version_Comparison_Types /= 2980 suit-condition-version-comparison-lesser 2982 suit-condition-version-comparison-greater = 1 2983 suit-condition-version-comparison-greater-equal = 2 2984 suit-condition-version-comparison-equal = 3 2985 suit-condition-version-comparison-lesser-equal = 4 2986 suit-condition-version-comparison-lesser = 5 2988 SUIT_Condition_Version_Comparison_Value = [+int] 2990 SUIT_Encryption_Info = COSE_Encrypt_Tagged/COSE_Encrypt0_Tagged 2991 SUIT_Compression_Info = { 2992 suit-compression-algorithm => SUIT_Compression_Algorithms, 2993 ? suit-compression-parameters => bstr 2994 } 2996 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_zlib 2997 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_brotli 2998 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_zstd 3000 SUIT_Compression_Algorithm_zlib = 1 3001 SUIT_Compression_Algorithm_brotli = 2 3002 SUIT_Compression_Algorithm_zstd = 3 3004 SUIT_Unpack_Info = { 3005 suit-unpack-algorithm => SUIT_Unpack_Algorithms, 3006 ? suit-unpack-parameters => bstr 3007 } 3009 SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Hex 3010 SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Elf 3011 SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Coff 3012 SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Srec 3014 SUIT_Unpack_Algorithm_Hex = 1 3015 SUIT_Unpack_Algorithm_Elf = 2 3016 SUIT_Unpack_Algorithm_Coff = 3 3017 SUIT_Unpack_Algorithm_Srec = 4 3019 SUIT_Text_Map = {SUIT_Text_Keys => tstr} 3021 SUIT_Text_Keys /= suit-text-manifest-description 3022 SUIT_Text_Keys /= suit-text-update-description 3023 SUIT_Text_Keys /= suit-text-vendor-name 3024 SUIT_Text_Keys /= suit-text-model-name 3025 SUIT_Text_Keys /= suit-text-vendor-domain 3026 SUIT_Text_Keys /= suit-text-model-info 3027 SUIT_Text_Keys /= suit-text-component-description 3028 SUIT_Text_Keys /= suit-text-manifest-json-source 3029 SUIT_Text_Keys /= suit-text-manifest-yaml-source 3030 SUIT_Text_Keys /= suit-text-version-dependencies 3032 suit-delegation = 1 3033 suit-authentication-wrapper = 2 3034 suit-manifest = 3 3036 suit-manifest-encryption-info = 4 3037 suit-manifest-encrypted = 5 3039 suit-manifest-version = 1 3040 suit-manifest-sequence-number = 2 3041 suit-common = 3 3042 suit-reference-uri = 4 3043 suit-dependency-resolution = 7 3044 suit-payload-fetch = 8 3045 suit-install = 9 3046 suit-validate = 10 3047 suit-load = 11 3048 suit-run = 12 3049 suit-text = 13 3050 suit-coswid = 14 3052 suit-dependencies = 1 3053 suit-components = 2 3054 suit-dependency-components = 3 3055 suit-common-sequence = 4 3057 suit-dependency-digest = 1 3058 suit-dependency-prefix = 2 3060 suit-component-identifier = 1 3061 suit-component-dependency-index = 2 3063 suit-command-custom = nint 3065 suit-condition-vendor-identifier = 1 3066 suit-condition-class-identifier = 2 3067 suit-condition-image-match = 3 3068 suit-condition-use-before = 4 3069 suit-condition-component-offset = 5 3071 suit-condition-device-identifier = 24 3072 suit-condition-image-not-match = 25 3073 suit-condition-minimum-battery = 26 3074 suit-condition-update-authorized = 27 3075 suit-condition-version = 28 3077 suit-directive-set-component-index = 12 3078 suit-directive-set-dependency-index = 13 3079 suit-directive-abort = 14 3080 suit-directive-try-each = 15 3081 ;suit-directive-do-each = 16 ; TBD 3082 ;suit-directive-map-filter = 17 ; TBD 3083 suit-directive-process-dependency = 18 3084 suit-directive-set-parameters = 19 3085 suit-directive-override-parameters = 20 3086 suit-directive-fetch = 21 3087 suit-directive-copy = 22 3088 suit-directive-run = 23 3090 suit-directive-wait = 29 3091 suit-directive-run-sequence = 30 3092 suit-directive-swap = 32 3094 suit-wait-event-authorization = 1 3095 suit-wait-event-power = 2 3096 suit-wait-event-network = 3 3097 suit-wait-event-other-device-version = 4 3098 suit-wait-event-time = 5 3099 suit-wait-event-time-of-day = 6 3100 suit-wait-event-day-of-week = 7 3102 suit-parameter-vendor-identifier = 1 3103 suit-parameter-class-identifier = 2 3104 suit-parameter-image-digest = 3 3105 suit-parameter-use-before = 4 3106 suit-parameter-component-offset = 5 3108 suit-parameter-strict-order = 12 3109 suit-parameter-soft-failure = 13 3110 suit-parameter-image-size = 14 3112 suit-parameter-encryption-info = 18 3113 suit-parameter-compression-info = 19 3114 suit-parameter-unpack-info = 20 3115 suit-parameter-uri = 21 3116 suit-parameter-source-component = 22 3117 suit-parameter-run-args = 23 3119 suit-parameter-device-identifier = 24 3120 suit-parameter-minimum-battery = 26 3121 suit-parameter-update-priority = 27 3122 suit-parameter-version = 28 3123 suit-parameter-wait-info = 29 3124 suit-parameter-uri-list = 30 3125 suit-parameter-custom = nint 3127 suit-compression-algorithm = 1 3128 suit-compression-parameters = 2 3130 suit-unpack-algorithm = 1 3131 suit-unpack-parameters = 2 3133 suit-text-manifest-description = 1 3134 suit-text-update-description = 2 3135 suit-text-vendor-name = 3 3136 suit-text-model-name = 4 3137 suit-text-vendor-domain = 5 3138 suit-text-model-info = 6 3139 suit-text-component-description = 7 3140 suit-text-manifest-json-source = 8 3141 suit-text-manifest-yaml-source = 9 3142 suit-text-version-dependencies = 10 3144 B. Examples 3146 The following examples demonstrate a small subset of the 3147 functionality of the manifest. However, despite this, even a simple 3148 manifest processor can execute most of these manifests. 3150 The examples are signed using the following ECDSA secp256r1 key: 3152 -----BEGIN PRIVATE KEY----- 3153 MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgApZYjZCUGLM50VBC 3154 CjYStX+09jGmnyJPrpDLTz/hiXOhRANCAASEloEarguqq9JhVxie7NomvqqL8Rtv 3155 P+bitWWchdvArTsfKktsCYExwKNtrNHXi9OB3N+wnAUtszmR23M4tKiW 3156 -----END PRIVATE KEY----- 3158 The corresponding public key can be used to verify these examples: 3160 -----BEGIN PUBLIC KEY----- 3161 MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEhJaBGq4LqqvSYVcYnuzaJr6qi/Eb 3162 bz/m4rVlnIXbwK07HypLbAmBMcCjbazR14vTgdzfsJwFLbM5kdtzOLSolg== 3163 -----END PUBLIC KEY----- 3165 Each example uses SHA256 as the digest function. 3167 B.1. Example 0: Secure Boot 3169 Secure boot and compatibility check. 3171 { 3172 / authentication-wrapper / 2:h'81586fd28443a10126a0582482025820655 3174 f1230fd3833ca828c18200498fd1cd90656a9a2620c6989921c06623703515840a0416 3175 20607b7765a51fe0566e5d8fed95491ee6df622132524fdbe67607bf7f2794d7a71dad 3176 7230d3cab86c5091a226d00061b0a74a01b3d371e07d5b3eca3d4' / [ 3177 h'd28443a10126a0582482025820655f1230fd3833ca828c18200498fd1cd9 3178 0656a9a2620c6989921c06623703515840a041620607b7765a51fe0566e5d8fed95491 3179 ee6df622132524fdbe67607bf7f2794d7a71dad7230d3cab86c5091a226d00061b0a74 3180 a01b3d371e07d5b3eca3d4' / 18([ 3181 / protected / h'a10126' / { 3182 / alg / 1:-7 / "ES256" /, 3183 } /, 3184 / unprotected / { 3185 }, 3186 / payload / h'82025820655f1230fd3833ca828c18200498fd1c 3187 d90656a9a2620c6989921c0662370351' / [ 3188 / algorithm-id / 2 / "sha256" /, 3189 / digest-bytes / 3190 h'"655f1230fd3833ca828c18200498fd1cd90656a9a2620c6989921c0662370351"' 3191 ] /, 3192 / signature / h'"a041620607b7765a51fe0566e5d8fed95491e 3193 e6df622132524fdbe67607bf7f2794d7a71dad7230d3cab86c5091a226d00061b0a74a 3194 01b3d371e07d5b3eca3d4"' 3195 ]) / 3196 ] /, 3197 / manifest / 3:h'a501010201035860a20244818141000458568614a40150fa6 3198 b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab4503582 3199 48202582000112233445566778899aabbccddeeff0123456789abcdeffedcba9876543 3200 2100e1987d001f602f60a438203f60c438217f6' / { 3201 / manifest-version / 1:1, 3202 / manifest-sequence-number / 2:1, 3203 / common / 3:h'a20244818141000458568614a40150fa6b4a53d5ad5fdfb 3204 e9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab450358248202582000112 3205 233445566778899aabbccddeeff0123456789abcdeffedcba98765432100e1987d001f 3206 602f6' / { 3207 / components / 2:h'81814100' / [ 3208 [h'"00"'] 3209 ] /, 3210 / common-sequence / 4:h'8614a40150fa6b4a53d5ad5fdfbe9de663 3211 e4d41ffe02501492af1425695e48bf429b2d51f2ab4503582482025820001122334455 3212 66778899aabbccddeeff0123456789abcdeffedcba98765432100e1987d001f602f6' 3213 / [ 3214 / directive-override-parameters / 20,{ 3215 / vendor-id / 3216 1:h'"fa6b4a53d5ad5fdfbe9de663e4d41ffe"' / fa6b4a53-d5ad-5fdf- 3217 be9d-e663e4d41ffe /, 3218 / class-id / 3219 2:h'"1492af1425695e48bf429b2d51f2ab45"' / 3220 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 3221 / image-digest / 3:h'8202582000112233445566778899a 3223 abbccddeeff0123456789abcdeffedcba9876543210' / [ 3224 / algorithm-id / 2 / "sha256" /, 3225 / digest-bytes / 3226 h'"00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210"' 3227 ] /, 3228 / image-size / 14:34768, 3229 } , 3230 / condition-vendor-identifier / 1,F6 / nil / , 3231 / condition-class-identifier / 2,F6 / nil / 3232 ] /, 3233 } /, 3234 / validate / 10:h'8203f6' / [ 3235 / condition-image-match / 3,F6 / nil / 3236 ] /, 3237 / run / 12:h'8217f6' / [ 3238 / directive-run / 23,F6 / nil / 3239 ] /, 3240 } /, 3241 } 3243 Total size of manifest without COSE authentication object: 118 3245 Manifest: 3247 a1035872a501010201035860a20244818141000458568614a40150fa6b4a 3248 53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab 3249 450358248202582000112233445566778899aabbccddeeff0123456789ab 3250 cdeffedcba98765432100e1987d001f602f60a438203f60c438217f6 3252 Total size of manifest with COSE authentication object: 235 3254 Manifest with COSE authentication object: 3256 a202587281586fd28443a10126a0582482025820655f1230fd3833ca828c 3257 18200498fd1cd90656a9a2620c6989921c06623703515840a041620607b7 3258 765a51fe0566e5d8fed95491ee6df622132524fdbe67607bf7f2794d7a71 3259 dad7230d3cab86c5091a226d00061b0a74a01b3d371e07d5b3eca3d40358 3260 72a501010201035860a20244818141000458568614a40150fa6b4a53d5ad 3261 5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab450358 3262 248202582000112233445566778899aabbccddeeff0123456789abcdeffe 3263 dcba98765432100e1987d001f602f60a438203f60c438217f6 3265 B.2. Example 1: Simultaneous Download and Installation of Payload 3267 Simultaneous download and installation of payload. 3269 { 3270 / authentication-wrapper / 2:h'81586fd28443a10126a0582482025820815 3272 32771898e4ebcccf12c607420eba62b5086192cac4c99692835b58ee62f7b584081592 3273 1e5148e9b81e79d8be570de6bb42ba2e903c8549f0e13dee4d0ee420d90dd9f8537ebe 3274 ad3f92b37df703539879129183b0beaf3ba75cacd8a91e075a24e' / [ 3275 h'd28443a10126a058248202582081532771898e4ebcccf12c607420eba62b 3276 5086192cac4c99692835b58ee62f7b5840815921e5148e9b81e79d8be570de6bb42ba2 3277 e903c8549f0e13dee4d0ee420d90dd9f8537ebead3f92b37df703539879129183b0bea 3278 f3ba75cacd8a91e075a24e' / 18([ 3279 / protected / h'a10126' / { 3280 / alg / 1:-7 / "ES256" /, 3281 } /, 3282 / unprotected / { 3283 }, 3284 / payload / h'8202582081532771898e4ebcccf12c607420eba6 3285 2b5086192cac4c99692835b58ee62f7b' / [ 3286 / algorithm-id / 2 / "sha256" /, 3287 / digest-bytes / 3288 h'"81532771898e4ebcccf12c607420eba62b5086192cac4c99692835b58ee62f7b"' 3289 ] /, 3290 / signature / h'"815921e5148e9b81e79d8be570de6bb42ba2e 3291 903c8549f0e13dee4d0ee420d90dd9f8537ebead3f92b37df703539879129183b0beaf 3292 3ba75cacd8a91e075a24e"' 3293 ]) / 3294 ] /, 3295 / manifest / 3:h'a501010202035860a20244818141000458568614a40150fa6 3296 b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab4503582 3297 48202582000112233445566778899aabbccddeeff0123456789abcdeffedcba9876543 3298 2100e1987d001f602f60958258613a115781b687474703a2f2f6578616d706c652e636 3299 f6d2f66696c652e62696e15f603f60a438203f6' / { 3300 / manifest-version / 1:1, 3301 / manifest-sequence-number / 2:2, 3302 / common / 3:h'a20244818141000458568614a40150fa6b4a53d5ad5fdfb 3303 e9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab450358248202582000112 3304 233445566778899aabbccddeeff0123456789abcdeffedcba98765432100e1987d001f 3305 602f6' / { 3306 / components / 2:h'81814100' / [ 3307 [h'"00"'] 3308 ] /, 3309 / common-sequence / 4:h'8614a40150fa6b4a53d5ad5fdfbe9de663 3310 e4d41ffe02501492af1425695e48bf429b2d51f2ab4503582482025820001122334455 3311 66778899aabbccddeeff0123456789abcdeffedcba98765432100e1987d001f602f6' 3312 / [ 3313 / directive-override-parameters / 20,{ 3314 / vendor-id / 3315 1:h'"fa6b4a53d5ad5fdfbe9de663e4d41ffe"' / fa6b4a53-d5ad-5fdf- 3316 be9d-e663e4d41ffe /, 3317 / class-id / 3318 2:h'"1492af1425695e48bf429b2d51f2ab45"' / 3319 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 3320 / image-digest / 3:h'8202582000112233445566778899a 3321 abbccddeeff0123456789abcdeffedcba9876543210' / [ 3322 / algorithm-id / 2 / "sha256" /, 3323 / digest-bytes / 3324 h'"00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210"' 3325 ] /, 3326 / image-size / 14:34768, 3327 } , 3328 / condition-vendor-identifier / 1,F6 / nil / , 3329 / condition-class-identifier / 2,F6 / nil / 3330 ] /, 3331 } /, 3332 / install / 9:h'8613a115781b687474703a2f2f6578616d706c652e636f 3333 6d2f66696c652e62696e15f603f6' / [ 3334 / directive-set-parameters / 19,{ 3335 / uri / 21:'http://example.com/file.bin', 3336 } , 3337 / directive-fetch / 21,F6 / nil / , 3338 / condition-image-match / 3,F6 / nil / 3339 ] /, 3340 / validate / 10:h'8203f6' / [ 3341 / condition-image-match / 3,F6 / nil / 3342 ] /, 3343 } /, 3344 } 3346 Total size of manifest without COSE authentication object: 153 3348 Manifest: 3350 a1035895a501010202035860a20244818141000458568614a40150fa6b4a 3351 53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab 3352 450358248202582000112233445566778899aabbccddeeff0123456789ab 3353 cdeffedcba98765432100e1987d001f602f60958258613a115781b687474 3354 703a2f2f6578616d706c652e636f6d2f66696c652e62696e15f603f60a43 3355 8203f6 3357 Total size of manifest with COSE authentication object: 270 3359 Manifest with COSE authentication object: 3361 a202587281586fd28443a10126a058248202582081532771898e4ebcccf1 3362 2c607420eba62b5086192cac4c99692835b58ee62f7b5840815921e5148e 3363 9b81e79d8be570de6bb42ba2e903c8549f0e13dee4d0ee420d90dd9f8537 3364 ebead3f92b37df703539879129183b0beaf3ba75cacd8a91e075a24e0358 3365 95a501010202035860a20244818141000458568614a40150fa6b4a53d5ad 3366 5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab450358 3367 248202582000112233445566778899aabbccddeeff0123456789abcdeffe 3368 dcba98765432100e1987d001f602f60958258613a115781b687474703a2f 3369 2f6578616d706c652e636f6d2f66696c652e62696e15f603f60a438203f6 3371 B.3. Example 2: Simultaneous Download, Installation, and Secure Boot 3373 Compatibility test, simultaneous download and installation, and 3374 secure boot. 3376 { 3377 / authentication-wrapper / 2:h'81586fd28443a10126a0582482025820883 3378 90f8988639d8a2cfb6da969fce488333ac5ba77aaf0d66b5623009bbf341158401929f 3379 fd488c455ab40eaf1aa96a7df4a9c16c658221055c3a113232fb81c5751a23a74b5efc 3380 06c459eb47a07028ef3c6a0d9051185dd78899c654249f9070dea' / [ 3381 h'd28443a10126a058248202582088390f8988639d8a2cfb6da969fce48833 3382 3ac5ba77aaf0d66b5623009bbf341158401929ffd488c455ab40eaf1aa96a7df4a9c16 3383 c658221055c3a113232fb81c5751a23a74b5efc06c459eb47a07028ef3c6a0d9051185 3384 dd78899c654249f9070dea' / 18([ 3385 / protected / h'a10126' / { 3386 / alg / 1:-7 / "ES256" /, 3387 } /, 3388 / unprotected / { 3389 }, 3390 / payload / h'8202582088390f8988639d8a2cfb6da969fce488 3391 333ac5ba77aaf0d66b5623009bbf3411' / [ 3392 / algorithm-id / 2 / "sha256" /, 3393 / digest-bytes / 3394 h'"88390f8988639d8a2cfb6da969fce488333ac5ba77aaf0d66b5623009bbf3411"' 3395 ] /, 3396 / signature / h'"1929ffd488c455ab40eaf1aa96a7df4a9c16c 3397 658221055c3a113232fb81c5751a23a74b5efc06c459eb47a07028ef3c6a0d9051185d 3398 d78899c654249f9070dea"' 3399 ]) / 3400 ] /, 3401 / manifest / 3:h'a601010203035860a20244818141000458568614a40150fa6 3402 b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab4503582 3403 48202582000112233445566778899aabbccddeeff0123456789abcdeffedcba9876543 3404 2100e1987d001f602f60958258613a115781b687474703a2f2f6578616d706c652e636 3405 f6d2f66696c652e62696e15f603f60a438203f60c438217f6' / { 3406 / manifest-version / 1:1, 3407 / manifest-sequence-number / 2:3, 3408 / common / 3:h'a20244818141000458568614a40150fa6b4a53d5ad5fdfb 3410 e9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab450358248202582000112 3411 233445566778899aabbccddeeff0123456789abcdeffedcba98765432100e1987d001f 3412 602f6' / { 3413 / components / 2:h'81814100' / [ 3414 [h'"00"'] 3415 ] /, 3416 / common-sequence / 4:h'8614a40150fa6b4a53d5ad5fdfbe9de663 3417 e4d41ffe02501492af1425695e48bf429b2d51f2ab4503582482025820001122334455 3418 66778899aabbccddeeff0123456789abcdeffedcba98765432100e1987d001f602f6' 3419 / [ 3420 / directive-override-parameters / 20,{ 3421 / vendor-id / 3422 1:h'"fa6b4a53d5ad5fdfbe9de663e4d41ffe"' / fa6b4a53-d5ad-5fdf- 3423 be9d-e663e4d41ffe /, 3424 / class-id / 3425 2:h'"1492af1425695e48bf429b2d51f2ab45"' / 3426 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 3427 / image-digest / 3:h'8202582000112233445566778899a 3428 abbccddeeff0123456789abcdeffedcba9876543210' / [ 3429 / algorithm-id / 2 / "sha256" /, 3430 / digest-bytes / 3431 h'"00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210"' 3432 ] /, 3433 / image-size / 14:34768, 3434 } , 3435 / condition-vendor-identifier / 1,F6 / nil / , 3436 / condition-class-identifier / 2,F6 / nil / 3437 ] /, 3438 } /, 3439 / install / 9:h'8613a115781b687474703a2f2f6578616d706c652e636f 3440 6d2f66696c652e62696e15f603f6' / [ 3441 / directive-set-parameters / 19,{ 3442 / uri / 21:'http://example.com/file.bin', 3443 } , 3444 / directive-fetch / 21,F6 / nil / , 3445 / condition-image-match / 3,F6 / nil / 3446 ] /, 3447 / validate / 10:h'8203f6' / [ 3448 / condition-image-match / 3,F6 / nil / 3449 ] /, 3450 / run / 12:h'8217f6' / [ 3451 / directive-run / 23,F6 / nil / 3452 ] /, 3453 } /, 3454 } 3456 Total size of manifest without COSE authentication object: 158 3457 Manifest: 3459 a103589aa601010203035860a20244818141000458568614a40150fa6b4a 3460 53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab 3461 450358248202582000112233445566778899aabbccddeeff0123456789ab 3462 cdeffedcba98765432100e1987d001f602f60958258613a115781b687474 3463 703a2f2f6578616d706c652e636f6d2f66696c652e62696e15f603f60a43 3464 8203f60c438217f6 3466 Total size of manifest with COSE authentication object: 275 3468 Manifest with COSE authentication object: 3470 a202587281586fd28443a10126a058248202582088390f8988639d8a2cfb 3471 6da969fce488333ac5ba77aaf0d66b5623009bbf341158401929ffd488c4 3472 55ab40eaf1aa96a7df4a9c16c658221055c3a113232fb81c5751a23a74b5 3473 efc06c459eb47a07028ef3c6a0d9051185dd78899c654249f9070dea0358 3474 9aa601010203035860a20244818141000458568614a40150fa6b4a53d5ad 3475 5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab450358 3476 248202582000112233445566778899aabbccddeeff0123456789abcdeffe 3477 dcba98765432100e1987d001f602f60958258613a115781b687474703a2f 3478 2f6578616d706c652e636f6d2f66696c652e62696e15f603f60a438203f6 3479 0c438217f6 3481 B.4. Example 3: Load from External Storage 3483 Compatibility test, simultaneous download and installation, load from 3484 external storage, and secure boot. 3486 { 3487 / authentication-wrapper / 2:h'81586fd28443a10126a0582482025820568 3488 56a72f9ac0ee73b4ea3a866cf2e5c990e8ed8c6056608bc221efd42172b2758402a9d7 3489 573ef6dcf5653b39027fdf87b81adeb0f03122bef0ecf5af9c7d77323c32827230f660 3490 8342b7bf5c125f17148bd67880420ab0d03e235e6ca1d15127499' / [ 3491 h'd28443a10126a058248202582056856a72f9ac0ee73b4ea3a866cf2e5c99 3492 0e8ed8c6056608bc221efd42172b2758402a9d7573ef6dcf5653b39027fdf87b81adeb 3493 0f03122bef0ecf5af9c7d77323c32827230f6608342b7bf5c125f17148bd67880420ab 3494 0d03e235e6ca1d15127499' / 18([ 3495 / protected / h'a10126' / { 3496 / alg / 1:-7 / "ES256" /, 3497 } /, 3498 / unprotected / { 3499 }, 3500 / payload / h'8202582056856a72f9ac0ee73b4ea3a866cf2e5c 3501 990e8ed8c6056608bc221efd42172b27' / [ 3502 / algorithm-id / 2 / "sha256" /, 3503 / digest-bytes / 3504 h'"56856a72f9ac0ee73b4ea3a866cf2e5c990e8ed8c6056608bc221efd42172b27"' 3505 ] /, 3506 / signature / h'"2a9d7573ef6dcf5653b39027fdf87b81adeb0 3507 f03122bef0ecf5af9c7d77323c32827230f6608342b7bf5c125f17148bd67880420ab0 3508 d03e235e6ca1d15127499"' 3509 ]) / 3510 ] /, 3511 / manifest / 3:h'a701010204035865a2024782814100814101045858880c001 3512 4a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f 3513 2ab450358248202582000112233445566778899aabbccddeeff0123456789abcdeffed 3514 cba98765432100e1987d001f602f6095827880c0013a115781b687474703a2f2f65786 3515 16d706c652e636f6d2f66696c652e62696e15f603f60a45840c0003f60b4b880c0113a 3516 1160016f603f60c45840c0117f6' / { 3517 / manifest-version / 1:1, 3518 / manifest-sequence-number / 2:4, 3519 / common / 3:h'a2024782814100814101045858880c0014a40150fa6b4a5 3520 3d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab45035824820 3521 2582000112233445566778899aabbccddeeff0123456789abcdeffedcba98765432100 3522 e1987d001f602f6' / { 3523 / components / 2:h'82814100814101' / [ 3524 [h'"00"'] , 3525 [h'"01"'] 3526 ] /, 3527 / common-sequence / 4:h'880c0014a40150fa6b4a53d5ad5fdfbe9d 3528 e663e4d41ffe02501492af1425695e48bf429b2d51f2ab450358248202582000112233 3529 445566778899aabbccddeeff0123456789abcdeffedcba98765432100e1987d001f602 3530 f6' / [ 3531 / directive-set-component-index / 12,0 , 3532 / directive-override-parameters / 20,{ 3533 / vendor-id / 3534 1:h'"fa6b4a53d5ad5fdfbe9de663e4d41ffe"' / fa6b4a53-d5ad-5fdf- 3535 be9d-e663e4d41ffe /, 3536 / class-id / 3537 2:h'"1492af1425695e48bf429b2d51f2ab45"' / 3538 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 3539 / image-digest / 3:h'8202582000112233445566778899a 3540 abbccddeeff0123456789abcdeffedcba9876543210' / [ 3541 / algorithm-id / 2 / "sha256" /, 3542 / digest-bytes / 3543 h'"00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210"' 3544 ] /, 3545 / image-size / 14:34768, 3546 } , 3547 / condition-vendor-identifier / 1,F6 / nil / , 3548 / condition-class-identifier / 2,F6 / nil / 3549 ] /, 3550 } /, 3551 / install / 9:h'880c0013a115781b687474703a2f2f6578616d706c652e 3552 636f6d2f66696c652e62696e15f603f6' / [ 3553 / directive-set-component-index / 12,0 , 3554 / directive-set-parameters / 19,{ 3555 / uri / 21:'http://example.com/file.bin', 3556 } , 3557 / directive-fetch / 21,F6 / nil / , 3558 / condition-image-match / 3,F6 / nil / 3559 ] /, 3560 / validate / 10:h'840c0003f6' / [ 3561 / directive-set-component-index / 12,0 , 3562 / condition-image-match / 3,F6 / nil / 3563 ] /, 3564 / load / 11:h'880c0113a1160016f603f6' / [ 3565 / directive-set-component-index / 12,1 , 3566 / directive-set-parameters / 19,{ 3567 / source-component / 22:0 / [h'"00"'] /, 3568 } , 3569 / directive-copy / 22,F6 / nil / , 3570 / condition-image-match / 3,F6 / nil / 3571 ] /, 3572 / run / 12:h'840c0117f6' / [ 3573 / directive-set-component-index / 12,1 , 3574 / directive-run / 23,F6 / nil / 3575 ] /, 3576 } /, 3577 } 3579 Total size of manifest without COSE authentication object: 182 3581 Manifest: 3583 a10358b2a701010204035865a2024782814100814101045858880c0014a4 3584 0150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf42 3585 9b2d51f2ab450358248202582000112233445566778899aabbccddeeff01 3586 23456789abcdeffedcba98765432100e1987d001f602f6095827880c0013 3587 a115781b687474703a2f2f6578616d706c652e636f6d2f66696c652e6269 3588 6e15f603f60a45840c0003f60b4b880c0113a1160016f603f60c45840c01 3589 17f6 3591 Total size of manifest with COSE authentication object: 299 3593 Manifest with COSE authentication object: 3595 a202587281586fd28443a10126a058248202582056856a72f9ac0ee73b4e 3596 a3a866cf2e5c990e8ed8c6056608bc221efd42172b2758402a9d7573ef6d 3597 cf5653b39027fdf87b81adeb0f03122bef0ecf5af9c7d77323c32827230f 3598 6608342b7bf5c125f17148bd67880420ab0d03e235e6ca1d151274990358 3599 b2a701010204035865a2024782814100814101045858880c0014a40150fa 3600 6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51 3601 f2ab450358248202582000112233445566778899aabbccddeeff01234567 3602 89abcdeffedcba98765432100e1987d001f602f6095827880c0013a11578 3603 1b687474703a2f2f6578616d706c652e636f6d2f66696c652e62696e15f6 3604 03f60a45840c0003f60b4b880c0113a1160016f603f60c45840c0117f6 3606 B.5. Example 4: Load and Decompress from External Storage 3608 Compatibility test, simultaneous download and installation, load and 3609 decompress from external storage, and secure boot. 3611 { 3612 / authentication-wrapper / 2:h'81586fd28443a10126a058248202582057b 3613 edc0076919ba83908365faf6d205e95c71268d29a94dc5e82698edd3a48225840e0a4d 3614 c500266518742802f2364b65f983175f060c1555d3d0b186f447500ba60c66e3231674 3615 1c3b642c68fed73d47542c3375c0ab72e0f4b94ec392ab398599d' / [ 3616 h'd28443a10126a058248202582057bedc0076919ba83908365faf6d205e95 3617 c71268d29a94dc5e82698edd3a48225840e0a4dc500266518742802f2364b65f983175 3618 f060c1555d3d0b186f447500ba60c66e32316741c3b642c68fed73d47542c3375c0ab7 3619 2e0f4b94ec392ab398599d' / 18([ 3620 / protected / h'a10126' / { 3621 / alg / 1:-7 / "ES256" /, 3622 } /, 3623 / unprotected / { 3624 }, 3625 / payload / h'8202582057bedc0076919ba83908365faf6d205e 3626 95c71268d29a94dc5e82698edd3a4822' / [ 3627 / algorithm-id / 2 / "sha256" /, 3628 / digest-bytes / 3629 h'"57bedc0076919ba83908365faf6d205e95c71268d29a94dc5e82698edd3a4822"' 3630 ] /, 3631 / signature / h'"e0a4dc500266518742802f2364b65f983175f 3632 060c1555d3d0b186f447500ba60c66e32316741c3b642c68fed73d47542c3375c0ab72 3633 e0f4b94ec392ab398599d"' 3634 ]) / 3635 ] /, 3636 / manifest / 3:h'a701010205035865a2024782814100814101045858880c001 3637 4a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f 3638 2ab450358248202582000112233445566778899aabbccddeeff0123456789abcdeffed 3639 cba98765432100e1987d001f602f6095827880c0013a115781b687474703a2f2f65786 3640 16d706c652e636f6d2f66696c652e62696e15f603f60a45840c0003f60b4d880c0113a 3641 21301160016f603f60c45840c0117f6' / { 3642 / manifest-version / 1:1, 3643 / manifest-sequence-number / 2:5, 3644 / common / 3:h'a2024782814100814101045858880c0014a40150fa6b4a5 3645 3d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab45035824820 3646 2582000112233445566778899aabbccddeeff0123456789abcdeffedcba98765432100 3647 e1987d001f602f6' / { 3648 / components / 2:h'82814100814101' / [ 3649 [h'"00"'] , 3650 [h'"01"'] 3651 ] /, 3652 / common-sequence / 4:h'880c0014a40150fa6b4a53d5ad5fdfbe9d 3653 e663e4d41ffe02501492af1425695e48bf429b2d51f2ab450358248202582000112233 3654 445566778899aabbccddeeff0123456789abcdeffedcba98765432100e1987d001f602 3655 f6' / [ 3656 / directive-set-component-index / 12,0 , 3657 / directive-override-parameters / 20,{ 3658 / vendor-id / 3659 1:h'"fa6b4a53d5ad5fdfbe9de663e4d41ffe"' / fa6b4a53-d5ad-5fdf- 3660 be9d-e663e4d41ffe /, 3661 / class-id / 3662 2:h'"1492af1425695e48bf429b2d51f2ab45"' / 3663 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 3664 / image-digest / 3:h'8202582000112233445566778899a 3665 abbccddeeff0123456789abcdeffedcba9876543210' / [ 3666 / algorithm-id / 2 / "sha256" /, 3667 / digest-bytes / 3668 h'"00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210"' 3669 ] /, 3670 / image-size / 14:34768, 3671 } , 3672 / condition-vendor-identifier / 1,F6 / nil / , 3673 / condition-class-identifier / 2,F6 / nil / 3674 ] /, 3675 } /, 3676 / install / 9:h'880c0013a115781b687474703a2f2f6578616d706c652e 3677 636f6d2f66696c652e62696e15f603f6' / [ 3678 / directive-set-component-index / 12,0 , 3679 / directive-set-parameters / 19,{ 3680 / uri / 21:'http://example.com/file.bin', 3681 } , 3682 / directive-fetch / 21,F6 / nil / , 3683 / condition-image-match / 3,F6 / nil / 3684 ] /, 3685 / validate / 10:h'840c0003f6' / [ 3686 / directive-set-component-index / 12,0 , 3687 / condition-image-match / 3,F6 / nil / 3688 ] /, 3689 / load / 11:h'880c0113a21301160016f603f6' / [ 3690 / directive-set-component-index / 12,1 , 3691 / directive-set-parameters / 19,{ 3692 / source-component / 22:0 / [h'"00"'] /, 3693 / compression-info / 19:1 / "gzip" /, 3694 } , 3695 / directive-copy / 22,F6 / nil / , 3696 / condition-image-match / 3,F6 / nil / 3697 ] /, 3698 / run / 12:h'840c0117f6' / [ 3699 / directive-set-component-index / 12,1 , 3700 / directive-run / 23,F6 / nil / 3701 ] /, 3702 } /, 3703 } 3705 Total size of manifest without COSE authentication object: 184 3707 Manifest: 3709 a10358b4a701010205035865a2024782814100814101045858880c0014a4 3710 0150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf42 3711 9b2d51f2ab450358248202582000112233445566778899aabbccddeeff01 3712 23456789abcdeffedcba98765432100e1987d001f602f6095827880c0013 3713 a115781b687474703a2f2f6578616d706c652e636f6d2f66696c652e6269 3714 6e15f603f60a45840c0003f60b4d880c0113a21301160016f603f60c4584 3715 0c0117f6 3717 Total size of manifest with COSE authentication object: 301 3719 Manifest with COSE authentication object: 3721 a202587281586fd28443a10126a058248202582057bedc0076919ba83908 3722 365faf6d205e95c71268d29a94dc5e82698edd3a48225840e0a4dc500266 3723 518742802f2364b65f983175f060c1555d3d0b186f447500ba60c66e3231 3724 6741c3b642c68fed73d47542c3375c0ab72e0f4b94ec392ab398599d0358 3725 b4a701010205035865a2024782814100814101045858880c0014a40150fa 3726 6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51 3727 f2ab450358248202582000112233445566778899aabbccddeeff01234567 3728 89abcdeffedcba98765432100e1987d001f602f6095827880c0013a11578 3729 1b687474703a2f2f6578616d706c652e636f6d2f66696c652e62696e15f6 3730 03f60a45840c0003f60b4d880c0113a21301160016f603f60c45840c0117 3731 f6 3733 B.6. Example 5: Compatibility Test, Download, Installation, and Secure 3734 Boot 3736 Compatibility test, download, installation, and secure boot. 3738 { 3739 / authentication-wrapper / 2:h'81586fd28443a10126a0582482025820ecc 3740 95235f2ab00b9912f8189b213b3e4ade42b792f491644e76004cd2ba87dc8584093952 3741 6b77d63dac2e138bf074aac757c5f010e8b2cf3ae9fcbba4cafc2d0f81c9ae46bc973c 3742 c0565410a1cb6bf10d2b3d0a2865392255cc4288d0337af3de837' / [ 3743 h'd28443a10126a0582482025820ecc95235f2ab00b9912f8189b213b3e4ad 3744 e42b792f491644e76004cd2ba87dc85840939526b77d63dac2e138bf074aac757c5f01 3745 0e8b2cf3ae9fcbba4cafc2d0f81c9ae46bc973cc0565410a1cb6bf10d2b3d0a2865392 3746 255cc4288d0337af3de837' / 18([ 3747 / protected / h'a10126' / { 3748 / alg / 1:-7 / "ES256" /, 3749 } /, 3750 / unprotected / { 3751 }, 3752 / payload / h'82025820ecc95235f2ab00b9912f8189b213b3e4 3753 ade42b792f491644e76004cd2ba87dc8' / [ 3754 / algorithm-id / 2 / "sha256" /, 3755 / digest-bytes / 3756 h'"ecc95235f2ab00b9912f8189b213b3e4ade42b792f491644e76004cd2ba87dc8"' 3757 ] /, 3758 / signature / h'"939526b77d63dac2e138bf074aac757c5f010 3759 e8b2cf3ae9fcbba4cafc2d0f81c9ae46bc973cc0565410a1cb6bf10d2b3d0a28653922 3760 55cc4288d0337af3de837"' 3761 ]) / 3762 ] /, 3763 / manifest / 3:h'a701010205035865a2024782814100814101045858880c001 3764 4a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f 3765 2ab450358248202582000112233445566778899aabbccddeeff0123456789abcdeffed 3766 cba98765432100e1987d001f602f6085823840c0113a115781b687474703a2f2f65786 3767 16d706c652e636f6d2f66696c652e62696e094b880c0013a1160116f603f60a45840c0 3768 003f60c45840c0017f6' / { 3769 / manifest-version / 1:1, 3770 / manifest-sequence-number / 2:5, 3771 / common / 3:h'a2024782814100814101045858880c0014a40150fa6b4a5 3772 3d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab45035824820 3773 2582000112233445566778899aabbccddeeff0123456789abcdeffedcba98765432100 3774 e1987d001f602f6' / { 3775 / components / 2:h'82814100814101' / [ 3776 [h'"00"'] , 3777 [h'"01"'] 3778 ] /, 3779 / common-sequence / 4:h'880c0014a40150fa6b4a53d5ad5fdfbe9d 3780 e663e4d41ffe02501492af1425695e48bf429b2d51f2ab450358248202582000112233 3781 445566778899aabbccddeeff0123456789abcdeffedcba98765432100e1987d001f602 3782 f6' / [ 3783 / directive-set-component-index / 12,0 , 3784 / directive-override-parameters / 20,{ 3785 / vendor-id / 3786 1:h'"fa6b4a53d5ad5fdfbe9de663e4d41ffe"' / fa6b4a53-d5ad-5fdf- 3787 be9d-e663e4d41ffe /, 3788 / class-id / 3789 2:h'"1492af1425695e48bf429b2d51f2ab45"' / 3790 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 3791 / image-digest / 3:h'8202582000112233445566778899a 3792 abbccddeeff0123456789abcdeffedcba9876543210' / [ 3793 / algorithm-id / 2 / "sha256" /, 3794 / digest-bytes / 3795 h'"00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210"' 3796 ] /, 3797 / image-size / 14:34768, 3798 } , 3799 / condition-vendor-identifier / 1,F6 / nil / , 3800 / condition-class-identifier / 2,F6 / nil / 3801 ] /, 3802 } /, 3803 / payload-fetch / 8:h'840c0113a115781b687474703a2f2f6578616d70 3804 6c652e636f6d2f66696c652e62696e' / [ 3805 / directive-set-component-index / 12,1 , 3806 / directive-set-parameters / 19,{ 3807 / uri / 21:'http://example.com/file.bin', 3808 } 3809 ] /, 3810 / install / 9:h'880c0013a1160116f603f6' / [ 3811 / directive-set-component-index / 12,0 , 3812 / directive-set-parameters / 19,{ 3813 / source-component / 22:1 / [h'"01"'] /, 3814 } , 3815 / directive-copy / 22,F6 / nil / , 3816 / condition-image-match / 3,F6 / nil / 3817 ] /, 3818 / validate / 10:h'840c0003f6' / [ 3819 / directive-set-component-index / 12,0 , 3820 / condition-image-match / 3,F6 / nil / 3821 ] /, 3822 / run / 12:h'840c0017f6' / [ 3823 / directive-set-component-index / 12,0 , 3824 / directive-run / 23,F6 / nil / 3825 ] /, 3826 } /, 3827 } 3829 Total size of manifest without COSE authentication object: 178 3831 Manifest: 3833 a10358aea701010205035865a2024782814100814101045858880c0014a4 3834 0150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf42 3835 9b2d51f2ab450358248202582000112233445566778899aabbccddeeff01 3836 23456789abcdeffedcba98765432100e1987d001f602f6085823840c0113 3837 a115781b687474703a2f2f6578616d706c652e636f6d2f66696c652e6269 3838 6e094b880c0013a1160116f603f60a45840c0003f60c45840c0017f6 3840 Total size of manifest with COSE authentication object: 295 3842 Manifest with COSE authentication object: 3844 a202587281586fd28443a10126a0582482025820ecc95235f2ab00b9912f 3845 8189b213b3e4ade42b792f491644e76004cd2ba87dc85840939526b77d63 3846 dac2e138bf074aac757c5f010e8b2cf3ae9fcbba4cafc2d0f81c9ae46bc9 3847 73cc0565410a1cb6bf10d2b3d0a2865392255cc4288d0337af3de8370358 3848 aea701010205035865a2024782814100814101045858880c0014a40150fa 3849 6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51 3850 f2ab450358248202582000112233445566778899aabbccddeeff01234567 3851 89abcdeffedcba98765432100e1987d001f602f6085823840c0113a11578 3852 1b687474703a2f2f6578616d706c652e636f6d2f66696c652e62696e094b 3853 880c0013a1160116f603f60a45840c0003f60c45840c0017f6 3855 B.7. Example 6: Two Images 3857 Compatibility test, 2 images, simultaneous download and installation, 3858 and secure boot. 3860 { 3861 / authentication-wrapper / 2:h'81586fd28443a10126a0582482025820732 3862 5a7d3acf130d161810c4874f275f658970b7bc5a63cda56e9920a4aaba3a3584088cb9 3863 6211bcc4cdb59cb0022cb213017b2d117bac1a5460ae92903acc196282f7888368bf0a 3864 065756e43f53cdbeee367e9523312063e8eaad0889a7cee371859' / [ 3865 h'd28443a10126a05824820258207325a7d3acf130d161810c4874f275f658 3866 970b7bc5a63cda56e9920a4aaba3a3584088cb96211bcc4cdb59cb0022cb213017b2d1 3867 17bac1a5460ae92903acc196282f7888368bf0a065756e43f53cdbeee367e952331206 3868 3e8eaad0889a7cee371859' / 18([ 3869 / protected / h'a10126' / { 3870 / alg / 1:-7 / "ES256" /, 3871 } /, 3872 / unprotected / { 3873 }, 3874 / payload / h'820258207325a7d3acf130d161810c4874f275f6 3875 58970b7bc5a63cda56e9920a4aaba3a3' / [ 3876 / algorithm-id / 2 / "sha256" /, 3877 / digest-bytes / 3878 h'"7325a7d3acf130d161810c4874f275f658970b7bc5a63cda56e9920a4aaba3a3"' 3879 ] /, 3880 / signature / h'"88cb96211bcc4cdb59cb0022cb213017b2d11 3882 7bac1a5460ae92903acc196282f7888368bf0a065756e43f53cdbeee367e9523312063 3883 e8eaad0889a7cee371859"' 3884 ]) / 3885 ] /, 3886 / manifest / 3:h'a50101020303589da20244818141000458938814a20150fa6 3887 b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab450f825 3888 8308405f614a20358248202582000112233445566778899aabbccddeeff0123456789a 3889 bcdeffedcba98765432100e1987d058328405f614a2035824820258200123456789abc 3890 deffedcba987654321000112233445566778899aabbccddeeff0e1a00012c2201f602f 3891 6095853860f8258248405f613a115781c687474703a2f2f6578616d706c652e636f6d2 3892 f66696c65312e62696e58248405f613a115781c687474703a2f2f6578616d706c652e6 3893 36f6d2f66696c65322e62696e15f603f60a438203f6' / { 3894 / manifest-version / 1:1, 3895 / manifest-sequence-number / 2:3, 3896 / common / 3:h'a20244818141000458938814a20150fa6b4a53d5ad5fdfb 3897 e9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab450f8258308405f614a20 3898 358248202582000112233445566778899aabbccddeeff0123456789abcdeffedcba987 3899 65432100e1987d058328405f614a2035824820258200123456789abcdeffedcba98765 3900 4321000112233445566778899aabbccddeeff0e1a00012c2201f602f6' / { 3901 / components / 2:h'81814100' / [ 3902 [h'"00"'] 3903 ] /, 3904 / common-sequence / 4:h'8814a20150fa6b4a53d5ad5fdfbe9de663 3905 e4d41ffe02501492af1425695e48bf429b2d51f2ab450f8258308405f614a203582482 3906 02582000112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210 3907 0e1987d058328405f614a2035824820258200123456789abcdeffedcba987654321000 3908 112233445566778899aabbccddeeff0e1a00012c2201f602f6' / [ 3909 / directive-override-parameters / 20,{ 3910 / vendor-id / 3911 1:h'"fa6b4a53d5ad5fdfbe9de663e4d41ffe"' / fa6b4a53-d5ad-5fdf- 3912 be9d-e663e4d41ffe /, 3913 / class-id / 3914 2:h'"1492af1425695e48bf429b2d51f2ab45"' / 3915 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 3916 } , 3917 / directive-try-each / 15,[ 3918 h'8405f614a20358248202582000112233445566778899aabb 3919 ccddeeff0123456789abcdeffedcba98765432100e1987d0' / [ 3920 / condition-component-offset / 5,F6 / nil / , 3921 / directive-override-parameters / 20,{ 3922 / image-digest / 3:h'820258200011223344556 3923 6778899aabbccddeeff0123456789abcdeffedcba9876543210' / [ 3924 / algorithm-id / 2 / "sha256" /, 3925 / digest-bytes / 3926 h'"00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210"' 3927 ] /, 3928 / image-size / 14:34768, 3929 } 3931 ] / , 3932 h'8405f614a2035824820258200123456789abcdeffedcba98 3933 7654321000112233445566778899aabbccddeeff0e1a00012c22' / [ 3934 / condition-component-offset / 5,F6 / nil / , 3935 / directive-override-parameters / 20,{ 3936 / image-digest / 3:h'820258200123456789abc 3937 deffedcba987654321000112233445566778899aabbccddeeff' / [ 3938 / algorithm-id / 2 / "sha256" /, 3939 / digest-bytes / 3940 h'"0123456789abcdeffedcba987654321000112233445566778899aabbccddeeff"' 3941 ] /, 3942 / image-size / 14:76834, 3943 } 3944 ] / 3945 ] , 3946 / condition-vendor-identifier / 1,F6 / nil / , 3947 / condition-class-identifier / 2,F6 / nil / 3948 ] /, 3949 } /, 3950 / install / 9:h'860f8258248405f613a115781c687474703a2f2f657861 3951 6d706c652e636f6d2f66696c65312e62696e58248405f613a115781c687474703a2f2f 3952 6578616d706c652e636f6d2f66696c65322e62696e15f603f6' / [ 3953 / directive-try-each / 15,[ 3954 h'8405f613a115781c687474703a2f2f6578616d706c652e636f6d 3955 2f66696c65312e62696e' / [ 3956 / condition-component-offset / 5,F6 / nil / , 3957 / directive-set-parameters / 19,{ 3958 / uri / 21:'http://example.com/file1.bin', 3959 } 3960 ] / , 3961 h'8405f613a115781c687474703a2f2f6578616d706c652e636f6d 3962 2f66696c65322e62696e' / [ 3963 / condition-component-offset / 5,F6 / nil / , 3964 / directive-set-parameters / 19,{ 3965 / uri / 21:'http://example.com/file2.bin', 3966 } 3967 ] / 3968 ] , 3969 / directive-fetch / 21,F6 / nil / , 3970 / condition-image-match / 3,F6 / nil / 3971 ] /, 3972 / validate / 10:h'8203f6' / [ 3973 / condition-image-match / 3,F6 / nil / 3974 ] /, 3975 } /, 3976 } 3978 Total size of manifest without COSE authentication object: 261 3979 Manifest: 3981 a103590100a50101020303589da20244818141000458938814a20150fa6b 3982 4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2 3983 ab450f8258308405f614a20358248202582000112233445566778899aabb 3984 ccddeeff0123456789abcdeffedcba98765432100e1987d058328405f614 3985 a2035824820258200123456789abcdeffedcba9876543210001122334455 3986 66778899aabbccddeeff0e1a00012c2201f602f6095853860f8258248405 3987 f613a115781c687474703a2f2f6578616d706c652e636f6d2f66696c6531 3988 2e62696e58248405f613a115781c687474703a2f2f6578616d706c652e63 3989 6f6d2f66696c65322e62696e15f603f60a438203f6 3991 Total size of manifest with COSE authentication object: 378 3993 Manifest with COSE authentication object: 3995 a202587281586fd28443a10126a05824820258207325a7d3acf130d16181 3996 0c4874f275f658970b7bc5a63cda56e9920a4aaba3a3584088cb96211bcc 3997 4cdb59cb0022cb213017b2d117bac1a5460ae92903acc196282f7888368b 3998 f0a065756e43f53cdbeee367e9523312063e8eaad0889a7cee3718590359 3999 0100a50101020303589da20244818141000458938814a20150fa6b4a53d5 4000 ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab450f 4001 8258308405f614a20358248202582000112233445566778899aabbccddee 4002 ff0123456789abcdeffedcba98765432100e1987d058328405f614a20358 4003 24820258200123456789abcdeffedcba9876543210001122334455667788 4004 99aabbccddeeff0e1a00012c2201f602f6095853860f8258248405f613a1 4005 15781c687474703a2f2f6578616d706c652e636f6d2f66696c65312e6269 4006 6e58248405f613a115781c687474703a2f2f6578616d706c652e636f6d2f 4007 66696c65322e62696e15f603f60a438203f6 4009 C. Design Rational 4011 In order to provide flexible behavior to constrained devices, while 4012 still allowing more powerful devices to use their full capabilities, 4013 the SUIT manifest encodes the required behavior of a Recipient 4014 device. Behavior is encoded as a specialized byte code, contained in 4015 a CBOR list. This promotes a flat encoding, which simplifies the 4016 parser. The information encoded by this byte code closely matches 4017 the operations that a device will perform, which promotes ease of 4018 processing. The core operations used by most update and trusted 4019 execution operations are represented in the byte code. The byte code 4020 can be extended by registering new operations. 4022 The specialized byte code approach gives benefits equivalent to those 4023 provided by a scripting language or conventional byte code, with two 4024 substantial differences. First, the language is extremely high 4025 level, consisting of only the operations that a device may perform 4026 during update and trusted execution of a firmware image. Second, the 4027 language specifies linear behavior, without reverse branches. 4028 Conditional processing is supported, and parallel and out-of-order 4029 processing may be performed by sufficiently capable devices. 4031 By structuring the data in this way, the manifest processor becomes a 4032 very simple engine that uses a pull parser to interpret the manifest. 4033 This pull parser invokes a series of command handlers that evaluate a 4034 Condition or execute a Directive. Most data is structured in a 4035 highly regular pattern, which simplifies the parser. 4037 The results of this allow a Recipient to implement a very small 4038 parser for constrained applications. If needed, such a parser also 4039 allows the Recipient to perform complex updates with reduced 4040 overhead. Conditional execution of commands allows a simple device 4041 to perform important decisions at validation-time. 4043 Dependency handling is vastly simplified as well. Dependencies 4044 function like subroutines of the language. When a manifest has a 4045 dependency, it can invoke that dependency's commands and modify their 4046 behavior by setting parameters. Because some parameters come with 4047 security implications, the dependencies also have a mechanism to 4048 reject modifications to parameters on a fine-grained level. 4050 Developing a robust permissions system works in this model too. The 4051 Recipient can use a simple ACL that is a table of Identities and 4052 Component Identifier permissions to ensure that operations on 4053 components fail unless they are permitted by the ACL. This table can 4054 be further refined with individual parameters and commands. 4056 Capability reporting is similarly simplified. A Recipient can report 4057 the Commands, Parameters, Algorithms, and Component Identifiers that 4058 it supports. This is sufficiently precise for a manifest author to 4059 create a manifest that the Recipient can accept. 4061 The simplicity of design in the Recipient due to all of these 4062 benefits allows even a highly constrained platform to use advanced 4063 update capabilities. 4065 D. Implementation Confirmance Matrix 4067 This section summarizes the functionality a minimal implementation 4068 needs to offer to claim conformance to this specification. 4070 The subsequent table shows the conditions. 4072 +-------------------+------------------+----------------+ 4073 | Name | Reference | Implementation | 4074 +-------------------+------------------+----------------+ 4075 | Vendor Identifier | Section 9.12.1.1 | REQUIRED | 4076 | | | | 4077 | Class Identifier | Section 9.12.1.1 | REQUIRED | 4078 | | | | 4079 | Device Identifier | Section 9.12.1.1 | OPTIONAL | 4080 | | | | 4081 | Image Match | Section 9.12.1.2 | REQUIRED | 4082 | | | | 4083 | Image Not Match | Section 9.12.1.3 | OPTIONAL | 4084 | | | | 4085 | Use Before | Section 9.12.1.4 | OPTIONAL | 4086 | | | | 4087 | Component Offset | Section 9.12.1.5 | OPTIONAL | 4088 | | | | 4089 | Minimum Battery | Section 9.12.1.6 | OPTIONAL | 4090 | | | | 4091 | Update Authorized | Section 9.12.1.7 | OPTIONAL | 4092 | | | | 4093 | Version | Section 9.12.1.8 | OPTIONAL | 4094 | | | | 4095 | Custom Condition | Section 9.12.1.9 | OPTIONAL | 4096 +-------------------+------------------+----------------+ 4098 The subsequent table shows the directives. 4100 +-------------------+---------------+-------------------------------+ 4101 | Name | Reference | Implementation | 4102 +-------------------+---------------+-------------------------------+ 4103 | Set Component | Section | REQUIRED if more than one | 4104 | Index | 9.12.3 | component | 4105 | | | | 4106 | Set Dependency | Section | REQUIRED if dependencies used | 4107 | Index | 9.12.4 | | 4108 | | | | 4109 | Abort | Section | OPTIONAL | 4110 | | 9.12.5 | | 4111 | | | | 4112 | Try Each | Section | OPTIONAL | 4113 | | 9.12.6 | | 4114 | | | | 4115 | Process | Section | OPTIONAL | 4116 | Dependency | 9.12.7 | | 4117 | | | | 4118 | Set Parameters | Section | OPTIONAL | 4119 | | 9.12.8 | | 4120 | | | | 4121 | Override | Section | REQUIRED | 4122 | Parameters | 9.12.9 | | 4123 | | | | 4124 | Fetch | Section | REQUIRED for Updater | 4125 | | 9.12.10 | | 4126 | | | | 4127 | Copy | Section | OPTIONAL | 4128 | | 9.12.11 | | 4129 | | | | 4130 | Run | Section | REQUIRED for Bootloader | 4131 | | 9.12.12 | | 4132 | | | | 4133 | Wait For Event | Section | OPTIONAL | 4134 | | 9.12.13 | | 4135 | | | | 4136 | Run Sequence | Section | OPTIONAL | 4137 | | 9.12.14 | | 4138 | | | | 4139 | Swap | Section | OPTIONAL | 4140 | | 9.12.15 | | 4141 +-------------------+---------------+-------------------------------+ 4143 TThe subsequent table shows the parameters 4144 +------------------+-----------------+----------------+ 4145 | Name | Reference | Implementation | 4146 +------------------+-----------------+----------------+ 4147 | Vendor ID | Section 9.11.1 | TBD | 4148 | | | | 4149 | Class ID | Section 9.11.2 | TBD | 4150 | | | | 4151 | Image Digest | Section 9.11.3 | TBD | 4152 | | | | 4153 | Image Size | Section 9.11.4 | TBD | 4154 | | | | 4155 | Use Before | Section 9.11.5 | TBD | 4156 | | | | 4157 | Component Offset | Section 9.11.6 | TBD | 4158 | | | | 4159 | Encryption Info | Section 9.11.7 | TBD | 4160 | | | | 4161 | Compression Info | Section 9.11.8 | TBD | 4162 | | | | 4163 | Unpack Info | Section 9.11.9 | TBD | 4164 | | | | 4165 | URI | Section 9.11.10 | TBD | 4166 | | | | 4167 | Source Component | Section 9.11.11 | TBD | 4168 | | | | 4169 | Run Args | Section 9.11.12 | TBD | 4170 | | | | 4171 | Device ID | Section 9.11.13 | TBD | 4172 | | | | 4173 | Minimum Battery | Section 9.11.14 | TBD | 4174 | | | | 4175 | Update Priority | Section 9.11.15 | TBD | 4176 | | | | 4177 | Version | Section 9.11.16 | TBD | 4178 | | | | 4179 | Wait Info | Section 9.11.17 | TBD | 4180 | | | | 4181 | URI List | Section 9.11.18 | TBD | 4182 | | | | 4183 | Strict Order | Section 9.11.19 | TBD | 4184 | | | | 4185 | Soft Failure | Section 9.11.20 | TBD | 4186 | | | | 4187 | Custom | Section 9.11.21 | TBD | 4188 +------------------+-----------------+----------------+ 4190 Authors' Addresses 4192 Brendan Moran 4193 Arm Limited 4195 EMail: Brendan.Moran@arm.com 4197 Hannes Tschofenig 4198 Arm Limited 4200 EMail: hannes.tschofenig@arm.com 4202 Henk Birkholz 4203 Fraunhofer SIT 4205 EMail: henk.birkholz@sit.fraunhofer.de 4207 Koen Zandberg 4208 Inria 4210 EMail: koen.zandberg@inria.fr