JCS is a scheme for signing data expressed as JSON [RFC7159] objects, loosely modeled after XML DSig's [XMLDSIG] "enveloped" signatures. Compared to its XML counterpart JCS is quite primitive but on the other hand it has proved to be simple to implement and use.Unlike JWS [RFC7515] which was designed for signing any kind of data, a JCS signature is intended to be an integral part of a JSON object with message centric systems like Yasmin [YASMIN] as the primary target. This concept was not originally considered due to the lack of a standardized canonicalization method for JSON data. However, version 6 of ECMAScript [ES6] introduced a simple to support predictable serialization scheme enabling both data and header information to be provided in plain text.In order to make library support of JCS straightforward in spite of having a different structure compared to JWS [RFC7515], JCS uses the same properties as well as cryptographic algorithms [RFC7518]. Due to the ECMAScript heritage, JCS may also be used for "in-object" JavaScript signatures, making JCS suitable for HTML5 applications. See ECMAScript Mode.There is also a "companion" specification coined JEF [JEF] which deals with JSON encryption.

The following cryptographically verifiable sample signature is used to visualize the JCS specification:The sample signature's payload consists of the properties above the "signature" property. Note: JCS does not mandate any specific ordering of properties like in the sample.For more examples see Test Vectors.

The scope of a signature (what is actually signed) comprises all properties including possible child objects of the JSON object holding the "signature" property except for the "val" property (shaded area in the sample).

Prerequisite: A JSON object in accordance with [RFC7159] supplied as a textual string containing a top level "signature" property.Additional input data constraints:

• JSON data of the type "Number", must already during signature creation have been serialized according to ECMAScript [ES6] section 7.1.12.1 including NOTE 2 (implemented by for example V8 [V8]), in order to achieve maximum interoperability.
• Property names within an object must be unique.
• There must not be any not here defined properties inside of the signature sub object.

The normalization steps are as follows:

• Whitespace must be removed which in practical terms means removal of all characters outside of quoted strings having a value of x09, x0a, x0d or x20.
• The val property (including leading or trailing ',') must be deleted from the signature sub object.
• JSON '\/' escape sequences within quoted strings must be treated as "degenerate" equivalents to '/' by rewriting them.
• As implied by ECMAScript [ES6] section 24.3.2.2:
  • Unicode escape sequences (\uhhhh) within quoted strings must be adjusted as follows: If the Unicode value falls within the traditional ASCII control character range (0x00 - 0x1f), it must be rewritten in lowercase hexadecimal notation unless it is one of the predefined JSON escapes (\" \\ \b \f \n \r \t) because the latter have precedence. If the Unicode value is outside of the ASCII control character range, it must be replaced by the corresponding Unicode character.

Note: A practical consequence of this arrangement is that the original property order is preserved. This is also compliant with ECMAScript JSON serialization as described in [ES6] section 9.1.12, albeit with the minor limitation outlined in ECMAScript Constraint.Also see Interoperability.Applied on the sample signature, a conforming JCS normalization process should return the following JSON string:The text in red highlights the string normalization process. Note that the output string was folded for improving readability. The signature supplied in the val property can now be validated by applying the algorithm specified in the alg property (together with the appropriate signature verification key), on the UTF-8 representation of the normalized textual data.Path validation (when applicable), is out of scope for JCS, but is preferably carried out as described in X.509 [RFC5280].The next sections cover the specifics of the JCS format.

JCS consists of a top-level "signature" property holding a composite JSON object.

JSON objects are described as tables with associated properties. When a property holds a JSON object this is denoted by a link to the actual definition. Properties may either be mandatory (M) or optional (O) as defined in the "Req" column.Array properties are identified by [ ] x-y where the range expression represents the valid number of array elements. In some JSON objects there is a choice from a set of mutually exclusive alternatives.
This is manifested in object tables like the following:

Property selection 1	Type selection 1	Req	Comment selection 1
Property selection 2	Type selection 2		Comment selection 2

The table below shows how the data types used by this specification are mapped into native JSON types:

Note that "Type" refers to the element type for arrays.

The following tables describe the JCS JSON structures in detail.

Multiple signatures enable different keys to independently of each other add a signature to a JSON object.The normalization procedure is essentially the same as for simple signatures but must also take the following in account as well:

• The signature property must be "signature".
• The '[' and ']' characters must be included in the normalized data for each signature object.
• Each signature requires its own normalization process. During this process the other signature objects must (temporarily) be removed.
• The ',' characters separating signature objects must be excluded from the normalized data.

Also see Counter Signatures and the multiple signature sample.

This specification does (to the author's knowledge), not introduce additional vulnerabilities over what is specified for JWS [RFC7515].

This section holds test data which can be used to verify the correctness of a JCS implementation.The Sample Object was signed by the following EC private key in JWK [RFC7517] format:The following signature object which uses a kid for identifying the public key can be verified with the key above:The following signature object uses the same key as in the previous example but also includes crit extensions:The following signature object uses the same key as in the previous example but also specifies excl properties:The following signature object uses the same key as in the previous example but featured in a certificate path:EC private key associated with the subsequent object:The following object was signed by the key above:The following signature object uses the same key as in the previous example but featured in a certificate path:EC private key associated with the subsequent object:The following object was signed by the key above:The following signature object uses the same key as in the previous example but builds on that the key to use is implicitly known since the object neither contains a kid, nor a jwk property:The following signature object uses the same key as in the previous example but featured in a certificate path:RSA private key associated with the subsequent object:The following object was signed by the key above:The following signature object uses the same key as in the previous example but featured in a certificate path:JWK [RFC7517] key set for verifying the subsequent object:The following signature object is referring to a jku property pointing to an object as described above:PEM [RFC7468] certificate path for verifying the subsequent object:The following signature object is referring to a x5u property pointing to an object as described above:HMAC key named "a256bitkey" here provided in hexadecimal notation:Signature object requiring the key above for validation:HMAC key named "a384bitkey" here provided in hexadecimal notation:Signature object requiring the key above for validation:HMAC key named "a512bitkey" here provided in hexadecimal notation:Signature object requiring the key above for validation:The following is a multiple signature (see Multiple Signatures) using the "example.com:p256" and "example.com:r2048" keys:The certificate based signatures share a common root (here supplied in PEM [RFC7468] format), which can be used for path validation:

ECMAScript mode in this context refers to the ability to sign JavaScript objects as well as using the standard JSON support for parsing and creating signed data.The code snippet below shows a signed JavaScript object:This signature could be verified by the following code:Constraint when using JCS with ECMAScriptFor JavaScript optimization reasons, ECMAScript's JSON.parse() internally rearranges order of properties with names expressed as integers, making a parsed JSON string like '{"2":"First","A":"Next","1":"Last"}' actually serialize as '{"1":"Last","2":"First","A":"Next"}'.Due to this fact, signature creators must (in the hopefully rather unusual case cross platform applications would mandate numeric property names), in an here unspecified way, "emulate" this scheme since this behavior is not intended to be an additional requirement to support by JSON tools in general in order to use this specification.

For counter signatures there are two entirely different solutions. One way dealing with counter signatures is using an application level counter signing solution like the following:Counter signed JSON object:For sophisticated peer based counter signature schemes another possibility is using Multiple Signatures, optionally including a JCS crit extension holding application specific (per signature) metadata.

JCS is a core element in a proof-of-concept application [PKIDROID] running on Android.The sample code below is based on the Java reference implementation [OPENKEY] which features an integrated JSON encoder, decoder and signature solution:

Since serialization of floating point numbers as specified by JCS is (at the time of writing) not available for all platforms, you may for highest possible interoperability need to put such data in quotes. Albeit a limitation, financial data is not natively supported by JSON either due to the fact that JavaScript lacks support for big decimals.JCS compatible reference implementations are available both for server Java and Android [OPENKEY]. These implementations use ECMAScript number serialization when creating JSON data, making them compliant with browsers and Node.js as well.Pyhton users can get the required parser behavior (modulo floating point data...) by using the following constructs:

During the initial phases of the design process, highly appreciated feedback were provided by Manu Sporny, Jim Klo, Jeffrey Walton, David Chadwick, Jim Schaad, Mike Jones, David Waite, Douglas Crockford, Arne Riiber, Brian Campbell, Sergey Beryozkin, and others.Special thanks go to James Manger who pointed out the ECMAScript [ES6] number serialization scheme as well as reviewing a related Internet draft.An early prototype was funded by PrimeKey Solutions AB and the Swedish Innovation Board (VINNOVA).

JCS was developed by Anders Rundgren (anders.rundgren.net@gmail.com) as a part of the OpenKeyStore project [OPENKEY].