idnits 2.17.1 draft-jones-jose-jwe-json-serialization-04.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 (December 27, 2012) is 4128 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 4627 (Obsoleted by RFC 7158, RFC 7159) Summary: 1 error (**), 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 December 27, 2012 5 Expires: June 30, 2013 7 JSON Web Encryption JSON Serialization (JWE-JS) 8 draft-jones-jose-jwe-json-serialization-04 10 Abstract 12 The JSON Web Encryption JSON Serialization (JWE-JS) is a means of 13 representing encrypted content using JavaScript Object Notation 14 (JSON) data structures. This specification describes a means of 15 representing secured content as a JSON data object (as opposed to the 16 JWE specification, which uses a compact serialization with a URL-safe 17 representation). It enables the same content to be encrypted to 18 multiple parties (unlike JWE). Cryptographic algorithms and 19 identifiers used with this specification are described in the 20 separate JSON Web Algorithms (JWA) specification. The JSON 21 Serialization for related digital signature and MAC functionality is 22 described in the separate JSON Web Signature JSON Serialization 23 (JWS-JS) specification. 25 Status of this Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at http://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on June 30, 2013. 42 Copyright Notice 44 Copyright (c) 2012 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (http://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 60 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 61 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . 3 62 3. JSON Serialization . . . . . . . . . . . . . . . . . . . . . . 3 63 4. Example JWE-JS . . . . . . . . . . . . . . . . . . . . . . . . 5 64 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 6 65 6. Security Considerations . . . . . . . . . . . . . . . . . . . . 6 66 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 6 67 7.1. Normative References . . . . . . . . . . . . . . . . . . . 6 68 7.2. Informative References . . . . . . . . . . . . . . . . . . 7 69 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . . 7 70 Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . . 7 71 Appendix C. Document History . . . . . . . . . . . . . . . . . . . 7 72 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 9 74 1. Introduction 76 The JSON Web Encryption JSON Serialization (JWE-JS) is a format for 77 representing encrypted content as a JavaScript Object Notation (JSON) 78 [RFC4627] object. It enables the same content to be encrypted to 79 multiple parties (unlike JWE [JWE].) The encryption mechanisms are 80 independent of the type of content being encrypted. Cryptographic 81 algorithms and identifiers used with this specification are described 82 in the separate JSON Web Algorithms (JWA) [JWA] specification. The 83 JSON Serialization for related digital signature and MAC 84 functionality is described in the separate JSON Web Signature JSON 85 Serialization (JWS-JS) [JWS-JS] specification. 87 1.1. Notational Conventions 89 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 90 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 91 document are to be interpreted as described in Key words for use in 92 RFCs to Indicate Requirement Levels [RFC2119]. 94 2. Terminology 96 This specification uses the same terminology as the JSON Web 97 Encryption (JWE) [JWE] specification. 99 3. JSON Serialization 101 The JSON Serialization represents encrypted content as a JSON object 102 with a "recipients" member containing an array of per-recipient 103 information, an "initialization_vector" member containing a shared 104 Encoded JWE Initialization Vector value, and a "ciphertext" member 105 containing a shared Encoded JWE Ciphertext value. Each member of the 106 "recipients" array is a JSON object with a "header" member containing 107 an Encoded JWE Header value, an "encrypted_key" member containing an 108 Encoded JWE Encrypted Key value, and an "integrity_value" member 109 containing an Encoded JWE Integrity Value value. 111 Unlike the compact serialization used by JWEs, content using the JSON 112 Serialization MAY be encrypted to more than one recipient. Each 113 recipient requires: 115 o a JWE Header value specifying the cryptographic parameters used to 116 encrypt the JWE Encrypted Key to that recipient and the parameters 117 used to encrypt the plaintext to produce the JWE Ciphertext; this 118 is represented as an Encoded JWE Header value in the "header" 119 member of an object in the "recipients" array. 121 o a JWE Encrypted Key value used to encrypt the ciphertext; this is 122 represented as an Encoded JWE Encrypted Key value in the 123 "encrypted_key" member of the same object in the "recipients" 124 array. 126 o a JWE Integrity Value that ensures the integrity of the Ciphertext 127 and the parameters used to create it; this is represented as an 128 Encoded JWE Integrity Value value in the "integrity_value" member 129 of the same object in the "recipients" array. 131 Therefore, the syntax is: 133 {"recipients":[ 134 {"header":"
", 135 "encrypted_key":"", 136 "integrity_value":""}, 137 ... 138 {"header":"
", 139 "encrypted_key":"", 140 "integrity_value":""}], 141 "initialization_vector":"", 142 "ciphertext":"" 143 } 145 The contents of the Encoded JWE Header, Encoded JWE Encrypted Key, 146 Encoded JWE Initialization Vector, Encoded JWE Ciphertext, and 147 Encoded JWE Integrity Value values are exactly as specified in JSON 148 Web Encryption (JWE) [JWE]. They are interpreted and validated in 149 the same manner, with each corresponding "header", "encrypted_key", 150 and "integrity_value" value being created and validated together. 152 Each JWE Encrypted Key value and the corresponding JWE Integrity 153 Value are computed using the parameters of the corresponding JWE 154 Header value in the same manner described in the JWE specification. 155 This has the desirable result that each Encoded JWE Encrypted Key 156 value in the "recipients" array and each Encoded JWE Integrity Value 157 in the same array element are identical to the values that would have 158 been computed for the same parameters in a JWE, as is the shared JWE 159 Ciphertext value. 161 All recipients use the same JWE Ciphertext and JWE Initialization 162 Vector values, resulting in potentially significant space savings if 163 the message is large. Therefore, all header parameters that specify 164 the treatment of the JWE Ciphertext value MUST be the same for all 165 recipients. This primarily means that the "enc" (encryption method) 166 header parameter value in the JWE Header for each recipient MUST be 167 the same. 169 4. Example JWE-JS 171 This section contains an example using the JWE JSON Serialization. 172 This example demonstrates the capability for encrypting the same 173 plaintext to multiple recipients. 175 Two recipients are present in this example: the first using the 176 RSAES-PKCS1-V1_5 algorithm to encrypt the Content Master Key (CMK) 177 and the second using RSAES OAEP to encrypt the CMK. The Plaintext is 178 encrypted using the AES CBC algorithm and the same block encryption 179 parameters to produce the common JWE Ciphertext value. The two 180 Decoded JWE Header Segments used are: 182 {"alg":"RSA1_5","enc":"A128CBC+HS256"} 184 and: 186 {"alg":"RSA-OAEP","enc":"A128CBC+HS256"} 188 The keys used for the first recipient are the same as those in 189 Appendix A.2 of [JWE], as is the plaintext used. The asymmetric 190 encryption key used for the second recipient is the same as that used 191 in Appendix A.1 of [JWE]; the block encryption keys and parameters 192 for the second recipient are the same as those for the first 193 recipient (which must be the case, since the initialization vector 194 and ciphertext are shared). 196 The complete JSON Web Encryption JSON Serialization (JWE-JS) for 197 these values is as follows (with line breaks for display purposes 198 only): 200 {"recipients":[ 201 {"header": 202 "eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDK0hTMjU2In0", 203 "encrypted_key": 204 "ZmnlqWgjXyqwjr7cXHys8F79anIUI6J2UWdAyRQEcGBU-KPHsePM910_RoTDG 205 u1IW40Dn0dvcdVEjpJcPPNIbzWcMxDi131Ejeg-b8ViW5YX5oRdYdiR4gMSDD 206 B3mbkInMNUFT-PK5CuZRnHB2rUK5fhPuF6XFqLLZCG5Q_rJm6Evex-XLcNQAJ 207 Na1-6CIU12Wj3mPExxw9vbnsQDU7B4BfmhdyiflLA7Ae5ZGoVRl3A__yLPXxR 208 jHFhpOeDp_adx8NyejF5cz9yDKULugNsDMdlHeJQOMGVLYaSZt3KP6aWNSqFA 209 1PHDg-10ceuTEtq_vPE4-Gtev4N4K4Eudlj4Q", 210 "integrity_value": 211 "8LXqMd0JLGsxMaB5uoNaMpg7uUW_p40RlaZHCwMIyzk"}, 212 {"header": 213 "eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkExMjhDQkMrSFMyNTYifQ", 214 "encrypted_key": 215 "nxwnYB86zEvVRofSxnDuFAE9-Gi2JtCy5eMyYedowjfGlkoA-Y0JyfwWXE_EU 216 vhq6WS_DM3a18You2Qsah3BvvSRPZ8-TNYX3_4QCEO-V8EVbF1eGoJFs9ODmC 217 cOiuMl1xLnSAYlwEDDnhwEkXv8o6MZEvh-msqTY6NyFGd6mhjpu9P4o2F2hOe 218 Nt6FthcR4cNpAVSbydEEBszsrp27nB-JwfmLjnSYQO1JBwbgUJXHZyIJcQa7i 219 43Vko02HkWTxBta0q5Zr_Jd7V2l-6HLYIuNc7fZH1DSJSTBTotcugumR5zNX_ 220 uxQyMoWOQ-SsQ7HxqrrFbo5FNoLPZiuNYuCdQ", 221 "integrity_value": 222 "QbYksTWNZTcMfJMLoGB_aTCA0-IuNObm19_VdpabviM"}], 223 "initialization_vector": 224 "AxY8DCtDaGlsbGljb3RoZQ", 225 "ciphertext": 226 "Rxsjg6PIExcmGSF7LnSEkDqWIKfAw1wZz2XpabV5PwQsolKwEauWYZNE9Q1hZJE 227 Z" 228 } 230 5. IANA Considerations 232 This specification makes no requests of IANA. 234 6. Security Considerations 236 The security considerations for this specification are the same as 237 those for the JSON Web Encryption (JWE) [JWE] specification. 239 7. References 241 7.1. Normative References 243 [JWA] Jones, M., "JSON Web Algorithms (JWA)", 244 draft-ietf-jose-json-web-algorithms (work in progress), 245 December 2012. 247 [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web 248 Encryption (JWE)", draft-ietf-jose-json-web-encryption 249 (work in progress), December 2012. 251 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 252 Requirement Levels", BCP 14, RFC 2119, March 1997. 254 [RFC4627] Crockford, D., "The application/json Media Type for 255 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 257 7.2. Informative References 259 [I-D.rescorla-jsms] 260 Rescorla, E. and J. Hildebrand, "JavaScript Message 261 Security Format", draft-rescorla-jsms-00 (work in 262 progress), March 2011. 264 [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple 265 Encryption", September 2010. 267 [JWS-JS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 268 Signature JSON Serialization (JWS-JS)", 269 draft-jones-jose-jws-json-serialization (work in 270 progress), December 2012. 272 Appendix A. Acknowledgements 274 JSON serializations for encrypted content were previously explored by 275 JSON Simple Encryption [JSE] and JavaScript Message Security Format 276 [I-D.rescorla-jsms]. 278 Appendix B. Open Issues 280 [[ to be removed by the RFC editor before publication as an RFC ]] 282 The following items remain to be considered or done in this draft: 284 o Track changes that occur in the JWE spec. 286 Appendix C. Document History 288 [[ to be removed by the RFC editor before publication as an RFC ]] 289 -04 291 o Added seriesInfo information to Internet Draft references. 293 -03 295 o Updated values for example AES CBC calculations. 297 -02 299 o Changed to use an array of structures for per-recipient values, 300 rather than a set of parallel arrays. 302 o Promoted Initialization Vector from being a header parameter to 303 being a top-level JWE element. This saves approximately 16 bytes 304 in the compact serialization, which is a significant savings for 305 some use cases. Promoting the Initialization Vector out of the 306 header also avoids repeating this shared value in the JSON 307 serialization. 309 -01 311 o Added a complete JWE-JS example. 313 o Generalized language to refer to Message Authentication Codes 314 (MACs) rather than Hash-based Message Authentication Codes 315 (HMACs). 317 -00 319 o Renamed draft-jones-json-web-encryption-json-serialization to 320 draft-jones-jose-jwe-json-serialization to have "jose" be in the 321 document name so it can be included in the Related Documents list 322 at http://datatracker.ietf.org/wg/jose/. No normative changes. 324 draft-jones-json-web-encryption-json-serialization-02 326 o Updated examples to track updated algorithm properties in the JWA 327 spec. 329 o Tracked editorial changes made to the JWE spec. 331 draft-jones-json-web-encryption-json-serialization-01 333 o Tracked changes between JOSE JWE draft -00 and -01, which added an 334 integrity check for non-Authenticated Encryption algorithms. 336 draft-jones-json-web-encryption-json-serialization-00 337 o Created the initial version incorporating JOSE working group input 338 and drawing from the JSON Serialization previously proposed in 339 draft-jones-json-web-token-01. 341 Author's Address 343 Michael B. Jones 344 Microsoft 346 Email: mbj@microsoft.com 347 URI: http://self-issued.info/