JSF is a scheme for signing data expressed as JSON [RFC8259] objects, loosely modeled after XML DSig's [XMLDSIG] "enveloped" signatures. Note that JSF requires that the JSON data to be signed is compatible with the I-JSON [RFC7493] profile.Unlike JSON Web Signature (JWS) [RFC7515] which was designed for signing any kind of data, a JSF 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, with the introduction of the JSON Canonicalization Scheme [RFC8785] both data and header information could be provided in plain text while still being subject to cryptographic operations.In order to make library support of JSF straightforward in spite of having a different structure compared to JWS, JSF uses the same JWA [RFC7518] and RFC8037 [RFC8037] signature algorithms.JSF may also be used for "in-object" JavaScript signatures, making JSF suitable for HTML5 applications. See ECMAScript Mode.There is also a "companion" specification for encryption coined JEF [JEF].

The following cryptographically verifiable sample signature is used to visualize the JSF specification:The sample signature's payload consists of the properties above the "signature" property. Note: JSF 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 "value" property except for the "value" property itself (shaded area in the sample).

JSF consists of an arbitrary but unique top level property (see p256#es256@name-jwk.json) holding a composite JSON object (signaturecore, multisignature or signaturechain).

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 JSF JSON structures in detail.

JSF implementors are presumed to be familiar with JWS [RFC7515].Prerequisite: A JSON object in accordance with [RFC7493] containing an arbitrary but unique top level property (see p256#es256@name-jwk.json) holding a JSF signaturecore, multisignature or signaturechain object.Note that there must not be any not here defined properties inside of the signature object and that the use of JCS [RFC8785] implies certain constraints on the JSON data.Since JSF uses the same algorithms as JWS, the JWA [RFC7518] reference apply. The process for recreating the signed data must be performed as follows:

1. The "value" property is deleted from the JSF signature object.
2. The signed data is retrieved by running the JCS [RFC8785] canonicalization method over the remaining object in its entirety.

Note that data that is unsigned (as defined by the excludes property), must be excluded from the JCS process.Applied on the Sample Object, a conforming JCS process should return the following JSON string:Note that the output string was folded for improving readability. The signature supplied in the value property can now be validated by applying the algorithm specified in the algorithm property (together with the appropriate signature verification key), on the UTF-8 representation of the canonicalized textual data.Path validation (when applicable), is out of scope for JSF, but is preferably carried out as described in X.509 [RFC5280].

Prerequisite: A JSON object in accordance with [RFC7493].The process to sign a JSON object using JSF is as follows:

1. Create a JSF object with all components defined except for the "value" property.
2. Add the JSF object to the top level JSON object to be signed using any valid JSON property name which does not clash with the other top level properties.
3. Generate the required format of the JSON object to be signed by running the JCS [RFC8785] canonicalization method over the JSON object in its entirety.
4. Apply the selected signature algorithm and key to the value generated in the previous step.
5. Complete the process by adding the "value" property (with the argument set to the result of the previous step), to the JSF object.

.Note that data that should not be signed (as defined by the excludes property), must be excluded from the JCS process.

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

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

See also Counter Signatures.

Signature chains require that each added signature object does not only sign the data but the preceding signature objects as well. See the Signature Chain Sample.The canonicalization procedure is essentially the same as for simple signatures but must also take the following in account:

• The '[' and ']' characters must be included in the canonicalized data for each signaturecore object.
• Each signature requires its own canonicalization process. During signature validation, array wise higher order signature objects must (temporarily) be removed including leading and trailing ',' characters.
• The ',' characters separating signature objects of array wise lower order than the one to add or validate must be included in the canonicalized data.

See also Counter Signatures.

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 JSF implementation.The Sample Object was signed by the following EC private key in the JWK [RFC7517] format:The following object was signed by the p256privatekey.jwk key while the public key is identified by a keyId property:The following object was signed by the p256privatekey.jwk key while the public key is supposed to be implicitly known by the verifier:The following object was signed by the p256privatekey.jwk key while the public key is featured in a certificatePath:The following object was signed by the p256privatekey.jwk key but uses another property name than in the other samples for holding the signaturecore object:The following object was signed by the p256privatekey.jwk key. There is also an extensions list:The following object was signed by the p256privatekey.jwk key. There is also an excludes list:EC private key associated with subsequent objects:The following object was signed by the p384privatekey.jwk key:The following object was signed by the p384privatekey.jwk key while the public key is identified by a keyId property:The following object was signed by the p384privatekey.jwk key while the public key is supposed to be implicitly known by the verifier:The following object was signed by the p384privatekey.jwk key while the public key is featured in a certificatePath:EC private key associated with subsequent objects:The following object was signed by the p521privatekey.jwk key:The following object was signed by the p521privatekey.jwk key while the public key is identified by a keyId property:The following object was signed by the p521privatekey.jwk key while the public key is supposed to be implicitly known by the verifier:The following object was signed by the p521privatekey.jwk key while the public key is featured in a certificatePath:RSA private key associated with subsequent objects:The following object was signed by the r2048privatekey.jwk key:The following object was signed by the r2048privatekey.jwk key. Note the use of the RSASSA PSS algorithm:The following object was signed by the r2048privatekey.jwk key while the public key is identified by a keyId property:The following object was signed by the r2048privatekey.jwk key while the public key is supposed to be implicitly known by the verifier:The following object was signed by the r2048privatekey.jwk key while the public key is featured in a certificatePath:Ed25519 private key associated with subsequent objects:The following object was signed by the ed25519privatekey.jwk key:The following object was signed by the ed25519privatekey.jwk key while the public key is identified by a keyId property:The following object was signed by the ed25519privatekey.jwk key while the public key is supposed to be implicitly known by the verifier:The following object was signed by the ed25519privatekey.jwk key while the public key is featured in a certificatePath:Ed448 private key associated with subsequent objects:The following object was signed by the ed448privatekey.jwk key:The following object was signed by the ed448privatekey.jwk key while the public key is identified by a keyId property:The following object was signed by the ed448privatekey.jwk key while the public key is supposed to be implicitly known by the verifier:The following object was signed by the ed448privatekey.jwk key while the public key is featured in a certificatePath:HMAC key named "a256bitkey" here provided in hexadecimal notation:The following object was signed by the key above:HMAC key named "a384bitkey" here provided in hexadecimal notation:The following object was signed by the key above:HMAC key named "a512bitkey" here provided in hexadecimal notation:The following object was signed by the key above:The following object was signed by multiple signatures (see Multiple Signatures) using the p256privatekey.jwk and r2048privatekey.jwk keys:The following object was signed by multiple signatures (see Multiple Signatures) using the p256privatekey.jwk and r2048privatekey.jwk keys while the public keys are identified by keyId properties. There is also an extensions list. Note that this JSF features optional extension arguments (the second signature lacks one element):The following object was signed by multiple signatures (see Multiple Signatures) using the p256privatekey.jwk and r2048privatekey.jwk keys while the public keys are identified by keyId properties. There is also an excludes list:The following object was signed by a chain of signatures (see Signature Chains) using the p256privatekey.jwk and r2048privatekey.jwk keys:The following object was signed by a chain of signatures (see Signature Chains) using the p256privatekey.jwk and r2048privatekey.jwk keys while the public keys are identified by keyId properties. There is also an extensions list. Note that this JSF features optional extension arguments (the second signature lacks one element):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:Due to the fact that the JSON.stringify() method converts JavaScript objects like above into JSON-compliant strings no special considerations are required for JavaScript.

For counter signatures there are several different solutions where Signature Chains is the most straightforward.Another 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 JSF extensions holding application specific (per signature) metadata.

JSF 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:

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 [ES] 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).

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