JSON Web Security Message Format

[[ 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) -- 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) and base64url encodings (without padding) 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 . 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 . 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" . 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) :

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 . 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: [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. 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: [byte array] [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 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: Key transport: the per-message key is encrypted with the recipient's public key 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 Symmetric key wrapping: the per-message key is encrypted using a shared symmetric secret key An intermediate component to aid describing the process is: [byte array] Output components (other than the mode and header) are: [byte array] [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 section 9]. A random per-message key is chosen, using the key size required by the AEAD algorithm. See 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 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: NameDescription zip String identifier for a compression algorithm. See section 3. sig String identifier for an asymmetric digital signature algorithm, or for a symmetric message authentication code (MAC) algorithm. See sections 4 and 5. kmg String identifier for a key transport algorithm, a key exchange algorithm, or a symmetric key wrapping algorithm. See sections 6, 7, or 8 respectively. enc String identifier for an authenticated encryption with additional data (AEAD) algorithm. See 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 . 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 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: NameReference 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. application jwsec none none 7bit 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. no known issues [this document] expected to be used by a range of web applications none IETF COMMON none IETF IETF

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. ...