From aaf00d51102e2a0ec6f32ade020f99981d0071d6 Mon Sep 17 00:00:00 2001 From: Oliver Terbu Date: Mon, 27 Nov 2023 16:12:20 +1300 Subject: [PATCH 1/6] fix: renamted JWT issuer metadata to JWT VC issuer metadata --- draft-ietf-oauth-sd-jwt-vc.md | 56 +++++++++++++++++------------------ 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/draft-ietf-oauth-sd-jwt-vc.md b/draft-ietf-oauth-sd-jwt-vc.md index 894abdf3..96719c78 100644 --- a/draft-ietf-oauth-sd-jwt-vc.md +++ b/draft-ietf-oauth-sd-jwt-vc.md @@ -327,7 +327,7 @@ A recipient of an SD-JWT VC MUST apply the following rules to validate that the verification key for the Issuer-signed JWT corresponds to the `iss` value: - JWT Issuer Metadata: If a recipient supports JWT Issuer Metadata and if the `iss` value contains an HTTPS URI, the recipient MUST -obtain the public key using JWT Issuer Metadata as defined in (#jwt-issuer-metadata). +obtain the public key using JWT Issuer Metadata as defined in (#jwt-vc-issuer-metadata). - X.509 Certificates: If the recipient supports X.509 Certificates, the recipient MUST obtain the public key from the leaf X.509 certificate defined by the `x5c` JWT header parameters of the Issuer-signed JWT and validate the X.509 certificate chain in the following cases: - If the `iss` value contains a DNS name encoded as a URI using the DNS URI scheme [@RFC4501], the DNS name MUST match a `dNSName` Subject Alternative Name (SAN) [@RFC5280] entry of the leaf certificate. @@ -339,30 +339,30 @@ Separate specifications or ecosystem regulations MAY define rules complementing If a recipient cannot validate that the public verification key corresponds to the `iss` value of the Issuer-signed JWT, the SD-JWT VC MUST be rejected. -# JWT Issuer Metadata {#jwt-issuer-metadata} +# JWT VC Issuer Metadata {#jwt-vc-issuer-metadata} -This specification defines the JWT Issuer Metadata to retrieve the JWT Issuer -Metadata configuration of the JWT Issuer of the JWT. The JWT Issuer is -identified by the `iss` claim in the JWT. Use of the JWT Issuer Metadata +This specification defines the JWT VC Issuer Metadata to retrieve the JWT VC +Issuer Metadata configuration of the Issuer of the SD-JWT VC. The Issuer +is identified by the `iss` claim in the JWT. Use of the JWT VC Issuer Metadata is OPTIONAL. -JWT Issuers publishing JWT Issuer Metadata MUST make a JWT Issuer Metadata +Issuers publishing JWT VC Issuer Metadata MUST make a JWT VC Issuer Metadata configuration available at the path formed by concatenating the string -`/.well-known/jwt-issuer` to the `iss` claim value in the JWT. The `iss` MUST +`/.well-known/jwt-vc-issuer` to the `iss` claim value in the JWT. The `iss` MUST be a case-sensitive URL using the HTTPS scheme that contains scheme, host and, optionally, port number and path components, but no query or fragment components. -## JWT Issuer Metadata Request +## JWT VC Issuer Metadata Request -A JWT Issuer Metadata configuration MUST be queried using an HTTP `GET` request -at the path defined in (#jwt-issuer-metadata). +A JWT VC Issuer Metadata configuration MUST be queried using an HTTP `GET` request +at the path defined in (#jwt-vc-issuer-metadata). -The following is a non-normative example of a HTTP request for the JWT Issuer +The following is a non-normative example of a HTTP request for the JWT VC Issuer Metadata configuration when `iss` is set to `https://example.com`: ``` -GET /.well-known/jwt-issuer HTTP/1.1 +GET /.well-known/jwt-vc-issuer HTTP/1.1 Host: example.com ``` @@ -370,44 +370,44 @@ If the `iss` value contains a path component, any terminating `/` MUST be removed before inserting `/.well-known/` and the well-known URI suffix between the host component and the path component. -The following is a non-normative example of a HTTP request for the JWT Issuer +The following is a non-normative example of a HTTP request for the JWT VC Issuer Metadata configuration when `iss` is set to `https://example.com/user/1234`: ``` -GET /.well-known/jwt-issuer/user/1234 HTTP/1.1 +GET /.well-known/jwt-vc-issuer/user/1234 HTTP/1.1 Host: example.com ``` -## JWT Issuer Metadata Response +## JWT VC Issuer Metadata Response -A successful response MUST use the `200 OK HTTP` and return the JWT Issuer +A successful response MUST use the `200 OK HTTP` and return the JWT VC Issuer Metadata configuration using the `application/json` content type. An error response uses the applicable HTTP status code value. -This specification defines the following JWT Issuer Metadata configuration +This specification defines the following JWT VC Issuer Metadata configuration parameters: * `issuer` - REQUIRED. The JWT Issuer identifier, which MUST be identical to the `iss` + REQUIRED. The Issuer identifier, which MUST be identical to the `iss` value in the JWT. * `jwks_uri` - * OPTIONAL. URL string referencing the JWT Issuer's JSON Web Key (JWK) Set -[@RFC7517] document which contains the JWT Issuer's public keys. The value of + * OPTIONAL. URL string referencing the Issuer's JSON Web Key (JWK) Set +[@RFC7517] document which contains the Issuer's public keys. The value of this field MUST point to a valid JWK Set document. * `jwks` - * OPTIONAL. JWT Issuer's JSON Web Key Set [@RFC7517] document value, which -contains the JWT Issuer's public keys. The value of this field MUST be a JSON + * OPTIONAL. Issuer's JSON Web Key Set [@RFC7517] document value, which +contains the Issuer's public keys. The value of this field MUST be a JSON object containing a valid JWK Set. -JWT Issuer Metadata MUST include either `jwks_uri` or `jwks` in their JWT +JWT VC Issuer Metadata MUST include either `jwks_uri` or `jwks` in their JWT VC Issuer Metadata, but not both. It is RECOMMENDED that the JWT contains a `kid` JWT header parameter that can be used to lookup the public key in the JWK Set included by value or referenced -in the JWT Issuer Metadata. +in the JWT VC Issuer Metadata. -The following is a non-normative example of a JWT Issuer Metadata configuration +The following is a non-normative example of a JWT VC Issuer Metadata configuration including `jwks`: ``` @@ -431,7 +431,7 @@ including `jwks`: } ``` -The following is a non-normative example of a JWT Issuer Metadata +The following is a non-normative example of a JWT VC Issuer Metadata configuration including `jwks_uri`: ``` @@ -441,9 +441,9 @@ configuration including `jwks_uri`: } ``` -Additional JWT Issuer Metadata configuration parameters MAY also be used. +Additional JWT VC Issuer Metadata configuration parameters MAY also be used. -## JWT Issuer Metadata Validation +## JWT VC Issuer Metadata Validation The `issuer` value returned MUST be identical to the `iss` value of the JWT. If these values are not identical, the data contained in the response MUST NOT be From 4aa7dcf3e1606d35e92e14eea7e95d2577c71883 Mon Sep 17 00:00:00 2001 From: Oliver Terbu Date: Mon, 27 Nov 2023 16:14:39 +1300 Subject: [PATCH 2/6] fix: moved JWT VC issuer metadata section to the end of the spec --- draft-ietf-oauth-sd-jwt-vc.md | 58 +++++++++++++++++------------------ 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/draft-ietf-oauth-sd-jwt-vc.md b/draft-ietf-oauth-sd-jwt-vc.md index 96719c78..f9080d7b 100644 --- a/draft-ietf-oauth-sd-jwt-vc.md +++ b/draft-ietf-oauth-sd-jwt-vc.md @@ -339,6 +339,35 @@ Separate specifications or ecosystem regulations MAY define rules complementing If a recipient cannot validate that the public verification key corresponds to the `iss` value of the Issuer-signed JWT, the SD-JWT VC MUST be rejected. +# Presenting Verifiable Credentials + +This section defines encoding, validation and processing rules for presentations +of SD-JWT VCs. + +## Key Binding JWT + +If the presentation of the SD-JWT VC includes a Key Binding JWT, the Key Binding +JWT MUST adhere to the rules defined in Section 5.3 of +[@!I-D.ietf-oauth-selective-disclosure-jwt]. + +The Key Binding JWT MAY include addtional claims which, when not understood, MUST +be ignored by the Verifier. + +## Examples + +The following is a non-normative example of a presentation of the SD-JWT shown +above including a Key Binding JWT: + +<{{examples/01/sd_jwt_presentation.txt}} + +In this presentation, the Holder provides only the Disclosure for the claim +`address`. Other claims are not disclosed to the Verifier. + +The following example shows a presentation of a (different) SD-JWT without a +Key Binding JWT: + +<{{examples/02/sd_jwt_presentation.txt}} + # JWT VC Issuer Metadata {#jwt-vc-issuer-metadata} This specification defines the JWT VC Issuer Metadata to retrieve the JWT VC @@ -449,35 +478,6 @@ The `issuer` value returned MUST be identical to the `iss` value of the JWT. If these values are not identical, the data contained in the response MUST NOT be used. -# Presenting Verifiable Credentials - -This section defines encoding, validation and processing rules for presentations -of SD-JWT VCs. - -## Key Binding JWT - -If the presentation of the SD-JWT VC includes a Key Binding JWT, the Key Binding -JWT MUST adhere to the rules defined in Section 5.3 of -[@!I-D.ietf-oauth-selective-disclosure-jwt]. - -The Key Binding JWT MAY include addtional claims which, when not understood, MUST -be ignored by the Verifier. - -## Examples - -The following is a non-normative example of a presentation of the SD-JWT shown -above including a Key Binding JWT: - -<{{examples/01/sd_jwt_presentation.txt}} - -In this presentation, the Holder provides only the Disclosure for the claim -`address`. Other claims are not disclosed to the Verifier. - -The following example shows a presentation of a (different) SD-JWT without a -Key Binding JWT: - -<{{examples/02/sd_jwt_presentation.txt}} - # Security Considerations {#security-considerations} The Security Considerations in the SD-JWT specification From 85b8315783257d61a0df2730d76ba9d5932cf580 Mon Sep 17 00:00:00 2001 From: Oliver Terbu Date: Mon, 27 Nov 2023 16:18:41 +1300 Subject: [PATCH 3/6] fix: renamed jwt issuer to jwt vc issuer in example --- draft-ietf-oauth-sd-jwt-vc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft-ietf-oauth-sd-jwt-vc.md b/draft-ietf-oauth-sd-jwt-vc.md index f9080d7b..d895a1a0 100644 --- a/draft-ietf-oauth-sd-jwt-vc.md +++ b/draft-ietf-oauth-sd-jwt-vc.md @@ -466,7 +466,7 @@ configuration including `jwks_uri`: ``` { "issuer":"https://example.com", - "jwks_uri":"https://jwt-issuer.example.org/my_public_keys.jwks" + "jwks_uri":"https://jwt-vc-issuer.example.org/my_public_keys.jwks" } ``` From 9e5c570ca426280efbedc50e934ab29c7de20440 Mon Sep 17 00:00:00 2001 From: Oliver Terbu Date: Mon, 27 Nov 2023 16:21:39 +1300 Subject: [PATCH 4/6] fix: renamed jwt issuer metadata to jwt vc issuer metadata in security considerations --- draft-ietf-oauth-sd-jwt-vc.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/draft-ietf-oauth-sd-jwt-vc.md b/draft-ietf-oauth-sd-jwt-vc.md index d895a1a0..e2c3950e 100644 --- a/draft-ietf-oauth-sd-jwt-vc.md +++ b/draft-ietf-oauth-sd-jwt-vc.md @@ -487,12 +487,12 @@ account when using SD-JWT VCs: ## Server-Side Request Forgery -The JWT Issuer Metadata configuration is retrieved from the JWT Issuer by the +The JWT VC Issuer Metadata configuration is retrieved from the JWT VC Issuer by the Holder or Verifier. Similar to other metadata endpoints, the URL for the retrieval MUST be considered an untrusted value and could be a vector for Server-Side Request Forgery (SSRF) attacks. -Before making a request to the JWT Issuer Metadata endpoint, the Holder or +Before making a request to the JWT VC Issuer Metadata endpoint, the Holder or Verifier MUST validate the URL to ensure that it is a valid HTTPS URL and that it does not point to internal resources. This requires, in particular, ensuring that the host part of the URL does not address an internal service (by IP @@ -502,7 +502,7 @@ resolved DNS name does not point to an internal IPv4 or IPv6 address. When retrieving the metadata, the Holder or Verifier MUST ensure that the request is made in a time-bound and size-bound manner to prevent denial of service attacks. The Holder or Verifier MUST also ensure that the response is a -valid JWT Issuer Metadata configuration document before processing it. +valid JWT VC Issuer Metadata configuration document before processing it. Additional considerations can be found in [@OWASP_SSRF]. From 5cb828951ba9981fd943e48d3ed70fd92a6d913d Mon Sep 17 00:00:00 2001 From: Oliver Terbu Date: Mon, 27 Nov 2023 16:23:27 +1300 Subject: [PATCH 5/6] fix: added renaming to document history --- draft-ietf-oauth-sd-jwt-vc.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/draft-ietf-oauth-sd-jwt-vc.md b/draft-ietf-oauth-sd-jwt-vc.md index e2c3950e..1d5ebe8d 100644 --- a/draft-ietf-oauth-sd-jwt-vc.md +++ b/draft-ietf-oauth-sd-jwt-vc.md @@ -552,7 +552,7 @@ resolution of the key material to verify the Issuer-signed JWT requires the Veri to phone home to the Issuer. For example, a malicious Issuer could generate a unique value for the Issuer identifier -per Holder, e.g., `https://example.com/issuer/holder-1234` and host the JWT Issuer Metadata. +per Holder, e.g., `https://example.com/issuer/holder-1234` and host the JWT VC Issuer Metadata. The Verifier would create a HTTPS GET request to the Holder-specific well-known URI when the SD-JWT VC is verified. This would allow the malicious Issuer to keep track where and how often the SD-JWT VC was used. @@ -678,9 +678,11 @@ for their contributions (some of which substantial) to this draft and to the ini # Document History -02 + * Made specific rules for public verification key validation conditional * Finetuned rules for obtaining public verification key * Editorial changes +* Renamed JWT Issuer Metadata to JWT VC Issuer Metadata -01 From 50000a67c3638020882161e04a84ac50aa62d939 Mon Sep 17 00:00:00 2001 From: Oliver Terbu Date: Thu, 30 Nov 2023 10:15:52 +1300 Subject: [PATCH 6/6] fix: renamed metadata in verification key validation --- draft-ietf-oauth-sd-jwt-vc.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/draft-ietf-oauth-sd-jwt-vc.md b/draft-ietf-oauth-sd-jwt-vc.md index 1d5ebe8d..9d847fb3 100644 --- a/draft-ietf-oauth-sd-jwt-vc.md +++ b/draft-ietf-oauth-sd-jwt-vc.md @@ -326,8 +326,8 @@ specification. A recipient of an SD-JWT VC MUST apply the following rules to validate that the public verification key for the Issuer-signed JWT corresponds to the `iss` value: -- JWT Issuer Metadata: If a recipient supports JWT Issuer Metadata and if the `iss` value contains an HTTPS URI, the recipient MUST -obtain the public key using JWT Issuer Metadata as defined in (#jwt-vc-issuer-metadata). +- JWT VC Issuer Metadata: If a recipient supports JWT VC Issuer Metadata and if the `iss` value contains an HTTPS URI, the recipient MUST +obtain the public key using JWT VC Issuer Metadata as defined in (#jwt-vc-issuer-metadata). - X.509 Certificates: If the recipient supports X.509 Certificates, the recipient MUST obtain the public key from the leaf X.509 certificate defined by the `x5c` JWT header parameters of the Issuer-signed JWT and validate the X.509 certificate chain in the following cases: - If the `iss` value contains a DNS name encoded as a URI using the DNS URI scheme [@RFC4501], the DNS name MUST match a `dNSName` Subject Alternative Name (SAN) [@RFC5280] entry of the leaf certificate.