idnits 2.17.00 (12 Aug 2021) /tmp/idnits58189/draft-ietf-jose-json-web-key-15.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (September 3, 2013) is 3181 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. 'ECMAScript' -- Possible downref: Non-RFC (?) normative reference: ref. 'ITU.X690.1994' == Outdated reference: draft-ietf-jose-json-web-algorithms has been published as RFC 7518 == Outdated reference: draft-ietf-jose-json-web-encryption has been published as RFC 7516 == Outdated reference: draft-ietf-jose-json-web-signature has been published as RFC 7515 ** Downref: Normative reference to an Historic RFC: RFC 1421 ** Downref: Normative reference to an Informational RFC: RFC 2818 ** Obsolete normative reference: RFC 4288 (Obsoleted by RFC 6838) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) -- Obsolete informational reference (is this intentional?): RFC 3447 (Obsoleted by RFC 8017) Summary: 6 errors (**), 0 flaws (~~), 4 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 JOSE Working Group M. Jones 3 Internet-Draft Microsoft 4 Intended status: Standards Track September 3, 2013 5 Expires: March 7, 2014 7 JSON Web Key (JWK) 8 draft-ietf-jose-json-web-key-15 10 Abstract 12 A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) data 13 structure that represents a cryptographic key. This specification 14 also defines a JSON Web Key Set (JWK Set) JSON data structure for 15 representing a set of JWKs. Cryptographic algorithms and identifiers 16 for use with this specification are described in the separate JSON 17 Web Algorithms (JWA) specification and IANA registries defined by 18 that specification. 20 Status of this Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on March 7, 2014. 37 Copyright Notice 39 Copyright (c) 2013 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 56 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 3. JSON Web Key (JWK) Format . . . . . . . . . . . . . . . . . . 4 58 3.1. "kty" (Key Type) Parameter . . . . . . . . . . . . . . . . 4 59 3.2. "use" (Key Use) Parameter . . . . . . . . . . . . . . . . 5 60 3.3. "alg" (Algorithm) Parameter . . . . . . . . . . . . . . . 5 61 3.4. "kid" (Key ID) Parameter . . . . . . . . . . . . . . . . . 5 62 3.5. "x5u" (X.509 URL) Parameter . . . . . . . . . . . . . . . 5 63 3.6. "x5t" (X.509 Certificate Thumbprint) Parameter . . . . . . 6 64 3.7. "x5c" (X.509 Certificate Chain) Parameter . . . . . . . . 6 65 4. JSON Web Key Set (JWK Set) Format . . . . . . . . . . . . . . 6 66 4.1. "keys" (JSON Web Key Set) Parameter . . . . . . . . . . . 6 67 5. String Comparison Rules . . . . . . . . . . . . . . . . . . . 7 68 6. Encrypted JWK and Encrypted JWK Set Formats . . . . . . . . . 7 69 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 70 7.1. JSON Web Key Parameters Registry . . . . . . . . . . . . . 8 71 7.1.1. Registration Template . . . . . . . . . . . . . . . . 8 72 7.1.2. Initial Registry Contents . . . . . . . . . . . . . . 9 73 7.2. JSON Web Key Set Parameters Registry . . . . . . . . . . . 9 74 7.2.1. Registration Template . . . . . . . . . . . . . . . . 10 75 7.2.2. Initial Registry Contents . . . . . . . . . . . . . . 10 76 7.3. JSON Web Signature and Encryption Type Values 77 Registration . . . . . . . . . . . . . . . . . . . . . . . 10 78 7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 10 79 7.4. Media Type Registration . . . . . . . . . . . . . . . . . 10 80 7.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 11 81 8. Security Considerations . . . . . . . . . . . . . . . . . . . 12 82 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12 83 9.1. Normative References . . . . . . . . . . . . . . . . . . . 12 84 9.2. Informative References . . . . . . . . . . . . . . . . . . 14 85 Appendix A. Example JSON Web Key Sets . . . . . . . . . . . . . . 14 86 A.1. Example Public Keys . . . . . . . . . . . . . . . . . . . 14 87 A.2. Example Private Keys . . . . . . . . . . . . . . . . . . . 15 88 A.3. Example Symmetric Keys . . . . . . . . . . . . . . . . . . 17 89 Appendix B. Example Use of "x5c" (X.509 Certificate Chain) 90 Parameter . . . . . . . . . . . . . . . . . . . . . . 17 91 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 18 92 Appendix D. Document History . . . . . . . . . . . . . . . . . . 19 93 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 22 95 1. Introduction 97 A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) [RFC4627] 98 data structure that represents a cryptographic key. This 99 specification also defines a JSON Web Key Set (JWK Set) JSON data 100 structure for representing a set of JWKs. Cryptographic algorithms 101 and identifiers for use with this specification are described in the 102 separate JSON Web Algorithms (JWA) [JWA] specification and IANA 103 registries defined by that specification. 105 Goals for this specification do not include representing certificate 106 chains, representing certified keys, and replacing X.509 107 certificates. 109 JWKs and JWK Sets are used in the JSON Web Signature (JWS) [JWS] and 110 JSON Web Encryption (JWE) [JWE] specifications. 112 Names defined by this specification are short because a core goal is 113 for the resulting representations to be compact. 115 1.1. Notational Conventions 117 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 118 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 119 document are to be interpreted as described in Key words for use in 120 RFCs to Indicate Requirement Levels [RFC2119]. 122 2. Terminology 124 JSON Web Key (JWK) A JSON object that represents a cryptographic 125 key. 127 JSON Web Key Set (JWK Set) A JSON object that contains an array of 128 JWKs as the value of its "keys" member. 130 Base64url Encoding Base64 encoding using the URL- and filename-safe 131 character set defined in Section 5 of RFC 4648 [RFC4648], with all 132 trailing '=' characters omitted (as permitted by Section 3.2). 133 (See Appendix C of [JWS] for notes on implementing base64url 134 encoding without padding.) 136 Collision Resistant Namespace A namespace that allows names to be 137 allocated in a manner such that they are highly unlikely to 138 collide with other names. Examples of Collision Resistant 139 Namespaces include: Domain Names, Object Identifiers (OIDs) as 140 defined in the ITU-T X.660 and X.670 Recommendation series, and 141 Universally Unique IDentifiers (UUIDs) [RFC4122]. When using an 142 administratively delegated namespace, the definer of a name needs 143 to take reasonable precautions to ensure they are in control of 144 the portion of the namespace they use to define the name. 146 3. JSON Web Key (JWK) Format 148 A JSON Web Key (JWK) is a JSON object containing specific members, as 149 specified below. Those members that are common to multiple key types 150 are defined below. 152 In addition to the common parameters, each JWK will have members that 153 are specific to the kind of key being represented. These members 154 represent the parameters of the key. Section 5 of the JSON Web 155 Algorithms (JWA) [JWA] specification defines multiple kinds of 156 cryptographic keys and their associated members. 158 The member names within a JWK MUST be unique; recipients MUST either 159 reject JWKs with duplicate member names or use a JSON parser that 160 returns only the lexically last duplicate member name, as specified 161 in Section 15.12 (The JSON Object) of ECMAScript 5.1 [ECMAScript]. 163 Additional members MAY be present in the JWK. If not understood by 164 implementations encountering them, they MUST be ignored. Member 165 names used for representing key parameters for different kinds of 166 keys need not be distinct. Any new member name SHOULD either be 167 registered in the IANA JSON Web Key Parameters registry Section 7.1 168 or be a value that contains a Collision Resistant Namespace. 170 3.1. "kty" (Key Type) Parameter 172 The "kty" (key type) member identifies the cryptographic algorithm 173 family used with the key. "kty" values SHOULD either be registered in 174 the IANA JSON Web Key Types registry [JWA] or be a value that 175 contains a Collision Resistant Namespace. The "kty" value is a case 176 sensitive string. Use of this member is REQUIRED. 178 A list of defined "kty" values can be found in the IANA JSON Web Key 179 Types registry [JWA]; the initial contents of this registry are the 180 values defined in Section 5.1 of the JSON Web Algorithms (JWA) [JWA] 181 specification. 183 Additional members used with these "kty" values can be found in the 184 IANA JSON Web Key Parameters registry Section 7.1; the initial 185 contents of this registry are the values defined in Sections 5.2 and 186 5.3 of the JSON Web Algorithms (JWA) [JWA] specification. 188 3.2. "use" (Key Use) Parameter 190 The "use" (key use) member identifies the intended use of the key. 191 Values defined by this specification are: 193 o "sig" (signature or MAC operation) 195 o "enc" (encryption) 197 Other values MAY be used. The "use" value is a case sensitive 198 string. Use of this member is OPTIONAL. 200 3.3. "alg" (Algorithm) Parameter 202 The "alg" (algorithm) member identifies the algorithm intended for 203 use with the key. The values used in this field are the same as 204 those used in the JWS [JWS] and JWE [JWE] "alg" and "enc" header 205 parameters; these values can be found in the JSON Web Signature and 206 Encryption Algorithms registry [JWA]. Use of this member is 207 OPTIONAL. 209 3.4. "kid" (Key ID) Parameter 211 The "kid" (key ID) member can be used to match a specific key. This 212 can be used, for instance, to choose among a set of keys within a JWK 213 Set during key rollover. The interpretation of the "kid" value is 214 unspecified. When "kid" values are used within a JWK Set, different 215 keys within the JWK Set SHOULD use distinct "kid" values. The "kid" 216 value is a case sensitive string. Use of this member is OPTIONAL. 218 When used with JWS or JWE, the "kid" value can be used to match a JWS 219 or JWE "kid" header parameter value. 221 3.5. "x5u" (X.509 URL) Parameter 223 The "x5u" (X.509 URL) member is a URI [RFC3986] that refers to a 224 resource for an X.509 public key certificate or certificate chain 225 [RFC5280]. The identified resource MUST provide a representation of 226 the certificate or certificate chain that conforms to RFC 5280 227 [RFC5280] in PEM encoded form [RFC1421]. The key in the first 228 certificate MUST match the bare public key represented by other 229 members of the JWK. The protocol used to acquire the resource MUST 230 provide integrity protection; an HTTP GET request to retrieve the 231 certificate MUST use TLS [RFC2818] [RFC5246]; the identity of the 232 server MUST be validated, as per Section 3.1 of HTTP Over TLS 233 [RFC2818]. Use of this member is OPTIONAL. 235 3.6. "x5t" (X.509 Certificate Thumbprint) Parameter 237 The "x5t" (X.509 Certificate Thumbprint) member is a base64url 238 encoded SHA-1 thumbprint (a.k.a. digest) of the DER encoding of an 239 X.509 certificate [RFC5280]. The key in the certificate MUST match 240 the bare public key represented by other members of the JWK. Use of 241 this member is OPTIONAL. 243 3.7. "x5c" (X.509 Certificate Chain) Parameter 245 The "x5c" (X.509 Certificate Chain) member contains a chain of one or 246 more PKIX certificates [RFC5280]. The certificate chain is 247 represented as a JSON array of certificate value strings. Each 248 string in the array is a base64 encoded ([RFC4648] Section 4 -- not 249 base64url encoded) DER [ITU.X690.1994] PKIX certificate value. The 250 PKIX certificate containing the key value MUST be the first 251 certificate. This MAY be followed by additional certificates, with 252 each subsequent certificate being the one used to certify the 253 previous one. The key in the first certificate MUST match the bare 254 public key represented by other members of the JWK. Use of this 255 member is OPTIONAL. 257 4. JSON Web Key Set (JWK Set) Format 259 A JSON Web Key Set (JWK Set) is a JSON object that contains an array 260 of JSON Web Key values as the value of its "keys" member. 262 The member names within a JWK Set MUST be unique; recipients MUST 263 either reject JWK Sets with duplicate member names or use a JSON 264 parser that returns only the lexically last duplicate member name, as 265 specified in Section 15.12 (The JSON Object) of ECMAScript 5.1 266 [ECMAScript]. 268 Additional members MAY be present in the JWK Set. If not understood 269 by implementations encountering them, they MUST be ignored. 270 Parameters for representing additional properties of JWK Sets SHOULD 271 either be registered in the IANA JSON Web Key Set Parameters registry 272 Section 7.2 or be a value that contains a Collision Resistant 273 Namespace. 275 4.1. "keys" (JSON Web Key Set) Parameter 277 The value of the "keys" (JSON Web Key Set) member is an array of JSON 278 Web Key (JWK) values. Use of this member is REQUIRED. 280 5. String Comparison Rules 282 Processing a JWK inevitably requires comparing known strings to 283 values in JSON objects. For example, in checking what the key type 284 is, the Unicode string encoding "kty" will be checked against the 285 member names in the JWK to see if there is a matching name. 287 Comparisons between JSON strings and other Unicode strings MUST be 288 performed by comparing Unicode code points without normalization as 289 specified in the String Comparison Rules in Section 5.3 of [JWS]. 291 6. Encrypted JWK and Encrypted JWK Set Formats 293 JWKs containing non-public key material will need to be encrypted in 294 some contexts to prevent the disclosure of private or symmetric key 295 values to unintended parties. The use of an Encrypted JWK, which is 296 a JWE with a JWK as its plaintext value, is RECOMMENED for this 297 purpose. The processing of Encrypted JWKs is identical to the 298 processing of other JWEs. A "cty" (content type) header parameter 299 value of "JWK" can be used to indicate that the content of the JWE is 300 a JWK in contexts where this is useful. 302 JWK Sets containing non-public key material will similarly need to be 303 encrypted. The use of an Encrypted JWK Set, which is a JWE with a 304 JWK Set as its plaintext value, is RECOMMENED for this purpose. The 305 processing of Encrypted JWK Sets is identical to the processing of 306 other JWEs. A "cty" (content type) header parameter value of 307 "JWK-SET" can be used to indicate that the content of the JWE is a 308 JWK Set in contexts where this is useful. 310 7. IANA Considerations 312 The following registration procedure is used for all the registries 313 established by this specification. 315 Values are registered with a Specification Required [RFC5226] after a 316 two-week review period on the [TBD]@ietf.org mailing list, on the 317 advice of one or more Designated Experts. However, to allow for the 318 allocation of values prior to publication, the Designated Expert(s) 319 may approve registration once they are satisfied that such a 320 specification will be published. 322 Registration requests must be sent to the [TBD]@ietf.org mailing list 323 for review and comment, with an appropriate subject (e.g., "Request 324 for access token type: example"). [[ Note to RFC-EDITOR: The name of 325 the mailing list should be determined in consultation with the IESG 326 and IANA. Suggested name: jose-reg-review. ]] 328 Within the review period, the Designated Expert(s) will either 329 approve or deny the registration request, communicating this decision 330 to the review list and IANA. Denials should include an explanation 331 and, if applicable, suggestions as to how to make the request 332 successful. 334 IANA must only accept registry updates from the Designated Expert(s) 335 and should direct all requests for registration to the review mailing 336 list. 338 7.1. JSON Web Key Parameters Registry 340 This specification establishes the IANA JSON Web Key Parameters 341 registry for reserved JWK parameter names. The registry records the 342 reserved parameter name and a reference to the specification that 343 defines it. It also records whether the parameter conveys public or 344 private information. This specification registers the parameter 345 names defined in Section 3. The same JWK parameter name may be 346 registered multiple times, provided that duplicate parameter 347 registrations are only for algorithm-specific JWK parameters; in this 348 case, the meaning of the duplicate parameter name is disambiguated by 349 the "kty" value of the JWK containing it. 351 7.1.1. Registration Template 353 Parameter Name: 354 The name requested (e.g., "example"). This name is case 355 sensitive. Names that match other registered names in a case 356 insensitive manner SHOULD NOT be accepted. 358 Parameter Information Class: 359 Registers whether the parameter conveys public or private 360 information. Its value must be one the words Public or Private. 362 Change Controller: 363 For Standards Track RFCs, state "IETF". For others, give the name 364 of the responsible party. Other details (e.g., postal address, 365 email address, home page URI) may also be included. 367 Specification Document(s): 368 Reference to the document(s) that specify the parameter, 369 preferably including URI(s) that can be used to retrieve copies of 370 the document(s). An indication of the relevant sections may also 371 be included but is not required. 373 7.1.2. Initial Registry Contents 375 o Parameter Name: "kty" 376 o Parameter Information Class: Public 377 o Change Controller: IETF 378 o Specification Document(s): Section 3.1 of [[ this document ]] 380 o Parameter Name: "use" 381 o Parameter Information Class: Public 382 o Change Controller: IETF 383 o Specification Document(s): Section 3.2 of [[ this document ]] 385 o Parameter Name: "alg" 386 o Parameter Information Class: Public 387 o Change Controller: IETF 388 o Specification Document(s): Section 3.3 of [[ this document ]] 390 o Parameter Name: "kid" 391 o Parameter Information Class: Public 392 o Change Controller: IETF 393 o Specification Document(s): Section 3.4 of [[ this document ]] 395 o Parameter Name: "x5u" 396 o Parameter Information Class: Public 397 o Change Controller: IETF 398 o Specification Document(s): Section 3.5 of [[ this document ]] 400 o Parameter Name: "x5t" 401 o Parameter Information Class: Public 402 o Change Controller: IETF 403 o Specification Document(s): Section 3.6 of [[ this document ]] 405 o Parameter Name: "x5c" 406 o Parameter Information Class: Public 407 o Change Controller: IETF 408 o Specification Document(s): Section 3.7 of [[ this document ]] 410 7.2. JSON Web Key Set Parameters Registry 412 This specification establishes the IANA JSON Web Key Set Parameters 413 registry for reserved JWK Set parameter names. The registry records 414 the reserved parameter name and a reference to the specification that 415 defines it. This specification registers the parameter names defined 416 in Section 4. 418 7.2.1. Registration Template 420 Parameter Name: 421 The name requested (e.g., "example"). This name is case 422 sensitive. Names that match other registered names in a case 423 insensitive manner SHOULD NOT be accepted. 425 Change Controller: 426 For Standards Track RFCs, state "IETF". For others, give the name 427 of the responsible party. Other details (e.g., postal address, 428 email address, home page URI) may also be included. 430 Specification Document(s): 431 Reference to the document(s) that specify the parameter, 432 preferably including URI(s) that can be used to retrieve copies of 433 the document(s). An indication of the relevant sections may also 434 be included but is not required. 436 7.2.2. Initial Registry Contents 438 o Parameter Name: "keys" 439 o Change Controller: IETF 440 o Specification Document(s): Section 4.1 of [[ this document ]] 442 7.3. JSON Web Signature and Encryption Type Values Registration 444 7.3.1. Registry Contents 446 This specification registers the "JWK" and "JWK-SET" type values in 447 the IANA JSON Web Signature and Encryption Type Values registry 448 [JWS], which can be used to indicate, respectively, that the content 449 is a JWK or a JWK Set. 451 o "typ" Header Parameter Value: "JWK" 452 o Abbreviation for MIME Type: application/jwk+json 453 o Change Controller: IETF 454 o Specification Document(s): Section 3 of [[ this document ]] 456 o "typ" Header Parameter Value: "JWK-SET" 457 o Abbreviation for MIME Type: application/jwk-set+json 458 o Change Controller: IETF 459 o Specification Document(s): Section 4 of [[ this document ]] 461 7.4. Media Type Registration 462 7.4.1. Registry Contents 464 This specification registers the "application/jwk+json" and 465 "application/jwk-set+json" Media Types [RFC2046] in the MIME Media 466 Type registry [RFC4288], which can be used to indicate, respectively, 467 that the content is a JWK or a JWK Set. 469 o Type Name: application 470 o Subtype Name: jwk+json 471 o Required Parameters: n/a 472 o Optional Parameters: n/a 473 o Encoding considerations: application/jwk+json values are 474 represented as JSON object; UTF-8 encoding SHOULD be employed for 475 the JSON object. 476 o Security Considerations: See the Security Considerations section 477 of [[ this document ]] 478 o Interoperability Considerations: n/a 479 o Published Specification: [[ this document ]] 480 o Applications that use this media type: TBD 481 o Additional Information: Magic number(s): n/a, File extension(s): 482 n/a, Macintosh file type code(s): n/a 483 o Person & email address to contact for further information: Michael 484 B. Jones, mbj@microsoft.com 485 o Intended Usage: COMMON 486 o Restrictions on Usage: none 487 o Author: Michael B. Jones, mbj@microsoft.com 488 o Change Controller: IETF 490 o Type Name: application 491 o Subtype Name: jwk-set+json 492 o Required Parameters: n/a 493 o Optional Parameters: n/a 494 o Encoding considerations: application/jwk-set+json values are 495 represented as a JSON Object; UTF-8 encoding SHOULD be employed 496 for the JSON object. 497 o Security Considerations: See the Security Considerations section 498 of [[ this document ]] 499 o Interoperability Considerations: n/a 500 o Published Specification: [[ this document ]] 501 o Applications that use this media type: TBD 502 o Additional Information: Magic number(s): n/a, File extension(s): 503 n/a, Macintosh file type code(s): n/a 504 o Person & email address to contact for further information: Michael 505 B. Jones, mbj@microsoft.com 506 o Intended Usage: COMMON 507 o Restrictions on Usage: none 508 o Author: Michael B. Jones, mbj@microsoft.com 509 o Change Controller: IETF 511 8. Security Considerations 513 All of the security issues faced by any cryptographic application 514 must be faced by a JWS/JWE/JWK agent. Among these issues are 515 protecting the user's private and symmetric keys, preventing various 516 attacks, and helping the user avoid mistakes such as inadvertently 517 encrypting a message for the wrong recipient. The entire list of 518 security considerations is beyond the scope of this document, but 519 some significant considerations are listed here. 521 A key is no more trustworthy than the method by which it was 522 received. 524 Private and symmetric keys MUST be protected from disclosure to 525 unintended parties. One recommended means of doing so is to encrypt 526 JWKs or JWK Sets containing them by using the JWK or JWK Set value as 527 the plaintext of a JWE. 529 The security considerations in RFC 3447 [RFC3447] and RFC 6030 530 [RFC6030] about protecting private and symmetric keys also apply to 531 this specification. 533 The security considerations in XML DSIG 2.0 534 [W3C.CR-xmldsig-core2-20120124], about key representations also apply 535 to this specification, other than those that are XML specific. 537 The TLS Requirements in [JWS] also apply to this specification. 539 9. References 541 9.1. Normative References 543 [ECMAScript] 544 Ecma International, "ECMAScript Language Specification, 545 5.1 Edition", ECMA 262, June 2011. 547 [ITU.X690.1994] 548 International Telecommunications Union, "Information 549 Technology - ASN.1 encoding rules: Specification of Basic 550 Encoding Rules (BER), Canonical Encoding Rules (CER) and 551 Distinguished Encoding Rules (DER)", ITU-T Recommendation 552 X.690, 1994. 554 [JWA] Jones, M., "JSON Web Algorithms (JWA)", 555 draft-ietf-jose-json-web-algorithms (work in progress), 556 September 2013. 558 [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web 559 Encryption (JWE)", draft-ietf-jose-json-web-encryption 560 (work in progress), September 2013. 562 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 563 Signature (JWS)", draft-ietf-jose-json-web-signature (work 564 in progress), September 2013. 566 [RFC1421] Linn, J., "Privacy Enhancement for Internet Electronic 567 Mail: Part I: Message Encryption and Authentication 568 Procedures", RFC 1421, February 1993. 570 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 571 Extensions (MIME) Part Two: Media Types", RFC 2046, 572 November 1996. 574 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 575 Requirement Levels", BCP 14, RFC 2119, March 1997. 577 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 579 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 580 Resource Identifier (URI): Generic Syntax", STD 66, 581 RFC 3986, January 2005. 583 [RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and 584 Registration Procedures", RFC 4288, December 2005. 586 [RFC4627] Crockford, D., "The application/json Media Type for 587 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 589 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 590 Encodings", RFC 4648, October 2006. 592 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 593 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 594 May 2008. 596 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 597 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 599 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 600 Housley, R., and W. Polk, "Internet X.509 Public Key 601 Infrastructure Certificate and Certificate Revocation List 602 (CRL) Profile", RFC 5280, May 2008. 604 [W3C.CR-xmldsig-core2-20120124] 605 Eastlake, D., Reagle, J., Yiu, K., Solo, D., Datta, P., 606 Hirsch, F., Cantor, S., and T. Roessler, "XML Signature 607 Syntax and Processing Version 2.0", World Wide Web 608 Consortium CR CR-xmldsig-core2-20120124, January 2012, 609 . 611 9.2. Informative References 613 [MagicSignatures] 614 Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic 615 Signatures", January 2011. 617 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 618 Standards (PKCS) #1: RSA Cryptography Specifications 619 Version 2.1", RFC 3447, February 2003. 621 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 622 Unique IDentifier (UUID) URN Namespace", RFC 4122, 623 July 2005. 625 [RFC6030] Hoyer, P., Pei, M., and S. Machani, "Portable Symmetric 626 Key Container (PSKC)", RFC 6030, October 2010. 628 Appendix A. Example JSON Web Key Sets 630 A.1. Example Public Keys 632 The following example JWK Set contains two public keys represented as 633 JWKs: one using an Elliptic Curve algorithm and a second one using an 634 RSA algorithm. The first specifies that the key is to be used for 635 encryption. The second specifies that the key is to be used with the 636 "RS256" algorithm. Both provide a Key ID for key matching purposes. 637 In both cases, integers are represented using the base64url encoding 638 of their big endian representations. (Long lines are broken are for 639 display purposes only.) 640 {"keys": 641 [ 642 {"kty":"EC", 643 "crv":"P-256", 644 "x":"MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4", 645 "y":"4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM", 646 "use":"enc", 647 "kid":"1"}, 649 {"kty":"RSA", 650 "n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx 651 4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMs 652 tn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2 653 QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbI 654 SD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqb 655 w0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw", 656 "e":"AQAB", 657 "alg":"RS256", 658 "kid":"2011-04-29"} 659 ] 660 } 662 A.2. Example Private Keys 664 The following example JWK Set contains two keys represented as JWKs 665 containing both public and private key values: one using an Elliptic 666 Curve algorithm and a second one using an RSA algorithm. This 667 example extends the example in the previous section, adding private 668 key values. (Line breaks are for display purposes only.) 669 {"keys": 670 [ 671 {"kty":"EC", 672 "crv":"P-256", 673 "x":"MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4", 674 "y":"4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM", 675 "d":"870MB6gfuTJ4HtUnUvYMyJpr5eUZNP4Bk43bVdj3eAE", 676 "use":"enc", 677 "kid":"1"}, 679 {"kty":"RSA", 680 "n":"0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx4 681 cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMst 682 n64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2Q 683 vzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbIS 684 D08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqbw 685 0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw", 686 "e":"AQAB", 687 "d":"X4cTteJY_gn4FYPsXB8rdXix5vwsg1FLN5E3EaG6RJoVH-HLLKD9 688 M7dx5oo7GURknchnrRweUkC7hT5fJLM0WbFAKNLWY2vv7B6NqXSzUvxT0_YSfqij 689 wp3RTzlBaCxWp4doFk5N2o8Gy_nHNKroADIkJ46pRUohsXywbReAdYaMwFs9tv8d 690 _cPVY3i07a3t8MN6TNwm0dSawm9v47UiCl3Sk5ZiG7xojPLu4sbg1U2jx4IBTNBz 691 nbJSzFHK66jT8bgkuqsk0GjskDJk19Z4qwjwbsnn4j2WBii3RL-Us2lGVkY8fkFz 692 me1z0HbIkfz0Y6mqnOYtqc0X4jfcKoAC8Q", 693 "p":"83i-7IvMGXoMXCskv73TKr8637FiO7Z27zv8oj6pbWUQyLPQBQxtPV 694 nwD20R-60eTDmD2ujnMt5PoqMrm8RfmNhVWDtjjMmCMjOpSXicFHj7XOuVIYQyqV 695 WlWEh6dN36GVZYk93N8Bc9vY41xy8B9RzzOGVQzXvNEvn7O0nVbfs", 696 "q":"3dfOR9cuYq-0S-mkFLzgItgMEfFzB2q3hWehMuG0oCuqnb3vobLyum 697 qjVZQO1dIrdwgTnCdpYzBcOfW5r370AFXjiWft_NGEiovonizhKpo9VVS78TzFgx 698 kIdrecRezsZ-1kYd_s1qDbxtkDEgfAITAG9LUnADun4vIcb6yelxk", 699 "dp":"G4sPXkc6Ya9y8oJW9_ILj4xuppu0lzi_H7VTkS8xj5SdX3coE0oim 700 YwxIi2emTAue0UOa5dpgFGyBJ4c8tQ2VF402XRugKDTP8akYhFo5tAA77Qe_Nmtu 701 YZc3C3m3I24G2GvR5sSDxUyAN2zq8Lfn9EUms6rY3Ob8YeiKkTiBj0", 702 "dq":"s9lAH9fggBsoFR8Oac2R_E2gw282rT2kGOAhvIllETE1efrA6huUU 703 vMfBcMpn8lqeW6vzznYY5SSQF7pMdC_agI3nG8Ibp1BUb0JUiraRNqUfLhcQb_d9 704 GF4Dh7e74WbRsobRonujTYN1xCaP6TO61jvWrX-L18txXw494Q_cgk", 705 "qi":"GyM_p6JrXySiz1toFgKbWV-JdI3jQ4ypu9rbMWx3rQJBfmt0FoYzg 706 UIZEVFEcOqwemRN81zoDAaa-Bk0KWNGDjJHZDdDmFhW3AN7lI-puxk_mHZGJ11rx 707 yR8O55XLSe3SPmRfKwZI6yU24ZxvQKFYItdldUKGzO6Ia6zTKhAVRU", 708 "alg":"RS256", 709 "kid":"2011-04-29"} 710 ] 711 } 713 A.3. Example Symmetric Keys 715 The following example JWK Set contains two symmetric keys represented 716 as JWKs: one designated as being for use with the AES Key Wrap 717 algorithm and a second one that is an HMAC key. (Line breaks are for 718 display purposes only.) 720 {"keys": 721 [ 722 {"kty":"oct", 723 "alg":"A128KW", 724 "k":"GawgguFyGrWKav7AX4VKUg"}, 726 {"kty":"oct", 727 "k":"AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75 728 aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow", 729 "kid":"HMAC key used in JWS A.1 example"} 730 ] 731 } 733 Appendix B. Example Use of "x5c" (X.509 Certificate Chain) Parameter 734 The following is an example of a JWK with a RSA signing key 735 represented both as a bare public key and as an X.509 certificate 736 using the "x5c" parameter: 738 {"kty":"RSA", 739 "use":"sig", 740 "kid":"1b94c", 741 "n":"vrjOfz9Ccdgx5nQudyhdoR17V-IubWMeOZCwX_jj0hgAsz2J_pqYW08 742 PLbK_PdiVGKPrqzmDIsLI7sA25VEnHU1uCLNwBuUiCO11_-7dYbsr4iJmG0Q 743 u2j8DsVyT1azpJC_NG84Ty5KKthuCaPod7iI7w0LK9orSMhBEwwZDCxTWq4a 744 YWAchc8t-emd9qOvWtVMDC2BXksRngh6X5bUYLy6AyHKvj-nUy1wgzjYQDwH 745 MTplCoLtU-o-8SNnZ1tmRoGE9uJkBLdh5gFENabWnU5m1ZqZPdwS-qo-meMv 746 VfJb6jJVWRpl2SUtCnYG2C32qvbWbjZ_jBPD5eunqsIo1vQ", 747 "e":"AQAB", 748 "x5c": 749 ["MIIDQjCCAiqgAwIBAgIGATz/FuLiMA0GCSqGSIb3DQEBBQUAMGIxCzAJB 750 gNVBAYTAlVTMQswCQYDVQQIEwJDTzEPMA0GA1UEBxMGRGVudmVyMRwwGgYD 751 VQQKExNQaW5nIElkZW50aXR5IENvcnAuMRcwFQYDVQQDEw5CcmlhbiBDYW1 752 wYmVsbDAeFw0xMzAyMjEyMzI5MTVaFw0xODA4MTQyMjI5MTVaMGIxCzAJBg 753 NVBAYTAlVTMQswCQYDVQQIEwJDTzEPMA0GA1UEBxMGRGVudmVyMRwwGgYDV 754 QQKExNQaW5nIElkZW50aXR5IENvcnAuMRcwFQYDVQQDEw5CcmlhbiBDYW1w 755 YmVsbDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAL64zn8/QnH 756 YMeZ0LncoXaEde1fiLm1jHjmQsF/449IYALM9if6amFtPDy2yvz3YlRij66 757 s5gyLCyO7ANuVRJx1NbgizcAblIgjtdf/u3WG7K+IiZhtELto/A7Fck9Ws6 758 SQvzRvOE8uSirYbgmj6He4iO8NCyvaK0jIQRMMGQwsU1quGmFgHIXPLfnpn 759 fajr1rVTAwtgV5LEZ4Iel+W1GC8ugMhyr4/p1MtcIM42EA8BzE6ZQqC7VPq 760 PvEjZ2dbZkaBhPbiZAS3YeYBRDWm1p1OZtWamT3cEvqqPpnjL1XyW+oyVVk 761 aZdklLQp2Btgt9qr21m42f4wTw+Xrp6rCKNb0CAwEAATANBgkqhkiG9w0BA 762 QUFAAOCAQEAh8zGlfSlcI0o3rYDPBB07aXNswb4ECNIKG0CETTUxmXl9KUL 763 +9gGlqCz5iWLOgWsnrcKcY0vXPG9J1r9AqBNTqNgHq2G03X09266X5CpOe1 764 zFo+Owb1zxtp3PehFdfQJ610CDLEaS9V9Rqp17hCyybEpOGVwe8fnk+fbEL 765 2Bo3UPGrpsHzUoaGpDftmWssZkhpBJKVMJyf/RuP2SmmaIzmnw9JiSlYhzo 766 4tpzd5rFXhjRbg4zW9C+2qok+2+qDM1iJ684gPHMIY8aLWrdgQTxkumGmTq 767 gawR+N5MDtdPTEQ0XfIBc2cJEUyMTY5MPvACWpkA6SdS4xSvdXK3IVfOWA=="] 768 } 770 Appendix C. Acknowledgements 772 A JSON representation for RSA public keys was previously introduced 773 by John Panzer, Ben Laurie, and Dirk Balfanz in Magic Signatures 774 [MagicSignatures]. 776 This specification is the work of the JOSE Working Group, which 777 includes dozens of active and dedicated participants. In particular, 778 the following individuals contributed ideas, feedback, and wording 779 that influenced this specification: 781 Dirk Balfanz, Richard Barnes, John Bradley, Brian Campbell, Breno de 782 Medeiros, Joe Hildebrand, Edmund Jay, Ben Laurie, James Manger, Matt 783 Miller, Tony Nadalin, Axel Nennker, John Panzer, Eric Rescorla, Nat 784 Sakimura, Jim Schaad, Paul Tarjan, Hannes Tschofenig, and Sean 785 Turner. 787 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 788 Sean Turner and Stephen Farrell served as Security area directors 789 during the creation of this specification. 791 Appendix D. Document History 793 [[ to be removed by the RFC editor before publication as an RFC ]] 795 -15 797 o Changes to address editorial issues #48, #64, #65, #66, and #91. 799 -14 801 o Relaxed language introducing key parameters since some parameters 802 are applicable to multiple, but not all, key types. 804 -13 806 o Applied spelling and grammar corrections. 808 -12 810 o Stated that recipients MUST either reject JWKs and JWK Sets with 811 duplicate member names or use a JSON parser that returns only the 812 lexically last duplicate member name. 814 -11 816 o Stated that when "kid" values are used within a JWK Set, different 817 keys within the JWK Set SHOULD use distinct "kid" values. 819 o Added optional "x5u" (X.509 URL), "x5t" (X.509 Certificate 820 Thumbprint), and "x5c" (X.509 Certificate Chain) JWK parameters. 822 o Added section on Encrypted JWK and Encrypted JWK Set Formats. 824 o Added a Parameter Information Class value to the JSON Web Key 825 Parameters registry, which registers whether the parameter conveys 826 public or private information. 828 o Registered "application/jwk+json" and "application/jwk-set+json" 829 MIME types and "JWK" and "JWK-SET" typ header parameter values, 830 addressing issue #21. 832 -10 834 o No changes were made, other than to the version number and date. 836 -09 838 o Expanded the scope of the JWK specification to include private and 839 symmetric key representations, as specified by 840 draft-jones-jose-json-private-and-symmetric-key-00. 842 o Defined that members that are not understood must be ignored. 844 -08 846 o Changed the name of the JWK key type parameter from "alg" to "kty" 847 to enable use of "alg" to indicate the particular algorithm that 848 the key is intended to be used with. 850 o Clarified statements of the form "This member is OPTIONAL" to "Use 851 of this member is OPTIONAL". 853 o Referenced String Comparison Rules in JWS. 855 o Added seriesInfo information to Internet Draft references. 857 -07 859 o Changed the name of the JWK RSA modulus parameter from "mod" to 860 "n" and the name of the JWK RSA exponent parameter from "xpo" to 861 "e", so that the identifiers are the same as those used in RFC 862 3447. 864 -06 866 o Changed the name of the JWK RSA exponent parameter from "exp" to 867 "xpo" so as to allow the potential use of the name "exp" for a 868 future extension that might define an expiration parameter for 869 keys. (The "exp" name is already used for this purpose in the JWT 870 specification.) 872 o Clarify that the "alg" (algorithm family) member is REQUIRED. 874 o Correct an instance of "JWK" that should have been "JWK Set". 876 o Applied changes made by the RFC Editor to RFC 6749's registry 877 language to this specification. 879 -05 881 o Indented artwork elements to better distinguish them from the body 882 text. 884 -04 886 o Refer to the registries as the primary sources of defined values 887 and then secondarily reference the sections defining the initial 888 contents of the registries. 890 o Normatively reference XML DSIG 2.0 [W3C.CR-xmldsig-core2-20120124] 891 for its security considerations. 893 o Added this language to Registration Templates: "This name is case 894 sensitive. Names that match other registered names in a case 895 insensitive manner SHOULD NOT be accepted." 897 o Described additional open issues. 899 o Applied editorial suggestions. 901 -03 903 o Clarified that "kid" values need not be unique within a JWK Set. 905 o Moved JSON Web Key Parameters registry to the JWK specification. 907 o Added "Collision Resistant Namespace" to the terminology section. 909 o Changed registration requirements from RFC Required to 910 Specification Required with Expert Review. 912 o Added Registration Template sections for defined registries. 914 o Added Registry Contents sections to populate registry values. 916 o Numerous editorial improvements. 918 -02 920 o Simplified JWK terminology to get replace the "JWK Key Object" and 921 "JWK Container Object" terms with simply "JSON Web Key (JWK)" and 922 "JSON Web Key Set (JWK Set)" and to eliminate potential confusion 923 between single keys and sets of keys. As part of this change, the 924 top-level member name for a set of keys was changed from "jwk" to 925 "keys". 927 o Clarified that values with duplicate member names MUST be 928 rejected. 930 o Established JSON Web Key Set Parameters registry. 932 o Explicitly listed non-goals in the introduction. 934 o Moved algorithm-specific definitions from JWK to JWA. 936 o Reformatted to give each member definition its own section 937 heading. 939 -01 941 o Corrected the Magic Signatures reference. 943 -00 945 o Created the initial IETF draft based upon 946 draft-jones-json-web-key-03 with no normative changes. 948 Author's Address 950 Michael B. Jones 951 Microsoft 953 Email: mbj@microsoft.com 954 URI: http://self-issued.info/