idnits 2.17.1 draft-jones-json-web-key-02.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 : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 290 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 30, 2011) is 4560 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) ** Obsolete normative reference: RFC 3447 (Obsoleted by RFC 8017) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) Summary: 3 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Jones 3 Internet-Draft Microsoft 4 Intended status: Standards Track October 30, 2011 5 Expires: May 2, 2012 7 JSON Web Key (JWK) 8 draft-jones-json-web-key-02 10 Abstract 12 A JSON Web Key (JWK) is a JSON data structure that represents a set 13 of public keys. 15 Requirements Language 17 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 18 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 19 document are to be interpreted as described in RFC 2119 [RFC2119]. 21 Status of this Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on May 2, 2012. 38 Copyright Notice 40 Copyright (c) 2011 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 3. JSON Web Key (JWK) Overview . . . . . . . . . . . . . . . . . . 3 58 3.1. Example JWK . . . . . . . . . . . . . . . . . . . . . . . . 3 59 4. JWK Format . . . . . . . . . . . . . . . . . . . . . . . . . . 4 60 4.1. JWK Container Object Format . . . . . . . . . . . . . . . . 4 61 4.2. JWK Key Object Format . . . . . . . . . . . . . . . . . . . 4 62 4.2.1. JWK Key Object Members for Elliptic Curve Keys . . . . 5 63 4.2.2. JWK Key Object Members for RSA Keys . . . . . . . . . . 6 64 5. Base64url encoding as used by JWKs . . . . . . . . . . . . . . 7 65 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 7 66 7. Security Considerations . . . . . . . . . . . . . . . . . . . . 7 67 8. Open Issues and Things To Be Done (TBD) . . . . . . . . . . . . 7 68 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7 69 9.1. Normative References . . . . . . . . . . . . . . . . . . . 7 70 9.2. Informative References . . . . . . . . . . . . . . . . . . 8 71 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . . 8 72 Appendix B. Document History . . . . . . . . . . . . . . . . . . . 8 73 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 8 75 1. Introduction 77 A JSON Web Key (JWK) is a JSON data structure that represents a set 78 of public keys as a JSON object [RFC4627]. The JWK format is used to 79 represent bare keys; representing certificate chains is an explicit 80 non-goal of this specification. JSON Web Keys are referenced in JSON 81 Web Signatures (JWSs) [JWS] using the "jku" (JSON Key URL) header 82 parameter. 84 2. Terminology 86 JSON Web Key (JWK) A JSON data structure that represents a set of 87 public keys. A JWK consists of a single JWK Container Object that 88 contains an array of JWK Key Objects. 90 JWK Container Object A JSON object that contains an array of JWK Key 91 Objects as a member. 93 JWK Key Object A JSON object that represents a single public key. 95 Base64url Encoding For the purposes of this specification, this term 96 always refers to the URL- and filename-safe Base64 encoding 97 described in RFC 4648 [RFC4648], Section 5, with the (non URL- 98 safe) '=' padding characters omitted, as permitted by Section 3.2. 99 (See Appendix C of [JWS] for notes on implementing base64url 100 encoding without padding.) 102 3. JSON Web Key (JWK) Overview 104 It is sometimes useful to be able to reference public key 105 representations, for instance, in order to verify the signature on 106 content signed with the corresponding private key. The JSON Web Key 107 (JWK) data structure provides a convenient JSON representation for 108 sets of public keys utilizing either the Elliptic Curve or RSA 109 families of algorithms. 111 3.1. Example JWK 113 The following example JWK contains two public keys: one using an 114 Elliptic Curve algorithm and a second one using an RSA algorithm. In 115 both cases, integers are represented using the base64url encoding of 116 their big endian representations. 118 {"keyvalues": 119 [ 120 {"algorithm":"EC", 121 "curve":"P-256", 122 "x":"MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4", 123 "y":"4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM", 124 "use":"encryption", 125 "keyid":"1"}, 127 {"algorithm":"RSA", 128 "modulus": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMstn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqbw0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw", 129 "exponent":"AQAB", 130 "keyid":"2011-04-29"} 131 ] 132 } 134 4. JWK Format 136 A JWK consists of a JWK Container Object, which is a JSON object that 137 contains an array of JWK Key Objects as a member. This section 138 specifies the format of these objects. 140 4.1. JWK Container Object Format 142 A JWK Container Object is a JSON object containing a specific member. 143 This member is: 145 +-----------+----------+--------------------------------------------+ 146 | Member | JSON | Container Object Member Semantics | 147 | Name | Value | | 148 | | Type | | 149 +-----------+----------+--------------------------------------------+ 150 | keyvalues | array | The "keyvalues" member value contains an | 151 | | | array of JWK Key Objects. This member is | 152 | | | REQUIRED. | 153 +-----------+----------+--------------------------------------------+ 155 JWK Container Object Member 157 Additional members MAY be present in the JWK Container Object. If 158 present, they MUST be understood by implementations using that JWK. 160 4.2. JWK Key Object Format 162 A JWK Key Object is a JSON object containing specific members. Those 163 members that are common to all key types are as follows: 165 +-----------+--------+----------------------------------------------+ 166 | Member | JSON | Key Object Member Semantics | 167 | Name | Value | | 168 | | Type | | 169 +-----------+--------+----------------------------------------------+ 170 | algorithm | string | The "algorithm" member identifies the | 171 | | | cryptographic algorithm family used with the | 172 | | | key. Values defined by this specification | 173 | | | are "EC" and "RSA". Specific additional | 174 | | | members are required to represent the key, | 175 | | | depending upon the "algorithm" value. The | 176 | | | "algorithm" value is case sensitive. This | 177 | | | member is REQUIRED. | 178 | use | string | The "use" member identifies the intended use | 179 | | | of the key. Values defined by this | 180 | | | specification are "signature" and | 181 | | | "encryption". Other values MAY be used. | 182 | | | The "use" value is case sensitive. This | 183 | | | member is OPTIONAL. | 184 | keyid | string | The "keyid" (Key ID) member can be used to | 185 | | | match a specific key. This can be used, for | 186 | | | instance, to choose among a set of keys | 187 | | | within the JWK during key rollover. The | 188 | | | "keyid" value MAY correspond to a JWS "kid" | 189 | | | value. The interpretation of the "keyid" | 190 | | | value is unspecified. This member is | 191 | | | OPTIONAL. | 192 +-----------+--------+----------------------------------------------+ 194 JWK Key Object Members 196 Additional members MAY be present in the JWK Key Object. If present, 197 they MUST be understood by implementations using that key. 199 4.2.1. JWK Key Object Members for Elliptic Curve Keys 201 JWKs can represent Elliptic Curve [FIPS.186-3] keys. In this case, 202 the "algorithm" member value MUST be "EC". Furthermore, these 203 additional members MUST be present: 205 +--------+--------+-------------------------------------------------+ 206 | Member | JSON | Key Object Member Semantics | 207 | Name | Value | | 208 | | Type | | 209 +--------+--------+-------------------------------------------------+ 210 | curve | string | The "curve" member identifies the cryptographic | 211 | | | curve used with the key. Values defined by | 212 | | | this specification are "P-256", "P-384" and | 213 | | | "P-521". Additional "curve" values MAY be | 214 | | | used, provided they are understood by | 215 | | | implementations using that Elliptic Curve key. | 216 | | | The "curve" value is case sensitive. | 217 | x | string | The "x" member contains the x coordinate for | 218 | | | the elliptic curve point. It is represented as | 219 | | | the base64url encoding of the coordinate's big | 220 | | | endian representation. | 221 | y | string | The "y" member contains the y coordinate for | 222 | | | the elliptic curve point. It is represented as | 223 | | | the base64url encoding of the coordinate's big | 224 | | | endian representation. | 225 +--------+--------+-------------------------------------------------+ 227 Members for Elliptic Curve Keys 229 4.2.2. JWK Key Object Members for RSA Keys 231 JWKs can represent RSA [RFC3447] keys. In this case, the "algorithm" 232 member value MUST be "RSA". Furthermore, these additional members 233 MUST be present: 235 +----------+--------+-----------------------------------------------+ 236 | Member | JSON | Key Object Member Semantics | 237 | Name | Value | | 238 | | Type | | 239 +----------+--------+-----------------------------------------------+ 240 | modulus | string | The "modulus" member contains the modulus | 241 | | | value for the RSA public key. It is | 242 | | | represented as the base64url encoding of the | 243 | | | value's big endian representation. | 244 | exponent | string | The "exponent" member contains the exponent | 245 | | | value for the RSA public key. It is | 246 | | | represented as the base64url encoding of the | 247 | | | value's big endian representation. | 248 +----------+--------+-----------------------------------------------+ 250 Members for RSA Keys 252 5. Base64url encoding as used by JWKs 254 JWKs make use of the base64url encoding as defined in RFC 4648 255 [RFC4648]. As allowed by Section 3.2 of the RFC, this specification 256 mandates that base64url encoding when used with JWKs MUST NOT use 257 padding. Notes on implementing base64url encoding can be found in 258 the JWS [JWS] specification. 260 6. IANA Considerations 262 No IANA actions are required by this specification. 264 7. Security Considerations 266 TBD 268 8. Open Issues and Things To Be Done (TBD) 270 The following items remain to be done in this draft: 272 o Write the Security Considerations section. 274 9. References 276 9.1. Normative References 278 [FIPS.186-3] 279 National Institute of Standards and Technology, "Digital 280 Signature Standard (DSS)", FIPS PUB 186-3, June 2009. 282 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 283 Requirement Levels", BCP 14, RFC 2119, March 1997. 285 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 286 Standards (PKCS) #1: RSA Cryptography Specifications 287 Version 2.1", RFC 3447, February 2003. 289 [RFC4627] Crockford, D., "The application/json Media Type for 290 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 292 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 293 Encodings", RFC 4648, October 2006. 295 9.2. Informative References 297 [JWS] Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, 298 J., Sakimura, N., and P. Tarjan, "JSON Web Signature 299 (JWS)", October 2011. 301 [MagicSignatures] 302 Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic 303 Signatures", August 2010. 305 Appendix A. Acknowledgements 307 A JSON representation for RSA public keys was previously introduced 308 in Magic Signatures [MagicSignatures]. 310 Appendix B. Document History 312 -02 314 o Editorial changes to have this spec better match the JWT, JWS, and 315 JWE specs. No normative changes. 317 -01 319 o Changed "algorithm" member value for Elliptic Curve keys from 320 "ECDSA" to "EC", since Elliptic Curve keys can be used with more 321 algorithms than just the Elliptic Curve Digital Signature 322 Algorithm (ECDSA). 324 o Added OPTIONAL "use" member to identify intended key usage, 325 especially since the same Elliptic Curve key should not be used 326 for both signing and encryption operations. 328 -00 330 o Created first version based upon decisions made at the Internet 331 Identity Workshop (IIW), as documented at 332 http://self-issued.info/?p=390. 334 Author's Address 336 Michael B. Jones 337 Microsoft 339 Email: mbj@microsoft.com 340 URI: http://self-issued.info/