forked from suit-wg/suit-firmware-encryption
-
Notifications
You must be signed in to change notification settings - Fork 0
/
draft-ietf-suit-firmware-encryption.xml
3551 lines (3177 loc) · 157 KB
/
draft-ietf-suit-firmware-encryption.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?>
<!-- generated by https://github.com/cabo/kramdown-rfc version 1.7.17 (Ruby 3.0.2) -->
<!DOCTYPE rfc [
<!ENTITY nbsp " ">
<!ENTITY zwsp "​">
<!ENTITY nbhy "‑">
<!ENTITY wj "⁠">
]>
<?rfc rfcedstyle="yes"?>
<?rfc tocindent="yes"?>
<?rfc strict="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc text-list-symbols="-o*+"?>
<?rfc docmapping="yes"?>
<?rfc toc_levels="4"?>
<rfc ipr="trust200902" docName="draft-ietf-suit-firmware-encryption-20" category="std" consensus="true" tocInclude="true" sortRefs="true" symRefs="true">
<front>
<title abbrev="Encrypted Payloads in SUIT Manifests">Encrypted Payloads in SUIT Manifests</title>
<author initials="H." surname="Tschofenig" fullname="Hannes Tschofenig">
<organization></organization>
<address>
<email>[email protected]</email>
</address>
</author>
<author initials="R." surname="Housley" fullname="Russ Housley">
<organization abbrev="Vigil Security">Vigil Security, LLC</organization>
<address>
<email>[email protected]</email>
</address>
</author>
<author initials="B." surname="Moran" fullname="Brendan Moran">
<organization>Arm Limited</organization>
<address>
<email>[email protected]</email>
</address>
</author>
<author initials="D." surname="Brown" fullname="David Brown">
<organization>Linaro</organization>
<address>
<email>[email protected]</email>
</address>
</author>
<author initials="K." surname="Takayama" fullname="Ken Takayama">
<organization>SECOM CO., LTD.</organization>
<address>
<email>[email protected]</email>
</address>
</author>
<date year="2024" month="July" day="08"/>
<area>Security</area>
<workgroup>SUIT</workgroup>
<keyword>Internet-Draft</keyword>
<abstract>
<?line 93?>
<t>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.</t>
</abstract>
</front>
<middle>
<?line 102?>
<section anchor="introduction"><name>Introduction</name>
<t>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 <xref target="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.</t>
<t><xref target="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.</t>
<t>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) <xref target="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.</t>
<t>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:</t>
<t><list style="symbols">
<t>software packages,</t>
<t>personalization data,</t>
<t>configuration data, and</t>
<t>machine learning models.</t>
</list></t>
<t>Hence, we use the term payload to generically refer to all those objects.</t>
<t>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:</t>
<t><list style="symbols">
<t>Ephemeral-Static (ES) Diffie-Hellman (DH), and</t>
<t>AES Key Wrap (AES-KW).</t>
</list></t>
<t>The former method relies on asymmetric key cryptography while the
latter uses symmetric key cryptography.</t>
<t>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.</t>
<t>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.</t>
</section>
<section anchor="conventions-and-terminology"><name>Conventions and Terminology</name>
<t>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 <xref target="RFC2119"/> <xref target="RFC8174"/>
when, and only when, they appear in all capitals, as shown here.</t>
<t>This document assumes familiarity with the IETF SUIT manifest <xref target="I-D.ietf-suit-manifest"/>,
the SUIT information model <xref target="RFC9124"/>, and the SUIT architecture <xref target="RFC9019"/>.</t>
<t>The following abbreviations are used in this document:</t>
<t><list style="symbols">
<t>Key Wrap (KW), defined in <xref target="RFC3394"/> (for use with AES)</t>
<t>Key-Encryption Key (KEK) <xref target="RFC3394"/></t>
<t>Content-Encryption Key (CEK) <xref target="RFC5652"/></t>
<t>Ephemeral-Static (ES) Diffie-Hellman (DH) <xref target="RFC9052"/></t>
<t>Authenticated Encryption with Associated Data (AEAD)</t>
<t>Execute in Place (XIP)</t>
</list></t>
<t>The terms sender and recipient have the following meaning:</t>
<t><list style="symbols">
<t>Sender: Entity that sends an encrypted payload.</t>
<t>Recipient: Entity that receives an encrypted payload.</t>
</list></t>
<t>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).</t>
<t>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.</t>
<t>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.</t>
</section>
<section anchor="arch"><name>Architecture</name>
<t><xref target="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 <xref target="arch-fig"/> shows it graphically.</t>
<t>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 <xref target="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.</t>
<t>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.</t>
<figure title="Architecture for the distribution of Encrypted Payloads." anchor="arch-fig"><artset><artwork type="svg"><svg xmlns="http://www.w3.org/2000/svg" version="1.1" height="384" width="472" viewBox="0 0 472 384" class="diagram" text-anchor="middle" font-family="monospace" font-size="13px">
<path d="M 8,32 L 8,96" fill="none" stroke="black"/>
<path d="M 8,160 L 8,224" fill="none" stroke="black"/>
<path d="M 8,288 L 8,352" fill="none" stroke="black"/>
<path d="M 96,32 L 96,96" fill="none" stroke="black"/>
<path d="M 96,160 L 96,224" fill="none" stroke="black"/>
<path d="M 96,288 L 96,352" fill="none" stroke="black"/>
<path d="M 128,64 L 128,320" fill="none" stroke="black"/>
<path d="M 328,160 L 328,208" fill="none" stroke="black"/>
<path d="M 344,48 L 344,80" fill="none" stroke="black"/>
<path d="M 384,88 L 384,152" fill="none" stroke="black"/>
<path d="M 432,48 L 432,80" fill="none" stroke="black"/>
<path d="M 448,160 L 448,208" fill="none" stroke="black"/>
<path d="M 8,32 L 96,32" fill="none" stroke="black"/>
<path d="M 344,48 L 432,48" fill="none" stroke="black"/>
<path d="M 104,64 L 128,64" fill="none" stroke="black"/>
<path d="M 344,80 L 432,80" fill="none" stroke="black"/>
<path d="M 8,96 L 96,96" fill="none" stroke="black"/>
<path d="M 8,160 L 96,160" fill="none" stroke="black"/>
<path d="M 328,160 L 448,160" fill="none" stroke="black"/>
<path d="M 104,192 L 320,192" fill="none" stroke="black"/>
<path d="M 328,208 L 448,208" fill="none" stroke="black"/>
<path d="M 8,224 L 96,224" fill="none" stroke="black"/>
<path d="M 8,288 L 96,288" fill="none" stroke="black"/>
<path d="M 104,320 L 128,320" fill="none" stroke="black"/>
<path d="M 8,352 L 96,352" fill="none" stroke="black"/>
<polygon class="arrowhead" points="392,152 380,146.4 380,157.6 " fill="black" transform="rotate(90,384,152)"/>
<polygon class="arrowhead" points="112,320 100,314.4 100,325.6 " fill="black" transform="rotate(180,104,320)"/>
<polygon class="arrowhead" points="112,192 100,186.4 100,197.6 " fill="black" transform="rotate(180,104,192)"/>
<polygon class="arrowhead" points="112,64 100,58.4 100,69.6 " fill="black" transform="rotate(180,104,64)"/>
<g class="text">
<text x="52" y="52">Device</text>
<text x="48" y="68">1</text>
<text x="388" y="68">Author</text>
<text x="424" y="116">Payload</text>
<text x="464" y="116">+</text>
<text x="428" y="132">Manifest</text>
<text x="52" y="180">Device</text>
<text x="176" y="180">Payload</text>
<text x="216" y="180">+</text>
<text x="260" y="180">Manifest</text>
<text x="388" y="180">Distribution</text>
<text x="48" y="196">2</text>
<text x="388" y="196">System</text>
<text x="56" y="260">...</text>
<text x="52" y="308">Device</text>
<text x="48" y="324">n</text>
</g>
</svg>
</artwork><artwork type="ascii-art"><![CDATA[
+----------+
| Device | +----------+
| 1 |<--+ | Author |
| | | +----------+
+----------+ | |
| | Payload +
| | Manifest
| v
+----------+ | +--------------+
| Device | | Payload + Manifest | Distribution |
| 2 |<--+------------------------| System |
| | | +--------------+
+----------+ |
|
... |
|
+----------+ |
| Device | |
| n |<--+
| |
+----------+
]]></artwork></artset></figure>
<t>The author has several deployment options, namely:</t>
<t><list style="symbols">
<t>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 <xref target="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.</t>
<t>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.</t>
</list></t>
<t>If the author delegates encryption rights to the distributor two models are possible:</t>
<t><list style="numbers" type="1">
<t>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 <xref target="RFC9124"/>. This model nevertheless represent the current
state of firmware updates for IoT devices.</t>
<t>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 <xref target="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.</t>
</list></t>
<t>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.</t>
<t>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.</t>
</section>
<section anchor="parameters"><name>Encryption Extensions</name>
<t>This specification introduces a new extension to the SUIT_Parameters structure.</t>
<t>The SUIT_Encryption_Info structure (called suit-parameter-encryption-info in
<xref target="parameter-fig"/>) contains the content key distribution information. The
content of the SUIT_Encryption_Info structure is explained in <xref target="AES-KW"/>
(for AES-KW) and in <xref target="ES-DH"/> (for ES-DH).</t>
<t>Once a CEK is available, the steps described in <xref target="content-enc"/> are applicable.
These steps apply to both content key distribution methods described in this
section.</t>
<t>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
is supported. Mandating only a single content key distribution
method for a constrained device also reduces the code size.</t>
<figure title="CDDL of the SUIT_Parameters Extension." anchor="parameter-fig"><artwork><![CDATA[
SUIT_Parameters //= (suit-parameter-encryption-info
=> bstr .cbor SUIT_Encryption_Info)
suit-parameter-encryption-info = TBD19
]]></artwork></figure>
<t>RFC Editor's Note (TBD19): The value for the suit-parameter-encryption-info
parameter is set to 19, as the proposed value.</t>
</section>
<section anchor="extended-directives"><name>Extended Directives</name>
<t>This specification extends these directives:</t>
<t><list style="symbols">
<t>Directive Write (suit-directive-write) to decrypt the content specified by
suit-parameter-content with suit-parameter-encryption-info.</t>
<t>Directive Copy (suit-directive-copy) to decrypt the content of the component
specified by suit-parameter-source-component with suit-parameter-encryption-info.</t>
</list></t>
<t>Examples of the two directives are shown below. These example focus on the
essential aspects. A complete example for AES Key Wrap with the Fetch and Copy
Directives can be found in <xref target="example-AES-KW-copy"/>. An example illustrating
the Write Directive is shown in <xref target="example-AES-KW-write"/>.</t>
<t><xref target="encryption-info-consumed-with-write"/> 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.</t>
<figure title="Example showing the extended suit-directive-write." anchor="encryption-info-consumed-with-write"><artwork><![CDATA[
/ directive-override-parameters / 20, {
/ parameter-content / 18: h'EA1...CED',
/ parameter-encryption-info / TBD19: h'D86...1F0'
},
/ directive-write / 18, 15
]]></artwork></figure>
<t>RFC Editor's Note (TBD19): The value for the parameter-encryption-info
parameter is set to 19, as the proposed value.</t>
<t><xref target="encryption-info-consumed-with-copy"/> 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.</t>
<figure title="Example showing the extended suit-directive-copy." anchor="encryption-info-consumed-with-copy"><artwork><![CDATA[
/ 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 / TBD19: h'D86...1F0',
/ parameter-source-component / 22: 1
},
/ directive-copy / 22, 15
]]></artwork></figure>
<t>RFC Editor's Note (TBD19): The value for the suit-parameter-encryption-info
parameter is set to 19, as the proposed value.</t>
<t>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.)</t>
<t>The lack of authentication and integrity protection of the payload is
particularly a concern when a cipher without integrity protection is
used.</t>
<t>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 <xref target="I-D.ietf-suit-manifest"/>.</t>
<t>Once a CEK is available, the steps described in <xref target="content-enc"/> are applicable.
These steps apply to both content key distribution methods.</t>
</section>
<section anchor="content-key-distribution"><name>Content Key Distribution</name>
<t>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 are 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.</t>
<t>The two content key distribution methods require the CEKs to be
randomly generated. The guidelines for random number generation
in <xref target="RFC8937"/> MUST be followed.</t>
<t>When an encrypted payload is sent to multiple recipients, there
are different deployment options. To explain these options we use the
following notation:</t>
<figure><artwork><![CDATA[
- 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.
]]></artwork></figure>
<section anchor="AES-KW"><name>Content Key Distribution with AES Key Wrap</name>
<section anchor="introduction-1"><name>Introduction</name>
<t>The AES Key Wrap (AES-KW) algorithm is described in <xref target="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 <xref target="RFC9052"/> and in Section 6.2.1 of
<xref target="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.</t>
<t>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.</t>
<t>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.</t>
</section>
<section anchor="deployment-options"><name>Deployment Options</name>
<t>There are three deployment options for use with AES Key Wrap for payload
encryption:</t>
<t><list style="symbols">
<t>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:</t>
</list></t>
<figure><artwork><![CDATA[
1. Fetch KEK(*, S)
2. Generate CEK
3. ENC(CEK, KEK)
4. ENC(payload, CEK)
]]></artwork></figure>
<t>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.</t>
<t><list style="symbols">
<t>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:</t>
</list></t>
<figure><artwork><![CDATA[
1. Generate CEK
2. for i=1 to n
{
2a. Fetch KEK(Ri, S)
2b. ENC(CEK, KEK(Ri, S))
}
3. ENC(payload, CEK)
]]></artwork></figure>
<t><list style="symbols">
<t>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:</t>
</list></t>
<figure><artwork><![CDATA[
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. }
]]></artwork></figure>
</section>
<section anchor="cddl"><name>CDDL</name>
<t>The CDDL for the AES-KW binary is shown in <xref target="cddl-aeskw"/>.
empty_or_serialized_map and header_map are structures defined in <xref target="RFC9052"/>.</t>
<figure title="CDDL for AES-KW-based Content Key Distribution" anchor="cddl-aeskw"><artwork><![CDATA[
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
}
]]></artwork></figure>
<t>Note that the AES-KW algorithm, as defined in Section 2.2.3.1 of <xref target="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.</t>
</section>
</section>
<section anchor="ES-DH"><name>Content Key Distribution with Ephemeral-Static Diffie-Hellman</name>
<section anchor="introduction-2"><name>Introduction</name>
<t>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 <xref target="RFC9052"/>.</t>
<t>The following two layer structure is used:</t>
<t><list style="symbols">
<t>Layer 0: Has a content encrypted with the CEK. The content may be detached.</t>
<t>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.</t>
</list></t>
<t>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 <xref target="esdh-aesgcm-example"/>.</t>
<t>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.</t>
</section>
<section anchor="deployment-options-1"><name>Deployment Options</name>
<t>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.</t>
<t><list style="symbols">
<t>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.</t>
</list></t>
<t>The steps taken by the sender are:</t>
<figure><artwork><![CDATA[
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)
]]></artwork></figure>
<t><list style="symbols">
<t>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:</t>
</list></t>
<figure><artwork><![CDATA[
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))
}
]]></artwork></figure>
</section>
<section anchor="cddl-1"><name>CDDL</name>
<t>The CDDL for the ECDH-ES+AES-KW binary is shown in <xref target="cddl-esdh"/>.
Only the minimum number of parameters is shown. empty_or_serialized_map
and header_map are structures defined in <xref target="RFC9052"/>.</t>
<figure title="CDDL for ES-DH-based Content Key Distribution" anchor="cddl-esdh"><artwork><![CDATA[
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
}
]]></artwork></figure>
<t>See <xref target="content-enc"/> for a description on how to encrypt the payload.</t>
</section>
<section anchor="context-information-structure"><name>Context Information Structure</name>
<t>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 <xref target="RFC9053"/> and tailors it accordingly.</t>
<t>The following information elements are bound to the context:</t>
<t><list style="symbols">
<t>the protocol employing the key-derivation method,</t>
<t>information about the utilized AES Key Wrap algorithm, and the key length.</t>
<t>the protected header field, which contains the content key encryption algorithm.</t>
</list></t>
<t>The sender and recipient identities are left empty.</t>
<t>The following fields in <xref target="cddl-context-info"/> require an explanation:</t>
<t><list style="symbols">
<t>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)</t>
<t>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.</t>
<t>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".</t>
<t>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.</t>
</list></t>
<figure title="CDDL for COSE_KDF_Context Structure" anchor="cddl-context-info"><sourcecode type="CDDL"><![CDATA[
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
)
]]></sourcecode></figure>
<t>The HKDF-based key derivation function MAY contain a salt value,
as described in Section 5.1 of <xref target="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 <xref target="RFC5869"/> and NIST
SP800-56 <xref target="SP800-56"/>.</t>
<t>Profiles of this specification MAY specify an extended version of the
context information structure or MAY utilize a different context information
structure.</t>
</section>
</section>
</section>
<section anchor="content-enc"><name>Content Encryption</name>
<t>This section summarizes the steps taken for content encryption, which
applies to both content key distribution methods.</t>
<t>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 <xref target="cddl-enc-aeskw"/> and is defined in Section 5.3 of <xref target="RFC9052"/>.</t>
<figure title="CDDL for Enc_structure Data Structure" anchor="cddl-enc-aeskw"><artwork><![CDATA[
Enc_structure = [
context : "Encrypt",
protected : empty_or_serialized_map,
external_aad : bstr
]
]]></artwork></figure>
<t>This Enc_structure needs to be populated as follows:</t>
<t><list style="symbols">
<t>The protected field in the Enc_structure from <xref target="cddl-enc-aeskw"/> refers
to the content of the protected field from the COSE_Encrypt structure.</t>
<t>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.</t>
</list></t>
<t>Some ciphers provide confidentiality without integrity protection, such
as AES-CTR and AES-CBC (see <xref target="RFC9459"/>). For these ciphers the
Enc_structure, shown in <xref target="cddl-enc-aeskw"/>, 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.</t>
<section anchor="aes-gcm"><name>AES-GCM</name>
<section anchor="introduction-3"><name>Introduction</name>
<t>AES-GCM is an AEAD cipher and provides confidentiality and integrity protection.</t>
<t>Examples in this section use the following parameters:</t>
<t><list style="symbols">
<t>Algorithm for payload encryption: AES-GCM-128
<list style="symbols">
<t>k: h'15F785B5C931414411B4B71373A9C0F7'</t>
<t>IV: h'F14AAB9D81D51F7AD943FE87AF4F70CD'</t>
</list></t>
<t>Plaintext: "This is a real firmware image."
<list style="symbols">
<t>in hex: 546869732069732061207265616C206669726D7761726520696D6167652E</t>
</list></t>
</list></t>
</section>
<section anchor="aes-kw-aes-gcm-example"><name>AES-KW + AES-GCM Example</name>
<t>This example uses the following parameters:</t>
<t><list style="symbols">
<t>Algorithm id for key wrap: A128KW</t>
<t>KEK COSE_Key (Secret Key):
<list style="symbols">
<t>kty: Symmetric</t>
<t>k: 'aaaaaaaaaaaaaaaa'</t>
<t>kid: 'kid-1'</t>
</list></t>
</list></t>
<t>The COSE_Encrypt structure, in hex format, is (with a line break inserted):</t>
<figure><artwork><![CDATA[
D8608443A10101A10550F14AAB9D81D51F7AD943FE87AF4F70CDF6818340
A2012204456B69642D31581875603FFC9518D794713C8CA8A115A7FB3256
5A6D59534D62
]]></artwork></figure>
<t>The resulting COSE_Encrypt structure in a diagnostic format is shown in
<xref target="aeskw-aesgcm-example"/>.</t>
<figure title="COSE_Encrypt Example for AES Key Wrap" anchor="aeskw-aesgcm-example"><artwork><![CDATA[
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 /
]
]
])
]]></artwork></figure>
<t>The encrypted payload (with a line feed added) was:</t>
<figure><artwork><![CDATA[
2F59C3A34D9570FB99A5382E66466A3221A8AD85CE508BA306FB431A60EF
A5AAAA078355070205A4B196832DF17F
]]></artwork></figure>
</section>
<section anchor="ecdh-esaes-kw-aes-gcm-example"><name>ECDH-ES+AES-KW + AES-GCM Example</name>
<t>This example uses the following parameters:</t>
<t><list style="symbols">
<t>Algorithm for content key distribution: ECDH-ES + A128KW</t>
<t>KEK COSE_Key (Receiver's Private Key):
<list style="symbols">
<t>kty: EC2</t>
<t>crv: P-256</t>
<t>x: h'5886CD61DD875862E5AAA820E7A15274C968A9BC96048DDCACE32F50C3651BA3'</t>
<t>y: h'9EED8125E932CD60C0EAD3650D0A485CF726D378D1B016ED4298B2961E258F1B'</t>
<t>d: h'60FE6DD6D85D5740A5349B6F91267EEAC5BA81B8CB53EE249E4B4EB102C476B3'</t>
<t>kid: 'kid-2'</t>
</list></t>
<t>KDF Context
<list style="symbols">
<t>Algorithm ID: 1 (A128GCM)</t>
<t>SuppPubInfo
<list style="symbols">
<t>keyDataLength: 128</t>
<t>protected: { / alg / 1: -29 / ECDH-ES+A128KW / }</t>
<t>other: 'SUIT Payload Encryption'</t>
</list></t>
</list></t>
</list></t>
<t>The COSE_Encrypt structure, in hex format, is (with a line break inserted):</t>
<figure><artwork><![CDATA[
D8608443A10101A10550F14AAB9D81D51F7AD943FE87AF4F70CDF6818344
A101381CA120A40102200121582038876D8B4552E6BC9484A3F06E3646B3
0AEFF51B95583CFFA0B5776D5273494222582034577AB5DD17276BB6BF15
AA465310371557AFF61FAC5BA5A1EFF46698DD8B7B5818C36BF2E8843246
F0E148DBA607375204A040D8B19629B2B5
]]></artwork></figure>
<t>The resulting COSE_Encrypt structure in a diagnostic format is shown in
<xref target="esdh-aesgcm-example"/>.</t>
<figure title="COSE_Encrypt Example for ES-DH" anchor="esdh-aesgcm-example"><artwork><![CDATA[
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 /
]
]
])
]]></artwork></figure>
<t>The encrypted payload (with a line feed added) was:</t>
<figure><artwork><![CDATA[
2F59C3A34D9570FB99A5382E66466A3221A8AD85CE508BA306FB431A60EF
A5AAAA078355070205A4B196832DF17F
]]></artwork></figure>
</section>
</section>
<section anchor="aes-ctr"><name>AES-CTR</name>
<section anchor="introduction-4"><name>Introduction</name>
<t>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 <xref target="aes-ctr-fig"/>.
Hence, when an image is encrypted using AES-CTR-128 or AES-CTR-256, the IV MUST