idnits 2.17.1 draft-moran-suit-behavioural-manifest-01.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 23 instances of too long lines in the document, the longest one being 23 characters in excess of 72. ** The abstract seems to contain references ([Information]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (March 11, 2019) is 1873 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'Type' is mentioned on line 578, but not defined == Missing Reference: 'Argument' is mentioned on line 656, but not defined == Missing Reference: 'Name' is mentioned on line 605, but not defined == Missing Reference: 'Value' is mentioned on line 605, but not defined -- Looks like a reference, but probably isn't: '1' on line 1205 -- Looks like a reference, but probably isn't: '2' on line 1207 -- Looks like a reference, but probably isn't: '3' on line 1210 == Outdated reference: A later version (-16) exists of draft-ietf-suit-architecture-02 == Outdated reference: A later version (-13) exists of draft-ietf-suit-information-model-02 Summary: 2 errors (**), 0 flaws (~~), 8 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 SUIT B. Moran 3 Internet-Draft T. Ibbs 4 Intended status: Informational G. Psimenos 5 Expires: September 12, 2019 ARM Limited 6 March 11, 2019 8 An Information Model for Behavioural Description of Firmware Update and 9 Related Operations 10 draft-moran-suit-behavioural-manifest-01 12 Abstract 14 This specification describes an approach to formally defining the 15 behaviour of a system under firmware update and secure boot 16 conditions. The behavioural documents described here can be used 17 with [Information] to construct a firmware update manifest. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at https://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on September 12, 2019. 36 Copyright Notice 38 Copyright (c) 2019 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (https://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 This document may contain material from IETF Documents or IETF 52 Contributions published or made publicly available before November 53 10, 2008. The person(s) controlling the copyright in some of this 54 material may not have granted the IETF Trust the right to allow 55 modifications of such material outside the IETF Standards Process. 56 Without obtaining an adequate license from the person(s) controlling 57 the copyright in such materials, this document may not be modified 58 outside the IETF Standards Process, and derivative works of it may 59 not be created outside the IETF Standards Process, except to format 60 it for publication as an RFC or to translate it into languages other 61 than English. 63 Table of Contents 65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 66 2. Conventions and Terminology . . . . . . . . . . . . . . . . . 3 67 3. Design Principles of the Behavioural Manifest . . . . . . . . 4 68 4. Structure of a behavioural manifest . . . . . . . . . . . . . 5 69 4.1. Processing Steps . . . . . . . . . . . . . . . . . . . . 7 70 5. Commands . . . . . . . . . . . . . . . . . . . . . . . . . . 7 71 5.1. Verify Recipient Identity . . . . . . . . . . . . . . . . 8 72 5.2. Verify Image Presence . . . . . . . . . . . . . . . . . . 9 73 5.3. Verify Component Properties . . . . . . . . . . . . . . . 9 74 5.4. Verify System Properties . . . . . . . . . . . . . . . . 9 75 5.5. Verify 3rd-party Authorisation . . . . . . . . . . . . . 9 76 5.6. Process sub-behaviours . . . . . . . . . . . . . . . . . 9 77 5.7. Process Dependencies . . . . . . . . . . . . . . . . . . 9 78 5.8. Set Parameters . . . . . . . . . . . . . . . . . . . . . 10 79 5.9. Move an Image . . . . . . . . . . . . . . . . . . . . . . 10 80 5.10. Invoke an Image . . . . . . . . . . . . . . . . . . . . . 10 81 5.11. Wait for an Event . . . . . . . . . . . . . . . . . . . . 10 82 6. Parameters . . . . . . . . . . . . . . . . . . . . . . . . . 11 83 6.1. Strict Order . . . . . . . . . . . . . . . . . . . . . . 11 84 6.2. Soft Failure . . . . . . . . . . . . . . . . . . . . . . 11 85 6.3. Source List . . . . . . . . . . . . . . . . . . . . . . . 11 86 6.4. Processing Step Configurations . . . . . . . . . . . . . 12 87 6.5. Image Identifier . . . . . . . . . . . . . . . . . . . . 12 88 7. ACLs/permissions . . . . . . . . . . . . . . . . . . . . . . 12 89 8. Workflows . . . . . . . . . . . . . . . . . . . . . . . . . . 13 90 9. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 15 91 9.1. Example 1: Boot an image on an XIP processor . . . . . . 16 92 9.2. Example 2: Download an image . . . . . . . . . . . . . . 16 93 9.3. Example 3: Check compatibility, download, and boot . . . 17 94 9.4. Example 4: Check compatibility, download, load from 95 external, and boot . . . . . . . . . . . . . . . . . . . 17 97 9.5. Example 5: Check compatibility, download, load with 98 decompress, and boot . . . . . . . . . . . . . . . . . . 18 99 9.6. Example 6: Check compatibility, download, install-from- 100 external and boot . . . . . . . . . . . . . . . . . . . . 20 101 9.7. Example 7: Download and boot an image with a dependency . 21 102 9.8. Example 8: Download and boot an image with a dependency 103 using override. . . . . . . . . . . . . . . . . . . . . . 23 104 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 105 11. Security Considerations . . . . . . . . . . . . . . . . . . . 25 106 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 25 107 12.1. Normative References . . . . . . . . . . . . . . . . . . 25 108 12.2. Informative References . . . . . . . . . . . . . . . . . 25 109 Appendix A. Mailing List Information . . . . . . . . . . . . . . 27 110 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 27 112 1. Introduction 114 Conventional hierarchical, descriptive documents, such as draft- 115 moran-manifest-03 imply the behaviour of the recipient without 116 specifying that behaviour. This creates a situation where recipients 117 must construct the assumed behaviour in accordance with a 118 specification, handling many edge cases and introducing significant 119 complexity. Capabilities are difficult to specify because they imply 120 behaviours, rather than data, but the descriptive document only 121 specifies data, not capabilities. This leaves the document author to 122 interpret capabilities (supported behaviours) into allowable 123 combinations of data. This disconnect demonstrates that devices 124 require both an information model and a behavioural model. 126 This creates a situation where the behaviour of a system is 127 imprecisely specified by the documents that it uses to perform secure 128 boot and secure firmware update. In high security applications, 129 precise specification of behaviour is beneficial, and can even be 130 used for formal verification. 132 By specifying the behaviour of a device in a document rather than 133 just the information, the gap between specified information and 134 specified behaviour can be closed. 136 2. Conventions and Terminology 138 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 139 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 140 "OPTIONAL" in this document are to be interpreted as described in RFC 141 2119 [RFC2119]. 143 - SUIT: Sofware Update for the Internet of Things, the IETF working 144 group for this standard. 146 - Image: A piece of information to be delivered. Typically Firmware 147 for the purposes of SUIT. 149 - Document, Behavioural Document: The data that defines the 150 behaviour of a recipient. 152 - Component: A target for storage of the Image 154 - Dependency: Another Behavioural Document upon which the current 155 Document relies. 157 - Recipient: The system, typically an IoT device, that receives a 158 Behavioural Document. 160 - Condition: A test for a property of the Recipient or its 161 components. 163 - Directive: An action for the Recipient to perform. 165 - Command: A Condition or a Directive. 167 3. Design Principles of the Behavioural Manifest 169 In order to provide flexible behaviour to constrained devices, while 170 still allowing more powerful devices to use their full capabilities, 171 the SUIT manifest takes a new approach, encoding the required 172 behaviour of a Recipient device, instead of just presenting the 173 information used to determine that behaviour. This gives benefits 174 equivalent to those provided by a scripting language or byte code, 175 with two substantial differences. First, the language is extremely 176 high level, consisting of only the operations that a device may 177 perform during update and secure boot of a firmware image. The 178 language specifies behaviours in a linearised form, without branches 179 or loops. Conditional processing is supported, and parallel and out- 180 of-order processing may be performed by sufficiently capable devices. 182 By structuring the data in this way, the manifest processor becomes a 183 very simple engine that uses a pull parser to interpret the manifest. 184 This pull parser consists of command handlers that evaluate a 185 Condition or execute a Directive. Most data is structured in a 186 highly regular pattern, which simplifies the parser. 188 The results of this allow a Recipient with minimal functionality to 189 perform complex updates with reduced overhead. Conditional execution 190 of commands allows a simple device to perform important decisions at 191 validation-time, such as which differential update to download for a 192 given current version, or which hash to check, based on the 193 installation address. 195 Dependency handling is vastly simplified as well. Dependencies 196 function like subroutines of the language. When a manifest has a 197 dependency, it can invoke that dependency's commands and modify their 198 behaviour by setting parameters. Because some parameters come with 199 security implications, the dependencies also have a mechanism to 200 reject modifications to parameters on a fine-grained level. 202 Developing a robust permissions system works in this model too. The 203 Recipient can use a simple ACL that is a table of Identities and 204 Component Identifier permissions to ensure that only manifests 205 authenticated by the appropriate identity have access to define a 206 component. 208 Capability reporting is similarly simplified. A Recipient can report 209 the Commands and Parameters that it supports. This is sufficiently 210 precise for a manifest author to create a manifest that the Recipient 211 can accept. 213 Because the behavioural description is precise, and the machine 214 definition upon which it relies is very simple it can be augmented 215 with a proof that the effects of an update fall within a specified 216 policy, in the same way as Proof Carrying Code. By combining this 217 capability with formal verification of the document processor, it is 218 possible to prove the result of a firmware update, prior to 219 application, either on the target or on an intermediate system. The 220 proof can be discarded before distribution to constrained nodes, 221 creating no additional overhead. 223 The simplicity of design in the Recipient due to all of these 224 benefits allows even a highly constrained platform to use advanced 225 update capabilities. 227 4. Structure of a behavioural manifest 229 Behavioural manifests are divided into sections based on the 230 behaviours of the Recipient. There are 8 conceptual sections of a 231 behavioural manifest, listed below. 233 1. Document-global data 235 2. Common behaviour 237 3. Dependency Resolution behaviour 239 4. Image Acquisition behaviour 241 5. Image Application behaviour 242 6. System Validation behaviour 244 7. Image Loading behaviour 246 8. Image Invocation behaviour 248 Document-global data contains the information that is required to 249 enable most behaviours along with a security parameter. The 250 information contained is listed below. 252 1. Document Structure Version 254 2. Document Sequence Number 256 3. List of Dependencies 258 1. List of Components affected by each Dependency 260 4. List of Components affected by this Document 262 Common behaviour is executed prior to each other behaviour. It is 263 used to make common decisions for all other behaviours. 265 Dependency Resolution is used to ensure that all required documents 266 have been collected prior to attempting to acquire any image. Where 267 a document has no dependencies, this section is not required. 269 Image Acquisition is used to obtain images from local or remote 270 sources and stage them for use by the Recipient. If a Document lists 271 no affected components, then Image Acquisition is not required. If a 272 device operates in a simultaneous Acqusition & Application mode (for 273 example, streaming installation), then Image Acquisition should be 274 discarded in favour of Image Application. Image Acquisition can be 275 used in combination with several processing steps defined in 276 Section 4.1. 278 Image Application is used to place an image into its long-term 279 storage. An image can be moved either from a staging area or from 280 another source (including a remote) into its long-term storage. This 281 can be done in combination with several processing steps defined in 282 Section 4.1. 284 System validation is used to ensure that all required dependencies 285 are present and that all required images are present. This process 286 is equivalent to that used in the validation portion of Secure Boot 287 workflows. 289 Image Loading is used to ensure that all required images are moved 290 from long-term storage to active use storage. This can include steps 291 like copying from external Flash to RAM, as defined by Component 292 information. This can be done in combination with several of the 293 processing steps defined in Section 4.1. 295 Image Invocation is used to finalise the manifest processor's 296 behaviour and forward execution to a designated component. This is 297 equivalent to Bootloader behaviour. 299 Some behaviours need only a single successful invocation. These 300 behaviours can then be discarded, provided that the Document 301 serialisation provides a mechanism to do so. Typically discarded 302 behaviours are Dependency Resolution, Image Acquisition, and Image 303 Application. 305 4.1. Processing Steps 307 Processing steps are the translation that is performed on an image 308 prior to its execution. These steps typically include, in order, 309 symmetric cryptographic operations, decompression operations, 310 unpacking operations. 312 Each of these operation may need additional information, such as 313 which algorithm is in use or arguments to that algorithm, such as key 314 identifiers for cryptographic operations. This information can be 315 encoded in Processing Step parameters, as described in Section 6.4. 317 5. Commands 319 Behaviours are constructed as lists of commands, each of which may 320 have arguments. The behaviours listed in any of the specified 321 sections derives from a short list of commands. These commands are 322 divided into two types, Conditions (verification operations) and 323 Directives (action operations) 325 The lists of commands are logically structured into sequences of zero 326 or more conditions followed by zero or more directives. The 327 *logical* structure is described by the following CDDL: 329 Behaviour = [ 330 + { 331 conditions => [ * Condition], 332 directives => [ * Directive] 333 } 334 ] 335 The conditions form preconditions that MUST be true for the following 336 sequence of directives to be executed. 338 However, this organisation could introduce significant complexity in 339 a parser, so the structure MAY be flattened into the following: 341 Behaviour = [ * (Condition/Directive) ] 343 This does not alter the logical organisation of sequences of 344 preconditions that precede sequences of directives, but it simplifies 345 the consumption of commands in behaviours. 347 The Conditions are, broadly, those listed below. 349 1. Verify device identity 351 2. Verify image presence (correctness) or absence 353 3. Verify component properties 355 4. Verify system properties 357 5. Verify 3rd-party authorisation 359 The Directives are those listed below. 361 1. Process sub-behaviours 363 2. Process dependencies 365 3. Set parameters 367 4. Move an Image or Document 369 5. Invoke an Image 371 6. Wait for an event 373 5.1. Verify Recipient Identity 375 This is used to ensure that the document is being processed by the 376 appropriate device and to eliminate incompatibility failures. 377 Identity can include what sort of device is targeted, what software 378 it uses, or who made it. Identity can also include the particular 379 device that is targeted. 381 5.2. Verify Image Presence 383 This is used to ensure that a required image is present. This often 384 includes the use of cryptographic checksums to validate the contents 385 of an image contained in a component. 387 5.3. Verify Component Properties 389 This can be used to verify several properties of a targeted 390 component, such as the current nominal version of its APIs, or the 391 base address or offset that it will use. 393 5.4. Verify System Properties 395 This can be used to verify several properties of the system 396 including, the current power state, such as battery level or presence 397 of external power, the current time reported by the device, or the 398 current state of a controlled piece of equipment. 400 5.5. Verify 3rd-party Authorisation 402 This can be used to ensure that some third-party has approved an 403 action, in a system specific way. Options include checking a remote 404 system for authorisation, looking for a cryptographic token, or 405 invoking a user-interface. 407 5.6. Process sub-behaviours 409 In some use-cases, a decision must be made as to which of several 410 behaviours must be invoked. To enable this use-case, sub-behaviours 411 provide a mechanism to permit soft-failure of a Condition. A 412 parameter of the sub-behaviour controls its response to a Condition 413 check failure, allowing the command following the sub-behaviour to be 414 the next to execute, or causing failure of the whole behaviour, 415 depending on its value. 417 This allows the construction of a conditional behaviour. A sub- 418 behaviour is invoked allowing condition checks to soft-fail. Once 419 the conditions that inform the conditional behaviour have succeeded, 420 the soft-failure parameter is switched to hard-failure, so that 421 further condition failures will be detected. 423 5.7. Process Dependencies 425 Dependencies are processed by invoking two behaviours within the 426 dependency; first the common behaviour is invoked, then the behaviour 427 matching the current behaviour of the current document is invoked. 428 So, if "Image Application" is active when "Process Dependencies" is 429 invoked, then each dependency's "Common" behaviour will be invoked, 430 followed by its "Image Application" behaviour. 432 It can be advantageous to process dependencies in a particular order, 433 so dependencies are processed in the order specified. 435 A failure of processing of any dependency results in a failure of the 436 Process Dependencies behaviour. 438 5.8. Set Parameters 440 Many Commands are partially governed by configuration present in the 441 form of parameters. Parameters control the source used for Image 442 Acquisition, the processing steps applied to those images, the order 443 in which commands are processed and more. See Section 6 for more 444 information. 446 Parameters can be set in one of three ways. They can be set-if-unset 447 (the default), append-if-set (typically used for source lists), set- 448 always (used for critical parameters). Parameters are either global 449 or scoped by Component/Component Group. 451 5.9. Move an Image 453 This Command directs the document processor to acquire an Image or 454 Document and store it to a specified Component or Document storage, 455 respectively. The source can be local or remote, or a prioritised 456 list of local and remote sources. The source or source list is 457 specified by the source parameter. The Image or document can 458 optionally be modified in transit by a sequence of processing steps, 459 as defined in Section 6. 461 5.10. Invoke an Image 463 This command forwards execution to the specified image in much the 464 same way as a bootloader. As with bootloaders, the semantics of 465 forwarding execution are application defined. An argument may be 466 provided to the Image. The semantics of the argument are 467 application-defined. 469 5.11. Wait for an Event 471 Frequently, a behaviour needs to wait for a property of the system to 472 change. This may be a message from a remote, a time, a power state, 473 a user-interaction, or some other system parameter. 475 6. Parameters 477 Available parameters may vary by implementation, but some core 478 parameters are usually present. 480 Typical parameters are listed below. 482 1. Strict Order 484 2. Soft-Failure 486 3. Source List 488 4. Processing Step Configuration 490 5. Image Identifier 492 In some use-cases, device identity may also be configured in a 493 parameter. 495 6.1. Strict Order 497 Some advanced devices may have particular requirements regarding 498 command ordering within a behaviour. Others may enable parallel 499 execution of commands. When the Strict Order parameter is set to 500 False, these extended capabilities are enabled. An advanced device 501 may then aggregate all successive commands up until the behaviour 502 ends or the Strict Order parameter is returned to True and process 503 those commands in parallel or reorder them as it requires. Strict 504 Order defaults to True. If a device does not support command 505 reordering or parallel processing, Strict Order = False has no 506 effect. 508 6.2. Soft Failure 510 When a device invokes a sub-behaviour, any condition check failure 511 and any directive failure causes the behaviour to immediately abort. 512 However, if the Soft Failure parameter is True, then an abort due to 513 a condition failure does not cause the sub-behaviour to report 514 failure. If the Soft Failure parameter is True, indicating hard 515 failure, then any abort causes the sub-behaviour to report failure as 516 well. 518 6.3. Source List 520 The source list is scoped to an individual component or dependency. 521 It is a prioritised search path for the Move command to use in order 522 to find an image or document. It can contain either local sources, 523 such as other components, or remote ones, such as URIs. 525 6.4. Processing Step Configurations 527 Many processing steps require configuration to operate, or 528 configuration informs whether or not to use them. Common processing 529 steps include symmetric cryptography, compression or decompression 530 operations, and packing or unpacking, for example relocation, 531 differential compression, or hex file interpretation. 533 Processing step configuration is scoped to an individual component or 534 document. 536 6.5. Image Identifier 538 In order to determine whether an image is present, the verify image 539 presence condition requires an identifier for the image. This could 540 be a version number or a cryptographic identity such as a digest. 542 7. ACLs/permissions 544 To manage permissions in documents, there are three models that can 545 be used. 547 First, the simplest model requires that all documents are 548 authenticated by a single identity. This mode has the advantage that 549 only a single document needs to be authenticated, since each 550 document's dependencies are uniquely identified in that document. 552 This simplest model can be extended by adding key delegation without 553 much increase in complexity. 555 A second model requires an ACL to be presented to the device, 556 authenticated by a trusted party or stored on the device. This ACL 557 grants access rights for specific Components or Component Groups to 558 the listed identities or identity groups. Any identity may verify 559 that an image is present, but Moving an image into or out of a 560 Component requires approval from the ACL. 562 A third model allows a Document Processor to provide even more fine- 563 grained controls: The ACL lists the Component or Component Group that 564 an identity may use, and also lists the commands that the identity 565 may use in combination with that Component/Group. 567 8. Workflows 569 The two most common workflows are image installation and image 570 invocation. Both of these workflows use a common component: 571 do_commands. 573 do_commands uses the following pseudocode: 575 function do_commands(section, sequence) 576 rc = SUCCESS 577 foreach (command in $sequence) 578 choose $command[Type]: 579 case Sub-Behaviour: 580 Load commands = $command[Argument][commands] 581 Load parameters = System Parameters 582 Load soft_failure = $parameters[Soft Failure] 583 Call rc = do_commands(commands) 584 if (soft_failure AND is_condition_failure(rc)) 585 rc = SUCCESS 586 endif 587 endcase 588 case Process Dependency: 589 ; Note Dependency selection can be done via argument or 590 ; parameter. May process multiple dependencies in a list. 591 Load Dependency 592 Load common = $Dependency[Common Sequence] 593 Call rc = do_commands(Common, $common) 594 if (rc is SUCCESS?) 595 Load $sequence = $Dependency[$section] 596 Call rc = do_commands($section, $sequence) 597 endif 598 endcase 599 case Set Parameters: 600 Load parameter_list = $command[Argument][Parameter List] 601 foreach (parameter in parameter_list) 602 if (is_append(parameter)?) 603 Append argument value to $parameter 604 elseif (is_set($parameter[Name])) 605 Set $parameter[Name] = $parameter[Value] 606 endif 607 endfor 608 endcase 609 case Move: 610 ; Note Component selection can be done via argument or 611 ; parameter. May process multiple components in a list. 612 ; Note Dependency selection can be done via argument or 613 ; parameter. May process multiple dependencies in a list. 614 ; Source 615 Load component_list = $command[Argument][Component List] 616 Load dependency_list = $command[Argument][Dependency List] 617 foreach (target_list in [component_list, dependency_list]) 618 foreach (target in $target_list) 619 Load $target parameters 620 Set source = choose_best_source($parameters[Source List]) 621 Acquire data from $source 622 foreach (processing_step in $parameters[Processing Step Configuration]) 623 rc = Process_Data($processing_step, $data) 624 endfor 625 Store $data to $target 626 endfor 627 endfor 628 endcase 629 case Invoke: 630 ; Note Component selection can be done via argument or 631 ; parameter. May process multiple components in a list. 632 Select component 633 Load Argument = $command[Argument] 634 Transfer execution to $component with $Argument; 635 endcase 636 case Wait: 637 Load arguments = $command[Argument][Wait Arguments] 638 Load type = $command[Argument][Wait Type] 639 Wait ($type, $arguments) 640 endcase 641 case Device Identity: 642 ; Note Device Identity selection can be done via argument or 643 ; parameter. May process multiple Device Identities in a list. 644 Load device_identity = $parameters[Device Identity] 645 if ($device_identity is nil) 646 Load device_identity = $command[Argument][Device Identity] 647 endif 648 rc = Compare $device_identity to $parameters 649 endcase 650 case Image Present/not Present: 651 ; Note Component selection can be done via argument or 652 ; parameter. May process multiple components in a list. 653 ; Note Dependency selection can be done via argument or 654 ; parameter. May process multiple dependencies in a list. 655 Load component_list = $command[Argument][Component List] 656 Load dependency_list = $command[Argument][Dependency List] 657 foreach (target_list in [component_list, dependency_list]) 658 foreach (target in $target_list) 659 Load $target parameters 660 Set image_identifier = $parameters[Image Identifier] 661 rc = Compare $component to $image_identifier; 662 endfor 664 endfor 665 endcase 666 case Verify Authorisation 667 Request authorisation 668 Wait for authorisation 669 rc = Check Response 670 endcase 671 endchoose 672 endwhile (no) 673 endfunction 675 Installation, is represented by the following pseudocode. 677 function install(Document) 678 Load $Document[Common Data] into parameters 679 foreach (sequence in [Common, Dependency Resolution, Image Acquisition, Image Application]) 680 rc = do_commands($sequence, $Document[$sequence]); 681 if (rc is not SUCCESS) 682 Abort 683 endif 684 endfor 685 endfunction 687 Image invocation is represented by the following pseudocode. 689 function invoke(Document) 690 Load $Document[Common Data] into parameters 691 foreach (sequence in [Common, System Validation, Image Loading, Image Invocation]) 692 rc = do_commands($sequence, $Document[$sequence]); 693 if (rc is not SUCCESS) 694 Abort 695 endif 696 endfor 697 endfunction 699 Each operation represented here is already present in a device 700 capable of firmware update or secure boot. This approach simply 701 defines the mechanism by which these operations are orchestrated, and 702 enforces that the behaviour of the system is defined by the 703 Behavioural Document, rather than implied by it. 705 9. Examples 707 These examples demonstrate the serialisation of the behaviours of an 708 update. They are serialised in JSON for readability, but JSON is not 709 recommended for use on constrained devices. 711 9.1. Example 1: Boot an image on an XIP processor 713 { 714 "structure-version" : 1, 715 "sequence-number" : 1, 716 "components": [ 717 { 718 "id" : , 719 "digest":"", 720 "size" : 721 } 722 ], 723 "validate" : [ 724 { 725 "condition-validate-image" : {"component" : 0} 726 } 727 ], 728 "image-invocation" : [ 729 { 730 "directive-run-component":{"component" : 0} 731 } 732 ] 733 } 735 9.2. Example 2: Download an image 737 { 738 "structure-version" : 1, 739 "sequence-number" : 2, 740 "components": [ 741 { 742 "id" : , 743 "digest":"", 744 "size" : 745 } 746 ], 747 "image-acquisition" : [ 748 { 749 "directive-move" : { 750 "source": "http://example.com/file.bin", 751 "destination" : 0 752 } 753 } 754 ] 755 } 757 9.3. Example 3: Check compatibility, download, and boot 759 { 760 "structure-version" : 1, 761 "sequence-number" : 3, 762 "components": [ 763 { 764 "id" : , 765 "digest":"", 766 "size" : 767 } 768 ], 769 "common" : [ 770 {"condition-vendor-id" : "fa6b4a53-d5ad-5fdf-be9d-e663e4d41ffe"}, 771 {"condition-class-id" : "1492af14-2569-5e48-bf42-9b2d51f2ab45"} 772 ], 773 "image-application" : [ 774 { 775 "directive-move" : { 776 "source": "http://example.com/file.bin", 777 "destination" : 0 778 } 779 } 780 ], 781 "validate" : [ 782 { 783 "condition-validate-image" : {"component" : 0} 784 } 785 ], 786 "image-invocation" : [ 787 { 788 "directive-run-component":{"component" : 0} 789 } 790 ] 791 } 793 9.4. Example 4: Check compatibility, download, load from external, and 794 boot 796 { 797 "structure-version" : 1, 798 "sequence-number" : 4, 799 "components": [ 800 { 801 "id" : , 802 "digest":"", 803 "size" : 804 }, 805 { 806 "id" : , 807 "digest":"", 808 "size" : 809 } 810 ], 811 "common" : [ 812 {"condition-vendor-id" : "fa6b4a53-d5ad-5fdf-be9d-e663e4d41ffe"}, 813 {"condition-class-id" : "1492af14-2569-5e48-bf42-9b2d51f2ab45"} 814 ], 815 "image-application" : [ 816 { 817 "directive-move" : { 818 "source": "http://example.com/file.bin", 819 "destination" : 0 820 } 821 } 822 ], 823 "validate" : [ 824 { 825 "condition-validate-image" : {"component" : 0} 826 } 827 ], 828 "load-image" : [ 829 { 830 "directive-move" : { 831 "source": 0, 832 "destination" : 1 833 } 834 } 835 ], 836 "image-invocation" : [ 837 { 838 "condition-validate-image" : {"component" : 1} 839 }, 840 { 841 "directive-run-component":{"component" : 1} 842 } 843 ] 844 } 846 9.5. Example 5: Check compatibility, download, load with decompress, 847 and boot 849 { 850 "structure-version" : 1, 851 "sequence-number" : 5, 852 "components": [ 853 { 854 "id" : , 855 "digest":"", 856 "size" : 857 }, 858 { 859 "id" : , 860 "digest":"", 861 "size" : 862 } 863 ], 864 "common" : [ 865 {"condition-vendor-id" : "fa6b4a53-d5ad-5fdf-be9d-e663e4d41ffe"}, 866 {"condition-class-id" : "1492af14-2569-5e48-bf42-9b2d51f2ab45"} 867 ], 868 "image-application" : [ 869 { 870 "directive-move" : { 871 "source": "http://example.com/file.bin", 872 "destination" : 0 873 } 874 } 875 ], 876 "validate" : [ 877 { 878 "condition-validate-image" : {"component" : 0} 879 } 880 ], 881 "load-image" : [ 882 { 883 "directive-move" : { 884 "source": 0, 885 "destination" : 1, 886 "processing-step-compression-algorithm" : "gzip" 887 } 888 } 889 ], 890 "image-invocation" : [ 891 { 892 "condition-validate-image" : {"component" : 1} 893 }, 894 { 895 "directive-run-component":{"component" : 1} 896 } 897 ] 898 } 899 9.6. Example 6: Check compatibility, download, install-from-external 900 and boot 902 { 903 "structure-version" : 1, 904 "sequence-number" : 6, 905 "components": [ 906 { 907 "id" : , 908 "digest":"", 909 "size" : 910 }, 911 { 912 "id" : , 913 "digest":"", 914 "size" : 915 } 916 ], 917 "common" : [ 918 {"condition-vendor-id" : "fa6b4a53-d5ad-5fdf-be9d-e663e4d41ffe"}, 919 {"condition-class-id" : "1492af14-2569-5e48-bf42-9b2d51f2ab45"} 920 ], 921 "image-acquisition" : [ 922 { 923 "directive-move" : { 924 "source": "http://example.com/file.bin", 925 "destination" : 0 926 } 927 } 928 ], 929 "validate" : [ 930 { 931 "sub-behaviour" : [ 932 "soft-failure" : True, 933 "condition-validate-not-image" : {"component" : 1} 934 "soft-failure" : False 935 "condition-validate-image" : {"component" : 0} 936 ] 937 } 938 ], 939 "load-image" : [ 940 { 941 "sub-behaviour" : [ 942 "soft-failure" : True, 943 "condition-validate-not-image" : {"component" : 1} 944 "soft-failure" : False 945 "directive-move" : { 946 "source": 0, 947 "destination" : 1 948 } 949 ] 950 } 951 ], 952 "image-invocation" : [ 953 { 954 "condition-validate-image" : {"component" : 1} 955 }, 956 { 957 "directive-run-component":{"component" : 1} 958 } 959 ] 960 } 962 9.7. Example 7: Download and boot an image with a dependency 964 [ 965 { 966 "structure-version" : 1, 967 "sequence-number" : 7, 968 "components": [ 969 { 970 "id" : , 971 "digest":"", 972 "size" : 973 } 974 ], 975 "common" : [ 976 {"condition-vendor-id" : "fa6b4a53-d5ad-5fdf-be9d-e663e4d41ffe"}, 977 {"condition-class-id" : "1492af14-2569-5e48-bf42-9b2d51f2ab45"} 978 ], 979 "image-application" : [ 980 { 981 "directive-move" : { 982 "source": "http://example.com/file.bin", 983 "destination" : 0 984 } 985 } 986 ], 987 "validate" : [ 988 { 989 "condition-validate-image" : {"component" : 0} 990 } 991 ], 992 "image-invocation" : [ 993 { 994 "directive-run-component":{"component" : 0} 996 } 997 ] 998 }, 999 { 1000 "structure-version" : 1, 1001 "sequence-number" : 8, 1002 "dependencies" : [ 1003 { 1004 "digest" : "" 1005 "components" : [] 1006 } 1007 ], 1008 "components": [ 1009 { 1010 "id" : , 1011 "digest":"", 1012 "size" : 1013 } 1014 ], 1015 "dependency-resolution" : [ 1016 { 1017 "directive-move" : { 1018 "source": "http://example.com/document0.bin", 1019 "destination" : 1020 } 1021 }, 1022 { 1023 "condition-validate-image" : {"dependency" : 0} 1024 }, 1025 ], 1026 "image-application" : [ 1027 { 1028 "directive-move" : { 1029 "source": "http://example.com/file1.bin", 1030 "destination" : 1 1031 } 1032 }, 1033 { "process-dependency" : 0 } 1034 ] 1035 "validate" : [ 1036 { 1037 "condition-validate-image" : {"dependency" : 0} 1038 }, 1039 { "process-dependency" : 0 }, 1040 { 1041 "condition-validate-image" : {"image" : 1} 1042 } 1043 ], 1044 "image-invocation" : [ 1045 { "process-dependency" : 0 } 1046 ] 1047 } 1048 ] 1050 9.8. Example 8: Download and boot an image with a dependency using 1051 override. 1053 Override fetch location for dependency. 1055 [ 1056 { 1057 "structure-version" : 1, 1058 "sequence-number" : 7, 1059 "components": [ 1060 { 1061 "id" : , 1062 "digest":"", 1063 "size" : 1064 } 1065 ], 1066 "common" : [ 1067 {"condition-vendor-id" : "fa6b4a53-d5ad-5fdf-be9d-e663e4d41ffe"}, 1068 {"condition-class-id" : "1492af14-2569-5e48-bf42-9b2d51f2ab45"} 1069 ], 1070 "image-application" : [ 1071 { 1072 "set-parameter" : { 1073 "component" : 0 1074 "source": "http://example.com/file.bin", 1075 } 1076 }, 1077 { 1078 "directive-move" : { 1079 "destination" : 0 1080 } 1081 } 1082 ], 1083 "validate" : [ 1084 { 1085 "condition-validate-image" : {"component" : 0} 1086 } 1087 ], 1088 "image-invocation" : [ 1089 { 1090 "directive-run-component":{"component" : 0} 1091 } 1093 ] 1094 }, 1095 { 1096 "structure-version" : 1, 1097 "sequence-number" : 8, 1098 "dependencies" : [ 1099 { 1100 "digest" : "" 1101 "components" : [] 1102 } 1103 ], 1104 "components": [ 1105 { 1106 "id" : , 1107 "digest":"", 1108 "size" : 1109 } 1110 ], 1111 "dependency-resolution" : [ 1112 { 1113 "directive-move" : { 1114 "source": "http://example.com/document0.bin", 1115 "destination" : 1116 } 1117 }, 1118 { 1119 "condition-validate-image" : {"dependency" : 0} 1120 }, 1121 ], 1122 "image-application" : [ 1123 { 1124 "directive-move" : { 1125 "source": "http://example.com/file1.bin", 1126 "destination" : 1 1127 } 1128 }, 1129 { 1130 "set-parameter" : { 1131 "component" : 0 1132 "source": "http://other-host.com/file.bin", 1133 } 1134 }, 1135 { "process-dependency" : 0 } 1136 ] 1137 "validate" : [ 1138 { 1139 "condition-validate-image" : {"dependency" : 0} 1140 }, 1141 { "process-dependency" : 0 }, 1142 { 1143 "condition-validate-image" : {"image" : 1} 1144 } 1145 ], 1146 "image-invocation" : [ 1147 { "process-dependency" : 0 } 1148 ] 1149 } 1150 ] 1152 10. IANA Considerations 1154 In any given serialisation of this approach, several registries will 1155 be required for: 1157 - Standard Commands 1159 - Standard Parameters 1161 This document requires no action from IANA. 1163 11. Security Considerations 1165 This document describes the distribution of firmware updates and the 1166 invocation of complex behaviours on a device. As such, the contents 1167 of a document following the described approach to updates MUST be 1168 authenticated as described in Section 7. A more detailed discussion 1169 about security can be found in the architecture document 1170 [Architecture]. 1172 12. References 1174 12.1. Normative References 1176 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1177 Requirement Levels", BCP 14, RFC 2119, 1178 DOI 10.17487/RFC2119, March 1997, 1179 . 1181 12.2. Informative References 1183 [Architecture] 1184 Moran, B., "A Firmware Update Architecture for Internet of 1185 Things Devices", July 2018, . 1188 [Information] 1189 Moran, B., "Firmware Updates for Internet of Things 1190 Devices - An Information Model for Manifests", July 2018, 1191 . 1194 12.3. URIs 1196 [1] mailto:suit@ietf.org 1198 [2] https://www1.ietf.org/mailman/listinfo/suit 1200 [3] https://www.ietf.org/mail-archive/web/suit/current/index.html 1202 Appendix A. Mailing List Information 1204 The discussion list for this document is located at the e-mail 1205 address suit@ietf.org [1]. Information on the group and information 1206 on how to subscribe to the list is at 1207 https://www1.ietf.org/mailman/listinfo/suit [2] 1209 Archives of the list can be found at: https://www.ietf.org/mail- 1210 archive/web/suit/current/index.html [3] 1212 Authors' Addresses 1214 Brendan Moran 1215 ARM Limited 1217 EMail: Brendan.Moran@arm.com 1219 Tony Ibbs 1220 ARM Limited 1222 EMail: Tony.Ibbs@arm.com 1224 George Psimenos 1225 ARM Limited