Internet DRAFT - draft-ietf-suit-firmware-encryption
draft-ietf-suit-firmware-encryption
SUIT H. Tschofenig
Internet-Draft
Intended status: Standards Track R. Housley
Expires: 3 September 2024 Vigil Security
B. Moran
Arm Limited
D. Brown
Linaro
K. Takayama
SECOM CO., LTD.
2 March 2024
Encrypted Payloads in SUIT Manifests
draft-ietf-suit-firmware-encryption-19
Abstract
This document specifies techniques for encrypting software, firmware,
machine learning models, and personalization data by utilizing the
IETF SUIT manifest. Key agreement is provided by ephemeral-static
(ES) Diffie-Hellman (DH) and AES Key Wrap (AES-KW). ES-DH uses
public key cryptography while AES-KW uses a pre-shared key.
Encryption of the plaintext is accomplished with conventional
symmetric key cryptography.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on 3 September 2024.
Copyright Notice
Copyright (c) 2024 IETF Trust and the persons identified as the
document authors. All rights reserved.
Tschofenig, et al. Expires 3 September 2024 [Page 1]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components
extracted from this document must include Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Conventions and Terminology . . . . . . . . . . . . . . . . . 4
3. Architecture . . . . . . . . . . . . . . . . . . . . . . . . 5
4. Encryption Extensions . . . . . . . . . . . . . . . . . . . . 8
5. Extended Directives . . . . . . . . . . . . . . . . . . . . . 8
6. Content Key Distribution . . . . . . . . . . . . . . . . . . 10
6.1. Content Key Distribution with AES Key Wrap . . . . . . . 10
6.1.1. Introduction . . . . . . . . . . . . . . . . . . . . 11
6.1.2. Deployment Options . . . . . . . . . . . . . . . . . 11
6.1.3. CDDL . . . . . . . . . . . . . . . . . . . . . . . . 12
6.2. Content Key Distribution with Ephemeral-Static
Diffie-Hellman . . . . . . . . . . . . . . . . . . . . . 13
6.2.1. Introduction . . . . . . . . . . . . . . . . . . . . 13
6.2.2. Deployment Options . . . . . . . . . . . . . . . . . 14
6.2.3. CDDL . . . . . . . . . . . . . . . . . . . . . . . . 15
6.2.4. Context Information Structure . . . . . . . . . . . . 16
7. Content Encryption . . . . . . . . . . . . . . . . . . . . . 17
7.1. AES-GCM . . . . . . . . . . . . . . . . . . . . . . . . . 18
7.1.1. Introduction . . . . . . . . . . . . . . . . . . . . 18
7.1.2. AES-KW + AES-GCM Example . . . . . . . . . . . . . . 19
7.1.3. ECDH-ES+AES-KW + AES-GCM Example . . . . . . . . . . 20
7.2. AES-CTR . . . . . . . . . . . . . . . . . . . . . . . . . 21
7.2.1. Introduction . . . . . . . . . . . . . . . . . . . . 22
7.2.2. AES-KW + AES-CTR Example . . . . . . . . . . . . . . 23
7.2.3. ECDH-ES+AES-KW + AES-CTR Example . . . . . . . . . . 24
7.3. AES-CBC . . . . . . . . . . . . . . . . . . . . . . . . . 25
7.3.1. Introduction . . . . . . . . . . . . . . . . . . . . 25
7.3.2. AES-KW + AES-CBC Example . . . . . . . . . . . . . . 27
7.3.3. ECDH-ES+AES-KW + AES-CBC Example . . . . . . . . . . 28
8. Integrity Check on Encrypted and Decrypted Payloads . . . . . 29
8.1. Validating Payload Integrity . . . . . . . . . . . . . . 29
8.1.1. Image Match after Decryption . . . . . . . . . . . . 30
8.1.2. Image Match before Decryption . . . . . . . . . . . . 30
8.1.3. Checking Authentication Tag while Decryption . . . . 31
8.2. Payload Integrity in SUIT Manifest . . . . . . . . . . . 31
9. Firmware Updates on IoT Devices with Flash Memory . . . . . . 33
10. Complete Examples . . . . . . . . . . . . . . . . . . . . . . 35
Tschofenig, et al. Expires 3 September 2024 [Page 2]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
10.1. AES Key Wrap Example with Write Directive . . . . . . . 36
10.2. AES Key Wrap Example with Fetch + Copy Directives . . . 38
10.3. ES-DH Example with Write + Copy Directives . . . . . . . 40
10.4. ES-DH Example with Dependency . . . . . . . . . . . . . 42
11. Operational Considerations . . . . . . . . . . . . . . . . . 46
12. Security Considerations . . . . . . . . . . . . . . . . . . . 47
13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 49
14. References . . . . . . . . . . . . . . . . . . . . . . . . . 49
14.1. Normative References . . . . . . . . . . . . . . . . . . 49
14.2. Informative References . . . . . . . . . . . . . . . . . 50
Appendix A. Full CDDL . . . . . . . . . . . . . . . . . . . . . 51
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 51
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 51
1. Introduction
Vulnerabilities with Internet of Things (IoT) devices have raised the
need for a reliable and secure firmware update mechanism that is also
suitable for constrained devices. To protect firmware images, the
SUIT manifest format was developed [I-D.ietf-suit-manifest]. It
provides a bundle of metadata, including where to find the payload,
the devices to which it applies and a security wrapper.
[RFC9124] details the information that has to be provided by the SUIT
manifest format. In addition to offering protection against
modification, via a digital signature or a message authentication
code, confidentiality may also be afforded.
Encryption prevents third parties, including attackers, from gaining
access to the payload. Attackers typically need intimate knowledge
of a binary, such as a firmware image, to mount their attacks. For
example, return-oriented programming (ROP) [ROP] requires access to
the binary and encryption makes it much more difficult to write
exploits. Beside confidentiality of the binary, confidentiality of
the sources (e.g. in case of open source software) may be required as
well to prevent reverse engineering and/or reproduction of the binary
firmware.
While the original motivating use case of this document was firmware
encryption, the use of SUIT manifests has been extended to other use
cases requiring integrity and confidentiality protection, such as:
* software packages,
* personalization data,
* configuration data, and
Tschofenig, et al. Expires 3 September 2024 [Page 3]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
* machine learning models.
Hence, we use the term payload to generically refer to all those
objects.
The payload is encrypted using a symmetric content encryption key,
which can be established using a variety of mechanisms; this document
defines two content key distribution methods for use with the IETF
SUIT manifest, namely:
* Ephemeral-Static (ES) Diffie-Hellman (DH), and
* AES Key Wrap (AES-KW).
The former method relies on asymmetric key cryptography while the
latter uses symmetric key cryptography.
Our design aims to reduce the number of content key distribution
methods for use with payload encryption and thereby increase
interoperability between different SUIT manifest parser
implementations.
The goal of this specification is to protect payloads during end-to-
end transport, and at rest when stored on a device. Constrained
devices often make use of XIP, which is a method of executing code
directly from flash memory rather than copying it into RAM. Since
many of these devices today do not offer hardware-based, on-the-fly
decryption of code stored in flash memory, it may be necessary to
decrypt and store firmware images in on-chip flash before code can be
executed. We do, however, expect that hardware-based, on-the-fly
decryption will become more common in the future, which will improve
confidentiality at rest.
2. Conventions and Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
This document assumes familiarity with the IETF SUIT manifest
[I-D.ietf-suit-manifest], the SUIT information model [RFC9124], and
the SUIT architecture [RFC9019].
The following abbreviations are used in this document:
* Key Wrap (KW), defined in [RFC3394] (for use with AES)
Tschofenig, et al. Expires 3 September 2024 [Page 4]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
* Key-Encryption Key (KEK) [RFC3394]
* Content-Encryption Key (CEK) [RFC5652]
* Ephemeral-Static (ES) Diffie-Hellman (DH) [RFC9052]
* Authenticated Encryption with Associated Data (AEAD)
* Execute in Place (XIP)
The terms sender and recipient have the following meaning:
* Sender: Entity that sends an encrypted payload.
* Recipient: Entity that receives an encrypted payload.
Additionally, we introduce the term "distribution system" (or
distributor) to refer to an entity that knows the recipients of
payloads. It is important to note that the distribution system is
far more than a file server. For use of encryption, the distribution
system either knows the public key of the recipient (for ES-DH), or
the KEK (for AES-KW).
The author, which is responsible for creating the payload, does not
know the recipients. The authors may, for example, be a developer
building a firmware image.
The author and the distribution system are logical roles. In some
deployments these roles are separated in different physical entities
and in others they are co-located.
3. Architecture
[RFC9019] describes the architecture for distributing payloads and
manifests from an author to devices. It does, however, not detail
the use of payload encryption. This document enhances the
architecture to support encryption and Figure 1 shows it graphically.
To encrypt a payload it is necessary to know the recipient. For AES-
KW, the KEK needs to be known and, in case of ES-DH, the sender needs
to be in possession of the public key of the recipient. The public
key and parameters may be in the recipient's X.509 certificate
[RFC5280]. For authentication of the sender and for integrity
protection the recipients must be provisioned with a trust anchor
when a manifest is protected using a digital signature. When a MAC
is used to protect the manifest then a symmetric key must be shared
by the recipient and the sender.
Tschofenig, et al. Expires 3 September 2024 [Page 5]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
With encryption, the author cannot just create a manifest for the
payload and sign it, since it typically does not know the recipients.
Hence, the author has to collaborate with the distribution system.
The varying degree of collaboration is discussed below.
+----------+
| Device | +----------+
| 1 |<--+ | Author |
| | | +----------+
+----------+ | |
| | Payload +
| | Manifest
| v
+----------+ | +--------------+
| Device | | Payload + Manifest | Distribution |
| 2 |<--+------------------------| System |
| | | +--------------+
+----------+ |
|
... |
|
+----------+ |
| Device | |
| n |<--+
| |
+----------+
Figure 1: Architecture for the distribution of Encrypted Payloads.
The author has several deployment options, namely:
* The author, as the sender, obtains information about the
recipients and their keys from the distribution system. There are
proprietary as well as standardized device management solutions
available providing this functionality, as discussed in [RFC9019].
Then, it performs the necessary steps to encrypt the payload. As
a last step it creates one or more manifests. The device(s)
perform decryption and act as recipients.
Tschofenig, et al. Expires 3 September 2024 [Page 6]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
* The author treats the distribution system as the initial
recipient. The author typically uses REST APIs or web user
interfaces to interact with the distribution system. Then, the
distribution system decrypts and re-encrypts the payload for
consumption by the device (or the devices). Delegating the task
of re-encrypting the payload to the distribution system offers
flexibility when the number of devices that need to receive
encrypted payloads changes dynamically or when updates to KEKs or
recipient public keys are necessary. As a downside, the author
needs to trust the distribution system with performing the re-
encryption of the payload.
If the author delegates encryption rights to the distributor two
models are possible:
1. The distributor replaces the COSE_Encrypt in the manifest and
then signs the manifest again. However, the COSE_Encrypt
structure is contained within a signed container, which presents
a problem: replacing the COSE_Encrypt with a new one will cause
the digest of the manifest to change, thereby changing the
signature. This means that the distributor must be able to sign
the new manifest. If this is the case, then the distributor
gains the ability to construct and sign manifests, which allows
the distributor the authority to sign code, effectively
presenting the distributor with full control over the recipient.
Because distributors typically perform their re-encryption online
in order to handle a large number of devices in a timely fashion,
it is not possible to air-gap the distributor's signing
operations. This impacts the recommendations in Section 4.3.17
of [RFC9124]. This model nevertheless represent the current
state of firmware updates for IoT devices.
2. The distributor uses a two-layer manifest system. More
precisely, the distributor constructs a new manifest that
overrides the COSE_Encrypt using the dependency system defined in
[I-D.ietf-suit-trust-domains]. This incurs additional overhead:
one additional signature verification and one additional
manifest, as well as the additional machinery in the recipient
needed for dependency processing. This extra complexity offers
extra security.
These two models also present different threat profiles for the
distributor. If the distributor only has encryption rights, then an
attacker who breaches the distributor can only mount a limited
attack: they can encrypt a modified binary, but the recipients will
identify the attack as soon as they perform the required image digest
check and revert back to a correct image immediately.
Tschofenig, et al. Expires 3 September 2024 [Page 7]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
It is RECOMMENDED that distributors implement the two-layer manifest
approach in order to distribute content encryption keys without
requiring re-signing of the manifest, despite the increase in
complexity and greater number of signature verifications that this
imposes on the recipient.
4. Encryption Extensions
This specification introduces a new extension to the SUIT_Parameters
structure.
The SUIT_Encryption_Info structure (called suit-parameter-encryption-
info in Figure 2) contains the content key distribution information.
The content of the SUIT_Encryption_Info structure is explained in
Section 6.1 (for AES-KW) and in Section 6.2 (for ES-DH).
Once a CEK is available, the steps described in Section 7 are
applicable. These steps apply to both content key distribution
methods described in this section.
The SUIT_Encryption_Info structure is either carried inside the suit-
directive-override-parameters or the suit-directive-set-parameters
parameters used in the "Directive Write" and "Directive Copy"
directives. An implementation claiming conformance with this
specification must implement support for these two parameters. Since
a device will typically only support one of the content key
distribution methods, the distribution system needs to know which of
two specified methods wis supported. Mandating only a single content
key distribution method for a constrained device also reduces the
code size.
SUIT_Parameters //= (suit-parameter-encryption-info
=> bstr .cbor SUIT_Encryption_Info)
suit-parameter-encryption-info = 19
Figure 2: CDDL of the SUIT_Parameters Extension.
RFC Editor's Note (TBD19): The value for the suit-parameter-
encryption-info parameter is set to 19, as the proposed value.
5. Extended Directives
This specification extends these directives:
* Directive Write (suit-directive-write) to decrypt the content
specified by suit-parameter-content with suit-parameter-
encryption-info.
Tschofenig, et al. Expires 3 September 2024 [Page 8]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
* Directive Copy (suit-directive-copy) to decrypt the content of the
component specified by suit-parameter-source-component with suit-
parameter-encryption-info.
Examples of the two directives are shown below.
Figure 3 illustrates the Directive Write. The encrypted payload
specified with parameter-content, namely h'EA1...CED' in the example,
is decrypted using the SUIT_Encryption_Info structure referred to by
parameter-encryption-info, i.e., h'D86...1F0'. The resulting
plaintext payload is stored into component #0.
/ directive-override-parameters / 20, {
/ parameter-content / 18: h'EA1...CED',
/ parameter-encryption-info / 19: h'D86...1F0'
},
/ directive-write / 18, 15
Figure 3: Example showing the extended suit-directive-write.
Figure 4 illustrates the Directive Copy. In this example the
encrypted payload is found at the URI indicated by the parameter-uri,
i.e. "http://example.com/encrypted.bin". The encrypted payload will
be downloaded and stored in component #1. Then, the information in
the SUIT_Encryption_Info structure referred to by parameter-
encryption-info, i.e. h'D86...1F0', will be used to decrypt the
content in component #1 and the resulting plaintext payload will be
stored into component #0.
/ directive-set-component-index / 12, 1,
/ directive-override-parameters / 20, {
/ parameter-uri / 21: "http://example.com/encrypted.bin",
},
/ directive-fetch / 21, 15,
/ directive-set-component-index / 12, 0,
/ directive-override-parameters / 20, {
/ parameter-encryption-info / 19: h'D86...1F0',
/ parameter-source-component / 22: 1
},
/ directive-copy / 22, 15
Figure 4: Example showing the extended suit-directive-copy.
The payload to be encrypted may be detached and, in that case, it is
not covered by the digital signature or the MAC protecting the
manifest. (To be more precise, the suit-authentication-wrapper found
in the envelope contains a digest of the manifest in the SUIT Digest
Container.)
Tschofenig, et al. Expires 3 September 2024 [Page 9]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
The lack of authentication and integrity protection of the payload is
particularly a concern when a cipher without integrity protection is
used.
To provide authentication and integrity protection of the payload in
the detached payload case a SUIT Digest Container with the hash of
the encrypted and/or plaintext payload MUST be included in the
manifest. See suit-parameter-image-digest parameter in
Section 8.4.8.6 of [I-D.ietf-suit-manifest].
Once a CEK is available, the steps described in Section 7 are
applicable. These steps apply to both content key distribution
methods.
6. Content Key Distribution
The sub-sections below describe two content key distribution methods,
namely AES Key Wrap (AES-KW) and Ephemeral-Static Diffie-Hellman (ES-
DH). Many other methods are specified in the literature, and even
supported by COSE. AES-KW and ES-DH cover the popular methods used
in the market today and they were selected due to their maturity,
different security properties, and because of their interoperability
properties.
The two content key distribution methods require the CEKs to be
randomly generated. The guidelines for random number generation in
[RFC8937] MUST be followed.
When an encrypted payload is sent to multiple recipients, there are
different deployment options. To explain these options we use the
following notation:
- KEK(R1, S) refers to a KEK shared between recipient R1 and
the sender S.
- CEK(R1, S) refers to a CEK shared between R1 and S.
- CEK(*, S) or KEK(*, S) are used when a single CEK or a single
KEK is shared with all authorized recipients by a given sender
S in a certain context.
- ENC(plaintext, k) refers to the encryption of plaintext with
a key k.
6.1. Content Key Distribution with AES Key Wrap
Tschofenig, et al. Expires 3 September 2024 [Page 10]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
6.1.1. Introduction
The AES Key Wrap (AES-KW) algorithm is described in [RFC3394], and
can be used to encrypt a randomly generated content-encryption key
(CEK) with a pre-shared key-encryption key (KEK). The COSE
conventions for using AES-KW are specified in Section 8.5.2 of
[RFC9052] and in Section 6.2.1 of [RFC9053]. The encrypted CEK is
carried in the COSE_recipient structure alongside the information
needed for AES-KW. The COSE_recipient structure, which is a
substructure of the COSE_Encrypt structure, contains the CEK
encrypted by the KEK.
To provide high security for AES Key Wrap, it is important that the
KEK is of high entropy, and that implementations protect the KEK from
disclosure. Compromise of the KEK may result in the disclosure of
all data protected with that KEK, including binaries, and
configuration data.
The COSE_Encrypt structure conveys information for encrypting the
payload, which includes information like the algorithm and the IV,
even though the payload may not be embedded in the
COSE_Encrypt.ciphertext if it is conveyed as detached content.
6.1.2. Deployment Options
There are three deployment options for use with AES Key Wrap for
payload encryption:
* If all recipients (typically of the same product family) share the
same KEK, a single COSE_recipient structure contains the encrypted
CEK. The sender executes the following steps:
1. Fetch KEK(*, S)
2. Generate CEK
3. ENC(CEK, KEK)
4. ENC(payload, CEK)
This deployment option is strongly discouraged. An attacker gaining
access to the KEK will be able to encrypt and send payloads to all
recipients configured to use this KEK.
Tschofenig, et al. Expires 3 September 2024 [Page 11]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
* If recipients have different KEKs, then multiple COSE_recipient
structures are included but only a single CEK is used. Each
COSE_recipient structure contains the CEK encrypted with the KEKs
appropriate for a given recipient. The benefit of this approach
is that the payload is encrypted only once with a CEK while there
is no sharing of the KEK across recipients. Hence, authorized
recipients still use their individual KEK to decrypt the CEK and
to subsequently obtain the plaintext. The steps taken by the
sender are:
1. Generate CEK
2. for i=1 to n
{
2a. Fetch KEK(Ri, S)
2b. ENC(CEK, KEK(Ri, S))
}
3. ENC(payload, CEK)
* The third option is to use different CEKs encrypted with KEKs of
authorized recipients. This approach is appropriate when no
benefits can be gained from encrypting and transmitting payloads
only once. Assume there are n recipients with their unique KEKs -
KEK(R1, S), ..., KEK(Rn, S) and unique CEKs. The sender needs to
execute the following steps:
1. for i=1 to n
{
1a. Fetch KEK(Ri, S)
1b. Generate CEK(Ri, S)
1c. ENC(CEK(Ri, S), KEK(Ri, S))
1d. ENC(payload, CEK(Ri, S))
2. }
6.1.3. CDDL
The CDDL for the AES-KW binary is shown in Figure 5.
empty_or_serialized_map and header_map are structures defined in
[RFC9052].
Tschofenig, et al. Expires 3 September 2024 [Page 12]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
SUIT_Encryption_Info_AESKW = #6.96([
protected : outer_header_map_protected,
unprotected : outer_header_map_unprotected,
ciphertext : bstr / nil,
recipients : [ + COSE_recipient_AESKW ]
])
outer_header_map_protected = empty_or_serialized_map
outer_header_map_unprotected = header_map
COSE_recipient_AESKW = [
protected : bstr .size 0 / bstr .cbor empty_map,
unprotected : recipient_header_unpr_map_aeskw,
ciphertext : bstr ; CEK encrypted with KEK
]
empty_map = {}
recipient_header_unpr_map_aeskw =
{
1 => int, ; algorithm identifier
? 4 => bstr, ; identifier of the KEK pre-shared with the recipient
* label => values ; extension point
}
Figure 5: CDDL for AES-KW-based Content Key Distribution
Note that the AES-KW algorithm, as defined in Section 2.2.3.1 of
[RFC3394], does not have public parameters that vary on a per-
invocation basis. Hence, the protected header in the COSE_recipient
structure is a byte string of zero length.
6.2. Content Key Distribution with Ephemeral-Static Diffie-Hellman
6.2.1. Introduction
Ephemeral-Static Diffie-Hellman (ES-DH) is a scheme that provides
public key encryption given a recipient's public key. There are
multiple variants of this scheme; this document re-uses the variant
specified in Section 8.5.5 of [RFC9052].
The following two layer structure is used:
* Layer 0: Has a content encrypted with the CEK. The content may be
detached.
Tschofenig, et al. Expires 3 September 2024 [Page 13]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
* Layer 1: Uses the AES Key Wrap algorithm to encrypt the randomly
generated CEK with the KEK derived with ES-DH, whereby the
resulting symmetric key is fed into the HKDF-based key derivation
function.
As a result, the two layers combine ES-DH with AES-KW and HKDF, and
it is called ECDH-ES + AES-KW. An example is given in Figure 10.
There exists another version of ES-DH algorithm, namely ECDH-ES +
HKDF, which does not use AES Key Wrap. It is not specified in this
document.
6.2.2. Deployment Options
There are only two deployment options with this approach since we
assume that recipients are always configured with a device-unique
public / private key pair.
* A sender wants to transmit a payload to multiple recipients and
all recipients receive the same encrypted payload, i.e. the same
CEK is used to encrypt the payload. One COSE_recipient structure
per recipient is used and it contains the CEK encrypted with the
KEK. To generate the KEK each COSE_recipient structure contains a
COSE_recipient_inner structure to carry the sender's ephemeral key
and an identifier for the recipients public key.
The steps taken by the sender are:
1. Generate CEK
2. for i=1 to n
{
2a. Generate KEK(Ri, S) using ES-DH
2b. ENC(CEK, KEK(Ri, S))
}
3. ENC(payload,CEK)
* The alternative is to encrypt a payload with a different CEK for
each recipient. This results in n-manifests. This approach is
useful when payloads contain information unique to a device. The
encryption operation then effectively becomes ENC(payload_i,
CEK(Ri, S)). Assume that KEK(R1, S),..., KEK(Rn, S) have been
generated for the different recipients using ES-DH. The following
steps need to be made by the sender:
Tschofenig, et al. Expires 3 September 2024 [Page 14]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
1. for i=1 to n
{
1a. Generate KEK(Ri, S) using ES-DH
1b. Generate CEK(Ri, S)
1c. ENC(CEK(Ri, S), KEK(Ri, S))
1d. ENC(payload, CEK(Ri, S))
}
6.2.3. CDDL
The CDDL for the ECDH-ES+AES-KW binary is shown in Figure 6. Only
the minimum number of parameters is shown. empty_or_serialized_map
and header_map are structures defined in [RFC9052].
SUIT_Encryption_Info_ESDH = #6.96([
protected : outer_header_map_protected,
unprotected : outer_header_map_unprotected,
ciphertext : bstr / nil,
recipients : [ + COSE_recipient_ESDH ]
])
outer_header_map_protected = empty_or_serialized_map
outer_header_map_unprotected = header_map
COSE_recipient_ESDH = [
protected : bstr .cbor recipient_header_map_esdh,
unprotected : recipient_header_unpr_map_esdh,
ciphertext : bstr ; CEK encrypted with KEK
]
recipient_header_map_esdh =
{
1 => int, ; algorithm identifier
* label => values ; extension point
}
recipient_header_unpr_map_esdh =
{
? 4 => bstr, ; identifier of the recipient public key
-1 => COSE_Key, ; ephemeral public key for the sender
* label => values ; extension point
}
Figure 6: CDDL for ES-DH-based Content Key Distribution
See Section 7 for a description on how to encrypt the payload.
Tschofenig, et al. Expires 3 September 2024 [Page 15]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
6.2.4. Context Information Structure
The context information structure is used to ensure that the derived
keying material is "bound" to the context of the transaction. This
specification re-uses the structure defined in Section 5.2 of
[RFC9053] and tailors it accordingly.
The following information elements are bound to the context:
* the protocol employing the key-derivation method,
* information about the utilized AES Key Wrap algorithm, and the key
length.
* the protected header field, which contains the content key
encryption algorithm.
The sender and recipient identities are left empty.
The following fields in Figure 7 require an explanation:
* The COSE_KDF_Context.AlgorithmID field MUST contain the algorithm
identifier for AES Key Wrap algorithm utilized. This
specification uses the following values: A128KW (value -3), A192KW
(value -4), or A256KW (value -5)
* The COSE_KDF_Context.SuppPubInfo.keyDataLength field MUST contain
the key length of the algorithm in the
COSE_KDF_Context.AlgorithmID field expressed as the number of
bits. For A128KW the value is 128, for A192KW the value is 192,
and for A256KW the value 256.
* The COSE_KDF_Context.SuppPubInfo.other field captures the protocol
in which the ES-DH content key distribution algorithm is used and
MUST be set to the constant string "SUIT Payload Encryption".
* The COSE_KDF_Context.SuppPubInfo.protected field MUST contain the
serialized content of the recipient_header_map_esdh field, which
contains (among other fields) the identifier of the content key
distribution method.
Tschofenig, et al. Expires 3 September 2024 [Page 16]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
COSE_KDF_Context = [
AlgorithmID : int,
PartyUInfo : [ PartyInfoSender ],
PartyVInfo : [ PartyInfoRecipient ],
SuppPubInfo : [
keyDataLength : uint,
protected : bstr,
other: 'SUIT Payload Encryption'
],
? SuppPrivInfo : bstr
]
PartyInfoSender = (
identity : nil,
nonce : nil,
other : nil
)
PartyInfoRecipient = (
identity : nil,
nonce : nil,
other : nil
)
Figure 7: CDDL for COSE_KDF_Context Structure
The HKDF-based key derivation function MAY contain a salt value, as
described in Section 5.1 of [RFC9053]. This optional value is used
to influence the key generation process. This specification does not
mandate the use of a salt value. If the salt is public and carried
in the message, then the "salt" algorithm header parameter MUST be
used. The purpose of the salt is to provide extra randomness in the
KDF context. If the salt is sent in the 'salt' algorithm header
parameter, then the receiver MUST be able to process the salt and
MUST pass it into the key derivation function. For more information
about the salt, see [RFC5869] and NIST SP800-56 [SP800-56].
Profiles of this specification MAY specify an extended version of the
context information structure or MAY utilize a different context
information structure.
7. Content Encryption
This section summarizes the steps taken for content encryption, which
applies to both content key distribution methods.
Tschofenig, et al. Expires 3 September 2024 [Page 17]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
For use with AEAD ciphers, such as AES-GCM and ChaCha20/Poly1305, the
COSE specification requires a consistent byte stream for the
authenticated data structure to be created. This structure is shown
in Figure 8 and is defined in Section 5.3 of [RFC9052].
Enc_structure = [
context : "Encrypt",
protected : empty_or_serialized_map,
external_aad : bstr
]
Figure 8: CDDL for Enc_structure Data Structure
This Enc_structure needs to be populated as follows:
* The protected field in the Enc_structure from Figure 8 refers to
the content of the protected field from the COSE_Encrypt
structure.
* The value of the external_aad MUST be set to a zero-length byte
string, i.e., h'' in diagnostic notation and encoded as 0x40.
Some ciphers provide confidentiality witout integrity protection,
such as AES-CTR and AES-CBC (see [RFC9459]). For these ciphers the
Enc_structure, shown in Figure 8, MUST NOT be used because the
Additional Authenticated Data (AAD) byte string is only consumable by
AEAD ciphers. Hence, the AAD structure is not supplied to the API of
those ciphers and the protected header in the SUIT_Encryption_Info
structure MUST be a zero-length byte string.
7.1. AES-GCM
7.1.1. Introduction
AES-GCM is an AEAD cipher and provides confidentiality and integrity
protection.
Examples in this section use the following parameters:
* Algorithm for payload encryption: AES-GCM-128
- k: h'15F785B5C931414411B4B71373A9C0F7'
- IV: h'F14AAB9D81D51F7AD943FE87AF4F70CD'
* Plaintext: "This is a real firmware image."
Tschofenig, et al. Expires 3 September 2024 [Page 18]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
- in hex:
546869732069732061207265616C206669726D7761726520696D6167652E
7.1.2. AES-KW + AES-GCM Example
This example uses the following parameters:
* Algorithm id for key wrap: A128KW
* KEK COSE_Key (Secret Key):
- kty: Symmetric
- k: 'aaaaaaaaaaaaaaaa'
- kid: 'kid-1'
The COSE_Encrypt structure, in hex format, is (with a line break
inserted):
D8608443A10101A10550F14AAB9D81D51F7AD943FE87AF4F70CDF6818340
A2012204456B69642D31581875603FFC9518D794713C8CA8A115A7FB3256
5A6D59534D62
The resulting COSE_Encrypt structure in a diagnostic format is shown
in Figure 9.
96([
/ protected: / << {
/ alg / 1: 1 / AES-GCM-128 /
} >>,
/ unprotected: / {
/ IV / 5: h'F14AAB9D81D51F7AD943FE87AF4F70CD'
},
/ payload: / null / detached ciphertext /,
/ recipients: / [
[
/ protected: / h'',
/ unprotected: / {
/ alg / 1: -3 / A128KW /,
/ kid / 4: 'kid-1'
},
/ payload: /
h'75603FFC9518D794713C8CA8A115A7FB32565A6D59534D62'
/ CEK encrypted with KEK /
]
]
])
Tschofenig, et al. Expires 3 September 2024 [Page 19]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
Figure 9: COSE_Encrypt Example for AES Key Wrap
The encrypted payload (with a line feed added) was:
2F59C3A34D9570FB99A5382E66466A3221A8AD85CE508BA306FB431A60EF
A5AAAA078355070205A4B196832DF17F
7.1.3. ECDH-ES+AES-KW + AES-GCM Example
This example uses the following parameters:
* Algorithm for content key distribution: ECDH-ES + A128KW
* KEK COSE_Key (Receiver's Private Key):
- kty: EC2
- crv: P-256
- x: h'5886CD61DD875862E5AAA820E7A15274C968A9BC96048DDCACE32F50C3
651BA3'
- y: h'9EED8125E932CD60C0EAD3650D0A485CF726D378D1B016ED4298B2961E
258F1B'
- d: h'60FE6DD6D85D5740A5349B6F91267EEAC5BA81B8CB53EE249E4B4EB102
C476B3'
- kid: 'kid-2'
* KDF Context
- Algorithm ID: 1 (A128GCM)
- SuppPubInfo
o keyDataLength: 128
o protected = << { / alg / 1: -29 / ECDH-ES+A128KW / } >>
o other = 'SUIT Payload Encryption'
The COSE_Encrypt structure, in hex format, is (with a line break
inserted):
Tschofenig, et al. Expires 3 September 2024 [Page 20]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
D8608443A10101A10550F14AAB9D81D51F7AD943FE87AF4F70CDF6818344
A101381CA120A40102200121582038876D8B4552E6BC9484A3F06E3646B3
0AEFF51B95583CFFA0B5776D5273494222582034577AB5DD17276BB6BF15
AA465310371557AFF61FAC5BA5A1EFF46698DD8B7B5818C36BF2E8843246
F0E148DBA607375204A040D8B19629B2B5
The resulting COSE_Encrypt structure in a diagnostic format is shown
in Figure 10.
96([
/ protected: / << {
/ alg / 1: 1 / AES-GCM-128 /
} >>,
/ unprotected: / {
/ IV / 5: h'F14AAB9D81D51F7AD943FE87AF4F70CD'
},
/ payload: / null / detached ciphertext /,
/ recipients: / [
[
/ protected: / << {
/ alg / 1: -29 / ECDH-ES + A128KW /
} >>,
/ unprotected: / {
/ ephemeral key / -1: {
/ kty / 1: 2 / EC2 /,
/ crv / -1: 1 / P-256 /,
/ x / -2: h'38876D8B4552E6BC9484A3F06E3646B3
0AEFF51B95583CFFA0B5776D52734942',
/ y / -3: h'34577AB5DD17276BB6BF15AA46531037
1557AFF61FAC5BA5A1EFF46698DD8B7B'
}
},
/ payload:
/ h'C36BF2E8843246F0E148DBA607375204A040D8B19629B2B5'
/ CEK encrypted with KEK /
]
]
])
Figure 10: COSE_Encrypt Example for ES-DH
The encrypted payload (with a line feed added) was:
2F59C3A34D9570FB99A5382E66466A3221A8AD85CE508BA306FB431A60EF
A5AAAA078355070205A4B196832DF17F
7.2. AES-CTR
Tschofenig, et al. Expires 3 September 2024 [Page 21]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
7.2.1. Introduction
AES-CTR is a non-AEAD cipher, provides confidentiality but no
integrity protection. Unlike AES-CBC, AES-CTR uses an IV per AES
operation, as shown in Figure 11. Hence, when an image is encrypted
using AES-CTR-128 or AES-CTR-256, the IV MUST start with zero (0) and
MUST be incremented by one for each 16-byte plaintext block within
the entire slot.
Using the previous example with a slot size of 64 KiB, the sector
size 4096 bytes and the AES plaintext block size of 16 byte requires
IVs from 0 to 255 in the first sector and 16 * 256 IVs for the
remaining sectors in the slot.
IV1 IV2
| |
| |
| |
+-------+ +-------+
| | | |
| | | |
k--| E | k--| E |
| | | |
+-------+ +-------+
| |
P1--(+) P2--(+)
| |
| |
C1 C2
Legend:
See previous diagram.
Figure 11: AES-CTR Operation
Examples in this section use the following parameters:
* Algorithm for payload encryption: AES-CTR-128
- k: h'261DE6165070FB8951EC5D7B92A065FE'
- IV: h'DAE613B2E0DC55F4322BE38BDBA9DC68'
* Plaintext: "This is a real firmware image."
- in hex:
546869732069732061207265616C206669726D7761726520696D6167652E
Tschofenig, et al. Expires 3 September 2024 [Page 22]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
7.2.2. AES-KW + AES-CTR Example
This example uses the following parameters:
* Algorithm id for key wrap: A128KW
* KEK COSE_Key (Secret Key):
- kty: Symmetric
- k: 'aaaaaaaaaaaaaaaa'
- kid: 'kid-1'
The COSE_Encrypt structure, in hex format, is (with a line break
inserted):
D8608440A20139FFFD0550DAE613B2E0DC55F4322BE38BDBA9DC68F68183
40A2012204456B69642D315818CE34035CE5C2E2666E46D4C131FC561DD1
90A6D26CFA1990
The resulting COSE_Encrypt structure in a diagnostic format is shown
in Figure 12.
96([
/ protected: / h'',
/ unprotected: / {
/ alg / 1: -65534 / A128CTR /,
/ IV / 5: h'DAE613B2E0DC55F4322BE38BDBA9DC68'
},
/ payload: / null / detached ciphertext /,
/ recipients: / [
[
/ protected: / h'',
/ unprotected: / {
/ alg / 1: -3 / A128KW /,
/ kid / 4: 'kid-1'
},
/ payload: /
h'CE34035CE5C2E2666E46D4C131FC561DD190A6D26CFA1990'
/ CEK encrypted with KEK /
]
]
])
Figure 12: COSE_Encrypt Example for AES Key Wrap
The encrypted payload (with a line feed added) was:
Tschofenig, et al. Expires 3 September 2024 [Page 23]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
2BB8DB522AE978246CC775C3B0241BD4B0333FFDD2DB70C7EE7A4966E3B7
7.2.3. ECDH-ES+AES-KW + AES-CTR Example
This example uses the following parameters:
* Algorithm for content key distribution: ECDH-ES + A128KW
* KEK COSE_Key (Receiver's Private Key):
- kty: EC2
- crv: P-256
- x: h'5886CD61DD875862E5AAA820E7A15274C968A9BC96048DDCACE32F50C3
651BA3'
- y: h'9EED8125E932CD60C0EAD3650D0A485CF726D378D1B016ED4298B2961E
258F1B'
- d: h'60FE6DD6D85D5740A5349B6F91267EEAC5BA81B8CB53EE249E4B4EB102
C476B3'
- kid: 'kid-2'
* KDF Context
- ALgorithm ID: -3 (A128KW)
- SuppPubInfo
o keyDataLength: 128
o protected = << { / alg / 1: -3 / A128KW / } >>
o other = 'SUIT Payload Encryption'
The COSE_Encrypt structure, in hex format, is (with a line break
inserted):
D8608440A20139FFFD0550DAE613B2E0DC55F4322BE38BDBA9DC68F68183
44A101381CA120A40102200121582050364E4DF3F5E8749D98E4378C04FA
FE643B6ACEE7138382D83F768C7186FB8522582099E6C96BEF3952B12EF8
3921B1749475D767284AA42D74D8923C137B01EDF5A05818E8599DCEE494
4EECA9781D3ECDE3D9C34E1C9FCE8906617F
The resulting COSE_Encrypt structure in a diagnostic format is shown
in Figure 13.
Tschofenig, et al. Expires 3 September 2024 [Page 24]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
96([
/ protected: / h'',
/ unprotected: / {
/ alg / 1: -65534 / A128CTR /,
/ IV / 5: h'DAE613B2E0DC55F4322BE38BDBA9DC68'
},
/ payload: / null / detached ciphertext /,
/ recipients: / [
[
/ protected: / << {
/ alg / 1: -29 / ECDH-ES + A128KW /
} >>,
/ unprotected: / {
/ ephemeral key / -1: {
/ kty / 1: 2 / EC2 /,
/ crv / -1: 1 / P-256 /,
/ x / -2: h'50364E4DF3F5E8749D98E4378C04FAFE643B6ACEE7138382D83F768C7186FB85',
/ y / -3: h'99E6C96BEF3952B12EF83921B1749475D767284AA42D74D8923C137B01EDF5A0'
}
},
/ payload: / h'E8599DCEE4944EECA9781D3ECDE3D9C34E1C9FCE8906617F'
/ CEK encrypted with KEK /
]
]
])
Figure 13: COSE_Encrypt Example for ES-DH
The encrypted payload (with a line feed added) was:
2BB8DB522AE978246CC775C3B0241BD4B0333FFDD2DB70C7EE7A4966E3B7
7.3. AES-CBC
7.3.1. Introduction
AES-CBC is a non-AEAD cipher, provides confidentiality but no
integrity protection. In AES-CBC, a single IV is used for encryption
of firmware belonging to a single sector, since individual AES blocks
are chained together, as shown in Figure 14. The numbering of
sectors in a slot MUST start with zero (0) and MUST increase by one
with every sector till the end of the slot is reached. The IV
follows this numbering.
Tschofenig, et al. Expires 3 September 2024 [Page 25]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
For example, let us assume the slot size of a specific flash
controller on an IoT device is 64 KiB, the sector size 4096 bytes (4
KiB) and AES-128-CBC uses an AES-block size of 128 bit (16 bytes).
Hence, sector 0 needs 4096/16=256 AES-128-CBC operations using IV 0.
If the firmware image fills the entire slot, then that slot contains
16 sectors, i.e. IVs ranging from 0 to 15.
P1 P2
| |
IV--(+) +-------(+)
| | |
| | |
+-------+ | +-------+
| | | | |
| | | | |
k--| E | | k--| E |
| | | | |
+-------+ | +-------+
| | |
+-----+ |
| |
| |
C1 C2
Legend:
Pi = Plaintext blocks
Ci = Ciphertext blocks
E = Encryption function
k = Symmetric key
(+) = XOR operation
Figure 14: AES-CBC Operation
Examples in this section use the following parameters:
* Algorithm for payload encryption: AES-CTR-128
- k: h'627FCF0EA82C967D5ED8981EB325F303'
- IV: h'93702C81590F845D9EC866CCAC767BD1'
* Plaintext: "This is a real firmware image."
- in hex:
546869732069732061207265616C206669726D7761726520696D6167652E
Tschofenig, et al. Expires 3 September 2024 [Page 26]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
7.3.2. AES-KW + AES-CBC Example
This example uses the following parameters:
* Algorithm id for key wrap: A128KW
* KEK COSE_Key (Secret Key):
- kty: Symmetric
- k: 'aaaaaaaaaaaaaaaa'
- kid: 'kid-1'
The COSE_Encrypt structure, in hex format, is (with a line break
inserted):
D8608440A20139FFFA055093702C81590F845D9EC866CCAC767BD1F68183
40A2012204456B69642D315818E198FF269626EC43299D33586FC7B2646B
13292261160422
The resulting COSE_Encrypt structure in a diagnostic format is shown
in Figure 15.
96([
/ protected: / h'',
/ unprotected: / {
/ alg / 1: -65531 / A128CBC /,
/ IV / 5: h'93702C81590F845D9EC866CCAC767BD1'
},
/ payload: / null / detached ciphertext /,
/ recipients: / [
[
/ protected: / h'',
/ unprotected: / {
/ alg / 1: -3 / A128KW /,
/ kid / 4: 'kid-1'
},
/ payload: /
h'E198FF269626EC43299D33586FC7B2646B13292261160422'
/ CEK encrypted with KEK /
]
]
])
Figure 15: COSE_Encrypt Example for AES Key Wrap
The encrypted payload (with a line feed added) was:
Tschofenig, et al. Expires 3 September 2024 [Page 27]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
9C09156CF4ACE0401086D98586E0B09FA5B5CF78F2BCCBF6C914DDB42BF0
E21E
7.3.3. ECDH-ES+AES-KW + AES-CBC Example
This example uses the following parameters:
* Algorithm for content key distribution: ECDH-ES + A128KW
* KEK COSE_Key (Receiver's Private Key):
- kty: EC2
- crv: P-256
- x: h'5886CD61DD875862E5AAA820E7A15274C968A9BC96048DDCACE32F50C3
651BA3'
- y: h'9EED8125E932CD60C0EAD3650D0A485CF726D378D1B016ED4298B2961E
258F1B'
- d: h'60FE6DD6D85D5740A5349B6F91267EEAC5BA81B8CB53EE249E4B4EB102
C476B3'
- kid: 'kid-2'
* KDF Context
- Algorithm ID: -65531 (A128CBC)
- SuppPubInfo
o keyDataLength: 128
o protected = h''
o other = 'SUIT Payload Encryption'
The COSE_Encrypt structure, in hex format, is (with a line break
inserted):
D8608440A20139FFFA055093702C81590F845D9EC866CCAC767BD1F68183
44A101381CA120A401022001215820BC6A2DCD5025C8C0F7A5D120EB3E45
8CA722F8FB94BD56A24709CB15A869748922582010136574F673511540FE
2A8589A7EDA372CB7B1AF94A8E1B4B94F6BDBD98AA185818AC8CDFB54264
22298FCF235EB5F24D9E4C44C1689167473A
Tschofenig, et al. Expires 3 September 2024 [Page 28]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
The resulting COSE_Encrypt structure in a diagnostic format is shown
in Figure 16.
96([
/ protected: / h'',
/ unprotected: / {
/ alg / 1: -65531 / A128CBC /,
/ IV / 5: h'93702C81590F845D9EC866CCAC767BD1'
},
/ payload: / null / detached ciphertext /,
/ recipients: / [
[
/ protected: / << {
/ alg / 1: -29 / ECDH-ES + A128KW /
} >>,
/ unprotected: / {
/ ephemeral key / -1: {
/ kty / 1: 2 / EC2 /,
/ crv / -1: 1 / P-256 /,
/ x / -2: h'BC6A2DCD5025C8C0F7A5D120EB3E458CA722F8FB94BD56A24709CB15A8697489',
/ y / -3: h'10136574F673511540FE2A8589A7EDA372CB7B1AF94A8E1B4B94F6BDBD98AA18'
}
},
/ payload: / h'AC8CDFB5426422298FCF235EB5F24D9E4C44C1689167473A'
/ CEK encrypted with KEK /
]
]
])
Figure 16: COSE_Encrypt Example for ES-DH
The encrypted payload (with a line feed added) was:
9C09156CF4ACE0401086D98586E0B09FA5B5CF78F2BCCBF6C914DDB42BF0
E21E
8. Integrity Check on Encrypted and Decrypted Payloads
In addition to suit-condition-image-match (Section 8.4.9.2 of
[I-D.ietf-suit-manifest]), AEAD algorithms used for content
encryption provides another way to validate the integrity of
components. This section provides a guideline to construct secure
but not redundant SUIT Manifest for encrypted payloads.
8.1. Validating Payload Integrity
This sub-section explains three ways to validate the integrity of
payloads.
Tschofenig, et al. Expires 3 September 2024 [Page 29]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
8.1.1. Image Match after Decryption
The suit-condition-image-match on the plaintext payload is used after
decryption. An example command sequence is shown in Figure 17.
/ directive-set-component-index / 12, 1,
/ directive-override-parameters / 20, {
/ parameter-uri / 21: "http://example.com/encrypted.bin"
},
/ directive-fetch / 21, 15,
/ directive-set-component-index / 12, 0,
/ directive-override-parameters / 20, {
/ parameter-image-digest / 3: << {
/ algorithm-id: / -16 / SHA256 /,
/ digest-bytes: / h'3B1...92A' / digest of plaintext payload /
} >>,
/ parameter-image-size / 14: 30 / size of plaintext payload /,
/ parameter-encryption-info / 19: h'369...50F',
/ parameter-source-component / 22: 1
},
/ directive-copy / 22, 15,
/ condition-image-match / 3, 15 / integrity check on decrypted payload /,
Figure 17: Check Image Match After Decryption
8.1.2. Image Match before Decryption
The suit-condition-image-match can also be applied on encrypted
payloads before decryption takes place. An example command sequence
is shown in Figure 18.
This option mitigates battery exhaustion attacks discussed in
Section 12.
Tschofenig, et al. Expires 3 September 2024 [Page 30]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
/ directive-set-component-index / 12, 1,
/ directive-override-parameters / 20, {
/ parameter-image-digest / 3: << {
/ algorithm-id: / -16 / SHA256 /,
/ digest-bytes: / h'8B4...D34' / digest of encrypted payload /
} >>,
/ parameter-image-size / 14: 30 / size of encrypted payload /,
/ parameter-uri / 21: "http://example.com/encrypted.bin"
},
/ directive-fetch / 21, 15,
/ condition-image-match / 3, 15 / integrity check on encrypted payload /,
/ directive-set-component-index / 12, 0,
/ directive-override-parameters / 20, {
/ parameter-encryption-info / 19: h'D86...1F0',
/ parameter-source-component / 22: 1
},
/ directive-copy / 22, 15,
Figure 18: Check Image Match Before Decryption
8.1.3. Checking Authentication Tag while Decryption
AEAD algorithms, such as AES-GCM and ChaCha20/Poly1305, verify the
integrity of the encrypted concent.
8.2. Payload Integrity in SUIT Manifest
This sub-section provides a guideline to decide how to validate the
integrity of the payloads with SUIT Manifest. Figure 19 illustrates
a classification tree to decide how to establish payload integrity.
Tschofenig, et al. Expires 3 September 2024 [Page 31]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
+------------------------------------------------+
| Q1. Payload Delivery |
+-+--------------------------------------------+-+
| |
| in Content others |
| v
| +--------------------------------+
| | Q2. Mitigate Battery |
| | Exhaustion Attacks |
| +-+----------------------------+-+
| | |
| | No Yes |
| v |
| +-----------------+ |
| | Q3. AEAD cipher | |
| +-+-------------+-+ |
| | | |
| | Yes No | |
v v v v
.+------+. .-----+-----. .----------+.
| NOT | | AFTER | | BEFORE |
| Required | | Decryption | | Decryption |
'--------' '-----------' '-----------'
Figure 19: Classification Tree: Appropriate Location of Image Match
There are three conditions:
* Q1. How does the recipient get the encrypted payload? If the
encrypted payload is an integrated payload, its integrity is
already validated with the suit-authentication-wrapper, so
additional integrity check is not required.
* Q2. Does the sender want to mitigate battery exhaustion attacks?
If yes, the encrypted payload has to be validated before
decryption.
* Q3. Is the payload encrypted with an AEAD cipher? If yes, the
additional integrity check is not required because the recipient
validates the integrity of the payload while decrypting it. If
no, validating its integrity must take place either before or
after decryption.
Tschofenig, et al. Expires 3 September 2024 [Page 32]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
9. Firmware Updates on IoT Devices with Flash Memory
There are many flavors of embedded devices, the market is large and
fragmented. Hence, it is likely that some implementations and
deployments implement their firmware update procedure differently
than described below. On a positive note, the SUIT manifest allows
different deployment scenarios to be supported easily thanks to the
"scripting" functionality offered by the commands.
This section is specific to firmware images on microcontrollers and
does not apply to generic software, configuration data, and machine
learning models. The differences are the result of two aspects:
* Use of flash memory: Flash memory on microcontrollers is a type of
non-volatile memory that erases data in larger units called
blocks, pages, or sectors and re-writes data at the byte level
(often 4-bytes) or larger units. Flash memory is furthermore
segmented into different memory regions, which store the
bootloader, different versions of firmware images (in so-called
slots), and configuration data. Figure 20 shows an example layout
of a microcontroller flash area.
* Microcontroller Design: Code on microcontrollers typically cannot
be executed from an arbitrary place in flash memory without extra
software development and design efforts. Hence, developers often
compile firmware such that the bootloader can execute the code
from a specific location in flash memory. Often, the location
where the to-be-booted firmware image is found is called "primary
slot".
When the encrypted firmware image has been transferred to the device,
it will typically be stored in a dedicated area called the "secondary
slot".
At the next boot, the bootloader will recognize a new firmware image
and will start decrypting the downloaded image sector-by-sector and
will swap it with the image found in the primary slot. This approach
of swapping the newly downloaded image with the previously valid
image requires two slots to allow the update to be reversed in case
the newly obtained firmware image fails to boot. This adds
robustness to the firmware update procedure.
The swap will only take place after the signature on the plaintext is
verified. Note that the plaintext firmware image is available in the
primary slot only after the swap has been completed, unless "dummy
decrypt" is used to compute the hash over the plaintext prior to
executing the decrypt operation during a swap. Dummy decryption here
refers to the decryption of the firmware image found in the secondary
Tschofenig, et al. Expires 3 September 2024 [Page 33]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
slot sector-by-sector and computing a rolling hash over the resulting
plaintext firmware image (also sector-by-sector) without performing
the swap operation. While there are performance optimizations
possible, such as conveying hashes for each sector in the manifest
rather than a hash of the entire firmware image, such optimizations
are not described in this specification.
Without hardware-based, on-the-fly decryption the image in the
primary slot is available in cleartext. It may need to be re-
encrypted before copying it to the secondary slot. This may be
necessary when the secondary slot has different access permissions or
when it is located in off-chip flash memory. Off-chip flash memory
tends to be more vulnerable to physical attacks.
+--------------------------------------------------+
| Bootloader |
+--------------------------------------------------+
| Primary Slot |
| (sector 1)|
|..................................................|
| |
| (sector 2)|
|..................................................|
| |
| (sector 3)|
|..................................................|
| |
| (sector 4)|
+--------------------------------------------------+
| Secondary Slot |
| (sector 1)|
|..................................................|
| |
| (sector 2)|
|..................................................|
| |
| (sector 3)|
|..................................................|
| |
| (sector 4)|
+--------------------------------------------------+
| Swap Area |
| |
+--------------------------------------------------+
| Configuration Data |
+--------------------------------------------------+
Figure 20: Example Flash Area Layout
Tschofenig, et al. Expires 3 September 2024 [Page 34]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
The ability to restart an interrupted firmware update is often a
requirement for unattended devices and the same is true for low-end,
constrained IoT devices. To fulfill this requirement it is necessary
to chunk a firmware image into sectors and to encrypt each sector
individually using a cipher that does not increase the size of the
resulting ciphertext (i.e., by not adding an authentication tag after
each encrypted block).
When an update gets aborted while the bootloader is decrypting the
newly obtained image and swapping the sectors, the bootloader can
restart where it left off. This technique offers robustness and
better performance.
For this purpose, ciphers without integrity protection are used to
encrypt the firmware image. Integrity protection of the firmware
image MUST be provided and the suit-parameter-image-digest, defined
in Section 8.4.8.6 of [I-D.ietf-suit-manifest], MUST be used.
[RFC9459] registers AES Counter (AES-CTR) mode and AES Cipher Block
Chaining (AES-CBC) ciphers that do not offer integrity protection.
These ciphers are useful for use cases that require firmware
encryption on IoT devices. For many other use cases where software
packages, configuration information or personalization data need to
be encrypted, the use of AEAD ciphers is RECOMMENDED.
The following sub-sections provide further information about the
initialization vector (IV) selection for use with AES-CBC and AES-CTR
in the firmware encryption context. An IV MUST NOT be re-used when
the same key is used. For this application, the IVs are not random
but rather based on the slot/sector-combination in flash memory. The
text below assumes that the block-size of AES is (much) smaller than
the sector size. The typical sector-size of flash memory is in the
order of KiB. Hence, multiple AES blocks need to be decrypted until
an entire sector is completed.
10. Complete Examples
The following manifests exemplify how to deliver encrypted payload
and its encryption info to devices.
HMAC-256 MAC are added in AES-KW examples using the following secret
key:
'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'
(616161... in hex, and its length is 32)
ES-DH examples are signed using the following ECDSA secp256r1 key:
Tschofenig, et al. Expires 3 September 2024 [Page 35]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
-----BEGIN PRIVATE KEY-----
MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgApZYjZCUGLM50VBC
CjYStX+09jGmnyJPrpDLTz/hiXOhRANCAASEloEarguqq9JhVxie7NomvqqL8Rtv
P+bitWWchdvArTsfKktsCYExwKNtrNHXi9OB3N+wnAUtszmR23M4tKiW
-----END PRIVATE KEY-----
The corresponding public key can be used to verify these examples:
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEhJaBGq4LqqvSYVcYnuzaJr6qi/Eb
bz/m4rVlnIXbwK07HypLbAmBMcCjbazR14vTgdzfsJwFLbM5kdtzOLSolg==
-----END PUBLIC KEY-----
Each example uses SHA-256 as the digest function.
10.1. AES Key Wrap Example with Write Directive
The following SUIT manifest requests a parser to authenticate the
manifest with COSE_Mac0 HMAC256, to write and decrypt the encrypted
payload into a component with the suit-directive-write directive.
The SUIT manifest in diagnostic notation (with line breaks added for
readability) is shown here:
/ SUIT_Envelope_Tagged / 107({
/ authentication-wrapper / 2: << [
<< [
/ digest-algorithm-id: / -16 / SHA256 /,
/ digest-bytes: / h'536EC695E423342FF57FA89B3E3C12C0
F9257992F7D96F017281782D2DF1C50F'
] >>,
<< / COSE_Mac0_Tagged / 17([
/ protected: / << {
/ algorithm-id / 1: 5 / HMAC256 /
} >>,
/ unprotected: / {},
/ payload: / null,
/ tag: / h'3B70571169B0FEE5E6220BF86E5E973F
7F32875495908EDAA91EC994BCA44B29'
]) >>
] >>,
/ manifest / 3: << {
/ manifest-version / 1: 1,
/ manifest-sequence-number / 2: 1,
/ common / 3: << {
/ components / 2: [
['plaintext-firmware']
]
Tschofenig, et al. Expires 3 September 2024 [Page 36]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
} >>,
/ install / 17: << [
/ fetch encrypted firmware /
/ directive-override-parameters / 20, {
/ parameter-content / 18:
h'2F59C3A34D9570FB99A5382E66466A3221A8AD85CE508B
A306FB431A60EFA5AAAA078355070205A4B196832DF17F',
/ parameter-encryption-info / 19: << 96([
/ protected: / << {
/ alg / 1: 1 / AES-GCM-128 /
} >>,
/ unprotected: / {
/ IV / 5: h'F14AAB9D81D51F7AD943FE87AF4F70CD'
},
/ payload: / null / detached ciphertext /,
/ recipients: / [
[
/ protected: / << {
} >>,
/ unprotected: / {
/ alg / 1: -3 / A128KW /,
/ kid / 4: 'kid-1'
},
/ payload: /
h'75603FFC9518D794713C8CA8A115A7FB32565A6D59534D62'
/ CEK encrypted with KEK /
]
]
]) >>
},
/ decrypt encrypted firmware /
/ directive-write / 18, 15
/ consumes the SUIT_Encryption_Info above /
] >>
} >>
})
In hex format, the SUIT manifest is this:
Tschofenig, et al. Expires 3 September 2024 [Page 37]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
D86BA2025853825824822F5820536EC695E423342FF57FA89B3E3C12C0F9
257992F7D96F017281782D2DF1C50F582AD18443A10105A0F658203B7057
1169B0FEE5E6220BF86E5E973F7F32875495908EDAA91EC994BCA44B2903
589DA4010102010357A102818152706C61696E746578742D6669726D7761
726511587C8414A212582E2F59C3A34D9570FB99A5382E66466A3221A8AD
85CE508BA306FB431A60EFA5AAAA078355070205A4B196832DF17F135843
D8608443A10101A10550F14AAB9D81D51F7AD943FE87AF4F70CDF6818341
A0A2012204456B69642D31581875603FFC9518D794713C8CA8A115A7FB32
565A6D59534D62120F
10.2. AES Key Wrap Example with Fetch + Copy Directives
The following SUIT manifest requests a parser to fetch the encrypted
payload and to store it. Then, the payload is decrypted and stored
into another component with the suit-directive-copy directive. This
approach works well on constrained devices with XIP flash memory.
The SUIT manifest in diagnostic notation (with line breaks added for
readability) is shown here:
/ SUIT_Envelope_Tagged / 107({
/ authentication-wrapper / 2: << [
<< [
/ digest-algorithm-id: / -16 / SHA256 /,
/ digest-bytes: / h'AAB6A7868C4E43D5983BDE019EF22779
21F6F8EF1FCAF9403CA97255BED2CD30'
] >>,
<< / COSE_Mac0_Tagged / 17([
/ protected: / << {
/ algorithm-id / 1: 5 / HMAC256 /
} >>,
/ unprotected: / {},
/ payload: / null,
/ tag: / h'93B4B774A5D0421ED6FB5EBF890A284C
DAC7816CBC048BF47EE7FA7FF3BC02C3'
]) >>
] >>,
/ manifest / 3: << {
/ manifest-version / 1: 1,
/ manifest-sequence-number / 2: 1,
/ common / 3: << {
/ components / 2: [
['plaintext-firmware'],
['encrypted-firmware']
]
} >>,
/ install / 17: << [
/ fetch encrypted firmware /
Tschofenig, et al. Expires 3 September 2024 [Page 38]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
/ directive-set-component-index / 12, 1 / ['encrypted-firmware'] /,
/ directive-override-parameters / 20, {
/ parameter-image-size / 14: 46,
/ parameter-uri / 21: "https://example.com/encrypted-firmware"
},
/ directive-fetch / 21, 15,
/ decrypt encrypted firmware /
/ directive-set-component-index / 12, 0 / ['plaintext-firmware'] /,
/ directive-override-parameters / 20, {
/ parameter-encryption-info / 19: << 96([
/ protected: / << {
/ alg / 1: 1 / AES-GCM-128 /
} >>,
/ unprotected: / {
/ IV / 5: h'F14AAB9D81D51F7AD943FE87AF4F70CD'
},
/ payload: / null / detached ciphertext /,
/ recipients: / [
[
/ protected: / << {
} >>,
/ unprotected: / {
/ alg / 1: -3 / A128KW /,
/ kid / 4: 'kid-1'
},
/ payload: /
h'75603FFC9518D794713C8CA8A115A7FB32565A6D59534D62'
/ CEK encrypted with KEK /
]
]
]) >>,
/ parameter-source-component / 22: 1 / ['encrypted-firmware'] /
},
/ directive-copy / 22, 15 / consumes the SUIT_Encryption_Info above /
] >>
} >>
})
In hex format, the SUIT manifest is this:
Tschofenig, et al. Expires 3 September 2024 [Page 39]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
D86BA2025853825824822F5820AAB6A7868C4E43D5983BDE019EF2277921
F6F8EF1FCAF9403CA97255BED2CD30582AD18443A10105A0F6582093B4B7
74A5D0421ED6FB5EBF890A284CDAC7816CBC048BF47EE7FA7FF3BC02C303
58B7A40101020103582BA102828152706C61696E746578742D6669726D77
6172658152656E637279707465642D6669726D776172651158818C0C0114
A20E182E15782668747470733A2F2F6578616D706C652E636F6D2F656E63
7279707465642D6669726D77617265150F0C0014A2135843D8608443A101
01A10550F14AAB9D81D51F7AD943FE87AF4F70CDF6818341A0A201220445
6B69642D31581875603FFC9518D794713C8CA8A115A7FB32565A6D59534D
621601160F
10.3. ES-DH Example with Write + Copy Directives
The following SUIT manifest requests a parser to authenticate the
manifest with COSE_Sign1 ES256, to write and decrypt the encrypted
payload into a component with the suit-directive-write directive.
The SUIT manifest in diagnostic notation (with line breaks added for
readability) is shown here:
/ SUIT_Envelope_Tagged / 107({
/ authentication-wrapper / 2: << [
<< [
/ digest-algorithm-id: / -16 / SHA256 /,
/ digest-bytes: / h'CEF034223D7F2C39D676876995B4ED4E
8221AC5BF184B6606EE62C41C149C266'
] >>,
<< / COSE_Sign1_Tagged / 18([
/ protected: / << {
/ algorithm-id / 1: -7 / ES256 /
} >>,
/ unprotected: / {},
/ payload: / null,
/ signature: /
h'65E59AAB8A35BDE9547458316D1C769F
FB2CEA304C9FB6151E5C8A88A002A292
C5B8C63C81B5AC0AE31948B610834E12
CBDBB2753EA221544B6733076A92EE20'
]) >>
] >>,
/ manifest / 3: << {
/ manifest-version / 1: 1,
/ manifest-sequence-number / 2: 1,
/ common / 3: << {
/ components / 2: [
['decrypted-firmware']
]
} >>,
Tschofenig, et al. Expires 3 September 2024 [Page 40]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
/ install / 17: << [
/ directive-set-component-index / 12, 0
/ ['plaintext-firmware'] /,
/ directive-override-parameters / 20, {
/ parameter-content / 18:
h'344FA2D5AD2F43F6F363DA6FF2C337FE69E33E3D63714D
23985BF02499EB0E8B231D45C378245DA3611C160CC511',
/ parameter-encryption-info / 19: << 96([
/ protected: / << {
/ alg / 1: 1 / AES-GCM-128 /
} >>,
/ unprotected: / {
/ IV / 5: h'DAE613B2E0DC55F4322BE38BDBA9DC68'
},
/ payload: / null / detached ciphertext /,
/ recipients: / [
[
/ protected: / << {
/ alg / 1: -29 / ECDH-ES + A128KW /
} >>,
/ unprotected: / {
/ ephemeral key / -1: {
/ kty / 1: 2 / EC2 /,
/ crv / -1: 1 / P-256 /,
/ x / -2: h'FF6E266DABAF51B7207569E31CF72646
183E94CEE64FCDC8695AD9A505AEFDEA',
/ y / -3: h'5FBC4A29844450B3AC22AB30C7F7004B
B59D8BD60D7997734A9FA0124B650895'
},
/ kid / 4: 'kid-2'
},
/ payload: /
h'B0E21628283F3E409F8158D8FFCA567F340E379AC39E49C9'
/ CEK encrypted with KEK /
]
]
]) >>
},
/ directive-write / 18, 15
/ consumes the SUIT_Encryption_Info above /
] >>
} >>
})
In hex format, the SUIT manifest is this:
Tschofenig, et al. Expires 3 September 2024 [Page 41]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
D86BA2025873825824822F5820CEF034223D7F2C39D676876995B4ED4E82
21AC5BF184B6606EE62C41C149C266584AD28443A10126A0F6584065E59A
AB8A35BDE9547458316D1C769FFB2CEA304C9FB6151E5C8A88A002A292C5
B8C63C81B5AC0AE31948B610834E12CBDBB2753EA221544B6733076A92EE
200358ECA4010102010357A1028181526465637279707465642D6669726D
776172651158CB860C0014A212582E344FA2D5AD2F43F6F363DA6FF2C337
FE69E33E3D63714D23985BF02499EB0E8B231D45C378245DA3611C160CC5
11135890D8608443A10101A10550DAE613B2E0DC55F4322BE38BDBA9DC68
F6818344A101381CA220A401022001215820FF6E266DABAF51B7207569E3
1CF72646183E94CEE64FCDC8695AD9A505AEFDEA2258205FBC4A29844450
B3AC22AB30C7F7004BB59D8BD60D7997734A9FA0124B65089504456B6964
2D325818B0E21628283F3E409F8158D8FFCA567F340E379AC39E49C9120F
10.4. ES-DH Example with Dependency
The following SUIT manifest requests a parser to resolve the
dependency.
The dependent manifest is signed with another key: ~~~ -----BEGIN EC
PRIVATE KEY-----
MHcCAQEEIIQa67e56m8CYL5zVaJFiLl30j0qxb8ray2DeUMqH+qYoAoGCCqGSM49
AwEHoUQDQgAEDpCKqPBm2x8ITgw2UsY5Ur2Z8qW9si+eATZ6rQOrpot32hvYrE8M
tJC6IQZIv3mrFk1JrTVR1x0xSydJ7kLSmg== -----END EC PRIVATE KEY----- ~~~
The dependency manifest is embedded as an integrated-dependency and
referred to by the "#dependency-manifest" URI.
The SUIT manifest in diagnostic notation (with line breaks added for
readability) is shown here:
/ SUIT_Envelope_Tagged / 107({
/ authentication-wrapper / 2: << [
<< [
/ digest-algorithm-id: / -16 / SHA256 /,
/ digest-bytes: / h'6A1D9F42E7B4047D2F54046019AE3ED4
3A8ACC467AC16576B17D6F8E633042D2'
] >>,
<< / COSE_Sign1_Tagged / 18([
/ protected: / << {
/ algorithm-id / 1: -7 / ES256 /
} >>,
/ unprotected: / {},
/ payload: / null,
/ signature: /
h'DF493BDBF167EFFB40593C5910D33B66
429721467DF05800EA66A88B91729CD5
1007981F151FC324745FF43E6F75AAF5
197DD5EC4AA6BCEFCE43E4B1E35C948E'
Tschofenig, et al. Expires 3 September 2024 [Page 42]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
]) >>
] >>,
/ manifest / 3: << {
/ manifest-version / 1: 1,
/ manifest-sequence-number / 2: 1,
/ common / 3: << {
/ dependencies / 1: {
/ component-index / 1: {
/ dependency-prefix / 1: [
'dependency-manifest.suit'
]
}
},
/ components / 2: [
['decrypted-firmware']
]
} >>,
/ manifest-component-id / 5: [
'dependent-manifest.suit'
],
/ install / 17: << [
/ NOTE: set SUIT_Encryption_Info /
/ directive-set-component-index / 12, 0
/ ['decrypted-firmware'] /,
/ directive-override-parameters / 20, {
/ parameter-content / 18:
h'344FA2D5AD2F43F6F363DA6FF2C337FE69E33E3D63714D
23985BF02499EB0E8B231D45C378245DA3611C160CC511',
/ parameter-encryption-info / 19: << 96([
/ protected: / << {
/ alg / 1: 1 / AES-GCM-128 /
} >>,
/ unprotected: / {
/ IV / 5: h'DAE613B2E0DC55F4322BE38BDBA9DC68'
},
/ payload: / null / detached ciphertext /,
/ recipients: / [
[
/ protected: / << {
/ alg / 1: -29 / ECDH-ES + A128KW /
} >>,
/ unprotected: / {
/ ephemeral key / -1: {
/ kty / 1: 2 / EC2 /,
/ crv / -1: 1 / P-256 /,
/ x / -2: h'FF6E266DABAF51B7207569E31CF72646
183E94CEE64FCDC8695AD9A505AEFDEA',
/ y / -3: h'5FBC4A29844450B3AC22AB30C7F7004B
Tschofenig, et al. Expires 3 September 2024 [Page 43]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
B59D8BD60D7997734A9FA0124B650895'
},
/ kid / 4: 'kid-2'
},
/ payload: /
h'B0E21628283F3E409F8158D8FFCA567F340E379AC39E49C9'
/ CEK encrypted with KEK /
]
]
]) >>
},
/ NOTE: call dependency-manifest /
/ directive-set-component-index / 12, 1
/ ['dependenty-manifest.suit'] /,
/ directive-override-parameters / 20, {
/ parameter-image-digest / 3: << [
/ algorithm-id / -16 / SHA256 /,
/ digest-bytes / h'1051324059C5193317CAC9A099BBC0B6
AFB56184C04277F566A3A4131F4A1C25'
] >>,
/ parameter-image-size / 14: 247,
/ parameter-uri / 21: "#dependency-manifest"
},
/ directive-fetch / 21, 15,
/ condition-dependency-integrity / 7, 15,
/ directive-process-dependency / 11, 15
] >>
} >>,
"#dependency-manifest": <<
/ SUIT_Envelope_Tagged / 107({
/ authentication-wrapper / 2: << [
<< [
/ digest-algorithm-id: / -16 / SHA256 /,
/ digest-bytes: / h'1051324059C5193317CAC9A099BBC0B6
AFB56184C04277F566A3A4131F4A1C25'
] >>,
<< / COSE_Sign1_Tagged / 18([
/ protected: / << {
/ algorithm-id / 1: -7 / ES256 /
} >>,
/ unprotected: / {},
/ payload: / null,
/ signature: /
h'55990F3745DC4F200FF946643A6DE30D
DCE57B080B7D68DE9896D8190B9A63E2
D60E7C3D9693B67221AA6D07BBF0AB45
314C236827A242C22B5E688DDC467269'
Tschofenig, et al. Expires 3 September 2024 [Page 44]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
]) >>
] >>,
/ manifest / 3: << {
/ manifest-version / 1: 1,
/ manifest-sequence-number / 2: 1,
/ common / 3: << {
/ components / 2: [
['decrypted-firmware']
],
/ shared-sequence / 4: << [
/ directive-set-componnt-index / 12, 0
/ ['decrypted-firmware'] /,
/ directive-override-parameters / 20, {
/ parameter-image-digest / 3: << [
/ algorithm-id / -16 / SHA256 /,
/ digest-bytes / h'36921488FE6680712F734E11F58D87EE
B66D4B21A8A1AD3441060814DA16D50F'
] >>,
/ parameter-image-size / 14: 30
}
] >>
} >>,
/ manifest-component-id / 5: [
'dependency-manifest.suit'
],
/ validate / 7: << [
/ condition-image-match / 3, 15
] >>,
/ install / 17: << [
/ directive-set-component-index / 12, 0
/ ['decrypted-firmware'] /,
/ directive-write / 18, 15
/ consumes the SUIT_Encryption_Info set by dependent /,
/ condition-image-match / 3, 15
/ check the integrity of the decrypted payload /
] >>
} >>
})
>>
})
In hex format, the SUIT manifest is this:
Tschofenig, et al. Expires 3 September 2024 [Page 45]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
D86BA3025873825824822F58206A1D9F42E7B4047D2F54046019AE3ED43A
8ACC467AC16576B17D6F8E633042D2584AD28443A10126A0F65840DF493B
DBF167EFFB40593C5910D33B66429721467DF05800EA66A88B91729CD510
07981F151FC324745FF43E6F75AAF5197DD5EC4AA6BCEFCE43E4B1E35C94
8E03590170A501010201035837A201A101A101815818646570656E64656E
63792D6D616E69666573742E73756974028181526465637279707465642D
6669726D77617265058157646570656E64656E742D6D616E69666573742E
73756974115901138E0C0014A212582E344FA2D5AD2F43F6F363DA6FF2C3
37FE69E33E3D63714D23985BF02499EB0E8B231D45C378245DA3611C160C
C511135890D8608443A10101A10550DAE613B2E0DC55F4322BE38BDBA9DC
68F6818344A101381CA220A401022001215820FF6E266DABAF51B7207569
E31CF72646183E94CEE64FCDC8695AD9A505AEFDEA2258205FBC4A298444
50B3AC22AB30C7F7004BB59D8BD60D7997734A9FA0124B65089504456B69
642D325818B0E21628283F3E409F8158D8FFCA567F340E379AC39E49C90C
0114A3035824822F58201051324059C5193317CAC9A099BBC0B6AFB56184
C04277F566A3A4131F4A1C250E18F7157423646570656E64656E63792D6D
616E6966657374150F070F0B0F7423646570656E64656E63792D6D616E69
6665737458F7D86BA2025873825824822F58201051324059C5193317CAC9
A099BBC0B6AFB56184C04277F566A3A4131F4A1C25584AD28443A10126A0
F6584055990F3745DC4F200FF946643A6DE30DDCE57B080B7D68DE9896D8
190B9A63E2D60E7C3D9693B67221AA6D07BBF0AB45314C236827A242C22B
5E688DDC46726903587BA601010201035849A20281815264656372797074
65642D6669726D7761726504582F840C0014A2035824822F582036921488
FE6680712F734E11F58D87EEB66D4B21A8A1AD3441060814DA16D50F0E18
1E05815818646570656E64656E63792D6D616E69666573742E7375697407
4382030F1147860C00120F030F
11. Operational Considerations
The algorithms described in this document assume that the party
performing payload encryption
* shares a key-encryption key (KEK) with the recipient (for use with
the AES Key Wrap scheme), or
* is in possession of the public key of the recipient (for use with
ES-DH).
Both cases require some upfront communication interaction to
distribute these keys to the involved communication parties. This
interaction may be provided by a device management protocol, as
described in [RFC9019], or may be executed earlier in the lifecycle
of the device, for example during manufacturing or during
commissioning. In addition to the keying material key identifiers
and algorithm information need to be provisioned. This specification
places no requirements on the structure of the key identifier.
Tschofenig, et al. Expires 3 September 2024 [Page 46]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
In some cases third party companies analyse binaries for known
security vulnerabilities. With encrypted payloads, this type of
analysis is prevented. Consequently, these third party companies
either need to be given access to the plaintext binary before
encryption or they need to become authorized recipients of the
encrypted payloads. In either case, it is necessary to explicitly
consider those third parties in the software supply chain when such a
binary analysis is desired.
12. Security Considerations
This entire document is about security.
It is good security practise to use different keys for different
purpose. For example, the KEK used with an AES-KW-based content key
distribution method for encryption should be different from the long-
term symmetric key used for authentication in a communication
security protocol.
To further reduce the attack surface it may be beneficial use
different long-term keys for the encryption of different types of
payloads. For example, KEK_1 may be used with an AES-KW content key
distribution method to encrypt a firmware image while KEK_2 would be
used to encrypt configuration data.
A large part of this document is focused on the content key
distribution and two methods are utilized, namely AES Key Wrap (AES-
KW) and Ephemeral-Static Diffie-Hellman (ES-DH). In this table we
summarize the main properties with respect to their deployment:
Tschofenig, et al. Expires 3 September 2024 [Page 47]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
+---------------++------------+---------------+----------------+
| || | | |
| Number of || Same key | One key | One Key |
| Long-Term || for all | per device | per device |
| Keys || devices | | |
| || | | |
+---------------++------------+---------------+----------------+
| || | | |
| Number of || Single | Single | One CEK |
| Content || CEK per | CEK per | per payload |
| Encryption || payload | payload | encryption |
| Keys (CEKs) || shared | shared | transaction |
| || with all | with all | per device |
| || devies | devies | |
| || | | |
+---------------++------------+---------------+----------------+
| || | | |
| Use Case || Legacy | Efficient | Point-to- |
| || Usage | Payload | Point Payload |
| || | Distribution | Distribution |
| || | | |
+---------------++------------+---------------+----------------+
| || | | |
| Recommended? || No, bad | Yes | Yes |
| || practice | | |
| || | | |
+---------------++------------+---------------+----------------+
The use of firmware encryption with IoT devices introduces an battery
exhaustion attack. This attack utilizes the fact that flash memory
operations are energy-expensive. To perform this attacker, the
adversary needs to be able to swap detached payloads and force the
device to process a wrong payload. Swapping the payloads is only
possible when there is no communication security protocol in place
between the device and the distribution system or when the
distribution system itself is compromised. The security features
provided by the manifest will detect this attack and the device will
not boot the incorrectly provided payload. However, at this time the
energy-expensive flash operations have already been performed.
Consequently, these operations may reduce the lifetime of devices and
battery powered IoT devices are particularly vulnerable to such an
attack. See Section 9 for further discussion about IoT devices using
flash memory.
Tschofenig, et al. Expires 3 September 2024 [Page 48]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
Including the digest of the encrypted payload in the manifest allows
the device to detect a battery exhaustion attack before energy
consuming decryption and flash memory copy or swap operations took
place. When battery exhaustion attacks are not a concern, it is
adequate to use the digest of the plaintet payload instead.
13. IANA Considerations
IANA is asked to add the following value to the SUIT Parameters
registry established by Section 11.5 of [I-D.ietf-suit-manifest]:
Label Name Reference
-----------------------------------------
TBD19 Encryption Info Section 4
[Editor's Note: TBD19: Proposed 19]
14. References
14.1. Normative References
[I-D.ietf-suit-manifest]
Moran, B., Tschofenig, H., Birkholz, H., Zandberg, K., and
O. Rønningstad, "A Concise Binary Object Representation
(CBOR)-based Serialization Format for the Software Updates
for Internet of Things (SUIT) Manifest", Work in Progress,
Internet-Draft, draft-ietf-suit-manifest-25, 5 February
2024, <https://datatracker.ietf.org/doc/html/draft-ietf-
suit-manifest-25>.
[I-D.ietf-suit-trust-domains]
Moran, B. and K. Takayama, "SUIT Manifest Extensions for
Multiple Trust Domains", Work in Progress, Internet-Draft,
draft-ietf-suit-trust-domains-05, 11 September 2023,
<https://datatracker.ietf.org/doc/html/draft-ietf-suit-
trust-domains-05>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/rfc/rfc2119>.
[RFC3394] Schaad, J. and R. Housley, "Advanced Encryption Standard
(AES) Key Wrap Algorithm", RFC 3394, DOI 10.17487/RFC3394,
September 2002, <https://www.rfc-editor.org/rfc/rfc3394>.
Tschofenig, et al. Expires 3 September 2024 [Page 49]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.
[RFC9052] Schaad, J., "CBOR Object Signing and Encryption (COSE):
Structures and Process", STD 96, RFC 9052,
DOI 10.17487/RFC9052, August 2022,
<https://www.rfc-editor.org/rfc/rfc9052>.
[RFC9053] Schaad, J., "CBOR Object Signing and Encryption (COSE):
Initial Algorithms", RFC 9053, DOI 10.17487/RFC9053,
August 2022, <https://www.rfc-editor.org/rfc/rfc9053>.
[RFC9459] Housley, R. and H. Tschofenig, "CBOR Object Signing and
Encryption (COSE): AES-CTR and AES-CBC", RFC 9459,
DOI 10.17487/RFC9459, September 2023,
<https://www.rfc-editor.org/rfc/rfc9459>.
14.2. Informative References
[iana-suit]
Internet Assigned Numbers Authority, "IANA SUIT Manifest
Registry", 2023, <TBD>.
[RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
Housley, R., and W. Polk, "Internet X.509 Public Key
Infrastructure Certificate and Certificate Revocation List
(CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008,
<https://www.rfc-editor.org/rfc/rfc5280>.
[RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70,
RFC 5652, DOI 10.17487/RFC5652, September 2009,
<https://www.rfc-editor.org/rfc/rfc5652>.
[RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand
Key Derivation Function (HKDF)", RFC 5869,
DOI 10.17487/RFC5869, May 2010,
<https://www.rfc-editor.org/rfc/rfc5869>.
[RFC8937] Cremers, C., Garratt, L., Smyshlyaev, S., Sullivan, N.,
and C. Wood, "Randomness Improvements for Security
Protocols", RFC 8937, DOI 10.17487/RFC8937, October 2020,
<https://www.rfc-editor.org/rfc/rfc8937>.
[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/rfc/rfc9019>.
Tschofenig, et al. Expires 3 September 2024 [Page 50]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
[RFC9124] Moran, B., Tschofenig, H., and H. Birkholz, "A Manifest
Information Model for Firmware Updates in Internet of
Things (IoT) Devices", RFC 9124, DOI 10.17487/RFC9124,
January 2022, <https://www.rfc-editor.org/rfc/rfc9124>.
[ROP] Wikipedia, "Return-Oriented Programming", March 2023,
<https://en.wikipedia.org/wiki/Return-
oriented_programming>.
[SP800-56] NIST, "Recommendation for Pair-Wise Key Establishment
Schemes Using Discrete Logarithm Cryptography, NIST
Special Publication 800-56A Revision 3", April 2018,
<http://nvlpubs.nist.gov/nistpubs/SpecialPublications/
NIST.SP.800-56Ar3.pdf>.
Appendix A. Full CDDL
The following CDDL must be appended to the SUIT Manifest CDDL. The
SUIT CDDL is defined in Appendix A of [I-D.ietf-suit-manifest]
SUIT_Encryption_Info = #6.96(COSE_Encrypt)
$$SUIT_Parameters //= (suit-parameter-encryption-info =>
bstr .cbor SUIT_Encryption_Info)
suit-parameter-encryption-info = 19
Acknowledgements
We would like to thank Henk Birkholz for his feedback on the CDDL
description in this document. Additionally, we would like to thank
Michael Richardson, Øyvind Rønningstad, Dave Thaler, Laurence
Lundblade, Christian Amsüss, Ruud Derwig, and Carsten Bormann for
their review feedback. Finally, we would like to thank Dick Brooks
for making us aware of the challenges encryption imposes on binary
analysis.
Authors' Addresses
Hannes Tschofenig
Email: hannes.tschofenig@gmx.net
Russ Housley
Vigil Security, LLC
Email: housley@vigilsec.com
Tschofenig, et al. Expires 3 September 2024 [Page 51]
Internet-Draft Encrypted Payloads in SUIT Manifests March 2024
Brendan Moran
Arm Limited
Email: Brendan.Moran@arm.com
David Brown
Linaro
Email: david.brown@linaro.org
Ken Takayama
SECOM CO., LTD.
Email: ken.takayama.ietf@gmail.com
Tschofenig, et al. Expires 3 September 2024 [Page 52]
