idnits 2.17.1 draft-jones-jose-jwe-json-serialization-01.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 are 2 instances of too long lines in the document, the longest one being 8 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 (July 16, 2012) is 4295 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: 2 errors (**), 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 July 16, 2012 5 Expires: January 17, 2013 7 JSON Web Encryption JSON Serialization (JWE-JS) 8 draft-jones-jose-jwe-json-serialization-01 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 January 17, 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. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . . 6 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 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 members for each of four constituent parts: a "headers" member 103 whose value is a non-empty array of Encoded JWE Header values, an 104 "encrypted_keys" member whose value is a non-empty array of Encoded 105 JWE Encrypted Key values, a "ciphertext" member whose value is an 106 Encoded JWE Ciphertext value, and an "integrity_values" member whose 107 value is a non-empty array of Encoded JWE Integrity Value values. 108 The number of elements in each of the arrays MUST be the same. 110 Unlike the compact serialization used by JWEs, content using the JSON 111 Serialization MAY be encrypted to more than one recipient. Each 112 recipient requires: 114 o a JWE Header value specifying the cryptographic parameters used to 115 encrypt the JWE Encrypted Key to that recipient and the parameters 116 used to encrypt the plaintext to produce the JWE Ciphertext; these 117 values are represented as Encoded JWE Header values that are 118 elements of the non-empty array contained in the "headers" member. 120 o a JWE Encrypted Key value; these values are represented as Encoded 121 JWE Encrypted Key values that are corresponding elements of the 122 non-empty array contained in the "encrypted_keys" member. 124 o a JWE Integrity Value that ensures the integrity of the Ciphertext 125 and the parameters used to create it; these values are represented 126 as Encoded JWE Integrity Value values that are corresponding 127 elements of the non-empty array contained in the 128 "integrity_values" member. 130 Therefore, the syntax is: 132 {"headers":["
",...,"
"], 133 "encrypted_keys":["",...,""], 134 "ciphertext":"", 135 "integrity_values":["",...,""] 136 } 138 The contents of the Encoded JWE Header, Encoded JWE Encrypted Key, 139 Encoded JWE Ciphertext, and Encoded JWE Integrity Value values are 140 exactly as specified in JSON Web Encryption (JWE) [JWE]. They are 141 interpreted and validated in the same manner, with each corresponding 142 "headers", "encrypted_keys", and "integrity_values" value being 143 created or validated together. The arrays MUST have the same number 144 of elements. 146 The i'th JWE Encrypted Key value and the i'th JWE Integrity Value are 147 computed using the parameters of i'th JWE Header value in the same 148 manner described in the JWE specification. This has the desirable 149 result that each Encoded JWE Encrypted Key value in the 150 "encrypted_keys" array and each Encoded JWE Integrity Value in the 151 "integrity_values" array are identical to the values that would have 152 been computed for the same header and payload in a JWE, as is the JWE 153 Ciphertext value. 155 All recipients use the same JWE Ciphertext value, resulting in 156 potentially significant space savings if the message is large. 157 Therefore, all header parameters that specify the treatment of the 158 JWE Ciphertext value MUST be the same for all recipients. In 159 particular, this means that the "enc" (encryption method) header 160 parameter value in the JWE Header for each recipient MUST be the 161 same, as MUST be the "iv" (initialization vector) value, the "int" 162 (integrity algorithm) value, and the "kdf" (key derivation function) 163 value, when present. 165 4. Example JWE-JS 167 This section contains an example using the JWE JSON Serialization. 168 This example demonstrates the capability for encrypting the same 169 plaintext to multiple recipients. 171 Two recipients are present in this example: the first using the 172 RSAES-PKCS1-V1_5 algorithm to encrypt the Content Master Key (CMK) 173 and the second using RSAES OAEP to encrypt the CMK. The Plaintext is 174 encrypted using the AES CBC algorithm and the same block encryption 175 parameters to produce the common JWE Ciphertext value. The two 176 Decoded JWE Header Segments used are: 178 {"alg":"RSA1_5","enc":"A128CBC","int":"HS256","iv":"AxY8DCtDaGlsbGljb3RoZQ"} 180 and: 182 {"alg":"RSA-OAEP","enc":"A128CBC","int":"HS256","iv":"AxY8DCtDaGlsbGljb3RoZQ"} 184 The keys used for the first recipient are the same as those in 185 Appendix A.2 of [JWE], as is the plaintext used. The asymmetric 186 encryption key used for the second recipient is the same as that used 187 in Appendix A.1 of [JWE]; the block encryption keys and parameters 188 for the second recipient are the same as those for the first 189 recipient (which must be the case, since the ciphertext is shared). 191 The complete JSON Web Encryption JSON Serialization (JWE-JS) for 192 these values is as follows (with line breaks for display purposes 193 only): 195 {"headers":[ 196 "eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDIiwiaW50IjoiSFMyNTYiLCJp 197 diI6IkF4WThEQ3REYUdsc2JHbGpiM1JvWlEifQ", 198 "eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkExMjhDQkMiLCJpbnQiOiJIUzI1NiIs 199 Iml2IjoiQXhZOERDdERhR2xzYkdsamIzUm9aUSJ9"], 200 "encrypted_keys":[ 201 "IPI_z172hSWHMFgED8EG9DM6hIXU_6NaO1DImCn0vNeuoBq847Sl6qw_GHSYHJUQ 202 XtXJq7S_CxWVrI82wjrOyaQca5tLZRZc45BfKHeqByThKI261QevEK56SyAwwXfK 203 KZjSvkQ5dwTFSgfy76rMSUvVynHYEhdCatBF9HWTAiXPx7hgZixG1FeP_QCmOylz 204 2VClVyYFCbjKREOwBFf-puNYfO75S3LNlJUtTsGGQL2oTKpMsEiUTdefkje91VX9 205 h8g7908lFsggbjV7NicJsufuXxnTj1fcWIrRDeNIOmakiPEODi0gTSz0ou-W-LWK 206 -3T1zYlOIiIKBjsExQKZ-w", 207 "gyhQHQYGyPZQP21Oxd6TdJjrmNkals3Jin2631_eaW-8tPEZxjeNA1lJD7gi2tAQ 208 X9ERZkbD8-9-8Gq9HkpJIhINX4TkqmCynmT8kQfjiv5t8KuTI_OjhD-I0CfvWs3T 209 7yf2W6_vQcs1ezsapKPGj92i6Z1xpWgtDuK5YwU3PLAEfNeAgBK0fM9x9DkIuhBN 210 7O9LWRtP6FnYKaygc5-tzR_O9nTJ0u4ImsBPGaHHQEfvzMBtQgAPQCdkDiITxSdJ 211 OdvBQVmg7uGKOybF42R-gzP63lxAqiYmp6DVPlPYydIEB2lCZxGUJIsmEM0qwXt1 212 GEmj_aYGhCUrkPSidvE6Ag"], 213 "ciphertext":"_Z_djlIoC4MDSCKireWS2beti4Q6iSG2UjFujQvdz-_PQdUcFNkO 214 ulegD6BgjgdFLjeB4HHOO7UHvP8PEDu0a0sA2a_-CI0w2YQQ2QQe35M", 215 "integrity_values":[ 216 "c41k4T4eAgCCt63m8ZNmiOinMciFFypOFpvid7i6D0k", 217 "NX62w-GLPhXVJuQxXnbWrBKLkt9j14IULcMdJ9kzeF0"] 218 } 220 5. IANA Considerations 222 This specification makes no requests of IANA. 224 6. Security Considerations 226 The security considerations for this specification are the same as 227 those for the JSON Web Encryption (JWE) [JWE] specification. 229 7. Open Issues 231 [[ to be removed by the RFC editor before publication as an RFC ]] 233 The following items remain to be considered or done in this draft: 235 o Track changes that occur in the JWE spec. 237 8. References 238 8.1. Normative References 240 [JWA] Jones, M., "JSON Web Algorithms (JWA)", July 2012. 242 [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web 243 Encryption (JWE)", July 2012. 245 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 246 Requirement Levels", BCP 14, RFC 2119, March 1997. 248 [RFC4627] Crockford, D., "The application/json Media Type for 249 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 251 8.2. Informative References 253 [I-D.rescorla-jsms] 254 Rescorla, E. and J. Hildebrand, "JavaScript Message 255 Security Format", draft-rescorla-jsms-00 (work in 256 progress), March 2011. 258 [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple 259 Encryption", September 2010. 261 [JWS-JS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 262 Signature JSON Serialization (JWS-JS)", July 2012. 264 Appendix A. Acknowledgements 266 JSON serializations for encrypted content were previously explored by 267 JSON Simple Encryption [JSE] and JavaScript Message Security Format 268 [I-D.rescorla-jsms]. 270 Appendix B. Document History 272 [[ to be removed by the RFC editor before publication as an RFC ]] 274 -01 276 o Added a complete JWE-JS example. 278 o Generalized language to refer to Message Authentication Codes 279 (MACs) rather than Hash-based Message Authentication Codes 280 (HMACs). 282 -00 283 o Renamed draft-jones-json-web-encryption-json-serialization to 284 draft-jones-jose-jwe-json-serialization to have "jose" be in the 285 document name so it can be included in the Related Documents list 286 at http://datatracker.ietf.org/wg/jose/. No normative changes. 288 draft-jones-json-web-encryption-json-serialization-02 290 o Updated examples to track updated algorithm properties in the JWA 291 spec. 293 o Tracked editorial changes made to the JWE spec. 295 draft-jones-json-web-encryption-json-serialization-01 297 o Tracked changes between JOSE JWE draft -00 and -01, which added an 298 integrity check for non-AEAD algorithms. 300 draft-jones-json-web-encryption-json-serialization-00 302 o Created the initial version incorporating JOSE working group input 303 and drawing from the JSON Serialization previously proposed in 304 draft-jones-json-web-token-01. 306 Author's Address 308 Michael B. Jones 309 Microsoft 311 Email: mbj@microsoft.com 312 URI: http://self-issued.info/