-
Notifications
You must be signed in to change notification settings - Fork 4
/
draft-ietf-cose-rfc8152bis-algs.xml
2248 lines (1968 loc) · 119 KB
/
draft-ietf-cose-rfc8152bis-algs.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'?>
<!DOCTYPE rfc SYSTEM "rfc2629-xhtml.ent" [
<!ENTITY SigSection "9.1">
<!ENTITY MacSection "9.2">
<!ENTITY ContentSection "9.3">
<!ENTITY KDFSection "9.4">
<!ENTITY CKeyDistributeSection "9.5">
<!ENTITY DirectDistribute "9.5.1">
<!ENTITY KeyWrap "9.5.2">
]>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<?rfc toc="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc comments="yes"?>
<rfc xmlns:xi="http://www.w3.org/2001/XInclude" ipr="trust200902" category="info" docName="draft-ietf-cose-rfc8152bis-algs-11" obsoletes="8152" submissionType="IETF" version="3" consensus="true">
<!-- xml2rfc v2v3 conversion 2.24.0 -->
<front>
<title abbrev="COSE Algorithms">
CBOR Object Signing and Encryption (COSE): Initial Algorithms
</title>
<seriesInfo name="Internet-Draft" value="draft-ietf-cose-rfc8152bis-algs-11"/>
<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 a 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 a set of algorithms that can be used with the CBOR Object Signing and Encryption (COSE) protocol RFC XXXX. <!-- <xref target="I-D.ietf-cose-rfc8152bis-struct"/>.-->
</t>
</abstract>
<note removeInRFC="true">
<name>Contributing to this document</name>
<!-- 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-rfc8152bis"/>.
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">
<name>Introduction</name>
<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 "Concise Binary Object Representation (CBOR)" <xref target="RFC7049"/>.
CBOR extended the data model of JavaScript Object Notation (JSON) <xref target="STD90"/> 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 transported and implementation size and be 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 core COSE specification consists of two documents.
<xref target="I-D.ietf-cose-rfc8152bis-struct"/> contains the serialization structures and the procedures for using the different cryptographic algorithms.
This document provides an initial set of algorithms for use with those structures.
</t>
<section anchor="requirements-terminology">
<name>Requirements Terminology</name>
<t>
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED",
"MAY", and "OPTIONAL" in this document are to be interpreted as
described in BCP 14 <xref target="RFC2119"/> <xref target="RFC8174"/> when, and only when, they
appear in all capitals, as shown here.
</t>
</section>
<section>
<name>Changes from RFC8152</name>
<ul>
<li>
Extract the sections dealing with specific algorithms into this document.
The sections dealing with structure and general processing rules are placed in <xref target="I-D.ietf-cose-rfc8152bis-struct"/>.
</li>
<li>Text clarifications and changes in terminology.</li>
</ul>
</section>
<section>
<name>Document Terminology</name>
<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 encryption algorithms that provide an authentication check of the contents with the encryption service.
An example of an AE algorithm used in COSE is AES Key Wrap <xref target="RFC3394"/>.
These algorithms are used for key encryption algorithms, but AEAD algorithms would be preferred.
</t>
<t>
Authenticated Encryption with Associated Data (AEAD) <xref target="RFC5116"/> algorithms provide the same authentication service of the content as AE algorithms do.
They also allow for associated data to be included in the authentication service, but which is not part of the encrypted body.
An example of an AEAD algorithm used in COSE is AES-GCM <xref target="RFC5116"/>.
These algorithms are used for content encryption and can be used for key encryption as well.
</t>
<t>The term 'byte string' is used for sequences of bytes, while the term 'text string' is used for sequences of characters.</t>
<t>
The tables for algorithms contain the following columns:
</t>
<ul>
<li>A name for use in documents for the algorithms.</li>
<li>
The value used on the wire for the algorithm.
One place this is used is the algorithm header parameter of a message.
</li>
<li>A short description so that the algorithm can be easily identified when scanning the IANA registry.</li>
</ul>
<t>
Additional columns may be present in the table depending on the algorithms.
</t>
</section>
<section>
<name>CBOR Grammar</name>
<t>
At the time that <xref target="RFC8152"/> was initially published, the CBOR Data Definition Language (CDDL) <xref target="RFC8610"/> had not yet been published.
This document uses a variant of CDDL which is described in <xref target="I-D.ietf-cose-rfc8152bis-struct"/>.
</t>
</section>
<section anchor="examples">
<name>Examples</name>
<t>
A GitHub project has been created at <xref target="GitHub-Examples"/> that contains a set of testing examples as well.
Each example is found in a JSON file that contains the inputs used to create the example, some of the intermediate values that can be used for debugging, and the output of the example.
The results are encoded using both hexadecimal and CBOR diagnostic notation format.
</t>
<t>
Some of the examples are designed to test failure case; these are clearly marked as such in the JSON file.
If errors in the examples in this document are found, the examples on GitHub will be updated, and a note to that effect will be placed in the JSON file.
</t>
</section>
</section>
<section anchor="SigAlgs">
<name>Signature Algorithms</name>
<t>
<relref section="&SigSection;" target="I-D.ietf-cose-rfc8152bis-struct"/> contains a generic description of signature algorithms.
The document defines signature algorithm identifiers for two signature algorithms.
</t>
<section anchor="ECDSA">
<name>ECDSA</name>
<t>ECDSA <xref target="DSS"/> defines a signature algorithm using ECC. Implementations <bcp14>SHOULD</bcp14> use a deterministic version of ECDSA such as the one defined in <xref target="RFC6979"/>. The use of a deterministic signature algorithm allows for systems to avoid relying on random number generators in order to avoid generating the same value of 'k' (the per-message random value). Biased generation of the value 'k' can be attacked, and collisions of this value leads to leaked keys. It additionally allows for doing deterministic tests for the signature algorithm. The use of deterministic ECDSA does not lessen the need to have good random number generation when creating the private key. </t>
<t>The ECDSA signature algorithm is parameterized with a hash function (h). In the event that the length of the hash function output is greater than the group of the key, the leftmost bytes of the hash output are used. </t>
<t>The algorithms defined in this document can be found in <xref target="x-table_ecdsa"/>. </t>
<table anchor="x-table_ecdsa" align="center">
<name>ECDSA Algorithm Values</name>
<thead>
<tr>
<th>Name</th>
<th>Value</th>
<th>Hash</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>ES256</td>
<td>-7</td>
<td>SHA-256</td>
<td>ECDSA w/ SHA-256</td>
</tr>
<tr>
<td>ES384</td>
<td>-35</td>
<td>SHA-384</td>
<td>ECDSA w/ SHA-384</td>
</tr>
<tr>
<td>ES512</td>
<td>-36</td>
<td>SHA-512</td>
<td>ECDSA w/ SHA-512</td>
</tr>
</tbody>
</table>
<t>This document defines ECDSA to work only with the curves P-256, P-384, and P-521. This document requires that the curves be encoded using the 'EC2' (two coordinate elliptic curve) key type. Implementations need to check that the key type and curve are correct when creating and verifying a signature. Future documents may define it to work with other curves and points in the future. </t>
<t>In order to promote interoperability, it is suggested that SHA-256 be used only with curve P-256, SHA-384 be used only with curve P-384, and SHA-512 be used with curve P-521. This is aligned with the recommendation in Section 4 of <xref target="RFC5480"/>. </t>
<t>
The signature algorithm results in a pair of integers (R, S).
These integers will be the same length as the length of the key used for the signature process.
The signature is encoded by converting the integers into byte strings of the same length as the key size.
The length is rounded up to the nearest byte and is left padded with zero bits to get to the correct length.
The two integers are then concatenated together to form a byte string that is the resulting signature.
</t>
<t>
Using the function defined in <xref target="RFC8017"/>, the signature is:
</t>
<t>
Signature = I2OSP(R, n) | I2OSP(S, n)
</t>
<t>
where n = ceiling(key_length / 8)
</t>
<t>When using a COSE key for this algorithm, the following checks are made:
</t>
<ul>
<li>The 'kty' field <bcp14>MUST</bcp14> be present, and it <bcp14>MUST</bcp14> be 'EC2'.</li>
<li>If the 'alg' field is present, it <bcp14>MUST</bcp14> match the ECDSA signature algorithm being used.</li>
<li>If the 'key_ops' field is present, it <bcp14>MUST</bcp14> include 'sign' when creating an ECDSA signature.</li>
<li>If the 'key_ops' field is present, it <bcp14>MUST</bcp14> include 'verify' when verifying an ECDSA signature.</li>
</ul>
<section>
<name>Security Considerations for ECDSA</name>
<t>The security strength of the signature is no greater than the minimum of the security strength associated with the bit length of the key and the security strength of the hash function. </t>
<t>
Note: Use of a deterministic signature technique is a good idea even when good random number generation exists.
Doing so both reduces the possibility of having the same value of 'k' in two signature operations and allows for reproducible signature values, which helps testing.
There have been recent attacks involving faulting the device in order to extract the key.
This can be addressed by combining both randomness and determinism <xref target="I-D.mattsson-cfrg-det-sigs-with-noise"/>.
</t>
<t>There are two substitution attacks that can theoretically be mounted against the ECDSA signature algorithm.
</t>
<ul>
<li>Changing the curve used to validate the signature: If one changes the curve used to validate the signature, then potentially one could have two messages with the same signature, each computed under a different curve. The only requirement on the new curve is that its order be the same as the old one and it be acceptable to the client. An example would be to change from using the curve secp256r1 (aka P-256) to using secp256k1. (Both are 256-bit curves.) We currently do not have any way to deal with this version of the attack except to restrict the overall set of curves that can be used. </li>
<li>Change the hash function used to validate the signature: If one either has two different hash functions of the same length or can truncate a hash function, then one could potentially find collisions between the hash functions rather than within a single hash function (for example, truncating SHA-512 to 256 bits might collide with a SHA-256 bit hash value). As the hash algorithm is part of the signature algorithm identifier, this attack is mitigated by including a signature algorithm identifier in the protected header bucket. </li>
</ul>
</section>
</section>
<section>
<name>Edwards-Curve Digital Signature Algorithms (EdDSAs)</name>
<t><xref target="RFC8032"/> describes the elliptic curve signature scheme Edwards-curve Digital Signature Algorithm (EdDSA). In that document, the signature algorithm is instantiated using parameters for edwards25519 and edwards448 curves. The document additionally describes two variants of the EdDSA algorithm: Pure EdDSA, where no hash function is applied to the content before signing, and HashEdDSA, where a hash function is applied to the content before signing and the result of that hash function is signed. For EdDSA, the content to be signed (either the message or the pre-hash value) is processed twice inside of the signature algorithm. For use with COSE, only the pure EdDSA version is used. This is because it is not expected that extremely large contents are going to be needed and, based on the arrangement of the message structure, the entire message is going to need to be held in memory in order to create or verify a signature. This means that there does not appear to be a need to be able to do block updates of the hash, followed by eliminating the message from memory. Applications can provide the same features by defining the content of the message as a hash value and transporting the COSE object (with the hash value) and the content as separate items. </t>
<t>The algorithms defined in this document can be found in <xref target="x-table-eddsa-algs"/>. A single signature algorithm is defined, which can be used for multiple curves. </t>
<table anchor="x-table-eddsa-algs" align="center">
<name>EdDSA Algorithm Values</name>
<thead>
<tr>
<th>Name</th>
<th>Value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>EdDSA</td>
<td>-8</td>
<td>EdDSA</td>
</tr>
</tbody>
</table>
<t><xref target="RFC8032"/> describes the method of encoding the signature value. </t>
<t>When using a COSE key for this algorithm, the following checks are made:
</t>
<ul>
<li>The 'kty' field <bcp14>MUST</bcp14> be present, and it <bcp14>MUST</bcp14> be 'OKP' (Octet Key Pair). </li>
<li>The 'crv' field <bcp14>MUST</bcp14> be present, and it <bcp14>MUST</bcp14> be a curve defined for this signature algorithm.</li>
<li>If the 'alg' field is present, it <bcp14>MUST</bcp14> match 'EdDSA'.</li>
<li>If the 'key_ops' field is present, it <bcp14>MUST</bcp14> include 'sign' when creating an EdDSA signature.</li>
<li>If the 'key_ops' field is present, it <bcp14>MUST</bcp14> include 'verify' when verifying an EdDSA signature.</li>
</ul>
<section>
<name>Security Considerations for EdDSA</name>
<t>How public values are computed is not the same when looking at EdDSA and Elliptic Curve Diffie-Hellman (ECDH); for this reason, the public key should not be used with the other algorithm. </t>
<t>If batch signature verification is performed, a well-seeded cryptographic random number generator is <bcp14>REQUIRED</bcp14> (<relref target="RFC8032" section="8.2"/>). Signing and non-batch signature verification are deterministic operations and do not need random numbers of any kind. </t>
</section>
</section>
</section>
<section>
<name>Message Authentication Code (MAC) Algorithms</name>
<t>
<relref section="&MacSection;" target="I-D.ietf-cose-rfc8152bis-struct"/> contains a generic description of MAC algorithms.
This section defines the conventions for two MAC algorithms.
</t>
<section>
<name>Hash-Based Message Authentication Codes (HMACs)</name>
<t>HMAC <xref target="RFC2104"/> <xref target="RFC4231"/> was designed to deal with length extension attacks. The algorithm was also designed to allow for new hash algorithms to be directly plugged in without changes to the hash function. The HMAC design process has been shown as solid since, while the security of hash algorithms such as MD5 has decreased over time; the security of HMAC combined with MD5 has not yet been shown to be compromised <xref target="RFC6151"/>. </t>
<t>The HMAC algorithm is parameterized by an inner and outer padding, a hash function (h), and an authentication tag value length. For this specification, the inner and outer padding are fixed to the values set in <xref target="RFC2104"/>. The length of the authentication tag corresponds to the difficulty of producing a forgery. For use in constrained environments, we define one HMAC algorithm that is truncated. There are currently no known issues with truncation; however, the security strength of the message tag is correspondingly reduced in strength. When truncating, the leftmost tag length bits are kept and transmitted. </t>
<t>The algorithms defined in this document can be found in <xref target="x-table-hmac"/>. </t>
<table anchor="x-table-hmac" align="center">
<name>HMAC Algorithm Values</name>
<thead>
<tr>
<th>Name</th>
<th>Value</th>
<th>Hash</th>
<th>Tag Length</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>HMAC 256/64</td>
<td>4</td>
<td>SHA-256</td>
<td>64</td>
<td>HMAC w/ SHA-256 truncated to 64 bits</td>
</tr>
<tr>
<td>HMAC 256/256</td>
<td>5</td>
<td>SHA-256</td>
<td>256</td>
<td>HMAC w/ SHA-256</td>
</tr>
<tr>
<td>HMAC 384/384</td>
<td>6</td>
<td>SHA-384</td>
<td>384</td>
<td>HMAC w/ SHA-384</td>
</tr>
<tr>
<td>HMAC 512/512</td>
<td>7</td>
<td>SHA-512</td>
<td>512</td>
<td>HMAC w/ SHA-512</td>
</tr>
</tbody>
</table>
<t>Some recipient algorithms transport the key, while others derive a key from secret data. For those algorithms that transport the key (such as AES Key Wrap), the size of the HMAC key <bcp14>SHOULD</bcp14> be the same size as the output of the underlying hash function. For those algorithms that derive the key (such as ECDH), the derived key <bcp14>MUST</bcp14> be the same size as the underlying hash function. </t>
<t>When using a COSE key for this algorithm, the following checks are made:
</t>
<ul>
<li>The 'kty' field <bcp14>MUST</bcp14> be present, and it <bcp14>MUST</bcp14> be 'Symmetric'.</li>
<li>If the 'alg' field is present, it <bcp14>MUST</bcp14> match the HMAC algorithm being used.</li>
<li>If the 'key_ops' field is present, it <bcp14>MUST</bcp14> include 'MAC create' when creating an HMAC authentication tag.</li>
<li>If the 'key_ops' field is present, it <bcp14>MUST</bcp14> include 'MAC verify' when verifying an HMAC authentication tag.</li>
</ul>
<t>Implementations creating and validating MAC values <bcp14>MUST</bcp14> validate that the key type, key length, and algorithm are correct and appropriate for the entities involved. </t>
<section>
<name>Security Considerations for HMAC</name>
<t>HMAC has proved to be resistant to attack even when used with weakened hash algorithms. The current best known attack is to brute force the key. This means that key size is going to be directly related to the security of an HMAC operation. </t>
</section>
</section>
<section>
<name>AES Message Authentication Code (AES-CBC-MAC)</name>
<t>AES-CBC-MAC is defined in <xref target="MAC"/>. (Note that this is not the same algorithm as AES Cipher-Based Message Authentication Code (AES-CMAC) <xref target="RFC4493"/>.) </t>
<t>AES-CBC-MAC is parameterized by the key length, the authentication tag length, and the Initialization Vector (IV) used. For all of these algorithms, the IV is fixed to all zeros. We provide an array of algorithms for various key lengths and tag lengths. The algorithms defined in this document are found in <xref target="x-table-aes-mac"/>. </t>
<table anchor="x-table-aes-mac" align="center">
<name>AES-MAC Algorithm Values</name>
<thead>
<tr>
<th>Name</th>
<th>Value</th>
<th>Key Length</th>
<th>Tag Length</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>AES-MAC 128/64</td>
<td>14</td>
<td>128</td>
<td>64</td>
<td>AES-MAC 128-bit key, 64-bit tag</td>
</tr>
<tr>
<td>AES-MAC 256/64</td>
<td>15</td>
<td>256</td>
<td>64</td>
<td>AES-MAC 256-bit key, 64-bit tag</td>
</tr>
<tr>
<td>AES-MAC 128/128</td>
<td>25</td>
<td>128</td>
<td>128</td>
<td>AES-MAC 128-bit key, 128-bit tag</td>
</tr>
<tr>
<td>AES-MAC 256/128</td>
<td>26</td>
<td>256</td>
<td>128</td>
<td>AES-MAC 256-bit key, 128-bit tag</td>
</tr>
</tbody>
</table>
<t>Keys may be obtained either from a key structure or from a recipient structure. Implementations creating and validating MAC values <bcp14>MUST</bcp14> validate that the key type, key length, and algorithm are correct and appropriate for the entities involved. </t>
<t>When using a COSE key for this algorithm, the following checks are made:
</t>
<ul>
<li>The 'kty' field <bcp14>MUST</bcp14> be present, and it <bcp14>MUST</bcp14> be 'Symmetric'.</li>
<li>If the 'alg' field is present, it <bcp14>MUST</bcp14> match the AES-MAC algorithm being used.</li>
<li>If the 'key_ops' field is present, it <bcp14>MUST</bcp14> include 'MAC create' when creating an AES-MAC authentication tag.</li>
<li>If the 'key_ops' field is present, it <bcp14>MUST</bcp14> include 'MAC verify' when verifying an AES-MAC authentication tag.</li>
</ul>
<section>
<name>Security Considerations AES-CBC_MAC </name>
<t>A number of attacks exist against Cipher Block Chaining Message Authentication Code (CBC-MAC) that need to be considered.
</t>
<ul>
<li>A single key must only be used for messages of a fixed or known length. If this is not the case, an attacker will be able to generate a message with a valid tag given two message and tag pairs. This can be addressed by using different keys for messages of different lengths.
The current structure mitigates this problem, as a specific encoding structure that includes lengths is built and signed. (CMAC also addresses this issue.) </li>
<li>In cipher Block Chaining (CBC) mode, if the same key is used for both encryption and authentication operations, an attacker can produce messages with a valid authentication code. </li>
<li>If the IV can be modified, then messages can be forged. This is addressed by fixing the IV to all zeros. </li>
</ul>
</section>
</section>
</section>
<section>
<name>Content Encryption Algorithms</name>
<t>
<relref section="&ContentSection;" target="I-D.ietf-cose-rfc8152bis-struct"/> contains a generic description of Content Encryption algorithms.
This document defines the identifier and usages for three content encryption algorithms.
</t>
<section>
<name>AES GCM</name>
<t>The Galois/Counter Mode (GCM) mode is a generic AEAD block cipher mode defined in <xref target="AES-GCM"/>. The GCM mode is combined with the AES block encryption algorithm to define an AEAD cipher. </t>
<t>The GCM mode is parameterized by the size of the authentication tag and the size of the nonce. This document fixes the size of the nonce at 96 bits. The size of the authentication tag is limited to a small set of values. For this document however, the size of the authentication tag is fixed at 128 bits. </t>
<t>The set of algorithms defined in this document are in <xref target="x-table-AES-GCM"/>. </t>
<table anchor="x-table-AES-GCM" align="center">
<name>Algorithm Value for AES-GCM</name>
<thead>
<tr>
<th>Name</th>
<th>Value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>A128GCM</td>
<td>1</td>
<td>AES-GCM mode w/ 128-bit key, 128-bit tag</td>
</tr>
<tr>
<td>A192GCM</td>
<td>2</td>
<td>AES-GCM mode w/ 192-bit key, 128-bit tag</td>
</tr>
<tr>
<td>A256GCM</td>
<td>3</td>
<td>AES-GCM mode w/ 256-bit key, 128-bit tag</td>
</tr>
</tbody>
</table>
<t>Keys may be obtained either from a key structure or from a recipient structure. Implementations encrypting and decrypting <bcp14>MUST</bcp14> validate that the key type, key length, and algorithm are correct and appropriate for the entities involved. </t>
<t>When using a COSE key for this algorithm, the following checks are made:
</t>
<ul>
<li>The 'kty' field <bcp14>MUST</bcp14> be present, and it <bcp14>MUST</bcp14> be 'Symmetric'.</li>
<li>If the 'alg' field is present, it <bcp14>MUST</bcp14> match the AES-GCM algorithm being used.</li>
<li>If the 'key_ops' field is present, it <bcp14>MUST</bcp14> include 'encrypt' or 'wrap key' when encrypting.</li>
<li>If the 'key_ops' field is present, it <bcp14>MUST</bcp14> include 'decrypt' or 'unwrap key' when decrypting.</li>
</ul>
<section>
<name>Security Considerations for AES-GCM</name>
<t>When using AES-GCM, the following restrictions <bcp14>MUST</bcp14> be enforced:
</t>
<ul>
<li>The key and nonce pair <bcp14>MUST</bcp14> be unique for every message encrypted. </li>
<li>The total number of messages encrypted for a single key <bcp14>MUST NOT</bcp14> exceed 2^32 <xref target="SP800-38d"/>. An explicit check is required only in environments where it is expected that it might be exceeded. </li>
<li>
A more recent analysis in <xref target="ROBUST"/> indicates that the the number of failed decryptions needs to be taken into account as part determining when a key roll-over is to be done.
Following the recommendation of for DTLS, the number of failed message decryptions should be limited to 2^36.
</li>
</ul>
<t>Consideration was given to supporting smaller tag values; the constrained community would desire tag sizes in the 64-bit range. Doing so drastically changes both the maximum messages size (generally not an issue) and the number of times that a key can be used. Given that Counter with CBC-MAC (CCM) is the usual mode for constrained environments, restricted modes are not supported. </t>
</section>
</section>
<section>
<name>AES CCM</name>
<t>CCM is a generic authentication encryption block cipher mode defined in <xref target="RFC3610"/>. The CCM mode is combined with the AES block encryption algorithm to define a commonly used content encryption algorithm used in constrained devices. </t>
<t>The CCM mode has two parameter choices. The first choice is M, the size of the authentication field. The choice of the value for M involves a trade-off between message growth (from the tag) and the probability that an attacker can undetectably modify a message. The second choice is L, the size of the length field. This value requires a trade-off between the maximum message size and the size of the Nonce. </t>
<t>It is unfortunate that the specification for CCM specified L and M as a count of bytes rather than a count of bits. This leads to possible misunderstandings where AES-CCM-8 is frequently used to refer to a version of CCM mode where the size of the authentication is 64 bits and not 8 bits. These values have traditionally been specified as bit counts rather than byte counts. This document will follow the convention of using bit counts so that it is easier to compare the different algorithms presented in this document. </t>
<t>We define a matrix of algorithms in this document over the values of L and M. Constrained devices are usually operating in situations where they use short messages and want to avoid doing recipient-specific cryptographic operations. This favors smaller values of both L and M. Less-constrained devices will want to be able to use larger messages and are more willing to generate new keys for every operation. This favors larger values of L and M. </t>
<t>The following values are used for L:
</t>
<dl newline="false">
<dt>16 bits (2):</dt>
<dd>This limits messages to 2^16 bytes (64 KiB) in length. This is sufficiently long for messages in the constrained world. The nonce length is 13 bytes allowing for 2^104 possible values of the nonce without repeating. </dd>
<dt>64 bits (8):</dt>
<dd>This limits messages to 2^64 bytes in length. The nonce length is 7 bytes allowing for 2^56 possible values of the nonce without repeating. </dd>
</dl>
<t>The following values are used for M:
</t>
<dl newline="false">
<dt>64 bits (8):</dt>
<dd>This produces a 64-bit authentication tag. This implies that there is a 1 in 2^64 chance that a modified message will authenticate. </dd>
<dt>128 bits (16):</dt>
<dd>This produces a 128-bit authentication tag. This implies that there is a 1 in 2^128 chance that a modified message will authenticate. </dd>
</dl>
<table anchor="x-table-AES-CCM" align="center">
<name>Algorithm Values for AES-CCM</name>
<thead>
<tr>
<th>Name</th>
<th>Value</th>
<th>L</th>
<th>M</th>
<th>Key Length</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>AES-CCM-16-64-128</td>
<td>10</td>
<td>16</td>
<td>64</td>
<td>128</td>
<td>AES-CCM mode 128-bit key, 64-bit tag, 13-byte nonce</td>
</tr>
<tr>
<td>AES-CCM-16-64-256</td>
<td>11</td>
<td>16</td>
<td>64</td>
<td>256</td>
<td>AES-CCM mode 256-bit key, 64-bit tag, 13-byte nonce</td>
</tr>
<tr>
<td>AES-CCM-64-64-128</td>
<td>12</td>
<td>64</td>
<td>64</td>
<td>128</td>
<td>AES-CCM mode 128-bit key, 64-bit tag, 7-byte nonce</td>
</tr>
<tr>
<td>AES-CCM-64-64-256</td>
<td>13</td>
<td>64</td>
<td>64</td>
<td>256</td>
<td>AES-CCM mode 256-bit key, 64-bit tag, 7-byte nonce</td>
</tr>
<tr>
<td>AES-CCM-16-128-128</td>
<td>30</td>
<td>16</td>
<td>128</td>
<td>128</td>
<td>AES-CCM mode 128-bit key, 128-bit tag, 13-byte nonce</td>
</tr>
<tr>
<td>AES-CCM-16-128-256</td>
<td>31</td>
<td>16</td>
<td>128</td>
<td>256</td>
<td>AES-CCM mode 256-bit key, 128-bit tag, 13-byte nonce</td>
</tr>
<tr>
<td>AES-CCM-64-128-128</td>
<td>32</td>
<td>64</td>
<td>128</td>
<td>128</td>
<td>AES-CCM mode 128-bit key, 128-bit tag, 7-byte nonce</td>
</tr>
<tr>
<td>AES-CCM-64-128-256</td>
<td>33</td>
<td>64</td>
<td>128</td>
<td>256</td>
<td>AES-CCM mode 256-bit key, 128-bit tag, 7-byte nonce</td>
</tr>
</tbody>
</table>
<t>Keys may be obtained either from a key structure or from a recipient structure. Implementations encrypting and decrypting <bcp14>MUST</bcp14> validate that the key type, key length, and algorithm are correct and appropriate for the entities involved. </t>
<t>When using a COSE key for this algorithm, the following checks are made:
</t>
<ul>
<li>The 'kty' field <bcp14>MUST</bcp14> be present, and it <bcp14>MUST</bcp14> be 'Symmetric'.</li>
<li>If the 'alg' field is present, it <bcp14>MUST</bcp14> match the AES-CCM algorithm being used.</li>
<li>If the 'key_ops' field is present, it <bcp14>MUST</bcp14> include 'encrypt' or 'wrap key' when encrypting.</li>
<li>If the 'key_ops' field is present, it <bcp14>MUST</bcp14> include 'decrypt' or 'unwrap key' when decrypting.</li>
</ul>
<section>
<name>Security Considerations for AES-CCM</name>
<t>When using AES-CCM, the following restrictions <bcp14>MUST</bcp14> be enforced:
</t>
<ul>
<li>The key and nonce pair <bcp14>MUST</bcp14> be unique for every message encrypted. Note that the value of L influences the number of unique nonces. </li>
<li>The total number of times the AES block cipher is used <bcp14>MUST NOT</bcp14> exceed 2^61 operations. This limitation is the sum of times the block cipher is used in computing the MAC value and in performing stream encryption operations. An explicit check is required only in environments where it is expected that it might be exceeded. </li>
<li>
<xref target="I-D.ietf-quic-tls"/> contains an analysis on the use of AES-CCM in that environment.
Based on that reommendation, one should restrict the number of messages encrypted to 2^23.
If one is using the 64-bit tag, then the limits are signficantly smaller if one wants to keep the same integrity limits.
A protocol recommending this needs to analysis what level of integrity is acceptable for the smaller tag size.
It may be that to keep the desired integrity one needs to re-key as often as every 2^7 messages.
</li>
<li>
In addition to the number of messages successfully decrypted, the number of failed decryptions needs to be kept as well.
If the number of failed decryptions exceeds 2^23 then a rekeying operation should occur.
</li>
</ul>
<t><xref target="RFC3610"/> additionally calls out one other consideration of note. It is possible to do a pre-computation attack against the algorithm in cases where portions of the plaintext are highly predictable. This reduces the security of the key size by half. Ways to deal with this attack include adding a random portion to the nonce value and/or increasing the key size used. Using a portion of the nonce for a random value will decrease the number of messages that a single key can be used for. Increasing the key size may require more resources in the constrained device. See Sections 5 and 10 of <xref target="RFC3610"/> for more information. </t>
</section>
</section>
<section>
<name>ChaCha20 and Poly1305</name>
<t>ChaCha20 and Poly1305 combined together is an AEAD mode that is defined in <xref target="RFC8439"/>. This is an algorithm defined to be a cipher that is not AES and thus would not suffer from any future weaknesses found in AES. These cryptographic functions are designed to be fast in software-only implementations. </t>
<t>The ChaCha20/Poly1305 AEAD construction defined in <xref target="RFC8439"/> has no parameterization. It takes a 256-bit key and a 96-bit nonce, as well as the plaintext and additional data as inputs and produces the ciphertext as an option. We define one algorithm identifier for this algorithm in <xref target="x-table-CHACHA"/>. </t>
<table anchor="x-table-CHACHA" align="center">
<name>Algorithm Value for ChaCha20/Poly1305</name>
<thead>
<tr>
<th>Name</th>
<th>Value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>ChaCha20/Poly1305</td>
<td>24</td>
<td>ChaCha20/Poly1305 w/ 256-bit key, 128-bit tag</td>
</tr>
</tbody>
</table>
<t>Keys may be obtained either from a key structure or from a recipient structure. Implementations encrypting and decrypting <bcp14>MUST</bcp14> validate that the key type, key length, and algorithm are correct and appropriate for the entities involved. </t>
<t>When using a COSE key for this algorithm, the following checks are made:
</t>
<ul>
<li>The 'kty' field <bcp14>MUST</bcp14> be present, and it <bcp14>MUST</bcp14> be 'Symmetric'.</li>
<li>If the 'alg' field is present, it <bcp14>MUST</bcp14> match the ChaCha20/Poly1305 algorithm being used.</li>
<li>If the 'key_ops' field is present, it <bcp14>MUST</bcp14> include 'encrypt' or 'wrap key' when encrypting.</li>
<li>If the 'key_ops' field is present, it <bcp14>MUST</bcp14> include 'decrypt' or 'unwrap key' when decrypting.</li>
</ul>
<section>
<name>Security Considerations for ChaCha20/Poly1305</name>
<t>The key and nonce values <bcp14>MUST</bcp14> be a unique pair for every invocation of the algorithm. Nonce counters are considered to be an acceptable way of ensuring that they are unique. </t>
<t>
A more recent analysis in <xref target="ROBUST"/> indicates that the the number of failed decryptions needs to be taken into account as part determining when a key roll-over is to be done.
Following the recommendation of for DTLS, the number of failed message decryptions should be limited to 2^36.
</t>
<t>
<xref target="I-D.ietf-quic-tls"/> recommends that no more than 2^24.5 messages be encrypted under a single key.
</t>
</section>
</section>
</section>
<section>
<name>Key Derivation Functions (KDFs)</name>
<t>
<relref section="&KDFSection;" target="I-D.ietf-cose-rfc8152bis-struct"/> contains a generic description of Key Derivation Functions.
This document defines a single context structure and a single KDF.
These elements are used for all of the recipient algorithms defined in this document that require a KDF process.
These algorithms are defined in Sections <xref target="direct-kdf" format="counter"/>, <xref target="ECDH" format="counter"/>, and <xref target="ECDH-wrap" format="counter"/>.
</t>
<section anchor="HKDF-section">
<name>HMAC-Based Extract-and-Expand Key Derivation Function (HKDF)</name>
<t>The HKDF key derivation algorithm is defined in <xref target="RFC5869"/><xref target="HKDF"/>. </t>
<t>The HKDF algorithm takes these inputs:
</t>
<ul empty="true">
<li>secret -- a shared value that is secret. Secrets may be either previously shared or derived from operations like a Diffie-Hellman (DH) key agreement. </li>
<li>salt -- an optional value that is used to change the generation process. The salt value can be either public or private. If the salt is public and carried in the message, then the 'salt' algorithm header parameter defined in <xref target="HKDF_Alg_Params"/> is used. While <xref target="RFC5869"/> suggests that the length of the salt be the same as the length of the underlying hash value, any positive salt length will improve the security as different key values will be generated. This parameter is protected by being included in the key computation and does not need to be separately authenticated. The salt value does not need to be unique for every message sent. </li>
<li>length -- the number of bytes of output that need to be generated. </li>
<li>context information -- Information that describes the context in which the resulting value will be used. Making this information specific to the context in which the material is going to be used ensures that the resulting material will always be tied to that usage. The context structure defined in <xref target="context"/> is used by the KDFs in this document. </li>
<li>PRF -- The underlying pseudorandom function to be used in the HKDF algorithm. The PRF is encoded into the HKDF algorithm selection. </li>
</ul>
<t>HKDF is defined to use HMAC as the underlying PRF. However, it is possible to use other functions in the same construct to provide a different KDF that is more appropriate in the constrained world. Specifically, one can use AES-CBC-MAC as the PRF for the expand step, but not for the extract step. When using a good random shared secret of the correct length, the extract step can be skipped. For the AES algorithm versions, the extract step is always skipped. </t>
<t>The extract step cannot be skipped if the secret is not uniformly random, for example, if it is the result of an ECDH key agreement step. This implies that the AES HKDF version cannot be used with ECDH. If the extract step is skipped, the 'salt' value is not used as part of the HKDF functionality. </t>
<t>The algorithms defined in this document are found in <xref target="x-table-hkdf"/>. </t>
<table anchor="x-table-hkdf" align="center">
<name>HKDF Algorithms</name>
<thead>
<tr>
<th>Name</th>
<th>PRF</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>HKDF SHA-256</td>
<td>HMAC with SHA-256</td>
<td>HKDF using HMAC SHA-256 as the PRF</td>
</tr>
<tr>
<td>HKDF SHA-512</td>
<td>HMAC with SHA-512</td>
<td>HKDF using HMAC SHA-512 as the PRF</td>
</tr>
<tr>
<td>HKDF AES-MAC-128</td>
<td>AES-CBC-MAC-128</td>
<td>HKDF using AES-MAC as the PRF w/ 128-bit key</td>
</tr>
<tr>
<td>HKDF AES-MAC-256</td>
<td>AES-CBC-MAC-256</td>
<td>HKDF using AES-MAC as the PRF w/ 256-bit key</td>
</tr>
</tbody>
</table>
<table anchor="HKDF_Alg_Params" align="center">
<name>HKDF Algorithm Parameters</name>
<thead>
<tr>
<th>Name</th>
<th>Label</th>
<th>Type</th>
<th>Algorithm</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>salt</td>
<td>-20</td>
<td>bstr</td>
<td>direct+HKDF-SHA-256, direct+HKDF-SHA-512, direct+HKDF-AES-128, direct+HKDF-AES-256, ECDH-ES+HKDF-256, ECDH-ES+HKDF-512, ECDH-SS+HKDF-256, ECDH-SS+HKDF-512, ECDH-ES+A128KW, ECDH-ES+A192KW, ECDH-ES+A256KW, ECDH-SS+A128KW, ECDH-SS+A192KW, ECDH-SS+A256KW </td>
<td>Random salt</td>
</tr>
</tbody>
</table>
</section>
<section anchor="context">
<name>Context Information Structure</name>
<t>The context information structure is used to ensure that the derived keying material is "bound" to the context of the transaction. The context information structure used here is based on that defined in <xref target="SP800-56A"/>. By using CBOR for the encoding of the context information structure, we automatically get the same type and length separation of fields that is obtained by the use of ASN.1. This means that there is no need to encode the lengths for the base elements, as it is done by the encoding used in JOSE (Section 4.6.2 of <xref target="RFC7518"/>). </t>
<t>The context information structure refers to PartyU and PartyV as the two parties that are doing the key derivation. Unless the application protocol defines differently, we assign PartyU to the entity that is creating the message and PartyV to the entity that is receiving the message. By doing this association, different keys will be derived for each direction as the context information is different in each direction. </t>
<t>The context structure is built from information that is known to both entities. This information can be obtained from a variety of sources:
</t>
<ul>
<li>Fields can be defined by the application. This is commonly used to assign fixed names to parties, but it can be used for other items such as nonces. </li>
<li>Fields can be defined by usage of the output. Examples of this are the algorithm and key size that are being generated. </li>
<li>Fields can be defined by parameters from the message. We define a set of header parameters in <xref target="KDF_Context_Alg_Params"/> that can be used to carry the values associated with the context structure. Examples of this are identities and nonce values. These header parameters are designed to be placed in the unprotected bucket of the recipient structure; they do not need to be in the protected bucket since they already are included in the cryptographic computation by virtue of being included in the context structure. </li>
</ul>
<table anchor="KDF_Context_Alg_Params" align="center">
<name>Context Algorithm Parameters</name>
<thead>
<tr>
<th>Name</th>
<th>Label</th>
<th>Type</th>
<th>Algorithm</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>PartyU identity</td>
<td>-21</td>
<td>bstr</td>
<td>direct+HKDF-SHA-256, direct+HKDF-SHA-512, direct+HKDF-AES-128, direct+HKDF-AES-256, ECDH-ES+HKDF-256, ECDH-ES+HKDF-512, ECDH-SS+HKDF-256, ECDH-SS+HKDF-512, ECDH-ES+A128KW, ECDH-ES+A192KW, ECDH-ES+A256KW, ECDH-SS+A128KW, ECDH-SS+A192KW, ECDH-SS+A256KW </td>
<td>Party U identity information</td>
</tr>
<tr>
<td>PartyU nonce</td>
<td>-22</td>
<td>bstr / int</td>
<td>direct+HKDF-SHA-256, direct+HKDF-SHA-512, direct+HKDF-AES-128, direct+HKDF-AES-256, ECDH-ES+HKDF-256, ECDH-ES+HKDF-512, ECDH-SS+HKDF-256, ECDH-SS+HKDF-512, ECDH-ES+A128KW, ECDH-ES+A192KW, ECDH-ES+A256KW, ECDH-SS+A128KW, ECDH-SS+A192KW, ECDH-SS+A256KW </td>
<td>Party U provided nonce</td>
</tr>
<tr>
<td>PartyU other</td>
<td>-23</td>
<td>bstr</td>
<td>direct+HKDF-SHA-256, direct+HKDF-SHA-512, direct+HKDF-AES-128, direct+HKDF-AES-256, ECDH-ES+HKDF-256, ECDH-ES+HKDF-512, ECDH-SS+HKDF-256, ECDH-SS+HKDF-512, ECDH-ES+A128KW, ECDH-ES+A192KW, ECDH-ES+A256KW, ECDH-SS+A128KW, ECDH-SS+A192KW, ECDH-SS+A256KW </td>
<td>Party U other provided information</td>
</tr>
<tr>
<td>PartyV identity</td>
<td>-24</td>
<td>bstr</td>
<td>direct+HKDF-SHA-256, direct+HKDF-SHA-512, direct+HKDF-AES-128, direct+HKDF-AES-256, ECDH-ES+HKDF-256, ECDH-ES+HKDF-512, ECDH-SS+HKDF-256, ECDH-SS+HKDF-512, ECDH-ES+A128KW, ECDH-ES+A192KW, ECDH-ES+A256KW, ECDH-SS+A128KW, ECDH-SS+A192KW, ECDH-SS+A256KW </td>
<td>Party V identity information</td>
</tr>
<tr>
<td>PartyV nonce</td>
<td>-25</td>
<td>bstr / int</td>
<td>direct+HKDF-SHA-256, direct+HKDF-SHA-512, direct+HKDF-AES-128, direct+HKDF-AES-256, ECDH-ES+HKDF-256, ECDH-ES+HKDF-512, ECDH-SS+HKDF-256, ECDH-SS+HKDF-512, ECDH-ES+A128KW, ECDH-ES+A192KW, ECDH-ES+A256KW, ECDH-SS+A128KW, ECDH-SS+A192KW, ECDH-SS+A256KW </td>
<td>Party V provided nonce</td>
</tr>
<tr>
<td>PartyV other</td>
<td>-26</td>
<td>bstr</td>
<td>direct+HKDF-SHA-256, direct+HKDF-SHA-512, direct+HKDF-AES-128, direct+HKDF-AES-256, ECDH-ES+HKDF-256, ECDH-ES+HKDF-512, ECDH-SS+HKDF-256, ECDH-SS+HKDF-512, ECDH-ES+A128KW, ECDH-ES+A192KW, ECDH-ES+A256KW, ECDH-SS+A128KW, ECDH-SS+A192KW, ECDH-SS+A256KW </td>
<td>Party V other provided information</td>
</tr>
</tbody>
</table>
<t>We define a CBOR object to hold the context information. This object is referred to as COSE_KDF_Context. The object is based on a CBOR array type. The fields in the array are:
</t>
<dl newline="false">
<dt>AlgorithmID:</dt>
<dd>
This field indicates the algorithm for which the key material will be used.
This normally is either a key wrap algorithm identifier or a content encryption algorithm identifier.
The values are from the "COSE Algorithms" registry.
This field is required to be present.
The field exists in the context information so that a different key is generated for each algorithm even of all of the other context information is the same.
In practice, this means if algorithm A is broken and thus finding the key is relatively easy, the key derived for algorithm B will not be the same as the key derived for algorithm A.
</dd>
<dt>PartyUInfo:</dt>
<dd>
<t>This field holds information about party U. The PartyUInfo is encoded as a CBOR array. The elements of PartyUInfo are encoded in the order presented below. The elements of the PartyUInfo array are:
</t>
<dl newline="false">
<dt>identity:</dt>
<dd>
<t>This contains the identity information for party U. The identities can be assigned in one of two manners. First, a protocol can assign identities based on roles. For example, the roles of "client" and "server" may be assigned to different entities in the protocol. Each entity would then use the correct label for the data they send or receive. The second way for a protocol to assign identities is to use a name based on a naming system (i.e., DNS, X.509 names).
</t>
<t> We define an algorithm parameter 'PartyU identity' that can be used to carry identity information in the message. However, identity information is often known as part of the protocol and can thus be inferred rather than made explicit. If identity information is carried in the message, applications <bcp14>SHOULD</bcp14> have a way of validating the supplied identity information. The identity information does not need to be specified and is set to nil in that case. </t>
</dd>
<dt>nonce:</dt>
<dd>
<t>This contains a nonce value. The nonce can either be implicit from the protocol or be carried as a value in the unprotected header bucket.
</t>
<t> We define an algorithm parameter 'PartyU nonce' that can be used to carry this value in the message; however, the nonce value could be determined by the application and the value determined from elsewhere.
</t>
<t> This option does not need to be specified and is set to nil in that case. </t>
</dd>
<dt>other:</dt>
<dd>This contains other information that is defined by the protocol. This option does not need to be specified and is set to nil in that case. </dd>
</dl>
</dd>
<dt>PartyVInfo:</dt>
<dd>This field holds information about party V. The content of the structure is the same as for the PartyUInfo but for party V. </dd>
<dt>SuppPubInfo:</dt>
<dd>
<t>This field contains public information that is mutually known to both parties.
</t>
<dl newline="false">
<dt>keyDataLength:</dt>
<dd>This is set to the number of bits of the desired output value. This practice means if algorithm A can use two different key lengths, the key derived for longer key size will not contain the key for shorter key size as a prefix. </dd>
<dt>protected:</dt>
<dd>This field contains the protected parameter field. If there are no elements in the protected field, then use a zero-length bstr. </dd>
<dt>other:</dt>
<dd>This field is for free form data defined by the application. An example is that an application could define two different byte strings to be placed here to generate different keys for a data stream versus a control stream. This field is optional and will only be present if the application defines a structure for this information. Applications that define this <bcp14>SHOULD</bcp14> use CBOR to encode the data so that types and lengths are correctly included. </dd>
</dl>
</dd>
<dt>SuppPrivInfo:</dt>
<dd>This field contains private information that is mutually known private information. An example of this information would be a preexisting shared secret. (This could, for example, be used in combination with an ECDH key agreement to provide a secondary proof of identity.) The field is optional and will only be present if the application defines a structure for this information. Applications that define this <bcp14>SHOULD</bcp14> use CBOR to encode the data so that types and lengths are correctly included. </dd>
</dl>
<t>The following CDDL fragment corresponds to the text above. </t>
<artwork type="CDDL" name="" alt=""><![CDATA[
PartyInfo = (
identity : bstr / nil,
nonce : bstr / int / nil,
other : bstr / nil
)
COSE_KDF_Context = [
AlgorithmID : int / tstr,
PartyUInfo : [ PartyInfo ],
PartyVInfo : [ PartyInfo ],
SuppPubInfo : [
keyDataLength : uint,
protected : empty_or_serialized_map,
? other : bstr
],
? SuppPrivInfo : bstr
]
]]></artwork>
</section>
</section>
<section anchor="key-management-algs">
<name>Content Key Distribution Methods</name>
<t>
<relref section="&CKeyDistributeSection;" target="I-D.ietf-cose-rfc8152bis-struct"/> contains a generic description of content key distribution methods.
This document defines the identifiers and usage for a number of content key distribution methods.
</t>
<section>
<name>Direct Encryption</name>
<t>
Direct encryption algorithm is defined in <relref section="&DirectDistribute;" target="I-D.ietf-cose-rfc8152bis-struct"/>.
Information about how to fill in the COSE_Recipient structure are detailed there.
</t>
<section>