-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathdraft-madden-jose-ecdh-1pu-02.html
848 lines (790 loc) · 39.2 KB
/
draft-madden-jose-ecdh-1pu-02.html
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
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html lang="en" xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head profile="http://www.w3.org/2006/03/hcard http://dublincore.org/documents/2008/08/04/dc-html/">
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
<title>Public Key Authenticated Encryption for JOSE: ECDH-1PU</title>
<style type="text/css" title="Xml2Rfc (sans serif)">
/*<![CDATA[*/
a {
text-decoration: none;
}
/* info code from SantaKlauss at http://www.madaboutstyle.com/tooltip2.html */
a.info {
/* This is the key. */
position: relative;
z-index: 24;
text-decoration: none;
}
a.info:hover {
z-index: 25;
color: #FFF; background-color: #900;
}
a.info span { display: none; }
a.info:hover span.info {
/* The span will display just on :hover state. */
display: block;
position: absolute;
font-size: smaller;
top: 2em; left: -5em; width: 15em;
padding: 2px; border: 1px solid #333;
color: #900; background-color: #EEE;
text-align: left;
}
a.smpl {
color: black;
}
a:hover {
text-decoration: underline;
}
a:active {
text-decoration: underline;
}
address {
margin-top: 1em;
margin-left: 2em;
font-style: normal;
}
body {
color: black;
font-family: verdana, helvetica, arial, sans-serif;
font-size: 10pt;
max-width: 55em;
}
cite {
font-style: normal;
}
dd {
margin-right: 2em;
}
dl {
margin-left: 2em;
}
ul.empty {
list-style-type: none;
}
ul.empty li {
margin-top: .5em;
}
dl p {
margin-left: 0em;
}
dt {
margin-top: .5em;
}
h1 {
font-size: 14pt;
line-height: 21pt;
page-break-after: avoid;
}
h1.np {
page-break-before: always;
}
h1 a {
color: #333333;
}
h2 {
font-size: 12pt;
line-height: 15pt;
page-break-after: avoid;
}
h3, h4, h5, h6 {
font-size: 10pt;
page-break-after: avoid;
}
h2 a, h3 a, h4 a, h5 a, h6 a {
color: black;
}
img {
margin-left: 3em;
}
li {
margin-left: 2em;
margin-right: 2em;
}
ol {
margin-left: 2em;
margin-right: 2em;
}
ol p {
margin-left: 0em;
}
p {
margin-left: 2em;
margin-right: 2em;
}
pre {
margin-left: 3em;
background-color: lightyellow;
padding: .25em;
}
pre.text2 {
border-style: dotted;
border-width: 1px;
background-color: #f0f0f0;
width: 69em;
}
pre.inline {
background-color: white;
padding: 0em;
}
pre.text {
border-style: dotted;
border-width: 1px;
background-color: #f8f8f8;
width: 69em;
}
pre.drawing {
border-style: solid;
border-width: 1px;
background-color: #f8f8f8;
padding: 2em;
}
table {
margin-left: 2em;
}
table.tt {
vertical-align: top;
}
table.full {
border-style: outset;
border-width: 1px;
}
table.headers {
border-style: outset;
border-width: 1px;
}
table.tt td {
vertical-align: top;
}
table.full td {
border-style: inset;
border-width: 1px;
}
table.tt th {
vertical-align: top;
}
table.full th {
border-style: inset;
border-width: 1px;
}
table.headers th {
border-style: none none inset none;
border-width: 1px;
}
table.left {
margin-right: auto;
}
table.right {
margin-left: auto;
}
table.center {
margin-left: auto;
margin-right: auto;
}
caption {
caption-side: bottom;
font-weight: bold;
font-size: 9pt;
margin-top: .5em;
}
table.header {
border-spacing: 1px;
width: 95%;
font-size: 10pt;
color: white;
}
td.top {
vertical-align: top;
}
td.topnowrap {
vertical-align: top;
white-space: nowrap;
}
table.header td {
background-color: gray;
width: 50%;
}
table.header a {
color: white;
}
td.reference {
vertical-align: top;
white-space: nowrap;
padding-right: 1em;
}
thead {
display:table-header-group;
}
ul.toc, ul.toc ul {
list-style: none;
margin-left: 1.5em;
margin-right: 0em;
padding-left: 0em;
}
ul.toc li {
line-height: 150%;
font-weight: bold;
font-size: 10pt;
margin-left: 0em;
margin-right: 0em;
}
ul.toc li li {
line-height: normal;
font-weight: normal;
font-size: 9pt;
margin-left: 0em;
margin-right: 0em;
}
li.excluded {
font-size: 0pt;
}
ul p {
margin-left: 0em;
}
.comment {
background-color: yellow;
}
.center {
text-align: center;
}
.error {
color: red;
font-style: italic;
font-weight: bold;
}
.figure {
font-weight: bold;
text-align: center;
font-size: 9pt;
}
.filename {
color: #333333;
font-weight: bold;
font-size: 12pt;
line-height: 21pt;
text-align: center;
}
.fn {
font-weight: bold;
}
.hidden {
display: none;
}
.left {
text-align: left;
}
.right {
text-align: right;
}
.title {
color: #990000;
font-size: 18pt;
line-height: 18pt;
font-weight: bold;
text-align: center;
margin-top: 36pt;
}
.vcardline {
display: block;
}
.warning {
font-size: 14pt;
background-color: yellow;
}
@media print {
.noprint {
display: none;
}
a {
color: black;
text-decoration: none;
}
table.header {
width: 90%;
}
td.header {
width: 50%;
color: black;
background-color: white;
vertical-align: top;
font-size: 12pt;
}
ul.toc a::after {
content: leader('.') target-counter(attr(href), page);
}
ul.ind li li a {
content: target-counter(attr(href), page);
}
.print2col {
column-count: 2;
-moz-column-count: 2;
column-fill: auto;
}
}
@page {
@top-left {
content: "Internet-Draft";
}
@top-right {
content: "December 2010";
}
@top-center {
content: "Abbreviated Title";
}
@bottom-left {
content: "Doe";
}
@bottom-center {
content: "Expires June 2011";
}
@bottom-right {
content: "[Page " counter(page) "]";
}
}
@page:first {
@top-left {
content: normal;
}
@top-right {
content: normal;
}
@top-center {
content: normal;
}
}
/*]]>*/
</style>
<link href="#rfc.toc" rel="Contents">
<link href="#rfc.section.1" rel="Chapter" title="1 Introduction">
<link href="#rfc.section.1.1" rel="Chapter" title="1.1 Requirements Terminology">
<link href="#rfc.section.2" rel="Chapter" title="2 Key Agreement with Elliptic Curve Diffie-Hellman One-Pass Unified Model (ECDH-1PU)">
<link href="#rfc.section.2.1" rel="Chapter" title="2.1 Header Parameters used for ECDH Key Agreement">
<link href="#rfc.section.2.1.1" rel="Chapter" title='2.1.1 "skid" Header Parameter'>
<link href="#rfc.section.2.2" rel="Chapter" title="2.2 Key Derivation for ECDH-1PU Key Agreement">
<link href="#rfc.section.3" rel="Chapter" title="3 IANA considerations">
<link href="#rfc.section.3.1" rel="Chapter" title="3.1 JSON Web Signature and Encryption Algorithms Registration">
<link href="#rfc.section.3.1.1" rel="Chapter" title="3.1.1 ECDH-1PU">
<link href="#rfc.section.3.2" rel="Chapter" title="3.2 JSON Web Signature and Encryption Header Parameters Registration">
<link href="#rfc.section.3.2.1" rel="Chapter" title="3.2.1 skid">
<link href="#rfc.section.4" rel="Chapter" title="4 Security Considerations">
<link href="#rfc.references" rel="Chapter" title="5 References">
<link href="#rfc.references.1" rel="Chapter" title="5.1 Normative References">
<link href="#rfc.references.2" rel="Chapter" title="5.2 Informative References">
<link href="#rfc.appendix.A" rel="Chapter" title="A Example ECDH-1PU Key Agreement Computation with A256GCM">
<link href="#rfc.appendix.B" rel="Chapter" title="B Document History">
<link href="#rfc.authors" rel="Chapter">
<meta name="generator" content="xml2rfc version 2.8.2 - https://tools.ietf.org/tools/xml2rfc" />
<link rel="schema.dct" href="http://purl.org/dc/terms/" />
<meta name="dct.creator" content="Madden, N." />
<meta name="dct.identifier" content="urn:ietf:id:draft-madden-jose-ecdh-1pu-02" />
<meta name="dct.issued" scheme="ISO8601" content="2019-8-13" />
<meta name="dct.abstract" content="This document describes the ECDH-1PU public key authenticated encryption algorithm for JWE. The algorithm is similar to the existing ECDH-ES encryption algorithm, but adds an additional ECDH key agreement between static keys of the sender and recipient. This additional step allows the recipient to be assured of sender authenticity without requiring a nested signed-then-encrypted message structure. " />
<meta name="description" content="This document describes the ECDH-1PU public key authenticated encryption algorithm for JWE. The algorithm is similar to the existing ECDH-ES encryption algorithm, but adds an additional ECDH key agreement between static keys of the sender and recipient. This additional step allows the recipient to be assured of sender authenticity without requiring a nested signed-then-encrypted message structure. " />
</head>
<body>
<table class="header">
<tbody>
<tr>
<td class="left">Network Working Group</td>
<td class="right">N. Madden</td>
</tr>
<tr>
<td class="left">Internet-Draft</td>
<td class="right">ForgeRock</td>
</tr>
<tr>
<td class="left">Intended status: Standards Track</td>
<td class="right">August 13, 2019</td>
</tr>
<tr>
<td class="left">Expires: February 14, 2020</td>
<td class="right"></td>
</tr>
</tbody>
</table>
<p class="title">Public Key Authenticated Encryption for JOSE: ECDH-1PU<br />
<span class="filename">draft-madden-jose-ecdh-1pu-02</span></p>
<h1 id="rfc.abstract"><a href="#rfc.abstract">Abstract</a></h1>
<p>This document describes the ECDH-1PU public key authenticated encryption algorithm for JWE. The algorithm is similar to the existing ECDH-ES encryption algorithm, but adds an additional ECDH key agreement between static keys of the sender and recipient. This additional step allows the recipient to be assured of sender authenticity without requiring a nested signed-then-encrypted message structure. </p>
<h1 id="rfc.status"><a href="#rfc.status">Status of This Memo</a></h1>
<p>This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.</p>
<p>Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.</p>
<p>Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."</p>
<p>This Internet-Draft will expire on February 14, 2020.</p>
<h1 id="rfc.copyrightnotice"><a href="#rfc.copyrightnotice">Copyright Notice</a></h1>
<p>Copyright (c) 2019 IETF Trust and the persons identified as the document authors. All rights reserved.</p>
<p>This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.</p>
<hr class="noprint" />
<h1 class="np" id="rfc.toc"><a href="#rfc.toc">Table of Contents</a></h1>
<ul class="toc">
<li>1. <a href="#rfc.section.1">Introduction</a>
</li>
<ul><li>1.1. <a href="#rfc.section.1.1">Requirements Terminology</a>
</li>
</ul><li>2. <a href="#rfc.section.2">Key Agreement with Elliptic Curve Diffie-Hellman One-Pass Unified Model (ECDH-1PU)</a>
</li>
<ul><li>2.1. <a href="#rfc.section.2.1">Header Parameters used for ECDH Key Agreement</a>
</li>
<ul><li>2.1.1. <a href="#rfc.section.2.1.1">"skid" Header Parameter</a>
</li>
</ul><li>2.2. <a href="#rfc.section.2.2">Key Derivation for ECDH-1PU Key Agreement</a>
</li>
</ul><li>3. <a href="#rfc.section.3">IANA considerations</a>
</li>
<ul><li>3.1. <a href="#rfc.section.3.1">JSON Web Signature and Encryption Algorithms Registration</a>
</li>
<ul><li>3.1.1. <a href="#rfc.section.3.1.1">ECDH-1PU</a>
</li>
</ul><li>3.2. <a href="#rfc.section.3.2">JSON Web Signature and Encryption Header Parameters Registration</a>
</li>
<ul><li>3.2.1. <a href="#rfc.section.3.2.1">skid</a>
</li>
</ul></ul><li>4. <a href="#rfc.section.4">Security Considerations</a>
</li>
<li>5. <a href="#rfc.references">References</a>
</li>
<ul><li>5.1. <a href="#rfc.references.1">Normative References</a>
</li>
<li>5.2. <a href="#rfc.references.2">Informative References</a>
</li>
</ul><li>Appendix A. <a href="#rfc.appendix.A">Example ECDH-1PU Key Agreement Computation with A256GCM</a>
</li>
<li>Appendix B. <a href="#rfc.appendix.B">Document History</a>
</li>
<li><a href="#rfc.authors">Author's Address</a>
</li>
</ul>
<h1 id="rfc.section.1">
<a href="#rfc.section.1">1.</a> <a href="#intro" id="intro">Introduction</a>
</h1>
<p id="rfc.section.1.p.1">JSON Object Signing and Encryption (JOSE) defines a number of encryption (JWE) <a href="#RFC7516" class="xref">[RFC7516]</a> and digital signature (JWS) <a href="#RFC7515" class="xref">[RFC7515]</a> algorithms. When symmetric cryptography is used, JWE provides authenticated encryption that ensures both confidentiality and sender authentication. However, for public key cryptography the existing JWE encryption algorithms provide only confidentiality and some level of ciphertext integrity. When sender authentication is required, users must resort to nested signed-then-encrypted structures, which increases the overhead and size of resulting messages. This document describes an alternative encryption algorithm called ECDH-1PU that provides public key authenticated encryption, allowing the benefits of authenticated encryption to be enjoyed for public key JWE as it currently is for symmetric cryptography. </p>
<p id="rfc.section.1.p.2">ECDH-1PU is based on the One-Pass Unified Model for Elliptic Curve Diffie-Hellman key agreement described in <a href="#NIST.800-56A" class="xref">[NIST.800-56A]</a>. </p>
<p id="rfc.section.1.p.3">The advantages of public key authenticated encryption with ECDH-1PU compared to using nested signed-then-encrypted documents include the following: </p>
<ul>
<li>The resulting message size is more compact as an additional layer of headers and base64url-encoding is avoided. A 500-byte payload when encrypted and authenticated with ECDH-1PU (with P-256 keys and "A256GCM" Content Encryption Method) results in a 1087-byte JWE in Compact Encoding. An equivalent nested signed-then-encrypted JOSE message using the same keys and encryption method is 1489 bytes (37% larger). </li>
<li>The same primitives are used for both confidentiality and authenticity, providing savings in code size for constrained environments. </li>
<li>The generic composition of signatures and public key encryption involves a number of subtle details that are essential to security <a href="#PKAE" class="xref">[PKAE]</a>. Providing a dedicated algorithm for public key authenticated encryption reduces complexity for users of JOSE libraries. </li>
<li>ECDH-1PU provides only authenticity and not the stronger security properties of non-repudiation or third-party verifiability. This can be an advantage in applications where privacy, anonymity, or plausible deniability are goals. </li>
</ul>
<p> </p>
<h1 id="rfc.section.1.1">
<a href="#rfc.section.1.1">1.1.</a> Requirements Terminology</h1>
<p id="rfc.section.1.1.p.1">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 <a href="#RFC8174" class="xref">[RFC8174]</a> when, and only when, they appear in all capitals, as shown here.</p>
<h1 id="rfc.section.2">
<a href="#rfc.section.2">2.</a> <a href="#ecdh-1pu" id="ecdh-1pu">Key Agreement with Elliptic Curve Diffie-Hellman One-Pass Unified Model (ECDH-1PU)</a>
</h1>
<p id="rfc.section.2.p.1">This section defines the specifics of key agreement with Elliptic Curve Diffie-Hellman One-Pass Unified Model, in combination with the one-step KDF, as defined in Section 5.8.2.1 of <a href="#NIST.800-56A" class="xref">[NIST.800-56A]</a> using the Concatenation Format of Section 5.8.2.1.1. This is identical to the ConcatKDF function used by the existing JWE ECDH-ES algorithm defined in Section 4.6 of <a href="#RFC7518" class="xref">[RFC7518]</a>. As for ECDH-ES, the key agreement result can be used in one of two ways: </p>
<ol>
<li>directly as the Content Encryption Key (CEK) for the "enc" algorithm, in the Direct Key Agreement mode, or</li>
<li>as a symmetric key used to wrap the CEK with the "A128KW", "A192KW", or "A256KW" algorithms, in the Key Agreement with Key Wrapping mode.</li>
</ol>
<p> </p>
<p id="rfc.section.2.p.2">A new ephemeral public key value MUST be generated for each key agreement operation. </p>
<p id="rfc.section.2.p.3">In Direct Key Agreement mode, the output of the KDF MUST be a key of the same length as that used by the "enc" algorithm. In this case, the empty octet sequence is used as the JWE Encrypted Key value. The "alg" (algorithm) Header Parameter value "ECDH-1PU" is used in Direct Key Agreement mode. </p>
<p id="rfc.section.2.p.4">In Key Agreement with Key Wrapping mode, the output of the KDF MUST be a key of the length needed for the specified key wrapping algorithm. In this case, the JWE Encrypted Key is the CEK wrapped with the agreed-upon key. </p>
<p id="rfc.section.2.p.5">The following "alg" (algorithm) Header Parameter values are used to indicate the JWE Encrypted Key is the result of encrypting the CEK using the result of the key agreement algorithm as the key encryption key for the corresponding key wrapping algorithm: </p>
<table cellpadding="3" cellspacing="0" class="tt full center">
<thead><tr>
<th class="left">"alg" Param Value</th>
<th class="left">Key Management Algorithm</th>
</tr></thead>
<tbody>
<tr>
<td class="left">ECDH-1PU+A128KW</td>
<td class="left">ECDH-1PU using one-pass KDF and CEK wrapped with "A128KW"</td>
</tr>
<tr>
<td class="left">ECDH-1PU+A192KW</td>
<td class="left">ECDH-1PU using one-pass KDF and CEK wrapped with "A192KW"</td>
</tr>
<tr>
<td class="left">ECDH-1PU+A256KW</td>
<td class="left">ECDH-1PU using one-pass KDF and CEK wrapped with "A256KW"</td>
</tr>
</tbody>
</table>
<h1 id="rfc.section.2.1">
<a href="#rfc.section.2.1">2.1.</a> Header Parameters used for ECDH Key Agreement</h1>
<p id="rfc.section.2.1.p.1">The "epk" (ephemeral public key), "apu" (Agreement PartyUInfo), and "apv" (Agreement PartyVInfo) header parameters are used in ECDH-1PU exactly as defined in Section 4.6.1 of <a href="#RFC7518" class="xref">[RFC7518]</a>. </p>
<p id="rfc.section.2.1.p.2">When no other values are supplied, it is RECOMMENDED that the producer software initializes the "apu" header to the base64url-encoding of the SHA-256 hash of the concatenation of the sender's static public key and the ephemeral public key, and the "apv" header to the base64url-encoding of the SHA-256 hash of the recipient's static public key. This ensures that all keys involved in the key agreement are cryptographically bound to the derived keys. </p>
<h1 id="rfc.section.2.1.1">
<a href="#rfc.section.2.1.1">2.1.1.</a> <a href="#skid" id="skid">"skid" Header Parameter</a>
</h1>
<p id="rfc.section.2.1.1.p.1">A new Header Parameter "skid" (Sender Key ID) is registered as a hint as to which of the sender's keys was used to authenticate the JWE. The structure of the "skid" value is unspecified. Its value MUST be a case-sensitive string. Use of this Header Parameter is OPTIONAL. When used with a JWK, the "skid" value is used to match a JWK "kid" parameter value <a href="#RFC7517" class="xref">[RFC7517]</a>. </p>
<h1 id="rfc.section.2.2">
<a href="#rfc.section.2.2">2.2.</a> Key Derivation for ECDH-1PU Key Agreement</h1>
<p id="rfc.section.2.2.p.1">The key derivation process derives the agreed-upon key from the shared secret Z established through the ECDH algorithm, per Section 6.2.1.2 of <a href="#NIST.800-56A" class="xref">[NIST.800-56A]</a>. For the NIST prime order curves "P-256", "P-384", and "P-521", the ECC CDH primitive for cofactor Diffie-Hellman defined in Section 5.7.1.2 of <a href="#NIST.800-56A" class="xref">[NIST.800-56A]</a> is used (taking note that the cofactor for all these curves is 1). For curves "X25519" and "X448" the appropriate ECDH primitive from Section 5 of <a href="#RFC7748" class="xref">[RFC7748]</a> is used. </p>
<p id="rfc.section.2.2.p.2">Key derivation is performed using the one-step KDF, as defined in Section 5.8.1 and Section 5.8.2.1 of <a href="#NIST.800-56A" class="xref">[NIST.800-56A]</a> using the Concatenation Format of Section 5.8.2.1.1, where the Auxilary Function H is SHA-256. The KDF parameters are set as follows: <a href="#NIST.800-56A" class="xref">[NIST.800-56A]</a> need to provide values that meet the requirements of that doucument, e.g., by using values that identify the producer and consumer. </p>
<dl>
<dt>Z</dt>
<dd style="margin-left: 8">This is set to the representation of the shared secret Z as an octet sequence. As per Section 6.2.1.2 of <a href="#NIST.800-56A" class="xref">[NIST.800-56A]</a> Z is the concatenation of Ze and Zs, where Ze is the shared secret derived from applying the ECDH primitive to the sender's ephemeral private key and the recipient's static public key. Zs is the shared secret derived from applying the ECDH primitive to the sender's static private key and the recipient's static public key. </dd>
<dt>keydatalen</dt>
<dd style="margin-left: 8">This is set to the number of bits in the desired output key. For "ECDH-1PU", this is the length of the key used by the "enc" algorithm. For "ECDH-1PU+A128KW", "ECDH-1PU+A192KW", and "ECDH-1PU+A256KW", this is 128, 192, and 256, respectively. </dd>
<dt>AlgorithmID</dt>
<dd style="margin-left: 8">The AlgorithmID values is of the form Datalen || Data, where Data is a variable-length string of zero or more octets, and Datalen is a fixed-length, big-endian 32-bit counter that indicates the length (in octets) of Data. In the Direct Key Agreement case, Data is set to the octets of the ASCII representation of the "enc" Header Parameter value. In the Key Agreement with Key Wrapping case, Data is set to the octets of the ASCII representation of the "alg" (algorithm) Header Parameter value. </dd>
<dt>PartyUInfo</dt>
<dd style="margin-left: 8">The PartyUInfo value is of the form Datalen || Data, where Data is a variable-length string of zero or more octets, and Datalen is a fixed-length, big-endian 32-bit counter that indicates the length (in octets) of Data. If an "apu" (agreement PartyUInfo) Header Parameter is present, Data is set to the result of base64url decoding the "apu" value and Datalen is set to the number of octets in Data. Otherwise, Datalen is set to 0 and Data is set to the empty octet sequence. </dd>
<dt>PartyVInfo</dt>
<dd style="margin-left: 8">The PartyVInfo value is of the form Datalen || Data, where Data is a variable-length string of zero or more octets, and Datalen is a fixed-length, big-endian 32-bit counter that indicates the length (in octets) of Data. If an "apv" (agreement PartyVInfo) Header Parameter is present, Data is set to the result of base64url decoding the "apv" value and Datalen is set to the number of octets in Data. Otherwise, Datalen is set to 0 and Data is set to the empty octet sequence. </dd>
<dt>SuppPubInfo</dt>
<dd style="margin-left: 8">This is set to the keydatalen represented as a 32-bit big-endian integer. </dd>
<dt>SuppPrivInfo</dt>
<dd style="margin-left: 8">This is set to the empty octet sequence. </dd>
</dl>
<p> Applications need to specify how the "apu" and "apv" Header Parameters are used for that application. The "apu" and "apv" values MUST be distinct, when used. Applications wishing to conform to </p>
<p id="rfc.section.2.2.p.3">See <a href="#example" class="xref">Appendix A</a> for an example key agreement computation using this method. </p>
<h1 id="rfc.section.3">
<a href="#rfc.section.3">3.</a> <a href="#IANA" id="IANA">IANA considerations</a>
</h1>
<p id="rfc.section.3.p.1">This section registers identifiers under the IANA JSON Web Signature and Encryption Algorithms Registry established by <a href="#RFC7518" class="xref">[RFC7518]</a> and the IANA JSON Web Signature and Encryption Header Parameters registry established by <a href="#RFC7515" class="xref">[RFC7515]</a>. </p>
<h1 id="rfc.section.3.1">
<a href="#rfc.section.3.1">3.1.</a> JSON Web Signature and Encryption Algorithms Registration</h1>
<p id="rfc.section.3.1.p.1">This section registers JWE algorithms as per the registry established in <a href="#RFC7518" class="xref">[RFC7518]</a>. </p>
<h1 id="rfc.section.3.1.1">
<a href="#rfc.section.3.1.1">3.1.1.</a> ECDH-1PU</h1>
<p></p>
<ul class="empty">
<li>Algorithm Name: "ECDH-1PU"</li>
<li>Algorithm Description: ECDH One-Pass Unified Model using one-pass KDF</li>
<li>Algorithm Usage Location(s): "alg"</li>
<li>JOSE Implementation Requirements: Optional</li>
<li>Change Controller: IESG</li>
<li>Specification Document(s): <a href="#ecdh-1pu" class="xref">Section 2</a>
</li>
<li>Algorithm Analysis Document(s): <a href="#NIST.800-56A" class="xref">[NIST.800-56A]</a> (Section 7.3), <a href="#PKAE" class="xref">[PKAE]</a>
</li>
</ul>
<p> </p>
<h1 id="rfc.section.3.2">
<a href="#rfc.section.3.2">3.2.</a> JSON Web Signature and Encryption Header Parameters Registration</h1>
<p id="rfc.section.3.2.p.1">This section registers new Header Parameters as per the registry established in <a href="#RFC7515" class="xref">[RFC7515]</a>. </p>
<h1 id="rfc.section.3.2.1">
<a href="#rfc.section.3.2.1">3.2.1.</a> skid</h1>
<p></p>
<ul class="empty">
<li>Header Parameter Name: "skid"</li>
<li>Header Parameter Description: Sender Key ID</li>
<li>Header Parameter Usage Location(s): JWE</li>
<li>Change Controller: IESG</li>
<li>Specification Document(s): <a href="#skid" class="xref">Section 2.1.1</a>
</li>
</ul>
<p> </p>
<h1 id="rfc.section.4">
<a href="#rfc.section.4">4.</a> <a href="#security" id="security">Security Considerations</a>
</h1>
<p id="rfc.section.4.p.1">The security considerations of <a href="#RFC7516" class="xref">[RFC7516]</a> and <a href="#RFC7518" class="xref">[RFC7518]</a> relevant to ECDH-ES also apply to this specification. </p>
<p id="rfc.section.4.p.2">The security considerations of <a href="#NIST.800-56A" class="xref">[NIST.800-56A]</a> apply here.</p>
<p id="rfc.section.4.p.3">When performing an ECDH key agreement between a static private key and any untrusted public key, care should be taken to ensure that the public key is a valid point on the same curve as the private key. Failure to do so may result in compromise of the static private key. For the NIST curves P-256, P-384, and P-521, appropriate validation routines are given in Section 5.6.2.3.3 of <a href="#NIST.800-56A" class="xref">[NIST.800-56A]</a>. For the curves used by X25519 and X448, consult the security considerations of <a href="#RFC7748" class="xref">[RFC7748]</a>. </p>
<p id="rfc.section.4.p.4">The ECDH-1PU algorithm is vulnerable to Key Compromise Impersonation (KCI) attacks. If the long-term static private key of a party is compromised, then the attacker can not only impersonate that party to other parties, but also impersonate any other party when communicating with the compromised party. If resistance to KCI is desired in a single message, then it is RECOMMENDED to use a nested JWS signature over the content. An interactive handshake protocol, such as those described in <a href="#Noise" class="xref">[Noise]</a> can also be used to prevent KCI. </p>
<p id="rfc.section.4.p.5">When Key Agreement with Key Wrapping is used, with the same Content Encryption Key (CEK) reused for multiple recipients, any of those recipients can produce a new message that appears to come from the original sender. The new message will be indistinguishable from a genuine message from the original sender to any of the other participants. The sender SHOULD use a unique CEK for each recipient of a message. </p>
<p id="rfc.section.4.p.6">The security properties of the one-pass unified model are given in Section 7.3 of <a href="#NIST.800-56A" class="xref">[NIST.800-56A]</a>. </p>
<h1 id="rfc.references">
<a href="#rfc.references">5.</a> References</h1>
<h1 id="rfc.references.1">
<a href="#rfc.references.1">5.1.</a> Normative References</h1>
<table><tbody>
<tr>
<td class="reference"><b id="NIST.800-56A">[NIST.800-56A]</b></td>
<td class="top">
<a title="Computer Security Division, Information Technology Laboratory">Barker, E.</a>, <a title="Computer Security Division, Information Technology Laboratory">Chen, L.</a>, <a title="Computer Security Division, Information Technology Laboratory">Roginsky, A.</a>, <a title="Computer Security Division, Information Technology Laboratory">Vassilev, A.</a> and <a title="National Security Agency">R. Davis</a>, "<a>Recommendation for Pair-Wise Key Establishment Using Discrete Logarithm Cryptography Revision 3.</a>", NIST Special Publication 800-56A, April 2018.</td>
</tr>
<tr>
<td class="reference"><b id="RFC7515">[RFC7515]</b></td>
<td class="top">
<a>Jones, M.</a>, <a>Bradley, J.</a> and <a>N. Sakimura</a>, "<a href="https://tools.ietf.org/html/rfc7515">JSON Web Signature (JWS)</a>", RFC 7515, DOI 10.17487/RFC7515, May 2015.</td>
</tr>
<tr>
<td class="reference"><b id="RFC7516">[RFC7516]</b></td>
<td class="top">
<a>Jones, M.</a> and <a>J. Hildebrand</a>, "<a href="https://tools.ietf.org/html/rfc7516">JSON Web Encryption (JWE)</a>", RFC 7516, DOI 10.17487/RFC7516, May 2015.</td>
</tr>
<tr>
<td class="reference"><b id="RFC7517">[RFC7517]</b></td>
<td class="top">
<a>Jones, M.</a>, "<a href="https://tools.ietf.org/html/rfc7517">JSON Web Key (JWK)</a>", RFC 7517, DOI 10.17487/RFC7517, May 2015.</td>
</tr>
<tr>
<td class="reference"><b id="RFC7518">[RFC7518]</b></td>
<td class="top">
<a>Jones, M.</a>, "<a href="https://tools.ietf.org/html/rfc7518">JSON Web Algorithms (JWA)</a>", RFC 7518, DOI 10.17487/RFC7518, May 2015.</td>
</tr>
<tr>
<td class="reference"><b id="RFC7748">[RFC7748]</b></td>
<td class="top">
<a>Langley, A.</a>, <a>Hamburg, M.</a> and <a>S. Turner</a>, "<a href="https://tools.ietf.org/html/rfc7748">Elliptic Curves for Security</a>", RFC 7748, DOI 10.17487/RFC7748, January 2016.</td>
</tr>
<tr>
<td class="reference"><b id="RFC8174">[RFC8174]</b></td>
<td class="top">
<a>Leiba, B.</a>, "<a href="https://tools.ietf.org/html/rfc8174">Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words</a>", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017.</td>
</tr>
</tbody></table>
<h1 id="rfc.references.2">
<a href="#rfc.references.2">5.2.</a> Informative References</h1>
<table><tbody>
<tr>
<td class="reference"><b id="Noise">[Noise]</b></td>
<td class="top">
<a>Perrin, T.</a>, "<a>The Noise Protocol Framework, Revision 34</a>", July 2018.</td>
</tr>
<tr>
<td class="reference"><b id="PKAE">[PKAE]</b></td>
<td class="top">
<a title="University of California at Davis">An, J.</a>, "<a>Authenticated Encryption in the Public-Key Setting: Security Notions and Analyses</a>", IACR ePrint 2001/079, 2001.</td>
</tr>
</tbody></table>
<h1 id="rfc.appendix.A">
<a href="#rfc.appendix.A">Appendix A.</a> <a href="#example" id="example">Example ECDH-1PU Key Agreement Computation with A256GCM</a>
</h1>
<p id="rfc.section.A.p.1">This example uses ECDH-1PU in Direct Key Agreement mode ("alg" value "ECDH-1PU") to produce an agreed-upon key for AES GCM with a 256-bit key ("enc" value "A256GCM"). The example re-uses the keys and parameters of the example computation in Appendix C of <a href="#RFC7518" class="xref">[RFC7518]</a>, with the addition of an extra static key-pair for Alice. </p>
<p id="rfc.section.A.p.2">When used in this way, ECDH-1PU has similar security properties to the "K" one-way handshake pattern of <a href="#Noise" class="xref">[Noise]</a>, although it is quite different in details. </p>
<p id="rfc.section.A.p.3">In this example, a producer Alice is encrypting content to a consumer Bob. Alice's static key-pair (in JWK format) used for the key agreement in this example (including the private part) is: </p>
<pre>
{"kty":"EC",
"crv":"P-256",
"x":"WKn-ZIGevcwGIyyrzFoZNBdaq9_TsqzGl96oc0CWuis",
"y":"y77t-RvAHRKTsSGdIYUfweuOvwrvDD-Q3Hv5J0fSKbE",
"d":"Hndv7ZZjs_ke8o9zXYo3iq-Yr8SewI5vrqd0pAvEPqg"}
</pre>
<p id="rfc.section.A.p.4">Bob's static key-pair (in JWK format) is: </p>
<pre>
{"kty":"EC",
"crv":"P-256",
"x":"weNJy2HscCSM6AEDTDg04biOvhFhyyWvOHQfeF_PxMQ",
"y":"e8lnCO-AlStT-NJVX-crhB7QRYhiix03illJOVAOyck",
"d":"VEmDZpDXXK8p8N0Cndsxs924q6nS1RXFASRl6BfUqdw"}
</pre>
<p id="rfc.section.A.p.5">The producer (Alice) generates an ephemeral key for the key agreement computation. Alice's ephemeral key (in JWK format) is: </p>
<pre>
{"kty":"EC",
"crv":"P-256",
"x":"gI0GAILBdu7T53akrFmMyGcsF3n5dO7MmwNBHKW5SV0",
"y":"SLW_xSffzlPWrHEVI30DHM_4egVwt3NQqeUD7nMFpps",
"d":"0_NxaRPUMQoAJt50Gz8YiTr8gRTwyEaCumd-MToTmIo"}
</pre>
<p id="rfc.section.A.p.6">Header Parameter values used in this example are as follows. The "apu" (agreement PartyUInfo) Header Parameter value is the base64url encoding of the UTF-8 string "Alice" and the "apv" (agreement PartyVInfo) Header Parameter value is the base64url encoding of the UTF-8 string "Bob". The "epk" (ephemeral public key) Header Parameter is used to communicate the producer's (Alice's) ephemeral public key value to the consumer (Bob). </p>
<pre>
{"alg":"ECDH-1PU",
"enc":"A256GCM",
"apu":"QWxpY2U",
"apv":"Qm9i",
"epk":
{"kty":"EC",
"crv":"P-256",
"x":"gI0GAILBdu7T53akrFmMyGcsF3n5dO7MmwNBHKW5SV0",
"y":"SLW_xSffzlPWrHEVI30DHM_4egVwt3NQqeUD7nMFpps"
}
}
</pre>
<p id="rfc.section.A.p.7">The resulting one-pass KDF <a href="#NIST.800-56A" class="xref">[NIST.800-56A]</a> parameter values are: </p>
<dl>
<dt>Ze</dt>
<dd style="margin-left: 8">This is set to the output of the ECDH key agreement between Alice's ephemeral private key and Bob's static public key. In this example, Ze is the following octet sequence (in hexadecimal notation): </dd>
</dl>
<p> </p>
<pre>
9e 56 d9 1d 81 71 35 d3 72 83 42 83 bf 84 26 9c
fb 31 6e a3 da 80 6a 48 f6 da a7 79 8c fe 90 c4</pre>
<p></p>
<p></p>
<dl>
<dt>Zs</dt>
<dd style="margin-left: 8">This is set to the output of the ECDH key agreement between Alice's static private key and Bob's static public key. In this example, Zs is the following octet sequence (in hexadecimal notation): </dd>
</dl>
<p> </p>
<pre>
e3 ca 34 74 38 4c 9f 62 b3 0b fd 4c 68 8b 3e 7d
41 10 a1 b4 ba dc 3c c5 4e f7 b8 12 41 ef d5 0d</pre>
<p></p>
<p></p>
<dl>
<dt>Z</dt>
<dd style="margin-left: 8">This is set to the concatenation of Ze followed by Zs. In this example, Z is the following octet sequence (in hexadecimal notation): </dd>
</dl>
<p> </p>
<pre>
9e 56 d9 1d 81 71 35 d3 72 83 42 83 bf 84 26 9c
fb 31 6e a3 da 80 6a 48 f6 da a7 79 8c fe 90 c4
e3 ca 34 74 38 4c 9f 62 b3 0b fd 4c 68 8b 3e 7d
41 10 a1 b4 ba dc 3c c5 4e f7 b8 12 41 ef d5 0d</pre>
<p></p>
<p></p>
<dl>
<dt>keydatalen</dt>
<dd style="margin-left: 8">This value is 256 - the number of bits in the desired output key (because "A256GCM" uses a 256-bit key). </dd>
<dt>AlgorithmID</dt>
<dd style="margin-left: 8">This is set to the octets representing the 32-bit big-endian value 7 - 00 00 00 07 in hexadecimal notation - the number of octets in the AlgorithmID content "A256GCM", followed by the octets representing the ASCII string "A256GCM" - 41 32 35 36 47 43 4d (in hex). The complete value is therefore: 00 00 00 07 41 32 35 36 47 43 4d </dd>
<dt>PartyUInfo</dt>
<dd style="margin-left: 8">This is set to the octets representing the 32-bit big-endian value 5, followed by the octets representing the UTF-8 string "Alice". In hexadecimal notation: 00 00 00 05 41 6c 69 63 65 </dd>
<dt>PartyVInfo</dt>
<dd style="margin-left: 8">This is set to the octets representing the 32-bit big-endian value 3, followed by the octets representing the UTF-8 string "Bob". In hexadecimal notation: 00 00 00 03 42 6f 62 </dd>
<dt>SuppPubInfo</dt>
<dd style="margin-left: 8">This is set to the octets representing the 32-bit big-endian value 256 - the keydatalen value. In hexadecimal notation: 00 00 01 00 </dd>
<dt>SuppPrivInfo</dt>
<dd style="margin-left: 8">This is set to the empty octet sequence. </dd>
</dl>
<p> </p>
<p id="rfc.section.A.p.14">Concatenating the parameters AlgorithmID through SuppPrivInfo results in a FixedInfo value in Concatenation Format (as per Section 5.8.2.1.1 of <a href="#NIST.800-56A" class="xref">[NIST.800-56A]</a>) of (in hexidecimal notation): </p>
<pre>
00 00 00 07 41 32 35 36 47 43 4d 00 00 00 05 41
6c 69 63 65 00 00 00 03 42 6f 62 00 00 01 00
</pre>
<p></p>
<p id="rfc.section.A.p.16">Concatenating the round number 1 (00 00 00 01), Z, and the FixedInfo value results in a one-pass KDF round 1 hash input of (hexadecimal): </p>
<pre>
00 00 00 01 9e 56 d9 1d 81 71 35 d3 72 83 42 83
bf 84 26 9c fb 31 6e a3 da 80 6a 48 f6 da a7 79
8c fe 90 c4 e3 ca 34 74 38 4c 9f 62 b3 0b fd 4c
68 8b 3e 7d 41 10 a1 b4 ba dc 3c c5 4e f7 b8 12
41 ef d5 0d 00 00 00 07 41 32 35 36 47 43 4d 00
00 00 05 41 6c 69 63 65 00 00 00 03 42 6f 62 00
00 01 00 </pre>
<p></p>
<p id="rfc.section.A.p.18">The resulting derived key, which is the full 256 bits of the round 1 hash output is: </p>
<pre>
6c af 13 72 3d 14 85 0a d4 b4 2c d6 dd e9 35 bf
fd 2f ff 00 a9 ba 70 de 05 c2 03 a5 e1 72 2c a7
</pre>
<p></p>
<p id="rfc.section.A.p.20">The base64url-encoded representation of this derived key is: </p>
<pre>
bK8Tcj0UhQrUtCzW3ek1v_0v_wCpunDeBcIDpeFyLKc
</pre>
<p></p>
<h1 id="rfc.appendix.B">
<a href="#rfc.appendix.B">Appendix B.</a> Document History</h1>
<p></p>
<dl>
<dt>-02</dt>
<dd style="margin-left: 8">Removed two-way interactive handshake protocol section and example after discussion with Hannes Tschofenig. </dd>
<dt>-01</dt>
<dd style="margin-left: 8">Added examples in <a href="#example" class="xref">Appendix A</a> and a two-way handshake example. Added "skid" Header Parameter and registration. Fleshed out Security Considerations. </dd>
</dl>
<p> </p>
<h1 id="rfc.authors"><a href="#rfc.authors">Author's Address</a></h1>
<div class="avoidbreak">
<address class="vcard">
<span class="vcardline">
<span class="fn">Neil Madden</span>
<span class="n hidden">
<span class="family-name">Madden</span>
</span>
</span>
<span class="org vcardline">ForgeRock</span>
<span class="adr">
<span class="vcardline">Broad Quay House</span>
<span class="vcardline">Prince Street</span>
<span class="vcardline">
<span class="locality">Bristol</span>,
<span class="region"></span>
<span class="code">BS1 4DJ</span>
</span>
<span class="country-name vcardline">United Kingdom</span>
</span>
<span class="vcardline">EMail: <a href="mailto:neil.madden@forgerock.com">neil.madden@forgerock.com</a></span>
</address>
</div>
</body>
</html>