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 normalization method for JSON data. However, version 6 of ECMAScript [ES6] introduced a predictable serialization scheme which enables 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 supports the same algorithms [RFC7518] as well as using JWK [RFC7517] for representing public key data. Since JCS is rooted in ECMAScript, 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 signature. 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 value property (shaded area in the sample).

Prerequisite: A JSON object in accordance with [RFC7159] containing a properly formatted signature sub object.Parsing constraints:

• The original property serialization order must be preserved as described by ECMAScript [ES6] section 9.1.12.
• 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 must not be empty ("").
• 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:

• The value property (including leading or trailing ',') must be deleted from the signature sub object.
• 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.
• 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.
• Now the JSON object associated with the signature must be recreated using the actual text left after applying the previous measures.
  Also see Interoperability and ECMAScript Mode.

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 value can now be calculated by running the algorithm specified in the algorithm property using the signature key over the UTF-8 representation of the normalized 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 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 "signatures".
• 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 Signature can be verified by the public part of the following EC key in JWK [RFC7517] format:The following signature object which uses a keyId for identifying the public key can be verified with the public part of the key above:The following signature object uses the same key as in the previous example but featured in a certificate path:EC key for verifying the subsequent object:The following signature object can be verified by the public part of the key above:The following signature object uses the same key as in the previous example but featured in a certificate path:EC key for verifying the subsequent object:The following signature object can be verified by the public part of 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 keyId, nor a publicKey property:The following signature object uses the same key as in the previous example but featured in a certificate path:RSA key for verifying the subsequent object:The following signature object can be verified by the public part of the key above:The following signature object uses the same key as in the previous example but featured in a certificate path:The following signature object is referring to a remoteKey which in turn should be identical to the key used in the previous RSA examples:HMAC key named "s256bitkey" here provided in Base64URL notation:Signature object requiring the key above for validation:HMAC key named "s384bitkey" here provided in Base64URL notation:Signature object requiring the key above for validation:HMAC key named "s512bitkey" here provided in Base64URL notation:Signature object requiring the key above for validation:The following is a multiple signature (see Multiple Signatures) using the "20170101:mybank:p256" and "20170101:mybank: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 ECMAScriptIf numeric property names are used, they must be provided in ascending numeric order and inserted before possible non-numeric properties.

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 JCS extensions holding application specific (per signature) metadata.

JCS as well as the freestanding sub objects publicKey and certificatePath, have been utilized 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. Note the handling of certificate serial numbers in JCS.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].