rfc9124.original   rfc9124.txt 
SUIT B. Moran Internet Engineering Task Force (IETF) B. Moran
Internet-Draft H. Tschofenig Request for Comments: 9124 H. Tschofenig
Intended status: Informational Arm Limited Category: Informational Arm Limited
Expires: January 9, 2022 H. Birkholz ISSN: 2070-1721 H. Birkholz
Fraunhofer SIT Fraunhofer SIT
July 08, 2021 January 2022
A Manifest Information Model for Firmware Updates in IoT Devices A Manifest Information Model for Firmware Updates in Internet of Things
draft-ietf-suit-information-model-13 (IoT) Devices
Abstract Abstract
Vulnerabilities with Internet of Things (IoT) devices have raised the Vulnerabilities with Internet of Things (IoT) devices have raised the
need for a reliable and secure firmware update mechanism that is also need for a reliable and secure firmware update mechanism that is also
suitable for constrained devices. Ensuring that devices function and suitable for constrained devices. Ensuring that devices function and
remain secure over their service life requires such an update remain secure over their service lifetime requires such an update
mechanism to fix vulnerabilities, to update configuration settings, mechanism to fix vulnerabilities, update configuration settings, and
as well as adding new functionality. add new functionality.
One component of such a firmware update is a concise and machine- One component of such a firmware update is a concise and machine-
processable meta-data document, or manifest, that describes the processable metadata document, or manifest, that describes the
firmware image(s) and offers appropriate protection. This document firmware image(s) and offers appropriate protection. This document
describes the information that must be present in the manifest. describes the information that must be present in the manifest.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This document is not an Internet Standards Track specification; it is
provisions of BCP 78 and BCP 79. published for informational purposes.
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 This document is a product of the Internet Engineering Task Force
and may be updated, replaced, or obsoleted by other documents at any (IETF). It represents the consensus of the IETF community. It has
time. It is inappropriate to use Internet-Drafts as reference received public review and has been approved for publication by the
material or to cite them other than as "work in progress." Internet Engineering Steering Group (IESG). Not all documents
approved by the IESG are candidates for any level of Internet
Standard; see Section 2 of RFC 7841.
This Internet-Draft will expire on January 9, 2022. Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
https://www.rfc-editor.org/info/rfc9124.
Copyright Notice Copyright Notice
Copyright (c) 2021 IETF Trust and the persons identified as the Copyright (c) 2022 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Revised BSD License text as described in Section 4.e of the
the Trust Legal Provisions and are provided without warranty as Trust Legal Provisions and are provided without warranty as described
described in the Simplified BSD License. in the Revised BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 1. Introduction
2. Requirements and Terminology . . . . . . . . . . . . . . . . 6 2. Requirements and Terminology
2.1. Requirements Notation . . . . . . . . . . . . . . . . . . 6 2.1. Requirements Notation
2.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 2.2. Terminology
3. Manifest Information Elements . . . . . . . . . . . . . . . . 6 3. Manifest Information Elements
3.1. Version ID of the Manifest Structure . . . . . . . . . . 7 3.1. Version ID of the Manifest Structure
3.2. Monotonic Sequence Number . . . . . . . . . . . . . . . . 7 3.2. Monotonic Sequence Number
3.3. Vendor ID . . . . . . . . . . . . . . . . . . . . . . . . 7 3.3. Vendor ID
3.4. Class ID . . . . . . . . . . . . . . . . . . . . . . . . 8 3.4. Class ID
3.4.1. Example 1: Different Classes . . . . . . . . . . . . 9 3.4.1. Example 1: Different Classes
3.4.2. Example 2: Upgrading Class ID . . . . . . . . . . . . 10 3.4.2. Example 2: Upgrading Class ID
3.4.3. Example 3: Shared Functionality . . . . . . . . . . . 10 3.4.3. Example 3: Shared Functionality
3.4.4. Example 4: White-labelling . . . . . . . . . . . . . 10 3.4.4. Example 4: Rebranding
3.5. Precursor Image Digest Condition . . . . . . . . . . . . 11 3.5. Precursor Image Digest Condition
3.6. Required Image Version List . . . . . . . . . . . . . . . 11 3.6. Required Image Version List
3.7. Expiration Time . . . . . . . . . . . . . . . . . . . . . 11 3.7. Expiration Time
3.8. Payload Format . . . . . . . . . . . . . . . . . . . . . 12 3.8. Payload Format
3.9. Processing Steps . . . . . . . . . . . . . . . . . . . . 12 3.9. Processing Steps
3.10. Storage Location . . . . . . . . . . . . . . . . . . . . 12 3.10. Storage Location
3.10.1. Example 1: Two Storage Locations . . . . . . . . . . 13 3.10.1. Example 1: Two Storage Locations
3.10.2. Example 2: File System . . . . . . . . . . . . . . . 13 3.10.2. Example 2: Filesystem
3.10.3. Example 3: Flash Memory . . . . . . . . . . . . . . 13 3.10.3. Example 3: Flash Memory
3.11. Component Identifier . . . . . . . . . . . . . . . . . . 13 3.11. Component Identifier
3.12. Payload Indicator . . . . . . . . . . . . . . . . . . . . 13 3.12. Payload Indicator
3.13. Payload Digests . . . . . . . . . . . . . . . . . . . . . 14 3.13. Payload Digests
3.14. Size . . . . . . . . . . . . . . . . . . . . . . . . . . 14 3.14. Size
3.15. Manifest Envelope Element: Signature . . . . . . . . . . 14 3.15. Manifest Envelope Element: Signature
3.16. Additional Installation Instructions . . . . . . . . . . 15 3.16. Additional Installation Instructions
3.17. Manifest text information . . . . . . . . . . . . . . . . 15 3.17. Manifest Text Information
3.18. Aliases . . . . . . . . . . . . . . . . . . . . . . . . . 15 3.18. Aliases
3.19. Dependencies . . . . . . . . . . . . . . . . . . . . . . 15 3.19. Dependencies
3.20. Encryption Wrapper . . . . . . . . . . . . . . . . . . . 16 3.20. Encryption Wrapper
3.21. XIP Address . . . . . . . . . . . . . . . . . . . . . . . 16 3.21. XIP Address
3.22. Load-time Metadata . . . . . . . . . . . . . . . . . . . 16 3.22. Load-Time Metadata
3.23. Run-time metadata . . . . . . . . . . . . . . . . . . . . 17 3.23. Runtime Metadata
3.24. Payload . . . . . . . . . . . . . . . . . . . . . . . . . 17 3.24. Payload
3.25. Manifest Envelope Element: Delegation Chain . . . . . . . 17 3.25. Manifest Envelope Element: Delegation Chain
4. Security Considerations . . . . . . . . . . . . . . . . . . . 18 4. Security Considerations
4.1. Threat Model . . . . . . . . . . . . . . . . . . . . . . 18 4.1. Threat Model
4.2. Threat Descriptions . . . . . . . . . . . . . . . . . . . 19 4.2. Threat Descriptions
4.2.1. THREAT.IMG.EXPIRED: Old Firmware . . . . . . . . . . 19 4.2.1. THREAT.IMG.EXPIRED: Old Firmware
4.2.2. THREAT.IMG.EXPIRED.OFFLINE : Offline device + Old 4.2.2. THREAT.IMG.EXPIRED.OFFLINE: Offline Device + Old
Firmware . . . . . . . . . . . . . . . . . . . . . . 19 Firmware
4.2.3. THREAT.IMG.INCOMPATIBLE: Mismatched Firmware . . . . 20 4.2.3. THREAT.IMG.INCOMPATIBLE: Mismatched Firmware
4.2.4. THREAT.IMG.FORMAT: The target device misinterprets 4.2.4. THREAT.IMG.FORMAT: The Target Device Misinterprets the
the type of payload . . . . . . . . . . . . . . . . . 20 Type of Payload
4.2.5. THREAT.IMG.LOCATION: The target device installs the 4.2.5. THREAT.IMG.LOCATION: The Target Device Installs the
payload to the wrong location . . . . . . . . . . . . 21 Payload to the Wrong Location
4.2.6. THREAT.NET.REDIRECT: Redirection to inauthentic 4.2.6. THREAT.NET.REDIRECT: Redirection to Inauthentic Payload
payload hosting . . . . . . . . . . . . . . . . . . . 21 Hosting
4.2.7. THREAT.NET.ONPATH: Traffic interception . . . . . . . 21 4.2.7. THREAT.NET.ONPATH: Traffic Interception
4.2.8. THREAT.IMG.REPLACE: Payload Replacement . . . . . . . 21 4.2.8. THREAT.IMG.REPLACE: Payload Replacement
4.2.9. THREAT.IMG.NON_AUTH: Unauthenticated Images . . . . . 22 4.2.9. THREAT.IMG.NON_AUTH: Unauthenticated Images
4.2.10. THREAT.UPD.WRONG_PRECURSOR: Unexpected Precursor 4.2.10. THREAT.UPD.WRONG_PRECURSOR: Unexpected Precursor Images
images . . . . . . . . . . . . . . . . . . . . . . . 22 4.2.11. THREAT.UPD.UNAPPROVED: Unapproved Firmware
4.2.11. THREAT.UPD.UNAPPROVED: Unapproved Firmware . . . . . 22 4.2.12. THREAT.IMG.DISCLOSURE: Reverse Engineering of Firmware
4.2.12. THREAT.IMG.DISCLOSURE: Reverse Engineering Of Image for Vulnerability Analysis
Firmware Image for Vulnerability Analysis . . . . . . 24
4.2.13. THREAT.MFST.OVERRIDE: Overriding Critical Manifest 4.2.13. THREAT.MFST.OVERRIDE: Overriding Critical Manifest
Elements . . . . . . . . . . . . . . . . . . . . . . 25 Elements
4.2.14. THREAT.MFST.EXPOSURE: Confidential Manifest Element 4.2.14. THREAT.MFST.EXPOSURE: Confidential Manifest Element
Exposure . . . . . . . . . . . . . . . . . . . . . . 25 Exposure
4.2.15. THREAT.IMG.EXTRA: Extra data after image . . . . . . 25 4.2.15. THREAT.IMG.EXTRA: Extra Data after Image
4.2.16. THREAT.KEY.EXPOSURE: Exposure of signing keys . . . . 25 4.2.16. THREAT.KEY.EXPOSURE: Exposure of Signing Keys
4.2.17. THREAT.MFST.MODIFICATION: Modification of manifest or 4.2.17. THREAT.MFST.MODIFICATION: Modification of Manifest or
payload prior to signing . . . . . . . . . . . . . . 26 Payload prior to Signing
4.2.18. THREAT.MFST.TOCTOU: Modification of manifest between 4.2.18. THREAT.MFST.TOCTOU: Modification of Manifest between
authentication and use . . . . . . . . . . . . . . . 26 Authentication and Use
4.3. Security Requirements . . . . . . . . . . . . . . . . . . 26 4.3. Security Requirements
4.3.1. REQ.SEC.SEQUENCE: Monotonic Sequence Numbers . . . . 27 4.3.1. REQ.SEC.SEQUENCE: Monotonic Sequence Numbers
4.3.2. REQ.SEC.COMPATIBLE: Vendor, Device-type Identifiers . 27 4.3.2. REQ.SEC.COMPATIBLE: Vendor, Device-Type Identifiers
4.3.3. REQ.SEC.EXP: Expiration Time . . . . . . . . . . . . 27 4.3.3. REQ.SEC.EXP: Expiration Time
4.3.4. REQ.SEC.AUTHENTIC: Cryptographic Authenticity . . . . 28 4.3.4. REQ.SEC.AUTHENTIC: Cryptographic Authenticity
4.3.5. REQ.SEC.AUTH.IMG_TYPE: Authenticated Payload Type . . 28 4.3.5. REQ.SEC.AUTH.IMG_TYPE: Authenticated Payload Type
4.3.6. Security Requirement REQ.SEC.AUTH.IMG_LOC: 4.3.6. REQ.SEC.AUTH.IMG_LOC: Authenticated Storage Location
Authenticated Storage Location . . . . . . . . . . . 28 4.3.7. REQ.SEC.AUTH.REMOTE_LOC: Authenticated Remote Payload
4.3.7. REQ.SEC.AUTH.REMOTE_LOC: Authenticated Remote Payload 29 4.3.8. REQ.SEC.AUTH.EXEC: Secure Execution
4.3.8. REQ.SEC.AUTH.EXEC: Secure Execution . . . . . . . . . 29 4.3.9. REQ.SEC.AUTH.PRECURSOR: Authenticated Precursor Images
4.3.9. REQ.SEC.AUTH.PRECURSOR: Authenticated precursor
images . . . . . . . . . . . . . . . . . . . . . . . 29
4.3.10. REQ.SEC.AUTH.COMPATIBILITY: Authenticated Vendor and 4.3.10. REQ.SEC.AUTH.COMPATIBILITY: Authenticated Vendor and
Class IDs . . . . . . . . . . . . . . . . . . . . . . 29 Class IDs
4.3.11. REQ.SEC.RIGHTS: Rights Require Authenticity . . . . . 29 4.3.11. REQ.SEC.RIGHTS: Rights Require Authenticity
4.3.12. REQ.SEC.IMG.CONFIDENTIALITY: Payload Encryption . . . 30 4.3.12. REQ.SEC.IMG.CONFIDENTIALITY: Payload Encryption
4.3.13. REQ.SEC.ACCESS_CONTROL: Access Control . . . . . . . 30 4.3.13. REQ.SEC.ACCESS_CONTROL: Access Control
4.3.14. REQ.SEC.MFST.CONFIDENTIALITY: Encrypted Manifests . . 31 4.3.14. REQ.SEC.MFST.CONFIDENTIALITY: Encrypted Manifests
4.3.15. REQ.SEC.IMG.COMPLETE_DIGEST: Whole Image Digest . . . 31 4.3.15. REQ.SEC.IMG.COMPLETE_DIGEST: Whole Image Digest
4.3.16. REQ.SEC.REPORTING: Secure Reporting . . . . . . . . . 31 4.3.16. REQ.SEC.REPORTING: Secure Reporting
4.3.17. REQ.SEC.KEY.PROTECTION: Protected storage of signing 4.3.17. REQ.SEC.KEY.PROTECTION: Protected Storage of Signing
keys . . . . . . . . . . . . . . . . . . . . . . . . 31 Keys
4.3.18. REQ.SEC.KEY.ROTATION: Protected storage of signing 4.3.18. REQ.SEC.KEY.ROTATION: Protected Storage of Signing Keys
keys . . . . . . . . . . . . . . . . . . . . . . . . 32 4.3.19. REQ.SEC.MFST.CHECK: Validate Manifests prior to
4.3.19. REQ.SEC.MFST.CHECK: Validate manifests prior to Deployment
deployment . . . . . . . . . . . . . . . . . . . . . 32 4.3.20. REQ.SEC.MFST.TRUSTED: Construct Manifests in a Trusted
4.3.20. REQ.SEC.MFST.TRUSTED: Construct manifests in a Environment
trusted environment . . . . . . . . . . . . . . . . . 32 4.3.21. REQ.SEC.MFST.CONST: Manifest Kept Immutable between
4.3.21. REQ.SEC.MFST.CONST: Manifest kept immutable between Check and Use
check and use . . . . . . . . . . . . . . . . . . . . 33 4.4. User Stories
4.4. User Stories . . . . . . . . . . . . . . . . . . . . . . 33
4.4.1. USER_STORY.INSTALL.INSTRUCTIONS: Installation 4.4.1. USER_STORY.INSTALL.INSTRUCTIONS: Installation
Instructions . . . . . . . . . . . . . . . . . . . . 33 Instructions
4.4.2. USER_STORY.MFST.FAIL_EARLY: Fail Early . . . . . . . 34 4.4.2. USER_STORY.MFST.FAIL_EARLY: Fail Early
4.4.3. USER_STORY.OVERRIDE: Override Non-Critical Manifest 4.4.3. USER_STORY.OVERRIDE: Override Non-critical Manifest
Elements . . . . . . . . . . . . . . . . . . . . . . 34 Elements
4.4.4. USER_STORY.COMPONENT: Component Update . . . . . . . 34 4.4.4. USER_STORY.COMPONENT: Component Update
4.4.5. USER_STORY.MULTI_AUTH: Multiple Authorizations . . . 35 4.4.5. USER_STORY.MULTI_AUTH: Multiple Authorizations
4.4.6. USER_STORY.IMG.FORMAT: Multiple Payload Formats . . . 35 4.4.6. USER_STORY.IMG.FORMAT: Multiple Payload Formats
4.4.7. USER_STORY.IMG.CONFIDENTIALITY: Prevent Confidential 4.4.7. USER_STORY.IMG.CONFIDENTIALITY: Prevent Confidential
Information Disclosures . . . . . . . . . . . . . . . 35 Information Disclosures
4.4.8. USER_STORY.IMG.UNKNOWN_FORMAT: Prevent Devices from 4.4.8. USER_STORY.IMG.UNKNOWN_FORMAT: Prevent Devices from
Unpacking Unknown Formats . . . . . . . . . . . . . . 35 Unpacking Unknown Formats
4.4.9. USER_STORY.IMG.CURRENT_VERSION: Specify Version 4.4.9. USER_STORY.IMG.CURRENT_VERSION: Specify Version Numbers
Numbers of Target Firmware . . . . . . . . . . . . . 36 of Target Firmware
4.4.10. USER_STORY.IMG.SELECT: Enable Devices to Choose 4.4.10. USER_STORY.IMG.SELECT: Enable Devices to Choose between
Between Images . . . . . . . . . . . . . . . . . . . 36 Images
4.4.11. USER_STORY.EXEC.MFST: Secure Execution Using 4.4.11. USER_STORY.EXEC.MFST: Secure Execution Using Manifests
Manifests . . . . . . . . . . . . . . . . . . . . . . 36 4.4.12. USER_STORY.EXEC.DECOMPRESS: Decompress on Load
4.4.12. USER_STORY.EXEC.DECOMPRESS: Decompress on Load . . . 36 4.4.13. USER_STORY.MFST.IMG: Payload in Manifest
4.4.13. USER_STORY.MFST.IMG: Payload in Manifest . . . . . . 36 4.4.14. USER_STORY.MFST.PARSE: Simple Parsing
4.4.14. USER_STORY.MFST.PARSE: Simple Parsing . . . . . . . . 37
4.4.15. USER_STORY.MFST.DELEGATION: Delegated Authority in 4.4.15. USER_STORY.MFST.DELEGATION: Delegated Authority in
Manifest . . . . . . . . . . . . . . . . . . . . . . 37 Manifest
4.4.16. USER_STORY.MFST.PRE_CHECK: Update Evaluation . . . . 37 4.4.16. USER_STORY.MFST.PRE_CHECK: Update Evaluation
4.4.17. USER_STORY.MFST.ADMINISTRATION: Administration of 4.4.17. USER_STORY.MFST.ADMINISTRATION: Administration of
manifests . . . . . . . . . . . . . . . . . . . . . . 37 Manifests
4.5. Usability Requirements . . . . . . . . . . . . . . . . . 37 4.5. Usability Requirements
4.5.1. REQ.USE.MFST.PRE_CHECK: Pre-Installation Checks . . . 37 4.5.1. REQ.USE.MFST.PRE_CHECK: Pre-installation Checks
4.5.2. REQ.USE.MFST.TEXT: Descriptive Manifest Information . 38 4.5.2. REQ.USE.MFST.TEXT: Descriptive Manifest Information
4.5.3. REQ.USE.MFST.OVERRIDE_REMOTE: Override Remote 4.5.3. REQ.USE.MFST.OVERRIDE_REMOTE: Override Remote Resource
Resource Location . . . . . . . . . . . . . . . . . . 38 Location
4.5.4. REQ.USE.MFST.COMPONENT: Component Updates . . . . . . 38 4.5.4. REQ.USE.MFST.COMPONENT: Component Updates
4.5.5. REQ.USE.MFST.MULTI_AUTH: Multiple authentications . . 39 4.5.5. REQ.USE.MFST.MULTI_AUTH: Multiple Authentications
4.5.6. REQ.USE.IMG.FORMAT: Format Usability . . . . . . . . 39 4.5.6. REQ.USE.IMG.FORMAT: Format Usability
4.5.7. REQ.USE.IMG.NESTED: Nested Formats . . . . . . . . . 40 4.5.7. REQ.USE.IMG.NESTED: Nested Formats
4.5.8. REQ.USE.IMG.VERSIONS: Target Version Matching . . . . 40 4.5.8. REQ.USE.IMG.VERSIONS: Target Version Matching
4.5.9. REQ.USE.IMG.SELECT: Select Image by Destination . . . 40 4.5.9. REQ.USE.IMG.SELECT: Select Image by Destination
4.5.10. REQ.USE.EXEC: Executable Manifest . . . . . . . . . . 41 4.5.10. REQ.USE.EXEC: Executable Manifest
4.5.11. REQ.USE.LOAD: Load-Time Information . . . . . . . . . 41 4.5.11. REQ.USE.LOAD: Load-Time Information
4.5.12. REQ.USE.PAYLOAD: Payload in Manifest Envelope . . . . 41 4.5.12. REQ.USE.PAYLOAD: Payload in Manifest Envelope
4.5.13. REQ.USE.PARSE: Simple Parsing . . . . . . . . . . . . 42 4.5.13. REQ.USE.PARSE: Simple Parsing
4.5.14. REQ.USE.DELEGATION: Delegation of Authority in 4.5.14. REQ.USE.DELEGATION: Delegation of Authority in Manifest
Manifest . . . . . . . . . . . . . . . . . . . . . . 42 5. IANA Considerations
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 42 6. References
6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 42 6.1. Normative References
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 43 6.2. Informative References
7.1. Normative References . . . . . . . . . . . . . . . . . . 43 Acknowledgements
7.2. Informative References . . . . . . . . . . . . . . . . . 44 Authors' Addresses
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 44
1. Introduction 1. Introduction
Vulnerabilities with Internet of Things (IoT) devices have raised the Vulnerabilities with Internet of Things (IoT) devices have raised the
need for a reliable and secure firmware update mechanism that is also need for a reliable and secure firmware update mechanism that is also
suitable for constrained devices. Ensuring that devices function and suitable for constrained devices. Ensuring that devices function and
remain secure over their service life requires such an update remain secure over their service lifetime requires such an update
mechanism to fix vulnerabilities, to update configuration settings, mechanism to fix vulnerabilities, update configuration settings, and
as well as adding new functionality. add new functionality.
One component of such a firmware update is a concise and machine- One component of such a firmware update is a concise and machine-
processable meta-data document, or manifest, that describes the processable metadata document, or manifest, that describes the
firmware image(s) and offers appropriate protection. This document firmware image(s) and offers appropriate protection. This document
describes the information that must be present in the manifest. describes the information that must be present in the manifest.
This document describes all the information elements required in a This document describes all the information elements required in a
manifest to secure firmware updates of IoT devices. Each information manifest to secure firmware updates of IoT devices. Each information
element is motiviated by user stories and threats it aims to element is motivated by user stories and threats it aims to mitigate.
mitigate. These threats and user stories are not intended to be an These threats and user stories are not intended to be an exhaustive
exhaustive list of the threats against IoT devices, nor of the list of the threats against IoT devices and possible user stories
possible user stories that describe how to conduct a firmware update. that describe how to conduct a firmware update. Instead, they are
Instead they are intended to describe the threats against firmware intended to describe the threats against firmware updates in
updates in isolation and provide sufficient motivation to specify the isolation and provide sufficient motivation to specify the
information elements that cover a wide range of user stories. information elements that cover a wide range of user stories.
To distinguish information elements from their encoding and To distinguish information elements from their encoding and
serialization over the wire this document presents an information serialization over the wire, this document presents an information
model. RFC 3444 [RFC3444] describes the differences between model. RFC 3444 [RFC3444] describes the differences between
information and data models. information models and data models.
Because this document covers a wide range of user stories and a wide Because this document covers a wide range of user stories and a wide
range of threats, not all information elements apply to all range of threats, not all information elements apply to all
scenarios. As a result, various information elements are optional to scenarios. As a result, various information elements are optional to
implement and optional to use, depending on which threats exist in a implement and optional to use, depending on which threats exist in a
particular domain of application and which user stories are important particular domain of application and which user stories are important
for deployments. for deployments.
2. Requirements and Terminology 2. Requirements and Terminology
2.1. Requirements Notation 2.1. Requirements Notation
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in "OPTIONAL" in this document are to be interpreted as described in
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
Unless otherwise stated these words apply to the design of the Unless otherwise stated, these words apply to the design of the
manifest format, not its implementation or application. Hence, manifest format, not its implementation or application. Hence,
whenever an information is declared as "REQUIRED" this implies that whenever an information element is declared as "REQUIRED", this
the manifest format document has to include support for it. implies that the manifest format document has to include support for
it.
2.2. Terminology 2.2. Terminology
This document uses terms defined in [I-D.ietf-suit-architecture]. This document uses terms defined in [RFC9019]. The term "Operator"
The term 'Operator' refers to both Device and Network Operator. refers to either a device operator or a network operator.
Secure time and secure clock refer to a set of requirements on time "Secure time" and "secure clock" refer to a set of requirements on
sources. For local time sources, this primarily means that the clock time sources. For local time sources, this primarily means that the
must be monotonically increasing, including across power cycles, clock must be monotonically increasing, including across power
firmware updates, etc. For remote time sources, the provided time cycles, firmware updates, etc. For remote time sources, the provided
must be both authenticated and guaranteed to be correct to within time must be both authenticated and guaranteed to be correct to
some predetermined bounds, whenever the time source is accessible. within some predetermined bounds, whenever the time source is
accessible.
The term Envelope is used to describe an encoding that allows the The term "Envelope" (or "Manifest Envelope") is used to describe an
bundling of a manifest with related information elements that are not encoding that allows the bundling of a manifest with related
directly contained within the manifest. information elements that are not directly contained within the
manifest.
The term Payload is used to describe the data that is delivered to a The term "payload" is used to describe the data that is delivered to
device during an update. This is distinct from a "firmware image", a device during an update. This is distinct from a "firmware image",
as described in [I-D.ietf-suit-architecture], because the payload is as described in [RFC9019], because the payload is often in an
often in an intermediate state, such as being encrypted, compressed intermediate state, such as being encrypted, compressed, and/or
and/or encoded as a differential update. The payload, taken in encoded as a differential update. The payload, taken in isolation,
isolation, is often not the final firmware image. is often not the final firmware image.
3. Manifest Information Elements 3. Manifest Information Elements
Each manifest information element is anchored in a security Each manifest information element is anchored in a security
requirement or a usability requirement. The manifest elements are requirement or a usability requirement. The manifest elements are
described below, justified by their requirements. described below, justified by their requirements.
3.1. Version ID of the Manifest Structure 3.1. Version ID of the Manifest Structure
An identifier that describes which iteration of the manifest format This is an identifier that describes which iteration of the manifest
is contained in the structure. This allows devices to identify the format is contained in the structure. This allows devices to
version of the manifest data model that is in use. identify the version of the manifest data model that is in use.
This element is REQUIRED. This element is REQUIRED.
3.2. Monotonic Sequence Number 3.2. Monotonic Sequence Number
A monotonically increasing (unsigned) sequence number to prevent This element provides a monotonically increasing (unsigned) sequence
malicious actors from reverting a firmware update against the number to prevent malicious actors from reverting a firmware update
policies of the relevant authority. This number must not wrap against the policies of the relevant authority. This number must not
around. wrap around.
For convenience, the monotonic sequence number may be a UTC For convenience, the monotonic sequence number may be a UTC
timestamp. This allows global synchronisation of sequence numbers timestamp. This allows global synchronization of sequence numbers
without any additional management. without any additional management.
This element is REQUIRED. This element is REQUIRED.
Implements: REQ.SEC.SEQUENCE (Section 4.3.1) Implements: REQ.SEC.SEQUENCE (Section 4.3.1)
3.3. Vendor ID 3.3. Vendor ID
The Vendor ID element helps to distinguish between identically named The Vendor ID element helps to distinguish between identically named
products from different vendors. Vendor ID is not intended to be a products from different vendors. The Vendor ID is not intended to be
human-readable element. It is intended for binary match/mismatch a human-readable element. It is intended for binary match/mismatch
comparison only. comparison only.
Recommended practice is to use [RFC4122] version 5 UUIDs with the Recommended practice is to use version 5 Universally Unique
vendor's domain name and the DNS name space ID. Other options Identifiers (UUIDs) [RFC4122] with the vendor's domain name and the
include type 1 and type 4 UUIDs. DNS name space ID. Other options include type 1 and type 4 UUIDs.
Fixed-size binary identifiers are preferred because they are simple Fixed-size binary identifiers are preferred because they are simple
to match, unambiguous in length, explicitly non-parsable, and require to match, unambiguous in length, explicitly non-parsable, and require
no issuing authority. Guaranteed unique integers are preferred no issuing authority. Guaranteed unique integers are preferred
because they are small and simple to match, however they may not be because they are small and simple to match; however, they may not be
fixed length and they may require an issuing authority to ensure fixed length, and they may require an issuing authority to ensure
uniqueness. Free-form text is avoided because it is variable-length, uniqueness. Free-form text is avoided because it is variable length,
prone to error, and often requires parsing outside the scope of the prone to error, and often requires parsing outside the scope of the
manifest serialization. manifest serialization.
If human-readable content is required, it SHOULD be contained in a If human-readable content is required, it SHOULD be contained in a
separate manifest information element: Manifest text information separate manifest information element: Manifest Text Information
(Section 3.17) (Section 3.17).
This element is RECOMMENDED. This element is RECOMMENDED.
Implements: REQ.SEC.COMPATIBLE (Section 4.3.2), Implements: REQ.SEC.COMPATIBLE (Section 4.3.2),
REQ.SEC.AUTH.COMPATIBILITY (Section 4.3.10). REQ.SEC.AUTH.COMPATIBILITY (Section 4.3.10)
Here is an example for a domain name-based UUID. Vendor A creates a Here is an example for a domain-name-based UUID. Vendor A creates a
UUID based on a domain name it controls, such as vendorId = UUID based on a domain name it controls, such as vendorId =
UUID5(DNS, "vendor-a.example") UUID5(DNS, "vendor-a.example").
Because the DNS infrastructure prevents multiple registrations of the Because the DNS infrastructure prevents multiple registrations of the
same domain name, this UUID is (with very high probability) same domain name, this UUID is (with very high probability)
guaranteed to be unique. Because the domain name is known, this UUID guaranteed to be unique. Because the domain name is known, this UUID
is reproducible. Type 1 and type 4 UUIDs produce similar guarantees is reproducible. Type 1 and type 4 UUIDs produce similar guarantees
of uniqueness, but not reproducibility. of uniqueness, but not reproducibility.
This approach creates a contention when a vendor changes its name or This approach creates a contention when a vendor changes its name or
relinquishes control of a domain name. In this scenario, it is relinquishes control of a domain name. In this scenario, it is
possible that another vendor would start using that same domain name. possible that another vendor would start using that same domain name.
However, this UUID is not proof of identity; a device's trust in a However, this UUID is not proof of identity; a device's trust in a
vendor must be anchored in a cryptographic key, not a UUID. vendor must be anchored in a cryptographic key, not a UUID.
3.4. Class ID 3.4. Class ID
A device "Class" is a set of different device types that can accept A device "Class" is a set of different device types that can accept
the same firmware update without modification. It thereby allows the same firmware update without modification. It thereby allows
devices to determine applicability of a firmware in an unambiguous devices to determine the applicability of the firmware in an
way. Class IDs must be unique within the scope of a Vendor ID. This unambiguous way. Class IDs must be unique within the scope of a
is to prevent similarly, or identically named devices colliding in Vendor ID. This is to prevent similarly or identically named devices
their customer's infrastructure. from colliding in their customer's infrastructure.
Recommended practice is to use [RFC4122] version 5 UUIDs with as much Recommended practice is to use version 5 UUIDs [RFC4122] with as much
information as necessary to define firmware compatibility. Possible information as necessary to define firmware compatibility. Possible
information used to derive the class UUID includes: information used to derive the Class ID UUID includes:
o model name or number * Model name or number
o hardware revision * Hardware revision
o runtime library version * Runtime library version
o bootloader version * Bootloader version
o ROM revision * ROM revision
o silicon batch number * Silicon batch number
The Class ID UUID should use the Vendor ID as the name space The Class ID UUID should use the Vendor ID as the name space
identifier. Classes may be more fine-grained granular than is identifier. Classes may be more fine-grained than is required to
required to identify firmware compatibility. Classes must not be identify firmware compatibility. Classes must not be less granular
less granular than is required to identify firmware compatibility. than is required to identify firmware compatibility. Devices may
Devices may have multiple Class IDs. have multiple Class IDs.
Class ID is not intended to be a human-readable element. It is The Class ID is not intended to be a human-readable element. It is
intended for binary match/mismatch comparison only. A manifest intended for binary match/mismatch comparison only. A manifest
serialization SHOULD NOT permit free-form text content to be used for serialization SHOULD NOT permit free-form text content to be used for
Class ID. A fixed-size binary identifier SHOULD be used. the Class ID. A fixed-size binary identifier SHOULD be used.
Some organizations desire to keep the same product naming across Some organizations desire to keep the same product naming across
multiple, incompatible hardware revisions for ease of user multiple, incompatible hardware revisions for ease of user
experience. If this naming is propagated into the firmware, then experience. If this naming is propagated into the firmware, then
matching a specific hardware version becomes a challenge. An opaque, matching a specific hardware version becomes a challenge. An opaque,
non-readable binary identifier has no naming implications and so is non-readable binary identifier has no naming implications and so is
more likely to be usable for distinguishing among incompatible device more likely to be usable for distinguishing among incompatible device
groupings, regardless of naming. groupings, regardless of naming.
Fixed-size binary identifiers are preferred because they are simple Fixed-size binary identifiers are preferred because they are simple
to match, unambiguous in length, opaque and free from naming to match, unambiguous in length, opaque and free from naming
implications, and explicitly non-parsable. Free-form text is avoided implications, and explicitly non-parsable. Free-form text is avoided
because it is variable-length, prone to error, often requires parsing because it is variable length, prone to error, often requires parsing
outside the scope of the manifest serialization, and may be outside the scope of the manifest serialization, and may be
homogenized across incompatible device groupings. homogenized across incompatible device groupings.
If Class ID is not implemented, then each logical device class must If the Class ID is not implemented, then each logical device class
use a unique trust anchor for authorization. must use a unique trust anchor for authorization.
This element is RECOMMENDED. This element is RECOMMENDED.
Implements: Security Requirement REQ.SEC.COMPATIBLE (Section 4.3.2), Implements: REQ.SEC.COMPATIBLE (Section 4.3.2),
REQ.SEC.AUTH.COMPATIBILITY (Section 4.3.10). REQ.SEC.AUTH.COMPATIBILITY (Section 4.3.10)
3.4.1. Example 1: Different Classes 3.4.1. Example 1: Different Classes
Vendor A creates product Z and product Y. The firmware images of Vendor A creates Product Z and Product Y. The firmware images of
products Z and Y are not interchangeable. Vendor A creates UUIDs as Products Z and Y are not interchangeable. Vendor A creates UUIDs as
follows: follows:
o vendorId = UUID5(DNS, "vendor-a.example") * vendorId = UUID5(DNS, "vendor-a.example")
o ZclassId = UUID5(vendorId, "Product Z") * ZclassId = UUID5(vendorId, "Product Z")
o YclassId = UUID5(vendorId, "Product Y") * YclassId = UUID5(vendorId, "Product Y")
This ensures that Vendor A's Product Z cannot install firmware for This ensures that Vendor A's Product Z cannot install firmware for
Product Y and Product Y cannot install firmware for Product Z. Product Y and Product Y cannot install firmware for Product Z.
3.4.2. Example 2: Upgrading Class ID 3.4.2. Example 2: Upgrading Class ID
Vendor A creates product X. Later, Vendor A adds a new feature to Vendor A creates Product X. Later, Vendor A adds a new feature to
product X, creating product X v2. Product X requires a firmware Product X, creating Product X v2. Product X requires a firmware
update to work with firmware intended for product X v2. update to work with firmware intended for Product X v2.
Vendor A creates UUIDs as follows: Vendor A creates UUIDs as follows:
o vendorId = UUID5(DNS, "vendor-a.example") * vendorId = UUID5(DNS, "vendor-a.example")
o XclassId = UUID5(vendorId, "Product X") * XclassId = UUID5(vendorId, "Product X")
o Xv2classId = UUID5(vendorId, "Product X v2") * Xv2classId = UUID5(vendorId, "Product X v2")
When product X receives the firmware update necessary to be When Product X receives the firmware update necessary to be
compatible with product X v2, part of the firmware update changes the compatible with Product X v2, part of the firmware update changes the
class ID to Xv2classId. Class ID to Xv2classId.
3.4.3. Example 3: Shared Functionality 3.4.3. Example 3: Shared Functionality
Vendor A produces two products, product X and product Y. These Vendor A produces two products: Product X and Product Y. These
components share a common core (such as an operating system), but components share a common core (such as an operating system (OS)) but
have different applications. The common core and the applications have different applications. The common core and the applications
can be updated independently. To enable X and Y to receive the same can be updated independently. To enable X and Y to receive the same
common core update, they require the same class ID. To ensure that common core update, they require the same Class ID. To ensure that
only product X receives application X and only product Y receives only Product X receives Application X and only Product Y receives
application Y, product X and product Y must have different class IDs. Application Y, Product X and Product Y must have different Class IDs.
The vendor creates Class IDs as follows: The vendor creates Class IDs as follows:
o vendorId = UUID5(DNS, "vendor-a.example") * vendorId = UUID5(DNS, "vendor-a.example")
o XclassId = UUID5(vendorId, "Product X") * XclassId = UUID5(vendorId, "Product X")
o YclassId = UUID5(vendorId, "Product Y") * YclassId = UUID5(vendorId, "Product Y")
o CommonClassId = UUID5(vendorId, "common core") * CommonClassId = UUID5(vendorId, "common core")
Product X matches against both XclassId and CommonClassId. Product Y Product X matches against both XclassId and CommonClassId. Product Y
matches against both YclassId and CommonClassId. matches against both YclassId and CommonClassId.
3.4.4. Example 4: White-labelling 3.4.4. Example 4: Rebranding
Vendor A creates a product A and its firmware. Vendor B sells the Vendor A creates a Product A and its firmware. Vendor B sells the
product under its own name as Product B with some customised product under its own name as Product B with some customized
configuration. The vendors create the Class IDs as follows: configuration. The vendors create the Class IDs as follows:
o vendorIdA = UUID5(DNS, "vendor-a.example") * vendorIdA = UUID5(DNS, "vendor-a.example")
o classIdA = UUID5(vendorIdA, "Product A-Unlabelled")
o vendorIdB = UUID5(DNS, "vendor-b.example") * classIdA = UUID5(vendorIdA, "Product A-Unlabeled")
o classIdB = UUID5(vendorIdB, "Product B") * vendorIdB = UUID5(DNS, "vendor-b.example")
The product will match against each of these class IDs. If Vendor A * classIdB = UUID5(vendorIdB, "Product B")
The product will match against each of these Class IDs. If Vendor A
and Vendor B provide different components for the device, the and Vendor B provide different components for the device, the
implementor may choose to make ID matching scoped to each component. implementor may choose to make ID matching scoped to each component.
Then, the vendorIdA, classIdA match the component ID supplied by Then, the vendorIdA, classIdA match the component ID supplied by
Vendor A, and the vendorIdB, classIdB match the component ID supplied Vendor A, and the vendorIdB, classIdB match the component ID supplied
by Vendor B. by Vendor B.
3.5. Precursor Image Digest Condition 3.5. Precursor Image Digest Condition
This element provides information about the payload that needs to be This element provides information about the payload that needs to be
present on the device for an update to apply. This may, for example, present on the device for an update to apply. This may, for example,
be the case with differential updates. be the case with differential updates.
This element is OPTIONAL. This element is OPTIONAL.
Implements: REQ.SEC.AUTH.PRECURSOR (Section 4.3.9) Implements: REQ.SEC.AUTH.PRECURSOR (Section 4.3.9)
3.6. Required Image Version List 3.6. Required Image Version List
Payloads may only be applied to a specific firmware version or Payloads may only be applied to a specific firmware version or
firmware versions. For example, a payload containing a differential multiple firmware versions. For example, a payload containing a
update may be applied only to a specific firmware version. differential update may be applied only to a specific firmware
version.
When a payload applies to multiple versions of a firmware, the When a payload applies to multiple versions of firmware, the required
required image version list specifies which firmware versions must be image version list specifies which firmware versions must be present
present for the update to be applied. This allows the update author for the update to be applied. This allows the update author to
to target specific versions of firmware for an update, while target specific versions of firmware for an update, while excluding
excluding those to which it should not or cannot be applied. those to which it should not or cannot be applied.
This element is OPTIONAL. This element is OPTIONAL.
Implements: REQ.USE.IMG.VERSIONS (Section 4.5.8) Implements: REQ.USE.IMG.VERSIONS (Section 4.5.8)
3.7. Expiration Time 3.7. Expiration Time
This element tells a device the time at which the manifest expires This element tells a device the time at which the manifest expires
and should no longer be used. This element should be used where a and should no longer be used. This element should be used where a
secure source of time is provided and firmware is intended to expire secure source of time is provided and firmware is intended to expire
predictably. This element may also be displayed (e.g. via an app) predictably. This element may also be displayed (e.g., via an app)
for user confirmation since users typically have a reliable knowledge for user confirmation, since users typically have a reliable
of the date. knowledge of the date.
Special consideration is required for end-of-life if a firmware will Special consideration is required for end-of-life if firmware will
not be updated again, for example if a business stops issuing updates not be updated again -- for example, if a business stops issuing
to a device. In this case the last valid firmware should not have an updates to a device. In this case, the last valid firmware should
expiration time. not have an expiration time.
This element is OPTIONAL. This element is OPTIONAL.
Implements: REQ.SEC.EXP (Section 4.3.3) Implements: REQ.SEC.EXP (Section 4.3.3)
3.8. Payload Format 3.8. Payload Format
This element describes the payload format within the signed metadata. This element describes the payload format within the signed metadata.
It is used to enable devices to decode payloads correctly. It is used to enable devices to decode payloads correctly.
This element is REQUIRED. This element is REQUIRED.
Implements: REQ.SEC.AUTH.IMG_TYPE (Section 4.3.5), REQ.USE.IMG.FORMAT Implements: REQ.SEC.AUTH.IMG_TYPE (Section 4.3.5),
(Section 4.5.6) REQ.USE.IMG.FORMAT (Section 4.5.6)
3.9. Processing Steps 3.9. Processing Steps
A representation of the Processing Steps required to decode a This element provides a representation of the processing steps
payload, in particular those that are compressed, packed, or required to decode a payload -- in particular, those that are
encrypted. The representation must describe which algorithms are compressed, packed, or encrypted. The representation must describe
used and must convey any additional parameters required by those which algorithms are used and must convey any additional parameters
algorithms. required by those algorithms.
A Processing Step may indicate the expected digest of the payload A processing step may indicate the expected digest of the payload
after the processing is complete. after the processing is complete.
This element is RECOMMENDED. This element is RECOMMENDED.
Implements: REQ.USE.IMG.NESTED (Section 4.5.7) Implements: REQ.USE.IMG.NESTED (Section 4.5.7)
3.10. Storage Location 3.10. Storage Location
This element tells the device where to store a payload within a given This element tells the device where to store a payload within a given
component. The device can use this to establish which permissions component. The device can use this to establish which permissions
are necessary and the physical storage location to use. are necessary and the physical storage location to use.
This element is REQUIRED. This element is REQUIRED.
Implements: REQ.SEC.AUTH.IMG_LOC (Section 4.3.6) Implements: REQ.SEC.AUTH.IMG_LOC (Section 4.3.6)
3.10.1. Example 1: Two Storage Locations 3.10.1. Example 1: Two Storage Locations
A device supports two components: an OS and an application. These A device supports two components: an OS and an application. These
components can be updated independently, expressing dependencies to components can be updated independently, expressing dependencies to
ensure compatibility between the components. The Author chooses two ensure compatibility between the components. The author chooses two
storage identifiers: storage identifiers:
o "OS" * "OS"
o "APP" * "APP"
3.10.2. Example 2: File System 3.10.2. Example 2: Filesystem
A device supports a full-featured filesystem. The Author chooses to A device supports a full-featured filesystem. The author chooses to
use the storage identifier as the path at which to install the use the storage identifier as the path at which to install the
payload. The payload may be a tarball, in which case, it unpacks the payload. The payload may be a tarball, in which case it unpacks the
tarball into the specified path. tarball into the specified path.
3.10.3. Example 3: Flash Memory 3.10.3. Example 3: Flash Memory
A device supports flash memory. The Author chooses to make the A device supports flash memory. The author chooses to make the
storage identifier the offset where the image should be written. storage identifier the offset where the image should be written.
3.11. Component Identifier 3.11. Component Identifier
In a device with more than one storage subsystem, a storage In a device with more than one storage subsystem, a storage
identifier is insufficient to identify where and how to store a identifier is insufficient to identify where and how to store a
payload. To resolve this, a component identifier indicates to which payload. To resolve this, a component identifier indicates to which
part of the storage subsystem the payload shall be placed. part of the storage subsystem the payload shall be placed.
A serialization may choose to combine Component Identifier and A serialization may choose to combine the use of a component
Storage Location (Section 3.10). identifier and storage location (Section 3.10).
This element is OPTIONAL. This element is OPTIONAL.
Implements: REQ.USE.MFST.COMPONENT (Section 4.5.4) Implements: REQ.USE.MFST.COMPONENT (Section 4.5.4)
3.12. Payload Indicator 3.12. Payload Indicator
This element provides the information required for the device to This element provides the information required for the device to
acquire the payload. This functionality is only needed when the acquire the payload. This functionality is only needed when the
target device does not intrinsically know where to find the payload. target device does not intrinsically know where to find the payload.
This can be encoded in several ways: This can be encoded in several ways:
o One URI * One URI
o A list of URIs * A list of URIs
o A prioritised list of URIs
o A list of signed URIs * A prioritized list of URIs
* A list of signed URIs
This element is OPTIONAL. This element is OPTIONAL.
Implements: REQ.SEC.AUTH.REMOTE_LOC (Section 4.3.7) Implements: REQ.SEC.AUTH.REMOTE_LOC (Section 4.3.7)
3.13. Payload Digests 3.13. Payload Digests
This element contains one or more digests of one or more payloads. This element contains one or more digests of one or more payloads.
This allows the target device to ensure authenticity of the This allows the target device to ensure authenticity of the
payload(s) when combined with the Signature (Section 3.15) element. payload(s) when combined with the Signature (Section 3.15) element.
A manifest format must provide a mechanism to select one payload from A manifest format must provide a mechanism to select one payload from
a list based on system parameters, such as Execute-In-Place a list based on system parameters, such as an execute-in-place (XIP)
Installation Address. installation address.
This element is REQUIRED. Support for more than one digest is This element is REQUIRED. Support for more than one digest is
OPTIONAL. OPTIONAL.
Implements: REQ.SEC.AUTHENTIC (Section 4.3.4), REQ.USE.IMG.SELECT Implements: REQ.SEC.AUTHENTIC (Section 4.3.4), REQ.USE.IMG.SELECT
(Section 4.5.9) (Section 4.5.9)
3.14. Size 3.14. Size
The size of the payload in bytes, which informs the target device how This element provides the size of the payload in bytes, which informs
big of a payload to expect. Without it, devices are exposed to some the target device how big of a payload to expect. Without it,
classes of denial of service attack. devices are exposed to some classes of denial-of-service attacks.
This element is REQUIRED. This element is REQUIRED.
Implements: REQ.SEC.AUTH.EXEC (Section 4.3.8) Implements: REQ.SEC.AUTH.EXEC (Section 4.3.8)
3.15. Manifest Envelope Element: Signature 3.15. Manifest Envelope Element: Signature
The Signature element contains all the information necessary to The signature element contains all the information necessary to
protect the contents of the manifest against modification and to protect the contents of the manifest against modification and to
offer authentication of the signer. Because the Signature element offer authentication of the signer. Because the signature element
authenticates the manifest, it cannot be contained within the authenticates the manifest, it cannot be contained within the
manifest. Instead, the manifest is either contained within the manifest. Instead, either the manifest is contained within the
signature element, or the signature element is a member of the signature element or the signature element is a member of the
Manifest Envelope and bundled with the manifest. Manifest Envelope and bundled with the manifest.
The Signature element represents the foundation of all security The signature element represents the foundation of all security
properties of the manifest. Manifests, which are included as properties of the manifest. Manifests, which are included as
dependencies by another manifests, should include a signature so that dependencies by other manifests, should include a signature so that
the recipient can distinguish between different actors with different the recipient can distinguish between different actors with different
permissions. permissions.
The Signature element must support multiple signers and multiple The signature element must support multiple signers and multiple
signing algorithms. A manifest format may allow multiple manifests signing algorithms. A manifest format may allow multiple manifests
to be covered by a single Signature element. to be covered by a single signature element.
This element is REQUIRED in non-dependency manifests. This element is REQUIRED in non-dependency manifests.
Implements: REQ.SEC.AUTHENTIC (Section 4.3.4), REQ.SEC.RIGHTS Implements: REQ.SEC.AUTHENTIC (Section 4.3.4), REQ.SEC.RIGHTS
(Section 4.3.11), REQ.USE.MFST.MULTI_AUTH (Section 4.5.5) (Section 4.3.11), REQ.USE.MFST.MULTI_AUTH (Section 4.5.5)
3.16. Additional Installation Instructions 3.16. Additional Installation Instructions
Additional installation instructions are machine-readable commands Additional installation instructions are machine-readable commands
the device should execute when processing the manifest. This the device should execute when processing the manifest. This
information is distinct from the information necessary to process a information is distinct from the information necessary to process a
payload. Additional installation instructions include information payload. Additional installation instructions include information
such as update timing (for example, install only on Sunday, at 0200), such as update timing (for example, install only on Sunday, at 0200),
procedural considerations (for example, shut down the equipment under procedural considerations (for example, shut down the equipment under
control before executing the update), pre- and post-installation control before executing the update), and pre- and post-installation
steps (for example, run a script). Other installation instructions steps (for example, run a script). Other installation instructions
could include requesting user confirmation before installing. could include requesting user confirmation before installing.
This element is OPTIONAL. This element is OPTIONAL.
Implements: REQ.USE.MFST.PRE_CHECK (Section 4.5.1) Implements: REQ.USE.MFST.PRE_CHECK (Section 4.5.1)
3.17. Manifest text information 3.17. Manifest Text Information
Textual information pertaining to the update described by the This is textual information pertaining to the update described by the
manifest. This information is for human consumption only. It MUST manifest. This information is for human consumption only. It MUST
NOT be the basis of any decision made by the recipient. NOT be the basis of any decision made by the recipient.
Implements: REQ.USE.MFST.TEXT (Section 4.5.2) This element is OPTIONAL.
Implements: REQ.USE.MFST.TEXT (Section 4.5.2)
3.18. Aliases 3.18. Aliases
A mechanism for a manifest to augment or replace URIs or URI lists Aliases provide a mechanism for a manifest to augment or replace URIs
defined by one or more of its dependencies. or URI lists defined by one or more of its dependencies.
This element is OPTIONAL. This element is OPTIONAL.
Implements: REQ.USE.MFST.OVERRIDE_REMOTE (Section 4.5.3) Implements: REQ.USE.MFST.OVERRIDE_REMOTE (Section 4.5.3)
3.19. Dependencies 3.19. Dependencies
A list of other manifests that are required by the current manifest. This is a list of other manifests that are required by the current
Manifests are identified an unambiguous way, such as a cryptographic manifest. Manifests are identified in an unambiguous way, such as a
digest. cryptographic digest.
This element is REQUIRED to support deployments that include both This element is REQUIRED to support deployments that include both
multiple authorities and multiple payloads. multiple authorities and multiple payloads.
Implements: REQ.USE.MFST.COMPONENT (Section 4.5.4) Implements: REQ.USE.MFST.COMPONENT (Section 4.5.4)
3.20. Encryption Wrapper 3.20. Encryption Wrapper
Encrypting firmware images requires symmetric content encryption Encrypting firmware images requires symmetric content encryption
keys. The encryption wrapper provides the information needed for a keys. The encryption wrapper provides the information needed for a
device to obtain or locate a key that it uses to decrypt the device to obtain or locate a key that it uses to decrypt the
firmware. firmware.
This element is REQUIRED for encrypted payloads. This element is REQUIRED for encrypted payloads.
Implements: REQ.SEC.IMG.CONFIDENTIALITY (Section 4.3.12) Implements: REQ.SEC.IMG.CONFIDENTIALITY (Section 4.3.12)
3.21. XIP Address 3.21. XIP Address
In order to support execute in place (XIP) systems with multiple In order to support XIP systems with multiple possible base
possible base addresses, it is necessary to specify which address the addresses, it is necessary to specify which address the payload is
payload is linked for. linked for.
For example a microcontroller may have a simple bootloader that For example, a microcontroller may have a simple bootloader that
chooses one of two images to boot. That microcontroller then needs chooses one of two images to boot. That microcontroller then needs
to choose one of two firmware images to install, based on which of to choose one of two firmware images to install, based on which of
its two images is older. its two images is older.
This element is OPTIONAL. This element is OPTIONAL.
Implements: REQ.USE.IMG.SELECT (Section 4.5.9) Implements: REQ.USE.IMG.SELECT (Section 4.5.9)
3.22. Load-time Metadata 3.22. Load-Time Metadata
Load-time metadata provides the device with information that it needs Load-time metadata provides the device with information that it needs
in order to load one or more images. This metadata may include any in order to load one or more images. This metadata may include any
of: of the following:
o the source (e.g. non-volatile storage) * The source (e.g., non-volatile storage)
o the destination (e.g. an address in RAM) * The destination (e.g., an address in RAM)
o cryptographic information * Cryptographic information
o decompression information * Decompression information
* Unpacking information
o unpacking information
Typically, loading is done by copying an image from its permanent Typically, loading is done by copying an image from its permanent
storage location into its active use location. The metadata allows storage location into its active use location. The metadata allows
operations such as decryption, decompression, and unpacking to be operations such as decryption, decompression, and unpacking to be
performed during that copy. performed during that copy.
This element is OPTIONAL. This element is OPTIONAL.
Implements: REQ.USE.LOAD (Section 4.5.11) Implements: REQ.USE.LOAD (Section 4.5.11)
3.23. Run-time metadata 3.23. Runtime Metadata
Run-time metadata provides the device with any extra information Runtime metadata provides the device with any extra information
needed to boot the device. This may include the entry-point of an needed to boot the device. This may include the entry point of an
XIP image or the kernel command-line to boot a Linux image. XIP image or the kernel command line to boot a Linux image.
This element is OPTIONAL. This element is OPTIONAL.
Implements: REQ.USE.EXEC (Section 4.5.10) Implements: REQ.USE.EXEC (Section 4.5.10)
3.24. Payload 3.24. Payload
The Payload element is contained within the manifest or manifest The Payload element is contained within the manifest or Manifest
envelope and enables the manifest and payload to be delivered Envelope and enables the manifest and payload to be delivered
simultaneously. This is used for delivering small payloads, such as simultaneously. This is used for delivering small payloads, such as
cryptographic keys or configuration data. cryptographic keys or configuration data.
This element is OPTIONAL. This element is OPTIONAL.
Implements: REQ.USE.PAYLOAD (Section 4.5.12) Implements: REQ.USE.PAYLOAD (Section 4.5.12)
3.25. Manifest Envelope Element: Delegation Chain 3.25. Manifest Envelope Element: Delegation Chain
The delegation chain offers enhanced authorization functionality via The delegation chain offers enhanced authorization functionality via
authorization tokens, such as CBOR Web Tokens [RFC8392] with Proof of authorization tokens, such as Concise Binary Object Representation
Possession Key Semantics [RFC8747]. Each token itself is protected (CBOR) Web Tokens [RFC8392] with Proof-of-Possession Key Semantics
and does not require another layer of protection. Each authorization [RFC8747]. Each token itself is protected and does not require
token typically includes a public key or a public key fingerprint, another layer of protection. Each authorization token typically
however this is dependent on the tokens used. Each token MAY include includes a public key or a public key fingerprint; however, this is
additional metadata, such as key usage information. Because the dependent on the tokens used. Each token MAY include additional
delegation chain is needed to verify the signature, it must be placed metadata, such as key usage information. Because the delegation
in the Manifest Envelope, rather than the Manifest. chain is needed to verify the signature, it must be placed in the
Manifest Envelope, rather than the manifest.
The first token in any delegation chain MUST be autheticated by the The first token in any delegation chain MUST be authenticated by the
recipient's Trust Anchor. Each subsequent token MUST be recipient's trust anchor. Each subsequent token MUST be
authenticated using the previous token. This allows a recipient to authenticated using the previous token. This allows a recipient to
discard each antecedent token after it has authenticated the discard each antecedent token after it has authenticated the
subsequent token. The final token MUST enable authentication of the subsequent token. The final token MUST enable authentication of the
manifest. More than one delegation chain MAY be used if more than manifest. More than one delegation chain MAY be used if more than
one signature is used. Note that no restriction is placed on the one signature is used. Note that no restriction is placed on the
encoding order of these tokens, the order of elements is logical encoding order of these tokens; the order of elements is logical
only. only.
This element is OPTIONAL. This element is OPTIONAL.
Implements: REQ.USE.DELEGATION (Section 4.5.14), REQ.SEC.KEY.ROTATION Implements: REQ.USE.DELEGATION (Section 4.5.14),
(Section 4.3.18) REQ.SEC.KEY.ROTATION (Section 4.3.18)
4. Security Considerations 4. Security Considerations
The following sub-sections describe the threat model, user stories, The following subsections describe the threat model, user stories,
security requirements, and usability requirements. This section also security requirements, and usability requirements. This section also
provides the motivations for each of the manifest information provides the motivations for each of the manifest information
elements. elements.
Note that it is worthwhile to recall that a firmware update is, by Note that it is worthwhile to recall that a firmware update is, by
definition, remote code execution. Hence, if a device is configured definition, remote code execution. Hence, if a device is configured
to trust an entity to provide firmware, it trusts this entity to do to trust an entity to provide firmware, it trusts this entity to
the "right thing". Many classes of attacks can be mitigated by behave correctly. Many classes of attacks can be mitigated by
verifying that a firmware update came from a trusted party and that verifying that a firmware update came from a trusted party and that
no rollback is taking place. However, if the trusted entity has been no rollback is taking place. However, if the trusted entity has been
compromised and distributes attacker-provided firmware to devices compromised and distributes attacker-provided firmware to devices,
then the possibilities for deference are limited. then the possibilities for defense are limited.
4.1. Threat Model 4.1. Threat Model
The following sub-sections aim to provide information about the The following subsections aim to provide information about the
threats that were considered, the security requirements that are threats that were considered, the security requirements that are
derived from those threats and the fields that permit implementation derived from those threats, and the fields that permit implementation
of the security requirements. This model uses the S.T.R.I.D.E. of the security requirements. This model uses the Spoofing,
[STRIDE] approach. Each threat is classified according to: Tampering, Repudiation, Information Disclosure, Denial of Service,
and Elevation of Privilege (STRIDE) approach [STRIDE]. Each threat
is classified according to the following:
o Spoofing identity * Spoofing identity
o Tampering with data * Tampering with data
o Repudiation * Repudiation
o Information disclosure * Information disclosure
o Denial of service * Denial of service
o Elevation of privilege * Elevation of privilege
This threat model only covers elements related to the transport of This threat model only covers elements related to the transport of
firmware updates. It explicitly does not cover threats outside of firmware updates. It explicitly does not cover threats outside of
the transport of firmware updates. For example, threats to an IoT the transport of firmware updates. For example, threats to an IoT
device due to physical access are out of scope. device due to physical access are out of scope.
4.2. Threat Descriptions 4.2. Threat Descriptions
Many of the threats detailed in this section contain a "threat Many of the threats detailed in this section contain a "threat
escalation" description. This explains how the described threat escalation" description. This explains how the described threat
might fit together with other threats and produce a high severity might fit together with other threats and produce a high-severity
threat. This is important because some of the described threats may threat. This is important because some of the described threats may
seem low severity but could be used with others to construct a high seem low severity but could be used with others to construct a high-
severity compromise. severity compromise.
4.2.1. THREAT.IMG.EXPIRED: Old Firmware 4.2.1. THREAT.IMG.EXPIRED: Old Firmware
Classification: Elevation of Privilege Classification: Elevation of Privilege
An attacker sends an old, but valid manifest with an old, but valid An attacker sends an old, but valid, manifest with an old, but valid,
firmware image to a device. If there is a known vulnerability in the firmware image to a device. If there is a known vulnerability in the
provided firmware image, this may allow an attacker to exploit the provided firmware image, this may allow an attacker to exploit the
vulnerability and gain control of the device. vulnerability and gain control of the device.
Threat Escalation: If the attacker is able to exploit the known Threat Escalation: If the attacker is able to exploit the known
vulnerability, then this threat can be escalated to ALL TYPES. vulnerability, then this threat can be escalated to all types.
Mitigated by: REQ.SEC.SEQUENCE (Section 4.3.1) Mitigated by: REQ.SEC.SEQUENCE (Section 4.3.1)
4.2.2. THREAT.IMG.EXPIRED.OFFLINE : Offline device + Old Firmware 4.2.2. THREAT.IMG.EXPIRED.OFFLINE: Offline Device + Old Firmware
Classification: Elevation of Privilege Classification: Elevation of Privilege
An attacker targets a device that has been offline for a long time An attacker targets a device that has been offline for a long time
and runs an old firmware version. The attacker sends an old, but and runs an old firmware version. The attacker sends an old, but
valid manifest to a device with an old, but valid firmware image. valid, manifest to a device with an old, but valid, firmware image.
The attacker-provided firmware is newer than the installed one but The attacker-provided firmware is newer than the installed firmware
older than the most recently available firmware. If there is a known but older than the most recently available firmware. If there is a
vulnerability in the provided firmware image then this may allow an known vulnerability in the provided firmware image, then this may
attacker to gain control of a device. Because the device has been allow an attacker to gain control of a device. Because the device
offline for a long time, it is unaware of any new updates. As such has been offline for a long time, it is unaware of any new updates.
it will treat the old manifest as the most current. As such, it will treat the old manifest as the most current.
The exact mitigation for this threat depends on where the threat The exact mitigation for this threat depends on where the threat
comes from. This requires careful consideration by the implementor. comes from. This requires careful consideration by the implementor.
If the threat is from a network actor, including an on-path attacker, If the threat is from a network actor, including an on-path attacker,
or an intruder into a management system, then a user confirmation can or an intruder into a management system, then a user confirmation can
mitigate this attack, simply by displaying an expiration date and mitigate this attack, simply by displaying an expiration date and
requesting confirmation. On the other hand, if the user is the requesting confirmation. On the other hand, if the user is the
attacker, then an online confirmation system (for example a trusted attacker, then an online confirmation system (for example, a trusted
timestamp server) can be used as a mitigation system. timestamp server) can be used as a mitigation system.
Threat Escalation: If the attacker is able to exploit the known Threat Escalation: If the attacker is able to exploit the known
vulnerability, then this threat can be escalated to ALL TYPES. vulnerability, then this threat can be escalated to all types.
Mitigated by: REQ.SEC.EXP (Section 4.3.3), REQ.USE.MFST.PRE_CHECK Mitigated by: REQ.SEC.EXP (Section 4.3.3), REQ.USE.MFST.PRE_CHECK
(Section 4.5.1), (Section 4.5.1)
4.2.3. THREAT.IMG.INCOMPATIBLE: Mismatched Firmware 4.2.3. THREAT.IMG.INCOMPATIBLE: Mismatched Firmware
Classification: Denial of Service Classification: Denial of Service
An attacker sends a valid firmware image, for the wrong type of An attacker sends a valid firmware image, for the wrong type of
device, signed by an actor with firmware installation permission on device, signed by an actor with firmware installation permission on
both types of device. The firmware is verified by the device both device types. The firmware is verified by the device positively
positively because it is signed by an actor with the appropriate because it is signed by an actor with the appropriate permission.
permission. This could have wide-ranging consequences. For devices This could have wide-ranging consequences. For devices that are
that are similar, it could cause minor breakage, or expose security similar, it could cause minor breakage or expose security
vulnerabilities. For devices that are very different, it is likely vulnerabilities. For devices that are very different, it is likely
to render devices inoperable. to render devices inoperable.
Mitigated by: REQ.SEC.COMPATIBLE (Section 4.3.2) Mitigated by: REQ.SEC.COMPATIBLE (Section 4.3.2)
For example, suppose that two vendors, Vendor A and Vendor B, adopt For example, suppose that two vendors -- Vendor A and Vendor B --
the same trade name in different geographic regions, and they both adopt the same trade name in different geographic regions, and they
make products with the same names, or product name matching is not both make products with the same names, or product name matching is
used. This causes firmware from Vendor A to match devices from not used. This causes firmware from Vendor A to match devices from
Vendor B. Vendor B.
If the vendors are the firmware authorities, then devices from Vendor If the vendors are the firmware authorities, then devices from Vendor
A will reject images signed by Vendor B since they use different A will reject images signed by Vendor B, since they use different
credentials. However, if both devices trust the same Author, then, credentials. However, if both devices trust the same author, then
devices from Vendor A could install firmware intended for devices devices from Vendor A could install firmware intended for devices
from Vendor B. from Vendor B.
4.2.4. THREAT.IMG.FORMAT: The target device misinterprets the type of 4.2.4. THREAT.IMG.FORMAT: The Target Device Misinterprets the Type of
payload Payload
Classification: Denial of Service Classification: Denial of Service
If a device misinterprets the format of the firmware image, it may If a device misinterprets the format of the firmware image, it may
cause a device to install a firmware image incorrectly. An cause a device to install a firmware image incorrectly. An
incorrectly installed firmware image would likely cause the device to incorrectly installed firmware image would likely cause the device to
stop functioning. stop functioning.
Threat Escalation: An attacker that can cause a device to Threat Escalation: An attacker that can cause a device to
misinterpret the received firmware image may gain elevation of misinterpret the received firmware image may gain elevation of
privilege and potentially expand this to all types of threat. privilege and potentially expand this to all types of threats.
Mitigated by: REQ.SEC.AUTH.IMG_TYPE (Section 4.3.5) Mitigated by: REQ.SEC.AUTH.IMG_TYPE (Section 4.3.5)
4.2.5. THREAT.IMG.LOCATION: The target device installs the payload to 4.2.5. THREAT.IMG.LOCATION: The Target Device Installs the Payload to
the wrong location the Wrong Location
Classification: Denial of Service Classification: Denial of Service
If a device installs a firmware image to the wrong location on the If a device installs a firmware image to the wrong location on the
device, then it is likely to break. For example, a firmware image device, then it is likely to break. For example, a firmware image
installed as an application could cause a device and/or an installed as an application could cause a device and/or application
application to stop functioning. to stop functioning.
Threat Escalation: An attacker that can cause a device to Threat Escalation: An attacker that can cause a device to
misinterpret the received code may gain elevation of privilege and misinterpret the received code may gain elevation of privilege and
potentially expand this to all types of threat. potentially expand this to all types of threats.
Mitigated by: REQ.SEC.AUTH.IMG_LOC (Section 4.3.6) Mitigated by: REQ.SEC.AUTH.IMG_LOC (Section 4.3.6)
4.2.6. THREAT.NET.REDIRECT: Redirection to inauthentic payload hosting 4.2.6. THREAT.NET.REDIRECT: Redirection to Inauthentic Payload Hosting
Classification: Denial of Service Classification: Denial of Service
If a device is tricked into fetching a payload for an attacker If a device is tricked into fetching a payload for an attacker-
controlled site, the attacker may send corrupted payloads to devices. controlled site, the attacker may send corrupted payloads to devices.
Mitigated by: REQ.SEC.AUTH.REMOTE_LOC (Section 4.3.7) Mitigated by: REQ.SEC.AUTH.REMOTE_LOC (Section 4.3.7)
4.2.7. THREAT.NET.ONPATH: Traffic interception 4.2.7. THREAT.NET.ONPATH: Traffic Interception
Classification: Spoofing Identity, Tampering with Data Classification: Spoofing Identity, Tampering with Data
An attacker intercepts all traffic to and from a device. The An attacker intercepts all traffic to and from a device. The
attacker can monitor or modify any data sent to or received from the attacker can monitor or modify any data sent to or received from the
device. This can take the form of: manifests, payloads, status device. This can take the form of manifests, payloads, status
reports, and capability reports being modified or not delivered to reports, and capability reports being modified or not delivered to
the intended recipient. It can also take the form of analysis of the intended recipient. It can also take the form of analysis of
data sent to or from the device, either in content, size, or data sent to or from the device, in content, size, or frequency.
frequency.
Mitigated by: REQ.SEC.AUTHENTIC (Section 4.3.4), Mitigated by: REQ.SEC.AUTHENTIC (Section 4.3.4),
REQ.SEC.IMG.CONFIDENTIALITY (Section 4.3.12), REQ.SEC.AUTH.REMOTE_LOC REQ.SEC.IMG.CONFIDENTIALITY (Section 4.3.12),
(Section 4.3.7), REQ.SEC.MFST.CONFIDENTIALITY (Section 4.3.14), REQ.SEC.AUTH.REMOTE_LOC (Section 4.3.7),
REQ.SEC.REPORTING (Section 4.3.16) REQ.SEC.MFST.CONFIDENTIALITY (Section 4.3.14), REQ.SEC.REPORTING
(Section 4.3.16)
4.2.8. THREAT.IMG.REPLACE: Payload Replacement 4.2.8. THREAT.IMG.REPLACE: Payload Replacement
Classification: Elevation of Privilege Classification: Elevation of Privilege
An attacker replaces a newly downloaded firmware after a device An attacker replaces newly downloaded firmware after a device
finishes verifying a manifest. This could cause the device to finishes verifying a manifest. This could cause the device to
execute the attacker's code. This attack likely requires physical execute the attacker's code. This attack likely requires physical
access to the device. However, it is possible that this attack is access to the device. However, it is possible that this attack is
carried out in combination with another threat that allows remote carried out in combination with another threat that allows remote
execution. This is a typical Time Of Check/Time Of Use (TICTOC) execution. This is a typical Time Of Check / Time Of Use (TOCTOU)
attack. attack.
Threat Escalation: If the attacker is able to exploit a known Threat Escalation: If the attacker is able to exploit a known
vulnerability, or if the attacker can supply their own firmware, then vulnerability or if the attacker can supply their own firmware,
this threat can be escalated to ALL TYPES. then this threat can be escalated to all types.
Mitigated by: REQ.SEC.AUTH.EXEC (Section 4.3.8) Mitigated by: REQ.SEC.AUTH.EXEC (Section 4.3.8)
4.2.9. THREAT.IMG.NON_AUTH: Unauthenticated Images 4.2.9. THREAT.IMG.NON_AUTH: Unauthenticated Images
Classification: Elevation of Privilege / All Types Classification: Elevation of Privilege / all types
If an attacker can install their firmware on a device, for example by If an attacker can install their firmware on a device -- for example,
manipulating either payload or metadata, then they have complete by manipulating either payload or metadata -- then they have complete
control of the device. control of the device.
Mitigated by: REQ.SEC.AUTHENTIC (Section 4.3.4) Mitigated by: REQ.SEC.AUTHENTIC (Section 4.3.4)
4.2.10. THREAT.UPD.WRONG_PRECURSOR: Unexpected Precursor images 4.2.10. THREAT.UPD.WRONG_PRECURSOR: Unexpected Precursor Images
Classification: Denial of Service / All Types Classification: Denial of Service / all types
Modifications of payloads and metadata allow an attacker to introduce Modifications of payloads and metadata allow an attacker to introduce
a number of denial of service attacks. Below are some examples. a number of denial-of-service attacks. Below are some examples.
An attacker sends a valid, current manifest to a device that has an An attacker sends a valid, current manifest to a device that has an
unexpected precursor image. If a payload format requires a precursor unexpected precursor image. If a payload format requires a precursor
image (for example, delta updates) and that precursor image is not image (for example, delta updates) and that precursor image is not
available on the target device, it could cause the update to break. available on the target device, it could cause the update to break.
An attacker that can cause a device to install a payload against the An attacker that can cause a device to install a payload against the
wrong precursor image could gain elevation of privilege and wrong precursor image could gain elevation of privilege and
potentially expand this to all types of threat. However, it is potentially expand this to all types of threats. However, it is
unlikely that a valid differential update applied to an incorrect unlikely that a valid differential update applied to an incorrect
precursor would result in a functional, but vulnerable firmware. precursor would result in functional, but vulnerable, firmware.
Mitigated by: REQ.SEC.AUTH.PRECURSOR (Section 4.3.9) Mitigated by: REQ.SEC.AUTH.PRECURSOR (Section 4.3.9)
4.2.11. THREAT.UPD.UNAPPROVED: Unapproved Firmware 4.2.11. THREAT.UPD.UNAPPROVED: Unapproved Firmware
Classification: Denial of Service, Elevation of Privilege Classification: Denial of Service, Elevation of Privilege
This threat can appear in several ways, however it is ultimately This threat can appear in several ways; however, it is ultimately
about ensuring that devices retain the behaviour required by their about ensuring that devices retain the behavior required by their
owner, or operator. The owner or operator of a device typically owner or Operator. The owner or Operator of a device typically
requires that the device maintain certain features, functions, requires that the device maintain certain features, functions,
capabilities, behaviours, or interoperability constraints (more capabilities, behaviors, or interoperability constraints (more
generally, behaviour). If these requirements are broken, then a generally, behavior). If these requirements are broken, then a
device will not fulfill its purpose. Therefore, if any party other device will not fulfill its purpose. Therefore, if any party other
than the device's owner or the owner's contracted Device Operator has than the device's owner or the owner's contracted device operator has
the ability to modify device behaviour without approval, then this the ability to modify device behavior without approval, then this
constitutes an elevation of privilege. constitutes an elevation of privilege.
Similarly, a Network Operator may require that devices behave in a Similarly, a network operator may require that devices behave in a
particular way in order to maintain the integrity of the network. If particular way in order to maintain the integrity of the network. If
devices behaviour on a network can be modified without the approval device behavior on a network can be modified without the approval of
of the Network Operator, then this constitutes an elevation of the network operator, then this constitutes an elevation of privilege
privilege with respect to the network. with respect to the network.
For example, if the owner of a device has purchased that device For example, if the owner of a device has purchased that device
because of features A, B, and C, and a firmware update is issued by because of Features A, B, and C, and a firmware update that removes
the manufacturer, which removes feature A, then the device may not Feature A is issued by the manufacturer, then the device may not
fulfill the owner's requirements any more. In certain circumstances, fulfill the owner's requirements any more. In certain circumstances,
this can cause significantly greater threats. Suppose that feature A this can cause significantly greater threats. Suppose that Feature A
is used to implement a safety-critical system, whether the is used to implement a safety-critical system, whether the
manufacturer intended this behaviour or not. When unapproved manufacturer intended this behavior or not. When unapproved firmware
firmware is installed, the system may become unsafe. is installed, the system may become unsafe.
In a second example, the owner or operator of a system of two or more In a second example, the owner or Operator of a system of two or more
interoperating devices needs to approve firmware for their system in interoperating devices needs to approve firmware for their system in
order to ensure interoperability with other devices in the system. order to ensure interoperability with other devices in the system.
If the firmware is not qualified, the system as a whole may not work. If the firmware is not qualified, the system as a whole may not work.
Therefore, if a device installs firmware without the approval of the Therefore, if a device installs firmware without the approval of the
device owner or operator, this is a threat to devices or the system device owner or Operator, this is a threat to devices or the system
as a whole. as a whole.
Similarly, the operator of a network may need to approve firmware for Similarly, the Operator of a network may need to approve firmware for
devices attached to the network in order to ensure favourable devices attached to the network in order to ensure favorable
operating conditions within the network. If the firmware is not operating conditions within the network. If the firmware is not
qualified, it may degrade the performance of the network. Therefore, qualified, it may degrade the performance of the network. Therefore,
if a device installs firmware without the approval of the Network if a device installs firmware without the approval of the network
Operator, this is a threat to the network itself. operator, this is a threat to the network itself.
Threat Escalation: If the firmware expects configuration that is Threat Escalation: If the network operator expects configuration
present in devices deployed in Network A, but not in devices deployed that is present in devices deployed in Network A, but not in
in Network B, then the device may experience degraded security, devices deployed in Network B, then the device may experience
leading to threats of All Types. degraded security, leading to threats of all types.
Mitigated by: REQ.SEC.RIGHTS (Section 4.3.11), REQ.SEC.ACCESS_CONTROL Mitigated by: REQ.SEC.RIGHTS (Section 4.3.11),
(Section 4.3.13) REQ.SEC.ACCESS_CONTROL (Section 4.3.13)
4.2.11.1. Example 1: Multiple Network Operators with a Single Device 4.2.11.1. Example 1: Multiple Network Operators with a Single Device
Operator Operator
In this example, assume that Device Operators expect the rights to In this example, assume that device operators expect the rights to
create firmware but that Network Operators expect the rights to create firmware but that network operators expect the rights to
qualify firmware as fit-for-purpose on their networks. Additionally, qualify firmware as "fit for purpose" on their networks.
assume that Device Operators manage devices that can be deployed on Additionally, assume that device operators manage devices that can be
any network, including Network A and B in our example. deployed on any network, including Network A and Network B in our
example.
An attacker may obtain a manifest for a device on Network A. Then, An attacker may obtain a manifest for a device on Network A. Then,
this attacker sends that manifest to a device on Network B. Because this attacker sends that manifest to a device on Network B. Because
Network A and Network B are under control of different Operators, and Network A and Network B are under the control of different Operators,
the firmware for a device on Network A has not been qualified to be and the firmware for a device on Network A has not been qualified to
deployed on Network B, the target device on Network B is now in be deployed on Network B, the target device on Network B is now in
violation of the Operator B's policy and may be disabled by this violation of Operator B's policy and may be disabled by this
unqualified, but signed firmware. unqualified, but signed, firmware.
This is a denial of service because it can render devices inoperable. This is a denial of service because it can render devices inoperable.
This is an elevation of privilege because it allows the attacker to This is an elevation of privilege because it allows the attacker to
make installation decisions that should be made by the Operator. make installation decisions that should be made by the Operator.
4.2.11.2. Example 2: Single Network Operator with Multiple Device 4.2.11.2. Example 2: Single Network Operator with Multiple Device
Operators Operators
Multiple devices that interoperate are used on the same network and Multiple devices that interoperate are used on the same network and
communicate with each other. Some devices are manufactured and communicate with each other. Some devices are manufactured and
managed by Device Operator A and other devices by Device Operator B. managed by Device Operator A and other devices by Device Operator B.
A new firmware is released by Device Operator A that breaks New firmware is released by Device Operator A that breaks
compatibility with devices from Device Operator B. An attacker sends compatibility with devices from Device Operator B. An attacker sends
the new firmware to the devices managed by Device Operator A without the new firmware to the devices managed by Device Operator A without
approval of the Network Operator. This breaks the behaviour of the the approval of the network operator. This breaks the behavior of
larger system causing denial of service and possibly other threats. the larger system, causing denial of service and, possibly, other
Where the network is a distributed SCADA system, this could cause threats. Where the network is a distributed Supervisory Control and
misbehaviour of the process that is under control. Data Acquisition (SCADA) system, this could cause misbehavior of the
process that is under control.
4.2.12. THREAT.IMG.DISCLOSURE: Reverse Engineering Of Firmware Image 4.2.12. THREAT.IMG.DISCLOSURE: Reverse Engineering of Firmware Image
for Vulnerability Analysis for Vulnerability Analysis
Classification: All Types Classification: all types
An attacker wants to mount an attack on an IoT device. To prepare An attacker wants to mount an attack on an IoT device. To prepare
the attack he or she retrieves the provided firmware image and the attack, the provided firmware image is reverse engineered and
performs reverse engineering of the firmware image to analyze it for analyzed for vulnerabilities.
specific vulnerabilities.
Mitigated by: REQ.SEC.IMG.CONFIDENTIALITY (Section 4.3.12) Mitigated by: REQ.SEC.IMG.CONFIDENTIALITY (Section 4.3.12)
4.2.13. THREAT.MFST.OVERRIDE: Overriding Critical Manifest Elements 4.2.13. THREAT.MFST.OVERRIDE: Overriding Critical Manifest Elements
Classification: Elevation of Privilege Classification: Elevation of Privilege
An authorized actor, but not the Author, uses an override mechanism An authorized actor, but not the author, uses an override mechanism
(USER_STORY.OVERRIDE (Section 4.4.3)) to change an information (USER_STORY.OVERRIDE (Section 4.4.3)) to change an information
element in a manifest signed by the Author. For example, if the element in a manifest signed by the author. For example, if the
authorized actor overrides the digest and URI of the payload, the authorized actor overrides the digest and URI of the payload, the
actor can replace the entire payload with a payload of their choice. actor can replace the entire payload with a payload of their choice.
Threat Escalation: By overriding elements such as payload Threat Escalation: By overriding elements such as payload
installation instructions or firmware digest, this threat can be installation instructions or a firmware digest, this threat can be
escalated to all types. escalated to all types.
Mitigated by: REQ.SEC.ACCESS_CONTROL (Section 4.3.13) Mitigated by: REQ.SEC.ACCESS_CONTROL (Section 4.3.13)
4.2.14. THREAT.MFST.EXPOSURE: Confidential Manifest Element Exposure 4.2.14. THREAT.MFST.EXPOSURE: Confidential Manifest Element Exposure
Classification: Information Disclosure Classification: Information Disclosure
A third party may be able to extract sensitive information from the A third party may be able to extract sensitive information from the
manifest. manifest.
Mitigated by: REQ.SEC.MFST.CONFIDENTIALITY (Section 4.3.14) Mitigated by: REQ.SEC.MFST.CONFIDENTIALITY (Section 4.3.14)
4.2.15. THREAT.IMG.EXTRA: Extra data after image 4.2.15. THREAT.IMG.EXTRA: Extra Data after Image
Classification: All Types Classification: all types
If a third party modifies the image so that it contains extra code If a third party modifies the image so that it contains extra code
after a valid, authentic image, that third party can then use their after a valid, authentic image, that third party can then use their
own code in order to make better use of an existing vulnerability. own code in order to make better use of an existing vulnerability.
Mitigated by: REQ.SEC.IMG.COMPLETE_DIGEST (Section 4.3.15) Mitigated by: REQ.SEC.IMG.COMPLETE_DIGEST (Section 4.3.15)
4.2.16. THREAT.KEY.EXPOSURE: Exposure of signing keys 4.2.16. THREAT.KEY.EXPOSURE: Exposure of Signing Keys
Classification: All Types Classification: all types
If a third party obtains a key or even indirect access to a key, for If a third party obtains a key or even indirect access to a key --
example in an hardware security module (HSM), then they can perform for example, in a hardware security module (HSM) -- then they can
the same actions as the legitimate owner of the key. If the key is perform the same actions as the legitimate owner of the key. If the
trusted for firmware update, then the third party can perform key is trusted for firmware updates, then the third party can perform
firmware updates as though they were the legitimate owner of the key. firmware updates as though they were the legitimate owner of the key.
For example, if manifest signing is performed on a server connected For example, if manifest signing is performed on a server connected
to the internet, an attacker may compromise the server and then be to the internet, an attacker may compromise the server and then be
able to sign manifests, even if the keys for manifest signing are able to sign manifests, even if the keys for manifest signing are
held in an HSM that is accessed by the server. held in an HSM that is accessed by the server.
Mitigated by: REQ.SEC.KEY.PROTECTION (Section 4.3.17), Mitigated by: REQ.SEC.KEY.PROTECTION (Section 4.3.17),
REQ.SEC.KEY.ROTATION (Section 4.3.18) REQ.SEC.KEY.ROTATION (Section 4.3.18)
4.2.17. THREAT.MFST.MODIFICATION: Modification of manifest or payload 4.2.17. THREAT.MFST.MODIFICATION: Modification of Manifest or Payload
prior to signing prior to Signing
Classification: All Types Classification: all types
If an attacker can alter a manifest or payload before it is signed, If an attacker can alter a manifest or payload before it is signed,
they can perform all the same actions as the manifest author. This they can perform all the same actions as the manifest author. This
allows the attacker to deploy firmware updates to any devices that allows the attacker to deploy firmware updates to any devices that
trust the manifest author. If an attacker can modify the code of a trust the manifest author. If an attacker can modify the code of a
payload before the corresponding manifest is created, they can insert payload before the corresponding manifest is created, they can insert
their own code. If an attacker can modify the manifest before it is their own code. If an attacker can modify the manifest before it is
signed, they can redirect the manifest to their own payload. signed, they can redirect the manifest to their own payload.
For example, the attacker deploys malware to the developer's computer For example, the attacker deploys malware to the developer's computer
or signing service that watches manifest creation activities and or signing service that watches manifest creation activities and
inserts code into any binary that is referenced by a manifest. inserts code into any binary that is referenced by a manifest.
For example, the attacker deploys malware to the developer's computer For example, the attacker deploys malware to the developer's computer
or signing service that replaces the referenced binary (digest) and or signing service that replaces the referenced binary (digest) and
URI with the attacker's binary (digest) and URI. URI with the attacker's binary (digest) and URI.
Mitigated by: REQ.SEC.MFST.CHECK (Section 4.3.19), Mitigated by: REQ.SEC.MFST.CHECK (Section 4.3.19),
REQ.SEC.MFST.TRUSTED (Section 4.3.20) REQ.SEC.MFST.TRUSTED (Section 4.3.20)
4.2.18. THREAT.MFST.TOCTOU: Modification of manifest between 4.2.18. THREAT.MFST.TOCTOU: Modification of Manifest between
authentication and use Authentication and Use
Classification: All Types Classification: all types
If an attacker can modify a manifest after it is authenticated (Time If an attacker can modify a manifest after it is authenticated (time
Of Check) but before it is used (Time Of Use), then the attacker can of check) but before it is used (time of use), then the attacker can
place any content whatsoever in the manifest. place any content whatsoever in the manifest.
Mitigated by: REQ.SEC.MFST.CONST (Section 4.3.21) Mitigated by: REQ.SEC.MFST.CONST (Section 4.3.21)
4.3. Security Requirements 4.3. Security Requirements
The security requirements here are a set of policies that mitigate The security requirements here are a set of policies that mitigate
the threats described in Section 4.1. the threats described in Section 4.1.
4.3.1. REQ.SEC.SEQUENCE: Monotonic Sequence Numbers 4.3.1. REQ.SEC.SEQUENCE: Monotonic Sequence Numbers
Only an actor with firmware installation authority is permitted to Only an actor with firmware installation authority is permitted to
decide when device firmware can be installed. To enforce this rule, decide when device firmware can be installed. To enforce this rule,
manifests MUST contain monotonically increasing sequence numbers. manifests MUST contain monotonically increasing sequence numbers.
Manifests may use UTC epoch timestamps to coordinate monotonically Manifests may use UTC epoch timestamps to coordinate monotonically
increasing sequence numbers across many actors in many locations. If increasing sequence numbers across many actors in many locations. If
UTC epoch timestamps are used, they must not be treated as times, UTC epoch timestamps are used, they must not be treated as times;
they must be treated only as sequence numbers. Devices must reject they must be treated only as sequence numbers. Devices must reject
manifests with sequence numbers smaller than any onboard sequence manifests with sequence numbers smaller than any onboard sequence
number, i.e. there is no sequence number roll over. number, i.e., there is no sequence number rollover.
Note: This is not a firmware version field. It is a manifest | Note: This is not a firmware version field. It is a manifest
sequence number. A firmware version may be rolled back by creating a | sequence number. A firmware version may be rolled back by
new manifest for the old firmware version with a later sequence | creating a new manifest for the old firmware version with a
number. | later sequence number.
Mitigates: THREAT.IMG.EXPIRED (Section 4.2.1) Mitigates: THREAT.IMG.EXPIRED (Section 4.2.1)
Implemented by: Monotonic Sequence Number (Section 3.2) Implemented by: Monotonic Sequence Number (Section 3.2)
4.3.2. REQ.SEC.COMPATIBLE: Vendor, Device-type Identifiers 4.3.2. REQ.SEC.COMPATIBLE: Vendor, Device-Type Identifiers
Devices MUST only apply firmware that is intended for them. Devices Devices MUST only apply firmware that is intended for them. Devices
must know that a given update applies to their vendor, model, must know that a given update applies to their vendor, model,
hardware revision, and software revision. Human-readable identifiers hardware revision, and software revision. Human-readable identifiers
are often error-prone in this regard, so unique identifiers should be are often prone to error in this regard, so unique identifiers should
used instead. be used instead.
Mitigates: THREAT.IMG.INCOMPATIBLE (Section 4.2.3) Mitigates: THREAT.IMG.INCOMPATIBLE (Section 4.2.3)
Implemented by: Vendor ID Condition (Section 3.3), Class ID Condition Implemented by: Vendor ID Condition (Section 3.3), Class ID
(Section 3.4) Condition (Section 3.4)
4.3.3. REQ.SEC.EXP: Expiration Time 4.3.3. REQ.SEC.EXP: Expiration Time
A firmware manifest MAY expire after a given time and devices may A firmware manifest MAY expire after a given time, and devices may
have a secure clock (local or remote). If a secure clock is provided have a secure clock (local or remote). If a secure clock is provided
and the Firmware manifest has an expiration timestamp, the device and the firmware manifest has an expiration timestamp, the device
must reject the manifest if current time is later than the expiration must reject the manifest if the current time is later than the
time. expiration time.
Special consideration is required for end-of-life in case device will Special consideration is required for end-of-life in cases where a
not be updated again, for example if a business stops issuing updates device will not be updated again -- for example, if a business stops
for a device. The last valid firmware should not have an expiration issuing updates for a device. The last valid firmware should not
time. have an expiration time.
If a device has a flawed time source (either local or remote), an old If a device has a flawed time source (either local or remote), an old
update can be deployed as new. update can be deployed as new.
Mitigates: THREAT.IMG.EXPIRED.OFFLINE (Section 4.2.2) Mitigates: THREAT.IMG.EXPIRED.OFFLINE (Section 4.2.2)
Implemented by: Expiration Time (Section 3.7) Implemented by: Expiration Time (Section 3.7)
4.3.4. REQ.SEC.AUTHENTIC: Cryptographic Authenticity 4.3.4. REQ.SEC.AUTHENTIC: Cryptographic Authenticity
The authenticity of an update MUST be demonstrable. Typically, this The authenticity of an update MUST be demonstrable. Typically, this
means that updates must be digitally signed. Because the manifest means that updates must be digitally signed. Because the manifest
contains information about how to install the update, the manifest's contains information about how to install the update, the manifest's
authenticity must also be demonstrable. To reduce the overhead authenticity must also be demonstrable. To reduce the overhead
required for validation, the manifest contains the cryptographic required for validation, the manifest contains the cryptographic
digest of the firmware image, rather than a second digital signature. digest of the firmware image, rather than a second digital signature.
The authenticity of the manifest can be verified with a digital The authenticity of the manifest can be verified with a digital
signature or Message Authentication Code. The authenticity of the signature or Message Authentication Code. The authenticity of the
firmware image is tied to the manifest by the use of a cryptographic firmware image is tied to the manifest by the use of a cryptographic
digest of the firmware image. digest of the firmware image.
Mitigates: THREAT.IMG.NON_AUTH (Section 4.2.9), THREAT.NET.ONPATH Mitigates: THREAT.IMG.NON_AUTH (Section 4.2.9), THREAT.NET.ONPATH
(Section 4.2.7) (Section 4.2.7)
Implemented by: Signature (Section 3.15), Payload Digest Implemented by: Signature (Section 3.15), Payload Digests
(Section 3.13) (Section 3.13)
4.3.5. REQ.SEC.AUTH.IMG_TYPE: Authenticated Payload Type 4.3.5. REQ.SEC.AUTH.IMG_TYPE: Authenticated Payload Type
The type of payload MUST be authenticated. For example, the target The type of payload MUST be authenticated. For example, the target
must know whether the payload is XIP firmware, a loadable module, or must know whether the payload is XIP firmware, a loadable module, or
configuration data. configuration data.
Mitigates: THREAT.IMG.FORMAT (Section 4.2.4) Mitigates: THREAT.IMG.FORMAT (Section 4.2.4)
Implemented by: Payload Format (Section 3.8), Signature Implemented by: Payload Format (Section 3.8), Signature
(Section 3.15) (Section 3.15)
4.3.6. Security Requirement REQ.SEC.AUTH.IMG_LOC: Authenticated Storage 4.3.6. REQ.SEC.AUTH.IMG_LOC: Authenticated Storage Location
Location
The location on the target where the payload is to be stored MUST be The location on the target where the payload is to be stored MUST be
authenticated. authenticated.
Mitigates: THREAT.IMG.LOCATION (Section 4.2.5) Mitigates: THREAT.IMG.LOCATION (Section 4.2.5)
Implemented by: Storage Location (Section 3.10) Implemented by: Storage Location (Section 3.10)
4.3.7. REQ.SEC.AUTH.REMOTE_LOC: Authenticated Remote Payload 4.3.7. REQ.SEC.AUTH.REMOTE_LOC: Authenticated Remote Payload
The location where a target should find a payload MUST be The location where a target should find a payload MUST be
authenticated. Remote resources need to receive an equal amount of authenticated. Remote resources need to receive an equal amount of
cryptographic protection as the manifest itself, when dereferencing cryptographic protection as the manifest itself, when dereferencing
URIs. The security considerations of Uniform Resource Identifiers URIs. The security considerations of Uniform Resource Identifiers
(URIs) are applicable [RFC3986]. (URIs) are applicable [RFC3986].
Mitigates: THREAT.NET.REDIRECT (Section 4.2.6), THREAT.NET.ONPATH Mitigates: THREAT.NET.REDIRECT (Section 4.2.6), THREAT.NET.ONPATH
(Section 4.2.7) (Section 4.2.7)
Implemented by: Payload Indicator (Section 3.12) Implemented by: Payload Indicator (Section 3.12)
4.3.8. REQ.SEC.AUTH.EXEC: Secure Execution 4.3.8. REQ.SEC.AUTH.EXEC: Secure Execution
The target SHOULD verify firmware at time of boot. This requires The target SHOULD verify firmware at the time of boot. This requires
authenticated payload size, and digest. authenticated payload size and firmware digest.
Mitigates: THREAT.IMG.REPLACE (Section 4.2.8) Mitigates: THREAT.IMG.REPLACE (Section 4.2.8)
Implemented by: Payload Digest (Section 3.13), Size (Section 3.14) Implemented by: Payload Digests (Section 3.13), Size (Section 3.14)
4.3.9. REQ.SEC.AUTH.PRECURSOR: Authenticated precursor images 4.3.9. REQ.SEC.AUTH.PRECURSOR: Authenticated Precursor Images
If an update uses a differential compression method, it MUST specify If an update uses a differential compression method, it MUST specify
the digest of the precursor image and that digest MUST be the digest of the precursor image, and that digest MUST be
authenticated. authenticated.
Mitigates: THREAT.UPD.WRONG_PRECURSOR (Section 4.2.10) Mitigates: THREAT.UPD.WRONG_PRECURSOR (Section 4.2.10)
Implemented by: Precursor Image Digest (Section 3.5) Implemented by: Precursor Image Digest (Section 3.5)
4.3.10. REQ.SEC.AUTH.COMPATIBILITY: Authenticated Vendor and Class IDs 4.3.10. REQ.SEC.AUTH.COMPATIBILITY: Authenticated Vendor and Class IDs
The identifiers that specify firmware compatibility MUST be The identifiers that specify firmware compatibility MUST be
authenticated to ensure that only compatible firmware is installed on authenticated to ensure that only compatible firmware is installed on
a target device. a target device.
Mitigates: THREAT.IMG.INCOMPATIBLE (Section 4.2.3) Mitigates: THREAT.IMG.INCOMPATIBLE (Section 4.2.3)
Implemented By: Vendor ID Condition (Section 3.3), Class ID Condition Implemented by: Vendor ID Condition (Section 3.3), Class ID
(Section 3.4) Condition (Section 3.4)
4.3.11. REQ.SEC.RIGHTS: Rights Require Authenticity 4.3.11. REQ.SEC.RIGHTS: Rights Require Authenticity
If a device grants different rights to different actors, exercising If a device grants different rights to different actors, exercising
those rights MUST be accompanied by proof of those rights, in the those rights MUST be accompanied by proof of those rights, in the
form of proof of authenticity. Authenticity mechanisms, such as form of proof of authenticity. Authenticity mechanisms, such as
those required in REQ.SEC.AUTHENTIC (Section 4.3.4), can be used to those required in REQ.SEC.AUTHENTIC (Section 4.3.4), can be used to
prove authenticity. prove authenticity.
For example, if a device has a policy that requires that firmware For example, if a device has a policy that requires that firmware
have both an Authorship right and a Qualification right and if that have both an Authorship right and a Qualification right and if that
device grants Authorship and Qualification rights to different device grants Authorship and Qualification rights to different
parties, such as a Device Operator and a Network Operator, parties, such as a device operator and a network operator,
respectively, then the firmware cannot be installed without proof of respectively, then the firmware cannot be installed without proof of
rights from both the Device Operator and the Network Operator. rights from both the device operator and the network operator.
Mitigates: THREAT.UPD.UNAPPROVED (Section 4.2.11) Mitigates: THREAT.UPD.UNAPPROVED (Section 4.2.11)
Implemented by: Signature (Section 3.15) Implemented by: Signature (Section 3.15)
4.3.12. REQ.SEC.IMG.CONFIDENTIALITY: Payload Encryption 4.3.12. REQ.SEC.IMG.CONFIDENTIALITY: Payload Encryption
The manifest information model MUST enable encrypted payloads. The manifest information model MUST enable encrypted payloads.
Encryption helps to prevent third parties, including attackers, from Encryption helps to prevent third parties, including attackers, from
reading the content of the firmware image. This can protect against reading the content of the firmware image. This can protect against
confidential information disclosures and discovery of vulnerabilities confidential information disclosures and discovery of vulnerabilities
through reverse engineering. Therefore the manifest must convey the through reverse engineering. Therefore, the manifest must convey the
information required to allow an intended recipient to decrypt an information required to allow an intended recipient to decrypt an
encrypted payload. encrypted payload.
Mitigates: THREAT.IMG.DISCLOSURE (Section 4.2.12), THREAT.NET.ONPATH Mitigates: THREAT.IMG.DISCLOSURE (Section 4.2.12), THREAT.NET.ONPATH
(Section 4.2.7) (Section 4.2.7)
Implemented by: Encryption Wrapper (Section 3.20) Implemented by: Encryption Wrapper (Section 3.20)
4.3.13. REQ.SEC.ACCESS_CONTROL: Access Control 4.3.13. REQ.SEC.ACCESS_CONTROL: Access Control
If a device grants different rights to different actors, then an If a device grants different rights to different actors, then an
exercise of those rights MUST be validated against a list of rights exercise of those rights MUST be validated against a list of rights
for the actor. This typically takes the form of an Access Control for the actor. This typically takes the form of an Access Control
List (ACL). ACLs are applied to two scenarios: List (ACL). ACLs are applied to two scenarios:
1. An ACL decides which elements of the manifest may be overridden 1. An ACL decides which elements of the manifest may be overridden
and by which actors. and by which actors.
2. An ACL decides which component identifier/storage identifier 2. An ACL decides which component identifier / storage identifier
pairs can be written by which actors. pairs can be written by which actors.
Mitigates: THREAT.MFST.OVERRIDE (Section 4.2.13), Mitigates: THREAT.MFST.OVERRIDE (Section 4.2.13),
THREAT.UPD.UNAPPROVED (Section 4.2.11) THREAT.UPD.UNAPPROVED (Section 4.2.11)
Implemented by: Client-side code, not specified in manifest. Implemented by: Client-side code, not specified in manifest
4.3.14. REQ.SEC.MFST.CONFIDENTIALITY: Encrypted Manifests 4.3.14. REQ.SEC.MFST.CONFIDENTIALITY: Encrypted Manifests
A manifest format MUST allow encryption of selected parts of the A manifest format MUST allow encryption of selected parts of the
manifest or encryption of the entire manifest to prevent sensitive manifest or encryption of the entire manifest to prevent sensitive
content of the firmware metadata to be leaked. content of the firmware metadata from being leaked.
Mitigates: THREAT.MFST.EXPOSURE (Section 4.2.14), THREAT.NET.ONPATH Mitigates: THREAT.MFST.EXPOSURE (Section 4.2.14), THREAT.NET.ONPATH
(Section 4.2.7) (Section 4.2.7)
Implemented by: Manifest Encryption Wrapper / Transport Security Implemented by: Manifest Encryption Wrapper / Transport Security
4.3.15. REQ.SEC.IMG.COMPLETE_DIGEST: Whole Image Digest 4.3.15. REQ.SEC.IMG.COMPLETE_DIGEST: Whole Image Digest
The digest SHOULD cover all available space in a fixed-size storage The digest SHOULD cover all available space in a fixed-size storage
location. Variable-size storage locations MUST be restricted to location. Variable-size storage locations MUST be restricted to
exactly the size of deployed payload. This prevents any data from exactly the size of deployed payload. This prevents any data from
being distributed without being covered by the digest. For example, being distributed without being covered by the digest. For example,
XIP microcontrollers typically have fixed-size storage. These XIP microcontrollers typically have fixed-size storage. These
devices should deploy a digest that covers the deployed firmware devices should deploy a digest that covers the deployed firmware
image, concatenated with the default erased value of any remaining image, concatenated with the default erased value of any remaining
space. space.
Mitigates: THREAT.IMG.EXTRA (Section 4.2.15) Mitigates: THREAT.IMG.EXTRA (Section 4.2.15)
Implemented by: Payload Digests (Section 3.13) Implemented by: Payload Digests (Section 3.13)
4.3.16. REQ.SEC.REPORTING: Secure Reporting 4.3.16. REQ.SEC.REPORTING: Secure Reporting
Status reports from the device to any remote system MUST be performed Status reports from the device to any remote system MUST be performed
over an authenticated, confidential channel in order to prevent over an authenticated, confidential channel in order to prevent
modification or spoofing of the reports. modification or spoofing of the reports.
Mitigates: THREAT.NET.ONPATH (Section 4.2.7) Mitigates: THREAT.NET.ONPATH (Section 4.2.7)
Implemented by: Transport Security / Manifest format triggering Implemented by: Transport Security / Manifest format triggering
generation of reports generation of reports
4.3.17. REQ.SEC.KEY.PROTECTION: Protected storage of signing keys 4.3.17. REQ.SEC.KEY.PROTECTION: Protected Storage of Signing Keys
Cryptographic keys for signing/authenticating manifests SHOULD be Cryptographic keys for signing/authenticating manifests SHOULD be
stored in a manner that is inaccessible to networked devices, for stored in a manner that is inaccessible to networked devices -- for
example in an HSM, or an air-gapped computer. This protects against example, in an HSM or an air-gapped computer. This protects against
an attacker obtaining the keys. an attacker obtaining the keys.
Keys SHOULD be stored in a way that limits the risk of a legitimate, Keys SHOULD be stored in a way that limits the risk of a legitimate,
but compromised, entity (such as a server or developer computer) but compromised, entity (such as a server or developer computer)
issuing signing requests. issuing signing requests.
Mitigates: THREAT.KEY.EXPOSURE (Section 4.2.16) Mitigates: THREAT.KEY.EXPOSURE (Section 4.2.16)
Implemented by: Hardware-assisted isolation technologies, which are Implemented by: Hardware-assisted isolation technologies, which are
outside the scope of the manifest format. outside the scope of the manifest format
4.3.18. REQ.SEC.KEY.ROTATION: Protected storage of signing keys 4.3.18. REQ.SEC.KEY.ROTATION: Protected Storage of Signing Keys
Cryptographic keys for signing/authenticating manifests SHOULD be Cryptographic keys for signing/authenticating manifests SHOULD be
replaced from time to time. Because it is difficult and risky to replaced from time to time. Because it is difficult and risky to
replace a Trust Anchor, keys used for signing updates SHOULD be replace a trust anchor, keys used for signing updates SHOULD be
delegates of that Trust Anchor. delegates of that trust anchor.
If key expiration is performed based on time, then a secure clock is If key expiration is performed based on time, then a secure clock is
needed. If the time source used by a recipient to check for needed. If the time source used by a recipient to check for
expiration is flawed, an old signing key can be used as current, expiration is flawed, an old signing key can be used as current,
which compounds THREAT.KEY.EXPOSURE (Section 4.2.16). which compounds THREAT.KEY.EXPOSURE (Section 4.2.16).
Mitigates: THREAT.KEY.EXPOSURE (Section 4.2.16) Mitigates: THREAT.KEY.EXPOSURE (Section 4.2.16)
Implemented by: Secure storage technology, which is a system design/ Implemented by: Secure storage technology, which is a system design/
implementation aspect outside the scope of the manifest format. implementation aspect outside the scope of the manifest format
4.3.19. REQ.SEC.MFST.CHECK: Validate manifests prior to deployment 4.3.19. REQ.SEC.MFST.CHECK: Validate Manifests prior to Deployment
Manifests SHOULD be verified prior to deployment. This reduces Manifests SHOULD be verified prior to deployment. This reduces
problems that may arise with devices installing firmware images that problems that may arise with devices installing firmware images that
damage devices unintentionally. damage devices unintentionally.
Mitigates: THREAT.MFST.MODIFICATION (Section 4.2.17) Mitigates: THREAT.MFST.MODIFICATION (Section 4.2.17)
Implemented by: Testing infrastructure. While outside the scope of Implemented by: Testing infrastructure. While outside the scope of
the manifest format, proper testing of low-level software is the manifest format, proper testing of low-level software is
essential for avoiding unnecessary down-time or worse situations. essential for avoiding unnecessary downtime or worse situations.
4.3.20. REQ.SEC.MFST.TRUSTED: Construct manifests in a trusted 4.3.20. REQ.SEC.MFST.TRUSTED: Construct Manifests in a Trusted
environment Environment
For high risk deployments, such as large numbers of devices or For high-risk deployments, such as large numbers of devices or
critical function devices, manifests SHOULD be constructed in an devices that provide critical functions, manifests SHOULD be
environment that is protected from interference, such as an air- constructed in an environment that is protected from interference,
gapped computer. Note that a networked computer connected to an HSM such as an air-gapped computer. Note that a networked computer
does not fulfill this requirement (see THREAT.MFST.MODIFICATION connected to an HSM does not fulfill this requirement (see
(Section 4.2.17)). THREAT.MFST.MODIFICATION (Section 4.2.17)).
Mitigates: THREAT.MFST.MODIFICATION (Section 4.2.17) Mitigates: THREAT.MFST.MODIFICATION (Section 4.2.17)
Implemented by: Physical and network security for protecting the
environment where firmware updates are prepared to avoid unauthorized
access to this infrastructure.
4.3.21. REQ.SEC.MFST.CONST: Manifest kept immutable between check and Implemented by: Physical and network security for protecting the
use environment where firmware updates are prepared to avoid
unauthorized access to this infrastructure
4.3.21. REQ.SEC.MFST.CONST: Manifest Kept Immutable between Check and
Use
Both the manifest and any data extracted from it MUST be held Both the manifest and any data extracted from it MUST be held
immutable between its authenticity verification (time of check) and immutable between its authenticity verification (time of check) and
its use (time of use). To make this guarantee, the manifest MUST fit its use (time of use). To make this guarantee, the manifest MUST fit
within an internal memory or a secure memory, such as encrypted within internal memory or secure memory, such as encrypted memory.
memory. The recipient SHOULD defend the manifest from tampering by The recipient SHOULD defend the manifest from tampering by code or
code or hardware resident in the recipient, for example other hardware resident in the recipient -- for example, other processes or
processes or debuggers. debuggers.
If an application requires that the manifest is verified before If an application requires that the manifest be verified before
storing it, then this means the manifest MUST fit in RAM. storing it, then this means the manifest MUST fit in RAM.
Mitigates: THREAT.MFST.TOCTOU (Section 4.2.18) Mitigates: THREAT.MFST.TOCTOU (Section 4.2.18)
Implemented by: Proper system design with sufficient resources and Implemented by: Proper system design with sufficient resources and
implementation avoiding TOCTOU attacks. implementation avoiding TOCTOU attacks
4.4. User Stories 4.4. User Stories
User stories provide expected use cases. These are used to feed into User stories provide expected use cases. These are used to feed into
usability requirements. usability requirements.
4.4.1. USER_STORY.INSTALL.INSTRUCTIONS: Installation Instructions 4.4.1. USER_STORY.INSTALL.INSTRUCTIONS: Installation Instructions
As a Device Operator, I want to provide my devices with additional As a device operator, I want to provide my devices with additional
installation instructions so that I can keep process details out of installation instructions so that I can keep process details out of
my payload data. my payload data.
Some installation instructions might be: Some installation instructions might be as follows:
o Use a table of hashes to ensure that each block of the payload is * Use a table of hashes to ensure that each block of the payload is
validated before writing. validated before writing.
o Do not report progress. * Do not report progress.
o Pre-cache the update, but do not install. * Pre-cache the update, but do not install.
o Install the pre-cached update matching this manifest. * Install the pre-cached update matching this manifest.
o Install this update immediately, overriding any long-running * Install this update immediately, overriding any long-running
tasks. tasks.
Satisfied by: REQ.USE.MFST.PRE_CHECK (Section 4.5.1) Satisfied by: REQ.USE.MFST.PRE_CHECK (Section 4.5.1)
4.4.2. USER_STORY.MFST.FAIL_EARLY: Fail Early 4.4.2. USER_STORY.MFST.FAIL_EARLY: Fail Early
As a designer of a resource-constrained IoT device, I want bad As a designer of a resource-constrained IoT device, I want bad
updates to fail as early as possible to preserve battery life and updates to fail as early as possible to preserve battery life and
limit consumed bandwidth. limit consumed bandwidth.
Satisfied by: REQ.USE.MFST.PRE_CHECK (Section 4.5.1) Satisfied by: REQ.USE.MFST.PRE_CHECK (Section 4.5.1)
4.4.3. USER_STORY.OVERRIDE: Override Non-Critical Manifest Elements 4.4.3. USER_STORY.OVERRIDE: Override Non-critical Manifest Elements
As a Device Operator, I would like to be able to override the non- As a device operator, I would like to be able to override the non-
critical information in the manifest so that I can control my devices critical information in the manifest so that I can control my devices
more precisely. The authority to override this information is more precisely. The authority to override this information is
provided via the installation of a limited trust anchor by another provided via the installation of a limited trust anchor by another
authority. authority.
Some examples of potentially overridable information: Some examples of potentially overridable information:
o URIs (Section 3.12): this allows the Device Operator to direct URIs (Section 3.12): This allows the device operator to direct
devices to their own infrastructure in order to reduce network devices to their own infrastructure in order to reduce network
load. load.
o Conditions: this allows the Device Operator to pose additional Conditions: This allows the device operator to impose additional
constraints on the installation of the manifest. constraints on the installation of the manifest.
o Directives (Section 3.16): this allows the Device Operator to add Directives (Section 3.16): This allows the device operator to add
more instructions such as time of installation. more instructions, such as time of installation.
o Processing Steps (Section 3.9): If an intermediary performs an Processing Steps (Section 3.9): If an intermediary performs an
action on behalf of a device, it may need to override the action on behalf of a device, it may need to override the
processing steps. It is still possible for a device to verify the processing steps. It is still possible for a device to verify the
final content and the result of any processing step that specifies final content and the result of any processing step that specifies
a digest. Some processing steps should be non-overridable. a digest. Some processing steps should be non-overridable.
Satisfied by: REQ.USE.MFST.COMPONENT (Section 4.5.4) Satisfied by: REQ.USE.MFST.COMPONENT (Section 4.5.4)
4.4.4. USER_STORY.COMPONENT: Component Update 4.4.4. USER_STORY.COMPONENT: Component Update
As a Device Operator, I want to divide my firmware into components, As a device operator, I want to divide my firmware into components,
so that I can reduce the size of updates, make different parties so that I can reduce the size of updates, make different parties
responsible for different components, and divide my firmware into responsible for different components, and divide my firmware into
frequently updated and infrequently updated components. frequently updated and infrequently updated components.
Satisfied by: REQ.USE.MFST.COMPONENT (Section 4.5.4) Satisfied by: REQ.USE.MFST.COMPONENT (Section 4.5.4)
4.4.5. USER_STORY.MULTI_AUTH: Multiple Authorizations 4.4.5. USER_STORY.MULTI_AUTH: Multiple Authorizations
As a Device Operator, I want to ensure the quality of a firmware As a device operator, I want to ensure the quality of a firmware
update before installing it, so that I can ensure interoperability of update before installing it, so that I can ensure interoperability of
all devices in my product family. I want to restrict the ability to all devices in my product family. I want to restrict the ability to
make changes to my devices to require my express approval. make changes to my devices to require my express approval.
Satisfied by: REQ.USE.MFST.MULTI_AUTH (Section 4.5.5), Satisfied by: REQ.USE.MFST.MULTI_AUTH (Section 4.5.5),
REQ.SEC.ACCESS_CONTROL (Section 4.3.13) REQ.SEC.ACCESS_CONTROL (Section 4.3.13)
4.4.6. USER_STORY.IMG.FORMAT: Multiple Payload Formats 4.4.6. USER_STORY.IMG.FORMAT: Multiple Payload Formats
As a Device Operator, I want to be able to send multiple payload As a device operator, I want to be able to send multiple payload
formats to suit the needs of my update, so that I can optimise the formats to suit the needs of my update, so that I can optimize the
bandwidth used by my devices. bandwidth used by my devices.
Satisfied by: REQ.USE.IMG.FORMAT (Section 4.5.6) Satisfied by: REQ.USE.IMG.FORMAT (Section 4.5.6)
4.4.7. USER_STORY.IMG.CONFIDENTIALITY: Prevent Confidential Information 4.4.7. USER_STORY.IMG.CONFIDENTIALITY: Prevent Confidential Information
Disclosures Disclosures
As a firmware author, I want to prevent confidential information in As a firmware author, I want to prevent confidential information in
the manifest from being disclosed when distributing manifests and the manifest from being disclosed when distributing manifests and
firmware images. Confidential information may include information firmware images. Confidential information may include information
about the device these updates are being applied to as well as about the device these updates are being applied to as well as
information in the firmware image itself. information in the firmware image itself.
Satisfied by: REQ.SEC.IMG.CONFIDENTIALITY (Section 4.3.12) Satisfied by: REQ.SEC.IMG.CONFIDENTIALITY (Section 4.3.12)
4.4.8. USER_STORY.IMG.UNKNOWN_FORMAT: Prevent Devices from Unpacking 4.4.8. USER_STORY.IMG.UNKNOWN_FORMAT: Prevent Devices from Unpacking
Unknown Formats Unknown Formats
As a Device Operator, I want devices to determine whether they can As a device operator, I want devices to determine whether they can
process a payload prior to downloading it. process a payload prior to downloading it.
In some cases, it may be desirable for a third party to perform some In some cases, it may be desirable for a third party to perform some
processing on behalf of a target. For this to occur, the third party processing on behalf of a target. For this to occur, the third party
MUST indicate what processing occurred and how to verify it against MUST indicate what processing occurred and how to verify it against
the Trust Provisioning Authority's intent. the Trust Provisioning Authority's intent.
This amounts to overriding Processing Steps (Section 3.9) and Payload This amounts to overriding Processing Steps (Section 3.9) and Payload
Indicator (Section 3.12). Indicator (Section 3.12).
Satisfied by: REQ.USE.IMG.FORMAT (Section 4.5.6), REQ.USE.IMG.NESTED Satisfied by: REQ.USE.IMG.FORMAT (Section 4.5.6), REQ.USE.IMG.NESTED
(Section 4.5.7), REQ.USE.MFST.OVERRIDE_REMOTE (Section 4.5.3) (Section 4.5.7), REQ.USE.MFST.OVERRIDE_REMOTE (Section 4.5.3)
4.4.9. USER_STORY.IMG.CURRENT_VERSION: Specify Version Numbers of 4.4.9. USER_STORY.IMG.CURRENT_VERSION: Specify Version Numbers of
Target Firmware Target Firmware
As a Device Operator, I want to be able to target devices for updates As a device operator, I want to be able to target devices for updates
based on their current firmware version, so that I can control which based on their current firmware version, so that I can control which
versions are replaced with a single manifest. versions are replaced with a single manifest.
Satisfied by: REQ.USE.IMG.VERSIONS (Section 4.5.8) Satisfied by: REQ.USE.IMG.VERSIONS (Section 4.5.8)
4.4.10. USER_STORY.IMG.SELECT: Enable Devices to Choose Between Images 4.4.10. USER_STORY.IMG.SELECT: Enable Devices to Choose between Images
As a developer, I want to be able to sign two or more versions of my As a developer, I want to be able to sign two or more versions of my
firmware in a single manifest so that I can use a very simple firmware in a single manifest so that I can use a very simple
bootloader that chooses between two or more images that are executed bootloader that chooses between two or more images that are executed
in-place. in place.
Satisfied by: REQ.USE.IMG.SELECT (Section 4.5.9) Satisfied by: REQ.USE.IMG.SELECT (Section 4.5.9)
4.4.11. USER_STORY.EXEC.MFST: Secure Execution Using Manifests 4.4.11. USER_STORY.EXEC.MFST: Secure Execution Using Manifests
As a signer for both secure execution/boot and firmware deployment, I As a signer for both secure execution/boot and firmware deployment, I
would like to use the same signed document for both tasks so that my would like to use the same signed document for both tasks so that my
data size is smaller, I can share common code, and I can reduce data size is smaller, I can share common code, and I can reduce
signature verifications. signature verifications.
Satisfied by: REQ.USE.EXEC (Section 4.5.10) Satisfied by: REQ.USE.EXEC (Section 4.5.10)
4.4.12. USER_STORY.EXEC.DECOMPRESS: Decompress on Load 4.4.12. USER_STORY.EXEC.DECOMPRESS: Decompress on Load
As a developer of firmware for a run-from-RAM device, I would like to As a developer of firmware for a run-from-RAM device, I would like to
use compressed images and to indicate to the bootloader that I am use compressed images and to indicate to the bootloader that I am
using a compressed image in the manifest so that it can be used with using a compressed image in the manifest so that it can be used with
secure execution/boot. secure execution/boot.
Satisfied by: REQ.USE.LOAD (Section 4.5.11) Satisfied by: REQ.USE.LOAD (Section 4.5.11)
4.4.13. USER_STORY.MFST.IMG: Payload in Manifest 4.4.13. USER_STORY.MFST.IMG: Payload in Manifest
As an operator of devices on a constrained network, I would like the As an Operator of devices on a constrained network, I would like the
manifest to be able to include a small payload in the same packet so manifest to be able to include a small payload in the same packet so
that I can reduce network traffic. that I can reduce network traffic.
Small payloads may include, for example, wrapped content encryption Small payloads may include, for example, wrapped content encryption
keys, configuration information, public keys, authorization tokens, keys, configuration information, public keys, authorization tokens,
or X.509 certificates. or X.509 certificates.
Satisfied by: REQ.USE.PAYLOAD (Section 4.5.12) Satisfied by: REQ.USE.PAYLOAD (Section 4.5.12)
4.4.14. USER_STORY.MFST.PARSE: Simple Parsing 4.4.14. USER_STORY.MFST.PARSE: Simple Parsing
As a developer for constrained devices, I want a low complexity As a developer for constrained devices, I want a low-complexity
library for processing updates so that I can fit more application library for processing updates so that I can fit more application
code on my device. code on my device.
Satisfied by: REQ.USE.PARSE (Section 4.5.13) Satisfied by: REQ.USE.PARSE (Section 4.5.13)
4.4.15. USER_STORY.MFST.DELEGATION: Delegated Authority in Manifest 4.4.15. USER_STORY.MFST.DELEGATION: Delegated Authority in Manifest
As a Device Operator that rotates delegated authority more often than As a device operator that rotates delegated authority more often than
delivering firmware updates, I would like to delegate a new authority delivering firmware updates, I would like to delegate a new authority
when I deliver a firmware update so that I can accomplish both tasks when I deliver a firmware update so that I can accomplish both tasks
in a single transmission. in a single transmission.
Satisfied by: REQ.USE.DELEGATION (Section 4.5.14) Satisfied by: REQ.USE.DELEGATION (Section 4.5.14)
4.4.16. USER_STORY.MFST.PRE_CHECK: Update Evaluation 4.4.16. USER_STORY.MFST.PRE_CHECK: Update Evaluation
As an operator of a constrained network, I would like devices on my As an Operator of a constrained network, I would like devices on my
network to be able to evaluate the suitability of an update prior to network to be able to evaluate the suitability of an update prior to
initiating any large download so that I can prevent unnecessary initiating any large download so that I can prevent unnecessary
consumption of bandwidth. consumption of bandwidth.
Satisfied by: REQ.USE.MFST.PRE_CHECK (Section 4.5.1) Satisfied by: REQ.USE.MFST.PRE_CHECK (Section 4.5.1)
4.4.17. USER_STORY.MFST.ADMINISTRATION: Administration of manifests 4.4.17. USER_STORY.MFST.ADMINISTRATION: Administration of Manifests
As a Device Operator, I want to understand what an update will do and As a device operator, I want to understand what an update will do and
to which devices it applies so that I can make informed choices about to which devices it applies so that I can make informed choices about
which updates to apply, when to apply them, and which devices should which updates to apply, when to apply them, and which devices should
be updated. be updated.
Satisfied by REQ.USE.MFST.TEXT (Section 4.5.2) Satisfied by: REQ.USE.MFST.TEXT (Section 4.5.2)
4.5. Usability Requirements 4.5. Usability Requirements
The following usability requirements satisfy the user stories listed The following usability requirements satisfy the user stories listed
above. above.
4.5.1. REQ.USE.MFST.PRE_CHECK: Pre-Installation Checks 4.5.1. REQ.USE.MFST.PRE_CHECK: Pre-installation Checks
A manifest format MUST be able to carry all information required to A manifest format MUST be able to carry all information required to
process an update. process an update.
For example: Information about which precursor image is required for For example, information about which precursor image is required for
a differential update must be placed in the manifest. a differential update must be placed in the manifest.
Satisfies: [USER_STORY.MFST.PRE_CHECK(#user-story-mfst-pre-check), Satisfies: USER_STORY.MFST.PRE_CHECK (Section 4.4.16),
USER_STORY.INSTALL.INSTRUCTIONS (Section 4.4.1) USER_STORY.INSTALL.INSTRUCTIONS (Section 4.4.1)
Implemented by: Additional installation instructions (Section 3.16) Implemented by: Additional Installation Instructions (Section 3.16)
4.5.2. REQ.USE.MFST.TEXT: Descriptive Manifest Information 4.5.2. REQ.USE.MFST.TEXT: Descriptive Manifest Information
It MUST be possible for a Device Operator to determine what a It MUST be possible for a device operator to determine what a
manifest will do and which devices will accept it prior to manifest will do and which devices will accept it prior to
distribution. distribution.
Satisfies: USER_STORY.MFST.ADMINISTRATION (Section 4.4.17) Satisfies: USER_STORY.MFST.ADMINISTRATION (Section 4.4.17)
Implemented by: Manifest text information (Section 3.17) Implemented by: Manifest Text Information (Section 3.17)
4.5.3. REQ.USE.MFST.OVERRIDE_REMOTE: Override Remote Resource Location 4.5.3. REQ.USE.MFST.OVERRIDE_REMOTE: Override Remote Resource Location
A manifest format MUST be able to redirect payload fetches. This A manifest format MUST be able to redirect payload fetches. This
applies where two manifests are used in conjunction. For example, a applies where two manifests are used in conjunction. For example, a
Device Operator creates a manifest specifying a payload and signs it, device operator creates a manifest specifying a payload and signs it,
and provides a URI for that payload. A Network Operator creates a and provides a URI for that payload. A network operator creates a
second manifest, with a dependency on the first. They use this second manifest, with a dependency on the first. They use this
second manifest to override the URIs provided by the Device Operator, second manifest to override the URIs provided by the device operator,
directing them into their own infrastructure instead. Some devices directing them into their own infrastructure instead. Some devices
may provide this capability, while others may only look at canonical may provide this capability, while others may only look at canonical
sources of firmware. For this to be possible, the device must fetch sources of firmware. For this to be possible, the device must fetch
the payload, whereas a device that accepts payload pushes will ignore the payload, whereas a device that accepts payload pushes will ignore
this feature. this feature.
Satisfies: USER_STORY.OVERRIDE (Section 4.4.3) Satisfies: USER_STORY.OVERRIDE (Section 4.4.3)
Implemented by: Aliases (Section 3.18) Implemented by: Aliases (Section 3.18)
4.5.4. REQ.USE.MFST.COMPONENT: Component Updates 4.5.4. REQ.USE.MFST.COMPONENT: Component Updates
A manifest format MUST be able to express the requirement to install A manifest format MUST be able to express the requirement to install
one or more payloads from one or more authorities so that a multi- one or more payloads from one or more authorities so that a multi-
payload update can be described. This allows multiple parties with payload update can be described. This allows multiple parties with
different permissions to collaborate in creating a single update for different permissions to collaborate in creating a single update for
the IoT device, across multiple components. the IoT device, across multiple components.
This requirement implies that it must be possible to construct a tree This requirement implies that it must be possible to construct a tree
of manifests on a multi-image target. of manifests on a multi-image target.
In order to enable devices with a heterogeneous storage architecture, In order to enable devices with a heterogeneous storage architecture,
the manifest must enable specification of both storage system and the the manifest must enable specification of both a storage system and
storage location within that storage system. the storage location within that storage system.
Satisfies: USER_STORY.OVERRIDE (Section 4.4.3), USER_STORY.COMPONENT Satisfies: USER_STORY.OVERRIDE (Section 4.4.3), USER_STORY.COMPONENT
(Section 4.4.4) (Section 4.4.4)
Implemented by: Dependencies, StorageIdentifier, ComponentIdentifier Implemented by: Dependencies, StorageIdentifier, ComponentIdentifier
4.5.4.1. Example 1: Multiple Microcontrollers 4.5.4.1. Example 1: Multiple Microcontrollers
An IoT device with multiple microcontrollers in the same physical An IoT device with multiple microcontrollers in the same physical
device will likely require multiple payloads with different component device will likely require multiple payloads with different component
identifiers. identifiers.
4.5.4.2. Example 2: Code and Configuration 4.5.4.2. Example 2: Code and Configuration
A firmware image can be divided into two payloads: code and A firmware image can be divided into two payloads: code and
skipping to change at page 39, line 33 skipping to change at line 1838
dependency structure between them. dependency structure between them.
4.5.4.3. Example 3: Multiple Software Modules 4.5.4.3. Example 3: Multiple Software Modules
A firmware image can be divided into multiple functional blocks for A firmware image can be divided into multiple functional blocks for
separate testing and distribution. This means that code would need separate testing and distribution. This means that code would need
to be distributed in multiple payloads. For example, this might be to be distributed in multiple payloads. For example, this might be
desirable in order to ensure that common code between devices is desirable in order to ensure that common code between devices is
identical in order to reduce distribution bandwidth. identical in order to reduce distribution bandwidth.
4.5.5. REQ.USE.MFST.MULTI_AUTH: Multiple authentications 4.5.5. REQ.USE.MFST.MULTI_AUTH: Multiple Authentications
A manifest format MUST be able to carry multiple signatures so that A manifest format MUST be able to carry multiple signatures so that
authorizations from multiple parties with different permissions can authorizations from multiple parties with different permissions can
be required in order to authorize installation of a manifest. be required in order to authorize installation of a manifest.
Satisfies: USER_STORY.MULTI_AUTH (Section 4.4.5) Satisfies: USER_STORY.MULTI_AUTH (Section 4.4.5)
Implemented by: Signature (Section 3.15) Implemented by: Signature (Section 3.15)
4.5.6. REQ.USE.IMG.FORMAT: Format Usability 4.5.6. REQ.USE.IMG.FORMAT: Format Usability
The manifest format MUST accommodate any payload format that an The manifest format MUST accommodate any payload format that an
Operator wishes to use. This enables the recipient to detect which Operator wishes to use. This enables the recipient to detect which
format the Operator has chosen. Some examples of payload format are: format the Operator has chosen. Some examples of payload format are
as follows:
o Binary * Binary
o Executable and Linkable Format (ELF) * Executable and Linkable Format (ELF)
o Differential
o Compressed * Differential
o Packed configuration * Compressed
o Intel HEX * Packed configuration
o Motorola S-Record * Intel HEX
Satisfies: USER_STORY.IMG.FORMAT (Section 4.4.6) * Motorola S-Record
USER_STORY.IMG.UNKNOWN_FORMAT (Section 4.4.8)
Implemented by: Payload Format (Section 3.8) Satisfies: USER_STORY.IMG.FORMAT (Section 4.4.6)
USER_STORY.IMG.UNKNOWN_FORMAT (Section 4.4.8)
Implemented by: Payload Format (Section 3.8)
4.5.7. REQ.USE.IMG.NESTED: Nested Formats 4.5.7. REQ.USE.IMG.NESTED: Nested Formats
The manifest format MUST accommodate nested formats, announcing to The manifest format MUST accommodate nested formats, announcing to
the target device all the nesting steps and any parameters used by the target device all the nesting steps and any parameters used by
those steps. those steps.
Satisfies: USER_STORY.IMG.CONFIDENTIALITY (Section 4.4.7) Satisfies: USER_STORY.IMG.CONFIDENTIALITY (Section 4.4.7)
Implemented by: Processing Steps (Section 3.9) Implemented by: Processing Steps (Section 3.9)
4.5.8. REQ.USE.IMG.VERSIONS: Target Version Matching 4.5.8. REQ.USE.IMG.VERSIONS: Target Version Matching
The manifest format MUST provide a method to specify multiple version The manifest format MUST provide a method to specify multiple version
numbers of firmware to which the manifest applies, either with a list numbers of firmware to which the manifest applies, either with a list
or with range matching. or with range matching.
Satisfies: USER_STORY.IMG.CURRENT_VERSION (Section 4.4.9) Satisfies: USER_STORY.IMG.CURRENT_VERSION (Section 4.4.9)
Implemented by: Required Image Version List (Section 3.6) Implemented by: Required Image Version List (Section 3.6)
4.5.9. REQ.USE.IMG.SELECT: Select Image by Destination 4.5.9. REQ.USE.IMG.SELECT: Select Image by Destination
The manifest format MUST provide a mechanism to list multiple The manifest format MUST provide a mechanism to list multiple
equivalent payloads by Execute-In-Place Installation Address, equivalent payloads by execute-in-place (XIP) installation address,
including the payload digest and, optionally, payload URIs. including the payload digest and, optionally, payload URIs.
Satisfies: USER_STORY.IMG.SELECT (Section 4.4.10) Satisfies: USER_STORY.IMG.SELECT (Section 4.4.10)
Implemented by: XIP Address (Section 3.21) Implemented by: XIP Address (Section 3.21)
4.5.10. REQ.USE.EXEC: Executable Manifest 4.5.10. REQ.USE.EXEC: Executable Manifest
The manifest format MUST allow to describe an executable system with The manifest format MUST allow the description of an executable
a manifest on both Execute-In-Place microcontrollers and on complex system with a manifest on both XIP microcontrollers and complex
operating systems. In addition, the manifest format MUST be able to operating systems. In addition, the manifest format MUST be able to
express metadata, such as a kernel command-line, used by any loader express metadata, such as a kernel command line, used by any loader
or bootloader. or bootloader.
Satisfies: USER_STORY.EXEC.MFST (Section 4.4.11) Satisfies: USER_STORY.EXEC.MFST (Section 4.4.11)
Implemented by: Run-time metadata (Section 3.23) Implemented by: Runtime Metadata (Section 3.23)
4.5.11. REQ.USE.LOAD: Load-Time Information 4.5.11. REQ.USE.LOAD: Load-Time Information
The manifest format MUST enable carrying additional metadata for load The manifest format MUST enable carrying additional metadata for
time processing of a payload, such as cryptographic information, load-time processing of a payload, such as cryptographic information,
load-address, and compression algorithm. Note that load comes before load address, and compression algorithm. Note that load comes before
execution/boot. execution/boot.
Satisfies: USER_STORY.EXEC.DECOMPRESS (Section 4.4.12) Satisfies: USER_STORY.EXEC.DECOMPRESS (Section 4.4.12)
Implemented by: Load-time metadata (Section 3.22) Implemented by: Load-Time Metadata (Section 3.22)
4.5.12. REQ.USE.PAYLOAD: Payload in Manifest Envelope 4.5.12. REQ.USE.PAYLOAD: Payload in Manifest Envelope
The manifest format MUST allow placing a payload in the same The manifest format MUST allow placing a payload in the same
structure as the manifest. This may place the payload in the same structure as the manifest. This may place the payload in the same
packet as the manifest. packet as the manifest.
Integrated payloads may include, for example, binaries as well as Integrated payloads may include, for example, binaries as well as
configuration information, and keying material. configuration information, and keying material.
When an integrated payload is provided, this increases the size of When an integrated payload is provided, this increases the size of
the manifest. Manifest size can cause several processing and storage the manifest. Manifest size can cause several processing and storage
concerns that require careful consideration. The payload can prevent concerns that require careful consideration. The payload can prevent
the whole manifest from being contained in a single network packet, the whole manifest from being contained in a single network packet,
which can cause fragmentation and the loss of portions of the which can cause fragmentation and the loss of portions of the
manifest in lossy networks. This causes the need for reassembly and manifest in lossy networks. This causes the need for reassembly and
retransmission logic. The manifest MUST be held immutable between retransmission logic. The manifest MUST be held immutable between
verification and processing (see REQ.SEC.MFST.CONST verification and processing (see REQ.SEC.MFST.CONST
(Section 4.3.21)), so a larger manifest will consume more memory with (Section 4.3.21)), so a larger manifest will consume more memory with
immutability guarantees, for example internal RAM or NVRAM, or immutability guarantees -- for example, internal RAM or NVRAM, or
external secure memory. If the manifest exceeds the available external secure memory. If the manifest exceeds the available
immutable memory, then it MUST be processed modularly, evaluating immutable memory, then it MUST be processed modularly, evaluating
each of: delegation chains, the security container, and the actual each of the following: delegation chains; the security container; and
manifest, which includes verifying the integrated payload. If the the actual manifest, which includes verifying the integrated payload.
security model calls for downloading the manifest and validating it If the security model calls for downloading the manifest and
before storing to NVRAM in order to prevent wear to NVRAM and energy validating it before storing to NVRAM in order to prevent wear to
expenditure in NVRAM, then either increasing memory allocated to NVRAM and energy expenditure in NVRAM, then either increasing memory
manifest storage or modular processing of the received manifest may allocated to manifest storage or modular processing of the received
be required. While the manifest has been organised to enable this manifest may be required. While the manifest has been organized to
type of processing, it creates additional complexity in the parser. enable this type of processing, it creates additional complexity in
If the manifest is stored in NVRAM prior to processing, the the parser. If the manifest is stored in NVRAM prior to processing,
integrated payload may cause the manifest to exceed the available the integrated payload may cause the manifest to exceed the available
storage. Because the manifest is received prior to validation of storage. Because the manifest is received prior to validation of
applicability, authority, or correctness, integrated payloads cause applicability, authority, or correctness, integrated payloads cause
the recipient to expend network bandwidth and energy that may not be the recipient to expend network bandwidth and energy that may not be
required if the manifest is discarded and these costs vary with the required if the manifest is discarded, and these costs vary with the
size of the integrated payload. size of the integrated payload.
See also: REQ.SEC.MFST.CONST (Section 4.3.21). See also: REQ.SEC.MFST.CONST (Section 4.3.21)
Satisfies: USER_STORY.MFST.IMG (Section 4.4.13) Satisfies: USER_STORY.MFST.IMG (Section 4.4.13)
Implemented by: Payload (Section 3.24) Implemented by: Payload (Section 3.24)
4.5.13. REQ.USE.PARSE: Simple Parsing 4.5.13. REQ.USE.PARSE: Simple Parsing
The structure of the manifest MUST be simple to parse to reduce the The structure of the manifest MUST be simple to parse to reduce the
attack vectors against manifest parsers. attack vectors against manifest parsers.
Satisfies: USER_STORY.MFST.PARSE (Section 4.4.14) Satisfies: USER_STORY.MFST.PARSE (Section 4.4.14)
Implemented by: N/A Implemented by: N/A
4.5.14. REQ.USE.DELEGATION: Delegation of Authority in Manifest 4.5.14. REQ.USE.DELEGATION: Delegation of Authority in Manifest
A manifest format MUST enable the delivery of delegation information. A manifest format MUST enable the delivery of delegation information.
This information delivers a new key with which the recipient can This information delivers a new key with which the recipient can
verify the manifest. verify the manifest.
Satisfies: USER_STORY.MFST.DELEGATION (Section 4.4.15) Satisfies: USER_STORY.MFST.DELEGATION (Section 4.4.15)
Implemented by: Delegation Chain (Section 3.25) Implemented by: Delegation Chain (Section 3.25)
5. IANA Considerations 5. IANA Considerations
This document does not require any actions by IANA. This document has no IANA actions.
6. Acknowledgements
We would like to thank our working group chairs, Dave Thaler, Russ
Housley and David Waltermire, for their review comments and their
support.
We would like to thank the participants of the 2018 Berlin SUIT
Hackathon and the June 2018 virtual design team meetings for their
discussion input.
In particular, we would like to thank Koen Zandberg, Emmanuel
Baccelli, Carsten Bormann, David Brown, Markus Gueller, Frank Audun
Kvamtro, Oyvind Ronningstad, Michael Richardson, Jan-Frederik
Rieckers, Francisco Acosta, Anton Gerasimov, Matthias Waehlisch, Max
Groening, Daniel Petry, Gaetan Harter, Ralph Hamm, Steve Patrick,
Fabio Utzig, Paul Lambert, Said Gharout, and Milen Stoychev.
We would like to thank those who contributed to the development of
this information model. In particular, we would like to thank
Milosch Meriac, Jean-Luc Giraud, Dan Ros, Amyas Philips, and Gary
Thomson.
Finally, we would like to thank the following IESG members for their
review feedback: Erik Kline, Murray Kucherawy, Barry Leiba, Alissa
Cooper, Stephen Farrell and Benjamin Kaduk.
7. References
7.1. Normative References 6. References
[I-D.ietf-suit-architecture] 6.1. Normative References
Moran, B., Tschofenig, H., Brown, D., and M. Meriac, "A
Firmware Update Architecture for Internet of Things",
draft-ietf-suit-architecture-16 (work in progress),
January 2021.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally
Unique IDentifier (UUID) URN Namespace", RFC 4122, Unique IDentifier (UUID) URN Namespace", RFC 4122,
DOI 10.17487/RFC4122, July 2005, DOI 10.17487/RFC4122, July 2005,
<https://www.rfc-editor.org/info/rfc4122>. <https://www.rfc-editor.org/info/rfc4122>.
skipping to change at page 44, line 10 skipping to change at line 2020
[RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, [RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig,
"CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392,
May 2018, <https://www.rfc-editor.org/info/rfc8392>. May 2018, <https://www.rfc-editor.org/info/rfc8392>.
[RFC8747] Jones, M., Seitz, L., Selander, G., Erdtman, S., and H. [RFC8747] Jones, M., Seitz, L., Selander, G., Erdtman, S., and H.
Tschofenig, "Proof-of-Possession Key Semantics for CBOR Tschofenig, "Proof-of-Possession Key Semantics for CBOR
Web Tokens (CWTs)", RFC 8747, DOI 10.17487/RFC8747, March Web Tokens (CWTs)", RFC 8747, DOI 10.17487/RFC8747, March
2020, <https://www.rfc-editor.org/info/rfc8747>. 2020, <https://www.rfc-editor.org/info/rfc8747>.
7.2. Informative References [RFC9019] Moran, B., Tschofenig, H., Brown, D., and M. Meriac, "A
Firmware Update Architecture for Internet of Things",
RFC 9019, DOI 10.17487/RFC9019, April 2021,
<https://www.rfc-editor.org/info/rfc9019>.
6.2. Informative References
[RFC3444] Pras, A. and J. Schoenwaelder, "On the Difference between [RFC3444] Pras, A. and J. Schoenwaelder, "On the Difference between
Information Models and Data Models", RFC 3444, Information Models and Data Models", RFC 3444,
DOI 10.17487/RFC3444, January 2003, DOI 10.17487/RFC3444, January 2003,
<https://www.rfc-editor.org/info/rfc3444>. <https://www.rfc-editor.org/info/rfc3444>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005, RFC 3986, DOI 10.17487/RFC3986, January 2005,
<https://www.rfc-editor.org/info/rfc3986>. <https://www.rfc-editor.org/info/rfc3986>.
[STRIDE] Microsoft, "The STRIDE Threat Model", May 2018, [STRIDE] Microsoft, "The STRIDE Threat Model", November 2009,
<https://msdn.microsoft.com/en-us/library/ <https://docs.microsoft.com/en-us/previous-versions/
ee823878(v=cs.20).aspx>. commerce-server/ee823878(v=cs.20)?redirectedfrom=MSDN>.
Acknowledgements
We would like to thank our working group chairs -- Dave Thaler, Russ
Housley, and David Waltermire -- for their review comments and their
support.
We would like to thank the participants of the 2018 Berlin Software
Updates for Internet of Things (SUIT) Hackathon and the June 2018
virtual design team meetings for their discussion input.
In particular, we would like to thank Koen Zandberg, Emmanuel
Baccelli, Carsten Bormann, David Brown, Markus Gueller, Frank Audun
Kvamtrø, Øyvind Rønningstad, Michael Richardson, Jan-Frederik
Rieckers, Francisco Acosta, Anton Gerasimov, Matthias Wählisch, Max
Gröning, Daniel Petry, Gaëtan Harter, Ralph Hamm, Steve Patrick,
Fabio Utzig, Paul Lambert, Saïd Gharout, and Milen Stoychev.
We would like to thank those who contributed to the development of
this information model. In particular, we would like to thank
Milosch Meriac, Jean-Luc Giraud, Dan Ros, Amyas Phillips, and Gary
Thomson.
Finally, we would like to thank the following IESG members for their
review feedback: Erik Kline, Murray Kucherawy, Barry Leiba, Alissa
Cooper, Stephen Farrell, and Benjamin Kaduk.
Authors' Addresses Authors' Addresses
Brendan Moran Brendan Moran
Arm Limited Arm Limited
EMail: Brendan.Moran@arm.com Email: Brendan.Moran@arm.com
Hannes Tschofenig Hannes Tschofenig
Arm Limited Arm Limited
EMail: hannes.tschofenig@gmx.net Email: hannes.tschofenig@gmx.net
Henk Birkholz Henk Birkholz
Fraunhofer SIT Fraunhofer SIT
EMail: henk.birkholz@sit.fraunhofer.de Email: henk.birkholz@sit.fraunhofer.de
 End of changes. 417 change blocks. 
823 lines changed or deleted 830 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/