idnits 2.17.1 draft-jones-json-web-key-00.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 (April 29, 2011) is 4736 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 April 29, 2011 5 Expires: October 31, 2011 7 JSON Web Key (JWK) 8 draft-jones-json-web-key-00 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 October 31, 2011. 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 ECDSA Keys . . . . . . . . . 5 63 4.2.2. JWK Key Object Members for RSA Keys . . . . . . . . . . 6 64 5. Base64url encoding as used by JWKs . . . . . . . . . . . . . . 6 65 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 6 66 7. Security Considerations . . . . . . . . . . . . . . . . . . . . 7 67 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7 68 8.1. Normative References . . . . . . . . . . . . . . . . . . . 7 69 8.2. Informative References . . . . . . . . . . . . . . . . . . 7 70 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . . 7 71 Appendix B. Document History . . . . . . . . . . . . . . . . . . . 7 72 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 8 74 1. Introduction 76 A JSON Web Key (JWK) is a JSON data structure that represents a set 77 of public keys as a JSON object [RFC4627]. The JWK format is used to 78 represent bare keys; representing certificate chains is an explicit 79 non-goal of this specification. JSON Web Keys are referenced in JSON 80 Web Signatures (JWSs) [JWS] using the "jku" (JSON Key URL) header 81 parameter. 83 2. Terminology 85 JSON Web Key (JWK) A JSON data structure that represents a set of 86 public keys. A JWK consists of a single JWK Container Object that 87 contains an array of JWK Key Objects. 89 JWK Container Object A JSON object that contains an array of JWK Key 90 Objects as a member. 92 JWK Key Object A JSON object that represents a single public key. 94 Base64url Encoding For the purposes of this specification, this term 95 always refers to the he URL- and filename-safe Base64 encoding 96 described in RFC 4648 [RFC4648], Section 5, with the '=' padding 97 characters omitted, as permitted by Section 3.2. 99 3. JSON Web Key (JWK) Overview 101 It is sometimes useful to be able to reference public key 102 representations, for instance, in order to verify the signature on 103 content signed with the corresponding private key. The JSON Web Key 104 (JWK) data structure provides a convenient JSON representation for 105 sets of public keys utilizing either the ECDSA or RSA families of 106 algorithms. 108 3.1. Example JWK 110 The following example JWK contains two public keys: one using the 111 ECDSA algorithm and a second one using the RSA algorithm. In both 112 cases, integers are represented using the base64url encoding of their 113 big endian representations. 115 {"keyvalues": 116 [ 117 {"algorithm":"ECDSA", 118 "curve":"P-256", 119 "x":"MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4", 120 "y":"4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM", 121 "keyid":"1"}, 123 {"algorithm":"RSA", 124 "modulus": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMstn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqbw0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw", 125 "exponent":"AQAB", 126 "keyid":"2011-04-29"} 127 ] 128 } 130 4. JWK Format 132 A JWK consists of a JWK Container Object, which is a JSON object that 133 contains an array of JWK Key Objects as a member. This section 134 specifies the format of these objects. 136 4.1. JWK Container Object Format 138 A JWK Container Object is a JSON object containing a specific member. 139 This member is: 141 +-----------+----------+--------------------------------------------+ 142 | Member | JSON | Container Object Member Semantics | 143 | Name | Value | | 144 | | Type | | 145 +-----------+----------+--------------------------------------------+ 146 | keyvalues | array | The "keyvalues" member value contains an | 147 | | | array of JWT Key Objects. This member is | 148 | | | REQUIRED. | 149 +-----------+----------+--------------------------------------------+ 151 JWK Container Object Member 153 Additional members MAY be present in the JWK Container Object. If 154 present, they MUST be understood by implementations using that JWK. 156 4.2. JWK Key Object Format 158 A JWK Key Object is a JSON object containing specific members. Those 159 members that are common to all key types are as follows: 161 +-----------+--------+----------------------------------------------+ 162 | Member | JSON | Key Object Member Semantics | 163 | Name | Value | | 164 | | Type | | 165 +-----------+--------+----------------------------------------------+ 166 | algorithm | string | The "algorithm" member identifies the | 167 | | | cryptographic algorithm used with the key. | 168 | | | Values defined by this specification are | 169 | | | "ECDSA" and "RSA". Specific additional | 170 | | | members are required to represent the key, | 171 | | | depending upon the "algorithm" value. The | 172 | | | "algorithm" value is case sensitive. This | 173 | | | member is REQUIRED. | 174 | keyid | string | The "keyid" (Key ID) member can be used to | 175 | | | match a specific key. This can be used, for | 176 | | | instance, to choose among a set of keys | 177 | | | within the JWK during key rollover. The | 178 | | | "keyid" value MAY correspond to a JWS "kid" | 179 | | | value. The interpretation of the "keyid" | 180 | | | value is unspecified. This member is | 181 | | | OPTIONAL. | 182 +-----------+--------+----------------------------------------------+ 184 JWK Key Object Members 186 Additional members MAY be present in the JWK Key Object. If present, 187 they MUST be understood by implementations using that key. 189 4.2.1. JWK Key Object Members for ECDSA Keys 191 JWKs can represent Elliptic Curve Digital Signature Algorithm (ECDSA) 192 [FIPS.186-3] keys. In this case, the "algorithm" member value MUST 193 be "ECDSA". Furthermore, these additional members MUST be present: 195 +--------+--------+-------------------------------------------------+ 196 | Member | JSON | Key Object Member Semantics | 197 | Name | Value | | 198 | | Type | | 199 +--------+--------+-------------------------------------------------+ 200 | curve | string | The "curve" member identifies the cryptographic | 201 | | | curve used with the key. Values defined by | 202 | | | this specification are "P-256", "P-384" and | 203 | | | "P-521". Additional "curve" values MAY be | 204 | | | used, provided they are understood by | 205 | | | implementations using that ECDSA key. The | 206 | | | "curve" value is case sensitive. | 207 | x | string | The "x" member contains the x coordinate for | 208 | | | the elliptic curve point. It is represented as | 209 | | | the base64url encoding of the coordinate's big | 210 | | | endian representation. | 211 | y | string | The "y" member contains the y coordinate for | 212 | | | the elliptic curve point. It is represented as | 213 | | | the base64url encoding of the coordinate's big | 214 | | | endian representation. | 215 +--------+--------+-------------------------------------------------+ 217 Members for ECDSA Keys 219 4.2.2. JWK Key Object Members for RSA Keys 221 JWKs can represent RSA [RFC3447] keys. In this case, the "algorithm" 222 member value MUST be "RSA". Furthermore, these additional members 223 MUST be present: 225 +----------+--------+-----------------------------------------------+ 226 | Member | JSON | Key Object Member Semantics | 227 | Name | Value | | 228 | | Type | | 229 +----------+--------+-----------------------------------------------+ 230 | modulus | string | The "modulus" member contains the modulus | 231 | | | value for the RSA public key. It is | 232 | | | represented as the base64url encoding of the | 233 | | | value's big endian representation. | 234 | exponent | string | The "exponent" member contains the exponent | 235 | | | value for the RSA public key. It is | 236 | | | represented as the base64url encoding of the | 237 | | | value's big endian representation. | 238 +----------+--------+-----------------------------------------------+ 240 Members for RSA Keys 242 5. Base64url encoding as used by JWKs 244 JWKs make use of the base64url encoding as defined in RFC 4648 245 [RFC4648]. As allowed by Section 3.2 of the RFC, this specification 246 mandates that base64url encoding when used with JWKs MUST NOT use 247 padding. Notes on implementing base64url encoding can be found in 248 the JWS [JWS] specification. 250 6. IANA Considerations 252 No IANA actions are required by this specification. 254 7. Security Considerations 256 TBD 258 8. References 260 8.1. Normative References 262 [FIPS.186-3] 263 National Institute of Standards and Technology, "Digital 264 Signature Standard (DSS)", FIPS PUB 186-3, June 2009. 266 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 267 Requirement Levels", BCP 14, RFC 2119, March 1997. 269 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 270 Standards (PKCS) #1: RSA Cryptography Specifications 271 Version 2.1", RFC 3447, February 2003. 273 [RFC4627] Crockford, D., "The application/json Media Type for 274 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 276 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 277 Encodings", RFC 4648, October 2006. 279 8.2. Informative References 281 [JWS] Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, 282 J., Sakimura, N., and P. Tarjan, "JSON Web Signature 283 (JWS)", April 2011. 285 [MagicSignatures] 286 Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic 287 Signatures", August 2010. 289 Appendix A. Acknowledgements 291 A JSON representation for RSA public keys was previously introduced 292 in Magic Signatures [MagicSignatures]. 294 Appendix B. Document History 296 -00 297 o Created first version based upon decisions made at the Internet 298 Identity Workshop (IIW), as documented at 299 http://self-issued.info/?p=390. 301 Author's Address 303 Michael B. Jones 304 Microsoft 306 Email: mbj@microsoft.com 307 URI: http://self-issued.info/