-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathdraft-ietf-suit-update-management.xml
1221 lines (998 loc) · 59.4 KB
/
draft-ietf-suit-update-management.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.6.31 (Ruby 3.2.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-update-management-05" category="std" consensus="true" tocInclude="true" sortRefs="true" symRefs="true">
<front>
<title abbrev="SUIT Update Management Extensions">Update Management Extensions for Software Updates for Internet of Things (SUIT) Manifests</title>
<author initials="B." surname="Moran" fullname="Brendan Moran">
<organization>Arm Limited</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="March" day="04"/>
<area>Security</area>
<workgroup>SUIT</workgroup>
<keyword>Internet-Draft</keyword>
<abstract>
<t>This specification describes extensions to the SUIT manifest format
defined in <xref target="I-D.ietf-suit-manifest"/>. These extensions allow an update
author, update distributor or device operator to more precisely control
the distribution and installation of updates to devices. These
extensions also provide a mechanism to inform a management system of
Software Identifier and Software Bill Of Materials information about an
updated device.</t>
</abstract>
</front>
<middle>
<section anchor="introduction"><name>Introduction</name>
<t>Full management of software updates for unattended, connected devices requires a cooperation between the update author(s) and management, distribution, policy enforcement, and auditing systems. This specification provides the extensions to the SUIT manifest (<xref target="I-D.ietf-suit-manifest"/>) that enable an author to coordinate with these other systems. These extensions enable authors to instruct devices to examine update priority, local update authorisation, update lifetime, and system properties. They also enable devices to report and distributors to collect Software Bill of Materials information.</t>
<t>Extensions in this specification are OPTIONAL to implement and OPTIONAL to include in manifests unless otherwise designated.</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>Additionally, the following terminology is used throughout this document:</t>
<t><list style="symbols">
<t>SUIT: Software Update for the Internet of Things, also the IETF working group for this proposed standard. While this software update mechanism is designed with the limitations and requirements of IoT devices in mind, there is no restriction preventing its use outside of IoT devices or for non-software payloads.</t>
</list></t>
</section>
<section anchor="extension-metadata"><name>Extension Metadata</name>
<t>Some additional metadata makes management of SUIT updates easier:</t>
<t><list style="symbols">
<t>A semantic version number for the update represented by the manifest</t>
<t>Concise Software Identifiers (CoSWID), Concise Module Identifiers (CoMID), Concise Reference Integrity Manifest (CoRIM)</t>
<t>Text descriptions of requirements</t>
<t>Text description of the current versions of components</t>
</list></t>
<section anchor="suit-set-version"><name>suit-set-version</name>
<t>This metadata encodes a semantic version for the component set that the manifest updates, including any dependencies. This enables version comparisons to be performed on manifests. Non-manifest images encode their versions independently of the manifest.</t>
<t>The version SHOULD be encoded as a semantic version, according to <xref target="semver"/>. There are several restrictions to these composition rules: alphanumeric pre-release indicators are not permitted. Because suit-set-version is a machine-readable parameter for determining compatibility and because <xref target="semver"/> mandates that the build-number is ignored, build numbers SHOULD NOT be included.</t>
<t>The composition of suit-set-version is the same as <xref target="suit-parameter-version"/>.</t>
<t>If a build number is desired, it SHOULD be included via <xref target="text-current-version"/>.</t>
</section>
<section anchor="manifest-digest-coswid"><name>suit-coswid</name>
<t>A CoSWID can enable Software Bill-of-Materials use-cases. A CoMID can enable monitoring of expected hardware. A CoRIM (which may contain both CoSWID and CoMID) can enable both of these use-cases, but can also act as the transport for expected values to an attestation Verifier (see <xref target="RFC9334"/>). Tightly coupling update and attestation ensures that verification infrastructure always knows what software to expect on each device.</t>
<t>suit-coswid is a member of the suit-manifest. It contains a Concise Software Identifier (CoSWID) as defined in <xref target="I-D.ietf-sacm-coswid"/>. This element SHOULD be made severable so that it can be discarded by the Recipient or an intermediary if it is not required by the Recipient.</t>
<t>suit-coswid typically requires no processing by the Recipient. However all Recipients MUST NOT fail if a suit-coswid is present.</t>
<t>suit-coswid is RECOMMENDED to implement and RECOMMENDED to include in manifests.</t>
<t>RFC EDITOR NOTE: Remove following 2 notes.</t>
<t><list style="symbols">
<t>NOTE: CoRIM comprises a list of CoSWIDs and a list of CoMIDs, so it may be preferable to a CoSWID.</t>
<t>NOTE: CoMID may be a preferable alternative to Vendor ID/Class ID, however it consumes more bandwidth, so a UUID based on CoMID may be appropriate.</t>
</list></t>
</section>
<section anchor="text-version-required"><name>text-version-required</name>
<t>suit-text-version-required is used to represent a version-based dependency on suit-parameter-version as described in <xref target="suit-parameter-version"/> and <xref target="suit-condition-version"/>. To describe a version dependency, a Manifest Author SHOULD populate the suit-text map with a SUIT_Component_Identifier key for the dependency component, and place in the corresponding map a suit-text-version-required key with a free text expression that is representative of the version constraints placed on the dependency. This text SHOULD be expressive enough that a device operator can be expected to understand the dependency. This is a free text field and there are no specific formatting rules.</t>
<t>By way of example only, to express a dependency on a component "['x', 'y']", where the version should be any v1.x later than v1.2.5, but not v2.0 or above, the author would add the following structure to the suit-text element. Note that this text is in cbor-diag notation.</t>
<figure><artwork><![CDATA[
[h'78',h'79'] : {
7 : ">=1.2.5,<2"
}
]]></artwork></figure>
</section>
<section anchor="text-current-version"><name>text-current-version</name>
<t>suit-text-current-version is used to provide human-readable version information equivalent to <xref target="suit-set-version"/>. This metadata MAY have a version listed for each or any component. The Manifest Processor MUST NOT consume this version; it is for human readability only.</t>
<t>To describe a version, a Manifest Author SHOULD populate the suit-text map with a SUIT_Component_Identifier key for the dependency component, and place in the corresponding map a suit-text-current-version key with a free text version that is representative of the version of the component. This text SHOULD be expressive enough that a device operator can be expected to understand the version. This is a free text field and there are no specific formatting rules.</t>
<t>It is RECOMMENDED that the Manifest Author use a Semantic Version (<xref target="semver"/>) in the free-text field. Unlike <xref target="suit-set-version"/>, the full semantic version specification can be used.</t>
</section>
</section>
<section anchor="extension-parameters"><name>Extension Parameters</name>
<t>Several parameters are needed to define the behaviour of the commands specified in <xref target="extension-commands"/>. These parameters follow the same considerations as defined in Section 8.4.8 of <xref target="I-D.ietf-suit-manifest"/>.</t>
<texttable>
<ttcol align='left'>Name</ttcol>
<ttcol align='left'>CDDL Structure</ttcol>
<ttcol align='left'>Reference</ttcol>
<c>Use Before</c>
<c>suit-parameter-use-before</c>
<c><xref target="suit-parameter-use-before"/></c>
<c>Minimum Battery</c>
<c>suit-parameter-minimum-battery</c>
<c><xref target="suit-parameter-minimum-battery"/></c>
<c>Update Priority</c>
<c>suit-parameter-update-priority</c>
<c><xref target="suit-parameter-update-priority"/></c>
<c>Version</c>
<c>suit-parameter-version</c>
<c><xref target="suit-parameter-version"/></c>
<c>Wait Info</c>
<c>suit-parameter-wait-info</c>
<c><xref target="suit-parameter-wait-info"/></c>
<c>Component Metadata</c>
<c>suit-parameter-component-metadata</c>
<c><xref target="suit-parameter-component-metadata"/></c>
</texttable>
<section anchor="suit-parameter-use-before"><name>suit-parameter-use-before</name>
<t>An expiry date for the use of the manifest encoded as the positive integer number of seconds since 1970-01-01. Implementations that use this parameter MUST use a 64-bit internal representation of the integer. Used with <xref target="suit-condition-use-before"/>.</t>
</section>
<section anchor="suit-parameter-minimum-battery"><name>suit-parameter-minimum-battery</name>
<t>This parameter sets the minimum battery level in mWh. This parameter is encoded as a positive integer. Used with suit-condition-minimum-battery (<xref target="suit-condition-minimum-battery"/>).</t>
</section>
<section anchor="suit-parameter-update-priority"><name>suit-parameter-update-priority</name>
<t>This parameter sets the priority of the update. This parameter is encoded as an integer. It is used along with suit-condition-update-authorized (<xref target="suit-condition-update-authorized"/>) to ask an application for permission to initiate an update. This does not constitute a privilege inversion because an explicit request for authorization has been provided by the Update Authority in the form of the suit-condition-update-authorized command.</t>
<t>Applications MAY define their own meanings for the update priority. For example, critical reliability and vulnerability fixes might be given negative numbers, while bug fixes might be given small positive numbers, and feature additions might be given larger positive numbers, which allows an application to make an informed decision about whether and when to allow an update to proceed.</t>
</section>
<section anchor="suit-parameter-version"><name>suit-parameter-version</name>
<t>Indicates allowable versions for the specified component. One version comparison can be made with each suit-parameter-version. This parameter is compared with version asserted by the current component when suit-condition-version (<xref target="suit-condition-version"/>) is invoked. The current component may assert the current version in many ways, including storage in a parameter storage database, in a metadata object, or in a known location within the component itself.</t>
<t>Each suit-parameter-version contains a comparison operator and a version, according to the following CDDL:</t>
<figure><sourcecode type="CDDL"><![CDATA[
SUIT_Parameter_Version_Match = [
suit-condition-version-comparison-type:
SUIT_Condition_Version_Comparison_Types,
suit-condition-version-comparison-value:
SUIT_Condition_Version_Comparison_Value
]
]]></sourcecode></figure>
<t>The comparison type can be:</t>
<t><list style="symbols">
<t>Greater.</t>
<t>Greater or Equal.</t>
<t>Equal.</t>
<t>Lesser or Equal.</t>
<t>Lesser.</t>
</list></t>
<t>The version comparison value is encoded as a CBOR list of integers. Comparisons are done on each integer in sequence. Comparison stops after all integers in the list defined by the manifest have been consumed OR after an non-equal comparison has occurred. For example, if the manifest defines a comparison, "Equal [1]", then this will match all version sequences starting with 1. If a manifest defines both "Greater or Equal [1,0]" and "Lesser [1,10]", then it will match versions 1.0.x up to, but not including 1.10.</t>
<t>suit-parameter-version is OPTIONAL to implement.</t>
<section anchor="suit-parameter-version-semantic-versioning-encoding-guidelines"><name>suit-parameter-version Semantic Versioning encoding guidelines</name>
<t>The encoded versions SHOULD be semantic versions (See <xref target="semver"/>). For example,</t>
<t><list style="symbols">
<t>1.2.3 = [1,2,3].</t>
<t>1.2-rc.3 = [1,2,-1,3].</t>
<t>1.2-beta = [1,2,-2].</t>
<t>1.2-alpha = [1,2,-3].</t>
<t>1.2.3-alpha.4 = [1,2,3,-3,4].</t>
</list></t>
<t>Versions SHOULD be composed of:</t>
<t><list style="numbers">
<t>A release version encoded as a sequence of 1 to 3 positive integers</t>
<t>A pre-release indicator encoded as a negative integer, followed by a sequence of positive integers</t>
</list></t>
<t>While <xref target="semver"/> allows a build number, it mandates that the build number is ignored. Because suit-parameter-version exists solely to enable the Manifest Processor to make a decision about version compatibility, build numbers SHOULD NOT be included.</t>
<t>In <xref target="semver"/>,</t>
<t><list style="numbers">
<t>The first integer represents the major number. This indicates breaking changes to the component.</t>
<t>The second integer represents the minor number. This is typically reserved for new features or large, non-breaking changes.</t>
<t>The third integer is the patch version. This is typically reserved for bug fixes.</t>
</list></t>
<t>The pre-release indicator SHOULD NOT appear as element 0. The pre-release indicator is encoded as:</t>
<t><list style="symbols">
<t>-1: Release Candidate</t>
<t>-2: Beta</t>
<t>-3: Alpha</t>
</list></t>
<t>This allows these releases to compare correctly with final releases. For example, Version 2.0, RC1 should be lower than Version 2.0.0 and higher than any Version 1.x. By encoding RC as -1, this works correctly: [2,0,-1,1] compares as lower than [2,0,0]. Similarly, beta (-2) is lower than RC and alpha (-3) is lower than RC.</t>
</section>
</section>
<section anchor="suit-parameter-wait-info"><name>suit-parameter-wait-info</name>
<t>suit-directive-wait (<xref target="suit-directive-wait"/>) directs the manifest processor to pause until a specified event occurs. The suit-parameter-wait-info encodes the parameters needed for the directive.</t>
<t>The exact implementation of the pause is implementation-defined. For example, this could be done by blocking on a semaphore, registering an event handler and suspending the manifest processor, polling for a notification, or aborting the update entirely, then restarting when a notification is received.</t>
<t>suit-parameter-wait-info is encoded as a map of wait events. When ALL wait events are satisfied, the Manifest Processor continues. The wait events currently defined are described in the following table.</t>
<texttable>
<ttcol align='left'>Name</ttcol>
<ttcol align='left'>Encoding</ttcol>
<ttcol align='left'>Description</ttcol>
<c>suit-wait-event-authorization</c>
<c>int</c>
<c>Same as suit-parameter-update-priority</c>
<c>suit-wait-event-power</c>
<c>int</c>
<c>Wait until power state</c>
<c>suit-wait-event-network</c>
<c>int</c>
<c>Wait until network state</c>
<c>suit-wait-event-other-device-version</c>
<c>See below</c>
<c>Wait for other device to match version</c>
<c>suit-wait-event-time</c>
<c>uint</c>
<c>Wait until time (seconds since 1970-01-01)</c>
<c>suit-wait-event-time-of-day</c>
<c>uint</c>
<c>Wait until seconds since 00:00:00 Local Time</c>
<c>suit-wait-event-time-of-day-utc</c>
<c>uint</c>
<c>Wait until seconds since 00:00:00 UTC</c>
<c>suit-wait-event-day-of-week</c>
<c>uint</c>
<c>Wait until days since Sunday Local Time</c>
<c>suit-wait-event-day-of-week-utc</c>
<c>uint</c>
<c>Wait until days since Sunday UTC</c>
</texttable>
<t>suit-wait-event-other-device-version reuses the encoding of suit-parameter-version-match. It is encoded as a sequence that contains an implementation-defined bstr identifier for the other device, and a list of one or more SUIT_Parameter_Version_Match.</t>
</section>
<section anchor="suit-parameter-component-metadata"><name>suit-parameter-component-metadata</name>
<t>In some instances, a system may need to know the file metadata for a component. This metadata can include:</t>
<t><list style="symbols">
<t>creator</t>
<t>creation time</t>
<t>modification time</t>
<t>default permissions (rwx)</t>
<t>a map of user/permission pairs</t>
<t>a map of role/permission pairs</t>
<t>a map of group/permission pairs</t>
<t>file type</t>
</list></t>
<t>Component metadata is applied at time of fetch, copy, or write; see <xref target="I-D.ietf-suit-manifest"/>, sections 8.4.10.4, 8.4.10.5, 8.4.10.6. Therefore, the component metadata parameter must be set in advance of the component being fetched, copied into, or written.</t>
<section anchor="suit-meta-creator"><name>Creator</name>
<t>Sometimes, management of file systems requires that the creator of each file is correctly recorded. Because the default creator of files will be the update agent, this can obscure the actual creator of each file. The Creator metadata element allows overriding the default behaviour and setting the correct creator.</t>
<t>The creator is defined as follows:</t>
<figure><sourcecode type="CDDL"><![CDATA[
SUIT_meta_actor_id = UUID_Tagged / bstr / str / int
UUID_Tagged = #6.37(bstr)
]]></sourcecode></figure>
<t>The actor ID can be whatever is most appropriate for any given system. For example, the actor ID might be a string (e.g., username), integer (e.g., POSIX userid), or UUID (e.g., TEEP TA UUID).</t>
</section>
<section anchor="creation-modification-time"><name>Creation & Modification Time</name>
<t>The creation and modification times are defined by CBOR time types. These are defined in <xref target="RFC8949"/>, Section 3.4.2. The CBOR tag is REQUIRED when either creation or modification time are provided.</t>
<figure><sourcecode type="CDDL"><![CDATA[
suit-meta-modification-time => #6.1(uint)
suit-meta-creation-time => #6.1(uint)
]]></sourcecode></figure>
</section>
<section anchor="component-default-permissions"><name>Component Default Permissions</name>
<t>Typical permissions management systems require read, write, and execute permissions that are applied to all users who do not have their own explicit permissions. These are the default permissions for the current component. Default permissions are described by the following CDDL:</t>
<figure><sourcecode type="CDDL"><![CDATA[
SUIT_meta_permissions = uint .bits SUIT_meta_permission_bits
SUIT_meta_permission_bits = &(
r: 2, w: 1, x: 0,
* $$SUIT_meta_permission_bits_extensions
)
]]></sourcecode></figure>
</section>
<section anchor="user-role-group-permissions"><name>User, Role, Group permissions</name>
<t>Many filesystems have users and groups. Additionally some have roles. Actors that have these associations can have specific permissions associated with them for each component. Each of these sets of permissions is defined the same way: with a map of actor identifiers to permissions.</t>
<figure><sourcecode type="CDDL"><![CDATA[
SUIT_meta_permission_map = {
+ SUIT_meta_actor_id => SUIT_meta_permissions
}
]]></sourcecode></figure>
<t>The SUIT_meta_actor_id is the same as defined for Creator, <xref target="suit-meta-creator"/>.</t>
</section>
<section anchor="file-type"><name>File Type</name>
<t>File Type typically identifies whether a file is a directory, regular file, or symbolic link. If not specified, File Type defaults to regular file.</t>
<t>This enables specific management operations for SUIT command sequences:</t>
<t><list style="symbols">
<t>To create a directory <list style="symbols">
<t>Set the Component Index to the Component Identifier of the directory to be created</t>
<t>Set the Component metadata, including the file type for directory</t>
<t>Set suit-parameter-content to an empty bstr</t>
<t>Invoke suit-directive-write</t>
</list></t>
<t>To create a symbolic link <list style="symbols">
<t>Set the Component Index to the Component Identifier of the link to be created</t>
<t>Set the Component metadata, including the file type for symbolic link</t>
<t>Set suit-parameter-content to the link target</t>
<t>Invoke suit-directive-write</t>
</list></t>
</list></t>
<t>For example, the following Payload Fetch & Install sequences will create a new /usr/local/bin directory, download https://cdn.example/example3.bin into a new file: /usr/local/bin/example3, then create a symlink at /usr/bin/example that points to /usr/local/bin/example3.</t>
<t><list style="symbols">
<t>Common has components for: <list style="symbols">
<t>/usr/bin/example</t>
<t>/usr/local/bin</t>
<t>/usr/local/bin/example3</t>
</list></t>
<t>Payload fetch: <list style="symbols">
<t>set component index = 1</t>
<t>set parameters: <list style="symbols">
<t>content = h''</t>
<t>metadata = {file-type: directory}</t>
</list></t>
<t>write</t>
<t>set component index = 2</t>
<t>set URI = "https://cdn.example/example3.bin"</t>
<t>fetch</t>
<t>condition image digest</t>
</list></t>
<t>Install: <list style="symbols">
<t>set component index = 0</t>
<t>set parameters: <list style="symbols">
<t>content = "/usr/local/bin/example3"</t>
<t>metadata = {file-type: symlink}</t>
</list></t>
<t>write</t>
</list></t>
</list></t>
</section>
</section>
</section>
<section anchor="extension-commands"><name>Extension Commands</name>
<t>The following table defines the semantics of the commands defined in this specification in the same way as in the Abstract Machine Description, Section 6.4, of <xref target="I-D.ietf-suit-manifest"/>.</t>
<texttable>
<ttcol align='left'>Command Name</ttcol>
<ttcol align='left'>CDDL Identifier</ttcol>
<ttcol align='left'>Semantic of the Operation</ttcol>
<c>Use Before</c>
<c>suit-condition-use-before</c>
<c>assert(now() < current.params[use-before])</c>
<c>Check Image Not Match</c>
<c>suit-condition-image-not-match</c>
<c>assert(not binary-match(digest(current), current.params[digest]))</c>
<c>Check Minimum Battery</c>
<c>suit-condition-minimum-battery</c>
<c>assert(battery >= current.params[minimum-battery])</c>
<c>Check Update Authorized</c>
<c>suit-condition-update-authorized</c>
<c>assert( isAuthorized( current.params[priority]))</c>
<c>Check Version</c>
<c>suit-condition-version</c>
<c>assert(version_check(current, current.params[version]))</c>
<c>Wait For Event</c>
<c>suit-directive-wait</c>
<c>until event(arg), wait</c>
<c>Override Multiple</c>
<c>suit-directive-override-multiple</c>
<c>components[i].params[k] := v for-each k,v in d for-each i,d in arg</c>
<c>Copy Params</c>
<c>suit-directive-copy-params</c>
<c>current.params[k] = components[i].params[k] for k in l for i,l in arg</c>
</texttable>
<section anchor="suit-condition-use-before"><name>suit-condition-use-before</name>
<t>Verify that the current time is BEFORE the specified time. suit-condition-use-before is used to specify the last time at which an update should be installed. The recipient evaluates the current time against the suit-parameter-use-before parameter (<xref target="suit-parameter-use-before"/>), which must have already been set as a parameter, encoded as seconds after 1970-01-01 00:00:00 UTC. Timestamp conditions MUST be evaluated in 64 bits, regardless of encoded CBOR size. suit-condition-use-before is OPTIONAL to implement.</t>
</section>
<section anchor="suit-condition-image-not-match"><name>suit-condition-image-not-match</name>
<t>Verify that the current component does not match the suit-parameter-image-digest (Section 8.4.8.6 of <xref target="I-D.ietf-suit-manifest"/>). If no digest is specified, the condition fails. suit-condition-image-not-match is OPTIONAL to implement.</t>
</section>
<section anchor="suit-condition-minimum-battery"><name>suit-condition-minimum-battery</name>
<t>suit-condition-minimum-battery provides a mechanism to test a Recipient's battery level before installing an update. This condition is primarily for use in primary-cell applications, where the battery is only ever discharged. For batteries that are charged, suit-directive-wait is more appropriate, since it defines a "wait" until the battery level is sufficient to install the update. suit-condition-minimum-battery is specified in mWh. suit-condition-minimum-battery is OPTIONAL to implement. suit-condition-minimum-battery consumes suit-parameter-minimum-battery (<xref target="suit-parameter-minimum-battery"/>).</t>
</section>
<section anchor="suit-condition-update-authorized"><name>suit-condition-update-authorized</name>
<t>Request authorization from the application and fail if not authorized. This can allow a user to decline an update. suit-parameter-update-priority (<xref target="suit-parameter-update-priority"/>) provides an integer priority level that the application can use to determine whether or not to authorize the update. Priorities are application defined. suit-condition-update-authorized is OPTIONAL to implement.</t>
</section>
<section anchor="suit-condition-version"><name>suit-condition-version</name>
<t>suit-condition-version allows comparing versions of firmware. Verifying image digests is preferred to version checks because digests are more precise. suit-condition-version examines a component's version against the version info specified in suit-parameter-version (<xref target="suit-parameter-version"/>).</t>
</section>
<section anchor="suit-directive-wait"><name>suit-directive-wait</name>
<t>suit-directive-wait directs the manifest processor to pause until a specified event occurs. Some possible events include:</t>
<t><list style="numbers">
<t>Authorization</t>
<t>External power</t>
<t>Network availability</t>
<t>Other device firmware version</t>
<t>Time</t>
<t>Time of day</t>
<t>Day of week</t>
</list></t>
</section>
<section anchor="suit-directive-override-multiple"><name>suit-directive-override-multiple</name>
<t>This directive enables setting parameters for multiple components at the same time. This allows a small reduction in encoding overhead:</t>
<t><list style="symbols">
<t>without override-multiple, the encoding for each component consists of: <list style="symbols">
<t>set-component-index (2 bytes)</t>
<t>override-parameters (1 byte + parameter map)</t>
</list></t>
<t>with override-multiple, the encoding for each component consists of: <list style="symbols">
<t>the component index key (1 byte)</t>
<t>the parameter map</t>
</list></t>
</list></t>
<t>Override-multiple requires the command (1-2 bytes) and one additional map to hold the parameter sets (1 byte). For one component, there is no savings. For multiple components, there is an encoding savings of 2 bytes per component.</t>
<t>Proper structuring of code should ensure that override-multiple follows a code-path nearly identical to set-component-index + override-parameters.</t>
<t>This command is purely an encoding alias for set-component-index and override-parameters. The component index is set to the last component listed in the override-multiple argument when override-multiple completes.</t>
<t>The following CDDL defines the argument for suit-directive-override-multiple:</t>
<t><spanx style="verb">CDDL
SUIT_Override_Mult_Arg = {
uint => {+ $$SUIT_Parameters}
}
</spanx></t>
</section>
<section anchor="suit-directive-copy-params"><name>suit-directive-copy-params</name>
<t>suit-directive-copy-params enables a manifest author to specify one or more components to copy parameters from, and a list of parameters to copy from each specified source component.</t>
<t>The behaviour is exactly the same as override parameters, but with parameter values defined in existing components. Parameters are only copied between identical keys (no copying from URI to digest, for example).</t>
<t>For each entry in the map, the manifest processor sets the source component to be the component identified by the index contained in the map key. For each parameter identified in the copy list, the manifest processor copies the parameter from the source component to the current component.</t>
<t>The following CDDL defines the argument for suit-directive-copy-params:</t>
<t><spanx style="verb">CDDL
SUIT_Directive_Copy_Params = {
uint => [+ int]
}
</spanx></t>
</section>
</section>
<section anchor="iana"><name>IANA Considerations</name>
<t>IANA is requested to:</t>
<t><list style="symbols">
<t>allocate key 14 in the SUIT Envelope registry for suit-coswid</t>
<t>allocate key 14 in the SUIT Manifest registry for suit-coswid</t>
<t>allocate key 7 in the SUIT Component Text registry for suit-text-version-required</t>
<t>allocate the commands and parameters as shown in the following tables</t>
</list></t>
<section anchor="suit-commands"><name>SUIT Commands</name>
<texttable>
<ttcol align='left'>Label</ttcol>
<ttcol align='left'>Name</ttcol>
<ttcol align='left'>Reference</ttcol>
<c>4</c>
<c>Use Before</c>
<c><xref target="suit-condition-use-before"/></c>
<c>25</c>
<c>Image Not Match</c>
<c><xref target="suit-condition-image-not-match"/></c>
<c>26</c>
<c>Minimum Battery</c>
<c><xref target="suit-condition-minimum-battery"/></c>
<c>27</c>
<c>Update Authorized</c>
<c><xref target="suit-condition-update-authorized"/></c>
<c>28</c>
<c>Version</c>
<c><xref target="suit-condition-version"/></c>
<c>29</c>
<c>Wait For Event</c>
<c><xref target="suit-directive-wait"/></c>
<c>34</c>
<c>Override Multiple</c>
<c><xref target="suit-directive-override-multiple"/></c>
<c>35</c>
<c>Copy Params</c>
<c><xref target="suit-directive-copy-params"/></c>
</texttable>
</section>
<section anchor="suit-parameters"><name>SUIT Parameters</name>
<texttable>
<ttcol align='left'>Label</ttcol>
<ttcol align='left'>Name</ttcol>
<ttcol align='left'>Reference</ttcol>
<c>4</c>
<c>Use Before</c>
<c><xref target="suit-parameter-use-before"/></c>
<c>26</c>
<c>Minimum Battery</c>
<c><xref target="suit-parameter-minimum-battery"/></c>
<c>27</c>
<c>Update Priority</c>
<c><xref target="suit-parameter-update-priority"/></c>
<c>28</c>
<c>Version</c>
<c><xref target="suit-parameter-version"/></c>
<c>29</c>
<c>Wait Info</c>
<c><xref target="suit-parameter-wait-info"/></c>
</texttable>
</section>
</section>
<section anchor="security-considerations"><name>Security Considerations</name>
<t>This document extends the SUIT manifest specification. A detailed security treatment can be found in the architecture <xref target="RFC9019"/> and in the information model <xref target="I-D.ietf-suit-information-model"/> documents.</t>
</section>
</middle>
<back>
<references title='Normative References'>
<reference anchor='I-D.ietf-sacm-coswid'>
<front>
<title>Concise Software Identification Tags</title>
<author fullname='Henk Birkholz' initials='H.' surname='Birkholz'>
<organization>Fraunhofer SIT</organization>
</author>
<author fullname='Jessica Fitzgerald-McKay' initials='J.' surname='Fitzgerald-McKay'>
<organization>National Security Agency</organization>
</author>
<author fullname='Charles Schmidt' initials='C.' surname='Schmidt'>
<organization>The MITRE Corporation</organization>
</author>
<author fullname='David Waltermire' initials='D.' surname='Waltermire'>
<organization>National Institute of Standards and Technology</organization>
</author>
<date day='24' month='February' year='2023'/>
<abstract>
<t>ISO/IEC 19770-2:2015 Software Identification (SWID) tags provide an extensible XML-based structure to identify and describe individual software components, patches, and installation bundles. SWID tag representations can be too large for devices with network and storage constraints. This document defines a concise representation of SWID tags: Concise SWID (CoSWID) tags. CoSWID supports a set of semantics and features that are similar to those for SWID tags, as well as new semantics that allow CoSWIDs to describe additional types of information, all in a more memory-efficient format.
</t>
</abstract>
</front>
<seriesInfo name='Internet-Draft' value='draft-ietf-sacm-coswid-24'/>
</reference>
<reference anchor='I-D.ietf-suit-manifest'>
<front>
<title>A Concise Binary Object Representation (CBOR)-based Serialization Format for the Software Updates for Internet of Things (SUIT) Manifest</title>
<author fullname='Brendan Moran' initials='B.' surname='Moran'>
<organization>Arm Limited</organization>
</author>
<author fullname='Hannes Tschofenig' initials='H.' surname='Tschofenig'>
</author>
<author fullname='Henk Birkholz' initials='H.' surname='Birkholz'>
<organization>Fraunhofer SIT</organization>
</author>
<author fullname='Koen Zandberg' initials='K.' surname='Zandberg'>
<organization>Inria</organization>
</author>
<author fullname='Øyvind Rønningstad' initials='O.' surname='Rønningstad'>
<organization>Nordic Semiconductor</organization>
</author>
<date day='5' month='February' year='2024'/>
<abstract>
<t> 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.
</t>
</abstract>
</front>
<seriesInfo name='Internet-Draft' value='draft-ietf-suit-manifest-25'/>
</reference>
<reference anchor='RFC9019'>
<front>
<title>A Firmware Update Architecture for Internet of Things</title>
<author fullname='B. Moran' initials='B.' surname='Moran'/>
<author fullname='H. Tschofenig' initials='H.' surname='Tschofenig'/>
<author fullname='D. Brown' initials='D.' surname='Brown'/>
<author fullname='M. Meriac' initials='M.' surname='Meriac'/>
<date month='April' year='2021'/>
<abstract>
<t>Vulnerabilities in Internet of Things (IoT) devices have raised the need for a reliable and secure firmware update mechanism suitable for devices with resource constraints. Incorporating such an update mechanism is a fundamental requirement for fixing vulnerabilities, but it also enables other important capabilities such as updating configuration settings and adding new functionality.</t>
<t>In addition to the definition of terminology and an architecture, this document provides the motivation for the standardization of a manifest format as a transport-agnostic means for describing and protecting firmware updates.</t>
</abstract>
</front>
<seriesInfo name='RFC' value='9019'/>
<seriesInfo name='DOI' value='10.17487/RFC9019'/>
</reference>
<reference anchor='RFC8949'>
<front>
<title>Concise Binary Object Representation (CBOR)</title>
<author fullname='C. Bormann' initials='C.' surname='Bormann'/>
<author fullname='P. Hoffman' initials='P.' surname='Hoffman'/>
<date month='December' year='2020'/>
<abstract>
<t>The Concise Binary Object Representation (CBOR) is a data format whose design goals include the possibility of extremely small code size, fairly small message size, and extensibility without the need for version negotiation. These design goals make it different from earlier binary serializations such as ASN.1 and MessagePack.</t>
<t>This document obsoletes RFC 7049, providing editorial improvements, new details, and errata fixes while keeping full compatibility with the interchange format of RFC 7049. It does not create a new version of the format.</t>
</abstract>
</front>
<seriesInfo name='STD' value='94'/>
<seriesInfo name='RFC' value='8949'/>
<seriesInfo name='DOI' value='10.17487/RFC8949'/>
</reference>
<reference anchor='RFC9334'>
<front>
<title>Remote ATtestation procedureS (RATS) Architecture</title>
<author fullname='H. Birkholz' initials='H.' surname='Birkholz'/>
<author fullname='D. Thaler' initials='D.' surname='Thaler'/>
<author fullname='M. Richardson' initials='M.' surname='Richardson'/>
<author fullname='N. Smith' initials='N.' surname='Smith'/>
<author fullname='W. Pan' initials='W.' surname='Pan'/>
<date month='January' year='2023'/>
<abstract>
<t>In network protocol exchanges, it is often useful for one end of a communication to know whether the other end is in an intended operating state. This document provides an architectural overview of the entities involved that make such tests possible through the process of generating, conveying, and evaluating evidentiary Claims. It provides a model that is neutral toward processor architectures, the content of Claims, and protocols.</t>
</abstract>
</front>
<seriesInfo name='RFC' value='9334'/>
<seriesInfo name='DOI' value='10.17487/RFC9334'/>
</reference>
<reference anchor="semver" target="https://semver.org">
<front>
<title>Semantic Versioning 2.0.0</title>
<author >
<organization></organization>
</author>
<date year="2013" month="June" day="18"/>
</front>
</reference>
<reference anchor='RFC2119'>
<front>
<title>Key words for use in RFCs to Indicate Requirement Levels</title>
<author fullname='S. Bradner' initials='S.' surname='Bradner'/>
<date month='March' year='1997'/>
<abstract>
<t>In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.</t>
</abstract>
</front>
<seriesInfo name='BCP' value='14'/>
<seriesInfo name='RFC' value='2119'/>
<seriesInfo name='DOI' value='10.17487/RFC2119'/>
</reference>
<reference anchor='RFC8174'>
<front>
<title>Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words</title>
<author fullname='B. Leiba' initials='B.' surname='Leiba'/>
<date month='May' year='2017'/>
<abstract>
<t>RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings.</t>
</abstract>
</front>
<seriesInfo name='BCP' value='14'/>
<seriesInfo name='RFC' value='8174'/>
<seriesInfo name='DOI' value='10.17487/RFC8174'/>
</reference>
</references>
<references title='Informative References'>
<reference anchor='I-D.ietf-suit-information-model'>
<front>
<title>A Manifest Information Model for Firmware Updates in Internet of Things (IoT) Devices</title>
<author fullname='Brendan Moran' initials='B.' surname='Moran'>
<organization>Arm Limited</organization>
</author>
<author fullname='Hannes Tschofenig' initials='H.' surname='Tschofenig'>
<organization>Arm Limited</organization>
</author>
<author fullname='Henk Birkholz' initials='H.' surname='Birkholz'>
<organization>Fraunhofer SIT</organization>
</author>
<date day='8' month='July' year='2021'/>
<abstract>
<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. Ensuring that devices function and remain secure over their service lifetime requires such an update mechanism to fix vulnerabilities, update configuration settings, and add new functionality.
One component of such a firmware update is a concise and machine-processable metadata document, or manifest, that describes the firmware image(s) and offers appropriate protection. This document describes the information that must be present in the manifest.
</t>
</abstract>
</front>
<seriesInfo name='Internet-Draft' value='draft-ietf-suit-information-model-13'/>
</reference>
</references>
<section anchor="full-cddl"><name>Full CDDL</name>
<t>To be valid, the following CDDL MUST be appended to the SUIT Manifest CDDL. The SUIT CDDL is defined in Appendix A of <xref target="I-D.ietf-suit-manifest"/>.</t>
<figure><sourcecode type="CDDL"><![CDATA[
$$unseverable-manifest-member-extensions //= (
suit-current-version => \
bstr .cbor SUIT_Condition_Version_Comparison_Value
)
$$SUIT_severable-members-extensions //= (
suit-coswid => bstr)
; suit-coswid => bstr .cbor concise-swid-tag)
$$severable-manifest-members-choice-extensions //= (
suit-coswid => bstr .cbor SUIT_Command_Sequence / SUIT_Digest
)
SUIT_Condition //= (
suit-condition-image-not-match, SUIT_Rep_Policy)
SUIT_Condition //= (
suit-condition-use-before, SUIT_Rep_Policy)
SUIT_Condition //= (
suit-condition-minimum-battery, SUIT_Rep_Policy)
SUIT_Condition //= (
suit-condition-update-authorized, SUIT_Rep_Policy)
SUIT_Condition //= (
suit-condition-version, SUIT_Rep_Policy)
SUIT_Directive //= (
suit-directive-wait, SUIT_Rep_Policy)
SUIT_Directive //= (
suit-directive-override-multiple, SUIT_Override_Mult_Arg)
SUIT_Directive //=(
suit-directive-copy-params, SUIT_Directive_Copy_Params)
SUIT_Override_Mult_Arg = {
+ uint => {+ $$SUIT_Parameters}
}
SUIT_Directive_Copy_Params = {
+ uint => [+ int]
}
SUIT_Wait_Event = { + SUIT_Wait_Events }
SUIT_Wait_Events //= (suit-wait-event-authorization => int)
SUIT_Wait_Events //= (suit-wait-event-power => int)
SUIT_Wait_Events //= (suit-wait-event-network => int)
SUIT_Wait_Events //= (suit-wait-event-other-device-version
=> SUIT_Wait_Event_Argument_Other_Device_Version)
SUIT_Wait_Events //= (suit-wait-event-time => uint); Timestamp
SUIT_Wait_Events //= (suit-wait-event-time-of-day
=> uint); Time of Day (seconds since 00:00:00)
SUIT_Wait_Events //= (suit-wait-event-day-of-week
=> uint); Days since Sunday
SUIT_Wait_Event_Argument_Other_Device_Version = [
other-device: bstr,
other-device-version: [ + SUIT_Parameter_Version_Match ]
]
SUIT_Parameters //= (suit-parameter-use-before => uint)
SUIT_Parameters //= (suit-parameter-minimum-battery => uint)
SUIT_Parameters //= (suit-parameter-update-priority => int)
SUIT_Parameters //= (suit-parameter-version =>
bstr .cbor SUIT_Parameter_Version_Match)
SUIT_Parameters //= (suit-parameter-wait-info =>
bstr .cbor SUIT_Wait_Event)
SUIT_Parameters //= (suit-parameter-component-metadata =>
bstr .cbor SUIT_Component_Metadata)
SUIT_Parameter_Version_Match = [
suit-condition-version-comparison-type:
SUIT_Condition_Version_Comparison_Types,
suit-condition-version-comparison-value:
SUIT_Condition_Version_Comparison_Value
]
SUIT_Condition_Version_Comparison_Types /=
suit-condition-version-comparison-greater
SUIT_Condition_Version_Comparison_Types /=
suit-condition-version-comparison-greater-equal
SUIT_Condition_Version_Comparison_Types /=
suit-condition-version-comparison-equal
SUIT_Condition_Version_Comparison_Types /=
suit-condition-version-comparison-lesser-equal
SUIT_Condition_Version_Comparison_Types /=
suit-condition-version-comparison-lesser
suit-condition-version-comparison-greater = 1
suit-condition-version-comparison-greater-equal = 2
suit-condition-version-comparison-equal = 3
suit-condition-version-comparison-lesser-equal = 4
suit-condition-version-comparison-lesser = 5
SUIT_Condition_Version_Comparison_Value = [+int]
SUIT_Component_Metadata = {
? suit-meta-default-permissions => SUIT_meta_permissions,
? suit-meta-user-permissions => SUIT_meta_permission_map,
? suit-meta-group-permissions => SUIT_meta_permission_map,
? suit-meta-role-permissions => SUIT_meta_permission_map,
? suit-meta-file-type => SUIT_Filetype,
? suit-meta-modification-time => CBOR_Datetime,
? suit-meta-creation-time => CBOR_Datetime,
? suit-meta-creator => SUIT_meta_actor_id,
* $$SUIT_Component_Metadata_Extensions
}
SUIT_meta_permissions = uint .bits SUIT_meta_permission_bits
SUIT_meta_permission_bits = &(
write_attr_ex: 13,
read_attr_ex: 12,
sync: 11,
delete: 10,
recurse_delete: 9,
write_attr: 8,
change_owner: 7,
change_perm: 6,
read_perm: 5,
read_attr: 4,
creatdir_append: 3,
list_read: 2,
create_write: 1,
traverse_exec: 0,
* $$SUIT_meta_permission_bits_extensions
)
SUIT_meta_permission_map = {
+ SUIT_meta_actor_id => SUIT_meta_permissions
}
SUIT_meta_actor_id = UUID_Tagged / bstr / str / int
UUID_Tagged = #6.37(bstr)
$$suit-text-component-key-extensions //= (
suit-text-version-required => tstr)
$$suit-text-component-key-extensions //= (
suit-text-current-version => tstr)
suit-set-version = 6
suit-coswid = 14
suit-condition-use-before = 4
suit-condition-image-not-match = 25
suit-condition-minimum-battery = 26
suit-condition-update-authorized = 27
suit-condition-version = 28
suit-directive-wait = 29
suit-directive-override-multiple = 34
suit-directive-copy-params = 35
suit-wait-event-authorization = 1
suit-wait-event-power = 2
suit-wait-event-network = 3
suit-wait-event-other-device-version = 4
suit-wait-event-time = 5
suit-wait-event-time-of-day = 6
suit-wait-event-day-of-week = 7
suit-parameter-use-before = 4
suit-parameter-minimum-battery = 26
suit-parameter-update-priority = 27
suit-parameter-version = 28
suit-parameter-wait-info = 29
suit-text-version-required = 7