-
Notifications
You must be signed in to change notification settings - Fork 12
/
draft-ietf-cose-msg.xml
5565 lines (4689 loc) · 276 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 RFC3394 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3394.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 RFC4493 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4493.xml" >
<!ENTITY RFC4949 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4949.xml" >
<!ENTITY RFC5116 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5116.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 RFC6838 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6838.xml" >
<!ENTITY RFC6979 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6979.xml" >
<!ENTITY RFC7942 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7942.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 RFC7748 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7748.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-EDDSA SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.irtf-cfrg-eddsa.xml" >
<!ENTITY RFC2898 SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.moriarty-pkcs5-v2dot1.xml" >
<!ENTITY RFC3447 SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.moriarty-pkcs1.xml" >
<!ENTITY OSCOAP SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.selander-ace-object-security.xml" >
<!ENTITY Appendix_A SYSTEM "includes/Appendix_A.xml">
<!ENTITY Appendix_B_3_1 SYSTEM "includes/Appendix_B_3_1.xml">
<!ENTITY Appendix_B_3_2 SYSTEM "includes/Appendix_B_3_2.xml">
<!ENTITY Appendix_B_3_3 SYSTEM "includes/Appendix_B_3_3.xml">
<!ENTITY Appendix_B_4_1 SYSTEM "includes/Appendix_B_4_1.xml">
<!ENTITY Appendix_B_4_2 SYSTEM "includes/Appendix_B_4_2.xml">
<!ENTITY Appendix_B_3_4 SYSTEM "includes/Appendix_B_3_4.xml">
<!ENTITY Appendix_B_5_2 SYSTEM "includes/Appendix_B_5_2.xml">
<!ENTITY Appendix_B_5_3 SYSTEM "includes/Appendix_B_5_3.xml">
<!ENTITY Appendix_B_5_4 SYSTEM "includes/Appendix_B_5_4.xml">
<!ENTITY Appendix_B_5_1 SYSTEM "includes/Appendix_B_5_1.xml">
<!ENTITY Appendix_B_6_1 SYSTEM "includes/Appendix_B_6_1.xml">
<!ENTITY Appendix_B_1_1 SYSTEM "includes/Appendix_B_1_1.xml">
<!ENTITY Appendix_B_1_2 SYSTEM "includes/Appendix_B_1_2.xml">
<!ENTITY Appendix_B_1_3 SYSTEM "includes/Appendix_B_1_3.xml">
<!ENTITY Appendix_B_1_4 SYSTEM "includes/Appendix_B_1_4.xml">
<!ENTITY Appendix_B_2_1 SYSTEM "includes/Appendix_B_2_1.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 EDITOR
There have been a number of comments about my use of parenthesized sentences in the middle of paragraphs.
Please look at these and determine if the parens should be left or removed.
-->
<!-- RFC EDITOR
-general, in many section, e.g. 16.2: when listing terms+ definition, it would be clearer to add ":" in front of the term.
[JLS] I’ll take with the RFC Editor about this. It is partly a matter of style.
-->
<rfc ipr="trust200902" docName="draft-ietf-cose-msg-latest" category="std">
<front>
<title>CBOR Object Signing and Encryption (COSE)</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 basic security services defined for this data format.
This document defines the CBOR Object Signing and Encryption (COSE) specification.
This specification describes how to create and process signature, message authentication codes and encryption using CBOR for serialization.
This specification additionally specifies how to represent cryptographic keys using CBOR.
</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 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) <xref target="RFC7049"/>.
CBOR extended the data model of the JavaScript Object Notation (JSON) <xref target="RFC7159"/> 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 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"/> using JSON that specified how to process encryption, signatures and Message Authentication Code (MAC) operations, and how to encode keys using JSON.
This document defines the CBOR Object Encryption and Signing (COSE) standard which does the same thing for the CBOR encoding 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 are appropriate to use.
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 was not always the same.
<!--
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 single top message structure so that encrypted, signed and MACed messages can easily be identified and still have a consistent view.
</t>
<t>
Signed messages distinguish between the protected and unprotected parameters that relate to the content from those that relate to the signature.
<!-- Signed messages separate the concept of protected and unprotected parameters that are for the content and the signature. -->
</t>
<t>
MACed messages are separated from signed messages.
</t>
<t>
MACed messages have the ability to use the same set of recipient algorithms as enveloped messages for obtaining 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 cipher text.
</t>
<t>
The set of cryptographic algorithms has been expanded in some directions, and trimmed in others.
</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 is currently no standard CBOR grammar available for use by specifications.
The CBOR structures are therefore described in prose.
</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 CBOR Data Definition Language (CDDL) <xref target="I-D.greevenbosch-appsawg-cbor-cddl"/>.
In this specification, the following primitive types are used:
<list style="empty">
<t>any - non-specific value that permits all CBOR values to be placed here.</t>
<t>bool - a boolean value (true: major type 7, value 21; false: major type 7, value 20).</t>
<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>
<t>
Two syntaxes from CDDL appear in this document as shorthand.
These are:
<list style="empty">
<t>FOO / BAR - indicates that either FOO or BAR can appear here</t>
<t>[+ FOO] - indicates that the type FOO appears one or more times in an array</t>
</list>
</t>
<t>
As well as the prose description, a version of a CBOR grammar is presented in CDDL.
Since CDDL has not been published as an RFC, this grammar may not work with the final version of CDDL.
The CDDL grammar is informational, the prose description is normative.
</t>
<t>
The collected CDDL can be extracted from the XML version of this document via the following XPath expression below.
(Depending on the XPath evaluator one is using, it may be necessary to deal with &gt; as an entity.)
</t>
<t>
<figure><artwork type='XPATH'><![CDATA[
//artwork[@type='CDDL']/text()
]]></artwork></figure>
</t>
<t>
CDDL expects the initial non-terminal symbol to be the first symbol in the file.
For this reason the first fragment of CDDL is presented here.
</t>
<figure><artwork type='CDDL'><![CDATA[
start = COSE_Messages / COSE_Key / COSE_KeySet / Internal_Types
; This is defined to make the tool quieter:
Internal_Types = Sig_structure / Enc_structure / MAC_structure /
COSE_KDF_Context
]]></artwork></figure>
<t>
The non-terminal Internal_Types is defined for dealing with the automated validation tools used during the writing of this document.
It references those non-terminals that are used for security computations, but are not emitted for transport.
</t>
</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 strings, negative integers and unsigned integers as map keys.
The integers are used for compactness of encoding and easy comparison.
The inclusion of strings allows for an additional range of short encoded values to be used as well.
Since the word "key" is mainly used in its other meaning, as a cryptographic key, we use the term "label" for this usage as a map key.
</t>
<t>
The presence of a label in a COSE map which is not a string or an integer is an error.
Applications can either fail processing or process messages with incorrect labels, however they MUST NOT create messages with incorrect labels.
</t>
<t>
A CDDL grammar fragment is defined that defines the non-terminals 'label', as in the previous paragraph and 'values', which permits any value to be used.
</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:
</t>
<t>Byte is a synonym for octet.</t>
<t>
Constrained Application Protocol (CoAP) is a specialized web transfer protocol for use in constrained systems.
It is defined in <xref target="RFC7252"/>.
</t>
<t>
Authenticated Encryption (AE) <xref target="RFC5116"/> algorithms are those encryption algorithms which provide an authentication check of the contents algorithm with the encryption service.
</t>
<t>
Authenticated Encryption with Authenticated Data (AEAD) <xref target="RFC5116"/> algorithms provide the same content authentication service as AE algorithms, but additionally provide for authentication of non-encrypted data as well.
</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 DONE
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?
Now gone.
</t>
-->
</section>
</section>
<section anchor="the-cosemsg-structure" title="Basic COSE Structure">
<t>
The COSE object structure is designed so that there can be a large amount of common code when parsing and processing the different types of security messages.
All of the message structures are built on the CBOR array type.
The first three elements of the array always contain the same information:
<list style="numbers">
<t>The set of protected header parameters wrapped in a bstr.</t>
<t>The set of unprotected header parameters as a map.</t>
<t>
The content of the message.
The content is either the plain text or the cipher text as appropriate.
The content may be detached, but the location is still used.
The content is wrapped in a bstr when present and is a nil value when detached.
</t>
</list>
Elements after this point are dependent on the specific message type.
</t>
<t>
COSE messages are also built using the concept of layers to separate different types of cryptographic concepts.
As an example of how this works, consider the COSE_Encrypt message (<xref target="EnvelopedData"/>).
This message type is broken into two layers: the content layer and the recipient layer.
In the content layer, the plain text is encrypted and information about the encrypted message are placed.
In the recipient layer, the content encryption key (CEK) is encrypted and information about how it is encrypted for each recipient is placed.
A single layer version of the encryption message COSE_Encrypt0 (<xref target="EnvelopedData0"/>) is provided for cases where the CEK is pre-shared.
</t>
<t>
Identification of which type of message has been presented is done by the following methods:
<list style="numbers">
<t>
The specific message type is known from the context.
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.
Messages with a CBOR tag are known in this specification as tagged messages, while those without the CBOR tag are known as untagged messages.
This document defines a CBOR tag for each of the message structures.
These tags can be found in <xref target="CBOR-Tags"/>.
</t>
<t>
When a COSE object is carried in a media type of application/cose, the optional parameter 'cose-type' can be used to identify the embedded object.
The parameter is OPTIONAL if the tagged version of the structure is used.
The parameter is REQUIRED if the untagged version of the structure is used.
The value to use with the parameter for each of the structures can be found in <xref target="CBOR-Tags"/>.
</t>
<t>
When a COSE object is carried as a CoAP payload, the CoAP
Content-Format Option can be used to identify the message content.
The CoAP Content-Format values can be found in <xref target="CoAP_content_type"/>.
The CBOR tag for the message structure is not required as each security message is uniquely identified.
</t>
</list>
</t>
<!-- Table 1 -->
<texttable anchor="CBOR-Tags" title="COSE Message Identification">
<ttcol>CBOR Tag</ttcol> <ttcol>cose-type</ttcol> <ttcol>Data Item</ttcol> <ttcol>Semantics</ttcol>
<c>98</c> <c>cose-sign</c> <c>COSE_Sign</c> <c>COSE Signed Data Object</c>
<c>18</c> <c>cose-sign1</c> <c>COSE_Sign1</c> <c>COSE Single Signer Data Object</c>
<c>96</c> <c>cose-encrypt</c> <c>COSE_Encrypt</c> <c>COSE Encrypted Data Object</c>
<c>16</c> <c>cose-encrypt0</c> <c>COSE_Encrypt0</c> <c>COSE Single Recipient Encrypted Data Object</c>
<c>97</c> <c>cose-mac</c> <c>COSE_Mac</c> <c>COSE Mac-ed Data Object</c>
<c>17</c> <c>cose-mac0</c> <c>COSE_Mac0</c> <c>COSE Mac w/o Recipients Object</c>
</texttable>
<!--
<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>
-->
<t>
The following CDDL fragment identifies all of the top messages defined in this document.
Separate non-terminals are defined for the tagged and the untagged versions of the messages.
</t>
<figure><artwork type="CDDL"><![CDATA[
COSE_Messages = COSE_Untagged_Message / COSE_Tagged_Message
COSE_Untagged_Message = COSE_Sign / COSE_Sign1 /
COSE_Encrypt / COSE_Encrypt0 /
COSE_Mac / COSE_Mac0
COSE_Tagged_Message = COSE_Sign_Tagged / COSE_Sign1_Tagged /
COSE_Encrypt_Tagged / COSE_Encrypt0_Tagged /
COSE_Mac_Tagged / COSE_Mac0_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 except for keys.
While these buckets are present, they may not all be usable in all instances.
For example, while the protected bucket is defined as part of the recipient structure, some of the algorithms used for recipient structures do not provide for authenticated data.
If this is the case, the protected bucket is left empty.
</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 have 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 a zero length map as a zero length string rather than as a zero length map (encoded as h'a0').
The zero length binary encoding is preferred because it is both shorter and the version used in the serialization structures for cryptographic computation.
After encoding the map, the value is wrapped in the binary object.
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 avoids 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.
With the exception of the COSE_Sign structure, the only data that needs 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" registry (<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>
<t>
Labels in each of the maps MUST be unique.
When processing messages, if a label appears multiple times, the message MUST be rejected as malformed.
Applications SHOULD verify that the same label does not occur in both the protected and unprotected headers.
If the message is not rejected as malformed, attributes MUST be obtained from the protected bucket before they are obtained from the unprotected bucket.
</t>
<t>
The following CDDL fragment represents the two header buckets.
A group Headers is defined in CDDL that represents the two buckets in which attributes are placed.
This group is used to provide these two fields consistently in all locations.
A type is also defined which represents the map of common headers.
</t>
<figure><artwork type="CDDL"><![CDATA[
Headers = (
protected : empty_or_serialized_map,
unprotected : header_map
)
header_map = {
Generic_Headers,
* label => values
}
empty_or_serialized_map = bstr .cbor header_map / bstr .size 0
]]></artwork></figure>
<section anchor="cose-headers" title="Common COSE Headers Parameters">
<t>
This section defines a set of common header parameters.
A summary of these parameters can be found in <xref target="Header-Table"/>.
This table should be consulted to determine the value of label, and 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:'>
<!-- old golden text
This parameter is used to indicate the algorithm used for the security processing.
This parameter MUST be present in the COSE_Signature, COSE_Sign1, COSE_Encrypt, COSE_Encrypt0, COSE_Mac, and COSE_Mac0 structures.
When the algorithm supports authenticating associated data, this parameter MUST be in the protected header bucket.
The value is taken from the "COSE Algorithms" Registry (see <xref target="cose-algorithm-registry"/>).
New messed up text -->
This parameter is used to indicate the algorithm used for the security processing.
This parameter MUST be authenticated where the ability to do so exists.
This support is provided by AEAD algorithms or construction (COSE_Sign, COSE_Sign0, COSE_Mac and COSE_Mac0).
This authentication can be done either by placing the header in the protected header bucket or as part of the externally supplied data.
The value is taken from the "COSE Algorithms" Registry (see <xref target="cose-algorithm-registry"/>).
</t>
<t hangText='crit:'>
The parameter is used to indicate which protected header labels an application that is processing a message is required to understand.
Parameters defined in this document do not need to be included as they should be understood by all implementations.
When present, this parameter MUST be placed in the protected header bucket.
The array MUST have at least one value in it.
<vspace/>
Not all labels need to be included in the 'crit' parameter.
The rules for deciding which header labels are placed in the array are:
<list style="symbols">
<t>Integer labels in the range of 0 to 8 SHOULD be omitted.</t>
<t>
Integer labels in the range -1 to -128 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 common parameters associated with that algorithm.
Integer labels in the range -129 to -65536 SHOULD be included as these would be less common parameters that might not be generally supported.
</t>
<t>
Labels for parameters required for an application MAY be omitted.
Applications should have a statement if the label can be omitted.
</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 cipher text fields.
Integers are from the "CoAP Content-Formats" IANA registry table <xref target="COAP.Formats"/>.
Text values following the syntax of "<type-name>/<subtype-name>" where <type-name> and <subtype-name> are defined in Section 4.2 of <xref target="RFC6838"/>.
Leading and trailing whitespace is also omitted.
Textual content values along with parameters and subparameters can be located using the IANA "Media Types" registry.
Applications SHOULD provide this parameter if the content structure is potentially ambiguous.
</t>
<t hangText='kid:'>
This parameter identifies one piece of data that can be used as input to find the needed cryptographic key.
The value of this parameter can be matched against the 'kid' member in a COSE_Key structure.
Other methods of key distribution can define an equivalent field to be matched.
Applications MUST NOT assume that 'kid' values are unique.
There may be more than one key with the same 'kid' value, so all of the keys associated with this 'kid' may need to be checked.
The internal structure of 'kid' values is not defined and cannot be relied on by applications.
Key identifier values are hints about which key to use.
This is not a security critical field.
For this reason, it can be placed in the unprotected headers bucket.
</t>
<t hangText="IV:">
This parameter holds the Initialization Vector (IV) value.
For some symmetric encryption algorithms this may be referred to as a nonce.
The IV can be placed in the unprotected header as modifying the IV will cause the decryption to yield plaintext that is readily detectable as garbled.
</t>
<t hangText='Partial IV'>
This parameter holds a part of the IV value.
When using the COSE_Encrypt0 structure, a portion of the IV can be part of the context associated with the key.
This field is used to carry a value that causes the IV to be changed for each message.
The IV can be placed in the unprotected header as modifying the IV will cause the decryption to yield plaintext that is readily detectable as garbled.
The 'Initialization Vector' and 'Partial Initialization Vector' parameters MUST NOT both be present in the same security layer.
<vspace/>
The message IV is generated by the following steps:
<list style="numbers">
<t>Left pad the partial IV with zeros to the length of IV.</t>
<t>XOR the padded partial IV with the context IV.</t>
</list>
</t>
<t hangText='counter signature:'>
This parameter holds one or more counter signature values.
Counter signatures provide a method of having a second party sign some data.
The counter signature parameter can occur as an unprotected attribute in any of the following structures: COSE_Sign1, COSE_Signature, COSE_Encrypt, COSE_recipient, COSE_Encrypt0, COSE_Mac and COSE_Mac0.
These structures all have the same beginning elements 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>
<!--
Removed following IETF 95
<t hangText='operation time'>
This parameter provides the time the content cryptographic operation is performed.
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 structure was created.
The unsigned integer value is the number of seconds, excluding leap seconds, after midnight UTC, January 1, 1970.
The field is primarily intended to be to be used for counter signatures, however it can additionally be used for replay detection as well.
</t>
-->
</list>
</t>
<!-- Table 2 -->
<texttable anchor="Header-Table" title="Common Header Parameters">
<ttcol align='left' width='9em'>name</ttcol>
<ttcol align='left' width='5em'>label</ttcol>
<ttcol align='left' width='14em'>value type</ttcol>
<ttcol align='left' width='11em'>value registry</ttcol>
<ttcol align='left'>description</ttcol>
<c>alg</c> <c>1</c> <c>int / tstr</c> <c>COSE Algorithms registry</c> <c>Cryptographic algorithm to use</c>
<c>crit</c> <c>2</c> <c>[+ label]</c> <c>COSE Header Labels registry</c> <c>Critical headers to be understood</c>
<c>content type</c> <c>3</c> <c>tstr / uint</c> <c>CoAP Content-Formats or Media Types registry</c> <c>Content type of the payload</c>
<c>kid</c> <c>4</c> <c>bstr</c> <c></c> <c>Key identifier</c>
<c>IV</c> <c>5</c> <c>bstr</c> <c></c> <c>Full Initialization Vector</c>
<c>Partial IV</c> <c>6</c> <c>bstr</c> <c></c> <c>Partial Initialization Vector</c>
<c>counter signature</c> <c>7</c> <c>COSE_Signature / [+ COSE_Signature ]</c> <c></c> <c>CBOR encoded signature structure</c>
<!--
Removed following IETF 95
<c>operation time</c><c>8</c> <c>uint</c> <c></c> <c>Time the COSE structure was created</c>
-->
</texttable>
<t>
The CDDL fragment that represents the set of headers defined in this section is given below.
Each of the headers is tagged as optional because they do not need to be in every map; headers required in specific maps are discussed above.
</t>
<figure><artwork type="CDDL"><![CDATA[
Generic_Headers = (
? 1 => int / tstr, ; algorithm identifier
? 2 => [+label], ; criticality
? 3 => tstr / int, ; content type
? 4 => bstr, ; key identifier
? 5 => bstr, ; IV
? 6 => bstr, ; Partial IV
? 7 => COSE_Signature / [+COSE_Signature] ; Counter signature
)
]]></artwork></figure>
</section>
</section>
<section anchor="signing-structure" title="Signing Objects">
<t>
COSE supports two different signature structures.
COSE_Sign allows for one or more signatures to be applied to the same content.
<!-- COSE_Sign allows for one or more signers to be applied to a single content. -->
COSE_Sign1 is restricted to a single signer.
The structures cannot be converted between each other; as the signature computation includes a parameter identifying which structure is being used, the converted structure will fail signature validation.
</t>
<section title="Signing with One or More Signers" anchor="full-signature">
<t>
The COSE_Sign 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.-->
Parameters relating to the content and parameters relating to the signature are carried along with the signature itself.
These parameters may be authenticated by the signature, or just present.
An example of a parameter about the content is the content type.
Examples of parameters about the signature would be the algorithm and key used to create the signature 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 for 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 Edwards Digital Signature Algorithm (EdDSA) <xref target="I-D.irtf-cfrg-eddsa"/> signature algorithm and with the Elliptic Curve Digital Signature Algorithm (ECDSA) <xref target="DSS"/> 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 signature structure can be encoded either as tagged or untagged depending on the context it will be used in.
A tagged COSE_Sign structure is identified by the CBOR tag TBD1.
The CDDL fragment that represents this is:
</t>
<!-- RFC EDITOR
The comment in the line below is a request for an action to occur.
Additionally, the comment is to be removed at the same time.
This action needs to occur in the other locations that are similarly marked
-->
<figure><artwork type="CDDL"><![CDATA[
COSE_Sign_Tagged = #6.98(COSE_Sign)
]]></artwork></figure>
<t>
A COSE Signed Message is defined in two parts.
The CBOR object that carries the body and information about the body is called the COSE_Sign structure.
The CBOR object that carries the signature and information about the signature is called the COSE_Signature structure.
Examples of COSE Signed Messages can be found in <xref target="SignedExamples"/>.
</t>
<t>
The COSE_Sign 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 signed security service.
The value MUST be msg_type_signed (1).
</t>
-->
<t hangText='protected'>
as described in <xref target="header-parameters"/>.
</t>
<t hangText='unprotected'>
as 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 ("detached content"), 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.
<vspace blankLines="1"/>
Note: When a signature with message recovery algorithm is used (<xref target="SigAlgs"/>), the maximum number of bytes that can be recovered is the length of the payload.
The size of the payload is reduced by the number of bytes that will be recovered.
If all of the bytes of the payload are consumed, then the payload is encoded as a zero length binary string rather than as being absent.
</t>
<t hangText='signatures'>
is an array of signatures.
Each signature is represented as a COSE_Signature structure.
</t>
</list>
</t>
<t>
The CDDL fragment that represents the above text for COSE_Sign follows.
</t>
<figure><artwork type="CDDL"><![CDATA[
COSE_Sign = [
Headers,
payload : bstr / nil,
signatures : [+ COSE_Signature]
]
]]></artwork></figure>
<t>
The COSE_Signature structure is a CBOR array.
The fields of the array in order are:
<list style="hanging">
<t hangText='protected'>
as described in <xref target="header-parameters"/>.
</t>
<t hangText='unprotected'>
as described in <xref target="header-parameters"/>.
</t>
<t hangText='signature'>
contains the computed signature value.
The type of the field is a bstr.
Algorithms MUST specify padding if the signature value is not a multiple of 8 bits.
</t>
</list>
</t>
<t>
The CDDL fragment that represents the above text for COSE_Signature follows.
</t>
<figure><artwork type="CDDL"><![CDATA[
COSE_Signature = [
Headers,
signature : bstr
]
]]></artwork></figure>
</section>
<section title="Signing with One Signer">
<t>
The COSE_Sign1 signature structure is used when only one signature is going to be placed on a message.
The parameters dealing with the content and the signature are placed in the same pair of buckets rather than having the separation of COSE_Sign.
</t>
<t>
The structure can be encoded either tagged or untagged depending on the context it will be used in.
A tagged COSE_Sign1 structure is identified by the CBOR tag TBD7.
The CDDL fragment that represents this is:
</t>
<figure><artwork type="CDDL"><![CDATA[
COSE_Sign1_Tagged = #6.18(COSE_Sign1)
]]></artwork></figure>
<t>
The CBOR object that carries the body, the signature, and the information about the body and signature is called the COSE_Sign1 structure.
Examples of COSE_Sign1 messages can be found in <xref target="Sign1_Examples"/>.
</t>
<t>
The COSE_Sign1 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 signed security service.
The value MUST be msg_type_signed (1).
</t>
-->
<t hangText='protected'>
as described in <xref target="header-parameters"/>.
</t>
<t hangText='unprotected'>
as described in <xref target="header-parameters"/>.
</t>
<t hangText='payload'>
as described in <xref target="full-signature"/>.
</t>
<t hangText='signature'>
contains the computed signature value.
The type of the field is a bstr.
</t>
</list>
</t>
<t>
The CDDL fragment that represents the above text for COSE_Sign1 follows.
</t>
<figure><artwork type="CDDL"><![CDATA[
COSE_Sign1 = [
Headers,
payload : bstr / nil,
signature : bstr
]
]]></artwork></figure>
</section>
<section title="Externally Supplied Data" anchor="Extern_AAD">
<t>
One of the features offered in the COSE document is the ability for applications to provide additional data to be authenticated, 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.
Examples of data that can be placed in this location would be the CoAP code or CoAP options.
If the data is in the header section, then it is available for proxies to help in performing its operations.
For example, the Accept Option can be used by a proxy to determine if an appropriate value is in the Proxy's cache.
But the sender can prevent a proxy from changing the set of values that it will accept by including that value in the resulting authentication tag.
However, it may also be desired to protect these values so that if they are modified in transit, it can be detected.
</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 that 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, applications need to ensure that the same byte string is not produced if there are different inputs.
This could occur by appending the strings 'AB' and 'CDE' or by appending the strings 'ABC' and 'DE'.
This is usually addressed by making fields a fixed width and/or encoding the length of the field as part of the output.
Using options from CoAP <xref target="RFC7252"/> as an example, these fields use a TLV structure so they can be concatenated without any problems.
</t>
<t>
If multiple items are included, an 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>
<t>
Applications need to ensure that the byte stream is going to be the same on both sides.
Using options from CoAP might give a problem if the same relative numbering is kept.
An intermediate node could insert or remove an option, changing how the relative number is done.
An application would need to specify that the relative number must be re-encoded to be relative only to the options that are in the external data.