-
Notifications
You must be signed in to change notification settings - Fork 10
/
draft-ietf-suit-manifest.txt
5656 lines (3800 loc) · 216 KB
/
draft-ietf-suit-manifest.txt
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
SUIT B. Moran
Internet-Draft Arm Limited
Intended status: Standards Track H. Tschofenig
Expires: 8 August 2024
H. Birkholz
Fraunhofer SIT
K. Zandberg
Inria
Ø. Rønningstad
Nordic Semiconductor
5 February 2024
A Concise Binary Object Representation (CBOR)-based Serialization Format
for the Software Updates for Internet of Things (SUIT) Manifest
draft-ietf-suit-manifest-25
Abstract
This specification describes the format of a manifest. A manifest is
a bundle of metadata about code/data obtained by a recipient (chiefly
the firmware for an IoT device), where to find the code/data, the
devices to which it applies, and cryptographic information protecting
the manifest. Software updates and Trusted Invocation both tend to
use sequences of common operations, so the manifest encodes those
sequences of operations, rather than declaring the metadata.
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 8 August 2024.
Copyright Notice
Copyright (c) 2024 IETF Trust and the persons identified as the
document authors. All rights reserved.
Moran, et al. Expires 8 August 2024 [Page 1]
Internet-Draft CBOR-based SUIT Manifest February 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 . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Conventions and Terminology . . . . . . . . . . . . . . . . . 6
3. How to use this Document . . . . . . . . . . . . . . . . . . 8
4. Background . . . . . . . . . . . . . . . . . . . . . . . . . 9
4.1. IoT Firmware Update Constraints . . . . . . . . . . . . . 9
4.2. SUIT Workflow Model . . . . . . . . . . . . . . . . . . . 10
5. Metadata Structure Overview . . . . . . . . . . . . . . . . . 11
5.1. Envelope . . . . . . . . . . . . . . . . . . . . . . . . 12
5.2. Authentication Block . . . . . . . . . . . . . . . . . . 12
5.3. Manifest . . . . . . . . . . . . . . . . . . . . . . . . 13
5.3.1. Critical Metadata . . . . . . . . . . . . . . . . . . 13
5.3.2. Common . . . . . . . . . . . . . . . . . . . . . . . 13
5.3.3. Command Sequences . . . . . . . . . . . . . . . . . . 13
5.3.4. Integrity Check Values . . . . . . . . . . . . . . . 14
5.3.5. Human-Readable Text . . . . . . . . . . . . . . . . . 14
5.4. Severable Elements . . . . . . . . . . . . . . . . . . . 14
5.5. Integrated Payloads . . . . . . . . . . . . . . . . . . . 15
6. Manifest Processor Behavior . . . . . . . . . . . . . . . . . 15
6.1. Manifest Processor Setup . . . . . . . . . . . . . . . . 15
6.2. Required Checks . . . . . . . . . . . . . . . . . . . . 17
6.3. Interpreter Fundamental Properties . . . . . . . . . . . 18
6.3.1. Resilience to Disruption . . . . . . . . . . . . . . 18
6.4. Abstract Machine Description . . . . . . . . . . . . . . 19
6.5. Special Cases of Component Index . . . . . . . . . . . . 21
6.6. Serialized Processing Interpreter . . . . . . . . . . . . 22
6.7. Parallel Processing Interpreter . . . . . . . . . . . . . 23
7. Creating Manifests . . . . . . . . . . . . . . . . . . . . . 24
7.1. Compatibility Check Template . . . . . . . . . . . . . . 25
7.2. Trusted Invocation Template . . . . . . . . . . . . . . . 25
7.3. Component Download Template . . . . . . . . . . . . . . . 26
7.4. Install Template . . . . . . . . . . . . . . . . . . . . 26
7.5. Integrated Payload Template . . . . . . . . . . . . . . . 27
7.6. Load from Nonvolatile Storage Template . . . . . . . . . 27
7.7. A/B Image Template . . . . . . . . . . . . . . . . . . . 27
8. Metadata Structure . . . . . . . . . . . . . . . . . . . . . 29
8.1. Encoding Considerations . . . . . . . . . . . . . . . . . 29
8.2. Envelope . . . . . . . . . . . . . . . . . . . . . . . . 30
Moran, et al. Expires 8 August 2024 [Page 2]
Internet-Draft CBOR-based SUIT Manifest February 2024
8.3. Authenticated Manifests . . . . . . . . . . . . . . . . . 30
8.4. Manifest . . . . . . . . . . . . . . . . . . . . . . . . 31
8.4.1. suit-manifest-version . . . . . . . . . . . . . . . . 32
8.4.2. suit-manifest-sequence-number . . . . . . . . . . . . 32
8.4.3. suit-reference-uri . . . . . . . . . . . . . . . . . 32
8.4.4. suit-text . . . . . . . . . . . . . . . . . . . . . . 32
8.4.5. suit-common . . . . . . . . . . . . . . . . . . . . . 34
8.4.6. SUIT_Command_Sequence . . . . . . . . . . . . . . . . 35
8.4.7. Reporting Policy . . . . . . . . . . . . . . . . . . 37
8.4.8. SUIT_Parameters . . . . . . . . . . . . . . . . . . . 38
8.4.9. SUIT_Condition . . . . . . . . . . . . . . . . . . . 46
8.4.10. SUIT_Directive . . . . . . . . . . . . . . . . . . . 49
8.4.11. suit-command-custom . . . . . . . . . . . . . . . . . 54
8.4.12. Integrity Check Values . . . . . . . . . . . . . . . 54
8.5. Severable Elements . . . . . . . . . . . . . . . . . . . 54
9. Access Control Lists . . . . . . . . . . . . . . . . . . . . 55
10. SUIT Digest Container . . . . . . . . . . . . . . . . . . . . 56
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 56
11.1. SUIT Envelope Elements . . . . . . . . . . . . . . . . . 56
11.2. SUIT Manifest Elements . . . . . . . . . . . . . . . . . 57
11.3. SUIT Common Elements . . . . . . . . . . . . . . . . . . 58
11.4. SUIT Commands . . . . . . . . . . . . . . . . . . . . . 58
11.5. SUIT Parameters . . . . . . . . . . . . . . . . . . . . 60
11.6. SUIT Text Values . . . . . . . . . . . . . . . . . . . . 61
11.7. SUIT Component Text Values . . . . . . . . . . . . . . 62
11.8. Expert Review Instructions . . . . . . . . . . . . . . . 63
11.9. Media Type Registration . . . . . . . . . . . . . . . . 64
12. Security Considerations . . . . . . . . . . . . . . . . . . . 66
13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 68
14. References . . . . . . . . . . . . . . . . . . . . . . . . . 69
14.1. Normative References . . . . . . . . . . . . . . . . . . 69
14.2. Informative References . . . . . . . . . . . . . . . . . 70
Appendix A. A. Full CDDL . . . . . . . . . . . . . . . . . . . 71
Appendix B. B. Examples . . . . . . . . . . . . . . . . . . . . 77
B.1. Example 0: Secure Boot . . . . . . . . . . . . . . . . . 79
B.2. Example 1: Simultaneous Download and Installation of
Payload . . . . . . . . . . . . . . . . . . . . . . . . . 81
B.3. Example 2: Simultaneous Download, Installation, Secure
Boot, Severed Fields . . . . . . . . . . . . . . . . . . 83
B.4. Example 3: A/B images . . . . . . . . . . . . . . . . . . 86
B.5. Example 4: Load from External Storage . . . . . . . . . . 89
B.6. Example 5: Two Images . . . . . . . . . . . . . . . . . . 92
Appendix C. C. Design Rational . . . . . . . . . . . . . . . . 95
C.1. C.1 Design Rationale: Envelope . . . . . . . . . . . . . 96
C.2. C.2 Byte String Wrappers . . . . . . . . . . . . . . . . 97
Appendix D. D. Implementation Conformance Matrix . . . . . . . 98
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 100
Moran, et al. Expires 8 August 2024 [Page 3]
Internet-Draft CBOR-based SUIT Manifest February 2024
1. Introduction
A firmware update mechanism is an essential security feature for IoT
devices to deal with vulnerabilities. The transport of firmware
images to the devices themselves is important security aspect.
Luckily, there are already various device management solutions
available offering the distribution of firmware images to IoT
devices. Equally important is the inclusion of metadata about the
conveyed firmware image (in the form of a manifest) and the use of a
security wrapper to provide end-to-end security protection to detect
modifications and (optionally) to make reverse engineering more
difficult. Firmware signing allows the author, who builds the
firmware image, to be sure that no other party (including potential
adversaries) can install firmware updates on IoT devices without
adequate privileges. For confidentiality protected firmware images
it is additionally required to encrypt the firmware image and to
distribute the content encryption key securely. The support for
firmware and payload encryption via the SUIT manifest format is
described in a companion document
[I-D.ietf-suit-firmware-encryption]. Starting security protection at
the author is a risk mitigation technique so firmware images and
manifests can be stored on untrusted repositories; it also reduces
the scope of a compromise of any repository or intermediate system to
be no worse than a denial of service.
A manifest is a bundle of metadata about the firmware for an IoT
device, where to find the firmware, and the devices to which it
applies.
This specification defines the SUIT manifest format and it is
intended to meet several goals:
* Meet the requirements defined in [RFC9124].
* Simple to parse on a constrained node.
* Simple to process on a constrained node.
* Compact encoding.
* Comprehensible by an intermediate system.
* Expressive enough to enable advanced use cases on advanced nodes.
* Extensible.
The SUIT manifest can be used for a variety of purposes throughout
its lifecycle, such as:
Moran, et al. Expires 8 August 2024 [Page 4]
Internet-Draft CBOR-based SUIT Manifest February 2024
* a Network Operator to reason about compatibility of a firmware,
such as timing and acceptance of firmware updates.
* a Device Operator to reason about the impact of a firmware.
* a device to reason about the authority & authenticity of a
firmware prior to installation.
* a device to reason about the applicability of a firmware.
* a device to reason about the installation of a firmware.
* a device to reason about the authenticity & encoding of a firmware
at boot.
Each of these uses happens at a different stage of the manifest
lifecycle, so each has different requirements.
It is assumed that the reader is familiar with the high-level
firmware update architecture [RFC9019] and the threats, requirements,
and user stories in [RFC9124].
The design of this specification is based on an observation that the
vast majority of operations that a device can perform during an
update or Trusted Invocation are composed of a small group of
operations:
* Copy some data from one place to another
* Transform some data
* Digest some data and compare to an expected value
* Compare some system parameters to an expected value
* Run some code
In this document, these operations are called commands. Commands are
classed as either conditions or directives. Conditions have no side-
effects, while directives do have side-effects. Conceptually, a
sequence of commands is like a script but the language is tailored to
software updates and Trusted Invocation.
The available commands support simple steps, such as copying a
firmware image from one place to another, checking that a firmware
image is correct, verifying that the specified firmware is the
correct firmware for the device, or unpacking a firmware. By using
these steps in different orders and changing the parameters they use,
Moran, et al. Expires 8 August 2024 [Page 5]
Internet-Draft CBOR-based SUIT Manifest February 2024
a broad range of use cases can be supported. The SUIT manifest uses
this observation to optimize metadata for consumption by constrained
devices.
While the SUIT manifest is informed by and optimized for firmware
update and Trusted Invocation use cases, there is nothing in the SUIT
Information Model [RFC9124] that restricts its use to only those use
cases. Other use cases include the management of trusted
applications (TAs) in a Trusted Execution Environment (TEE), as
discussed in [RFC9397].
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.
Additionally, the following terminology is used throughout this
document:
* SUIT: Software Update for the Internet of Things, also the IETF
working group for this standard.
* Payload: A piece of information to be delivered. Typically
Firmware for the purposes of SUIT.
* Resource: A piece of information that is used to construct a
payload.
* Manifest: A manifest is a bundle of metadata about the firmware
for an IoT device, where to find the firmware, and the devices to
which it applies.
* Envelope: A container with the manifest, an authentication wrapper
with cryptographic information protecting the manifest,
authorization information, and severable elements. Severable
elements can be removed from the manifest without impacting its
security, see Section 8.5.
* Update: One or more manifests that describe one or more payloads.
* Update Authority: The owner of a cryptographic key used to sign
updates, trusted by Recipients.
* Recipient: The system, typically an IoT device, that receives and
processes a manifest.
Moran, et al. Expires 8 August 2024 [Page 6]
Internet-Draft CBOR-based SUIT Manifest February 2024
* Manifest Processor: A component of the Recipient that consumes
Manifests and executes the commands in the Manifest.
* Component: An updatable logical block of the Firmware, Software,
configuration, or data of the Recipient.
* Component Set: A group of interdependent Components that must be
updated simultaneously.
* Command: A Condition or a Directive.
* Condition: A test for a property of the Recipient or its
Components.
* Directive: An action for the Recipient to perform.
* Trusted Invocation: A process by which a system ensures that only
trusted code is executed, for example secure boot or launching a
Trusted Application.
* A/B images: Dividing a Recipient's storage into two or more
bootable images, at different offsets, such that the active image
can write to the inactive image(s).
* Record: The result of a Command and any metadata about it.
* Report: A list of Records.
* Procedure: The process of invoking one or more sequences of
commands.
* Update Procedure: A procedure that updates a Recipient by fetching
dependencies and images, and installing them.
* Invocation Procedure: A procedure in which a Recipient verifies
dependencies and images, loading images, and invokes one or more
image.
* Software: Instructions and data that allow a Recipient to perform
a useful function.
* Firmware: Software that is typically changed infrequently, stored
in nonvolatile memory, and small enough to apply to [RFC7228]
Class 0-2 devices.
* Image: Information that a Recipient uses to perform its function,
typically firmware/software, configuration, or resource data such
as text or images. Also, a Payload, once installed is an Image.
Moran, et al. Expires 8 August 2024 [Page 7]
Internet-Draft CBOR-based SUIT Manifest February 2024
* Slot: One of several possible storage locations for a given
Component, typically used in A/B image systems
* Abort: An event in which the Manifest Processor immediately halts
execution of the current Procedure. It creates a Record of an
error condition.
3. How to use this Document
This specification covers five aspects of firmware update:
* Section 4 describes the device constraints, use cases, and design
principles that informed the structure of the manifest.
* Section 5 gives a general overview of the metadata structure to
inform the following sections
* Section 6 describes what actions a Manifest processor should take.
* Section 7 describes the process of creating a Manifest.
* Section 8 specifies the content of the Envelope and the Manifest.
To implement an updatable device, see Section 6 and Section 8. To
implement a tool that generates updates, see Section 7 and Section 8.
The IANA consideration section, see Section 11, provides instructions
to IANA to create several registries. This section also provides the
CBOR labels for the structures defined in this document.
The complete CDDL description is provided in Appendix A, examples are
given in Appendix B and a design rational is offered in Appendix C.
Finally, Appendix D gives a summarize of the mandatory-to-implement
features of this specification.
Additional specifications describe functionality of advanced use
cases, such as:
* Firmware Encryption is covered in
[I-D.ietf-suit-firmware-encryption]
* Update Management is covered in [I-D.ietf-suit-update-management]
* Features, such as dependencies, key delegation, multiple
processors, required by the use of multiple trust domains are
covered in [I-D.ietf-suit-trust-domains]
Moran, et al. Expires 8 August 2024 [Page 8]
Internet-Draft CBOR-based SUIT Manifest February 2024
* Secure reporting of the update status is covered in
[I-D.ietf-suit-report]
A technique to efficiently compress firmware images may be
standardized in the future.
4. Background
Distributing software updates to diverse devices with diverse trust
anchors in a coordinated system presents unique challenges. Devices
have a broad set of constraints, requiring different metadata to make
appropriate decisions. There may be many actors in production IoT
systems, each of whom has some authority. Distributing firmware in
such a multi-party environment presents additional challenges. Each
party requires a different subset of data. Some data may not be
accessible to all parties. Multiple signatures may be required from
parties with different authorities. This topic is covered in more
depth in [RFC9019]. The security aspects are described in [RFC9124].
4.1. IoT Firmware Update Constraints
The various constraints of IoT devices and the range of use cases
that need to be supported create a broad set of requirements. For
example, devices with:
* limited processing power and storage may require a simple
representation of metadata.
* bandwidth constraints may require firmware compression or partial
update support.
* bootloader complexity constraints may require simple selection
between two bootable images.
* small internal storage may require external storage support.
* multiple microcontrollers may require coordinated update of all
applications.
* large storage and complex functionality may require parallel
update of many software components.
* extra information may need to be conveyed in the manifest in the
earlier stages of the device lifecycle before those data items are
stripped when the manifest is delivered to a constrained device.
Moran, et al. Expires 8 August 2024 [Page 9]
Internet-Draft CBOR-based SUIT Manifest February 2024
Supporting the requirements introduced by the constraints on IoT
devices requires the flexibility to represent a diverse set of
possible metadata, but also requires that the encoding is kept
simple.
4.2. SUIT Workflow Model
There are several fundamental assumptions that inform the model of
Update Procedure workflow:
* Compatibility must be checked before any other operation is
performed.
* In some applications, payloads must be fetched and validated prior
to installation.
There are several fundamental assumptions that inform the model of
the Invocation Procedure workflow:
* Compatibility must be checked before any other operation is
performed.
* All payloads must be validated prior to loading.
* All loaded images must be validated prior to execution.
Based on these assumptions, the manifest is structured to work with a
pull parser, where each section of the manifest is used in sequence.
The expected workflow for a Recipient installing an update can be
broken down into five steps:
1. Verify the signature of the manifest.
2. Verify the applicability of the manifest.
3. Fetch payload(s).
4. Install payload(s).
5. Verify image(s).
When installation is complete, similar information can be used for
validating and invoking images in a further three steps:
1. Verify image(s).
2. Load image(s).
Moran, et al. Expires 8 August 2024 [Page 10]
Internet-Draft CBOR-based SUIT Manifest February 2024
3. Invoke image(s).
If verification and invocation is implemented in a bootloader, then
the bootloader MUST also verify the signature of the manifest and the
applicability of the manifest in order to implement secure boot
workflows. The bootloader may add its own authentication, e.g. a
Message Authentication Code (MAC), to the manifest in order to
prevent further verifications.
5. Metadata Structure Overview
This section provides a high level overview of the manifest
structure. The full description of the manifest structure is in
Section 8.4
The manifest is structured from several key components:
1. The Envelope (see Section 5.1) contains the Authentication Block,
the Manifest, any Severable Elements, and any Integrated
Payloads.
2. The Authentication Block (see Section 5.2) contains a list of
signatures or MACs of the manifest.
3. The Manifest (see Section 5.3) contains all critical, non-
severable metadata that the Recipient requires. It is further
broken down into:
1. Critical metadata, such as sequence number.
2. Common metadata, such as affected components.
3. Command sequences, directing the Recipient how to install and
use the payload(s).
4. Integrity check values for severable elements.
4. Severable elements (see Section 5.4).
5. Integrated payloads (see Section 5.5).
The diagram below illustrates the hierarchy of the Envelope.
Moran, et al. Expires 8 August 2024 [Page 11]
Internet-Draft CBOR-based SUIT Manifest February 2024
+-------------------------+
| Envelope |
+-------------------------+
| Authentication Block |
| Manifest --------------> +------------------------------+
| Severable Elements | | Manifest |
| Integrated Payloads | +------------------------------+
+-------------------------+ | Structure Version |
| Sequence Number |
| Reference to Full Manifest |
+------ Common Structure |
| +---- Command Sequences |
+-------------------------+ | | | Digests of Envelope Elements |
| Common Structure | <--+ | +------------------------------+
+-------------------------+ |
| Components IDs | +-> +-----------------------+
| Common Command Sequence ---------> | Command Sequence |
+-------------------------+ +-----------------------+
| List of ( pairs of ( |
| * command code |
| * argument / |
| reporting policy |
| )) |
+-----------------------+
5.1. Envelope
The SUIT Envelope is a container that encloses the Authentication
Block, the Manifest, any Severable Elements, and any integrated
payloads. The Envelope is used instead of conventional cryptographic
envelopes, such as COSE_Envelope because it allows modular
processing, severing of elements, and integrated payloads in a way
that avoids substantial complexity that would be needed with existing
solutions. See Appendix C.1 for a description of the reasoning for
this.
See Section 8.2 for more detail.
5.2. Authentication Block
The Authentication Block contains a bstr-wrapped SUIT Digest
Container, see Section 10, and one or more [RFC9052] CBOR Object
Signing and Encryption (COSE) authentication blocks. These blocks
are one of:
* COSE_Sign_Tagged
* COSE_Sign1_Tagged
Moran, et al. Expires 8 August 2024 [Page 12]
Internet-Draft CBOR-based SUIT Manifest February 2024
* COSE_Mac_Tagged
* COSE_Mac0_Tagged
Each of these objects is used in detached payload mode. The payload
is the bstr-wrapped SUIT_Digest.
See Section 8.3 for more detail.
5.3. Manifest
The Manifest contains most metadata about one or more images. The
Manifest is divided into Critical Metadata, Common Metadata, Command
Sequences, and Integrity Check Values.
See Section 8.4 for more detail.
5.3.1. Critical Metadata
Some metadata needs to be accessed before the manifest is processed.
This metadata can be used to determine which manifest is newest and
whether the structure version is supported. It also MAY provide a
URI for obtaining a canonical copy of the manifest and Envelope.
See Section 8.4.1, Section 8.4.2, and Section 8.4.3 for more detail.
5.3.2. Common
Some metadata is used repeatedly and in more than one command
sequence. In order to reduce the size of the manifest, this metadata
is collected into the Common section. Common is composed of two
parts: a list of components referenced by the manifest, and a command
sequence to execute prior to each other command sequence. The common
command sequence is typically used to set commonly used values and
perform compatibility checks. The common command sequence MUST NOT
have any side-effects outside of setting parameter values.
See Section 8.4.5 for more detail.
5.3.3. Command Sequences
Command sequences provide the instructions that a Recipient requires
in order to install or use an image. These sequences tell a device
to set parameter values, test system parameters, copy data from one
place to another, transform data, digest data, and run code.
Moran, et al. Expires 8 August 2024 [Page 13]
Internet-Draft CBOR-based SUIT Manifest February 2024
Command sequences are broken up into three groups: Common Command
Sequence (see Section 5.3.2), update commands, and secure boot
commands.
Update Command Sequences are: Payload Fetch, Payload Installation
and, System Validation. An Update Procedure is the complete set of
each Update Command Sequence, each preceded by the Common Command
Sequence.
Invocation Command Sequences are: System Validation, Image Loading,
and Image Invocation. An Invocation Procedure is the complete set of
each Invocation Command Sequence, each preceded by the Common Command
Sequence.
Command Sequences are grouped into these sets to ensure that there is
common coordination between dependencies and dependents on when to
execute each command (dependencies are not defined in this
specification).
See Section 8.4.6 for more detail.
5.3.4. Integrity Check Values
To enable severable elements Section 5.4, there needs to be a
mechanism to verify the integrity of the severed data. While the
severed data stays outside the manifest, for efficiency reasons,
Integrity Check Values are used to include the digest of the data in
the manifest. Note that Integrated Payloads, see {#ovr-integrated},
are integrity-checked using Command Sequences.
See Section 8.4.12 for more detail.
5.3.5. Human-Readable Text
Text is typically a Severable Element (Section 5.4). It contains all
the text that describes the update. Because text is explicitly for
human consumption, it is all grouped together so that it can be
Severed easily. The text section has space both for describing the
manifest as a whole and for describing each individual component.
See Section 8.4.4 for more detail.
5.4. Severable Elements
Severable Elements are elements of the Envelope (Section 5.1) that
have Integrity Check Values (Section 5.3.4) in the Manifest
(Section 5.3).
Moran, et al. Expires 8 August 2024 [Page 14]
Internet-Draft CBOR-based SUIT Manifest February 2024
Because of this organisation, these elements can be discarded or
"Severed" from the Envelope without changing the signature of the
Manifest. This allows savings based on the size of the Envelope in
several scenarios, for example:
* A management system severs the Text sections before sending an
Envelope to a constrained Recipient, which saves Recipient
bandwidth.
* A Recipient severs the Installation section after installing the
Update, which saves storage space.
See Section 8.5 for more detail.
5.5. Integrated Payloads
In some cases, it is beneficial to include a payload in the Envelope
of a manifest. For example:
* When an update is delivered via a comparatively unconstrained
medium, such as a removable mass storage device, it may be
beneficial to bundle updates into single files.
* When a manifest transports a small payload, such as an encrypted
key, that payload may be placed in the manifest's envelope.
See Section 7.5 for more detail.
6. Manifest Processor Behavior
This section describes the behavior of the manifest processor and
focuses primarily on interpreting commands in the manifest. However,
there are several other important behaviors of the manifest
processor: encoding version detection, rollback protection, and
authenticity verification are chief among these.
6.1. Manifest Processor Setup
Prior to executing any command sequence, the manifest processor or
its host application MUST inspect the manifest version field and fail
when it encounters an unsupported encoding version. Next, the
manifest processor or its host application MUST extract the manifest
sequence number and perform a rollback check using this sequence
number. The exact logic of rollback protection may vary by
application, but it has the following properties:
* Whenever the manifest processor can choose between several
manifests, it MUST select the latest valid, authentic manifest.
Moran, et al. Expires 8 August 2024 [Page 15]
Internet-Draft CBOR-based SUIT Manifest February 2024
* If the latest valid, authentic manifest fails, it MAY select the
next latest valid, authentic manifest, according to application-
specific policy.
Here, valid means that a manifest has a supported encoding version
and it has not been excluded for other reasons. Reasons for
excluding typically involve first executing the manifest and may
include:
* Test failed (e.g. Vendor ID/Class ID).
* Unsupported command encountered.
* Unsupported parameter encountered.
* Unsupported Component Identifier encountered.
* Payload not available.
* Application crashed when executed.
* Watchdog timeout occurred.
* Payload verification failed.
* Missing required component from a Component Set.
* Required parameter not supplied.
These failure reasons MAY be combined with retry mechanisms prior to
marking a manifest as invalid.
Selecting an older manifest in the event of failure of the latest
valid manifest is one possible strategy to provide robustness of the
firmware update process. It may not be appropriate for all
applications. In particular Trusted Execution Environments MAY
require a failure to invoke a new installation, rather than a
rollback approach. See [RFC9124], Section 4.2.1 for more discussion
on the security considerations that apply to rollback.
Following these initial tests, the manifest processor clears all
parameter storage. This ensures that the manifest processor begins
without any leaked data.
Moran, et al. Expires 8 August 2024 [Page 16]
Internet-Draft CBOR-based SUIT Manifest February 2024
6.2. Required Checks
The RECOMMENDED process is to verify the signature of the manifest
prior to parsing/executing any section of the manifest. This guards
the parser against arbitrary input by unauthenticated third parties,
but it costs extra energy when a Recipient receives an incompatible
manifest.
When validating authenticity of manifests, the manifest processor MAY
use an ACL (see Section 9) to determine the extent of the rights
conferred by that authenticity.
Once a valid, authentic manifest has been selected, the manifest
processor MUST examine the component list and check that the number
of components listed in the manifest is not larger than the number in
the target system.
For each listed component, the manifest processor MUST provide
storage for the supported parameters. If the manifest processor does
not have sufficient temporary storage to process the parameters for
all components, it MAY process components serially for each command
sequence. See Section 6.6 for more details.
The manifest processor SHOULD check that the shared sequence contains
at least Check Vendor Identifier command and at least one Check Class
Identifier command.
Because the shared sequence contains Check Vendor Identifier and
Check Class Identifier command(s), no custom commands are permitted
in the shared sequence. This ensures that any custom commands are
only executed by devices that understand them.
If the manifest contains more than one component, each command
sequence MUST begin with a Set Component Index Section 8.4.10.1.
If a Recipient supports groups of interdependent components (a
Component Set), then it SHOULD verify that all Components in the
Component Set are specified by one update, that is:
1. the manifest Author has sufficient permissions for the requested
operations (see Section 9) and
2. the manifest specifies a digest and a payload for every Component
in the Component Set.
Moran, et al. Expires 8 August 2024 [Page 17]
Internet-Draft CBOR-based SUIT Manifest February 2024
6.3. Interpreter Fundamental Properties
The interpreter has a small set of design goals:
1. Executing an update MUST either result in an error, or a correct
system state that can be checked against known digests.
2. Executing a Trusted Invocation MUST either result in an error, or
an invoked image.
3. Executing the same manifest on multiple Recipients MUST result in
the same system state.
NOTE: when using A/B images, the manifest functions as two (or more)
logical manifests, each of which applies to a system in a particular
starting state. With that provision, design goal 3 holds.
6.3.1. Resilience to Disruption
As required in Section 3 of [RFC9019] and as an extension of design
goal 1, devices must remain operable after a disruption, such as a
power failure or network interruption, interrupts the update process.
The manifest processor must be resilient to these faults. In order
to enable this resilience, systems implementing the manifest
processor MUST make the following guarantees:
One of: 1. A fallback/recovery image is provided so that a disrupted
system can apply the SUIT Manifest again. 2. Manifest Authors MUST
construct Manifests in such a way that repeated partial invocations
of any Manifest always results in a correct system state. Typically
this is done by using Try-Each and Conditions to bypass operations
that have already been completed. 3. A journal of manifest
operations is stored in nonvolatile memory. The journal enables the
parser to re-create the state just prior to the disruption. This
journal can, for example, be a SUIT Report or a journaling file
system.
AND
1. Where a command is not repeatable because of the way in which it
alters system state (e.g. swapping images or in-place delta) it
MUST be resumable or revertible. This applies to commands that
modify at least one source component as well as the destination