idnits 2.17.1 draft-jones-jose-jwe-json-serialization-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 : ---------------------------------------------------------------------------- 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 (October 15, 2012) is 4203 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. 'JWA' -- Possible downref: Non-RFC (?) normative reference: ref. 'JWE' ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 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 October 15, 2012 5 Expires: April 18, 2013 7 JSON Web Encryption JSON Serialization (JWE-JS) 8 draft-jones-jose-jwe-json-serialization-02 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 April 18, 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 . . . . . . . . . . . . . . . . . . . . . . . . . 8 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 "O6AqXqgVlJJ4c4lp5sXZd7bpGHAw6ARkHUeXQxD1cAW4-X1x0qtj_AN0mukqE 205 Ol4Y6UOwJXIJY9-G1ELK-RQWrKH_StR-AM9H7GpKmSEji8QYOcMOjr-u9H1Lt 206 _pBEieG802SxWz0rbFTXRcj4BWLxcpCtjUZ31AP-sc-L_eCZ5UNl0aSRNqFsk 207 uPkzRsFZRDJqSSJeVOyJ7pZCQ83fli19Vgi_3R7XMUqluQuuc7ZHOWixi47jX 208 lBTlWRZ5iFxaS8G6J8wUrd4BKggAw3qX5XoIfXQVlQZE0Vmkq_zQSIo5LnFKy 209 owooRcdsEuNh9B9Mkyt0ZQElG-jGdtHWjZSOA", 210 "integrity_value": 211 "RBGhYzE8_cZLHjJqqHuLhzbgWgL_wV3LDSUrcbkOiIA"}, 212 {"header": 213 "eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkExMjhDQkMrSFMyNTYifQ", 214 "encrypted_key": 215 "myoFYZHErXG4gMVWl9UrFOCFIwvOUudYrxTsRsOt6maTc3W8G1FqGVOIBSZve 216 BdZz2LqS42xta5OXEwLYaocObUxtfH9H8vMsjO-mBo7U9mp_PkS9PqVJMkeEe 217 PLhzNLH0ecq7nYT6AFr5sSt4WMOPjSwHVQWtx43fZt4HvYaE_vgeSrxdi8KAb 218 xbLzK_-qcYT6H7cwOMZrT6SFcXgLXESuKpF0azSGQtUmo0MLICP0YPBecGLTo 219 PiveOH2awKZx0FkzPwi4JmOIvnAJ_wVQQJDVELwO9SIoF8olCQRHGyZ9rzDrr 220 GRkoYgm2jVz-x0BuFVQFa4ZNufudtiT8pQxKg", 221 "integrity_value": 222 "i45dXWFjRKk805VtjIw_8iqGq1r9qPV7ULDLbnNAC_Q"}], 223 "initialization_vector": 224 "AxY8DCtDaGlsbGljb3RoZQ", 225 "ciphertext": 226 "1eBWFgcrz40wC88cgv8rPgu3EfmC1p4zT0kIxxfSF2zDJcQ-iEHk1jQM95xAdr5 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)", October 2012. 245 [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web 246 Encryption (JWE)", October 2012. 248 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 249 Requirement Levels", BCP 14, RFC 2119, March 1997. 251 [RFC4627] Crockford, D., "The application/json Media Type for 252 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 254 7.2. Informative References 256 [I-D.rescorla-jsms] 257 Rescorla, E. and J. Hildebrand, "JavaScript Message 258 Security Format", draft-rescorla-jsms-00 (work in 259 progress), March 2011. 261 [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple 262 Encryption", September 2010. 264 [JWS-JS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 265 Signature JSON Serialization (JWS-JS)", October 2012. 267 Appendix A. Acknowledgements 269 JSON serializations for encrypted content were previously explored by 270 JSON Simple Encryption [JSE] and JavaScript Message Security Format 271 [I-D.rescorla-jsms]. 273 Appendix B. Open Issues 275 [[ to be removed by the RFC editor before publication as an RFC ]] 277 The following items remain to be considered or done in this draft: 279 o Track changes that occur in the JWE spec. 281 Appendix C. Document History 283 [[ to be removed by the RFC editor before publication as an RFC ]] 285 -02 287 o Changed to use an array of structures for per-recipient values, 288 rather than a set of parallel arrays. 290 o Promoted Initialization Vector from being a header parameter to 291 being a top-level JWE element. This saves approximately 16 bytes 292 in the compact serialization, which is a significant savings for 293 some use cases. Promoting the Initialization Vector out of the 294 header also avoids repeating this shared value in the JSON 295 serialization. 297 -01 299 o Added a complete JWE-JS example. 301 o Generalized language to refer to Message Authentication Codes 302 (MACs) rather than Hash-based Message Authentication Codes 303 (HMACs). 305 -00 307 o Renamed draft-jones-json-web-encryption-json-serialization to 308 draft-jones-jose-jwe-json-serialization to have "jose" be in the 309 document name so it can be included in the Related Documents list 310 at http://datatracker.ietf.org/wg/jose/. No normative changes. 312 draft-jones-json-web-encryption-json-serialization-02 314 o Updated examples to track updated algorithm properties in the JWA 315 spec. 317 o Tracked editorial changes made to the JWE spec. 319 draft-jones-json-web-encryption-json-serialization-01 321 o Tracked changes between JOSE JWE draft -00 and -01, which added an 322 integrity check for non-AEAD algorithms. 324 draft-jones-json-web-encryption-json-serialization-00 326 o Created the initial version incorporating JOSE working group input 327 and drawing from the JSON Serialization previously proposed in 328 draft-jones-json-web-token-01. 330 Author's Address 332 Michael B. Jones 333 Microsoft 335 Email: mbj@microsoft.com 336 URI: http://self-issued.info/