Network Working Group J. Schaad Internet-Draft Soaring Hawk Consulting Intended status: Informational June 23, 2012 Expires: December 25, 2012 JOSE Serialization Proposal for Multiple People draft-schaad-jose-serialize-00 Abstract This is a fast proposal for doing serialization of JOSE signature, authentication and encryption formats. Status of this Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on December 25, 2012. Copyright Notice Copyright (c) 2012 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Schaad Expires December 25, 2012 [Page 1] Internet-Draft JOSE Serialization June 2012 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Constraints and Design Issues . . . . . . . . . . . . . . 3 2. Serialization Formats . . . . . . . . . . . . . . . . . . . . 4 2.1. JSON Serialization . . . . . . . . . . . . . . . . . . . . 4 2.2. String Serialization . . . . . . . . . . . . . . . . . . . 4 3. Header JSON construction . . . . . . . . . . . . . . . . . . . 6 4. Canonicalization . . . . . . . . . . . . . . . . . . . . . . . 7 5. Signature Processing Steps . . . . . . . . . . . . . . . . . . 8 5.1. Signature Creation . . . . . . . . . . . . . . . . . . . . 8 6. Authentication Processing Steps . . . . . . . . . . . . . . . 9 6.1. Authentication Creation . . . . . . . . . . . . . . . . . 9 7. Encryption Processing Steps . . . . . . . . . . . . . . . . . 10 7.1. Encryption Creation . . . . . . . . . . . . . . . . . . . 10 8. Security Considerations . . . . . . . . . . . . . . . . . . . 11 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13 10.1. Normative References . . . . . . . . . . . . . . . . . . . 13 10.2. Informative References . . . . . . . . . . . . . . . . . . 13 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 14 Schaad Expires December 25, 2012 [Page 2] Internet-Draft JOSE Serialization June 2012 1. Introduction This is a simple fast proposal for doing serialization of JOSE signature, authentication and encryption formats. The proposal is setup to allow for multiple signatures or recipients to be created. 1.1. Constraints and Design Issues This is what controlled the format. 1. Minimal changes to the other JOSE documents. This is not to be interpreted as an endorsement of those documents but instead is to reduce the current set of arguments to a minimum. 2. Assume that when creating a signature operation, all signatures are to be applied at one time. If additional signatures are to be added it will be done as a nested rather than parallel signature. This avoids the issues of [RFC6211] which was designed to prevent removal of parallel signatures. Since all of the parallel signature information is signed, this cannot be done without breaking all of the signatures. 3. Assume that when doing an authenticated or encrypted operation, all recipients will be defined at the time that the message is created. If new recipients are to be added in the future, then a new authentication value will need to be created. 4. Long field names are used for the purpose of clarity. If adopted, it is assumed that shorter field names will be used. Schaad Expires December 25, 2012 [Page 3] Internet-Draft JOSE Serialization June 2012 2. Serialization Formats This document describes both a version that is encoded as a JSON object and also a simple string. 2.1. JSON Serialization The JSON serialization format is a JSON object the following fields: Header has a string value that contains the base64 encoded header for the JSON security. The header is either a single entity or a multiple entity header value. This element is REQUIRED. Content has a string value that contains the base64 encoded content value. This element is OPTIONAL. If this element is present then the ContentURI element MUST be absent. ContentURI has a URI for the location of the content. This element is OPTIONAL. If this element is present then the Content element MUST be absent. Signatures contains the signature value(s) associated with the header. The element is either a single string or an array of strings. The string value(s) contain the base64 encoded signature value. This element is OPTIONAL. It MUST be present if a signature operation has been done. MAC has a string value that contains the base64 encoded message authentication value. This element is OPTIONAL. It MUST be present if an authentication or AEAD encryption operation has been done. 2.2. String Serialization The simple string serialization matches the current serialization method. A string is constructed by concatenating the following items: 1. The Header value from the JSON serialization. 2. A period character. 3. The Content value from the JSON serialization. This element MAY be omitted if the content is location known. 4. A period character. Schaad Expires December 25, 2012 [Page 4] Internet-Draft JOSE Serialization June 2012 5. Either the Signatures or MAC value from the JSON serialization. Schaad Expires December 25, 2012 [Page 5] Internet-Draft JOSE Serialization June 2012 3. Header JSON construction The header consists of either a single header object or an array of header objects. If it is a single header, then object is the same as in the current documents. If the header is an array of objects The JSON header structure consists of the field headers which is an array of objects. Each of the objects is a SJON header structure from the current documents. When doing either encryption or authentication, there is one additional new field which is placed in the current set of header fields. wrappedKey is an OPTIONAL string element. The value is the base64 encoded wrapped CMK. The CMK is then used either as the CEK for encryption or the MAC key for authentication. It is RECOMMENDED that this value be used for authentication rather than directly using a pre-shared secret. For encryption this key replaces the second field in the simple serialization. For authentication this is a new element. When a sender creates a header JSON string, the following rules apply: 1. The string produce MUST be a well formed JSON string. 2. The string MUST NOT have any leading or trailing whitespace. 3. For every name-value pair, there MUST NOT be another name-value pair with the same name in the same lexical context. 4. The canonicalization algorithm in Section 4 SHOULD be applied to the string. When a recipient parses the header JSON string, the following rules apply: 1. There MUST be no leading or trailing whitespace characters. 2. Every character in the string MUST be consumed during parsing. 3. Every name in every lexical context MUST be unique. If any of these rules fail, then processing of the header MUST fail. Schaad Expires December 25, 2012 [Page 6] Internet-Draft JOSE Serialization June 2012 4. Canonicalization This canonicalization algorithm is designed for compactness of representation. This algorithm does not have the same purpose as canonicalization algorithms in the XML Digital Signature world where it is applied by both the sender and the recipient to produce a binary stream for hashing. The canonicalization algorithm consists of applying the following rules: 1. Whitespace preceding and following the brace characters is removed. 2. Whitespace preceding and following the colon character is removed. 3. Whitespace preceding the comma character is removed. 4. Whitespace is collapsed into a single space character. The preceding rules apply only in the syntax space, it does not apply to values. Schaad Expires December 25, 2012 [Page 7] Internet-Draft JOSE Serialization June 2012 5. Signature Processing Steps 5.1. Signature Creation The following steps are descriptive rather than proscriptive. Any other processing that produces the same result is acceptable. 1. Create the header object containing all of the desired and required parameters. 2. Serialize the header to an array of bytes using the UTF8 Encoding. 3. Hash the binary version of the header 4. Apply the Base64URL encoding to the binary version of the header. 5. Create the content to be signed. If the content is to be represented as in JSON , then the object is serialized to a byte array using the UTF8 Encoding. 6. Hash the content. 7. Apply the base64URL encoding to the content. 8. Compute the signature(s). 9. If there is a single object, then base64URL encode the signature value. If there are multiple signatures then create an object with the array of signature values, serialize it to a binary stream and base64URL encode the resulting binary stream. 10. Apply the appropriate serialization process. Schaad Expires December 25, 2012 [Page 8] Internet-Draft JOSE Serialization June 2012 6. Authentication Processing Steps 6.1. Authentication Creation The following steps are descriptive rather than proscriptive. Any other processing that produces the same result is acceptable. 1. Create the header object containing all of the desired and required parameters. A. Create a per message key to be used in the authentication process. B. For each recipient - wrap the key by a unique key for the recipient and identify which key is to be used for unwrapping the per message key. C. In some circumstances (one recipient and transient key) a shared key can be identified and used as the per message key. 2. Serialize the header to an array of bytes using the UTF8 Encoding. 3. MAC the binary version of the header 4. Apply the Base64URL encoding to the binary version of the header. 5. Create the content to be authenticated. If the content is to be represented as in JSON , then the object is serialized to a byte array using the UTF8 Encoding. 6. MAC the content. 7. Apply the base64URL encoding to the content. 8. Finish computing the MAC value. 9. Base64URL encode the resulting MAC value. (Note there is a single MAC value as there is only one message key.) 10. Apply the appropriate serialization process. Schaad Expires December 25, 2012 [Page 9] Internet-Draft JOSE Serialization June 2012 7. Encryption Processing Steps 7.1. Encryption Creation The following steps are descriptive rather than proscriptive. Any other processing that produces the same result is acceptable. 1. Create the header object containing all of the desired and required parameters. A. Create a per message key to be used in the encryption process. B. For each recipient - wrap the key by a unique key for the recipient and identify which key is to be used for unwrapping the per message key. C. In some circumstances (one recipient and transient key) a shared key can be identified and used as the per message key. 2. Serialize the header to an array of bytes using the UTF8 Encoding. 3. Pass in the header as the auxiliary data to the AEAD algorithm 4. Apply the Base64URL encoding to the binary version of the header. 5. Create the content to be encrypted. If the content is to be represented as in JSON , then the object is serialized to a byte array using the UTF8 Encoding. 6. Encrypt and authenticate the content. 7. Apply the base64URL encoding to the encrypted content. 8. Finish computing the MAC value. 9. Base64URL encode the resulting MAC value. (Note there is a single MAC value as there is only one message key.) 10. Apply the appropriate serialization process. Schaad Expires December 25, 2012 [Page 10] Internet-Draft JOSE Serialization June 2012 8. Security Considerations To be supplied Schaad Expires December 25, 2012 [Page 11] Internet-Draft JOSE Serialization June 2012 9. IANA Considerations No action by IANA is required for this document. Schaad Expires December 25, 2012 [Page 12] Internet-Draft JOSE Serialization June 2012 10. References 10.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. 10.2. Informative References [RFC6211] Schaad, J., "Cryptographic Message Syntax (CMS) Algorithm Identifier Protection Attribute", RFC 6211, April 2011. Schaad Expires December 25, 2012 [Page 13] Internet-Draft JOSE Serialization June 2012 Author's Address Jim Schaad Soaring Hawk Consulting Email: ietf@augustcellars.com Schaad Expires December 25, 2012 [Page 14]