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]