JavaScript Message Security Format

Many applications require the ability to send cryptographically secured (encrypted, digitally signed, etc.) messages. While the IETF has defined a number of formats for such messages, those formats are widely viewed as being excessively complicated for the demands of Web applications, which typically only need the ability to secure simple messages. In addition, existing formats use encoding mechanisms (e.g., ASN.1 DER) which are not congenial for many classes of applications (e.g., Web applications). This presents an obstacle to the deployment of strong security by such applications. This document describes a new cryptographic message format, JavaScript Message Security (JSMS). This format is intended to meet the need of modern applications, including JavaScript-based Web applications. While JSMS is modeled on existing formats -- principally CMS -- it uses JavaScript Object Notation (JSON) rather than ASN.1, making it far easier for applications to handle. In the interest of simplicity, JSMS also omits many of less commonly used CMS modes (such as password-based encryption).

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in . In order to enable JSON to carry binary data, JSMS makes extensive use of Base64 encoding . Whenever this document refers to Base64 encoding, we mean the URL-safe variant "base64url" encoding. As stated in section 3.1 of , Base64 does not allow linefeeds. Since linefeeds are not valid characters in a JSON string, whenever a field is specified to be Base64-encoded in this document, it MUST NOT include any line breaks. Base64-encoded fields also MUST NOT include JSON-encoded linefeeds such as "\n". Any linebreaks in the middle of Base64-encoded sections of the examples in this document have been inserted in order to make the examples fit on the page. Any trailing "=" characters SHOULD be removed. They are not needed, because JSON strings have defined lengths (namely the number of characters between unescaped '"' characters).

The JSMS message format is simply a JSON object with an appropriate collection of fields. Each operating mode will have a separate set of fields, with a common field to distinguish between the modes.

JSMS supports three operational modes: A block of data signed by a single signer using his asymmetric key and optionally carrying his certificate. A block of data with authentication and integrity protection provided using a symmetric-key Message Authentication Code (MAC). The MAC key may be provided in encrypted form (as with Encryped Data) or identified by name. A block of data encrypted under a random message encryption key (MEK). The MEK is then separately encrypted for each recipient, either via symmetric or asymmetric encryption. The data is always integrity protected, through the use of an Authenticated Encryption with Associated Data (AEAD) algorithm such as AES-GCM or AES-CCM. Any other desired security functions are provided by composition of these modes. For instance, a signed and encrypted message is produced by first creating a Signed message and then encrypting that data.

In general, JSMS follows the following design principles. Wherever possible, protocol choices have been made such that the time and effort required to implement the protocol in many different programming languages will be minimized. This means that optimizations for bandwidth, CPU, and memory utilization have been explicitly avoided. Any data that does not have a straightforward string representation (binary values, large integers, etc.) is base64-encoded (see: ). In some cases, hexadecimal encodings might be more convenient, but consistency is even more important to reduce implementation complexity. In many cryptographic message formats, canonical encodings are used to allow the same value to be computed at both sender and recipient (e.g., for digital signatures). This is inconvenient in JSON, which just views messages as a bundle of key/value pairs. Instead, whenever canonicalization would be required, the relevant data is serialized and base64-encoded for transport, allowing both sides to run computations over the same original set of octets. We assume that the entire message can fit in main memory and make no effort to design a wire representation which can be handled in small chunks in a single pass. This means, for instance, that there is no need to have a message digest indicator at the beginning of the message and then the signature at the end, as is done in CMS. Fields are simply serialized in whatever order is most convenient for the JSON implementation. The examples in this document are generally shown in whatever order seems most readable and are not normative. To simplify the adaptation of existing cryptographic modules and the validation of JSMS implementations, changes from the CMS cryptographic operations are minimized. JSMS is semantically equivalent to a profile of CMS, as described in .

Experience has shown that certificate handling (path construction) is one of the trickier parts of building a cryptographic system. While JSMS supports PKIX certificates, its certificate processing is far simpler than that of CMS. (It also supports the use of bare public keys in order to avoid the use of X.509 altogether.) When a JSMS agent provides its certificate, it must provide an ordered chain (as in TLS ) terminating in its own certificate, thus removing the need to construct certificate paths. The certificates MUST be ordered with the end-entity certificate first and each certificate that follows signing the certificate immediately preceding it.

JSMS will often be used in an online messaging environments with users that have an address of the form user@domain, such as email, XMPP, or SIP. As such, protocols such as WebFinger or an end-to-end protocol can be used to retrieve appropriate certificates. Downstream uses of JSMS SHOULD define a discovery mechanism suitable for the intended use.

A JSMS object is a JSON object that encodes cryptographic informaton related to a content byte string. This document specifies the set of keys that must be present in a JSMS object, what the associated values are, and how these values are generated and processed in order to realize security features. In processing JSMS objects, unknown keys MUST be ignored. JSMS defines three top-level types of secure object, each of which provides a specific cryptographic protection to a byte string. Signature using a public-key digital signature algorithm Authentication using a Message Authentication Code (MAC) Encryption and authentication using an Authenticated Encryption with Associated Data (AEAD) algorithm

For each field in a JSON object, we define the type of information that must be included in that field. At base are the object, array, string, number types defined by JSON. We also use two special sub-classes of strings: Fields with type "Token" contain a string drawn from a defined list of strings (e.g., an IANA registry for algorithm names). Fields with type "ByteString" contain a Base64-encoded byte string (note the considerations related to Base64 encoding in above). In addition to the primitive data types, defines a collection of useful object types that are used by the top-level JSMS objects. These are simply referred to by name when they appear as a field value in another object.

The following elements are common to all JSMS messages: REQUIRED Number. The version of JSMS used by this objec.t. This field MUST be set to 1. REQUIRED Token. The type of this JSMS object. This field MUST be set to one of the following values SignedData object AuthenticatedData object EncryptedData object OPTIONAL ByteString. The content byte string, Base64-encoded. If the "content" key is not present in a given JSMS object, then the JSMS object is "detached". In this case, the content must be associated with the JSMS object through some out-of-band mechanism before the JSMS object can be processed. Note that there is a risk that detached JSMS object might become invalid if the content is transformed, even if this transformation preserves the semantics of the content. For example, if the content is a JSON object, and the object passes through an intermediate process that adds whitespace or re-orders the fields in the object (neither of which changes the meaning of the object), then the recipient will not be able to verify the signature. For this reason, detached JSMS objects SHOULD NOT be used unless there is a canonical form for the content being processed.

A SignedData object MUST have a "type" field set to "signed". In addition, a SignedData object contains the following keys: REQUIRED AlgorithmIdentifier. The digest algorithm used in signing the content. REQUIRED Array of Signature. One or more digital signatures over the content. OPTIONAL Array of String. A certificate chain associating the signer's public key with an identifier. Each element in the array is a string containing the Base64-encoded representation of a DER-formatted certificate. The certificates MUST be ordered with the end-entity certificate first and each certificate that follows signing the certificate immediately preceding it. OPTIONAL String. An HTTP or HTTPS URI referring to a certificate chain. The referenced resource MUST have type "application/json" and contain an array of certificates in the same format as the "certificates" element above, including the ordering constraint.

A Signature object represents the signature over the content in the SignedData object by a specific key pair. A Signature objec can contain the following keys: REQUIRED AlgorithmIdentifier. The signature algorithm used in signing the content. REQUIRED PublicKey. The public key identifier for the signer, represented as a PublicKey object (see ) REQUIRED ByteString. The Base64-encoded signature value If the "key" value represents the public key as an identifier, then a certificate for the signer MUST be provided by setting either the "certificates" or "certificatesURL" fields. The subject key in the end-entity certificate MUST match the identifier in the "key" value; the certificate SHOULD contain the subjectKeyIdentifier field, with a value matching the "key" value. (Note that this implies that when there are multiple signers, only one key can be represented by ID.)

The inputs to the process of generating a SignedData object are: The content, as a byte string A digest algorithm One or more signature algorithms and asymmetric key pairs To generate the signature for SignedData object, the originator takes the following steps: Compute the message digest by applying the digest algorithm to the content. For each signing key pair, compute the signature by using the signature algorithm to sign the message digest with the private key from the asymmetric key pair. The originator then encodes the SignedData object by including the appropriate AlgorithmIdentifiers for the digest algorithms, a Signature object for each signature, and (optionally) the content.

To verify a SignedData object, the recipient takes the following steps: Verify that the digest and signature algorithms are supported. Otherwise, report an error and fail. Compute the content byte string by decoding the "content" value of the JSMS object. If the JSMS object does not contain a "content" field, retrieve the content by other means. Compute the message digest by applying the digest algorithm to the content. Compute the signature by decoding the "signature" value of the JSMS object. Compute the public key: If the key is represented directly, then decode it according to the rules specified by the algorithm name. If the key is represented by an ID, then retrieve the corresponding subject public key from the end-entity certificate . If no "certificates" or "certificatesURI" value is present, then report an error and fail. If the key is represented by a URI, retrieve the public key from the URI. Verify the signature by using the signature algorithm to verify the message digest with the public key.

An AuthenticatedData object MUST have a "type" field set to "authenticated". In addition, an AuthenticatedData object contains the following keys: REQUIRED AlgorithmIdentifier. The MAC algorithm used to authenticate the content. REQUIRED ByteString. The MAC value OPTIONAL Array of WrappedKey. Wrapped versions of the symmetric key used for this MAC. Each element in the array MUST be a WrappedKey object (see below) OPTIONAL ByteString. An opaque identifier for a pre-shared MAC key An AuthenticatedData object MUST contain either the "key" field or the "keyId" field, so that the recipient knows which key to use to verify the MAC.

The inputs to the process of generating a AuthenticatedData object are: The content, as a byte string A MAC algorithm A MAC key and key identifier, or One or more recipient keys and key encipherment algorithms If the recipient key is specified rather than the MAC key directly, then a random MAC key is generated and encoded in a WrappedKey objects for each recipient (see ). Once the MAC key has been determined, the originator uses the MAC algorithm and MAC key to compute the MAC over the content byte string. The originator then encodes the AuthenticatedData object by including the appropriate AlgorithmIdentifier for the MAC algorithm and the Base64 representations of the MAC value and (optionally) the content. If the MAC key was specified directly, then the Base64 representation of the key identifier is set as the "keyId" value; otherwise, the WrappedKey objects are collected in an array and set as the "keys" value.

To verify a AuthenticatedData object, the recipient takes the following steps: Verify that the MAC algorithm is supported. If not, report an error and fail. Compute the content byte string by decoding the "content" value of the JSMS object. If the JSMS object does not contain a "content" field, retrieve the content by other means. Compute the MAC key: If the "keyId" value is present and represents a known key, use the identified key. If the "keys" value is present, check each WrappedKey object to determine if it matches a known key for this recipient. If any of the wrapped keys matches, unwrap the key from the first one and use it (see Section ). Otherwise, report an error and fail. Use the MAC algorithm and MAC key to compute the MAC over the content byte string Decode the MAC value from the "mac" field. Verify that the computed MAC matches the MAC from the object.

An EncryptedData object MUST have a "type" field set to "encrypted". Note also that in an EncryptedData object, the "content" field contains the encrypted form of the content, not the content itself (as plaintext). An EncryptedData object contains the following keys in addition to any common fields: REQUIRED AlgorithmIdentifier. The encryption algorithm used to encrypt the content REQUIRED Array of WrappedKey. Wrapped versions of the symmetric key used to encrypt the content. Each element in the array MUST be a WrappedKey object (see ). OPTIONAL ByteString. The MAC value, if required by the algorithm Note that although the "mac" field is optional, an EncryptedData object always has an integrity check. All of the encryption algorithms used in JSMS are "Authenticated Encryption with Associated Data" algorithms, which include an authentication / integrity fuction by definition. The MAC field is optional because some AEAD algorithms have a separate MAC value (e.g., GCM), while others incorporate the MAC value into the ciphertext (e.g., CCM).

The inputs to the process of generating a SignedData object are: The content, as a byte string An encryption algorithm One or more recipient keys and key encipherment algorithms The originator generates a random encryption key of a length suitable for the encryption algorithm, then encodes it in a WrappedKey object for each recipient (see ). The content is then encrypted using the generated encryption key and the specified encryption algorithm. The originator then encodes the EncryptedData object by including the appropriate AlgorithmIdentifier for the encryption algorithm, an array containing the WrappedKey objects, and (optionally) the Base64 representation of the content.

To decrypt an EncryptedData object, the recipient takes the following steps: Verify that the encryption algorithm is supported. If not, report an error and fail. Compute the content byte string by decoding the "content" value of the JSMS object. If the JSMS object does not contain a "content" field, retrieve the content by other means. Locate the encryption key: Check each WrappedKey object to determine if it matches a known key for this recipient. If any of the wrapped keys matches, unwrap the key from the first one and use it (see ). Otherwise, report an error and fail. Decrypt the content using the encryption key and the specified encryption algorithm. Verify that the integrity check in the AEAD decryption was successful. If not, report an error and fail. Return the decrypted content.

In this section we define some common object types that are used across the top-level objects above.

An AlgorithmIdentifier object names a cryptographic algorithm and specifies any associated parameters such as nonces or initialization vectors (IVs). If the algorithm has no parameters, then the AlgorithmIdentifier object is simply a token representing the name of the algorithm, drawn from an IANA registry of algorithm names. If the algorithm specifies parameters, the AlgorithmIdentifier object is a JSON object. There is only one required field, "name". Any other fields are specified in the algorithm definition. REQUIRED Token. The name of the algorithm, chosen from one of the IANA registries defined by this document. The following table summarizes the algorithms to be used with JSMS. [[ More detail to be added later, in a separate document ]]

Obviously, there will be more detail needed beyond the above, and some IANA considerations to create the necessary registries. For some algorithms, there will be specific notes about how they are to be used with JSMS, for example: The signature value produced by DSA is comprised of two integers. The byte string to be filled in the "signature" field is the two-element JSON array containing two integers, "[r,s]" RSAES-OAEP is always used with SHA-256 and the default MGF1 masking generation function Elliptic curves may only be specified by name, not by directly specifying curve parameters. [[ We may define our own registry, or re-use the ones from TLS/IKE. ]] AEAD algorithms are only used for authenticated encryption; there is never associated data. Further AEAD algorithms may be defined using [draft-mcgrew-aead-aes-cbc-hmac-sha1]

A PublicKey object describes the public key used by a signer. The key may be specified as a JSON structure directly, as a URI, or as an identifier. A PublicKey object has the following fields: OPTIONAL Token. The name of the algorithm with which this key is to be used OPTIONAL ByteString. An identifier for the key OPTIONAL String. A URI pointing to a direct form of the key If the key is specified directly, then the "type" key MUST be present; the "id" and "uri" fields MAY be present. Subsequent entries in the array specify the elements of the key, in a manner determined by the algorithm. Formats for RSA and ECDH/ECDSA public keys are specified below. If the key is provided as a URI, then the "uri" field MUST be present, containing a URI where the key can be retrieved, in the JSON format described above. The method that the recipient of a JSMS object uses to retrieve the key will depend on the URI scheme. For HTTP URIs, the relying party MUST issue an HTTP request with the GET method and an Accept header including the MIME type for JSMS PublicKey object, "[[MIMETYPE-TBD]]". For MAILTO, SIP, and XMPP URIs, the recipient MAY use the WebFinger protocol to retrieve a public key for the user. If the key is referenced by an opaque identifier or "fingerprint", then the "id" field MUST be present, and contain the Base64-encoded SHA-1 hash of the public key, represented as a DER-encoded subjectPublicKeyInfo data structure. (This fingerprint value is the same as the one commonly included in the subjectKeyIdentifier field in an X.509 certificate.) The recipient of a JSMS object can determine which of the above cases a given key falls into by seeking the three fields in sequence. If a "type" field is present, then the key is represented directly. If a "uri" field is present, then the key is represented directly, but must be retreived from the URI. Finally, if the "id" field is the only one of the three present, then the key is represented by ID only, and must be retrieved from somewhere else (e.g., from a certificate in the JSMS object). Example: {"id": "i1LbR8FCEw-aiFcAAfUvpp75wdY="} Example: {"uri": "xmpp:juliet@example.com"}

An RSA public key comprises two additional parameters in addition to the algorithm identifier "rsa". REQUIRED ByteString. The modulus, represented as an integer in network byte order (big-endian) REQUIRED Integer. The public exponent, represented as an integer in network byte order (big-endian) Example: {"type":"rsa", "n":98739...04251, "e": 3}

Public keys for several types of elliptic curve algorithms, including ECDSA and ECDH, have the same format, namely an point on a specified elliptic curve. In an elliptic curve PublicKey object, the curve parameters are specified in the algorithm identifier, and there are two additional fields that specify the point on the curve: REQUIRED ByteString. The x coordinate of the point REQUIRED Integer. The y coordinate of the point. MUST be equal to 0 or 1. These coordinates correspond to the compressed form of an elliptic curve point, as specified in [[SEC01]]. In terms of the calculation specified in section 2.3.3 of [[SEC01]], the "x" coordinate is the byte string X and the "y" coordinate is the reduced y coordinate (or, equivalently, Y mod 2). Example: {"type":"ecdh", "x":"IIIs_x1m6Na6xKN37vOwvy7AvFeG9HhBN2EN3u5EZQ4", "y": 1}

In JSMS objects that use symmetric keys (for MAC or encryption), it is necessary for the originator to convey the symmetric key used for in JSMS computations to the recipient. The WrappedKey object is a JSON object that allows these keys to be provided either using key transport or key agreement. The following fields may be present in a WrappedKey object: REQUIRED TOKEN The type of wrapping being done. This document defines the following values for this field: Symmetric key transport. The "KEKIdentifier" field MUST be present. Any other non-required fields MUST be ignored. Asymmetric key transport. The "recipientKey" field MUST be present. Any other non-required fields MUST be ignored. Key agreement. The "originatorKey" and "recipientKey" MUST be present, and the "userKeyMaterial" field MAY be present. Any other non-required fields MUST be ignored. REQUIRED AlgorithmIdentifier The algorithm used to encrypt the symmetric key REQUIRED BYTES The symmetric key, encrypted according to the algorithm indicated by the "algorithm" value OPTIONAL BYTES An opaque identifier for the symmtric key encryption key OPTIONAL PublicKey The public key of the originator OPTIONAL PublicKey The public key of the recipient OPTIONAL BYTES User key material The techniques used for wrapping and unwrapping the encrypted key is determined by "type" and "algorithm" fields. In general, the options are the same as for CMS [RFC5280], without the option for password-based key wrapping. The key is encrypted under a pre-shared symmetric key encryption key identified by the "KEKIdentifier" field The key is encrypted under the recipient's public key, identified in the "recipientKey" field. The key is encrypted under a shared secret derived using a key agreement algorithm combining the originator's private key and the recipient's public key, corresponding to the "originatorKey" and "recipientKey", respectively. The value provided in the "userKeyMaterial" field may be used to provide additional entropy. [[ More detail to be added. ]]

The compact JSON format of a JSMS object is identical to the normal JSMS format, except that field names are replaced with shorter equivalent field names. Translations for the field names above are given in the table below. In a given JSMS object, field names MUST either all be in long form or all be in short form. An implementation MUST reject a JSMS object with mixed long and short names as improperly formatted.

In applications where a JSMS object is required to be URL-safe, it is RECOMMENDED that it be rendered in the compact serialization, then Base64-encoded. [[ If there is a desire to avoid double-base64url-encoding things, then we could define a mechanism for moving some fields out of the object. ]]

This section contains complete examples of all three JSMS types. All white space is for readability only, and must be removed before the examples can be considered valid JSMS objects.

In this object the content is signed under the specified RSA key pair, using SHA256 as the digest.

In this object the content is authenticated with a MAC under a randomly-generated key (AuthenticatedData Key above), wrapped using the key encryption key above, identified by the above key tag.

As another example, the following object is a detached MAC (over the same content string) in the compact encoding. Here we use the key as the MAC key directly (instead of as a key encryption key). The object is shown both in raw JSON form and in the Base64 encoding.

In this object, the content is encrypted under the general AEAD algorithm using AES-128-CBC for encryption and HMAC-SHA1 for authentication. The keys are described above as "EncryptedData Key (E)" and "EncryptedData Key (A)", respectively. The temporary keys are wrapped using the PKCS#1 wrapping, under the RSA key pair above.

The JSMS message format is semantically equivalent to a profile of the Cryptographic Message Syntax (CMS), and mirrors a fair bit of its syntactical structure as well. The top-level message types each map to top-level CMS types: SignedData to SignedData, AuthenticatedData to AuthenticatedData, and EncryptedData to AuthEnvelopedData . The main difference other than encoding is that many optional fields have been removed, for example the protected and unprotected attributes. This similarity also applies to the secondary objects. Just as in CMS, AlgorithmIdentifier objects carry an identifier for the algorithm (here a name instead of an OID) and any related parameters. The PublicKey object format is an amalgam of the SubjectKeyIdentifier from CMS and the SubjectPublicKeyInfo from X.509. PublicKey objects can be mapped to CMS constructs by converting them to SubjectKeyIdentifier objects (using the appropriate hash) and including a certificate containing the public key. The WrappedKey object format maps directly to the CMS RecipientInfo structure, with the above considerations related to public keys, and without the option for password-based wrapping. The major way in which JSMS diverges from CMS is that it allows the use of static MAC keys, referenced by an identifier. CMS requires the use of random MAC keys, encrypted in a RecipientInfo (i.e., a WrappedKey) for each recipient. JSMS allows the use of random keys, but also includes the "keyId" field to reference static MAC keys directly. The security implications of this change are discussed in . In fact, it should be possible to translate JSMS objects back and forth to CMS without changing any values (simply reformatting), with only a couple of exception cases: JSMS objects that use static MAC keys cannot be translated to CMS because CMS does not allow this keying mechanism. JSMS objects using general AEAD algorithms (according to [[draft-mcgrew-aead-aes-cbc-hmac-sha1]]) because the required algorithm identifiers have not been defined for CMS. CMS objects using features that are not supported in JSMS (e.g., password-based key wrapping) cannot be translated to JSMS.

The overall JSMS structure covers the integrity, authentication, and encryption use cases as the JSON Web Encryption (JWE) and JSON Web Signature (JWS) specifications. Most of the fields in JWS and JWE map conceptually to JSMS fields, with a couple of exceptions. The major differences are as follows: The signature and MAC functions of the JWS object are separated into SignedData and AuthenticatedData JSMS objects. JSMS is pure JSON, whereas in JWE and JWS only the header parameters are represented in JSON. JSMS parameters are not integrity-protected, as they are in JWE and JWS. JSMS allows for full algorithm agility in key agreement, while JWE only allows ECDH-ES. JSMS supports multiple recipients for EncryptedData and AuthenticatedData objects via the inclusion of multiple WrappedKey objects. Sending a JWE to multiple recipients requires re-encryption of the entire object for each recipient. The "typ" and "zip" parameters are not defined in JSMS, but could be added without significant change. JSMS requires that recipients MUST ignore unknown header parameters, in order to facilitate extensibility. The PublicKey structure is analogous to the JSON Web Key (JWK) (with the public key parameters specified in the JSON Web Algorithms (JWA) document). The JWK "use" and "kid" parameters are not defined in JSMS, but could be added without significant change.

TODO: Register MIME types Registries for algorithms (signing, hash, MAC, encrypion, encipherment, agreement)

Much more to follow here. [[ Given the CMS mapping above, import CMS security considerations. ]] [[ Notes on identity for SignedData and AuthenticatedData: It is important to note that the above verification process only checks that the JSMS object was signed with a given public key. In order for this information to be useful to an applications, it is usually necessary to bind the public key to an application-layer identifier. If the "certificates" or "certificatesURI" value is present, then the recipient SHOULD verify that the chain is valid, and that the the end-entity certificate chains to a trust anchor. In this case, the recipient can consider the identity asserted in the end-entity certificate to be bound to the public key. Applications using this specification without certificates will need to specify an alternative mechanism for binding public keys to identifiers. ]] [[ Notes on the security of static-key MACs. Need to periodically refresh keys. ]] [[ For multiple signatures, the considerations of RFC 4853. ]]

The inspirataion and starting point for this document was draft-rescorla-jsms-00. Thanks to Eric Rescorla and Joe Hildebrand for allowing me to re-use a fair bit of their document, and for some helpful early reviews.