SUIT M. Pagel
Internet Draft Microsoft Corp
Intended status: Standards Track September 12, 2018
Expires: March 2018
A Binary Manifest Serialization Format
draft-pagel-suit-manifest-00
Abstract
This specification describes the serialization format of a software
update manifest that is suitable for low-end devices as it
eliminates the need to execute a parser.
A manifest is a metadata structure describing the firmware, the
devices to which it applies, and cryptographic information
protecting the 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), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet-
Drafts.
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."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html
This Internet-Draft will expire on March 12, 2019.
Pagel Expires March 12, 2019 [Page 1]
Internet-Draft Binary Manifest Format September 2018
Copyright Notice
Copyright (c) 2018 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
(http://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 the Trust Legal Provisions and are provided without
warranty as described in the Simplified BSD License.
Table of Contents
1. Introduction...................................................2
2. Pros and Cons vs CBOR based Format.............................5
3. Manifest Format in Detail......................................5
4. Security Considerations........................................8
4.1. MFSR1: Monotonic Sequence Numbers.........................8
4.2. MFSR2: Vendor, Device-type Identifiers....................8
4.3. MFSR3: Best-Before Timestamps.............................8
4.4. MFSR5: Cryptographic Authenticity.........................9
4.5. MFSR4a/b: Authenticated Payload Type and Storage Location.9
4.6. MFSR4c: Authenticated Remote Resource Location............9
4.7. MFSR4d: Secure Boot.......................................9
4.8. MFSR4e: Authenticated precursor images....................9
4.9. MFSR4f: Authenticated Vendor and Class IDs................9
4.10. MFSR6: Rights Require Authenticity.......................9
4.11. MFSR7: Firmware encryption..............................10
5. IANA Considerations...........................................10
6. Security Considerations.......................................10
7. Mailing List Information......................................10
8. References....................................................10
8.1. Normative References.....................................10
Author's Addresses...............................................11
1. Introduction
This document describes a binary format for secured, signed software
update "manifests" that is suitable for low-end devices as it
eliminates the need to execute a parser.
The SUIT architecture and information model are designed to maximize
flexibility. However, in the field we expect each platform provider
Pagel Expires March 12, 2019 [Page 2]
Internet-Draft Binary Manifest Format September 2018
to pick a single option to implement within their software stack to
keep code as small as possible. For example, basic devices typically
support only a single compression or crypto algorithm and associated
signature format. Therefore, the manifest used in the field does not
need to specify such algorithms as such decision have already been
made by the platform provider. SUIT compliant development tools or
Update Servers may need to support different options if they want to
target multiple device platforms.
We expect each device platform to maintain a set of policies
separate from the manifest, which may mandate certain software
layers and/or components to be present. The manifest format allows
for updating any number of software layers such as drivers,
operating systems, and application software. Each layer may consist
of multiple software components represented by an image of a
particular version of such component. Each such layer may be
provided and signed by a different vendor and combined into a
manifest set and (in footer) signed by the Network Operator as shown
below:
+------------------------------------------------+
| ManifestSet Header |
| +--------------------------------------------+ |
| | Manifest 1 Header | |
| | +----------------------------------------+ | |
| | | Component - Image 1 | | |
| | +----------------------------------------+ | |
| | ... | |
| | +----------------------------------------+ | |
| | | Component - Image n | | |
| | +----------------------------------------+ | |
| | Signature | |
| +--------------------------------------------+ |
| ... |
| +--------------------------------------------+ |
| | Manifest m | |
| +--------------------------------------------+ |
| Signature |
+------------------------------------------------+
Manifest Structure
Each platform may use a Type id number to identify the type of
component and pass such id in the Type parameter to the installer.
Each type may also imply a different payload format. The platform
may also mandate the order and location each component type gets are
installed. A location may be a specific memory partition or separate
Pagel Expires March 12, 2019 [Page 3]
Internet-Draft Binary Manifest Format September 2018
device such as an SD Card or might even mandate a certain base
memory address. A Flags parameter is provided for a vendor to pass
any options, such as location or preprocessing requirements, to the
device installer. The platform vendor would need to provide platform
specific specifications for the Type and Flags parameters.
To allow platform vendors to support multiple platforms and identify
such, it may use the ClassId parameter of the first manifest in a
set to identify the platform. Even more importantly, product
manufacturers use the ClassId of the last manifest in the set to
identify the specific model of product so that the installer can
ensure it uses the proper manifest file intended for the product and
such model also implies what platform it uses.
To meet privacy requirements, we recommend using transport layer
security / channel encryption.
At a bare minimum, a manifest describes a single software image to
run. However, manifests might expose richer information, like
versioning for application binary interfaces (ABI) or even
dependencies between components. These dependencies can be verified
before downloading or installing software. For example, an
application might depend on a particular version of an operating
system. Each component may expose ABIs and consume the ABIs of other
components. Each ABI would have a specific ABIType id associated
with it. To update components selectively, the manifest specifies a
full dependency graph for all components.
The Operator may deliver the latest manifests via broadcast or via
an Update Server. The device may call the Update Server with its
ClassId and current software configuration. The Update Server may
enforce update policies based on such configuration and deliver
different manifests accordingly. Policies may include enforcing a
certain update sequence, or throttling of installs, or selective
test installs, or location specific installs etc.
Rather than including the image URIs in the manifest, the manifest
includes only UUID based image descriptors called ImageUid. The
device installer receives the manifest and then compares the
ImageUids which are currently installed on the device with the ones
specified in the manifest and if any have changed, it may request
the URIs for those images for download and installation over the
network from the Update Server. The Update Server may use a one-
time or short-lived URL to limit the availability/distribution of
the image. The device may also send its location so that a content
distribution network could provide a copy from a nearby file or
content cache server, peer device, or in the field via USB
Pagel Expires March 12, 2019 [Page 4]
Internet-Draft Binary Manifest Format September 2018
thumbdrive. The images may also be received through a broadcast from
other devices. The signature of the manifest guarantees the
manifest's authenticity.
2. Pros and Cons vs CBOR based Format
CBOR makes it easier to handle and/or skip optional or new fields
whereas a binary structure requires a versioned structure to
introduce new fields, which adds complexity to the implementation.
However, the binary structure has the advantage that it can be
loaded into memory directly without the use of a parser and
therefore the installer code is much simpler or smaller. As
installers are a common source of bugs and vulnerabilities, simple
code is usually considered more secure. It addresses Section 3.6/7
of the architecture document (Small bootloader and parser) quite
well. Also, the separation of image URIs allows for a much smaller
manifest and therefore reduces memory requirements.
A basic device may not be able to support many options anyways and
such devices are more space constrained; the binary format may be a
better fit.
A more sophisticated device may offer more options and may use CBOR
for other purposes anyways, then the currently proposed format may
be more suitable.
3. Manifest Format in Detail
The following tables show the various fields of the manifest set
header and signature footer and each manifest with header, image
array, and signature footer and the image array with the embedded
dependency array. To allow for simple loading, the byte order of
numeric fields is considered specific to the platform.
ManifestSetHeader
Type Field Description
UInt32 MagicValue 0x7086760e acting as a
static file format signature
UInt16 Version 1 - Version of the manifest
set data structure
Pagel Expires March 12, 2019 [Page 5]
Internet-Draft Binary Manifest Format September 2018
UInt16 Flags Hints for device specific
policy engine, it can either
be interpreted as 16 flags,
integer value, or a
combination depending on the
device
UInt16 ManifestSetDataSize Size of the total set in
bytes
ManifestSetFooter
Type Field Description
UInt8[20] SignCertThumbprint Thumbprint of the cert
used to sign this
manifest. All zeros if the
manifest is unsigned.
UInt8[64] Signature Digital signature of all
the data prior to this
field using the signature
method specific to the
device/platform.
Manifest
Type Field Description
UInt16 Version Version of the manifest
data structure
UInt16 ImageCount Number of images in the
manifest
UInt16 ManifestEntrySize Size of each entry in
bytes, allows safe
interpretation even if
size changes due to data
structure version changes
Pagel Expires March 12, 2019 [Page 6]
Internet-Draft Binary Manifest Format September 2018
UInt8[16] VendorId UUID5(DNS, "example.com")
UInt8[16] ClassId UUID5(VendorId, "Product
X")
UInt64 BuildDate Manifest creation time in
unix epoch time
ImageManifes ImageEntries Entries for the images
tEntry[Image
Count]
UInt8[20] SignCertThumbprint Thumbprint of the cert
used to sign this
manifest. All zeros if the
manifest is unsigned.
UInt8[64] Signature Digital signature of all
the data prior to this
field using the signature
method specific to the
device/platform.
ImageManifestEntry
Type Field Description
UInt8[16] ImageUid Image UID
UInt8[16] ComponentUid UID of the
Component the
image
represents.
UInt16 Type Component Type
(values specific
to the device
architecture)
UInt32 CompressedImageFileSize Size of the
image file in
bytes as
compressed
Pagel Expires March 12, 2019 [Page 7]
Internet-Draft Binary Manifest Format September 2018
UInt32 UncompressedImageFileSize Size of the
image file in
bytes after it
is uncompressed
ABIDependency[2] Provides Lists any ABI
type and version
this component
provides
ABIDependency[2] DependsOn Lists any ABI
type and version
this component
it consumes
meaning depends
on
ABIDependency
Type Field Description
UInt32 Version Image UID
UInt32 ABIType Type of ABI interface
4. Security Considerations
This document is about a manifest format describing and protecting
firmware images and as such it is part of a larger solution for
offering a standardized way of delivering firmware updates to IoT
devices. A more detailed discussion about security can be found in
the architecture document [I-D.ietf-suit-architecture] and in the
information model document [I-D.ietf-suit-information-model]. The
next few sections address the specific security requirements as
defined in the information model:
4.1. MFSR1: Monotonic Sequence Numbers
The BuildDate may be used to enforce sequential updates. However,
there are often other methods (e.g., using a hardware root of trust
and e-fuses) to block the installation of compromised images.
Pagel Expires March 12, 2019 [Page 8]
Internet-Draft Binary Manifest Format September 2018
4.2. MFSR2: Vendor, Device-type Identifiers
The array of ImageUIDs provides the specific set of images which
need to be installed on the device.
4.3. MFSR3: Best-Before Timestamps
This requirement appears to be optional. In case you are concerned
about this case, an installer could enforce that a manifest is only
valid for a particular timeframe from the BuildDate. The Update
Server would re-sign (with a new BuildDate) close to the expiry
time.
4.4. MFSR5: Cryptographic Authenticity
Each manifest (and each image file) is signed.
4.5. MFSR4a/b: Authenticated Payload Type and Storage Location
Each image has a Type identifier. The device software uses its own
policy to determine which image types are supported and which
location they are installed. If a component can be installed in
various locations, the Flags parameter can be used to specify
preferred location.
4.6. MFSR4c: Authenticated Remote Resource Location
Once the manifest is processed and the images to update are
identified, the device may request a download location from an
Update Server.
4.7. MFSR4d: Secure Boot
We certainly encourage that both the installer and bootloader verify
the authenticity of the manifest.
4.8. MFSR4e: Authenticated precursor images
As IoT devices may not be able to connect to the Internet to receive
updates for a long period of time, we do not believe that sequential
installation is practical and therefore the current proposal does
not allow for this option. However, we do believe the proposal
contains enough flexibility that support could be added later
4.9. MFSR4f: Authenticated Vendor and Class IDs
Both the Vendor and Class Id are part of the signed manifest body.
Pagel Expires March 12, 2019 [Page 9]
Internet-Draft Binary Manifest Format September 2018
4.10. MFSR6: Rights Require Authenticity
Rights management is outside of the scope of the manifest format,
but a device or Update Server may enforce them.
4.11. MFSR7: Firmware encryption
A platform may mandate image encryption for any or all components.
If encryption is optional, the vendor may need to specify such fact
in the Flags parameter.
5. IANA Considerations
TBD
6. Security Considerations
This document is about a manifest format describing and protecting
firmware images and as such it is part of a larger solution for
offering a standardized way of delivering firmware updates to IoT
devices. A more detailed discussion about security can be found in
the architecture document [I-D.ietf-suit-architecture] and in the
information model document [I-D.ietf-suit-information-model].
7. 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
Archives of the list can be found at: https://www.ietf.org/mail-
archive/web/suit/current/index.html
8. References
8.1. Normative References
[I-D.ietf-suit-architecture]
Moran, B., Meriac, M., Tschofenig, H., and D. Brown, "A
Firmware Update Architecture for Internet of Things Devices",
draft-ietf-suit-architecture-01 (work in progress), July 2018.
[I-D.ietf-suit-information-model]
Pagel Expires March 12, 2019 [Page 10]
Internet-Draft Binary Manifest Format September 2018
Moran, B., Tschofenig, H., Birkholz, H., and J. Jimenez,
"Firmware Updates for Internet of Things Devices - An
Information Model for Manifests", draft-ietf-suit-information-
model-01 (work in progress), June 2018.
Author's Addresses
Martin Pagel
Microsoft Corp
Email: martin.pagel@microsoft.com
Pagel Expires March 12, 2019 [Page 11]