From b2f69ec42fef1c15533e657788b4a4b9a4457b16 Mon Sep 17 00:00:00 2001 From: Kristina Yasuda Date: Tue, 18 Jun 2024 17:46:23 +0200 Subject: [PATCH 01/28] add transaction_data --- openid-4-verifiable-presentations-1_0.md | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 698ba286..2ec3e52b 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -272,7 +272,13 @@ A public key to be used by the Wallet as an input to the key agreement to encryp : OPTIONAL. A string determining the HTTP method to be used when the `request_uri` parameter is included in the same request. Two case-sensitive valid values are defined in this specification: `get` and `post`. If `request_uri_method` value is `get`, the Wallet MUST send the request to retrieve the Request Object using the HTTP GET method, i.e., as defined in [@RFC9101]. If `request_uri_method` value is `post`, a supporting Wallet MUST send the request using the HTTP POST method as detailed in (#request_uri_method_post). If the `request_uri_method` parameter is not present, the Wallet MUST process the `request_uri` parameter as defined in [@RFC9101]. Wallets not supporting the `post` method will send a GET request to the request URI (default behavior as defined in [@RFC9101]). `request_uri_method` parameter MUST NOT be present if a `request_uri` parameter is not present. If the Verifier set the `request_uri_method` parameter value to `post` and there is no other means to convey its capabilities to the Wallet, it SHOULD add the `client_metadata` parameter to the Authorization Request. -This enables the Wallet to assess the Verifier's capabilities, allowing it to transmit only the relevant capabilities through the `wallet_metadata` parameter in the Request URI POST request. If the Verifier uses the `client_id_scheme` parameter in the Request Object, it MUST also add the same `client_id_scheme` value in the Authorization Request. +This enables the Wallet to assess the Verifier's capabilities, allowing it to transmit only the relevant capabilities through the `wallet_metadata` parameter in the Request URI POST request. If the Verifier uses the `client_id_scheme` parameter in the Request Object, it MUST also add the same `client_id_scheme` value in the Authorization Request. + +`transaction_data`: +: OPTIONAL. Array of strings, where each string is a Base64url encoded object that contains a typed parameter set with details about the transaction that the Verifier is requesting the End-User to authorize. See (#transaction_data) for details. Each object consists of the following parameters: + +* `type`: REQUIRED. String that is the Identifier of the transaction data type and determines the allowable contents of the object that contains it. The specific values are out of scope of this specification. +* `input_descriptor_ids`: REQUIRED. Array of strings each pointing to an Input Descriptor that identifies a request for a Credential that the Verifier is requesting transaction data in a particular object to be bound to. The following additional considerations are given for pre-existing Authorization Request parameters: @@ -433,7 +439,7 @@ When the Verifier is sending a Request Object as defined in [@!RFC9101], the `au Note: "https://self-issued.me/v2" is a symbolic string and can be used as an `aud` Claim value even when this specification is used standalone, without SIOPv2. -## Verifier Metadata Management {#client_metadata_management} +## Verifier Metadata Management (Client Identifier schemes) {#client_metadata_management} The `client_id_scheme` enables deployments of this specification to use different mechanisms to obtain and validate metadata of the Verifier beyond the scope of [@!RFC6749]. The term `client_id_scheme` is used since the Verifier is acting as an OAuth 2.0 Client. @@ -746,6 +752,14 @@ The following is a non-normative example of the payload of the JWT used in the e <{{examples/response/jarm_jwt_vc_json_body.json}} +## Transaction Data {#transaction_data} + +Transaction data mechanism enables binding between the user identification/authentication and user’s authorization, for example to complete a payment transaction, or to sign specific document(s) using QES (Qualified Electronic Signatures). This is achieved by signing the transaction data used for user authorization with the user-controlled key used for proof of possession of the Credential being presented as a means for user identification/authentication. + +The Wallet that received `transaction_data` parameter in the request, MUST include in the response a `transaction_data` parameter defined below: + +* `transaction_data`: Array of hashes, where each hash is calculated using a hash function over the strings received in the `transaction_data` request parameter. Each hash value ensures the integrity of, and maps to, the respective transaction data object. Where in the response this parameter is included is defined by each Credential Format Profile, but it has to be included in the mechanism used for the proof of possession of the Credential that is signed using the user-controlled key. + ## Error Response The error response follows the rules as defined in [@!RFC6749], with the following additional clarifications: @@ -1749,6 +1763,8 @@ Setting `limit_disclosure` property defined in [@!DIF.PresentationExchange] to ` A non-normative example of the Authorization Response would look the same as in the examples of other Credential formats in this Annex. +`transaction_data` response parameter defined in (#transaction-data) MUST be included in the Key Binding JWT as a top level parameter. + The following is a non-normative example of the content of the `presentation_submission` parameter: <{{examples/response/ps_sd_jwt_vc.json}} From 7d47e4b2b940218ac28692a83d1a787fd055f341 Mon Sep 17 00:00:00 2001 From: Kristina Yasuda Date: Tue, 18 Jun 2024 17:55:21 +0200 Subject: [PATCH 02/28] add error codes --- openid-4-verifiable-presentations-1_0.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 2ec3e52b..4a0394d6 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -275,7 +275,7 @@ If the Verifier set the `request_uri_method` parameter value to `post` and there This enables the Wallet to assess the Verifier's capabilities, allowing it to transmit only the relevant capabilities through the `wallet_metadata` parameter in the Request URI POST request. If the Verifier uses the `client_id_scheme` parameter in the Request Object, it MUST also add the same `client_id_scheme` value in the Authorization Request. `transaction_data`: -: OPTIONAL. Array of strings, where each string is a Base64url encoded object that contains a typed parameter set with details about the transaction that the Verifier is requesting the End-User to authorize. See (#transaction_data) for details. Each object consists of the following parameters: +: OPTIONAL. Array of strings, where each string is a Base64url encoded object that contains a typed parameter set with details about the transaction that the Verifier is requesting the End-User to authorize. See (#transaction_data) for details. The Wallet MUST refuse to process any unknown transaction data type or transaction data not conforming to the respective type definition. Each object consists of the following parameters: * `type`: REQUIRED. String that is the Identifier of the transaction data type and determines the allowable contents of the object that contains it. The specific values are out of scope of this specification. * `input_descriptor_ids`: REQUIRED. Array of strings each pointing to an Input Descriptor that identifies a request for a Credential that the Verifier is requesting transaction data in a particular object to be bound to. @@ -760,7 +760,7 @@ The Wallet that received `transaction_data` parameter in the request, MUST inclu * `transaction_data`: Array of hashes, where each hash is calculated using a hash function over the strings received in the `transaction_data` request parameter. Each hash value ensures the integrity of, and maps to, the respective transaction data object. Where in the response this parameter is included is defined by each Credential Format Profile, but it has to be included in the mechanism used for the proof of possession of the Credential that is signed using the user-controlled key. -## Error Response +## Error Response {#error_response} The error response follows the rules as defined in [@!RFC6749], with the following additional clarifications: @@ -805,6 +805,14 @@ This document also defines the following additional error codes and error descri - The value of the `request_uri_method` request parameter is neither `get` nor `post` (case-sensitive). +`invalid_transaction_data`: + +- any of the following are true of the objects in the transaction_data structure: + - contains an unknown transaction data type value, + - is an object of known type but containing unknown fields, + - contains fields of the wrong type for the transaction data type, + - contains fields with invalid values for the transaction data type, or + - is missing required fields for the transaction data type. ## VP Token Validation From 1f15ab3fd07fe6b13e7b3a40a1836c93ea5ce92b Mon Sep 17 00:00:00 2001 From: Kristina <52878547+Sakurann@users.noreply.github.com> Date: Thu, 8 Aug 2024 05:40:35 -0700 Subject: [PATCH 03/28] update correct reference. Co-authored-by: Brian Campbell <71398439+bc-pi@users.noreply.github.com> --- openid-4-verifiable-presentations-1_0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 4a0394d6..de7d2d16 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -1771,7 +1771,7 @@ Setting `limit_disclosure` property defined in [@!DIF.PresentationExchange] to ` A non-normative example of the Authorization Response would look the same as in the examples of other Credential formats in this Annex. -`transaction_data` response parameter defined in (#transaction-data) MUST be included in the Key Binding JWT as a top level parameter. +`transaction_data` response parameter defined in (#transaction_data) MUST be included in the Key Binding JWT as a top level claim. The following is a non-normative example of the content of the `presentation_submission` parameter: From 76380c6141d4e6b164ef03d82d503c0704000f4f Mon Sep 17 00:00:00 2001 From: Kristina <52878547+Sakurann@users.noreply.github.com> Date: Tue, 13 Aug 2024 20:18:23 +0200 Subject: [PATCH 04/28] rename response parameter to tx_data_hashes Co-authored-by: Brian Campbell <71398439+bc-pi@users.noreply.github.com> --- openid-4-verifiable-presentations-1_0.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index de7d2d16..f566973e 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -756,9 +756,9 @@ The following is a non-normative example of the payload of the JWT used in the e Transaction data mechanism enables binding between the user identification/authentication and user’s authorization, for example to complete a payment transaction, or to sign specific document(s) using QES (Qualified Electronic Signatures). This is achieved by signing the transaction data used for user authorization with the user-controlled key used for proof of possession of the Credential being presented as a means for user identification/authentication. -The Wallet that received `transaction_data` parameter in the request, MUST include in the response a `transaction_data` parameter defined below: +The Wallet that received `transaction_data` parameter in the request, MUST include in the response a `tx_data_hashes` parameter defined below: -* `transaction_data`: Array of hashes, where each hash is calculated using a hash function over the strings received in the `transaction_data` request parameter. Each hash value ensures the integrity of, and maps to, the respective transaction data object. Where in the response this parameter is included is defined by each Credential Format Profile, but it has to be included in the mechanism used for the proof of possession of the Credential that is signed using the user-controlled key. +* `tx_data_hashes`: Array of hashes, where each hash is calculated using a hash function over the strings received in the `transaction_data` request parameter. Each hash value ensures the integrity of, and maps to, the respective transaction data object. Where in the response this parameter is included is defined by each Credential Format Profile, but it has to be included in the mechanism used for the proof of possession of the Credential that is signed using the user-controlled key. ## Error Response {#error_response} From 351bf764dc42980e64eebb95f16cc25e050d5780 Mon Sep 17 00:00:00 2001 From: Kristina <52878547+Sakurann@users.noreply.github.com> Date: Thu, 22 Aug 2024 17:06:04 +0200 Subject: [PATCH 05/28] Apply editorial suggestions from code review Co-authored-by: Daniel Fett --- openid-4-verifiable-presentations-1_0.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index f566973e..57425aea 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -277,7 +277,7 @@ This enables the Wallet to assess the Verifier's capabilities, allowing it to tr `transaction_data`: : OPTIONAL. Array of strings, where each string is a Base64url encoded object that contains a typed parameter set with details about the transaction that the Verifier is requesting the End-User to authorize. See (#transaction_data) for details. The Wallet MUST refuse to process any unknown transaction data type or transaction data not conforming to the respective type definition. Each object consists of the following parameters: -* `type`: REQUIRED. String that is the Identifier of the transaction data type and determines the allowable contents of the object that contains it. The specific values are out of scope of this specification. +* `type`: REQUIRED. String that is the Identifier of the transaction data type and determines the allowable contents of the object that contains it. The specific values are out of scope of this specification. It is RECOMMENDED to use collision-resistant names for `type` values. * `input_descriptor_ids`: REQUIRED. Array of strings each pointing to an Input Descriptor that identifies a request for a Credential that the Verifier is requesting transaction data in a particular object to be bound to. The following additional considerations are given for pre-existing Authorization Request parameters: @@ -754,7 +754,7 @@ The following is a non-normative example of the payload of the JWT used in the e ## Transaction Data {#transaction_data} -Transaction data mechanism enables binding between the user identification/authentication and user’s authorization, for example to complete a payment transaction, or to sign specific document(s) using QES (Qualified Electronic Signatures). This is achieved by signing the transaction data used for user authorization with the user-controlled key used for proof of possession of the Credential being presented as a means for user identification/authentication. +The transaction data mechanism enables a binding between the user's identification/authentication and the user’s authorization, for example to complete a payment transaction, or to sign specific document(s) using QES (Qualified Electronic Signatures). This is achieved by signing the transaction data used for user authorization with the user-controlled key used for proof of possession of the Credential being presented as a means for user identification/authentication. The Wallet that received `transaction_data` parameter in the request, MUST include in the response a `tx_data_hashes` parameter defined below: @@ -807,7 +807,7 @@ This document also defines the following additional error codes and error descri `invalid_transaction_data`: -- any of the following are true of the objects in the transaction_data structure: +- any of the following is true for at least one object in the transaction_data structure: - contains an unknown transaction data type value, - is an object of known type but containing unknown fields, - contains fields of the wrong type for the transaction data type, @@ -1771,7 +1771,7 @@ Setting `limit_disclosure` property defined in [@!DIF.PresentationExchange] to ` A non-normative example of the Authorization Response would look the same as in the examples of other Credential formats in this Annex. -`transaction_data` response parameter defined in (#transaction_data) MUST be included in the Key Binding JWT as a top level claim. +The `transaction_data` response parameter defined in (#transaction_data) MUST be included in the Key Binding JWT as a top level claim. The following is a non-normative example of the content of the `presentation_submission` parameter: From 923aabd37531645cecf197d5a406f1a9878e0201 Mon Sep 17 00:00:00 2001 From: Kristina <52878547+Sakurann@users.noreply.github.com> Date: Thu, 22 Aug 2024 17:24:04 +0200 Subject: [PATCH 06/28] renaming to requested_credential_ids --- openid-4-verifiable-presentations-1_0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 57425aea..123fb5a1 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -278,7 +278,7 @@ This enables the Wallet to assess the Verifier's capabilities, allowing it to tr : OPTIONAL. Array of strings, where each string is a Base64url encoded object that contains a typed parameter set with details about the transaction that the Verifier is requesting the End-User to authorize. See (#transaction_data) for details. The Wallet MUST refuse to process any unknown transaction data type or transaction data not conforming to the respective type definition. Each object consists of the following parameters: * `type`: REQUIRED. String that is the Identifier of the transaction data type and determines the allowable contents of the object that contains it. The specific values are out of scope of this specification. It is RECOMMENDED to use collision-resistant names for `type` values. -* `input_descriptor_ids`: REQUIRED. Array of strings each pointing to an Input Descriptor that identifies a request for a Credential that the Verifier is requesting transaction data in a particular object to be bound to. +* `requested_credential_ids`: REQUIRED. Array of strings each pointing to an Input Descriptor that identifies a request for a Credential that the Verifier is requesting transaction data in a particular object to be bound to. The following additional considerations are given for pre-existing Authorization Request parameters: From cc55aa335f31ca1a21d27ec010e8a120c400b375 Mon Sep 17 00:00:00 2001 From: Kristina <52878547+Sakurann@users.noreply.github.com> Date: Wed, 11 Sep 2024 15:10:50 +0200 Subject: [PATCH 07/28] reflect WG feedback --- openid-4-verifiable-presentations-1_0.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 123fb5a1..03ff8794 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -275,10 +275,10 @@ If the Verifier set the `request_uri_method` parameter value to `post` and there This enables the Wallet to assess the Verifier's capabilities, allowing it to transmit only the relevant capabilities through the `wallet_metadata` parameter in the Request URI POST request. If the Verifier uses the `client_id_scheme` parameter in the Request Object, it MUST also add the same `client_id_scheme` value in the Authorization Request. `transaction_data`: -: OPTIONAL. Array of strings, where each string is a Base64url encoded object that contains a typed parameter set with details about the transaction that the Verifier is requesting the End-User to authorize. See (#transaction_data) for details. The Wallet MUST refuse to process any unknown transaction data type or transaction data not conforming to the respective type definition. Each object consists of the following parameters: +: OPTIONAL. Array of strings, where each string is a base64url encoded JSON object that contains a typed parameter set with details about the transaction that the Verifier is requesting the End-User to authorize. See (#transaction_data) for details. The Wallet MUST return an error if a request contains even one unrecognized transaction data type or transaction data not conforming to the respective type definition. Each object consists of the following parameters: -* `type`: REQUIRED. String that is the Identifier of the transaction data type and determines the allowable contents of the object that contains it. The specific values are out of scope of this specification. It is RECOMMENDED to use collision-resistant names for `type` values. -* `requested_credential_ids`: REQUIRED. Array of strings each pointing to an Input Descriptor that identifies a request for a Credential that the Verifier is requesting transaction data in a particular object to be bound to. + * `type`: REQUIRED. String that is the Identifier of the transaction data type and determines the allowable contents of the object that contains it. The specific values are out of scope of this specification. It is RECOMMENDED to use collision-resistant names for `type` values. + * `credential_ids`: REQUIRED. Array of strings each pointing to an identifier that identifies a set of information describing a Credential that the Verifier is requesting transaction data in a particular object to be bound to (Input Descriptor in Presentation Exchange). The following additional considerations are given for pre-existing Authorization Request parameters: @@ -756,9 +756,12 @@ The following is a non-normative example of the payload of the JWT used in the e The transaction data mechanism enables a binding between the user's identification/authentication and the user’s authorization, for example to complete a payment transaction, or to sign specific document(s) using QES (Qualified Electronic Signatures). This is achieved by signing the transaction data used for user authorization with the user-controlled key used for proof of possession of the Credential being presented as a means for user identification/authentication. -The Wallet that received `transaction_data` parameter in the request, MUST include in the response a `tx_data_hashes` parameter defined below: -* `tx_data_hashes`: Array of hashes, where each hash is calculated using a hash function over the strings received in the `transaction_data` request parameter. Each hash value ensures the integrity of, and maps to, the respective transaction data object. Where in the response this parameter is included is defined by each Credential Format Profile, but it has to be included in the mechanism used for the proof of possession of the Credential that is signed using the user-controlled key. +The Wallet that received the `transaction_data` parameter in the request MUST include in the response a `tx_data_hashes` parameter defined below. If the wallet does not support `transaction_data` parameter, it MUST return an error. + +Where in the response `tx_data_hashes` parameter is included is specific to each credential format and is defined in a respective Credential Format Profile. + +* `transaction_data_hashes`: Array of hashes, where each hash is calculated using a hash function over the strings received in the `transaction_data` request parameter. Each hash value ensures the integrity of, and maps to, the respective transaction data object. Where in the response this parameter is included is defined by each Credential Format Profile, but it has to be included in the mechanism used for the proof of possession of the Credential that is signed using the user-controlled key. ## Error Response {#error_response} @@ -1771,7 +1774,7 @@ Setting `limit_disclosure` property defined in [@!DIF.PresentationExchange] to ` A non-normative example of the Authorization Response would look the same as in the examples of other Credential formats in this Annex. -The `transaction_data` response parameter defined in (#transaction_data) MUST be included in the Key Binding JWT as a top level claim. +The `transaction_data` response parameter defined in (#transaction_data) MUST be included in the Key Binding JWT as a top level claim. This means that transaction data mechanism cannot be used with SD-JWT VCs without cryptographic key binding and, therefore, do not use KB JWT. The following is a non-normative example of the content of the `presentation_submission` parameter: From 681677f5157774e490221fec4f925dc31d45be72 Mon Sep 17 00:00:00 2001 From: Kristina <52878547+Sakurann@users.noreply.github.com> Date: Wed, 11 Sep 2024 16:34:10 +0200 Subject: [PATCH 08/28] change tx_data_hashes to transaction_data_hashes --- openid-4-verifiable-presentations-1_0.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 03ff8794..8738ebac 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -757,9 +757,9 @@ The following is a non-normative example of the payload of the JWT used in the e The transaction data mechanism enables a binding between the user's identification/authentication and the user’s authorization, for example to complete a payment transaction, or to sign specific document(s) using QES (Qualified Electronic Signatures). This is achieved by signing the transaction data used for user authorization with the user-controlled key used for proof of possession of the Credential being presented as a means for user identification/authentication. -The Wallet that received the `transaction_data` parameter in the request MUST include in the response a `tx_data_hashes` parameter defined below. If the wallet does not support `transaction_data` parameter, it MUST return an error. +The Wallet that received the `transaction_data` parameter in the request MUST include in the response a `transaction_data_hashes` parameter defined below. If the wallet does not support `transaction_data` parameter, it MUST return an error. -Where in the response `tx_data_hashes` parameter is included is specific to each credential format and is defined in a respective Credential Format Profile. +Where in the response `transaction_data_hashes` parameter is included is specific to each credential format and is defined in a respective Credential Format Profile. * `transaction_data_hashes`: Array of hashes, where each hash is calculated using a hash function over the strings received in the `transaction_data` request parameter. Each hash value ensures the integrity of, and maps to, the respective transaction data object. Where in the response this parameter is included is defined by each Credential Format Profile, but it has to be included in the mechanism used for the proof of possession of the Credential that is signed using the user-controlled key. From bd9b35b3b7bfc5fd68ac25816b07c1efdd022005 Mon Sep 17 00:00:00 2001 From: Kristina <52878547+Sakurann@users.noreply.github.com> Date: Wed, 11 Sep 2024 16:36:47 +0200 Subject: [PATCH 09/28] fix transaction_data_hashes parameters in the kb jwt --- openid-4-verifiable-presentations-1_0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 8738ebac..b7efc331 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -1774,7 +1774,7 @@ Setting `limit_disclosure` property defined in [@!DIF.PresentationExchange] to ` A non-normative example of the Authorization Response would look the same as in the examples of other Credential formats in this Annex. -The `transaction_data` response parameter defined in (#transaction_data) MUST be included in the Key Binding JWT as a top level claim. This means that transaction data mechanism cannot be used with SD-JWT VCs without cryptographic key binding and, therefore, do not use KB JWT. +The `transaction_data_hashes` response parameter defined in (#transaction_data) MUST be included in the Key Binding JWT as a top level claim. This means that transaction data mechanism cannot be used with SD-JWT VCs without cryptographic key binding and, therefore, do not use KB JWT. The following is a non-normative example of the content of the `presentation_submission` parameter: From 6d871c8641ed4239bc249a83b5dc497e3b9611ba Mon Sep 17 00:00:00 2001 From: Kristina Yasuda Date: Wed, 11 Sep 2024 16:58:45 +0200 Subject: [PATCH 10/28] add transaction_data_hashes_alg --- openid-4-verifiable-presentations-1_0.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index b7efc331..02b7509e 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -279,6 +279,8 @@ This enables the Wallet to assess the Verifier's capabilities, allowing it to tr * `type`: REQUIRED. String that is the Identifier of the transaction data type and determines the allowable contents of the object that contains it. The specific values are out of scope of this specification. It is RECOMMENDED to use collision-resistant names for `type` values. * `credential_ids`: REQUIRED. Array of strings each pointing to an identifier that identifies a set of information describing a Credential that the Verifier is requesting transaction data in a particular object to be bound to (Input Descriptor in Presentation Exchange). + The claim transaction_data_alg indicates the hash algorithm used to generate the digests. If the claim is not present, a default value of sha-256 MUST be used. + * `transaction_data_hashes_alg`: OPTIONAL. Array of strings each representing a hash algorithm identifier, one of which MUST be used to calculate hashes in `transaction_data_hashes` response parameter. The value of the identifier MUST be a hash algorithm value from the "Hash Name String" column in the IANA "Named Information Hash Algorithm" registry [IANA.Hash.Algorithms] or a value defined in another specification and/or profile of this specification. If this parameter is not present, a default value of `sha-256` MUST be used. To promote interoperability, implementations MUST support the sha-256 hash algorithm. The following additional considerations are given for pre-existing Authorization Request parameters: @@ -762,6 +764,7 @@ The Wallet that received the `transaction_data` parameter in the request MUST in Where in the response `transaction_data_hashes` parameter is included is specific to each credential format and is defined in a respective Credential Format Profile. * `transaction_data_hashes`: Array of hashes, where each hash is calculated using a hash function over the strings received in the `transaction_data` request parameter. Each hash value ensures the integrity of, and maps to, the respective transaction data object. Where in the response this parameter is included is defined by each Credential Format Profile, but it has to be included in the mechanism used for the proof of possession of the Credential that is signed using the user-controlled key. +* `transaction_data_hashes_alg`: REQUIRED when this parameter was present in the `transaction_data` request parameter. String representing a hash algorithm identifier used to calculate hashes in `transaction_data_hashes` response parameter. ## Error Response {#error_response} From 8e5792f30736e3d550c92a16d6588f990cdf880c Mon Sep 17 00:00:00 2001 From: Kristina Yasuda Date: Wed, 11 Sep 2024 17:01:24 +0200 Subject: [PATCH 11/28] add a change log --- openid-4-verifiable-presentations-1_0.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 02b7509e..1b92fc1d 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -7,7 +7,7 @@ keyword = ["security", "openid", "ssi"] [seriesInfo] name = "Internet-Draft" -value = "openid-4-verifiable-presentations-1_0-20" +value = "openid-4-verifiable-presentations-1_0-22" status = "standard" [[author]] @@ -1922,6 +1922,10 @@ The technology described in this specification was made available from contribut [[ To be removed from the final specification ]] + -22 + + * add transaction data mechanism + -21 * fix indentation of examples From dab521ca1aacda42a37088b4aa1291e6b4def200 Mon Sep 17 00:00:00 2001 From: Kristina Yasuda Date: Wed, 11 Sep 2024 18:38:51 +0200 Subject: [PATCH 12/28] add credential being issued to be used for transaction data text --- openid-4-verifiable-presentations-1_0.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 1b92fc1d..a48a52b9 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -282,6 +282,8 @@ This enables the Wallet to assess the Verifier's capabilities, allowing it to tr The claim transaction_data_alg indicates the hash algorithm used to generate the digests. If the claim is not present, a default value of sha-256 MUST be used. * `transaction_data_hashes_alg`: OPTIONAL. Array of strings each representing a hash algorithm identifier, one of which MUST be used to calculate hashes in `transaction_data_hashes` response parameter. The value of the identifier MUST be a hash algorithm value from the "Hash Name String" column in the IANA "Named Information Hash Algorithm" registry [IANA.Hash.Algorithms] or a value defined in another specification and/or profile of this specification. If this parameter is not present, a default value of `sha-256` MUST be used. To promote interoperability, implementations MUST support the sha-256 hash algorithm. +Each document defining a transaction data type specifies whether that type requires a Credential that is bound to transaction data to be specifically issued for that purpose. How the Credential Issuer expresses that a particular Credential can be used for obtaining user's authorization using transaction data mechanism is out of scope for this specification. + The following additional considerations are given for pre-existing Authorization Request parameters: `nonce`: @@ -758,10 +760,9 @@ The following is a non-normative example of the payload of the JWT used in the e The transaction data mechanism enables a binding between the user's identification/authentication and the user’s authorization, for example to complete a payment transaction, or to sign specific document(s) using QES (Qualified Electronic Signatures). This is achieved by signing the transaction data used for user authorization with the user-controlled key used for proof of possession of the Credential being presented as a means for user identification/authentication. - The Wallet that received the `transaction_data` parameter in the request MUST include in the response a `transaction_data_hashes` parameter defined below. If the wallet does not support `transaction_data` parameter, it MUST return an error. -Where in the response `transaction_data_hashes` parameter is included is specific to each credential format and is defined in a respective Credential Format Profile. +Where to include`transaction_data_hashes` parameter in the response is specific to each credential format and is defined in a respective Credential Format Profile. * `transaction_data_hashes`: Array of hashes, where each hash is calculated using a hash function over the strings received in the `transaction_data` request parameter. Each hash value ensures the integrity of, and maps to, the respective transaction data object. Where in the response this parameter is included is defined by each Credential Format Profile, but it has to be included in the mechanism used for the proof of possession of the Credential that is signed using the user-controlled key. * `transaction_data_hashes_alg`: REQUIRED when this parameter was present in the `transaction_data` request parameter. String representing a hash algorithm identifier used to calculate hashes in `transaction_data_hashes` response parameter. From 0acd29a74cee54c6770bb71168c79d0f2507b699 Mon Sep 17 00:00:00 2001 From: Kristina Yasuda Date: Wed, 11 Sep 2024 18:47:07 +0200 Subject: [PATCH 13/28] add examples --- examples/response/kb_jwt_unsecured.json | 3 ++- openid-4-verifiable-presentations-1_0.md | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/examples/response/kb_jwt_unsecured.json b/examples/response/kb_jwt_unsecured.json index 4ec99254..b4e7d122 100644 --- a/examples/response/kb_jwt_unsecured.json +++ b/examples/response/kb_jwt_unsecured.json @@ -2,5 +2,6 @@ "nonce": "n-0S6_WzA2Mj", "aud": "https://example.com/verifier", "iat": 1709838604, - "sd_hash": "Dy-RYwZfaaoC3inJbLslgPvMp09bH-clYP_3qbRqtW4" + "sd_hash": "Dy-RYwZfaaoC3inJbLslgPvMp09bH-clYP_3qbRqtW4", + "transaction_data": [ "fOBUSQvo46yQO-wRwXBcGqvnbKIueISEL961_Sjd4do" ] } diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 3712fa29..e53b83aa 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -303,7 +303,7 @@ GET /authorize? &nonce=n-0S6_WzA2Mj HTTP/1.1 ``` -The following is a non-normative example of an Authorization Request with a `request_uri_method` parameter (including the additional `client_id_scheme` and `client_metadata` parameters): +The following is a non-normative example of an Authorization Request with a `request_uri_method` parameter (including the additional `client_id_scheme`, `client_metadata` and `transaction_data` parameters): ``` GET /authorize? @@ -312,6 +312,7 @@ GET /authorize? &client_metadata=... &request_uri=https%3A%2F%2Fclient.example.org%2Frequest%2Fvapof4ql2i7m41m68uep &request_uri_method=post HTTP/1.1 + &transaction_data=... ``` ## `presentation_definition` Parameter {#request_presentation_definition} From 3672f78a6d9211ba8d162e163d90e3a2deefeadd Mon Sep 17 00:00:00 2001 From: Kristina Yasuda Date: Thu, 10 Oct 2024 14:39:02 +0200 Subject: [PATCH 14/28] clarify transaction data is not ignored when not recognized --- openid-4-verifiable-presentations-1_0.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 28f98273..d6098d5f 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -251,6 +251,10 @@ Depending on the Client Identifier Scheme, the Verifier can communicate a JSON o This specification enables the Verifier to send both Presentation Definition JSON object and Client Metadata JSON object by value or by reference. +Additional request parameters, other than those defined in this section, MAY be defined and used, as described in [@!RFC6749]. +The Wallet MUST ignore any unrecognized parameters, other than `transaction_data` parameter. +The wallets that do not recognize `transaction_data` parameter MUST reject requests that contain it. + ## New Parameters {#new_parameters} This specification defines the following new request parameters: @@ -306,10 +310,6 @@ The following additional considerations are given for pre-existing Authorization `client_id`: : REQUIRED. Defined in [@!RFC6749]. This specification defines additional requirements to enable the use of Client Identifier Schemes as described in (#client_metadata_management). -Additional request parameters MAY be defined and used, -as described in [@!RFC6749]. -The Wallet MUST ignore any unrecognized parameters. - ## Examples The following is a non-normative example of an Authorization Request: From 9f39e708ddfd19acbeaa0d04dff85dd71df55759 Mon Sep 17 00:00:00 2001 From: Kristina <52878547+Sakurann@users.noreply.github.com> Date: Thu, 10 Oct 2024 14:40:48 +0200 Subject: [PATCH 15/28] add e.g. and Apply suggestions from code review Co-authored-by: Brian Campbell <71398439+bc-pi@users.noreply.github.com> --- openid-4-verifiable-presentations-1_0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index d6098d5f..98981e52 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -288,7 +288,7 @@ This enables the Wallet to assess the Verifier's capabilities, allowing it to tr : OPTIONAL. Array of strings, where each string is a base64url encoded JSON object that contains a typed parameter set with details about the transaction that the Verifier is requesting the End-User to authorize. See (#transaction_data) for details. The Wallet MUST return an error if a request contains even one unrecognized transaction data type or transaction data not conforming to the respective type definition. Each object consists of the following parameters: * `type`: REQUIRED. String that is the Identifier of the transaction data type and determines the allowable contents of the object that contains it. The specific values are out of scope of this specification. It is RECOMMENDED to use collision-resistant names for `type` values. - * `credential_ids`: REQUIRED. Array of strings each pointing to an identifier that identifies a set of information describing a Credential that the Verifier is requesting transaction data in a particular object to be bound to (Input Descriptor in Presentation Exchange). + * `credential_ids`: REQUIRED. Array of strings each pointing to an identifier that identifies a set of information describing a Credential that the Verifier is requesting transaction data in a particular object to be bound to (e.g., Input Descriptor in Presentation Exchange). The claim transaction_data_alg indicates the hash algorithm used to generate the digests. If the claim is not present, a default value of sha-256 MUST be used. * `transaction_data_hashes_alg`: OPTIONAL. Array of strings each representing a hash algorithm identifier, one of which MUST be used to calculate hashes in `transaction_data_hashes` response parameter. The value of the identifier MUST be a hash algorithm value from the "Hash Name String" column in the IANA "Named Information Hash Algorithm" registry [IANA.Hash.Algorithms] or a value defined in another specification and/or profile of this specification. If this parameter is not present, a default value of `sha-256` MUST be used. To promote interoperability, implementations MUST support the sha-256 hash algorithm. From fd86bb616edb0af24106aa0b25e44e2bc14f48f2 Mon Sep 17 00:00:00 2001 From: Kristina <52878547+Sakurann@users.noreply.github.com> Date: Tue, 15 Oct 2024 19:47:13 +0200 Subject: [PATCH 16/28] Apply suggestions from Joseph's code review Co-authored-by: Joseph Heenan --- openid-4-verifiable-presentations-1_0.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 98981e52..4b581a21 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -252,8 +252,8 @@ Depending on the Client Identifier Scheme, the Verifier can communicate a JSON o This specification enables the Verifier to send both Presentation Definition JSON object and Client Metadata JSON object by value or by reference. Additional request parameters, other than those defined in this section, MAY be defined and used, as described in [@!RFC6749]. -The Wallet MUST ignore any unrecognized parameters, other than `transaction_data` parameter. -The wallets that do not recognize `transaction_data` parameter MUST reject requests that contain it. +The Wallet MUST ignore any unrecognized parameters, other than the `transaction_data` parameter. +The wallets that do not support the `transaction_data` parameter MUST reject requests that contain it. ## New Parameters {#new_parameters} This specification defines the following new request parameters: @@ -282,14 +282,13 @@ This specification defines the following new request parameters: If the Verifier set the `request_uri_method` parameter value to `post` and there is no other means to convey its capabilities to the Wallet, it SHOULD add the `client_metadata` parameter to the Authorization Request. -This enables the Wallet to assess the Verifier's capabilities, allowing it to transmit only the relevant capabilities through the `wallet_metadata` parameter in the Request URI POST request. If the Verifier uses the `client_id_scheme` parameter in the Request Object, it MUST also add the same `client_id_scheme` value in the Authorization Request. +This enables the Wallet to assess the Verifier's capabilities, allowing it to transmit only the relevant capabilities through the `wallet_metadata` parameter in the Request URI POST request. `transaction_data`: : OPTIONAL. Array of strings, where each string is a base64url encoded JSON object that contains a typed parameter set with details about the transaction that the Verifier is requesting the End-User to authorize. See (#transaction_data) for details. The Wallet MUST return an error if a request contains even one unrecognized transaction data type or transaction data not conforming to the respective type definition. Each object consists of the following parameters: * `type`: REQUIRED. String that is the Identifier of the transaction data type and determines the allowable contents of the object that contains it. The specific values are out of scope of this specification. It is RECOMMENDED to use collision-resistant names for `type` values. * `credential_ids`: REQUIRED. Array of strings each pointing to an identifier that identifies a set of information describing a Credential that the Verifier is requesting transaction data in a particular object to be bound to (e.g., Input Descriptor in Presentation Exchange). - The claim transaction_data_alg indicates the hash algorithm used to generate the digests. If the claim is not present, a default value of sha-256 MUST be used. * `transaction_data_hashes_alg`: OPTIONAL. Array of strings each representing a hash algorithm identifier, one of which MUST be used to calculate hashes in `transaction_data_hashes` response parameter. The value of the identifier MUST be a hash algorithm value from the "Hash Name String" column in the IANA "Named Information Hash Algorithm" registry [IANA.Hash.Algorithms] or a value defined in another specification and/or profile of this specification. If this parameter is not present, a default value of `sha-256` MUST be used. To promote interoperability, implementations MUST support the sha-256 hash algorithm. Each document defining a transaction data type specifies whether that type requires a Credential that is bound to transaction data to be specifically issued for that purpose. How the Credential Issuer expresses that a particular Credential can be used for obtaining user's authorization using transaction data mechanism is out of scope for this specification. @@ -323,15 +322,14 @@ GET /authorize? &nonce=n-0S6_WzA2Mj HTTP/1.1 ``` -The following is a non-normative example of an Authorization Request with a `request_uri_method` parameter (including the additional `client_metadata` and `transaction_data` parameters): +The following is a non-normative example of an Authorization Request with a `request_uri_method` parameter (including the additional `client_metadata`): ``` GET /authorize? client_id=x509_san_dns:client.example.org &client_metadata=... &request_uri=https%3A%2F%2Fclient.example.org%2Frequest%2Fvapof4ql2i7m41m68uep - &request_uri_method=post HTTP/1.1 - &transaction_data=... + &request_uri_method=post ``` ## `presentation_definition` Parameter {#request_presentation_definition} @@ -827,10 +825,10 @@ The transaction data mechanism enables a binding between the user's identificati The Wallet that received the `transaction_data` parameter in the request MUST include in the response a `transaction_data_hashes` parameter defined below. If the wallet does not support `transaction_data` parameter, it MUST return an error. -Where to include`transaction_data_hashes` parameter in the response is specific to each credential format and is defined in a respective Credential Format Profile. +Where to include the`transaction_data_hashes` parameter in the response is specific to each credential format and is defined by the Credential Format Profile, such as those in (#alternative_credential_formats). * `transaction_data_hashes`: Array of hashes, where each hash is calculated using a hash function over the strings received in the `transaction_data` request parameter. Each hash value ensures the integrity of, and maps to, the respective transaction data object. Where in the response this parameter is included is defined by each Credential Format Profile, but it has to be included in the mechanism used for the proof of possession of the Credential that is signed using the user-controlled key. -* `transaction_data_hashes_alg`: REQUIRED when this parameter was present in the `transaction_data` request parameter. String representing a hash algorithm identifier used to calculate hashes in `transaction_data_hashes` response parameter. +* `transaction_data_hashes_alg`: REQUIRED when this parameter was present in the `transaction_data` request parameter. String representing the hash algorithm identifier used to calculate hashes in `transaction_data_hashes` response parameter. ## Error Response {#error_response} @@ -879,7 +877,7 @@ This document also defines the following additional error codes and error descri `invalid_transaction_data`: -- any of the following is true for at least one object in the transaction_data structure: +- any of the following is true for at least one object in the `transaction_data` structure: - contains an unknown transaction data type value, - is an object of known type but containing unknown fields, - contains fields of the wrong type for the transaction data type, From 4c5542dd1e562c258afb42c9a0f7712c16289c30 Mon Sep 17 00:00:00 2001 From: Kristina <52878547+Sakurann@users.noreply.github.com> Date: Tue, 15 Oct 2024 19:56:17 +0200 Subject: [PATCH 17/28] change IANA reference --- openid-4-verifiable-presentations-1_0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 4b581a21..bc356040 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -289,7 +289,7 @@ This enables the Wallet to assess the Verifier's capabilities, allowing it to tr * `type`: REQUIRED. String that is the Identifier of the transaction data type and determines the allowable contents of the object that contains it. The specific values are out of scope of this specification. It is RECOMMENDED to use collision-resistant names for `type` values. * `credential_ids`: REQUIRED. Array of strings each pointing to an identifier that identifies a set of information describing a Credential that the Verifier is requesting transaction data in a particular object to be bound to (e.g., Input Descriptor in Presentation Exchange). - * `transaction_data_hashes_alg`: OPTIONAL. Array of strings each representing a hash algorithm identifier, one of which MUST be used to calculate hashes in `transaction_data_hashes` response parameter. The value of the identifier MUST be a hash algorithm value from the "Hash Name String" column in the IANA "Named Information Hash Algorithm" registry [IANA.Hash.Algorithms] or a value defined in another specification and/or profile of this specification. If this parameter is not present, a default value of `sha-256` MUST be used. To promote interoperability, implementations MUST support the sha-256 hash algorithm. + * `transaction_data_hashes_alg`: OPTIONAL. Array of strings each representing a hash algorithm identifier, one of which MUST be used to calculate hashes in `transaction_data_hashes` response parameter. The value of the identifier MUST be a hash algorithm value from the "Hash Name String" column in the IANA "Named Information Hash Algorithm" registry [@IANA.JOSE] or a value defined in another specification and/or profile of this specification. If this parameter is not present, a default value of `sha-256` MUST be used. To promote interoperability, implementations MUST support the sha-256 hash algorithm. Each document defining a transaction data type specifies whether that type requires a Credential that is bound to transaction data to be specifically issued for that purpose. How the Credential Issuer expresses that a particular Credential can be used for obtaining user's authorization using transaction data mechanism is out of scope for this specification. From 98e9108b074dfb8554677edcfa814647797b5654 Mon Sep 17 00:00:00 2001 From: Kristina <52878547+Sakurann@users.noreply.github.com> Date: Tue, 15 Oct 2024 19:56:44 +0200 Subject: [PATCH 18/28] Clarify that the wallet must use only one of the credentials if there are multiple in the array --- openid-4-verifiable-presentations-1_0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index bc356040..4665e88f 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -288,7 +288,7 @@ This enables the Wallet to assess the Verifier's capabilities, allowing it to tr : OPTIONAL. Array of strings, where each string is a base64url encoded JSON object that contains a typed parameter set with details about the transaction that the Verifier is requesting the End-User to authorize. See (#transaction_data) for details. The Wallet MUST return an error if a request contains even one unrecognized transaction data type or transaction data not conforming to the respective type definition. Each object consists of the following parameters: * `type`: REQUIRED. String that is the Identifier of the transaction data type and determines the allowable contents of the object that contains it. The specific values are out of scope of this specification. It is RECOMMENDED to use collision-resistant names for `type` values. - * `credential_ids`: REQUIRED. Array of strings each pointing to an identifier that identifies a set of information describing a Credential that the Verifier is requesting transaction data in a particular object to be bound to (e.g., Input Descriptor in Presentation Exchange). + * `credential_ids`: REQUIRED. Array of strings each pointing to an identifier that identifies a set of information describing a Credential that the Verifier is requesting transaction data in a particular object to be bound to (i.e., the `id` field in the Input Descriptor in Presentation Exchange or the `id` field in the Credential Query in Verifiable Presentation Query Language defined in (#vp_query)). When there are more than one element in the array, the Wallet MUST use only one of those Credentials. * `transaction_data_hashes_alg`: OPTIONAL. Array of strings each representing a hash algorithm identifier, one of which MUST be used to calculate hashes in `transaction_data_hashes` response parameter. The value of the identifier MUST be a hash algorithm value from the "Hash Name String" column in the IANA "Named Information Hash Algorithm" registry [@IANA.JOSE] or a value defined in another specification and/or profile of this specification. If this parameter is not present, a default value of `sha-256` MUST be used. To promote interoperability, implementations MUST support the sha-256 hash algorithm. Each document defining a transaction data type specifies whether that type requires a Credential that is bound to transaction data to be specifically issued for that purpose. How the Credential Issuer expresses that a particular Credential can be used for obtaining user's authorization using transaction data mechanism is out of scope for this specification. From 425fa60e6611c80fcbe3cf74e8c43893158a06ba Mon Sep 17 00:00:00 2001 From: Kristina <52878547+Sakurann@users.noreply.github.com> Date: Thu, 17 Oct 2024 14:50:41 +0200 Subject: [PATCH 19/28] Apply suggestions from Christian's code review Co-authored-by: Christian Bormann <8774236+c2bo@users.noreply.github.com> --- openid-4-verifiable-presentations-1_0.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 4665e88f..fefac1a5 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -281,7 +281,6 @@ This specification defines the following new request parameters: : OPTIONAL. A string determining the HTTP method to be used when the `request_uri` parameter is included in the same request. Two case-sensitive valid values are defined in this specification: `get` and `post`. If `request_uri_method` value is `get`, the Wallet MUST send the request to retrieve the Request Object using the HTTP GET method, i.e., as defined in [@RFC9101]. If `request_uri_method` value is `post`, a supporting Wallet MUST send the request using the HTTP POST method as detailed in (#request_uri_method_post). If the `request_uri_method` parameter is not present, the Wallet MUST process the `request_uri` parameter as defined in [@RFC9101]. Wallets not supporting the `post` method will send a GET request to the Request URI (default behavior as defined in [@RFC9101]). `request_uri_method` parameter MUST NOT be present if a `request_uri` parameter is not present. If the Verifier set the `request_uri_method` parameter value to `post` and there is no other means to convey its capabilities to the Wallet, it SHOULD add the `client_metadata` parameter to the Authorization Request. - This enables the Wallet to assess the Verifier's capabilities, allowing it to transmit only the relevant capabilities through the `wallet_metadata` parameter in the Request URI POST request. `transaction_data`: @@ -329,7 +328,7 @@ GET /authorize? client_id=x509_san_dns:client.example.org &client_metadata=... &request_uri=https%3A%2F%2Fclient.example.org%2Frequest%2Fvapof4ql2i7m41m68uep - &request_uri_method=post + &request_uri_method=post HTTP/1.1 ``` ## `presentation_definition` Parameter {#request_presentation_definition} @@ -827,7 +826,7 @@ The Wallet that received the `transaction_data` parameter in the request MUST in Where to include the`transaction_data_hashes` parameter in the response is specific to each credential format and is defined by the Credential Format Profile, such as those in (#alternative_credential_formats). -* `transaction_data_hashes`: Array of hashes, where each hash is calculated using a hash function over the strings received in the `transaction_data` request parameter. Each hash value ensures the integrity of, and maps to, the respective transaction data object. Where in the response this parameter is included is defined by each Credential Format Profile, but it has to be included in the mechanism used for the proof of possession of the Credential that is signed using the user-controlled key. +* `transaction_data_hashes`: Array of hashes, where each hash is calculated using a hash function over the strings received in the `transaction_data` request parameter. Each hash value ensures the integrity of, and maps to, the respective transaction data object. Where in the response this parameter is included is defined by each Credential Format Profile, but it has to be included in the mechanism used for the proof of possession of the Credential that is signed using the user-controlled key. * `transaction_data_hashes_alg`: REQUIRED when this parameter was present in the `transaction_data` request parameter. String representing the hash algorithm identifier used to calculate hashes in `transaction_data_hashes` response parameter. ## Error Response {#error_response} From 2d39362e0895a3ed5f5cb2a41fc5064e0ba03d1b Mon Sep 17 00:00:00 2001 From: Kristina <52878547+Sakurann@users.noreply.github.com> Date: Fri, 18 Oct 2024 12:35:37 +0200 Subject: [PATCH 20/28] clarify the processing rules --- openid-4-verifiable-presentations-1_0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index fefac1a5..9d9b8b59 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -253,7 +253,7 @@ This specification enables the Verifier to send both Presentation Definition JSO Additional request parameters, other than those defined in this section, MAY be defined and used, as described in [@!RFC6749]. The Wallet MUST ignore any unrecognized parameters, other than the `transaction_data` parameter. -The wallets that do not support the `transaction_data` parameter MUST reject requests that contain it. +One exception to this rule is `transaction_data` parameter, and the wallets that do not support this parameter MUST reject requests that contain it. ## New Parameters {#new_parameters} This specification defines the following new request parameters: From 6b3418ec1f260086c803882a2e5494b9ca5f5acd Mon Sep 17 00:00:00 2001 From: Kristina <52878547+Sakurann@users.noreply.github.com> Date: Fri, 18 Oct 2024 12:37:40 +0200 Subject: [PATCH 21/28] IANA.Hash.Algorithms Co-authored-by: Michael B. Jones --- openid-4-verifiable-presentations-1_0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 9d9b8b59..b05f3511 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -288,7 +288,7 @@ This enables the Wallet to assess the Verifier's capabilities, allowing it to tr * `type`: REQUIRED. String that is the Identifier of the transaction data type and determines the allowable contents of the object that contains it. The specific values are out of scope of this specification. It is RECOMMENDED to use collision-resistant names for `type` values. * `credential_ids`: REQUIRED. Array of strings each pointing to an identifier that identifies a set of information describing a Credential that the Verifier is requesting transaction data in a particular object to be bound to (i.e., the `id` field in the Input Descriptor in Presentation Exchange or the `id` field in the Credential Query in Verifiable Presentation Query Language defined in (#vp_query)). When there are more than one element in the array, the Wallet MUST use only one of those Credentials. - * `transaction_data_hashes_alg`: OPTIONAL. Array of strings each representing a hash algorithm identifier, one of which MUST be used to calculate hashes in `transaction_data_hashes` response parameter. The value of the identifier MUST be a hash algorithm value from the "Hash Name String" column in the IANA "Named Information Hash Algorithm" registry [@IANA.JOSE] or a value defined in another specification and/or profile of this specification. If this parameter is not present, a default value of `sha-256` MUST be used. To promote interoperability, implementations MUST support the sha-256 hash algorithm. + * `transaction_data_hashes_alg`: OPTIONAL. Array of strings each representing a hash algorithm identifier, one of which MUST be used to calculate hashes in `transaction_data_hashes` response parameter. The value of the identifier MUST be a hash algorithm value from the "Hash Name String" column in the IANA "Named Information Hash Algorithm" registry [@IANA.Hash.Algorithms] or a value defined in another specification and/or profile of this specification. If this parameter is not present, a default value of `sha-256` MUST be used. To promote interoperability, implementations MUST support the sha-256 hash algorithm. Each document defining a transaction data type specifies whether that type requires a Credential that is bound to transaction data to be specifically issued for that purpose. How the Credential Issuer expresses that a particular Credential can be used for obtaining user's authorization using transaction data mechanism is out of scope for this specification. From 1d902fc6fa138e6f141bc7e72fcd7a66b7f0ec6c Mon Sep 17 00:00:00 2001 From: Joseph Heenan Date: Fri, 18 Oct 2024 11:58:42 +0100 Subject: [PATCH 22/28] Fix compile error with vp_query ref (with Kristina's permission) I'd made a suggestion that added a reference to the new query language, but that stops the spec compiling because the new query language isn't merged yet and won't be for a few days. To let the spec compile, just remove that reference. We can always add it back later. --- openid-4-verifiable-presentations-1_0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index ec565a92..e800db63 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -287,7 +287,7 @@ This enables the Wallet to assess the Verifier's capabilities, allowing it to tr : OPTIONAL. Array of strings, where each string is a base64url encoded JSON object that contains a typed parameter set with details about the transaction that the Verifier is requesting the End-User to authorize. See (#transaction_data) for details. The Wallet MUST return an error if a request contains even one unrecognized transaction data type or transaction data not conforming to the respective type definition. Each object consists of the following parameters: * `type`: REQUIRED. String that is the Identifier of the transaction data type and determines the allowable contents of the object that contains it. The specific values are out of scope of this specification. It is RECOMMENDED to use collision-resistant names for `type` values. - * `credential_ids`: REQUIRED. Array of strings each pointing to an identifier that identifies a set of information describing a Credential that the Verifier is requesting transaction data in a particular object to be bound to (i.e., the `id` field in the Input Descriptor in Presentation Exchange or the `id` field in the Credential Query in Verifiable Presentation Query Language defined in (#vp_query)). When there are more than one element in the array, the Wallet MUST use only one of those Credentials. + * `credential_ids`: REQUIRED. Array of strings each pointing to an identifier that identifies a set of information describing a Credential that the Verifier is requesting transaction data in a particular object to be bound to (i.e., the `id` field in the Input Descriptor in Presentation Exchange or the `id` field in the Credential Query in Verifiable Presentation Query Language). When there are more than one element in the array, the Wallet MUST use only one of those Credentials. * `transaction_data_hashes_alg`: OPTIONAL. Array of strings each representing a hash algorithm identifier, one of which MUST be used to calculate hashes in `transaction_data_hashes` response parameter. The value of the identifier MUST be a hash algorithm value from the "Hash Name String" column in the IANA "Named Information Hash Algorithm" registry [@IANA.Hash.Algorithms] or a value defined in another specification and/or profile of this specification. If this parameter is not present, a default value of `sha-256` MUST be used. To promote interoperability, implementations MUST support the sha-256 hash algorithm. Each document defining a transaction data type specifies whether that type requires a Credential that is bound to transaction data to be specifically issued for that purpose. How the Credential Issuer expresses that a particular Credential can be used for obtaining user's authorization using transaction data mechanism is out of scope for this specification. From 466ba1da3993b549018a3f5ad02eca4d208baa85 Mon Sep 17 00:00:00 2001 From: Joseph Heenan Date: Fri, 18 Oct 2024 12:02:51 +0100 Subject: [PATCH 23/28] Fix compile error with IANA.Hash.Algorithms reference Add the necessary entry in {backmatter}. Committed with Kristina's permission. --- openid-4-verifiable-presentations-1_0.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index e800db63..867b3b14 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -1637,6 +1637,15 @@ issuers in Self-Sovereign Identity ecosystems using TRAIN + + + Named Information Hash Algorithm Registry + + IANA + + + + # OpenID4VP profile for the W3C Digital Credentials API This section defines a profile of OpenID4VP for use with the W3C Digital Credentials API [@!w3c.digital_credentials_api]. From 352a6e87af7fb26a33835d41294a6cb48bd098fc Mon Sep 17 00:00:00 2001 From: Kristina <52878547+Sakurann@users.noreply.github.com> Date: Mon, 21 Oct 2024 13:41:23 +0200 Subject: [PATCH 24/28] Apply suggestions from Paul's code review Co-authored-by: Christian Bormann <8774236+c2bo@users.noreply.github.com> Co-authored-by: Paul Bastian --- examples/response/kb_jwt_unsecured.json | 2 +- openid-4-verifiable-presentations-1_0.md | 10 ++++++---- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/examples/response/kb_jwt_unsecured.json b/examples/response/kb_jwt_unsecured.json index b4e7d122..bf408111 100644 --- a/examples/response/kb_jwt_unsecured.json +++ b/examples/response/kb_jwt_unsecured.json @@ -3,5 +3,5 @@ "aud": "https://example.com/verifier", "iat": 1709838604, "sd_hash": "Dy-RYwZfaaoC3inJbLslgPvMp09bH-clYP_3qbRqtW4", - "transaction_data": [ "fOBUSQvo46yQO-wRwXBcGqvnbKIueISEL961_Sjd4do" ] + "transaction_data_hashes": [ "fOBUSQvo46yQO-wRwXBcGqvnbKIueISEL961_Sjd4do" ] } diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 867b3b14..9f46c023 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -286,11 +286,11 @@ This enables the Wallet to assess the Verifier's capabilities, allowing it to tr `transaction_data`: : OPTIONAL. Array of strings, where each string is a base64url encoded JSON object that contains a typed parameter set with details about the transaction that the Verifier is requesting the End-User to authorize. See (#transaction_data) for details. The Wallet MUST return an error if a request contains even one unrecognized transaction data type or transaction data not conforming to the respective type definition. Each object consists of the following parameters: - * `type`: REQUIRED. String that is the Identifier of the transaction data type and determines the allowable contents of the object that contains it. The specific values are out of scope of this specification. It is RECOMMENDED to use collision-resistant names for `type` values. - * `credential_ids`: REQUIRED. Array of strings each pointing to an identifier that identifies a set of information describing a Credential that the Verifier is requesting transaction data in a particular object to be bound to (i.e., the `id` field in the Input Descriptor in Presentation Exchange or the `id` field in the Credential Query in Verifiable Presentation Query Language). When there are more than one element in the array, the Wallet MUST use only one of those Credentials. + * `type`: REQUIRED. String that identifies the type of transaction data . This value determines parameters that can be included in the `transaction_data` object. The specific values are out of scope of this specification. It is RECOMMENDED to use collision-resistant names for `type` values. + * `credential_ids`: REQUIRED. Array of strings each referencing a Credential requested by the Verifier that can be used to authorize this transaction. In Presentation Exchange, the string matches the `id` field in the Input Descriptor. In Verifiable Presentation Query Language (defined in (#vp_query)), the string matches the `id` field in the Credential Query. If there is more than one element in the array, the Wallet MUST use only one of the referenced Credentials for transaction authorization. * `transaction_data_hashes_alg`: OPTIONAL. Array of strings each representing a hash algorithm identifier, one of which MUST be used to calculate hashes in `transaction_data_hashes` response parameter. The value of the identifier MUST be a hash algorithm value from the "Hash Name String" column in the IANA "Named Information Hash Algorithm" registry [@IANA.Hash.Algorithms] or a value defined in another specification and/or profile of this specification. If this parameter is not present, a default value of `sha-256` MUST be used. To promote interoperability, implementations MUST support the sha-256 hash algorithm. -Each document defining a transaction data type specifies whether that type requires a Credential that is bound to transaction data to be specifically issued for that purpose. How the Credential Issuer expresses that a particular Credential can be used for obtaining user's authorization using transaction data mechanism is out of scope for this specification. +Each document specifying details of a transaction data type defines what Credential(s) can be used to authorize those transactions. Those Credential(s) can be issued specifically for the transaction authorization use case or re-use existing Credential(s) used for user identification. A mechanism for Credential Issuers to express that a particular Credential can be used for authorization of transaction data is out of scope for this specification. ## Existing Parameters @@ -877,11 +877,13 @@ This document also defines the following additional error codes and error descri `invalid_transaction_data`: - any of the following is true for at least one object in the `transaction_data` structure: - - contains an unknown transaction data type value, + - contains an unknown or unsupported transaction data type value, - is an object of known type but containing unknown fields, - contains fields of the wrong type for the transaction data type, - contains fields with invalid values for the transaction data type, or - is missing required fields for the transaction data type. + - the credential_ids does not match + - the referenced Credential is not available in the Wallet `wallet_unavailable`: From be9f30b272e9e9a85915506b77e51e3ff2f71394 Mon Sep 17 00:00:00 2001 From: Kristina <52878547+Sakurann@users.noreply.github.com> Date: Mon, 21 Oct 2024 13:42:30 +0200 Subject: [PATCH 25/28] minor nit --- openid-4-verifiable-presentations-1_0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 9f46c023..bb4128c0 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -883,7 +883,7 @@ This document also defines the following additional error codes and error descri - contains fields with invalid values for the transaction data type, or - is missing required fields for the transaction data type. - the credential_ids does not match - - the referenced Credential is not available in the Wallet + - the referenced Credential(s) are not available in the Wallet `wallet_unavailable`: From 5419a0e41284d9df793ee5afd1d227902f7294b6 Mon Sep 17 00:00:00 2001 From: Kristina Yasuda Date: Mon, 21 Oct 2024 14:29:56 +0200 Subject: [PATCH 26/28] add transaction data content example --- openid-4-verifiable-presentations-1_0.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index bb4128c0..a5c03cfe 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -292,6 +292,16 @@ This enables the Wallet to assess the Verifier's capabilities, allowing it to tr Each document specifying details of a transaction data type defines what Credential(s) can be used to authorize those transactions. Those Credential(s) can be issued specifically for the transaction authorization use case or re-use existing Credential(s) used for user identification. A mechanism for Credential Issuers to express that a particular Credential can be used for authorization of transaction data is out of scope for this specification. +The following is a non-normative example of a transaction data content, after base64url decoding one of the strings in the `transaction_data` parameter: + +``` +{ + "type": "example_type", + "credential_ids": [ "id card credential" ], + "transaction_data_hashes_alg": [ "sha-256" ] +} +``` + ## Existing Parameters The following additional considerations are given for pre-existing Authorization Request parameters: @@ -318,6 +328,7 @@ GET /authorize? &client_id=redirect_uri:https%3A%2F%2Fclient.example.org%2Fcb &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb &presentation_definition=... + &transaction_data=... &nonce=n-0S6_WzA2Mj HTTP/1.1 ``` From 2517679272d45559277931947d3fee7a14836532 Mon Sep 17 00:00:00 2001 From: Kristina <52878547+Sakurann@users.noreply.github.com> Date: Mon, 21 Oct 2024 16:46:55 +0200 Subject: [PATCH 27/28] Apply suggestions from final code review --- openid-4-verifiable-presentations-1_0.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index a5c03cfe..a82293c2 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -284,7 +284,7 @@ If the Verifier set the `request_uri_method` parameter value to `post` and there This enables the Wallet to assess the Verifier's capabilities, allowing it to transmit only the relevant capabilities through the `wallet_metadata` parameter in the Request URI POST request. `transaction_data`: -: OPTIONAL. Array of strings, where each string is a base64url encoded JSON object that contains a typed parameter set with details about the transaction that the Verifier is requesting the End-User to authorize. See (#transaction_data) for details. The Wallet MUST return an error if a request contains even one unrecognized transaction data type or transaction data not conforming to the respective type definition. Each object consists of the following parameters: +: OPTIONAL. Array of strings, where each string is a base64url encoded JSON object that contains a typed parameter set with details about the transaction that the Verifier is requesting the End-User to authorize. See (#transaction_data) for details. The Wallet MUST return an error if a request contains even one unrecognized transaction data type or transaction data not conforming to the respective type definition. In addition to the parameters determined by the type of transaction data, each `transaction_data` object consists of the following parameters defined by this specification: * `type`: REQUIRED. String that identifies the type of transaction data . This value determines parameters that can be included in the `transaction_data` object. The specific values are out of scope of this specification. It is RECOMMENDED to use collision-resistant names for `type` values. * `credential_ids`: REQUIRED. Array of strings each referencing a Credential requested by the Verifier that can be used to authorize this transaction. In Presentation Exchange, the string matches the `id` field in the Input Descriptor. In Verifiable Presentation Query Language (defined in (#vp_query)), the string matches the `id` field in the Credential Query. If there is more than one element in the array, the Wallet MUST use only one of the referenced Credentials for transaction authorization. @@ -299,6 +299,7 @@ The following is a non-normative example of a transaction data content, after ba "type": "example_type", "credential_ids": [ "id card credential" ], "transaction_data_hashes_alg": [ "sha-256" ] + // other transaction data type specific parameters } ``` From c2e593ce8ad562e17e6d8611faff799a7b516cfe Mon Sep 17 00:00:00 2001 From: Joseph Heenan Date: Mon, 21 Oct 2024 16:03:50 +0100 Subject: [PATCH 28/28] Remove #vp_query reference so spec compiles We probably want to add this back after query language is merged, but for now we need to keep the spec compiling. --- openid-4-verifiable-presentations-1_0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index a82293c2..2b37a56a 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -287,7 +287,7 @@ This enables the Wallet to assess the Verifier's capabilities, allowing it to tr : OPTIONAL. Array of strings, where each string is a base64url encoded JSON object that contains a typed parameter set with details about the transaction that the Verifier is requesting the End-User to authorize. See (#transaction_data) for details. The Wallet MUST return an error if a request contains even one unrecognized transaction data type or transaction data not conforming to the respective type definition. In addition to the parameters determined by the type of transaction data, each `transaction_data` object consists of the following parameters defined by this specification: * `type`: REQUIRED. String that identifies the type of transaction data . This value determines parameters that can be included in the `transaction_data` object. The specific values are out of scope of this specification. It is RECOMMENDED to use collision-resistant names for `type` values. - * `credential_ids`: REQUIRED. Array of strings each referencing a Credential requested by the Verifier that can be used to authorize this transaction. In Presentation Exchange, the string matches the `id` field in the Input Descriptor. In Verifiable Presentation Query Language (defined in (#vp_query)), the string matches the `id` field in the Credential Query. If there is more than one element in the array, the Wallet MUST use only one of the referenced Credentials for transaction authorization. + * `credential_ids`: REQUIRED. Array of strings each referencing a Credential requested by the Verifier that can be used to authorize this transaction. In Presentation Exchange, the string matches the `id` field in the Input Descriptor. In Verifiable Presentation Query Language, the string matches the `id` field in the Credential Query. If there is more than one element in the array, the Wallet MUST use only one of the referenced Credentials for transaction authorization. * `transaction_data_hashes_alg`: OPTIONAL. Array of strings each representing a hash algorithm identifier, one of which MUST be used to calculate hashes in `transaction_data_hashes` response parameter. The value of the identifier MUST be a hash algorithm value from the "Hash Name String" column in the IANA "Named Information Hash Algorithm" registry [@IANA.Hash.Algorithms] or a value defined in another specification and/or profile of this specification. If this parameter is not present, a default value of `sha-256` MUST be used. To promote interoperability, implementations MUST support the sha-256 hash algorithm. Each document specifying details of a transaction data type defines what Credential(s) can be used to authorize those transactions. Those Credential(s) can be issued specifically for the transaction authorization use case or re-use existing Credential(s) used for user identification. A mechanism for Credential Issuers to express that a particular Credential can be used for authorization of transaction data is out of scope for this specification.