idnits 2.17.00 (12 Aug 2021) /tmp/idnits46921/draft-ietf-suit-manifest-04.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 : ---------------------------------------------------------------------------- No issues found here. 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 (March 09, 2020) is 802 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 3925 -- Looks like a reference, but probably isn't: '2' on line 3927 -- Looks like a reference, but probably isn't: '3' on line 3929 == Missing Reference: '-1' is mentioned on line 1917, but not defined == Missing Reference: '-2' is mentioned on line 1919, but not defined == Missing Reference: '-3' is mentioned on line 1923, but not defined -- Looks like a reference, but probably isn't: '4' on line 1923 == Outdated reference: draft-ietf-suit-architecture has been published as RFC 9019 == Outdated reference: draft-ietf-suit-information-model has been published as RFC 9124 Summary: 0 errors (**), 0 flaws (~~), 7 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: September 10, 2020 H. Birkholz 6 Fraunhofer SIT 7 K. Zandberg 8 Inria 9 March 09, 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-04 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 trusted 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. 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at https://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on September 10, 2020. 42 Copyright Notice 44 Copyright (c) 2020 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (https://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 This document may contain material from IETF Documents or IETF 58 Contributions published or made publicly available before November 59 10, 2008. The person(s) controlling the copyright in some of this 60 material may not have granted the IETF Trust the right to allow 61 modifications of such material outside the IETF Standards Process. 62 Without obtaining an adequate license from the person(s) controlling 63 the copyright in such materials, this document may not be modified 64 outside the IETF Standards Process, and derivative works of it may 65 not be created outside the IETF Standards Process, except to format 66 it for publication as an RFC or to translate it into languages other 67 than English. 69 Table of Contents 71 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 72 2. Conventions and Terminology . . . . . . . . . . . . . . . . . 5 73 3. How to use this Document . . . . . . . . . . . . . . . . . . 6 74 4. Background . . . . . . . . . . . . . . . . . . . . . . . . . 6 75 4.1. IoT Firmware Update Constraints . . . . . . . . . . . . . 7 76 4.2. Update Workflow Model . . . . . . . . . . . . . . . . . . 7 77 4.2.1. Pre-Authentication Compatibility Checks . . . . . . . 9 78 4.3. SUIT Manifest Goals . . . . . . . . . . . . . . . . . . . 9 79 4.4. SUIT Manifest Design Summary . . . . . . . . . . . . . . 10 80 5. Interpreter Behavior . . . . . . . . . . . . . . . . . . . . 11 81 5.1. Interpreter Setup . . . . . . . . . . . . . . . . . . . . 11 82 5.2. Required Checks . . . . . . . . . . . . . . . . . . . . . 12 83 5.3. Interpreter Fundamental Properties . . . . . . . . . . . 13 84 5.4. Abstract Machine Description . . . . . . . . . . . . . . 13 85 5.4.1. Parameters . . . . . . . . . . . . . . . . . . . . . 14 86 5.4.2. Commands . . . . . . . . . . . . . . . . . . . . . . 15 87 5.4.3. Command Behavior . . . . . . . . . . . . . . . . . . 16 88 5.5. Serialized Processing Interpreter . . . . . . . . . . . . 17 89 5.6. Parallel Processing Interpreter . . . . . . . . . . . . . 17 90 5.7. Processing Dependencies . . . . . . . . . . . . . . . . . 18 91 6. Creating Manifests . . . . . . . . . . . . . . . . . . . . . 18 92 6.1. Manifest Source Material . . . . . . . . . . . . . . . . 19 93 6.2. Required Template: Compatibility Check . . . . . . . . . 19 94 6.3. Use Case Template: XIP Secure Boot . . . . . . . . . . . 20 95 6.4. Use Case Template: Firmware Download . . . . . . . . . . 21 96 6.5. Use Case Template: Load from External Storage . . . . . . 21 97 6.6. Use Case Template Load & Decompress from External Storage 21 98 6.7. Use Case Template: Dependency . . . . . . . . . . . . . . 22 99 7. Manifest Structure . . . . . . . . . . . . . . . . . . . . . 22 100 7.1. Severable Elements . . . . . . . . . . . . . . . . . . . 24 101 7.2. Envelope . . . . . . . . . . . . . . . . . . . . . . . . 25 102 7.3. Manifest . . . . . . . . . . . . . . . . . . . . . . . . 27 103 7.4. SUIT_Dependency . . . . . . . . . . . . . . . . . . . . . 32 104 7.5. SUIT_Component_Reference . . . . . . . . . . . . . . . . 32 105 7.6. Manifest Parameters . . . . . . . . . . . . . . . . . . . 33 106 7.6.1. SUIT_Parameter_Strict_Order . . . . . . . . . . . . . 35 107 7.6.2. SUIT_Parameter_Soft_Failure . . . . . . . . . . . . . 35 108 7.7. SUIT_Parameter_Encryption_Info . . . . . . . . . . . . . 35 109 7.7.1. SUIT_Parameter_Compression_Info . . . . . . . . . . . 35 110 7.7.2. SUIT_Parameter_Unpack_Info . . . . . . . . . . . . . 36 111 7.7.3. SUIT_Parameters CDDL . . . . . . . . . . . . . . . . 36 112 7.8. SUIT_Command_Sequence . . . . . . . . . . . . . . . . . . 38 113 7.9. SUIT_Condition . . . . . . . . . . . . . . . . . . . . . 39 114 7.9.1. Identifier Conditions . . . . . . . . . . . . . . . . 40 115 7.9.2. suit-condition-image-match . . . . . . . . . . . . . 41 116 7.9.3. suit-condition-image-not-match . . . . . . . . . . . 41 117 7.9.4. suit-condition-use-before . . . . . . . . . . . . . . 41 118 7.9.5. suit-condition-minimum-battery . . . . . . . . . . . 41 119 7.9.6. suit-condition-update-authorized . . . . . . . . . . 42 120 7.9.7. suit-condition-version . . . . . . . . . . . . . . . 42 121 7.9.8. SUIT_Condition_Custom . . . . . . . . . . . . . . . . 43 122 7.9.9. Identifiers . . . . . . . . . . . . . . . . . . . . . 44 123 7.9.10. SUIT_Condition CDDL . . . . . . . . . . . . . . . . . 45 124 7.10. SUIT_Directive . . . . . . . . . . . . . . . . . . . . . 45 125 7.10.1. suit-directive-set-component-index . . . . . . . . . 46 126 7.10.2. suit-directive-set-dependency-index . . . . . . . . 47 127 7.10.3. suit-directive-abort . . . . . . . . . . . . . . . . 47 128 7.10.4. suit-directive-run-sequence . . . . . . . . . . . . 47 129 7.10.5. suit-directive-try-each . . . . . . . . . . . . . . 48 130 7.10.6. suit-directive-process-dependency . . . . . . . . . 48 131 7.10.7. suit-directive-set-parameters . . . . . . . . . . . 49 132 7.10.8. suit-directive-override-parameters . . . . . . . . . 49 133 7.10.9. suit-directive-fetch . . . . . . . . . . . . . . . . 50 134 7.10.10. suit-directive-copy . . . . . . . . . . . . . . . . 50 135 7.10.11. suit-directive-swap . . . . . . . . . . . . . . . . 51 136 7.10.12. suit-directive-run . . . . . . . . . . . . . . . . . 51 137 7.10.13. suit-directive-wait . . . . . . . . . . . . . . . . 52 138 7.10.14. SUIT_Directive CDDL . . . . . . . . . . . . . . . . 53 139 7.11. SUIT_Text_Map . . . . . . . . . . . . . . . . . . . . . . 55 140 8. Access Control Lists . . . . . . . . . . . . . . . . . . . . 55 141 9. SUIT digest container . . . . . . . . . . . . . . . . . . . . 56 142 10. Creating Conditional Sequences . . . . . . . . . . . . . . . 57 143 11. Full CDDL . . . . . . . . . . . . . . . . . . . . . . . . . . 59 144 12. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 67 145 12.1. Example 0: Secure Boot . . . . . . . . . . . . . . . . . 68 146 12.2. Example 1: Simultaneous Download and Installation of 147 Payload . . . . . . . . . . . . . . . . . . . . . . . . 69 148 12.3. Example 2: Simultaneous Download, Installation, and 149 Secure Boot . . . . . . . . . . . . . . . . . . . . . . 72 150 12.4. Example 3: Load from External Storage . . . . . . . . . 74 151 12.5. Example 4: Load and Decompress from External Storage . . 76 152 12.6. Example 5: Compatibility Test, Download, Installation, 153 and Secure Boot . . . . . . . . . . . . . . . . . . . . 79 154 12.7. Example 6: Two Images . . . . . . . . . . . . . . . . . 81 155 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 84 156 14. Security Considerations . . . . . . . . . . . . . . . . . . . 85 157 15. Mailing List Information . . . . . . . . . . . . . . . . . . 85 158 16. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 85 159 17. References . . . . . . . . . . . . . . . . . . . . . . . . . 86 160 17.1. Normative References . . . . . . . . . . . . . . . . . . 86 161 17.2. Informative References . . . . . . . . . . . . . . . . . 86 162 17.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 87 163 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 87 165 1. Introduction 167 A firmware update mechanism is an essential security feature for IoT 168 devices to deal with vulnerabilities. While the transport of 169 firmware images to the devices themselves is important there are 170 already various techniques available, such as the Lightweight 171 Machine-to-Machine (LwM2M) protocol offering device management of IoT 172 devices. Equally important is the inclusion of meta-data about the 173 conveyed firmware image (in the form of a manifest) and the use of 174 end-to-end security protection to detect modifications and 175 (optionally) to make reverse engineering more difficult. End-to-end 176 security allows the author, who builds the firmware image, to be sure 177 that no other party (including potential adversaries) can install 178 firmware updates on IoT devices without adequate privileges. This 179 authorization process is ensured by the use of dedicated symmetric or 180 asymmetric keys installed on the IoT device: for use cases where only 181 integrity protection is required it is sufficient to install a trust 182 anchor on the IoT device. For confidentiality protected firmware 183 images it is additionally required to install either one or multiple 184 symmetric or asymmetric keys on the IoT device. Starting security 185 protection at the author is a risk mitigation technique so firmware 186 images and manifests can be stored on untrusted repositories; it also 187 reduces the scope of a compromise of any repository or intermediate 188 system to be no worse than a denial of service. 190 It is assumed that the reader is familiar with the high-level 191 firmware update architecture [I-D.ietf-suit-architecture]. 193 Most Update and Trusted Execution operations are composed of the same 194 small set of fundamental operations, such as copying a firmware image 195 from one place to another, checking that a firmware image is correct, 196 verifying that the specified firmware is the correct firmware for the 197 device, or unpacking a firmware. By using these fundamental 198 operations in different orders and changing the parameters they use, 199 a great many use cases can be supported by the same encoding. The 200 SUIT manifest uses this observation to heavily optimize update 201 metadata for consumption by constrained devices. 203 While the SUIT manifest is informed by and optimized for firmware 204 update use cases, there is nothing in the 205 [I-D.ietf-suit-information-model] that restricts its use to only 206 firmware use cases. Software update and delivery of arbitrary data 207 can equally be managed by SUIT-based metadata. 209 2. Conventions and Terminology 211 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 212 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 213 "OPTIONAL" in this document are to be interpreted as described in 214 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 215 capitals, as shown here. 217 The following terminology is used throughout this document. 219 - SUIT: Software Update for the Internet of Things, the IETF working 220 group for this standard. 222 - Payload: A piece of information to be delivered. Typically 223 Firmware for the purposes of SUIT. 225 - Resource: A piece of information that is used to construct a 226 payload. 228 - Manifest: A piece of information that describes one or more 229 payloads, one or more resources, and the processors needed to 230 transform resources into payloads. 232 - Update: One or more manifests that describe one or more payloads. 234 - Update Authority: The owner of a cryptographic key used to sign 235 updates, trusted by Recipients. 237 - Recipient: The system, typically an IoT device, that receives a 238 manifest. 240 - Condition: A test for a property of the Recipient or its 241 components. 243 - Directive: An action for the Recipient to perform. 245 - Command: A Condition or a Directive. 247 - Trusted Execution: A process by which a system ensures that only 248 trusted code is executed, for example secure boot. 250 - A/B images: Dividing a device's storage into two or more bootable 251 images, at different offsets, such that the active image can write 252 to the inactive image(s). 254 3. How to use this Document 256 This specification covers four aspects of firmware update: the 257 background that has informed this specification, the behavior of a 258 device consuming a manifest, the process of creating a manifest, and 259 the structure of the manifest itself. 261 - Section 4 describes the device constraints, use cases, and design 262 principles that informed the structure of the manifest. 264 - Section 5 describes what actions a manifest processor should take. 266 - Section 6 describes the process of creating a manifest. 268 - Section 7 specifies the content of the manifest. 270 For information about firmware update in general and the background 271 of the suit manifest, see Section 4. To implement an updatable 272 device, see Section 5 and Section 7. To implement a tool that 273 generates updates, see Section 6 and Section 7. 275 4. Background 277 This section describes the logistical challenges, device constraints, 278 use cases, and design principles that informed the structure of the 279 manifest. For the security considerations of the manifest, see 280 [I-D.ietf-suit-information-model]. 282 Distributing firmware updates to diverse devices with diverse trust 283 anchors in a coordinated system presents unique challenges. Devices 284 have a broad set of constraints, requiring different metadata to make 285 appropriate decisions. There may be many actors in production IoT 286 systems, each of whom has some authority. Distributing firmware in 287 such a multi-party environment presents additional challenges. Each 288 party requires a different subset of data. Some data may not be 289 accessible to all parties. Multiple signatures may be required from 290 parties with different authorities. This topic is covered in more 291 depth in [I-D.ietf-suit-architecture]. 293 4.1. IoT Firmware Update Constraints 295 The various constraints on IoT devices create a broad set of use-case 296 requirements. For example, devices with: 298 - limited processing power and storage may require a simple 299 representation of metadata. 301 - bandwidth constraints may require firmware compression or partial 302 update support. 304 - bootloader complexity constraints may require simple selection 305 between two bootable images. 307 - small internal storage may require external storage support. 309 - multiple processors may require coordinated update of all 310 applications. 312 - large storage and complex functionality may require parallel 313 update of many software components. 315 - mesh networks may require multicast distribution. 317 Supporting the requirements introduced by the constraints on IoT 318 devices requires the flexibility to represent a diverse set of 319 possible metadata, but also requires that the encoding is kept 320 simple. 322 4.2. Update Workflow Model 324 There are several fundamental assumptions that inform the model of 325 the firmware update workflow: 327 - Compatibility must be checked before any other operation is 328 performed. 330 - All dependency manifests should be present before any payload is 331 fetched. 333 - In some applications, payloads must be fetched and validated prior 334 to installation. 336 There are several fundamental assumptions that inform the model of 337 the secure boot workflow: 339 - Compatibility must be checked before any other operation is 340 performed. 342 - All dependencies and payloads must be validated prior to loading. 344 - All loaded images must be validated prior to execution. 346 Based on these assumptions, the manifest is structured to work with a 347 pull parser, where each section of the manifest is used in sequence. 348 The expected workflow for a device installing an update can be broken 349 down into 5 steps: 351 1. Verify the signature of the manifest. 353 2. Verify the applicability of the manifest. 355 3. Resolve dependencies. 357 4. Fetch payload(s). 359 5. Install payload(s). 361 When installation is complete, similar information can be used for 362 validating and running images in a further 3 steps: 364 1. Verify image(s). 366 2. Load image(s). 368 3. Run image(s). 370 If verification and running is implemented in a bootloader, then the 371 bootloader MUST also verify the signature of the manifest and the 372 applicability of the manifest in order to implement secure boot 373 workflows. The bootloader MAY add its own authentication, e.g. a 374 MAC, to the manifest in order to prevent further verifications. 376 When multiple manifests are used for an update, each manifest's steps 377 occur in a lockstep fashion; all manifests have dependency resolution 378 performed before any manifest performs a payload fetch, etc. 380 4.2.1. Pre-Authentication Compatibility Checks 382 The RECOMMENDED process is to verify the signature of the manifest 383 prior to parsing/executing any section of the manifest. This guards 384 the parser against arbitrary input by unauthenticated third parties, 385 but it costs extra energy when a device receives an incompatible 386 manifest. 388 If a device: 390 1. expects to receive many incompatible manifests. 392 2. expects to receive few manifests with failing signatures-for 393 example if it is behind a gateway that checks signatures. 395 3. has a power budget that makes signature verification undesirable. 397 Then, the device MAY choose to parse and execute only the SUIT_Common 398 section of the manifest prior to signature verification. The 399 guidelines in Creating Manifests (Section 6) require that the common 400 section contain the applicability checks, so this section is 401 sufficient for applicability verification. The manifest parser MUST 402 NOT execute any command with side-effects outside the parser (for 403 example, Run, Copy, Swap, or Fetch commands) prior to authentication 404 and any such command MUST result in an error. 406 4.3. SUIT Manifest Goals 408 The manifest described in this document is intended to meet several 409 goals, as described below. 411 - Meet the requirements defined in 412 [I-D.ietf-suit-information-model]. 414 - Simple to parse on a constrained node 416 - Simple to process on a constrained node 418 - Compact encoding 420 - Comprehensible by an intermediate system 422 - Expressive enough to enable advanced use cases on advanced nodes 424 - Extensible 426 The SUIT manifest can be used for a variety of purposes throughout 427 its lifecycle. The manifest allows: 429 - the Firmware Author to reason about releasing a firmware. 431 - the Network Operator to reason about compatibility of a firmware. 433 - the Device Operator to reason about the impact of a firmware. 435 - the Device Operator to manage distribution of firmware to devices. 437 - the Plant Manager to reason about timing and acceptance of 438 firmware updates. 440 - the device to reason about the authority & authenticity of a 441 firmware prior to installation. 443 - the device to reason about the applicability of a firmware. 445 - the device to reason about the installation of a firmware. 447 - the device to reason about the authenticity & encoding of a 448 firmware at boot. 450 Each of these uses happens at a different stage of the manifest 451 lifecycle, so each has different requirements. 453 4.4. SUIT Manifest Design Summary 455 In order to provide flexible behavior to constrained devices, while 456 still allowing more powerful devices to use their full capabilities, 457 the SUIT manifest encodes the required behavior of a Recipient 458 device. Behavior is encoded as a specialized byte code, contained in 459 a CBOR list. This promotes a flat encoding, which simplifies the 460 parser. The information encoded by this byte code closely matches 461 the operations that a device will perform, which promotes ease of 462 processing. The core operations used by most update and trusted 463 execution operations are represented in the byte code. The byte code 464 can be extended by registering new operations. 466 The specialized byte code approach gives benefits equivalent to those 467 provided by a scripting language or conventional byte code, with two 468 substantial differences. First, the language is extremely high 469 level, consisting of only the operations that a device may perform 470 during update and trusted execution of a firmware image. Second, the 471 language specifies linear behavior, without reverse branches. 472 Conditional processing is supported, and parallel and out-of-order 473 processing may be performed by sufficiently capable devices. 475 By structuring the data in this way, the manifest processor becomes a 476 very simple engine that uses a pull parser to interpret the manifest. 478 This pull parser invokes a series of command handlers that evaluate a 479 Condition or execute a Directive. Most data is structured in a 480 highly regular pattern, which simplifies the parser. 482 The results of this allow a Recipient to implement a very small 483 parser for constrained applications. If needed, such a parser also 484 allows the Recipient to perform complex updates with reduced 485 overhead. Conditional execution of commands allows a simple device 486 to perform important decisions at validation-time. 488 Dependency handling is vastly simplified as well. Dependencies 489 function like subroutines of the language. When a manifest has a 490 dependency, it can invoke that dependency's commands and modify their 491 behavior by setting parameters. Because some parameters come with 492 security implications, the dependencies also have a mechanism to 493 reject modifications to parameters on a fine-grained level. 495 Developing a robust permissions system works in this model too. The 496 Recipient can use a simple ACL that is a table of Identities and 497 Component Identifier permissions to ensure that operations on 498 components fail unless they are permitted by the ACL. This table can 499 be further refined with individual parameters and commands. 501 Capability reporting is similarly simplified. A Recipient can report 502 the Commands, Parameters, Algorithms, and Component Identifiers that 503 it supports. This is sufficiently precise for a manifest author to 504 create a manifest that the Recipient can accept. 506 The simplicity of design in the Recipient due to all of these 507 benefits allows even a highly constrained platform to use advanced 508 update capabilities. 510 5. Interpreter Behavior 512 This section describes the behavior of the manifest interpreter. 513 This section focuses primarily on interpreting commands in the 514 manifest. However, there are several other important behaviors of 515 the interpreter: encoding version detection , rollback protection, 516 and authenticity verification are chief among these (see 517 Section 5.1). 519 5.1. Interpreter Setup 521 Prior to executing any command sequence, the interpreter or its host 522 application MUST inspect the manifest version field and fail when it 523 encounters an unsupported encoding version. Next, the interpreter or 524 its host application MUST extract the manifest sequence number and 525 perform a rollback check using this sequence number. The exact logic 526 of rollback protection may vary by application, but it has the 527 following properties: 529 - Whenever the interpreter can choose between several manifests, it 530 MUST select the latest valid manifest, authentic manifest. 532 - If the latest valid, authentic manifest fails, it MAY select the 533 next latest valid, authentic manifest. 535 Here, valid means that a manifest has a supported encoding version 536 AND it has not been excluded for other reasons. Reasons for 537 excluding typically involve first executing the manifest and MAY 538 include: 540 - Test failed (e.g. Vendor ID/Class ID). 542 - Unsupported command encountered. 544 - Unsupported parameter encountered. 546 - Unsupported component ID encountered. 548 - Payload not available (update interpreter). 550 - Dependency not available (update interpreter). 552 - Application crashed when executed (bootloader interpreter). 554 - Watchdog timeout occurred (bootloader interpreter). 556 - Dependency or Payload verification failed (bootloader 557 interpreter). 559 These failure reasons MAY be combined with retry mechanisms prior to 560 marking a manifest as invalid. 562 Following these initial tests, the interpreter clears all parameter 563 storage. This ensures that the interpreter begins without any leaked 564 data. 566 5.2. Required Checks 568 Once a valid, authentic manifest has been selected, the interpreter 569 MUST examine the component list and verify that its maximum number of 570 components is not exceeded and that each listed component ID is 571 supported. 573 For each listed component, the interpreter MUST provide storage for 574 the supported parameters (Section 5.4.1). If the interpreter does 575 not have sufficient temporary storage to process the parameters for 576 all components, it MAY process components serially for each command 577 sequence. See Section 5.5 for more details. 579 The interpreter SHOULD check that the common section contains at 580 least one vendor ID check and at least one class ID check. 582 If the manifest contains more than one component, each command 583 sequence MUST begin with a Set Current Component command. 585 If a dependency is specified, then the interpreter MUST perform the 586 following checks: 588 1. At the beginning of each section in the dependent: all previous 589 sections of each dependency have been executed. 591 2. At the end of each section in the dependent: The corresponding 592 section in each dependency has been executed. 594 If the interpreter does not support dependencies and a manifest 595 specifies a dependency, then the interpreter MUST reject the 596 manifest. 598 5.3. Interpreter Fundamental Properties 600 The interpreter has a small set of design goals: 602 1. Executing an update MUST either result in an error, or a 603 verifiably correct system state. 605 2. Executing a secure boot MUST either result in an error, or a 606 booted system. 608 3. Executing the same manifest on multiple devices MUST result in 609 the same system state. 611 NOTE: when using A/B images, the manifest functions as two (or more) 612 logical manifests, each of which applies to a system in a particular 613 starting state. With that provision, design goal 3 holds. 615 5.4. Abstract Machine Description 617 The byte code that forms the bulk of the manifest is processed by an 618 interpreter. This interpreter can be modeled as a simple abstract 619 machine. This machine consists of several data storage locations 620 that are modified by commands. Certain commands also affect the 621 machine's behavior. 623 Every command that modifies system state targets a specific 624 component. Components are units of code or data that can be targeted 625 by an update. They are identified by Component identifiers, arrays 626 of binary-strings-effectively a binary path. Each component has a 627 corresponding set of configuration, Parameters. Parameters are used 628 as the inputs to commands. 630 5.4.1. Parameters 632 Some parameters are REQUIRED to implement. These parameters allow a 633 device to perform core functions. 635 - Vendor ID. 637 - Class ID. 639 - Image Digest. 641 Some parameters are RECOMMENDED to implement. These parameters are 642 needed for most use-cases. 644 - Image Size. 646 - URI. 648 Other parameters are OPTIONAL to implement. These parameters allow a 649 device to implement specific use-cases. 651 - Strict Order. 653 - Soft Failure. 655 - Device ID. 657 - Encryption Info. 659 - Unpack Info. 661 - Source Component. 663 - URI List. 665 - Custom Parameters. 667 5.4.2. Commands 669 Commands define the behavior of a device. The commands are divided 670 into two groups: those that modify state (directives) and those that 671 perform tests (conditions). There are also several Control Flow 672 operations. 674 Some commands are REQUIRED to implement. These commands allow a 675 device to perform core functions 677 - Check Vendor Identifier (cvid). 679 - Check Class Identifier (ccid). 681 - Verify Image (cimg). 683 - Set Current Component (setc). 685 - Override Parameters (ovrp). 687 NOTE: on systems that support only a single component, Set Current 688 Component has no effect. 690 Some commands are RECOMMENDED to implement. These commands are 691 needed for most use-cases 693 - Set Current Dependency (setd). 695 - Set Parameters (setp). 697 - Process Dependency (pdep). 699 - Run (run). 701 - Fetch (getc). 703 Other commands are OPTIONAL to implement. These commands allow a 704 device to implement specific use-cases. 706 - Use Before (ubf). 708 - Check Component Offset (cco). 710 - Check Device Identifier (cdid). 712 - Check Image Not Match (nimg). 714 - Check Minimum Battery (minb). 716 - Check Update Authorized (auth). 718 - Check Version (cver). 720 - Abort (abrt). 722 - Try Each (try). 724 - Copy (copy). 726 - Swap (swap). 728 - Wait For Event (wfe). 730 - Run Sequence (srun) mandatory component set. 732 - Run with Arguments (arun). 734 5.4.3. Command Behavior 736 The following table describes the behavior of each command. "params" 737 represents the parameters for the current component or dependency. 739 +------+------------------------------------------------------------+ 740 | Code | Operation | 741 +------+------------------------------------------------------------+ 742 | cvid | binary-match(component, params[vendor-id]) | 743 | | | 744 | ccid | binary-match(component, params[class-id]) | 745 | | | 746 | cimg | binary-match(digest(component), params[digest]) | 747 | | | 748 | setc | component := components[arg] | 749 | | | 750 | ovrp | params[k] := v for k,v in arg | 751 | | | 752 | setd | dependency := dependencies[arg] | 753 | | | 754 | setp | params[k] := v if not k in params for k,v in arg | 755 | | | 756 | pdep | exec(dependency[common]); exec(dependency[current- | 757 | | segment]) | 758 | | | 759 | run | run(component) | 760 | | | 761 | getc | store(component, fetch(params[uri])) | 762 | | | 763 | ubf | assert(now() < arg) | 764 | | | 765 | cco | assert(offsetof(component) == arg) | 766 | | | 767 | cdid | binary-match(component, params[device-id]) | 768 | | | 769 | nimg | not binary-match(digest(component), params[digest]) | 770 | | | 771 | minb | assert(battery >= arg) | 772 | | | 773 | auth | assert(isAuthorized()) | 774 | | | 775 | cver | assert(version_check(component, arg)) | 776 | | | 777 | abrt | assert(0) | 778 | | | 779 | try | break if exec(seq) is not error for seq in arg | 780 | | | 781 | copy | store(component, params[src-component]) | 782 | | | 783 | swap | swap(component, params[src-component]) | 784 | | | 785 | wfe | until event(arg), wait | 786 | | | 787 | srun | exec(arg) | 788 | | | 789 | arun | run(component, arg) | 790 +------+------------------------------------------------------------+ 792 5.5. Serialized Processing Interpreter 794 Because each manifest has a list of components and a list of 795 components defined by its dependencies, it is possible for the 796 manifest processor to handle one component at a time, traversing the 797 manifest tree once for each listed component. In this mode, the 798 interpreter ignores any commands executed while the component index 799 is not the current component. This reduces the overall volatile 800 storage required to process the update so that the only limit on 801 number of components is the size of the manifest. However, this 802 approach requires additional processing power. 804 5.6. Parallel Processing Interpreter 806 Advanced devices may make use of the Strict Order parameter and 807 enable parallel processing of some segments, or it may reorder some 808 segments. To perform parallel processing, once the Strict Order 809 parameter is set to False, the device may fork a process for each 810 command until the Strict Order parameter is returned to True or the 811 command sequence ends. Then, it joins all forked processes before 812 continuing processing of commands. To perform out-of-order 813 processing, a similar approach is used, except the device consumes 814 all commands after the Strict Order parameter is set to False, then 815 it sorts these commands into its preferred order, invokes them all, 816 then continues processing. 818 Under each of these scenarios the parallel processing must halt: 820 - Set Parameters. 822 - Override Parameters. 824 - Set Strict Order = True. 826 - Set Dependency Index. 828 - Set Component Index. 830 To perform more useful parallel operations, sequences of commands may 831 be collected in a suit-directive-run-sequence. Then, each of these 832 sequences may be run in parallel. Each sequence defaults to Strict 833 Order = True. To isolate each sequence from each other sequence, 834 each sequence must declare a single target component. Set Component 835 Index is not permitted inside this sequence. 837 5.7. Processing Dependencies 839 As described in Section 5.2, each manifest must invoke each of its 840 dependencies sections from the corresponding section of the 841 dependent. Any changes made to parameters by the dependency persist 842 in the dependent. 844 When a Process Dependency command is encountered, the interpreter 845 loads the dependency identified by the Current Dependency Index. The 846 interpreter first executes the common-sequence section of the 847 identified dependency, then it executes the section of the dependency 848 that corresponds to the currently executing section of the dependent. 850 The interpreter also performs the checks described in Section 5.2 to 851 ensure that the dependent is processing the dependency correctly. 853 6. Creating Manifests 855 Manifests are created using tools for constructing COSE structures, 856 calculating cryptographic values and compiling desired system state 857 into a sequence of operations required to achieve that state. The 858 process of constructing COSE structures is covered in [RFC8152] and 859 the calculation of cryptographic values is beyond the scope of this 860 document. 862 Compiling desired system state into a sequence of operations can be 863 accomplished in many ways, however several templates are provided 864 here to cover common use-cases. Many of these templates can be 865 aggregated to produce more complex behavior. 867 NOTE: On systems that support only a single component, Set Current 868 Component has no effect and can be omitted. 870 NOTE: Digest should always be set using Override Parameters, since 871 this prevents a less-privileged dependent from replacing the digest. 873 6.1. Manifest Source Material 875 When a manifest is constructed from a descriptive document, the 876 descriptive document SHOULD be included in the severable text 877 section. This section MAY be pruned from the manifest prior to 878 distribution to a device. The inclusion of text source material 879 enables several use-cases on unconstrained intermediate systems, 880 where small manifest size, low parser complexity, and pull parsing 881 are not required. 883 An unconstrained system that makes decisions based on the manifest 884 can use the source material instead so that it does not need to 885 execute the manifest. 887 An unconstrained system that presents data to a user can do so 888 according to typical usage patterns without first executing the 889 manifest, and can trust that information with the same level of 890 confidence as the manifest itself. 892 A verifier can be constructed to emulate execution the manifest and 893 compare the results of that execution to the source material, 894 providing a check that the manifest performs its stated objectives 895 and that the manifest does not exceed the capabilities of the target 896 device. 898 6.2. Required Template: Compatibility Check 900 The compatibility check ensures that devices only install compatible 901 images. 903 Common: Set Current Component Check Vendor Identifier Check Class 904 Identifier 905 All manifests MUST contain the compatibility check template, except 906 as outlined below. 908 If a device class has a unique trust anchor, and every element in its 909 trust chain is unique-different from every element in any other 910 device class, then it MAY include the compatibility check. 912 If a manifest includes a dependency that performs a compatibility 913 check, then the dependent manifest MAY include the compatibility 914 check. 916 The compatibility check template contains a data dependency: Vendor 917 Identifier and Class Identifier MUST be set prior to executing the 918 template. One example of the full template is included below, 919 however Parameters may be set within a Try-Each block as well. They 920 may also be inherited from a dependent manifest. 922 - Common: 924 o Set Current Component. 926 o Set Parameters: 928 * Vendor ID. 930 * Class ID. 932 o Check Vendor Identifier. 934 o Check Class Identifier. 936 6.3. Use Case Template: XIP Secure Boot 938 - Common: 940 o Set Current Component. 942 o Override Parameters: 944 * Digest. 946 * Size. 948 - Run: 950 o Set Current Component. 952 o Check Image Match. 954 o Directive Run. 956 6.4. Use Case Template: Firmware Download 958 - Common: 960 o Set Current Component. 962 o Override Parameters: 964 * Digest. 966 * Size. 968 - Install: 970 o Set Current Component. 972 o Set Parameters: 974 * URI. 976 o Fetch. 978 6.5. Use Case Template: Load from External Storage 980 - Load: 982 o Set Current Component. 984 o Set Parameters: 986 * Source Index. 988 o Copy. 990 6.6. Use Case Template Load & Decompress from External Storage 992 - Load: 994 o Set Current Component. 996 o Set Parameters: 998 * Source Index. 1000 * Compression Info. 1002 o Copy. 1004 6.7. Use Case Template: Dependency 1006 - Dependency Resolution: 1008 o Set Current Dependency. 1010 o Set Parameters: 1012 * URI. 1014 o Fetch. 1016 o Check Image Match. 1018 o Process Dependency. 1020 - Validate: 1022 o Set Current Dependency. 1024 o Check Image Match. 1026 o Process Dependency. 1028 For any other section that the dependency has, the dependent MUST 1029 invoke Process Dependency. 1031 NOTE: Any changes made to parameters in a dependency persist in the 1032 dependent. 1034 7. Manifest Structure 1036 The manifest is enveloped in a CBOR map containing: 1038 1. Authentication delegation chain(s) 1040 2. The authentication wrapper (a list of COSE sign/MAC objects) 1042 3. The manifest (a map) 1044 1. Critical Information 1046 2. Information shared by all command sequences 1048 1. List of dependencies 1049 2. List of payloads 1051 3. List of payloads in dependencies 1053 4. Common list of conditions, directives 1055 3. Reference URI 1057 4. Dependency resolution Reference or conditions/directives 1059 5. Payload fetch Reference or conditions/directives 1061 6. Installation Reference or conditions/directives 1063 7. Verification conditions/directives 1065 8. Load conditions/directives 1067 9. Run conditions/directives 1069 10. Text / Reference 1071 11. COSWID / Reference 1073 4. Dependency resolution conditions/directives 1075 5. Payload fetch conditions/directives 1077 6. Installation conditions/directives 1079 7. Text 1081 8. COSWID 1083 9. Inline Payload(s) 1085 All elements in the outer map are wrapped in bstr. 1087 +--------------------+ 1088 | Manifest Envelope | 1089 +--------------------+ 1090 | Delegation CWTs | 1091 | COSE Envelopes | 1092 | Manifest --------------------> +-----------------------+ 1093 | Severable Elements | | Manifest (bstr) | 1094 +--------------------+ +-----------------------+ 1095 | Structure Version | 1096 | Sequence Number | 1097 +-----------------------+ <------- Common Info | 1098 | Common Info (bstr) | | Reference URI | 1099 +-----------------------+ | Installation Commands ---+ 1100 | Dependencies | | Invocation Commands -----+ 1101 | Components IDs | | Protected Elements | | 1102 | Component References | +-----------------------+ | 1103 | Common Commands --------+ | 1104 +-----------------------+ | | 1105 +-> +-----------------------+ <---+ 1106 | Commands (bstr) | 1107 +-----------------------+ 1108 | List of ( pairs of ( | 1109 | * command ID code | 1110 | * argument | 1111 | )) | 1112 +-----------------------+ 1114 The map indices in this encoding are reset to 1 for each map within 1115 the structure. This is to keep the indices as small as possible. 1116 The goal is to keep the index objects to single bytes (CBOR positive 1117 integers 1-23). 1119 Wherever enumerations are used, they are started at 1. This allows 1120 detection of several common software errors that are caused by 1121 uninitialised variables. Positive numbers in enumerations are 1122 reserved for IANA registration. Negative numbers are used to 1123 identify application-specific implementations. 1125 CDDL names are hyphenated and CDDL structures follow the convention 1126 adopted in COSE [RFC8152]: SUIT_Structure_Name. 1128 7.1. Severable Elements 1130 Because the manifest can be used by different actors at different 1131 times, some parts of the manifest can be removed without affecting 1132 later stages of the lifecycle. This is called "Severing." Severing 1133 of information is achieved by separating that information from the 1134 signed container so that removing it does not affect the signature. 1136 This means that ensuring authenticity of severable parts of the 1137 manifest is a requirement for the signed portion of the manifest. 1138 Severing some parts makes it possible to discard parts of the 1139 manifest that are no longer necessary. This is important because it 1140 allows the storage used by the manifest to be greatly reduced. For 1141 example, no text size limits are needed if text is removed from the 1142 manifest prior to delivery to a constrained device. 1144 Elements are made severable by removing them from the manifest, 1145 encoding them in a bstr, and placing a SUIT_Digest of the bstr in the 1146 manifest so that they can still be authenticated. The SUIT_Digest 1147 typically consumes 4 bytes more than the size of the raw digest, 1148 therefore elements smaller than (Digest Bits)/8 + 4 SHOULD never be 1149 severable. Elements larger than (Digest Bits)/8 + 4 MAY be 1150 severable, while elements that are much larger than (Digest Bits)/8 + 1151 4 SHOULD be severable. 1153 Because of this, all command sequences in the manifest are encoded in 1154 a bstr so that there is a single code path needed for all command 1155 sequences 1157 7.2. Envelope 1159 This object is a container for the other pieces of the manifest to 1160 provide a common mechanism to find each of the parts. All elements 1161 of the envelope are contained in bstr objects. Wherever the manifest 1162 references an object in the envelope, the bstr is included in the 1163 digest calculation. 1165 The CDDL that describes the envelope is below 1167 SUIT_Envelope = { 1168 suit-delegation => bstr .cbor SUIT_Delegation 1169 suit-authentication-wrapper 1170 => bstr .cbor SUIT_Authentication_Wrapper / nil, 1171 $$SUIT_Manifest_Wrapped, 1172 * $$SUIT_Severed_Fields, 1173 } 1175 SUIT_Delegation = [ + [ + CWT ] ] 1177 SUIT_Authentication_Wrapper = [ + bstr .cbor SUIT_Authentication_Block ] 1179 SUIT_Authentication_Block /= COSE_Mac_Tagged 1180 SUIT_Authentication_Block /= COSE_Sign_Tagged 1181 SUIT_Authentication_Block /= COSE_Mac0_Tagged 1182 SUIT_Authentication_Block /= COSE_Sign1_Tagged 1184 $$SUIT_Manifest_Wrapped //= (suit-manifest => bstr .cbor SUIT_Manifest) 1185 $$SUIT_Manifest_Wrapped //= ( 1186 suit-manifest-encryption-info => bstr .cbor SUIT_Encryption_Wrapper, 1187 suit-manifest-encrypted => bstr 1188 ) 1190 SUIT_Encryption_Wrapper = COSE_Encrypt_Tagged / COSE_Encrypt0_Tagged 1192 $$SUIT_Severed_Fields //= ( suit-dependency-resolution => 1193 bstr .cbor SUIT_Command_Sequence) 1194 $$SUIT_Severed_Fields //= (suit-payload-fetch => 1195 bstr .cbor SUIT_Command_Sequence) 1196 $$SUIT_Severed_Fields //= (suit-install => 1197 bstr .cbor SUIT_Command_Sequence) 1198 $$SUIT_Severed_Fields //= (suit-text => 1199 bstr .cbor SUIT_Text_Map) 1200 $$SUIT_Severed_Fields //= (suit-coswid => 1201 bstr .cbor concise-software-identity) 1203 All elements of the envelope must be wrapped in a bstr to minimize 1204 the complexity of the code that evaluates the cryptographic integrity 1205 of the element and to ensure correct serialization for integrity and 1206 authenticity checks. 1208 The suit-authentication-wrapper contains a list of 1 or more 1209 cryptographic authentication wrappers for the core part of the 1210 manifest. These are implemented as COSE_Mac_Tagged or 1211 COSE_Sign_Tagged blocks. Each of these blocks contains a SUIT_Digest 1212 of the manifest. This enables modular processing of the manifest. 1213 The COSE_Mac_Tagged and COSE_Sign_Tagged blocks are described in RFC 1214 8152 [RFC8152] and are beyond the scope of this document. The suit- 1215 authentication-wrapper MUST come before any element in the 1216 SUIT_Envelope, except for the OPTIONAL suit-delegation, regardless of 1217 canonical encoding of CBOR. All validators MUST reject any 1218 SUIT_Envelope that begins with any element other than a suit- 1219 authentication-wrapper or suit-delegation. 1221 A SUIT_Envelope that has not had authentication information added 1222 MUST still contain the suit-authentication-wrapper element, but the 1223 content MUST be nil. 1225 The envelope MUST contain only one of 1227 - a plaintext manifest: SUIT_Manifest. 1229 - an encrypted manifest: both a SUIT_Encryption_Wrapper and the 1230 ciphertext of a manifest. 1232 When the envelope contains SUIT_Encryption_Wrapper, the suit- 1233 authentication-wrapper MUST authenticate the plaintext of suit- 1234 manifest-encrypted. This ensures that the manifest can be stored 1235 decrypted and that a recipient MAY convert the suit-manifest- 1236 encrypted element to a suit-manifest element. 1238 suit-manifest contains a SUIT_Manifest structure, which describes the 1239 payload(s) to be installed and any dependencies on other manifests. 1241 suit-manifest-encryption-info contains a SUIT_Encryption_Wrapper, a 1242 COSE object that describes the information required to decrypt a 1243 ciphertext manifest. 1245 suit-manifest-encrypted contains a ciphertext manifest. 1247 Each of suit-dependency-resolution, suit-payload-fetch, and suit- 1248 payload-installation contain the severable contents of the 1249 identically named portions of the manifest, described in Section 7.3. 1251 suit-text contains all the human-readable information that describes 1252 any and all parts of the manifest, its payload(s) and its 1253 resource(s). 1255 suit-coswid contains a Concise Software Identifier. This may be 1256 discarded by the Recipient if not needed. 1258 7.3. Manifest 1260 The manifest describes the critical metadata for the referenced 1261 payload(s). In addition, it contains: 1263 1. a version number for the manifest structure itself 1265 2. a sequence number 1267 3. a list of dependencies 1269 4. a list of components affected 1271 5. a list of components affected by dependencies 1273 6. a reference for each of the severable blocks. 1275 7. a list of actions that the Recipient should perform. 1277 The following CDDL fragment defines the manifest. 1279 SUIT_Manifest = { 1280 suit-manifest-version => 1, 1281 suit-manifest-sequence-number => uint, 1282 suit-common => bstr .cbor SUIT_Common, 1283 ? suit-reference-uri => #6.32(tstr), 1284 * $$SUIT_Severable_Command_Sequences, 1285 * $$SUIT_Command_Sequences, 1286 * $$SUIT_Protected_Elements, 1287 } 1289 $$SUIT_Severable_Command_Sequences //= (suit-dependency-resolution => 1290 SUIT_Severable_Command_Segment) 1291 $$SUIT_Severable_Command_Segments //= (suit-payload-fetch => 1292 SUIT_Severable_Command_Sequence) 1293 $$SUIT_Severable_Command_Segments //= (suit-install => 1294 SUIT_Severable_Command_Sequence) 1296 SUIT_Severable_Command_Sequence = 1297 SUIT_Digest / bstr .cbor SUIT_Command_Sequence 1299 $$SUIT_Command_Sequences //= ( suit-validate => 1300 bstr .cbor SUIT_Command_Sequence ) 1301 $$SUIT_Command_Sequences //= ( suit-load => 1302 bstr .cbor SUIT_Command_Sequence ) 1303 $$SUIT_Command_Sequences //= ( suit-run => 1304 bstr .cbor SUIT_Command_Sequence ) 1306 $$SUIT_Protected_Elements //= ( suit-text => SUIT_Digest ) 1307 $$SUIT_Protected_Elements //= ( suit-coswid => SUIT_Digest ) 1309 SUIT_Common = { 1310 ? suit-dependencies => bstr .cbor SUIT_Dependencies, 1311 ? suit-components => bstr .cbor SUIT_Components, 1312 ? suit-dependency-components 1313 => bstr .cbor SUIT_Component_References, 1314 ? suit-common-sequence => bstr .cbor SUIT_Command_Sequence, 1315 } 1317 Several fields in the Manifest can be either a CBOR structure or a 1318 SUIT_Digest. In each of these cases, the SUIT_Digest provides for a 1319 severable field. Severable fields are RECOMMENDED to implement. In 1320 particular, text SHOULD be severable, since most useful text elements 1321 occupy more space than a SUIT_Digest, but are not needed by the 1322 Recipient. Because SUIT_Digest is a CBOR Array and each severable 1323 element is a CBOR bstr, it is straight-forward for a Recipient to 1324 determine whether an element is been severable. The key used for a 1325 severable element is the same in the SUIT_Manifest and in the 1326 SUIT_Envelope so that a Recipient can easily identify the correct 1327 data in the envelope. 1329 The suit-manifest-version indicates the version of serialization used 1330 to encode the manifest. Version 1 is the version described in this 1331 document. suit-manifest-version is REQUIRED. 1333 The suit-manifest-sequence-number is a monotonically increasing anti- 1334 rollback counter. It also helps devices to determine which in a set 1335 of manifests is the "root" manifest in a given update. Each manifest 1336 MUST have a sequence number higher than each of its dependencies. 1337 Each Recipient MUST reject any manifest that has a sequence number 1338 lower than its current sequence number. It MAY be convenient to use 1339 a UTC timestamp in seconds as the sequence number. suit-manifest- 1340 sequence-number is REQUIRED. 1342 suit-common encodes all the information that is shared between each 1343 of the command sequences, including: suit-dependencies, suit- 1344 components, suit-dependency-components, and suit-common-sequence. 1345 suit-common is REQUIRED to implement. 1347 suit-dependencies is a list of SUIT_Dependency blocks that specify 1348 manifests that must be present before the current manifest can be 1349 processed. suit-dependencies is OPTIONAL to implement. 1351 In order to distinguish between components that are affected by the 1352 current manifest and components that are affected by a dependency, 1353 they are kept in separate lists. Components affected by the current 1354 manifest only list the component identifier. Components affected by 1355 a dependency include the component identifier and the index of the 1356 dependency that defines the component. 1358 suit-components is a list of SUIT_Component blocks that specify the 1359 component identifiers that will be affected by the content of the 1360 current manifest. suit-components is OPTIONAL, but at least one 1361 manifest MUST contain a suit-components block. 1363 suit-dependency-components is a list of SUIT_Component_Reference 1364 blocks that specify component identifiers that will be affected by 1365 the content of a dependency of the current manifest. suit-dependency- 1366 components is OPTIONAL. 1368 suit-common-sequence is a SUIT_Command_Sequence to execute prior to 1369 executing any other command sequence. Typical actions in suit- 1370 common-sequence include setting expected device identity and image 1371 digests when they are conditional (see Section 10 for more 1372 information on conditional sequences). suit-common-sequence is 1373 RECOMMENDED. 1375 suit-reference-uri is a text string that encodes a URI where a full 1376 version of this manifest can be found. This is convenient for 1377 allowing management systems to show the severed elements of a 1378 manifest when this URI is reported by a device after installation. 1380 suit-dependency-resolution is a SUIT_Command_Sequence to execute in 1381 order to perform dependency resolution. Typical actions include 1382 configuring URIs of dependency manifests, fetching dependency 1383 manifests, and validating dependency manifests' contents. suit- 1384 dependency-resolution is REQUIRED when suit-dependencies is present. 1386 suit-payload-fetch is a SUIT_Command_Sequence to execute in order to 1387 obtain a payload. Some manifests may include these actions in the 1388 suit-install section instead if they operate in a streaming 1389 installation mode. This is particularly relevant for constrained 1390 devices without any temporary storage for staging the update. suit- 1391 payload-fetch is OPTIONAL. 1393 suit-install is a SUIT_Command_Sequence to execute in order to 1394 install a payload. Typical actions include verifying a payload 1395 stored in temporary storage, copying a staged payload from temporary 1396 storage, and unpacking a payload. suit-install is OPTIONAL. 1398 suit-validate is a SUIT_Command_Sequence to execute in order to 1399 validate that the result of applying the update is correct. Typical 1400 actions involve image validation and manifest validation. suit- 1401 validate is REQUIRED. If the manifest contains dependencies, one 1402 process-dependency invocation per dependency or one process- 1403 dependency invocation targeting all dependencies SHOULD be present in 1404 validate. 1406 suit-load is a SUIT_Command_Sequence to execute in order to prepare a 1407 payload for execution. Typical actions include copying an image from 1408 permanent storage into RAM, optionally including actions such as 1409 decryption or decompression. suit-load is OPTIONAL. 1411 suit-run is a SUIT_Command_Sequence to execute in order to run an 1412 image. suit-run typically contains a single instruction: either the 1413 "run" directive for the bootable manifest or the "process 1414 dependencies" directive for any dependents of the bootable manifest. 1415 suit-run is OPTIONAL. Only one manifest in an update may contain the 1416 "run" directive. 1418 suit-text is a digest that uniquely identifies the content of the 1419 Text that is packaged in the SUIT_Envelope. text is OPTIONAL. 1421 suit-coswid is a digest that uniquely identifies the content of the 1422 concise-software-identifier that is packaged in the SUIT_Envelope. 1423 coswid is OPTIONAL. 1425 7.4. SUIT_Dependency 1427 SUIT_Dependency specifies a manifest that describes a dependency of 1428 the current manifest. 1430 The following CDDL describes the SUIT_Dependency structure. 1432 SUIT_Dependency = { 1433 suit-dependency-digest => SUIT_Digest, 1434 ? suit-dependency-prefix => SUIT_Component_Identifier, 1435 } 1437 The suit-dependency-digest specifies the dependency manifest uniquely 1438 by identifying a particular Manifest structure. The digest is 1439 calculated over the Manifest structure instead of the COSE 1440 Sig_structure or Mac_structure. This means that a digest may need to 1441 be calculated more than once, however this is necessary to ensure 1442 that removing a signature from a manifest does not break dependencies 1443 due to missing signature elements. This is also necessary to support 1444 the trusted intermediary use case, where an intermediary re-signs the 1445 Manifest, removing the original signature, potentially with a 1446 different algorithm, or trading COSE_Sign for COSE_Mac. 1448 The suit-dependency-prefix element contains a 1449 SUIT_Component_Identifier. This specifies the scope at which the 1450 dependency operates. This allows the dependency to be forwarded on 1451 to a component that is capable of parsing its own manifests. It also 1452 allows one manifest to be deployed to multiple dependent devices 1453 without those devices needing consistent component hierarchy. This 1454 element is OPTIONAL. 1456 7.5. SUIT_Component_Reference 1458 The SUIT_Component_Reference describes an image that is defined by 1459 another manifest. This is useful for overriding the behavior of 1460 another manifest, for example by directing the recipient to look at a 1461 different URI for the image or by changing the expected format, such 1462 as when a gateway performs decryption on behalf of a constrained 1463 device. The following CDDL describes the SUIT_Component_Reference. 1465 SUIT_Component_Reference = { 1466 suit-component-identifier => SUIT_Component_Identifier, 1467 suit-component-dependency-index => uint 1468 } 1470 7.6. Manifest Parameters 1472 Many conditions and directives require additional information. That 1473 information is contained within parameters that can be set in a 1474 consistent way. This allows reduction of manifest size and 1475 replacement of parameters from one manifest to the next. 1477 The defined manifest parameters are described below. 1479 +------+---------+------------+-------------+-----------------------+ 1480 | ID | CBOR | Scope | Name | Description | 1481 | | Type | | | | 1482 +------+---------+------------+-------------+-----------------------+ 1483 | 1 | bstr | Component | Vendor ID | A RFC4122 UUID | 1484 | | | / Global | | representing the | 1485 | | | | | vendor of the device | 1486 | | | | | or component | 1487 | | | | | | 1488 | 2 | bstr | Component | Class ID | A RFC4122 UUID | 1489 | | | / Global | | representing the | 1490 | | | | | class of the device | 1491 | | | | | or component | 1492 | | | | | | 1493 | 3 | bstr | Component | Image | A SUIT_Digest | 1494 | | | / | Digest | | 1495 | | | Dependency | | | 1496 | | | | | | 1497 | 4 | uint | Component | Use Before | POSIX timestamp | 1498 | | | / Global | | | 1499 | | | | | | 1500 | 5 | uint | Component | Component | Offset of the | 1501 | | | | Offset | component | 1502 | | | | | | 1503 | 12 | boolean | Global | Strict | Requires that the | 1504 | | | | Order | manifest is processed | 1505 | | | | | in a strictly linear | 1506 | | | | | fashion. Set to 0 to | 1507 | | | | | enable parallel | 1508 | | | | | handling of manifest | 1509 | | | | | directives. | 1510 | | | | | | 1511 | 13 | boolean | Command | Soft | Condition failures | 1512 | | | Segment | Failure | only terminate the | 1513 | | | | | current command | 1514 | | | | | segment. | 1515 | | | | | | 1516 | 14 | uint | Component | Image Size | Integer size | 1517 | | | / | | | 1518 | | | Dependency | | | 1519 | | | | | | 1520 | 18 | bstr | Component | Encryption | A COSE object | 1521 | | | / | Info | defining the | 1522 | | | Dependency | | encryption mode of a | 1523 | | | | | resource | 1524 | | | | | | 1525 | 19 | bstr | Component | Compression | The information | 1526 | | | | Info | required to | 1527 | | | | | decompress the image | 1528 | | | | | | 1529 | 20 | bstr | Component | Unpack Info | The information | 1530 | | | | | required to unpack | 1531 | | | | | the image | 1532 | | | | | | 1533 | 21 | tstr | Component | URI | A URI from which to | 1534 | | | / | | fetch a resource | 1535 | | | Dependency | | | 1536 | | | | | | 1537 | 22 | uint | Component | Source | A Component Index | 1538 | | | | Component | | 1539 | | | | | | 1540 | 23 | bstr / | Component | Run | An encoded set of | 1541 | | nil | | Arguments | arguments for Run | 1542 | | | | | | 1543 | 24 | bstr | Component | Device ID | A RFC4122 UUID | 1544 | | | / Global | | representing the | 1545 | | | | | device or component | 1546 | | | | | | 1547 | 25 | uint | Global | Minimum | A minimum battery | 1548 | | | | Battery | level in mWh | 1549 | | | | | | 1550 | 26 | int | Component | Priority | The priority of the | 1551 | | | / Global | | update | 1552 | | | | | | 1553 | nint | int / | Custom | Custom | Application-defined | 1554 | | bstr / | | Parameter | parameter | 1555 | | tstr | | | | 1556 +------+---------+------------+-------------+-----------------------+ 1558 CBOR-encoded object parameters are still wrapped in a bstr. This is 1559 because it allows a parser that is aggregating parameters to 1560 reference the object with a single pointer and traverse it without 1561 understanding the contents. This is important for modularization and 1562 division of responsibility within a pull parser. The same 1563 consideration does not apply to Directives because those elements are 1564 invoked with their arguments immediately 1566 7.6.1. SUIT_Parameter_Strict_Order 1568 The Strict Order Parameter allows a manifest to govern when 1569 directives can be executed out-of-order. This allows for systems 1570 that have a sensitivity to order of updates to choose the order in 1571 which they are executed. It also allows for more advanced systems to 1572 parallelize their handling of updates. Strict Order defaults to 1573 True. It MAY be set to False when the order of operations does not 1574 matter. When arriving at the end of a command sequence, ALL commands 1575 MUST have completed, regardless of the state of 1576 SUIT_Parameter_Strict_Order. If SUIT_Parameter_Strict_Order is 1577 returned to True, ALL preceding commands MUST complete before the 1578 next command is executed. 1580 7.6.2. SUIT_Parameter_Soft_Failure 1582 When executing a command sequence inside SUIT_Directive_Try_Each and 1583 a condition failure occurs, the manifest processor aborts the 1584 sequence. If Soft Failure is True, it returns Success. Otherwise, 1585 it returns the original condition failure. 1586 SUIT_Parameter_Soft_Failure is scoped to the enclosing 1587 SUIT_Command_Sequence. Its value is discarded when 1588 SUIT_Command_Sequence terminates. 1590 7.7. SUIT_Parameter_Encryption_Info 1592 Encryption Info defines the mechanism that Fetch or Copy should use 1593 to decrypt the data they transfer. SUIT_Parameter_Encryption_Info is 1594 encoded as a COSE_Encrypt_Tagged or a COSE_Encrypt0_Tagged, wrapped 1595 in a bstr. 1597 7.7.1. SUIT_Parameter_Compression_Info 1599 Compression Info defines any information that is required for a 1600 device to perform decompression operations. Typically, this includes 1601 the algorithm identifier. 1603 SUIT_Parameter_Compression_Info is defined by the following CDDL: 1605 SUIT_Compression_Info = { 1606 suit-compression-algorithm => SUIT_Compression_Algorithms 1607 ? suit-compression-parameters => bstr 1608 } 1610 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_gzip 1611 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_bzip2 1612 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_deflate 1613 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_LZ4 1614 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_lzma 1616 7.7.2. SUIT_Parameter_Unpack_Info 1618 SUIT_Unpack_Info defines the information required for a device to 1619 interpret a packed format, such as elf, hex, or binary diff. 1620 SUIT_Unpack_Info is defined by the following CDDL: 1622 SUIT_Unpack_Info = { 1623 suit-unpack-algorithm => SUIT_Unpack_Algorithms 1624 ? suit-unpack-parameters => bstr 1625 } 1627 SUIT_Unpack_Algorithms //= SUIT_Unpack_Algorithm_Delta 1628 SUIT_Unpack_Algorithms //= SUIT_Unpack_Algorithm_Hex 1629 SUIT_Unpack_Algorithms //= SUIT_Unpack_Algorithm_Elf 1631 7.7.3. SUIT_Parameters CDDL 1633 The following CDDL describes all SUIT_Parameters. 1635 SUIT_Parameters //= (suit-parameter-vendor-identifier => RFC4122_UUID) 1636 SUIT_Parameters //= (suit-parameter-class-identifier => RFC4122_UUID) 1637 SUIT_Parameters //= (suit-parameter-image-digest 1638 => bstr .cbor SUIT_Digest) 1639 SUIT_Parameters //= (suit-parameter-image-size => uint) 1640 SUIT_Parameters //= (suit-parameter-use-before => uint) 1641 SUIT_Parameters //= (suit-parameter-component-offset => uint) 1643 SUIT_Parameters //= (suit-parameter-encryption-info 1644 => bstr .cbor SUIT_Encryption_Info) 1645 SUIT_Parameters //= (suit-parameter-compression-info 1646 => bstr .cbor SUIT_Compression_Info) 1647 SUIT_Parameters //= (suit-parameter-unpack-info 1648 => bstr .cbor SUIT_Unpack_Info) 1650 SUIT_Parameters //= (suit-parameter-uri => tstr) 1651 SUIT_Parameters //= (suit-parameter-source-component => uint) 1652 SUIT_Parameters //= (suit-parameter-run-args => bstr) 1654 SUIT_Parameters //= (suit-parameter-device-identifier => RFC4122_UUID) 1655 SUIT_Parameters //= (suit-parameter-minimum-battery => uint) 1656 SUIT_Parameters //= (suit-parameter-update-priority => uint) 1657 SUIT_Parameters //= (suit-parameter-version => 1658 SUIT_Parameter_Version_Match) 1659 SUIT_Parameters //= (suit-parameter-wait-info => 1660 bstr .cbor SUIT_Wait_Events) 1662 SUIT_Parameters //= (suit-parameter-uri-list 1663 => bstr .cbor SUIT_Component_URI_List) 1664 SUIT_Parameters //= (suit-parameter-custom => int/bool/tstr/bstr) 1666 SUIT_Parameters //= (suit-parameter-strict-order => bool) 1667 SUIT_Parameters //= (suit-parameter-soft-failure => bool) 1669 RFC4122_UUID = bstr .size 16 1671 SUIT_Condition_Version_Comparison_Value = [+int] 1673 SUIT_Encryption_Info = COSE_Encrypt_Tagged/COSE_Encrypt0_Tagged 1674 SUIT_Compression_Info = { 1675 suit-compression-algorithm => SUIT_Compression_Algorithms, 1676 ? suit-compression-parameters => bstr 1677 } 1679 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_gzip 1680 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_bzip2 1681 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_lz4 1682 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_lzma 1684 SUIT_Unpack_Info = { 1685 suit-unpack-algorithm => SUIT_Unpack_Algorithms, 1686 ? suit-unpack-parameters => bstr 1687 } 1689 SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Delta 1690 SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Hex 1691 SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Elf 1693 7.8. SUIT_Command_Sequence 1695 A SUIT_Command_Sequence defines a series of actions that the 1696 Recipient MUST take to accomplish a particular goal. These goals are 1697 defined in the manifest and include: 1699 1. Dependency Resolution 1701 2. Payload Fetch 1703 3. Payload Installation 1705 4. Image Validation 1707 5. Image Loading 1709 6. Run or Boot 1711 Each of these follows exactly the same structure to ensure that the 1712 parser is as simple as possible. 1714 Lists of commands are constructed from two kinds of element: 1716 1. Conditions that MUST be true-any failure is treated as a failure 1717 of the update/load/boot 1719 2. Directives that MUST be executed. 1721 The lists of commands are logically structured into sequences of zero 1722 or more conditions followed by zero or more directives. The 1723 *logical* structure is described by the following CDDL: 1725 Command_Sequence = { 1726 conditions => [ * Condition], 1727 directives => [ * Directive] 1728 } 1730 This introduces significant complexity in the parser, however, so the 1731 structure is flattened to make parsing simpler: 1733 SUIT_Command_Sequence = [ + (SUIT_Condition/SUIT_Directive) ] 1735 Each condition is a command code identifier, followed by Nil. Each 1736 directive is composed of: 1738 1. A command code identifier 1740 2. An argument block or Nil 1741 Argument blocks are defined for each type of directive. 1743 Many conditions and directives apply to a given component, and these 1744 generally grouped together. Therefore, a special command to set the 1745 current component index is provided with a matching command to set 1746 the current dependency index. This index is a numeric index into the 1747 component ID tables defined at the beginning of the document. For 1748 the purpose of setting the index, the two component ID tables are 1749 considered to be concatenated together. 1751 To facilitate optional conditions, a special directive is provided. 1752 It runs several new lists of conditions/directives, one after 1753 another, that are contained as an argument to the directive. By 1754 default, it assumes that a failure of a condition should not indicate 1755 a failure of the update/boot, but a parameter is provided to override 1756 this behavior. 1758 7.9. SUIT_Condition 1760 Conditions are used to define mandatory properties of a system in 1761 order for an update to be applied. They can be pre-conditions or 1762 post-conditions of any directive or series of directives, depending 1763 on where they are placed in the list. Conditions never take 1764 arguments; conditions should test using parameters instead. 1765 Conditions include: 1767 +----------------+-------------------+----------------+ 1768 | Condition Code | Condition Name | Implementation | 1769 +----------------+-------------------+----------------+ 1770 | 1 | Vendor Identifier | REQUIRED | 1771 | | | | 1772 | 2 | Class Identifier | REQUIRED | 1773 | | | | 1774 | 3 | Image Match | REQUIRED | 1775 | | | | 1776 | 4 | Use Before | OPTIONAL | 1777 | | | | 1778 | 5 | Component Offset | OPTIONAL | 1779 | | | | 1780 | 24 | Device Identifier | OPTIONAL | 1781 | | | | 1782 | 25 | Image Not Match | OPTIONAL | 1783 | | | | 1784 | 26 | Minimum Battery | OPTIONAL | 1785 | | | | 1786 | 27 | Update Authorized | OPTIONAL | 1787 | | | | 1788 | 28 | Version | OPTIONAL | 1789 | | | | 1790 | nint | Custom Condition | OPTIONAL | 1791 +----------------+-------------------+----------------+ 1793 Each condition MUST report a success code on completion. If a 1794 condition reports failure, then the current sequence of commands MUST 1795 terminate. If a condition requires additional information, this MUST 1796 be specified in one or more parameters before the condition is 1797 executed. If a Recipient attempts to process a condition that 1798 expects additional information and that information has not been set, 1799 it MUST report a failure. If a Recipient encounters an unknown 1800 Condition Code, it MUST report a failure. 1802 Positive Condition numbers are reserved for IANA registration. 1803 Negative numbers are reserved for proprietary, application-specific 1804 directives. 1806 7.9.1. Identifier Conditions 1808 There are three identifier-based conditions: suit-condition-vendor- 1809 identifier, suit-condition-class-identifier, and suit-condition- 1810 device-identifier. Each of these conditions match a RFC 4122 1811 [RFC4122] UUID that MUST have already been set as a parameter. The 1812 installing device MUST match the specified UUID in order to consider 1813 the manifest valid. These identifiers MAY be scoped by component. 1815 The Recipient uses the ID parameter that has already been set using 1816 the Set Parameters directive. If no ID has been set, this condition 1817 fails. suit-condition-class-identifier and suit-condition-vendor- 1818 identifier are REQUIRED to implement. suit-condition-device- 1819 identifier is OPTIONAL to implement. 1821 7.9.2. suit-condition-image-match 1823 Verify that the current component matches the digest parameter for 1824 the current component. The digest is verified against the digest 1825 specified in the Component's parameters list. If no digest is 1826 specified, the condition fails. suit-condition-image-match is 1827 REQUIRED to implement. 1829 7.9.3. suit-condition-image-not-match 1831 Verify that the current component does not match the supplied digest. 1832 If no digest is specified, then the digest is compared against the 1833 digest specified in the Component's parameters list. If no digest is 1834 specified, the condition fails. suit-condition-image-not-match is 1835 OPTIONAL to implement. 1837 7.9.4. suit-condition-use-before 1839 Verify that the current time is BEFORE the specified time. suit- 1840 condition-use-before is used to specify the last time at which an 1841 update should be installed. The recipient evaluates the current time 1842 against the suit-parameter-use-before parameter, which must have 1843 already been set as a parameter, encoded as a POSIX timestamp, that 1844 is seconds after 1970-01-01 00:00:00. Timestamp conditions MUST be 1845 evaluated in 64 bits, regardless of encoded CBOR size. suit- 1846 condition-use-before is OPTIONAL to implement. 1848 7.9.5. suit-condition-minimum-battery 1850 suit-condition-minimum-battery provides a mechanism to test a 1851 device's battery level before installing an update. This condition 1852 is for use in primary-cell applications, where the battery is only 1853 ever discharged. For batteries that are charged, suit-directive-wait 1854 is more appropriate, since it defines a "wait" until the battery 1855 level is sufficient to install the update. suit-condition-minimum- 1856 battery is specified in mWh. suit-condition-minimum-battery is 1857 OPTIONAL to implement. 1859 7.9.6. suit-condition-update-authorized 1861 Request Authorization from the application and fail if not 1862 authorized. This can allow a user to decline an update. Argument is 1863 an integer priority level. Priorities are application defined. suit- 1864 condition-update-authorized is OPTIONAL to implement. 1866 7.9.7. suit-condition-version 1868 suit-condition-version allows comparing versions of firmware. 1869 Verifying image digests is preferred to version checks because 1870 digests are more precise. The image can be compared as: 1872 - Greater. 1874 - Greater or Equal. 1876 - Equal. 1878 - Lesser or Equal. 1880 - Lesser. 1882 Versions are encoded as a CBOR list of integers. Comparisons are 1883 done on each integer in sequence. Comparison stops after all 1884 integers in the list defined by the manifest have been consumed OR 1885 after a non-equal match has occurred. For example, if the manifest 1886 defines a comparison, "Equal [1]", then this will match all version 1887 sequences starting with 1. If a manifest defines both "Greater or 1888 Equal [1,0]" and "Lesser [1,10]", then it will match versions 1.0.x 1889 up to, but not including 1.10. 1891 The following CDDL describes SUIT_Condition_Version_Argument 1892 SUIT_Condition_Version_Argument = [ 1893 suit-condition-version-comparison-type: 1894 SUIT_Condition_Version_Comparison_Types, 1895 suit-condition-version-comparison-value: 1896 SUIT_Condition_Version_Comparison_Value 1897 ] 1899 SUIT_Condition_Version_Comparison_Types /= 1900 suit-condition-version-comparison-greater 1901 SUIT_Condition_Version_Comparison_Types /= 1902 suit-condition-version-comparison-greater-equal 1903 SUIT_Condition_Version_Comparison_Types /= 1904 suit-condition-version-comparison-equal 1905 SUIT_Condition_Version_Comparison_Types /= 1906 suit-condition-version-comparison-lesser-equal 1907 SUIT_Condition_Version_Comparison_Types /= 1908 suit-condition-version-comparison-lesser 1910 SUIT_Condition_Version_Comparison_Value = [+int] 1912 While the exact encoding of versions is application-defined, semantic 1913 versions map conveniently. For example, 1915 - 1.2.3 = [1,2,3]. 1917 - 1.2-rc3 = [1,2,-1,3]. 1919 - 1.2-beta = [1,2,-2]. 1921 - 1.2-alpha = [1,2,-3]. 1923 - 1.2-alpha4 = [1,2,-3,4]. 1925 suit-condition-version is OPTIONAL to implement. 1927 7.9.8. SUIT_Condition_Custom 1929 SUIT_Condition_Custom describes any proprietary, application specific 1930 condition. This is encoded as a negative integer, chosen by the 1931 firmware developer. If additional information must be provided to 1932 the condition, it should be encoded in a custom parameter (a nint) as 1933 described in Section 7.6. SUIT_Condition_Custom is OPTIONAL to 1934 implement. 1936 7.9.9. Identifiers 1938 Many conditions use identifiers to determine whether a manifest 1939 matches a given Recipient or not. These identifiers are defined to 1940 be RFC 4122 [RFC4122] UUIDs. These UUIDs are explicitly NOT human- 1941 readable. They are for machine-based matching only. 1943 A device may match any number of UUIDs for vendor or class 1944 identifier. This may be relevant to physical or software modules. 1945 For example, a device that has an OS and one or more applications 1946 might list one Vendor ID for the OS and one or more additional Vendor 1947 IDs for the applications. This device might also have a Class ID 1948 that must be matched for the OS and one or more Class IDs for the 1949 applications. 1951 A more complete example: A device has the following physical 1952 components: 1. A host MCU 2. A WiFi module 1954 This same device has three software modules: 1. An operating system 1955 2. A WiFi module interface driver 3. An application 1957 Suppose that the WiFi module's firmware has a proprietary update 1958 mechanism and doesn't support manifest processing. This device can 1959 report four class IDs: 1961 1. hardware model/revision 1963 2. OS 1965 3. WiFi module model/revision 1967 4. Application 1969 This allows the OS, WiFi module, and application to be updated 1970 independently. To combat possible incompatibilities, the OS class ID 1971 can be changed each time the OS has a change to its API. 1973 This approach allows a vendor to target, for example, all devices 1974 with a particular WiFi module with an update, which is a very 1975 powerful mechanism, particularly when used for security updates. 1977 7.9.9.1. Creating UUIDs: 1979 UUIDs MUST be created according to RFC 4122 [RFC4122]. UUIDs SHOULD 1980 use versions 3, 4, or 5, as described in RFC4122. Versions 1 and 2 1981 do not provide a tangible benefit over version 4 for this 1982 application. 1984 The RECOMMENDED method to create a vendor ID is: Vendor ID = 1985 UUID5(DNS_PREFIX, vendor domain name) 1987 The RECOMMENDED method to create a class ID is: Class ID = 1988 UUID5(Vendor ID, Class-Specific-Information) 1990 Class-specific information is composed of a variety of data, for 1991 example: 1993 - Model number. 1995 - Hardware revision. 1997 - Bootloader version (for immutable bootloaders). 1999 7.9.10. SUIT_Condition CDDL 2001 The following CDDL describes SUIT_Condition: 2003 SUIT_Condition //= (suit-condition-vendor-identifier, nil) 2004 SUIT_Condition //= (suit-condition-class-identifier, nil) 2005 SUIT_Condition //= (suit-condition-device-identifier, nil) 2006 SUIT_Condition //= (suit-condition-image-match, nil) 2007 SUIT_Condition //= (suit-condition-image-not-match, nil) 2008 SUIT_Condition //= (suit-condition-use-before, nil) 2009 SUIT_Condition //= (suit-condition-minimum-battery, nil) 2010 SUIT_Condition //= (suit-condition-update-authorized, nil) 2011 SUIT_Condition //= (suit-condition-version, nil) 2012 SUIT_Condition //= (suit-condition-component-offset, nil) 2014 7.10. SUIT_Directive 2016 Directives are used to define the behavior of the recipient. 2017 Directives include: 2019 +--------------+--------------------+-------------------------------+ 2020 | Directive | Directive Name | Implementation | 2021 | Code | | | 2022 +--------------+--------------------+-------------------------------+ 2023 | 12 | Set Component | REQUIRED if more than one | 2024 | | Index | component | 2025 | | | | 2026 | 13 | Set Dependency | REQUIRED if dependencies used | 2027 | | Index | | 2028 | | | | 2029 | 14 | Abort | OPTIONAL | 2030 | | | | 2031 | 15 | Try Each | OPTIONAL | 2032 | | | | 2033 | 16 | Reserved | N/A | 2034 | | | | 2035 | 17 | Reserved | N/A | 2036 | | | | 2037 | 18 | Process Dependency | OPTIONAL | 2038 | | | | 2039 | 19 | Set Parameters | OPTIONAL | 2040 | | | | 2041 | 20 | Override | REQUIRED | 2042 | | Parameters | | 2043 | | | | 2044 | 21 | Fetch | REQUIRED for Updater | 2045 | | | | 2046 | 22 | Copy | OPTIONAL | 2047 | | | | 2048 | 23 | Run | REQUIRED for Bootloader | 2049 | | | | 2050 | 29 | Wait | OPTIONAL | 2051 | | | | 2052 | 30 | Run Sequence | OPTIONAL | 2053 | | | | 2054 | 32 | Swap | OPTIONAL | 2055 +--------------+--------------------+-------------------------------+ 2057 When a Recipient executes a Directive, it MUST report a success code. 2058 If the Directive reports failure, then the current Command Sequence 2059 MUST terminate. 2061 7.10.1. suit-directive-set-component-index 2063 Set Component Index defines the component to which successive 2064 directives and conditions will apply. The supplied argument MUST be 2065 either a boolean or an unsigned integer index into the concatenation 2066 of suit-components and suit-dependency-components. If the following 2067 directives apply to ALL components, then the boolean value "True" is 2068 used instead of an index. True does not apply to dependency 2069 components. If the following directives apply to NO components, then 2070 the boolean value "False" is used. When suit-directive-set- 2071 dependency-index is used, suit-directive-set-component-index = False 2072 is implied. When suit-directive-set-component-index is used, suit- 2073 directive-set-dependency-index = False is implied. 2075 The following CDDL describes the argument to suit-directive-set- 2076 component-index. 2078 SUIT_Directive_Set_Component_Index_Argument = uint/bool 2080 7.10.2. suit-directive-set-dependency-index 2082 Set Dependency Index defines the manifest to which successive 2083 directives and conditions will apply. The supplied argument MUST be 2084 either a boolean or an unsigned integer index into the dependencies. 2085 If the following directives apply to ALL dependencies, then the 2086 boolean value "True" is used instead of an index. If the following 2087 directives apply to NO dependencies, then the boolean value "False" 2088 is used. When suit-directive-set-component-index is used, suit- 2089 directive-set-dependency-index = False is implied. When suit- 2090 directive-set-dependency-index is used, suit-directive-set-component- 2091 index = False is implied. 2093 Typical operations that require suit-directive-set-dependency-index 2094 include setting a source URI, invoking "Fetch," or invoking "Process 2095 Dependency" for an individual dependency. 2097 The following CDDL describes the argument to suit-directive-set- 2098 dependency-index. 2100 SUIT_Directive_Set_Manifest_Index_Argument = uint/bool 2102 7.10.3. suit-directive-abort 2104 Unconditionally fail. This operation is typically used in 2105 conjunction with suit-directive-try-each. 2107 7.10.4. suit-directive-run-sequence 2109 To enable conditional commands, and to allow several strictly ordered 2110 sequences to be executed out-of-order, suit-directive-run-sequence 2111 allows the manifest processor to execute its argument as a 2112 SUIT_Command_Sequence. The argument must be wrapped in a bstr. 2114 When a sequence is executed, any failure of a condition causes 2115 immediate termination of the sequence. 2117 The following CDDL describes the SUIT_Run_Sequence argument. 2119 SUIT_Directive_Run_Sequence_Argument = bstr .cbor SUIT_Command_Sequence 2121 When suit-directive-run-sequence completes, it forwards the last 2122 status code that occurred in the sequence. If the Soft Failure 2123 parameter is true, then suit-directive-run-sequence only fails when a 2124 directive in the argument sequence fails. 2126 SUIT_Parameter_Soft_Failure defaults to False when suit-directive- 2127 run-sequence begins. Its value is discarded when suit-directive-run- 2128 sequence terminates. 2130 7.10.5. suit-directive-try-each 2132 This command runs several SUIT_Command_Sequence, one after another, 2133 in a strict order. Use this command to implement a "try/catch-try/ 2134 catch" sequence. Manifest processors MAY implement this command. 2136 SUIT_Parameter_Soft_Failure is initialized to True at the beginning 2137 of each sequence. If one sequence aborts due to a condition failure, 2138 the next is started. If no sequence completes without condition 2139 failure, then suit-directive-try-each returns an error. If a 2140 particular application calls for all sequences to fail and still 2141 continue, then an empty sequence (nil) can be added to the Try Each 2142 Argument. 2144 The following CDDL describes the SUIT_Try_Each argument. 2146 SUIT_Directive_Try_Each_Argument = [ 2147 + bstr .cbor SUIT_Command_Sequence, 2148 nil / bstr .cbor SUIT_Command_Sequence 2149 ] 2151 7.10.6. suit-directive-process-dependency 2153 Execute the commands in the common section of the current dependency, 2154 followed by the commands in the equivalent section of the current 2155 dependency. For example, if the current section is "fetch payload," 2156 this will execute "common" in the current dependency, then "fetch 2157 payload" in the current dependency. Once this is complete, the 2158 command following suit-directive-process-dependency will be 2159 processed. 2161 If the current dependency is False, this directive has no effect. If 2162 the current dependency is True, then this directive applies to all 2163 dependencies. If the current section is "common," this directive 2164 MUST have no effect. 2166 When SUIT_Process_Dependency completes, it forwards the last status 2167 code that occurred in the dependency. 2169 The argument to suit-directive-process-dependency is defined in the 2170 following CDDL. 2172 SUIT_Directive_Process_Dependency_Argument = nil 2174 7.10.7. suit-directive-set-parameters 2176 suit-directive-set-parameters allows the manifest to configure 2177 behavior of future directives by changing parameters that are read by 2178 those directives. When dependencies are used, suit-directive-set- 2179 parameters also allows a manifest to modify the behavior of its 2180 dependencies. 2182 Available parameters are defined in Section 7.6. 2184 If a parameter is already set, suit-directive-set-parameters will 2185 skip setting the parameter to its argument. This provides the core 2186 of the override mechanism, allowing dependent manifests to change the 2187 behavior of a manifest. 2189 The argument to suit-directive-set-parameters is defined in the 2190 following CDDL. 2192 SUIT_Directive_Set_Parameters_Argument = {+ SUIT_Parameters} 2194 N.B.: A directive code is reserved for an optimization: a way to set 2195 a parameter to the contents of another parameter, optionally with 2196 another component ID. 2198 7.10.8. suit-directive-override-parameters 2200 suit-directive-override-parameters replaces any listed parameters 2201 that are already set with the values that are provided in its 2202 argument. This allows a manifest to prevent replacement of critical 2203 parameters. 2205 Available parameters are defined in Section 7.6. 2207 The argument to suit-directive-override-parameters is defined in the 2208 following CDDL. 2210 SUIT_Directive_Override_Parameters_Argument = {+ SUIT_Parameters} 2212 7.10.9. suit-directive-fetch 2214 suit-directive-fetch instructs the manifest processor to obtain one 2215 or more manifests or payloads, as specified by the manifest index and 2216 component index, respectively. 2218 suit-directive-fetch can target one or more manifests and one or more 2219 payloads. suit-directive-fetch retrieves each component and each 2220 manifest listed in component-index and manifest-index, respectively. 2221 If component-index or manifest-index is True, instead of an integer, 2222 then all current manifest components/manifests are fetched. The 2223 current manifest's dependent-components are not automatically 2224 fetched. In order to pre-fetch these, they MUST be specified in a 2225 component-index integer. 2227 suit-directive-fetch typically takes no arguments unless one is 2228 needed to modify fetch behavior. If an argument is needed, it must 2229 be wrapped in a bstr. 2231 suit-directive-fetch reads the URI or URI List parameter to find the 2232 source of the fetch it performs. 2234 The behavior of suit-directive-fetch can be modified by setting one 2235 or more of SUIT_Parameter_Encryption_Info, 2236 SUIT_Parameter_Compression_Info, SUIT_Parameter_Unpack_Info. These 2237 three parameters each activate and configure a processing step that 2238 can be applied to the data that is transferred during suit-directive- 2239 fetch. 2241 The argument to suit-directive-fetch is defined in the following 2242 CDDL. 2244 SUIT_Directive_Fetch_Argument = nil/bstr 2246 7.10.10. suit-directive-copy 2248 suit-directive-copy instructs the manifest processor to obtain one or 2249 more payloads, as specified by the component index. suit-directive- 2250 copy retrieves each component listed in component-index, 2251 respectively. If component-index is True, instead of an integer, 2252 then all current manifest components are copied. The current 2253 manifest's dependent-components are not automatically copied. In 2254 order to copy these, they MUST be specified in a component-index 2255 integer. 2257 The behavior of suit-directive-copy can be modified by setting one or 2258 more of SUIT_Parameter_Encryption_Info, 2259 SUIT_Parameter_Compression_Info, SUIT_Parameter_Unpack_Info. These 2260 three parameters each activate and configure a processing step that 2261 can be applied to the data that is transferred during suit-directive- 2262 copy. 2264 *N.B.* Fetch and Copy are very similar. Merging them into one 2265 command may be appropriate. 2267 suit-directive-copy reads its source from 2268 SUIT_Parameter_Source_Component. 2270 The argument to suit-directive-copy is defined in the following CDDL. 2272 SUIT_Directive_Copy_Argument = nil 2274 7.10.11. suit-directive-swap 2276 suit-directive-swap instructs the manifest processor to move the 2277 source to the destination and the destination to the source 2278 simultaneously. Swap has nearly identical semantics to suit- 2279 directive-copy except that suit-directive-swap replaces the source 2280 with the current contents of the destination in an application- 2281 defined way. If SUIT_Parameter_Compression_Info or 2282 SUIT_Parameter_Encryption_Info are present, they must be handled in a 2283 symmetric way, so that the source is decompressed into the 2284 destination and the destination is compressed into the source. The 2285 source is decrypted into the destination and the destination is 2286 encrypted into the source. suit-directive-swap is OPTIONAL to 2287 implement. 2289 7.10.12. suit-directive-run 2291 suit-directive-run directs the manifest processor to transfer 2292 execution to the current Component Index. When this is invoked, the 2293 manifest processor MAY be unloaded and execution continues in the 2294 Component Index. Arguments provided to Run are forwarded to the 2295 executable code located in Component Index, in an application- 2296 specific way. For example, this could form the Linux Kernel Command 2297 Line if booting a Linux device. 2299 If the executable code at Component Index is constructed in such a 2300 way that it does not unload the manifest processor, then the manifest 2301 processor may resume execution after the executable completes. This 2302 allows the manifest processor to invoke suitable helpers and to 2303 verify them with image conditions. 2305 The argument to suit-directive-run is defined in the following CDDL. 2307 SUIT_Directive_Run_Argument = nil/bstr 2309 7.10.13. suit-directive-wait 2311 suit-directive-wait directs the manifest processor to pause until a 2312 specified event occurs. Some possible events include: 2314 1. Authorization 2316 2. External Power 2318 3. Network availability 2320 4. Other Device Firmware Version 2322 5. Time 2324 6. Time of Day 2326 7. Day of Week 2328 The following CDDL defines the encoding of these events. 2330 SUIT_Wait_Events //= (suit-wait-event-authorization => int) 2331 SUIT_Wait_Events //= (suit-wait-event-power => int) 2332 SUIT_Wait_Events //= (suit-wait-event-network => int) 2333 SUIT_Wait_Events //= (suit-wait-event-other-device-version 2334 => SUIT_Wait_Event_Argument_Other_Device_Version) 2335 SUIT_Wait_Events //= (suit-wait-event-time => uint); Timestamp 2336 SUIT_Wait_Events //= (suit-wait-event-time-of-day 2337 => uint); Time of Day (seconds since 00:00:00) 2338 SUIT_Wait_Events //= (suit-wait-event-day-of-week 2339 => uint); Days since Sunday 2341 SUIT_Wait_Event_Argument_Authorization = int ; priority 2342 SUIT_Wait_Event_Argument_Power = int ; Power Level 2343 SUIT_Wait_Event_Argument_Network = int ; Network State 2344 SUIT_Wait_Event_Argument_Other_Device_Version = [ 2345 other-device: bstr, 2346 other-device-version: [+int] 2347 ] 2348 SUIT_Wait_Event_Argument_Time = uint ; Timestamp 2349 SUIT_Wait_Event_Argument_Time_Of_Day = uint ; Time of Day 2350 ; (seconds since 00:00:00) 2351 SUIT_Wait_Event_Argument_Day_Of_Week = uint ; Days since Sunday 2353 7.10.14. SUIT_Directive CDDL 2355 The following CDDL describes SUIT_Directive: 2357 SUIT_Directive //= (suit-directive-set-component-index, uint/bool) 2358 SUIT_Directive //= (suit-directive-set-dependency-index, uint/bool) 2359 SUIT_Directive //= (suit-directive-run-sequence, 2360 bstr .cbor SUIT_Command_Sequence) 2361 SUIT_Directive //= (suit-directive-try-each, 2362 SUIT_Directive_Try_Each_Argument) 2363 SUIT_Directive //= (suit-directive-process-dependency, nil) 2364 SUIT_Directive //= (suit-directive-set-parameters, 2365 {+ SUIT_Parameters}) 2366 SUIT_Directive //= (suit-directive-override-parameters, 2367 {+ SUIT_Parameters}) 2368 SUIT_Directive //= (suit-directive-fetch, nil) 2369 SUIT_Directive //= (suit-directive-copy, nil) 2370 SUIT_Directive //= (suit-directive-run, nil) 2371 SUIT_Directive //= (suit-directive-wait, 2372 { + SUIT_Wait_Events }) 2374 SUIT_Directive_Try_Each_Argument = [ 2375 + bstr .cbor SUIT_Command_Sequence, 2376 nil / bstr .cbor SUIT_Command_Sequence 2377 ] 2379 SUIT_Wait_Events //= (suit-wait-event-authorization => int) 2380 SUIT_Wait_Events //= (suit-wait-event-power => int) 2381 SUIT_Wait_Events //= (suit-wait-event-network => int) 2382 SUIT_Wait_Events //= (suit-wait-event-other-device-version 2383 => SUIT_Wait_Event_Argument_Other_Device_Version) 2384 SUIT_Wait_Events //= (suit-wait-event-time => uint); Timestamp 2385 SUIT_Wait_Events //= (suit-wait-event-time-of-day 2386 => uint); Time of Day (seconds since 00:00:00) 2387 SUIT_Wait_Events //= (suit-wait-event-day-of-week 2388 => uint); Days since Sunday 2390 SUIT_Wait_Event_Argument_Authorization = int ; priority 2391 SUIT_Wait_Event_Argument_Power = int ; Power Level 2392 SUIT_Wait_Event_Argument_Network = int ; Network State 2393 SUIT_Wait_Event_Argument_Other_Device_Version = [ 2394 other-device: bstr, 2395 other-device-version: [+int] 2396 ] 2397 SUIT_Wait_Event_Argument_Time = uint ; Timestamp 2398 SUIT_Wait_Event_Argument_Time_Of_Day = uint ; Time of Day 2399 ; (seconds since 00:00:00) 2400 SUIT_Wait_Event_Argument_Day_Of_Week = uint ; Days since Sunday 2402 7.11. SUIT_Text_Map 2404 The SUIT_Text_Map contains all text descriptions needed for this 2405 manifest. The text section is typically severable, allowing 2406 manifests to be distributed without the text, since end-nodes do not 2407 require text. The meaning of each field is described below. 2409 Each section MAY be present. If present, each section MUST be as 2410 described. Negative integer IDs are reserved for application- 2411 specific text values. 2413 +----+-----------------------+--------------------------------------+ 2414 | ID | Name | Summary | 2415 +----+-----------------------+--------------------------------------+ 2416 | 1 | manifest-description | Free text description of the | 2417 | | | manifest | 2418 | | | | 2419 | 2 | update-description | Free text description of the update | 2420 | | | | 2421 | 3 | vendor-name | Free text vendor name | 2422 | | | | 2423 | 4 | model-name | Free text model name | 2424 | | | | 2425 | 5 | vendor-domain | The domain used to create the | 2426 | | | vendor-id (Section 7.9.9.1) | 2427 | | | | 2428 | 6 | model-info | The information used to create the | 2429 | | | class-id (Section 7.9.9.1) | 2430 | | | | 2431 | 7 | component-description | Free text description of each | 2432 | | | component in the manifest | 2433 | | | | 2434 | 8 | json-source | The JSON-formatted document that was | 2435 | | | used to create the manifest | 2436 | | | | 2437 | 9 | yaml-source | The yaml-formatted document that was | 2438 | | | used to create the manifest | 2439 | | | | 2440 | 10 | version-dependencies | List of component versions required | 2441 | | | by the manifest | 2442 +----+-----------------------+--------------------------------------+ 2444 8. Access Control Lists 2446 To manage permissions in the manifest, there are three models that 2447 can be used. 2449 First, the simplest model requires that all manifests are 2450 authenticated by a single trusted key. This mode has the advantage 2451 that only a root manifest needs to be authenticated, since all of its 2452 dependencies have digests included in the root manifest. 2454 This simplest model can be extended by adding key delegation without 2455 much increase in complexity. 2457 A second model requires an ACL to be presented to the device, 2458 authenticated by a trusted party or stored on the device. This ACL 2459 grants access rights for specific component IDs or component ID 2460 prefixes to the listed identities or identity groups. Any identity 2461 may verify an image digest, but fetching into or fetching from a 2462 component ID requires approval from the ACL. 2464 A third model allows a device to provide even more fine-grained 2465 controls: The ACL lists the component ID or component ID prefix that 2466 an identity may use, and also lists the commands that the identity 2467 may use in combination with that component ID. 2469 9. SUIT digest container 2471 RFC 8152 [RFC8152] provides containers for signature, MAC, and 2472 encryption, but no basic digest container. The container needed for 2473 a digest requires a type identifier and a container for the raw 2474 digest data. Some forms of digest may require additional parameters. 2475 These can be added following the digest. This structure is described 2476 by the following CDDL. 2478 The algorithms listed are sufficient for verifying integrity of 2479 Firmware Updates as of this writing, however this may change over 2480 time. 2482 SUIT_Digest = [ 2483 suit-digest-algorithm-id : $suit-digest-algorithm-ids, 2484 suit-digest-bytes : bytes, 2485 ? suit-digest-parameters : any 2486 ] 2488 digest-algorithm-ids /= algorithm-id-sha224 2489 digest-algorithm-ids /= algorithm-id-sha256 2490 digest-algorithm-ids /= algorithm-id-sha384 2491 digest-algorithm-ids /= algorithm-id-sha512 2492 digest-algorithm-ids /= algorithm-id-sha3-224 2493 digest-algorithm-ids /= algorithm-id-sha3-256 2494 digest-algorithm-ids /= algorithm-id-sha3-384 2495 digest-algorithm-ids /= algorithm-id-sha3-512 2497 algorithm-id-sha224 = 1 2498 algorithm-id-sha256 = 2 2499 algorithm-id-sha384 = 3 2500 algorithm-id-sha512 = 4 2501 algorithm-id-sha3-224 = 5 2502 algorithm-id-sha3-256 = 6 2503 algorithm-id-sha3-384 = 7 2504 algorithm-id-sha3-512 = 8 2506 10. Creating Conditional Sequences 2508 For some use cases, it is important to provide a sequence that can 2509 fail without terminating an update. For example, a dual-image XIP 2510 MCU may require an update that can be placed at one of two offsets. 2511 This has two implications, first, the digest of each offset will be 2512 different. Second, the image fetched for each offset will have a 2513 different URI. Conditional sequences allow this to be resolved in a 2514 simple way. 2516 The following JSON representation of a manifest demonstrates how this 2517 would be represented. It assumes that the bootloader and manifest 2518 processor take care of A/B switching and that the manifest is not 2519 aware of this distinction. 2521 { 2522 "structure-version" : 1, 2523 "sequence-number" : 7, 2524 "common" :{ 2525 "components" : [ 2526 [b'0'] 2527 ], 2528 "common-sequence" : [ 2529 { 2530 "directive-set-var" : { 2531 "size": 32567 2532 }, 2533 }, 2534 { 2535 "try-each" : [ 2536 [ 2537 {"condition-component-offset" : ""}, 2538 { 2539 "directive-set-var": { 2540 "digest" : "" 2541 } 2542 } 2543 ], 2544 [ 2545 {"condition-component-offset" : ""}, 2546 { 2547 "directive-set-var": { 2548 "digest" : "" 2549 } 2550 } 2551 ], 2552 [{ "abort" : null }] 2553 ] 2554 } 2555 ] 2556 } 2557 "fetch" : [ 2558 { 2559 "try-each" : [ 2560 [ 2561 {"condition-component-offset" : ""}, 2562 { 2563 "directive-set-var": { 2564 "uri" : "" 2565 } 2566 } 2567 ], 2568 [ 2569 {"condition-component-offset" : ""}, 2570 { 2571 "directive-set-var": { 2572 "uri" : "" 2573 } 2574 } 2575 ], 2576 [{ "directive-abort" : null }] 2577 ] 2579 }, 2580 "fetch" : null 2581 ] 2582 } 2584 11. Full CDDL 2586 In order to create a valid SUIT Manifest document the structure of 2587 the corresponding CBOR message MUST adhere to the following CDDL data 2588 definition. 2590 SUIT_Envelope = { 2591 suit-delegation => bstr .cbor SUIT_Delegation 2592 suit-authentication-wrapper 2593 => bstr .cbor SUIT_Authentication_Wrapper / nil, 2594 $$SUIT_Manifest_Wrapped, 2595 * $$SUIT_Severed_Fields, 2596 } 2598 SUIT_Delegation = [ + [ + CWT ] ] 2600 CWT = SUIT_Authentication_Block 2602 SUIT_Authentication_Wrapper = [ + bstr .cbor SUIT_Authentication_Block ] 2604 SUIT_Authentication_Block /= COSE_Mac_Tagged 2605 SUIT_Authentication_Block /= COSE_Sign_Tagged 2606 SUIT_Authentication_Block /= COSE_Mac0_Tagged 2607 SUIT_Authentication_Block /= COSE_Sign1_Tagged 2609 $$SUIT_Manifest_Wrapped //= (suit-manifest => bstr .cbor SUIT_Manifest) 2610 $$SUIT_Manifest_Wrapped //= ( 2611 suit-manifest-encryption-info => bstr .cbor SUIT_Encryption_Wrapper, 2612 suit-manifest-encrypted => bstr 2613 ) 2615 SUIT_Encryption_Wrapper = COSE_Encrypt_Tagged / COSE_Encrypt0_Tagged 2617 $$SUIT_Severed_Fields //= ( suit-dependency-resolution => 2618 bstr .cbor SUIT_Command_Sequence) 2619 $$SUIT_Severed_Fields //= (suit-payload-fetch => 2620 bstr .cbor SUIT_Command_Sequence) 2621 $$SUIT_Severed_Fields //= (suit-install => 2622 bstr .cbor SUIT_Command_Sequence) 2623 $$SUIT_Severed_Fields //= (suit-text => 2624 bstr .cbor SUIT_Text_Map) 2625 $$SUIT_Severed_Fields //= (suit-coswid => 2626 bstr .cbor concise-software-identity) 2628 COSE_Mac_Tagged = any 2629 COSE_Sign_Tagged = any 2630 COSE_Mac0_Tagged = any 2631 COSE_Sign1_Tagged = any 2632 COSE_Encrypt_Tagged = any 2633 COSE_Encrypt0_Tagged = any 2635 SUIT_Digest = [ 2636 suit-digest-algorithm-id : suit-digest-algorithm-ids, 2637 suit-digest-bytes : bstr, 2638 ? suit-digest-parameters : any 2639 ] 2641 ; Named Information Hash Algorithm Identifiers 2642 suit-digest-algorithm-ids /= algorithm-id-sha224 2643 suit-digest-algorithm-ids /= algorithm-id-sha256 2644 suit-digest-algorithm-ids /= algorithm-id-sha384 2645 suit-digest-algorithm-ids /= algorithm-id-sha512 2646 suit-digest-algorithm-ids /= algorithm-id-sha3-224 2647 suit-digest-algorithm-ids /= algorithm-id-sha3-256 2648 suit-digest-algorithm-ids /= algorithm-id-sha3-384 2649 suit-digest-algorithm-ids /= algorithm-id-sha3-512 2651 algorithm-id-sha224 = 1 2652 algorithm-id-sha256 = 2 2653 algorithm-id-sha384 = 3 2654 algorithm-id-sha512 = 4 2655 algorithm-id-sha3-224 = 5 2656 algorithm-id-sha3-256 = 6 2657 algorithm-id-sha3-384 = 7 2658 algorithm-id-sha3-512 = 8 2660 SUIT_Manifest = { 2661 suit-manifest-version => 1, 2662 suit-manifest-sequence-number => uint, 2663 suit-common => bstr .cbor SUIT_Common, 2664 ? suit-reference-uri => #6.32(tstr), 2665 * $$SUIT_Severable_Command_Sequences, 2666 * $$SUIT_Command_Sequences, 2667 * $$SUIT_Protected_Elements, 2668 } 2670 $$SUIT_Severable_Command_Sequences //= (suit-dependency-resolution => 2671 SUIT_Severable_Command_Sequence) 2672 $$SUIT_Severable_Command_Sequences //= (suit-payload-fetch => 2673 SUIT_Severable_Command_Sequence) 2674 $$SUIT_Severable_Command_Sequences //= (suit-install => 2675 SUIT_Severable_Command_Sequence) 2677 SUIT_Severable_Command_Sequence = 2678 SUIT_Digest / bstr .cbor SUIT_Command_Sequence 2680 $$SUIT_Command_Sequences //= ( suit-validate => 2681 bstr .cbor SUIT_Command_Sequence ) 2682 $$SUIT_Command_Sequences //= ( suit-load => 2683 bstr .cbor SUIT_Command_Sequence ) 2684 $$SUIT_Command_Sequences //= ( suit-run => 2685 bstr .cbor SUIT_Command_Sequence ) 2687 $$SUIT_Protected_Elements //= ( suit-text => SUIT_Digest ) 2688 $$SUIT_Protected_Elements //= ( suit-coswid => SUIT_Digest ) 2690 SUIT_Common = { 2691 ? suit-dependencies => bstr .cbor SUIT_Dependencies, 2692 ? suit-components => bstr .cbor SUIT_Components, 2693 ? suit-dependency-components 2694 => bstr .cbor SUIT_Component_References, 2695 ? suit-common-sequence => bstr .cbor SUIT_Command_Sequence, 2696 } 2698 SUIT_Dependencies = [ + SUIT_Dependency ] 2699 SUIT_Components = [ + SUIT_Component_Identifier ] 2700 SUIT_Component_References = [ + SUIT_Component_Reference ] 2702 concise-software-identity = any 2704 SUIT_Dependency = { 2705 suit-dependency-digest => SUIT_Digest, 2706 suit-dependency-prefix => SUIT_Component_Identifier, 2707 } 2709 SUIT_Component_Identifier = [* bstr] 2711 SUIT_Component_Reference = { 2712 suit-component-identifier => SUIT_Component_Identifier, 2713 suit-component-dependency-index => uint 2714 } 2716 SUIT_Command_Sequence = [ + ( 2717 SUIT_Condition // SUIT_Directive // SUIT_Command_Custom 2718 ) ] 2720 SUIT_Command_Custom = (suit-command-custom, bstr/tstr/int/nil) 2721 SUIT_Condition //= (suit-condition-vendor-identifier, nil) 2722 SUIT_Condition //= (suit-condition-class-identifier, nil) 2723 SUIT_Condition //= (suit-condition-device-identifier, nil) 2724 SUIT_Condition //= (suit-condition-image-match, nil) 2725 SUIT_Condition //= (suit-condition-image-not-match, nil) 2726 SUIT_Condition //= (suit-condition-use-before, nil) 2727 SUIT_Condition //= (suit-condition-minimum-battery, nil) 2728 SUIT_Condition //= (suit-condition-update-authorized, nil) 2729 SUIT_Condition //= (suit-condition-version, nil) 2730 SUIT_Condition //= (suit-condition-component-offset, nil) 2732 SUIT_Directive //= (suit-directive-set-component-index, uint/bool) 2733 SUIT_Directive //= (suit-directive-set-dependency-index, uint/bool) 2734 SUIT_Directive //= (suit-directive-run-sequence, 2735 bstr .cbor SUIT_Command_Sequence) 2736 SUIT_Directive //= (suit-directive-try-each, 2737 SUIT_Directive_Try_Each_Argument) 2738 SUIT_Directive //= (suit-directive-process-dependency, nil) 2739 SUIT_Directive //= (suit-directive-set-parameters, 2740 {+ SUIT_Parameters}) 2741 SUIT_Directive //= (suit-directive-override-parameters, 2742 {+ SUIT_Parameters}) 2743 SUIT_Directive //= (suit-directive-fetch, nil) 2744 SUIT_Directive //= (suit-directive-copy, nil) 2745 SUIT_Directive //= (suit-directive-swap, nil) 2746 SUIT_Directive //= (suit-directive-run, nil) 2747 SUIT_Directive //= (suit-directive-wait, nil) 2748 SUIT_Directive //= (suit-directive-abort, nil) 2750 SUIT_Directive_Try_Each_Argument = [ 2751 + bstr .cbor SUIT_Command_Sequence, 2752 nil / bstr .cbor SUIT_Command_Sequence 2753 ] 2755 SUIT_Wait_Event = { + SUIT_Wait_Events } 2757 SUIT_Wait_Events //= (suit-wait-event-authorization => int) 2758 SUIT_Wait_Events //= (suit-wait-event-power => int) 2759 SUIT_Wait_Events //= (suit-wait-event-network => int) 2760 SUIT_Wait_Events //= (suit-wait-event-other-device-version 2761 => SUIT_Wait_Event_Argument_Other_Device_Version) 2762 SUIT_Wait_Events //= (suit-wait-event-time => uint); Timestamp 2763 SUIT_Wait_Events //= (suit-wait-event-time-of-day 2764 => uint); Time of Day (seconds since 00:00:00) 2765 SUIT_Wait_Events //= (suit-wait-event-day-of-week 2766 => uint); Days since Sunday 2768 SUIT_Wait_Event_Argument_Other_Device_Version = [ 2769 other-device: bstr, 2770 other-device-version: [+int] 2771 ] 2772 SUIT_Parameters //= (suit-parameter-vendor-identifier => RFC4122_UUID) 2773 SUIT_Parameters //= (suit-parameter-class-identifier => RFC4122_UUID) 2774 SUIT_Parameters //= (suit-parameter-image-digest 2775 => bstr .cbor SUIT_Digest) 2776 SUIT_Parameters //= (suit-parameter-image-size => uint) 2777 SUIT_Parameters //= (suit-parameter-use-before => uint) 2778 SUIT_Parameters //= (suit-parameter-component-offset => uint) 2780 SUIT_Parameters //= (suit-parameter-encryption-info 2781 => bstr .cbor SUIT_Encryption_Info) 2782 SUIT_Parameters //= (suit-parameter-compression-info 2783 => bstr .cbor SUIT_Compression_Info) 2784 SUIT_Parameters //= (suit-parameter-unpack-info 2785 => bstr .cbor SUIT_Unpack_Info) 2787 SUIT_Parameters //= (suit-parameter-uri => tstr) 2788 SUIT_Parameters //= (suit-parameter-source-component => uint) 2789 SUIT_Parameters //= (suit-parameter-run-args => bstr) 2791 SUIT_Parameters //= (suit-parameter-device-identifier => RFC4122_UUID) 2792 SUIT_Parameters //= (suit-parameter-minimum-battery => uint) 2793 SUIT_Parameters //= (suit-parameter-update-priority => uint) 2794 SUIT_Parameters //= (suit-parameter-version => 2795 SUIT_Parameter_Version_Match) 2796 SUIT_Parameters //= (suit-parameter-wait-info => 2797 bstr .cbor SUIT_Wait_Event) 2799 SUIT_Parameters //= (suit-parameter-custom => int/bool/tstr/bstr) 2801 SUIT_Parameters //= (suit-parameter-strict-order => bool) 2802 SUIT_Parameters //= (suit-parameter-soft-failure => bool) 2804 RFC4122_UUID = bstr .size 16 2806 SUIT_Parameter_Version_Match = [ 2807 suit-condition-version-comparison-type: 2808 SUIT_Condition_Version_Comparison_Types, 2809 suit-condition-version-comparison-value: 2810 SUIT_Condition_Version_Comparison_Value 2811 ] 2812 SUIT_Condition_Version_Comparison_Types /= 2813 suit-condition-version-comparison-greater 2814 SUIT_Condition_Version_Comparison_Types /= 2815 suit-condition-version-comparison-greater-equal 2816 SUIT_Condition_Version_Comparison_Types /= 2817 suit-condition-version-comparison-equal 2818 SUIT_Condition_Version_Comparison_Types /= 2819 suit-condition-version-comparison-lesser-equal 2821 SUIT_Condition_Version_Comparison_Types /= 2822 suit-condition-version-comparison-lesser 2824 suit-condition-version-comparison-greater = 1 2825 suit-condition-version-comparison-greater-equal = 2 2826 suit-condition-version-comparison-equal = 3 2827 suit-condition-version-comparison-lesser-equal = 4 2828 suit-condition-version-comparison-lesser = 5 2830 SUIT_Condition_Version_Comparison_Value = [+int] 2832 SUIT_Encryption_Info = COSE_Encrypt_Tagged/COSE_Encrypt0_Tagged 2833 SUIT_Compression_Info = { 2834 suit-compression-algorithm => SUIT_Compression_Algorithms, 2835 ? suit-compression-parameters => bstr 2836 } 2838 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_gzip 2839 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_bzip2 2840 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_deflate 2841 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_lz4 2842 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_lzma 2844 SUIT_Compression_Algorithm_gzip = 1 2845 SUIT_Compression_Algorithm_bzip2 = 2 2846 SUIT_Compression_Algorithm_deflate = 3 2847 SUIT_Compression_Algorithm_lz4 = 4 2848 SUIT_Compression_Algorithm_lzma = 7 2850 SUIT_Unpack_Info = { 2851 suit-unpack-algorithm => SUIT_Unpack_Algorithms, 2852 ? suit-unpack-parameters => bstr 2853 } 2855 SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Delta 2856 SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Hex 2857 SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Elf 2859 SUIT_Unpack_Algorithm_Delta = 1 2860 SUIT_Unpack_Algorithm_Hex = 2 2861 SUIT_Unpack_Algorithm_Elf = 3 2863 SUIT_Text_Map = {SUIT_Text_Keys => tstr} 2865 SUIT_Text_Keys /= suit-text-manifest-description 2866 SUIT_Text_Keys /= suit-text-update-description 2867 SUIT_Text_Keys /= suit-text-vendor-name 2868 SUIT_Text_Keys /= suit-text-model-name 2869 SUIT_Text_Keys /= suit-text-vendor-domain 2870 SUIT_Text_Keys /= suit-text-model-info 2871 SUIT_Text_Keys /= suit-text-component-description 2872 SUIT_Text_Keys /= suit-text-manifest-json-source 2873 SUIT_Text_Keys /= suit-text-manifest-yaml-source 2874 SUIT_Text_Keys /= suit-text-version-dependencies 2876 suit-delegation = 1 2877 suit-authentication-wrapper = 2 2878 suit-manifest = 3 2880 suit-manifest-encryption-info = 4 2881 suit-manifest-encrypted = 5 2883 suit-manifest-version = 1 2884 suit-manifest-sequence-number = 2 2885 suit-common = 3 2886 suit-reference-uri = 4 2887 suit-dependency-resolution = 7 2888 suit-payload-fetch = 8 2889 suit-install = 9 2890 suit-validate = 10 2891 suit-load = 11 2892 suit-run = 12 2893 suit-text = 13 2894 suit-coswid = 14 2896 suit-dependencies = 1 2897 suit-components = 2 2898 suit-dependency-components = 3 2899 suit-common-sequence = 4 2901 suit-dependency-digest = 1 2902 suit-dependency-prefix = 2 2904 suit-component-identifier = 1 2905 suit-component-dependency-index = 2 2907 suit-command-custom = nint 2909 suit-condition-vendor-identifier = 1 2910 suit-condition-class-identifier = 2 2911 suit-condition-image-match = 3 2912 suit-condition-use-before = 4 2913 suit-condition-component-offset = 5 2915 suit-condition-device-identifier = 24 2916 suit-condition-image-not-match = 25 2917 suit-condition-minimum-battery = 26 2918 suit-condition-update-authorized = 27 2919 suit-condition-version = 28 2921 suit-directive-set-component-index = 12 2922 suit-directive-set-dependency-index = 13 2923 suit-directive-abort = 14 2924 suit-directive-try-each = 15 2925 ;suit-directive-do-each = 16 ; TBD 2926 ;suit-directive-map-filter = 17 ; TBD 2927 suit-directive-process-dependency = 18 2928 suit-directive-set-parameters = 19 2929 suit-directive-override-parameters = 20 2930 suit-directive-fetch = 21 2931 suit-directive-copy = 22 2932 suit-directive-run = 23 2934 suit-directive-wait = 29 2935 suit-directive-run-sequence = 30 2936 suit-directive-swap = 32 2938 suit-wait-event-authorization = 1 2939 suit-wait-event-power = 2 2940 suit-wait-event-network = 3 2941 suit-wait-event-other-device-version = 4 2942 suit-wait-event-time = 5 2943 suit-wait-event-time-of-day = 6 2944 suit-wait-event-day-of-week = 7 2946 suit-parameter-vendor-identifier = 1 2947 suit-parameter-class-identifier = 2 2948 suit-parameter-image-digest = 3 2949 suit-parameter-use-before = 4 2950 suit-parameter-component-offset = 5 2952 suit-parameter-strict-order = 12 2953 suit-parameter-soft-failure = 13 2954 suit-parameter-image-size = 14 2956 suit-parameter-encryption-info = 18 2957 suit-parameter-compression-info = 19 2958 suit-parameter-unpack-info = 20 2959 suit-parameter-uri = 21 2960 suit-parameter-source-component = 22 2961 suit-parameter-run-args = 23 2963 suit-parameter-device-identifier = 24 2964 suit-parameter-minimum-battery = 26 2965 suit-parameter-update-priority = 27 2966 suit-parameter-version = 28 2967 suit-parameter-wait-info = 29 2969 suit-parameter-custom = nint 2971 suit-compression-algorithm = 1 2972 suit-compression-parameters = 2 2974 suit-unpack-algorithm = 1 2975 suit-unpack-parameters = 2 2977 suit-text-manifest-description = 1 2978 suit-text-update-description = 2 2979 suit-text-vendor-name = 3 2980 suit-text-model-name = 4 2981 suit-text-vendor-domain = 5 2982 suit-text-model-info = 6 2983 suit-text-component-description = 7 2984 suit-text-manifest-json-source = 8 2985 suit-text-manifest-yaml-source = 9 2986 suit-text-version-dependencies = 10 2988 12. Examples 2990 The following examples demonstrate a small subset of the 2991 functionality of the manifest. However, despite this, even a simple 2992 manifest processor can execute most of these manifests. 2994 The examples are signed using the following ECDSA secp256r1 key: 2996 -----BEGIN PRIVATE KEY----- 2997 MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgApZYjZCUGLM50VBC 2998 CjYStX+09jGmnyJPrpDLTz/hiXOhRANCAASEloEarguqq9JhVxie7NomvqqL8Rtv 2999 P+bitWWchdvArTsfKktsCYExwKNtrNHXi9OB3N+wnAUtszmR23M4tKiW 3000 -----END PRIVATE KEY----- 3002 The corresponding public key can be used to verify these examples: 3004 -----BEGIN PUBLIC KEY----- 3005 MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEhJaBGq4LqqvSYVcYnuzaJr6qi/Eb 3006 bz/m4rVlnIXbwK07HypLbAmBMcCjbazR14vTgdzfsJwFLbM5kdtzOLSolg== 3007 -----END PUBLIC KEY----- 3009 Each example uses SHA256 as the digest function. 3011 12.1. Example 0: Secure Boot 3013 Secure boot and compatibility check. 3015 { 3016 / authentication-wrapper / 2:h'81d28443a10126a058248202582064d8094 3017 da3ef71c5971b7b84e7f4be1f56452c32fdde7bc1c70889112f1d5d9958407d637397e 3018 12abdd41bc026a8e8a22f0f902a5b972e7786d570a37ac43c370b64a6946b0311f059c 3019 a01d40f74d88d6fd7193baa36f5cf20aa57c46a0411a6b704' / [ 3020 18([ 3021 / protected / h'a10126' / { 3022 / alg / 1:-7 / ES256 /, 3023 } /, 3024 / unprotected / { 3025 }, 3026 / payload / h'8202582064d8094da3ef71c5971b7b84e7f4be1f 3027 56452c32fdde7bc1c70889112f1d5d99' / [ 3028 / algorithm-id / 2 / sha256 /, 3029 / digest-bytes / 3030 h'64d8094da3ef71c5971b7b84e7f4be1f56452c32fdde7bc1c70889112f1d5d99' 3031 ] /, 3032 / signature / h'7d637397e12abdd41bc026a8e8a22f0f902a5b 3033 972e7786d570a37ac43c370b64a6946b0311f059ca01d40f74d88d6fd7193baa36f5cf 3034 20aa57c46a0411a6b704' 3035 ]) 3036 ] /, 3037 / manifest / 3:h'a50101020103585ea20244818141000458548614a40150fa6 3038 b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab4503820 3039 2582000112233445566778899aabbccddeeff0123456789abcdeffedcba98765432100 3040 e1987d001f602f60a438203f60c438217f6' / { 3041 / manifest-version / 1:1, 3042 / manifest-sequence-number / 2:1, 3043 / common / 3:h'a20244818141000458548614a40150fa6b4a53d5ad5fdfb 3044 e9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab450382025820001122334 3045 45566778899aabbccddeeff0123456789abcdeffedcba98765432100e1987d001f602f 3046 6' / { 3047 / components / 2:h'81814100' / [ 3048 [h'00'] 3049 ] /, 3050 / common-sequence / 4:h'8614a40150fa6b4a53d5ad5fdfbe9de663 3051 e4d41ffe02501492af1425695e48bf429b2d51f2ab4503820258200011223344556677 3052 8899aabbccddeeff0123456789abcdeffedcba98765432100e1987d001f602f6' / [ 3053 / directive-override-parameters / 20,{ 3054 / vendor-id / 3055 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 3056 be9d-e663e4d41ffe /, 3057 / class-id / 2:h'1492af1425695e48bf429b2d51f2ab45' 3058 / 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 3059 / image-digest / 3:[ 3060 / algorithm-id / 2 / sha256 /, 3061 / digest-bytes / 3062 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 3063 ], 3064 / image-size / 14:34768, 3065 } , 3066 / condition-vendor-identifier / 1,F6 / nil / , 3067 / condition-class-identifier / 2,F6 / nil / 3068 ] /, 3069 } /, 3070 / validate / 10:h'8203f6' / [ 3071 / condition-image-match / 3,F6 / nil / 3072 ] /, 3073 / run / 12:h'8217f6' / [ 3074 / directive-run / 23,F6 / nil / 3075 ] /, 3076 } /, 3077 } 3079 Total size of manifest without COSE authentication object: 116 3081 Manifest: 3083 a1035870a50101020103585ea20244818141000458548614a40150fa6b4a 3084 53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab 3085 45038202582000112233445566778899aabbccddeeff0123456789abcdef 3086 fedcba98765432100e1987d001f602f60a438203f60c438217f6 3088 Total size of manifest with COSE authentication object: 231 3090 Manifest with COSE authentication object: 3092 a202587081d28443a10126a058248202582064d8094da3ef71c5971b7b84 3093 e7f4be1f56452c32fdde7bc1c70889112f1d5d9958407d637397e12abdd4 3094 1bc026a8e8a22f0f902a5b972e7786d570a37ac43c370b64a6946b0311f0 3095 59ca01d40f74d88d6fd7193baa36f5cf20aa57c46a0411a6b704035870a5 3096 0101020103585ea20244818141000458548614a40150fa6b4a53d5ad5fdf 3097 be9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab4503820258 3098 2000112233445566778899aabbccddeeff0123456789abcdeffedcba9876 3099 5432100e1987d001f602f60a438203f60c438217f6 3101 12.2. Example 1: Simultaneous Download and Installation of Payload 3103 Simultaneous download and installation of payload. 3105 { 3106 / authentication-wrapper / 2:h'81d28443a10126a0582482025820666b83f 3108 f51628190387170489535aa9441656d8a24401de6458595c42cb0165d58405cb310acb 3109 34f7ebb42acfffce430dbda94faa412900ce8e76650445e2c37e4cc132d8bb5f30ecf5 3110 f8130270bbf8d159f6d36e1cdf97b64229910fdb447538af1' / [ 3111 18([ 3112 / protected / h'a10126' / { 3113 / alg / 1:-7 / ES256 /, 3114 } /, 3115 / unprotected / { 3116 }, 3117 / payload / h'82025820666b83ff51628190387170489535aa94 3118 41656d8a24401de6458595c42cb0165d' / [ 3119 / algorithm-id / 2 / sha256 /, 3120 / digest-bytes / 3121 h'666b83ff51628190387170489535aa9441656d8a24401de6458595c42cb0165d' 3122 ] /, 3123 / signature / h'5cb310acb34f7ebb42acfffce430dbda94faa4 3124 12900ce8e76650445e2c37e4cc132d8bb5f30ecf5f8130270bbf8d159f6d36e1cdf97b 3125 64229910fdb447538af1' 3126 ]) 3127 ] /, 3128 / manifest / 3:h'a50101020203585ea20244818141000458548614a40150fa6 3129 b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab4503820 3130 2582000112233445566778899aabbccddeeff0123456789abcdeffedcba98765432100 3131 e1987d001f602f60958258613a115781b687474703a2f2f6578616d706c652e636f6d2 3132 f66696c652e62696e15f603f60a438203f6' / { 3133 / manifest-version / 1:1, 3134 / manifest-sequence-number / 2:2, 3135 / common / 3:h'a20244818141000458548614a40150fa6b4a53d5ad5fdfb 3136 e9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab450382025820001122334 3137 45566778899aabbccddeeff0123456789abcdeffedcba98765432100e1987d001f602f 3138 6' / { 3139 / components / 2:h'81814100' / [ 3140 [h'00'] 3141 ] /, 3142 / common-sequence / 4:h'8614a40150fa6b4a53d5ad5fdfbe9de663 3143 e4d41ffe02501492af1425695e48bf429b2d51f2ab4503820258200011223344556677 3144 8899aabbccddeeff0123456789abcdeffedcba98765432100e1987d001f602f6' / [ 3145 / directive-override-parameters / 20,{ 3146 / vendor-id / 3147 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 3148 be9d-e663e4d41ffe /, 3149 / class-id / 2:h'1492af1425695e48bf429b2d51f2ab45' 3150 / 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 3151 / image-digest / 3:[ 3152 / algorithm-id / 2 / sha256 /, 3153 / digest-bytes / 3154 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 3155 ], 3156 / image-size / 14:34768, 3157 } , 3158 / condition-vendor-identifier / 1,F6 / nil / , 3159 / condition-class-identifier / 2,F6 / nil / 3160 ] /, 3161 } /, 3162 / install / 9:h'8613a115781b687474703a2f2f6578616d706c652e636f 3163 6d2f66696c652e62696e15f603f6' / [ 3164 / directive-set-parameters / 19,{ 3165 / uri / 21:'http://example.com/file.bin', 3166 } , 3167 / directive-fetch / 21,F6 / nil / , 3168 / condition-image-match / 3,F6 / nil / 3169 ] /, 3170 / validate / 10:h'8203f6' / [ 3171 / condition-image-match / 3,F6 / nil / 3172 ] /, 3173 } /, 3174 } 3176 Total size of manifest without COSE authentication object: 151 3178 Manifest: 3180 a1035893a50101020203585ea20244818141000458548614a40150fa6b4a 3181 53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab 3182 45038202582000112233445566778899aabbccddeeff0123456789abcdef 3183 fedcba98765432100e1987d001f602f60958258613a115781b687474703a 3184 2f2f6578616d706c652e636f6d2f66696c652e62696e15f603f60a438203 3185 f6 3187 Total size of manifest with COSE authentication object: 266 3189 Manifest with COSE authentication object: 3191 a202587081d28443a10126a0582482025820666b83ff5162819038717048 3192 9535aa9441656d8a24401de6458595c42cb0165d58405cb310acb34f7ebb 3193 42acfffce430dbda94faa412900ce8e76650445e2c37e4cc132d8bb5f30e 3194 cf5f8130270bbf8d159f6d36e1cdf97b64229910fdb447538af1035893a5 3195 0101020203585ea20244818141000458548614a40150fa6b4a53d5ad5fdf 3196 be9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab4503820258 3197 2000112233445566778899aabbccddeeff0123456789abcdeffedcba9876 3198 5432100e1987d001f602f60958258613a115781b687474703a2f2f657861 3199 6d706c652e636f6d2f66696c652e62696e15f603f60a438203f6 3201 12.3. Example 2: Simultaneous Download, Installation, and Secure Boot 3203 Compatibility test, simultaneous download and installation, and 3204 secure boot. 3206 { 3207 / authentication-wrapper / 2:h'81d28443a10126a058248202582038df852 3208 c98928fae9694fce5b6b51addd631bfde473eceb20c8b929ae6ec2d6c584050bba3dd9 3209 b0ad6da91265cff1ec69c3a9e2e42ffd97e780e37c78ac7889140620439874108ec527 3210 1f3325988f2774f17339fcd61a5c08a3d15fb7fcdeef9294e' / [ 3211 18([ 3212 / protected / h'a10126' / { 3213 / alg / 1:-7 / ES256 /, 3214 } /, 3215 / unprotected / { 3216 }, 3217 / payload / h'8202582038df852c98928fae9694fce5b6b51add 3218 d631bfde473eceb20c8b929ae6ec2d6c' / [ 3219 / algorithm-id / 2 / sha256 /, 3220 / digest-bytes / 3221 h'38df852c98928fae9694fce5b6b51addd631bfde473eceb20c8b929ae6ec2d6c' 3222 ] /, 3223 / signature / h'50bba3dd9b0ad6da91265cff1ec69c3a9e2e42 3224 ffd97e780e37c78ac7889140620439874108ec5271f3325988f2774f17339fcd61a5c0 3225 8a3d15fb7fcdeef9294e' 3226 ]) 3227 ] /, 3228 / manifest / 3:h'a60101020303585ea20244818141000458548614a40150fa6 3229 b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab4503820 3230 2582000112233445566778899aabbccddeeff0123456789abcdeffedcba98765432100 3231 e1987d001f602f60958258613a115781b687474703a2f2f6578616d706c652e636f6d2 3232 f66696c652e62696e15f603f60a438203f60c438217f6' / { 3233 / manifest-version / 1:1, 3234 / manifest-sequence-number / 2:3, 3235 / common / 3:h'a20244818141000458548614a40150fa6b4a53d5ad5fdfb 3236 e9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab450382025820001122334 3237 45566778899aabbccddeeff0123456789abcdeffedcba98765432100e1987d001f602f 3238 6' / { 3239 / components / 2:h'81814100' / [ 3240 [h'00'] 3241 ] /, 3242 / common-sequence / 4:h'8614a40150fa6b4a53d5ad5fdfbe9de663 3243 e4d41ffe02501492af1425695e48bf429b2d51f2ab4503820258200011223344556677 3244 8899aabbccddeeff0123456789abcdeffedcba98765432100e1987d001f602f6' / [ 3245 / directive-override-parameters / 20,{ 3246 / vendor-id / 3247 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 3248 be9d-e663e4d41ffe /, 3249 / class-id / 2:h'1492af1425695e48bf429b2d51f2ab45' 3250 / 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 3251 / image-digest / 3:[ 3252 / algorithm-id / 2 / sha256 /, 3253 / digest-bytes / 3254 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 3255 ], 3256 / image-size / 14:34768, 3257 } , 3258 / condition-vendor-identifier / 1,F6 / nil / , 3259 / condition-class-identifier / 2,F6 / nil / 3260 ] /, 3261 } /, 3262 / install / 9:h'8613a115781b687474703a2f2f6578616d706c652e636f 3263 6d2f66696c652e62696e15f603f6' / [ 3264 / directive-set-parameters / 19,{ 3265 / uri / 21:'http://example.com/file.bin', 3266 } , 3267 / directive-fetch / 21,F6 / nil / , 3268 / condition-image-match / 3,F6 / nil / 3269 ] /, 3270 / validate / 10:h'8203f6' / [ 3271 / condition-image-match / 3,F6 / nil / 3272 ] /, 3273 / run / 12:h'8217f6' / [ 3274 / directive-run / 23,F6 / nil / 3275 ] /, 3276 } /, 3277 } 3279 Total size of manifest without COSE authentication object: 156 3281 Manifest: 3283 a1035898a60101020303585ea20244818141000458548614a40150fa6b4a 3284 53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab 3285 45038202582000112233445566778899aabbccddeeff0123456789abcdef 3286 fedcba98765432100e1987d001f602f60958258613a115781b687474703a 3287 2f2f6578616d706c652e636f6d2f66696c652e62696e15f603f60a438203 3288 f60c438217f6 3290 Total size of manifest with COSE authentication object: 271 3292 Manifest with COSE authentication object: 3294 a202587081d28443a10126a058248202582038df852c98928fae9694fce5 3295 b6b51addd631bfde473eceb20c8b929ae6ec2d6c584050bba3dd9b0ad6da 3296 91265cff1ec69c3a9e2e42ffd97e780e37c78ac7889140620439874108ec 3297 5271f3325988f2774f17339fcd61a5c08a3d15fb7fcdeef9294e035898a6 3298 0101020303585ea20244818141000458548614a40150fa6b4a53d5ad5fdf 3299 be9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab4503820258 3300 2000112233445566778899aabbccddeeff0123456789abcdeffedcba9876 3301 5432100e1987d001f602f60958258613a115781b687474703a2f2f657861 3302 6d706c652e636f6d2f66696c652e62696e15f603f60a438203f60c438217 3303 f6 3305 12.4. Example 3: Load from External Storage 3307 Compatibility test, simultaneous download and installation, load from 3308 external storage, and secure boot. 3310 { 3311 / authentication-wrapper / 2:h'81d28443a10126a05824820258208ae1d4d 3312 1846e82975dd5d7555ef0c3836e7e653a8bb1214466457781c0d2f2aa58401ef2d0ca6 3313 aabf259feb880a1a4deb4e345cda314b2facf9983766da3744af825b3f98c74afdfa85 3314 aed406b10315e0cc6c44ee19321681c69f911bc90bf8d22c0' / [ 3315 18([ 3316 / protected / h'a10126' / { 3317 / alg / 1:-7 / ES256 /, 3318 } /, 3319 / unprotected / { 3320 }, 3321 / payload / h'820258208ae1d4d1846e82975dd5d7555ef0c383 3322 6e7e653a8bb1214466457781c0d2f2aa' / [ 3323 / algorithm-id / 2 / sha256 /, 3324 / digest-bytes / 3325 h'8ae1d4d1846e82975dd5d7555ef0c3836e7e653a8bb1214466457781c0d2f2aa' 3326 ] /, 3327 / signature / h'1ef2d0ca6aabf259feb880a1a4deb4e345cda3 3328 14b2facf9983766da3744af825b3f98c74afdfa85aed406b10315e0cc6c44ee1932168 3329 1c69f911bc90bf8d22c0' 3330 ]) 3331 ] /, 3332 / manifest / 3:h'a701010204035863a2024782814100814101045856880c001 3333 4a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f 3334 2ab45038202582000112233445566778899aabbccddeeff0123456789abcdeffedcba9 3335 8765432100e1987d001f602f6095827880c0013a115781b687474703a2f2f6578616d7 3336 06c652e636f6d2f66696c652e62696e15f603f60a45840c0003f60b4b880c0113a1160 3337 016f603f60c45840c0117f6' / { 3338 / manifest-version / 1:1, 3339 / manifest-sequence-number / 2:4, 3340 / common / 3:h'a2024782814100814101045856880c0014a40150fa6b4a5 3341 3d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab45038202582 3342 000112233445566778899aabbccddeeff0123456789abcdeffedcba98765432100e198 3343 7d001f602f6' / { 3344 / components / 2:h'82814100814101' / [ 3345 [h'00'] , 3346 [h'01'] 3347 ] /, 3348 / common-sequence / 4:h'880c0014a40150fa6b4a53d5ad5fdfbe9d 3349 e663e4d41ffe02501492af1425695e48bf429b2d51f2ab450382025820001122334455 3350 66778899aabbccddeeff0123456789abcdeffedcba98765432100e1987d001f602f6' 3351 / [ 3352 / directive-set-component-index / 12,0 , 3353 / directive-override-parameters / 20,{ 3354 / vendor-id / 3355 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 3356 be9d-e663e4d41ffe /, 3357 / class-id / 2:h'1492af1425695e48bf429b2d51f2ab45' 3358 / 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 3359 / image-digest / 3:[ 3360 / algorithm-id / 2 / sha256 /, 3361 / digest-bytes / 3362 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 3363 ], 3364 / image-size / 14:34768, 3365 } , 3366 / condition-vendor-identifier / 1,F6 / nil / , 3367 / condition-class-identifier / 2,F6 / nil / 3368 ] /, 3369 } /, 3370 / install / 9:h'880c0013a115781b687474703a2f2f6578616d706c652e 3371 636f6d2f66696c652e62696e15f603f6' / [ 3372 / directive-set-component-index / 12,0 , 3373 / directive-set-parameters / 19,{ 3374 / uri / 21:'http://example.com/file.bin', 3375 } , 3376 / directive-fetch / 21,F6 / nil / , 3377 / condition-image-match / 3,F6 / nil / 3378 ] /, 3379 / validate / 10:h'840c0003f6' / [ 3380 / directive-set-component-index / 12,0 , 3381 / condition-image-match / 3,F6 / nil / 3382 ] /, 3383 / load / 11:h'880c0113a1160016f603f6' / [ 3384 / directive-set-component-index / 12,1 , 3385 / directive-set-parameters / 19,{ 3386 / source-component / 22:0 / [h'00'] /, 3387 } , 3388 / directive-copy / 22,F6 / nil / , 3389 / condition-image-match / 3,F6 / nil / 3391 ] /, 3392 / run / 12:h'840c0117f6' / [ 3393 / directive-set-component-index / 12,1 , 3394 / directive-run / 23,F6 / nil / 3395 ] /, 3396 } /, 3397 } 3399 Total size of manifest without COSE authentication object: 180 3401 Manifest: 3403 a10358b0a701010204035863a2024782814100814101045856880c0014a4 3404 0150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf42 3405 9b2d51f2ab45038202582000112233445566778899aabbccddeeff012345 3406 6789abcdeffedcba98765432100e1987d001f602f6095827880c0013a115 3407 781b687474703a2f2f6578616d706c652e636f6d2f66696c652e62696e15 3408 f603f60a45840c0003f60b4b880c0113a1160016f603f60c45840c0117f6 3410 Total size of manifest with COSE authentication object: 295 3412 Manifest with COSE authentication object: 3414 a202587081d28443a10126a05824820258208ae1d4d1846e82975dd5d755 3415 5ef0c3836e7e653a8bb1214466457781c0d2f2aa58401ef2d0ca6aabf259 3416 feb880a1a4deb4e345cda314b2facf9983766da3744af825b3f98c74afdf 3417 a85aed406b10315e0cc6c44ee19321681c69f911bc90bf8d22c00358b0a7 3418 01010204035863a2024782814100814101045856880c0014a40150fa6b4a 3419 53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab 3420 45038202582000112233445566778899aabbccddeeff0123456789abcdef 3421 fedcba98765432100e1987d001f602f6095827880c0013a115781b687474 3422 703a2f2f6578616d706c652e636f6d2f66696c652e62696e15f603f60a45 3423 840c0003f60b4b880c0113a1160016f603f60c45840c0117f6 3425 12.5. Example 4: Load and Decompress from External Storage 3427 Compatibility test, simultaneous download and installation, load and 3428 decompress from external storage, and secure boot. 3430 { 3431 / authentication-wrapper / 2:h'81d28443a10126a0582482025820310798d 3432 3d8276a740505d1f017972e281d6d26c9967a658879ae6d07e6a238a958404d48f0059 3433 918c261bc1636b467b2b455801c4d211758a42e82a8f8fc245f21857d7c0e78f1b6d6a 3434 8ab1f0c9e147043066c0af53c1563070d4934faeec21bac55' / [ 3435 18([ 3436 / protected / h'a10126' / { 3437 / alg / 1:-7 / ES256 /, 3438 } /, 3439 / unprotected / { 3440 }, 3441 / payload / h'82025820310798d3d8276a740505d1f017972e28 3442 1d6d26c9967a658879ae6d07e6a238a9' / [ 3443 / algorithm-id / 2 / sha256 /, 3444 / digest-bytes / 3445 h'310798d3d8276a740505d1f017972e281d6d26c9967a658879ae6d07e6a238a9' 3446 ] /, 3447 / signature / h'4d48f0059918c261bc1636b467b2b455801c4d 3448 211758a42e82a8f8fc245f21857d7c0e78f1b6d6a8ab1f0c9e147043066c0af53c1563 3449 070d4934faeec21bac55' 3450 ]) 3451 ] /, 3452 / manifest / 3:h'a701010205035863a2024782814100814101045856880c001 3453 4a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f 3454 2ab45038202582000112233445566778899aabbccddeeff0123456789abcdeffedcba9 3455 8765432100e1987d001f602f6095827880c0013a115781b687474703a2f2f6578616d7 3456 06c652e636f6d2f66696c652e62696e15f603f60a45840c0003f60b4d880c0113a2130 3457 1160016f603f60c45840c0117f6' / { 3458 / manifest-version / 1:1, 3459 / manifest-sequence-number / 2:5, 3460 / common / 3:h'a2024782814100814101045856880c0014a40150fa6b4a5 3461 3d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab45038202582 3462 000112233445566778899aabbccddeeff0123456789abcdeffedcba98765432100e198 3463 7d001f602f6' / { 3464 / components / 2:h'82814100814101' / [ 3465 [h'00'] , 3466 [h'01'] 3467 ] /, 3468 / common-sequence / 4:h'880c0014a40150fa6b4a53d5ad5fdfbe9d 3469 e663e4d41ffe02501492af1425695e48bf429b2d51f2ab450382025820001122334455 3470 66778899aabbccddeeff0123456789abcdeffedcba98765432100e1987d001f602f6' 3471 / [ 3472 / directive-set-component-index / 12,0 , 3473 / directive-override-parameters / 20,{ 3474 / vendor-id / 3475 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 3476 be9d-e663e4d41ffe /, 3477 / class-id / 2:h'1492af1425695e48bf429b2d51f2ab45' 3478 / 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 3479 / image-digest / 3:[ 3480 / algorithm-id / 2 / sha256 /, 3481 / digest-bytes / 3482 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 3483 ], 3484 / image-size / 14:34768, 3485 } , 3486 / condition-vendor-identifier / 1,F6 / nil / , 3487 / condition-class-identifier / 2,F6 / nil / 3488 ] /, 3489 } /, 3490 / install / 9:h'880c0013a115781b687474703a2f2f6578616d706c652e 3491 636f6d2f66696c652e62696e15f603f6' / [ 3492 / directive-set-component-index / 12,0 , 3493 / directive-set-parameters / 19,{ 3494 / uri / 21:'http://example.com/file.bin', 3495 } , 3496 / directive-fetch / 21,F6 / nil / , 3497 / condition-image-match / 3,F6 / nil / 3498 ] /, 3499 / validate / 10:h'840c0003f6' / [ 3500 / directive-set-component-index / 12,0 , 3501 / condition-image-match / 3,F6 / nil / 3502 ] /, 3503 / load / 11:h'880c0113a21301160016f603f6' / [ 3504 / directive-set-component-index / 12,1 , 3505 / directive-set-parameters / 19,{ 3506 / source-component / 22:0 / [h'00'] /, 3507 / compression-info / 19:1 / gzip /, 3508 } , 3509 / directive-copy / 22,F6 / nil / , 3510 / condition-image-match / 3,F6 / nil / 3511 ] /, 3512 / run / 12:h'840c0117f6' / [ 3513 / directive-set-component-index / 12,1 , 3514 / directive-run / 23,F6 / nil / 3515 ] /, 3516 } /, 3517 } 3519 Total size of manifest without COSE authentication object: 182 3521 Manifest: 3523 a10358b2a701010205035863a2024782814100814101045856880c0014a4 3524 0150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf42 3525 9b2d51f2ab45038202582000112233445566778899aabbccddeeff012345 3526 6789abcdeffedcba98765432100e1987d001f602f6095827880c0013a115 3527 781b687474703a2f2f6578616d706c652e636f6d2f66696c652e62696e15 3528 f603f60a45840c0003f60b4d880c0113a21301160016f603f60c45840c01 3529 17f6 3531 Total size of manifest with COSE authentication object: 297 3533 Manifest with COSE authentication object: 3535 a202587081d28443a10126a0582482025820310798d3d8276a740505d1f0 3536 17972e281d6d26c9967a658879ae6d07e6a238a958404d48f0059918c261 3537 bc1636b467b2b455801c4d211758a42e82a8f8fc245f21857d7c0e78f1b6 3538 d6a8ab1f0c9e147043066c0af53c1563070d4934faeec21bac550358b2a7 3539 01010205035863a2024782814100814101045856880c0014a40150fa6b4a 3540 53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab 3541 45038202582000112233445566778899aabbccddeeff0123456789abcdef 3542 fedcba98765432100e1987d001f602f6095827880c0013a115781b687474 3543 703a2f2f6578616d706c652e636f6d2f66696c652e62696e15f603f60a45 3544 840c0003f60b4d880c0113a21301160016f603f60c45840c0117f6 3546 12.6. Example 5: Compatibility Test, Download, Installation, and Secure 3547 Boot 3549 Compatibility test, download, installation, and secure boot. 3551 { 3552 / authentication-wrapper / 2:h'81d28443a10126a05824820258209a45659 3553 58c6e09c92fc69feeb09081c875f113082245ba2025801fa46dc2280e58404604e6413 3554 30d610fd0a0545b9b816f09c0767edf66fc57f40393cd4423e0807b36226e843e0f57b 3555 f860a3cf542655048648dea81e62e39f19e7ac96652d3de90' / [ 3556 18([ 3557 / protected / h'a10126' / { 3558 / alg / 1:-7 / ES256 /, 3559 } /, 3560 / unprotected / { 3561 }, 3562 / payload / h'820258209a4565958c6e09c92fc69feeb09081c8 3563 75f113082245ba2025801fa46dc2280e' / [ 3564 / algorithm-id / 2 / sha256 /, 3565 / digest-bytes / 3566 h'9a4565958c6e09c92fc69feeb09081c875f113082245ba2025801fa46dc2280e' 3567 ] /, 3568 / signature / h'4604e641330d610fd0a0545b9b816f09c0767e 3569 df66fc57f40393cd4423e0807b36226e843e0f57bf860a3cf542655048648dea81e62e 3570 39f19e7ac96652d3de90' 3571 ]) 3572 ] /, 3573 / manifest / 3:h'a701010205035863a2024782814101814100045856880c011 3574 4a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f 3575 2ab45038202582000112233445566778899aabbccddeeff0123456789abcdeffedcba9 3576 8765432100e1987d001f602f6085823840c0013a115781b687474703a2f2f6578616d7 3577 06c652e636f6d2f66696c652e62696e094b880c0113a1160016f603f60a45840c0103f 3578 60c45840c0117f6' / { 3579 / manifest-version / 1:1, 3580 / manifest-sequence-number / 2:5, 3581 / common / 3:h'a2024782814101814100045856880c0114a40150fa6b4a5 3582 3d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab45038202582 3583 000112233445566778899aabbccddeeff0123456789abcdeffedcba98765432100e198 3584 7d001f602f6' / { 3585 / components / 2:h'82814101814100' / [ 3586 [h'01'] , 3587 [h'00'] 3588 ] /, 3589 / common-sequence / 4:h'880c0114a40150fa6b4a53d5ad5fdfbe9d 3590 e663e4d41ffe02501492af1425695e48bf429b2d51f2ab450382025820001122334455 3591 66778899aabbccddeeff0123456789abcdeffedcba98765432100e1987d001f602f6' 3592 / [ 3593 / directive-set-component-index / 12,1 , 3594 / directive-override-parameters / 20,{ 3595 / vendor-id / 3596 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 3597 be9d-e663e4d41ffe /, 3598 / class-id / 2:h'1492af1425695e48bf429b2d51f2ab45' 3599 / 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 3600 / image-digest / 3:[ 3601 / algorithm-id / 2 / sha256 /, 3602 / digest-bytes / 3603 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 3604 ], 3605 / image-size / 14:34768, 3606 } , 3607 / condition-vendor-identifier / 1,F6 / nil / , 3608 / condition-class-identifier / 2,F6 / nil / 3609 ] /, 3610 } /, 3611 / payload-fetch / 8:h'840c0013a115781b687474703a2f2f6578616d70 3612 6c652e636f6d2f66696c652e62696e' / [ 3613 / directive-set-component-index / 12,0 , 3614 / directive-set-parameters / 19,{ 3615 / uri / 21:'http://example.com/file.bin', 3616 } 3617 ] /, 3618 / install / 9:h'880c0113a1160016f603f6' / [ 3619 / directive-set-component-index / 12,1 , 3620 / directive-set-parameters / 19,{ 3621 / source-component / 22:0 / [h'01'] /, 3622 } , 3623 / directive-copy / 22,F6 / nil / , 3624 / condition-image-match / 3,F6 / nil / 3625 ] /, 3626 / validate / 10:h'840c0103f6' / [ 3627 / directive-set-component-index / 12,1 , 3628 / condition-image-match / 3,F6 / nil / 3629 ] /, 3630 / run / 12:h'840c0117f6' / [ 3631 / directive-set-component-index / 12,1 , 3632 / directive-run / 23,F6 / nil / 3633 ] /, 3634 } /, 3635 } 3637 Total size of manifest without COSE authentication object: 176 3639 Manifest: 3641 a10358aca701010205035863a2024782814101814100045856880c0114a4 3642 0150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf42 3643 9b2d51f2ab45038202582000112233445566778899aabbccddeeff012345 3644 6789abcdeffedcba98765432100e1987d001f602f6085823840c0013a115 3645 781b687474703a2f2f6578616d706c652e636f6d2f66696c652e62696e09 3646 4b880c0113a1160016f603f60a45840c0103f60c45840c0117f6 3648 Total size of manifest with COSE authentication object: 291 3650 Manifest with COSE authentication object: 3652 a202587081d28443a10126a05824820258209a4565958c6e09c92fc69fee 3653 b09081c875f113082245ba2025801fa46dc2280e58404604e641330d610f 3654 d0a0545b9b816f09c0767edf66fc57f40393cd4423e0807b36226e843e0f 3655 57bf860a3cf542655048648dea81e62e39f19e7ac96652d3de900358aca7 3656 01010205035863a2024782814101814100045856880c0114a40150fa6b4a 3657 53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab 3658 45038202582000112233445566778899aabbccddeeff0123456789abcdef 3659 fedcba98765432100e1987d001f602f6085823840c0013a115781b687474 3660 703a2f2f6578616d706c652e636f6d2f66696c652e62696e094b880c0113 3661 a1160016f603f60a45840c0103f60c45840c0117f6 3663 12.7. Example 6: Two Images 3665 Compatibility test, 2 images, simultaneous download and installation, 3666 and secure boot. 3668 { 3669 / authentication-wrapper / 2:h'81d28443a10126a05824820258201d15a17 3670 13d3a4510ca392454adff987abb5425348e449618122ffa817012cc315840197a4a3a4 3671 188fe1dd8baa468ae9a35ac8e5ef462017530116eadd90892c96c6ab00825fcb45edb7 3672 57547733c14d3b637ea8a085ce7bfc782a0b2cd80d31b1294' / [ 3673 18([ 3674 / protected / h'a10126' / { 3675 / alg / 1:-7 / ES256 /, 3676 } /, 3677 / unprotected / { 3678 }, 3679 / payload / h'820258201d15a1713d3a4510ca392454adff987a 3680 bb5425348e449618122ffa817012cc31' / [ 3681 / algorithm-id / 2 / sha256 /, 3682 / digest-bytes / 3683 h'1d15a1713d3a4510ca392454adff987abb5425348e449618122ffa817012cc31' 3684 ] /, 3685 / signature / h'197a4a3a4188fe1dd8baa468ae9a35ac8e5ef4 3686 62017530116eadd90892c96c6ab00825fcb45edb757547733c14d3b637ea8a085ce7bf 3687 c782a0b2cd80d31b1294' 3688 ]) 3689 ] /, 3690 / manifest / 3:h'a501010203035899a202448181410004588f8814a20150fa6 3691 b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab450f825 3692 82e8405f614a2038202582000112233445566778899aabbccddeeff0123456789abcde 3693 ffedcba98765432100e1987d058308405f614a203820258200123456789abcdeffedcb 3694 a987654321000112233445566778899aabbccddeeff0e1a00012c2201f602f60958538 3695 60f8258248405f613a115781c687474703a2f2f6578616d706c652e636f6d2f66696c6 3696 5312e62696e58248405f613a115781c687474703a2f2f6578616d706c652e636f6d2f6 3697 6696c65322e62696e15f603f60a438203f6' / { 3698 / manifest-version / 1:1, 3699 / manifest-sequence-number / 2:3, 3700 / common / 3:h'a202448181410004588f8814a20150fa6b4a53d5ad5fdfb 3701 e9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab450f82582e8405f614a20 3702 38202582000112233445566778899aabbccddeeff0123456789abcdeffedcba9876543 3703 2100e1987d058308405f614a203820258200123456789abcdeffedcba9876543210001 3704 12233445566778899aabbccddeeff0e1a00012c2201f602f6' / { 3705 / components / 2:h'81814100' / [ 3706 [h'00'] 3707 ] /, 3708 / common-sequence / 4:h'8814a20150fa6b4a53d5ad5fdfbe9de663 3709 e4d41ffe02501492af1425695e48bf429b2d51f2ab450f82582e8405f614a203820258 3710 2000112233445566778899aabbccddeeff0123456789abcdeffedcba98765432100e19 3711 87d058308405f614a203820258200123456789abcdeffedcba98765432100011223344 3712 5566778899aabbccddeeff0e1a00012c2201f602f6' / [ 3713 / directive-override-parameters / 20,{ 3714 / vendor-id / 3715 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 3716 be9d-e663e4d41ffe /, 3717 / class-id / 2:h'1492af1425695e48bf429b2d51f2ab45' 3718 / 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, 3719 } , 3720 / directive-try-each / 15,[ 3721 h'8405f614a2038202582000112233445566778899aabbccdd 3722 eeff0123456789abcdeffedcba98765432100e1987d0' / [ 3723 / condition-component-offset / 5,F6 / nil / , 3724 / directive-override-parameters / 20,{ 3725 / image-digest / 3:[ 3726 / algorithm-id / 2 / sha256 /, 3727 / digest-bytes / 3728 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 3729 ], 3730 / image-size / 14:34768, 3731 } 3732 ] / , 3733 h'8405f614a203820258200123456789abcdeffedcba987654 3734 321000112233445566778899aabbccddeeff0e1a00012c22' / [ 3735 / condition-component-offset / 5,F6 / nil / , 3736 / directive-override-parameters / 20,{ 3737 / image-digest / 3:[ 3738 / algorithm-id / 2 / sha256 /, 3739 / digest-bytes / 3740 h'0123456789abcdeffedcba987654321000112233445566778899aabbccddeeff' 3741 ], 3742 / image-size / 14:76834, 3743 } 3744 ] / 3745 ] , 3746 / condition-vendor-identifier / 1,F6 / nil / , 3747 / condition-class-identifier / 2,F6 / nil / 3748 ] /, 3749 } /, 3750 / install / 9:h'860f8258248405f613a115781c687474703a2f2f657861 3751 6d706c652e636f6d2f66696c65312e62696e58248405f613a115781c687474703a2f2f 3752 6578616d706c652e636f6d2f66696c65322e62696e15f603f6' / [ 3753 / directive-try-each / 15,[ 3754 h'8405f613a115781c687474703a2f2f6578616d706c652e636f6d 3755 2f66696c65312e62696e' / [ 3756 / condition-component-offset / 5,F6 / nil / , 3757 / directive-set-parameters / 19,{ 3758 / uri / 21:'http://example.com/file1.bin', 3759 } 3760 ] / , 3761 h'8405f613a115781c687474703a2f2f6578616d706c652e636f6d 3762 2f66696c65322e62696e' / [ 3763 / condition-component-offset / 5,F6 / nil / , 3764 / directive-set-parameters / 19,{ 3765 / uri / 21:'http://example.com/file2.bin', 3766 } 3767 ] / 3768 ] , 3769 / directive-fetch / 21,F6 / nil / , 3770 / condition-image-match / 3,F6 / nil / 3771 ] /, 3772 / validate / 10:h'8203f6' / [ 3773 / condition-image-match / 3,F6 / nil / 3774 ] /, 3776 } /, 3777 } 3779 Total size of manifest without COSE authentication object: 256 3781 Manifest: 3783 a10358fca501010203035899a202448181410004588f8814a20150fa6b4a 3784 53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab 3785 450f82582e8405f614a2038202582000112233445566778899aabbccddee 3786 ff0123456789abcdeffedcba98765432100e1987d058308405f614a20382 3787 0258200123456789abcdeffedcba987654321000112233445566778899aa 3788 bbccddeeff0e1a00012c2201f602f6095853860f8258248405f613a11578 3789 1c687474703a2f2f6578616d706c652e636f6d2f66696c65312e62696e58 3790 248405f613a115781c687474703a2f2f6578616d706c652e636f6d2f6669 3791 6c65322e62696e15f603f60a438203f6 3793 Total size of manifest with COSE authentication object: 371 3795 Manifest with COSE authentication object: 3797 a202587081d28443a10126a05824820258201d15a1713d3a4510ca392454 3798 adff987abb5425348e449618122ffa817012cc315840197a4a3a4188fe1d 3799 d8baa468ae9a35ac8e5ef462017530116eadd90892c96c6ab00825fcb45e 3800 db757547733c14d3b637ea8a085ce7bfc782a0b2cd80d31b12940358fca5 3801 01010203035899a202448181410004588f8814a20150fa6b4a53d5ad5fdf 3802 be9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab450f82582e 3803 8405f614a2038202582000112233445566778899aabbccddeeff01234567 3804 89abcdeffedcba98765432100e1987d058308405f614a203820258200123 3805 456789abcdeffedcba987654321000112233445566778899aabbccddeeff 3806 0e1a00012c2201f602f6095853860f8258248405f613a115781c68747470 3807 3a2f2f6578616d706c652e636f6d2f66696c65312e62696e58248405f613 3808 a115781c687474703a2f2f6578616d706c652e636f6d2f66696c65322e62 3809 696e15f603f60a438203f6 3811 13. IANA Considerations 3813 IANA is requested to setup a registry group for SUIT elements. 3815 Within this group, IANA is requested to setup registries for SUIT 3816 keys: 3818 - SUIT Envelope Elements 3820 - SUIT Manifest Elements 3822 - SUIT Common Elements 3823 - SUIT Commands 3825 - SUIT Parameters 3827 - SUIT Text Values 3829 - SUIT Algorithm Identifiers 3831 For each registry, values 0-23 are Standards Action, 24-255 are IETF 3832 Review, 256-65535 are Expert Review, and 65536 or greater are First 3833 Come First Served. 3835 Negative values -23 to 0 are Experimental Use, -24 and lower are 3836 Private Use. 3838 14. Security Considerations 3840 This document is about a manifest format describing and protecting 3841 firmware images and as such it is part of a larger solution for 3842 offering a standardized way of delivering firmware updates to IoT 3843 devices. A more detailed discussion about security can be found in 3844 the architecture document [I-D.ietf-suit-architecture] and in 3845 [I-D.ietf-suit-information-model]. 3847 15. Mailing List Information 3849 The discussion list for this document is located at the e-mail 3850 address suit@ietf.org [1]. Information on the group and information 3851 on how to subscribe to the list is at 3852 https://www1.ietf.org/mailman/listinfo/suit [2] 3854 Archives of the list can be found at: https://www.ietf.org/mail- 3855 archive/web/suit/current/index.html [3] 3857 16. Acknowledgements 3859 We would like to thank the following persons for their support in 3860 designing this mechanism: 3862 - Milosch Meriac 3864 - Geraint Luff 3866 - Dan Ros 3868 - John-Paul Stanford 3870 - Hugo Vincent 3871 - Carsten Bormann 3873 - Oeyvind Roenningstad 3875 - Frank Audun Kvamtroe 3877 - Krzysztof Chruściński 3879 - Andrzej Puzdrowski 3881 - Michael Richardson 3883 - David Brown 3885 - Emmanuel Baccelli 3887 17. References 3889 17.1. Normative References 3891 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3892 Requirement Levels", BCP 14, RFC 2119, 3893 DOI 10.17487/RFC2119, March 1997, 3894 . 3896 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 3897 Unique IDentifier (UUID) URN Namespace", RFC 4122, 3898 DOI 10.17487/RFC4122, July 2005, 3899 . 3901 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 3902 RFC 8152, DOI 10.17487/RFC8152, July 2017, 3903 . 3905 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3906 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3907 May 2017, . 3909 17.2. Informative References 3911 [I-D.ietf-suit-architecture] 3912 Moran, B., Tschofenig, H., Brown, D., and M. Meriac, "A 3913 Firmware Update Architecture for Internet of Things", 3914 draft-ietf-suit-architecture-08 (work in progress), 3915 November 2019. 3917 [I-D.ietf-suit-information-model] 3918 Moran, B., Tschofenig, H., and H. Birkholz, "An 3919 Information Model for Firmware Updates in IoT Devices", 3920 draft-ietf-suit-information-model-05 (work in progress), 3921 January 2020. 3923 17.3. URIs 3925 [1] mailto:suit@ietf.org 3927 [2] https://www1.ietf.org/mailman/listinfo/suit 3929 [3] https://www.ietf.org/mail-archive/web/suit/current/index.html 3931 Authors' Addresses 3933 Brendan Moran 3934 Arm Limited 3936 EMail: Brendan.Moran@arm.com 3938 Hannes Tschofenig 3939 Arm Limited 3941 EMail: hannes.tschofenig@arm.com 3943 Henk Birkholz 3944 Fraunhofer SIT 3946 EMail: henk.birkholz@sit.fraunhofer.de 3948 Koen Zandberg 3949 Inria 3951 EMail: koen.zandberg@inria.fr