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