idnits 2.17.00 (12 Aug 2021) /tmp/idnits42032/draft-ietf-jose-json-web-key-11.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 (May 28, 2013) is 3279 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. '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 (==), 3 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 May 28, 2013 5 Expires: November 29, 2013 7 JSON Web Key (JWK) 8 draft-ietf-jose-json-web-key-11 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. 19 Status of this Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at http://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on November 29, 2013. 36 Copyright Notice 38 Copyright (c) 2013 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 55 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 3. JSON Web Key (JWK) Format . . . . . . . . . . . . . . . . . . 4 57 3.1. "kty" (Key Type) Parameter . . . . . . . . . . . . . . . . 4 58 3.2. "use" (Key Use) Parameter . . . . . . . . . . . . . . . . 5 59 3.3. "alg" (Algorithm) Parameter . . . . . . . . . . . . . . . 5 60 3.4. "kid" (Key ID) Parameter . . . . . . . . . . . . . . . . . 5 61 3.5. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . . . 5 62 3.6. "x5t" (X.509 Certificate Thumbprint) Header Parameter . . 6 63 3.7. "x5c" (X.509 Certificate Chain) Parameter . . . . . . . . 6 64 4. JSON Web Key Set (JWK Set) Format . . . . . . . . . . . . . . 6 65 4.1. "keys" (JSON Web Key Set) Parameter . . . . . . . . . . . 6 66 5. String Comparison Rules . . . . . . . . . . . . . . . . . . . 6 67 6. Encrypted JWK and Encrypted JWK Set Formats . . . . . . . . . 7 68 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 69 7.1. JSON Web Key Parameters Registry . . . . . . . . . . . . . 8 70 7.1.1. Registration Template . . . . . . . . . . . . . . . . 8 71 7.1.2. Initial Registry Contents . . . . . . . . . . . . . . 8 72 7.2. JSON Web Key Set Parameters Registry . . . . . . . . . . . 9 73 7.2.1. Registration Template . . . . . . . . . . . . . . . . 9 74 7.2.2. Initial Registry Contents . . . . . . . . . . . . . . 10 75 7.3. JSON Web Signature and Encryption Type Values 76 Registration . . . . . . . . . . . . . . . . . . . . . . . 10 77 7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 10 78 7.4. Media Type Registration . . . . . . . . . . . . . . . . . 10 79 7.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 10 80 8. Security Considerations . . . . . . . . . . . . . . . . . . . 11 81 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12 82 9.1. Normative References . . . . . . . . . . . . . . . . . . . 12 83 9.2. Informative References . . . . . . . . . . . . . . . . . . 13 84 Appendix A. Example JSON Web Key Sets . . . . . . . . . . . . . . 14 85 A.1. Example Public Keys . . . . . . . . . . . . . . . . . . . 14 86 A.2. Example Private Keys . . . . . . . . . . . . . . . . . . . 15 87 A.3. Example Symmetric Keys . . . . . . . . . . . . . . . . . . 17 88 Appendix B. Example Use of "x5c" (X.509 Certificate Chain) 89 Parameter . . . . . . . . . . . . . . . . . . . . . . 17 90 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 18 91 Appendix D. Document History . . . . . . . . . . . . . . . . . . 19 92 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 22 94 1. Introduction 96 A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) [RFC4627] 97 data structure that represents a cryptographic key. This 98 specification also defines a JSON Web Key Set (JWK Set) JSON data 99 structure for representing a set of JWKs. Cryptographic algorithms 100 and identifiers for use with this specification are described in the 101 separate JSON Web Algorithms (JWA) [JWA] specification. 103 Goals for this specification do not include representing certificate 104 chains, representing certified keys, and replacing X.509 105 certificates. 107 JWKs and JWK Sets are used in the JSON Web Signature (JWS) [JWS] and 108 JSON Web Encryption (JWE) [JWE] specifications. 110 1.1. Notational Conventions 112 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 113 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 114 document are to be interpreted as described in Key words for use in 115 RFCs to Indicate Requirement Levels [RFC2119]. 117 2. Terminology 119 JSON Web Key (JWK) A JSON object that represents a cryptographic 120 key. 122 JSON Web Key Set (JWK Set) A JSON object that contains an array of 123 JWKs as the value of its "keys" member. 125 Base64url Encoding The URL- and filename-safe Base64 encoding 126 described in RFC 4648 [RFC4648], Section 5, with the (non URL- 127 safe) '=' padding characters omitted, as permitted by Section 3.2. 128 (See Appendix C of [JWS] for notes on implementing base64url 129 encoding without padding.) 131 Collision Resistant Namespace A namespace that allows names to be 132 allocated in a manner such that they are highly unlikely to 133 collide with other names. For instance, collision resistance can 134 be achieved through administrative delegation of portions of the 135 namespace or through use of collision-resistant name allocation 136 functions. Examples of Collision Resistant Namespaces include: 137 Domain Names, Object Identifiers (OIDs) as defined in the ITU-T 138 X.660 and X.670 Recommendation series, and Universally Unique 139 IDentifiers (UUIDs) [RFC4122]. When using an administratively 140 delegated namespace, the definer of a name needs to take 141 reasonable precautions to ensure they are in control of the 142 portion of the namespace they use to define the name. 144 Encrypted JWK A JWE with a JWK as its plaintext value. 146 Encrypted JWK Set A JWE with a JWK Set as its plaintext value. 148 3. JSON Web Key (JWK) Format 150 A JSON Web Key (JWK) is a JSON object containing specific members, as 151 specified below. Those members that are common to all key types are 152 defined below. 154 In addition to the common parameters, each JWK will have members that 155 are specific to the kind of key being represented. These members 156 represent the parameters of the key. Section 5 of the JSON Web 157 Algorithms (JWA) [JWA] specification defines multiple kinds of 158 cryptographic keys and their associated members. 160 The member names within a JWK MUST be unique; objects with duplicate 161 member names MUST be rejected. 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) Header 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) Header 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 x5c The "x5c" (X.509 Certificate Chain) member contains a chain of 246 one or 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 -- 249 not base64url encoded) DER [ITU.X690.1994] PKIX certificate value. 250 The PKIX certificate containing the key value MUST be the first 251 certificate. This MAY be followed by additional certificates, 252 with each subsequent certificate being the one used to certify the 253 previous one. The key in the first certificate MUST match the 254 bare public key represented by other members of the JWK. Use of 255 this 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; objects with 263 duplicate member names MUST be rejected. 265 Additional members MAY be present in the JWK Set. If not understood 266 by implementations encountering them, they MUST be ignored. 267 Parameters for representing additional properties of JWK Sets SHOULD 268 either be registered in the IANA JSON Web Key Set Parameters registry 269 Section 7.2 or be a value that contains a Collision Resistant 270 Namespace. 272 4.1. "keys" (JSON Web Key Set) Parameter 274 The value of the "keys" (JSON Web Key Set) member is an array of JSON 275 Web Key (JWK) values. Use of this member is REQUIRED. 277 5. String Comparison Rules 279 Processing a JWK inevitably requires comparing known strings to 280 values in JSON objects. For example, in checking what the key type 281 is, the Unicode string encoding "kty" will be checked against the 282 member names in the JWK to see if there is a matching name. 284 Comparisons between JSON strings and other Unicode strings MUST be 285 performed by comparing Unicode code points without normalization as 286 specified in the String Comparison Rules in Section 5.3 of [JWS]. 288 6. Encrypted JWK and Encrypted JWK Set Formats 290 JWKs containing non-public key material will need to be encrypted in 291 some contexts to prevent the disclosure of private or symmetric key 292 values to unintended parties. The use of an Encrypted JWK, which is 293 a JWE with a JWK as its plaintext value, is RECOMMENED for this 294 purpose. The processing of Encrypted JWKs is identical to the 295 processing of other JWEs. A "cty" (content type) header parameter 296 value of "JWK" can be used to indicate that the content of the JWE is 297 a JWK in contexts where this is useful. 299 JWK Sets containing non-public key material will similarly need to be 300 encrypted. The use of an Encrypted JWK Set, which is a JWE with a 301 JWK Set as its plaintext value, is RECOMMENED for this purpose. The 302 processing of Encrypted JWK Sets is identical to the processing of 303 other JWEs. A "cty" (content type) header parameter value of 304 "JWK-SET" can be used to indicate that the content of the JWE is a 305 JWK Set in contexts where this is useful. 307 7. IANA Considerations 309 The following registration procedure is used for all the registries 310 established by this specification. 312 Values are registered with a Specification Required [RFC5226] after a 313 two-week review period on the [TBD]@ietf.org mailing list, on the 314 advice of one or more Designated Experts. However, to allow for the 315 allocation of values prior to publication, the Designated Expert(s) 316 may approve registration once they are satisfied that such a 317 specification will be published. 319 Registration requests must be sent to the [TBD]@ietf.org mailing list 320 for review and comment, with an appropriate subject (e.g., "Request 321 for access token type: example"). [[ Note to RFC-EDITOR: The name of 322 the mailing list should be determined in consultation with the IESG 323 and IANA. Suggested name: jose-reg-review. ]] 325 Within the review period, the Designated Expert(s) will either 326 approve or deny the registration request, communicating this decision 327 to the review list and IANA. Denials should include an explanation 328 and, if applicable, suggestions as to how to make the request 329 successful. 331 IANA must only accept registry updates from the Designated Expert(s) 332 and should direct all requests for registration to the review mailing 333 list. 335 7.1. JSON Web Key Parameters Registry 337 This specification establishes the IANA JSON Web Key Parameters 338 registry for reserved JWK parameter names. The registry records the 339 reserved parameter name and a reference to the specification that 340 defines it. It also records whether the parameter conveys public or 341 private information. This specification registers the parameter 342 names defined in Section 3. The same JWK parameter name may be 343 registered multiple times, provided that duplicate parameter 344 registrations are only for algorithm-specific JWK parameters; in this 345 case, the meaning of the duplicate parameter name is disambiguated by 346 the "kty" value of the JWK containing it. 348 7.1.1. Registration Template 350 Parameter Name: 351 The name requested (e.g., "example"). This name is case 352 sensitive. Names that match other registered names in a case 353 insensitive manner SHOULD NOT be accepted. 355 Parameter Information Class: 356 Registers whether the parameter conveys public or private 357 information. Its value must be one the words Public or Private. 359 Change Controller: 360 For Standards Track RFCs, state "IETF". For others, give the name 361 of the responsible party. Other details (e.g., postal address, 362 email address, home page URI) may also be included. 364 Specification Document(s): 365 Reference to the document(s) that specify the parameter, 366 preferably including URI(s) that can be used to retrieve copies of 367 the document(s). An indication of the relevant sections may also 368 be included but is not required. 370 7.1.2. Initial Registry Contents 372 o Parameter Name: "kty" 373 o Parameter Information Class: Public 374 o Change Controller: IETF 375 o Specification Document(s): Section 3.1 of [[ this document ]] 377 o Parameter Name: "use" 378 o Parameter Information Class: Public 379 o Change Controller: IETF 380 o Specification Document(s): Section 3.2 of [[ this document ]] 382 o Parameter Name: "alg" 383 o Parameter Information Class: Public 384 o Change Controller: IETF 385 o Specification Document(s): Section 3.3 of [[ this document ]] 387 o Parameter Name: "kid" 388 o Parameter Information Class: Public 389 o Change Controller: IETF 390 o Specification Document(s): Section 3.4 of [[ this document ]] 392 o Parameter Name: "x5u" 393 o Parameter Information Class: Public 394 o Change Controller: IETF 395 o Specification Document(s): Section 3.5 of [[ this document ]] 397 o Parameter Name: "x5t" 398 o Parameter Information Class: Public 399 o Change Controller: IETF 400 o Specification Document(s): Section 3.6 of [[ this document ]] 402 o Parameter Name: "x5c" 403 o Parameter Information Class: Public 404 o Change Controller: IETF 405 o Specification Document(s): Section 3.7 of [[ this document ]] 407 7.2. JSON Web Key Set Parameters Registry 409 This specification establishes the IANA JSON Web Key Set Parameters 410 registry for reserved JWK Set parameter names. The registry records 411 the reserved parameter name and a reference to the specification that 412 defines it. This specification registers the parameter names defined 413 in Section 4. 415 7.2.1. Registration Template 416 Parameter Name: 417 The name requested (e.g., "example"). This name is case 418 sensitive. Names that match other registered names in a case 419 insensitive manner SHOULD NOT be accepted. 421 Change Controller: 422 For Standards Track RFCs, state "IETF". For others, give the name 423 of the responsible party. Other details (e.g., postal address, 424 email address, home page URI) may also be included. 426 Specification Document(s): 427 Reference to the document(s) that specify the parameter, 428 preferably including URI(s) that can be used to retrieve copies of 429 the document(s). An indication of the relevant sections may also 430 be included but is not required. 432 7.2.2. Initial Registry Contents 434 o Parameter Name: "keys" 435 o Change Controller: IETF 436 o Specification Document(s): Section 4.1 of [[ this document ]] 438 7.3. JSON Web Signature and Encryption Type Values Registration 440 7.3.1. Registry Contents 442 This specification registers the "JWK" and "JWK-SET" type values in 443 the IANA JSON Web Signature and Encryption Type Values registry 444 [JWS]: 446 o "typ" Header Parameter Value: "JWK" 447 o Abbreviation for MIME Type: application/jwk+json 448 o Change Controller: IETF 449 o Specification Document(s): Section 3 of [[ this document ]] 451 o "typ" Header Parameter Value: "JWK-SET" 452 o Abbreviation for MIME Type: application/jwk-set+json 453 o Change Controller: IETF 454 o Specification Document(s): Section 4 of [[ this document ]] 456 7.4. Media Type Registration 458 7.4.1. Registry Contents 460 This specification registers the "application/jwk+json" and 461 "application/jwk-set+json" Media Types [RFC2046] in the MIME Media 462 Type registry [RFC4288] to indicate, respectively, that the content 463 is a JWK or a JWK Set. 465 o Type Name: application 466 o Subtype Name: jwk+json 467 o Required Parameters: n/a 468 o Optional Parameters: n/a 469 o Encoding considerations: application/jwk+json values are 470 represented as JSON object; UTF-8 encoding SHOULD be employed for 471 the JSON object. 472 o Security Considerations: See the Security Considerations section 473 of [[ this document ]] 474 o Interoperability Considerations: n/a 475 o Published Specification: [[ this document ]] 476 o Applications that use this media type: TBD 477 o Additional Information: Magic number(s): n/a, File extension(s): 478 n/a, Macintosh file type code(s): n/a 479 o Person & email address to contact for further information: Michael 480 B. Jones, mbj@microsoft.com 481 o Intended Usage: COMMON 482 o Restrictions on Usage: none 483 o Author: Michael B. Jones, mbj@microsoft.com 484 o Change Controller: IETF 486 o Type Name: application 487 o Subtype Name: jwk-set+json 488 o Required Parameters: n/a 489 o Optional Parameters: n/a 490 o Encoding considerations: application/jwk-set+json values are 491 represented as a JSON Object; UTF-8 encoding SHOULD be employed 492 for the JSON object. 493 o Security Considerations: See the Security Considerations section 494 of [[ this document ]] 495 o Interoperability Considerations: n/a 496 o Published Specification: [[ this document ]] 497 o Applications that use this media type: TBD 498 o Additional Information: Magic number(s): n/a, File extension(s): 499 n/a, Macintosh file type code(s): n/a 500 o Person & email address to contact for further information: Michael 501 B. Jones, mbj@microsoft.com 502 o Intended Usage: COMMON 503 o Restrictions on Usage: none 504 o Author: Michael B. Jones, mbj@microsoft.com 505 o Change Controller: IETF 507 8. Security Considerations 509 All of the security issues faced by any cryptographic application 510 must be faced by a JWS/JWE/JWK agent. Among these issues are 511 protecting the user's private and symmetric keys, preventing various 512 attacks, and helping the user avoid mistakes such as inadvertently 513 encrypting a message for the wrong recipient. The entire list of 514 security considerations is beyond the scope of this document, but 515 some significant considerations are listed here. 517 A key is no more trustworthy than the method by which it was 518 received. 520 Private and symmetric keys must be protected from disclosure to 521 unintended parties. One recommended means of doing so is to encrypt 522 JWKs or JWK Sets containing them by using the JWK or JWK Set value as 523 the plaintext of a JWE. 525 The security considerations in RFC 3447 [RFC3447] and RFC 6030 526 [RFC6030] about protecting private and symmetric keys also apply to 527 this specification. 529 The security considerations in XML DSIG 2.0 530 [W3C.CR-xmldsig-core2-20120124], about key representations also apply 531 to this specification, other than those that are XML specific. 533 9. References 535 9.1. Normative References 537 [ITU.X690.1994] 538 International Telecommunications Union, "Information 539 Technology - ASN.1 encoding rules: Specification of Basic 540 Encoding Rules (BER), Canonical Encoding Rules (CER) and 541 Distinguished Encoding Rules (DER)", ITU-T Recommendation 542 X.690, 1994. 544 [JWA] Jones, M., "JSON Web Algorithms (JWA)", 545 draft-ietf-jose-json-web-algorithms (work in progress), 546 May 2013. 548 [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web 549 Encryption (JWE)", draft-ietf-jose-json-web-encryption 550 (work in progress), May 2013. 552 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 553 Signature (JWS)", draft-ietf-jose-json-web-signature (work 554 in progress), May 2013. 556 [RFC1421] Linn, J., "Privacy Enhancement for Internet Electronic 557 Mail: Part I: Message Encryption and Authentication 558 Procedures", RFC 1421, February 1993. 560 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 561 Extensions (MIME) Part Two: Media Types", RFC 2046, 562 November 1996. 564 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 565 Requirement Levels", BCP 14, RFC 2119, March 1997. 567 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 569 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 570 Resource Identifier (URI): Generic Syntax", STD 66, 571 RFC 3986, January 2005. 573 [RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and 574 Registration Procedures", RFC 4288, December 2005. 576 [RFC4627] Crockford, D., "The application/json Media Type for 577 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 579 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 580 Encodings", RFC 4648, October 2006. 582 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 583 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 584 May 2008. 586 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 587 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 589 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 590 Housley, R., and W. Polk, "Internet X.509 Public Key 591 Infrastructure Certificate and Certificate Revocation List 592 (CRL) Profile", RFC 5280, May 2008. 594 [W3C.CR-xmldsig-core2-20120124] 595 Eastlake, D., Reagle, J., Yiu, K., Solo, D., Datta, P., 596 Hirsch, F., Cantor, S., and T. Roessler, "XML Signature 597 Syntax and Processing Version 2.0", World Wide Web 598 Consortium CR CR-xmldsig-core2-20120124, January 2012, 599 . 601 9.2. Informative References 603 [MagicSignatures] 604 Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic 605 Signatures", January 2011. 607 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 608 Standards (PKCS) #1: RSA Cryptography Specifications 609 Version 2.1", RFC 3447, February 2003. 611 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 612 Unique IDentifier (UUID) URN Namespace", RFC 4122, 613 July 2005. 615 [RFC6030] Hoyer, P., Pei, M., and S. Machani, "Portable Symmetric 616 Key Container (PSKC)", RFC 6030, October 2010. 618 Appendix A. Example JSON Web Key Sets 620 A.1. Example Public Keys 622 The following example JWK Set contains two public keys represented as 623 JWKs: one using an Elliptic Curve algorithm and a second one using an 624 RSA algorithm. The first specifies that the key is to be used for 625 encryption. The second specifies that the key is to be used with the 626 "RS256" algorithm. Both provide a Key ID for key matching purposes. 627 In both cases, integers are represented using the base64url encoding 628 of their big endian representations. (Long lines are broken are for 629 display purposes only.) 631 {"keys": 632 [ 633 {"kty":"EC", 634 "crv":"P-256", 635 "x":"MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4", 636 "y":"4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM", 637 "use":"enc", 638 "kid":"1"}, 640 {"kty":"RSA", 641 "n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx 642 4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMs 643 tn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2 644 QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbI 645 SD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqb 646 w0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw", 647 "e":"AQAB", 648 "alg":"RS256", 649 "kid":"2011-04-29"} 650 ] 651 } 653 A.2. Example Private Keys 655 The following example JWK Set contains two keys represented as JWKs 656 containing both public and private key values: one using an Elliptic 657 Curve algorithm and a second one using an RSA algorithm. This 658 example extends the example in the previous section, adding private 659 key values. (Line breaks are for display purposes only.) 660 {"keys": 661 [ 662 {"kty":"EC", 663 "crv":"P-256", 664 "x":"MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4", 665 "y":"4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM", 666 "d":"870MB6gfuTJ4HtUnUvYMyJpr5eUZNP4Bk43bVdj3eAE", 667 "use":"enc", 668 "kid":"1"}, 670 {"kty":"RSA", 671 "n":"0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx4 672 cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMst 673 n64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2Q 674 vzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbIS 675 D08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqbw 676 0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw", 677 "e":"AQAB", 678 "d":"X4cTteJY_gn4FYPsXB8rdXix5vwsg1FLN5E3EaG6RJoVH-HLLKD9 679 M7dx5oo7GURknchnrRweUkC7hT5fJLM0WbFAKNLWY2vv7B6NqXSzUvxT0_YSfqij 680 wp3RTzlBaCxWp4doFk5N2o8Gy_nHNKroADIkJ46pRUohsXywbReAdYaMwFs9tv8d 681 _cPVY3i07a3t8MN6TNwm0dSawm9v47UiCl3Sk5ZiG7xojPLu4sbg1U2jx4IBTNBz 682 nbJSzFHK66jT8bgkuqsk0GjskDJk19Z4qwjwbsnn4j2WBii3RL-Us2lGVkY8fkFz 683 me1z0HbIkfz0Y6mqnOYtqc0X4jfcKoAC8Q", 684 "p":"83i-7IvMGXoMXCskv73TKr8637FiO7Z27zv8oj6pbWUQyLPQBQxtPV 685 nwD20R-60eTDmD2ujnMt5PoqMrm8RfmNhVWDtjjMmCMjOpSXicFHj7XOuVIYQyqV 686 WlWEh6dN36GVZYk93N8Bc9vY41xy8B9RzzOGVQzXvNEvn7O0nVbfs", 687 "q":"3dfOR9cuYq-0S-mkFLzgItgMEfFzB2q3hWehMuG0oCuqnb3vobLyum 688 qjVZQO1dIrdwgTnCdpYzBcOfW5r370AFXjiWft_NGEiovonizhKpo9VVS78TzFgx 689 kIdrecRezsZ-1kYd_s1qDbxtkDEgfAITAG9LUnADun4vIcb6yelxk", 690 "dp":"G4sPXkc6Ya9y8oJW9_ILj4xuppu0lzi_H7VTkS8xj5SdX3coE0oim 691 YwxIi2emTAue0UOa5dpgFGyBJ4c8tQ2VF402XRugKDTP8akYhFo5tAA77Qe_Nmtu 692 YZc3C3m3I24G2GvR5sSDxUyAN2zq8Lfn9EUms6rY3Ob8YeiKkTiBj0", 693 "dq":"s9lAH9fggBsoFR8Oac2R_E2gw282rT2kGOAhvIllETE1efrA6huUU 694 vMfBcMpn8lqeW6vzznYY5SSQF7pMdC_agI3nG8Ibp1BUb0JUiraRNqUfLhcQb_d9 695 GF4Dh7e74WbRsobRonujTYN1xCaP6TO61jvWrX-L18txXw494Q_cgk", 696 "qi":"GyM_p6JrXySiz1toFgKbWV-JdI3jQ4ypu9rbMWx3rQJBfmt0FoYzg 697 UIZEVFEcOqwemRN81zoDAaa-Bk0KWNGDjJHZDdDmFhW3AN7lI-puxk_mHZGJ11rx 698 yR8O55XLSe3SPmRfKwZI6yU24ZxvQKFYItdldUKGzO6Ia6zTKhAVRU", 699 "alg":"RS256", 700 "kid":"2011-04-29"} 701 ] 702 } 704 A.3. Example Symmetric Keys 706 The following example JWK Set contains two symmetric keys represented 707 as JWKs: one designated as being for use with the AES Key Wrap 708 algorithm and a second one that is an HMAC key. (Line breaks are for 709 display purposes only.) 711 {"keys": 712 [ 713 {"kty":"oct", 714 "alg":"A128KW", 715 "k":"GawgguFyGrWKav7AX4VKUg"}, 717 {"kty":"oct", 718 "k":"AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75 719 aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow", 720 "kid":"HMAC key used in JWS A.1 example"} 721 ] 722 } 724 Appendix B. Example Use of "x5c" (X.509 Certificate Chain) Parameter 725 The following is a non-normative example of a JWK with a RSA signing 726 key represented both as a bare public key and as an X.509 certificate 727 using the "x5c" parameter: 729 {"kty":"RSA", 730 "use":"sig", 731 "kid":"1b94c", 732 "n":"vrjOfz9Ccdgx5nQudyhdoR17V-IubWMeOZCwX_jj0hgAsz2J_pqYW08 733 PLbK_PdiVGKPrqzmDIsLI7sA25VEnHU1uCLNwBuUiCO11_-7dYbsr4iJmG0Q 734 u2j8DsVyT1azpJC_NG84Ty5KKthuCaPod7iI7w0LK9orSMhBEwwZDCxTWq4a 735 YWAchc8t-emd9qOvWtVMDC2BXksRngh6X5bUYLy6AyHKvj-nUy1wgzjYQDwH 736 MTplCoLtU-o-8SNnZ1tmRoGE9uJkBLdh5gFENabWnU5m1ZqZPdwS-qo-meMv 737 VfJb6jJVWRpl2SUtCnYG2C32qvbWbjZ_jBPD5eunqsIo1vQ", 738 "e":"AQAB", 739 "x5c": 740 ["MIIDQjCCAiqgAwIBAgIGATz/FuLiMA0GCSqGSIb3DQEBBQUAMGIxCzAJB 741 gNVBAYTAlVTMQswCQYDVQQIEwJDTzEPMA0GA1UEBxMGRGVudmVyMRwwGgYD 742 VQQKExNQaW5nIElkZW50aXR5IENvcnAuMRcwFQYDVQQDEw5CcmlhbiBDYW1 743 wYmVsbDAeFw0xMzAyMjEyMzI5MTVaFw0xODA4MTQyMjI5MTVaMGIxCzAJBg 744 NVBAYTAlVTMQswCQYDVQQIEwJDTzEPMA0GA1UEBxMGRGVudmVyMRwwGgYDV 745 QQKExNQaW5nIElkZW50aXR5IENvcnAuMRcwFQYDVQQDEw5CcmlhbiBDYW1w 746 YmVsbDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAL64zn8/QnH 747 YMeZ0LncoXaEde1fiLm1jHjmQsF/449IYALM9if6amFtPDy2yvz3YlRij66 748 s5gyLCyO7ANuVRJx1NbgizcAblIgjtdf/u3WG7K+IiZhtELto/A7Fck9Ws6 749 SQvzRvOE8uSirYbgmj6He4iO8NCyvaK0jIQRMMGQwsU1quGmFgHIXPLfnpn 750 fajr1rVTAwtgV5LEZ4Iel+W1GC8ugMhyr4/p1MtcIM42EA8BzE6ZQqC7VPq 751 PvEjZ2dbZkaBhPbiZAS3YeYBRDWm1p1OZtWamT3cEvqqPpnjL1XyW+oyVVk 752 aZdklLQp2Btgt9qr21m42f4wTw+Xrp6rCKNb0CAwEAATANBgkqhkiG9w0BA 753 QUFAAOCAQEAh8zGlfSlcI0o3rYDPBB07aXNswb4ECNIKG0CETTUxmXl9KUL 754 +9gGlqCz5iWLOgWsnrcKcY0vXPG9J1r9AqBNTqNgHq2G03X09266X5CpOe1 755 zFo+Owb1zxtp3PehFdfQJ610CDLEaS9V9Rqp17hCyybEpOGVwe8fnk+fbEL 756 2Bo3UPGrpsHzUoaGpDftmWssZkhpBJKVMJyf/RuP2SmmaIzmnw9JiSlYhzo 757 4tpzd5rFXhjRbg4zW9C+2qok+2+qDM1iJ684gPHMIY8aLWrdgQTxkumGmTq 758 gawR+N5MDtdPTEQ0XfIBc2cJEUyMTY5MPvACWpkA6SdS4xSvdXK3IVfOWA=="] 759 } 761 Appendix C. Acknowledgements 763 A JSON representation for RSA public keys was previously introduced 764 by John Panzer, Ben Laurie, and Dirk Balfanz in Magic Signatures 765 [MagicSignatures]. 767 This specification is the work of the JOSE Working Group, which 768 includes dozens of active and dedicated participants. In particular, 769 the following individuals contributed ideas, feedback, and wording 770 that influenced this specification: 772 Dirk Balfanz, Richard Barnes, John Bradley, Brian Campbell, Breno de 773 Medeiros, Joe Hildebrand, Edmund Jay, Ben Laurie, James Manger, Matt 774 Miller, Tony Nadalin, Axel Nennker, John Panzer, Eric Rescorla, Nat 775 Sakimura, Jim Schaad, Paul Tarjan, Hannes Tschofenig, and Sean 776 Turner. 778 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 779 Sean Turner and Stephen Farrell served as Security area directors 780 during the creation of this specification. 782 Appendix D. Document History 784 [[ to be removed by the RFC editor before publication as an RFC ]] 786 -11 788 o Stated that when "kid" values are used within a JWK Set, different 789 keys within the JWK Set SHOULD use distinct "kid" values. 791 o Added optional "x5u" (X.509 URL), "x5t" (X.509 Certificate 792 Thumbprint), and "x5c" (X.509 Certificate Chain) JWK parameters. 794 o Added section on Encrypted JWK and Encrypted JWK Set Formats. 796 o Added a Parameter Information Class value to the JSON Web Key 797 Parameters registry, which registers whether the parameter conveys 798 public or private information. 800 o Registered "application/jwk+json" and "application/jwk-set+json" 801 MIME types and "JWK" and "JWK-SET" typ header parameter values, 802 addressing issue #21. 804 -10 806 o No changes were made, other than to the version number and date. 808 -09 810 o Expanded the scope of the JWK specification to include private and 811 symmetric key representations, as specified by 812 draft-jones-jose-json-private-and-symmetric-key-00. 814 o Defined that members that are not understood must be ignored. 816 -08 817 o Changed the name of the JWK key type parameter from "alg" to "kty" 818 to enable use of "alg" to indicate the particular algorithm that 819 the key is intended to be used with. 821 o Clarified statements of the form "This member is OPTIONAL" to "Use 822 of this member is OPTIONAL". 824 o Referenced String Comparison Rules in JWS. 826 o Added seriesInfo information to Internet Draft references. 828 -07 830 o Changed the name of the JWK RSA modulus parameter from "mod" to 831 "n" and the name of the JWK RSA exponent parameter from "xpo" to 832 "e", so that the identifiers are the same as those used in RFC 833 3447. 835 -06 837 o Changed the name of the JWK RSA exponent parameter from "exp" to 838 "xpo" so as to allow the potential use of the name "exp" for a 839 future extension that might define an expiration parameter for 840 keys. (The "exp" name is already used for this purpose in the JWT 841 specification.) 843 o Clarify that the "alg" (algorithm family) member is REQUIRED. 845 o Correct an instance of "JWK" that should have been "JWK Set". 847 o Applied changes made by the RFC Editor to RFC 6749's registry 848 language to this specification. 850 -05 852 o Indented artwork elements to better distinguish them from the body 853 text. 855 -04 857 o Refer to the registries as the primary sources of defined values 858 and then secondarily reference the sections defining the initial 859 contents of the registries. 861 o Normatively reference XML DSIG 2.0 [W3C.CR-xmldsig-core2-20120124] 862 for its security considerations. 864 o Added this language to Registration Templates: "This name is case 865 sensitive. Names that match other registered names in a case 866 insensitive manner SHOULD NOT be accepted." 868 o Described additional open issues. 870 o Applied editorial suggestions. 872 -03 874 o Clarified that "kid" values need not be unique within a JWK Set. 876 o Moved JSON Web Key Parameters registry to the JWK specification. 878 o Added "Collision Resistant Namespace" to the terminology section. 880 o Changed registration requirements from RFC Required to 881 Specification Required with Expert Review. 883 o Added Registration Template sections for defined registries. 885 o Added Registry Contents sections to populate registry values. 887 o Numerous editorial improvements. 889 -02 891 o Simplified JWK terminology to get replace the "JWK Key Object" and 892 "JWK Container Object" terms with simply "JSON Web Key (JWK)" and 893 "JSON Web Key Set (JWK Set)" and to eliminate potential confusion 894 between single keys and sets of keys. As part of this change, the 895 top-level member name for a set of keys was changed from "jwk" to 896 "keys". 898 o Clarified that values with duplicate member names MUST be 899 rejected. 901 o Established JSON Web Key Set Parameters registry. 903 o Explicitly listed non-goals in the introduction. 905 o Moved algorithm-specific definitions from JWK to JWA. 907 o Reformatted to give each member definition its own section 908 heading. 910 -01 911 o Corrected the Magic Signatures reference. 913 -00 915 o Created the initial IETF draft based upon 916 draft-jones-json-web-key-03 with no normative changes. 918 Author's Address 920 Michael B. Jones 921 Microsoft 923 Email: mbj@microsoft.com 924 URI: http://self-issued.info/