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]