Copyright © 2022 the Contributors to the JSON Web Signature 2020 Specification, published by the Credentials Community Group under the W3C Community Final Specification Agreement (FSA). A human-readable summary is available.
This specification describes a JSON Web Signature Suite created in 2020 for the Linked Data Proof specification. The Signature Suite utilizes Detached JWS signatures to provide support for a subset of the digital signature algorithms registered with IANA.
This specification was published by the Credentials Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Final Specification Agreement (FSA) other conditions apply. Learn more about W3C Community and Business Groups.
This is an experimental specification and is undergoing regular revisions. It is not fit for production deployment.
If you wish to make comments regarding this document, please send them to public-credentials@w3.org (subscribe, archives).
This specification defines a cryptographic suite for the purpose of creating, verifying proofs for JSON Web Signatures in conformance with the Linked Data Proofs [LD-PROOFS] specification.
In general the suites uses the RDF Dataset Normalization Algorithm [RDF-DATASET-NORMALIZATION] to transform an input document into its canonical form. The cannonical representation is then hashed and signed with a detached signature algorithm.
The following terms are used to describe concepts involved in the generation and verification of the Linked Data Proof signature suite.
type
of the verification method for the signature
suite JsonWebSignature2020.
type
of the linked data proof for the signature suite
JsonWebSignature2020.
The JSON Web Signature signature suite 2020 MUST be used in conjunction with the signing and verification algorithms in the Linked Data Proofs [LD-PROOFS] specification. The suite consists of the following algorithms:
Parameter | Value | Specification |
---|---|---|
canonicalization algorithm | https://w3id.org/security#URDNA2015 | [RDF-DATASET-NORMALIZATION] |
message digest algorithm | SHA-256 | [RFC4634] |
signature algorithm | JSON Web Signature (JWS) Unencoded Payload Option | [RFC7797] |
This suite support cryptographic agility, see [RFC7696]. This table maps a key type to a subset of [IANA_JOSE] supported signing and encryption algorithms.
kty | crvOrSize | signature | keyAgreement | encryption |
---|---|---|---|---|
OKP | Ed25519 | EdDSA | ECDH-ES+A256KW | |
OKP | X25519 | ECDH | ECDH-ES+A256KW | |
EC | secp256k1 | ES256K | ECDH | ECDH-ES+A256KW |
EC | P-256 | ES256 | ECDH | ECDH-ES+A256KW |
EC | P-384 | ES384 | ECDH | ECDH-ES+A256KW |
RSA | 2048+ | PS256 | RSA-OAEP |
The cryptographic material used to verify a linked data proof is called the verification method.
This suite relies on public key material represented using [RFC7517].
This suite supports public key use for both digital signature verification, according to [RFC7515], and key agreement according to [RFC8037].
This suite MAY be used to verify linked data proofs produced by key material in any representation that can be converted to JWK, however it is RECOMMENDED that this suite be used with verification method's of type JsonWebKey2020.
The id
of the verification method SHOULD be the JWK
thumbprint calculated from the publicKeyJwk
property
value according to [RFC7638].
The type
of the verification method SHOULD be
JsonWebKey2020.
The controller
of the verification method SHOULD be a
URI.
The publicKeyJwk
property of the verification method
SHOULD be a JWK formatted according to [RFC7517].
Be careful not to accidentally publish the JWK representation of a
private key. See
rfc7517#appendix-A.2
for examples of private key representations. The property
publicKeyJwk
MUST never contain "d"
.
{
"id": "https://example.com/issuer/123#ovsDKYBjFemIy8DVhc-w2LSi8CvXMw2AYDzHj04yxkc",
"type": "JsonWebKey2020",
"controller": "https://example.com/issuer/123",
"publicKeyJwk": {
"kty": "OKP",
"crv": "Ed25519",
"x": "CV-aGlld3nVdgnhoZK0D36Wk-9aIMlZjZOK2XhPMnkQ"
}
}
{
"@context": ["https://www.w3.org/ns/did/v1", "https://w3id.org/security/suites/jws-2020/v1"],
"id": "did:example:123",
"publicKey": [
{
"id": "did:example:123#_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A",
"type": "JsonWebKey2020",
"controller": "did:example:123",
"publicKeyJwk": {
"kty": "OKP",
"crv": "Ed25519",
"x": "VCpo2LMLhn6iWku8MKvSLg2ZAoC-nlOyPVQaO3FxVeQ"
}
},
{
"id": "did:example:123#4SZ-StXrp5Yd4_4rxHVTCYTHyt4zyPfN1fIuYsm6k3A",
"type": "JsonWebKey2020",
"controller": "did:example:123",
"publicKeyJwk": {
"kty": "EC",
"crv": "secp256k1",
"x": "Z4Y3NNOxv0J6tCgqOBFnHnaZhJF6LdulT7z8A-2D5_8",
"y": "i5a2NtJoUKXkLm6q8nOEu9WOkso1Ag6FTUT6k_LMnGk"
}
},
{
"id": "did:example:123#n4cQ-I_WkHMcwXBJa7IHkYu8CMfdNcZKnKsOrnHLpFs",
"type": "JsonWebKey2020",
"controller": "did:example:123",
"publicKeyJwk": {
"kty": "RSA",
"e": "AQAB",
"n": "omwsC1AqEk6whvxyOltCFWheSQvv1MExu5RLCMT4jVk9khJKv8JeMXWe3bWHatjPskdf2dlaGkW5QjtOnUKL742mvr4tCldKS3ULIaT1hJInMHHxj2gcubO6eEegACQ4QSu9LO0H-LM_L3DsRABB7Qja8HecpyuspW1Tu_DbqxcSnwendamwL52V17eKhlO4uXwv2HFlxufFHM0KmCJujIKyAxjD_m3q__IiHUVHD1tDIEvLPhG9Azsn3j95d-saIgZzPLhQFiKluGvsjrSkYU5pXVWIsV-B2jtLeeLC14XcYxWDUJ0qVopxkBvdlERcNtgF4dvW4X00EHj4vCljFw"
}
},
{
"id": "did:example:123#_TKzHv2jFIyvdTGF1Dsgwngfdg3SH6TpDv0Ta1aOEkw",
"type": "JsonWebKey2020",
"controller": "did:example:123",
"publicKeyJwk": {
"kty": "EC",
"crv": "P-256",
"x": "38M1FDts7Oea7urmseiugGW7tWc3mLpJh6rKe7xINZ8",
"y": "nDQW6XZ7b_u2Sy9slofYLlG03sOEoug3I0aAPQ0exs4"
}
},
{
"id": "did:example:123#8wgRfY3sWmzoeAL-78-oALNvNj67ZlQxd1ss_NX1hZY",
"type": "JsonWebKey2020",
"controller": "did:example:123",
"publicKeyJwk": {
"kty": "EC",
"crv": "P-384",
"x": "GnLl6mDti7a2VUIZP5w6pcRX8q5nvEIgB3Q_5RI2p9F_QVsaAlDN7IG68Jn0dS_F",
"y": "jq4QoAHKiIzezDp88s_cxSPXtuXYFliuCGndgU4Qp8l91xzD1spCmFIzQgVjqvcP"
}
},
{
"id": "did:example:123#NjQ6Y_ZMj6IUK_XkgCDwtKHlNTUTVjEYOWZtxhp1n-E",
"type": "JsonWebKey2020",
"controller": "did:example:123",
"publicKeyJwk": {
"kty": "EC",
"crv": "P-521",
"x": "AVlZG23LyXYwlbjbGPMxZbHmJpDSu-IvpuKigEN2pzgWtSo--Rwd-n78nrWnZzeDc187Ln3qHlw5LRGrX4qgLQ-y",
"y": "ANIbFeRdPHf1WYMCUjcPz-ZhecZFybOqLIJjVOlLETH7uPlyG0gEoMWnIZXhQVypPy_HtUiUzdnSEPAylYhHBTX2"
}
}
],
"authentication": [
"did:example:123#_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A",
"did:example:123#4SZ-StXrp5Yd4_4rxHVTCYTHyt4zyPfN1fIuYsm6k3A",
"did:example:123#n4cQ-I_WkHMcwXBJa7IHkYu8CMfdNcZKnKsOrnHLpFs",
"did:example:123#_TKzHv2jFIyvdTGF1Dsgwngfdg3SH6TpDv0Ta1aOEkw",
"did:example:123#8wgRfY3sWmzoeAL-78-oALNvNj67ZlQxd1ss_NX1hZY",
"did:example:123#NjQ6Y_ZMj6IUK_XkgCDwtKHlNTUTVjEYOWZtxhp1n-E"
],
"assertionMethod": [
"did:example:123#_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A",
"did:example:123#4SZ-StXrp5Yd4_4rxHVTCYTHyt4zyPfN1fIuYsm6k3A",
"did:example:123#n4cQ-I_WkHMcwXBJa7IHkYu8CMfdNcZKnKsOrnHLpFs",
"did:example:123#_TKzHv2jFIyvdTGF1Dsgwngfdg3SH6TpDv0Ta1aOEkw",
"did:example:123#8wgRfY3sWmzoeAL-78-oALNvNj67ZlQxd1ss_NX1hZY",
"did:example:123#NjQ6Y_ZMj6IUK_XkgCDwtKHlNTUTVjEYOWZtxhp1n-E"
],
"capabilityDelegation": [
"did:example:123#_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A",
"did:example:123#4SZ-StXrp5Yd4_4rxHVTCYTHyt4zyPfN1fIuYsm6k3A",
"did:example:123#n4cQ-I_WkHMcwXBJa7IHkYu8CMfdNcZKnKsOrnHLpFs",
"did:example:123#_TKzHv2jFIyvdTGF1Dsgwngfdg3SH6TpDv0Ta1aOEkw",
"did:example:123#8wgRfY3sWmzoeAL-78-oALNvNj67ZlQxd1ss_NX1hZY",
"did:example:123#NjQ6Y_ZMj6IUK_XkgCDwtKHlNTUTVjEYOWZtxhp1n-E"
],
"capabilityInvocation": [
"did:example:123#_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A",
"did:example:123#4SZ-StXrp5Yd4_4rxHVTCYTHyt4zyPfN1fIuYsm6k3A",
"did:example:123#n4cQ-I_WkHMcwXBJa7IHkYu8CMfdNcZKnKsOrnHLpFs",
"did:example:123#_TKzHv2jFIyvdTGF1Dsgwngfdg3SH6TpDv0Ta1aOEkw",
"did:example:123#8wgRfY3sWmzoeAL-78-oALNvNj67ZlQxd1ss_NX1hZY",
"did:example:123#NjQ6Y_ZMj6IUK_XkgCDwtKHlNTUTVjEYOWZtxhp1n-E"
]
}
The cryptographic material used to represent a linked data proof is called the proof type.
This suite relies on detached digital signatures represented using [RFC7797].
The verificationMethod
property of the proof SHOULD be
a URI. Dereferencing the verificationMethod
SHOULD
result in an object of type
JsonWebKey2020.
The type
property of the proof MUST be
JsonWebSignature2020.
The created
property of the proof MUST be an
[ISO_8601] formated date string.
The proofPurpose
property of the proof MUST be a
string, and SHOULD match the verification relationship expressed by
the verification method controller
.
The jws
property of the proof MUST be a detached JWS
produced according to [RFC7797].
The header of the detached JWS MUST look like this:
{"b64":false,"crit":["b64"],"alg":"PS256"}
where alg
is a value registered in [IANA_JOSE]
AND is present in the supported algorithms table of this suite.
The following test vectors are provided to assist with implementers.
{
"seed_0": "9b937b81322d816cfab9d5a3baacc9b2a5febe4b149f126b3630f93a29527017"
}
{
"keypair_0": {
"id": "#ovsDKYBjFemIy8DVhc-w2LSi8CvXMw2AYDzHj04yxkc",
"type": "JsonWebKey2020",
"controller": "did:key:z6Mkf5rGMoatrSj1f4CyvuHBeXJELe9RPdzo2PKGNCKVtZxP",
"publicKeyJwk": {
"kty": "OKP",
"crv": "Ed25519",
"x": "CV-aGlld3nVdgnhoZK0D36Wk-9aIMlZjZOK2XhPMnkQ"
},
"privateKeyJwk": {
"kty": "OKP",
"crv": "Ed25519",
"x": "CV-aGlld3nVdgnhoZK0D36Wk-9aIMlZjZOK2XhPMnkQ",
"d": "m5N7gTItgWz6udWjuqzJsqX-vksUnxJrNjD5OilScBc"
}
},
"keypair_1": {
"id": "#zaS0k3zk2KpT4NqqpdUA1YD0JVTOtQf3pNoKDI-wes0",
"type": "JsonWebKey2020",
"controller": "did:key:zQ3shP2mWsZYWgvgM11nenXRTx9L1yiJKmkf9dfX7NaMKb1pX",
"publicKeyJwk": {
"kty": "EC",
"crv": "secp256k1",
"x": "GBMxavme-AfIVDKqI6WBJ4V5wZItsxJ9muhxPByllHQ",
"y": "SChlfVBhTXG_sRGc9ZdFeCYzI3Kbph3ivE12OFVk4jo"
},
"privateKeyJwk": {
"kty": "EC",
"crv": "secp256k1",
"x": "GBMxavme-AfIVDKqI6WBJ4V5wZItsxJ9muhxPByllHQ",
"y": "SChlfVBhTXG_sRGc9ZdFeCYzI3Kbph3ivE12OFVk4jo",
"d": "m5N7gTItgWz6udWjuqzJsqX-vksUnxJrNjD5OilScBc"
}
},
"keypair_2": {
"id": "#zwlFQYyCqQXZ3nzpxkxJFxlpGU2l8LZQ9gxIxDdEhuY",
"type": "JsonWebKey2020",
"controller": "did:key:zUewtYk1yGS3SWp7kxrFK3DZRHMFbGEnrgFrqsi6hG8Z7EpRzbMP7d5y49HhrUv4tgV4DHCSoQUtF1NRNe43bymdi7K91PkwEGJRR4jv4Vb2mu2ZcBJXbw3d35JfqsVeLcwXFUi",
"publicKeyJwk": {
"kty": "EC",
"crv": "P-384",
"x": "eQbMauiHc9HuiqXT894gW5XTCrOpeY8cjLXAckfRtdVBLzVHKaiXAAxBFeVrSB75",
"y": "YOjxhMkdH9QnNmGCGuGXJrjAtk8CQ1kTmEEi9cg2R9ge-zh8SFT1Xu6awoUjK5Bv"
},
"privateKeyJwk": {
"kty": "EC",
"crv": "P-384",
"x": "eQbMauiHc9HuiqXT894gW5XTCrOpeY8cjLXAckfRtdVBLzVHKaiXAAxBFeVrSB75",
"y": "YOjxhMkdH9QnNmGCGuGXJrjAtk8CQ1kTmEEi9cg2R9ge-zh8SFT1Xu6awoUjK5Bv",
"d": "dXghMAzYZmv46SNRuxmfDIuAlv7XIhvlkPzW3vXsopB1ihWp47tx0hqjZmYO6fJa"
}
}
}
{
"message_0": "hello world"
}
{
"signature_0": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..v_Tni1_9lPQsS52GOnCMTFp7vDRjZIcj3pmuY1mF9W7nMAH94DpGecNwdFsXrz09n9bDTd8gJFqXWZeWIGvUAA",
"signature_1": "eyJhbGciOiJFUzI1NksiLCJiNjQiOmZhbHNlLCJjcml0IjpbImI2NCJdfQ..dsgrLHXb5-VsUKVop4JJyO9dkFvJKRVNeOcEDD9nBAl3MqzJrJYfEfL8wArG-9ZjL12UD8btrJljZ7_C8p51mA"
}
{
"issuer_0": {
"@context": [
"https://www.w3.org/ns/did/v1",
"https://w3id.org/security/suites/jws-2020/v1",
{
"@base": "https://example.com/issuer/123"
}
],
"id": "https://example.com/issuer/123",
"publicKey": [
{
"id": "#ovsDKYBjFemIy8DVhc-w2LSi8CvXMw2AYDzHj04yxkc",
"type": "JsonWebKey2020",
"controller": "https://example.com/issuer/123",
"publicKeyJwk": {
"kty": "OKP",
"crv": "Ed25519",
"x": "CV-aGlld3nVdgnhoZK0D36Wk-9aIMlZjZOK2XhPMnkQ"
}
}
],
"assertionMethod": ["#ovsDKYBjFemIy8DVhc-w2LSi8CvXMw2AYDzHj04yxkc"]
}
}
{
"vc_template_0": {
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1",
"https://w3id.org/security/suites/jws-2020/v1"
],
"id": "http://example.gov/credentials/3732",
"type": ["VerifiableCredential", "UniversityDegreeCredential"],
"issuer": { "id": "did:example:123" },
"issuanceDate": "2020-03-10T04:24:12.164Z",
"credentialSubject": {
"id": "did:example:456",
"degree": {
"type": "BachelorDegree",
"name": "Bachelor of Science and Arts"
}
}
},
"vc_0": {
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1",
"https://w3id.org/security/suites/jws-2020/v1"
],
"id": "http://example.gov/credentials/3732",
"type": ["VerifiableCredential", "UniversityDegreeCredential"],
"issuer": {
"id": "https://example.com/issuer/123"
},
"issuanceDate": "2020-03-10T04:24:12.164Z",
"credentialSubject": {
"id": "did:example:456",
"degree": {
"type": "BachelorDegree",
"name": "Bachelor of Science and Arts"
}
},
"proof": {
"type": "JsonWebSignature2020",
"created": "2019-12-11T03:50:55Z",
"jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..MJ5GwWRMsadCyLNXU_flgJtsS32584MydBxBuygps_cM0sbU3abTEOMyUvmLNcKOwOBE1MfDoB1_YY425W3sAg",
"proofPurpose": "assertionMethod",
"verificationMethod": "https://example.com/issuer/123#ovsDKYBjFemIy8DVhc-w2LSi8CvXMw2AYDzHj04yxkc"
}
}
}
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY, MUST, RECOMMENDED, and SHOULD in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
A conforming document is any concrete expression of the data model that complies with the normative statements in this specification. Specifically, all relevant normative statements in Sections 2. Terminology and 3. Suite Definition of this document MUST be enforced.
A conforming processor
is any algorithm realized as software and/or
hardware that generates or consumes a conforming document. Conforming
processors MUST produce errors when non-conforming documents are consumed.
This document also contains examples that contain JSON and JSON-LD content.
Some of these examples contain characters that are invalid JSON, such as
inline comments (//
) and the use of ellipsis (...
)
to denote information that adds little value to the example. Implementers are
cautioned to remove this content if they desire to use the information as
valid JSON or JSON-LD.
The following section describes security considerations that developers implementing this specification should be aware of in order to create secure software.
This specification relies on URDNA2015, please review [RDF-DATASET-NORMALIZATION].
Referenced in: