forked from cose-wg/cose-spec
-
Notifications
You must be signed in to change notification settings - Fork 0
/
draft-ietf-cose-msg.xml
3948 lines (3318 loc) · 184 KB
/
draft-ietf-cose-msg.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" ?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY RFC2104 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2104.xml" >
<!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml" >
<!ENTITY RFC2633 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2633.xml" >
<!ENTITY RFC2898 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2898.xml" >
<!ENTITY RFC3394 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3394.xml" >
<!ENTITY RFC3447 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3447.xml" >
<!ENTITY RFC3610 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3610.xml" >
<!ENTITY RFC4231 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4231.xml" >
<!ENTITY RFC4262 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4262.xml" >
<!ENTITY RFC5480 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5480.xml" >
<!ENTITY RFC5652 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5652.xml" >
<!ENTITY RFC5751 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5751.xml" >
<!ENTITY RFC5752 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5752.xml" >
<!ENTITY RFC5869 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5869.xml" >
<!ENTITY RFC5990 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5990.xml" >
<!ENTITY RFC6090 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6090.xml" >
<!ENTITY RFC6151 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6151.xml" >
<!ENTITY RFC6979 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6979.xml" >
<!ENTITY RFC7049 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7049.xml" >
<!ENTITY RFC7159 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7159.xml" >
<!ENTITY RFC7252 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7252.xml" >
<!ENTITY RFC7515 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7515.xml" >
<!ENTITY RFC7516 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7516.xml" >
<!ENTITY RFC7517 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7517.xml" >
<!ENTITY RFC7518 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7518.xml" >
<!ENTITY RFC7539 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7539.xml" >
<!ENTITY CDDL SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.greevenbosch-appsawg-cbor-cddl.xml" >
<!ENTITY CBCMAC SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.mcgrew-aead-aes-cbc-hmac-sha2.xml" >
<!ENTITY CFRG-EC SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.irtf-cfrg-curves.xml" >
<!ENTITY Triple-01 SYSTEM "includes/Triple-01.xml">
<!ENTITY Enc-01 SYSTEM "includes/Enc-01.xml">
<!ENTITY Enc-02 SYSTEM "includes/Enc-02.xml">
<!ENTITY Mac-01 SYSTEM "includes/Mac-01.xml">
<!ENTITY Mac-02 SYSTEM "includes/Mac-02.xml">
<!ENTITY Mac-03 SYSTEM "includes/Mac-03.xml">
<!ENTITY Mac-04 SYSTEM "includes/Mac-04.xml">
<!ENTITY Sig-01 SYSTEM "includes/Sig-01.xml">
<!ENTITY Sig-02 SYSTEM "includes/Sig-02.xml">
<!ENTITY PrivKeys SYSTEM "includes/private-keyset.xml">
<!ENTITY PubKeys SYSTEM "includes/public-keyset.xml">
]>
<?rfc toc="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc comments="yes"?>
<rfc ipr="trust200902" docName="draft-ietf-cose-msg-latest" category="info">
<front>
<title>CBOR Encoded Message Syntax</title>
<author initials="J." surname="Schaad" fullname="Jim Schaad">
<organization>August Cellars</organization>
<address>
<email>[email protected]</email>
</address>
</author>
<date/>
<area>Security</area>
<workgroup>COSE Working Group</workgroup>
<abstract>
<t>
Concise Binary Object Representation (CBOR) is data format designed for small code size and small message size.
There is a need for the ability to have the basic security services defined for this data format.
This document specifies how to do signatures, message authentication codes and encryption using this data format.
</t>
</abstract>
<note title="Contributing to this document">
<!-- RFC EDITOR - Please remove this note before publishing -->
<t>
The source for this draft is being maintained in GitHub.
Suggested changes should be submitted as pull requests at <eref target="https://github.com/cose-wg/cose-spec"/>.
Instructions are on that page as well.
Editorial changes can be managed in GitHub, but any substantial issues need to be discussed on the COSE mailing list.
</t>
</note>
</front>
<middle>
<section anchor="introduction" title="Introduction">
<t>
There has been an increased focus on the small, constrained devices that make up the Internet of Things (IOT).
One of the standards that has come out of this process is the Concise Binary Object Representation (CBOR).
CBOR extended the data model of the JavaScript Object Notation (JSON) by allowing for binary data among other changes.
CBOR is being adopted by several of the IETF working groups dealing with the IOT world as their encoding of data structures.
CBOR was designed specifically to be both small in terms of messages transport and implementation size as well having a schema free decoder.
A need exists to provide basic message security services for IOT and using CBOR as the message encoding format makes sense.
</t>
<t>
The JOSE working group produced a set of documents <xref target="RFC7515"/><xref target="RFC7516"/><xref target="RFC7517"/><xref target="RFC7518"/> that defined how to perform encryption, signatures and message authentication (MAC) operations for JSON documents and then to encode the results using the JSON format <xref target="RFC7159"/>.
This document does the same work for use with the CBOR <xref target="RFC7049"/> document format.
While there is a strong attempt to keep the flavor of the original JOSE documents, two considerations are taken into account:
</t>
<t>
<list style="symbols">
<t>
CBOR has capabilities that are not present in JSON and should be used.
One example of this is the fact that CBOR has a method of encoding binary directly without first converting it into a base64 encoded string.
</t>
<t>
COSE is not a direct copy of the JOSE specification.
In the process of creating COSE, decisions that were made for JOSE were re-examined.
In many cases different results were decided on as the criteria were not always the same as for JOSE.
<!--
Hannes
For a working group draft it does not matter whether the author agrees or disagrees. I would suggest to remove this paragraph.
REPLACED TEXT:
The author did not always agree with some of the decisions made by the JOSE working group.
Many of these decisions have been re-examined, and where it seems to the author to be superior or simpler, replaced.
-->
</t>
</list>
</t>
<section anchor="design-changes-from-jose" title="Design changes from JOSE">
<t>
<list style="symbols">
<t>
Define a top level message structure so that encrypted, signed and MACed messages can easily identified and still have a consistent view.
</t>
<t>
Signed messages separate the concept of protected and unprotected parameters that are for the content and the signature.
</t>
<t>
Recipient processing has been made more uniform.
A recipient structure is required for all recipients rather than only for some.
</t>
<t>
MAC messages are separated from signed messages.
</t>
<t>
MAC messages have the ability to use all recipient algorithms on the MAC authentication key.
</t>
<t>
Use binary encodings for binary data rather than base64url encodings.
</t>
<t>
Combine the authentication tag for encryption algorithms with the ciphertext.
</t>
<t>
Remove the flattened mode of encoding.
Forcing the use of an array of recipients at all times forces the message size to be two bytes larger, but one gets a corresponding decrease in the implementation size that should compensate for this.
<cref source="JLS">Need to check this list for correctness before publishing.</cref>
</t>
</list>
</t>
</section>
<section anchor="requirements-terminology" title="Requirements Terminology">
<!-- NOTE FOR AUTHORS:
We use the following terms in the document
field - an entry in a CBOR array
parameter - an element in a CBOR map (as oppose to 'member' which is frequently used in JSON
label - the key of an element in a CBOR map. Unless otherwise separated from text, enclose with single quote marks
value - the value of an element in a CBOR map
-->
<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 <xref target="RFC2119"/>.
</t>
<t>
When the words appear in lower case, their natural language meaning is used.
</t>
</section>
<section anchor="cbor-grammar" title="CBOR Grammar">
<t>
There currently is no standard CBOR grammar available for use by specifications.
We therefore describe the CBOR structures in prose.
There is a version of a CBOR grammar in the CBOR Data Definition Language (CDDL) <xref target="I-D.greevenbosch-appsawg-cbor-cddl"/>.
An informational version of the CBOR grammar that reflects what is in the prose can be found in <xref target="Grammar_Appendix"/>.
CDDL has not been fixed, so this grammar may will only work with the version of CDDL at the time of publishing.
</t>
<t>
The document was developed by first working on the grammar and then developing the prose to go with it.
An artifact of this is that the prose was written using the primitive type strings defined by early versions CDDL.
In this specification the following primitive types are used:
<list style="empty">
<t>bstr - byte string (major type 2).</t>
<t>int - an unsigned integer or a negative integer.</t>
<t>nil - a null value (major type 7, value 22).</t>
<t>nint - a negative integer (major type 1).</t>
<t>tstr - a UTF-8 text string (major type 3).</t>
<t>uint - an unsigned integer (major type 0).</t>
</list>
</t>
<!-- RFC EDITOR - Please make sure the following paragraphs have been removed. -->
<t>
Text from here to start of next section to be removed
</t>
<t>
NOTE: For the purposes of review, we are currently interlacing the CDDL grammar into the text of document.
This is being done for simplicity of comparison of the grammar against the prose.
The grammar will be removed to an appendix during WGLC.
</t>
<figure><artwork type='CDDL'>
<![CDATA[
start = COSE_Untagged_Message / COSE_Tagged_Message /
COSE_Key / COSE_KeySet
]]></artwork></figure>
</section>
<section title="CBOR Related Terminology" anchor="label">
<t>
In JSON, maps are called objects and only have one kind of map key: a string.
In COSE, we use both strings and integers (both negative and non-negative integers) as map keys.
The integers are used for compactness of encoding and easy comparison.
(Generally, in this document the value zero is going to be reserved and not used.)
Since the work "key" is mainly used in its other meaning, as a cryptographic key, we use the term "label" for this usage as a map keys.
</t>
<!-- RFC EDITOR - Please make sure the following paragraphs have been removed. -->
<t>
Text from here to start of next section to be removed
</t>
<figure><artwork type='CDDL'>
<![CDATA[
label = int / tstr
values = any
]]></artwork></figure>
</section>
<section title="Document Terminology">
<t>
In this document we use the following terminology:
<cref source="JLS">
I have not gone through the document to determine what needs to be here yet.
We mostly want to grab terms which are used in unusual ways or are not generally understood.
</cref>
</t>
<t>Byte is a synonym for octet.</t>
<t>
Key management is used as a term to describe how a key at level n is obtained from level n+1 in encrypted and MACed messages.
The term is also used to discuss key life cycle management, this document does not discuss key life cycle operations.
<!-- Ilari OPEN
Should we remove the term "KEY MANAGEMENT" in this location as well.
JLS - perhaps we should do a discussion of how the term is used in different places and punt?
-->
</t>
</section>
<section title="Mandatory to Implement Algorithms">
<t>
One of the issues that needs to be addressed is a requirement that a standard specify a set of algorithms that are required to be implemented.
<cref source="JLS">
It would be possible to extend this section to talk about those decisions which an application needs to think about rather than just talking about MTI algorithms.
</cref>
This is done to promote interoperability as it provides a minimal set of algorithms that all devices can be sure will exist at both ends.
However, we have elected not to specify a set of mandatory algorithms in this document.
</t>
<t>
It is expected that COSE is going to be used in a wide variety of applications and on a wide variety of devices.
Many of the constrained devices are going to be setup to use a small fixed set of algorithms, and this set of algorithms may not match those available on a device.
We therefore have deferred to the application protocols the decision of what to specify for mandatory algorithms.
</t>
<t>
Since the set of algorithms in an environment of constrained devices may depend on what the set of devices are and how long they have been in operation, we want to highlight that application protocols will need to specify some type of discovery method of algorithm capabilities.
The discovery method may be as simple as requiring preconfiguration of the set of algorithms to providing a discovery method built into the protocol.
S/MIME provided a number of different ways to approach the problem:
<list style="symbols">
<t>Advertising in the message (S/MIME capabilities) <xref target="RFC5751"/>.</t>
<t>Advertising in the certificate (capabilities extension) <xref target="RFC4262"/></t>
<t>Minimum requirements for the S/MIME which have been updated over time <xref target="RFC2633"/><xref target="RFC5751"/></t>
</list>
</t>
</section>
</section>
<section anchor="the-cosemsg-structure" title="Basic COSE Structure">
<t>
The COSE Message structure is designed so that there can be a large amount of common code when parsing and processing the different security messages.
All of the message structures are built on a CBOR array type.
The first three elements of the array contains the same basic information.
The first element is a set of protected header information.
The second element is a set of unprotected header information.
The third element is the content of the message (either as plain text or encrypted).
Elements after this point are dependent on the specific message type.
</t>
<t>
Identification of which message is present is done by one of two methods:
<list style="symbols">
<t>
The specific message type is known from the context in which it is placed.
This may be defined by a marker in the containing structure or by restrictions specified by the application protocol.
</t>
<t>
The message type is identified by a CBOR tag.
This document defines a CBOR tag for each of the message structures.
</t>
</list>
</t>
<!--
<t>
The COSE_MSG structure is a top level CBOR object that corresponds to the DataContent type in the Cryptographic Message Syntax (CMS) <xref target="RFC5652"/>.
< ! - - Hannes
I would remove references to CMS and S/MIME since they are most likely only helpful to a very small audience.
OPEN
- - >
<cref source="Hannes">I would remove references to CMS and S/MIME since they are most likely only helpful to a very small audience.</cref>
This structure allows for a top level message to be sent that could be any of the different security services.
The security service is identified within the message.
</t>
<t>
The COSE_Tagged_MSG CBOR type takes the COSE_MSG and prepends a CBOR tag of TBD1 to the encoding of COSE_MSG.
By having both a tagged and untagged version of the COSE_MSG structure, it becomes easy to either use COSE_MSG as a top level object or embedded in another object.
The tagged version allows for a method of placing the COSE_MSG structure into a choice, using a consistent tag value to determine that this is a COSE object.
</t>
<t>
The existence of the COSE_MSG and COSE_Tagged_MSG CBOR data types are not intended to prevent protocols from using the individual security primitives directly.
Where only a single service is required, that structure can be used directly.
</t>
<t>
Each of the top-level security objects use a CBOR array as the base structure.
For each of the top-level security objects, the first field is a 'msg_type'.
The CBOR type for a 'msg_type' is 'int'.
The 'msg_type' is defined to distinguish between the different structures when they appear as part of a COSE_MSG object.
<cref source="JLS">
I have moved msg_type into the individual structures.
However, they would not be necessary in the cases where a) the security service is known and b) security libraries can setup to take individual structures.
Should they be moved back to just appearing if used in a COSE_MSG rather than on the individual structure?
This would make things shorter if one was using just a signed message because the msg_type field can be omitted as well as the COSE_Tagged_MSG tag field.
One the other hand, it will complicated the code if one is doing general purpose library type things.
</cref>
<cref source="JLS">Should we create an IANA registries for the values of msg_type?</cref>
<cref source="CB">I would like to make msg_type go away</cref>
</t>
<t>
The message types defined in this document are:
<list style="empty">
<t>0 - Reserved.</t>
<t>1 - Signed Message.</t>
<t>2 - Enveloped Message</t>
<t>3 - Authenticated Message (MACed message)</t>
<t>4 - Encrypted Message</t>
</list>
</t>
<t>
Implementations MUST be prepared to find an integer in this field that does not correspond to the values 1 to 3.
If a message type is found then the client does not support the associated security object, the client MUST stop attempting to process the structure and fail.
The value of 0 is reserved and not assigned to a security object.
If the value of 0 is found, then clients MUST fail processing the structure.
Implementations need to recognize that the set of values might be extended at a later date, but they should not provide a security service based on guesses of what the security object might be.
</t>
-->
<!-- RFC EDITOR - Please make sure the following paragraphs have been removed. -->
<t>
Text from here to start of next section to be removed
</t>
<figure><artwork type="CDDL"><![CDATA[
COSE_Untagged_Message = COSE_Sign /
COSE_enveloped /
COSE_encryptData /
COSE_Mac
COSE_Tagged_Message = COSE_Sign_Tagged /
COSE_Enveloped_Tagged /
COSE_EncryptedData_Tagged /
COSE_Mac_Tagged
]]></artwork></figure>
<!--
<texttable anchor="Top-Level-Keys" title="COSE Map Labels">
<ttcol align='left'>name</ttcol>
<ttcol align='left'>number</ttcol>
<ttcol align='left'>comments</ttcol>
<c>msg_type</c> <c>1</c> <c>Occurs only in top level messages</c>
<c>protected</c> <c>2</c> <c>Occurs in all structures</c>
<c>unprotected</c> <c>3</c> <c>Occurs in all structures</c>
<c>payload</c> <c>4</c> <c>Contains the content of the structure</c>
<c>signatures</c> <c>5</c> <c>For COSE_Sign - array of signatures</c>
<c>signature</c> <c>6</c> <c>For COSE_signature only</c>
<c>ciphertext</c> <c>4</c> <c>TODO: Should we reuse the same as payload or not?</c>
<c>recipients</c> <c>9</c> <c>For COSE_encrypt and COSE_mac</c>
<c>tag</c> <c>10</c> <c>For COSE_mac only</c>
</texttable>
<t>
The CDDL grammar that provides the label values is:
</t>
<figure><artwork type="CDDL"><![CDATA[
; message_labels
msg_type=1
protected=2
unprotected=3
payload=4
signatures=5
signature=6
ciphertext=4
recipients=9
tag=10
]]></artwork></figure>
-->
</section>
<section anchor="header-parameters" title="Header Parameters">
<t>
The structure of COSE has been designed to have two buckets of information that are not considered to be part of the payload itself, but are used for holding information about content, algorithms, keys, or evaluation hints for the processing of the layer.
These two buckets are available for use in all of the structures in this document except for keys.
While these buckets can be present, they may not all be usable in all instances.
For example, while the protected bucket is defined as part of recipient structures, most of the algorithms that are used for recipients do not provide the necessary functionality to provide the needed protection and thus the bucket should not be used.
</t>
<t>
Both buckets are implemented as CBOR maps.
The map key is a 'label' (<xref target="label"/>).
The value portion is dependent on the definition for the label.
Both maps use the same set of label/value pairs.
The integer and string values for labels has been divided into several sections with a standard range, a private range, and a range that is dependent on the algorithm selected.
The defined labels can be found in the 'COSE Header Parameters' IANA registry (<xref target="cose-header-key-table"/>).
</t>
<t>
Two buckets are provided for each layer:
<list style="hanging">
<t hangText='protected:'>
Contains parameters about the current layer that are to be cryptographically protected.
This bucket MUST be empty if it is not going to be included in a cryptographic computation.
This bucket is encoded in the message as a binary object.
This value is obtained by CBOR encoding the protected map and wrapping it in a bstr object.
Senders SHOULD encode an empty protected map as a zero length binary object (it is shorter).
Recipients MUST accept both a zero length binary value and a zero length map encoded in the binary value.
The wrapping allows for the encoding of the protected map to be transported with a greater chance that it will not be altered in transit.
(Badly behaved intermediates could decode and re-encode, but this will result in a failure to verify unless the re-encoded byte string is identical to the decoded byte string.)
This finesses the problem of all parties needing to be able to do a common canonical encoding.
</t>
<t hangText='unprotected:'>
Contains parameters about the current layer that are not cryptographically protected.
</t>
</list>
Only parameters that deal with the current layer are to be placed at that layer.
As an example of this, the parameter 'content type' describes the content of the message being carried in the message.
As such this parameter is placed only in the content layer and is not placed in the recipient or signature layers.
In principle, one should be able to process any given layer without reference to any other layer.
(The only data that should need to cross layers is the cryptographic key.)
</t>
<t>
The buckets are present in all of the security objects defined in this document.
The fields in order are the 'protected' bucket (as a CBOR 'bstr' type) and then the 'unprotected' bucket (as a CBOR 'map' type).
The presence of both buckets is required.
The parameters that go into the buckets come from the IANA "COSE Header Parameters" (<xref target="cose-header-key-table"/>).
Some common parameters are defined in the next section, but a number of parameters are defined throughout this document.
</t>
<!-- RFC EDITOR - Please make sure the following paragraphs have been removed. -->
<t>
Text from here to start of next section to be removed
<cref source="JLS">
A completest version of this grammar would list the options available in the protected and unprotected headers.
Do we want to head that direction?
</cref>
</t>
<figure><artwork type="CDDL"><![CDATA[
header_map = {+ label => any }
Headers = (
protected : bstr, ; Contains a header_map
unprotected : header_map
)
]]></artwork></figure>
<section anchor="cose-headers" title="Common COSE Headers Parameters">
<t>
This section defines a set of common header parameters.
A summary of those parameters can be found in <xref target="Header-Table"/>.
This table should be consulted to determine the value of label used as well as the type of the value.
</t>
<t>
The set of header parameters defined in this section are:
</t>
<t>
<list style="hanging">
<t hangText='alg'>
This parameter is used to indicate the algorithm used for the security processing.
This parameter MUST be present at each level of a signed, encrypted or authenticated message.
The value is taken from the 'COSE Algorithm Registry' (see <xref target="cose-algorithm-registry"/>).
</t>
<t hangText='crit'>
This parameter is used to ensure that applications will take appropriate action based on the values found.
The parameter is used to indicate which protected header labels an application that is processing a message is required to understand.
The value is an array of COSE Header Labels.
When present, this parameter MUST be placed in the protected header bucket.
<vspace/>
<list style="symbols">
<t>Integer labels in the range of 0 to 10 SHOULD be omitted.</t>
<t>
Integer labels in the range -1 to -255 can be omitted as they are algorithm dependent.
If an application can correctly process an algorithm, it can be assumed that it will correctly process all of the parameters associated with that algorithm.
(The algorithm range is -1 to -65536, it is assumed that the higher end will deal with more optional algorithm specific items.)
</t>
</list>
The header parameter values indicated by 'crit' can be processed by either the security library code or by an application using a security library, the only requirement is that the parameter is processed.
If the 'crit' value list includes a value for which the parameter is not in the protected bucket, this is a fatal error in processing the message.
</t>
<t hangText='content type'>
This parameter is used to indicate the content type of the data in the payload or ciphertext fields.
Integers are from the 'CoAP Content-Formats' IANA registry table.
Strings are from the IANA 'Media Types' registry.
Applications SHOULD provide this parameter if the content structure is potentially ambiguous.
</t>
<t hangText='kid'>
This parameter one of the ways that can be used to find the key to be used.
The value of this parameter is matched against the 'kid' member in a COSE_Key structure.
Applications MUST NOT assume that 'kid' values are unique.
There may be more than one key with the same 'kid' value, it may be required that all of the keys need to be checked to find the correct one.
The internal structure of 'kid' values is not defined and generally cannot be relied on by applications.
Key identifier values are hints about which key to use, they are not directly a security critical field, for this reason they can be placed in the unprotected headers bucket.
</t>
<t hangText='nonce'>
This parameter holds either a nonce or Initialization Vector value.
The value can be used either as a counter value for a protocol or as an IV for an algorithm.
</t>
<t hangText='counter signature'>
This parameter holds a counter signature value.
Counter signatures provide a method of having a second party sign some data, the counter signature can occur as an unprotected attribute in any of the following structures: COSE_Sign, COSE_signature, COSE_enveloped, COSE_recipient, COSE_encryptedData, COSE_mac.
These structures all have the same basic structure so that a consistent calculation of the counter signature can be computed.
Details on computing counter signatures are found in <xref target="counter_signature"/>.
</t>
<t hangText='creation time'>
This parameter provides the time the content was created.
For signatures and recipient structures, this would be the time that the signature or recipient key object was created.
For content structures, this would be the time that the content was created.
The unsigned integer value is the number of seconds, excluding leap seconds; after midnight UTC, January 1, 1970.
</t>
<t hangText='sequence number'>
This parameter provides a counter field.
The use of this parameter is application specific.
</t>
</list>
</t>
<texttable anchor="Header-Table" title="Common Header Parameters">
<ttcol align='left'>name</ttcol>
<ttcol align='left'>label</ttcol>
<ttcol align='left'>value type</ttcol>
<ttcol align='left'>value registry</ttcol>
<ttcol align='left'>description</ttcol>
<c>alg</c> <c>1</c> <c>int / tstr</c> <c>COSE Algorithm Registry</c> <c>Integers are taken from table --POINT TO REGISTRY--</c>
<c>crit</c> <c>2</c> <c>[+ label]</c> <c>COSE Header Label Registry</c> <c>integer values are from -- POINT TO REGISTRY --</c>
<c>content type</c> <c>3</c> <c>tstr / int</c> <c>CoAP Content-Formats or Media Types registry</c> <c>Value is either a Media Type or an integer from the CoAP Content Format registry</c>
<c>kid</c> <c>4</c> <c>bstr</c> <c></c> <c>key identifier</c>
<c>nonce</c> <c>5</c> <c>bstr</c> <c></c> <c>Nonce or Initialization Vector (IV)</c>
<c>counter signature</c> <c>6</c> <c>COSE_signature</c> <c></c> <c>CBOR encoded signature structure</c>
<c>creation time</c><c>*</c> <c>uint</c> <c></c> <c>Time the content was created</c>
<c>sequence number</c><c>*</c> <c>uint</c> <c></c> <c>Application specific Integer value</c>
</texttable>
<t>
OPEN ISSUES:
<list style="numbers">
<t>
I am currently torn on the question "Should epk and iv/nonce be algorithm specific or generic headers?"
They are really specific to an algorithm and can potentially be defined in different ways for different algorithms.
As an example, it would make sense to defined nonce for CCM and GCM modes that can have the leading zero bytes stripped, while for other algorithms this might be undesirable.
</t>
<t>
We might want to define some additional items. What are they? A possible example would be a sequence number as this might be common. On the other hand, this is the type of things that is frequently used as the nonce in some places and thus should not be used in the same way. Other items might be challenge/response fields for freshness as these are likely to be common.
</t>
</list>
</t>
</section>
</section>
<section anchor="signing-structure" title="Signing Structure">
<t>
The signature structure allows for one or more signatures to be applied to a message payload.
There are provisions for parameters about the content and parameters about the signature to be carried along with the signature itself.
These parameters may be authenticated by the signature, or just present.
Examples of parameters about the content would be the type of content, when the content was created, and who created the content.
<cref source="Hannes">
Ensure that the list of examples only includes items which are implemented in this specification.
Check the other places where such lists occur and ensure that they also follow this rule.
</cref>
Examples of parameters about the signature would be the algorithm and key used to create the signature, when the signature was created, and counter-signatures.
</t>
<t>
When more than one signature is present, the successful validation of one signature associated with a given signer is usually treated as a successful signature by that signer.
However, there are some application environments where other rules are needed.
An application that employs a rule other than one valid signature for each signer must specify those rules.
Also, where simple matching of the signer identifier is not sufficient to determine whether the signatures were generated by the same signer, the application specification must describe how to determine which signatures were generated by the same signer.
Support of different communities of recipients is the primary reason that signers choose to include more than one signature.
For example, the COSE_Sign structure might include signatures generated with the RSA signature algorithm and with the Elliptic Curve Digital Signature Algorithm (ECDSA) signature algorithm.
This allows recipients to verify the signature associated with one algorithm or the other.
(The original source of this text is <xref target="RFC5652"/>.)
<!-- RFC Editor: This is not a direct quote from RFC 5652, but the basic text has come from there. I want to acknowledge the original source of the quote but am not sure what is the correct way to go about this.-->
More detailed information on multiple signature evaluation can be found in <xref target="RFC5752"/>.
</t>
<t>
The COSE_Sign structure is a CBOR array.
The fields of the array in order are:
</t>
<t>
<list style="hanging">
<!--
<t hangText='msg_type'>
identifies this as providing the signed security service.
The value MUST be msg_type_signed (1).
</t>
-->
<t hangText='protected'>
is described in <xref target="header-parameters"/>.
</t>
<t hangText='unprotected'>
is described in <xref target="header-parameters"/>.
</t>
<t hangText='payload'>
contains the serialized content to be signed.
If the payload is not present in the message, the application is required to supply the payload separately.
The payload is wrapped in a bstr to ensure that it is transported without changes.
If the payload is transported separately, then a nil CBOR object is placed in this location and it is the responsibility of the application to ensure that it will be transported without changes.
</t>
<t hangText='signatures'>
is an array of signature items.
Each of these items uses the COSE_signature structure for its representation.
</t>
</list>
</t>
<t>
The COSE_signature structure is a CBOR array.
The fields of the array in order are:
</t>
<t>
<list style="hanging">
<t hangText='protected'>
is described in <xref target="header-parameters"/>.
</t>
<t hangText='unprotected'>
is described in <xref target="header-parameters"/>.
</t>
<t hangText='signature'>
contains the computed signature value.
The type of the field is a bstr.
</t>
</list>
</t>
<!-- RFC EDITOR - Please make sure the following paragraphs have been removed. -->
<t>
Text from here to start of next section to be removed
</t>
<figure><artwork type="CDDL"><![CDATA[
COSE_Sign_Tagged = #6.999(COSE_Sign) ; Replace 999 with TBD1
COSE_Sign = [
Headers,
payload : bstr / nil,
signatures : [+ COSE_signature]
]
COSE_signature = [
Headers,
signature : bstr
]
]]></artwork></figure>
<section title="Externally Supplied Data" anchor="Extern_AAD">
<t>
One of the features that we supply in the COSE document is the ability for applications to provide additional data to be authenticated as part of the security, but that is not carried as part of the COSE object.
The primary reason for supporting this can be seen by looking at the CoAP message structure <xref target="RFC7252"/> where the facility exists for options to be carried before the payload.
An example of data that can be placed in this location would be transaction ids and nonces to check for replay protection.
If the data is in the options section, then it is available for routers to help in performing the replay detection and prevention.
However, it may also be desired to protect these values so that they cannot be modified in transit.
This is the purpose of the externally supplied data field.
</t>
<t>
This document describes the process for using a byte array of externally supplied authenticated data, however the method of constructing the byte array is a function of the application.
Applications which use this feature need to define how the externally supplied authenticated data is to be constructed.
Such a construction needs to take into account the following issues:
<list style="symbols">
<t>
If multiple items are included, care needs to be taken that data cannot bleed between the items.
This is usually addressed by making fields fixed width and/or encoding the length of the field.
Using options from CoAP as an example, these fields use a TLV structure so they can be concatenated without any problems.
</t>
<t>
If multiple items are included, a defined order for the items needs to be defined.
Using options from CoAP as an example, an application could state that the fields are to be ordered by the option number.
</t>
</list>
</t>
</section>
<section title="Signing and Verification Process">
<t>
In order to create a signature, a consistent byte stream is needed in order to process.
This document uses a CBOR array to construct the byte stream to be processed.
The fields of the array in order are:
<list style="numbers">
<t>
The body protected attributes.
This is a bstr type containing the protected attributes of the body.
</t>
<t>
The signature protected attributes.
This is a bstr type containing the protected attributes of the signature.
</t>
<t>
The external protected attributes.
This is a bstr type containing the protected attributes external to the COSE_Signature structure.
</t>
<t>
The payload to be signed.
The payload is encoded in a bstr.
The payload is placed here independent of how it is transported.
</t>
</list>
</t>
<t>
How to compute a signature:
<list style="numbers">
<t>
Create a CBOR array and populate it with the appropriate fields.
For body_protected and sign_protected, if the fields are not present in their corresponding maps, a bstr of length zero is used.
</t>
<t>
If the application has supplied external additional authenticated data to be included in the computation, then it is placed in the third field.
If no data was supplied, then a zero length binary value is used.
</t>
<t>
Create the value ToBeSigned by encoding the Sig_structure to a byte string.
</t>
<t>
Call the signature creation algorithm passing in K (the key to sign with), alg (the algorithm to sign with) and ToBeSigned (the value to sign).
</t>
<t>
Place the resulting signature value in the 'signature' field of the map.
</t>
</list>
</t>
<t>
How to verify a signature:
<list style="numbers">
<t>
Create a Sig_structure object and populate it with the appropriate fields.
For body_protected and sign_protected, if the fields are not present in their corresponding maps, a bstr of length zero is used.
</t>
<t>
If the application has supplied external additional authenticated data to be included in the computation, then it is placed in the third field.
If no data was supplied, then a zero length binary value is used.
</t>
<t>
Create the value ToBeSigned by encoding the Sig_structure to a byte string.
</t>
<t>
Call the signature verification algorithm passing in K (the key to verify with), alg (the algorithm to sign with), ToBeSigned (the value to sign), and sig (the signature to be verified).
</t>
</list>
</t>
<t>
In addition to performing the signature verification, one must also perform the appropriate checks to ensure that the key is correctly paired with the signing identity and that the appropriate authorization is done.
</t>
<!-- RFC EDITOR - Please make sure the following paragraphs have been removed. -->
<t>
Text from here to start of next section to be removed
</t>
<t>
The COSE structure used to create the byte stream to be signed uses the following CDDL grammar structure:
</t>
<figure><artwork type="CDDL"><![CDATA[
Sig_structure = [
body_protected: bstr,
sign_protected: bstr,
external_aad: bstr,
payload: bstr
]
]]></artwork></figure>
</section>
<section anchor="counter_signature" title="Computing Counter Signatures">
<t>
Counter signatures provide a method of having a different signature occur on some piece of content.
This is normally used to provide a signature on a signature allowing for a proof that a signature existed at a given time.
In this document we allow for counter signatures to exist in a greater number of environments.
A counter signature can exist, for example, on a COSE_encryptedData object and allow for a signature to be present on the encrypted content of a message.
</t>
<t>
The creation and validation of counter signatures over the different items relies on the fact that the structure all of our objects have the same structure.
The first element may be a message type, this is followed by a set of protected attributes, a set of unprotected attributes and a body in that order.
This means that the Sig_structure can be used for in a uniform manner to get the byte stream for processing a signature.
If the counter signature is going to be computed over a COSE_encryptedData structure, the body_protected and payload items can be mapped into the Sig_structure in the same manner as from the COSE_Sign structure.
</t>
<t>
While one can create a counter signature for a COSE_Sign structure, there is not much of a point to doing so. It is equivalent to create a new COSE_signature structure and placing it in the signatures array. It is strongly suggested that it not be done, but it is not banned.
</t>
</section>
</section>
<section anchor="encryption-object" title="Encryption objects">
<t>
COSE supports two different encryption structures.
COSE_enveloped is used when the key needs to be explicitly identified.
This structure supports the use of recipient structures to allow for random content encryption keys to be used.
COSE_encrypted is used when a recipient structure is not needed because the key to be used is known implicitly.
</t>
<section title="Enveloped COSE structure">
<t>
The enveloped structure allows for one or more recipients of a message.
There are provisions for parameters about the content and parameters about the recipient information to be carried in the message.
The parameters associated with the content can be authenticated by the content encryption algorithm.
The parameters associated with the recipient can be authenticated by the recipient algorithm (when the algorithm supports it).
Examples of parameters about the content are the type of the content, when the content was created, and the content encryption algorithm.
Examples of parameters about the recipient are the recipient's key identifier, the recipient encryption algorithm.
</t>
<t>
In COSE, the same techniques and structures for encrypting both the plain text and the keys used to protect the text.
This is different from the approach used by both <xref target="RFC5652"/> and <xref target="RFC7516"/> where different structures are used for the content layer and for the recipient layer.
</t>
<t>
The COSE_encrypt structure is a CBOR array.
The fields of the array in order are:
<list style="hanging">
<!--
<t hangText='msg_type'>
identifies this as providing the encrypted security service.
The value MUST be msg_type_encrypted (2).
</t>
-->
<t hangText='protected'>
is described in <xref target="header-parameters"/>.
</t>
<t hangText='unprotected'>
is described in <xref target="header-parameters"/>.
</t>
<t hangText='ciphertext'>
contains the encrypted plain text encoded as a bstr.
If the ciphertext is to be transported independently of the control information about the encryption process (i.e. detached content) then the field is encoded as a null object.
</t>
<t hangText='recipients'>
contains an array of recipient information structures.
The type for the recipient information structure is a COSE_recipient.
</t>
</list>
</t>
<t>
The COSE_recipient structure is a CBOR array.
The fields of the array in order are:
<list style="hanging">
<t hangText='protected'>
is described in <xref target="header-parameters"/>.
</t>
<t hangText='unprotected'>
is described in <xref target="header-parameters"/>.
</t>
<t hangText='ciphertext'>
contains the encrypted key encoded as a bstr.
If there is not an encrypted key, then this field is encoded as a nil type.
</t>
<t hangText='recipients'>
contains an array of recipient information structures.
The type for the recipient information structure is a COSE_recipient.
If there are no recipient information structures, this element is absent.
</t>
</list>
</t>
<!-- RFC EDITOR - Please make sure the following paragraphs have been removed. -->
<t>
Text from here to start of next section to be removed
</t>
<figure><artwork type="CDDL"><![CDATA[
COSE_Enveloped_Tagged = #6.998(COSE_enveloped) ; Replace 998 with TBD32
COSE_enveloped = [