idnits 2.17.1 draft-jones-json-web-encryption-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 : ---------------------------------------------------------------------------- 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 (March 12, 2012) is 4428 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 March 12, 2012 5 Expires: September 13, 2012 7 JSON Web Encryption JSON Serialization (JWE-JS) 8 draft-jones-json-web-encryption-json-serialization-01 10 Abstract 12 The JSON Web Encryption JSON Serialization (JWE-JS) is a means of 13 representing encrypted content using JSON data structures. This 14 specification describes a means of representing secured content as a 15 JSON data object (as opposed to the JWE specification, which uses a 16 compact serialization with a URL-safe representation). It enables 17 the same content to be encrypted to multiple parties (unlike JWE). 18 Cryptographic algorithms and identifiers used with this specification 19 are enumerated in the separate JSON Web Algorithms (JWA) 20 specification. The JSON Serialization for related digital signature 21 and HMAC functionality is described in the separate JSON Web 22 Signature JSON Serialization (JWS-JS) specification. 24 Requirements Language 26 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 27 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 28 document are to be interpreted as described in RFC 2119 [RFC2119]. 30 Status of this Memo 32 This Internet-Draft is submitted in full conformance with the 33 provisions of BCP 78 and BCP 79. 35 Internet-Drafts are working documents of the Internet Engineering 36 Task Force (IETF). Note that other groups may also distribute 37 working documents as Internet-Drafts. The list of current Internet- 38 Drafts is at http://datatracker.ietf.org/drafts/current/. 40 Internet-Drafts are draft documents valid for a maximum of six months 41 and may be updated, replaced, or obsoleted by other documents at any 42 time. It is inappropriate to use Internet-Drafts as reference 43 material or to cite them other than as "work in progress." 45 This Internet-Draft will expire on September 13, 2012. 47 Copyright Notice 48 Copyright (c) 2012 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (http://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 64 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . 3 65 3. JSON Serialization . . . . . . . . . . . . . . . . . . . . . . 3 66 4. Example JWE-JS . . . . . . . . . . . . . . . . . . . . . . . . 4 67 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 5 68 6. Security Considerations . . . . . . . . . . . . . . . . . . . . 5 69 7. Open Issues and Things To Be Done (TBD) . . . . . . . . . . . . 6 70 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 6 71 8.1. Normative References . . . . . . . . . . . . . . . . . . . 6 72 8.2. Informative References . . . . . . . . . . . . . . . . . . 6 73 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . . 6 74 Appendix B. Document History . . . . . . . . . . . . . . . . . . . 7 75 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 7 77 1. Introduction 79 The JSON Web Encryption JSON Serialization (JWE-JS) is a format for 80 representing encrypted content as a JSON RFC 4627 [RFC4627] object. 81 It enables the same content to be encrypted to multiple parties 82 (unlike JWE [JWE].) The encryption mechanisms are independent of the 83 type of content being encrypted. Cryptographic algorithms and 84 identifiers used with this specification are enumerated in the 85 separate JSON Web Algorithms (JWA) [JWA] specification. The JSON 86 Serialization for related digital signature and HMAC functionality is 87 described in the separate JSON Web Signature JSON Serialization 88 (JWS-JS) [JWS-JS] specification. 90 2. Terminology 92 This specification uses the same terminology as the JSON Web 93 Encryption (JWE) [JWE] specification. 95 3. JSON Serialization 97 The JSON Serialization represents encrypted content as a JSON object 98 with members for each of four constituent parts: a "headers" member 99 whose value is a non-empty array of Encoded JWE Header values, an 100 "encrypted_keys" member whose value is a non-empty array of Encoded 101 JWE Encrypted Key values, a "ciphertext" member whose value is an 102 Encoded JWE Ciphertext value, and an "integrity_values" member whose 103 value is a non-empty array of Encoded JWE Integrity Value values. 104 The number of elements in each of the arrays MUST be the same. 106 Unlike the compact serialization used by JWEs, content using the JSON 107 Serialization MAY be encrypted to more than one recipient. Each 108 recipient requires: 110 o a JWE Header value specifying the cryptographic parameters used to 111 encrypt the JWE Encrypted Key to that recipient and the parameters 112 used to encrypt the plaintext to produce the JWE Ciphertext; these 113 values are represented as Encoded JWE Header values that are 114 elements of the non-empty array contained in the "headers" member. 116 o a JWE Encrypted Key value; these values are represented as Encoded 117 JWE Encrypted Key values that are corresponding elements of the 118 non-empty array contained in the "encrypted_keys" member. 120 o a JWE Integrity Value that ensures the integrity of the Ciphertext 121 and the parameters used to create it; these values are represented 122 as Encoded JWE Integrity Value values that are corresponding 123 elements of the non-empty array contained in the 124 "integrity_values" member. 126 Therefore, the syntax is: 127 {"headers":["
",...,"
"], 128 "encrypted_keys":["",...,""], 129 "ciphertext":"", 130 "integrity_values":["",...,""] 131 } 133 The contents of the Encoded JWE Header, Encoded JWE Encrypted Key, 134 Encoded JWE Ciphertext, and Encoded JWE Integrity Value values are 135 exactly as specified in JSON Web Encryption (JWE) [JWE]. They are 136 interpreted and validated in the same manner, with each corresponding 137 "headers", "encrypted_keys", and "integrity_values" value being 138 created or validated together. The arrays MUST have the same number 139 of elements. 141 The i'th JWE Encrypted Key value and the i'th JWE Integrity Value are 142 computed using the parameters of i'th JWE Header value in the same 143 manner described in the JWE specification. This has the desirable 144 result that each Encoded JWE Encrypted Key value in the 145 "encrypted_keys" array and each Encoded JWE Integrity Value in the 146 "integrity_values" array are identical to the values that would have 147 been computed for the same header and payload in a JWE, as is the JWE 148 Ciphertext value. 150 All recipients use the same JWE Ciphertext value, resulting in 151 potentially significant space savings if the message is large. 152 Therefore, all header parameters that specify the treatment of the 153 JWE Ciphertext value MUST be the same for all recipients. In 154 particular, this means that the "enc" (encryption method) header 155 parameter value in the JWE Header for each recipient MUST be the 156 same, as MUST be the "iv" (initialization vector) value (when 157 required for the algorithm). 159 4. Example JWE-JS 161 This section contains an example using the JWE JSON Serialization. 162 This example demonstrates the capability for encrypting the same 163 plaintext to multiple recipients. 165 Two recipients are present in this example: the first using the RSA- 166 PKCS1_1.5 algorithm to produce the JWE Encrypted Key and the second 167 using the ECDH-ES algorithm to produce the JWE Encrypted Key. The 168 Plaintext is encrypted using the AES-256-CBC algorithm to produce the 169 JWE Ciphertext. The two Decoded JWE Header Segments used are: 171 {"alg":"RSA1_5", 172 "enc":"A256CBC", 173 "int":"HS256", 174 "iv":"Mz-mW_4JHfg", 175 "x5t":"7noOPq-hJ1_hCnvWh6IeYI2w9Q0"} 177 and: 178 {"alg":"ECDH-ES", 179 "enc":"A256CBC", 180 "epk":{ 181 "alg":"EC", 182 "crv":"P-256", 183 "x":"235RT7iKTI3KWvS4_mIwUhX6OC_X2I-bsOpS5w7MGA4", 184 "y":"ZSv0dtvXs4o2XsIVhFzgiMTSg9uSsytaOvC-XRtfoIM"}, 185 "jku":"https://example.com/public_key.jwk"} 187 The complete JSON Web Encryption JSON Serialization (JWE-JS) for 188 these values is as follows (with line breaks for display purposes 189 only): 190 {"headers":[ 191 "eyJhbGciOiJSU0ExXzUiLA0KICJlbmMiOiJBMjU2Q0JDIiwNCiAiaW50IjoiS 192 FMyNTYiLA0KICJpdiI6Ik16LW1XXzRKSGZnIiwNCiAieDV0IjoiN25vT1BxLWhKM 193 V9oQ252V2g2SWVZSTJ3OVEwIn0", 194 "eyJhbGciOiJFQ0RILUVTIiwNCiAiZW5jIjoiQTI1NkNCQyIsDQogImVwayI6e 195 w0KICAiYWxnIjoiRUMiLA0KICAiY3J2IjoiUC0yNTYiLA0KICAieCI6IjIzNVJUN 196 2lLVEkzS1d2UzRfbUl3VWhYNk9DX1gySS1ic09wUzV3N01HQTQiLA0KICAieSI6I 197 lpTdjBkdHZYczRvMlhzSVZoRnpnaU1UU2c5dVNzeXRhT3ZDLVhSdGZvSU0ifSwNC 198 iAiamt1IjoiaHR0cHM6Ly9leGFtcGxlLmNvbS9wdWJsaWNfa2V5Lmp3ayJ9"], 199 "encrypted_keys":[ 200 "TBD_encrypted_key_1_value_TBD", 201 "TBD_encrypted_key_2_value_TBD"], 202 "ciphertext":"TBD_ciphertext_value_TBD", 203 "integrity_values":[ 204 "TBD_integrity_1_value_TBD", 205 "TBD_integrity_2_value_TBD"] 206 } 208 TBD: Finish this example. 210 5. IANA Considerations 212 This specification makes no requests of IANA. 214 6. Security Considerations 216 The security considerations for this specification are the same as 217 those for the JSON Web Encryption (JWE) [JWE] specification. 219 7. Open Issues and Things To Be Done (TBD) 221 The following items remain to be done in this draft: 223 o Complete the example. 225 o Track changes that occur in the JWE spec. 227 8. References 229 8.1. Normative References 231 [JWA] Jones, M., "JSON Web Algorithms (JWA)", March 2012. 233 [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web 234 Encryption (JWE)", March 2012. 236 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 237 Requirement Levels", BCP 14, RFC 2119, March 1997. 239 [RFC4627] Crockford, D., "The application/json Media Type for 240 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 242 8.2. Informative References 244 [I-D.rescorla-jsms] 245 Rescorla, E. and J. Hildebrand, "JavaScript Message 246 Security Format", draft-rescorla-jsms-00 (work in 247 progress), March 2011. 249 [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple 250 Encryption", September 2010. 252 [JWS-JS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 253 Signature JSON Serialization (JWS-JS)", March 2012. 255 Appendix A. Acknowledgements 257 JSON serializations for encrypted content were previously explored by 258 JSON Simple Encryption [JSE] and JavaScript Message Security Format 259 [I-D.rescorla-jsms]. 261 Appendix B. Document History 263 -01 265 o Tracked changes between JOSE JWE draft -00 and -01, which added an 266 integrity check for non-AEAD algorithms. 268 -00 270 o Created the initial version incorporating JOSE working group input 271 and drawing from the JSON Serialization previously proposed in 272 draft-jones-json-web-token-01. 274 Author's Address 276 Michael B. Jones 277 Microsoft 279 Email: mbj@microsoft.com 280 URI: http://self-issued.info/