idnits 2.17.1 draft-ietf-jose-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 : ---------------------------------------------------------------------------- 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 (January 16, 2012) is 4483 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: 2 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). 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 January 16, 2012 5 Expires: July 19, 2012 7 JSON Web Key (JWK) 8 draft-ietf-jose-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 July 19, 2012. 38 Copyright Notice 40 Copyright (c) 2012 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 . . . . . . . . . . . . . . . . . . . 5 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 Signature (JWS) [JWS] using the "jku" (JSON Key URL) header 82 parameter and in JSON Web Encryption (JWE) [JWE] using the "jku" 83 (JSON Key URL) and "epk" (Ephemeral Public Key) header parameters. 85 2. Terminology 87 JSON Web Key (JWK) A JSON data structure that represents a set of 88 public keys. A JWK consists of a single JWK Container Object that 89 contains an array of JWK Key Objects. 91 JWK Container Object A JSON object that contains an array of JWK Key 92 Objects as a member. 94 JWK Key Object A JSON object that represents a single public key. 96 Base64url Encoding For the purposes of this specification, this term 97 always refers to the URL- and filename-safe Base64 encoding 98 described in RFC 4648 [RFC4648], Section 5, with the (non URL- 99 safe) '=' padding characters omitted, as permitted by Section 3.2. 100 (See Appendix B of [JWS] for notes on implementing base64url 101 encoding without padding.) 103 3. JSON Web Key (JWK) Overview 105 It is sometimes useful to be able to reference public key 106 representations, for instance, in order to verify the digital 107 signature on content signed with the corresponding private key. The 108 JSON Web Key (JWK) data structure provides a convenient JSON 109 representation for sets of public keys utilizing either the Elliptic 110 Curve or RSA families of algorithms. 112 3.1. Example JWK 114 The following example JWK contains two public keys: one using an 115 Elliptic Curve algorithm and a second one using an RSA algorithm. 116 The first specifies that the key is to be used for encryption. Both 117 provide a Key ID for matching purposes. In both cases, integers are 118 represented using the base64url encoding of their big endian 119 representations. (Long lines are broken are for display purposes 120 only.) 121 {"jwk": 122 [ 123 {"alg":"EC", 124 "crv":"P-256", 125 "x":"MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4", 126 "y":"4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM", 127 "use":"enc", 128 "kid":"1"}, 130 {"alg":"RSA", 131 "mod": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx 132 4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMs 133 tn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2 134 QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbI 135 SD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqb 136 w0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw", 137 "exp":"AQAB", 138 "kid":"2011-04-29"} 139 ] 140 } 142 4. JWK Format 144 A JWK consists of a JWK Container Object, which is a JSON object that 145 contains an array of JWK Key Objects as a member. This section 146 specifies the format of these objects. 148 4.1. JWK Container Object Format 150 A JWK Container Object is a JSON object containing a specific member. 151 This member is: 153 +--------+----------+-----------------------------------------------+ 154 | Member | JSON | Container Object Member Semantics | 155 | Name | Value | | 156 | | Type | | 157 +--------+----------+-----------------------------------------------+ 158 | jwk | array | The "jwk" member value contains an array of | 159 | | | JWK Key Objects. This member is REQUIRED. | 160 +--------+----------+-----------------------------------------------+ 162 JWK Container Object Member 164 Additional members MAY be present in the JWK Container Object. If 165 present, they MUST be understood by implementations using that JWK. 167 4.2. JWK Key Object Format 169 A JWK Key Object is a JSON object containing specific members. Those 170 members that are common to all key types are as follows: 172 +--------+--------+-------------------------------------------------+ 173 | Member | JSON | Key Object Member Semantics | 174 | Name | Value | | 175 | | Type | | 176 +--------+--------+-------------------------------------------------+ 177 | alg | string | The "alg" member identifies the cryptographic | 178 | | | algorithm family used with the key. Values | 179 | | | defined by this specification are "EC" and | 180 | | | "RSA". Specific additional members are | 181 | | | required to represent the key, depending upon | 182 | | | the "alg" value. The "alg" value is case | 183 | | | sensitive. This member is REQUIRED. | 184 | use | string | The "use" member identifies the intended use of | 185 | | | the key. Values defined by this specification | 186 | | | are "sig" (signature) and "enc" (encryption). | 187 | | | Other values MAY be used. The "use" value is | 188 | | | case sensitive. This member is OPTIONAL. | 189 | kid | string | The "kid" (Key ID) member can be used to match | 190 | | | a specific key. This can be used, for | 191 | | | instance, to choose among a set of keys within | 192 | | | the JWK during key rollover. The "kid" value | 193 | | | MAY correspond to a JWS "kid" value. The | 194 | | | interpretation of the "kid" value is | 195 | | | unspecified. This member is OPTIONAL. | 196 +--------+--------+-------------------------------------------------+ 198 JWK Key Object Members 200 Additional members MAY be present in the JWK Key Object. If present, 201 they MUST be understood by implementations using that key. 203 4.2.1. JWK Key Object Members for Elliptic Curve Keys 205 JWKs can represent Elliptic Curve [FIPS.186-3] keys. In this case, 206 the "alg" member value MUST be "EC". Furthermore, these additional 207 members MUST be present: 209 +--------+--------+-------------------------------------------------+ 210 | Member | JSON | Key Object Member Semantics | 211 | Name | Value | | 212 | | Type | | 213 +--------+--------+-------------------------------------------------+ 214 | crv | string | The "crv" member identifies the cryptographic | 215 | | | curve used with the key. Values defined by | 216 | | | this specification are "P-256", "P-384" and | 217 | | | "P-521". Additional "crv" values MAY be used, | 218 | | | provided they are understood by implementations | 219 | | | using that Elliptic Curve key. The "crv" value | 220 | | | is case sensitive. | 221 | x | string | The "x" member contains the x coordinate for | 222 | | | the elliptic curve point. It is represented as | 223 | | | the base64url encoding of the coordinate's big | 224 | | | endian representation. | 225 | y | string | The "y" member contains the y coordinate for | 226 | | | the elliptic curve point. It is represented as | 227 | | | the base64url encoding of the coordinate's big | 228 | | | endian representation. | 229 +--------+--------+-------------------------------------------------+ 231 Members for Elliptic Curve Keys 233 4.2.2. JWK Key Object Members for RSA Keys 235 JWKs can represent RSA [RFC3447] keys. In this case, the "alg" 236 member value MUST be "RSA". Furthermore, these additional members 237 MUST be present: 239 +--------+--------+-------------------------------------------------+ 240 | Member | JSON | Key Object Member Semantics | 241 | Name | Value | | 242 | | Type | | 243 +--------+--------+-------------------------------------------------+ 244 | mod | string | The "mod" member contains the modulus value for | 245 | | | the RSA public key. It is represented as the | 246 | | | base64url encoding of the value's big endian | 247 | | | representation. | 248 | exp | string | The "exp" member contains the exponent value | 249 | | | for the RSA public key. It is represented as | 250 | | | the base64url encoding of the value's big | 251 | | | endian representation. | 252 +--------+--------+-------------------------------------------------+ 254 Members for RSA Keys 256 5. Base64url encoding as used by JWKs 258 JWKs make use of the base64url encoding as defined in RFC 4648 259 [RFC4648]. As allowed by Section 3.2 of the RFC, this specification 260 mandates that base64url encoding when used with JWKs MUST NOT use 261 padding. Notes on implementing base64url encoding can be found in 262 the JWS [JWS] specification. 264 6. IANA Considerations 266 No IANA actions are required by this specification. 268 7. Security Considerations 270 TBD 272 8. Open Issues and Things To Be Done (TBD) 274 The following items remain to be done in this draft: 276 o Write the Security Considerations section. 278 9. References 280 9.1. Normative References 282 [FIPS.186-3] 283 National Institute of Standards and Technology, "Digital 284 Signature Standard (DSS)", FIPS PUB 186-3, June 2009. 286 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 287 Requirement Levels", BCP 14, RFC 2119, March 1997. 289 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 290 Standards (PKCS) #1: RSA Cryptography Specifications 291 Version 2.1", RFC 3447, February 2003. 293 [RFC4627] Crockford, D., "The application/json Media Type for 294 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 296 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 297 Encodings", RFC 4648, October 2006. 299 9.2. Informative References 301 [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web 302 Encryption (JWE)", January 2012. 304 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 305 Signature (JWS)", January 2012. 307 [MagicSignatures] 308 Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic 309 Signatures", August 2010. 311 Appendix A. Acknowledgements 313 A JSON representation for RSA public keys was previously introduced 314 in Magic Signatures [MagicSignatures]. 316 Appendix B. Document History 318 -00 320 o Created the initial IETF draft based upon 321 draft-jones-json-web-key-03 with no normative changes. 323 Author's Address 325 Michael B. Jones 326 Microsoft 328 Email: mbj@microsoft.com 329 URI: http://self-issued.info/