Cleartext JSON Web Signature (JWS)
Spotify ABBirger Jarlsgatan 61, 4tr113 56StockholmSwedenerdtman@spotify.comIndependentMontpellierFranceanders.rundgren.net@gmail.comMicrosoftmbj@microsoft.comhttp://self-issued.info/
Security
JSON Object Signing and Encryption (JOSE)
JOSE, Signing, Encryption, Cleartext
Cleartext JSON Web Signature (JWS) is a means of signing JSON objects directly
without representing the JSON to be signed in a non-JSON representation, such as base64url-encoded JSON.
The signature and information about the signature is added to the JSON object when it is signed.
The signature calculation for signing the JSON object
uses the JSON canonicalization defined by .
Cleartext JWS builds on the JWS, JWA, and JWK specifications,
reusing data structures and semantics from these specifications, where applicable.
Cleartext JSON Web Signature (JWS) represents a signed JSON object directly
as a JSON object ,
without representing the JSON to be signed in a non-JSON representation, such as base64url-encoded JSON.
The signature and information about the signature is added to the JSON object when it is signed.
The signature calculation for signing the JSON object
uses the JSON canonicalization defined by .
By including the signature information in the JSON object to be signed, it is easy to
inspect data in transit and when archived, integrity can be guaranteed.
Cleartext JWS builds on the JWS ,
JWA , and JWK specifications,
reusing data structures and semantics from these specifications, where applicable.
Cryptographic algorithm identifiers used by this specification come from the
IANA "JSON Web Signature and Encryption Algorithms" registry .
There are three essential differences between Cleartext JWS and JWS:
Cleartext JWS can only sign JSON objects, rather than arbitrary data.
Cleartext JWS signature information is included within the signed data.
Cleartext JWS depends on predictable JSON Serialization,
rather than base64url-encoding the data to be signed.
The table below is a comparison of JWS and Cleartext JWS:
JWSCleartext JWSData to be SignedArbitrary data
JSON or JavaScript objects
Encoding of Signed DataBase64urlNoneEncoding of Header ParametersBase64urlNoneURL FriendlyCore featureOut of scope
In the following example, note that the signature information is included in the JSON object.
The members in the __cleartext_signature object are
the JWS Header Parameters for the signature.
The signature member contains the base64url-encoded signature value.
(Line breaks within values are for display purposes only.)
The key in can be used for verifying the example signature.
Note: Recreating the example signature using the example private key would normally
result in a different signature value
since ECDSA includes random data in the signature calculation.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED",
"MAY", and "OPTIONAL" in this document are to be interpreted as
described in BCP 14
when, and only when, they appear in all capitals, as shown here.
When signing JSON data with Cleartext JWS, a JSON object with the
JWS Header Parameters is created and placed within the JSON data to be
signed. In addition to the already defined JWS Header Parameters,
Cleartext JWS defines two new Header Parameters: signature
for the base64url-encoded signature value and signers
to support multiple signers within the same signature object.
The identifier for the Cleartext Signature Object in the JSON data to be
signed MUST be __cleartext_signature, unless
the application specifies that a different identifier is to be used.
The scope of a signature (the data that is actually signed) comprises all
values including child objects of the signature object
except for the signature member.
If multiple signers are present, only the data pertaining to all signers
and the data specific to that signer are included
(but not the data specific to other signers).
See for more about the multiple signatures case.
The signature Header Parameter contains the
base64url-encoded JWS Signature as a string.
The optional signers Header Parameter contains an
array of sets of Header Parameters that are specific to each signer,
including the signature value for each signer.
See for more about the multiple signatures case.
To create a Cleartext JWS, the following steps are performed. The order of the
steps is not significant in cases where there are no dependencies
between the inputs and outputs of the steps.
Create the application specific JSON object to be signed. In this
step the JSON should not be canonicalized.
Create the __cleartext_signature object
with the Header Parameters to be used and add it
as a top-level member to the JSON object to be signed with the key
__cleartext_signature.
Canonicalize the JOSN object to be signed using the canocalization
process defined by . Let the output of the
canonicalization be the cleartext input to the signature algorithm.
Compute the JWS Signature in the manner defined for the particular
algorithm being used over the canonicalize JSON object to be signed. The
alg (algorithm) Header Parameter MUST be
present in the __cleartext_signature
member, with the algorithm value accurately representing the
algorithm used to construct the JWS Signature.
Add the signature member to the signature
object (__cleartext_signature) within the original application JSON object.
with the value BASE64URL(JWS Signature).
When validating a Cleartext JWS, the following steps are performed. The order
of the steps is not significant in cases where there are no
dependencies between the inputs and outputs of the steps. If any of
the listed steps fails, then the input MUST be rejected.
When there are multiple JWS Signature values, it is an application
decision which of the JWS Signature values must successfully validate
for the Cleartext JWS to be accepted. In some cases, all must successfully
validate, or the Cleartext JWS will be considered invalid. In other cases,
only a specific JWS Signature value needs to be successfully
validated. However, in all cases, at least one JWS Signature value
MUST successfully validate, or the Cleartext JWS MUST be considered invalid.
Parse the application JSON data, including the signature object.
Verify that the implementation understands and can process all
fields that it is required to support, whether required by this
specification, by the algorithm being used, or by the crit
Header Parameter value, and that the values of those parameters
are also understood and supported.
Save and remove the signature member
from the signature object (__cleartext_signature) and
base64url-decode the encoded representation of the JWS Signature.
Canonicalize the signed object, including the signature
object (__cleartext_signature), by following the rules by
and let
the output be input to the signature algorithm.
Validate the JWS Signature against the JWS Signing Input, i.e., the
canonicalize data, in the manner defined for the
algorithm being used, which MUST be accurately represented by the
value of the alg (algorithm) Header Parameter value,
which MUST be present. Record whether the
validation succeeded or not.
Return a result indicating whether or not the Cleartext JWS was
successfully validated.
For later validation of the signed JSON object, put the signature
member back into the signature object (__cleartext_signature) within
the application JSON object.
Multiple signers using different keys can independently add signatures to a JSON object
in the manner described in this section.
The signature procedure is essentially the same as for single signatures
but also includes the following:
There MUST be an additional JWS Header parameter signers, holding an array
of signature objects.
Each signature requires its own canocalization process. During this
process, the signature objects for other signatures MUST be (temporarily) removed.
The canonicalized data in the signers value
MUST include the array brackets ([]) containing the data specific to this signature
but MUST NOT include the data for other signatures.
The resulting array will be single-valued, with no commas separating additional elements.
A given Header Parameter MUST NOT occur in both the top-level signature object
and a signature object within the signers value.
Any Header Parameter occurring in the top-level signature object applies to all signatures.
A signature object is equivalent to an ordinary signature object,
but MAY exclude the alg Header parameter
if it is present in the top-level signature object itself.
If in the top-level signature object,
all enclosed signature objects MUST use the same algorithm as well as not
including the alg Header parameter.
See for an example.
Likewise, if a crit Header parameter is specified in
the top-level signature object, it MUST be applied to
all signature objects and MUST NOT be present in them individually.
See for an example.
The following example shows a multiply signed object:
The ECDSA signature can be validated using the key in
and the RSA signature can be validated using the key in .
This section registers the following Header Parameters in the
IANA "JSON Web Signature and Encryption Header Parameters" registry
.
Header Parameter Name: signatureHeader Parameter Description: The base64url-encoded signature valueHeader Parameter Usage Location(s): Cleartext JWSChange Controller: IESGSpecification Document(s): Header Parameter Name: signersHeader Parameter Description: List of signature objects, each with a set of Header Parameters and a signature valueHeader Parameter Usage Location(s): Cleartext JWSChange Controller: IESGSpecification Document(s):
The same security considerations apply to this specification as do for JWS
.
JSON Web Signature and Encryption AlgorithmsIANAJSON Web Signature and Encryption Header ParametersIANA
This section contains a set of test vectors.
(Line breaks within values are for display purposes only.)
The first signature can be verified using the key in
and the second signature can be verified using the key in .
The first signature can be verified using the key in
and the second signature can be verified using the key in .
Elliptic Curve private key, represented as a JWK:Elliptic Curve private key, represented as a JWK:RSA private key, represented as a JWK:
This document builds on the work done in the JOSE working group, so a big thanks goes out
to all involved in that work. It is specifically inspired by JWS,
so special thanks are due to the authors of that document, Michael B. Jones, John Bradley,
and Nat Sakimura.
The following open issues remain to be addressed in this specification.
The signature creation and validation steps for the multiple signatures case needs to be added to
and .
[[ to be removed by the RFC Editor before publication as an RFC ]]
-01
Changed canocalization from ES6 serialization to .
"signature object" is now used consistently through out the specification.
-00
Initial version.