Network Working Group J. Manger
Internet-Draft Telstra
Intended status: Standards Track June 11, 2012
Expires: December 13, 2012
JSON Web Security Message Format
draft-manger-jose-jwsec-00.txt
Abstract
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.
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 13, 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
Manger Expires December 13, 2012 [Page 1]
Internet-Draft JWsec June 2012
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.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Conventions Used In This Document . . . . . . . . . . . . 4
1.2. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
4. Unprotected message (mode U) . . . . . . . . . . . . . . . . . 7
5. Signed message (mode S) . . . . . . . . . . . . . . . . . . . 8
6. Encrypted message (mode E) . . . . . . . . . . . . . . . . . . 8
6.1. Key transport . . . . . . . . . . . . . . . . . . . . . . 10
6.2. Key agreement . . . . . . . . . . . . . . . . . . . . . . 10
6.3. Symmetric key wrapping . . . . . . . . . . . . . . . . . . 10
7. Header elements . . . . . . . . . . . . . . . . . . . . . . . 10
8. IANA considerations . . . . . . . . . . . . . . . . . . . . . 11
8.1. JWsec Header Element Registry . . . . . . . . . . . . . . 11
8.2. Media type . . . . . . . . . . . . . . . . . . . . . . . . 12
9. Security considerations . . . . . . . . . . . . . . . . . . . 12
10. Normative References . . . . . . . . . . . . . . . . . . . . . 13
Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 13
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 13
Manger Expires December 13, 2012 [Page 2]
Internet-Draft JWsec June 2012
1. Introduction
[[ This document presents the author's ideas for improving the
JWS/JWE/JWT drafts -- formulated as a complete spec. This
document copies lots of text from draft-rescorla-jsms-00,
draft-ietf-jose-json-web-signature-01,
draft-ietf-jose-json-web-encryption, and (parts of)
draft-ietf-oauth-json-web-token-00. ]]
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.
Manger Expires December 13, 2012 [Page 3]
Internet-Draft JWsec June 2012
1.1. Conventions Used In This Document
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.
1.2. Examples
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.
Manger Expires December 13, 2012 [Page 4]
Internet-Draft JWsec June 2012
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.
2. Model
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.
Manger Expires December 13, 2012 [Page 5]
Internet-Draft JWsec June 2012
-->[unprotected]---
input data | | JWsec message
-------------+->--+->[ signed ]--+->--+--------------->
[byte array] ^ | | | [string]
| -->[ encrypted ]--- |
| |
--------[UTF-8 encode]<------
3. Syntax
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
Manger Expires December 13, 2012 [Page 6]
Internet-Draft JWsec June 2012
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.
4. Unprotected message (mode U)
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:
compressed [byte array]
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.
Manger Expires December 13, 2012 [Page 7]
Internet-Draft JWsec June 2012
There are no mandatory header elements so an empty JSON object {} is
a valid header.
5. Signed message (mode S)
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:
compressed [byte array]
signature [byte array]
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.
6. Encrypted message (mode E)
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
Manger Expires December 13, 2012 [Page 8]
Internet-Draft JWsec June 2012
techniques are available to distribute the per-message key:
o Key transport: the per-message key is encrypted with the
recipient's public key
o Key agreement: a pairwise symmetric key is generated from the
originator's and recipient's public/private key pairs, and then
used to encrypt the per-message key
o Symmetric key wrapping: the per-message key is encrypted using a
shared symmetric secret key
An intermediate component to aid describing the process is:
plaintext [byte array]
Output components (other than the mode and header) are:
enckey [byte array]
ciphertext [byte array]
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.
Manger Expires December 13, 2012 [Page 9]
Internet-Draft JWsec June 2012
6.1. Key transport
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.
6.2. Key agreement
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.
6.3. Symmetric key wrapping
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.
7. Header elements
The following header elements are defined in this document:
Manger Expires December 13, 2012 [Page 10]
Internet-Draft JWsec June 2012
+------+------------------------------------------------------------+
| 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.
8. IANA considerations
8.1. JWsec Header Element Registry
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
Manger Expires December 13, 2012 [Page 11]
Internet-Draft JWsec June 2012
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] |
+------+-----------------+
8.2. Media type
The "application/jwsec" media type is registered with IANA to
identify a JWsec message.
Type name: application
Subtype name: jwsec
Required parameters: none
Optional parameters: none
Encoding considerations: 7bit
Security considerations: Some JWsec messages provide data origin
authenticity and confidentiality, but others provide no security.
A recipient of a message with this media type needs to ensure that
the security provided by the actual message received meets the
receiver's expectations for the message.
Interoperability considerations: no known issues
Published specification [this document]
Applications that use this media type: expected to be used by a
range of web applications
Additional information: none
Contact: IETF
Intended usage: COMMON
Restrictions on usage: none
Author: IETF
Change controller: IETF
9. Security considerations
JWsec messages have different security properties depending on the
Manger Expires December 13, 2012 [Page 12]
Internet-Draft JWsec June 2012
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.
...
10. Normative References
[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.
Appendix A. Acknowledgments
[TODO]
Manger Expires December 13, 2012 [Page 13]
Internet-Draft JWsec June 2012
Author's Address
James Manger
Telstra
Email: james@manger.com.au
Manger Expires December 13, 2012 [Page 14]