idnits 2.17.1 draft-ietf-suit-manifest-03.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 (February 07, 2020) is 1537 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 3733 -- Looks like a reference, but probably isn't: '2' on line 3735 -- Looks like a reference, but probably isn't: '3' on line 3737 == Missing Reference: '-1' is mentioned on line 1788, but not defined == Missing Reference: '-2' is mentioned on line 1790, but not defined == Missing Reference: '-3' is mentioned on line 1794, but not defined -- Looks like a reference, but probably isn't: '4' on line 1794 ** Obsolete normative reference: RFC 8152 (Obsoleted by RFC 9052, RFC 9053) == Outdated reference: A later version (-16) exists of draft-ietf-suit-architecture-08 == Outdated reference: A later version (-13) exists of draft-ietf-suit-information-model-05 Summary: 1 error (**), 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: August 10, 2020 H. Birkholz 6 Fraunhofer SIT 7 February 07, 2020 9 A Concise Binary Object Representation (CBOR)-based Serialization Format 10 for the Software Updates for Internet of Things (SUIT) Manifest 11 draft-ietf-suit-manifest-03 13 Abstract 15 This specification describes the format of a manifest. A manifest is 16 a bundle of metadata about the firmware for an IoT device, where to 17 find the firmware, the devices to which it applies, and cryptographic 18 information protecting the manifest. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at https://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on August 10, 2020. 37 Copyright Notice 39 Copyright (c) 2020 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (https://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 This document may contain material from IETF Documents or IETF 53 Contributions published or made publicly available before November 54 10, 2008. The person(s) controlling the copyright in some of this 55 material may not have granted the IETF Trust the right to allow 56 modifications of such material outside the IETF Standards Process. 57 Without obtaining an adequate license from the person(s) controlling 58 the copyright in such materials, this document may not be modified 59 outside the IETF Standards Process, and derivative works of it may 60 not be created outside the IETF Standards Process, except to format 61 it for publication as an RFC or to translate it into languages other 62 than English. 64 Table of Contents 66 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 67 2. Conventions and Terminology . . . . . . . . . . . . . . . . . 5 68 3. How to use this Document . . . . . . . . . . . . . . . . . . 6 69 4. Background . . . . . . . . . . . . . . . . . . . . . . . . . 6 70 4.1. Landscape . . . . . . . . . . . . . . . . . . . . . . . . 6 71 4.2. Update Workflow Model . . . . . . . . . . . . . . . . . . 7 72 4.3. SUIT Manifest Goals . . . . . . . . . . . . . . . . . . . 8 73 4.4. SUIT Manifest Design Summary . . . . . . . . . . . . . . 9 74 5. Interpreter Behavior . . . . . . . . . . . . . . . . . . . . 10 75 5.1. Interpreter Setup . . . . . . . . . . . . . . . . . . . . 10 76 5.2. Required Checks . . . . . . . . . . . . . . . . . . . . . 11 77 5.3. Interpreter Fundamental Properties . . . . . . . . . . . 12 78 5.4. Abstract Machine Description . . . . . . . . . . . . . . 12 79 5.4.1. Parameters . . . . . . . . . . . . . . . . . . . . . 13 80 5.4.2. Commands . . . . . . . . . . . . . . . . . . . . . . 14 81 5.4.3. Command Behavior . . . . . . . . . . . . . . . . . . 15 82 5.5. Serialized Processing Interpreter . . . . . . . . . . . . 16 83 5.6. Parallel Processing Interpreter . . . . . . . . . . . . . 16 84 5.7. Processing Dependencies . . . . . . . . . . . . . . . . . 17 85 6. Creating Manifests . . . . . . . . . . . . . . . . . . . . . 17 86 6.1. Manifest Source Material . . . . . . . . . . . . . . . . 18 87 6.2. Required Template: Compatibility Check . . . . . . . . . 18 88 6.3. Use Case Template: XIP Secure Boot . . . . . . . . . . . 19 89 6.4. Use Case Template: Firmware Download . . . . . . . . . . 20 90 6.5. Use Case Template: Load from External Storage . . . . . . 20 91 6.6. Use Case Template Load & Decompress from External Storage 20 92 6.7. Use Case Template: Dependency . . . . . . . . . . . . . . 21 93 7. Manifest Structure . . . . . . . . . . . . . . . . . . . . . 21 94 7.1. Severable Elements . . . . . . . . . . . . . . . . . . . 22 95 7.2. Outer Wrapper . . . . . . . . . . . . . . . . . . . . . . 23 96 7.3. Manifest . . . . . . . . . . . . . . . . . . . . . . . . 25 97 7.4. SUIT_Dependency . . . . . . . . . . . . . . . . . . . . . 28 98 7.5. SUIT_Component_Reference . . . . . . . . . . . . . . . . 29 99 7.6. Manifest Parameters . . . . . . . . . . . . . . . . . . . 29 100 7.6.1. SUIT_Parameter_Strict_Order . . . . . . . . . . . . . 31 101 7.6.2. SUIT_Parameter_Soft_Failure . . . . . . . . . . . . . 32 102 7.7. SUIT_Parameter_Encryption_Info . . . . . . . . . . . . . 32 103 7.7.1. SUIT_Parameter_Compression_Info . . . . . . . . . . . 32 104 7.7.2. SUIT_Parameter_Unpack_Info . . . . . . . . . . . . . 32 105 7.7.3. SUIT_Parameters CDDL . . . . . . . . . . . . . . . . 33 106 7.8. SUIT_Command_Sequence . . . . . . . . . . . . . . . . . . 35 107 7.9. SUIT_Condition . . . . . . . . . . . . . . . . . . . . . 36 108 7.9.1. Identifier Conditions . . . . . . . . . . . . . . . . 37 109 7.9.2. suit-condition-image-match . . . . . . . . . . . . . 38 110 7.9.3. suit-condition-image-not-match . . . . . . . . . . . 38 111 7.9.4. suit-condition-use-before . . . . . . . . . . . . . . 38 112 7.9.5. suit-condition-minimum-battery . . . . . . . . . . . 38 113 7.9.6. suit-condition-update-authorized . . . . . . . . . . 38 114 7.9.7. suit-condition-version . . . . . . . . . . . . . . . 39 115 7.9.8. SUIT_Condition_Custom . . . . . . . . . . . . . . . . 40 116 7.9.9. Identifiers . . . . . . . . . . . . . . . . . . . . . 40 117 7.9.10. SUIT_Condition CDDL . . . . . . . . . . . . . . . . . 41 118 7.10. SUIT_Directive . . . . . . . . . . . . . . . . . . . . . 42 119 7.10.1. suit-directive-set-component-index . . . . . . . . . 43 120 7.10.2. suit-directive-set-dependency-index . . . . . . . . 44 121 7.10.3. suit-directive-abort . . . . . . . . . . . . . . . . 44 122 7.10.4. suit-directive-run-sequence . . . . . . . . . . . . 44 123 7.10.5. suit-directive-try-each . . . . . . . . . . . . . . 45 124 7.10.6. suit-directive-process-dependency . . . . . . . . . 45 125 7.10.7. suit-directive-set-parameters . . . . . . . . . . . 46 126 7.10.8. suit-directive-override-parameters . . . . . . . . . 46 127 7.10.9. suit-directive-fetch . . . . . . . . . . . . . . . . 47 128 7.10.10. suit-directive-copy . . . . . . . . . . . . . . . . 47 129 7.10.11. suit-directive-swap . . . . . . . . . . . . . . . . 48 130 7.10.12. suit-directive-run . . . . . . . . . . . . . . . . . 48 131 7.10.13. suit-directive-wait . . . . . . . . . . . . . . . . 49 132 7.10.14. SUIT_Directive CDDL . . . . . . . . . . . . . . . . 50 133 7.11. SUIT_Text_Map . . . . . . . . . . . . . . . . . . . . . . 52 134 8. Access Control Lists . . . . . . . . . . . . . . . . . . . . 52 135 9. SUIT digest container . . . . . . . . . . . . . . . . . . . . 53 136 10. Creating Conditional Sequences . . . . . . . . . . . . . . . 54 137 11. Full CDDL . . . . . . . . . . . . . . . . . . . . . . . . . . 56 138 12. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 63 139 12.1. Example 0: Secure Boot . . . . . . . . . . . . . . . . . 64 140 12.2. Example 1: Simultaneous Download and Installation of 141 Payload . . . . . . . . . . . . . . . . . . . . . . . . 66 142 12.3. Example 2: Simultaneous Download, Installation, and 143 Secure Boot . . . . . . . . . . . . . . . . . . . . . . 68 144 12.4. Example 3: Load from External Storage . . . . . . . . . 69 145 12.5. Example 4: Load and Decompress from External Storage . . 72 146 12.6. Example 5: Compatibility Test, Download, Installation, 147 and Secure Boot . . . . . . . . . . . . . . . . . . . . 75 148 12.7. Example 6: Two Images . . . . . . . . . . . . . . . . . 77 149 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 80 150 14. Security Considerations . . . . . . . . . . . . . . . . . . . 80 151 15. Mailing List Information . . . . . . . . . . . . . . . . . . 81 152 16. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 81 153 17. References . . . . . . . . . . . . . . . . . . . . . . . . . 81 154 17.1. Normative References . . . . . . . . . . . . . . . . . . 81 155 17.2. Informative References . . . . . . . . . . . . . . . . . 82 156 17.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 82 157 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 82 159 1. Introduction 161 A firmware update mechanism is an essential security feature for IoT 162 devices to deal with vulnerabilities. While the transport of 163 firmware images to the devices themselves is important there are 164 already various techniques available, such as the Lightweight 165 Machine-to-Machine (LwM2M) protocol offering device management of IoT 166 devices. Equally important is the inclusion of meta-data about the 167 conveyed firmware image (in the form of a manifest) and the use of 168 end-to-end security protection to detect modifications and 169 (optionally) to make reverse engineering more difficult. End-to-end 170 security allows the author, who builds the firmware image, to be sure 171 that no other party (including potential adversaries) can install 172 firmware updates on IoT devices without adequate privileges. This 173 authorization process is ensured by the use of dedicated symmetric or 174 asymmetric keys installed on the IoT device: for use cases where only 175 integrity protection is required it is sufficient to install a trust 176 anchor on the IoT device. For confidentiality protected firmware 177 images it is additionally required to install either one or multiple 178 symmetric or asymmetric keys on the IoT device. Starting security 179 protection at the author is a risk mitigation technique so firmware 180 images and manifests can be stored on untrusted repositories; it also 181 reduces the scope of a compromise of any repository or intermediate 182 system to be no worse than a denial of service. 184 It is assumed that the reader is familiar with the high-level 185 firmware update architecture [I-D.ietf-suit-architecture]. 187 The SUIT manifest is heavily optimized for consumption by constrained 188 devices. This means that it is not constructed as a conventional 189 descriptive document. Instead, of describing what an update IS, it 190 describes what a recipient should DO. 192 While the SUIT manifest is informed by and optimized for firmware 193 update use cases, there is nothing in the 194 [I-D.ietf-suit-information-model] that restricts its use to only 195 firmware use cases. Software update and delivery of arbitrary data 196 can equally be managed by SUIT-based metadata. 198 2. Conventions and Terminology 200 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 201 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 202 "OPTIONAL" in this document are to be interpreted as described in 203 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 204 capitals, as shown here. 206 The following terminology is used throughout this document. 208 - SUIT: Software Update for the Internet of Things, the IETF working 209 group for this standard. 211 - Payload: A piece of information to be delivered. Typically 212 Firmware for the purposes of SUIT. 214 - Resource: A piece of information that is used to construct a 215 payload. 217 - Manifest: A piece of information that describes one or more 218 payloads, one or more resources, and the processors needed to 219 transform resources into payloads. 221 - Update: One or more manifests that describe one or more payloads. 223 - Update Authority: The owner of a cryptographic key used to sign 224 updates, trusted by Recipients. 226 - Recipient: The system, typically an IoT device, that receives a 227 manifest. 229 - Condition: A test for a property of the Recipient or its 230 components. 232 - Directive: An action for the Recipient to perform. 234 - Command: A Condition or a Directive. 236 - Trusted Execution: A process by which a system ensures that only 237 trusted code is executed, for example secure boot. 239 - A/B images: Dividing a device's storage into two or more bootable 240 images, at different offsets, such that the active image can write 241 to the inactive image(s). 243 The map indices in this encoding are reset to 1 for each map within 244 the structure. This is to keep the indices as small as possible. 245 The goal is to keep the index objects to single bytes (CBOR positive 246 integers 1-23). 248 Wherever enumerations are used, they are started at 1. This allows 249 detection of several common software errors that are caused by 250 uninitialised variables. Positive numbers in enumerations are 251 reserved for IANA registration. Negative numbers are used to 252 identify application-specific implementations. 254 CDDL names are hyphenated and CDDL structures follow the convention 255 adopted in COSE [RFC8152]: SUIT_Structure_Name. 257 3. How to use this Document 259 For information about firmware update in general and the background 260 of the suit manifest, see Section 4. To implement an updatable 261 device, see Section 5 and Section 7. To implement a tool that 262 generates updates, see Section 6 and Section 7. 264 4. Background 266 Distributing firmware updates to diverse devices with diverse trust 267 anchors in a coordinated system presents unique challenges. Devices 268 have a broad set of constraints, requiring different metadata to make 269 appropriate decisions. There may be many actors in production IoT 270 systems, each of whom has some authority. Distributing firmware in 271 such a multi-party environment presents additional challenges. Each 272 party requires a different subset of data. Some data may not be 273 accessible to all parties. Multiple signatures may be required from 274 parties with different authorities. This topic is covered in more 275 depth in [I-D.ietf-suit-architecture]. 277 4.1. Landscape 279 The various constraints on IoT devices creates a broad set of use- 280 case requirements. For example, devices with: 282 - limited processing power and storage may require a simple 283 representation of metadata. 285 - bandwidth constraints may require firmware compression or partial 286 update support. 288 - bootloader complexity constraints may require simple selection 289 between two bootable images. 291 - small internal storage may require external storage support. 293 - multiple processors may require coordinated update of all 294 applications. 296 - large storage and complex functionality may require parallel 297 update of many software components. 299 - mesh networks may require multicast distribution. 301 Supporting the requirements introduced by the constraints on IoT 302 devices requires the flexibility to represent a diverse set of 303 possible metadata, but also requires that the encoding is kept 304 simple. 306 4.2. Update Workflow Model 308 There are several fundamental assumptions that inform the model of 309 the firmware update workflow: 311 - Compatibility must be checked before any other operation is 312 performed. 314 - All dependency manifests should be present before any payload is 315 fetched. 317 - In some applications, payloads must be fetched and validated prior 318 to installation. 320 There are several fundamental assumptions that inform the model of 321 the secure boot workflow: 323 - Compatibility must be checked before any other operation is 324 performed. 326 - All dependencies and payloads must be validated prior to loading. 328 - All loaded images must be validated prior to execution. 330 Based on these assumptions, the manifest is structured to work with a 331 pull parser, where each section of the manifest is used in sequence. 332 The expected workflow for a device installing an update can be broken 333 down into 5 steps: 335 1. Verify the signature of the manifest. 337 2. Verify the applicability of the manifest. 339 3. Resolve dependencies. 341 4. Fetch payload(s). 343 5. Install payload(s). 345 When installation is complete, similar information can be used for 346 validating and running images in a further 3 steps: 348 1. Verify image(s). 350 2. Load image(s). 352 3. Run image(s). 354 If verification and running is implemented in bootloader, then the 356 When multiple manifests are used for an update, each manifest's steps 357 occur in a lockstep fashion; all manifests have dependency resolution 358 performed before any manifest performs a payload fetch, etc. 360 4.3. SUIT Manifest Goals 362 The manifest described in this document is intended to meet several 363 goals, as described below. 365 1. Meet the requirements defined in 366 [I-D.ietf-suit-information-model]. 368 2. Simple to parse on a constrained node 370 3. Simple to process on a constrained node 372 4. Compact encoding 374 5. Comprehensible by an intermediate system 376 6. Expressive enough to enable advanced use cases on advanced nodes 378 7. Extensible 380 The SUIT manifest can be used for a variety of purposes throughout 381 its lifecycle. The manifest allows: 383 1. the Firmware Author to reason about releasing a firmware. 385 2. the Network Operator to reason about compatibility of a firmware. 387 3. the Device Operator to reason about the impact of a firmware. 389 4. the Device Operator to manage distribution of firmware to 390 devices. 392 5. the Plant Manager to reason about timing and acceptance of 393 firmware updates. 395 6. the device to reason about the authority & authenticity of a 396 firmware prior to installation. 398 7. the device to reason about the applicability of a firmware. 400 8. the device to reason about the installation of a firmware. 402 9. the device to reason about the authenticity & encoding of a 403 firmware at boot. 405 Each of these uses happens at a different stage of the manifest 406 lifecycle, so each has different requirements. 408 4.4. SUIT Manifest Design Summary 410 In order to provide flexible behavior to constrained devices, while 411 still allowing more powerful devices to use their full capabilities, 412 the SUIT manifest encodes the required behavior of a Recipient 413 device. Behavior is encoded as a specialized byte code, contained in 414 a CBOR list. This promotes a flat encoding, which simplifies the 415 parser. The information encoded by this byte code closely matches 416 the operations that a device will perform, which promotes ease of 417 processing. The core operations used by most update and trusted 418 execution operations are represented in the byte code. The byte code 419 can be extended by registering new operations. 421 The specialized byte code approach gives benefits equivalent to those 422 provided by a scripting language or conventional byte code, with two 423 substantial differences. First, the language is extremely high 424 level, consisting of only the operations that a device may perform 425 during update and trusted execution of a firmware image. Second, the 426 language specifies behaviors in a linearized form, without reverse 427 branches. Conditional processing is supported, and parallel and out- 428 of-order processing may be performed by sufficiently capable devices. 430 By structuring the data in this way, the manifest processor becomes a 431 very simple engine that uses a pull parser to interpret the manifest. 432 This pull parser invokes a series of command handlers that evaluate a 433 Condition or execute a Directive. Most data is structured in a 434 highly regular pattern, which simplifies the parser. 436 The results of this allow a Recipient to implement a very small 437 parser for constrained applications. If needed, such a parser also 438 allows the Recipient to perform complex updates with reduced 439 overhead. Conditional execution of commands allows a simple device 440 to perform important decisions at validation-time. 442 Dependency handling is vastly simplified as well. Dependencies 443 function like subroutines of the language. When a manifest has a 444 dependency, it can invoke that dependency's commands and modify their 445 behavior by setting parameters. Because some parameters come with 446 security implications, the dependencies also have a mechanism to 447 reject modifications to parameters on a fine-grained level. 449 Developing a robust permissions system works in this model too. The 450 Recipient can use a simple ACL that is a table of Identities and 451 Component Identifier permissions to ensure that only manifests 452 authenticated by the appropriate identity have access to operate on a 453 component. 455 Capability reporting is similarly simplified. A Recipient can report 456 the Commands, Parameters, Algorithms, and Component Identifiers that 457 it supports. This is sufficiently precise for a manifest author to 458 create a manifest that the Recipient can accept. 460 The simplicity of design in the Recipient due to all of these 461 benefits allows even a highly constrained platform to use advanced 462 update capabilities. 464 5. Interpreter Behavior 466 This section describes the behavior of the manifest interpreter. 467 This section focuses primarily on interpreting commands in the 468 manifest. However, there are several other important behaviors of 469 the interpreter: encoding version detection, rollback protection, and 470 authenticity verification are chief among these. 472 5.1. Interpreter Setup 474 Prior to executing any command sequence, the interpreter or its host 475 application MUST inspect the manifest version field and fail when it 476 encounters an unsupported encoding version. Next, the interpreter or 477 its host application MUST extract the manifest sequence number and 478 perform a rollback check using this sequence number. The exact logic 479 of rollback protection may vary by application, but it has the 480 following properties: 482 - Whenever the interpreter can choose between several manifests, it 483 MUST select the latest valid manifest, authentic manifest. 485 - If the latest valid, authentic manifest fails, it MAY select the 486 next latest valid, authentic manifest. 488 Here, valid means that a manifest has a supported encoding version 489 AND it has not been excluded for other reasons. Reasons for 490 excluding typically involve first executing the manifest and MAY 491 include: 493 - Test failed (e.g. Vendor ID/Class ID). 495 - Unsupported command encountered. 497 - Unsupported parameter encountered. 499 - Unsupported component ID encountered. 501 - Payload not available (update interpreter). 503 - Dependency not available (update interpreter). 505 - Application crashed when executed (bootloader interpreter). 507 - Watchdog timeout occurred (bootloader interpreter). 509 - Dependency or Payload verification failed (bootloader 510 interpreter). 512 These failure reasons MAY be combined with retry mechanisms prior to 513 marking a manifest as invalid. 515 Following these initial tests, the interpreter clears all parameter 516 storage. This ensures that the interpreter begins without any leaked 517 data. 519 5.2. Required Checks 521 Once a valid, authentic manifest has been selected, the interpreter 522 MUST examine the component list and verify that its maximum number of 523 components is not exceeded and that each listed component ID is 524 supported. 526 For each listed component, the interpreter MUST provide storage for 527 the supported parameters (Section 5.4.1). If the interpreter does 528 not have sufficient temporary storage to process the parameters for 529 all components, it MAY process components serially for each command 530 sequence. See Section 5.5 for more details. 532 The interpreter SHOULD check that the common section contains at 533 least one vendor ID check and at least one class ID check. 535 If the manifest contains more than one component, each command 536 sequence MUST begin with a Set Current Component command. 538 If a dependency is specified, then the interpreter MUST perform the 539 following checks: 541 1. At the beginning of each section in the dependent: all previous 542 sections of each dependency have been executed. 544 2. At the end of each section in the dependent: The corresponding 545 section in each dependency has been executed. 547 If the interpreter does not support dependencies and a manifest 548 specifies a dependency, then the interpreter MUST reject the 549 manifest. 551 5.3. Interpreter Fundamental Properties 553 The interpreter has a small set of design goals: 555 1. Executing an update MUST either result in an error, or a 556 verifiably correct system state. 558 2. Executing a secure boot MUST either result in an error, or a 559 booted system. 561 3. Executing the same manifest on multiple devices MUST result in 562 the same system state. 564 NOTE: when using A/B images, the manifest functions as two (or more) 565 logical manifests, each of which applies to a system in a particular 566 starting state. With that provision, design goal 3 holds. 568 5.4. Abstract Machine Description 570 The byte code that forms the bulk of the manifest is processed by an 571 interpreter. This interpreter can be modeled as a simple abstract 572 machine. This machine consists of several data storage locations 573 that are modified by commands. Certain commands also affect the 574 machine's behavior. 576 Every command that modifies system state targets a specific 577 component. Components are units of code or data that can be targeted 578 by an update. They are identified by Component identifiers, arrays 579 of binary-strings-effectively a binary path. Each component has a 580 corresponding set of configuration, Parameters. Parameters are used 581 as the inputs to commands. 583 5.4.1. Parameters 585 Some parameters are REQUIRED to implement. These parameters allow a 586 device to perform core functions. 588 - Vendor ID. 590 - Class ID. 592 - Image Digest. 594 Some parameters are RECOMMENDED to implement. These parameters are 595 needed for most use-cases. 597 - Image Size. 599 - URI. 601 Other parameters are OPTIONAL to implement. These parameters allow a 602 device to implement specific use-cases. 604 - Strict Order. 606 - Soft Failure. 608 - Device ID. 610 - Encryption Info. 612 - Unpack Info. 614 - Source Component. 616 - URI List. 618 - Custom Parameters. 620 5.4.2. Commands 622 Commands define the behavior of a device. The commands are divided 623 into two groups: those that modify state (directives) and those that 624 perform tests (conditions). There are also several Control Flow 625 operations. 627 Some commands are REQUIRED to implement. These commands allow a 628 device to perform core functions 630 - Check Vendor Identifier (cvid). 632 - Check Class Identifier (ccid). 634 - Verify Image (cimg). 636 - Set Current Component (setc). 638 - Override Parameters (ovrp). 640 NOTE: on systems that support only a single component, Set Current 641 Component has no effect. 643 Some commands are RECOMMENDED to implement. These commands are 644 needed for most use-cases 646 - Set Current Dependency (setd). 648 - Set Parameters (setp). 650 - Process Dependency (pdep). 652 - Run (run). 654 - Fetch (getc). 656 Other commands are OPTIONAL to implement. These commands allow a 657 device to implement specific use-cases. 659 - Use Before (ubf). 661 - Check Component Offset (cco). 663 - Check Device Identifier (cdid). 665 - Check Image Not Match (nimg). 667 - Check Minimum Battery (minb). 669 - Check Update Authorized (auth). 671 - Check Version (cver). 673 - Abort (abrt). 675 - Try Each (try). 677 - Copy (copy). 679 - Swap (swap). 681 - Wait For Event (wfe). 683 - Run Sequence (srun) mandatory component set. 685 - Run with Arguments (arun). 687 5.4.3. Command Behavior 689 The following table describes the behavior of each command. "params" 690 represents the parameters for the current component or dependency. 692 +------+------------------------------------------------------------+ 693 | Code | Operation | 694 +------+------------------------------------------------------------+ 695 | cvid | binary-match(component, params[vendor-id]) | 696 | | | 697 | ccid | binary-match(component, params[class-id]) | 698 | | | 699 | cimg | binary-match(digest(component), params[digest]) | 700 | | | 701 | setc | component := components[arg] | 702 | | | 703 | ovrp | params[k] := v for k,v in arg | 704 | | | 705 | setd | dependency := dependencies[arg] | 706 | | | 707 | setp | params[k] := v if not k in params for k,v in arg | 708 | | | 709 | pdep | exec(dependency[common]); exec(dependency[current- | 710 | | segment]) | 711 | | | 712 | run | run(component) | 713 | | | 714 | getc | store(component, fetch(params[uri])) | 715 | | | 716 | ubf | assert(now() < arg) | 717 | | | 718 | cco | assert(offsetof(component) == arg) | 719 | | | 720 | cdid | binary-match(component, params[device-id]) | 721 | | | 722 | nimg | not binary-match(digest(component), params[digest]) | 723 | | | 724 | minb | assert(battery >= arg) | 725 | | | 726 | auth | assert(isAuthorized()) | 727 | | | 728 | cver | assert(version_check(component, arg)) | 729 | | | 730 | abrt | assert(0) | 731 | | | 732 | try | break if exec(seq) is not error for seq in arg | 733 | | | 734 | copy | store(component, params[src-component]) | 735 | | | 736 | swap | swap(component, params[src-component]) | 737 | | | 738 | wfe | until event(arg), wait | 739 | | | 740 | srun | exec(arg) | 741 | | | 742 | arun | run(component, arg) | 743 +------+------------------------------------------------------------+ 745 5.5. Serialized Processing Interpreter 747 Because each manifest has a list of components and a list of 748 components defined by its dependencies, it is possible for the 749 manifest processor to handle one component at a time, traversing the 750 manifest tree once for each listed component. In this mode, the 751 interpreter ignores any commands executed while the component index 752 is not the current component. This reduces the overall volatile 753 storage required to process the update so that the only limit on 754 number of components is the size of the manifest. However, this 755 approach requires additional processing power. 757 5.6. Parallel Processing Interpreter 759 Advanced devices may make use of the Strict Order parameter and 760 enable parallel processing of some segments, or it may reorder some 761 segments. To perform parallel processing, once the Strict Order 762 parameter is set to False, the device may fork a process for each 763 command until the Strict Order parameter is returned to True or the 764 command sequence ends. Then, it joins all forked processes before 765 continuing processing of commands. To perform out-of-order 766 processing, a similar approach is used, except the device consumes 767 all commands after the Strict Order parameter is set to False, then 768 it sorts these commands into its preferred order, invokes them all, 769 then continues processing. 771 Under each of these scenarios the parallel processing must halt: 773 - Set Parameters. 775 - Override Parameters. 777 - Set Strict Order = True. 779 - Set Dependency Index. 781 - Set Component Index. 783 To perform more useful parallel operations, sequences of commands may 784 be collected in a suit-directive-run-sequence. Then, each of these 785 sequences may be run in parallel. Each sequence defaults to Strict 786 Order = True. To isolate each sequence from each other sequence, 787 each sequence must declare a single target component. Set Component 788 Index is not permitted inside this sequence. 790 5.7. Processing Dependencies 792 As described in Section 5.2, each manifest must invoke each of its 793 dependencies sections from the corresponding section of the 794 dependent. Any changes made to parameters by the dependency persist 795 in the dependent. 797 When a Process Dependency command is encountered, the interpreter 798 loads the dependency identified by the Current Dependency Index. The 799 interpreter first executes the common-sequence section of the 800 identified dependency, then it executes the section of the dependency 801 that corresponds to the currently executing section of the dependent. 803 The interpreter also performs the checks described in Section 5.2 to 804 ensure that the dependent is processing the dependency correctly. 806 6. Creating Manifests 808 Manifests are created using tools for constructing COSE structures, 809 calculating cryptographic values and compiling desired system state 810 into a sequence of operations required to achieve that state. The 811 process of constructing COSE structures is covered in [RFC8152] and 812 the calculation of cryptographic values is beyond the scope of this 813 document. 815 Compiling desired system state into a sequence of operations can be 816 accomplished in many ways, however several templates are provided 817 here to cover common use-cases. Many of these templates can be 818 aggregated to produce more complex behavior. 820 NOTE: On systems that support only a single component, Set Current 821 Component has no effect and can be omitted. 823 NOTE: Digest should always be set using Override Parameters, since 824 this prevents a less-privileged dependent from replacing the digest. 826 6.1. Manifest Source Material 828 When a manifest is constructed from a descriptive document, the 829 descriptive document SHOULD be included in the severable text 830 section. This section MAY be pruned from the manifest prior to 831 distribution to a device. The inclusion of text source material 832 enables several use-cases on unconstrained intermediate systems, 833 where small manifest size, low parser complexity, and pull parsing 834 are not required. 836 An unconstrained system that makes decisions based on the manifest 837 can use the source material instead so that it does not need to 838 execute the manifest. 840 An unconstrained system that presents data to a user can do so 841 according to typical usage patterns without first executing the 842 manifest, and can trust that information with the same level of 843 confidence as the manifest itself. 845 A verifier can be constructed to emulate execution the manifest and 846 compare the results of that execution to the source material, 847 providing a check that the manifest performs its stated objectives 848 and that the manifest does not exceed the capabilities of the target 849 device. 851 6.2. Required Template: Compatibility Check 853 The compatibility check ensures that devices only install compatible 854 images. 856 Common: Set Current Component Check Vendor Identifier Check Class 857 Identifier 858 All manifests MUST contain the compatibility check template, except 859 as outlined below. 861 If a device class has a unique trust anchor, and every element in its 862 trust chain is unique-different from every element in any other 863 device class, then it MAY include the compatibility check. 865 If a manifest includes a dependency that performs a compatibility 866 check, then the dependent manifest MAY include the compatibility 867 check. 869 The compatibility check template contains a data dependency: Vendor 870 Identifier and Class Identifier MUST be set prior to executing the 871 template. One example of the full template is included below, 872 however Parameters may be set within a Try-Each block as well. They 873 may also be inherited from a dependent manifest. 875 - Common: 877 o Set Current Component. 879 o Set Parameters: 881 * Vendor ID. 883 * Class ID. 885 o Check Vendor Identifier. 887 o Check Class Identifier. 889 6.3. Use Case Template: XIP Secure Boot 891 - Common: 893 o Set Current Component. 895 o Override Parameters: 897 * Digest. 899 * Size. 901 - Run: 903 o Set Current Component. 905 o Check Image Match. 907 o Directive Run. 909 6.4. Use Case Template: Firmware Download 911 - Common: 913 o Set Current Component. 915 o Override Parameters: 917 * Digest. 919 * Size. 921 - Install: 923 o Set Current Component. 925 o Set Parameters: 927 * URI. 929 o Fetch. 931 6.5. Use Case Template: Load from External Storage 933 - Load: 935 o Set Current Component. 937 o Set Parameters: 939 * Source Index. 941 o Copy. 943 6.6. Use Case Template Load & Decompress from External Storage 945 - Load: 947 o Set Current Component. 949 o Set Parameters: 951 * Source Index. 953 * Compression Info. 955 o Copy. 957 6.7. Use Case Template: Dependency 959 - Dependency Resolution: 961 o Set Current Dependency. 963 o Set Parameters: 965 * URI. 967 o Fetch. 969 o Check Image Match. 971 o Process Dependency. 973 - Validate: 975 o Set Current Dependency. 977 o Check Image Match. 979 o Process Dependency. 981 For any other section that the dependency has, the dependent MUST 982 invoke Process Dependency. 984 NOTE: Any changes made to parameters in a dependency persist in the 985 dependent. 987 7. Manifest Structure 989 The manifest is divided into several sections in a hierarchy as 990 follows: 992 1. The outer wrapper 994 1. Authentication delegation chain(s) 996 2. The authentication wrapper 998 3. The manifest 1000 1. Critical Information 1002 2. Information shared by all command sequences 1003 1. List of dependencies 1005 2. List of payloads 1007 3. List of payloads in dependencies 1009 4. Common list of conditions, directives 1011 3. Dependency resolution Reference or list of conditions, 1012 directives 1014 4. Payload fetch Reference or list of conditions, 1015 directives 1017 5. Installation Reference or list of conditions, 1018 directives 1020 6. Verification conditions/directives 1022 7. Load conditions/directives 1024 8. Run conditions/directives 1026 9. Text / Reference 1028 10. COSWID / Reference 1030 4. Dependency resolution conditions/directives 1032 5. Payload fetch conditions/directives 1034 6. Installation conditions/directives 1036 7. Text 1038 8. COSWID / Reference 1040 9. Intermediate Certificate(s) / CWTs 1042 10. Inline Payload(s) 1044 7.1. Severable Elements 1046 Because the manifest can be used by different actors at different 1047 times, some parts of the manifest can be removed without affecting 1048 later stages of the lifecycle. This is called "Severing." Severing 1049 of information is achieved by separating that information from the 1050 signed container so that removing it does not affect the signature. 1052 This means that ensuring authenticity of severable parts of the 1053 manifest is a requirement for the signed portion of the manifest. 1054 Severing some parts makes it possible to discard parts of the 1055 manifest that are no longer necessary. This is important because it 1056 allows the storage used by the manifest to be greatly reduced. For 1057 example, no text size limits are needed if text is removed from the 1058 manifest prior to delivery to a constrained device. 1060 Elements are made severable by removing them from the manifest, 1061 encoding them in a bstr, and placing a SUIT_Digest of the bstr in the 1062 manifest so that they can still be authenticated. The SUIT_Digest 1063 typically consumes 4 bytes more than the size of the raw digest, 1064 therefore elements smaller than (Digest Bits)/8 + 4 SHOULD never be 1065 severable. Elements larger than (Digest Bits)/8 + 4 MAY be 1066 severable, while elements that are much larger than (Digest Bits)/8 + 1067 4 SHOULD be severable. 1069 Because of this, all command sequences in the manifest are encoded in 1070 a bstr so that there is a single code path needed for all command 1071 sequences 1073 7.2. Outer Wrapper 1075 This object is a container for the other pieces of the manifest to 1076 provide a common mechanism to find each of the parts. All elements 1077 of the outer wrapper are contained in bstr objects. Wherever the 1078 manifest references an object in the outer wrapper, the bstr is 1079 included in the digest calculation. 1081 The CDDL that describes the wrapper is below 1083 SUIT_Outer_Wrapper = { 1084 suit-delegation => bstr .cbor SUIT_Delegation 1085 suit-authentication-wrapper => bstr .cbor 1086 SUIT_Authentication_Wrapper / nil, 1087 $SUIT_Manifest_Wrapped, 1088 ? suit-dependency-resolution => bstr .cbor SUIT_Command_Sequence, 1089 ? suit-payload-fetch => bstr .cbor SUIT_Command_Sequence, 1090 ? suit-install => bstr .cbor SUIT_Command_Sequence, 1091 ? suit-text => bstr .cbor SUIT_Text_Map, 1092 ? suit-coswid => bstr .cbor COSWID 1093 } 1095 SUIT_Delegation = [ + [ + CWT ] ] 1097 SUIT_Authentication_Wrapper = [ + (COSE_Mac_Tagged / COSE_Sign_Tagged / 1098 COSE_Mac0_Tagged / COSE_Sign1_Tagged)] 1099 SUIT_Encryption_Wrapper = COSE_Encrypt_Tagged / COSE_Encrypt0_Tagged 1101 SUIT_Manifest_Wrapped //= (suit-manifest => bstr .cbor SUIT_Manifest) 1102 SUIT_Manifest_Wrapped //= ( 1103 suit-manifest-encryption-info => bstr .cbor SUIT_Encryption_Wrapper, 1104 suit-manifest-encrypted => bstr 1105 ) 1107 All elements of the outer wrapper must be wrapped in a bstr to 1108 minimize the complexity of the code that evaluates the cryptographic 1109 integrity of the element and to ensure correct serialization for 1110 integrity and authenticity checks. 1112 The suit-authentication-wrapper contains a list of 1 or more 1113 cryptographic authentication wrappers for the core part of the 1114 manifest. These are implemented as COSE_Mac_Tagged or 1115 COSE_Sign_Tagged blocks. The Manifest is authenticated by these 1116 blocks in "detached payload" mode. The COSE_Mac_Tagged and 1117 COSE_Sign_Tagged blocks are described in RFC 8152 [RFC8152] and are 1118 beyond the scope of this document. The suit-authentication-wrapper 1119 MUST come first in the SUIT_Outer_Wrapper, regardless of canonical 1120 encoding of CBOR. All validators MUST reject any SUIT_Outer_Wrapper 1121 that begins with any element other than a suit-authentication- 1122 wrapper. 1124 A manifest that has not had authentication information added MUST 1125 still contain the suit-authentication-wrapper element, but the 1126 content MUST be nil. 1128 The outer wrapper MUST contain only one of 1130 - a plaintext manifest: SUIT_Manifest. 1132 - an encrypted manifest: both a SUIT_Encryption_Wrapper and the 1133 ciphertext of a manifest. 1135 When the outer wrapper contains SUIT_Encryption_Wrapper, the suit- 1136 authentication-wrapper MUST authenticate the plaintext of suit- 1137 manifest-encrypted. 1139 suit-manifest contains a SUIT_Manifest structure, which describes the 1140 payload(s) to be installed and any dependencies on other manifests. 1142 suit-manifest-encryption-info contains a SUIT_Encryption_Wrapper, a 1143 COSE object that describes the information required to decrypt a 1144 ciphertext manifest. 1146 suit-manifest-encrypted contains a ciphertext manifest. 1148 Each of suit-dependency-resolution, suit-payload-fetch, and suit- 1149 payload-installation contain the severable contents of the 1150 identically named portions of the manifest, described in Section 7.3. 1152 suit-text contains all the human-readable information that describes 1153 any and all parts of the manifest, its payload(s) and its 1154 resource(s). 1156 suit-coswid contains a Concise Software Identifier. This may be 1157 discarded by the Recipient if not needed. 1159 7.3. Manifest 1161 The manifest describes the critical metadata for the referenced 1162 payload(s). In addition, it contains: 1164 1. a version number for the manifest structure itself 1166 2. a sequence number 1168 3. a list of dependencies 1170 4. a list of components affected 1172 5. a list of components affected by dependencies 1174 6. a reference for each of the severable blocks. 1176 7. a list of actions that the Recipient should perform. 1178 The following CDDL fragment defines the manifest. 1180 SUIT_Manifest = { 1181 suit-manifest-version 1182 => 1, 1183 suit-manifest-sequence-number 1184 => uint, 1185 suit-common 1186 => bstr .cbor SUIT_Common, 1187 ? suit-dependency-resolution 1188 => Digest / bstr .cbor SUIT_Command_Sequence, 1189 ? suit-payload-fetch 1190 => Digest / bstr .cbor SUIT_Command_Sequence, 1191 ? suit-install 1192 => Digest / bstr .cbor SUIT_Command_Sequence, 1193 ? suit-validate 1194 => bstr .cbor SUIT_Command_Sequence, 1195 ? suit-load 1196 => bstr .cbor SUIT_Command_Sequence, 1197 ? suit-run 1198 => bstr .cbor SUIT_Command_Sequence, 1199 ? suit-text 1200 => Digest, 1201 ? suit-coswid 1202 => Digest / bstr .cbor concise-software-identity, 1203 } 1205 SUIT_Common = { 1206 ? suit-dependencies 1207 => bstr .cbor [ + SUIT_Dependency ], 1208 ? suit-components 1209 => bstr .cbor [ + SUIT_Component_Identifier ], 1210 ? suit-dependency-components 1211 => bstr .cbor [ + SUIT_Component_Reference ], 1212 ? suit-common-sequence 1213 => bstr .cbor SUIT_Command_Sequence, 1214 } 1216 Several fields in the Manifest can be either a CBOR structure or a 1217 SUIT_Digest. In each of these cases, the SUIT_Digest provides for a 1218 severable field. Severable fields are RECOMMENDED to implement. In 1219 particular, text SHOULD be severable, since most useful text elements 1220 occupy more space than a SUIT_Digest, but are not needed by the 1221 Recipient. Because SUIT_Digest is a CBOR Array and each severable 1222 element is a CBOR bstr, it is straight-forward for a Recipient to 1223 determine whether an element is been severable. The key used for a 1224 severable element is the same in the SUIT_Manifest and in the 1225 SUIT_Outer_Wrapper so that a Recipient can easily identify the 1226 correct data in the outer wrapper. 1228 The suit-manifest-version indicates the version of serialization used 1229 to encode the manifest. Version 1 is the version described in this 1230 document. suit-manifest-version is REQUIRED. 1232 The suit-manifest-sequence-number is a monotonically increasing anti- 1233 rollback counter. It also helps devices to determine which in a set 1234 of manifests is the "root" manifest in a given update. Each manifest 1235 MUST have a sequence number higher than each of its dependencies. 1236 Each Recipient MUST reject any manifest that has a sequence number 1237 lower than its current sequence number. It MAY be convenient to use 1238 a UTC timestamp in seconds as the sequence number. suit-manifest- 1239 sequence-number is REQUIRED. 1241 suit-common encodes all the information that is shared between each 1242 of the command sequences, including: suit-dependencies, suit- 1243 components, suit-dependency-components, and suit-common-sequence. 1244 suit-common is REQUIRED to implement. 1246 suit-dependencies is a list of SUIT_Dependency blocks that specify 1247 manifests that must be present before the current manifest can be 1248 processed. suit-dependencies is OPTIONAL to implement. 1250 In order to distinguish between components that are affected by the 1251 current manifest and components that are affected by a dependency, 1252 they are kept in separate lists. Components affected by the current 1253 manifest only list the component identifier. Components affected by 1254 a dependency include the component identifier and the index of the 1255 dependency that defines the component. 1257 suit-components is a list of SUIT_Component blocks that specify the 1258 component identifiers that will be affected by the content of the 1259 current manifest. suit-components is OPTIONAL, but at least one 1260 manifest MUST contain a suit-components block. 1262 suit-dependency-components is a list of SUIT_Component_Reference 1263 blocks that specify component identifiers that will be affected by 1264 the content of a dependency of the current manifest. suit-dependency- 1265 components is OPTIONAL. 1267 suit-common-sequence is a SUIT_Command_Sequence to execute prior to 1268 executing any other command sequence. Typical actions in suit- 1269 common-sequence include setting expected device identity and image 1270 digests when they are conditional (see Section 10 for more 1271 information on conditional sequences). suit-common-sequence is 1272 RECOMMENDED. 1274 suit-dependency-resolution is a SUIT_Command_Sequence to execute in 1275 order to perform dependency resolution. Typical actions include 1276 configuring URIs of dependency manifests, fetching dependency 1277 manifests, and validating dependency manifests' contents. suit- 1278 dependency-resolution is REQUIRED when suit-dependencies is present. 1280 suit-payload-fetch is a SUIT_Command_Sequence to execute in order to 1281 obtain a payload. Some manifests may include these actions in the 1282 suit-install section instead if they operate in a streaming 1283 installation mode. This is particularly relevant for constrained 1284 devices without any temporary storage for staging the update. suit- 1285 payload-fetch is OPTIONAL. 1287 suit-install is a SUIT_Command_Sequence to execute in order to 1288 install a payload. Typical actions include verifying a payload 1289 stored in temporary storage, copying a staged payload from temporary 1290 storage, and unpacking a payload. suit-install is OPTIONAL. 1292 suit-validate is a SUIT_Command_Sequence to execute in order to 1293 validate that the result of applying the update is correct. Typical 1294 actions involve image validation and manifest validation. suit- 1295 validate is REQUIRED. If the manifest contains dependencies, one 1296 process-dependency invocation per dependency or one process- 1297 dependency invocation targeting all dependencies SHOULD be present in 1298 validate. 1300 suit-load is a SUIT_Command_Sequence to execute in order to prepare a 1301 payload for execution. Typical actions include copying an image from 1302 permanent storage into RAM, optionally including actions such as 1303 decryption or decompression. suit-load is OPTIONAL. 1305 suit-run is a SUIT_Command_Sequence to execute in order to run an 1306 image. suit-run typically contains a single instruction: either the 1307 "run" directive for the bootable manifest or the "process 1308 dependencies" directive for any dependents of the bootable manifest. 1309 suit-run is OPTIONAL. Only one manifest in an update may contain the 1310 "run" directive. 1312 suit-text is a digest that uniquely identifies the content of the 1313 Text that is packaged in the OuterWrapper. text is OPTIONAL. 1315 suit-coswid is a digest that uniquely identifies the content of the 1316 concise-software-identifier that is packaged in the OuterWrapper. 1317 coswid is OPTIONAL. 1319 7.4. SUIT_Dependency 1321 SUIT_Dependency specifies a manifest that describes a dependency of 1322 the current manifest. 1324 The following CDDL describes the SUIT_Dependency structure. 1326 SUIT_Dependency = { 1327 suit-dependency-digest => SUIT_Digest, 1328 ? suit-dependency-prefix => SUIT_Component_Identifier, 1329 } 1331 The suit-dependency-digest specifies the dependency manifest uniquely 1332 by identifying a particular Manifest structure. The digest is 1333 calculated over the Manifest structure instead of the COSE 1334 Sig_structure or Mac_structure. This means that a digest may need to 1335 be calculated more than once, however this is necessary to ensure 1336 that removing a signature from a manifest does not break dependencies 1337 due to missing signature elements. This is also necessary to support 1338 the trusted intermediary use case, where an intermediary re-signs the 1339 Manifest, removing the original signature, potentially with a 1340 different algorithm, or trading COSE_Sign for COSE_Mac. 1342 The suit-dependency-prefix element contains a 1343 SUIT_Component_Identifier. This specifies the scope at which the 1344 dependency operates. This allows the dependency to be forwarded on 1345 to a component that is capable of parsing its own manifests. It also 1346 allows one manifest to be deployed to multiple dependent devices 1347 without those devices needing consistent component hierarchy. This 1348 element is OPTIONAL. 1350 7.5. SUIT_Component_Reference 1352 The SUIT_Component_Reference describes an image that is defined by 1353 another manifest. This is useful for overriding the behavior of 1354 another manifest, for example by directing the recipient to look at a 1355 different URI for the image or by changing the expected format, such 1356 as when a gateway performs decryption on behalf of a constrained 1357 device. The following CDDL describes the SUIT_Component_Reference. 1359 SUIT_Component_Reference = { 1360 suit-component-identifier => SUIT_Component_Identifier, 1361 suit-component-dependency-index => uint 1362 } 1364 7.6. Manifest Parameters 1366 Many conditions and directives require additional information. That 1367 information is contained within parameters that can be set in a 1368 consistent way. This allows reduction of manifest size and 1369 replacement of parameters from one manifest to the next. 1371 The defined manifest parameters are described below. 1373 +-----+--------+-------------------+------------+-------------------+ 1374 | ID | CBOR | Scope | Name | Description | 1375 | | Type | | | | 1376 +-----+--------+-------------------+------------+-------------------+ 1377 | 1 | boolea | Global | Strict | Requires that the | 1378 | | n | | Order | manifest is | 1379 | | | | | processed in a | 1380 | | | | | strictly linear | 1381 | | | | | fashion. Set to 0 | 1382 | | | | | to enable | 1383 | | | | | parallel handling | 1384 | | | | | of manifest | 1385 | | | | | directives. | 1386 | | | | | | 1387 | 2 | boolea | Command Segment | Soft | Condition | 1388 | | n | | Failure | failures only | 1389 | | | | | terminate the | 1390 | | | | | current command | 1391 | | | | | segment. | 1392 | | | | | | 1393 | 3 | bstr | Component/Global | Vendor ID | A RFC4122 UUID | 1394 | | | | | representing the | 1395 | | | | | vendor of the | 1396 | | | | | device or | 1397 | | | | | component | 1398 | | | | | | 1399 | 4 | bstr | Component/Global | Class ID | A RFC4122 UUID | 1400 | | | | | representing the | 1401 | | | | | class of the | 1402 | | | | | device or | 1403 | | | | | component | 1404 | | | | | | 1405 | 5 | bstr | Component/Global | Device ID | A RFC4122 UUID | 1406 | | | | | representing the | 1407 | | | | | device or | 1408 | | | | | component | 1409 | | | | | | 1410 | 6 | tstr | Component/Depende | URI | A URI from which | 1411 | | | ncy | | to fetch a | 1412 | | | | | resource | 1413 | | | | | | 1414 | 7 | bstr | Component/Depende | Encryption | A COSE object | 1415 | | | ncy | Info | defining the | 1416 | | | | | encryption mode | 1417 | | | | | of a resource | 1418 | | | | | | 1419 | 8 | bstr | Component | Compressio | The information | 1420 | | | | n Info | required to | 1421 | | | | | decompress the | 1422 | | | | | image | 1423 | | | | | | 1424 | 9 | bstr | Component | Unpack | The information | 1425 | | | | Info | required to | 1426 | | | | | unpack the image | 1427 | | | | | | 1428 | 10 | uint | Component | Source | A Component Index | 1429 | | | | Component | | 1430 | | | | | | 1431 | 11 | bstr | Component/Depende | Image | A SUIT_Digest | 1432 | | | ncy | Digest | | 1433 | | | | | | 1434 | 12 | uint | Component/Depende | Image Size | Integer size | 1435 | | | ncy | | | 1436 | | | | | | 1437 | 24 | bstr | Component/Depende | URI List | A CBOR encoded | 1438 | | | ncy | | list of ranked | 1439 | | | | | URIs | 1440 | | | | | | 1441 | 25 | boolea | Component/Depende | URI List | A CBOR encoded | 1442 | | n | ncy | Append | list of ranked | 1443 | | | | | URIs | 1444 | | | | | | 1445 | nin | int/bs | Custom | Custom | Application- | 1446 | t | tr | | Parameter | defined parameter | 1447 +-----+--------+-------------------+------------+-------------------+ 1449 CBOR-encoded object parameters are still wrapped in a bstr. This is 1450 because it allows a parser that is aggregating parameters to 1451 reference the object with a single pointer and traverse it without 1452 understanding the contents. This is important for modularization and 1453 division of responsibility within a pull parser. The same 1454 consideration does not apply to Conditions and Directives because 1455 those elements are invoked with their arguments immediately 1457 7.6.1. SUIT_Parameter_Strict_Order 1459 The Strict Order Parameter allows a manifest to govern when 1460 directives can be executed out-of-order. This allows for systems 1461 that have a sensitivity to order of updates to choose the order in 1462 which they are executed. It also allows for more advanced systems to 1463 parallelize their handling of updates. Strict Order defaults to 1464 True. It MAY be set to False when the order of operations does not 1465 matter. When arriving at the end of a command sequence, ALL commands 1466 MUST have completed, regardless of the state of 1467 SUIT_Parameter_Strict_Order. If SUIT_Parameter_Strict_Order is 1468 returned to True, ALL preceding commands MUST complete before the 1469 next command is executed. 1471 7.6.2. SUIT_Parameter_Soft_Failure 1473 When executing a command sequence inside SUIT_Directive_Try_Each and 1474 a condition failure occurs, the manifest processor aborts the 1475 sequence. If Soft Failure is True, it returns Success. Otherwise, 1476 it returns the original condition failure. 1477 SUIT_Parameter_Soft_Failure is scoped to the enclosing 1478 SUIT_Command_Sequence. Its value is discarded when 1479 SUIT_Command_Sequence terminates. 1481 7.7. SUIT_Parameter_Encryption_Info 1483 Encryption Info defines the mechanism that Fetch or Copy should use 1484 to decrypt the data they transfer. SUIT_Parameter_Encryption_Info is 1485 encoded as a COSE_Encrypt_Tagged or a COSE_Encrypt0_Tagged, wrapped 1486 in a bstr. 1488 7.7.1. SUIT_Parameter_Compression_Info 1490 Compression Info defines any information that is required for a 1491 device to perform decompression operations. Typically, this includes 1492 the algorithm identifier. 1494 SUIT_Parameter_Compression_Info is defined by the following CDDL: 1496 SUIT_Compression_Info = { 1497 suit-compression-algorithm => SUIT_Compression_Algorithms 1498 ? suit-compression-parameters => bstr 1499 } 1501 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_gzip 1502 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_bzip2 1503 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_deflate 1504 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_LZ4 1505 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_lzma 1507 7.7.2. SUIT_Parameter_Unpack_Info 1509 SUIT_Unpack_Info defines the information required for a device to 1510 interpret a packed format, such as elf, hex, or binary diff. 1511 SUIT_Unpack_Info is defined by the following CDDL: 1513 SUIT_Unpack_Info = { 1514 suit-unpack-algorithm => SUIT_Unpack_Algorithms 1515 ? suit-unpack-parameters => bstr 1516 } 1518 SUIT_Unpack_Algorithms //= SUIT_Unpack_Algorithm_Delta 1519 SUIT_Unpack_Algorithms //= SUIT_Unpack_Algorithm_Hex 1520 SUIT_Unpack_Algorithms //= SUIT_Unpack_Algorithm_Elf 1522 7.7.3. SUIT_Parameters CDDL 1524 The following CDDL describes all SUIT_Parameters. 1526 SUIT_Parameters //= (suit-parameter-strict-order => bool) 1527 SUIT_Parameters //= (suit-parameter-soft-failure => bool) 1528 SUIT_Parameters //= (suit-parameter-vendor-id => bstr) 1529 SUIT_Parameters //= (suit-parameter-class-id => bstr) 1530 SUIT_Parameters //= (suit-parameter-device-id => bstr) 1531 SUIT_Parameters //= (suit-parameter-uri => tstr) 1532 SUIT_Parameters //= (suit-parameter-encryption-info 1533 => bstr .cbor SUIT_Encryption_Info) 1534 SUIT_Parameters //= (suit-parameter-compression-info 1535 => bstr .cbor SUIT_Compression_Info) 1536 SUIT_Parameters //= (suit-parameter-unpack-info 1537 => bstr .cbor SUIT_Unpack_Info) 1538 SUIT_Parameters //= (suit-parameter-source-component 1539 => uint) 1540 SUIT_Parameters //= (suit-parameter-image-digest 1541 => bstr .cbor SUIT_Digest) 1542 SUIT_Parameters //= (suit-parameter-image-size => uint) 1543 SUIT_Parameters //= (suit-parameter-uri-list 1544 => bstr .cbor SUIT_Component_URI_List) 1545 SUIT_Parameters //= (suit-parameter-custom 1546 => int/bool/tstr/bstr) 1548 SUIT_Component_URI_List = [ + [priority: int, uri: tstr] ] 1550 SUIT_Encryption_Info= COSE_Encrypt_Tagged/COSE_Encrypt0_Tagged 1551 SUIT_Compression_Info = { 1552 suit-compression-algorithm => SUIT_Compression_Algorithms 1553 ? suit-compression-parameters => bstr 1554 } 1556 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_gzip 1557 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_bzip2 1558 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_deflate 1559 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_LZ4 1560 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_lzma 1562 SUIT_Unpack_Info = { 1563 suit-unpack-algorithm => SUIT_Unpack_Algorithms 1564 ? suit-unpack-parameters => bstr 1565 } 1567 SUIT_Unpack_Algorithms //= SUIT_Unpack_Algorithm_Delta 1568 SUIT_Unpack_Algorithms //= SUIT_Unpack_Algorithm_Hex 1569 SUIT_Unpack_Algorithms //= SUIT_Unpack_Algorithm_Elf 1571 7.8. SUIT_Command_Sequence 1573 A SUIT_Command_Sequence defines a series of actions that the 1574 Recipient MUST take to accomplish a particular goal. These goals are 1575 defined in the manifest and include: 1577 1. Dependency Resolution 1579 2. Payload Fetch 1581 3. Payload Installation 1583 4. Image Validation 1585 5. Image Loading 1587 6. Run or Boot 1589 Each of these follows exactly the same structure to ensure that the 1590 parser is as simple as possible. 1592 Lists of commands are constructed from two kinds of element: 1594 1. Conditions that MUST be true-any failure is treated as a failure 1595 of the update/load/boot 1597 2. Directives that MUST be executed. 1599 The lists of commands are logically structured into sequences of zero 1600 or more conditions followed by zero or more directives. The 1601 *logical* structure is described by the following CDDL: 1603 Command_Sequence = { 1604 conditions => [ * Condition], 1605 directives => [ * Directive] 1606 } 1608 This introduces significant complexity in the parser, however, so the 1609 structure is flattened to make parsing simpler: 1611 SUIT_Command_Sequence = [ + (SUIT_Condition/SUIT_Directive) ] 1613 Each condition and directive is composed of: 1615 1. A command code identifier 1617 2. An argument block 1618 Argument blocks are defined for each type of command. 1620 Many conditions and directives apply to a given component, and these 1621 generally grouped together. Therefore, a special command to set the 1622 current component index is provided with a matching command to set 1623 the current dependency index. This index is a numeric index into the 1624 component ID tables defined at the beginning of the document. For 1625 the purpose of setting the index, the two component ID tables are 1626 considered to be concatenated together. 1628 To facilitate optional conditions, a special directive is provided. 1629 It runs several new lists of conditions/directives, one after 1630 another, that are contained as an argument to the directive. By 1631 default, it assumes that a failure of a condition should not indicate 1632 a failure of the update/boot, but a parameter is provided to override 1633 this behavior. 1635 7.9. SUIT_Condition 1637 Conditions are used to define mandatory properties of a system in 1638 order for an update to be applied. They can be pre-conditions or 1639 post-conditions of any directive or series of directives, depending 1640 on where they are placed in the list. Conditions include: 1642 +----------------+-------------------+----------------------------+ 1643 | Condition Code | Condition Name | Argument Type | 1644 +----------------+-------------------+----------------------------+ 1645 | 1 | Vendor Identifier | nil | 1646 | | | | 1647 | 2 | Class Identifier | nil | 1648 | | | | 1649 | 3 | Image Match | nil | 1650 | | | | 1651 | 4 | Use Before | Unsigned Integer timestamp | 1652 | | | | 1653 | 5 | Component Offset | Unsigned Integer | 1654 | | | | 1655 | 24 | Device Identifier | nil | 1656 | | | | 1657 | 25 | Image Not Match | nil | 1658 | | | | 1659 | 26 | Minimum Battery | Unsigned Integer | 1660 | | | | 1661 | 27 | Update Authorized | Integer | 1662 | | | | 1663 | 28 | Version | List of Integers | 1664 | | | | 1665 | nint | Custom Condition | bstr | 1666 +----------------+-------------------+----------------------------+ 1668 Each condition MUST report a success code on completion. If a 1669 condition reports failure, then the current sequence of commands MUST 1670 terminate. If a Recipient encounters an unknown Condition Code, it 1671 MUST report a failure. 1673 Positive Condition numbers are reserved for IANA registration. 1674 Negative numbers are reserved for proprietary, application-specific 1675 directives. 1677 7.9.1. Identifier Conditions 1679 There are three identifier-based conditions: suit-condition-vendor- 1680 identifier, suit-condition-class-identifier, and suit-condition- 1681 device-identifier. Each of these conditions match a RFC 4122 1682 [RFC4122] UUID that MUST have already been set as a parameter. The 1683 installing device MUST match the specified UUID in order to consider 1684 the manifest valid. These identifiers MAY be scoped by component. 1686 The Recipient uses the ID parameter that has already been set using 1687 the Set Parameters directive. If no ID has been set, this condition 1688 fails. suit-condition-class-identifier and suit-condition-vendor- 1689 identifier are REQUIRED to implement. suit-condition-device- 1690 identifier is OPTIONAL to implement. 1692 7.9.2. suit-condition-image-match 1694 Verify that the current component matches the digest parameter for 1695 the current component. The digest is verified against the digest 1696 specified in the Component's parameters list. If no digest is 1697 specified, the condition fails. suit-condition-image-match is 1698 REQUIRED to implement. 1700 7.9.3. suit-condition-image-not-match 1702 Verify that the current component does not match the supplied digest. 1703 If no digest is specified, then the digest is compared against the 1704 digest specified in the Components list. If no digest is specified 1705 and the component is not present in the Components list, the 1706 condition fails. suit-condition-image-not-match is OPTIONAL to 1707 implement. 1709 7.9.4. suit-condition-use-before 1711 Verify that the current time is BEFORE the specified time. suit- 1712 condition-use-before is used to specify the last time at which an 1713 update should be installed. One argument is required, encoded as a 1714 POSIX timestamp, that is seconds after 1970-01-01 00:00:00. 1715 Timestamp conditions MUST be evaluated in 64 bits, regardless of 1716 encoded CBOR size. suit-condition-use-before is OPTIONAL to 1717 implement. 1719 7.9.5. suit-condition-minimum-battery 1721 suit-condition-minimum-battery provides a mechanism to test a 1722 device's battery level before installing an update. This condition 1723 is for use in primary-cell applications, where the battery is only 1724 ever discharged. For batteries that are charged, suit-directive-wait 1725 is more appropriate, since it defines a "wait" until the battery 1726 level is sufficient to install the update. suit-condition-minimum- 1727 battery is specified in mWh. suit-condition-minimum-battery is 1728 OPTIONAL to implement. 1730 7.9.6. suit-condition-update-authorized 1732 Request Authorization from the application and fail if not 1733 authorized. This can allow a user to decline an update. Argument is 1734 an integer priority level. Priorities are application defined. suit- 1735 condition-update-authorized is OPTIONAL to implement. 1737 7.9.7. suit-condition-version 1739 suit-condition-version allows comparing versions of firmware. 1740 Verifying image digests is preferred to version checks because 1741 digests are more precise. The image can be compared as: 1743 - Greater. 1745 - Greater or Equal. 1747 - Equal. 1749 - Lesser or Equal. 1751 - Lesser. 1753 Versions are encoded as a CBOR list of integers. Comparisons are 1754 done on each integer in sequence. Comparison stops after all 1755 integers in the list defined by the manifest have been consumed OR 1756 after a non-equal match has occurred. For example, if the manifest 1757 defines a comparison, "Equal [1]", then this will match all version 1758 sequences starting with 1. If a manifest defines both "Greater or 1759 Equal [1,0]" and "Lesser [1,10]", then it will match versions 1.0.x 1760 up to, but not including 1.10. 1762 The following CDDL describes SUIT_Condition_Version_Argument 1764 SUIT_Condition_Version_Argument = [ 1765 suit-condition-version-comparison-type: 1766 SUIT_Condition_Version_Comparison_Types, 1767 suit-condition-version-comparison-value: 1768 SUIT_Condition_Version_Comparison_Value 1769 ] 1771 SUIT_Condition_Version_Comparison_Types /= 1772 suit-condition-version-comparison-greater 1773 SUIT_Condition_Version_Comparison_Types /= 1774 suit-condition-version-comparison-greater-equal 1775 SUIT_Condition_Version_Comparison_Types /= 1776 suit-condition-version-comparison-equal 1777 SUIT_Condition_Version_Comparison_Types /= 1778 suit-condition-version-comparison-lesser-equal 1779 SUIT_Condition_Version_Comparison_Types /= 1780 suit-condition-version-comparison-lesser 1782 SUIT_Condition_Version_Comparison_Value = [+int] 1783 While the exact encoding of versions is application-defined, semantic 1784 versions map conveniently. For example, 1786 - 1.2.3 = [1,2,3]. 1788 - 1.2-rc3 = [1,2,-1,3]. 1790 - 1.2-beta = [1,2,-2]. 1792 - 1.2-alpha = [1,2,-3]. 1794 - 1.2-alpha4 = [1,2,-3,4]. 1796 suit-condition-version is OPTIONAL to implement. 1798 7.9.8. SUIT_Condition_Custom 1800 SUIT_Condition_Custom describes any proprietary, application specific 1801 condition. This is encoded as a negative integer, chosen by the 1802 firmware developer, and a bstr that encodes the parameters passed to 1803 the system that evaluates the condition matching that integer. 1804 SUIT_Condition_Custom is OPTIONAL to implement. 1806 7.9.9. Identifiers 1808 Many conditions use identifiers to determine whether a manifest 1809 matches a given Recipient or not. These identifiers are defined to 1810 be RFC 4122 [RFC4122] UUIDs. These UUIDs are explicitly NOT human- 1811 readable. They are for machine-based matching only. 1813 A device may match any number of UUIDs for vendor or class 1814 identifier. This may be relevant to physical or software modules. 1815 For example, a device that has an OS and one or more applications 1816 might list one Vendor ID for the OS and one or more additional Vendor 1817 IDs for the applications. This device might also have a Class ID 1818 that must be matched for the OS and one or more Class IDs for the 1819 applications. 1821 A more complete example: A device has the following physical 1822 components: 1. A host MCU 2. A WiFi module 1824 This same device has three software modules: 1. An operating system 1825 2. A WiFi module interface driver 3. An application 1827 Suppose that the WiFi module's firmware has a proprietary update 1828 mechanism and doesn't support manifest processing. This device can 1829 report four class IDs: 1831 1. hardware model/revision 1833 2. OS 1835 3. WiFi module model/revision 1837 4. Application 1839 This allows the OS, WiFi module, and application to be updated 1840 independently. To combat possible incompatibilities, the OS class ID 1841 can be changed each time the OS has a change to its API. 1843 This approach allows a vendor to target, for example, all devices 1844 with a particular WiFi module with an update, which is a very 1845 powerful mechanism, particularly when used for security updates. 1847 7.9.9.1. Creating UUIDs: 1849 UUIDs MUST be created according to RFC 4122 [RFC4122]. UUIDs SHOULD 1850 use versions 3, 4, or 5, as described in RFC4122. Versions 1 and 2 1851 do not provide a tangible benefit over version 4 for this 1852 application. 1854 The RECOMMENDED method to create a vendor ID is: Vendor ID = 1855 UUID5(DNS_PREFIX, vendor domain name) 1857 The RECOMMENDED method to create a class ID is: Class ID = 1858 UUID5(Vendor ID, Class-Specific-Information) 1860 Class-specific information is composed of a variety of data, for 1861 example: 1863 - Model number. 1865 - Hardware revision. 1867 - Bootloader version (for immutable bootloaders). 1869 7.9.10. SUIT_Condition CDDL 1871 The following CDDL describes SUIT_Condition: 1873 SUIT_Condition //= (suit-condition-vendor-identifier, nil) 1874 SUIT_Condition //= (suit-condition-class-identifier, nil) 1875 SUIT_Condition //= (suit-condition-device-identifier, nil) 1876 SUIT_Condition //= (suit-condition-image-match, nil) 1877 SUIT_Condition //= (suit-condition-image-not-match, nil) 1878 SUIT_Condition //= (suit-condition-use-before, uint) 1879 SUIT_Condition //= (suit-condition-minimum-battery, uint) 1880 SUIT_Condition //= (suit-condition-update-authorized, int) 1881 SUIT_Condition //= (suit-condition-version, 1882 SUIT_Condition_Version_Argument) 1883 SUIT_Condition //= (suit-condition-component-offset, uint) 1884 SUIT_Condition //= (suit-condition-custom, bstr) 1886 SUIT_Condition_Version_Argument = [ 1887 suit-condition-version-comparison-type: 1888 SUIT_Condition_Version_Comparison_Types, 1889 suit-condition-version-comparison-value: 1890 SUIT_Condition_Version_Comparison_Value 1891 ] 1893 SUIT_Condition_Version_Comparison_Types /= 1894 suit-condition-version-comparison-greater 1895 SUIT_Condition_Version_Comparison_Types /= 1896 suit-condition-version-comparison-greater-equal 1897 SUIT_Condition_Version_Comparison_Types /= 1898 suit-condition-version-comparison-equal 1899 SUIT_Condition_Version_Comparison_Types /= 1900 suit-condition-version-comparison-lesser-equal 1901 SUIT_Condition_Version_Comparison_Types /= 1902 suit-condition-version-comparison-lesser 1904 SUIT_Condition_Version_Comparison_Value = [+int] 1906 7.10. SUIT_Directive 1908 Directives are used to define the behavior of the recipient. 1909 Directives include: 1911 +----------------+----------------------+ 1912 | Directive Code | Directive Name | 1913 +----------------+----------------------+ 1914 | 12 | Set Component Index | 1915 | | | 1916 | 13 | Set Dependency Index | 1917 | | | 1918 | 14 | Abort | 1919 | | | 1920 | 15 | Try Each | 1921 | | | 1922 | 16 | Reserved | 1923 | | | 1924 | 17 | Reserved | 1925 | | | 1926 | 18 | Process Dependency | 1927 | | | 1928 | 19 | Set Parameters | 1929 | | | 1930 | 20 | Override Parameters | 1931 | | | 1932 | 21 | Fetch | 1933 | | | 1934 | 22 | Copy | 1935 | | | 1936 | 23 | Run | 1937 | | | 1938 | 29 | Wait | 1939 | | | 1940 | 30 | Run Sequence | 1941 | | | 1942 | 31 | Run with Arguments | 1943 | | | 1944 | 32 | Swap | 1945 +----------------+----------------------+ 1947 When a Recipient executes a Directive, it MUST report a success code. 1948 If the Directive reports failure, then the current Command Sequence 1949 MUST terminate. 1951 7.10.1. suit-directive-set-component-index 1953 Set Component Index defines the component to which successive 1954 directives and conditions will apply. The supplied argument MUST be 1955 either a boolean or an unsigned integer index into the concatenation 1956 of suit-components and suit-dependency-components. If the following 1957 directives apply to ALL components, then the boolean value "True" is 1958 used instead of an index. True does not apply to dependency 1959 components. If the following directives apply to NO components, then 1960 the boolean value "False" is used. When suit-directive-set- 1961 dependency-index is used, suit-directive-set-component-index = False 1962 is implied. When suit-directive-set-component-index is used, suit- 1963 directive-set-dependency-index = False is implied. 1965 The following CDDL describes the argument to suit-directive-set- 1966 component-index. 1968 SUIT_Directive_Set_Component_Index_Argument = uint/bool 1970 7.10.2. suit-directive-set-dependency-index 1972 Set Dependency Index defines the manifest to which successive 1973 directives and conditions will apply. The supplied argument MUST be 1974 either a boolean or an unsigned integer index into the dependencies. 1975 If the following directives apply to ALL dependencies, then the 1976 boolean value "True" is used instead of an index. If the following 1977 directives apply to NO dependencies, then the boolean value "False" 1978 is used. When suit-directive-set-component-index is used, suit- 1979 directive-set-dependency-index = False is implied. When suit- 1980 directive-set-dependency-index is used, suit-directive-set-component- 1981 index = False is implied. 1983 Typical operations that require suit-directive-set-dependency-index 1984 include setting a source URI, invoking "Fetch," or invoking "Process 1985 Dependency" for an individual dependency. 1987 The following CDDL describes the argument to suit-directive-set- 1988 dependency-index. 1990 SUIT_Directive_Set_Manifest_Index_Argument = uint/bool 1992 7.10.3. suit-directive-abort 1994 Unconditionally fail. This operation is typically used in 1995 conjunction with suit-directive-try-each. 1997 7.10.4. suit-directive-run-sequence 1999 To enable conditional commands, and to allow several strictly ordered 2000 sequences to be executed out-of-order, suit-directive-run-sequence 2001 allows the manifest processor to execute its argument as a 2002 SUIT_Command_Sequence. The argument must be wrapped in a bstr. 2004 When a sequence is executed, any failure of a condition causes 2005 immediate termination of the sequence. 2007 The following CDDL describes the SUIT_Run_Sequence argument. 2009 SUIT_Directive_Run_Sequence_Argument = bstr .cbor SUIT_Command_Sequence 2011 When suit-directive-run-sequence completes, it forwards the last 2012 status code that occurred in the sequence. If the Soft Failure 2013 parameter is true, then suit-directive-run-sequence only fails when a 2014 directive in the argument sequence fails. 2016 SUIT_Parameter_Soft_Failure defaults to False when suit-directive- 2017 run-sequence begins. Its value is discarded when suit-directive-run- 2018 sequence terminates. 2020 7.10.5. suit-directive-try-each 2022 This command runs several SUIT_Command_Sequence, one after another, 2023 in a strict order. Use this command to implement a "try/catch-try/ 2024 catch" sequence. Manifest processors MAY implement this command. 2026 SUIT_Parameter_Soft_Failure is initialized to True at the beginning 2027 of each sequence. If one sequence aborts due to a condition failure, 2028 the next is started. If no sequence completes without condition 2029 failure, then suit-directive-try-each returns an error. If a 2030 particular application calls for all sequences to fail and still 2031 continue, then an empty sequence (nil) can be added to the Try Each 2032 Argument. 2034 The following CDDL describes the SUIT_Try_Each argument. 2036 SUIT_Directive_Try_Each_Argument = [ 2037 + bstr .cbor SUIT_Command_Sequence, 2038 nil / bstr .cbor SUIT_Command_Sequence 2039 ] 2041 7.10.6. suit-directive-process-dependency 2043 Execute the commands in the common section of the current dependency, 2044 followed by the commands in the equivalent section of the current 2045 dependency. For example, if the current section is "fetch payload," 2046 this will execute "common" in the current dependency, then "fetch 2047 payload" in the current dependency. Once this is complete, the 2048 command following suit-directive-process-dependency will be 2049 processed. 2051 If the current dependency is False, this directive has no effect. If 2052 the current dependency is True, then this directive applies to all 2053 dependencies. If the current section is "common," this directive 2054 MUST have no effect. 2056 When SUIT_Process_Dependency completes, it forwards the last status 2057 code that occurred in the dependency. 2059 The argument to suit-directive-process-dependency is defined in the 2060 following CDDL. 2062 SUIT_Directive_Process_Dependency_Argument = nil 2064 7.10.7. suit-directive-set-parameters 2066 suit-directive-set-parameters allows the manifest to configure 2067 behavior of future directives by changing parameters that are read by 2068 those directives. When dependencies are used, suit-directive-set- 2069 parameters also allows a manifest to modify the behavior of its 2070 dependencies. 2072 Available parameters are defined in Section 7.6. 2074 If a parameter is already set, suit-directive-set-parameters will 2075 skip setting the parameter to its argument. This provides the core 2076 of the override mechanism, allowing dependent manifests to change the 2077 behavior of a manifest. 2079 The argument to suit-directive-set-parameters is defined in the 2080 following CDDL. 2082 SUIT_Directive_Set_Parameters_Argument = {+ SUIT_Parameters} 2084 N.B.: A directive code is reserved for an optimization: a way to set 2085 a parameter to the contents of another parameter, optionally with 2086 another component ID. 2088 7.10.8. suit-directive-override-parameters 2090 suit-directive-override-parameters replaces any listed parameters 2091 that are already set with the values that are provided in its 2092 argument. This allows a manifest to prevent replacement of critical 2093 parameters. 2095 Available parameters are defined in Section 7.6. 2097 The argument to suit-directive-override-parameters is defined in the 2098 following CDDL. 2100 SUIT_Directive_Override_Parameters_Argument = {+ SUIT_Parameters} 2102 7.10.9. suit-directive-fetch 2104 suit-directive-fetch instructs the manifest processor to obtain one 2105 or more manifests or payloads, as specified by the manifest index and 2106 component index, respectively. 2108 suit-directive-fetch can target one or more manifests and one or more 2109 payloads. suit-directive-fetch retrieves each component and each 2110 manifest listed in component-index and manifest-index, respectively. 2111 If component-index or manifest-index is True, instead of an integer, 2112 then all current manifest components/manifests are fetched. The 2113 current manifest's dependent-components are not automatically 2114 fetched. In order to pre-fetch these, they MUST be specified in a 2115 component-index integer. 2117 suit-directive-fetch typically takes no arguments unless one is 2118 needed to modify fetch behavior. If an argument is needed, it must 2119 be wrapped in a bstr. 2121 suit-directive-fetch reads the URI or URI List parameter to find the 2122 source of the fetch it performs. 2124 The behavior of suit-directive-fetch can be modified by setting one 2125 or more of SUIT_Parameter_Encryption_Info, 2126 SUIT_Parameter_Compression_Info, SUIT_Parameter_Unpack_Info. These 2127 three parameters each activate and configure a processing step that 2128 can be applied to the data that is transferred during suit-directive- 2129 fetch. 2131 The argument to suit-directive-fetch is defined in the following 2132 CDDL. 2134 SUIT_Directive_Fetch_Argument = nil/bstr 2136 7.10.10. suit-directive-copy 2138 suit-directive-copy instructs the manifest processor to obtain one or 2139 more payloads, as specified by the component index. suit-directive- 2140 copy retrieves each component listed in component-index, 2141 respectively. If component-index is True, instead of an integer, 2142 then all current manifest components are copied. The current 2143 manifest's dependent-components are not automatically copied. In 2144 order to copy these, they MUST be specified in a component-index 2145 integer. 2147 The behavior of suit-directive-copy can be modified by setting one or 2148 more of SUIT_Parameter_Encryption_Info, 2149 SUIT_Parameter_Compression_Info, SUIT_Parameter_Unpack_Info. These 2150 three parameters each activate and configure a processing step that 2151 can be applied to the data that is transferred during suit-directive- 2152 copy. 2154 *N.B.* Fetch and Copy are very similar. Merging them into one 2155 command may be appropriate. 2157 suit-directive-copy reads its source from 2158 SUIT_Parameter_Source_Component. 2160 The argument to suit-directive-copy is defined in the following CDDL. 2162 SUIT_Directive_Copy_Argument = nil 2164 7.10.11. suit-directive-swap 2166 suit-directive-swap instructs the manifest processor to move the 2167 source to the destination and the destination to the source 2168 simultaneously. Swap has nearly identical semantics to suit- 2169 directive-copy except that suit-directive-swap replaces the source 2170 with the current contents of the destination in an application- 2171 defined way. If SUIT_Parameter_Compression_Info or 2172 SUIT_Parameter_Encryption_Info are present, they must be handled in a 2173 symmetric way, so that the source is decompressed into the 2174 destination and the destination is compressed into the source. The 2175 source is decrypted into the destination and the destination is 2176 encrypted into the source. suit-directive-swap is OPTIONAL to 2177 implement. 2179 7.10.12. suit-directive-run 2181 suit-directive-run directs the manifest processor to transfer 2182 execution to the current Component Index. When this is invoked, the 2183 manifest processor MAY be unloaded and execution continues in the 2184 Component Index. Arguments provided to Run are forwarded to the 2185 executable code located in Component Index, in an application- 2186 specific way. For example, this could form the Linux Kernel Command 2187 Line if booting a Linux device. 2189 If the executable code at Component Index is constructed in such a 2190 way that it does not unload the manifest processor, then the manifest 2191 processor may resume execution after the executable completes. This 2192 allows the manifest processor to invoke suitable helpers and to 2193 verify them with image conditions. 2195 The argument to suit-directive-run is defined in the following CDDL. 2197 SUIT_Directive_Run_Argument = nil/bstr 2199 7.10.13. suit-directive-wait 2201 suit-directive-wait directs the manifest processor to pause until a 2202 specified event occurs. Some possible events include: 2204 1. Authorization 2206 2. External Power 2208 3. Network availability 2210 4. Other Device Firmware Version 2212 5. Time 2214 6. Time of Day 2216 7. Day of Week 2218 The following CDDL defines the encoding of these events. 2220 SUIT_Wait_Events //= (suit-wait-event-authorization => int) 2221 SUIT_Wait_Events //= (suit-wait-event-power => int) 2222 SUIT_Wait_Events //= (suit-wait-event-network => int) 2223 SUIT_Wait_Events //= (suit-wait-event-other-device-version 2224 => SUIT_Wait_Event_Argument_Other_Device_Version) 2225 SUIT_Wait_Events //= (suit-wait-event-time => uint); Timestamp 2226 SUIT_Wait_Events //= (suit-wait-event-time-of-day 2227 => uint); Time of Day (seconds since 00:00:00) 2228 SUIT_Wait_Events //= (suit-wait-event-day-of-week 2229 => uint); Days since Sunday 2231 SUIT_Wait_Event_Argument_Authorization = int ; priority 2232 SUIT_Wait_Event_Argument_Power = int ; Power Level 2233 SUIT_Wait_Event_Argument_Network = int ; Network State 2234 SUIT_Wait_Event_Argument_Other_Device_Version = [ 2235 other-device: bstr, 2236 other-device-version: [+int] 2237 ] 2238 SUIT_Wait_Event_Argument_Time = uint ; Timestamp 2239 SUIT_Wait_Event_Argument_Time_Of_Day = uint ; Time of Day 2240 ; (seconds since 00:00:00) 2241 SUIT_Wait_Event_Argument_Day_Of_Week = uint ; Days since Sunday 2243 7.10.14. SUIT_Directive CDDL 2245 The following CDDL describes SUIT_Directive: 2247 SUIT_Directive //= (suit-directive-set-component-index, uint/bool) 2248 SUIT_Directive //= (suit-directive-set-dependency-index, uint/bool) 2249 SUIT_Directive //= (suit-directive-run-sequence, 2250 bstr .cbor SUIT_Command_Sequence) 2251 SUIT_Directive //= (suit-directive-try-each, 2252 SUIT_Directive_Try_Each_Argument) 2253 SUIT_Directive //= (suit-directive-process-dependency, nil) 2254 SUIT_Directive //= (suit-directive-set-parameters, 2255 {+ SUIT_Parameters}) 2256 SUIT_Directive //= (suit-directive-override-parameters, 2257 {+ SUIT_Parameters}) 2258 SUIT_Directive //= (suit-directive-fetch, nil) 2259 SUIT_Directive //= (suit-directive-copy, nil) 2260 SUIT_Directive //= (suit-directive-run, nil) 2261 SUIT_Directive //= (suit-directive-wait, 2262 { + SUIT_Wait_Events }) 2263 SUIT_Directive //= (suit-directive-run-with-arguments, bstr) 2265 SUIT_Directive_Try_Each_Argument = [ 2266 + bstr .cbor SUIT_Command_Sequence, 2267 nil / bstr .cbor SUIT_Command_Sequence 2268 ] 2270 SUIT_Wait_Events //= (suit-wait-event-authorization => int) 2271 SUIT_Wait_Events //= (suit-wait-event-power => int) 2272 SUIT_Wait_Events //= (suit-wait-event-network => int) 2273 SUIT_Wait_Events //= (suit-wait-event-other-device-version 2274 => SUIT_Wait_Event_Argument_Other_Device_Version) 2275 SUIT_Wait_Events //= (suit-wait-event-time => uint); Timestamp 2276 SUIT_Wait_Events //= (suit-wait-event-time-of-day 2277 => uint); Time of Day (seconds since 00:00:00) 2278 SUIT_Wait_Events //= (suit-wait-event-day-of-week 2279 => uint); Days since Sunday 2281 SUIT_Wait_Event_Argument_Authorization = int ; priority 2282 SUIT_Wait_Event_Argument_Power = int ; Power Level 2283 SUIT_Wait_Event_Argument_Network = int ; Network State 2284 SUIT_Wait_Event_Argument_Other_Device_Version = [ 2285 other-device: bstr, 2286 other-device-version: [+int] 2287 ] 2288 SUIT_Wait_Event_Argument_Time = uint ; Timestamp 2289 SUIT_Wait_Event_Argument_Time_Of_Day = uint ; Time of Day 2290 ; (seconds since 00:00:00) 2291 SUIT_Wait_Event_Argument_Day_Of_Week = uint ; Days since Sunday 2293 7.11. SUIT_Text_Map 2295 The SUIT_Text_Map contains all text descriptions needed for this 2296 manifest. The text section is typically severable, allowing 2297 manifests to be distributed without the text, since end-nodes do not 2298 require text. The meaning of each field is described below. 2300 Each section MAY be present. If present, each section MUST be as 2301 described. Negative integer IDs are reserved for application- 2302 specific text values. 2304 +----+-----------------------+--------------------------------------+ 2305 | ID | Name | Summary | 2306 +----+-----------------------+--------------------------------------+ 2307 | 1 | manifest-description | Free text description of the | 2308 | | | manifest | 2309 | | | | 2310 | 2 | update-description | Free text description of the update | 2311 | | | | 2312 | 3 | vendor-name | Free text vendor name | 2313 | | | | 2314 | 4 | model-name | Free text model name | 2315 | | | | 2316 | 5 | vendor-domain | The domain used to create the | 2317 | | | vendor-id (Section 7.9.9.1) | 2318 | | | | 2319 | 6 | model-info | The information used to create the | 2320 | | | class-id (Section 7.9.9.1) | 2321 | | | | 2322 | 7 | component-description | Free text description of each | 2323 | | | component in the manifest | 2324 | | | | 2325 | 8 | json-source | The JSON-formatted document that was | 2326 | | | used to create the manifest | 2327 | | | | 2328 | 9 | yaml-source | The yaml-formatted document that was | 2329 | | | used to create the manifest | 2330 | | | | 2331 | 10 | version-dependencies | List of component versions required | 2332 | | | by the manifest | 2333 +----+-----------------------+--------------------------------------+ 2335 8. Access Control Lists 2337 To manage permissions in the manifest, there are three models that 2338 can be used. 2340 First, the simplest model requires that all manifests are 2341 authenticated by a single trusted key. This mode has the advantage 2342 that only a root manifest needs to be authenticated, since all of its 2343 dependencies have digests included in the root manifest. 2345 This simplest model can be extended by adding key delegation without 2346 much increase in complexity. 2348 A second model requires an ACL to be presented to the device, 2349 authenticated by a trusted party or stored on the device. This ACL 2350 grants access rights for specific component IDs or component ID 2351 prefixes to the listed identities or identity groups. Any identity 2352 may verify an image digest, but fetching into or fetching from a 2353 component ID requires approval from the ACL. 2355 A third model allows a device to provide even more fine-grained 2356 controls: The ACL lists the component ID or component ID prefix that 2357 an identity may use, and also lists the commands that the identity 2358 may use in combination with that component ID. 2360 9. SUIT digest container 2362 RFC 8152 [RFC8152] provides containers for signature, MAC, and 2363 encryption, but no basic digest container. The container needed for 2364 a digest requires a type identifier and a container for the raw 2365 digest data. Some forms of digest may require additional parameters. 2366 These can be added following the digest. This structure is described 2367 by the following CDDL. 2369 The algorithms listed are sufficient for verifying integrity of 2370 Firmware Updates as of this writing, however this may change over 2371 time. 2373 SUIT_Digest = [ 2374 suit-digest-algorithm-id : $suit-digest-algorithm-ids, 2375 suit-digest-bytes : bytes, 2376 ? suit-digest-parameters : any 2377 ] 2379 digest-algorithm-ids /= algorithm-id-sha224 2380 digest-algorithm-ids /= algorithm-id-sha256 2381 digest-algorithm-ids /= algorithm-id-sha384 2382 digest-algorithm-ids /= algorithm-id-sha512 2383 digest-algorithm-ids /= algorithm-id-sha3-224 2384 digest-algorithm-ids /= algorithm-id-sha3-256 2385 digest-algorithm-ids /= algorithm-id-sha3-384 2386 digest-algorithm-ids /= algorithm-id-sha3-512 2388 algorithm-id-sha224 = 1 2389 algorithm-id-sha256 = 2 2390 algorithm-id-sha384 = 3 2391 algorithm-id-sha512 = 4 2392 algorithm-id-sha3-224 = 5 2393 algorithm-id-sha3-256 = 6 2394 algorithm-id-sha3-384 = 7 2395 algorithm-id-sha3-512 = 8 2397 10. Creating Conditional Sequences 2399 For some use cases, it is important to provide a sequence that can 2400 fail without terminating an update. For example, a dual-image XIP 2401 MCU may require an update that can be placed at one of two offsets. 2402 This has two implications, first, the digest of each offset will be 2403 different. Second, the image fetched for each offset will have a 2404 different URI. Conditional sequences allow this to be resolved in a 2405 simple way. 2407 The following JSON representation of a manifest demonstrates how this 2408 would be represented. It assumes that the bootloader and manifest 2409 processor take care of A/B switching and that the manifest is not 2410 aware of this distinction. 2412 { 2413 "structure-version" : 1, 2414 "sequence-number" : 7, 2415 "common" :{ 2416 "components" : [ 2417 [b'0'] 2418 ], 2419 "common-sequence" : [ 2420 { 2421 "directive-set-var" : { 2422 "size": 32567 2423 }, 2424 }, 2425 { 2426 "try-each" : [ 2427 [ 2428 {"condition-component-offset" : ""}, 2429 { 2430 "directive-set-var": { 2431 "digest" : "" 2432 } 2433 } 2434 ], 2435 [ 2436 {"condition-component-offset" : ""}, 2437 { 2438 "directive-set-var": { 2439 "digest" : "" 2440 } 2441 } 2442 ], 2443 [{ "abort" : null }] 2444 ] 2445 } 2446 ] 2447 } 2448 "fetch" : [ 2449 { 2450 "try-each" : [ 2451 [ 2452 {"condition-component-offset" : ""}, 2453 { 2454 "directive-set-var": { 2455 "uri" : "" 2456 } 2457 } 2458 ], 2459 [ 2460 {"condition-component-offset" : ""}, 2461 { 2462 "directive-set-var": { 2463 "uri" : "" 2464 } 2465 } 2466 ], 2467 [{ "directive-abort" : null }] 2468 ] 2470 }, 2471 "fetch" : null 2472 ] 2473 } 2475 11. Full CDDL 2477 In order to create a valid SUIT Manifest document the structure of 2478 the corresponding CBOR message MUST adhere to the following CDDL data 2479 definition. 2481 SUIT_Outer_Wrapper = { 2482 suit-delegation => bstr .cbor SUIT_Delegation 2483 suit-authentication-wrapper 2484 => bstr .cbor SUIT_Authentication_Wrapper / nil, 2485 $$SUIT_Manifest_Wrapped, 2486 suit-dependency-resolution => bstr .cbor SUIT_Command_Sequence, 2487 suit-payload-fetch => bstr .cbor SUIT_Command_Sequence, 2488 suit-install => bstr .cbor SUIT_Command_Sequence, 2489 suit-text => bstr .cbor SUIT_Text_Map, 2490 suit-coswid => bstr .cbor concise-software-identity 2491 } 2493 SUIT_Authentication_Wrapper = [ + ( 2494 COSE_Mac_Tagged / 2495 COSE_Sign_Tagged / 2496 COSE_Mac0_Tagged / 2497 COSE_Sign1_Tagged) 2498 ] 2500 SUIT_Encryption_Wrapper = COSE_Encrypt_Tagged / COSE_Encrypt0_Tagged 2502 $$SUIT_Manifest_Wrapped //= (suit-manifest => bstr .cbor SUIT_Manifest) 2503 $$SUIT_Manifest_Wrapped //= ( 2504 suit-manifest-encryption-info => bstr .cbor SUIT_Encryption_Wrapper, 2505 suit-manifest-encrypted => bstr 2506 ) 2508 COSE_Mac_Tagged = any 2509 COSE_Sign_Tagged = any 2510 COSE_Mac0_Tagged = any 2511 COSE_Sign1_Tagged = any 2512 COSE_Encrypt_Tagged = any 2513 COSE_Encrypt0_Tagged = any 2515 SUIT_Digest = [ 2516 suit-digest-algorithm-id : $suit-digest-algorithm-ids, 2517 suit-digest-bytes : bstr, 2518 ? suit-digest-parameters : any 2519 ] 2521 ; Named Information Hash Algorithm Identifiers 2522 suit-digest-algorithm-ids /= algorithm-id-sha224 2523 suit-digest-algorithm-ids /= algorithm-id-sha256 2524 suit-digest-algorithm-ids /= algorithm-id-sha384 2525 suit-digest-algorithm-ids /= algorithm-id-sha512 2526 suit-digest-algorithm-ids /= algorithm-id-sha3-224 2527 suit-digest-algorithm-ids /= algorithm-id-sha3-256 2528 suit-digest-algorithm-ids /= algorithm-id-sha3-384 2529 suit-digest-algorithm-ids /= algorithm-id-sha3-512 2531 algorithm-id-sha224 = 1 2532 algorithm-id-sha256 = 2 2533 algorithm-id-sha384 = 3 2534 algorithm-id-sha512 = 4 2535 algorithm-id-sha3-224 = 5 2536 algorithm-id-sha3-256 = 6 2537 algorithm-id-sha3-384 = 7 2538 algorithm-id-sha3-512 = 8 2540 SUIT_Manifest = { 2541 suit-manifest-version => 1, 2542 suit-manifest-sequence-number => uint, 2543 ? suit-common => bstr .cbor SUIT_Common, 2544 ? suit-dependency-resolution 2545 => SUIT_Digest / bstr .cbor SUIT_Command_Sequence, 2546 ? suit-payload-fetch 2547 => SUIT_Digest / bstr .cbor SUIT_Command_Sequence, 2548 ? suit-install 2549 => SUIT_Digest / bstr .cbor SUIT_Command_Sequence, 2550 ? suit-validate => bstr .cbor SUIT_Command_Sequence, 2551 ? suit-load => bstr .cbor SUIT_Command_Sequence, 2552 ? suit-run => bstr .cbor SUIT_Command_Sequence, 2553 ? suit-text => SUIT_Digest, 2554 ? suit-coswid 2555 => SUIT_Digest / bstr .cbor concise-software-identity, 2556 } 2558 SUIT_Common = { 2559 ? suit-dependencies => bstr .cbor SUIT_Dependencies, 2560 ? suit-components => bstr .cbor SUIT_Components, 2561 ? suit-dependency-components 2562 => bstr .cbor SUIT_Component_References, 2563 ? suit-common-sequence => bstr .cbor SUIT_Command_Sequence, 2564 } 2565 SUIT_Dependencies = [ + SUIT_Dependency ] 2566 SUIT_Components = [ + SUIT_Component_Identifier ] 2567 SUIT_Component_References = [ + SUIT_Component_Reference ] 2569 concise-software-identity = any 2571 SUIT_Dependency = { 2572 suit-dependency-digest => SUIT_Digest, 2573 suit-dependency-prefix => SUIT_Component_Identifier, 2574 } 2576 SUIT_Component_Identifier = [* bstr] 2578 SUIT_Component_Reference = { 2579 suit-component-identifier => SUIT_Component_Identifier, 2580 suit-component-dependency-index => uint 2581 } 2583 SUIT_Command_Sequence = [ + ( 2584 SUIT_Condition // SUIT_Directive // SUIT_Command_Custom 2585 ) ] 2587 SUIT_Command_Custom = (nint, bstr) 2588 SUIT_Condition //= (suit-condition-vendor-identifier, nil) 2589 SUIT_Condition //= (suit-condition-class-identifier, nil) 2590 SUIT_Condition //= (suit-condition-device-identifier, nil) 2591 SUIT_Condition //= (suit-condition-image-match, nil) 2592 SUIT_Condition //= (suit-condition-image-not-match, nil) 2593 SUIT_Condition //= (suit-condition-use-before, uint) 2594 SUIT_Condition //= (suit-condition-minimum-battery, uint) 2595 SUIT_Condition //= (suit-condition-update-authorized, int) 2596 SUIT_Condition //= (suit-condition-version, 2597 SUIT_Condition_Version_Argument) 2598 SUIT_Condition //= (suit-condition-component-offset, uint) 2599 SUIT_Condition //= (suit-condition-custom, bstr) 2601 RFC4122_UUID = bstr .size 16 2603 SUIT_Condition_Version_Argument = [ 2604 suit-condition-version-comparison-type: 2605 SUIT_Condition_Version_Comparison_Types, 2606 suit-condition-version-comparison-value: 2607 SUIT_Condition_Version_Comparison_Value 2608 ] 2609 SUIT_Condition_Version_Comparison_Types /= 2610 suit-condition-version-comparison-greater 2612 SUIT_Condition_Version_Comparison_Types /= 2613 suit-condition-version-comparison-greater-equal 2614 SUIT_Condition_Version_Comparison_Types /= 2615 suit-condition-version-comparison-equal 2616 SUIT_Condition_Version_Comparison_Types /= 2617 suit-condition-version-comparison-lesser-equal 2618 SUIT_Condition_Version_Comparison_Types /= 2619 suit-condition-version-comparison-lesser 2621 suit-condition-version-comparison-greater = 1 2622 suit-condition-version-comparison-greater-equal = 2 2623 suit-condition-version-comparison-equal = 3 2624 suit-condition-version-comparison-lesser-equal = 4 2625 suit-condition-version-comparison-lesser = 5 2627 SUIT_Condition_Version_Comparison_Value = [+int] 2629 SUIT_Directive //= (suit-directive-set-component-index, uint/bool) 2630 SUIT_Directive //= (suit-directive-set-dependency-index, uint/bool) 2631 SUIT_Directive //= (suit-directive-run-sequence, 2632 bstr .cbor SUIT_Command_Sequence) 2633 SUIT_Directive //= (suit-directive-try-each, 2634 SUIT_Directive_Try_Each_Argument) 2635 SUIT_Directive //= (suit-directive-process-dependency, nil) 2636 SUIT_Directive //= (suit-directive-set-parameters, 2637 {+ SUIT_Parameters}) 2638 SUIT_Directive //= (suit-directive-override-parameters, 2639 {+ SUIT_Parameters}) 2640 SUIT_Directive //= (suit-directive-fetch, nil) 2641 SUIT_Directive //= (suit-directive-copy, nil) 2642 SUIT_Directive //= (suit-directive-swap, nil) 2643 SUIT_Directive //= (suit-directive-run, nil) 2644 SUIT_Directive //= (suit-directive-wait, 2645 { + SUIT_Wait_Events }) 2646 SUIT_Directive //= (suit-directive-run-with-arguments, bstr) 2648 SUIT_Directive_Try_Each_Argument = [ 2649 + bstr .cbor SUIT_Command_Sequence, 2650 nil / bstr .cbor SUIT_Command_Sequence 2651 ] 2653 SUIT_Wait_Events //= (suit-wait-event-authorization => int) 2654 SUIT_Wait_Events //= (suit-wait-event-power => int) 2655 SUIT_Wait_Events //= (suit-wait-event-network => int) 2656 SUIT_Wait_Events //= (suit-wait-event-other-device-version 2657 => SUIT_Wait_Event_Argument_Other_Device_Version) 2658 SUIT_Wait_Events //= (suit-wait-event-time => uint); Timestamp 2659 SUIT_Wait_Events //= (suit-wait-event-time-of-day 2660 => uint); Time of Day (seconds since 00:00:00) 2661 SUIT_Wait_Events //= (suit-wait-event-day-of-week 2662 => uint); Days since Sunday 2664 SUIT_Wait_Event_Argument_Authorization = int ; priority 2665 SUIT_Wait_Event_Argument_Power = int ; Power Level 2666 SUIT_Wait_Event_Argument_Network = int ; Network State 2667 SUIT_Wait_Event_Argument_Other_Device_Version = [ 2668 other-device: bstr, 2669 other-device-version: [+int] 2670 ] 2671 SUIT_Wait_Event_Argument_Time = uint ; Timestamp 2672 SUIT_Wait_Event_Argument_Time_Of_Day = uint ; Time of Day 2673 ; (seconds since 00:00:00) 2674 SUIT_Wait_Event_Argument_Day_Of_Week = uint ; Days since Sunday 2676 SUIT_Parameters //= (suit-parameter-strict-order => bool) 2677 SUIT_Parameters //= (suit-parameter-soft-failure => bool) 2678 SUIT_Parameters //= (suit-parameter-vendor-id => bstr) 2679 SUIT_Parameters //= (suit-parameter-class-id => bstr) 2680 SUIT_Parameters //= (suit-parameter-device-id => bstr) 2681 SUIT_Parameters //= (suit-parameter-uri => tstr) 2682 SUIT_Parameters //= (suit-parameter-encryption-info 2683 => bstr .cbor SUIT_Encryption_Info) 2684 SUIT_Parameters //= (suit-parameter-compression-info 2685 => bstr .cbor SUIT_Compression_Info) 2686 SUIT_Parameters //= (suit-parameter-unpack-info 2687 => bstr .cbor SUIT_Unpack_Info) 2688 SUIT_Parameters //= (suit-parameter-source-component => uint) 2689 SUIT_Parameters //= (suit-parameter-image-digest 2690 => bstr .cbor SUIT_Digest) 2691 SUIT_Parameters //= (suit-parameter-image-size => uint) 2692 SUIT_Parameters //= (suit-parameter-uri-list 2693 => bstr .cbor SUIT_Component_URI_List) 2694 SUIT_Parameters //= (suit-parameter-custom => int/bool/tstr/bstr) 2696 SUIT_Component_URI_List = [ + [priority: int, uri: tstr] ] 2698 SUIT_Encryption_Info = COSE_Encrypt_Tagged/COSE_Encrypt0_Tagged 2699 SUIT_Compression_Info = { 2700 suit-compression-algorithm => SUIT_Compression_Algorithms, 2701 ? suit-compression-parameters => bstr 2702 } 2704 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_gzip 2705 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_bzip2 2706 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_lz4 2707 SUIT_Compression_Algorithms /= SUIT_Compression_Algorithm_lzma 2709 SUIT_Compression_Algorithm_gzip = 1 2710 SUIT_Compression_Algorithm_bzip2 = 2 2711 SUIT_Compression_Algorithm_deflate = 3 2712 SUIT_Compression_Algorithm_lz4 = 4 2713 SUIT_Compression_Algorithm_lzma = 7 2715 SUIT_Unpack_Info = { 2716 suit-unpack-algorithm => SUIT_Unpack_Algorithms, 2717 ? suit-unpack-parameters => bstr 2718 } 2720 SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Delta 2721 SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Hex 2722 SUIT_Unpack_Algorithms /= SUIT_Unpack_Algorithm_Elf 2724 SUIT_Unpack_Algorithm_Delta = 1 2725 SUIT_Unpack_Algorithm_Hex = 2 2726 SUIT_Unpack_Algorithm_Elf = 3 2728 SUIT_Text_Map = {int => tstr} 2730 suit-authentication-wrapper = 1 2731 suit-manifest = 2 2733 suit-manifest-encryption-info = 3 2734 suit-manifest-encrypted = 4 2736 suit-manifest-version = 1 2737 suit-manifest-sequence-number = 2 2738 suit-common = 3 2739 suit-dependency-resolution = 7 2740 suit-payload-fetch = 8 2741 suit-install = 9 2742 suit-validate = 10 2743 suit-load = 11 2744 suit-run = 12 2745 suit-text = 13 2746 suit-coswid = 14 2748 suit-dependencies = 1 2749 suit-components = 2 2750 suit-dependency-components = 3 2751 suit-common-sequence = 4 2753 suit-dependency-digest = 1 2754 suit-dependency-prefix = 2 2755 suit-component-identifier = 1 2756 suit-component-dependency-index = 2 2758 suit-command-custom = nint 2760 suit-condition-vendor-identifier = 1 2761 suit-condition-class-identifier = 2 2762 suit-condition-image-match = 3 2763 suit-condition-use-before = 4 2764 suit-condition-component-offset = 5 2765 suit-condition-custom = 6 2767 suit-condition-device-identifier = 24 2768 suit-condition-image-not-match = 25 2769 suit-condition-minimum-battery = 26 2770 suit-condition-update-authorized = 27 2771 suit-condition-version = 28 2773 suit-directive-set-component-index = 12 2774 suit-directive-set-dependency-index = 13 2775 suit-directive-abort = 14 2776 suit-directive-try-each = 15 2777 ;suit-directive-do-each = 16 ; TBD 2778 ;suit-directive-map-filter = 17 ; TBD 2779 suit-directive-process-dependency = 18 2780 suit-directive-set-parameters = 19 2781 suit-directive-override-parameters = 20 2782 suit-directive-fetch = 21 2783 suit-directive-copy = 22 2784 suit-directive-run = 23 2786 suit-directive-wait = 29 2787 suit-directive-run-sequence = 30 2788 suit-directive-run-with-arguments = 31 2789 suit-directive-swap = 32 2791 suit-wait-event-argument-authorization = 1 2792 suit-wait-event-power = 2 2793 suit-wait-event-network = 3 2794 suit-wait-event-other-device-version = 4 2795 suit-wait-event-time = 5 2796 suit-wait-event-time-of-day = 6 2797 suit-wait-event-day-of-week = 7 2798 suit-wait-event-authorization = 8 2800 suit-parameter-strict-order = 1 2801 suit-parameter-soft-failure = 2 2802 suit-parameter-vendor-id = 3 2803 suit-parameter-class-id = 4 2804 suit-parameter-device-id = 5 2805 suit-parameter-uri = 6 2806 suit-parameter-encryption-info = 7 2807 suit-parameter-compression-info = 8 2808 suit-parameter-unpack-info = 9 2809 suit-parameter-source-component = 10 2810 suit-parameter-image-digest = 11 2811 suit-parameter-image-size = 12 2813 suit-parameter-uri-list = 24 2814 suit-parameter-uri-list-append = 25 2815 suit-parameter-prioritized-parameters = 26 2817 suit-parameter-custom = nint 2819 suit-compression-algorithm = 1 2820 suit-compression-parameters = 2 2822 suit-unpack-algorithm = 1 2823 suit-unpack-parameters = 2 2825 suit-text-manifest-description = 1 2826 suit-text-update-description = 2 2827 suit-text-vendor-name = 3 2828 suit-text-model-name = 4 2829 suit-text-vendor-domain = 5 2830 suit-text-model-info = 6 2831 suit-text-component-description = 7 2832 suit-text-manifest-json-source = 8 2833 suit-text-manifest-yaml-source = 9 2834 suit-text-version-dependencies = 10 2836 12. Examples 2838 The following examples demonstrate a small subset of the 2839 functionality of the manifest. However, despite this, even a simple 2840 manifest processor can execute most of these manifests. 2842 The examples are signed using the following ECDSA secp256r1 key: 2844 -----BEGIN PRIVATE KEY----- 2845 MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgApZYjZCUGLM50VBC 2846 CjYStX+09jGmnyJPrpDLTz/hiXOhRANCAASEloEarguqq9JhVxie7NomvqqL8Rtv 2847 P+bitWWchdvArTsfKktsCYExwKNtrNHXi9OB3N+wnAUtszmR23M4tKiW 2848 -----END PRIVATE KEY----- 2850 The corresponding public key can be used to verify these examples: 2852 -----BEGIN PUBLIC KEY----- 2853 MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEhJaBGq4LqqvSYVcYnuzaJr6qi/Eb 2854 bz/m4rVlnIXbwK07HypLbAmBMcCjbazR14vTgdzfsJwFLbM5kdtzOLSolg== 2855 -----END PUBLIC KEY----- 2857 12.1. Example 0: Secure Boot 2859 Secure boot and compatibility check. 2861 { 2862 / authentication-wrapper / 2:h'81d28443a10126a058248202582073054c8 2863 cc42e3e76c974ad0bed685d88b0b99df40fbaf72f58cd0b97dcd03285584057bc22b81 2864 43137abb3e8dc180a74348b58905d36ac16c199443cd1d09214a68bd4acdbbde78a521 2865 7768faa00627a0a92da30f36bd2187f77ba14b16b0637c618' / [ 2866 18([ 2867 / protected / h'a10126' / { 2868 / alg / 1:-7 / ES256 /, 2869 } /, 2870 / unprotected / { 2871 }, 2872 / payload / h'8202582073054c8cc42e3e76c974ad0bed685d88 2873 b0b99df40fbaf72f58cd0b97dcd03285' / [ 2874 / algorithm-id / 2 / sha256 /, 2875 / digest-bytes / 2876 h'73054c8cc42e3e76c974ad0bed685d88b0b99df40fbaf72f58cd0b97dcd03285' 2877 ] /, 2878 / signature / h'57bc22b8143137abb3e8dc180a74348b58905d 2879 36ac16c199443cd1d09214a68bd4acdbbde78a5217768faa00627a0a92da30f36bd218 2880 7f77ba14b16b0637c618' 2881 ]) 2882 ] /, 2883 / manifest / 3:h'a50101020103585aa2024481814100045850860150fa6b4a5 2884 3d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab4514a20b820 2885 2582000112233445566778899aabbccddeeff0123456789abcdeffedcba98765432100 2886 c1987d00a438203f60c438217f6' / { 2887 / manifest-version / 1:1, 2888 / manifest-sequence-number / 2:1, 2889 / common / 3:h'a2024481814100045850860150fa6b4a53d5ad5fdfbe9de 2890 663e4d41ffe02501492af1425695e48bf429b2d51f2ab4514a20b82025820001122334 2891 45566778899aabbccddeeff0123456789abcdeffedcba98765432100c1987d0' / { 2892 / components / 2:h'81814100' / [ 2893 [h'00'] 2894 ] /, 2895 / common-sequence / 4:h'860150fa6b4a53d5ad5fdfbe9de663e4d4 2896 1ffe02501492af1425695e48bf429b2d51f2ab4514a20b820258200011223344556677 2897 8899aabbccddeeff0123456789abcdeffedcba98765432100c1987d0' / [ 2898 / condition-vendor-identifier / 2899 1,h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 2900 be9d-e663e4d41ffe / , 2901 / condition-class-identifier / 2902 2,h'1492af1425695e48bf429b2d51f2ab45' / 2903 1492af14-2569-5e48-bf42-9b2d51f2ab45 / , 2904 / directive-override-parameters / 20,{ 2905 / image-digest / 11:[ 2906 / algorithm-id / 2 / sha256 /, 2907 / digest-bytes / 2908 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 2909 ], 2910 / image-size / 12:34768, 2911 } 2912 ] /, 2913 } /, 2914 / validate / 10:h'8203f6' / [ 2915 / condition-image-match / 3,F6 / nil / 2916 ] /, 2917 / run / 12:h'8217f6' / [ 2918 / directive-run / 23,None 2919 ] /, 2920 } /, 2921 } 2923 Total size of manifest without COSE authentication object: 112 2925 Manifest: 2927 a103586ca50101020103585aa2024481814100045850860150fa6b4a53d5 2928 ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab4514 2929 a20b8202582000112233445566778899aabbccddeeff0123456789abcdef 2930 fedcba98765432100c1987d00a438203f60c438217f6 2932 Total size of manifest with COSE authentication object: 227 2934 Manifest with COSE authentication object: 2936 a202587081d28443a10126a058248202582073054c8cc42e3e76c974ad0b 2937 ed685d88b0b99df40fbaf72f58cd0b97dcd03285584057bc22b8143137ab 2938 b3e8dc180a74348b58905d36ac16c199443cd1d09214a68bd4acdbbde78a 2939 5217768faa00627a0a92da30f36bd2187f77ba14b16b0637c61803586ca5 2940 0101020103585aa2024481814100045850860150fa6b4a53d5ad5fdfbe9d 2941 e663e4d41ffe02501492af1425695e48bf429b2d51f2ab4514a20b820258 2942 2000112233445566778899aabbccddeeff0123456789abcdeffedcba9876 2943 5432100c1987d00a438203f60c438217f6 2945 12.2. Example 1: Simultaneous Download and Installation of Payload 2947 Simultaneous download and installation of payload. 2949 { 2950 / authentication-wrapper / 2:h'81d28443a10126a0582482025820be9d3da 2951 5d45b780bcaeb84a909b54913302a358d9d7dc6b94c7fbb1f56dbf5f95840d89fb4194 2952 4231adb3920bdae14a4965699771b50e062c28ffef93400a9b63150902bc65929e8066 2953 e1a0eb45be50ee96db0435e5c141ae8fb94cbf2b37205ba6b' / [ 2954 18([ 2955 / protected / h'a10126' / { 2956 / alg / 1:-7 / ES256 /, 2957 } /, 2958 / unprotected / { 2959 }, 2960 / payload / h'82025820be9d3da5d45b780bcaeb84a909b54913 2961 302a358d9d7dc6b94c7fbb1f56dbf5f9' / [ 2962 / algorithm-id / 2 / sha256 /, 2963 / digest-bytes / 2964 h'be9d3da5d45b780bcaeb84a909b54913302a358d9d7dc6b94c7fbb1f56dbf5f9' 2965 ] /, 2966 / signature / h'd89fb41944231adb3920bdae14a4965699771b 2967 50e062c28ffef93400a9b63150902bc65929e8066e1a0eb45be50ee96db0435e5c141a 2968 e8fb94cbf2b37205ba6b' 2969 ]) 2970 ] /, 2971 / manifest / 3:h'a40101020203585aa2024481814100045850860150fa6b4a5 2972 3d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab4514a20b820 2973 2582000112233445566778899aabbccddeeff0123456789abcdeffedcba98765432100 2974 c1987d00958258613a106781b687474703a2f2f6578616d706c652e636f6d2f66696c6 2975 52e62696e15f603f6' / { 2976 / manifest-version / 1:1, 2977 / manifest-sequence-number / 2:2, 2978 / common / 3:h'a2024481814100045850860150fa6b4a53d5ad5fdfbe9de 2979 663e4d41ffe02501492af1425695e48bf429b2d51f2ab4514a20b82025820001122334 2980 45566778899aabbccddeeff0123456789abcdeffedcba98765432100c1987d0' / { 2981 / components / 2:h'81814100' / [ 2982 [h'00'] 2983 ] /, 2984 / common-sequence / 4:h'860150fa6b4a53d5ad5fdfbe9de663e4d4 2985 1ffe02501492af1425695e48bf429b2d51f2ab4514a20b820258200011223344556677 2986 8899aabbccddeeff0123456789abcdeffedcba98765432100c1987d0' / [ 2987 / condition-vendor-identifier / 2988 1,h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 2989 be9d-e663e4d41ffe / , 2990 / condition-class-identifier / 2991 2,h'1492af1425695e48bf429b2d51f2ab45' / 2992 1492af14-2569-5e48-bf42-9b2d51f2ab45 / , 2993 / directive-override-parameters / 20,{ 2994 / image-digest / 11:[ 2995 / algorithm-id / 2 / sha256 /, 2996 / digest-bytes / 2997 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 2998 ], 2999 / image-size / 12:34768, 3000 } 3001 ] /, 3002 } /, 3003 / install / 9:h'8613a106781b687474703a2f2f6578616d706c652e636f 3004 6d2f66696c652e62696e15f603f6' / [ 3005 / directive-set-parameters / 19,{ 3006 / uri / 6:'http://example.com/file.bin', 3007 } , 3008 / directive-fetch / 21,F6 / nil / , 3009 / condition-image-match / 3,F6 / nil / 3010 ] /, 3011 } /, 3012 } 3014 Total size of manifest without COSE authentication object: 142 3016 Manifest: 3018 a103588aa40101020203585aa2024481814100045850860150fa6b4a53d5 3019 ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab4514 3020 a20b8202582000112233445566778899aabbccddeeff0123456789abcdef 3021 fedcba98765432100c1987d00958258613a106781b687474703a2f2f6578 3022 616d706c652e636f6d2f66696c652e62696e15f603f6 3024 Total size of manifest with COSE authentication object: 257 3026 Manifest with COSE authentication object: 3028 a202587081d28443a10126a0582482025820be9d3da5d45b780bcaeb84a9 3029 09b54913302a358d9d7dc6b94c7fbb1f56dbf5f95840d89fb41944231adb 3030 3920bdae14a4965699771b50e062c28ffef93400a9b63150902bc65929e8 3031 066e1a0eb45be50ee96db0435e5c141ae8fb94cbf2b37205ba6b03588aa4 3032 0101020203585aa2024481814100045850860150fa6b4a53d5ad5fdfbe9d 3033 e663e4d41ffe02501492af1425695e48bf429b2d51f2ab4514a20b820258 3034 2000112233445566778899aabbccddeeff0123456789abcdeffedcba9876 3035 5432100c1987d00958258613a106781b687474703a2f2f6578616d706c65 3036 2e636f6d2f66696c652e62696e15f603f6 3038 12.3. Example 2: Simultaneous Download, Installation, and Secure Boot 3040 Compatibility test, simultaneous download and installation, and 3041 secure boot. ~~~ { / authentication-wrapper / 3042 2:h'81d28443a10126a058248202582070cf2a4 fed640658ada6ff33b59af192ca22 3043 b4142e9ae9d8d9b05f2b5a118cf35840f6c95681e f4298dc1288e11004a4b72be80a 3044 374be13efccf5ec94fa1ad2ca7d5510d5ff43ceac60 3045 e7dd32d3614bd0350768f985eff8ba9933625d206286cf983' / [ 18([ / 3046 protected / h'a10126' / { / alg / 1:-7 / ES256 /, } /, / unprotected 3047 / { }, / payload / h'8202582070cf2a4fed640658ada6ff33b59af192 3048 ca22b4142e9ae9d8d9b05f2b5a118cf3' / [ / algorithm-id / 2 / sha256 /, 3049 / digest-bytes / 3050 h'70cf2a4fed640658ada6ff33b59af192ca22b4142e9ae9d8d9b05f2b5a118cf3' ] 3051 /, / signature / h'f6c95681ef4298dc1288e11004a4b72be80a37 4be13efccf5 3052 ec94fa1ad2ca7d5510d5ff43ceac60e7dd32d3614bd0350768f985eff8b 3053 a9933625d206286cf983' ]) ] /, / manifest / 3054 3:h'a60101020303585aa2024481814100045850860150fa6b4a5 3d5ad5fdfbe9de6 3055 63e4d41ffe02501492af1425695e48bf429b2d51f2ab4514a20b820 2582000112233 3056 445566778899aabbccddeeff0123456789abcdeffedcba98765432100 c1987d00958 3057 258613a106781b687474703a2f2f6578616d706c652e636f6d2f66696c6 3058 52e62696e15f603f60a438203f60c438217f6' / { / manifest-version / 1:1, 3059 / manifest-sequence-number / 2:3, / common / 3060 3:h'a2024481814100045850860150fa6b4a53d5ad5fdfbe9de 663e4d41ffe025014 3061 92af1425695e48bf429b2d51f2ab4514a20b82025820001122334 3062 45566778899aabbccddeeff0123456789abcdeffedcba98765432100c1987d0' / { 3063 / components / 2:h'81814100' / [ [h'00'] ] /, / common-sequence / 3064 4:h'860150fa6b4a53d5ad5fdfbe9de663e4d4 1ffe02501492af1425695e48bf429b 3065 2d51f2ab4514a20b820258200011223344556677 3066 8899aabbccddeeff0123456789abcdeffedcba98765432100c1987d0' / [ / 3067 condition-vendor-identifier / 1,h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / 3068 fa6b4a53-d5ad-5fdf- be9d-e663e4d41ffe / , / condition-class- 3069 identifier / 2,h'1492af1425695e48bf429b2d51f2ab45' / 3070 1492af14-2569-5e48-bf42-9b2d51f2ab45 / , / directive-override- 3071 parameters / 20,{ / image-digest / 11:[ / algorithm-id / 2 / sha256 3072 /, / digest-bytes / 3073 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 3074 ], / image-size / 12:34768, } ] /, } /, / install / 3075 9:h'8613a106781b687474703a2f2f6578616d706c652e636f 3076 6d2f66696c652e62696e15f603f6' / [ / directive-set-parameters / 19,{ / 3077 uri / 6:'http://example.com/file.bin', } , / directive-fetch / 21,F6 3078 / nil / , / condition-image-match / 3,F6 / nil / ] /, / validate / 3079 10:h'8203f6' / [ / condition-image-match / 3,F6 / nil / ] /, / run / 3080 12:h'8217f6' / [ / directive-run / 23,None ] /, } /, } ~~~ 3082 Total size of manifest without COSE authentication object: 152 3084 Manifest: 3086 a1035894a60101020303585aa2024481814100045850860150fa6b4a53d5 3087 ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab4514 3088 a20b8202582000112233445566778899aabbccddeeff0123456789abcdef 3089 fedcba98765432100c1987d00958258613a106781b687474703a2f2f6578 3090 616d706c652e636f6d2f66696c652e62696e15f603f60a438203f60c4382 3091 17f6 3093 Total size of manifest with COSE authentication object: 267 3095 Manifest with COSE authentication object: 3097 a202587081d28443a10126a058248202582070cf2a4fed640658ada6ff33 3098 b59af192ca22b4142e9ae9d8d9b05f2b5a118cf35840f6c95681ef4298dc 3099 1288e11004a4b72be80a374be13efccf5ec94fa1ad2ca7d5510d5ff43cea 3100 c60e7dd32d3614bd0350768f985eff8ba9933625d206286cf983035894a6 3101 0101020303585aa2024481814100045850860150fa6b4a53d5ad5fdfbe9d 3102 e663e4d41ffe02501492af1425695e48bf429b2d51f2ab4514a20b820258 3103 2000112233445566778899aabbccddeeff0123456789abcdeffedcba9876 3104 5432100c1987d00958258613a106781b687474703a2f2f6578616d706c65 3105 2e636f6d2f66696c652e62696e15f603f60a438203f60c438217f6 3107 12.4. Example 3: Load from External Storage 3109 Compatibility test, simultaneous download and installation, load from 3110 external storage, and secure boot. 3112 { 3113 / authentication-wrapper / 2:h'81d28443a10126a0582482025820bb008f5 3114 7fd1babff8cc432d18c4c9cfc69d7e8ab76b07cc910c6d03ec598baab58409e98c58fc 3115 d82668443a0249fa5eab10474a099572dfb31c0d2adf750f57c4987d484badf8524a20 3116 a9e92c4599698eb696254d4c0f77947c8af353b544600ea11' / [ 3117 18([ 3118 / protected / h'a10126' / { 3119 / alg / 1:-7 / ES256 /, 3120 } /, 3121 / unprotected / { 3122 }, 3123 / payload / h'82025820bb008f57fd1babff8cc432d18c4c9cfc 3124 69d7e8ab76b07cc910c6d03ec598baab' / [ 3125 / algorithm-id / 2 / sha256 /, 3126 / digest-bytes / 3127 h'bb008f57fd1babff8cc432d18c4c9cfc69d7e8ab76b07cc910c6d03ec598baab' 3128 ] /, 3129 / signature / h'9e98c58fcd82668443a0249fa5eab10474a099 3130 572dfb31c0d2adf750f57c4987d484badf8524a20a9e92c4599698eb696254d4c0f779 3131 47c8af353b544600ea11' 3132 ]) 3133 ] /, 3134 / manifest / 3:h'a70101020403585fa2024782814100814101045852880c000 3135 150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab4 3136 514a20b8202582000112233445566778899aabbccddeeff0123456789abcdeffedcba9 3137 8765432100c1987d0095827880c0013a106781b687474703a2f2f6578616d706c652e6 3138 36f6d2f66696c652e62696e15f603f60a45840c0003f60b5834880c0114a30a000b820 3139 2582000112233445566778899aabbccddeeff0123456789abcdeffedcba98765432100 3140 c1987d016f603f60c45840c0117f6' / { 3141 / manifest-version / 1:1, 3142 / manifest-sequence-number / 2:4, 3143 / common / 3:h'a2024782814100814101045852880c000150fa6b4a53d5a 3144 d5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab4514a20b8202582 3145 000112233445566778899aabbccddeeff0123456789abcdeffedcba98765432100c198 3146 7d0' / { 3147 / components / 2:h'82814100814101' / [ 3148 [h'00'] , 3149 [h'01'] 3150 ] /, 3151 / common-sequence / 4:h'880c000150fa6b4a53d5ad5fdfbe9de663 3152 e4d41ffe02501492af1425695e48bf429b2d51f2ab4514a20b82025820001122334455 3153 66778899aabbccddeeff0123456789abcdeffedcba98765432100c1987d0' / [ 3154 / directive-set-component-index / 12,0 , 3155 / condition-vendor-identifier / 3156 1,h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 3157 be9d-e663e4d41ffe / , 3158 / condition-class-identifier / 3159 2,h'1492af1425695e48bf429b2d51f2ab45' / 3160 1492af14-2569-5e48-bf42-9b2d51f2ab45 / , 3161 / directive-override-parameters / 20,{ 3162 / image-digest / 11:[ 3163 / algorithm-id / 2 / sha256 /, 3164 / digest-bytes / 3165 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 3166 ], 3167 / image-size / 12:34768, 3168 } 3169 ] /, 3170 } /, 3171 / install / 9:h'880c0013a106781b687474703a2f2f6578616d706c652e 3172 636f6d2f66696c652e62696e15f603f6' / [ 3173 / directive-set-component-index / 12,0 , 3174 / directive-set-parameters / 19,{ 3175 / uri / 6:'http://example.com/file.bin', 3176 } , 3177 / directive-fetch / 21,F6 / nil / , 3178 / condition-image-match / 3,F6 / nil / 3179 ] /, 3180 / validate / 10:h'840c0003f6' / [ 3181 / directive-set-component-index / 12,0 , 3182 / condition-image-match / 3,F6 / nil / 3183 ] /, 3184 / load / 11:h'880c0114a30a000b8202582000112233445566778899aabb 3185 ccddeeff0123456789abcdeffedcba98765432100c1987d016f603f6' / [ 3186 / directive-set-component-index / 12,1 , 3187 / directive-override-parameters / 20,{ 3188 / image-digest / 11:[ 3189 / algorithm-id / 2 / sha256 /, 3190 / digest-bytes / 3191 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 3192 ], 3193 / image-size / 12:34768, 3194 / source-component / 10:0 / [h'00'] /, 3195 } , 3196 / directive-copy / 22,None , 3197 / condition-image-match / 3,F6 / nil / 3198 ] /, 3199 / run / 12:h'840c0117f6' / [ 3200 / directive-set-component-index / 12,1 , 3201 / directive-run / 23,None 3202 ] /, 3203 } /, 3204 } 3206 Total size of manifest without COSE authentication object: 218 3208 Manifest: 3210 a10358d6a70101020403585fa2024782814100814101045852880c000150 3211 fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d 3212 51f2ab4514a20b8202582000112233445566778899aabbccddeeff012345 3213 6789abcdeffedcba98765432100c1987d0095827880c0013a106781b6874 3214 74703a2f2f6578616d706c652e636f6d2f66696c652e62696e15f603f60a 3215 45840c0003f60b5834880c0114a30a000b82025820001122334455667788 3216 99aabbccddeeff0123456789abcdeffedcba98765432100c1987d016f603 3217 f60c45840c0117f6 3219 Total size of manifest with COSE authentication object: 333 3221 Manifest with COSE authentication object: 3223 a202587081d28443a10126a0582482025820bb008f57fd1babff8cc432d1 3224 8c4c9cfc69d7e8ab76b07cc910c6d03ec598baab58409e98c58fcd826684 3225 43a0249fa5eab10474a099572dfb31c0d2adf750f57c4987d484badf8524 3226 a20a9e92c4599698eb696254d4c0f77947c8af353b544600ea110358d6a7 3227 0101020403585fa2024782814100814101045852880c000150fa6b4a53d5 3228 ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab4514 3229 a20b8202582000112233445566778899aabbccddeeff0123456789abcdef 3230 fedcba98765432100c1987d0095827880c0013a106781b687474703a2f2f 3231 6578616d706c652e636f6d2f66696c652e62696e15f603f60a45840c0003 3232 f60b5834880c0114a30a000b8202582000112233445566778899aabbccdd 3233 eeff0123456789abcdeffedcba98765432100c1987d016f603f60c45840c 3234 0117f6 3236 12.5. Example 4: Load and Decompress from External Storage 3238 Compatibility test, simultaneous download and installation, load and 3239 decompress from external storage, and secure boot. 3241 { 3242 / authentication-wrapper / 2:h'81d28443a10126a0582482025820b973e24 3243 24d03de20c59cb702607a83796dd465674115ae84b3c2c472794dbb8c5840be0ae3d36 3244 0e46dd07f02547ff19e4a1557b7bfce401718ade8200918f191a50dca84148704f76d9 3245 7a8c239615114eab0617e9fc9d4faeac1572e7cae61e660c1' / [ 3246 18([ 3247 / protected / h'a10126' / { 3248 / alg / 1:-7 / ES256 /, 3249 } /, 3250 / unprotected / { 3251 }, 3252 / payload / h'82025820b973e2424d03de20c59cb702607a8379 3253 6dd465674115ae84b3c2c472794dbb8c' / [ 3254 / algorithm-id / 2 / sha256 /, 3255 / digest-bytes / 3256 h'b973e2424d03de20c59cb702607a83796dd465674115ae84b3c2c472794dbb8c' 3257 ] /, 3258 / signature / h'be0ae3d360e46dd07f02547ff19e4a1557b7bf 3259 ce401718ade8200918f191a50dca84148704f76d97a8c239615114eab0617e9fc9d4fa 3260 eac1572e7cae61e660c1' 3261 ]) 3262 ] /, 3263 / manifest / 3:h'a70101020503585fa2024782814100814101045852880c000 3264 150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab4 3265 514a20b8202582000112233445566778899aabbccddeeff0123456789abcdeffedcba9 3266 8765432100c1987d0095827880c0013a106781b687474703a2f2f6578616d706c652e6 3267 36f6d2f66696c652e62696e15f603f60a45840c0003f60b5836880c0114a408010a000 3268 b8202582000112233445566778899aabbccddeeff0123456789abcdeffedcba9876543 3269 2100c1987d016f603f60c45840c0117f6' / { 3270 / manifest-version / 1:1, 3271 / manifest-sequence-number / 2:5, 3272 / common / 3:h'a2024782814100814101045852880c000150fa6b4a53d5a 3273 d5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab4514a20b8202582 3274 000112233445566778899aabbccddeeff0123456789abcdeffedcba98765432100c198 3275 7d0' / { 3276 / components / 2:h'82814100814101' / [ 3277 [h'00'] , 3278 [h'01'] 3279 ] /, 3280 / common-sequence / 4:h'880c000150fa6b4a53d5ad5fdfbe9de663 3281 e4d41ffe02501492af1425695e48bf429b2d51f2ab4514a20b82025820001122334455 3282 66778899aabbccddeeff0123456789abcdeffedcba98765432100c1987d0' / [ 3283 / directive-set-component-index / 12,0 , 3284 / condition-vendor-identifier / 3285 1,h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 3286 be9d-e663e4d41ffe / , 3287 / condition-class-identifier / 3288 2,h'1492af1425695e48bf429b2d51f2ab45' / 3289 1492af14-2569-5e48-bf42-9b2d51f2ab45 / , 3290 / directive-override-parameters / 20,{ 3291 / image-digest / 11:[ 3292 / algorithm-id / 2 / sha256 /, 3293 / digest-bytes / 3294 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 3295 ], 3296 / image-size / 12:34768, 3297 } 3298 ] /, 3299 } /, 3300 / install / 9:h'880c0013a106781b687474703a2f2f6578616d706c652e 3301 636f6d2f66696c652e62696e15f603f6' / [ 3302 / directive-set-component-index / 12,0 , 3303 / directive-set-parameters / 19,{ 3304 / uri / 6:'http://example.com/file.bin', 3305 } , 3306 / directive-fetch / 21,F6 / nil / , 3307 / condition-image-match / 3,F6 / nil / 3308 ] /, 3309 / validate / 10:h'840c0003f6' / [ 3310 / directive-set-component-index / 12,0 , 3311 / condition-image-match / 3,F6 / nil / 3312 ] /, 3313 / load / 11:h'880c0114a408010a000b8202582000112233445566778899 3314 aabbccddeeff0123456789abcdeffedcba98765432100c1987d016f603f6' / [ 3315 / directive-set-component-index / 12,1 , 3316 / directive-override-parameters / 20,{ 3317 / image-digest / 11:[ 3318 / algorithm-id / 2 / sha256 /, 3319 / digest-bytes / 3320 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 3321 ], 3322 / image-size / 12:34768, 3323 / source-component / 10:0 / [h'00'] /, 3324 / compression-info / 8:1 / gzip /, 3325 } , 3326 / directive-copy / 22,None , 3327 / condition-image-match / 3,F6 / nil / 3328 ] /, 3329 / run / 12:h'840c0117f6' / [ 3330 / directive-set-component-index / 12,1 , 3331 / directive-run / 23,None 3332 ] /, 3333 } /, 3334 } 3336 Total size of manifest without COSE authentication object: 220 3338 Manifest: 3340 a10358d8a70101020503585fa2024782814100814101045852880c000150 3341 fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d 3342 51f2ab4514a20b8202582000112233445566778899aabbccddeeff012345 3343 6789abcdeffedcba98765432100c1987d0095827880c0013a106781b6874 3344 74703a2f2f6578616d706c652e636f6d2f66696c652e62696e15f603f60a 3345 45840c0003f60b5836880c0114a408010a000b8202582000112233445566 3346 778899aabbccddeeff0123456789abcdeffedcba98765432100c1987d016 3347 f603f60c45840c0117f6 3349 Total size of manifest with COSE authentication object: 335 3351 Manifest with COSE authentication object: 3353 a202587081d28443a10126a0582482025820b973e2424d03de20c59cb702 3354 607a83796dd465674115ae84b3c2c472794dbb8c5840be0ae3d360e46dd0 3355 7f02547ff19e4a1557b7bfce401718ade8200918f191a50dca84148704f7 3356 6d97a8c239615114eab0617e9fc9d4faeac1572e7cae61e660c10358d8a7 3357 0101020503585fa2024782814100814101045852880c000150fa6b4a53d5 3358 ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab4514 3359 a20b8202582000112233445566778899aabbccddeeff0123456789abcdef 3360 fedcba98765432100c1987d0095827880c0013a106781b687474703a2f2f 3361 6578616d706c652e636f6d2f66696c652e62696e15f603f60a45840c0003 3362 f60b5836880c0114a408010a000b8202582000112233445566778899aabb 3363 ccddeeff0123456789abcdeffedcba98765432100c1987d016f603f60c45 3364 840c0117f6 3366 12.6. Example 5: Compatibility Test, Download, Installation, and Secure 3367 Boot 3369 Compatibility test, download, installation, and secure boot. 3371 { 3372 / authentication-wrapper / 2:h'81d28443a10126a05824820258207f35fdc 3373 e6a55bed88d04497d38b7c2b4ffd1ddb74a83d9acd252d2077637de7058407bec97551 3374 827d684ac07b77c3f663f4f9436aff0b79fdfd89061bfe9bddb73919c88d32dc52fd9e 3375 b1d1ea34172eef5c222e7d897778c6b0254e20c7e87942ae1' / [ 3376 18([ 3377 / protected / h'a10126' / { 3378 / alg / 1:-7 / ES256 /, 3379 } /, 3380 / unprotected / { 3381 }, 3382 / payload / h'820258207f35fdce6a55bed88d04497d38b7c2b4 3383 ffd1ddb74a83d9acd252d2077637de70' / [ 3384 / algorithm-id / 2 / sha256 /, 3385 / digest-bytes / 3386 h'7f35fdce6a55bed88d04497d38b7c2b4ffd1ddb74a83d9acd252d2077637de70' 3387 ] /, 3388 / signature / h'7bec97551827d684ac07b77c3f663f4f9436af 3389 f0b79fdfd89061bfe9bddb73919c88d32dc52fd9eb1d1ea34172eef5c222e7d897778c 3390 6b0254e20c7e87942ae1' 3391 ]) 3392 ] /, 3393 / manifest / 3:h'a70101020503585fa2024782814100814101045852880c000 3394 150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab4 3395 514a20b8202582000112233445566778899aabbccddeeff0123456789abcdeffedcba9 3396 8765432100c1987d008584c880c0113a206781b687474703a2f2f6578616d706c652e6 3397 36f6d2f66696c652e62696e0b8202582000112233445566778899aabbccddeeff01234 3398 56789abcdeffedcba987654321015f603f6094d8a0c0013a10a0116f60c0103f60a458 3399 40c0003f60c45840c0017f6' / { 3400 / manifest-version / 1:1, 3401 / manifest-sequence-number / 2:5, 3402 / common / 3:h'a2024782814100814101045852880c000150fa6b4a53d5a 3403 d5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab4514a20b8202582 3404 000112233445566778899aabbccddeeff0123456789abcdeffedcba98765432100c198 3405 7d0' / { 3406 / components / 2:h'82814100814101' / [ 3407 [h'00'] , 3408 [h'01'] 3409 ] /, 3410 / common-sequence / 4:h'880c000150fa6b4a53d5ad5fdfbe9de663 3411 e4d41ffe02501492af1425695e48bf429b2d51f2ab4514a20b82025820001122334455 3412 66778899aabbccddeeff0123456789abcdeffedcba98765432100c1987d0' / [ 3413 / directive-set-component-index / 12,0 , 3414 / condition-vendor-identifier / 3415 1,h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 3416 be9d-e663e4d41ffe / , 3417 / condition-class-identifier / 3418 2,h'1492af1425695e48bf429b2d51f2ab45' / 3419 1492af14-2569-5e48-bf42-9b2d51f2ab45 / , 3420 / directive-override-parameters / 20,{ 3421 / image-digest / 11:[ 3422 / algorithm-id / 2 / sha256 /, 3423 / digest-bytes / 3424 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 3425 ], 3426 / image-size / 12:34768, 3427 } 3428 ] /, 3429 } /, 3430 / payload-fetch / 8:h'880c0113a206781b687474703a2f2f6578616d70 3431 6c652e636f6d2f66696c652e62696e0b8202582000112233445566778899aabbccddee 3432 ff0123456789abcdeffedcba987654321015f603f6' / [ 3433 / directive-set-component-index / 12,1 , 3434 / directive-set-parameters / 19,{ 3435 / image-digest / 11:[ 3436 / algorithm-id / 2 / sha256 /, 3437 / digest-bytes / 3438 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 3439 ], 3440 / uri / 6:'http://example.com/file.bin', 3441 } , 3442 / directive-fetch / 21,F6 / nil / , 3443 / condition-image-match / 3,F6 / nil / 3444 ] /, 3445 / install / 9:h'8a0c0013a10a0116f60c0103f6' / [ 3446 / directive-set-component-index / 12,0 , 3447 / directive-set-parameters / 19,{ 3448 / source-component / 10:1 / [h'01'] /, 3449 } , 3450 / directive-copy / 22,None , 3451 / directive-set-component-index / 12,1 , 3452 / condition-image-match / 3,F6 / nil / 3453 ] /, 3454 / validate / 10:h'840c0003f6' / [ 3455 / directive-set-component-index / 12,0 , 3456 / condition-image-match / 3,F6 / nil / 3457 ] /, 3458 / run / 12:h'840c0017f6' / [ 3459 / directive-set-component-index / 12,0 , 3460 / directive-run / 23,None 3461 ] /, 3463 } /, 3464 } 3466 Total size of manifest without COSE authentication object: 215 3468 Manifest: 3470 a10358d3a70101020503585fa2024782814100814101045852880c000150 3471 fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d 3472 51f2ab4514a20b8202582000112233445566778899aabbccddeeff012345 3473 6789abcdeffedcba98765432100c1987d008584c880c0113a206781b6874 3474 74703a2f2f6578616d706c652e636f6d2f66696c652e62696e0b82025820 3475 00112233445566778899aabbccddeeff0123456789abcdeffedcba987654 3476 321015f603f6094d8a0c0013a10a0116f60c0103f60a45840c0003f60c45 3477 840c0017f6 3479 Total size of manifest with COSE authentication object: 330 3481 Manifest with COSE authentication object: 3483 a202587081d28443a10126a05824820258207f35fdce6a55bed88d04497d 3484 38b7c2b4ffd1ddb74a83d9acd252d2077637de7058407bec97551827d684 3485 ac07b77c3f663f4f9436aff0b79fdfd89061bfe9bddb73919c88d32dc52f 3486 d9eb1d1ea34172eef5c222e7d897778c6b0254e20c7e87942ae10358d3a7 3487 0101020503585fa2024782814100814101045852880c000150fa6b4a53d5 3488 ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab4514 3489 a20b8202582000112233445566778899aabbccddeeff0123456789abcdef 3490 fedcba98765432100c1987d008584c880c0113a206781b687474703a2f2f 3491 6578616d706c652e636f6d2f66696c652e62696e0b820258200011223344 3492 5566778899aabbccddeeff0123456789abcdeffedcba987654321015f603 3493 f6094d8a0c0013a10a0116f60c0103f60a45840c0003f60c45840c0017f6 3495 12.7. Example 6: Two Images 3497 Compatibility test, 2 images, simultaneous download and installation, 3498 and secure boot. 3500 { 3501 / authentication-wrapper / 2:h'81d28443a10126a058248202582007954f5 3502 19cdd8101156768fbe12f23eb5ca73481e91ca4801bf94dc82f52b0ea5840a76e7f712 3503 b8d3ed6bcf79eaef8f15ee76f8da15aa16b220431f528d5cc237f95688748a156c8ee8 3504 47c517b0c660328a7877be52b1902f50e7acecc4bbd6c439f' / [ 3505 18([ 3506 / protected / h'a10126' / { 3507 / alg / 1:-7 / ES256 /, 3508 } /, 3509 / unprotected / { 3510 }, 3511 / payload / h'8202582007954f519cdd8101156768fbe12f23eb 3512 5ca73481e91ca4801bf94dc82f52b0ea' / [ 3513 / algorithm-id / 2 / sha256 /, 3514 / digest-bytes / 3515 h'07954f519cdd8101156768fbe12f23eb5ca73481e91ca4801bf94dc82f52b0ea' 3516 ] /, 3517 / signature / h'a76e7f712b8d3ed6bcf79eaef8f15ee76f8da1 3518 5aa16b220431f528d5cc237f95688748a156c8ee847c517b0c660328a7877be52b1902 3519 f50e7acecc4bbd6c439f' 3520 ]) 3521 ] /, 3522 / manifest / 3:h'a60101020303588ea20247828141008141010458818c0c000 3523 150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab4 3524 514a20b8202582000112233445566778899aabbccddeeff0123456789abcdeffedcba9 3525 8765432100c1987d00c0114a20b820258200123456789abcdeffedcba9876543210001 3526 12233445566778899aabbccddeeff0c1a00012c2209584f900c0013a106781c6874747 3527 03a2f2f6578616d706c652e636f6d2f66696c65312e62696e15f603f60c0113a106781 3528 c687474703a2f2f6578616d706c652e636f6d2f66696c65322e62696e15f603f60a498 3529 80c0003f60c0103f60c45840c0017f6' / { 3530 / manifest-version / 1:1, 3531 / manifest-sequence-number / 2:3, 3532 / common / 3:h'a20247828141008141010458818c0c000150fa6b4a53d5a 3533 d5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab4514a20b8202582 3534 000112233445566778899aabbccddeeff0123456789abcdeffedcba98765432100c198 3535 7d00c0114a20b820258200123456789abcdeffedcba987654321000112233445566778 3536 899aabbccddeeff0c1a00012c22' / { 3537 / components / 2:h'82814100814101' / [ 3538 [h'00'] , 3539 [h'01'] 3540 ] /, 3541 / common-sequence / 4:h'8c0c000150fa6b4a53d5ad5fdfbe9de663 3542 e4d41ffe02501492af1425695e48bf429b2d51f2ab4514a20b82025820001122334455 3543 66778899aabbccddeeff0123456789abcdeffedcba98765432100c1987d00c0114a20b 3544 820258200123456789abcdeffedcba987654321000112233445566778899aabbccddee 3545 ff0c1a00012c22' / [ 3546 / directive-set-component-index / 12,0 , 3547 / condition-vendor-identifier / 3548 1,h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- 3549 be9d-e663e4d41ffe / , 3550 / condition-class-identifier / 3551 2,h'1492af1425695e48bf429b2d51f2ab45' / 3552 1492af14-2569-5e48-bf42-9b2d51f2ab45 / , 3553 / directive-override-parameters / 20,{ 3554 / image-digest / 11:[ 3555 / algorithm-id / 2 / sha256 /, 3556 / digest-bytes / 3557 h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' 3558 ], 3559 / image-size / 12:34768, 3560 } , 3561 / directive-set-component-index / 12,1 , 3562 / directive-override-parameters / 20,{ 3563 / image-digest / 11:[ 3564 / algorithm-id / 2 / sha256 /, 3565 / digest-bytes / 3566 h'0123456789abcdeffedcba987654321000112233445566778899aabbccddeeff' 3567 ], 3568 / image-size / 12:76834, 3569 } 3570 ] /, 3571 } /, 3572 / install / 9:h'900c0013a106781c687474703a2f2f6578616d706c652e 3573 636f6d2f66696c65312e62696e15f603f60c0113a106781c687474703a2f2f6578616d 3574 706c652e636f6d2f66696c65322e62696e15f603f6' / [ 3575 / directive-set-component-index / 12,0 , 3576 / directive-set-parameters / 19,{ 3577 / uri / 6:'http://example.com/file1.bin', 3578 } , 3579 / directive-fetch / 21,F6 / nil / , 3580 / condition-image-match / 3,F6 / nil / , 3581 / directive-set-component-index / 12,1 , 3582 / directive-set-parameters / 19,{ 3583 / uri / 6:'http://example.com/file2.bin', 3584 } , 3585 / directive-fetch / 21,F6 / nil / , 3586 / condition-image-match / 3,F6 / nil / 3587 ] /, 3588 / validate / 10:h'880c0003f60c0103f6' / [ 3589 / directive-set-component-index / 12,0 , 3590 / condition-image-match / 3,F6 / nil / , 3591 / directive-set-component-index / 12,1 , 3592 / condition-image-match / 3,F6 / nil / 3593 ] /, 3594 / run / 12:h'840c0017f6' / [ 3595 / directive-set-component-index / 12,0 , 3596 / directive-run / 23,None 3597 ] /, 3598 } /, 3599 } 3601 Total size of manifest without COSE authentication object: 254 3603 Manifest: 3605 a10358faa60101020303588ea20247828141008141010458818c0c000150 3606 fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d 3607 51f2ab4514a20b8202582000112233445566778899aabbccddeeff012345 3608 6789abcdeffedcba98765432100c1987d00c0114a20b8202582001234567 3609 89abcdeffedcba987654321000112233445566778899aabbccddeeff0c1a 3610 00012c2209584f900c0013a106781c687474703a2f2f6578616d706c652e 3611 636f6d2f66696c65312e62696e15f603f60c0113a106781c687474703a2f 3612 2f6578616d706c652e636f6d2f66696c65322e62696e15f603f60a49880c 3613 0003f60c0103f60c45840c0017f6 3615 Total size of manifest with COSE authentication object: 369 3617 Manifest with COSE authentication object: 3619 a202587081d28443a10126a058248202582007954f519cdd8101156768fb 3620 e12f23eb5ca73481e91ca4801bf94dc82f52b0ea5840a76e7f712b8d3ed6 3621 bcf79eaef8f15ee76f8da15aa16b220431f528d5cc237f95688748a156c8 3622 ee847c517b0c660328a7877be52b1902f50e7acecc4bbd6c439f0358faa6 3623 0101020303588ea20247828141008141010458818c0c000150fa6b4a53d5 3624 ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab4514 3625 a20b8202582000112233445566778899aabbccddeeff0123456789abcdef 3626 fedcba98765432100c1987d00c0114a20b820258200123456789abcdeffe 3627 dcba987654321000112233445566778899aabbccddeeff0c1a00012c2209 3628 584f900c0013a106781c687474703a2f2f6578616d706c652e636f6d2f66 3629 696c65312e62696e15f603f60c0113a106781c687474703a2f2f6578616d 3630 706c652e636f6d2f66696c65322e62696e15f603f60a49880c0003f60c01 3631 03f60c45840c0017f6 3633 13. IANA Considerations 3635 Several registries will be required for: 3637 - standard Commands. 3639 - standard Parameters. 3641 - standard Algorithm identifiers. 3643 - standard text values. 3645 14. Security Considerations 3647 This document is about a manifest format describing and protecting 3648 firmware images and as such it is part of a larger solution for 3649 offering a standardized way of delivering firmware updates to IoT 3650 devices. A more detailed discussion about security can be found in 3651 the architecture document [I-D.ietf-suit-architecture] and in 3652 [I-D.ietf-suit-information-model]. 3654 15. Mailing List Information 3656 The discussion list for this document is located at the e-mail 3657 address suit@ietf.org [1]. Information on the group and information 3658 on how to subscribe to the list is at 3659 https://www1.ietf.org/mailman/listinfo/suit [2] 3661 Archives of the list can be found at: https://www.ietf.org/mail- 3662 archive/web/suit/current/index.html [3] 3664 16. Acknowledgements 3666 We would like to thank the following persons for their support in 3667 designing this mechanism: 3669 - Milosch Meriac 3671 - Geraint Luff 3673 - Dan Ros 3675 - John-Paul Stanford 3677 - Hugo Vincent 3679 - Carsten Bormann 3681 - Oeyvind Roenningstad 3683 - Frank Audun Kvamtroe 3685 - Krzysztof Chruściński 3687 - Andrzej Puzdrowski 3689 - Michael Richardson 3691 - David Brown 3693 - Emmanuel Baccelli 3695 17. References 3697 17.1. Normative References 3699 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3700 Requirement Levels", BCP 14, RFC 2119, 3701 DOI 10.17487/RFC2119, March 1997, 3702 . 3704 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 3705 Unique IDentifier (UUID) URN Namespace", RFC 4122, 3706 DOI 10.17487/RFC4122, July 2005, 3707 . 3709 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 3710 RFC 8152, DOI 10.17487/RFC8152, July 2017, 3711 . 3713 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3714 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3715 May 2017, . 3717 17.2. Informative References 3719 [I-D.ietf-suit-architecture] 3720 Moran, B., Tschofenig, H., Brown, D., and M. Meriac, "A 3721 Firmware Update Architecture for Internet of Things", 3722 draft-ietf-suit-architecture-08 (work in progress), 3723 November 2019. 3725 [I-D.ietf-suit-information-model] 3726 Moran, B., Tschofenig, H., and H. Birkholz, "An 3727 Information Model for Firmware Updates in IoT Devices", 3728 draft-ietf-suit-information-model-05 (work in progress), 3729 January 2020. 3731 17.3. URIs 3733 [1] mailto:suit@ietf.org 3735 [2] https://www1.ietf.org/mailman/listinfo/suit 3737 [3] https://www.ietf.org/mail-archive/web/suit/current/index.html 3739 Authors' Addresses 3741 Brendan Moran 3742 Arm Limited 3744 EMail: Brendan.Moran@arm.com 3745 Hannes Tschofenig 3746 Arm Limited 3748 EMail: hannes.tschofenig@arm.com 3750 Henk Birkholz 3751 Fraunhofer SIT 3753 EMail: henk.birkholz@sit.fraunhofer.de