+ A conforming JWS document is one that conforms to all of the + "MUST" statements in Section . +
++ A conforming JWS issuer implementation produces + [=conforming JWS documents=] and MUST secure them as described in Section + . +
+ A conforming JWS verifier implementation verifies + [=conforming JWS documents=] as described in Section + . +
++ A conforming SD-JWT document is one that conforms to all of the + "MUST" statements in Section . +
++ A conforming SD-JWT issuer implementation produces + [=conforming SD-JWT documents=] and MUST secure them as described in Section + . +
+ A conforming SD-JWT verifier implementation verifies + [=conforming SD-JWT documents=] as described in Section + . +
++ A conforming COSE document is one that conforms to all of the + "MUST" statements in Section . +
++ A conforming COSE issuer implementation produces + [=conforming COSE documents=] and MUST secure them as described in Section + . +
++ A conforming COSE verifier implementation verifies + [=conforming COSE documents=] as described in Section + . +
+The describes
+ the approach taken by JSON Web Tokens to secure JWT Claims Sets as applying an
+ external proof.
+
The normative statements in Securing
+ Mechanisms apply to securing
+ application/vc-ld+jwt and
+ application/vp-ld+jwt,
+ application/vc-ld+sd-jwt and
+ application/vp-ld+sd-jwt,
+ as well as
+ application/vc-ld+cose and
+ application/vp-ld+cose.
+
+ JSON Web Token implementers are advised to review Implementation + Requirements. +
+
+ Issuers, Holders, and Verifiers MUST understand the
+ JSON Web Token header parameter setting
+ "alg": "none" when securing [[VC-DATA-MODEL-2.0]]
+ with JSON Web Tokens.
+ When content types from [[VC-DATA-MODEL-2.0]] are secured using
+ JSON Web Tokens, the header parameter setting "alg": "none",
+ MUST be used to communicate that a JWT Claims Set that comprises a
+ Verifiable Credential or a Verifiable Presentation has no
+ integrity protection.
+ When a JWT Claims Set that comprises a Verifiable Credential or a
+ Verifiable Presentation contains
+ proof, and the JSON Web Token header contains
+ "alg": "none", the JWT Claims Set MUST be considered to
+ have no integrity protection.
+
+ Verifiable Credentials and Verifiable Presentations are not
+ required to be secured nor integrity protected, nor to contain a
+ proof member.
+
+ Issuers, Holders, and Verifiers of Verifiable Credentials and/or + Verifiable Presentations MUST ignore all, and MUST NOT produce any, + JWT Claims Sets that have no integrity protection. +
+
+ The JWT Claim Names vc and vp
+ MUST NOT be present in any JWT Claims Set that comprises a
+ Verifiable Credential or a Verifiable Presentation.
+
- When iss is absent and the issuer - is identified as a DID Subject, - the kid MUST be an absolute DID URL. -
-
-{
- "issuer": "did:example:123"
- // ...
-}
-
-
-{
- "alg": "ES384",
- "kid": "did:example:123#key-456
-}
-
- - When iss is absent, and the holder - is identified as a DID Subject, - the kid MUST be an absolute DID URL. -
-
-{
- "holder": "did:example:abc"
- // ...
-}
-
-
-{
- "alg": "ES384",
- "kid": "did:example:abc#key-456
-}
-
-
-
- - When iss is absent, and the issuer is - identified as a [[URL]], - the kid MUST be an absolute [[URL]] to a verification method listed in a controller document. -
- -
-{
- "issuer": {
- "id": "https://university.example/issuers/565049"
- }
- // ...
-}
-
-
-{
- "alg": "ES384",
- "kid": "https://university.example/issuers/565049#key-123
-}
-
-
- - When the holder is identified as a [[URL]], - and iss is absent, - the kid MUST be an absolute [[URL]] to a verification method listed in a controller document. -
-
-{
- "holder": {
- "id": "https://university.example/issuers/565049"
- }
- // ...
-}
-
-
-{
- "alg": "ES384",
- "kid": "https://university.example/issuers/565049#key-123
-}
-
-
-
-
- - When iss is present and is a [[URL]], - the kid MUST match a key discovered via a JWT Issuer Metadata Request, - as described in [[SD-JWT-VC]]. -
- -- This normative statement depends on the IETF OAuth working group draft [[SD-JWT-VC]]. - This feature is at risk and will be removed from the specification if at least - two independent, interoperable implementations are not demonstrated. -
-To complete the verification process, a verifier needs to obtain the cryptographic keys used to @@ -963,7 +965,7 @@
kid is present in the JOSE Header
or the COSE Header,
a verifier can use this parameter
- as a hint indicating which key was used to secure the verifiable credential, when performing a
+ as a hint indicating which key was used to secure the [=verifiable credential=], when performing a
verification process as defined in RFC7515.
@@ -1010,94 +1012,103 @@ - Use of a proof-of-possession key provided by the Holder to the Issuer - to establish a cryptographic binding to the Holder in the Verifiable Credential - that is verifiable by the Verifier in the Verifiable Presentation is RECOMMENDED. + Use of a proof-of-possession key provided by the [=Holder=] to the [=Issuer=] + to establish a cryptographic binding to the [=Holder=] in the [=Verifiable Credential=] + that is verifiable by the [=Verifier=] in the [=Verifiable Presentation=] is RECOMMENDED.
+ When the [=issuer=] value is a URL using the HTTPS scheme, + [=issuer=] metadata including the [=issuer=]'s [=public keys=] can be retrieved using the mechanism + defined in [[SD-JWT-VC]]. +
-- When the issuer value is a URL using the HTTPS scheme, - issuer metadata including the issuer's public keys can be retrieved using the mechanism - defined in [[SD-JWT-VC]]. -
++ This normative statement depends on the IETF OAuth working group draft [[SD-JWT-VC]]. + This feature is at risk and will be removed from the specification if at least + two independent, interoperable implementations are not demonstrated. +
-- This normative statement depends on the IETF OAuth working group draft [[SD-JWT-VC]]. - This feature is at risk and will be removed from the specification if at least - two independent, interoperable implementations are not demonstrated. -
-
+ {
+ "alg": "EdDSA",
+ "kid": "https://vendor.example/issuers/42/keys/urn:ietf:params:oauth:jwk-thumbprint:sha-256:NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs"
+ }
+
When using [=controller documents=] with this specification, the following requirements apply.
The value of the `type` property of the verification method MUST be JsonWebKey.
-
- Verification material MUST be expressed in the publicKeyJwk property
- of a JsonWebKey. This key material is retrieved based on hints in the
- JOSE or COSE message envelopes, such as kid or iss. At
- the time of writing, there is no standard way to retrieve a public key in JWK format
- from a DID URL or controller document.
-
+ Verification material MUST be expressed in the publicKeyJwk property
+ of a JsonWebKey. This key material is retrieved based on hints in the
+ JOSE or COSE message envelopes, such as kid or iss. At
+ the time of writing, there is no standard way to retrieve a public key in JWK format
+ from a DID URL or [=controller document=].
+
+ When iss is absent, and the issuer is + identified as a [[URL]], + the kid MUST be an absolute [[URL]] to a + verification method listed in a [=controller document=] or + a DID Document. +
-- A conforming JWS document is one that conforms to all of the - "MUST" statements in Section . -
-- A conforming JWS issuer implementation produces - [=conforming JWS documents=] and MUST secure them as described in Section - . -
- A conforming JWS verifier implementation verifies - [=conforming JWS documents=] as described in Section - . -
-- A conforming SD-JWT document is one that conforms to all of the - "MUST" statements in Section . -
-- A conforming SD-JWT issuer implementation produces - [=conforming SD-JWT documents=] and MUST secure them as described in Section - . -
- A conforming SD-JWT verifier implementation verifies - [=conforming SD-JWT documents=] as described in Section - . -
-- A conforming COSE document is one that conforms to all of the - "MUST" statements in Section . -
-- A conforming COSE issuer implementation produces - [=conforming COSE documents=] and MUST secure them as described in Section - . -
-- A conforming COSE verifier implementation verifies - [=conforming COSE documents=] as described in Section - . -
+
+ When using [[URL]] identifiers, the kid is RECOMMENDED to be
+ an absolute [[URL]] that includes a JWK Thumbprint URI
+ as defined in [[RFC7638]]. For example:
+ https://vendor.example/issuers/42/keys/urn:ietf:params:oauth:jwk-thumbprint:sha-256:NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs
+
+{
+ "issuer": {
+ "id": "https://university.example/issuers/565049"
+ }
+ // ...
+}
+
+
+{
+ "alg": "ES384",
+ "kid": "https://university.example/issuers/565049#key-123
+}
+
+
+ + When the holder is + identified as a [[URL]], + and iss is absent, + the kid MUST be an absolute [[URL]] to a + verification method listed in a [=controller document=]. +
+
+{
+ "holder": {
+ "id": "https://university.example/issuers/565049"
+ }
+ // ...
+}
+
+
+{
+ "alg": "ES384",
+ "kid": "https://university.example/issuers/565049#key-123
+}
+
enveloping proof.
- This specification defines how to secure different data structures
+ This specification defines how to secure different data structures
using various enveloping proof mechanisms:
@@ -1187,7 +1198,7 @@
- This specification uses Selective Disclosure for JWTs (SD-JWT) as + This specification uses Selective Disclosure for JWTs (SD-JWT) as defined in the IETF draft [[SD-JWT]]. Implementers should refer to this draft for the full details of the SD-JWT format and processing requirements. @@ -1206,12 +1217,11 @@
vp-ld+jwt
inputDocument: the verifiable credential secured as a JWT [[RFC7519]]
+ inputDocument: the [=verifiable credential=] secured as a JWT [[RFC7519]]
- Upon receipt of the verifiable credential or presentation secured as a JWT - [[RFC7519]], the holder or verifier follows this algorithm: + Upon receipt of the [=verifiable credential=] or [=verifiable presentation=] secured as a JWT + [[RFC7519]], the [=holder=] or [=verifier=] follows this algorithm:
- Upon receipt of the verifiable credential or presentation secured with + Upon receipt of the [=verifiable credential=] or [=verifiable presentation=] secured with [[SD-JWT]], the holder or verifier follows this algorithm:
vp-ld+cose
inputDocument: the verifiable credential or verifiable presentation
+ inputDocument: the [=verifiable credential=] or [=verifiable presentation=]
secured with [[[RFC9052]]]
- Upon receipt of the verifiable credential or presentation secured with - [[RFC9052]], the holder or verifier follows this algorithm: + Upon receipt of the [=verifiable credential=] or [=verifiable presentation=] secured with + [[RFC9052]], the [=holder=] or [=verifier=] follows this algorithm:
All claims expected for the typ MUST be present.
- All claims that are understood MUST be evaluated according the verifier's validation policies.
+ All claims that are understood MUST be evaluated according the [=verifier=]'s validation policies.
All claims that are not understood MUST be ignored.
- Based on the validation policy of the verifier, the type of credentials, and + Based on the validation policy of the verifier, the type of [=credentials=], and the type of securing mechanism, additional validation checks MAY be applied. - For example, dependencies between multiple credentials, ordering or timing - information associated with multiple credentials, and/or multiple presentations - could cause an otherwise valid credential or presentation to be considered + For example, dependencies between multiple [=credentials=], ordering or timing + information associated with multiple credentials, and/or multiple [=presentations=] + could cause an otherwise valid [=credential=] or [=presentation=] to be considered invalid.
+The Working Group thanks Orie Steele for his substantive intellectual and content +contributions to this specification. It wouldn't be the same without them. +
+