idnits 2.17.1 draft-schaad-jose-serialize-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 == Line 108 has weird spacing: '... Header has a...' == Line 112 has weird spacing: '...Content has a...' == Line 120 has weird spacing: '...natures conta...' == Line 162 has weird spacing: '...ppedKey is an...' == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (June 23, 2012) is 4317 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Unused Reference: 'RFC2119' is defined on line 353, but no explicit reference was found in the text Summary: 0 errors (**), 0 flaws (~~), 7 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Schaad 3 Internet-Draft Soaring Hawk Consulting 4 Intended status: Informational June 23, 2012 5 Expires: December 25, 2012 7 JOSE Serialization Proposal for Multiple People 8 draft-schaad-jose-serialize-00 10 Abstract 12 This is a fast proposal for doing serialization of JOSE signature, 13 authentication and encryption formats. 15 Status of this Memo 17 This Internet-Draft is submitted in full conformance with the 18 provisions of BCP 78 and BCP 79. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF). Note that other groups may also distribute 22 working documents as Internet-Drafts. The list of current Internet- 23 Drafts is at http://datatracker.ietf.org/drafts/current/. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as "work in progress." 30 This Internet-Draft will expire on December 25, 2012. 32 Copyright Notice 34 Copyright (c) 2012 IETF Trust and the persons identified as the 35 document authors. All rights reserved. 37 This document is subject to BCP 78 and the IETF Trust's Legal 38 Provisions Relating to IETF Documents 39 (http://trustee.ietf.org/license-info) in effect on the date of 40 publication of this document. Please review these documents 41 carefully, as they describe your rights and restrictions with respect 42 to this document. Code Components extracted from this document must 43 include Simplified BSD License text as described in Section 4.e of 44 the Trust Legal Provisions and are provided without warranty as 45 described in the Simplified BSD License. 47 Table of Contents 49 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 50 1.1. Constraints and Design Issues . . . . . . . . . . . . . . 3 51 2. Serialization Formats . . . . . . . . . . . . . . . . . . . . 4 52 2.1. JSON Serialization . . . . . . . . . . . . . . . . . . . . 4 53 2.2. String Serialization . . . . . . . . . . . . . . . . . . . 4 54 3. Header JSON construction . . . . . . . . . . . . . . . . . . . 6 55 4. Canonicalization . . . . . . . . . . . . . . . . . . . . . . . 7 56 5. Signature Processing Steps . . . . . . . . . . . . . . . . . . 8 57 5.1. Signature Creation . . . . . . . . . . . . . . . . . . . . 8 58 6. Authentication Processing Steps . . . . . . . . . . . . . . . 9 59 6.1. Authentication Creation . . . . . . . . . . . . . . . . . 9 60 7. Encryption Processing Steps . . . . . . . . . . . . . . . . . 10 61 7.1. Encryption Creation . . . . . . . . . . . . . . . . . . . 10 62 8. Security Considerations . . . . . . . . . . . . . . . . . . . 11 63 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 64 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13 65 10.1. Normative References . . . . . . . . . . . . . . . . . . . 13 66 10.2. Informative References . . . . . . . . . . . . . . . . . . 13 67 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 14 69 1. Introduction 71 This is a simple fast proposal for doing serialization of JOSE 72 signature, authentication and encryption formats. The proposal is 73 setup to allow for multiple signatures or recipients to be created. 75 1.1. Constraints and Design Issues 77 This is what controlled the format. 79 1. Minimal changes to the other JOSE documents. This is not to be 80 interpreted as an endorsement of those documents but instead is 81 to reduce the current set of arguments to a minimum. 83 2. Assume that when creating a signature operation, all signatures 84 are to be applied at one time. If additional signatures are to 85 be added it will be done as a nested rather than parallel 86 signature. This avoids the issues of [RFC6211] which was 87 designed to prevent removal of parallel signatures. Since all of 88 the parallel signature information is signed, this cannot be done 89 without breaking all of the signatures. 91 3. Assume that when doing an authenticated or encrypted operation, 92 all recipients will be defined at the time that the message is 93 created. If new recipients are to be added in the future, then a 94 new authentication value will need to be created. 96 4. Long field names are used for the purpose of clarity. If 97 adopted, it is assumed that shorter field names will be used. 99 2. Serialization Formats 101 This document describes both a version that is encoded as a JSON 102 object and also a simple string. 104 2.1. JSON Serialization 106 The JSON serialization format is a JSON object the following fields: 108 Header has a string value that contains the base64 encoded header 109 for the JSON security. The header is either a single entity or a 110 multiple entity header value. This element is REQUIRED. 112 Content has a string value that contains the base64 encoded content 113 value. This element is OPTIONAL. If this element is present then 114 the ContentURI element MUST be absent. 116 ContentURI has a URI for the location of the content. This element 117 is OPTIONAL. If this element is present then the Content element 118 MUST be absent. 120 Signatures contains the signature value(s) associated with the 121 header. The element is either a single string or an array of 122 strings. The string value(s) contain the base64 encoded signature 123 value. This element is OPTIONAL. It MUST be present if a 124 signature operation has been done. 126 MAC has a string value that contains the base64 encoded message 127 authentication value. This element is OPTIONAL. It MUST be 128 present if an authentication or AEAD encryption operation has been 129 done. 131 2.2. String Serialization 133 The simple string serialization matches the current serialization 134 method. 136 A string is constructed by concatenating the following items: 138 1. The Header value from the JSON serialization. 140 2. A period character. 142 3. The Content value from the JSON serialization. This element MAY 143 be omitted if the content is location known. 145 4. A period character. 147 5. Either the Signatures or MAC value from the JSON serialization. 149 3. Header JSON construction 151 The header consists of either a single header object or an array of 152 header objects. If it is a single header, then object is the same as 153 in the current documents. If the header is an array of objects The 154 JSON header structure consists of the field headers which is an array 155 of objects. Each of the objects is a SJON header structure from the 156 current documents. 158 When doing either encryption or authentication, there is one 159 additional new field which is placed in the current set of header 160 fields. 162 wrappedKey is an OPTIONAL string element. The value is the base64 163 encoded wrapped CMK. The CMK is then used either as the CEK for 164 encryption or the MAC key for authentication. It is RECOMMENDED 165 that this value be used for authentication rather than directly 166 using a pre-shared secret. For encryption this key replaces the 167 second field in the simple serialization. For authentication this 168 is a new element. 170 When a sender creates a header JSON string, the following rules 171 apply: 173 1. The string produce MUST be a well formed JSON string. 175 2. The string MUST NOT have any leading or trailing whitespace. 177 3. For every name-value pair, there MUST NOT be another name-value 178 pair with the same name in the same lexical context. 180 4. The canonicalization algorithm in Section 4 SHOULD be applied to 181 the string. 183 When a recipient parses the header JSON string, the following rules 184 apply: 186 1. There MUST be no leading or trailing whitespace characters. 188 2. Every character in the string MUST be consumed during parsing. 190 3. Every name in every lexical context MUST be unique. 192 If any of these rules fail, then processing of the header MUST fail. 194 4. Canonicalization 196 This canonicalization algorithm is designed for compactness of 197 representation. This algorithm does not have the same purpose as 198 canonicalization algorithms in the XML Digital Signature world where 199 it is applied by both the sender and the recipient to produce a 200 binary stream for hashing. 202 The canonicalization algorithm consists of applying the following 203 rules: 205 1. Whitespace preceding and following the brace characters is 206 removed. 208 2. Whitespace preceding and following the colon character is 209 removed. 211 3. Whitespace preceding the comma character is removed. 213 4. Whitespace is collapsed into a single space character. 215 The preceding rules apply only in the syntax space, it does not apply 216 to values. 218 5. Signature Processing Steps 220 5.1. Signature Creation 222 The following steps are descriptive rather than proscriptive. Any 223 other processing that produces the same result is acceptable. 225 1. Create the header object containing all of the desired and 226 required parameters. 228 2. Serialize the header to an array of bytes using the UTF8 229 Encoding. 231 3. Hash the binary version of the header 233 4. Apply the Base64URL encoding to the binary version of the 234 header. 236 5. Create the content to be signed. If the content is to be 237 represented as in JSON , then the object is serialized to a byte 238 array using the UTF8 Encoding. 240 6. Hash the content. 242 7. Apply the base64URL encoding to the content. 244 8. Compute the signature(s). 246 9. If there is a single object, then base64URL encode the signature 247 value. If there are multiple signatures then create an object 248 with the array of signature values, serialize it to a binary 249 stream and base64URL encode the resulting binary stream. 251 10. Apply the appropriate serialization process. 253 6. Authentication Processing Steps 255 6.1. Authentication Creation 257 The following steps are descriptive rather than proscriptive. Any 258 other processing that produces the same result is acceptable. 260 1. Create the header object containing all of the desired and 261 required parameters. 263 A. Create a per message key to be used in the authentication 264 process. 266 B. For each recipient - wrap the key by a unique key for the 267 recipient and identify which key is to be used for 268 unwrapping the per message key. 270 C. In some circumstances (one recipient and transient key) a 271 shared key can be identified and used as the per message 272 key. 274 2. Serialize the header to an array of bytes using the UTF8 275 Encoding. 277 3. MAC the binary version of the header 279 4. Apply the Base64URL encoding to the binary version of the 280 header. 282 5. Create the content to be authenticated. If the content is to be 283 represented as in JSON , then the object is serialized to a byte 284 array using the UTF8 Encoding. 286 6. MAC the content. 288 7. Apply the base64URL encoding to the content. 290 8. Finish computing the MAC value. 292 9. Base64URL encode the resulting MAC value. (Note there is a 293 single MAC value as there is only one message key.) 295 10. Apply the appropriate serialization process. 297 7. Encryption Processing Steps 299 7.1. Encryption Creation 301 The following steps are descriptive rather than proscriptive. Any 302 other processing that produces the same result is acceptable. 304 1. Create the header object containing all of the desired and 305 required parameters. 307 A. Create a per message key to be used in the encryption 308 process. 310 B. For each recipient - wrap the key by a unique key for the 311 recipient and identify which key is to be used for 312 unwrapping the per message key. 314 C. In some circumstances (one recipient and transient key) a 315 shared key can be identified and used as the per message 316 key. 318 2. Serialize the header to an array of bytes using the UTF8 319 Encoding. 321 3. Pass in the header as the auxiliary data to the AEAD algorithm 323 4. Apply the Base64URL encoding to the binary version of the 324 header. 326 5. Create the content to be encrypted. If the content is to be 327 represented as in JSON , then the object is serialized to a byte 328 array using the UTF8 Encoding. 330 6. Encrypt and authenticate the content. 332 7. Apply the base64URL encoding to the encrypted content. 334 8. Finish computing the MAC value. 336 9. Base64URL encode the resulting MAC value. (Note there is a 337 single MAC value as there is only one message key.) 339 10. Apply the appropriate serialization process. 341 8. Security Considerations 343 To be supplied 345 9. IANA Considerations 347 No action by IANA is required for this document. 349 10. References 351 10.1. Normative References 353 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 354 Requirement Levels", BCP 14, RFC 2119, March 1997. 356 10.2. Informative References 358 [RFC6211] Schaad, J., "Cryptographic Message Syntax (CMS) Algorithm 359 Identifier Protection Attribute", RFC 6211, April 2011. 361 Author's Address 363 Jim Schaad 364 Soaring Hawk Consulting 366 Email: ietf@augustcellars.com