Internet DRAFT - draft-moran-suit-behavioural-manifest
draft-moran-suit-behavioural-manifest
SUIT B. Moran
Internet-Draft T. Ibbs
Intended status: Informational G. Psimenos
Expires: September 12, 2019 ARM Limited
March 11, 2019
An Information Model for Behavioural Description of Firmware Update and
Related Operations
draft-moran-suit-behavioural-manifest-01
Abstract
This specification describes an approach to formally defining the
behaviour of a system under firmware update and secure boot
conditions. The behavioural documents described here can be used
with [Information] to construct a firmware update manifest.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on September 12, 2019.
Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
Moran, et al. Expires September 12, 2019 [Page 1]
Internet-DraftBehavioural description of Firwmware Updates March 2019
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
This document may contain material from IETF Documents or IETF
Contributions published or made publicly available before November
10, 2008. The person(s) controlling the copyright in some of this
material may not have granted the IETF Trust the right to allow
modifications of such material outside the IETF Standards Process.
Without obtaining an adequate license from the person(s) controlling
the copyright in such materials, this document may not be modified
outside the IETF Standards Process, and derivative works of it may
not be created outside the IETF Standards Process, except to format
it for publication as an RFC or to translate it into languages other
than English.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Conventions and Terminology . . . . . . . . . . . . . . . . . 3
3. Design Principles of the Behavioural Manifest . . . . . . . . 4
4. Structure of a behavioural manifest . . . . . . . . . . . . . 5
4.1. Processing Steps . . . . . . . . . . . . . . . . . . . . 7
5. Commands . . . . . . . . . . . . . . . . . . . . . . . . . . 7
5.1. Verify Recipient Identity . . . . . . . . . . . . . . . . 8
5.2. Verify Image Presence . . . . . . . . . . . . . . . . . . 9
5.3. Verify Component Properties . . . . . . . . . . . . . . . 9
5.4. Verify System Properties . . . . . . . . . . . . . . . . 9
5.5. Verify 3rd-party Authorisation . . . . . . . . . . . . . 9
5.6. Process sub-behaviours . . . . . . . . . . . . . . . . . 9
5.7. Process Dependencies . . . . . . . . . . . . . . . . . . 9
5.8. Set Parameters . . . . . . . . . . . . . . . . . . . . . 10
5.9. Move an Image . . . . . . . . . . . . . . . . . . . . . . 10
5.10. Invoke an Image . . . . . . . . . . . . . . . . . . . . . 10
5.11. Wait for an Event . . . . . . . . . . . . . . . . . . . . 10
6. Parameters . . . . . . . . . . . . . . . . . . . . . . . . . 11
6.1. Strict Order . . . . . . . . . . . . . . . . . . . . . . 11
6.2. Soft Failure . . . . . . . . . . . . . . . . . . . . . . 11
6.3. Source List . . . . . . . . . . . . . . . . . . . . . . . 11
6.4. Processing Step Configurations . . . . . . . . . . . . . 12
6.5. Image Identifier . . . . . . . . . . . . . . . . . . . . 12
7. ACLs/permissions . . . . . . . . . . . . . . . . . . . . . . 12
8. Workflows . . . . . . . . . . . . . . . . . . . . . . . . . . 13
9. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 15
9.1. Example 1: Boot an image on an XIP processor . . . . . . 16
9.2. Example 2: Download an image . . . . . . . . . . . . . . 16
9.3. Example 3: Check compatibility, download, and boot . . . 17
9.4. Example 4: Check compatibility, download, load from
external, and boot . . . . . . . . . . . . . . . . . . . 17
Moran, et al. Expires September 12, 2019 [Page 2]
Internet-DraftBehavioural description of Firwmware Updates March 2019
9.5. Example 5: Check compatibility, download, load with
decompress, and boot . . . . . . . . . . . . . . . . . . 18
9.6. Example 6: Check compatibility, download, install-from-
external and boot . . . . . . . . . . . . . . . . . . . . 20
9.7. Example 7: Download and boot an image with a dependency . 21
9.8. Example 8: Download and boot an image with a dependency
using override. . . . . . . . . . . . . . . . . . . . . . 23
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25
11. Security Considerations . . . . . . . . . . . . . . . . . . . 25
12. References . . . . . . . . . . . . . . . . . . . . . . . . . 25
12.1. Normative References . . . . . . . . . . . . . . . . . . 25
12.2. Informative References . . . . . . . . . . . . . . . . . 25
Appendix A. Mailing List Information . . . . . . . . . . . . . . 27
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 27
1. Introduction
Conventional hierarchical, descriptive documents, such as draft-
moran-manifest-03 imply the behaviour of the recipient without
specifying that behaviour. This creates a situation where recipients
must construct the assumed behaviour in accordance with a
specification, handling many edge cases and introducing significant
complexity. Capabilities are difficult to specify because they imply
behaviours, rather than data, but the descriptive document only
specifies data, not capabilities. This leaves the document author to
interpret capabilities (supported behaviours) into allowable
combinations of data. This disconnect demonstrates that devices
require both an information model and a behavioural model.
This creates a situation where the behaviour of a system is
imprecisely specified by the documents that it uses to perform secure
boot and secure firmware update. In high security applications,
precise specification of behaviour is beneficial, and can even be
used for formal verification.
By specifying the behaviour of a device in a document rather than
just the information, the gap between specified information and
specified behaviour can be closed.
2. Conventions and Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in RFC
2119 [RFC2119].
- SUIT: Sofware Update for the Internet of Things, the IETF working
group for this standard.
Moran, et al. Expires September 12, 2019 [Page 3]
Internet-DraftBehavioural description of Firwmware Updates March 2019
- Image: A piece of information to be delivered. Typically Firmware
for the purposes of SUIT.
- Document, Behavioural Document: The data that defines the
behaviour of a recipient.
- Component: A target for storage of the Image
- Dependency: Another Behavioural Document upon which the current
Document relies.
- Recipient: The system, typically an IoT device, that receives a
Behavioural Document.
- Condition: A test for a property of the Recipient or its
components.
- Directive: An action for the Recipient to perform.
- Command: A Condition or a Directive.
3. Design Principles of the Behavioural Manifest
In order to provide flexible behaviour to constrained devices, while
still allowing more powerful devices to use their full capabilities,
the SUIT manifest takes a new approach, encoding the required
behaviour of a Recipient device, instead of just presenting the
information used to determine that behaviour. This gives benefits
equivalent to those provided by a scripting language or byte code,
with two substantial differences. First, the language is extremely
high level, consisting of only the operations that a device may
perform during update and secure boot of a firmware image. The
language specifies behaviours in a linearised form, without branches
or loops. Conditional processing is supported, and parallel and out-
of-order processing may be performed by sufficiently capable devices.
By structuring the data in this way, the manifest processor becomes a
very simple engine that uses a pull parser to interpret the manifest.
This pull parser consists of command handlers that evaluate a
Condition or execute a Directive. Most data is structured in a
highly regular pattern, which simplifies the parser.
The results of this allow a Recipient with minimal functionality to
perform complex updates with reduced overhead. Conditional execution
of commands allows a simple device to perform important decisions at
validation-time, such as which differential update to download for a
given current version, or which hash to check, based on the
installation address.
Moran, et al. Expires September 12, 2019 [Page 4]
Internet-DraftBehavioural description of Firwmware Updates March 2019
Dependency handling is vastly simplified as well. Dependencies
function like subroutines of the language. When a manifest has a
dependency, it can invoke that dependency's commands and modify their
behaviour by setting parameters. Because some parameters come with
security implications, the dependencies also have a mechanism to
reject modifications to parameters on a fine-grained level.
Developing a robust permissions system works in this model too. The
Recipient can use a simple ACL that is a table of Identities and
Component Identifier permissions to ensure that only manifests
authenticated by the appropriate identity have access to define a
component.
Capability reporting is similarly simplified. A Recipient can report
the Commands and Parameters that it supports. This is sufficiently
precise for a manifest author to create a manifest that the Recipient
can accept.
Because the behavioural description is precise, and the machine
definition upon which it relies is very simple it can be augmented
with a proof that the effects of an update fall within a specified
policy, in the same way as Proof Carrying Code. By combining this
capability with formal verification of the document processor, it is
possible to prove the result of a firmware update, prior to
application, either on the target or on an intermediate system. The
proof can be discarded before distribution to constrained nodes,
creating no additional overhead.
The simplicity of design in the Recipient due to all of these
benefits allows even a highly constrained platform to use advanced
update capabilities.
4. Structure of a behavioural manifest
Behavioural manifests are divided into sections based on the
behaviours of the Recipient. There are 8 conceptual sections of a
behavioural manifest, listed below.
1. Document-global data
2. Common behaviour
3. Dependency Resolution behaviour
4. Image Acquisition behaviour
5. Image Application behaviour
Moran, et al. Expires September 12, 2019 [Page 5]
Internet-DraftBehavioural description of Firwmware Updates March 2019
6. System Validation behaviour
7. Image Loading behaviour
8. Image Invocation behaviour
Document-global data contains the information that is required to
enable most behaviours along with a security parameter. The
information contained is listed below.
1. Document Structure Version
2. Document Sequence Number
3. List of Dependencies
1. List of Components affected by each Dependency
4. List of Components affected by this Document
Common behaviour is executed prior to each other behaviour. It is
used to make common decisions for all other behaviours.
Dependency Resolution is used to ensure that all required documents
have been collected prior to attempting to acquire any image. Where
a document has no dependencies, this section is not required.
Image Acquisition is used to obtain images from local or remote
sources and stage them for use by the Recipient. If a Document lists
no affected components, then Image Acquisition is not required. If a
device operates in a simultaneous Acqusition & Application mode (for
example, streaming installation), then Image Acquisition should be
discarded in favour of Image Application. Image Acquisition can be
used in combination with several processing steps defined in
Section 4.1.
Image Application is used to place an image into its long-term
storage. An image can be moved either from a staging area or from
another source (including a remote) into its long-term storage. This
can be done in combination with several processing steps defined in
Section 4.1.
System validation is used to ensure that all required dependencies
are present and that all required images are present. This process
is equivalent to that used in the validation portion of Secure Boot
workflows.
Moran, et al. Expires September 12, 2019 [Page 6]
Internet-DraftBehavioural description of Firwmware Updates March 2019
Image Loading is used to ensure that all required images are moved
from long-term storage to active use storage. This can include steps
like copying from external Flash to RAM, as defined by Component
information. This can be done in combination with several of the
processing steps defined in Section 4.1.
Image Invocation is used to finalise the manifest processor's
behaviour and forward execution to a designated component. This is
equivalent to Bootloader behaviour.
Some behaviours need only a single successful invocation. These
behaviours can then be discarded, provided that the Document
serialisation provides a mechanism to do so. Typically discarded
behaviours are Dependency Resolution, Image Acquisition, and Image
Application.
4.1. Processing Steps
Processing steps are the translation that is performed on an image
prior to its execution. These steps typically include, in order,
symmetric cryptographic operations, decompression operations,
unpacking operations.
Each of these operation may need additional information, such as
which algorithm is in use or arguments to that algorithm, such as key
identifiers for cryptographic operations. This information can be
encoded in Processing Step parameters, as described in Section 6.4.
5. Commands
Behaviours are constructed as lists of commands, each of which may
have arguments. The behaviours listed in any of the specified
sections derives from a short list of commands. These commands are
divided into two types, Conditions (verification operations) and
Directives (action operations)
The lists of commands are logically structured into sequences of zero
or more conditions followed by zero or more directives. The
*logical* structure is described by the following CDDL:
Behaviour = [
+ {
conditions => [ * Condition],
directives => [ * Directive]
}
]
Moran, et al. Expires September 12, 2019 [Page 7]
Internet-DraftBehavioural description of Firwmware Updates March 2019
The conditions form preconditions that MUST be true for the following
sequence of directives to be executed.
However, this organisation could introduce significant complexity in
a parser, so the structure MAY be flattened into the following:
Behaviour = [ * (Condition/Directive) ]
This does not alter the logical organisation of sequences of
preconditions that precede sequences of directives, but it simplifies
the consumption of commands in behaviours.
The Conditions are, broadly, those listed below.
1. Verify device identity
2. Verify image presence (correctness) or absence
3. Verify component properties
4. Verify system properties
5. Verify 3rd-party authorisation
The Directives are those listed below.
1. Process sub-behaviours
2. Process dependencies
3. Set parameters
4. Move an Image or Document
5. Invoke an Image
6. Wait for an event
5.1. Verify Recipient Identity
This is used to ensure that the document is being processed by the
appropriate device and to eliminate incompatibility failures.
Identity can include what sort of device is targeted, what software
it uses, or who made it. Identity can also include the particular
device that is targeted.
Moran, et al. Expires September 12, 2019 [Page 8]
Internet-DraftBehavioural description of Firwmware Updates March 2019
5.2. Verify Image Presence
This is used to ensure that a required image is present. This often
includes the use of cryptographic checksums to validate the contents
of an image contained in a component.
5.3. Verify Component Properties
This can be used to verify several properties of a targeted
component, such as the current nominal version of its APIs, or the
base address or offset that it will use.
5.4. Verify System Properties
This can be used to verify several properties of the system
including, the current power state, such as battery level or presence
of external power, the current time reported by the device, or the
current state of a controlled piece of equipment.
5.5. Verify 3rd-party Authorisation
This can be used to ensure that some third-party has approved an
action, in a system specific way. Options include checking a remote
system for authorisation, looking for a cryptographic token, or
invoking a user-interface.
5.6. Process sub-behaviours
In some use-cases, a decision must be made as to which of several
behaviours must be invoked. To enable this use-case, sub-behaviours
provide a mechanism to permit soft-failure of a Condition. A
parameter of the sub-behaviour controls its response to a Condition
check failure, allowing the command following the sub-behaviour to be
the next to execute, or causing failure of the whole behaviour,
depending on its value.
This allows the construction of a conditional behaviour. A sub-
behaviour is invoked allowing condition checks to soft-fail. Once
the conditions that inform the conditional behaviour have succeeded,
the soft-failure parameter is switched to hard-failure, so that
further condition failures will be detected.
5.7. Process Dependencies
Dependencies are processed by invoking two behaviours within the
dependency; first the common behaviour is invoked, then the behaviour
matching the current behaviour of the current document is invoked.
So, if "Image Application" is active when "Process Dependencies" is
Moran, et al. Expires September 12, 2019 [Page 9]
Internet-DraftBehavioural description of Firwmware Updates March 2019
invoked, then each dependency's "Common" behaviour will be invoked,
followed by its "Image Application" behaviour.
It can be advantageous to process dependencies in a particular order,
so dependencies are processed in the order specified.
A failure of processing of any dependency results in a failure of the
Process Dependencies behaviour.
5.8. Set Parameters
Many Commands are partially governed by configuration present in the
form of parameters. Parameters control the source used for Image
Acquisition, the processing steps applied to those images, the order
in which commands are processed and more. See Section 6 for more
information.
Parameters can be set in one of three ways. They can be set-if-unset
(the default), append-if-set (typically used for source lists), set-
always (used for critical parameters). Parameters are either global
or scoped by Component/Component Group.
5.9. Move an Image
This Command directs the document processor to acquire an Image or
Document and store it to a specified Component or Document storage,
respectively. The source can be local or remote, or a prioritised
list of local and remote sources. The source or source list is
specified by the source parameter. The Image or document can
optionally be modified in transit by a sequence of processing steps,
as defined in Section 6.
5.10. Invoke an Image
This command forwards execution to the specified image in much the
same way as a bootloader. As with bootloaders, the semantics of
forwarding execution are application defined. An argument may be
provided to the Image. The semantics of the argument are
application-defined.
5.11. Wait for an Event
Frequently, a behaviour needs to wait for a property of the system to
change. This may be a message from a remote, a time, a power state,
a user-interaction, or some other system parameter.
Moran, et al. Expires September 12, 2019 [Page 10]
Internet-DraftBehavioural description of Firwmware Updates March 2019
6. Parameters
Available parameters may vary by implementation, but some core
parameters are usually present.
Typical parameters are listed below.
1. Strict Order
2. Soft-Failure
3. Source List
4. Processing Step Configuration
5. Image Identifier
In some use-cases, device identity may also be configured in a
parameter.
6.1. Strict Order
Some advanced devices may have particular requirements regarding
command ordering within a behaviour. Others may enable parallel
execution of commands. When the Strict Order parameter is set to
False, these extended capabilities are enabled. An advanced device
may then aggregate all successive commands up until the behaviour
ends or the Strict Order parameter is returned to True and process
those commands in parallel or reorder them as it requires. Strict
Order defaults to True. If a device does not support command
reordering or parallel processing, Strict Order = False has no
effect.
6.2. Soft Failure
When a device invokes a sub-behaviour, any condition check failure
and any directive failure causes the behaviour to immediately abort.
However, if the Soft Failure parameter is True, then an abort due to
a condition failure does not cause the sub-behaviour to report
failure. If the Soft Failure parameter is True, indicating hard
failure, then any abort causes the sub-behaviour to report failure as
well.
6.3. Source List
The source list is scoped to an individual component or dependency.
It is a prioritised search path for the Move command to use in order
Moran, et al. Expires September 12, 2019 [Page 11]
Internet-DraftBehavioural description of Firwmware Updates March 2019
to find an image or document. It can contain either local sources,
such as other components, or remote ones, such as URIs.
6.4. Processing Step Configurations
Many processing steps require configuration to operate, or
configuration informs whether or not to use them. Common processing
steps include symmetric cryptography, compression or decompression
operations, and packing or unpacking, for example relocation,
differential compression, or hex file interpretation.
Processing step configuration is scoped to an individual component or
document.
6.5. Image Identifier
In order to determine whether an image is present, the verify image
presence condition requires an identifier for the image. This could
be a version number or a cryptographic identity such as a digest.
7. ACLs/permissions
To manage permissions in documents, there are three models that can
be used.
First, the simplest model requires that all documents are
authenticated by a single identity. This mode has the advantage that
only a single document needs to be authenticated, since each
document's dependencies are uniquely identified in that document.
This simplest model can be extended by adding key delegation without
much increase in complexity.
A second model requires an ACL to be presented to the device,
authenticated by a trusted party or stored on the device. This ACL
grants access rights for specific Components or Component Groups to
the listed identities or identity groups. Any identity may verify
that an image is present, but Moving an image into or out of a
Component requires approval from the ACL.
A third model allows a Document Processor to provide even more fine-
grained controls: The ACL lists the Component or Component Group that
an identity may use, and also lists the commands that the identity
may use in combination with that Component/Group.
Moran, et al. Expires September 12, 2019 [Page 12]
Internet-DraftBehavioural description of Firwmware Updates March 2019
8. Workflows
The two most common workflows are image installation and image
invocation. Both of these workflows use a common component:
do_commands.
do_commands uses the following pseudocode:
function do_commands(section, sequence)
rc = SUCCESS
foreach (command in $sequence)
choose $command[Type]:
case Sub-Behaviour:
Load commands = $command[Argument][commands]
Load parameters = System Parameters
Load soft_failure = $parameters[Soft Failure]
Call rc = do_commands(commands)
if (soft_failure AND is_condition_failure(rc))
rc = SUCCESS
endif
endcase
case Process Dependency:
; Note Dependency selection can be done via argument or
; parameter. May process multiple dependencies in a list.
Load Dependency
Load common = $Dependency[Common Sequence]
Call rc = do_commands(Common, $common)
if (rc is SUCCESS?)
Load $sequence = $Dependency[$section]
Call rc = do_commands($section, $sequence)
endif
endcase
case Set Parameters:
Load parameter_list = $command[Argument][Parameter List]
foreach (parameter in parameter_list)
if (is_append(parameter)?)
Append argument value to $parameter
elseif (is_set($parameter[Name]))
Set $parameter[Name] = $parameter[Value]
endif
endfor
endcase
case Move:
; Note Component selection can be done via argument or
; parameter. May process multiple components in a list.
; Note Dependency selection can be done via argument or
; parameter. May process multiple dependencies in a list.
; Source
Moran, et al. Expires September 12, 2019 [Page 13]
Internet-DraftBehavioural description of Firwmware Updates March 2019
Load component_list = $command[Argument][Component List]
Load dependency_list = $command[Argument][Dependency List]
foreach (target_list in [component_list, dependency_list])
foreach (target in $target_list)
Load $target parameters
Set source = choose_best_source($parameters[Source List])
Acquire data from $source
foreach (processing_step in $parameters[Processing Step Configuration])
rc = Process_Data($processing_step, $data)
endfor
Store $data to $target
endfor
endfor
endcase
case Invoke:
; Note Component selection can be done via argument or
; parameter. May process multiple components in a list.
Select component
Load Argument = $command[Argument]
Transfer execution to $component with $Argument;
endcase
case Wait:
Load arguments = $command[Argument][Wait Arguments]
Load type = $command[Argument][Wait Type]
Wait ($type, $arguments)
endcase
case Device Identity:
; Note Device Identity selection can be done via argument or
; parameter. May process multiple Device Identities in a list.
Load device_identity = $parameters[Device Identity]
if ($device_identity is nil)
Load device_identity = $command[Argument][Device Identity]
endif
rc = Compare $device_identity to $parameters
endcase
case Image Present/not Present:
; Note Component selection can be done via argument or
; parameter. May process multiple components in a list.
; Note Dependency selection can be done via argument or
; parameter. May process multiple dependencies in a list.
Load component_list = $command[Argument][Component List]
Load dependency_list = $command[Argument][Dependency List]
foreach (target_list in [component_list, dependency_list])
foreach (target in $target_list)
Load $target parameters
Set image_identifier = $parameters[Image Identifier]
rc = Compare $component to $image_identifier;
endfor
Moran, et al. Expires September 12, 2019 [Page 14]
Internet-DraftBehavioural description of Firwmware Updates March 2019
endfor
endcase
case Verify Authorisation
Request authorisation
Wait for authorisation
rc = Check Response
endcase
endchoose
endwhile (no)
endfunction
Installation, is represented by the following pseudocode.
function install(Document)
Load $Document[Common Data] into parameters
foreach (sequence in [Common, Dependency Resolution, Image Acquisition, Image Application])
rc = do_commands($sequence, $Document[$sequence]);
if (rc is not SUCCESS)
Abort
endif
endfor
endfunction
Image invocation is represented by the following pseudocode.
function invoke(Document)
Load $Document[Common Data] into parameters
foreach (sequence in [Common, System Validation, Image Loading, Image Invocation])
rc = do_commands($sequence, $Document[$sequence]);
if (rc is not SUCCESS)
Abort
endif
endfor
endfunction
Each operation represented here is already present in a device
capable of firmware update or secure boot. This approach simply
defines the mechanism by which these operations are orchestrated, and
enforces that the behaviour of the system is defined by the
Behavioural Document, rather than implied by it.
9. Examples
These examples demonstrate the serialisation of the behaviours of an
update. They are serialised in JSON for readability, but JSON is not
recommended for use on constrained devices.
Moran, et al. Expires September 12, 2019 [Page 15]
Internet-DraftBehavioural description of Firwmware Updates March 2019
9.1. Example 1: Boot an image on an XIP processor
{
"structure-version" : 1,
"sequence-number" : 1,
"components": [
{
"id" : <Component Identifier>,
"digest":"<SHA256 of Image>",
"size" : <Size of Image>
}
],
"validate" : [
{
"condition-validate-image" : {"component" : 0}
}
],
"image-invocation" : [
{
"directive-run-component":{"component" : 0}
}
]
}
9.2. Example 2: Download an image
{
"structure-version" : 1,
"sequence-number" : 2,
"components": [
{
"id" : <Component Identifier>,
"digest":"<SHA256 of Image>",
"size" : <Size of Image>
}
],
"image-acquisition" : [
{
"directive-move" : {
"source": "http://example.com/file.bin",
"destination" : 0
}
}
]
}
Moran, et al. Expires September 12, 2019 [Page 16]
Internet-DraftBehavioural description of Firwmware Updates March 2019
9.3. Example 3: Check compatibility, download, and boot
{
"structure-version" : 1,
"sequence-number" : 3,
"components": [
{
"id" : <Component Identifier>,
"digest":"<SHA256 of Image>",
"size" : <Size of Image>
}
],
"common" : [
{"condition-vendor-id" : "fa6b4a53-d5ad-5fdf-be9d-e663e4d41ffe"},
{"condition-class-id" : "1492af14-2569-5e48-bf42-9b2d51f2ab45"}
],
"image-application" : [
{
"directive-move" : {
"source": "http://example.com/file.bin",
"destination" : 0
}
}
],
"validate" : [
{
"condition-validate-image" : {"component" : 0}
}
],
"image-invocation" : [
{
"directive-run-component":{"component" : 0}
}
]
}
9.4. Example 4: Check compatibility, download, load from external, and
boot
{
"structure-version" : 1,
"sequence-number" : 4,
"components": [
{
"id" : <Flash Component Identifier>,
"digest":"<SHA256 of Image>",
"size" : <Size of Image>
},
Moran, et al. Expires September 12, 2019 [Page 17]
Internet-DraftBehavioural description of Firwmware Updates March 2019
{
"id" : <RAM Component Identifier>,
"digest":"<SHA256 of Image>",
"size" : <Size of Image>
}
],
"common" : [
{"condition-vendor-id" : "fa6b4a53-d5ad-5fdf-be9d-e663e4d41ffe"},
{"condition-class-id" : "1492af14-2569-5e48-bf42-9b2d51f2ab45"}
],
"image-application" : [
{
"directive-move" : {
"source": "http://example.com/file.bin",
"destination" : 0
}
}
],
"validate" : [
{
"condition-validate-image" : {"component" : 0}
}
],
"load-image" : [
{
"directive-move" : {
"source": 0,
"destination" : 1
}
}
],
"image-invocation" : [
{
"condition-validate-image" : {"component" : 1}
},
{
"directive-run-component":{"component" : 1}
}
]
}
9.5. Example 5: Check compatibility, download, load with decompress,
and boot
{
"structure-version" : 1,
"sequence-number" : 5,
"components": [
Moran, et al. Expires September 12, 2019 [Page 18]
Internet-DraftBehavioural description of Firwmware Updates March 2019
{
"id" : <Flash Component Identifier>,
"digest":"<SHA256 of Compressed Image>",
"size" : <Size of Compressed Image>
},
{
"id" : <RAM Component Identifier>,
"digest":"<SHA256 of Image>",
"size" : <Size of Image>
}
],
"common" : [
{"condition-vendor-id" : "fa6b4a53-d5ad-5fdf-be9d-e663e4d41ffe"},
{"condition-class-id" : "1492af14-2569-5e48-bf42-9b2d51f2ab45"}
],
"image-application" : [
{
"directive-move" : {
"source": "http://example.com/file.bin",
"destination" : 0
}
}
],
"validate" : [
{
"condition-validate-image" : {"component" : 0}
}
],
"load-image" : [
{
"directive-move" : {
"source": 0,
"destination" : 1,
"processing-step-compression-algorithm" : "gzip"
}
}
],
"image-invocation" : [
{
"condition-validate-image" : {"component" : 1}
},
{
"directive-run-component":{"component" : 1}
}
]
}
Moran, et al. Expires September 12, 2019 [Page 19]
Internet-DraftBehavioural description of Firwmware Updates March 2019
9.6. Example 6: Check compatibility, download, install-from-external
and boot
{
"structure-version" : 1,
"sequence-number" : 6,
"components": [
{
"id" : <External Flash Component Identifier>,
"digest":"<SHA256 of Image>",
"size" : <Size of Image>
},
{
"id" : <Internal Flash Component Identifier>,
"digest":"<SHA256 of Image>",
"size" : <Size of Image>
}
],
"common" : [
{"condition-vendor-id" : "fa6b4a53-d5ad-5fdf-be9d-e663e4d41ffe"},
{"condition-class-id" : "1492af14-2569-5e48-bf42-9b2d51f2ab45"}
],
"image-acquisition" : [
{
"directive-move" : {
"source": "http://example.com/file.bin",
"destination" : 0
}
}
],
"validate" : [
{
"sub-behaviour" : [
"soft-failure" : True,
"condition-validate-not-image" : {"component" : 1}
"soft-failure" : False
"condition-validate-image" : {"component" : 0}
]
}
],
"load-image" : [
{
"sub-behaviour" : [
"soft-failure" : True,
"condition-validate-not-image" : {"component" : 1}
"soft-failure" : False
"directive-move" : {
"source": 0,
Moran, et al. Expires September 12, 2019 [Page 20]
Internet-DraftBehavioural description of Firwmware Updates March 2019
"destination" : 1
}
]
}
],
"image-invocation" : [
{
"condition-validate-image" : {"component" : 1}
},
{
"directive-run-component":{"component" : 1}
}
]
}
9.7. Example 7: Download and boot an image with a dependency
[
{
"structure-version" : 1,
"sequence-number" : 7,
"components": [
{
"id" : <Component Identifier 0>,
"digest":"<SHA256 of Image>",
"size" : <Size of Image>
}
],
"common" : [
{"condition-vendor-id" : "fa6b4a53-d5ad-5fdf-be9d-e663e4d41ffe"},
{"condition-class-id" : "1492af14-2569-5e48-bf42-9b2d51f2ab45"}
],
"image-application" : [
{
"directive-move" : {
"source": "http://example.com/file.bin",
"destination" : 0
}
}
],
"validate" : [
{
"condition-validate-image" : {"component" : 0}
}
],
"image-invocation" : [
{
"directive-run-component":{"component" : 0}
Moran, et al. Expires September 12, 2019 [Page 21]
Internet-DraftBehavioural description of Firwmware Updates March 2019
}
]
},
{
"structure-version" : 1,
"sequence-number" : 8,
"dependencies" : [
{
"digest" : "<SHA256 of Document 0>"
"components" : [<Component Identifier 0>]
}
],
"components": [
{
"id" : <Component Identifier 1>,
"digest":"<SHA256 of Image>",
"size" : <Size of Image>
}
],
"dependency-resolution" : [
{
"directive-move" : {
"source": "http://example.com/document0.bin",
"destination" : <Document 0 ID>
}
},
{
"condition-validate-image" : {"dependency" : 0}
},
],
"image-application" : [
{
"directive-move" : {
"source": "http://example.com/file1.bin",
"destination" : 1
}
},
{ "process-dependency" : 0 }
]
"validate" : [
{
"condition-validate-image" : {"dependency" : 0}
},
{ "process-dependency" : 0 },
{
"condition-validate-image" : {"image" : 1}
}
],
Moran, et al. Expires September 12, 2019 [Page 22]
Internet-DraftBehavioural description of Firwmware Updates March 2019
"image-invocation" : [
{ "process-dependency" : 0 }
]
}
]
9.8. Example 8: Download and boot an image with a dependency using
override.
Override fetch location for dependency.
[
{
"structure-version" : 1,
"sequence-number" : 7,
"components": [
{
"id" : <Component Identifier 0>,
"digest":"<SHA256 of Image>",
"size" : <Size of Image>
}
],
"common" : [
{"condition-vendor-id" : "fa6b4a53-d5ad-5fdf-be9d-e663e4d41ffe"},
{"condition-class-id" : "1492af14-2569-5e48-bf42-9b2d51f2ab45"}
],
"image-application" : [
{
"set-parameter" : {
"component" : 0
"source": "http://example.com/file.bin",
}
},
{
"directive-move" : {
"destination" : 0
}
}
],
"validate" : [
{
"condition-validate-image" : {"component" : 0}
}
],
"image-invocation" : [
{
"directive-run-component":{"component" : 0}
}
Moran, et al. Expires September 12, 2019 [Page 23]
Internet-DraftBehavioural description of Firwmware Updates March 2019
]
},
{
"structure-version" : 1,
"sequence-number" : 8,
"dependencies" : [
{
"digest" : "<SHA256 of Document 0>"
"components" : [<Component Identifier 0>]
}
],
"components": [
{
"id" : <Component Identifier 1>,
"digest":"<SHA256 of Image>",
"size" : <Size of Image>
}
],
"dependency-resolution" : [
{
"directive-move" : {
"source": "http://example.com/document0.bin",
"destination" : <Document 0 ID>
}
},
{
"condition-validate-image" : {"dependency" : 0}
},
],
"image-application" : [
{
"directive-move" : {
"source": "http://example.com/file1.bin",
"destination" : 1
}
},
{
"set-parameter" : {
"component" : 0
"source": "http://other-host.com/file.bin",
}
},
{ "process-dependency" : 0 }
]
"validate" : [
{
"condition-validate-image" : {"dependency" : 0}
},
Moran, et al. Expires September 12, 2019 [Page 24]
Internet-DraftBehavioural description of Firwmware Updates March 2019
{ "process-dependency" : 0 },
{
"condition-validate-image" : {"image" : 1}
}
],
"image-invocation" : [
{ "process-dependency" : 0 }
]
}
]
10. IANA Considerations
In any given serialisation of this approach, several registries will
be required for:
- Standard Commands
- Standard Parameters
This document requires no action from IANA.
11. Security Considerations
This document describes the distribution of firmware updates and the
invocation of complex behaviours on a device. As such, the contents
of a document following the described approach to updates MUST be
authenticated as described in Section 7. A more detailed discussion
about security can be found in the architecture document
[Architecture].
12. References
12.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
12.2. Informative References
[Architecture]
Moran, B., "A Firmware Update Architecture for Internet of
Things Devices", July 2018, <https://tools.ietf.org/html/
draft-ietf-suit-architecture-02>.
Moran, et al. Expires September 12, 2019 [Page 25]
Internet-DraftBehavioural description of Firwmware Updates March 2019
[Information]
Moran, B., "Firmware Updates for Internet of Things
Devices - An Information Model for Manifests", July 2018,
<https://tools.ietf.org/html/
draft-ietf-suit-information-model-02>.
12.3. URIs
[1] mailto:suit@ietf.org
[2] https://www1.ietf.org/mailman/listinfo/suit
[3] https://www.ietf.org/mail-archive/web/suit/current/index.html
Moran, et al. Expires September 12, 2019 [Page 26]
Internet-DraftBehavioural description of Firwmware Updates March 2019
Appendix A. Mailing List Information
The discussion list for this document is located at the e-mail
address suit@ietf.org [1]. Information on the group and information
on how to subscribe to the list is at
https://www1.ietf.org/mailman/listinfo/suit [2]
Archives of the list can be found at: https://www.ietf.org/mail-
archive/web/suit/current/index.html [3]
Authors' Addresses
Brendan Moran
ARM Limited
EMail: Brendan.Moran@arm.com
Tony Ibbs
ARM Limited
EMail: Tony.Ibbs@arm.com
George Psimenos
ARM Limited
Moran, et al. Expires September 12, 2019 [Page 27]
