-
Notifications
You must be signed in to change notification settings - Fork 2
/
rfc7517.txt
2243 lines (1567 loc) · 91.7 KB
/
rfc7517.txt
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
Internet Engineering Task Force (IETF) M. Jones
Request for Comments: 7517 Microsoft
Category: Standards Track May 2015
ISSN: 2070-1721
JSON Web Key (JWK)
Abstract
A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) data
structure that represents a cryptographic key. This specification
also defines a JWK Set JSON data structure that represents a set of
JWKs. Cryptographic algorithms and identifiers for use with this
specification are described in the separate JSON Web Algorithms (JWA)
specification and IANA registries established by that specification.
Status of This Memo
This is an Internet Standards Track document.
This document is a product of the Internet Engineering Task Force
(IETF). It represents the consensus of the IETF community. It has
received public review and has been approved for publication by the
Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 5741.
Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
http://www.rfc-editor.org/info/rfc7517.
Copyright Notice
Copyright (c) 2015 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://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.
Jones Standards Track [Page 1]
RFC 7517 JSON Web Key (JWK) May 2015
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4
3. Example JWK . . . . . . . . . . . . . . . . . . . . . . . . . 5
4. JSON Web Key (JWK) Format . . . . . . . . . . . . . . . . . . 5
4.1. "kty" (Key Type) Parameter . . . . . . . . . . . . . . . 6
4.2. "use" (Public Key Use) Parameter . . . . . . . . . . . . 6
4.3. "key_ops" (Key Operations) Parameter . . . . . . . . . . 7
4.4. "alg" (Algorithm) Parameter . . . . . . . . . . . . . . . 8
4.5. "kid" (Key ID) Parameter . . . . . . . . . . . . . . . . 8
4.6. "x5u" (X.509 URL) Parameter . . . . . . . . . . . . . . . 8
4.7. "x5c" (X.509 Certificate Chain) Parameter . . . . . . . . 9
4.8. "x5t" (X.509 Certificate SHA-1 Thumbprint) Parameter . . 9
4.9. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint)
Parameter . . . . . . . . . . . . . . . . . . . . . . . . 10
5. JWK Set Format . . . . . . . . . . . . . . . . . . . . . . . 10
5.1. "keys" Parameter . . . . . . . . . . . . . . . . . . . . 10
6. String Comparison Rules . . . . . . . . . . . . . . . . . . . 11
7. Encrypted JWK and Encrypted JWK Set Formats . . . . . . . . . 11
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11
8.1. JSON Web Key Parameters Registry . . . . . . . . . . . . 12
8.1.1. Registration Template . . . . . . . . . . . . . . . . 12
8.1.2. Initial Registry Contents . . . . . . . . . . . . . . 13
8.2. JSON Web Key Use Registry . . . . . . . . . . . . . . . . 15
8.2.1. Registration Template . . . . . . . . . . . . . . . . 15
8.2.2. Initial Registry Contents . . . . . . . . . . . . . . 15
8.3. JSON Web Key Operations Registry . . . . . . . . . . . . 16
8.3.1. Registration Template . . . . . . . . . . . . . . . . 16
8.3.2. Initial Registry Contents . . . . . . . . . . . . . . 16
8.4. JSON Web Key Set Parameters Registry . . . . . . . . . . 17
8.4.1. Registration Template . . . . . . . . . . . . . . . . 17
8.4.2. Initial Registry Contents . . . . . . . . . . . . . . 18
8.5. Media Type Registration . . . . . . . . . . . . . . . . . 18
8.5.1. Registry Contents . . . . . . . . . . . . . . . . . . 18
9. Security Considerations . . . . . . . . . . . . . . . . . . . 19
9.1. Key Provenance and Trust . . . . . . . . . . . . . . . . 20
9.2. Preventing Disclosure of Non-public Key Information . . . 20
9.3. RSA Private Key Representations and Blinding . . . . . . 21
9.4. Key Entropy and Random Values . . . . . . . . . . . . . . 21
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 21
10.1. Normative References . . . . . . . . . . . . . . . . . . 21
10.2. Informative References . . . . . . . . . . . . . . . . . 23
Appendix A. Example JSON Web Key Sets . . . . . . . . . . . . . 25
A.1. Example Public Keys . . . . . . . . . . . . . . . . . . . 25
A.2. Example Private Keys . . . . . . . . . . . . . . . . . . 25
A.3. Example Symmetric Keys . . . . . . . . . . . . . . . . . 27
Jones Standards Track [Page 2]
RFC 7517 JSON Web Key (JWK) May 2015
Appendix B. Example Use of "x5c" (X.509 Certificate Chain)
Parameter . . . . . . . . . . . . . . . . . . . . . 28
Appendix C. Example Encrypted RSA Private Key . . . . . . . . . 28
C.1. Plaintext RSA Private Key . . . . . . . . . . . . . . . . 29
C.2. JOSE Header . . . . . . . . . . . . . . . . . . . . . . . 32
C.3. Content Encryption Key (CEK) . . . . . . . . . . . . . . 32
C.4. Key Derivation . . . . . . . . . . . . . . . . . . . . . 33
C.5. Key Encryption . . . . . . . . . . . . . . . . . . . . . 33
C.6. Initialization Vector . . . . . . . . . . . . . . . . . . 33
C.7. Additional Authenticated Data . . . . . . . . . . . . . . 34
C.8. Content Encryption . . . . . . . . . . . . . . . . . . . 34
C.9. Complete Representation . . . . . . . . . . . . . . . . . 38
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 40
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 40
1. Introduction
A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) [RFC7159]
data structure that represents a cryptographic key. This
specification also defines a JWK Set JSON data structure that
represents a set of JWKs. Cryptographic algorithms and identifiers
for use with this specification are described in the separate JSON
Web Algorithms (JWA) [JWA] specification and IANA registries
established by that specification.
Goals for this specification do not include representing new kinds of
certificate chains, representing new kinds of certified keys, or
replacing X.509 certificates.
JWKs and JWK Sets are used in the JSON Web Signature [JWS] and JSON
Web Encryption [JWE] specifications.
Names defined by this specification are short because a core goal is
for the resulting representations to be compact.
1.1. Notational Conventions
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
"Key words for use in RFCs to Indicate Requirement Levels" [RFC2119].
The interpretation should only be applied when the terms appear in
all capital letters.
BASE64URL(OCTETS) denotes the base64url encoding of OCTETS, per
Section 2 of [JWS].
Jones Standards Track [Page 3]
RFC 7517 JSON Web Key (JWK) May 2015
UTF8(STRING) denotes the octets of the UTF-8 [RFC3629] representation
of STRING, where STRING is a sequence of zero or more Unicode
[UNICODE] characters.
ASCII(STRING) denotes the octets of the ASCII [RFC20] representation
of STRING, where STRING is a sequence of zero or more ASCII
characters.
The concatenation of two values A and B is denoted as A || B.
2. Terminology
The terms "JSON Web Signature (JWS)", "Base64url Encoding",
"Collision-Resistant Name", "Header Parameter", and "JOSE Header" are
defined by the JWS specification [JWS].
The terms "JSON Web Encryption (JWE)", "Additional Authenticated Data
(AAD)", "JWE Authentication Tag", "JWE Ciphertext", "JWE Compact
Serialization", "JWE Encrypted Key", "JWE Initialization Vector", and
"JWE Protected Header" are defined by the JWE specification [JWE].
The terms "Ciphertext", "Digital Signature", "Message Authentication
Code (MAC)", and "Plaintext" are defined by the "Internet Security
Glossary, Version 2" [RFC4949].
These terms are defined by this specification:
JSON Web Key (JWK)
A JSON object that represents a cryptographic key. The members of
the object represent properties of the key, including its value.
JWK Set
A JSON object that represents a set of JWKs. The JSON object MUST
have a "keys" member, which is an array of JWKs.
Jones Standards Track [Page 4]
RFC 7517 JSON Web Key (JWK) May 2015
3. Example JWK
This section provides an example of a JWK. The following example JWK
declares that the key is an Elliptic Curve [DSS] key, it is used with
the P-256 Elliptic Curve, and its x and y coordinates are the
base64url-encoded values shown. A key identifier is also provided
for the key.
{"kty":"EC",
"crv":"P-256",
"x":"f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU",
"y":"x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0",
"kid":"Public key used in JWS spec Appendix A.3 example"
}
Additional example JWK values can be found in Appendix A.
4. JSON Web Key (JWK) Format
A JWK is a JSON object that represents a cryptographic key. The
members of the object represent properties of the key, including its
value. This JSON object MAY contain whitespace and/or line breaks
before or after any JSON values or structural characters, in
accordance with Section 2 of RFC 7159 [RFC7159]. This document
defines the key parameters that are not algorithm specific and, thus,
common to many keys.
In addition to the common parameters, each JWK will have members that
are key type specific. These members represent the parameters of the
key. Section 6 of the JSON Web Algorithms (JWA) [JWA] specification
defines multiple kinds of cryptographic keys and their associated
members.
The member names within a JWK MUST be unique; JWK parsers MUST either
reject JWKs with duplicate member names or use a JSON parser that
returns only the lexically last duplicate member name, as specified
in Section 15.12 (The JSON Object) of ECMAScript 5.1 [ECMAScript].
Additional members can be present in the JWK; if not understood by
implementations encountering them, they MUST be ignored. Member
names used for representing key parameters for different keys types
need not be distinct. Any new member name should either be
registered in the IANA "JSON Web Key Parameters" registry established
by Section 8.1 or be a value that contains a Collision-Resistant
Name.
Jones Standards Track [Page 5]
RFC 7517 JSON Web Key (JWK) May 2015
4.1. "kty" (Key Type) Parameter
The "kty" (key type) parameter identifies the cryptographic algorithm
family used with the key, such as "RSA" or "EC". "kty" values should
either be registered in the IANA "JSON Web Key Types" registry
established by [JWA] or be a value that contains a Collision-
Resistant Name. The "kty" value is a case-sensitive string. This
member MUST be present in a JWK.
A list of defined "kty" values can be found in the IANA "JSON Web Key
Types" registry established by [JWA]; the initial contents of this
registry are the values defined in Section 6.1 of [JWA].
The key type definitions include specification of the members to be
used for those key types. Members used with specific "kty" values
can be found in the IANA "JSON Web Key Parameters" registry
established by Section 8.1.
4.2. "use" (Public Key Use) Parameter
The "use" (public key use) parameter identifies the intended use of
the public key. The "use" parameter is employed to indicate whether
a public key is used for encrypting data or verifying the signature
on data.
Values defined by this specification are:
o "sig" (signature)
o "enc" (encryption)
Other values MAY be used. The "use" value is a case-sensitive
string. Use of the "use" member is OPTIONAL, unless the application
requires its presence.
When a key is used to wrap another key and a public key use
designation for the first key is desired, the "enc" (encryption) key
use value is used, since key wrapping is a kind of encryption. The
"enc" value is also to be used for public keys used for key agreement
operations.
Additional "use" (public key use) values can be registered in the
IANA "JSON Web Key Use" registry established by Section 8.2.
Registering any extension values used is highly recommended when this
specification is used in open environments, in which multiple
organizations need to have a common understanding of any extensions
used. However, unregistered extension values can be used in closed
environments, in which the producing and consuming organization will
always be the same.
Jones Standards Track [Page 6]
RFC 7517 JSON Web Key (JWK) May 2015
4.3. "key_ops" (Key Operations) Parameter
The "key_ops" (key operations) parameter identifies the operation(s)
for which the key is intended to be used. The "key_ops" parameter is
intended for use cases in which public, private, or symmetric keys
may be present.
Its value is an array of key operation values. Values defined by
this specification are:
o "sign" (compute digital signature or MAC)
o "verify" (verify digital signature or MAC)
o "encrypt" (encrypt content)
o "decrypt" (decrypt content and validate decryption, if applicable)
o "wrapKey" (encrypt key)
o "unwrapKey" (decrypt key and validate decryption, if applicable)
o "deriveKey" (derive key)
o "deriveBits" (derive bits not to be used as a key)
(Note that the "key_ops" values intentionally match the "KeyUsage"
values defined in the Web Cryptography API
[W3C.CR-WebCryptoAPI-20141211] specification.)
Other values MAY be used. The key operation values are case-
sensitive strings. Duplicate key operation values MUST NOT be
present in the array. Use of the "key_ops" member is OPTIONAL,
unless the application requires its presence.
Multiple unrelated key operations SHOULD NOT be specified for a key
because of the potential vulnerabilities associated with using the
same key with multiple algorithms. Thus, the combinations "sign"
with "verify", "encrypt" with "decrypt", and "wrapKey" with
"unwrapKey" are permitted, but other combinations SHOULD NOT be used.
Additional "key_ops" (key operations) values can be registered in the
IANA "JSON Web Key Operations" registry established by Section 8.3.
The same considerations about registering extension values apply to
the "key_ops" member as do for the "use" member.
The "use" and "key_ops" JWK members SHOULD NOT be used together;
however, if both are used, the information they convey MUST be
consistent. Applications should specify which of these members they
use, if either is to be used by the application.
Jones Standards Track [Page 7]
RFC 7517 JSON Web Key (JWK) May 2015
4.4. "alg" (Algorithm) Parameter
The "alg" (algorithm) parameter identifies the algorithm intended for
use with the key. The values used should either be registered in the
IANA "JSON Web Signature and Encryption Algorithms" registry
established by [JWA] or be a value that contains a Collision-
Resistant Name. The "alg" value is a case-sensitive ASCII string.
Use of this member is OPTIONAL.
4.5. "kid" (Key ID) Parameter
The "kid" (key ID) parameter is used to match a specific key. This
is used, for instance, to choose among a set of keys within a JWK Set
during key rollover. The structure of the "kid" value is
unspecified. When "kid" values are used within a JWK Set, different
keys within the JWK Set SHOULD use distinct "kid" values. (One
example in which different keys might use the same "kid" value is if
they have different "kty" (key type) values but are considered to be
equivalent alternatives by the application using them.) The "kid"
value is a case-sensitive string. Use of this member is OPTIONAL.
When used with JWS or JWE, the "kid" value is used to match a JWS or
JWE "kid" Header Parameter value.
4.6. "x5u" (X.509 URL) Parameter
The "x5u" (X.509 URL) parameter is a URI [RFC3986] that refers to a
resource for an X.509 public key certificate or certificate chain
[RFC5280]. The identified resource MUST provide a representation of
the certificate or certificate chain that conforms to RFC 5280
[RFC5280] in PEM-encoded form, with each certificate delimited as
specified in Section 6.1 of RFC 4945 [RFC4945]. The key in the first
certificate MUST match the public key represented by other members of
the JWK. The protocol used to acquire the resource MUST provide
integrity protection; an HTTP GET request to retrieve the certificate
MUST use TLS [RFC2818] [RFC5246]; the identity of the server MUST be
validated, as per Section 6 of RFC 6125 [RFC6125]. Use of this
member is OPTIONAL.
While there is no requirement that optional JWK members providing key
usage, algorithm, or other information be present when the "x5u"
member is used, doing so may improve interoperability for
applications that do not handle PKIX certificates [RFC5280]. If
other members are present, the contents of those members MUST be
semantically consistent with the related fields in the first
certificate. For instance, if the "use" member is present, then it
MUST correspond to the usage that is specified in the certificate,
Jones Standards Track [Page 8]
RFC 7517 JSON Web Key (JWK) May 2015
when it includes this information. Similarly, if the "alg" member is
present, it MUST correspond to the algorithm specified in the
certificate.
4.7. "x5c" (X.509 Certificate Chain) Parameter
The "x5c" (X.509 certificate chain) parameter contains a chain of one
or more PKIX certificates [RFC5280]. The certificate chain is
represented as a JSON array of certificate value strings. Each
string in the array is a base64-encoded (Section 4 of [RFC4648] --
not base64url-encoded) DER [ITU.X690.1994] PKIX certificate value.
The PKIX certificate containing the key value MUST be the first
certificate. This MAY be followed by additional certificates, with
each subsequent certificate being the one used to certify the
previous one. The key in the first certificate MUST match the public
key represented by other members of the JWK. Use of this member is
OPTIONAL.
As with the "x5u" member, optional JWK members providing key usage,
algorithm, or other information MAY also be present when the "x5c"
member is used. If other members are present, the contents of those
members MUST be semantically consistent with the related fields in
the first certificate. See the last paragraph of Section 4.6 for
additional guidance on this.
4.8. "x5t" (X.509 Certificate SHA-1 Thumbprint) Parameter
The "x5t" (X.509 certificate SHA-1 thumbprint) parameter is a
base64url-encoded SHA-1 thumbprint (a.k.a. digest) of the DER
encoding of an X.509 certificate [RFC5280]. Note that certificate
thumbprints are also sometimes known as certificate fingerprints.
The key in the certificate MUST match the public key represented by
other members of the JWK. Use of this member is OPTIONAL.
As with the "x5u" member, optional JWK members providing key usage,
algorithm, or other information MAY also be present when the "x5t"
member is used. If other members are present, the contents of those
members MUST be semantically consistent with the related fields in
the referenced certificate. See the last paragraph of Section 4.6
for additional guidance on this.
Jones Standards Track [Page 9]
RFC 7517 JSON Web Key (JWK) May 2015
4.9. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Parameter
The "x5t#S256" (X.509 certificate SHA-256 thumbprint) parameter is a
base64url-encoded SHA-256 thumbprint (a.k.a. digest) of the DER
encoding of an X.509 certificate [RFC5280]. Note that certificate
thumbprints are also sometimes known as certificate fingerprints.
The key in the certificate MUST match the public key represented by
other members of the JWK. Use of this member is OPTIONAL.
As with the "x5u" member, optional JWK members providing key usage,
algorithm, or other information MAY also be present when the
"x5t#S256" member is used. If other members are present, the
contents of those members MUST be semantically consistent with the
related fields in the referenced certificate. See the last paragraph
of Section 4.6 for additional guidance on this.
5. JWK Set Format
A JWK Set is a JSON object that represents a set of JWKs. The JSON
object MUST have a "keys" member, with its value being an array of
JWKs. This JSON object MAY contain whitespace and/or line breaks.
The member names within a JWK Set MUST be unique; JWK Set parsers
MUST either reject JWK Sets with duplicate member names or use a JSON
parser that returns only the lexically last duplicate member name, as
specified in Section 15.12 ("The JSON Object") of ECMAScript 5.1
[ECMAScript].
Additional members can be present in the JWK Set; if not understood
by implementations encountering them, they MUST be ignored.
Parameters for representing additional properties of JWK Sets should
either be registered in the IANA "JSON Web Key Set Parameters"
registry established by Section 8.4 or be a value that contains a
Collision-Resistant Name.
Implementations SHOULD ignore JWKs within a JWK Set that use "kty"
(key type) values that are not understood by them, that are missing
required members, or for which values are out of the supported
ranges.
5.1. "keys" Parameter
The value of the "keys" parameter is an array of JWK values. By
default, the order of the JWK values within the array does not imply
an order of preference among them, although applications of JWK Sets
can choose to assign a meaning to the order for their purposes, if
desired.
Jones Standards Track [Page 10]
RFC 7517 JSON Web Key (JWK) May 2015
6. String Comparison Rules
The string comparison rules for this specification are the same as
those defined in Section 5.3 of [JWS].
7. Encrypted JWK and Encrypted JWK Set Formats
Access to JWKs containing non-public key material by parties without
legitimate access to the non-public information MUST be prevented.
This can be accomplished by encrypting the JWK when potentially
observable by such parties to prevent the disclosure of private or
symmetric key values. The use of an Encrypted JWK, which is a JWE
with the UTF-8 encoding of a JWK as its plaintext value, is
recommended for this purpose. The processing of Encrypted JWKs is
identical to the processing of other JWEs. A "cty" (content type)
Header Parameter value of "jwk+json" MUST be used to indicate that
the content of the JWE is a JWK, unless the application knows that
the encrypted content is a JWK by another means or convention, in
which case the "cty" value would typically be omitted.
JWK Sets containing non-public key material will also need to be
encrypted under these circumstances. The use of an Encrypted JWK
Set, which is a JWE with the UTF-8 encoding of a JWK Set as its
plaintext value, is recommended for this purpose. The processing of
Encrypted JWK Sets is identical to the processing of other JWEs. A
"cty" (content type) Header Parameter value of "jwk-set+json" MUST be
used to indicate that the content of the JWE is a JWK Set, unless the
application knows that the encrypted content is a JWK Set by another
means or convention, in which case the "cty" value would typically be
omitted.
See Appendix C for an example encrypted JWK.
8. IANA Considerations
The following registration procedure is used for all the registries
established by this specification.
The registration procedure for values is Specification Required
[RFC5226] after a three-week review period on the
jose-reg-review@ietf.org mailing list, on the advice of one or more
Designated Experts. However, to allow for the allocation of values
prior to publication, the Designated Experts may approve registration
once they are satisfied that such a specification will be published.
Registration requests sent to the mailing list for review should use
an appropriate subject (e.g., "Request to register JWK parameter:
example").
Jones Standards Track [Page 11]
RFC 7517 JSON Web Key (JWK) May 2015
Within the review period, the Designated Experts will either approve
or deny the registration request, communicating this decision to the
review list and IANA. Denials should include an explanation and, if
applicable, suggestions as to how to make the request successful.
Registration requests that are undetermined for a period longer than
21 days can be brought to the IESG's attention (using the
iesg@ietf.org mailing list) for resolution.
Criteria that should be applied by the Designated Experts include
determining whether the proposed registration duplicates existing
functionality, whether it is likely to be of general applicability or
useful only for a single application, and whether the registration
description is clear.
IANA must only accept registry updates from the Designated Experts
and should direct all requests for registration to the review mailing
list.
It is suggested that multiple Designated Experts be appointed who are
able to represent the perspectives of different applications using
this specification, in order to enable broadly informed review of
registration decisions. In cases where a registration decision could
be perceived as creating a conflict of interest for a particular
Expert, that Expert should defer to the judgment of the other
Experts.
8.1. JSON Web Key Parameters Registry
This section establishes the IANA "JSON Web Key Parameters" registry
for JWK parameter names. The registry records the parameter name,
the key type(s) that the parameter is used with, and a reference to
the specification that defines it. It also records whether the
parameter conveys public or private information. This section
registers the parameter names defined in Section 4. The same JWK
parameter name may be registered multiple times, provided that
duplicate parameter registrations are only for key-type-specific JWK
parameters; in this case, the meaning of the duplicate parameter name
is disambiguated by the "kty" value of the JWK containing it.
8.1.1. Registration Template
Parameter Name:
The name requested (e.g., "kid"). Because a core goal of this
specification is for the resulting representations to be compact,
it is RECOMMENDED that the name be short -- not to exceed 8
characters without a compelling reason to do so. This name is
case sensitive. Names may not match other registered names in a
case-insensitive manner unless the Designated Experts state that
Jones Standards Track [Page 12]
RFC 7517 JSON Web Key (JWK) May 2015
there is a compelling reason to allow an exception. However,
matching names may be registered, provided that the accompanying
sets of "kty" values that the parameter name is used with are
disjoint; for the purposes of matching "kty" values, "*" matches
all values.
Parameter Description:
Brief description of the parameter (e.g., "Key ID").
Used with "kty" Value(s):
The key type parameter value(s) that the parameter name is to be
used with, or the value "*" if the parameter value is used with
all key types. Values may not match other registered "kty" values
in a case-insensitive manner when the registered parameter name is
the same (including when the parameter name matches in a case-
insensitive manner) unless the Designated Experts state that there
is a compelling reason to allow an exception.
Parameter Information Class:
Registers whether the parameter conveys public or private
information. Its value must be either Public or Private.
Change Controller:
For Standards Track RFCs, list the "IESG". For others, give the
name of the responsible party. Other details (e.g., postal
address, email address, home page URI) may also be included.
Specification Document(s):
Reference to the document or documents that specify the parameter,
preferably including URIs that can be used to retrieve copies of
the documents. An indication of the relevant sections may also be
included but is not required.
8.1.2. Initial Registry Contents
o Parameter Name: "kty"
o Parameter Description: Key Type
o Used with "kty" Value(s): *
o Parameter Information Class: Public
o Change Controller: IESG
o Specification Document(s): Section 4.1 of RFC 7517
o Parameter Name: "use"
o Parameter Description: Public Key Use
o Used with "kty" Value(s): *
o Parameter Information Class: Public
o Change Controller: IESG
o Specification Document(s): Section 4.2 of RFC 7517
Jones Standards Track [Page 13]
RFC 7517 JSON Web Key (JWK) May 2015
o Parameter Name: "key_ops"
o Parameter Description: Key Operations
o Used with "kty" Value(s): *
o Parameter Information Class: Public
o Change Controller: IESG
o Specification Document(s): Section 4.3 of RFC 7517
o Parameter Name: "alg"
o Parameter Description: Algorithm
o Used with "kty" Value(s): *
o Parameter Information Class: Public
o Change Controller: IESG
o Specification Document(s): Section 4.4 of RFC 7517
o Parameter Name: "kid"
o Parameter Description: Key ID
o Used with "kty" Value(s): *
o Parameter Information Class: Public
o Change Controller: IESG
o Specification Document(s): Section 4.5 of RFC 7517
o Parameter Name: "x5u"
o Parameter Description: X.509 URL
o Used with "kty" Value(s): *
o Parameter Information Class: Public
o Change Controller: IESG
o Specification Document(s): Section 4.6 of RFC 7517
o Parameter Name: "x5c"
o Parameter Description: X.509 Certificate Chain
o Used with "kty" Value(s): *
o Parameter Information Class: Public
o Change Controller: IESG
o Specification Document(s): Section 4.7 of RFC 7517
o Parameter Name: "x5t"
o Parameter Description: X.509 Certificate SHA-1 Thumbprint
o Used with "kty" Value(s): *
o Parameter Information Class: Public
o Change Controller: IESG
o Specification Document(s): Section 4.8 of RFC 7517
o Parameter Name: "x5t#S256"
o Parameter Description: X.509 Certificate SHA-256 Thumbprint
o Used with "kty" Value(s): *
o Parameter Information Class: Public
o Change Controller: IESG
o Specification Document(s): Section 4.9 of RFC 7517
Jones Standards Track [Page 14]
RFC 7517 JSON Web Key (JWK) May 2015
8.2. JSON Web Key Use Registry
This section establishes the IANA "JSON Web Key Use" registry for JWK
"use" (public key use) member values. The registry records the
public key use value and a reference to the specification that
defines it. This section registers the parameter names defined in
Section 4.2.
8.2.1. Registration Template
Use Member Value:
The name requested (e.g., "sig"). Because a core goal of this
specification is for the resulting representations to be compact,
it is RECOMMENDED that the name be short -- not to exceed 8
characters without a compelling reason to do so. This name is
case sensitive. Names may not match other registered names in a
case-insensitive manner unless the Designated Experts state that
there is a compelling reason to allow an exception.
Use Description:
Brief description of the use (e.g., "Digital Signature or MAC").
Change Controller:
For Standards Track RFCs, list the "IESG". For others, give the
name of the responsible party. Other details (e.g., postal
address, email address, home page URI) may also be included.
Specification Document(s):
Reference to the document or documents that specify the parameter,
preferably including URIs that can be used to retrieve copies of
the documents. An indication of the relevant sections may also be
included but is not required.
8.2.2. Initial Registry Contents
o Use Member Value: "sig"
o Use Description: Digital Signature or MAC
o Change Controller: IESG
o Specification Document(s): Section 4.2 of RFC 7517
o Use Member Value: "enc"
o Use Description: Encryption
o Change Controller: IESG
o Specification Document(s): Section 4.2 of RFC 7517
Jones Standards Track [Page 15]
RFC 7517 JSON Web Key (JWK) May 2015
8.3. JSON Web Key Operations Registry
This section establishes the IANA "JSON Web Key Operations" registry
for values of JWK "key_ops" array elements. The registry records the
key operation value and a reference to the specification that defines
it. This section registers the parameter names defined in
Section 4.3.
8.3.1. Registration Template
Key Operation Value:
The name requested (e.g., "sign"). Because a core goal of this
specification is for the resulting representations to be compact,
it is RECOMMENDED that the name be short -- not to exceed 8
characters without a compelling reason to do so. This name is
case sensitive. Names may not match other registered names in a
case-insensitive manner unless the Designated Experts state that
there is a compelling reason to allow an exception.
Key Operation Description:
Brief description of the key operation (e.g., "Compute digital
signature or MAC").
Change Controller:
For Standards Track RFCs, list the "IESG". For others, give the
name of the responsible party. Other details (e.g., postal
address, email address, home page URI) may also be included.
Specification Document(s):
Reference to the document or documents that specify the parameter,
preferably including URIs that can be used to retrieve copies of
the documents. An indication of the relevant sections may also be
included but is not required.
8.3.2. Initial Registry Contents
o Key Operation Value: "sign"
o Key Operation Description: Compute digital signature or MAC
o Change Controller: IESG
o Specification Document(s): Section 4.3 of RFC 7517
o Key Operation Value: "verify"
o Key Operation Description: Verify digital signature or MAC
o Change Controller: IESG
o Specification Document(s): Section 4.3 of RFC 7517
Jones Standards Track [Page 16]
RFC 7517 JSON Web Key (JWK) May 2015
o Key Operation Value: "encrypt"
o Key Operation Description: Encrypt content
o Change Controller: IESG
o Specification Document(s): Section 4.3 of RFC 7517
o Key Operation Value: "decrypt"
o Key Operation Description: Decrypt content and validate
decryption, if applicable
o Change Controller: IESG
o Specification Document(s): Section 4.3 of RFC 7517
o Key Operation Value: "wrapKey"
o Key Operation Description: Encrypt key
o Change Controller: IESG
o Specification Document(s): Section 4.3 of RFC 7517
o Key Operation Value: "unwrapKey"
o Key Operation Description: Decrypt key and validate decryption, if
applicable
o Change Controller: IESG
o Specification Document(s): Section 4.3 of RFC 7517
o Key Operation Value: "deriveKey"
o Key Operation Description: Derive key
o Change Controller: IESG
o Specification Document(s): Section 4.3 of RFC 7517
o Key Operation Value: "deriveBits"
o Key Operation Description: Derive bits not to be used as a key
o Change Controller: IESG
o Specification Document(s): Section 4.3 of RFC 7517
8.4. JSON Web Key Set Parameters Registry
This section establishes the IANA "JSON Web Key Set Parameters"
registry for JWK Set parameter names. The registry records the
parameter name and a reference to the specification that defines it.
This section registers the parameter names defined in Section 5.
8.4.1. Registration Template
Parameter Name:
The name requested (e.g., "keys"). Because a core goal of this
specification is for the resulting representations to be compact,
it is RECOMMENDED that the name be short -- not to exceed 8
characters without a compelling reason to do so. This name is
case sensitive. Names may not match other registered names in a
case-insensitive manner unless the Designated Experts state that
there is a compelling reason to allow an exception.
Jones Standards Track [Page 17]
RFC 7517 JSON Web Key (JWK) May 2015
Parameter Description:
Brief description of the parameter (e.g., "Array of JWK values").
Change Controller:
For Standards Track RFCs, list the "IESG". For others, give the
name of the responsible party. Other details (e.g., postal
address, email address, home page URI) may also be included.
Specification Document(s):
Reference to the document or documents that specify the parameter,
preferably including URIs that can be used to retrieve copies of
the documents. An indication of the relevant sections may also be
included but is not required.
8.4.2. Initial Registry Contents
o Parameter Name: "keys"
o Parameter Description: Array of JWK Values
o Change Controller: IESG
o Specification Document(s): Section 5.1 of RFC 7517
8.5. Media Type Registration
8.5.1. Registry Contents
This section registers the "application/jwk+json" and "application/
jwk-set+json" media types [RFC2046] in the "Media Types" registry
[IANA.MediaTypes] in the manner described in RFC 6838 [RFC6838],
which can be used to indicate that the content is a JWK or a JWK Set,
respectively.
o Type Name: application
o Subtype Name: jwk+json
o Required Parameters: n/a
o Optional Parameters: n/a
o Encoding considerations: 8bit; application/jwk+json values are
represented as a JSON object; UTF-8 encoding SHOULD be employed
for the JSON object.
o Security Considerations: See the Security Considerations section
of RFC 7517.
o Interoperability Considerations: n/a
o Published Specification: RFC 7517