| Network Working Group | J.H.M. Manger |
| Internet-Draft | Telstra |
| Intended status: Standards Track | June 11, 2012 |
| Expires: December 11, 2012 |
JSON Web Security Message Format
draft-manger-jose-jwsec-00.txt
This document describes a cryptographic message format based on JavaScript Object Notation (JSON) and base-64 encodings to be easy for web applications to generate and process. Signed, encrypted, signed-then-encrypted, and unprotected messages are supported using symmetric and/or asymmetric keys.
Please discuss this document on the jose@ietf.org mailing list.
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 11, 2012.
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.
This document may contain material from IETF Documents or IETF Contributions published or made publicly available before November 10, 2008. The person(s) controlling the copyright in some of this material may not have granted the IETF Trust the right to allow modifications of such material outside the IETF Standards Process. Without obtaining an adequate license from the person(s) controlling the copyright in such materials, this document may not be modified outside the IETF Standards Process, and derivative works of it may not be created outside the IETF Standards Process, except to format it for publication as an RFC or to translate it into languages other than English.
Many applications require the ability to send cryptographically secured messages (encrypted, digitally signed, etc.). While the IETF has defined a number of formats for such messages -- such as Cryptographic Message Syntax (CMS) [RFC5652] -- those formats are widely viewed as being excessively complicated for the demands of many web applications, which typically only need the ability to secure simple messages. In addition, existing formats use encoding mechanisms that are not congenial for web applications, such as Abstract Syntax Notation (ASN.1) Distinguished Encoding Rules (DER). This presents an obstacle to the deployment of strong security by such applications.
This document describes a new cryptographic message format, nicknamed JWsec, intended to meet the needs of the web environment. JWsec uses JavaScript Object Notation (JSON) [RFC4627] and base64url encodings (without padding) [RFC4648] section 5. JWsec is loosly modelled on some of the basic functionality of CMS, but omits many CMS modes in the interests of simplicity.
A JWsec message can protect any array of bytes, though it is more suited to protecting kilobytes than gigabytes. A JWsec message can provide data origin authenticity and/or confidentiality for the data. It can compress the data. A JWsec message can also carry the data with no cryptographic protection, which enables protocols to specify JWsec for fields that do not require security in all circumstances.
After providing some example JWsec messages, this document describes the processing model, the message syntax, and then three modes of protection: unprotected; signed; and encrypted. The JSON elements that can appear in a JWsec message header are summarized in section 7.
An initial set of algorithms that a JWsec message can use for signing, encrypting, and compressing are specified separately in JSON Web Security Message Algorithms [ALGS]. That document also establishes a registry for listing further algorithms.
The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].
Requirements are specified for originators who create JWsec messages and recipients who receive them. Requirements stated for messages apply to originators who create them.
Long base64url encodings are wrapped over multiple lines only for display purposes. The real values do not include line breaks.
This simple JWsec message consists of 3 dot-separated components:
U.e30.SGVsbG8sIFdvcmxkIQ
The initial letter "U" indicated that this is an unprotected JWsec message. The other components are base64url encodings (without padding). The second component decodes to a JSON object (the header), in this case an empty JSON object {} indicating that no processing (eg no compression) of the data has occured. The last component decodes to the actual data: 13 bytes, which is the UTF-8-encoded 13-character string "Hello, World!".
The next example is a signed JWsec message since it starts with "S".
S.eyAic2lnIjoiSFMyNTYiLCAia2lkIjoiRmViMTJrMSIgfQ. SGVsbG8sIFdvcmxkIQ. MDEyMzQ-FIX-OWFiY2RlZj_xMjM0NTY-ODlhYmNkZWY
The header (the JSON object decoded from the second dot-separated component) is:
{ "sig":"HS256", "kid":"Feb12k1" }
The next component decodes to the data "Hello, World!". The final component decodes to a 256-bit MAC (message authentication code) calculated over the preceeding portion of the JWsec message. In this instance the MAC uses the HS256 algorithm (HMAC with SHA-256) with the secret key identified by the label "Feb12k1", and covers the 71 initial characters of the message (UTF-8 encoded into 71 bytes).
MDEyMzQ-FI...ZWY = B64(HMAC(S.eyAi...IgfQ.SGVsbG8sIFdvcmxkIQ))
The following example is a signed-then-encrypted JWsec message.
e.ew0KICJhbGc-FIX-U0ExXzUiLA0KICJraWQiOiJodHRwOi8vZX hhbXBsZS5vcm-FIX-ibGljLmp3ayNrMiIsDQogImVuYyI6IkEyN TZHQ00iLA0KI-FIX-AiOiJERUYiLA0KICJlbnYiOnRydWUNCn0. [2048-bit RSA BT2 value]. [96-bit IV][ciphertext][128-bit tag]
The decoded header is:
{
"kmg":"RSA1_5",
"kid":"http://example.org/public.jwk#k2",
"enc":"A256GCM",
"zip":"DEF",
}
The third component is a random 256-bit AES key encrypted with a 2048-bit RSA public key, as per the RSA1_5 key transport algorithm. The fourth component is the concatenation of a 96-bit IV, the ciphertext, and a 128-bit authentication tag. The ciphertext and tag are calculated using AES in Galois/Counter mode.
After verifying the tag, decrypting the ciphertext, and decompressing with the DEFLATE algorithm, the result is S.eyJzaWciOiJSUzI1... This data is processed as another (inner) JWsec messages.
The initial lowercase "e" on the outer JWsec messages indicates the encryption wraps another JWsec message. The initial "S" on the inner JWsec message indicates signed data. Together they show that this is a signed-then-encrypted message.
Appendix A has a complete example.
The starting point for creating a JWsec message is the input data, which is a byte array. One or more modes of protection are applied in turn, using algorithms and keys chosen by the message originator. Three modes of protection are specified in this document: unprotected; signed; and encrypted. The resultant JWsec message is a string, using a limited alphabet of 65 characters. To apply multiple modes of protection, the output JWsec message from one mode is UTF-8 encoded to give the input data for the next mode.
-->[unprotected]---
input data | | JWsec message
-------------+->--+->[ signed ]--+->--+--------------->
[byte array] ^ | | | [string]
| -->[ encrypted ]--- |
| |
--------[UTF-8 encode]<------
A JWsec message is a string consisting of dot-separated components. Each component only uses a limited set of 64 characters: A-Z, a-z, 0-9, "-" (hypen-minus), and "_" (low line). This set is sufficient to hold a base64url encoding (without padding), as defined in RFC4648 section 5 "Base 64 Encoding with URL and Filename Safe Alphabet" [RFC4648]. The limited range of characters used in a JWsec message make it suitable to be carried in fields of many web protocols without requiring escaping (eg in an HTTP header, URI query string, HTML form POST, XML document, JSON string value etc).
A JWsec message MUST match the <jwsec> production, defined using Augmented Backus-Naur Form (ABNF) [RFC5234]:
jwsec = ("U" "." header64 "." compressed64) /
("S" "." header64 "." compressed64 "." signature64) /
("E" "." header64 "." enckey64 "." ciphertext64) /
(ext "." header64 *("." component64))
; note: "X" matches "X" or "x" in ABNF
ext = %x41-5A / %x61-7A ; A-Z a-z
header64 = 1*b64url ; base64url-encoded UTF-8-encoded JSON object
; base64url-encoded byte arrays
compressed64 = *b64url ; input data, optionally compressed
signature64 = *b64url ; digital signature or MAC
enckey64 = *b64url ; encrypted per-message key
ciphertext64 = *b64url ; IV, encrypted data, and authentication tag
component64 = *b64url
b64url = %x41-5A / %x61-7A / %x30-39 / %x2D / %x5F
; A-Z a-z 0-9 - _
The first dot-separated component in a JWsec message is a single letter indicating the nature of the protection provided to the data. It determines the semantics of the components after the header. Three modes are defined in this specification: "U" or "u" for unprotected data; "S" or "s" for signed data; and "E" or "e" for encrypted data. A lowercase letter for the mode indicates that the input data for the JWsec message is another a JWsec message (UTF-8 encoded).
Additional modes can be defined in RFCs that update this specification.
Each JWsec message incorporates a header that is a JSON object with 0, 1, or more elements [RFC4627]. The header64 field is the base64url encoding (without padding) of the UTF-8 encoding of the header JSON object. Header elements identify the algorithms and keys required to process the message.
Various header elements are defined in this document. Further header elements holding algorithm-specific parameters are likely to be defined as algorithms are specified for use with JWsec. Other header elements could be defined to hold status information about keys or certificates, for instance. A recipient MUST ignore any header elements it does not recognize so new header elements can be deployed while maintaining interoperability.
Subsequent sections for each mode define output components that are bytes arrays. Those byte arrays are base64url encoded (without padding) then joined to the mode and header (all separated by dots) to form a JWsec message. A component's value can be a zero-length byte array, in which case the corresponding part of the JWsec message is an empty string but the dot-separators are still present.
An unprotected JWsec message offers no security for the input data it carries. It can compress the data. An unprotected message can be useful when security is provided by a lower layer. Using an unprotected JWsec message as the input data for an encrypted JWsec message provides a place (the unprotected JWsec message's header) to include any header elements associated with the input data that are confidential.
Output components (other than the mode and header) are:
The compressed data is the input data after applying the compression algorithm specified by the "zip" header element. If there is no "zip" element the compressed data equals the input data. A recipient MUST understand the "zip" header element.
There are no mandatory header elements so an empty JSON object {} is a valid header.
A signed JWsec message provides data-origin authentication for the input data. Signing can use the private key of a public/private key pair to create a digital signature; or it can use a secret symmetric key to create a message authentication code (MAC). The data can, optionally, be compressed.
Output components (other than the mode and header) are:
The compressed data is the input data after applying the compression algorithm specified by the "zip" element in the header. If there is no "zip" element the compressed data equals the input data. A recipient MUST understand the "zip" header element.
The header MUST include a "sig" element identifying either an asymmetric signature algorithm or a MAC algorithm [see [ALGS] sections 4 and 5]. The signature or MAC covers the mode, header, and compressed data. It is calculated over the (UTF-8 encoded) prefix of the JWsec message upto (but excluding) the dot-separator before the signature64 component.
signature = SIGN(("S" or "s") "." B64(header) "." B64(compressed))
When using a MAC algorithm the header MUST include a "kid" element to identify the secret key.
When using an asymmetric signature algorithm the public verification key needs to be available to the recipient. The header MUST include an "okid" element to identify the public key. The header SHOULD include a "jku" or "x5u" element holding a URI for the raw or certified public key respectively.
An encrypted JWsec message provides confidentiality for the input data. The input data is, optionally, compressed. The message is also integrity protected. This is achieved by using an authenticated encryption algorithm that supports additional data (AEAD algorithm), keyed with a randomly-chosen per-message secret key. Three techniques are available to distribute the per-message key:
An intermediate component to aid describing the process is:
Output components (other than the mode and header) are:
The plaintext is the input data after applying the compression algorithm specified by the "zip" element in the header. If there is no "zip" element the plaintext equals the input data. A recipient MUST understand the "zip" header element.
The header MUST include an "enc" element identifying an AEAD algorithm [see [ALGS] section 9]. A random per-message key is chosen, using the key size required by the AEAD algorithm. See [RFC4086] for considerations on generating random values. The data to be encrypted by the AEAD algorithm is the plaintext. The additional data to be authenticated by the AEAD algorithm is the (UTF-8 encoded) prefix of the JWsec message up to (but excluding) the dot-separator before the ciphertext64 component.
If the AEAD algorithm involves an initialization vector (IV) it is prepended to the ciphertext. The authentication tag generated by the AEAD algorithm is appended to the ciphertext. The lengths of the IV and authentication tag are defined by the AEAD algorithm.
additionalData = ("E" or "e") "." B64(header) "." B64(enckey)
ciphertext = [iv] ENCRYPT(plaintext) authtag
The header MUST include a "kmg" element identifying a key transport, key agreement, or symmetric key wrapping algorithm [see [ALGS] sections 6, 7, and 8]. The encrypted per-message key is held in the enckey component.
When the "kmg" header element identifies a key transport algorithm, that algorithm is used to encrypted the per-message key with the recipient's public key.
The header MUST include a "kid" element to identify the recipient's asymmetric key pair.
When the "kmg" header element identifies a key agreement algorithm, the originator and recipient each use their own private key and the other party's public key to generate a pairwise symmetric key. That symmetric key is used to encrypted the per-message key using a symmetric key wrapping algorithm.
Note: the specification of a key agreement algorithm has to specify a symmetric key wrapping algorithm as well.
The header MUST include a "kid" element to identify the recipient's asymmetric key pair.
The originator's public key also needs to be identified. The header MUST include either an "epk" element or an "okid" element. The former hold the originator's actual public key. The latter is an identifier for the public key, and SHOULD be accompanied by either a "jku" or "x5u" element, conveying a URI for the raw or certified public key respectively.
When the "kmg" header element identifies a symmetric key wrapping algorithm, that algorithm is used to encrypted the per-message key with a secret key shared by the originator and recipient.
The header MUST include a "kid" element to identify the shared secret key.
The following header elements are defined in this document:
| Name | Description |
|---|---|
| zip | String identifier for a compression algorithm. See [ALGS] section 3. |
| sig | String identifier for an asymmetric digital signature algorithm, or for a symmetric message authentication code (MAC) algorithm. See [ALGS] sections 4 and 5. |
| kmg | String identifier for a key transport algorithm, a key exchange algorithm, or a symmetric key wrapping algorithm. See [ALGS] sections 6, 7, or 8 respectively. |
| enc | String identifier for an authenticated encryption with additional data (AEAD) algorithm. See [ALGS] section 9. |
| kid | String identifier for the recipient's key that is needed to process the message. The identified key can be either: a symmetric secret key shared by the message originator and recipient; or an asymmetric key pair for which the recipient has the private key while the originator used the public key. |
| okid | String identifier for the originator's asymmetric key pair, the public key of which is needed by the recipient to process the message. |
| jku | String holding a Uniform Resource Identifier (URI) for one or more public keys in JSON Web Key format [draft-ietf-jose-json-web-key]. It MUST be an HTTPS URI. |
| x5u | String holding a Uniform Resource Identifier (URI) for an X.509 certificate chain. |
Additional header elements can be defined in other documents. A header element name can be a URI or a short name. A short name MUST NOT contain a colon ":" (which a URI will contain), but can otherwise be any Unicode string. A header element name that is a short name MUST be registered in the JWsec header element registry. A header element name that is a URI MAY be registered.
This document establishes a registry that IANA will maintain for elements that can appear in the header of a JWsec message. The registry's name is "JWsec Header Element Registry". The registry lists element names and the specification where they are defined.
The policy for registring a name that is a URI is First Come First Served (as per [RFC5226] section 4.1). The policy for registring a name that is not a URI (and MUST NOT contain a colon) is Specification Required.
The initial contents of the registry are:
| Name | Reference |
|---|---|
| zip | [this document] |
| sig | [this document] |
| kmg | [this document] |
| enc | [this document] |
| kid | [this document] |
| okid | [this document] |
| jku | [this document] |
| x5u | [this document] |
The "application/jwsec" media type is registered with IANA to identify a JWsec message.
JWsec messages have different security properties depending on the modes of protection applied, the order they are applied, and whether symmetric or asymmetric keys are used. A JWsec message can have no security. Consequently, a recipient needs to explicitly confirm that the protection applied to each received message matchs the expected protection.
...
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. |
| [RFC4086] | Eastlake, D., Schiller, J. and S. Crocker, "Randomness Requirements for Security", BCP 106, RFC 4086, June 2005. |
| [RFC4627] | Crockford, D., "The application/json Media Type for JavaScript Object Notation (JSON)", RFC 4627, July 2006. |
| [RFC4648] | Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", RFC 4648, October 2006. |
| [RFC5652] | Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, RFC 5652, September 2009. |
| [RFC5234] | Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, January 2008. |
| [RFC5226] | Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 5226, May 2008. |
| [draft-ietf-jose-json-web-key] | Jones, M., "JSON Web Key (JWK)", May 2012. |
| [ALGS] | Doe, J., "JSON Web Security Message Algorithms (similar to draft-ietf-jose-json-web-algorithms)", June 2012. |
[TODO]