From 665eda82c37a6b1a6eaa14d2157c98e4e00128d8 Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Thu, 25 Jul 2024 14:03:58 +0200 Subject: [PATCH 01/49] First draft of new query language --- .../query_lang/credentials_alternatives.json | 43 ++ examples/query_lang/multi_credentials.json | 42 ++ examples/query_lang/nested_claim_queries.json | 41 ++ examples/query_lang/simple.json | 17 + examples/query_lang/simple_mdoc.json | 22 + openid-4-verifiable-presentations-1_0.md | 504 ++++++++++++++---- 6 files changed, 563 insertions(+), 106 deletions(-) create mode 100644 examples/query_lang/credentials_alternatives.json create mode 100644 examples/query_lang/multi_credentials.json create mode 100644 examples/query_lang/nested_claim_queries.json create mode 100644 examples/query_lang/simple.json create mode 100644 examples/query_lang/simple_mdoc.json diff --git a/examples/query_lang/credentials_alternatives.json b/examples/query_lang/credentials_alternatives.json new file mode 100644 index 00000000..fdf5d312 --- /dev/null +++ b/examples/query_lang/credentials_alternatives.json @@ -0,0 +1,43 @@ +{ + "rules": { + "required": 2, + "from": [ + { "ref": "pid" }, + { + "required": 1, + "from": [ + { "ref": "pid_reduced" }, + { "ref": "residence_info" } + ] + } + ] + }, + "credentials": { + "pid": { + "format": "vc+sd-jwt", + "vct_values": ["https://credentials.example.com/identity_credential"], + "claims": [ + { "path": ["last_name"] }, + { "path": ["first_name"] }, + { "path": ["address", "street_address"] } + ] + }, + "pid_reduced": { + "format": "vc+sd-jwt", + "vct_values": ["https://credentials.example.com/identity_credential"], + "claims": [ + { "path": ["last_name"] }, + { "path": ["first_name"] } + ] + }, + "residence_info": { + "format": "vc+sd-jwt", + "vct_values": ["https://credentials.example.com/residence_credential"], + "claims": [ + { "path": ["zip_code"] }, + { "path": ["city"] }, + { "path": ["state"] } + ] + } + } +} \ No newline at end of file diff --git a/examples/query_lang/multi_credentials.json b/examples/query_lang/multi_credentials.json new file mode 100644 index 00000000..c706ce34 --- /dev/null +++ b/examples/query_lang/multi_credentials.json @@ -0,0 +1,42 @@ +{ + "credentials": { + "pid": { + "format": "vc+sd-jwt", + "vc+sd-jwt": { + "vct_values": [ "https://example.com/personal_identity" ] + }, + "purpose": [{ + "lang": "en-US", + "text": "To prove the identity of the holder" + }], + "claims": [ + { "path": [ "last_name" ] }, + { "path": [ "first_name" ] }, + { "path": [ "address", "street_address" ] } + ] + }, + "degree": { + "format": "vc+sd-jwt", + "vc+sd-jwt": { + "vct_values": [ "https://example.com/education_credential" ] + }, + "claims": [ + { "path": [ "last_name" ] }, + { "path": [ "first_name" ] }, + { "path": [ "degree" ] } + ] + }, + "residence": { + "format": "vc+sd-jwt", + "vc+sd-jwt": { + "vct_values": [ "https://example.com/residence_proof" ] + }, + "claims": [ + { "path": [ "last_name" ] }, + { "path": [ "first_name" ] }, + { "path": [ "city" ] }, + { "path": [ "state" ] } + ] + } + } +} \ No newline at end of file diff --git a/examples/query_lang/nested_claim_queries.json b/examples/query_lang/nested_claim_queries.json new file mode 100644 index 00000000..7d8fe0ca --- /dev/null +++ b/examples/query_lang/nested_claim_queries.json @@ -0,0 +1,41 @@ +{ + "credentials": { + "my_cred_1": { + "format": "vc+sd-jwt", + "vc+sd-jwt": { + "vct_values": [ "https://credentials.example.com/identity_credential" ], + "alg_values": [ "ES256", "ES384" ], + "sd_alg_values": [ "SHA-256" ] + }, + "purpose": [{ + "lang": "en-US", + "text": "To prove the identity of the holder" + }, + { + "lang": "no-NO", + "text": "For å bevise innehaverens identitet" + }, + { + "lang": "jp-JP", + "text": "保持者の身元を証明するため" + } + ], + "claims": [ + { "path": [ "last_name" ] }, + { + "required": 1, + "from": [ + { "path": [ "zip_code" ] }, + { + "required": 2, + "from": [ + { "path": [ "city" ] }, + { "path": [ "state" ] } + ] + } + ] + } + ] + } + } +} \ No newline at end of file diff --git a/examples/query_lang/simple.json b/examples/query_lang/simple.json new file mode 100644 index 00000000..b0c61a89 --- /dev/null +++ b/examples/query_lang/simple.json @@ -0,0 +1,17 @@ +{ + "credentials": { + "my_cred_1": { + "format": "vc+sd-jwt", + "vc+sd-jwt": { + "vct_values": [ "https://credentials.example.com/identity_credential" ], + "alg_values": ["ES256", "ES384"], + "sd_alg_values": ["SHA-256"] + }, + "claims":[ + { "path": ["last_name"] }, + { "path": ["first_name"] }, + { "path": ["address", "street_address"] } + ] + } + } +} \ No newline at end of file diff --git a/examples/query_lang/simple_mdoc.json b/examples/query_lang/simple_mdoc.json new file mode 100644 index 00000000..bf102166 --- /dev/null +++ b/examples/query_lang/simple_mdoc.json @@ -0,0 +1,22 @@ +{ + "credentials": { + "my_mdoc_credential": { + "format": "mso_mdoc", + "mso_mdoc": { + "doctype_values": "org.iso.7367.1.mVR", + "alg_values": [ "EdDSA" ], + "hash_algorithm_values": [ "SHA-384"] + }, + "claims": [ + { + "namespace": "org.iso.7367.1", + "claim_name": "vehicle_holder" + }, + { + "namespace": "org.iso.18013.5.1", + "claim_name": "first_name" + } + ] + } + } +} \ No newline at end of file diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index d1450d23..ea22a7cf 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -46,7 +46,7 @@ organization="Mattr" .# Abstract -This specification defines a protocol for requesting and presenting Verifiable Credentials. +This specification defines a protocol for requesting and presenting Verifiable Credentials. {mainmatter} @@ -54,7 +54,7 @@ This specification defines a protocol for requesting and presenting Verifiable C This specification defines a mechanism on top of OAuth 2.0 [@!RFC6749] that enables presentation of Verifiable Credentials as Verifiable Presentations. Verifiable Credentials and Verifiable Presentations can be of any format, including, but not limited to W3C Verifiable Credentials Data Model [@VC_DATA], ISO mdoc [@ISO.18013-5], IETF SD-JWT VC [@!I-D.ietf-oauth-sd-jwt-vc], and AnonCreds [@Hyperledger.Indy]. -OAuth 2.0 [@!RFC6749] is used as a base protocol as it provides the required rails to build a simple, secure, and developer-friendly Credential presentation layer on top of it. Moreover, implementers can, in a single interface, support Credential presentation and the issuance of Access Tokens for access to APIs based on Verifiable Credentials in the Wallet. OpenID Connect [@!OpenID.Core] deployments can also extend their implementations using this specification with the ability to transport Verifiable Presentations. +OAuth 2.0 [@!RFC6749] is used as a base protocol as it provides the required rails to build a simple, secure, and developer-friendly Credential presentation layer on top of it. Moreover, implementers can, in a single interface, support Credential presentation and the issuance of Access Tokens for access to APIs based on Verifiable Credentials in the Wallet. OpenID Connect [@!OpenID.Core] deployments can also extend their implementations using this specification with the ability to transport Verifiable Presentations. This specification can also be combined with [@!SIOPv2], if implementers require OpenID Connect features, such as the issuance of Self-Issued ID Tokens [@!SIOPv2]. @@ -98,11 +98,11 @@ Verifier: Issuer-Holder-Verifier Model: : A model for exchanging claims, where claims are issued in the form of Verifiable Credentials independent of the process of presenting them as Verifiable Presentation to the Verifiers. An issued Verifiable Credential can (but must not necessarily) be used multiple times. -Holder Binding: -: Ability of the Holder to prove legitimate possession of a Verifiable Credential. +Holder Binding: +: Ability of the Holder to prove legitimate possession of a Verifiable Credential. Cryptographic Holder Binding: -: Ability of the Holder to prove legitimate possession of a Verifiable Credential by proving control over the same private key during the issuance and presentation. Mechanism might depend on the Credential Format. For example, in `jwt_vc_json` Credential Format, a Verifiable Credential with Cryptographic Holder Binding contains a public key or a reference to a public key that matches to the private key controlled by the Holder. +: Ability of the Holder to prove legitimate possession of a Verifiable Credential by proving control over the same private key during the issuance and presentation. Mechanism might depend on the Credential Format. For example, in `jwt_vc_json` Credential Format, a Verifiable Credential with Cryptographic Holder Binding contains a public key or a reference to a public key that matches to the private key controlled by the Holder. Claims-based Holder Binding: : Ability of the Holder to prove legitimate possession of a Verifiable Credential by proofing certain claims, e.g., name and date of birth, for example by presenting another Verifiable Credential. Claims-based Holder Binding allows long term, cross device use of a Credential as it does not depend on cryptographic key material stored on a certain device. One example of such a Verifiable Credential could be a Diploma. @@ -116,13 +116,13 @@ VP Token: Wallet: : An entity used by the Holder to receive, store, present, and manage Verifiable Credentials and key material. There is no single deployment model of a Wallet: Verifiable Credentials and keys can both be stored/managed locally, or by using a remote self-hosted service, or a remote third-party service. In the context of this specification, the Wallet acts as an OAuth 2.0 Authorization Server (see [@!RFC6749]) towards the Credential Verifier which acts as the OAuth 2.0 Client. -# Overview +# Overview This specification defines a mechanism on top of OAuth 2.0 to request and present Verifiable Credentials as Verifiable Presentations. As the primary extension, OpenID for Verifiable Presentations introduces the VP Token as a container to enable End-Users to present Verifiable Presentations to Verifiers using the Wallet. A VP Token contains one or more Verifiable Presentations in the same or different Credential formats. -This specification supports any Credential format used in the Issuer-Holder-Verifier Model, including, but not limited to those defined in [@VC_DATA] (VCDM), [@ISO.18013-5] (mdoc), [@!I-D.ietf-oauth-sd-jwt-vc] (SD-JWT VC), and [@Hyperledger.Indy] (AnonCreds). Credentials of multiple formats can be presented in the same transaction. The examples given in the main part of this specification use W3C Verifiable Credentials, while examples in other Credential formats are given in (#alternative_credential_formats). +This specification supports any Credential format used in the Issuer-Holder-Verifier Model, including, but not limited to those defined in [@VC_DATA] (VCDM), [@ISO.18013-5] (mdoc), [@!I-D.ietf-oauth-sd-jwt-vc] (SD-JWT VC), and [@Hyperledger.Indy] (AnonCreds). Credentials of multiple formats can be presented in the same transaction. The examples given in the main part of this specification use W3C Verifiable Credentials, while examples in other Credential formats are given in (#alternative_credential_formats). Implementations can use any pre-existing OAuth 2.0 Grant Type and Response Type in conjunction with this specification to support different deployment architectures. @@ -138,7 +138,7 @@ Any of the OAuth 2.0 related specifications, such as [@RFC9126] and [@RFC9101], Below is a diagram of a flow where the End-User presents a Credential to a Verifier interacting with the End-User on the same device that the device the Wallet resides on. -The flow utilizes simple redirects to pass Authorization Request and Response between the Verifier and the Wallet. The Verifiable Presentations are returned to the Verifier in the fragment part of the redirect URI, when Response Mode is `fragment`. +The flow utilizes simple redirects to pass Authorization Request and Response between the Verifier and the Wallet. The Verifiable Presentations are returned to the Verifier in the fragment part of the redirect URI, when Response Mode is `fragment`. Note: The diagram does not illustrate all the optional features of this specification. @@ -146,7 +146,7 @@ Note: The diagram does not illustrate all the optional features of this specific ~~~ ascii-art +--------------+ +--------------+ +--------------+ | User | | Verifier | | Wallet | -+--------------+ +--------------+ +--------------+ ++--------------+ +--------------+ +--------------+ | | | | Interacts | | |---------------->| | @@ -164,7 +164,7 @@ Note: The diagram does not illustrate all the optional features of this specific !--- Figure: Same Device Flow -(1) The Verifier sends an Authorization Request to the Wallet. It contains a Presentation Definition as defined in [@!DIF.PresentationExchange] that describes the requirements of the Credential(s) that the Verifier is requesting to be presented. Such requirements could include what type of Credential(s), in what format(s), which individual Claims within those Credential(s) (Selective Disclosure), etc. The Wallet processes the Authorization Request and determines what Credentials are available matching the Verifier's request. The Wallet also authenticates the End-User and gathers consent to present the requested Credentials. +(1) The Verifier sends an Authorization Request to the Wallet. It contains a Presentation Definition as defined in [@!DIF.PresentationExchange] that describes the requirements of the Credential(s) that the Verifier is requesting to be presented. Such requirements could include what type of Credential(s), in what format(s), which individual Claims within those Credential(s) (Selective Disclosure), etc. The Wallet processes the Authorization Request and determines what Credentials are available matching the Verifier's request. The Wallet also authenticates the End-User and gathers consent to present the requested Credentials. (2) The Wallet prepares the Verifiable Presentation(s) of the Verifiable Credential(s) that the End-User has consented to. It then sends to the Verifier an Authorization Response where the Verifiable Presentation(s) are contained in the `vp_token` parameter. @@ -207,11 +207,11 @@ Note: The usage of the Request URI as defined in [@!RFC9101] does not depend on !--- Figure: Cross Device Flow -(1) The Verifier sends to the Wallet an Authorization Request that contains a Request URI from where to obtain the Request Object containing Authorization Request parameters. +(1) The Verifier sends to the Wallet an Authorization Request that contains a Request URI from where to obtain the Request Object containing Authorization Request parameters. (2) The Wallet sends an HTTP GET request to the Request URI to retrieve the Request Object. -(2.5) The HTTP GET response returns the Request Object containing Authorization Request parameters. It especially contains a Presentation Definition as defined in [@!DIF.PresentationExchange] that describes the requirements of the Credential(s) that the Verifier is requesting to be presented. Such requirements could include what type of Credential(s), in what format(s), which individual Claims within those Credential(s) (Selective Disclosure), etc. The Wallet processes the Request Object and determines what Credentials are available matching the Verifier's request. The Wallet also authenticates the End-User and gathers her consent to present the requested Credentials. +(2.5) The HTTP GET response returns the Request Object containing Authorization Request parameters. It especially contains a Presentation Definition as defined in [@!DIF.PresentationExchange] that describes the requirements of the Credential(s) that the Verifier is requesting to be presented. Such requirements could include what type of Credential(s), in what format(s), which individual Claims within those Credential(s) (Selective Disclosure), etc. The Wallet processes the Request Object and determines what Credentials are available matching the Verifier's request. The Wallet also authenticates the End-User and gathers her consent to present the requested Credentials. (3) The Wallet prepares the Verifiable Presentation(s) of the Verifiable Credential(s) that the End-User has consented to. It then sends to the Verifier an Authorization Response where the Verifiable Presentation(s) are contained in the `vp_token` parameter. @@ -219,8 +219,8 @@ Figure: Cross Device Flow OpenID for Verifiable Presentations extends existing OAuth 2.0 mechanisms as following: -* A new `presentation_definition` Authorization Request parameter that uses the [@!DIF.PresentationExchange] syntax is defined to request presentation of Verifiable Credentials in arbitrary formats. See (#vp_token_request) for more details. -* A new `vp_token` response parameter is defined to return Verifiable Presentations to the Verifier in either Authorization or Token Response depending on the Response Type. See (#response) for more details. +* A new `presentation_definition` Authorization Request parameter that uses the [@!DIF.PresentationExchange] syntax is defined to request presentation of Verifiable Credentials in arbitrary formats. See (#vp_token_request) for more details. +* A new `vp_token` response parameter is defined to return Verifiable Presentations to the Verifier in either Authorization or Token Response depending on the Response Type. See (#response) for more details. * New Response Types `vp_token` and `vp_token id_token` are defined to request Verifiable Credentials to be returned in the Authorization Response (standalone or along with a Self-Issued ID Token [@!SIOPv2]). See (#response) for more details. * A new OAuth 2.0 Response Mode `direct_post` is defined to support sending the response across devices, or when the size of the response exceeds the redirect URL character size limitation. See (#response_mode_post) for more details. * The [@!DIF.PresentationExchange] `format` parameter is used throughout the protocol in order to enable customization according to the specific needs of a particular Credential format. Examples in (#alternative_credential_formats) are given for Credential formats as specified in [@VC_DATA], [@ISO.18013-5], [@!I-D.ietf-oauth-sd-jwt-vc], and [@Hyperledger.Indy]. @@ -252,12 +252,15 @@ This specification enables the Verifier to send both Presentation Definition JSO This specification defines the following new parameters: `presentation_definition`: -: A string containing a Presentation Definition JSON object. See (#request_presentation_definition) for more details. This parameter MUST be present when `presentation_definition_uri` parameter, or a `scope` value representing a Presentation Definition is not present. +: A string containing a Presentation Definition JSON object. See (#request_presentation_definition) for more details. Exactly one of `vp_query` or `presentation_definition` or `presentation_definition_uri` MUST be present in the Authorization Request. `presentation_definition_uri`: -: A string containing an HTTPS URL pointing to a resource where a Presentation Definition JSON object can be retrieved. This parameter MUST be present when `presentation_definition` parameter, or a `scope` value representing a Presentation Definition is not present. See (#request_presentation_definition_uri) for more details. +: A string containing an HTTPS URL pointing to a resource where a Presentation Definition JSON object can be retrieved. See (#request_presentation_definition_uri) for more details. Exactly one of `vp_query` or `presentation_definition` or `presentation_definition_uri` MUST be present in the Authorization Request. + +`vp_query`: +: A string containing a JSON-encoded VP Query as defined in (#vp_query). This parameter is OPTIONAL. Exactly one of `vp_query` or `presentation_definition` or `presentation_definition_uri` MUST be present in the Authorization Request. -`client_id_scheme`: +`client_id_scheme`: : OPTIONAL. A string identifying the scheme of the value in the `client_id` Authorization Request parameter (Client Identifier scheme). The `client_id_scheme` parameter namespaces the respective Client Identifier. If an Authorization Request uses the `client_id_scheme` parameter, the Wallet MUST interpret the Client Identifier of the Verifier in the context of the Client Identifier scheme. If the parameter is not present, the Wallet MUST behave as specified in [@!RFC6749]. See (#client_metadata_management) for the values defined by this specification. If the same Client Identifier is used with different Client Identifier schemes, those occurrences MUST be treated as different Verifiers. Note that the Verifier needs to determine which Client Identifier schemes the Wallet supports prior to sending the Authorization Request in order to choose a supported scheme. `client_metadata`: @@ -265,11 +268,11 @@ This specification defines the following new parameters: A public key to be used by the Wallet as an input to the key agreement to encrypt Authorization Response (see (#jarm)). It MAY be passed by the Verifier using the `jwks` or the `jwks_uri` claim within the `client_metadata` request parameter. -`request_uri_method`: +`request_uri_method`: : 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. +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. The following additional considerations are given for pre-existing Authorization Request parameters: @@ -280,9 +283,9 @@ The following additional considerations are given for pre-existing Authorization : OPTIONAL. Defined in [@!RFC6749]. The Wallet MAY allow Verifiers to request presentation of Verifiable Credentials by utilizing a pre-defined scope value. See (#request_scope) for more details. `response_mode`: -: OPTIONAL. Defined in [@!OAuth.Responses]. This parameter is used (through the new Response Mode `direct_post`) to ask the Wallet to send the response to the Verifier via an HTTPS connection (see (#response_mode_post) for more details). It is also used to request signing and encrypting (see (#jarm) for more details). If the parameter is not present, the default value is `fragment`. +: OPTIONAL. Defined in [@!OAuth.Responses]. This parameter is used (through the new Response Mode `direct_post`) to ask the Wallet to send the response to the Verifier via an HTTPS connection (see (#response_mode_post) for more details). It is also used to request signing and encrypting (see (#jarm) for more details). If the parameter is not present, the default value is `fragment`. -The following is a non-normative example of an Authorization Request: +The following is a non-normative example of an Authorization Request: ``` GET /authorize? @@ -293,7 +296,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` and `client_metadata` parameters): ``` GET /authorize? @@ -320,7 +323,7 @@ The following non-normative example shows how the Verifiers can also ask for alt <{{examples/request/vp_token_alternative_credentials.json}} -The Verifiable Credential and Verifiable Presentation formats supported by the Wallet should be published in its metadata using the metadata parameter `vp_formats_supported` (see (#as_metadata_parameters)). +The Verifiable Credential and Verifiable Presentation formats supported by the Wallet should be published in its metadata using the metadata parameter `vp_formats_supported` (see (#as_metadata_parameters)). The formats supported by a Verifier may be set up using the metadata parameter `vp_formats` (see (#client_metadata_parameters)). The Wallet MUST ignore any `format` property inside a `presentation_definition` object if that `format` was not included in the `vp_formats` property of the metadata. @@ -328,7 +331,7 @@ Note: When a Verifier is requesting the presentation of a Verifiable Presentatio ## `presentation_definition_uri` Parameter {#request_presentation_definition_uri} -`presentation_definition_uri` is used to retrieve the Presentation Definition from the resource at the specified URL, rather than being passed by value. The Wallet MUST send an HTTP GET request without additional parameters. The resource MUST be exposed without further need to authenticate or authorize. +`presentation_definition_uri` is used to retrieve the Presentation Definition from the resource at the specified URL, rather than being passed by value. The Wallet MUST send an HTTP GET request without additional parameters. The resource MUST be exposed without further need to authenticate or authorize. The protocol for the `presentation_definition_uri` MUST be HTTPS. @@ -380,21 +383,21 @@ Content-Type: application/json Wallets MAY support requesting presentation of Verifiable Credentials using OAuth 2.0 scope values. -Such a scope value MUST be an alias for a well-defined Presentation Definition that will be -referred to in the `presentation_submission` response parameter. +Such a scope value MUST be an alias for a well-defined Presentation Definition that will be +referred to in the `presentation_submission` response parameter. -The specific scope values, and the mapping between a certain scope value and the respective -Presentation Definition is out of scope of this specification. +The specific scope values, and the mapping between a certain scope value and the respective +Presentation Definition is out of scope of this specification. Possible options include normative text in a separate specification defining scope values along with a description of their -semantics or machine readable definitions in the Wallet's server metadata, mapping a scope value to an equivalent -Presentation Definition JSON object. +semantics or machine readable definitions in the Wallet's server metadata, mapping a scope value to an equivalent +Presentation Definition JSON object. -Such definition of a scope value MUST allow the Verifier to determine the identifiers of the Presentation Definition and Input Descriptor(s) in the `presentation_submission` response parameter (`definition_id` and `descriptor_map.id` respectively) as well as the Credential formats and types in the `vp_token` response parameter defined in (#response-parameters). +Such definition of a scope value MUST allow the Verifier to determine the identifiers of the Presentation Definition and Input Descriptor(s) in the `presentation_submission` response parameter (`definition_id` and `descriptor_map.id` respectively) as well as the Credential formats and types in the `vp_token` response parameter defined in (#response-parameters). It is RECOMMENDED to use collision-resistant scopes values. -The following is a non-normative example of an Authorization Request using the scope value `com.example.IDCardCredential_presentation`, +The following is a non-normative example of an Authorization Request using the scope value `com.example.IDCardCredential_presentation`, which is an alias for the first Presentation Definition example given in (#request_presentation_definition): ``` @@ -417,7 +420,7 @@ See (#response) on how the `response_type` value determines the response used to ## Passing Authorization Request Across Devices -There are use-cases when the Authorization Request is being displayed on a device different from a device on which the requested Credential is stored. In those cases, an Authorization Request can be passed across devices by being rendered as a QR Code. +There are use-cases when the Authorization Request is being displayed on a device different from a device on which the requested Credential is stored. In those cases, an Authorization Request can be passed across devices by being rendered as a QR Code. The usage of the Response Mode `direct_post` (see (#response_mode_post)) in conjunction with `request_uri` is RECOMMENDED, since Authorization Request size might be large and might not fit in a QR code. @@ -428,13 +431,13 @@ When the Verifier is sending a Request Object as defined in [@!RFC9101], the `au - the `aud` Claim MUST equal to the `issuer` Claim value, when Dynamic Discovery is performed. - the `aud` Claim MUST be "https://self-issued.me/v2", when Static Discovery metadata is used. -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. +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} 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. -This specification defines the following values for the `client_id_scheme` parameter, followed by the examples where applicable: +This specification defines the following values for the `client_id_scheme` parameter, followed by the examples where applicable: * `pre-registered`: This value represents the [@!RFC6749] default behavior, i.e., the Client Identifier needs to be known to the Wallet in advance of the Authorization Request. The Verifier metadata is obtained using [@!RFC7591] or through out-of-band mechanisms. @@ -483,19 +486,19 @@ Other specifications can define further values for the `client_id_scheme` parame ## Request URI Method `post` {#request_uri_method_post} -This request is handled by the Request URI endpoint of the Verifier. +This request is handled by the Request URI endpoint of the Verifier. The request MUST use the HTTP POST method with the `https` scheme, and the content type `application/x-www-form-urlencoded` and the accept header set to `application/oauth-authz-req+jwt`. -The following parameters are defined: +The following parameters are defined: `wallet_metadata`: -: OPTIONAL. A String containing a JSON object containing metadata parameters as defined in (#as_metadata_parameters). +: OPTIONAL. A String containing a JSON object containing metadata parameters as defined in (#as_metadata_parameters). `wallet_nonce`: -: OPTIONAL. A String value used to mitigate replay attacks of the Authorization Request. When received, the Verifier MUST use it as the `wallet_nonce` value in the signed authorization request object. Value can be a base64url encoded, fresh, cryptographically random number with sufficient entropy. +: OPTIONAL. A String value used to mitigate replay attacks of the Authorization Request. When received, the Verifier MUST use it as the `wallet_nonce` value in the signed authorization request object. Value can be a base64url encoded, fresh, cryptographically random number with sufficient entropy. -If the Wallet requires the Verifier to encrypt the Request Object, it SHOULD use the `jwks` or `jwks_uri` parameter within the `wallet_metadata` parameter to pass the public key for the input to the key agreement. Other mechanisms to pass the encryption key can be used as well. If the Wallet requires an encrypted Authorization Response, it SHOULD specify supported encryption algorithms using the `authorization_encryption_alg_values_supported` and `authorization_encryption_enc_values_supported` parameters. +If the Wallet requires the Verifier to encrypt the Request Object, it SHOULD use the `jwks` or `jwks_uri` parameter within the `wallet_metadata` parameter to pass the public key for the input to the key agreement. Other mechanisms to pass the encryption key can be used as well. If the Wallet requires an encrypted Authorization Response, it SHOULD specify supported encryption algorithms using the `authorization_encryption_alg_values_supported` and `authorization_encryption_enc_values_supported` parameters. Additionally, if the `client_id_scheme` value permits signed Request Objects, the Wallet SHOULD list supported cryptographic algorithms for securing the Request Object through the `request_object_signing_alg_values_supported` parameter. Conversely, the Wallet MUST NOT include this parameter if the `client_id_scheme` precludes signed Request Objects. @@ -532,7 +535,7 @@ The following is a non-normative example of a request object: } ``` -The Wallet MUST process the request as defined in [@RFC9101]. Additionally, if the Wallet passed a `wallet_nonce` in the POST request, the Wallet MUST validate whether the request object contains the respective nonce value in a `wallet_nonce` claim. If it does not, the Wallet MUST terminate request processing. +The Wallet MUST process the request as defined in [@RFC9101]. Additionally, if the Wallet passed a `wallet_nonce` in the POST request, the Wallet MUST validate whether the request object contains the respective nonce value in a `wallet_nonce` claim. If it does not, the Wallet MUST terminate request processing. The Wallet MUST extract the set of Authorization Request parameters from the Request Object. The Wallet MUST only use the parameters in this Request Object, even if the same parameter was provided in an Authorization Request query parameter. The Client Identifier value in the `client_id` Authorization Request parameter and the Request Object `client_id` claim value MUST be identical. If the Authorization Request contains a `client_id_scheme` parameter, the `client_id_scheme` Authorization Request parameter and the Request Object `client_id_scheme` claim value MUST be identical. If any of these conditions are not met, the Wallet MUST terminate request processing. @@ -542,6 +545,266 @@ The Wallet then validates the request as specified in OAuth 2.0 [@RFC6749]. If the Verifier responds with any HTTP error response, the Wallet MUST terminate the process. +# Verifiable Presentation Query Language {#vp_query} + +The Verifiable Presentation Query Language (VP Query) is a JSON-encoded query +language that allows the Verifier to request the Wallet to present Verifiable +Credentials that match the query. The query consists of a set of constraints +that the requested Verifiable Credentials must satisfy. The Wallet evaluates the +query against the Verifiable Credentials it holds and returns the Verifiable +Presentations that match the query. + +A valid VP Query is defined as a JSON-encoded object with the following +properties: + +`credentials`: +: REQUIRED. An object. Each key in the object represents one +Credential Query as defined in (#credential_query). The key is a string that +uniquely identifies the Credential Query within the VP Query. + +`rules`: +: OPTIONAL. An object defining rules that specify which combinations of +credentials MAY be returned by the Wallet, as defined in (#credential_rules). If +omitted, all credentials listed in `credentials` are requested for presentation. + +## Credential Query {#credential_query} + +A Credential Query is an object representing a request for one specific +credential. It contains the following properties: + +`format`: +: REQUIRED. A string that specifies the format of the requested +Verifiable Credential. Valid Credential format identifier values are defined in +Appendix A of [@!OpenID.VCI]. The value of this property MUST be one of the +supported Credential formats as defined in the Wallet's metadata. + +Format-specific properties (using the format value as a key): +: OPTIONAL. +Additional properties requested by the Verifier that are specific to the +Credential format, as defined in (#format_specific_properties). If omitted, +no format-specific restrictions are placed on the requested Credential. + +`purpose`: +: OPTIONAL. A purpose description array as defined in +(#purpose_description). + +`claims`: +: OPTIONAL. An array that specifies the claims that the requested +Verifiable Credential must contain. Each entry in the array corresponds to at +least one claim that MUST be returned by the Wallet to fulfill the credential +request (unless specified otherwise by extensions to this specification). Each +entry MUST be one of the following objects: + +- Claim query: An object describing a single claim that is to be returned, as + specified in (#claim_query). +- An optionality rule: An object containing the following properties: + - `required` (REQUIRED): defines a number of claims that must be returned from + the `from` set of claims, as specified next. + - `from` (REQUIRED): An array; each entry is either a claim query or another + optionality rule. The entries are listed in order of preference, with the + first entry being the most preferred. + +More than two nested levels of optionality rules MUST NOT be used by a Verifier +or allowed by a Wallet. + +## Format-specific Properties {#format_specific_properties} + +The following format-specific properties are defined: + +### Format `vc+sd-jwt` {#format_vc+sd-jwt} + +`vct_values`: +: OPTIONAL. An array of strings that specifies allowed values for +the type of the requested Verifiable Credential. All elements in the array MUST +be valid type identifiers as defined in [@!I-D.ietf-oauth-sd-jwt-vc]. The Wallet +MAY return credentials that inherit from any of the specified types, following +the inheritance logic defined in [@!I-D.ietf-oauth-sd-jwt-vc]. + +`credential_signing_alg_values`: +: OPTIONAL. An array of strings that specifies +the allowed algorithms for signing the SD-JWT (i.e., only the issuer-signed part). + +`kbjwt_signing_alg_values`: +: OPTIONAL. An array of strings that specifies the +allowed algorithms for signing the Key-Binding JWT (KB-JWT) (i.e., the part signed +by the holder). + +`sd_alg_values`: +: OPTIONAL. An array of strings that specifies the allowed hash algorithms for +digests in the SD-JWT and KB-JWT. + +### Format `mso_mdoc` {#format_mso_mdoc} + +TBD + +### Format `jwt_vp*` + +TBD + +## Claim Query {#claim_query} + +A claim query is an object that describes one or more claims that are to be +returned. Depending on the format of the requested Verifiable Credential, the +claim query can contain different properties. + + + +### JSON-based Claims Structures {#json_based_claims} + +For credentials containing JSON-based claims structures, the following +properties are defined: + +`path`: +: REQUIRED. A claims path pointer that specifies the path to the claim +within the Verifiable Credential, as defined in (#claims_path_query). + +### ISO 18013-5 Credentials {#iso_18013-5} + +For ISO 18013-5 Credentials, the following properties are defined: + +`namespace`: +: REQUIRED. A string that specifies the namespace of the claim +within the Verifiable Credential, e.g., `org.iso.18013.5.1`. + +`claim_name`: +: REQUIRED. A string that specifies the name of the claim within +the Verifiable Credential, e.g., `first_name`. + +### Claims Path Pointer + +A claims path pointer is a pointer into the JSON structure of the Verifiable +Credential, identifying one or more claims. A claims path pointer MUST be a +non-empty array of strings and non-negative integers. A string indicates that +the respective key is to be selected, a `*` value indicates that all elements of +the currently selected array(s) are to be selected, and a non-negative integer +indicates that the respective index in an array is to be selected. The path is +formed as follows: + + - Start with an empty array. + - To address a particular claim within an object, append the key (claim name) + to the array. + - To address an element within an array, append the index to the array (as a + non-negative, 0-based integer). + - To address all elements within an array, append the string `*` to the array. + +Verifiers MUST NOT point to the same claim more than once in a single query. +Wallets SHOULD ignore such duplicate claim queries. + +#### Example + +The following shows a non-normative, simplified example of a Credential: + +```json +{ + "name": "Arthur Dent", + "address": { + "street_address": "42 Market Street", + "city": "Milliways", + "postal_code": "12345" + }, + "degrees": [ + { + "type": "Bachelor of Science", + "university": "University of Betelgeuse" + }, + { + "type": "Master of Science", + "university": "University of Betelgeuse" + } + ], + "nationalities": ["British", "Betelgeusian"] +} +``` + +The following shows examples of claims path queries and the respective selected +claims: + +- `["name"]`: The claim `name` with the value `Arthur Dent` is selected. +- `["address"]`: The claim `address` with its sub-claims as the value is + selected. +- `["address", "street_address"]`: The claim `street_address` with the value `42 + Market Street` is selected. +- `["degrees", "*", "type"]`: All `type` claims in the `degrees` array are + selected. +- `["nationalities", 1]`: The second nationality is selected. +- `[]` (empty array): The entire Credential is selected. + +#### Processing + +In detail, the array is processed by the Wallet from left to right as follows: + + 1. Select the root element of the credential, i.e., the top-level JSON object. + 2. Process the query components from left to right: + 1. If the query component is a string, select the element in the respective + key in the currently selected element(s). If any of the currently + selected element(s) is not an object, abort processing and return an + error. If the key does not exist in any element currently selected, + remove that element from the selection. + 2. If the query component is `*`, select all elements of the currently + selected array(s). If any of the currently selected element(s) is not an + array, abort processing and return an error. + 3. If the query component is a non-negative integer, select the element at + the respective index in the currently selected array(s). If any of the + currently selected element(s) is not an array, abort processing and + return an error. If the index does not exist in a selected array, remove + that array from the selection. + 3. If the set of elements currently selected is empty, abort processing and + return an error. + +The result of the processing is the set of elements which is requested for +presentation. + + +## Purpose Description {#purpose_description} + +A purpose description array is an object that describes the purpose for which +the Verifier is requesting the Verifiable Credential. It can contain multiple +objects, each describing the purpose in a specific language. Each object +contains the following properties: + +`lang:` +: REQUIRED. A string that specifies the language of the purpose +description. The value of this property MUST be a valid language tag as defined +in [@!BCP47]. + +`text`: +: REQUIRED. A string that contains the purpose description in the +language specified by the `lang` property. + +## Credential Rules {#credential_rules} + +Just as for claims, the Verifier can define rules that specify which +combinations of credentials MAY be returned by the Wallet. The rules are defined +in the top-level property `rules`. The values is a credential rule object, +defined as having the following properties: + +- `required`: An integer specifying the number of credentials that MUST be + returned from the `from` set of credentials. +- `from`: An array of objects, each being either + - a nested credential rule, or + - a credential query reference, i.e., an object with a single key `ref` that + references a credential query defined in the `credentials` object. + +Within `from`, the credentials are listed in order of preference, with the first +entry being the most preferred. + +## Examples {#vp_query_examples} + +The following is a non-normative example of a VP Query that requests a Verifiable +Credential of the format `vc+sd-jwt` with a type value of +`https://credentials.example.com/identity_credential` and the claims `last_name`, +`first_name`, and `address.street_address`: + +<{{examples/query_lang/simple.json}} + +Additional examples can be found in (#vp_query_examples). + +## Additional Request Properties {#additional_request_properties} + +`intend_to_retain`: TBD + +`if_present`: TBD + # Response {#response} A VP Token is only returned if the corresponding Authorization Request contained a `presentation_definition` parameter, a `presentation_definition_uri` parameter, or a `scope` parameter representing a Presentation Definition (#vp_token_request). @@ -580,7 +843,7 @@ The `presentation_submission` element MUST be included as a separate response pa Including the `presentation_submission` parameter as a separate response parameter allows the Wallet to provide the Verifier with additional information about the format and structure in advance of the processing of the VP Token, and can be used even with the Credential formats that do not allow for the direct inclusion of `presentation_submission` parameters inside a Credential itself. -The following is a non-normative example of an Authorization Response when the Response Type value in the Authorization Request was `vp_token`: +The following is a non-normative example of an Authorization Response when the Response Type value in the Authorization Request was `vp_token`: ``` HTTP/1.1 302 Found @@ -597,7 +860,7 @@ The following is a non-normative example of a `presentation_submission` paramete <{{examples/response/presentation_submission.json}} -A `descriptor_map` element MUST contain a `path_nested` parameter referring to the actual Credential carried in the respective Verifiable Presentation. +A `descriptor_map` element MUST contain a `path_nested` parameter referring to the actual Credential carried in the respective Verifiable Presentation. The following is a non-normative example of a VP Token containing multiple Verifiable Presentations: @@ -609,9 +872,9 @@ The following is a non-normative example of a `presentation_submission` paramete ## Response Mode "direct_post" {#response_mode_post} -The Response Mode `direct_post` allows the Wallet to send the Authorization Response to an endpoint controlled by the Verifier via an HTTP POST request. +The Response Mode `direct_post` allows the Wallet to send the Authorization Response to an endpoint controlled by the Verifier via an HTTP POST request. -It has been defined to address the following use cases: +It has been defined to address the following use cases: * Verifier and Wallet are located on different devices; thus, the Wallet cannot send the Authorization Response to the Verifier using a redirect. * The Authorization Response size exceeds the URL length limits of user agents, so flows relying only on redirects (such as Response Mode `fragment`) cannot be used. In those cases, the Response Mode `direct_post` is the way to convey the Verifiable Presentations to the Verifier without the need for the Wallet to have a backend. @@ -621,12 +884,12 @@ The Response Mode is defined in accordance with [@!OAuth.Responses] as follows: `direct_post`: : In this mode, the Authorization Response is sent to the Verifier using an HTTP POST request to an endpoint controlled by the Verifier. The Authorization Response parameters are encoded in the body using the `application/x-www-form-urlencoded` content type. The flow can end with an HTTP POST request from the Wallet to the Verifier, or it can end with a redirect that follows the HTTP POST request, if the Verifier responds with a redirect URI to the Wallet. -The following new Authorization Request parameter is defined to be used in conjunction with Response Mode `direct_post`: +The following new Authorization Request parameter is defined to be used in conjunction with Response Mode `direct_post`: `response_uri`: : REQUIRED when the Response Mode `direct_post` is used. The Response URI to which the Wallet MUST send the Authorization Response using an HTTP POST request as defined by the Response Mode `direct_post`. The Response URI receives all Authorization Response parameters as defined by the respective Response Type. When the `response_uri` parameter is present, the `redirect_uri` Authorization Request parameter MUST NOT be present. If the `redirect_uri` Authorization Request parameter is present when the Response Mode is `direct_post`, the Wallet MUST return an `invalid_request` Authorization Response error. The `response_uri` value MUST be a value that the client would be permitted to use as `redirect_uri` when following the rules defined in (#client_metadata_management). -Note: The Verifier's component providing the user interface (Frontend) and the Verifier's component providing the Response URI (Response Endpoint) need to be able to map authorization requests to the respective authorization responses. The Verifier MAY use the `state` Authorization Request parameter to add appropriate data to the Authorization Response for that purpose, for details see (#implementation_considerations_direct_post). +Note: The Verifier's component providing the user interface (Frontend) and the Verifier's component providing the Response URI (Response Endpoint) need to be able to map authorization requests to the respective authorization responses. The Verifier MAY use the `state` Authorization Request parameter to add appropriate data to the Authorization Response for that purpose, for details see (#implementation_considerations_direct_post). The following is a non-normative example of the payload of a Request Object with Response Mode `direct_post`: @@ -694,7 +957,7 @@ Content-Type: application/json Cache-Control: no-store { - "redirect_uri": "https://client.example.org/cb#response_code=091535f699ea575c7937fa5f0f454aee" + "redirect_uri": "https://client.example.org/cb#response_code=091535f699ea575c7937fa5f0f454aee" } ``` @@ -723,7 +986,7 @@ The following is a non-normative example of the payload of a JWT used in an Auth The JWT response document MUST include `vp_token` and `presentation_submission` parameters as defined in (#response-parameters). -The key material used for encryption and signing SHOULD be determined using existing metadata mechanisms. +The key material used for encryption and signing SHOULD be determined using existing metadata mechanisms. To obtain Verifier's public key for the input to the key agreement to encrypt the Authorization Response, the Wallet MUST use `jwks` or `jwks_uri` claim within the `client_metadata` request parameter, or within the metadata defined in the Entity Configuration when [@!OpenID.Federation] is used, or other mechanisms. @@ -747,7 +1010,7 @@ The following is a non-normative example of the payload of the JWT used in the e The error response follows the rules as defined in [@!RFC6749], with the following additional clarifications: -`invalid_scope`: +`invalid_scope`: - Requested scope value is invalid, unknown, or malformed. @@ -852,7 +1115,7 @@ Verifier utilizing this specification has multiple options to obtain Wallet's me # Verifier Metadata (Client Metadata) {#client_metadata} -To convey Verifier metadata, Client metadata defined in Section 2 of [@!RFC7591] is used. +To convey Verifier metadata, Client metadata defined in Section 2 of [@!RFC7591] is used. This specification defines how the Wallet can determine Credential formats, proof types and algorithms supported by the Verifier to be used in a protocol exchange. @@ -870,12 +1133,12 @@ The Verifier Attestation JWT is a JWT especially designed to allow a Wallet to a A Verifier Attestation JWT MUST contain the following claims: -* `iss`: REQUIRED. This claim identifies the issuer of the Verifier Attestation JWT. The `iss` value MAY be used to retrieve the issuer's public key. How the trust is established between Wallet and Issuer and how the public key is obtained for validating the attestation's signature is out of scope of this specification. +* `iss`: REQUIRED. This claim identifies the issuer of the Verifier Attestation JWT. The `iss` value MAY be used to retrieve the issuer's public key. How the trust is established between Wallet and Issuer and how the public key is obtained for validating the attestation's signature is out of scope of this specification. * `sub`: REQUIRED. The value of this claim MUST be the `client_id` of the client making the credential request. * `iat`: OPTIONAL. (number). The value of this claim MUST be the time at which the Verifier Attestation JWT was issued using the syntax defined in [RFC7519]. * `exp`: REQUIRED. (number). The value of this claim MUST be the time at which the Verifier Attestation JWT expires using the syntax defined in [RFC7519]. The Wallet MUST reject any Verifier Attestation JWT with an expiration time that has passed, subject to allowable clock skew between systems. * `nbf`: OPTIONAL. The Verifier Attestation JWT MAY contain an "nbf" (not before) claim that identifies the time before which the token MUST NOT be accepted for processing. -* `cnf`: REQUIRED. This claim contains the confirmation method as defined in [@!RFC7800]. It MUST contain a JWK as defined in Section 3.2 of [RFC7800]. This claim determines the public key for which's corresponding private key the Verifier MUST proof possession of when presenting the Verifier Attestation JWT. This additional security measure allows the Verifier to obtain a Verifier Attestion JWT from a trusted issuer and use it for a long time independent of that issuer without the risk of an advisary impersonating the Verifier by replaying a captured attestation. +* `cnf`: REQUIRED. This claim contains the confirmation method as defined in [@!RFC7800]. It MUST contain a JWK as defined in Section 3.2 of [RFC7800]. This claim determines the public key for which's corresponding private key the Verifier MUST proof possession of when presenting the Verifier Attestation JWT. This additional security measure allows the Verifier to obtain a Verifier Attestion JWT from a trusted issuer and use it for a long time independent of that issuer without the risk of an advisary impersonating the Verifier by replaying a captured attestation. The Verifier Attestation JWT MAY use any claim registered in the "JSON Web Token Claims" registry as defined in [@!RFC7519]. @@ -883,11 +1146,11 @@ Verifier Attestation JWTs compliant with this specification MUST use the media t A Verifier Attestation JWT MUST set the `typ` JOSE header to `verifier-attestation+jwt`. -The Verifier Attestation JWT MAY be conveyed in the header of a JWS signed object (JOSE header). +The Verifier Attestation JWT MAY be conveyed in the header of a JWS signed object (JOSE header). -This specification introduces a JOSE header, which can be used to add a JWT to such a header as follows: +This specification introduces a JOSE header, which can be used to add a JWT to such a header as follows: -* `jwt`: This JOSE header MUST contain a JWT. +* `jwt`: This JOSE header MUST contain a JWT. In the context of this specification, such a JWT MUST set the `typ` JOSE header to `verifier-attestation+jwt`. @@ -976,9 +1239,9 @@ When using Response Mode `direct_post`, also see (#security_considerations_direc ## Response Mode `direct_post` {#implementation_considerations_direct_post} -The design of the interactions between the different components of the Verifier (especially Frontend and Response Endpoint) when using Response Mode `direct_post` is at the discretion of the Verifier since it does not affect the interface between the Verifier and the Wallet. +The design of the interactions between the different components of the Verifier (especially Frontend and Response Endpoint) when using Response Mode `direct_post` is at the discretion of the Verifier since it does not affect the interface between the Verifier and the Wallet. -In order to support implementers, this section outlines a possible design that fulfills the Security Considerations given in (#security_considerations). +In order to support implementers, this section outlines a possible design that fulfills the Security Considerations given in (#security_considerations). The design is illustrated in the following sequence diagram: @@ -987,7 +1250,7 @@ The design is illustrated in the following sequence diagram: +-------+ +------------+ +---------------------+ +----------+ | User | | Verifier | | Verifier | | Wallet | | | | | | Response Endpoint | | | -+-------+ +------------+ +---------------------+ +----------+ ++-------+ +------------+ +---------------------+ +----------+ | | | | | interacts | | | |------------->| | | @@ -1038,44 +1301,44 @@ Figure: Reference Design for Response Mode `direct_post` (1) The Verifier produces a `nonce` value by generating at least 16 fresh, cryptographically random bytes with sufficient entropy, associates it with the session and base64url encodes it. -(2) The Verifier initiates a new transaction at its Response Endpoint. +(2) The Verifier initiates a new transaction at its Response Endpoint. (3) The Response Endpoint will set up the transaction and respond with two fresh, cryptographically random numbers with sufficient entropy designated as `transaction-id` and `request-id`. Those values are used in the process to identify the authorization response (`request-id`) and to ensure only the Verifier can obtain the Authorization Response data (`transaction-id`). (4) The Verifier then sends the Authorization Request with the `request-id` as `state` and the `nonce` value created in step (1) to the Wallet. -(5) After authenticating the End-User and getting her consent to share the request Credentials, the Wallet sends the Authorization Response with the parameters `vp_token`, `presentation_submission` and `state` to the `response_uri` of the Verifier. +(5) After authenticating the End-User and getting her consent to share the request Credentials, the Wallet sends the Authorization Response with the parameters `vp_token`, `presentation_submission` and `state` to the `response_uri` of the Verifier. -(6) The Verifier's Response Endpoint checks whether the `state` value is a valid `request-id`. If so, it stores the Authorization Response data linked to the respective `transaction-id`. It then creates a `response_code` as fresh, cryptographically random number with sufficient entropy that it also links with the respective Authorization Response data. It then returns the `redirect_uri`, which includes the `response_code` to the Wallet. +(6) The Verifier's Response Endpoint checks whether the `state` value is a valid `request-id`. If so, it stores the Authorization Response data linked to the respective `transaction-id`. It then creates a `response_code` as fresh, cryptographically random number with sufficient entropy that it also links with the respective Authorization Response data. It then returns the `redirect_uri`, which includes the `response_code` to the Wallet. -Note: If the Verifier's Response Endpoint does not return a `redirect_uri`, processing at the Wallet stops at that step. The Verifier is supposed to fetch the Authorization Response without waiting for a redirect (see step 8). +Note: If the Verifier's Response Endpoint does not return a `redirect_uri`, processing at the Wallet stops at that step. The Verifier is supposed to fetch the Authorization Response without waiting for a redirect (see step 8). (7) The Wallet sends the user agent to the Verifier (`redirect_uri`). The Verifier receives the Request and extracts the `response_code` parameter. -(8) The Verifier sends the `response_code` and the `transaction-id` from its session to the Response Endpoint. +(8) The Verifier sends the `response_code` and the `transaction-id` from its session to the Response Endpoint. -* The Response Endpoint uses the `transaction-id` to look the matching Authorization Response data up, which implicitly validates the `transaction-id` associated with the Verifier's session. +* The Response Endpoint uses the `transaction-id` to look the matching Authorization Response data up, which implicitly validates the `transaction-id` associated with the Verifier's session. * If an Authorization Response is found, the Response Endpoint checks whether the `response_code` was associated with this Authorization Response in step (6). -Note: If the Verifier's Response Endpoint did not return a `redirect_uri` in step (6), the Verifier will periodically query the Response Endpoint with the `transaction-id` to obtain the Authorization Response once it becomes available. +Note: If the Verifier's Response Endpoint did not return a `redirect_uri` in step (6), the Verifier will periodically query the Response Endpoint with the `transaction-id` to obtain the Authorization Response once it becomes available. -(9) The Response Endpoint returns the VP Token and Presentation Submission for further processing to the Verifier. +(9) The Response Endpoint returns the VP Token and Presentation Submission for further processing to the Verifier. (10) The Verifier checks whether the `nonce` received in the Credential(s) in the VP Token in step (9) corresponds to the `nonce` value from the session. The Verifier then consumes the VP Token and invalidates the `transaction-id`, `request-id` and `nonce` in the session. # Security Considerations {#security_considerations} -## Preventing Replay of the VP Token {#preventing-replay} +## Preventing Replay of the VP Token {#preventing-replay} An attacker could try to inject a VP Token (or an individual Verifiable Presentation), that was obtained from a previous Authorization Response, into another Authorization Response thus impersonating the End-User that originally presented that VP Token or the respective Verifiable Presentation. -Implementers of this specification MUST implement the controls as defined in this section to detect such an attack. +Implementers of this specification MUST implement the controls as defined in this section to detect such an attack. -This specification assumes that a Verifiable Credential is always presented with a cryptographic proof of possession which can be a Verifiable Presentation. This cryptographic proof of possession MUST be bound by the Wallet to the intended audience (the Client Identifier of the Verifier) and the respective transaction (identified by the `nonce` parameter in the Authorization Request). The Verifier MUST verify this binding. +This specification assumes that a Verifiable Credential is always presented with a cryptographic proof of possession which can be a Verifiable Presentation. This cryptographic proof of possession MUST be bound by the Wallet to the intended audience (the Client Identifier of the Verifier) and the respective transaction (identified by the `nonce` parameter in the Authorization Request). The Verifier MUST verify this binding. -The Verifier MUST create a fresh, cryptographically random number with sufficient entropy for every Authorization Request, store it with its current session, and pass it in the `nonce` Authorization Request Parameter to the Wallet. +The Verifier MUST create a fresh, cryptographically random number with sufficient entropy for every Authorization Request, store it with its current session, and pass it in the `nonce` Authorization Request Parameter to the Wallet. -The Wallet MUST link every Verifiable Presentation returned to the Verifier in the VP Token to the `client_id` and the `nonce` values of the respective Authentication Request. +The Wallet MUST link every Verifiable Presentation returned to the Verifier in the VP Token to the `client_id` and the `nonce` values of the respective Authentication Request. The Verifier MUST validate every individual Verifiable Presentation in an Authorization Response and ensure that it is linked to the values of the `client_id` and the `nonce` parameter it had used for the respective Authorization Request. If the response contains multiple Verifiable Presentations which do not contain the same nonce value, the response is rejected. @@ -1119,7 +1382,7 @@ The following is a non-normative example of a Verifiable Presentation of a forma "type": "RsaSignature2018", "created": "2018-09-14T21:19:10Z", "proofPurpose": "authentication", - "verificationMethod": "did:example:ebfeb1f712ebc6f1c276e12ec21#keys-1", + "verificationMethod": "did:example:ebfeb1f712ebc6f1c276e12ec21#keys-1", "challenge": "343s$FSFDa-", "domain": "s6BhdRkqt3", "jws": "eyJhb...nKb78" @@ -1131,13 +1394,13 @@ In the example above, the requested `nonce` value is included as the `challenge` ## Session Fixation {#session_fixation} -To perform a Session Fixation attack, an attacker would start the process using a Verifier executed on a device under his control, capture the Authorization Request and relay it to the device of a victim. The attacker would then periodically try to conclude the process in his Verifier, which would cause the Verifier on his device to try to fetch and verify the Authorization Response. +To perform a Session Fixation attack, an attacker would start the process using a Verifier executed on a device under his control, capture the Authorization Request and relay it to the device of a victim. The attacker would then periodically try to conclude the process in his Verifier, which would cause the Verifier on his device to try to fetch and verify the Authorization Response. -Such an attack is impossible against flows implemented with the Response Mode `fragment` as the Wallet will always send the VP Token to the redirect endpoint on the same device where it resides. This means an attacker could extract a valid Authorization Request from a Verifier on his device and trick a Victim into performing the same Authorization Request on her device. But there is technically no way for an attacker to get hold of the resulting VP Token. +Such an attack is impossible against flows implemented with the Response Mode `fragment` as the Wallet will always send the VP Token to the redirect endpoint on the same device where it resides. This means an attacker could extract a valid Authorization Request from a Verifier on his device and trick a Victim into performing the same Authorization Request on her device. But there is technically no way for an attacker to get hold of the resulting VP Token. -However, the Response Mode `direct_post` is susceptible to such an attack as the result is sent from the Wallet out-of-band to the Verifier's Response Endpoint. +However, the Response Mode `direct_post` is susceptible to such an attack as the result is sent from the Wallet out-of-band to the Verifier's Response Endpoint. -This kind of attack can be detected if the Response Mode `direct_post` is used in conjunction with the redirect URI, which causes the Wallet to redirect the flow to the Verifier's frontend at the device where the transaction was concluded. The Verifier's Response Endpoint MUST include a fresh secret (Response Code) into the redirect URI returned to the Wallet and the Verifier's Response Endpoint MUST require the frontend to pass the respective Response Code when fetching the Authorization Response. That stops session fixation attacks as long as the attacker is unable to get access to the Response Code. +This kind of attack can be detected if the Response Mode `direct_post` is used in conjunction with the redirect URI, which causes the Wallet to redirect the flow to the Verifier's frontend at the device where the transaction was concluded. The Verifier's Response Endpoint MUST include a fresh secret (Response Code) into the redirect URI returned to the Wallet and the Verifier's Response Endpoint MUST require the frontend to pass the respective Response Code when fetching the Authorization Response. That stops session fixation attacks as long as the attacker is unable to get access to the Response Code. See (#implementation_considerations_direct_post) for more implementation considerations. @@ -1151,13 +1414,13 @@ The Wallet MUST ensure the data in the Authorization Response cannot leak throug ### Protection of the Response URI -The Verifier SHOULD protect its Response URI from inadvertent requests by checking that the value of the received `state` parameter corresponds to a recent Authorization Request. It MAY also use JARM [@!JARM] to authenticate the originator of the request. +The Verifier SHOULD protect its Response URI from inadvertent requests by checking that the value of the received `state` parameter corresponds to a recent Authorization Request. It MAY also use JARM [@!JARM] to authenticate the originator of the request. ### Protection of the Authorization Response Data -This specification assumes that the Verifier's Response Endpoint offers an internal interface to other components of the Verifier to obtain (and subsequently process) Authorization Response data. An attacker could try to obtain Authorization Response Data from a Verifier's Response Endpoint by looking up this data through the internal interface. This could lead to leakage valid Verifiable Presentations containing PII. +This specification assumes that the Verifier's Response Endpoint offers an internal interface to other components of the Verifier to obtain (and subsequently process) Authorization Response data. An attacker could try to obtain Authorization Response Data from a Verifier's Response Endpoint by looking up this data through the internal interface. This could lead to leakage valid Verifiable Presentations containing PII. -Implementations of this specification MUST have security mechanisms in place to prevent inadvertent requests against this internal interface. Implementation options to fulfill this requirement include: +Implementations of this specification MUST have security mechanisms in place to prevent inadvertent requests against this internal interface. Implementation options to fulfill this requirement include: * Authentication between the different parts within the Verifier * Two cryptographically random numbers. The first being used to manage state between the Wallet and Verifier. The second being used to ensure that only a legitimate component of the Verifier can obtain the Authorization Response data. @@ -1176,7 +1439,7 @@ If an encrypted Authorization Response has no additional integrity protection, a In many instances the referenced server will be operated by a known federation or other trusted operator, and the URL's domain name will already be widely known. Wallets using this URI can mitigate request forgeries by having a pre-configured set of trusted domain names and only fetching Presentation Definition from these sources. In addition, the Presentation Definitions could be signed by a trusted authority, such as the federation operator. -### JSONPath and Arbitrary Scripting +### JSONPath and Arbitrary Scripting Implementers MUST make sure that JSONPath used as part of `presentation_definition` and `presentation_submission` parameters cannot be used to execute arbitrary scripts on a server. This can be achieved, for example, by implementing the entire syntax of the query without relying on the parsers of programming language engine. For details, see Section 4 of [@I-D.ietf-jsonpath-base]. @@ -1200,7 +1463,7 @@ If no user interaction is required before sending the request, it is easy to req Mandatory user interaction before sending the request, like clicking a button, unlocking the wallet or even just showing a screen of the app, can make this less attractive/likely to being exploited. -Requests from the Wallet to the Verifier SHOULD be sent with the minimal amount of information possible, and in particular, without any HTTP headers identifying the software used for the request (e.g., HTTP libraries or their versions). The Wallet MUST NOT send PII or any other data that could be used for fingerprinting to the Request URI in order to prevent user tracking. +Requests from the Wallet to the Verifier SHOULD be sent with the minimal amount of information possible, and in particular, without any HTTP headers identifying the software used for the request (e.g., HTTP libraries or their versions). The Wallet MUST NOT send PII or any other data that could be used for fingerprinting to the Request URI in order to prevent user tracking. {backmatter} @@ -1307,7 +1570,7 @@ Requests from the Wallet to the Verifier SHOULD be sent with the minimal amount A novel approach to establish trust in Verifiable Credential -issuers in Self-Sovereign Identity ecosystems using TRAIN +issuers in Self-Sovereign Identity ecosystems using TRAIN University of Stuttgart @@ -1437,7 +1700,7 @@ issuers in Self-Sovereign Identity ecosystems using TRAIN Google - + Evernym @@ -1511,15 +1774,15 @@ but can be used with multiple protocols. The Web Platform, working in conjunctio This OpenID4VP profile utilizes the mechanisms of the W3C Digital Credentials API while also allowing to leverage advanced security features of OpenID4VP, if needed. It also defines the OpenID4VP request parameters that MAY be used with the W3C Digital Credentials API. -The Digital Credentials API offers several advantages for implementers of both Verifiers and Wallets. +The Digital Credentials API offers several advantages for implementers of both Verifiers and Wallets. -Firstly, the API serves as a privacy-preserving alternative to invoking Wallets via URLs, particularly custom URL schemes. The underlying app platform will only invoke a Wallet if the user confirms the request based on contextual information about the credential request and the requestor (Verifier). +Firstly, the API serves as a privacy-preserving alternative to invoking Wallets via URLs, particularly custom URL schemes. The underlying app platform will only invoke a Wallet if the user confirms the request based on contextual information about the credential request and the requestor (Verifier). Secondly, the session with the user will always continue in the initial context, typically a browser tab, when the request has been fulfilled (or aborted), which results in an improved user experience. Thirdly, cross-device requests benefit from the use of secure transports with proximity checks, which are handled by the OS platform, e.g., using FIDO CTAP 2.2 with hybrid transports. -And lastly, as part of the request, the Wallet is provided with information about the Verifier's origin as authenticated by the user agent, which is important for phishing resistance. +And lastly, as part of the request, the Wallet is provided with information about the Verifier's origin as authenticated by the user agent, which is important for phishing resistance. ## Protocol @@ -1551,7 +1814,7 @@ try { } ``` -Out of the Authorization Request parameters defined in [@!RFC6749] and (#vp_token_request), the following are supported with this profile: +Out of the Authorization Request parameters defined in [@!RFC6749] and (#vp_token_request), the following are supported with this profile: * `client_id` * `client_id_scheme` @@ -1661,13 +1924,13 @@ The following is a non-normative example of an Authorization Request: <{{examples/request/request.txt}} -The requirements regarding the Credential to be presented are conveyed in the `presentation_definition` parameter. +The requirements regarding the Credential to be presented are conveyed in the `presentation_definition` parameter. The following is a non-normative example of the contents of a `presentation_definition` parameter: <{{examples/request/pd_jwt_vc.json}} -This `presentation_definition` parameter contains a single `input_descriptor` element, which sets the desired format to JWT VC and defines a constraint over the `vc.type` parameter to select Verifiable Credentials of type `IDCredential`. +This `presentation_definition` parameter contains a single `input_descriptor` element, which sets the desired format to JWT VC and defines a constraint over the `vc.type` parameter to select Verifiable Credentials of type `IDCredential`. #### Presentation Response @@ -1675,7 +1938,7 @@ The following is a non-normative example of an Authorization Response: <{{examples/response/response.txt}} -The following is a non-normative example of the content of the `presentation_submission` parameter: +The following is a non-normative example of the content of the `presentation_submission` parameter: <{{examples/response/ps_jwt_vc.json}} @@ -1725,7 +1988,7 @@ The following is a non-normative example of the Verifiable Presentation in the ` <{{examples/response/ldp_vp.json}} -Note: The VP's `challenge` claim contains the value of the `nonce` of the presentation request and the `domain` claims contains the Client Identifier of the Verifier. This allows the Verifier to detect replay of a presentation as recommended in (#preventing-replay). +Note: The VP's `challenge` claim contains the value of the `nonce` of the presentation request and the `domain` claims contains the Client Identifier of the Verifier. This allows the Verifier to detect replay of a presentation as recommended in (#preventing-replay). ## AnonCreds @@ -1739,13 +2002,13 @@ Identifier for a CL-signature crypto scheme used in the examples in this section ### Example Credential -The following is a non-normative example of an AnonCred Credential that will be used throughout this section. +The following is a non-normative example of an AnonCred Credential that will be used throughout this section. <{{examples/credentials/ac_vc.json}} -The most important parts for the purpose of this section are `scheme_id` parameter and `values` parameter that contains the actual End-User claims. +The most important parts for the purpose of this section are `scheme_id` parameter and `values` parameter that contains the actual End-User claims. -### Presentation Request +### Presentation Request #### Request Example {#anoncreds_request} @@ -1759,19 +2022,19 @@ The following is a non-normative example of the content of the `presentation_def The `format` object in the `input_descrioptor` element uses the format identifier `ac_vc` as defined above and sets the `proof_type` to `CLSignature2019` to denote this descriptor requires a Credential in AnonCreds format signed with a CL signature (Camenisch-Lysyanskaya signature). The rest of the expressions operate on the AnonCreds JSON structure. -The `constraints` object requires the selected Credential to conform with the schema definition `did:indy:idu:test:3QowxFtwciWceMFr7WbwnM:2:BasicScheme:0\\.1`, which is denoted as a constraint over the AnonCred's `schema_id` parameter. +The `constraints` object requires the selected Credential to conform with the schema definition `did:indy:idu:test:3QowxFtwciWceMFr7WbwnM:2:BasicScheme:0\\.1`, which is denoted as a constraint over the AnonCred's `schema_id` parameter. #### Request Example with Selective Release of Claims The next example leverages the AnonCreds' capabilities for selective release by requesting a subset of the claims in the Credential to be disclosed to the Verifier. -A non-normative example of an Authorization Request would look the same as in (#anoncreds_request). +A non-normative example of an Authorization Request would look the same as in (#anoncreds_request). The following is a non-normative example of the difference is in the `presentation_definition` parameter: <{{examples/request/pd_ac_vc_sd.json}} -This example is identic to the previous one with the following exceptions: It sets the element `limit_disclosure` of the constraint to `require` and adds two more constraints for the individual claims `given_name` and `family_name`. Since such claims are stored underneath a `values` container in an AnonCred, `values` is part of the path to identify the respective claims. +This example is identic to the previous one with the following exceptions: It sets the element `limit_disclosure` of the constraint to `require` and adds two more constraints for the individual claims `given_name` and `family_name`. Since such claims are stored underneath a `values` container in an AnonCred, `values` is part of the path to identify the respective claims. ### Presentation Response @@ -1962,6 +2225,33 @@ The following is a non-normative example of the payload of a Self-Issued ID Toke Note: The `nonce` and `aud` are set to the `nonce` of the request and the Client Identifier of the Verifier, respectively, in the same way as for the Verifier, Verifiable Presentations to prevent replay. +# Examples for VP Queries {#vp_query_examples} + +The following is a non-normative example of a VP Query that requests a Verifiable +Credential in the format `mso_mdoc` with the claims `vehicle_holder` and +`first_name`: + +<{{examples/query_lang/simple_mdoc.json}} + +The following is a non-normative example of a VP Query that shows the usage of +the `purpose` property, and requests the claim `last_name` and + +- either the claim `zip_code`, or +- the claims `city` and `state`: + +<{{examples/query_lang/nested_claims_queries.json}} + +The following is a non-normative example of a VP Query that requests multiple +Verifiable Credentials; all of them must be returned: + +<{{examples/query_lang/multi_credentials.json}} + +Finally, the following shows a complex query where the Wallet can either deliver +the first credential (containing all data the Verifier needs) or present two +credentials that together contain all the data the Verifier needs: + +<{{examples/query_lang/credentials_alternatives.json}} + # IANA Considerations ## Response Types @@ -2014,7 +2304,7 @@ Interoperability considerations: : n/a This specification registers the following JWS header name in the IANA "JSON Web Signature and Encryption Header Parameters" registry established by [@!RFC7515]. * Header Parameter Name: `jwt` -* Header Parameter Description: This header contains a JWT. Processing rules MAY depend on the `typ` header value of the respective JWT. +* Header Parameter Description: This header contains a JWT. Processing rules MAY depend on the `typ` header value of the respective JWT. * Header Parameter Usage Location: JWS * Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net * Specification Document(s): (#verifier_attestation_jwt) @@ -2035,20 +2325,22 @@ The technology described in this specification was made available from contribut [[ To be removed from the final specification ]] + * Introduced VP Query Language + -21 * removed `client_metadata_uri` authorization parameter * added how OpenID4VP request/response can be used over the browser API * remove path_nested description from Response Parameters section and move it into W3C VC Annex * fix indentation of examples - * added references to ISO/IEC 23220 and 18013 documents + * added references to ISO/IEC 23220 and 18013 documents * added `post` request method for Request URI * Added IETF SD-JWT VC profile -20 * added "verifier_attestation" client id scheme value - + -19 * added "x509_san_uri" and "x509_san_dns" client id scheme value @@ -2059,7 +2351,7 @@ The technology described in this specification was made available from contribut -17 - * direct_post response mode uses state to identify response + * direct_post response mode uses state to identify response * Added sequence diagrams for same and cross device flows to overview section -16 @@ -2069,7 +2361,7 @@ The technology described in this specification was made available from contribut -15 - * Added definition of VP Token + * Added definition of VP Token * Editorial improvements for better readability (restructured request and response section, consistent terminology, and casing) -14 @@ -2091,7 +2383,7 @@ The technology described in this specification was made available from contribut * changed base protocol to OAuth 2.0 * consolidated the examples - + -10 * Added AnonCreds example @@ -2141,6 +2433,6 @@ The technology described in this specification was made available from contribut * adopted DIF Presentation Exchange request syntax * added security considerations regarding replay detection for Verifiable Credentials - -00 + -00 * initial revision From 157e6966ee97e1ca470a1fc3ca2d37f8cda8ff62 Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Thu, 25 Jul 2024 14:12:54 +0200 Subject: [PATCH 02/49] Fix compile errors --- openid-4-verifiable-presentations-1_0.md | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 01613bca..8707cea1 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -656,7 +656,7 @@ properties are defined: `path`: : REQUIRED. A claims path pointer that specifies the path to the claim -within the Verifiable Credential, as defined in (#claims_path_query). +within the Verifiable Credential, as defined in (#claims_path_pointer). ### ISO 18013-5 Credentials {#iso_18013-5} @@ -670,7 +670,7 @@ within the Verifiable Credential, e.g., `org.iso.18013.5.1`. : REQUIRED. A string that specifies the name of the claim within the Verifiable Credential, e.g., `first_name`. -### Claims Path Pointer +### Claims Path Pointer {#claims_path_pointer} A claims path pointer is a pointer into the JSON structure of the Verifiable Credential, identifying one or more claims. A claims path pointer MUST be a @@ -1405,12 +1405,9 @@ Such an attack is impossible against flows implemented with the Response Mode `f However, the Response Mode `direct_post` is susceptible to such an attack as the result is sent from the Wallet out-of-band to the Verifier's Response Endpoint. This kind of attack can be detected if the Response Mode `direct_post` is used in conjunction with the redirect URI, which causes the Wallet to redirect the flow to the Verifier's frontend at the device where the transaction was concluded. The Verifier's Response Endpoint MUST include a fresh secret (Response Code) into the redirect URI returned to the Wallet and the Verifier's Response Endpoint MUST require the frontend to pass the respective Response Code when fetching the Authorization Response. That stops session fixation attacks as long as the attacker is unable to get access to the Response Code. -<<<<<<< HEAD -======= Note that this protection technique is not applicable to cross-device scenarios because the browser used by the wallet will not have the original session. It is also not applicable in same-device scenarios if the wallet uses a browser different from the one used on the presentation request (e.g. device with multiple installed browsers), because the original session will also not be available there. ->>>>>>> main See (#implementation_considerations_direct_post) for more implementation considerations. @@ -1778,6 +1775,17 @@ issuers in Self-Sovereign Identity ecosystems using TRAIN + + + BCP47 + + IETF + + + + + + # 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 e4bd784edef86e2dff9424c48b891a8f4eafbcfa Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Tue, 30 Jul 2024 08:52:35 +0200 Subject: [PATCH 03/49] Apply suggestions from code review Co-authored-by: Ted Thibodeau Jr Co-authored-by: Oliver Terbu Co-authored-by: Christian Bormann <8774236+c2bo@users.noreply.github.com> --- openid-4-verifiable-presentations-1_0.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 8707cea1..74685e21 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -252,13 +252,13 @@ This specification enables the Verifier to send both Presentation Definition JSO This specification defines the following new parameters: `presentation_definition`: -: A string containing a Presentation Definition JSON object. See (#request_presentation_definition) for more details. Exactly one of `vp_query` or `presentation_definition` or `presentation_definition_uri` MUST be present in the Authorization Request. +: A string containing a Presentation Definition JSON object. See (#request_presentation_definition) for more details. Exactly one of `vp_query`, `presentation_definition`, or `presentation_definition_uri` MUST be present in the Authorization Request. `presentation_definition_uri`: -: A string containing an HTTPS URL pointing to a resource where a Presentation Definition JSON object can be retrieved. See (#request_presentation_definition_uri) for more details. Exactly one of `vp_query` or `presentation_definition` or `presentation_definition_uri` MUST be present in the Authorization Request. +: A string containing an HTTPS URL pointing to a resource where a Presentation Definition JSON object can be retrieved. See (#request_presentation_definition_uri) for more details. Exactly one of `vp_query`, `presentation_definition`, or `presentation_definition_uri` MUST be present in the Authorization Request. `vp_query`: -: A string containing a JSON-encoded VP Query as defined in (#vp_query). This parameter is OPTIONAL. Exactly one of `vp_query` or `presentation_definition` or `presentation_definition_uri` MUST be present in the Authorization Request. +: A string containing a JSON-encoded VP Query as defined in (#vp_query). Exactly one of `vp_query`, `presentation_definition`, `presentation_definition_uri` MUST be present in the Authorization Request. `client_id_scheme`: : OPTIONAL. A string identifying the scheme of the value in the `client_id` Authorization Request parameter (Client Identifier scheme). The `client_id_scheme` parameter namespaces the respective Client Identifier. If an Authorization Request uses the `client_id_scheme` parameter, the Wallet MUST interpret the Client Identifier of the Verifier in the context of the Client Identifier scheme. If the parameter is not present, the Wallet MUST behave as specified in [@!RFC6749]. See (#client_metadata_management) for the values defined by this specification. If the same Client Identifier is used with different Client Identifier schemes, those occurrences MUST be treated as different Verifiers. Note that the Verifier needs to determine which Client Identifier schemes the Wallet supports prior to sending the Authorization Request in order to choose a supported scheme. @@ -667,18 +667,18 @@ For ISO 18013-5 Credentials, the following properties are defined: within the Verifiable Credential, e.g., `org.iso.18013.5.1`. `claim_name`: -: REQUIRED. A string that specifies the name of the claim within -the Verifiable Credential, e.g., `first_name`. +: REQUIRED. A string that specifies the name of the claim within the provided namespace +in the Verifiable Credential, e.g., `first_name`. ### Claims Path Pointer {#claims_path_pointer} A claims path pointer is a pointer into the JSON structure of the Verifiable Credential, identifying one or more claims. A claims path pointer MUST be a -non-empty array of strings and non-negative integers. A string indicates that -the respective key is to be selected, a `*` value indicates that all elements of -the currently selected array(s) are to be selected, and a non-negative integer -indicates that the respective index in an array is to be selected. The path is -formed as follows: +non-empty array of strings and non-negative integers. A `*` string value indicates +that all elements of the currently selected array(s) are to be selected; any other +string indicates that the respective key is to be selected; and a non-negative +integer indicates that the respective index in an array is to be selected. The path +is formed as follows: - Start with an empty array. - To address a particular claim within an object, append the key (claim name) @@ -2261,7 +2261,7 @@ the `purpose` property, and requests the claim `last_name` and - either the claim `zip_code`, or - the claims `city` and `state`: -<{{examples/query_lang/nested_claims_queries.json}} +<{{examples/query_lang/nested_claim_queries.json}} The following is a non-normative example of a VP Query that requests multiple Verifiable Credentials; all of them must be returned: From bf0ee771c5efa67c7676e54716ec93f9718bb58b Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Tue, 30 Jul 2024 09:25:28 +0200 Subject: [PATCH 04/49] Add back accidentally deleted whitespace --- openid-4-verifiable-presentations-1_0.md | 213 +++++++++++------------ 1 file changed, 105 insertions(+), 108 deletions(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 74685e21..c1b25a1a 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -46,7 +46,7 @@ organization="Mattr" .# Abstract -This specification defines a protocol for requesting and presenting Verifiable Credentials. +This specification defines a protocol for requesting and presenting Verifiable Credentials. {mainmatter} @@ -54,7 +54,7 @@ This specification defines a protocol for requesting and presenting Verifiable C This specification defines a mechanism on top of OAuth 2.0 [@!RFC6749] that enables presentation of Verifiable Credentials as Verifiable Presentations. Verifiable Credentials and Verifiable Presentations can be of any format, including, but not limited to W3C Verifiable Credentials Data Model [@VC_DATA], ISO mdoc [@ISO.18013-5], IETF SD-JWT VC [@!I-D.ietf-oauth-sd-jwt-vc], and AnonCreds [@Hyperledger.Indy]. -OAuth 2.0 [@!RFC6749] is used as a base protocol as it provides the required rails to build a simple, secure, and developer-friendly Credential presentation layer on top of it. Moreover, implementers can, in a single interface, support Credential presentation and the issuance of Access Tokens for access to APIs based on Verifiable Credentials in the Wallet. OpenID Connect [@!OpenID.Core] deployments can also extend their implementations using this specification with the ability to transport Verifiable Presentations. +OAuth 2.0 [@!RFC6749] is used as a base protocol as it provides the required rails to build a simple, secure, and developer-friendly Credential presentation layer on top of it. Moreover, implementers can, in a single interface, support Credential presentation and the issuance of Access Tokens for access to APIs based on Verifiable Credentials in the Wallet. OpenID Connect [@!OpenID.Core] deployments can also extend their implementations using this specification with the ability to transport Verifiable Presentations. This specification can also be combined with [@!SIOPv2], if implementers require OpenID Connect features, such as the issuance of Self-Issued ID Tokens [@!SIOPv2]. @@ -98,11 +98,11 @@ Verifier: Issuer-Holder-Verifier Model: : A model for exchanging claims, where claims are issued in the form of Verifiable Credentials independent of the process of presenting them as Verifiable Presentation to the Verifiers. An issued Verifiable Credential can (but must not necessarily) be used multiple times. -Holder Binding: -: Ability of the Holder to prove legitimate possession of a Verifiable Credential. +Holder Binding: +: Ability of the Holder to prove legitimate possession of a Verifiable Credential. Cryptographic Holder Binding: -: Ability of the Holder to prove legitimate possession of a Verifiable Credential by proving control over the same private key during the issuance and presentation. Mechanism might depend on the Credential Format. For example, in `jwt_vc_json` Credential Format, a Verifiable Credential with Cryptographic Holder Binding contains a public key or a reference to a public key that matches to the private key controlled by the Holder. +: Ability of the Holder to prove legitimate possession of a Verifiable Credential by proving control over the same private key during the issuance and presentation. Mechanism might depend on the Credential Format. For example, in `jwt_vc_json` Credential Format, a Verifiable Credential with Cryptographic Holder Binding contains a public key or a reference to a public key that matches to the private key controlled by the Holder. Claims-based Holder Binding: : Ability of the Holder to prove legitimate possession of a Verifiable Credential by proofing certain claims, e.g., name and date of birth, for example by presenting another Verifiable Credential. Claims-based Holder Binding allows long term, cross device use of a Credential as it does not depend on cryptographic key material stored on a certain device. One example of such a Verifiable Credential could be a Diploma. @@ -116,13 +116,13 @@ VP Token: Wallet: : An entity used by the Holder to receive, store, present, and manage Verifiable Credentials and key material. There is no single deployment model of a Wallet: Verifiable Credentials and keys can both be stored/managed locally, or by using a remote self-hosted service, or a remote third-party service. In the context of this specification, the Wallet acts as an OAuth 2.0 Authorization Server (see [@!RFC6749]) towards the Credential Verifier which acts as the OAuth 2.0 Client. -# Overview +# Overview This specification defines a mechanism on top of OAuth 2.0 to request and present Verifiable Credentials as Verifiable Presentations. As the primary extension, OpenID for Verifiable Presentations introduces the VP Token as a container to enable End-Users to present Verifiable Presentations to Verifiers using the Wallet. A VP Token contains one or more Verifiable Presentations in the same or different Credential formats. -This specification supports any Credential format used in the Issuer-Holder-Verifier Model, including, but not limited to those defined in [@VC_DATA] (VCDM), [@ISO.18013-5] (mdoc), [@!I-D.ietf-oauth-sd-jwt-vc] (SD-JWT VC), and [@Hyperledger.Indy] (AnonCreds). Credentials of multiple formats can be presented in the same transaction. The examples given in the main part of this specification use W3C Verifiable Credentials, while examples in other Credential formats are given in (#alternative_credential_formats). +This specification supports any Credential format used in the Issuer-Holder-Verifier Model, including, but not limited to those defined in [@VC_DATA] (VCDM), [@ISO.18013-5] (mdoc), [@!I-D.ietf-oauth-sd-jwt-vc] (SD-JWT VC), and [@Hyperledger.Indy] (AnonCreds). Credentials of multiple formats can be presented in the same transaction. The examples given in the main part of this specification use W3C Verifiable Credentials, while examples in other Credential formats are given in (#alternative_credential_formats). Implementations can use any pre-existing OAuth 2.0 Grant Type and Response Type in conjunction with this specification to support different deployment architectures. @@ -138,7 +138,7 @@ Any of the OAuth 2.0 related specifications, such as [@RFC9126] and [@RFC9101], Below is a diagram of a flow where the End-User presents a Credential to a Verifier interacting with the End-User on the same device that the device the Wallet resides on. -The flow utilizes simple redirects to pass Authorization Request and Response between the Verifier and the Wallet. The Verifiable Presentations are returned to the Verifier in the fragment part of the redirect URI, when Response Mode is `fragment`. +The flow utilizes simple redirects to pass Authorization Request and Response between the Verifier and the Wallet. The Verifiable Presentations are returned to the Verifier in the fragment part of the redirect URI, when Response Mode is `fragment`. Note: The diagram does not illustrate all the optional features of this specification. @@ -146,7 +146,7 @@ Note: The diagram does not illustrate all the optional features of this specific ~~~ ascii-art +--------------+ +--------------+ +--------------+ | User | | Verifier | | Wallet | -+--------------+ +--------------+ +--------------+ ++--------------+ +--------------+ +--------------+ | | | | Interacts | | |---------------->| | @@ -164,7 +164,7 @@ Note: The diagram does not illustrate all the optional features of this specific !--- Figure: Same Device Flow -(1) The Verifier sends an Authorization Request to the Wallet. It contains a Presentation Definition as defined in [@!DIF.PresentationExchange] that describes the requirements of the Credential(s) that the Verifier is requesting to be presented. Such requirements could include what type of Credential(s), in what format(s), which individual Claims within those Credential(s) (Selective Disclosure), etc. The Wallet processes the Authorization Request and determines what Credentials are available matching the Verifier's request. The Wallet also authenticates the End-User and gathers consent to present the requested Credentials. +(1) The Verifier sends an Authorization Request to the Wallet. It contains a Presentation Definition as defined in [@!DIF.PresentationExchange] that describes the requirements of the Credential(s) that the Verifier is requesting to be presented. Such requirements could include what type of Credential(s), in what format(s), which individual Claims within those Credential(s) (Selective Disclosure), etc. The Wallet processes the Authorization Request and determines what Credentials are available matching the Verifier's request. The Wallet also authenticates the End-User and gathers consent to present the requested Credentials. (2) The Wallet prepares the Verifiable Presentation(s) of the Verifiable Credential(s) that the End-User has consented to. It then sends to the Verifier an Authorization Response where the Verifiable Presentation(s) are contained in the `vp_token` parameter. @@ -207,11 +207,11 @@ Note: The usage of the Request URI as defined in [@!RFC9101] does not depend on !--- Figure: Cross Device Flow -(1) The Verifier sends to the Wallet an Authorization Request that contains a Request URI from where to obtain the Request Object containing Authorization Request parameters. +(1) The Verifier sends to the Wallet an Authorization Request that contains a Request URI from where to obtain the Request Object containing Authorization Request parameters. (2) The Wallet sends an HTTP GET request to the Request URI to retrieve the Request Object. -(2.5) The HTTP GET response returns the Request Object containing Authorization Request parameters. It especially contains a Presentation Definition as defined in [@!DIF.PresentationExchange] that describes the requirements of the Credential(s) that the Verifier is requesting to be presented. Such requirements could include what type of Credential(s), in what format(s), which individual Claims within those Credential(s) (Selective Disclosure), etc. The Wallet processes the Request Object and determines what Credentials are available matching the Verifier's request. The Wallet also authenticates the End-User and gathers her consent to present the requested Credentials. +(2.5) The HTTP GET response returns the Request Object containing Authorization Request parameters. It especially contains a Presentation Definition as defined in [@!DIF.PresentationExchange] that describes the requirements of the Credential(s) that the Verifier is requesting to be presented. Such requirements could include what type of Credential(s), in what format(s), which individual Claims within those Credential(s) (Selective Disclosure), etc. The Wallet processes the Request Object and determines what Credentials are available matching the Verifier's request. The Wallet also authenticates the End-User and gathers her consent to present the requested Credentials. (3) The Wallet prepares the Verifiable Presentation(s) of the Verifiable Credential(s) that the End-User has consented to. It then sends to the Verifier an Authorization Response where the Verifiable Presentation(s) are contained in the `vp_token` parameter. @@ -219,8 +219,8 @@ Figure: Cross Device Flow OpenID for Verifiable Presentations extends existing OAuth 2.0 mechanisms as following: -* A new `presentation_definition` Authorization Request parameter that uses the [@!DIF.PresentationExchange] syntax is defined to request presentation of Verifiable Credentials in arbitrary formats. See (#vp_token_request) for more details. -* A new `vp_token` response parameter is defined to return Verifiable Presentations to the Verifier in either Authorization or Token Response depending on the Response Type. See (#response) for more details. +* A new `presentation_definition` Authorization Request parameter that uses the [@!DIF.PresentationExchange] syntax is defined to request presentation of Verifiable Credentials in arbitrary formats. See (#vp_token_request) for more details. +* A new `vp_token` response parameter is defined to return Verifiable Presentations to the Verifier in either Authorization or Token Response depending on the Response Type. See (#response) for more details. * New Response Types `vp_token` and `vp_token id_token` are defined to request Verifiable Credentials to be returned in the Authorization Response (standalone or along with a Self-Issued ID Token [@!SIOPv2]). See (#response) for more details. * A new OAuth 2.0 Response Mode `direct_post` is defined to support sending the response across devices, or when the size of the response exceeds the redirect URL character size limitation. See (#response_mode_post) for more details. * The [@!DIF.PresentationExchange] `format` parameter is used throughout the protocol in order to enable customization according to the specific needs of a particular Credential format. Examples in (#alternative_credential_formats) are given for Credential formats as specified in [@VC_DATA], [@ISO.18013-5], [@!I-D.ietf-oauth-sd-jwt-vc], and [@Hyperledger.Indy]. @@ -252,15 +252,12 @@ This specification enables the Verifier to send both Presentation Definition JSO This specification defines the following new parameters: `presentation_definition`: -: A string containing a Presentation Definition JSON object. See (#request_presentation_definition) for more details. Exactly one of `vp_query`, `presentation_definition`, or `presentation_definition_uri` MUST be present in the Authorization Request. +: A string containing a Presentation Definition JSON object. See (#request_presentation_definition) for more details. This parameter MUST be present when `presentation_definition_uri` parameter, or a `scope` value representing a Presentation Definition is not present. `presentation_definition_uri`: -: A string containing an HTTPS URL pointing to a resource where a Presentation Definition JSON object can be retrieved. See (#request_presentation_definition_uri) for more details. Exactly one of `vp_query`, `presentation_definition`, or `presentation_definition_uri` MUST be present in the Authorization Request. - -`vp_query`: -: A string containing a JSON-encoded VP Query as defined in (#vp_query). Exactly one of `vp_query`, `presentation_definition`, `presentation_definition_uri` MUST be present in the Authorization Request. +: A string containing an HTTPS URL pointing to a resource where a Presentation Definition JSON object can be retrieved. This parameter MUST be present when `presentation_definition` parameter, or a `scope` value representing a Presentation Definition is not present. See (#request_presentation_definition_uri) for more details. -`client_id_scheme`: +`client_id_scheme`: : OPTIONAL. A string identifying the scheme of the value in the `client_id` Authorization Request parameter (Client Identifier scheme). The `client_id_scheme` parameter namespaces the respective Client Identifier. If an Authorization Request uses the `client_id_scheme` parameter, the Wallet MUST interpret the Client Identifier of the Verifier in the context of the Client Identifier scheme. If the parameter is not present, the Wallet MUST behave as specified in [@!RFC6749]. See (#client_metadata_management) for the values defined by this specification. If the same Client Identifier is used with different Client Identifier schemes, those occurrences MUST be treated as different Verifiers. Note that the Verifier needs to determine which Client Identifier schemes the Wallet supports prior to sending the Authorization Request in order to choose a supported scheme. `client_metadata`: @@ -268,11 +265,11 @@ This specification defines the following new parameters: A public key to be used by the Wallet as an input to the key agreement to encrypt Authorization Response (see (#jarm)). It MAY be passed by the Verifier using the `jwks` or the `jwks_uri` claim within the `client_metadata` request parameter. -`request_uri_method`: +`request_uri_method`: : 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. +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. The following additional considerations are given for pre-existing Authorization Request parameters: @@ -283,9 +280,9 @@ The following additional considerations are given for pre-existing Authorization : OPTIONAL. Defined in [@!RFC6749]. The Wallet MAY allow Verifiers to request presentation of Verifiable Credentials by utilizing a pre-defined scope value. See (#request_scope) for more details. `response_mode`: -: OPTIONAL. Defined in [@!OAuth.Responses]. This parameter is used (through the new Response Mode `direct_post`) to ask the Wallet to send the response to the Verifier via an HTTPS connection (see (#response_mode_post) for more details). It is also used to request signing and encrypting (see (#jarm) for more details). If the parameter is not present, the default value is `fragment`. +: OPTIONAL. Defined in [@!OAuth.Responses]. This parameter is used (through the new Response Mode `direct_post`) to ask the Wallet to send the response to the Verifier via an HTTPS connection (see (#response_mode_post) for more details). It is also used to request signing and encrypting (see (#jarm) for more details). If the parameter is not present, the default value is `fragment`. -The following is a non-normative example of an Authorization Request: +The following is a non-normative example of an Authorization Request: ``` GET /authorize? @@ -296,7 +293,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` and `client_metadata` parameters): ``` GET /authorize? @@ -323,7 +320,7 @@ The following non-normative example shows how the Verifiers can also ask for alt <{{examples/request/vp_token_alternative_credentials.json}} -The Verifiable Credential and Verifiable Presentation formats supported by the Wallet should be published in its metadata using the metadata parameter `vp_formats_supported` (see (#as_metadata_parameters)). +The Verifiable Credential and Verifiable Presentation formats supported by the Wallet should be published in its metadata using the metadata parameter `vp_formats_supported` (see (#as_metadata_parameters)). The formats supported by a Verifier may be set up using the metadata parameter `vp_formats` (see (#client_metadata_parameters)). The Wallet MUST ignore any `format` property inside a `presentation_definition` object if that `format` was not included in the `vp_formats` property of the metadata. @@ -331,7 +328,7 @@ Note: When a Verifier is requesting the presentation of a Verifiable Presentatio ## `presentation_definition_uri` Parameter {#request_presentation_definition_uri} -`presentation_definition_uri` is used to retrieve the Presentation Definition from the resource at the specified URL, rather than being passed by value. The Wallet MUST send an HTTP GET request without additional parameters. The resource MUST be exposed without further need to authenticate or authorize. +`presentation_definition_uri` is used to retrieve the Presentation Definition from the resource at the specified URL, rather than being passed by value. The Wallet MUST send an HTTP GET request without additional parameters. The resource MUST be exposed without further need to authenticate or authorize. The protocol for the `presentation_definition_uri` MUST be HTTPS. @@ -383,21 +380,21 @@ Content-Type: application/json Wallets MAY support requesting presentation of Verifiable Credentials using OAuth 2.0 scope values. -Such a scope value MUST be an alias for a well-defined Presentation Definition that will be -referred to in the `presentation_submission` response parameter. +Such a scope value MUST be an alias for a well-defined Presentation Definition that will be +referred to in the `presentation_submission` response parameter. -The specific scope values, and the mapping between a certain scope value and the respective -Presentation Definition is out of scope of this specification. +The specific scope values, and the mapping between a certain scope value and the respective +Presentation Definition is out of scope of this specification. Possible options include normative text in a separate specification defining scope values along with a description of their -semantics or machine readable definitions in the Wallet's server metadata, mapping a scope value to an equivalent -Presentation Definition JSON object. +semantics or machine readable definitions in the Wallet's server metadata, mapping a scope value to an equivalent +Presentation Definition JSON object. -Such definition of a scope value MUST allow the Verifier to determine the identifiers of the Presentation Definition and Input Descriptor(s) in the `presentation_submission` response parameter (`definition_id` and `descriptor_map.id` respectively) as well as the Credential formats and types in the `vp_token` response parameter defined in (#response-parameters). +Such definition of a scope value MUST allow the Verifier to determine the identifiers of the Presentation Definition and Input Descriptor(s) in the `presentation_submission` response parameter (`definition_id` and `descriptor_map.id` respectively) as well as the Credential formats and types in the `vp_token` response parameter defined in (#response-parameters). It is RECOMMENDED to use collision-resistant scopes values. -The following is a non-normative example of an Authorization Request using the scope value `com.example.IDCardCredential_presentation`, +The following is a non-normative example of an Authorization Request using the scope value `com.example.IDCardCredential_presentation`, which is an alias for the first Presentation Definition example given in (#request_presentation_definition): ``` @@ -420,7 +417,7 @@ See (#response) on how the `response_type` value determines the response used to ## Passing Authorization Request Across Devices -There are use-cases when the Authorization Request is being displayed on a device different from a device on which the requested Credential is stored. In those cases, an Authorization Request can be passed across devices by being rendered as a QR Code. +There are use-cases when the Authorization Request is being displayed on a device different from a device on which the requested Credential is stored. In those cases, an Authorization Request can be passed across devices by being rendered as a QR Code. The usage of the Response Mode `direct_post` (see (#response_mode_post)) in conjunction with `request_uri` is RECOMMENDED, since Authorization Request size might be large and might not fit in a QR code. @@ -431,13 +428,13 @@ When the Verifier is sending a Request Object as defined in [@!RFC9101], the `au - the `aud` Claim MUST equal to the `issuer` Claim value, when Dynamic Discovery is performed. - the `aud` Claim MUST be "https://self-issued.me/v2", when Static Discovery metadata is used. -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. +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} 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. -This specification defines the following values for the `client_id_scheme` parameter, followed by the examples where applicable: +This specification defines the following values for the `client_id_scheme` parameter, followed by the examples where applicable: * `pre-registered`: This value represents the [@!RFC6749] default behavior, i.e., the Client Identifier needs to be known to the Wallet in advance of the Authorization Request. The Verifier metadata is obtained using [@!RFC7591] or through out-of-band mechanisms. @@ -486,19 +483,19 @@ Other specifications can define further values for the `client_id_scheme` parame ## Request URI Method `post` {#request_uri_method_post} -This request is handled by the Request URI endpoint of the Verifier. +This request is handled by the Request URI endpoint of the Verifier. The request MUST use the HTTP POST method with the `https` scheme, and the content type `application/x-www-form-urlencoded` and the accept header set to `application/oauth-authz-req+jwt`. -The following parameters are defined: +The following parameters are defined: `wallet_metadata`: -: OPTIONAL. A String containing a JSON object containing metadata parameters as defined in (#as_metadata_parameters). +: OPTIONAL. A String containing a JSON object containing metadata parameters as defined in (#as_metadata_parameters). `wallet_nonce`: -: OPTIONAL. A String value used to mitigate replay attacks of the Authorization Request. When received, the Verifier MUST use it as the `wallet_nonce` value in the signed authorization request object. Value can be a base64url encoded, fresh, cryptographically random number with sufficient entropy. +: OPTIONAL. A String value used to mitigate replay attacks of the Authorization Request. When received, the Verifier MUST use it as the `wallet_nonce` value in the signed authorization request object. Value can be a base64url encoded, fresh, cryptographically random number with sufficient entropy. -If the Wallet requires the Verifier to encrypt the Request Object, it SHOULD use the `jwks` or `jwks_uri` parameter within the `wallet_metadata` parameter to pass the public key for the input to the key agreement. Other mechanisms to pass the encryption key can be used as well. If the Wallet requires an encrypted Authorization Response, it SHOULD specify supported encryption algorithms using the `authorization_encryption_alg_values_supported` and `authorization_encryption_enc_values_supported` parameters. +If the Wallet requires the Verifier to encrypt the Request Object, it SHOULD use the `jwks` or `jwks_uri` parameter within the `wallet_metadata` parameter to pass the public key for the input to the key agreement. Other mechanisms to pass the encryption key can be used as well. If the Wallet requires an encrypted Authorization Response, it SHOULD specify supported encryption algorithms using the `authorization_encryption_alg_values_supported` and `authorization_encryption_enc_values_supported` parameters. Additionally, if the `client_id_scheme` value permits signed Request Objects, the Wallet SHOULD list supported cryptographic algorithms for securing the Request Object through the `request_object_signing_alg_values_supported` parameter. Conversely, the Wallet MUST NOT include this parameter if the `client_id_scheme` precludes signed Request Objects. @@ -535,7 +532,7 @@ The following is a non-normative example of a request object: } ``` -The Wallet MUST process the request as defined in [@RFC9101]. Additionally, if the Wallet passed a `wallet_nonce` in the POST request, the Wallet MUST validate whether the request object contains the respective nonce value in a `wallet_nonce` claim. If it does not, the Wallet MUST terminate request processing. +The Wallet MUST process the request as defined in [@RFC9101]. Additionally, if the Wallet passed a `wallet_nonce` in the POST request, the Wallet MUST validate whether the request object contains the respective nonce value in a `wallet_nonce` claim. If it does not, the Wallet MUST terminate request processing. The Wallet MUST extract the set of Authorization Request parameters from the Request Object. The Wallet MUST only use the parameters in this Request Object, even if the same parameter was provided in an Authorization Request query parameter. The Client Identifier value in the `client_id` Authorization Request parameter and the Request Object `client_id` claim value MUST be identical. If the Authorization Request contains a `client_id_scheme` parameter, the `client_id_scheme` Authorization Request parameter and the Request Object `client_id_scheme` claim value MUST be identical. If any of these conditions are not met, the Wallet MUST terminate request processing. @@ -843,7 +840,7 @@ The `presentation_submission` element MUST be included as a separate response pa Including the `presentation_submission` parameter as a separate response parameter allows the Wallet to provide the Verifier with additional information about the format and structure in advance of the processing of the VP Token, and can be used even with the Credential formats that do not allow for the direct inclusion of `presentation_submission` parameters inside a Credential itself. -The following is a non-normative example of an Authorization Response when the Response Type value in the Authorization Request was `vp_token`: +The following is a non-normative example of an Authorization Response when the Response Type value in the Authorization Request was `vp_token`: ``` HTTP/1.1 302 Found @@ -860,7 +857,7 @@ The following is a non-normative example of a `presentation_submission` paramete <{{examples/response/presentation_submission.json}} -A `descriptor_map` element MUST contain a `path_nested` parameter referring to the actual Credential carried in the respective Verifiable Presentation. +A `descriptor_map` element MUST contain a `path_nested` parameter referring to the actual Credential carried in the respective Verifiable Presentation. The following is a non-normative example of a VP Token containing multiple Verifiable Presentations: @@ -872,9 +869,9 @@ The following is a non-normative example of a `presentation_submission` paramete ## Response Mode "direct_post" {#response_mode_post} -The Response Mode `direct_post` allows the Wallet to send the Authorization Response to an endpoint controlled by the Verifier via an HTTP POST request. +The Response Mode `direct_post` allows the Wallet to send the Authorization Response to an endpoint controlled by the Verifier via an HTTP POST request. -It has been defined to address the following use cases: +It has been defined to address the following use cases: * Verifier and Wallet are located on different devices; thus, the Wallet cannot send the Authorization Response to the Verifier using a redirect. * The Authorization Response size exceeds the URL length limits of user agents, so flows relying only on redirects (such as Response Mode `fragment`) cannot be used. In those cases, the Response Mode `direct_post` is the way to convey the Verifiable Presentations to the Verifier without the need for the Wallet to have a backend. @@ -884,12 +881,12 @@ The Response Mode is defined in accordance with [@!OAuth.Responses] as follows: `direct_post`: : In this mode, the Authorization Response is sent to the Verifier using an HTTP POST request to an endpoint controlled by the Verifier. The Authorization Response parameters are encoded in the body using the `application/x-www-form-urlencoded` content type. The flow can end with an HTTP POST request from the Wallet to the Verifier, or it can end with a redirect that follows the HTTP POST request, if the Verifier responds with a redirect URI to the Wallet. -The following new Authorization Request parameter is defined to be used in conjunction with Response Mode `direct_post`: +The following new Authorization Request parameter is defined to be used in conjunction with Response Mode `direct_post`: `response_uri`: : REQUIRED when the Response Mode `direct_post` is used. The Response URI to which the Wallet MUST send the Authorization Response using an HTTP POST request as defined by the Response Mode `direct_post`. The Response URI receives all Authorization Response parameters as defined by the respective Response Type. When the `response_uri` parameter is present, the `redirect_uri` Authorization Request parameter MUST NOT be present. If the `redirect_uri` Authorization Request parameter is present when the Response Mode is `direct_post`, the Wallet MUST return an `invalid_request` Authorization Response error. The `response_uri` value MUST be a value that the client would be permitted to use as `redirect_uri` when following the rules defined in (#client_metadata_management). -Note: The Verifier's component providing the user interface (Frontend) and the Verifier's component providing the Response URI (Response Endpoint) need to be able to map authorization requests to the respective authorization responses. The Verifier MAY use the `state` Authorization Request parameter to add appropriate data to the Authorization Response for that purpose, for details see (#implementation_considerations_direct_post). +Note: The Verifier's component providing the user interface (Frontend) and the Verifier's component providing the Response URI (Response Endpoint) need to be able to map authorization requests to the respective authorization responses. The Verifier MAY use the `state` Authorization Request parameter to add appropriate data to the Authorization Response for that purpose, for details see (#implementation_considerations_direct_post). The following is a non-normative example of the payload of a Request Object with Response Mode `direct_post`: @@ -957,7 +954,7 @@ Content-Type: application/json Cache-Control: no-store { - "redirect_uri": "https://client.example.org/cb#response_code=091535f699ea575c7937fa5f0f454aee" + "redirect_uri": "https://client.example.org/cb#response_code=091535f699ea575c7937fa5f0f454aee" } ``` @@ -986,7 +983,7 @@ The following is a non-normative example of the payload of a JWT used in an Auth The JWT response document MUST include `vp_token` and `presentation_submission` parameters as defined in (#response-parameters). -The key material used for encryption and signing SHOULD be determined using existing metadata mechanisms. +The key material used for encryption and signing SHOULD be determined using existing metadata mechanisms. To obtain Verifier's public key for the input to the key agreement to encrypt the Authorization Response, the Wallet MUST use `jwks` or `jwks_uri` claim within the `client_metadata` request parameter, or within the metadata defined in the Entity Configuration when [@!OpenID.Federation] is used, or other mechanisms. @@ -1010,7 +1007,7 @@ The following is a non-normative example of the payload of the JWT used in the e The error response follows the rules as defined in [@!RFC6749], with the following additional clarifications: -`invalid_scope`: +`invalid_scope`: - Requested scope value is invalid, unknown, or malformed. @@ -1119,7 +1116,7 @@ Verifier utilizing this specification has multiple options to obtain Wallet's me # Verifier Metadata (Client Metadata) {#client_metadata} -To convey Verifier metadata, Client metadata defined in Section 2 of [@!RFC7591] is used. +To convey Verifier metadata, Client metadata defined in Section 2 of [@!RFC7591] is used. This specification defines how the Wallet can determine Credential formats, proof types and algorithms supported by the Verifier to be used in a protocol exchange. @@ -1137,12 +1134,12 @@ The Verifier Attestation JWT is a JWT especially designed to allow a Wallet to a A Verifier Attestation JWT MUST contain the following claims: -* `iss`: REQUIRED. This claim identifies the issuer of the Verifier Attestation JWT. The `iss` value MAY be used to retrieve the issuer's public key. How the trust is established between Wallet and Issuer and how the public key is obtained for validating the attestation's signature is out of scope of this specification. +* `iss`: REQUIRED. This claim identifies the issuer of the Verifier Attestation JWT. The `iss` value MAY be used to retrieve the issuer's public key. How the trust is established between Wallet and Issuer and how the public key is obtained for validating the attestation's signature is out of scope of this specification. * `sub`: REQUIRED. The value of this claim MUST be the `client_id` of the client making the credential request. * `iat`: OPTIONAL. (number). The value of this claim MUST be the time at which the Verifier Attestation JWT was issued using the syntax defined in [RFC7519]. * `exp`: REQUIRED. (number). The value of this claim MUST be the time at which the Verifier Attestation JWT expires using the syntax defined in [RFC7519]. The Wallet MUST reject any Verifier Attestation JWT with an expiration time that has passed, subject to allowable clock skew between systems. * `nbf`: OPTIONAL. The Verifier Attestation JWT MAY contain an "nbf" (not before) claim that identifies the time before which the token MUST NOT be accepted for processing. -* `cnf`: REQUIRED. This claim contains the confirmation method as defined in [@!RFC7800]. It MUST contain a JWK as defined in Section 3.2 of [RFC7800]. This claim determines the public key for which's corresponding private key the Verifier MUST proof possession of when presenting the Verifier Attestation JWT. This additional security measure allows the Verifier to obtain a Verifier Attestion JWT from a trusted issuer and use it for a long time independent of that issuer without the risk of an advisary impersonating the Verifier by replaying a captured attestation. +* `cnf`: REQUIRED. This claim contains the confirmation method as defined in [@!RFC7800]. It MUST contain a JWK as defined in Section 3.2 of [RFC7800]. This claim determines the public key for which's corresponding private key the Verifier MUST proof possession of when presenting the Verifier Attestation JWT. This additional security measure allows the Verifier to obtain a Verifier Attestion JWT from a trusted issuer and use it for a long time independent of that issuer without the risk of an advisary impersonating the Verifier by replaying a captured attestation. The Verifier Attestation JWT MAY use any claim registered in the "JSON Web Token Claims" registry as defined in [@!RFC7519]. @@ -1150,11 +1147,11 @@ Verifier Attestation JWTs compliant with this specification MUST use the media t A Verifier Attestation JWT MUST set the `typ` JOSE header to `verifier-attestation+jwt`. -The Verifier Attestation JWT MAY be conveyed in the header of a JWS signed object (JOSE header). +The Verifier Attestation JWT MAY be conveyed in the header of a JWS signed object (JOSE header). -This specification introduces a JOSE header, which can be used to add a JWT to such a header as follows: +This specification introduces a JOSE header, which can be used to add a JWT to such a header as follows: -* `jwt`: This JOSE header MUST contain a JWT. +* `jwt`: This JOSE header MUST contain a JWT. In the context of this specification, such a JWT MUST set the `typ` JOSE header to `verifier-attestation+jwt`. @@ -1243,9 +1240,9 @@ When using Response Mode `direct_post`, also see (#security_considerations_direc ## Response Mode `direct_post` {#implementation_considerations_direct_post} -The design of the interactions between the different components of the Verifier (especially Frontend and Response Endpoint) when using Response Mode `direct_post` is at the discretion of the Verifier since it does not affect the interface between the Verifier and the Wallet. +The design of the interactions between the different components of the Verifier (especially Frontend and Response Endpoint) when using Response Mode `direct_post` is at the discretion of the Verifier since it does not affect the interface between the Verifier and the Wallet. -In order to support implementers, this section outlines a possible design that fulfills the Security Considerations given in (#security_considerations). +In order to support implementers, this section outlines a possible design that fulfills the Security Considerations given in (#security_considerations). The design is illustrated in the following sequence diagram: @@ -1254,7 +1251,7 @@ The design is illustrated in the following sequence diagram: +-------+ +------------+ +---------------------+ +----------+ | User | | Verifier | | Verifier | | Wallet | | | | | | Response Endpoint | | | -+-------+ +------------+ +---------------------+ +----------+ ++-------+ +------------+ +---------------------+ +----------+ | | | | | interacts | | | |------------->| | | @@ -1305,44 +1302,44 @@ Figure: Reference Design for Response Mode `direct_post` (1) The Verifier produces a `nonce` value by generating at least 16 fresh, cryptographically random bytes with sufficient entropy, associates it with the session and base64url encodes it. -(2) The Verifier initiates a new transaction at its Response Endpoint. +(2) The Verifier initiates a new transaction at its Response Endpoint. (3) The Response Endpoint will set up the transaction and respond with two fresh, cryptographically random numbers with sufficient entropy designated as `transaction-id` and `request-id`. Those values are used in the process to identify the authorization response (`request-id`) and to ensure only the Verifier can obtain the Authorization Response data (`transaction-id`). (4) The Verifier then sends the Authorization Request with the `request-id` as `state` and the `nonce` value created in step (1) to the Wallet. -(5) After authenticating the End-User and getting her consent to share the request Credentials, the Wallet sends the Authorization Response with the parameters `vp_token`, `presentation_submission` and `state` to the `response_uri` of the Verifier. +(5) After authenticating the End-User and getting her consent to share the request Credentials, the Wallet sends the Authorization Response with the parameters `vp_token`, `presentation_submission` and `state` to the `response_uri` of the Verifier. -(6) The Verifier's Response Endpoint checks whether the `state` value is a valid `request-id`. If so, it stores the Authorization Response data linked to the respective `transaction-id`. It then creates a `response_code` as fresh, cryptographically random number with sufficient entropy that it also links with the respective Authorization Response data. It then returns the `redirect_uri`, which includes the `response_code` to the Wallet. +(6) The Verifier's Response Endpoint checks whether the `state` value is a valid `request-id`. If so, it stores the Authorization Response data linked to the respective `transaction-id`. It then creates a `response_code` as fresh, cryptographically random number with sufficient entropy that it also links with the respective Authorization Response data. It then returns the `redirect_uri`, which includes the `response_code` to the Wallet. -Note: If the Verifier's Response Endpoint does not return a `redirect_uri`, processing at the Wallet stops at that step. The Verifier is supposed to fetch the Authorization Response without waiting for a redirect (see step 8). +Note: If the Verifier's Response Endpoint does not return a `redirect_uri`, processing at the Wallet stops at that step. The Verifier is supposed to fetch the Authorization Response without waiting for a redirect (see step 8). (7) The Wallet sends the user agent to the Verifier (`redirect_uri`). The Verifier receives the Request and extracts the `response_code` parameter. -(8) The Verifier sends the `response_code` and the `transaction-id` from its session to the Response Endpoint. +(8) The Verifier sends the `response_code` and the `transaction-id` from its session to the Response Endpoint. -* The Response Endpoint uses the `transaction-id` to look the matching Authorization Response data up, which implicitly validates the `transaction-id` associated with the Verifier's session. +* The Response Endpoint uses the `transaction-id` to look the matching Authorization Response data up, which implicitly validates the `transaction-id` associated with the Verifier's session. * If an Authorization Response is found, the Response Endpoint checks whether the `response_code` was associated with this Authorization Response in step (6). -Note: If the Verifier's Response Endpoint did not return a `redirect_uri` in step (6), the Verifier will periodically query the Response Endpoint with the `transaction-id` to obtain the Authorization Response once it becomes available. +Note: If the Verifier's Response Endpoint did not return a `redirect_uri` in step (6), the Verifier will periodically query the Response Endpoint with the `transaction-id` to obtain the Authorization Response once it becomes available. -(9) The Response Endpoint returns the VP Token and Presentation Submission for further processing to the Verifier. +(9) The Response Endpoint returns the VP Token and Presentation Submission for further processing to the Verifier. (10) The Verifier checks whether the `nonce` received in the Credential(s) in the VP Token in step (9) corresponds to the `nonce` value from the session. The Verifier then consumes the VP Token and invalidates the `transaction-id`, `request-id` and `nonce` in the session. # Security Considerations {#security_considerations} -## Preventing Replay of the VP Token {#preventing-replay} +## Preventing Replay of the VP Token {#preventing-replay} An attacker could try to inject a VP Token (or an individual Verifiable Presentation), that was obtained from a previous Authorization Response, into another Authorization Response thus impersonating the End-User that originally presented that VP Token or the respective Verifiable Presentation. -Implementers of this specification MUST implement the controls as defined in this section to detect such an attack. +Implementers of this specification MUST implement the controls as defined in this section to detect such an attack. -This specification assumes that a Verifiable Credential is always presented with a cryptographic proof of possession which can be a Verifiable Presentation. This cryptographic proof of possession MUST be bound by the Wallet to the intended audience (the Client Identifier of the Verifier) and the respective transaction (identified by the `nonce` parameter in the Authorization Request). The Verifier MUST verify this binding. +This specification assumes that a Verifiable Credential is always presented with a cryptographic proof of possession which can be a Verifiable Presentation. This cryptographic proof of possession MUST be bound by the Wallet to the intended audience (the Client Identifier of the Verifier) and the respective transaction (identified by the `nonce` parameter in the Authorization Request). The Verifier MUST verify this binding. -The Verifier MUST create a fresh, cryptographically random number with sufficient entropy for every Authorization Request, store it with its current session, and pass it in the `nonce` Authorization Request Parameter to the Wallet. +The Verifier MUST create a fresh, cryptographically random number with sufficient entropy for every Authorization Request, store it with its current session, and pass it in the `nonce` Authorization Request Parameter to the Wallet. -The Wallet MUST link every Verifiable Presentation returned to the Verifier in the VP Token to the `client_id` and the `nonce` values of the respective Authentication Request. +The Wallet MUST link every Verifiable Presentation returned to the Verifier in the VP Token to the `client_id` and the `nonce` values of the respective Authentication Request. The Verifier MUST validate every individual Verifiable Presentation in an Authorization Response and ensure that it is linked to the values of the `client_id` and the `nonce` parameter it had used for the respective Authorization Request. If the response contains multiple Verifiable Presentations which do not contain the same nonce value, the response is rejected. @@ -1386,7 +1383,7 @@ The following is a non-normative example of a Verifiable Presentation of a forma "type": "RsaSignature2018", "created": "2018-09-14T21:19:10Z", "proofPurpose": "authentication", - "verificationMethod": "did:example:ebfeb1f712ebc6f1c276e12ec21#keys-1", + "verificationMethod": "did:example:ebfeb1f712ebc6f1c276e12ec21#keys-1", "challenge": "343s$FSFDa-", "domain": "s6BhdRkqt3", "jws": "eyJhb...nKb78" @@ -1398,11 +1395,11 @@ In the example above, the requested `nonce` value is included as the `challenge` ## Session Fixation {#session_fixation} -To perform a Session Fixation attack, an attacker would start the process using a Verifier executed on a device under his control, capture the Authorization Request and relay it to the device of a victim. The attacker would then periodically try to conclude the process in his Verifier, which would cause the Verifier on his device to try to fetch and verify the Authorization Response. +To perform a Session Fixation attack, an attacker would start the process using a Verifier executed on a device under his control, capture the Authorization Request and relay it to the device of a victim. The attacker would then periodically try to conclude the process in his Verifier, which would cause the Verifier on his device to try to fetch and verify the Authorization Response. -Such an attack is impossible against flows implemented with the Response Mode `fragment` as the Wallet will always send the VP Token to the redirect endpoint on the same device where it resides. This means an attacker could extract a valid Authorization Request from a Verifier on his device and trick a Victim into performing the same Authorization Request on her device. But there is technically no way for an attacker to get hold of the resulting VP Token. +Such an attack is impossible against flows implemented with the Response Mode `fragment` as the Wallet will always send the VP Token to the redirect endpoint on the same device where it resides. This means an attacker could extract a valid Authorization Request from a Verifier on his device and trick a Victim into performing the same Authorization Request on her device. But there is technically no way for an attacker to get hold of the resulting VP Token. -However, the Response Mode `direct_post` is susceptible to such an attack as the result is sent from the Wallet out-of-band to the Verifier's Response Endpoint. +However, the Response Mode `direct_post` is susceptible to such an attack as the result is sent from the Wallet out-of-band to the Verifier's Response Endpoint. This kind of attack can be detected if the Response Mode `direct_post` is used in conjunction with the redirect URI, which causes the Wallet to redirect the flow to the Verifier's frontend at the device where the transaction was concluded. The Verifier's Response Endpoint MUST include a fresh secret (Response Code) into the redirect URI returned to the Wallet and the Verifier's Response Endpoint MUST require the frontend to pass the respective Response Code when fetching the Authorization Response. That stops session fixation attacks as long as the attacker is unable to get access to the Response Code. @@ -1421,13 +1418,13 @@ The Wallet MUST ensure the data in the Authorization Response cannot leak throug ### Protection of the Response URI -The Verifier SHOULD protect its Response URI from inadvertent requests by checking that the value of the received `state` parameter corresponds to a recent Authorization Request. It MAY also use JARM [@!JARM] to authenticate the originator of the request. +The Verifier SHOULD protect its Response URI from inadvertent requests by checking that the value of the received `state` parameter corresponds to a recent Authorization Request. It MAY also use JARM [@!JARM] to authenticate the originator of the request. ### Protection of the Authorization Response Data -This specification assumes that the Verifier's Response Endpoint offers an internal interface to other components of the Verifier to obtain (and subsequently process) Authorization Response data. An attacker could try to obtain Authorization Response Data from a Verifier's Response Endpoint by looking up this data through the internal interface. This could lead to leakage valid Verifiable Presentations containing PII. +This specification assumes that the Verifier's Response Endpoint offers an internal interface to other components of the Verifier to obtain (and subsequently process) Authorization Response data. An attacker could try to obtain Authorization Response Data from a Verifier's Response Endpoint by looking up this data through the internal interface. This could lead to leakage valid Verifiable Presentations containing PII. -Implementations of this specification MUST have security mechanisms in place to prevent inadvertent requests against this internal interface. Implementation options to fulfill this requirement include: +Implementations of this specification MUST have security mechanisms in place to prevent inadvertent requests against this internal interface. Implementation options to fulfill this requirement include: * Authentication between the different parts within the Verifier * Two cryptographically random numbers. The first being used to manage state between the Wallet and Verifier. The second being used to ensure that only a legitimate component of the Verifier can obtain the Authorization Response data. @@ -1446,7 +1443,7 @@ If an encrypted Authorization Response has no additional integrity protection, a In many instances the referenced server will be operated by a known federation or other trusted operator, and the URL's domain name will already be widely known. Wallets using this URI can mitigate request forgeries by having a pre-configured set of trusted domain names and only fetching Presentation Definition from these sources. In addition, the Presentation Definitions could be signed by a trusted authority, such as the federation operator. -### JSONPath and Arbitrary Scripting +### JSONPath and Arbitrary Scripting Implementers MUST make sure that JSONPath used as part of `presentation_definition` and `presentation_submission` parameters cannot be used to execute arbitrary scripts on a server. This can be achieved, for example, by implementing the entire syntax of the query without relying on the parsers of programming language engine. For details, see Section 4 of [@I-D.ietf-jsonpath-base]. @@ -1470,7 +1467,7 @@ If no user interaction is required before sending the request, it is easy to req Mandatory user interaction before sending the request, like clicking a button, unlocking the wallet or even just showing a screen of the app, can make this less attractive/likely to being exploited. -Requests from the Wallet to the Verifier SHOULD be sent with the minimal amount of information possible, and in particular, without any HTTP headers identifying the software used for the request (e.g., HTTP libraries or their versions). The Wallet MUST NOT send PII or any other data that could be used for fingerprinting to the Request URI in order to prevent user tracking. +Requests from the Wallet to the Verifier SHOULD be sent with the minimal amount of information possible, and in particular, without any HTTP headers identifying the software used for the request (e.g., HTTP libraries or their versions). The Wallet MUST NOT send PII or any other data that could be used for fingerprinting to the Request URI in order to prevent user tracking. ## Authorization Error Response with the `wallet_unavailable` error code @@ -1581,7 +1578,7 @@ In the event that another component is invoked instead of the Wallet, the user M A novel approach to establish trust in Verifiable Credential -issuers in Self-Sovereign Identity ecosystems using TRAIN +issuers in Self-Sovereign Identity ecosystems using TRAIN University of Stuttgart @@ -1711,7 +1708,7 @@ issuers in Self-Sovereign Identity ecosystems using TRAIN Google - + Evernym @@ -1796,15 +1793,15 @@ but can be used with multiple protocols. The Web Platform, working in conjunctio This OpenID4VP profile utilizes the mechanisms of the W3C Digital Credentials API while also allowing to leverage advanced security features of OpenID4VP, if needed. It also defines the OpenID4VP request parameters that MAY be used with the W3C Digital Credentials API. -The Digital Credentials API offers several advantages for implementers of both Verifiers and Wallets. +The Digital Credentials API offers several advantages for implementers of both Verifiers and Wallets. -Firstly, the API serves as a privacy-preserving alternative to invoking Wallets via URLs, particularly custom URL schemes. The underlying app platform will only invoke a Wallet if the user confirms the request based on contextual information about the credential request and the requestor (Verifier). +Firstly, the API serves as a privacy-preserving alternative to invoking Wallets via URLs, particularly custom URL schemes. The underlying app platform will only invoke a Wallet if the user confirms the request based on contextual information about the credential request and the requestor (Verifier). Secondly, the session with the user will always continue in the initial context, typically a browser tab, when the request has been fulfilled (or aborted), which results in an improved user experience. Thirdly, cross-device requests benefit from the use of secure transports with proximity checks, which are handled by the OS platform, e.g., using FIDO CTAP 2.2 with hybrid transports. -And lastly, as part of the request, the Wallet is provided with information about the Verifier's origin as authenticated by the user agent, which is important for phishing resistance. +And lastly, as part of the request, the Wallet is provided with information about the Verifier's origin as authenticated by the user agent, which is important for phishing resistance. ## Protocol @@ -1836,7 +1833,7 @@ try { } ``` -Out of the Authorization Request parameters defined in [@!RFC6749] and (#vp_token_request), the following are supported with this profile: +Out of the Authorization Request parameters defined in [@!RFC6749] and (#vp_token_request), the following are supported with this profile: * `client_id` * `client_id_scheme` @@ -1946,13 +1943,13 @@ The following is a non-normative example of an Authorization Request: <{{examples/request/request.txt}} -The requirements regarding the Credential to be presented are conveyed in the `presentation_definition` parameter. +The requirements regarding the Credential to be presented are conveyed in the `presentation_definition` parameter. The following is a non-normative example of the contents of a `presentation_definition` parameter: <{{examples/request/pd_jwt_vc.json}} -This `presentation_definition` parameter contains a single `input_descriptor` element, which sets the desired format to JWT VC and defines a constraint over the `vc.type` parameter to select Verifiable Credentials of type `IDCredential`. +This `presentation_definition` parameter contains a single `input_descriptor` element, which sets the desired format to JWT VC and defines a constraint over the `vc.type` parameter to select Verifiable Credentials of type `IDCredential`. #### Presentation Response @@ -1960,7 +1957,7 @@ The following is a non-normative example of an Authorization Response: <{{examples/response/response.txt}} -The following is a non-normative example of the content of the `presentation_submission` parameter: +The following is a non-normative example of the content of the `presentation_submission` parameter: <{{examples/response/ps_jwt_vc.json}} @@ -2010,7 +2007,7 @@ The following is a non-normative example of the Verifiable Presentation in the ` <{{examples/response/ldp_vp.json}} -Note: The VP's `challenge` claim contains the value of the `nonce` of the presentation request and the `domain` claims contains the Client Identifier of the Verifier. This allows the Verifier to detect replay of a presentation as recommended in (#preventing-replay). +Note: The VP's `challenge` claim contains the value of the `nonce` of the presentation request and the `domain` claims contains the Client Identifier of the Verifier. This allows the Verifier to detect replay of a presentation as recommended in (#preventing-replay). ## AnonCreds @@ -2024,13 +2021,13 @@ Identifier for a CL-signature crypto scheme used in the examples in this section ### Example Credential -The following is a non-normative example of an AnonCred Credential that will be used throughout this section. +The following is a non-normative example of an AnonCred Credential that will be used throughout this section. <{{examples/credentials/ac_vc.json}} -The most important parts for the purpose of this section are `scheme_id` parameter and `values` parameter that contains the actual End-User claims. +The most important parts for the purpose of this section are `scheme_id` parameter and `values` parameter that contains the actual End-User claims. -### Presentation Request +### Presentation Request #### Request Example {#anoncreds_request} @@ -2044,19 +2041,19 @@ The following is a non-normative example of the content of the `presentation_def The `format` object in the `input_descrioptor` element uses the format identifier `ac_vc` as defined above and sets the `proof_type` to `CLSignature2019` to denote this descriptor requires a Credential in AnonCreds format signed with a CL signature (Camenisch-Lysyanskaya signature). The rest of the expressions operate on the AnonCreds JSON structure. -The `constraints` object requires the selected Credential to conform with the schema definition `did:indy:idu:test:3QowxFtwciWceMFr7WbwnM:2:BasicScheme:0\\.1`, which is denoted as a constraint over the AnonCred's `schema_id` parameter. +The `constraints` object requires the selected Credential to conform with the schema definition `did:indy:idu:test:3QowxFtwciWceMFr7WbwnM:2:BasicScheme:0\\.1`, which is denoted as a constraint over the AnonCred's `schema_id` parameter. #### Request Example with Selective Release of Claims The next example leverages the AnonCreds' capabilities for selective release by requesting a subset of the claims in the Credential to be disclosed to the Verifier. -A non-normative example of an Authorization Request would look the same as in (#anoncreds_request). +A non-normative example of an Authorization Request would look the same as in (#anoncreds_request). The following is a non-normative example of the difference is in the `presentation_definition` parameter: <{{examples/request/pd_ac_vc_sd.json}} -This example is identic to the previous one with the following exceptions: It sets the element `limit_disclosure` of the constraint to `require` and adds two more constraints for the individual claims `given_name` and `family_name`. Since such claims are stored underneath a `values` container in an AnonCred, `values` is part of the path to identify the respective claims. +This example is identic to the previous one with the following exceptions: It sets the element `limit_disclosure` of the constraint to `require` and adds two more constraints for the individual claims `given_name` and `family_name`. Since such claims are stored underneath a `values` container in an AnonCred, `values` is part of the path to identify the respective claims. ### Presentation Response @@ -2326,7 +2323,7 @@ Interoperability considerations: : n/a This specification registers the following JWS header name in the IANA "JSON Web Signature and Encryption Header Parameters" registry established by [@!RFC7515]. * Header Parameter Name: `jwt` -* Header Parameter Description: This header contains a JWT. Processing rules MAY depend on the `typ` header value of the respective JWT. +* Header Parameter Description: This header contains a JWT. Processing rules MAY depend on the `typ` header value of the respective JWT. * Header Parameter Usage Location: JWS * Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net * Specification Document(s): (#verifier_attestation_jwt) @@ -2355,7 +2352,7 @@ The technology described in this specification was made available from contribut * added how OpenID4VP request/response can be used over the browser API * remove path_nested description from Response Parameters section and move it into W3C VC Annex * fix indentation of examples - * added references to ISO/IEC 23220 and 18013 documents + * added references to ISO/IEC 23220 and 18013 documents * added `post` request method for Request URI * Added IETF SD-JWT VC profile * Added `wallet_unavailable` error @@ -2363,7 +2360,7 @@ The technology described in this specification was made available from contribut -20 * added "verifier_attestation" client id scheme value - + -19 * added "x509_san_uri" and "x509_san_dns" client id scheme value @@ -2374,7 +2371,7 @@ The technology described in this specification was made available from contribut -17 - * direct_post response mode uses state to identify response + * direct_post response mode uses state to identify response * Added sequence diagrams for same and cross device flows to overview section -16 @@ -2384,7 +2381,7 @@ The technology described in this specification was made available from contribut -15 - * Added definition of VP Token + * Added definition of VP Token * Editorial improvements for better readability (restructured request and response section, consistent terminology, and casing) -14 @@ -2406,7 +2403,7 @@ The technology described in this specification was made available from contribut * changed base protocol to OAuth 2.0 * consolidated the examples - + -10 * Added AnonCreds example @@ -2456,6 +2453,6 @@ The technology described in this specification was made available from contribut * adopted DIF Presentation Exchange request syntax * added security considerations regarding replay detection for Verifiable Credentials - -00 + -00 * initial revision From 7d719609a0c5e10a85f28d4f5ac4f82f05a10638 Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Tue, 30 Jul 2024 09:44:36 +0200 Subject: [PATCH 05/49] Fix anchor name --- openid-4-verifiable-presentations-1_0.md | 208 +++++++++++------------ 1 file changed, 104 insertions(+), 104 deletions(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index c1b25a1a..3cdfd52c 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -46,7 +46,7 @@ organization="Mattr" .# Abstract -This specification defines a protocol for requesting and presenting Verifiable Credentials. +This specification defines a protocol for requesting and presenting Verifiable Credentials. {mainmatter} @@ -54,7 +54,7 @@ This specification defines a protocol for requesting and presenting Verifiable C This specification defines a mechanism on top of OAuth 2.0 [@!RFC6749] that enables presentation of Verifiable Credentials as Verifiable Presentations. Verifiable Credentials and Verifiable Presentations can be of any format, including, but not limited to W3C Verifiable Credentials Data Model [@VC_DATA], ISO mdoc [@ISO.18013-5], IETF SD-JWT VC [@!I-D.ietf-oauth-sd-jwt-vc], and AnonCreds [@Hyperledger.Indy]. -OAuth 2.0 [@!RFC6749] is used as a base protocol as it provides the required rails to build a simple, secure, and developer-friendly Credential presentation layer on top of it. Moreover, implementers can, in a single interface, support Credential presentation and the issuance of Access Tokens for access to APIs based on Verifiable Credentials in the Wallet. OpenID Connect [@!OpenID.Core] deployments can also extend their implementations using this specification with the ability to transport Verifiable Presentations. +OAuth 2.0 [@!RFC6749] is used as a base protocol as it provides the required rails to build a simple, secure, and developer-friendly Credential presentation layer on top of it. Moreover, implementers can, in a single interface, support Credential presentation and the issuance of Access Tokens for access to APIs based on Verifiable Credentials in the Wallet. OpenID Connect [@!OpenID.Core] deployments can also extend their implementations using this specification with the ability to transport Verifiable Presentations. This specification can also be combined with [@!SIOPv2], if implementers require OpenID Connect features, such as the issuance of Self-Issued ID Tokens [@!SIOPv2]. @@ -98,11 +98,11 @@ Verifier: Issuer-Holder-Verifier Model: : A model for exchanging claims, where claims are issued in the form of Verifiable Credentials independent of the process of presenting them as Verifiable Presentation to the Verifiers. An issued Verifiable Credential can (but must not necessarily) be used multiple times. -Holder Binding: -: Ability of the Holder to prove legitimate possession of a Verifiable Credential. +Holder Binding: +: Ability of the Holder to prove legitimate possession of a Verifiable Credential. Cryptographic Holder Binding: -: Ability of the Holder to prove legitimate possession of a Verifiable Credential by proving control over the same private key during the issuance and presentation. Mechanism might depend on the Credential Format. For example, in `jwt_vc_json` Credential Format, a Verifiable Credential with Cryptographic Holder Binding contains a public key or a reference to a public key that matches to the private key controlled by the Holder. +: Ability of the Holder to prove legitimate possession of a Verifiable Credential by proving control over the same private key during the issuance and presentation. Mechanism might depend on the Credential Format. For example, in `jwt_vc_json` Credential Format, a Verifiable Credential with Cryptographic Holder Binding contains a public key or a reference to a public key that matches to the private key controlled by the Holder. Claims-based Holder Binding: : Ability of the Holder to prove legitimate possession of a Verifiable Credential by proofing certain claims, e.g., name and date of birth, for example by presenting another Verifiable Credential. Claims-based Holder Binding allows long term, cross device use of a Credential as it does not depend on cryptographic key material stored on a certain device. One example of such a Verifiable Credential could be a Diploma. @@ -116,13 +116,13 @@ VP Token: Wallet: : An entity used by the Holder to receive, store, present, and manage Verifiable Credentials and key material. There is no single deployment model of a Wallet: Verifiable Credentials and keys can both be stored/managed locally, or by using a remote self-hosted service, or a remote third-party service. In the context of this specification, the Wallet acts as an OAuth 2.0 Authorization Server (see [@!RFC6749]) towards the Credential Verifier which acts as the OAuth 2.0 Client. -# Overview +# Overview This specification defines a mechanism on top of OAuth 2.0 to request and present Verifiable Credentials as Verifiable Presentations. As the primary extension, OpenID for Verifiable Presentations introduces the VP Token as a container to enable End-Users to present Verifiable Presentations to Verifiers using the Wallet. A VP Token contains one or more Verifiable Presentations in the same or different Credential formats. -This specification supports any Credential format used in the Issuer-Holder-Verifier Model, including, but not limited to those defined in [@VC_DATA] (VCDM), [@ISO.18013-5] (mdoc), [@!I-D.ietf-oauth-sd-jwt-vc] (SD-JWT VC), and [@Hyperledger.Indy] (AnonCreds). Credentials of multiple formats can be presented in the same transaction. The examples given in the main part of this specification use W3C Verifiable Credentials, while examples in other Credential formats are given in (#alternative_credential_formats). +This specification supports any Credential format used in the Issuer-Holder-Verifier Model, including, but not limited to those defined in [@VC_DATA] (VCDM), [@ISO.18013-5] (mdoc), [@!I-D.ietf-oauth-sd-jwt-vc] (SD-JWT VC), and [@Hyperledger.Indy] (AnonCreds). Credentials of multiple formats can be presented in the same transaction. The examples given in the main part of this specification use W3C Verifiable Credentials, while examples in other Credential formats are given in (#alternative_credential_formats). Implementations can use any pre-existing OAuth 2.0 Grant Type and Response Type in conjunction with this specification to support different deployment architectures. @@ -138,7 +138,7 @@ Any of the OAuth 2.0 related specifications, such as [@RFC9126] and [@RFC9101], Below is a diagram of a flow where the End-User presents a Credential to a Verifier interacting with the End-User on the same device that the device the Wallet resides on. -The flow utilizes simple redirects to pass Authorization Request and Response between the Verifier and the Wallet. The Verifiable Presentations are returned to the Verifier in the fragment part of the redirect URI, when Response Mode is `fragment`. +The flow utilizes simple redirects to pass Authorization Request and Response between the Verifier and the Wallet. The Verifiable Presentations are returned to the Verifier in the fragment part of the redirect URI, when Response Mode is `fragment`. Note: The diagram does not illustrate all the optional features of this specification. @@ -146,7 +146,7 @@ Note: The diagram does not illustrate all the optional features of this specific ~~~ ascii-art +--------------+ +--------------+ +--------------+ | User | | Verifier | | Wallet | -+--------------+ +--------------+ +--------------+ ++--------------+ +--------------+ +--------------+ | | | | Interacts | | |---------------->| | @@ -164,7 +164,7 @@ Note: The diagram does not illustrate all the optional features of this specific !--- Figure: Same Device Flow -(1) The Verifier sends an Authorization Request to the Wallet. It contains a Presentation Definition as defined in [@!DIF.PresentationExchange] that describes the requirements of the Credential(s) that the Verifier is requesting to be presented. Such requirements could include what type of Credential(s), in what format(s), which individual Claims within those Credential(s) (Selective Disclosure), etc. The Wallet processes the Authorization Request and determines what Credentials are available matching the Verifier's request. The Wallet also authenticates the End-User and gathers consent to present the requested Credentials. +(1) The Verifier sends an Authorization Request to the Wallet. It contains a Presentation Definition as defined in [@!DIF.PresentationExchange] that describes the requirements of the Credential(s) that the Verifier is requesting to be presented. Such requirements could include what type of Credential(s), in what format(s), which individual Claims within those Credential(s) (Selective Disclosure), etc. The Wallet processes the Authorization Request and determines what Credentials are available matching the Verifier's request. The Wallet also authenticates the End-User and gathers consent to present the requested Credentials. (2) The Wallet prepares the Verifiable Presentation(s) of the Verifiable Credential(s) that the End-User has consented to. It then sends to the Verifier an Authorization Response where the Verifiable Presentation(s) are contained in the `vp_token` parameter. @@ -207,11 +207,11 @@ Note: The usage of the Request URI as defined in [@!RFC9101] does not depend on !--- Figure: Cross Device Flow -(1) The Verifier sends to the Wallet an Authorization Request that contains a Request URI from where to obtain the Request Object containing Authorization Request parameters. +(1) The Verifier sends to the Wallet an Authorization Request that contains a Request URI from where to obtain the Request Object containing Authorization Request parameters. (2) The Wallet sends an HTTP GET request to the Request URI to retrieve the Request Object. -(2.5) The HTTP GET response returns the Request Object containing Authorization Request parameters. It especially contains a Presentation Definition as defined in [@!DIF.PresentationExchange] that describes the requirements of the Credential(s) that the Verifier is requesting to be presented. Such requirements could include what type of Credential(s), in what format(s), which individual Claims within those Credential(s) (Selective Disclosure), etc. The Wallet processes the Request Object and determines what Credentials are available matching the Verifier's request. The Wallet also authenticates the End-User and gathers her consent to present the requested Credentials. +(2.5) The HTTP GET response returns the Request Object containing Authorization Request parameters. It especially contains a Presentation Definition as defined in [@!DIF.PresentationExchange] that describes the requirements of the Credential(s) that the Verifier is requesting to be presented. Such requirements could include what type of Credential(s), in what format(s), which individual Claims within those Credential(s) (Selective Disclosure), etc. The Wallet processes the Request Object and determines what Credentials are available matching the Verifier's request. The Wallet also authenticates the End-User and gathers her consent to present the requested Credentials. (3) The Wallet prepares the Verifiable Presentation(s) of the Verifiable Credential(s) that the End-User has consented to. It then sends to the Verifier an Authorization Response where the Verifiable Presentation(s) are contained in the `vp_token` parameter. @@ -219,8 +219,8 @@ Figure: Cross Device Flow OpenID for Verifiable Presentations extends existing OAuth 2.0 mechanisms as following: -* A new `presentation_definition` Authorization Request parameter that uses the [@!DIF.PresentationExchange] syntax is defined to request presentation of Verifiable Credentials in arbitrary formats. See (#vp_token_request) for more details. -* A new `vp_token` response parameter is defined to return Verifiable Presentations to the Verifier in either Authorization or Token Response depending on the Response Type. See (#response) for more details. +* A new `presentation_definition` Authorization Request parameter that uses the [@!DIF.PresentationExchange] syntax is defined to request presentation of Verifiable Credentials in arbitrary formats. See (#vp_token_request) for more details. +* A new `vp_token` response parameter is defined to return Verifiable Presentations to the Verifier in either Authorization or Token Response depending on the Response Type. See (#response) for more details. * New Response Types `vp_token` and `vp_token id_token` are defined to request Verifiable Credentials to be returned in the Authorization Response (standalone or along with a Self-Issued ID Token [@!SIOPv2]). See (#response) for more details. * A new OAuth 2.0 Response Mode `direct_post` is defined to support sending the response across devices, or when the size of the response exceeds the redirect URL character size limitation. See (#response_mode_post) for more details. * The [@!DIF.PresentationExchange] `format` parameter is used throughout the protocol in order to enable customization according to the specific needs of a particular Credential format. Examples in (#alternative_credential_formats) are given for Credential formats as specified in [@VC_DATA], [@ISO.18013-5], [@!I-D.ietf-oauth-sd-jwt-vc], and [@Hyperledger.Indy]. @@ -257,7 +257,7 @@ This specification defines the following new parameters: `presentation_definition_uri`: : A string containing an HTTPS URL pointing to a resource where a Presentation Definition JSON object can be retrieved. This parameter MUST be present when `presentation_definition` parameter, or a `scope` value representing a Presentation Definition is not present. See (#request_presentation_definition_uri) for more details. -`client_id_scheme`: +`client_id_scheme`: : OPTIONAL. A string identifying the scheme of the value in the `client_id` Authorization Request parameter (Client Identifier scheme). The `client_id_scheme` parameter namespaces the respective Client Identifier. If an Authorization Request uses the `client_id_scheme` parameter, the Wallet MUST interpret the Client Identifier of the Verifier in the context of the Client Identifier scheme. If the parameter is not present, the Wallet MUST behave as specified in [@!RFC6749]. See (#client_metadata_management) for the values defined by this specification. If the same Client Identifier is used with different Client Identifier schemes, those occurrences MUST be treated as different Verifiers. Note that the Verifier needs to determine which Client Identifier schemes the Wallet supports prior to sending the Authorization Request in order to choose a supported scheme. `client_metadata`: @@ -265,11 +265,11 @@ This specification defines the following new parameters: A public key to be used by the Wallet as an input to the key agreement to encrypt Authorization Response (see (#jarm)). It MAY be passed by the Verifier using the `jwks` or the `jwks_uri` claim within the `client_metadata` request parameter. -`request_uri_method`: +`request_uri_method`: : 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. +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. The following additional considerations are given for pre-existing Authorization Request parameters: @@ -280,9 +280,9 @@ The following additional considerations are given for pre-existing Authorization : OPTIONAL. Defined in [@!RFC6749]. The Wallet MAY allow Verifiers to request presentation of Verifiable Credentials by utilizing a pre-defined scope value. See (#request_scope) for more details. `response_mode`: -: OPTIONAL. Defined in [@!OAuth.Responses]. This parameter is used (through the new Response Mode `direct_post`) to ask the Wallet to send the response to the Verifier via an HTTPS connection (see (#response_mode_post) for more details). It is also used to request signing and encrypting (see (#jarm) for more details). If the parameter is not present, the default value is `fragment`. +: OPTIONAL. Defined in [@!OAuth.Responses]. This parameter is used (through the new Response Mode `direct_post`) to ask the Wallet to send the response to the Verifier via an HTTPS connection (see (#response_mode_post) for more details). It is also used to request signing and encrypting (see (#jarm) for more details). If the parameter is not present, the default value is `fragment`. -The following is a non-normative example of an Authorization Request: +The following is a non-normative example of an Authorization Request: ``` GET /authorize? @@ -293,7 +293,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` and `client_metadata` parameters): ``` GET /authorize? @@ -320,7 +320,7 @@ The following non-normative example shows how the Verifiers can also ask for alt <{{examples/request/vp_token_alternative_credentials.json}} -The Verifiable Credential and Verifiable Presentation formats supported by the Wallet should be published in its metadata using the metadata parameter `vp_formats_supported` (see (#as_metadata_parameters)). +The Verifiable Credential and Verifiable Presentation formats supported by the Wallet should be published in its metadata using the metadata parameter `vp_formats_supported` (see (#as_metadata_parameters)). The formats supported by a Verifier may be set up using the metadata parameter `vp_formats` (see (#client_metadata_parameters)). The Wallet MUST ignore any `format` property inside a `presentation_definition` object if that `format` was not included in the `vp_formats` property of the metadata. @@ -328,7 +328,7 @@ Note: When a Verifier is requesting the presentation of a Verifiable Presentatio ## `presentation_definition_uri` Parameter {#request_presentation_definition_uri} -`presentation_definition_uri` is used to retrieve the Presentation Definition from the resource at the specified URL, rather than being passed by value. The Wallet MUST send an HTTP GET request without additional parameters. The resource MUST be exposed without further need to authenticate or authorize. +`presentation_definition_uri` is used to retrieve the Presentation Definition from the resource at the specified URL, rather than being passed by value. The Wallet MUST send an HTTP GET request without additional parameters. The resource MUST be exposed without further need to authenticate or authorize. The protocol for the `presentation_definition_uri` MUST be HTTPS. @@ -380,21 +380,21 @@ Content-Type: application/json Wallets MAY support requesting presentation of Verifiable Credentials using OAuth 2.0 scope values. -Such a scope value MUST be an alias for a well-defined Presentation Definition that will be -referred to in the `presentation_submission` response parameter. +Such a scope value MUST be an alias for a well-defined Presentation Definition that will be +referred to in the `presentation_submission` response parameter. -The specific scope values, and the mapping between a certain scope value and the respective -Presentation Definition is out of scope of this specification. +The specific scope values, and the mapping between a certain scope value and the respective +Presentation Definition is out of scope of this specification. Possible options include normative text in a separate specification defining scope values along with a description of their -semantics or machine readable definitions in the Wallet's server metadata, mapping a scope value to an equivalent -Presentation Definition JSON object. +semantics or machine readable definitions in the Wallet's server metadata, mapping a scope value to an equivalent +Presentation Definition JSON object. -Such definition of a scope value MUST allow the Verifier to determine the identifiers of the Presentation Definition and Input Descriptor(s) in the `presentation_submission` response parameter (`definition_id` and `descriptor_map.id` respectively) as well as the Credential formats and types in the `vp_token` response parameter defined in (#response-parameters). +Such definition of a scope value MUST allow the Verifier to determine the identifiers of the Presentation Definition and Input Descriptor(s) in the `presentation_submission` response parameter (`definition_id` and `descriptor_map.id` respectively) as well as the Credential formats and types in the `vp_token` response parameter defined in (#response-parameters). It is RECOMMENDED to use collision-resistant scopes values. -The following is a non-normative example of an Authorization Request using the scope value `com.example.IDCardCredential_presentation`, +The following is a non-normative example of an Authorization Request using the scope value `com.example.IDCardCredential_presentation`, which is an alias for the first Presentation Definition example given in (#request_presentation_definition): ``` @@ -417,7 +417,7 @@ See (#response) on how the `response_type` value determines the response used to ## Passing Authorization Request Across Devices -There are use-cases when the Authorization Request is being displayed on a device different from a device on which the requested Credential is stored. In those cases, an Authorization Request can be passed across devices by being rendered as a QR Code. +There are use-cases when the Authorization Request is being displayed on a device different from a device on which the requested Credential is stored. In those cases, an Authorization Request can be passed across devices by being rendered as a QR Code. The usage of the Response Mode `direct_post` (see (#response_mode_post)) in conjunction with `request_uri` is RECOMMENDED, since Authorization Request size might be large and might not fit in a QR code. @@ -428,13 +428,13 @@ When the Verifier is sending a Request Object as defined in [@!RFC9101], the `au - the `aud` Claim MUST equal to the `issuer` Claim value, when Dynamic Discovery is performed. - the `aud` Claim MUST be "https://self-issued.me/v2", when Static Discovery metadata is used. -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. +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} 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. -This specification defines the following values for the `client_id_scheme` parameter, followed by the examples where applicable: +This specification defines the following values for the `client_id_scheme` parameter, followed by the examples where applicable: * `pre-registered`: This value represents the [@!RFC6749] default behavior, i.e., the Client Identifier needs to be known to the Wallet in advance of the Authorization Request. The Verifier metadata is obtained using [@!RFC7591] or through out-of-band mechanisms. @@ -483,19 +483,19 @@ Other specifications can define further values for the `client_id_scheme` parame ## Request URI Method `post` {#request_uri_method_post} -This request is handled by the Request URI endpoint of the Verifier. +This request is handled by the Request URI endpoint of the Verifier. The request MUST use the HTTP POST method with the `https` scheme, and the content type `application/x-www-form-urlencoded` and the accept header set to `application/oauth-authz-req+jwt`. -The following parameters are defined: +The following parameters are defined: `wallet_metadata`: -: OPTIONAL. A String containing a JSON object containing metadata parameters as defined in (#as_metadata_parameters). +: OPTIONAL. A String containing a JSON object containing metadata parameters as defined in (#as_metadata_parameters). `wallet_nonce`: -: OPTIONAL. A String value used to mitigate replay attacks of the Authorization Request. When received, the Verifier MUST use it as the `wallet_nonce` value in the signed authorization request object. Value can be a base64url encoded, fresh, cryptographically random number with sufficient entropy. +: OPTIONAL. A String value used to mitigate replay attacks of the Authorization Request. When received, the Verifier MUST use it as the `wallet_nonce` value in the signed authorization request object. Value can be a base64url encoded, fresh, cryptographically random number with sufficient entropy. -If the Wallet requires the Verifier to encrypt the Request Object, it SHOULD use the `jwks` or `jwks_uri` parameter within the `wallet_metadata` parameter to pass the public key for the input to the key agreement. Other mechanisms to pass the encryption key can be used as well. If the Wallet requires an encrypted Authorization Response, it SHOULD specify supported encryption algorithms using the `authorization_encryption_alg_values_supported` and `authorization_encryption_enc_values_supported` parameters. +If the Wallet requires the Verifier to encrypt the Request Object, it SHOULD use the `jwks` or `jwks_uri` parameter within the `wallet_metadata` parameter to pass the public key for the input to the key agreement. Other mechanisms to pass the encryption key can be used as well. If the Wallet requires an encrypted Authorization Response, it SHOULD specify supported encryption algorithms using the `authorization_encryption_alg_values_supported` and `authorization_encryption_enc_values_supported` parameters. Additionally, if the `client_id_scheme` value permits signed Request Objects, the Wallet SHOULD list supported cryptographic algorithms for securing the Request Object through the `request_object_signing_alg_values_supported` parameter. Conversely, the Wallet MUST NOT include this parameter if the `client_id_scheme` precludes signed Request Objects. @@ -532,7 +532,7 @@ The following is a non-normative example of a request object: } ``` -The Wallet MUST process the request as defined in [@RFC9101]. Additionally, if the Wallet passed a `wallet_nonce` in the POST request, the Wallet MUST validate whether the request object contains the respective nonce value in a `wallet_nonce` claim. If it does not, the Wallet MUST terminate request processing. +The Wallet MUST process the request as defined in [@RFC9101]. Additionally, if the Wallet passed a `wallet_nonce` in the POST request, the Wallet MUST validate whether the request object contains the respective nonce value in a `wallet_nonce` claim. If it does not, the Wallet MUST terminate request processing. The Wallet MUST extract the set of Authorization Request parameters from the Request Object. The Wallet MUST only use the parameters in this Request Object, even if the same parameter was provided in an Authorization Request query parameter. The Client Identifier value in the `client_id` Authorization Request parameter and the Request Object `client_id` claim value MUST be identical. If the Authorization Request contains a `client_id_scheme` parameter, the `client_id_scheme` Authorization Request parameter and the Request Object `client_id_scheme` claim value MUST be identical. If any of these conditions are not met, the Wallet MUST terminate request processing. @@ -608,7 +608,7 @@ or allowed by a Wallet. The following format-specific properties are defined: -### Format `vc+sd-jwt` {#format_vc+sd-jwt} +### Format `vc+sd-jwt` {#format_vc_sd_jwt} `vct_values`: : OPTIONAL. An array of strings that specifies allowed values for @@ -840,7 +840,7 @@ The `presentation_submission` element MUST be included as a separate response pa Including the `presentation_submission` parameter as a separate response parameter allows the Wallet to provide the Verifier with additional information about the format and structure in advance of the processing of the VP Token, and can be used even with the Credential formats that do not allow for the direct inclusion of `presentation_submission` parameters inside a Credential itself. -The following is a non-normative example of an Authorization Response when the Response Type value in the Authorization Request was `vp_token`: +The following is a non-normative example of an Authorization Response when the Response Type value in the Authorization Request was `vp_token`: ``` HTTP/1.1 302 Found @@ -857,7 +857,7 @@ The following is a non-normative example of a `presentation_submission` paramete <{{examples/response/presentation_submission.json}} -A `descriptor_map` element MUST contain a `path_nested` parameter referring to the actual Credential carried in the respective Verifiable Presentation. +A `descriptor_map` element MUST contain a `path_nested` parameter referring to the actual Credential carried in the respective Verifiable Presentation. The following is a non-normative example of a VP Token containing multiple Verifiable Presentations: @@ -869,9 +869,9 @@ The following is a non-normative example of a `presentation_submission` paramete ## Response Mode "direct_post" {#response_mode_post} -The Response Mode `direct_post` allows the Wallet to send the Authorization Response to an endpoint controlled by the Verifier via an HTTP POST request. +The Response Mode `direct_post` allows the Wallet to send the Authorization Response to an endpoint controlled by the Verifier via an HTTP POST request. -It has been defined to address the following use cases: +It has been defined to address the following use cases: * Verifier and Wallet are located on different devices; thus, the Wallet cannot send the Authorization Response to the Verifier using a redirect. * The Authorization Response size exceeds the URL length limits of user agents, so flows relying only on redirects (such as Response Mode `fragment`) cannot be used. In those cases, the Response Mode `direct_post` is the way to convey the Verifiable Presentations to the Verifier without the need for the Wallet to have a backend. @@ -881,12 +881,12 @@ The Response Mode is defined in accordance with [@!OAuth.Responses] as follows: `direct_post`: : In this mode, the Authorization Response is sent to the Verifier using an HTTP POST request to an endpoint controlled by the Verifier. The Authorization Response parameters are encoded in the body using the `application/x-www-form-urlencoded` content type. The flow can end with an HTTP POST request from the Wallet to the Verifier, or it can end with a redirect that follows the HTTP POST request, if the Verifier responds with a redirect URI to the Wallet. -The following new Authorization Request parameter is defined to be used in conjunction with Response Mode `direct_post`: +The following new Authorization Request parameter is defined to be used in conjunction with Response Mode `direct_post`: `response_uri`: : REQUIRED when the Response Mode `direct_post` is used. The Response URI to which the Wallet MUST send the Authorization Response using an HTTP POST request as defined by the Response Mode `direct_post`. The Response URI receives all Authorization Response parameters as defined by the respective Response Type. When the `response_uri` parameter is present, the `redirect_uri` Authorization Request parameter MUST NOT be present. If the `redirect_uri` Authorization Request parameter is present when the Response Mode is `direct_post`, the Wallet MUST return an `invalid_request` Authorization Response error. The `response_uri` value MUST be a value that the client would be permitted to use as `redirect_uri` when following the rules defined in (#client_metadata_management). -Note: The Verifier's component providing the user interface (Frontend) and the Verifier's component providing the Response URI (Response Endpoint) need to be able to map authorization requests to the respective authorization responses. The Verifier MAY use the `state` Authorization Request parameter to add appropriate data to the Authorization Response for that purpose, for details see (#implementation_considerations_direct_post). +Note: The Verifier's component providing the user interface (Frontend) and the Verifier's component providing the Response URI (Response Endpoint) need to be able to map authorization requests to the respective authorization responses. The Verifier MAY use the `state` Authorization Request parameter to add appropriate data to the Authorization Response for that purpose, for details see (#implementation_considerations_direct_post). The following is a non-normative example of the payload of a Request Object with Response Mode `direct_post`: @@ -954,7 +954,7 @@ Content-Type: application/json Cache-Control: no-store { - "redirect_uri": "https://client.example.org/cb#response_code=091535f699ea575c7937fa5f0f454aee" + "redirect_uri": "https://client.example.org/cb#response_code=091535f699ea575c7937fa5f0f454aee" } ``` @@ -983,7 +983,7 @@ The following is a non-normative example of the payload of a JWT used in an Auth The JWT response document MUST include `vp_token` and `presentation_submission` parameters as defined in (#response-parameters). -The key material used for encryption and signing SHOULD be determined using existing metadata mechanisms. +The key material used for encryption and signing SHOULD be determined using existing metadata mechanisms. To obtain Verifier's public key for the input to the key agreement to encrypt the Authorization Response, the Wallet MUST use `jwks` or `jwks_uri` claim within the `client_metadata` request parameter, or within the metadata defined in the Entity Configuration when [@!OpenID.Federation] is used, or other mechanisms. @@ -1007,7 +1007,7 @@ The following is a non-normative example of the payload of the JWT used in the e The error response follows the rules as defined in [@!RFC6749], with the following additional clarifications: -`invalid_scope`: +`invalid_scope`: - Requested scope value is invalid, unknown, or malformed. @@ -1116,7 +1116,7 @@ Verifier utilizing this specification has multiple options to obtain Wallet's me # Verifier Metadata (Client Metadata) {#client_metadata} -To convey Verifier metadata, Client metadata defined in Section 2 of [@!RFC7591] is used. +To convey Verifier metadata, Client metadata defined in Section 2 of [@!RFC7591] is used. This specification defines how the Wallet can determine Credential formats, proof types and algorithms supported by the Verifier to be used in a protocol exchange. @@ -1134,12 +1134,12 @@ The Verifier Attestation JWT is a JWT especially designed to allow a Wallet to a A Verifier Attestation JWT MUST contain the following claims: -* `iss`: REQUIRED. This claim identifies the issuer of the Verifier Attestation JWT. The `iss` value MAY be used to retrieve the issuer's public key. How the trust is established between Wallet and Issuer and how the public key is obtained for validating the attestation's signature is out of scope of this specification. +* `iss`: REQUIRED. This claim identifies the issuer of the Verifier Attestation JWT. The `iss` value MAY be used to retrieve the issuer's public key. How the trust is established between Wallet and Issuer and how the public key is obtained for validating the attestation's signature is out of scope of this specification. * `sub`: REQUIRED. The value of this claim MUST be the `client_id` of the client making the credential request. * `iat`: OPTIONAL. (number). The value of this claim MUST be the time at which the Verifier Attestation JWT was issued using the syntax defined in [RFC7519]. * `exp`: REQUIRED. (number). The value of this claim MUST be the time at which the Verifier Attestation JWT expires using the syntax defined in [RFC7519]. The Wallet MUST reject any Verifier Attestation JWT with an expiration time that has passed, subject to allowable clock skew between systems. * `nbf`: OPTIONAL. The Verifier Attestation JWT MAY contain an "nbf" (not before) claim that identifies the time before which the token MUST NOT be accepted for processing. -* `cnf`: REQUIRED. This claim contains the confirmation method as defined in [@!RFC7800]. It MUST contain a JWK as defined in Section 3.2 of [RFC7800]. This claim determines the public key for which's corresponding private key the Verifier MUST proof possession of when presenting the Verifier Attestation JWT. This additional security measure allows the Verifier to obtain a Verifier Attestion JWT from a trusted issuer and use it for a long time independent of that issuer without the risk of an advisary impersonating the Verifier by replaying a captured attestation. +* `cnf`: REQUIRED. This claim contains the confirmation method as defined in [@!RFC7800]. It MUST contain a JWK as defined in Section 3.2 of [RFC7800]. This claim determines the public key for which's corresponding private key the Verifier MUST proof possession of when presenting the Verifier Attestation JWT. This additional security measure allows the Verifier to obtain a Verifier Attestion JWT from a trusted issuer and use it for a long time independent of that issuer without the risk of an advisary impersonating the Verifier by replaying a captured attestation. The Verifier Attestation JWT MAY use any claim registered in the "JSON Web Token Claims" registry as defined in [@!RFC7519]. @@ -1147,11 +1147,11 @@ Verifier Attestation JWTs compliant with this specification MUST use the media t A Verifier Attestation JWT MUST set the `typ` JOSE header to `verifier-attestation+jwt`. -The Verifier Attestation JWT MAY be conveyed in the header of a JWS signed object (JOSE header). +The Verifier Attestation JWT MAY be conveyed in the header of a JWS signed object (JOSE header). -This specification introduces a JOSE header, which can be used to add a JWT to such a header as follows: +This specification introduces a JOSE header, which can be used to add a JWT to such a header as follows: -* `jwt`: This JOSE header MUST contain a JWT. +* `jwt`: This JOSE header MUST contain a JWT. In the context of this specification, such a JWT MUST set the `typ` JOSE header to `verifier-attestation+jwt`. @@ -1240,9 +1240,9 @@ When using Response Mode `direct_post`, also see (#security_considerations_direc ## Response Mode `direct_post` {#implementation_considerations_direct_post} -The design of the interactions between the different components of the Verifier (especially Frontend and Response Endpoint) when using Response Mode `direct_post` is at the discretion of the Verifier since it does not affect the interface between the Verifier and the Wallet. +The design of the interactions between the different components of the Verifier (especially Frontend and Response Endpoint) when using Response Mode `direct_post` is at the discretion of the Verifier since it does not affect the interface between the Verifier and the Wallet. -In order to support implementers, this section outlines a possible design that fulfills the Security Considerations given in (#security_considerations). +In order to support implementers, this section outlines a possible design that fulfills the Security Considerations given in (#security_considerations). The design is illustrated in the following sequence diagram: @@ -1251,7 +1251,7 @@ The design is illustrated in the following sequence diagram: +-------+ +------------+ +---------------------+ +----------+ | User | | Verifier | | Verifier | | Wallet | | | | | | Response Endpoint | | | -+-------+ +------------+ +---------------------+ +----------+ ++-------+ +------------+ +---------------------+ +----------+ | | | | | interacts | | | |------------->| | | @@ -1302,44 +1302,44 @@ Figure: Reference Design for Response Mode `direct_post` (1) The Verifier produces a `nonce` value by generating at least 16 fresh, cryptographically random bytes with sufficient entropy, associates it with the session and base64url encodes it. -(2) The Verifier initiates a new transaction at its Response Endpoint. +(2) The Verifier initiates a new transaction at its Response Endpoint. (3) The Response Endpoint will set up the transaction and respond with two fresh, cryptographically random numbers with sufficient entropy designated as `transaction-id` and `request-id`. Those values are used in the process to identify the authorization response (`request-id`) and to ensure only the Verifier can obtain the Authorization Response data (`transaction-id`). (4) The Verifier then sends the Authorization Request with the `request-id` as `state` and the `nonce` value created in step (1) to the Wallet. -(5) After authenticating the End-User and getting her consent to share the request Credentials, the Wallet sends the Authorization Response with the parameters `vp_token`, `presentation_submission` and `state` to the `response_uri` of the Verifier. +(5) After authenticating the End-User and getting her consent to share the request Credentials, the Wallet sends the Authorization Response with the parameters `vp_token`, `presentation_submission` and `state` to the `response_uri` of the Verifier. -(6) The Verifier's Response Endpoint checks whether the `state` value is a valid `request-id`. If so, it stores the Authorization Response data linked to the respective `transaction-id`. It then creates a `response_code` as fresh, cryptographically random number with sufficient entropy that it also links with the respective Authorization Response data. It then returns the `redirect_uri`, which includes the `response_code` to the Wallet. +(6) The Verifier's Response Endpoint checks whether the `state` value is a valid `request-id`. If so, it stores the Authorization Response data linked to the respective `transaction-id`. It then creates a `response_code` as fresh, cryptographically random number with sufficient entropy that it also links with the respective Authorization Response data. It then returns the `redirect_uri`, which includes the `response_code` to the Wallet. -Note: If the Verifier's Response Endpoint does not return a `redirect_uri`, processing at the Wallet stops at that step. The Verifier is supposed to fetch the Authorization Response without waiting for a redirect (see step 8). +Note: If the Verifier's Response Endpoint does not return a `redirect_uri`, processing at the Wallet stops at that step. The Verifier is supposed to fetch the Authorization Response without waiting for a redirect (see step 8). (7) The Wallet sends the user agent to the Verifier (`redirect_uri`). The Verifier receives the Request and extracts the `response_code` parameter. -(8) The Verifier sends the `response_code` and the `transaction-id` from its session to the Response Endpoint. +(8) The Verifier sends the `response_code` and the `transaction-id` from its session to the Response Endpoint. -* The Response Endpoint uses the `transaction-id` to look the matching Authorization Response data up, which implicitly validates the `transaction-id` associated with the Verifier's session. +* The Response Endpoint uses the `transaction-id` to look the matching Authorization Response data up, which implicitly validates the `transaction-id` associated with the Verifier's session. * If an Authorization Response is found, the Response Endpoint checks whether the `response_code` was associated with this Authorization Response in step (6). -Note: If the Verifier's Response Endpoint did not return a `redirect_uri` in step (6), the Verifier will periodically query the Response Endpoint with the `transaction-id` to obtain the Authorization Response once it becomes available. +Note: If the Verifier's Response Endpoint did not return a `redirect_uri` in step (6), the Verifier will periodically query the Response Endpoint with the `transaction-id` to obtain the Authorization Response once it becomes available. -(9) The Response Endpoint returns the VP Token and Presentation Submission for further processing to the Verifier. +(9) The Response Endpoint returns the VP Token and Presentation Submission for further processing to the Verifier. (10) The Verifier checks whether the `nonce` received in the Credential(s) in the VP Token in step (9) corresponds to the `nonce` value from the session. The Verifier then consumes the VP Token and invalidates the `transaction-id`, `request-id` and `nonce` in the session. # Security Considerations {#security_considerations} -## Preventing Replay of the VP Token {#preventing-replay} +## Preventing Replay of the VP Token {#preventing-replay} An attacker could try to inject a VP Token (or an individual Verifiable Presentation), that was obtained from a previous Authorization Response, into another Authorization Response thus impersonating the End-User that originally presented that VP Token or the respective Verifiable Presentation. -Implementers of this specification MUST implement the controls as defined in this section to detect such an attack. +Implementers of this specification MUST implement the controls as defined in this section to detect such an attack. -This specification assumes that a Verifiable Credential is always presented with a cryptographic proof of possession which can be a Verifiable Presentation. This cryptographic proof of possession MUST be bound by the Wallet to the intended audience (the Client Identifier of the Verifier) and the respective transaction (identified by the `nonce` parameter in the Authorization Request). The Verifier MUST verify this binding. +This specification assumes that a Verifiable Credential is always presented with a cryptographic proof of possession which can be a Verifiable Presentation. This cryptographic proof of possession MUST be bound by the Wallet to the intended audience (the Client Identifier of the Verifier) and the respective transaction (identified by the `nonce` parameter in the Authorization Request). The Verifier MUST verify this binding. -The Verifier MUST create a fresh, cryptographically random number with sufficient entropy for every Authorization Request, store it with its current session, and pass it in the `nonce` Authorization Request Parameter to the Wallet. +The Verifier MUST create a fresh, cryptographically random number with sufficient entropy for every Authorization Request, store it with its current session, and pass it in the `nonce` Authorization Request Parameter to the Wallet. -The Wallet MUST link every Verifiable Presentation returned to the Verifier in the VP Token to the `client_id` and the `nonce` values of the respective Authentication Request. +The Wallet MUST link every Verifiable Presentation returned to the Verifier in the VP Token to the `client_id` and the `nonce` values of the respective Authentication Request. The Verifier MUST validate every individual Verifiable Presentation in an Authorization Response and ensure that it is linked to the values of the `client_id` and the `nonce` parameter it had used for the respective Authorization Request. If the response contains multiple Verifiable Presentations which do not contain the same nonce value, the response is rejected. @@ -1383,7 +1383,7 @@ The following is a non-normative example of a Verifiable Presentation of a forma "type": "RsaSignature2018", "created": "2018-09-14T21:19:10Z", "proofPurpose": "authentication", - "verificationMethod": "did:example:ebfeb1f712ebc6f1c276e12ec21#keys-1", + "verificationMethod": "did:example:ebfeb1f712ebc6f1c276e12ec21#keys-1", "challenge": "343s$FSFDa-", "domain": "s6BhdRkqt3", "jws": "eyJhb...nKb78" @@ -1395,11 +1395,11 @@ In the example above, the requested `nonce` value is included as the `challenge` ## Session Fixation {#session_fixation} -To perform a Session Fixation attack, an attacker would start the process using a Verifier executed on a device under his control, capture the Authorization Request and relay it to the device of a victim. The attacker would then periodically try to conclude the process in his Verifier, which would cause the Verifier on his device to try to fetch and verify the Authorization Response. +To perform a Session Fixation attack, an attacker would start the process using a Verifier executed on a device under his control, capture the Authorization Request and relay it to the device of a victim. The attacker would then periodically try to conclude the process in his Verifier, which would cause the Verifier on his device to try to fetch and verify the Authorization Response. -Such an attack is impossible against flows implemented with the Response Mode `fragment` as the Wallet will always send the VP Token to the redirect endpoint on the same device where it resides. This means an attacker could extract a valid Authorization Request from a Verifier on his device and trick a Victim into performing the same Authorization Request on her device. But there is technically no way for an attacker to get hold of the resulting VP Token. +Such an attack is impossible against flows implemented with the Response Mode `fragment` as the Wallet will always send the VP Token to the redirect endpoint on the same device where it resides. This means an attacker could extract a valid Authorization Request from a Verifier on his device and trick a Victim into performing the same Authorization Request on her device. But there is technically no way for an attacker to get hold of the resulting VP Token. -However, the Response Mode `direct_post` is susceptible to such an attack as the result is sent from the Wallet out-of-band to the Verifier's Response Endpoint. +However, the Response Mode `direct_post` is susceptible to such an attack as the result is sent from the Wallet out-of-band to the Verifier's Response Endpoint. This kind of attack can be detected if the Response Mode `direct_post` is used in conjunction with the redirect URI, which causes the Wallet to redirect the flow to the Verifier's frontend at the device where the transaction was concluded. The Verifier's Response Endpoint MUST include a fresh secret (Response Code) into the redirect URI returned to the Wallet and the Verifier's Response Endpoint MUST require the frontend to pass the respective Response Code when fetching the Authorization Response. That stops session fixation attacks as long as the attacker is unable to get access to the Response Code. @@ -1418,13 +1418,13 @@ The Wallet MUST ensure the data in the Authorization Response cannot leak throug ### Protection of the Response URI -The Verifier SHOULD protect its Response URI from inadvertent requests by checking that the value of the received `state` parameter corresponds to a recent Authorization Request. It MAY also use JARM [@!JARM] to authenticate the originator of the request. +The Verifier SHOULD protect its Response URI from inadvertent requests by checking that the value of the received `state` parameter corresponds to a recent Authorization Request. It MAY also use JARM [@!JARM] to authenticate the originator of the request. ### Protection of the Authorization Response Data -This specification assumes that the Verifier's Response Endpoint offers an internal interface to other components of the Verifier to obtain (and subsequently process) Authorization Response data. An attacker could try to obtain Authorization Response Data from a Verifier's Response Endpoint by looking up this data through the internal interface. This could lead to leakage valid Verifiable Presentations containing PII. +This specification assumes that the Verifier's Response Endpoint offers an internal interface to other components of the Verifier to obtain (and subsequently process) Authorization Response data. An attacker could try to obtain Authorization Response Data from a Verifier's Response Endpoint by looking up this data through the internal interface. This could lead to leakage valid Verifiable Presentations containing PII. -Implementations of this specification MUST have security mechanisms in place to prevent inadvertent requests against this internal interface. Implementation options to fulfill this requirement include: +Implementations of this specification MUST have security mechanisms in place to prevent inadvertent requests against this internal interface. Implementation options to fulfill this requirement include: * Authentication between the different parts within the Verifier * Two cryptographically random numbers. The first being used to manage state between the Wallet and Verifier. The second being used to ensure that only a legitimate component of the Verifier can obtain the Authorization Response data. @@ -1443,7 +1443,7 @@ If an encrypted Authorization Response has no additional integrity protection, a In many instances the referenced server will be operated by a known federation or other trusted operator, and the URL's domain name will already be widely known. Wallets using this URI can mitigate request forgeries by having a pre-configured set of trusted domain names and only fetching Presentation Definition from these sources. In addition, the Presentation Definitions could be signed by a trusted authority, such as the federation operator. -### JSONPath and Arbitrary Scripting +### JSONPath and Arbitrary Scripting Implementers MUST make sure that JSONPath used as part of `presentation_definition` and `presentation_submission` parameters cannot be used to execute arbitrary scripts on a server. This can be achieved, for example, by implementing the entire syntax of the query without relying on the parsers of programming language engine. For details, see Section 4 of [@I-D.ietf-jsonpath-base]. @@ -1467,7 +1467,7 @@ If no user interaction is required before sending the request, it is easy to req Mandatory user interaction before sending the request, like clicking a button, unlocking the wallet or even just showing a screen of the app, can make this less attractive/likely to being exploited. -Requests from the Wallet to the Verifier SHOULD be sent with the minimal amount of information possible, and in particular, without any HTTP headers identifying the software used for the request (e.g., HTTP libraries or their versions). The Wallet MUST NOT send PII or any other data that could be used for fingerprinting to the Request URI in order to prevent user tracking. +Requests from the Wallet to the Verifier SHOULD be sent with the minimal amount of information possible, and in particular, without any HTTP headers identifying the software used for the request (e.g., HTTP libraries or their versions). The Wallet MUST NOT send PII or any other data that could be used for fingerprinting to the Request URI in order to prevent user tracking. ## Authorization Error Response with the `wallet_unavailable` error code @@ -1578,7 +1578,7 @@ In the event that another component is invoked instead of the Wallet, the user M A novel approach to establish trust in Verifiable Credential -issuers in Self-Sovereign Identity ecosystems using TRAIN +issuers in Self-Sovereign Identity ecosystems using TRAIN University of Stuttgart @@ -1708,7 +1708,7 @@ issuers in Self-Sovereign Identity ecosystems using TRAIN Google - + Evernym @@ -1793,15 +1793,15 @@ but can be used with multiple protocols. The Web Platform, working in conjunctio This OpenID4VP profile utilizes the mechanisms of the W3C Digital Credentials API while also allowing to leverage advanced security features of OpenID4VP, if needed. It also defines the OpenID4VP request parameters that MAY be used with the W3C Digital Credentials API. -The Digital Credentials API offers several advantages for implementers of both Verifiers and Wallets. +The Digital Credentials API offers several advantages for implementers of both Verifiers and Wallets. -Firstly, the API serves as a privacy-preserving alternative to invoking Wallets via URLs, particularly custom URL schemes. The underlying app platform will only invoke a Wallet if the user confirms the request based on contextual information about the credential request and the requestor (Verifier). +Firstly, the API serves as a privacy-preserving alternative to invoking Wallets via URLs, particularly custom URL schemes. The underlying app platform will only invoke a Wallet if the user confirms the request based on contextual information about the credential request and the requestor (Verifier). Secondly, the session with the user will always continue in the initial context, typically a browser tab, when the request has been fulfilled (or aborted), which results in an improved user experience. Thirdly, cross-device requests benefit from the use of secure transports with proximity checks, which are handled by the OS platform, e.g., using FIDO CTAP 2.2 with hybrid transports. -And lastly, as part of the request, the Wallet is provided with information about the Verifier's origin as authenticated by the user agent, which is important for phishing resistance. +And lastly, as part of the request, the Wallet is provided with information about the Verifier's origin as authenticated by the user agent, which is important for phishing resistance. ## Protocol @@ -1833,7 +1833,7 @@ try { } ``` -Out of the Authorization Request parameters defined in [@!RFC6749] and (#vp_token_request), the following are supported with this profile: +Out of the Authorization Request parameters defined in [@!RFC6749] and (#vp_token_request), the following are supported with this profile: * `client_id` * `client_id_scheme` @@ -1943,13 +1943,13 @@ The following is a non-normative example of an Authorization Request: <{{examples/request/request.txt}} -The requirements regarding the Credential to be presented are conveyed in the `presentation_definition` parameter. +The requirements regarding the Credential to be presented are conveyed in the `presentation_definition` parameter. The following is a non-normative example of the contents of a `presentation_definition` parameter: <{{examples/request/pd_jwt_vc.json}} -This `presentation_definition` parameter contains a single `input_descriptor` element, which sets the desired format to JWT VC and defines a constraint over the `vc.type` parameter to select Verifiable Credentials of type `IDCredential`. +This `presentation_definition` parameter contains a single `input_descriptor` element, which sets the desired format to JWT VC and defines a constraint over the `vc.type` parameter to select Verifiable Credentials of type `IDCredential`. #### Presentation Response @@ -1957,7 +1957,7 @@ The following is a non-normative example of an Authorization Response: <{{examples/response/response.txt}} -The following is a non-normative example of the content of the `presentation_submission` parameter: +The following is a non-normative example of the content of the `presentation_submission` parameter: <{{examples/response/ps_jwt_vc.json}} @@ -2007,7 +2007,7 @@ The following is a non-normative example of the Verifiable Presentation in the ` <{{examples/response/ldp_vp.json}} -Note: The VP's `challenge` claim contains the value of the `nonce` of the presentation request and the `domain` claims contains the Client Identifier of the Verifier. This allows the Verifier to detect replay of a presentation as recommended in (#preventing-replay). +Note: The VP's `challenge` claim contains the value of the `nonce` of the presentation request and the `domain` claims contains the Client Identifier of the Verifier. This allows the Verifier to detect replay of a presentation as recommended in (#preventing-replay). ## AnonCreds @@ -2021,13 +2021,13 @@ Identifier for a CL-signature crypto scheme used in the examples in this section ### Example Credential -The following is a non-normative example of an AnonCred Credential that will be used throughout this section. +The following is a non-normative example of an AnonCred Credential that will be used throughout this section. <{{examples/credentials/ac_vc.json}} -The most important parts for the purpose of this section are `scheme_id` parameter and `values` parameter that contains the actual End-User claims. +The most important parts for the purpose of this section are `scheme_id` parameter and `values` parameter that contains the actual End-User claims. -### Presentation Request +### Presentation Request #### Request Example {#anoncreds_request} @@ -2041,19 +2041,19 @@ The following is a non-normative example of the content of the `presentation_def The `format` object in the `input_descrioptor` element uses the format identifier `ac_vc` as defined above and sets the `proof_type` to `CLSignature2019` to denote this descriptor requires a Credential in AnonCreds format signed with a CL signature (Camenisch-Lysyanskaya signature). The rest of the expressions operate on the AnonCreds JSON structure. -The `constraints` object requires the selected Credential to conform with the schema definition `did:indy:idu:test:3QowxFtwciWceMFr7WbwnM:2:BasicScheme:0\\.1`, which is denoted as a constraint over the AnonCred's `schema_id` parameter. +The `constraints` object requires the selected Credential to conform with the schema definition `did:indy:idu:test:3QowxFtwciWceMFr7WbwnM:2:BasicScheme:0\\.1`, which is denoted as a constraint over the AnonCred's `schema_id` parameter. #### Request Example with Selective Release of Claims The next example leverages the AnonCreds' capabilities for selective release by requesting a subset of the claims in the Credential to be disclosed to the Verifier. -A non-normative example of an Authorization Request would look the same as in (#anoncreds_request). +A non-normative example of an Authorization Request would look the same as in (#anoncreds_request). The following is a non-normative example of the difference is in the `presentation_definition` parameter: <{{examples/request/pd_ac_vc_sd.json}} -This example is identic to the previous one with the following exceptions: It sets the element `limit_disclosure` of the constraint to `require` and adds two more constraints for the individual claims `given_name` and `family_name`. Since such claims are stored underneath a `values` container in an AnonCred, `values` is part of the path to identify the respective claims. +This example is identic to the previous one with the following exceptions: It sets the element `limit_disclosure` of the constraint to `require` and adds two more constraints for the individual claims `given_name` and `family_name`. Since such claims are stored underneath a `values` container in an AnonCred, `values` is part of the path to identify the respective claims. ### Presentation Response @@ -2323,7 +2323,7 @@ Interoperability considerations: : n/a This specification registers the following JWS header name in the IANA "JSON Web Signature and Encryption Header Parameters" registry established by [@!RFC7515]. * Header Parameter Name: `jwt` -* Header Parameter Description: This header contains a JWT. Processing rules MAY depend on the `typ` header value of the respective JWT. +* Header Parameter Description: This header contains a JWT. Processing rules MAY depend on the `typ` header value of the respective JWT. * Header Parameter Usage Location: JWS * Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net * Specification Document(s): (#verifier_attestation_jwt) @@ -2352,7 +2352,7 @@ The technology described in this specification was made available from contribut * added how OpenID4VP request/response can be used over the browser API * remove path_nested description from Response Parameters section and move it into W3C VC Annex * fix indentation of examples - * added references to ISO/IEC 23220 and 18013 documents + * added references to ISO/IEC 23220 and 18013 documents * added `post` request method for Request URI * Added IETF SD-JWT VC profile * Added `wallet_unavailable` error @@ -2360,7 +2360,7 @@ The technology described in this specification was made available from contribut -20 * added "verifier_attestation" client id scheme value - + -19 * added "x509_san_uri" and "x509_san_dns" client id scheme value @@ -2371,7 +2371,7 @@ The technology described in this specification was made available from contribut -17 - * direct_post response mode uses state to identify response + * direct_post response mode uses state to identify response * Added sequence diagrams for same and cross device flows to overview section -16 @@ -2381,7 +2381,7 @@ The technology described in this specification was made available from contribut -15 - * Added definition of VP Token + * Added definition of VP Token * Editorial improvements for better readability (restructured request and response section, consistent terminology, and casing) -14 @@ -2403,7 +2403,7 @@ The technology described in this specification was made available from contribut * changed base protocol to OAuth 2.0 * consolidated the examples - + -10 * Added AnonCreds example @@ -2453,6 +2453,6 @@ The technology described in this specification was made available from contribut * adopted DIF Presentation Exchange request syntax * added security considerations regarding replay detection for Verifiable Credentials - -00 + -00 * initial revision From 50b17212bee50c0132b2b28bfa109835b4ee3b31 Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Tue, 30 Jul 2024 09:48:51 +0200 Subject: [PATCH 06/49] Revert "Fix anchor name" This reverts commit 7d719609a0c5e10a85f28d4f5ac4f82f05a10638. --- openid-4-verifiable-presentations-1_0.md | 208 +++++++++++------------ 1 file changed, 104 insertions(+), 104 deletions(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 3cdfd52c..c1b25a1a 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -46,7 +46,7 @@ organization="Mattr" .# Abstract -This specification defines a protocol for requesting and presenting Verifiable Credentials. +This specification defines a protocol for requesting and presenting Verifiable Credentials. {mainmatter} @@ -54,7 +54,7 @@ This specification defines a protocol for requesting and presenting Verifiable C This specification defines a mechanism on top of OAuth 2.0 [@!RFC6749] that enables presentation of Verifiable Credentials as Verifiable Presentations. Verifiable Credentials and Verifiable Presentations can be of any format, including, but not limited to W3C Verifiable Credentials Data Model [@VC_DATA], ISO mdoc [@ISO.18013-5], IETF SD-JWT VC [@!I-D.ietf-oauth-sd-jwt-vc], and AnonCreds [@Hyperledger.Indy]. -OAuth 2.0 [@!RFC6749] is used as a base protocol as it provides the required rails to build a simple, secure, and developer-friendly Credential presentation layer on top of it. Moreover, implementers can, in a single interface, support Credential presentation and the issuance of Access Tokens for access to APIs based on Verifiable Credentials in the Wallet. OpenID Connect [@!OpenID.Core] deployments can also extend their implementations using this specification with the ability to transport Verifiable Presentations. +OAuth 2.0 [@!RFC6749] is used as a base protocol as it provides the required rails to build a simple, secure, and developer-friendly Credential presentation layer on top of it. Moreover, implementers can, in a single interface, support Credential presentation and the issuance of Access Tokens for access to APIs based on Verifiable Credentials in the Wallet. OpenID Connect [@!OpenID.Core] deployments can also extend their implementations using this specification with the ability to transport Verifiable Presentations. This specification can also be combined with [@!SIOPv2], if implementers require OpenID Connect features, such as the issuance of Self-Issued ID Tokens [@!SIOPv2]. @@ -98,11 +98,11 @@ Verifier: Issuer-Holder-Verifier Model: : A model for exchanging claims, where claims are issued in the form of Verifiable Credentials independent of the process of presenting them as Verifiable Presentation to the Verifiers. An issued Verifiable Credential can (but must not necessarily) be used multiple times. -Holder Binding: -: Ability of the Holder to prove legitimate possession of a Verifiable Credential. +Holder Binding: +: Ability of the Holder to prove legitimate possession of a Verifiable Credential. Cryptographic Holder Binding: -: Ability of the Holder to prove legitimate possession of a Verifiable Credential by proving control over the same private key during the issuance and presentation. Mechanism might depend on the Credential Format. For example, in `jwt_vc_json` Credential Format, a Verifiable Credential with Cryptographic Holder Binding contains a public key or a reference to a public key that matches to the private key controlled by the Holder. +: Ability of the Holder to prove legitimate possession of a Verifiable Credential by proving control over the same private key during the issuance and presentation. Mechanism might depend on the Credential Format. For example, in `jwt_vc_json` Credential Format, a Verifiable Credential with Cryptographic Holder Binding contains a public key or a reference to a public key that matches to the private key controlled by the Holder. Claims-based Holder Binding: : Ability of the Holder to prove legitimate possession of a Verifiable Credential by proofing certain claims, e.g., name and date of birth, for example by presenting another Verifiable Credential. Claims-based Holder Binding allows long term, cross device use of a Credential as it does not depend on cryptographic key material stored on a certain device. One example of such a Verifiable Credential could be a Diploma. @@ -116,13 +116,13 @@ VP Token: Wallet: : An entity used by the Holder to receive, store, present, and manage Verifiable Credentials and key material. There is no single deployment model of a Wallet: Verifiable Credentials and keys can both be stored/managed locally, or by using a remote self-hosted service, or a remote third-party service. In the context of this specification, the Wallet acts as an OAuth 2.0 Authorization Server (see [@!RFC6749]) towards the Credential Verifier which acts as the OAuth 2.0 Client. -# Overview +# Overview This specification defines a mechanism on top of OAuth 2.0 to request and present Verifiable Credentials as Verifiable Presentations. As the primary extension, OpenID for Verifiable Presentations introduces the VP Token as a container to enable End-Users to present Verifiable Presentations to Verifiers using the Wallet. A VP Token contains one or more Verifiable Presentations in the same or different Credential formats. -This specification supports any Credential format used in the Issuer-Holder-Verifier Model, including, but not limited to those defined in [@VC_DATA] (VCDM), [@ISO.18013-5] (mdoc), [@!I-D.ietf-oauth-sd-jwt-vc] (SD-JWT VC), and [@Hyperledger.Indy] (AnonCreds). Credentials of multiple formats can be presented in the same transaction. The examples given in the main part of this specification use W3C Verifiable Credentials, while examples in other Credential formats are given in (#alternative_credential_formats). +This specification supports any Credential format used in the Issuer-Holder-Verifier Model, including, but not limited to those defined in [@VC_DATA] (VCDM), [@ISO.18013-5] (mdoc), [@!I-D.ietf-oauth-sd-jwt-vc] (SD-JWT VC), and [@Hyperledger.Indy] (AnonCreds). Credentials of multiple formats can be presented in the same transaction. The examples given in the main part of this specification use W3C Verifiable Credentials, while examples in other Credential formats are given in (#alternative_credential_formats). Implementations can use any pre-existing OAuth 2.0 Grant Type and Response Type in conjunction with this specification to support different deployment architectures. @@ -138,7 +138,7 @@ Any of the OAuth 2.0 related specifications, such as [@RFC9126] and [@RFC9101], Below is a diagram of a flow where the End-User presents a Credential to a Verifier interacting with the End-User on the same device that the device the Wallet resides on. -The flow utilizes simple redirects to pass Authorization Request and Response between the Verifier and the Wallet. The Verifiable Presentations are returned to the Verifier in the fragment part of the redirect URI, when Response Mode is `fragment`. +The flow utilizes simple redirects to pass Authorization Request and Response between the Verifier and the Wallet. The Verifiable Presentations are returned to the Verifier in the fragment part of the redirect URI, when Response Mode is `fragment`. Note: The diagram does not illustrate all the optional features of this specification. @@ -146,7 +146,7 @@ Note: The diagram does not illustrate all the optional features of this specific ~~~ ascii-art +--------------+ +--------------+ +--------------+ | User | | Verifier | | Wallet | -+--------------+ +--------------+ +--------------+ ++--------------+ +--------------+ +--------------+ | | | | Interacts | | |---------------->| | @@ -164,7 +164,7 @@ Note: The diagram does not illustrate all the optional features of this specific !--- Figure: Same Device Flow -(1) The Verifier sends an Authorization Request to the Wallet. It contains a Presentation Definition as defined in [@!DIF.PresentationExchange] that describes the requirements of the Credential(s) that the Verifier is requesting to be presented. Such requirements could include what type of Credential(s), in what format(s), which individual Claims within those Credential(s) (Selective Disclosure), etc. The Wallet processes the Authorization Request and determines what Credentials are available matching the Verifier's request. The Wallet also authenticates the End-User and gathers consent to present the requested Credentials. +(1) The Verifier sends an Authorization Request to the Wallet. It contains a Presentation Definition as defined in [@!DIF.PresentationExchange] that describes the requirements of the Credential(s) that the Verifier is requesting to be presented. Such requirements could include what type of Credential(s), in what format(s), which individual Claims within those Credential(s) (Selective Disclosure), etc. The Wallet processes the Authorization Request and determines what Credentials are available matching the Verifier's request. The Wallet also authenticates the End-User and gathers consent to present the requested Credentials. (2) The Wallet prepares the Verifiable Presentation(s) of the Verifiable Credential(s) that the End-User has consented to. It then sends to the Verifier an Authorization Response where the Verifiable Presentation(s) are contained in the `vp_token` parameter. @@ -207,11 +207,11 @@ Note: The usage of the Request URI as defined in [@!RFC9101] does not depend on !--- Figure: Cross Device Flow -(1) The Verifier sends to the Wallet an Authorization Request that contains a Request URI from where to obtain the Request Object containing Authorization Request parameters. +(1) The Verifier sends to the Wallet an Authorization Request that contains a Request URI from where to obtain the Request Object containing Authorization Request parameters. (2) The Wallet sends an HTTP GET request to the Request URI to retrieve the Request Object. -(2.5) The HTTP GET response returns the Request Object containing Authorization Request parameters. It especially contains a Presentation Definition as defined in [@!DIF.PresentationExchange] that describes the requirements of the Credential(s) that the Verifier is requesting to be presented. Such requirements could include what type of Credential(s), in what format(s), which individual Claims within those Credential(s) (Selective Disclosure), etc. The Wallet processes the Request Object and determines what Credentials are available matching the Verifier's request. The Wallet also authenticates the End-User and gathers her consent to present the requested Credentials. +(2.5) The HTTP GET response returns the Request Object containing Authorization Request parameters. It especially contains a Presentation Definition as defined in [@!DIF.PresentationExchange] that describes the requirements of the Credential(s) that the Verifier is requesting to be presented. Such requirements could include what type of Credential(s), in what format(s), which individual Claims within those Credential(s) (Selective Disclosure), etc. The Wallet processes the Request Object and determines what Credentials are available matching the Verifier's request. The Wallet also authenticates the End-User and gathers her consent to present the requested Credentials. (3) The Wallet prepares the Verifiable Presentation(s) of the Verifiable Credential(s) that the End-User has consented to. It then sends to the Verifier an Authorization Response where the Verifiable Presentation(s) are contained in the `vp_token` parameter. @@ -219,8 +219,8 @@ Figure: Cross Device Flow OpenID for Verifiable Presentations extends existing OAuth 2.0 mechanisms as following: -* A new `presentation_definition` Authorization Request parameter that uses the [@!DIF.PresentationExchange] syntax is defined to request presentation of Verifiable Credentials in arbitrary formats. See (#vp_token_request) for more details. -* A new `vp_token` response parameter is defined to return Verifiable Presentations to the Verifier in either Authorization or Token Response depending on the Response Type. See (#response) for more details. +* A new `presentation_definition` Authorization Request parameter that uses the [@!DIF.PresentationExchange] syntax is defined to request presentation of Verifiable Credentials in arbitrary formats. See (#vp_token_request) for more details. +* A new `vp_token` response parameter is defined to return Verifiable Presentations to the Verifier in either Authorization or Token Response depending on the Response Type. See (#response) for more details. * New Response Types `vp_token` and `vp_token id_token` are defined to request Verifiable Credentials to be returned in the Authorization Response (standalone or along with a Self-Issued ID Token [@!SIOPv2]). See (#response) for more details. * A new OAuth 2.0 Response Mode `direct_post` is defined to support sending the response across devices, or when the size of the response exceeds the redirect URL character size limitation. See (#response_mode_post) for more details. * The [@!DIF.PresentationExchange] `format` parameter is used throughout the protocol in order to enable customization according to the specific needs of a particular Credential format. Examples in (#alternative_credential_formats) are given for Credential formats as specified in [@VC_DATA], [@ISO.18013-5], [@!I-D.ietf-oauth-sd-jwt-vc], and [@Hyperledger.Indy]. @@ -257,7 +257,7 @@ This specification defines the following new parameters: `presentation_definition_uri`: : A string containing an HTTPS URL pointing to a resource where a Presentation Definition JSON object can be retrieved. This parameter MUST be present when `presentation_definition` parameter, or a `scope` value representing a Presentation Definition is not present. See (#request_presentation_definition_uri) for more details. -`client_id_scheme`: +`client_id_scheme`: : OPTIONAL. A string identifying the scheme of the value in the `client_id` Authorization Request parameter (Client Identifier scheme). The `client_id_scheme` parameter namespaces the respective Client Identifier. If an Authorization Request uses the `client_id_scheme` parameter, the Wallet MUST interpret the Client Identifier of the Verifier in the context of the Client Identifier scheme. If the parameter is not present, the Wallet MUST behave as specified in [@!RFC6749]. See (#client_metadata_management) for the values defined by this specification. If the same Client Identifier is used with different Client Identifier schemes, those occurrences MUST be treated as different Verifiers. Note that the Verifier needs to determine which Client Identifier schemes the Wallet supports prior to sending the Authorization Request in order to choose a supported scheme. `client_metadata`: @@ -265,11 +265,11 @@ This specification defines the following new parameters: A public key to be used by the Wallet as an input to the key agreement to encrypt Authorization Response (see (#jarm)). It MAY be passed by the Verifier using the `jwks` or the `jwks_uri` claim within the `client_metadata` request parameter. -`request_uri_method`: +`request_uri_method`: : 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. +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. The following additional considerations are given for pre-existing Authorization Request parameters: @@ -280,9 +280,9 @@ The following additional considerations are given for pre-existing Authorization : OPTIONAL. Defined in [@!RFC6749]. The Wallet MAY allow Verifiers to request presentation of Verifiable Credentials by utilizing a pre-defined scope value. See (#request_scope) for more details. `response_mode`: -: OPTIONAL. Defined in [@!OAuth.Responses]. This parameter is used (through the new Response Mode `direct_post`) to ask the Wallet to send the response to the Verifier via an HTTPS connection (see (#response_mode_post) for more details). It is also used to request signing and encrypting (see (#jarm) for more details). If the parameter is not present, the default value is `fragment`. +: OPTIONAL. Defined in [@!OAuth.Responses]. This parameter is used (through the new Response Mode `direct_post`) to ask the Wallet to send the response to the Verifier via an HTTPS connection (see (#response_mode_post) for more details). It is also used to request signing and encrypting (see (#jarm) for more details). If the parameter is not present, the default value is `fragment`. -The following is a non-normative example of an Authorization Request: +The following is a non-normative example of an Authorization Request: ``` GET /authorize? @@ -293,7 +293,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` and `client_metadata` parameters): ``` GET /authorize? @@ -320,7 +320,7 @@ The following non-normative example shows how the Verifiers can also ask for alt <{{examples/request/vp_token_alternative_credentials.json}} -The Verifiable Credential and Verifiable Presentation formats supported by the Wallet should be published in its metadata using the metadata parameter `vp_formats_supported` (see (#as_metadata_parameters)). +The Verifiable Credential and Verifiable Presentation formats supported by the Wallet should be published in its metadata using the metadata parameter `vp_formats_supported` (see (#as_metadata_parameters)). The formats supported by a Verifier may be set up using the metadata parameter `vp_formats` (see (#client_metadata_parameters)). The Wallet MUST ignore any `format` property inside a `presentation_definition` object if that `format` was not included in the `vp_formats` property of the metadata. @@ -328,7 +328,7 @@ Note: When a Verifier is requesting the presentation of a Verifiable Presentatio ## `presentation_definition_uri` Parameter {#request_presentation_definition_uri} -`presentation_definition_uri` is used to retrieve the Presentation Definition from the resource at the specified URL, rather than being passed by value. The Wallet MUST send an HTTP GET request without additional parameters. The resource MUST be exposed without further need to authenticate or authorize. +`presentation_definition_uri` is used to retrieve the Presentation Definition from the resource at the specified URL, rather than being passed by value. The Wallet MUST send an HTTP GET request without additional parameters. The resource MUST be exposed without further need to authenticate or authorize. The protocol for the `presentation_definition_uri` MUST be HTTPS. @@ -380,21 +380,21 @@ Content-Type: application/json Wallets MAY support requesting presentation of Verifiable Credentials using OAuth 2.0 scope values. -Such a scope value MUST be an alias for a well-defined Presentation Definition that will be -referred to in the `presentation_submission` response parameter. +Such a scope value MUST be an alias for a well-defined Presentation Definition that will be +referred to in the `presentation_submission` response parameter. -The specific scope values, and the mapping between a certain scope value and the respective -Presentation Definition is out of scope of this specification. +The specific scope values, and the mapping between a certain scope value and the respective +Presentation Definition is out of scope of this specification. Possible options include normative text in a separate specification defining scope values along with a description of their -semantics or machine readable definitions in the Wallet's server metadata, mapping a scope value to an equivalent -Presentation Definition JSON object. +semantics or machine readable definitions in the Wallet's server metadata, mapping a scope value to an equivalent +Presentation Definition JSON object. -Such definition of a scope value MUST allow the Verifier to determine the identifiers of the Presentation Definition and Input Descriptor(s) in the `presentation_submission` response parameter (`definition_id` and `descriptor_map.id` respectively) as well as the Credential formats and types in the `vp_token` response parameter defined in (#response-parameters). +Such definition of a scope value MUST allow the Verifier to determine the identifiers of the Presentation Definition and Input Descriptor(s) in the `presentation_submission` response parameter (`definition_id` and `descriptor_map.id` respectively) as well as the Credential formats and types in the `vp_token` response parameter defined in (#response-parameters). It is RECOMMENDED to use collision-resistant scopes values. -The following is a non-normative example of an Authorization Request using the scope value `com.example.IDCardCredential_presentation`, +The following is a non-normative example of an Authorization Request using the scope value `com.example.IDCardCredential_presentation`, which is an alias for the first Presentation Definition example given in (#request_presentation_definition): ``` @@ -417,7 +417,7 @@ See (#response) on how the `response_type` value determines the response used to ## Passing Authorization Request Across Devices -There are use-cases when the Authorization Request is being displayed on a device different from a device on which the requested Credential is stored. In those cases, an Authorization Request can be passed across devices by being rendered as a QR Code. +There are use-cases when the Authorization Request is being displayed on a device different from a device on which the requested Credential is stored. In those cases, an Authorization Request can be passed across devices by being rendered as a QR Code. The usage of the Response Mode `direct_post` (see (#response_mode_post)) in conjunction with `request_uri` is RECOMMENDED, since Authorization Request size might be large and might not fit in a QR code. @@ -428,13 +428,13 @@ When the Verifier is sending a Request Object as defined in [@!RFC9101], the `au - the `aud` Claim MUST equal to the `issuer` Claim value, when Dynamic Discovery is performed. - the `aud` Claim MUST be "https://self-issued.me/v2", when Static Discovery metadata is used. -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. +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} 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. -This specification defines the following values for the `client_id_scheme` parameter, followed by the examples where applicable: +This specification defines the following values for the `client_id_scheme` parameter, followed by the examples where applicable: * `pre-registered`: This value represents the [@!RFC6749] default behavior, i.e., the Client Identifier needs to be known to the Wallet in advance of the Authorization Request. The Verifier metadata is obtained using [@!RFC7591] or through out-of-band mechanisms. @@ -483,19 +483,19 @@ Other specifications can define further values for the `client_id_scheme` parame ## Request URI Method `post` {#request_uri_method_post} -This request is handled by the Request URI endpoint of the Verifier. +This request is handled by the Request URI endpoint of the Verifier. The request MUST use the HTTP POST method with the `https` scheme, and the content type `application/x-www-form-urlencoded` and the accept header set to `application/oauth-authz-req+jwt`. -The following parameters are defined: +The following parameters are defined: `wallet_metadata`: -: OPTIONAL. A String containing a JSON object containing metadata parameters as defined in (#as_metadata_parameters). +: OPTIONAL. A String containing a JSON object containing metadata parameters as defined in (#as_metadata_parameters). `wallet_nonce`: -: OPTIONAL. A String value used to mitigate replay attacks of the Authorization Request. When received, the Verifier MUST use it as the `wallet_nonce` value in the signed authorization request object. Value can be a base64url encoded, fresh, cryptographically random number with sufficient entropy. +: OPTIONAL. A String value used to mitigate replay attacks of the Authorization Request. When received, the Verifier MUST use it as the `wallet_nonce` value in the signed authorization request object. Value can be a base64url encoded, fresh, cryptographically random number with sufficient entropy. -If the Wallet requires the Verifier to encrypt the Request Object, it SHOULD use the `jwks` or `jwks_uri` parameter within the `wallet_metadata` parameter to pass the public key for the input to the key agreement. Other mechanisms to pass the encryption key can be used as well. If the Wallet requires an encrypted Authorization Response, it SHOULD specify supported encryption algorithms using the `authorization_encryption_alg_values_supported` and `authorization_encryption_enc_values_supported` parameters. +If the Wallet requires the Verifier to encrypt the Request Object, it SHOULD use the `jwks` or `jwks_uri` parameter within the `wallet_metadata` parameter to pass the public key for the input to the key agreement. Other mechanisms to pass the encryption key can be used as well. If the Wallet requires an encrypted Authorization Response, it SHOULD specify supported encryption algorithms using the `authorization_encryption_alg_values_supported` and `authorization_encryption_enc_values_supported` parameters. Additionally, if the `client_id_scheme` value permits signed Request Objects, the Wallet SHOULD list supported cryptographic algorithms for securing the Request Object through the `request_object_signing_alg_values_supported` parameter. Conversely, the Wallet MUST NOT include this parameter if the `client_id_scheme` precludes signed Request Objects. @@ -532,7 +532,7 @@ The following is a non-normative example of a request object: } ``` -The Wallet MUST process the request as defined in [@RFC9101]. Additionally, if the Wallet passed a `wallet_nonce` in the POST request, the Wallet MUST validate whether the request object contains the respective nonce value in a `wallet_nonce` claim. If it does not, the Wallet MUST terminate request processing. +The Wallet MUST process the request as defined in [@RFC9101]. Additionally, if the Wallet passed a `wallet_nonce` in the POST request, the Wallet MUST validate whether the request object contains the respective nonce value in a `wallet_nonce` claim. If it does not, the Wallet MUST terminate request processing. The Wallet MUST extract the set of Authorization Request parameters from the Request Object. The Wallet MUST only use the parameters in this Request Object, even if the same parameter was provided in an Authorization Request query parameter. The Client Identifier value in the `client_id` Authorization Request parameter and the Request Object `client_id` claim value MUST be identical. If the Authorization Request contains a `client_id_scheme` parameter, the `client_id_scheme` Authorization Request parameter and the Request Object `client_id_scheme` claim value MUST be identical. If any of these conditions are not met, the Wallet MUST terminate request processing. @@ -608,7 +608,7 @@ or allowed by a Wallet. The following format-specific properties are defined: -### Format `vc+sd-jwt` {#format_vc_sd_jwt} +### Format `vc+sd-jwt` {#format_vc+sd-jwt} `vct_values`: : OPTIONAL. An array of strings that specifies allowed values for @@ -840,7 +840,7 @@ The `presentation_submission` element MUST be included as a separate response pa Including the `presentation_submission` parameter as a separate response parameter allows the Wallet to provide the Verifier with additional information about the format and structure in advance of the processing of the VP Token, and can be used even with the Credential formats that do not allow for the direct inclusion of `presentation_submission` parameters inside a Credential itself. -The following is a non-normative example of an Authorization Response when the Response Type value in the Authorization Request was `vp_token`: +The following is a non-normative example of an Authorization Response when the Response Type value in the Authorization Request was `vp_token`: ``` HTTP/1.1 302 Found @@ -857,7 +857,7 @@ The following is a non-normative example of a `presentation_submission` paramete <{{examples/response/presentation_submission.json}} -A `descriptor_map` element MUST contain a `path_nested` parameter referring to the actual Credential carried in the respective Verifiable Presentation. +A `descriptor_map` element MUST contain a `path_nested` parameter referring to the actual Credential carried in the respective Verifiable Presentation. The following is a non-normative example of a VP Token containing multiple Verifiable Presentations: @@ -869,9 +869,9 @@ The following is a non-normative example of a `presentation_submission` paramete ## Response Mode "direct_post" {#response_mode_post} -The Response Mode `direct_post` allows the Wallet to send the Authorization Response to an endpoint controlled by the Verifier via an HTTP POST request. +The Response Mode `direct_post` allows the Wallet to send the Authorization Response to an endpoint controlled by the Verifier via an HTTP POST request. -It has been defined to address the following use cases: +It has been defined to address the following use cases: * Verifier and Wallet are located on different devices; thus, the Wallet cannot send the Authorization Response to the Verifier using a redirect. * The Authorization Response size exceeds the URL length limits of user agents, so flows relying only on redirects (such as Response Mode `fragment`) cannot be used. In those cases, the Response Mode `direct_post` is the way to convey the Verifiable Presentations to the Verifier without the need for the Wallet to have a backend. @@ -881,12 +881,12 @@ The Response Mode is defined in accordance with [@!OAuth.Responses] as follows: `direct_post`: : In this mode, the Authorization Response is sent to the Verifier using an HTTP POST request to an endpoint controlled by the Verifier. The Authorization Response parameters are encoded in the body using the `application/x-www-form-urlencoded` content type. The flow can end with an HTTP POST request from the Wallet to the Verifier, or it can end with a redirect that follows the HTTP POST request, if the Verifier responds with a redirect URI to the Wallet. -The following new Authorization Request parameter is defined to be used in conjunction with Response Mode `direct_post`: +The following new Authorization Request parameter is defined to be used in conjunction with Response Mode `direct_post`: `response_uri`: : REQUIRED when the Response Mode `direct_post` is used. The Response URI to which the Wallet MUST send the Authorization Response using an HTTP POST request as defined by the Response Mode `direct_post`. The Response URI receives all Authorization Response parameters as defined by the respective Response Type. When the `response_uri` parameter is present, the `redirect_uri` Authorization Request parameter MUST NOT be present. If the `redirect_uri` Authorization Request parameter is present when the Response Mode is `direct_post`, the Wallet MUST return an `invalid_request` Authorization Response error. The `response_uri` value MUST be a value that the client would be permitted to use as `redirect_uri` when following the rules defined in (#client_metadata_management). -Note: The Verifier's component providing the user interface (Frontend) and the Verifier's component providing the Response URI (Response Endpoint) need to be able to map authorization requests to the respective authorization responses. The Verifier MAY use the `state` Authorization Request parameter to add appropriate data to the Authorization Response for that purpose, for details see (#implementation_considerations_direct_post). +Note: The Verifier's component providing the user interface (Frontend) and the Verifier's component providing the Response URI (Response Endpoint) need to be able to map authorization requests to the respective authorization responses. The Verifier MAY use the `state` Authorization Request parameter to add appropriate data to the Authorization Response for that purpose, for details see (#implementation_considerations_direct_post). The following is a non-normative example of the payload of a Request Object with Response Mode `direct_post`: @@ -954,7 +954,7 @@ Content-Type: application/json Cache-Control: no-store { - "redirect_uri": "https://client.example.org/cb#response_code=091535f699ea575c7937fa5f0f454aee" + "redirect_uri": "https://client.example.org/cb#response_code=091535f699ea575c7937fa5f0f454aee" } ``` @@ -983,7 +983,7 @@ The following is a non-normative example of the payload of a JWT used in an Auth The JWT response document MUST include `vp_token` and `presentation_submission` parameters as defined in (#response-parameters). -The key material used for encryption and signing SHOULD be determined using existing metadata mechanisms. +The key material used for encryption and signing SHOULD be determined using existing metadata mechanisms. To obtain Verifier's public key for the input to the key agreement to encrypt the Authorization Response, the Wallet MUST use `jwks` or `jwks_uri` claim within the `client_metadata` request parameter, or within the metadata defined in the Entity Configuration when [@!OpenID.Federation] is used, or other mechanisms. @@ -1007,7 +1007,7 @@ The following is a non-normative example of the payload of the JWT used in the e The error response follows the rules as defined in [@!RFC6749], with the following additional clarifications: -`invalid_scope`: +`invalid_scope`: - Requested scope value is invalid, unknown, or malformed. @@ -1116,7 +1116,7 @@ Verifier utilizing this specification has multiple options to obtain Wallet's me # Verifier Metadata (Client Metadata) {#client_metadata} -To convey Verifier metadata, Client metadata defined in Section 2 of [@!RFC7591] is used. +To convey Verifier metadata, Client metadata defined in Section 2 of [@!RFC7591] is used. This specification defines how the Wallet can determine Credential formats, proof types and algorithms supported by the Verifier to be used in a protocol exchange. @@ -1134,12 +1134,12 @@ The Verifier Attestation JWT is a JWT especially designed to allow a Wallet to a A Verifier Attestation JWT MUST contain the following claims: -* `iss`: REQUIRED. This claim identifies the issuer of the Verifier Attestation JWT. The `iss` value MAY be used to retrieve the issuer's public key. How the trust is established between Wallet and Issuer and how the public key is obtained for validating the attestation's signature is out of scope of this specification. +* `iss`: REQUIRED. This claim identifies the issuer of the Verifier Attestation JWT. The `iss` value MAY be used to retrieve the issuer's public key. How the trust is established between Wallet and Issuer and how the public key is obtained for validating the attestation's signature is out of scope of this specification. * `sub`: REQUIRED. The value of this claim MUST be the `client_id` of the client making the credential request. * `iat`: OPTIONAL. (number). The value of this claim MUST be the time at which the Verifier Attestation JWT was issued using the syntax defined in [RFC7519]. * `exp`: REQUIRED. (number). The value of this claim MUST be the time at which the Verifier Attestation JWT expires using the syntax defined in [RFC7519]. The Wallet MUST reject any Verifier Attestation JWT with an expiration time that has passed, subject to allowable clock skew between systems. * `nbf`: OPTIONAL. The Verifier Attestation JWT MAY contain an "nbf" (not before) claim that identifies the time before which the token MUST NOT be accepted for processing. -* `cnf`: REQUIRED. This claim contains the confirmation method as defined in [@!RFC7800]. It MUST contain a JWK as defined in Section 3.2 of [RFC7800]. This claim determines the public key for which's corresponding private key the Verifier MUST proof possession of when presenting the Verifier Attestation JWT. This additional security measure allows the Verifier to obtain a Verifier Attestion JWT from a trusted issuer and use it for a long time independent of that issuer without the risk of an advisary impersonating the Verifier by replaying a captured attestation. +* `cnf`: REQUIRED. This claim contains the confirmation method as defined in [@!RFC7800]. It MUST contain a JWK as defined in Section 3.2 of [RFC7800]. This claim determines the public key for which's corresponding private key the Verifier MUST proof possession of when presenting the Verifier Attestation JWT. This additional security measure allows the Verifier to obtain a Verifier Attestion JWT from a trusted issuer and use it for a long time independent of that issuer without the risk of an advisary impersonating the Verifier by replaying a captured attestation. The Verifier Attestation JWT MAY use any claim registered in the "JSON Web Token Claims" registry as defined in [@!RFC7519]. @@ -1147,11 +1147,11 @@ Verifier Attestation JWTs compliant with this specification MUST use the media t A Verifier Attestation JWT MUST set the `typ` JOSE header to `verifier-attestation+jwt`. -The Verifier Attestation JWT MAY be conveyed in the header of a JWS signed object (JOSE header). +The Verifier Attestation JWT MAY be conveyed in the header of a JWS signed object (JOSE header). -This specification introduces a JOSE header, which can be used to add a JWT to such a header as follows: +This specification introduces a JOSE header, which can be used to add a JWT to such a header as follows: -* `jwt`: This JOSE header MUST contain a JWT. +* `jwt`: This JOSE header MUST contain a JWT. In the context of this specification, such a JWT MUST set the `typ` JOSE header to `verifier-attestation+jwt`. @@ -1240,9 +1240,9 @@ When using Response Mode `direct_post`, also see (#security_considerations_direc ## Response Mode `direct_post` {#implementation_considerations_direct_post} -The design of the interactions between the different components of the Verifier (especially Frontend and Response Endpoint) when using Response Mode `direct_post` is at the discretion of the Verifier since it does not affect the interface between the Verifier and the Wallet. +The design of the interactions between the different components of the Verifier (especially Frontend and Response Endpoint) when using Response Mode `direct_post` is at the discretion of the Verifier since it does not affect the interface between the Verifier and the Wallet. -In order to support implementers, this section outlines a possible design that fulfills the Security Considerations given in (#security_considerations). +In order to support implementers, this section outlines a possible design that fulfills the Security Considerations given in (#security_considerations). The design is illustrated in the following sequence diagram: @@ -1251,7 +1251,7 @@ The design is illustrated in the following sequence diagram: +-------+ +------------+ +---------------------+ +----------+ | User | | Verifier | | Verifier | | Wallet | | | | | | Response Endpoint | | | -+-------+ +------------+ +---------------------+ +----------+ ++-------+ +------------+ +---------------------+ +----------+ | | | | | interacts | | | |------------->| | | @@ -1302,44 +1302,44 @@ Figure: Reference Design for Response Mode `direct_post` (1) The Verifier produces a `nonce` value by generating at least 16 fresh, cryptographically random bytes with sufficient entropy, associates it with the session and base64url encodes it. -(2) The Verifier initiates a new transaction at its Response Endpoint. +(2) The Verifier initiates a new transaction at its Response Endpoint. (3) The Response Endpoint will set up the transaction and respond with two fresh, cryptographically random numbers with sufficient entropy designated as `transaction-id` and `request-id`. Those values are used in the process to identify the authorization response (`request-id`) and to ensure only the Verifier can obtain the Authorization Response data (`transaction-id`). (4) The Verifier then sends the Authorization Request with the `request-id` as `state` and the `nonce` value created in step (1) to the Wallet. -(5) After authenticating the End-User and getting her consent to share the request Credentials, the Wallet sends the Authorization Response with the parameters `vp_token`, `presentation_submission` and `state` to the `response_uri` of the Verifier. +(5) After authenticating the End-User and getting her consent to share the request Credentials, the Wallet sends the Authorization Response with the parameters `vp_token`, `presentation_submission` and `state` to the `response_uri` of the Verifier. -(6) The Verifier's Response Endpoint checks whether the `state` value is a valid `request-id`. If so, it stores the Authorization Response data linked to the respective `transaction-id`. It then creates a `response_code` as fresh, cryptographically random number with sufficient entropy that it also links with the respective Authorization Response data. It then returns the `redirect_uri`, which includes the `response_code` to the Wallet. +(6) The Verifier's Response Endpoint checks whether the `state` value is a valid `request-id`. If so, it stores the Authorization Response data linked to the respective `transaction-id`. It then creates a `response_code` as fresh, cryptographically random number with sufficient entropy that it also links with the respective Authorization Response data. It then returns the `redirect_uri`, which includes the `response_code` to the Wallet. -Note: If the Verifier's Response Endpoint does not return a `redirect_uri`, processing at the Wallet stops at that step. The Verifier is supposed to fetch the Authorization Response without waiting for a redirect (see step 8). +Note: If the Verifier's Response Endpoint does not return a `redirect_uri`, processing at the Wallet stops at that step. The Verifier is supposed to fetch the Authorization Response without waiting for a redirect (see step 8). (7) The Wallet sends the user agent to the Verifier (`redirect_uri`). The Verifier receives the Request and extracts the `response_code` parameter. -(8) The Verifier sends the `response_code` and the `transaction-id` from its session to the Response Endpoint. +(8) The Verifier sends the `response_code` and the `transaction-id` from its session to the Response Endpoint. -* The Response Endpoint uses the `transaction-id` to look the matching Authorization Response data up, which implicitly validates the `transaction-id` associated with the Verifier's session. +* The Response Endpoint uses the `transaction-id` to look the matching Authorization Response data up, which implicitly validates the `transaction-id` associated with the Verifier's session. * If an Authorization Response is found, the Response Endpoint checks whether the `response_code` was associated with this Authorization Response in step (6). -Note: If the Verifier's Response Endpoint did not return a `redirect_uri` in step (6), the Verifier will periodically query the Response Endpoint with the `transaction-id` to obtain the Authorization Response once it becomes available. +Note: If the Verifier's Response Endpoint did not return a `redirect_uri` in step (6), the Verifier will periodically query the Response Endpoint with the `transaction-id` to obtain the Authorization Response once it becomes available. -(9) The Response Endpoint returns the VP Token and Presentation Submission for further processing to the Verifier. +(9) The Response Endpoint returns the VP Token and Presentation Submission for further processing to the Verifier. (10) The Verifier checks whether the `nonce` received in the Credential(s) in the VP Token in step (9) corresponds to the `nonce` value from the session. The Verifier then consumes the VP Token and invalidates the `transaction-id`, `request-id` and `nonce` in the session. # Security Considerations {#security_considerations} -## Preventing Replay of the VP Token {#preventing-replay} +## Preventing Replay of the VP Token {#preventing-replay} An attacker could try to inject a VP Token (or an individual Verifiable Presentation), that was obtained from a previous Authorization Response, into another Authorization Response thus impersonating the End-User that originally presented that VP Token or the respective Verifiable Presentation. -Implementers of this specification MUST implement the controls as defined in this section to detect such an attack. +Implementers of this specification MUST implement the controls as defined in this section to detect such an attack. -This specification assumes that a Verifiable Credential is always presented with a cryptographic proof of possession which can be a Verifiable Presentation. This cryptographic proof of possession MUST be bound by the Wallet to the intended audience (the Client Identifier of the Verifier) and the respective transaction (identified by the `nonce` parameter in the Authorization Request). The Verifier MUST verify this binding. +This specification assumes that a Verifiable Credential is always presented with a cryptographic proof of possession which can be a Verifiable Presentation. This cryptographic proof of possession MUST be bound by the Wallet to the intended audience (the Client Identifier of the Verifier) and the respective transaction (identified by the `nonce` parameter in the Authorization Request). The Verifier MUST verify this binding. -The Verifier MUST create a fresh, cryptographically random number with sufficient entropy for every Authorization Request, store it with its current session, and pass it in the `nonce` Authorization Request Parameter to the Wallet. +The Verifier MUST create a fresh, cryptographically random number with sufficient entropy for every Authorization Request, store it with its current session, and pass it in the `nonce` Authorization Request Parameter to the Wallet. -The Wallet MUST link every Verifiable Presentation returned to the Verifier in the VP Token to the `client_id` and the `nonce` values of the respective Authentication Request. +The Wallet MUST link every Verifiable Presentation returned to the Verifier in the VP Token to the `client_id` and the `nonce` values of the respective Authentication Request. The Verifier MUST validate every individual Verifiable Presentation in an Authorization Response and ensure that it is linked to the values of the `client_id` and the `nonce` parameter it had used for the respective Authorization Request. If the response contains multiple Verifiable Presentations which do not contain the same nonce value, the response is rejected. @@ -1383,7 +1383,7 @@ The following is a non-normative example of a Verifiable Presentation of a forma "type": "RsaSignature2018", "created": "2018-09-14T21:19:10Z", "proofPurpose": "authentication", - "verificationMethod": "did:example:ebfeb1f712ebc6f1c276e12ec21#keys-1", + "verificationMethod": "did:example:ebfeb1f712ebc6f1c276e12ec21#keys-1", "challenge": "343s$FSFDa-", "domain": "s6BhdRkqt3", "jws": "eyJhb...nKb78" @@ -1395,11 +1395,11 @@ In the example above, the requested `nonce` value is included as the `challenge` ## Session Fixation {#session_fixation} -To perform a Session Fixation attack, an attacker would start the process using a Verifier executed on a device under his control, capture the Authorization Request and relay it to the device of a victim. The attacker would then periodically try to conclude the process in his Verifier, which would cause the Verifier on his device to try to fetch and verify the Authorization Response. +To perform a Session Fixation attack, an attacker would start the process using a Verifier executed on a device under his control, capture the Authorization Request and relay it to the device of a victim. The attacker would then periodically try to conclude the process in his Verifier, which would cause the Verifier on his device to try to fetch and verify the Authorization Response. -Such an attack is impossible against flows implemented with the Response Mode `fragment` as the Wallet will always send the VP Token to the redirect endpoint on the same device where it resides. This means an attacker could extract a valid Authorization Request from a Verifier on his device and trick a Victim into performing the same Authorization Request on her device. But there is technically no way for an attacker to get hold of the resulting VP Token. +Such an attack is impossible against flows implemented with the Response Mode `fragment` as the Wallet will always send the VP Token to the redirect endpoint on the same device where it resides. This means an attacker could extract a valid Authorization Request from a Verifier on his device and trick a Victim into performing the same Authorization Request on her device. But there is technically no way for an attacker to get hold of the resulting VP Token. -However, the Response Mode `direct_post` is susceptible to such an attack as the result is sent from the Wallet out-of-band to the Verifier's Response Endpoint. +However, the Response Mode `direct_post` is susceptible to such an attack as the result is sent from the Wallet out-of-band to the Verifier's Response Endpoint. This kind of attack can be detected if the Response Mode `direct_post` is used in conjunction with the redirect URI, which causes the Wallet to redirect the flow to the Verifier's frontend at the device where the transaction was concluded. The Verifier's Response Endpoint MUST include a fresh secret (Response Code) into the redirect URI returned to the Wallet and the Verifier's Response Endpoint MUST require the frontend to pass the respective Response Code when fetching the Authorization Response. That stops session fixation attacks as long as the attacker is unable to get access to the Response Code. @@ -1418,13 +1418,13 @@ The Wallet MUST ensure the data in the Authorization Response cannot leak throug ### Protection of the Response URI -The Verifier SHOULD protect its Response URI from inadvertent requests by checking that the value of the received `state` parameter corresponds to a recent Authorization Request. It MAY also use JARM [@!JARM] to authenticate the originator of the request. +The Verifier SHOULD protect its Response URI from inadvertent requests by checking that the value of the received `state` parameter corresponds to a recent Authorization Request. It MAY also use JARM [@!JARM] to authenticate the originator of the request. ### Protection of the Authorization Response Data -This specification assumes that the Verifier's Response Endpoint offers an internal interface to other components of the Verifier to obtain (and subsequently process) Authorization Response data. An attacker could try to obtain Authorization Response Data from a Verifier's Response Endpoint by looking up this data through the internal interface. This could lead to leakage valid Verifiable Presentations containing PII. +This specification assumes that the Verifier's Response Endpoint offers an internal interface to other components of the Verifier to obtain (and subsequently process) Authorization Response data. An attacker could try to obtain Authorization Response Data from a Verifier's Response Endpoint by looking up this data through the internal interface. This could lead to leakage valid Verifiable Presentations containing PII. -Implementations of this specification MUST have security mechanisms in place to prevent inadvertent requests against this internal interface. Implementation options to fulfill this requirement include: +Implementations of this specification MUST have security mechanisms in place to prevent inadvertent requests against this internal interface. Implementation options to fulfill this requirement include: * Authentication between the different parts within the Verifier * Two cryptographically random numbers. The first being used to manage state between the Wallet and Verifier. The second being used to ensure that only a legitimate component of the Verifier can obtain the Authorization Response data. @@ -1443,7 +1443,7 @@ If an encrypted Authorization Response has no additional integrity protection, a In many instances the referenced server will be operated by a known federation or other trusted operator, and the URL's domain name will already be widely known. Wallets using this URI can mitigate request forgeries by having a pre-configured set of trusted domain names and only fetching Presentation Definition from these sources. In addition, the Presentation Definitions could be signed by a trusted authority, such as the federation operator. -### JSONPath and Arbitrary Scripting +### JSONPath and Arbitrary Scripting Implementers MUST make sure that JSONPath used as part of `presentation_definition` and `presentation_submission` parameters cannot be used to execute arbitrary scripts on a server. This can be achieved, for example, by implementing the entire syntax of the query without relying on the parsers of programming language engine. For details, see Section 4 of [@I-D.ietf-jsonpath-base]. @@ -1467,7 +1467,7 @@ If no user interaction is required before sending the request, it is easy to req Mandatory user interaction before sending the request, like clicking a button, unlocking the wallet or even just showing a screen of the app, can make this less attractive/likely to being exploited. -Requests from the Wallet to the Verifier SHOULD be sent with the minimal amount of information possible, and in particular, without any HTTP headers identifying the software used for the request (e.g., HTTP libraries or their versions). The Wallet MUST NOT send PII or any other data that could be used for fingerprinting to the Request URI in order to prevent user tracking. +Requests from the Wallet to the Verifier SHOULD be sent with the minimal amount of information possible, and in particular, without any HTTP headers identifying the software used for the request (e.g., HTTP libraries or their versions). The Wallet MUST NOT send PII or any other data that could be used for fingerprinting to the Request URI in order to prevent user tracking. ## Authorization Error Response with the `wallet_unavailable` error code @@ -1578,7 +1578,7 @@ In the event that another component is invoked instead of the Wallet, the user M A novel approach to establish trust in Verifiable Credential -issuers in Self-Sovereign Identity ecosystems using TRAIN +issuers in Self-Sovereign Identity ecosystems using TRAIN University of Stuttgart @@ -1708,7 +1708,7 @@ issuers in Self-Sovereign Identity ecosystems using TRAIN Google - + Evernym @@ -1793,15 +1793,15 @@ but can be used with multiple protocols. The Web Platform, working in conjunctio This OpenID4VP profile utilizes the mechanisms of the W3C Digital Credentials API while also allowing to leverage advanced security features of OpenID4VP, if needed. It also defines the OpenID4VP request parameters that MAY be used with the W3C Digital Credentials API. -The Digital Credentials API offers several advantages for implementers of both Verifiers and Wallets. +The Digital Credentials API offers several advantages for implementers of both Verifiers and Wallets. -Firstly, the API serves as a privacy-preserving alternative to invoking Wallets via URLs, particularly custom URL schemes. The underlying app platform will only invoke a Wallet if the user confirms the request based on contextual information about the credential request and the requestor (Verifier). +Firstly, the API serves as a privacy-preserving alternative to invoking Wallets via URLs, particularly custom URL schemes. The underlying app platform will only invoke a Wallet if the user confirms the request based on contextual information about the credential request and the requestor (Verifier). Secondly, the session with the user will always continue in the initial context, typically a browser tab, when the request has been fulfilled (or aborted), which results in an improved user experience. Thirdly, cross-device requests benefit from the use of secure transports with proximity checks, which are handled by the OS platform, e.g., using FIDO CTAP 2.2 with hybrid transports. -And lastly, as part of the request, the Wallet is provided with information about the Verifier's origin as authenticated by the user agent, which is important for phishing resistance. +And lastly, as part of the request, the Wallet is provided with information about the Verifier's origin as authenticated by the user agent, which is important for phishing resistance. ## Protocol @@ -1833,7 +1833,7 @@ try { } ``` -Out of the Authorization Request parameters defined in [@!RFC6749] and (#vp_token_request), the following are supported with this profile: +Out of the Authorization Request parameters defined in [@!RFC6749] and (#vp_token_request), the following are supported with this profile: * `client_id` * `client_id_scheme` @@ -1943,13 +1943,13 @@ The following is a non-normative example of an Authorization Request: <{{examples/request/request.txt}} -The requirements regarding the Credential to be presented are conveyed in the `presentation_definition` parameter. +The requirements regarding the Credential to be presented are conveyed in the `presentation_definition` parameter. The following is a non-normative example of the contents of a `presentation_definition` parameter: <{{examples/request/pd_jwt_vc.json}} -This `presentation_definition` parameter contains a single `input_descriptor` element, which sets the desired format to JWT VC and defines a constraint over the `vc.type` parameter to select Verifiable Credentials of type `IDCredential`. +This `presentation_definition` parameter contains a single `input_descriptor` element, which sets the desired format to JWT VC and defines a constraint over the `vc.type` parameter to select Verifiable Credentials of type `IDCredential`. #### Presentation Response @@ -1957,7 +1957,7 @@ The following is a non-normative example of an Authorization Response: <{{examples/response/response.txt}} -The following is a non-normative example of the content of the `presentation_submission` parameter: +The following is a non-normative example of the content of the `presentation_submission` parameter: <{{examples/response/ps_jwt_vc.json}} @@ -2007,7 +2007,7 @@ The following is a non-normative example of the Verifiable Presentation in the ` <{{examples/response/ldp_vp.json}} -Note: The VP's `challenge` claim contains the value of the `nonce` of the presentation request and the `domain` claims contains the Client Identifier of the Verifier. This allows the Verifier to detect replay of a presentation as recommended in (#preventing-replay). +Note: The VP's `challenge` claim contains the value of the `nonce` of the presentation request and the `domain` claims contains the Client Identifier of the Verifier. This allows the Verifier to detect replay of a presentation as recommended in (#preventing-replay). ## AnonCreds @@ -2021,13 +2021,13 @@ Identifier for a CL-signature crypto scheme used in the examples in this section ### Example Credential -The following is a non-normative example of an AnonCred Credential that will be used throughout this section. +The following is a non-normative example of an AnonCred Credential that will be used throughout this section. <{{examples/credentials/ac_vc.json}} -The most important parts for the purpose of this section are `scheme_id` parameter and `values` parameter that contains the actual End-User claims. +The most important parts for the purpose of this section are `scheme_id` parameter and `values` parameter that contains the actual End-User claims. -### Presentation Request +### Presentation Request #### Request Example {#anoncreds_request} @@ -2041,19 +2041,19 @@ The following is a non-normative example of the content of the `presentation_def The `format` object in the `input_descrioptor` element uses the format identifier `ac_vc` as defined above and sets the `proof_type` to `CLSignature2019` to denote this descriptor requires a Credential in AnonCreds format signed with a CL signature (Camenisch-Lysyanskaya signature). The rest of the expressions operate on the AnonCreds JSON structure. -The `constraints` object requires the selected Credential to conform with the schema definition `did:indy:idu:test:3QowxFtwciWceMFr7WbwnM:2:BasicScheme:0\\.1`, which is denoted as a constraint over the AnonCred's `schema_id` parameter. +The `constraints` object requires the selected Credential to conform with the schema definition `did:indy:idu:test:3QowxFtwciWceMFr7WbwnM:2:BasicScheme:0\\.1`, which is denoted as a constraint over the AnonCred's `schema_id` parameter. #### Request Example with Selective Release of Claims The next example leverages the AnonCreds' capabilities for selective release by requesting a subset of the claims in the Credential to be disclosed to the Verifier. -A non-normative example of an Authorization Request would look the same as in (#anoncreds_request). +A non-normative example of an Authorization Request would look the same as in (#anoncreds_request). The following is a non-normative example of the difference is in the `presentation_definition` parameter: <{{examples/request/pd_ac_vc_sd.json}} -This example is identic to the previous one with the following exceptions: It sets the element `limit_disclosure` of the constraint to `require` and adds two more constraints for the individual claims `given_name` and `family_name`. Since such claims are stored underneath a `values` container in an AnonCred, `values` is part of the path to identify the respective claims. +This example is identic to the previous one with the following exceptions: It sets the element `limit_disclosure` of the constraint to `require` and adds two more constraints for the individual claims `given_name` and `family_name`. Since such claims are stored underneath a `values` container in an AnonCred, `values` is part of the path to identify the respective claims. ### Presentation Response @@ -2323,7 +2323,7 @@ Interoperability considerations: : n/a This specification registers the following JWS header name in the IANA "JSON Web Signature and Encryption Header Parameters" registry established by [@!RFC7515]. * Header Parameter Name: `jwt` -* Header Parameter Description: This header contains a JWT. Processing rules MAY depend on the `typ` header value of the respective JWT. +* Header Parameter Description: This header contains a JWT. Processing rules MAY depend on the `typ` header value of the respective JWT. * Header Parameter Usage Location: JWS * Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net * Specification Document(s): (#verifier_attestation_jwt) @@ -2352,7 +2352,7 @@ The technology described in this specification was made available from contribut * added how OpenID4VP request/response can be used over the browser API * remove path_nested description from Response Parameters section and move it into W3C VC Annex * fix indentation of examples - * added references to ISO/IEC 23220 and 18013 documents + * added references to ISO/IEC 23220 and 18013 documents * added `post` request method for Request URI * Added IETF SD-JWT VC profile * Added `wallet_unavailable` error @@ -2360,7 +2360,7 @@ The technology described in this specification was made available from contribut -20 * added "verifier_attestation" client id scheme value - + -19 * added "x509_san_uri" and "x509_san_dns" client id scheme value @@ -2371,7 +2371,7 @@ The technology described in this specification was made available from contribut -17 - * direct_post response mode uses state to identify response + * direct_post response mode uses state to identify response * Added sequence diagrams for same and cross device flows to overview section -16 @@ -2381,7 +2381,7 @@ The technology described in this specification was made available from contribut -15 - * Added definition of VP Token + * Added definition of VP Token * Editorial improvements for better readability (restructured request and response section, consistent terminology, and casing) -14 @@ -2403,7 +2403,7 @@ The technology described in this specification was made available from contribut * changed base protocol to OAuth 2.0 * consolidated the examples - + -10 * Added AnonCreds example @@ -2453,6 +2453,6 @@ The technology described in this specification was made available from contribut * adopted DIF Presentation Exchange request syntax * added security considerations regarding replay detection for Verifiable Credentials - -00 + -00 * initial revision From 2005364efc4c2a5a5c6887a70efda4bb8c3a4adb Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Tue, 30 Jul 2024 09:49:33 +0200 Subject: [PATCH 07/49] Fix anchor name --- 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 c1b25a1a..adbd4938 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -608,7 +608,7 @@ or allowed by a Wallet. The following format-specific properties are defined: -### Format `vc+sd-jwt` {#format_vc+sd-jwt} +### Format `vc+sd-jwt` {#format_vc_sd_jwt} `vct_values`: : OPTIONAL. An array of strings that specifies allowed values for From ba440bab4505923b2e0a9b6efb189506b2112aae Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Thu, 1 Aug 2024 13:41:01 +0200 Subject: [PATCH 08/49] Apply suggestions from Mike's code review Co-authored-by: Michael B. Jones --- examples/query_lang/credentials_alternatives.json | 14 +++++++------- examples/query_lang/multi_credentials.json | 14 +++++++------- examples/query_lang/nested_claim_queries.json | 6 +++--- examples/query_lang/simple.json | 4 ++-- openid-4-verifiable-presentations-1_0.md | 6 +++--- 5 files changed, 22 insertions(+), 22 deletions(-) diff --git a/examples/query_lang/credentials_alternatives.json b/examples/query_lang/credentials_alternatives.json index fdf5d312..a3e9d30b 100644 --- a/examples/query_lang/credentials_alternatives.json +++ b/examples/query_lang/credentials_alternatives.json @@ -17,8 +17,8 @@ "format": "vc+sd-jwt", "vct_values": ["https://credentials.example.com/identity_credential"], "claims": [ - { "path": ["last_name"] }, - { "path": ["first_name"] }, + { "path": ["given_name"] }, + { "path": ["family_name"] }, { "path": ["address", "street_address"] } ] }, @@ -26,17 +26,17 @@ "format": "vc+sd-jwt", "vct_values": ["https://credentials.example.com/identity_credential"], "claims": [ - { "path": ["last_name"] }, - { "path": ["first_name"] } + { "path": ["family_name"] }, + { "path": ["given_name"] } ] }, "residence_info": { "format": "vc+sd-jwt", "vct_values": ["https://credentials.example.com/residence_credential"], "claims": [ - { "path": ["zip_code"] }, - { "path": ["city"] }, - { "path": ["state"] } + { "path": ["postal_code"] }, + { "path": ["locality"] }, + { "path": ["region"] } ] } } diff --git a/examples/query_lang/multi_credentials.json b/examples/query_lang/multi_credentials.json index c706ce34..d8f5b64d 100644 --- a/examples/query_lang/multi_credentials.json +++ b/examples/query_lang/multi_credentials.json @@ -11,7 +11,7 @@ }], "claims": [ { "path": [ "last_name" ] }, - { "path": [ "first_name" ] }, + { "path": [ "given_name" ] }, { "path": [ "address", "street_address" ] } ] }, @@ -21,8 +21,8 @@ "vct_values": [ "https://example.com/education_credential" ] }, "claims": [ - { "path": [ "last_name" ] }, - { "path": [ "first_name" ] }, + { "path": [ "family_name" ] }, + { "path": [ "given_name" ] }, { "path": [ "degree" ] } ] }, @@ -32,10 +32,10 @@ "vct_values": [ "https://example.com/residence_proof" ] }, "claims": [ - { "path": [ "last_name" ] }, - { "path": [ "first_name" ] }, - { "path": [ "city" ] }, - { "path": [ "state" ] } + { "path": [ "family_name" ] }, + { "path": [ "given_name" ] }, + { "path": [ "locality" ] }, + { "path": [ "region" ] } ] } } diff --git a/examples/query_lang/nested_claim_queries.json b/examples/query_lang/nested_claim_queries.json index 7d8fe0ca..0969f46c 100644 --- a/examples/query_lang/nested_claim_queries.json +++ b/examples/query_lang/nested_claim_queries.json @@ -25,12 +25,12 @@ { "required": 1, "from": [ - { "path": [ "zip_code" ] }, + { "path": [ "postal_code" ] }, { "required": 2, "from": [ - { "path": [ "city" ] }, - { "path": [ "state" ] } + { "path": [ "locality" ] }, + { "path": [ "region" ] } ] } ] diff --git a/examples/query_lang/simple.json b/examples/query_lang/simple.json index b0c61a89..49a918ba 100644 --- a/examples/query_lang/simple.json +++ b/examples/query_lang/simple.json @@ -8,8 +8,8 @@ "sd_alg_values": ["SHA-256"] }, "claims":[ - { "path": ["last_name"] }, - { "path": ["first_name"] }, + { "path": ["family_name"] }, + { "path": ["given_name"] }, { "path": ["address", "street_address"] } ] } diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index adbd4938..6db04bb9 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -696,7 +696,7 @@ The following shows a non-normative, simplified example of a Credential: "name": "Arthur Dent", "address": { "street_address": "42 Market Street", - "city": "Milliways", + "locality": "Milliways", "postal_code": "12345" }, "degrees": [ @@ -2255,8 +2255,8 @@ Credential in the format `mso_mdoc` with the claims `vehicle_holder` and The following is a non-normative example of a VP Query that shows the usage of the `purpose` property, and requests the claim `last_name` and -- either the claim `zip_code`, or -- the claims `city` and `state`: +- either the claim `postal_code`, or +- the claims `locality` and `region`: <{{examples/query_lang/nested_claim_queries.json}} From 24aa2734c15a3c77b65425fd53a27be229672534 Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Tue, 20 Aug 2024 17:14:03 +0200 Subject: [PATCH 09/49] Update openid-4-verifiable-presentations-1_0.md Co-authored-by: Christian Bormann <8774236+c2bo@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 6db04bb9..07dd7859 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -798,7 +798,7 @@ Additional examples can be found in (#vp_query_examples). ## Additional Request Properties {#additional_request_properties} -`intend_to_retain`: TBD +`intent_to_retain`: TBD `if_present`: TBD From acdfd88ed26b85c3664c0d13f2a9f04fd3b52bd7 Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Tue, 20 Aug 2024 19:26:33 +0200 Subject: [PATCH 10/49] Remove purpose from credential query language proposal --- examples/query_lang/multi_credentials.json | 4 ---- examples/query_lang/nested_claim_queries.json | 13 ------------ openid-4-verifiable-presentations-1_0.md | 20 +------------------ 3 files changed, 1 insertion(+), 36 deletions(-) diff --git a/examples/query_lang/multi_credentials.json b/examples/query_lang/multi_credentials.json index d8f5b64d..c25641a1 100644 --- a/examples/query_lang/multi_credentials.json +++ b/examples/query_lang/multi_credentials.json @@ -5,10 +5,6 @@ "vc+sd-jwt": { "vct_values": [ "https://example.com/personal_identity" ] }, - "purpose": [{ - "lang": "en-US", - "text": "To prove the identity of the holder" - }], "claims": [ { "path": [ "last_name" ] }, { "path": [ "given_name" ] }, diff --git a/examples/query_lang/nested_claim_queries.json b/examples/query_lang/nested_claim_queries.json index 0969f46c..937acade 100644 --- a/examples/query_lang/nested_claim_queries.json +++ b/examples/query_lang/nested_claim_queries.json @@ -7,19 +7,6 @@ "alg_values": [ "ES256", "ES384" ], "sd_alg_values": [ "SHA-256" ] }, - "purpose": [{ - "lang": "en-US", - "text": "To prove the identity of the holder" - }, - { - "lang": "no-NO", - "text": "For å bevise innehaverens identitet" - }, - { - "lang": "jp-JP", - "text": "保持者の身元を証明するため" - } - ], "claims": [ { "path": [ "last_name" ] }, { diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 71e08706..1829ae58 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -751,23 +751,6 @@ In detail, the array is processed by the Wallet from left to right as follows: The result of the processing is the set of elements which is requested for presentation. - -## Purpose Description {#purpose_description} - -A purpose description array is an object that describes the purpose for which -the Verifier is requesting the Verifiable Credential. It can contain multiple -objects, each describing the purpose in a specific language. Each object -contains the following properties: - -`lang:` -: REQUIRED. A string that specifies the language of the purpose -description. The value of this property MUST be a valid language tag as defined -in [@!BCP47]. - -`text`: -: REQUIRED. A string that contains the purpose description in the -language specified by the `lang` property. - ## Credential Rules {#credential_rules} Just as for claims, the Verifier can define rules that specify which @@ -2254,8 +2237,7 @@ Credential in the format `mso_mdoc` with the claims `vehicle_holder` and <{{examples/query_lang/simple_mdoc.json}} -The following is a non-normative example of a VP Query that shows the usage of -the `purpose` property, and requests the claim `last_name` and +The following is a non-normative example of a VP Query that requests the claim `last_name` and - either the claim `postal_code`, or - the claims `locality` and `region`: From 110714cfc8aadef6946cbd19b1733b0ae3052a1f Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Tue, 20 Aug 2024 19:54:16 +0200 Subject: [PATCH 11/49] Add missing vp_query definition back into the PR --- openid-4-verifiable-presentations-1_0.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 1829ae58..0c8ddae4 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -220,6 +220,8 @@ Figure: Cross Device Flow OpenID for Verifiable Presentations extends existing OAuth 2.0 mechanisms as following: * A new `presentation_definition` Authorization Request parameter that uses the [@!DIF.PresentationExchange] syntax is defined to request presentation of Verifiable Credentials in arbitrary formats. See (#vp_token_request) for more details. +* A new query language is defined to enable requesting Verifiable Credentials in a more flexible way. See (#vp_query) for more details. +* A new `vp_query` Authorization Request parameter is defined to request presentation of Verifiable Credentials in the JSON-encoded VP Query format. See (#vp_token_request) for more details. * A new `vp_token` response parameter is defined to return Verifiable Presentations to the Verifier in either Authorization or Token Response depending on the Response Type. See (#response) for more details. * New Response Types `vp_token` and `vp_token id_token` are defined to request Verifiable Credentials to be returned in the Authorization Response (standalone or along with a Self-Issued ID Token [@!SIOPv2]). See (#response) for more details. * A new OAuth 2.0 Response Mode `direct_post` is defined to support sending the response across devices, or when the size of the response exceeds the redirect URL character size limitation. See (#response_mode_post) for more details. @@ -252,10 +254,14 @@ This specification enables the Verifier to send both Presentation Definition JSO This specification defines the following new parameters: `presentation_definition`: -: A string containing a Presentation Definition JSON object. See (#request_presentation_definition) for more details. This parameter MUST be present when `presentation_definition_uri` parameter, or a `scope` value representing a Presentation Definition is not present. +: A string containing a Presentation Definition JSON object. See (#request_presentation_definition) for more details. Exactly one of `vp_query` or `presentation_definition` or `presentation_definition_uri` MUST be present in the Authorization Request. `presentation_definition_uri`: -: A string containing an HTTPS URL pointing to a resource where a Presentation Definition JSON object can be retrieved. This parameter MUST be present when `presentation_definition` parameter, or a `scope` value representing a Presentation Definition is not present. See (#request_presentation_definition_uri) for more details. +: A string containing an HTTPS URL pointing to a resource where a Presentation Definition JSON object can be retrieved. See (#request_presentation_definition_uri) for more details. Exactly one of `vp_query` or `presentation_definition` or `presentation_definition_uri` MUST be present in the Authorizat +ion Request. + +`vp_query`: +: A string containing a JSON-encoded VP Query as defined in (#vp_query). This parameter is OPTIONAL. Exactly one of `vp_query` or `presentation_definition` or `presentation_definition_uri` MUST be present in the Authorization Request. `client_id_scheme`: : OPTIONAL. A string identifying the scheme of the value in the `client_id` Authorization Request parameter (Client Identifier scheme). The `client_id_scheme` parameter namespaces the respective Client Identifier. If an Authorization Request uses the `client_id_scheme` parameter, the Wallet MUST interpret the Client Identifier of the Verifier in the context of the Client Identifier scheme. If the parameter is not present, the Wallet MUST behave as specified in [@!RFC6749]. See (#client_metadata_management) for the values defined by this specification. If the same Client Identifier is used with different Client Identifier schemes, those occurrences MUST be treated as different Verifiers. Note that the Verifier needs to determine which Client Identifier schemes the Wallet supports prior to sending the Authorization Request in order to choose a supported scheme. From da380196d5c63cad9523f55e54fd434340221ae0 Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Tue, 20 Aug 2024 19:56:41 +0200 Subject: [PATCH 12/49] Remove another purpose mention --- openid-4-verifiable-presentations-1_0.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 0c8ddae4..3f4b8c67 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -587,10 +587,6 @@ Additional properties requested by the Verifier that are specific to the Credential format, as defined in (#format_specific_properties). If omitted, no format-specific restrictions are placed on the requested Credential. -`purpose`: -: OPTIONAL. A purpose description array as defined in -(#purpose_description). - `claims`: : OPTIONAL. An array that specifies the claims that the requested Verifiable Credential must contain. Each entry in the array corresponds to at From da854b3158e30813216b792316c635189db48ccb Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Wed, 11 Sep 2024 16:52:11 +0200 Subject: [PATCH 13/49] New format in examples --- .../query_lang/credentials_alternatives.json | 73 +++++++++++-------- examples/query_lang/multi_credentials.json | 63 ++++++++-------- examples/query_lang/nested_claim_queries.json | 28 ------- examples/query_lang/simple.json | 19 ++--- examples/query_lang/simple_mdoc.json | 13 ++-- 5 files changed, 88 insertions(+), 108 deletions(-) delete mode 100644 examples/query_lang/nested_claim_queries.json diff --git a/examples/query_lang/credentials_alternatives.json b/examples/query_lang/credentials_alternatives.json index a3e9d30b..cbc76747 100644 --- a/examples/query_lang/credentials_alternatives.json +++ b/examples/query_lang/credentials_alternatives.json @@ -1,43 +1,52 @@ { - "rules": { - "required": 2, - "from": [ - { "ref": "pid" }, - { - "required": 1, - "from": [ - { "ref": "pid_reduced" }, - { "ref": "residence_info" } - ] - } - ] - }, - "credentials": { - "pid": { + "expect_credentials": [ + { + "group": "pid", "format": "vc+sd-jwt", - "vct_values": ["https://credentials.example.com/identity_credential"], - "claims": [ - { "path": ["given_name"] }, - { "path": ["family_name"] }, - { "path": ["address", "street_address"] } + "expect_meta": { + "vct_values": ["https://credentials.example.com/identity_credential"] + }, + "expect_claims": [ + {"path": ["given_name"]}, + {"path": ["family_name"]}, + {"path": ["address", "street_address"]} + ], + "alternatives": ["other_pid", "pid_reduced"] + }, + { + "group": "other_pid", + "format": "vc+sd-jwt", + "expect_meta": { + "vct_values": ["https://othercredentials.example/pid"] + }, + "expect_claims": [ + {"path": ["given_name"]}, + {"path": ["family_name"]}, + {"path": ["address", "street_address"]} ] }, - "pid_reduced": { + { + "group": "pid_reduced", "format": "vc+sd-jwt", - "vct_values": ["https://credentials.example.com/identity_credential"], - "claims": [ - { "path": ["family_name"] }, - { "path": ["given_name"] } + "expect_meta": { + "vct_values": ["https://credentials.example.com/reduced_identity_credential"] + }, + "expect_claims": [ + {"path": ["family_name"]}, + {"path": ["given_name"]} ] }, - "residence_info": { + { + "group": "pid_reduced", "format": "vc+sd-jwt", - "vct_values": ["https://credentials.example.com/residence_credential"], - "claims": [ - { "path": ["postal_code"] }, - { "path": ["locality"] }, - { "path": ["region"] } + "expect_meta": { + "vct_values": ["https://cred.example/residence_credential"] + }, + "expect_claims": [ + {"path": ["postal_code"]}, + {"path": ["locality"]}, + {"path": ["region"]} ] } - } + ] } \ No newline at end of file diff --git a/examples/query_lang/multi_credentials.json b/examples/query_lang/multi_credentials.json index c25641a1..de13acab 100644 --- a/examples/query_lang/multi_credentials.json +++ b/examples/query_lang/multi_credentials.json @@ -1,38 +1,35 @@ { - "credentials": { - "pid": { - "format": "vc+sd-jwt", - "vc+sd-jwt": { - "vct_values": [ "https://example.com/personal_identity" ] - }, - "claims": [ - { "path": [ "last_name" ] }, - { "path": [ "given_name" ] }, - { "path": [ "address", "street_address" ] } - ] + "expect_credentials": [ + { + "group": "pid", + "format": "vc+sd-jwt", + "expect_meta": { + "vct_values": ["https://credentials.example.com/identity_credential"] + }, + "expect_claims": [ + {"path": ["given_name"]}, + {"path": ["family_name"]}, + {"path": ["address", "street_address"]} + ] + }, + { + "group": "other_pid", + "format": "mso_mdoc", + "expect_meta": { + "doctype_values": "org.iso.7367.1.mVR", + "alg_values": [ "EdDSA" ], + "hash_algorithm_values": [ "SHA-384"] + }, + "expect_claims": [ + { + "namespace": "org.iso.7367.1", + "claim_name": "vehicle_holder" }, - "degree": { - "format": "vc+sd-jwt", - "vc+sd-jwt": { - "vct_values": [ "https://example.com/education_credential" ] - }, - "claims": [ - { "path": [ "family_name" ] }, - { "path": [ "given_name" ] }, - { "path": [ "degree" ] } - ] - }, - "residence": { - "format": "vc+sd-jwt", - "vc+sd-jwt": { - "vct_values": [ "https://example.com/residence_proof" ] - }, - "claims": [ - { "path": [ "family_name" ] }, - { "path": [ "given_name" ] }, - { "path": [ "locality" ] }, - { "path": [ "region" ] } - ] + { + "namespace": "org.iso.18013.5.1", + "claim_name": "first_name" } + ] } +] } \ No newline at end of file diff --git a/examples/query_lang/nested_claim_queries.json b/examples/query_lang/nested_claim_queries.json deleted file mode 100644 index 937acade..00000000 --- a/examples/query_lang/nested_claim_queries.json +++ /dev/null @@ -1,28 +0,0 @@ -{ - "credentials": { - "my_cred_1": { - "format": "vc+sd-jwt", - "vc+sd-jwt": { - "vct_values": [ "https://credentials.example.com/identity_credential" ], - "alg_values": [ "ES256", "ES384" ], - "sd_alg_values": [ "SHA-256" ] - }, - "claims": [ - { "path": [ "last_name" ] }, - { - "required": 1, - "from": [ - { "path": [ "postal_code" ] }, - { - "required": 2, - "from": [ - { "path": [ "locality" ] }, - { "path": [ "region" ] } - ] - } - ] - } - ] - } - } -} \ No newline at end of file diff --git a/examples/query_lang/simple.json b/examples/query_lang/simple.json index 49a918ba..57ca344e 100644 --- a/examples/query_lang/simple.json +++ b/examples/query_lang/simple.json @@ -1,17 +1,18 @@ { - "credentials": { - "my_cred_1": { - "format": "vc+sd-jwt", - "vc+sd-jwt": { + "expect_credentials": [ + { + "group": "my_credential", + "format": ["vc+sd-jwt"], + "expect_meta": { "vct_values": [ "https://credentials.example.com/identity_credential" ], "alg_values": ["ES256", "ES384"], "sd_alg_values": ["SHA-256"] }, - "claims":[ - { "path": ["family_name"] }, - { "path": ["given_name"] }, - { "path": ["address", "street_address"] } + "expect_claims": [ + {"path": ["last_name"]}, + {"path": ["locality"]}, + {"path": ["region"]} ] } - } + ] } \ No newline at end of file diff --git a/examples/query_lang/simple_mdoc.json b/examples/query_lang/simple_mdoc.json index bf102166..fd767063 100644 --- a/examples/query_lang/simple_mdoc.json +++ b/examples/query_lang/simple_mdoc.json @@ -1,13 +1,14 @@ { - "credentials": { - "my_mdoc_credential": { + "expect_credentials": [ + { + "group": "my_credential", "format": "mso_mdoc", - "mso_mdoc": { - "doctype_values": "org.iso.7367.1.mVR", + "expect_meta": { + "doctype_values": ["org.iso.7367.1.mVR"], "alg_values": [ "EdDSA" ], "hash_algorithm_values": [ "SHA-384"] }, - "claims": [ + "expect_claims": [ { "namespace": "org.iso.7367.1", "claim_name": "vehicle_holder" @@ -18,5 +19,5 @@ } ] } - } + ] } \ No newline at end of file From d21e8e9b46471ffb588e42201eca85c7f9b13ebb Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Wed, 11 Sep 2024 17:36:08 +0200 Subject: [PATCH 14/49] Update spec text --- examples/query_lang/claims_alternatives.json | 36 ++++ .../query_lang/credentials_alternatives.json | 2 +- examples/query_lang/multi_credentials.json | 2 +- examples/query_lang/simple.json | 8 +- examples/query_lang/simple_mdoc.json | 2 +- openid-4-verifiable-presentations-1_0.md | 168 +++++++++--------- 6 files changed, 123 insertions(+), 95 deletions(-) create mode 100644 examples/query_lang/claims_alternatives.json diff --git a/examples/query_lang/claims_alternatives.json b/examples/query_lang/claims_alternatives.json new file mode 100644 index 00000000..111c9f7b --- /dev/null +++ b/examples/query_lang/claims_alternatives.json @@ -0,0 +1,36 @@ +{ + "expect_credentials": [ + { + "group": "pid", + "format": "vc+sd-jwt", + "expect_meta": { + "vct_values": [ "https://credentials.example.com/identity_credential" ], + "credential_signing_alg_values": ["ES256", "ES384"], + "sd_alg_values": ["SHA-256"] + }, + "expect_claims": [ + {"path": ["last_name"]}, + { + "path": ["postal_code"], + "alternative_claims": ["locality_and_region"] + }, + { + "group": "locality_and_region", + "path": ["locality"] + }, + { + "group": "locality_and_region", + "path": ["region"] + }, + { + "group": "age_verification", + "path": ["date_of_birth"] + }, + { + "group": "newsletter", + "path": ["email"] + } + ] + } + ] +} \ No newline at end of file diff --git a/examples/query_lang/credentials_alternatives.json b/examples/query_lang/credentials_alternatives.json index cbc76747..e9974b5a 100644 --- a/examples/query_lang/credentials_alternatives.json +++ b/examples/query_lang/credentials_alternatives.json @@ -11,7 +11,7 @@ {"path": ["family_name"]}, {"path": ["address", "street_address"]} ], - "alternatives": ["other_pid", "pid_reduced"] + "alternative_credentials": ["other_pid", "pid_reduced"] }, { "group": "other_pid", diff --git a/examples/query_lang/multi_credentials.json b/examples/query_lang/multi_credentials.json index de13acab..32972d10 100644 --- a/examples/query_lang/multi_credentials.json +++ b/examples/query_lang/multi_credentials.json @@ -13,7 +13,7 @@ ] }, { - "group": "other_pid", + "group": "mdl", "format": "mso_mdoc", "expect_meta": { "doctype_values": "org.iso.7367.1.mVR", diff --git a/examples/query_lang/simple.json b/examples/query_lang/simple.json index 57ca344e..6c3f482c 100644 --- a/examples/query_lang/simple.json +++ b/examples/query_lang/simple.json @@ -2,16 +2,16 @@ "expect_credentials": [ { "group": "my_credential", - "format": ["vc+sd-jwt"], + "format": "vc+sd-jwt", "expect_meta": { "vct_values": [ "https://credentials.example.com/identity_credential" ], - "alg_values": ["ES256", "ES384"], + "credential_signing_alg_values": ["ES256", "ES384"], "sd_alg_values": ["SHA-256"] }, "expect_claims": [ {"path": ["last_name"]}, - {"path": ["locality"]}, - {"path": ["region"]} + {"path": ["first_name"]}, + {"path": ["address", "street_address"]} ] } ] diff --git a/examples/query_lang/simple_mdoc.json b/examples/query_lang/simple_mdoc.json index fd767063..4263bd57 100644 --- a/examples/query_lang/simple_mdoc.json +++ b/examples/query_lang/simple_mdoc.json @@ -5,7 +5,7 @@ "format": "mso_mdoc", "expect_meta": { "doctype_values": ["org.iso.7367.1.mVR"], - "alg_values": [ "EdDSA" ], + "credential_signing_alg_values": [ "EdDSA" ], "hash_algorithm_values": [ "SHA-384"] }, "expect_claims": [ diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 634d91b3..48ebdd95 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -558,53 +558,92 @@ query against the Verifiable Credentials it holds and returns the Verifiable Presentations that match the query. A valid VP Query is defined as a JSON-encoded object with the following -properties: +top-level property: -`credentials`: -: REQUIRED. An object. Each key in the object represents one -Credential Query as defined in (#credential_query). The key is a string that -uniquely identifies the Credential Query within the VP Query. +`expect_credentials`: +: REQUIRED. An array of Credential Queries that specify the requested +Verifiable Credentials, as defined in (#credential_query). -`rules`: -: OPTIONAL. An object defining rules that specify which combinations of -credentials MAY be returned by the Wallet, as defined in (#credential_rules). If -omitted, all credentials listed in `credentials` are requested for presentation. +Note: While this specification does not define additional top-level properties, +future extensions MAY define additional properties that modify the behavior of +the Wallet when processing the query. ## Credential Query {#credential_query} A Credential Query is an object representing a request for one specific credential. It contains the following properties: +`group`: +: REQUIRED. A string identifying the credential in the response, or, if multiple +credentials carry the same group identifier, the group of credentials that the +requested credential belongs to. + `format`: : REQUIRED. A string that specifies the format of the requested Verifiable Credential. Valid Credential format identifier values are defined in Appendix A of [@!OpenID.VCI]. The value of this property MUST be one of the supported Credential formats as defined in the Wallet's metadata. -Format-specific properties (using the format value as a key): -: OPTIONAL. -Additional properties requested by the Verifier that are specific to the -Credential format, as defined in (#format_specific_properties). If omitted, -no format-specific restrictions are placed on the requested Credential. +`expect_meta`: +: OPTIONAL. An object defining additional properties requested by the Verifier that +apply to the metadata and validity data of the credential. The properties of +this object are defined per format in (#format_specific_properties). If omitted, +no specific restrictions are placed on the metadata or validity of the requested +Credential. -`claims`: +`expect_claims`: : OPTIONAL. An array that specifies the claims that the requested -Verifiable Credential must contain. Each entry in the array corresponds to at -least one claim that MUST be returned by the Wallet to fulfill the credential -request (unless specified otherwise by extensions to this specification). Each -entry MUST be one of the following objects: - -- Claim query: An object describing a single claim that is to be returned, as - specified in (#claim_query). -- An optionality rule: An object containing the following properties: - - `required` (REQUIRED): defines a number of claims that must be returned from - the `from` set of claims, as specified next. - - `from` (REQUIRED): An array; each entry is either a claim query or another - optionality rule. The entries are listed in order of preference, with the - first entry being the most preferred. - -More than two nested levels of optionality rules MUST NOT be used by a Verifier -or allowed by a Wallet. +Verifiable Credential must contain. Each entry in the array corresponds to exactly +one claim that is to be returned by the Wallet to fulfill the credential +request. + +`alternative_credentials`: +: OPTIONAL. An array of credential group identifiers that specify alternative +groups of credentials that MAY be returned instead of the credential. Any credential +in a group listed in `alternative_credentials` MUST NOT itself contain an +`alternative_credentials` property. + +Each entry MUST be an object with the following properties: + +`group`: +: OPTIONAL. A string identifying a group of claims for expressing alternatives +between claims. Multiple claims MAY have the same group identifier. The group +identifier for claims is not reflected in the response. + +`path`: +: REQUIRED if the credential format uses a JSON-based claims structure; MUST NOT +be present otherwise. The value MUST be a claims path pointer that specifies the path to the claim +within the Verifiable Credential, as defined in (#claims_path_pointer). + +`namespace`: +: REQUIRED if the credential format is based on ISO 18013-5; MUST NOT be present otherwise. +The value MUST be a string that specifies the namespace of the claim +within the Verifiable Credential, e.g., `org.iso.18013.5.1`. + +`claim_name`: +: REQUIRED if the credential format is based on ISO 18013-5; MUST NOT be present otherwise. +The value MUST be a string that specifies the name of the claim within the provided namespace +in the Verifiable Credential, e.g., `first_name`. + +`alternative_claims`: +: OPTIONAL. An array of claim group identifiers that specify alternative groups of claims +that MAY be returned instead of the claim specified by the `path` or `claim_name` property. Any +claim in a group listed in `alternatives` MUST NOT itself contain an `alternatives` property. + +### Semantics of `alternative_claims` and `alternative_credentials` + +By default, each element within `expect_credentials` or `expect_claims` MUST be returned, unless: + +- The element contains an `alternative_claims` or `alternative_credentials` + property and for at least one of the groups listed as an alternative, all + elements in the group can be returned. +- The element is part of a group that is itself listed as an alternative in + another element and returning the element is not needed to fulfill the + previous rule. + +Groups of claims are scoped to the specific credential; i.e., groups with the +same identifier that appear in separate Credential Query in `expect_credentials` +have no relation to each other. ## Format-specific Properties {#format_specific_properties} @@ -640,36 +679,8 @@ TBD TBD -## Claim Query {#claim_query} - -A claim query is an object that describes one or more claims that are to be -returned. Depending on the format of the requested Verifiable Credential, the -claim query can contain different properties. - - -### JSON-based Claims Structures {#json_based_claims} - -For credentials containing JSON-based claims structures, the following -properties are defined: - -`path`: -: REQUIRED. A claims path pointer that specifies the path to the claim -within the Verifiable Credential, as defined in (#claims_path_pointer). - -### ISO 18013-5 Credentials {#iso_18013-5} - -For ISO 18013-5 Credentials, the following properties are defined: - -`namespace`: -: REQUIRED. A string that specifies the namespace of the claim -within the Verifiable Credential, e.g., `org.iso.18013.5.1`. - -`claim_name`: -: REQUIRED. A string that specifies the name of the claim within the provided namespace -in the Verifiable Credential, e.g., `first_name`. - -### Claims Path Pointer {#claims_path_pointer} +## Claims Path Pointer {#claims_path_pointer} A claims path pointer is a pointer into the JSON structure of the Verifiable Credential, identifying one or more claims. A claims path pointer MUST be a @@ -689,7 +700,7 @@ is formed as follows: Verifiers MUST NOT point to the same claim more than once in a single query. Wallets SHOULD ignore such duplicate claim queries. -#### Example +### Example The following shows a non-normative, simplified example of a Credential: @@ -728,7 +739,7 @@ claims: - `["nationalities", 1]`: The second nationality is selected. - `[]` (empty array): The entire Credential is selected. -#### Processing +### Processing In detail, the array is processed by the Wallet from left to right as follows: @@ -753,23 +764,6 @@ In detail, the array is processed by the Wallet from left to right as follows: The result of the processing is the set of elements which is requested for presentation. -## Credential Rules {#credential_rules} - -Just as for claims, the Verifier can define rules that specify which -combinations of credentials MAY be returned by the Wallet. The rules are defined -in the top-level property `rules`. The values is a credential rule object, -defined as having the following properties: - -- `required`: An integer specifying the number of credentials that MUST be - returned from the `from` set of credentials. -- `from`: An array of objects, each being either - - a nested credential rule, or - - a credential query reference, i.e., an object with a single key `ref` that - references a credential query defined in the `credentials` object. - -Within `from`, the credentials are listed in order of preference, with the first -entry being the most preferred. - ## Examples {#vp_query_examples} The following is a non-normative example of a VP Query that requests a Verifiable @@ -781,17 +775,12 @@ Credential of the format `vc+sd-jwt` with a type value of Additional examples can be found in (#vp_query_examples). -## Additional Request Properties {#additional_request_properties} - -`intent_to_retain`: TBD - -`if_present`: TBD # Response {#response} A VP Token is only returned if the corresponding Authorization Request contained a `presentation_definition` parameter, a `presentation_definition_uri` parameter, or a `scope` parameter representing a Presentation Definition (#vp_token_request). -VP Token can be returned in the Authorization Response or the Token Response depending on the Response Type used. See (#response_type_vp_token) for more details. +A VP Token can be returned in the Authorization Response or the Token Response depending on the Response Type used. See (#response_type_vp_token) for more details. If the Response Type value is `vp_token`, the VP Token is returned in the Authorization Response. When the Response Type value is `vp_token id_token` and the `scope` parameter contains `openid`, the VP Token is returned in the Authorization Response alongside a Self-Issued ID Token as defined in [@!SIOPv2]. @@ -2233,6 +2222,7 @@ The following is a non-normative example of the payload of a Self-Issued ID Toke Note: The `nonce` and `aud` are set to the `nonce` of the request and the Client Identifier of the Verifier, respectively, in the same way as for the Verifier, Verifiable Presentations to prevent replay. + # Examples for VP Queries {#vp_query_examples} The following is a non-normative example of a VP Query that requests a Verifiable @@ -2241,12 +2231,12 @@ Credential in the format `mso_mdoc` with the claims `vehicle_holder` and <{{examples/query_lang/simple_mdoc.json}} -The following is a non-normative example of a VP Query that requests the claim `last_name` and +The following is a non-normative example of a VP Query that requests the claim `last_name`, `date_of_birth`, and `email` and - either the claim `postal_code`, or - the claims `locality` and `region`: -<{{examples/query_lang/nested_claim_queries.json}} +<{{examples/query_lang/claims_alternatives.json}} The following is a non-normative example of a VP Query that requests multiple Verifiable Credentials; all of them must be returned: @@ -2254,11 +2244,13 @@ Verifiable Credentials; all of them must be returned: <{{examples/query_lang/multi_credentials.json}} Finally, the following shows a complex query where the Wallet can either deliver -the first credential (containing all data the Verifier needs) or present two +the first credential (here called `pid`, containing all data the Verifier +needs), or a second credential (here called `other_pid`), or present two credentials that together contain all the data the Verifier needs: <{{examples/query_lang/credentials_alternatives.json}} + # IANA Considerations ## Response Types From 1263648eccf949ba76fa4192e0024055bcbf0c93 Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Wed, 11 Sep 2024 17:48:36 +0200 Subject: [PATCH 15/49] Add value matching --- .../query_lang/value_matching_simple.json | 25 +++++++++++++++++++ openid-4-verifiable-presentations-1_0.md | 20 +++++++++++++-- 2 files changed, 43 insertions(+), 2 deletions(-) create mode 100644 examples/query_lang/value_matching_simple.json diff --git a/examples/query_lang/value_matching_simple.json b/examples/query_lang/value_matching_simple.json new file mode 100644 index 00000000..f61f09ea --- /dev/null +++ b/examples/query_lang/value_matching_simple.json @@ -0,0 +1,25 @@ +{ + "expect_credentials": [ + { + "group": "my_credential", + "format": "vc+sd-jwt", + "expect_meta": { + "vct_values": [ "https://credentials.example.com/identity_credential" ], + "credential_signing_alg_values": ["ES256", "ES384"], + "sd_alg_values": ["SHA-256"] + }, + "expect_claims": [ + { + "path": ["last_name"], + "value": "Doe" + }, + {"path": ["first_name"]}, + {"path": ["address", "street_address"]}, + { + "path": ["postal_code"], + "values": ["90210", "90211"] + } + ] + } + ] +} \ No newline at end of file diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 48ebdd95..0a6ec076 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -625,9 +625,20 @@ within the Verifiable Credential, e.g., `org.iso.18013.5.1`. The value MUST be a string that specifies the name of the claim within the provided namespace in the Verifiable Credential, e.g., `first_name`. +`value`: +: OPTIONAL. A string, integer or boolean value that specifies the expected value of the claim. If the +`value` property is present, the Wallet MUST return the claim only if the type and value +of the claim match the type and value specified in the query. + +`values`: +: OPTIONAL. An array of strings, integers or boolean values that specifies the expected values of the claim. +If the `values` property is present, the Wallet MUST return the claim only if the +type and value of the claim both match for at least one of the elements in the array. + `alternative_claims`: : OPTIONAL. An array of claim group identifiers that specify alternative groups of claims -that MAY be returned instead of the claim specified by the `path` or `claim_name` property. Any +that MAY be returned instead of the claim specified by the `path` or `claim_name` property if +that claim is not present or does not match the restriction expressed by `value` or `values`. Any claim in a group listed in `alternatives` MUST NOT itself contain an `alternatives` property. ### Semantics of `alternative_claims` and `alternative_credentials` @@ -2243,13 +2254,18 @@ Verifiable Credentials; all of them must be returned: <{{examples/query_lang/multi_credentials.json}} -Finally, the following shows a complex query where the Wallet can either deliver +The following shows a complex query where the Wallet can either deliver the first credential (here called `pid`, containing all data the Verifier needs), or a second credential (here called `other_pid`), or present two credentials that together contain all the data the Verifier needs: <{{examples/query_lang/credentials_alternatives.json}} +The following example shows a query that uses the `value` and `values` restrictions +to request a credential with specific values for the `last_name` and `postal_code` claims: + +<{{examples/query_lang/value_matching_simple.json}} + # IANA Considerations From df46111609b83ab0fd86e86f55aaca44975a55d3 Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Thu, 12 Sep 2024 09:05:27 +0200 Subject: [PATCH 16/49] Apply suggestions from code review Co-authored-by: Timo Glastra --- examples/query_lang/multi_credentials.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/query_lang/multi_credentials.json b/examples/query_lang/multi_credentials.json index 32972d10..024d8839 100644 --- a/examples/query_lang/multi_credentials.json +++ b/examples/query_lang/multi_credentials.json @@ -16,7 +16,7 @@ "group": "mdl", "format": "mso_mdoc", "expect_meta": { - "doctype_values": "org.iso.7367.1.mVR", + "doctype_values": ["org.iso.7367.1.mVR"], "alg_values": [ "EdDSA" ], "hash_algorithm_values": [ "SHA-384"] }, From fc66dd1b3eebb384f434f82ba98b66d30721cb77 Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Thu, 12 Sep 2024 17:58:33 +0200 Subject: [PATCH 17/49] Add comments --- examples/query_lang/claims_alternatives.json | 3 +-- examples/query_lang/credentials_alternatives.json | 1 + 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/examples/query_lang/claims_alternatives.json b/examples/query_lang/claims_alternatives.json index 111c9f7b..079858b6 100644 --- a/examples/query_lang/claims_alternatives.json +++ b/examples/query_lang/claims_alternatives.json @@ -12,6 +12,7 @@ {"path": ["last_name"]}, { "path": ["postal_code"], + // alternatively, deliver the two claims in the group locality_and_region "alternative_claims": ["locality_and_region"] }, { @@ -23,11 +24,9 @@ "path": ["region"] }, { - "group": "age_verification", "path": ["date_of_birth"] }, { - "group": "newsletter", "path": ["email"] } ] diff --git a/examples/query_lang/credentials_alternatives.json b/examples/query_lang/credentials_alternatives.json index e9974b5a..07652cf8 100644 --- a/examples/query_lang/credentials_alternatives.json +++ b/examples/query_lang/credentials_alternatives.json @@ -11,6 +11,7 @@ {"path": ["family_name"]}, {"path": ["address", "street_address"]} ], + // alternatively, deliver other_pid or both credentials in pid_reduced "alternative_credentials": ["other_pid", "pid_reduced"] }, { From c2d3f9e2d90eb6a18a5e9d4b709b93edbb60a176 Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Wed, 18 Sep 2024 11:14:52 +0200 Subject: [PATCH 18/49] New proposal for QL --- examples/query_lang/claims_alternatives.json | 31 +++++++------------ .../query_lang/credentials_alternatives.json | 18 ++++++----- examples/query_lang/multi_credentials.json | 4 +-- examples/query_lang/simple.json | 2 +- examples/query_lang/simple_mdoc.json | 2 +- 5 files changed, 26 insertions(+), 31 deletions(-) diff --git a/examples/query_lang/claims_alternatives.json b/examples/query_lang/claims_alternatives.json index 079858b6..73b58367 100644 --- a/examples/query_lang/claims_alternatives.json +++ b/examples/query_lang/claims_alternatives.json @@ -9,26 +9,17 @@ "sd_alg_values": ["SHA-256"] }, "expect_claims": [ - {"path": ["last_name"]}, - { - "path": ["postal_code"], - // alternatively, deliver the two claims in the group locality_and_region - "alternative_claims": ["locality_and_region"] - }, - { - "group": "locality_and_region", - "path": ["locality"] - }, - { - "group": "locality_and_region", - "path": ["region"] - }, - { - "path": ["date_of_birth"] - }, - { - "path": ["email"] - } + {"id": "a", "path": ["last_name"]}, + {"id": "b", "path": ["postal_code"]}, + {"id": "c", "path": ["locality"]}, + {"id": "d", "path": ["region"]}, + {"id": "e", "path": ["date_of_birth"]}, + {"id": "f", "path": ["email"]} + ], + "valid_claim_sets": [ + // postal code or (locality and region), last_name, and date_of_birth are mandatory; email is optional + ["a", "c", "d", "e", "f?"], + ["a", "b", "e", "f?"] ] } ] diff --git a/examples/query_lang/credentials_alternatives.json b/examples/query_lang/credentials_alternatives.json index 07652cf8..df019a08 100644 --- a/examples/query_lang/credentials_alternatives.json +++ b/examples/query_lang/credentials_alternatives.json @@ -1,7 +1,7 @@ { "expect_credentials": [ { - "group": "pid", + "id": "pid", "format": "vc+sd-jwt", "expect_meta": { "vct_values": ["https://credentials.example.com/identity_credential"] @@ -10,12 +10,10 @@ {"path": ["given_name"]}, {"path": ["family_name"]}, {"path": ["address", "street_address"]} - ], - // alternatively, deliver other_pid or both credentials in pid_reduced - "alternative_credentials": ["other_pid", "pid_reduced"] + ] }, { - "group": "other_pid", + "id": "other_pid", "format": "vc+sd-jwt", "expect_meta": { "vct_values": ["https://othercredentials.example/pid"] @@ -27,7 +25,7 @@ ] }, { - "group": "pid_reduced", + "id": "pid_reduced_cred_1", "format": "vc+sd-jwt", "expect_meta": { "vct_values": ["https://credentials.example.com/reduced_identity_credential"] @@ -38,7 +36,7 @@ ] }, { - "group": "pid_reduced", + "id": "pid_reduced_cred_2", "format": "vc+sd-jwt", "expect_meta": { "vct_values": ["https://cred.example/residence_credential"] @@ -49,5 +47,11 @@ {"path": ["region"]} ] } + ], + "valid_credential_sets": [ + // deliver the pid, or the other_pid, or both pid_reduced_cred1 + 2 + ["pid"], + ["other_pid"], + ["pid_reduced_cred_1", "pid_reduced_cred_2"] ] } \ No newline at end of file diff --git a/examples/query_lang/multi_credentials.json b/examples/query_lang/multi_credentials.json index 024d8839..03cb05c5 100644 --- a/examples/query_lang/multi_credentials.json +++ b/examples/query_lang/multi_credentials.json @@ -1,7 +1,7 @@ { "expect_credentials": [ { - "group": "pid", + "id": "pid", "format": "vc+sd-jwt", "expect_meta": { "vct_values": ["https://credentials.example.com/identity_credential"] @@ -13,7 +13,7 @@ ] }, { - "group": "mdl", + "id": "mdl", "format": "mso_mdoc", "expect_meta": { "doctype_values": ["org.iso.7367.1.mVR"], diff --git a/examples/query_lang/simple.json b/examples/query_lang/simple.json index 6c3f482c..6b3bfdb9 100644 --- a/examples/query_lang/simple.json +++ b/examples/query_lang/simple.json @@ -1,7 +1,7 @@ { "expect_credentials": [ { - "group": "my_credential", + "id": "my_credential", "format": "vc+sd-jwt", "expect_meta": { "vct_values": [ "https://credentials.example.com/identity_credential" ], diff --git a/examples/query_lang/simple_mdoc.json b/examples/query_lang/simple_mdoc.json index 4263bd57..b89523f3 100644 --- a/examples/query_lang/simple_mdoc.json +++ b/examples/query_lang/simple_mdoc.json @@ -1,7 +1,7 @@ { "expect_credentials": [ { - "group": "my_credential", + "id": "my_credential", "format": "mso_mdoc", "expect_meta": { "doctype_values": ["org.iso.7367.1.mVR"], From 1b0c50401b6493a4dfacf9f57bbc388ea5fbe8d4 Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Wed, 18 Sep 2024 11:19:15 +0200 Subject: [PATCH 19/49] Improve comments --- examples/query_lang/claims_alternatives.json | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/examples/query_lang/claims_alternatives.json b/examples/query_lang/claims_alternatives.json index 73b58367..13f84351 100644 --- a/examples/query_lang/claims_alternatives.json +++ b/examples/query_lang/claims_alternatives.json @@ -8,18 +8,23 @@ "credential_signing_alg_values": ["ES256", "ES384"], "sd_alg_values": ["SHA-256"] }, - "expect_claims": [ - {"id": "a", "path": ["last_name"]}, + "expect_claims": [ // define claims, may add other properties like a purpose to each claims + { + "id": "a", // required for use in valid_claim_sets below; if that is omitted, the id is optional + "path": ["last_name"] + }, {"id": "b", "path": ["postal_code"]}, {"id": "c", "path": ["locality"]}, {"id": "d", "path": ["region"]}, {"id": "e", "path": ["date_of_birth"]}, {"id": "f", "path": ["email"]} ], - "valid_claim_sets": [ + "valid_claim_sets": [ // defines the rules // postal code or (locality and region), last_name, and date_of_birth are mandatory; email is optional ["a", "c", "d", "e", "f?"], - ["a", "b", "e", "f?"] + ["a", "b", "e", "f?"] + + // Note: the ? to mark a claim as optional is syntactical sugar; the rules could be rewritten without it, but that would require a lot of repetition ] } ] From c37d2e32e5272636a2c5f696adcaf29bb3e0624d Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Wed, 18 Sep 2024 11:21:20 +0200 Subject: [PATCH 20/49] Improve examples --- .../query_lang/credentials_alternatives.json | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/examples/query_lang/credentials_alternatives.json b/examples/query_lang/credentials_alternatives.json index df019a08..23d6529c 100644 --- a/examples/query_lang/credentials_alternatives.json +++ b/examples/query_lang/credentials_alternatives.json @@ -46,12 +46,22 @@ {"path": ["locality"]}, {"path": ["region"]} ] + }, + { + "id": "nice_to_have", + "format": "vc+sd-jwt", + "expect_meta": { + "vct_values": ["https://company.example/company_rewards"] + }, + "expect_claims": [ + {"path": ["rewards_number"]} + ] } ], "valid_credential_sets": [ - // deliver the pid, or the other_pid, or both pid_reduced_cred1 + 2 - ["pid"], - ["other_pid"], - ["pid_reduced_cred_1", "pid_reduced_cred_2"] + // deliver the pid, or the other_pid, or both pid_reduced_cred1 + 2; nice_to_have is optional in all cases + ["pid", "nice_to_have?"], + ["other_pid", "nice_to_have?"], + ["pid_reduced_cred_1", "pid_reduced_cred_2"], "nice_to_have?" ] } \ No newline at end of file From 90de9361fec3a754142fe9ded1afcadb90d97c12 Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Thu, 19 Sep 2024 21:43:26 +0200 Subject: [PATCH 21/49] Update text describing the mechanisms --- examples/query_lang/claims_alternatives.json | 5 +- .../query_lang/credentials_alternatives.json | 8 +- .../query_lang/value_matching_simple.json | 2 +- openid-4-verifiable-presentations-1_0.md | 119 +++++++++++------- 4 files changed, 81 insertions(+), 53 deletions(-) diff --git a/examples/query_lang/claims_alternatives.json b/examples/query_lang/claims_alternatives.json index 13f84351..6f418135 100644 --- a/examples/query_lang/claims_alternatives.json +++ b/examples/query_lang/claims_alternatives.json @@ -8,6 +8,7 @@ "credential_signing_alg_values": ["ES256", "ES384"], "sd_alg_values": ["SHA-256"] }, + // Comments in JSON to be removed before merging PR, they are just here to make Brian less sad "expect_claims": [ // define claims, may add other properties like a purpose to each claims { "id": "a", // required for use in valid_claim_sets below; if that is omitted, the id is optional @@ -21,8 +22,8 @@ ], "valid_claim_sets": [ // defines the rules // postal code or (locality and region), last_name, and date_of_birth are mandatory; email is optional - ["a", "c", "d", "e", "f?"], - ["a", "b", "e", "f?"] + ["a", "b", "e", "f?"], + ["a", "c", "d", "e", "f?"] // Note: the ? to mark a claim as optional is syntactical sugar; the rules could be rewritten without it, but that would require a lot of repetition ] diff --git a/examples/query_lang/credentials_alternatives.json b/examples/query_lang/credentials_alternatives.json index 23d6529c..ff30b644 100644 --- a/examples/query_lang/credentials_alternatives.json +++ b/examples/query_lang/credentials_alternatives.json @@ -54,7 +54,11 @@ "vct_values": ["https://company.example/company_rewards"] }, "expect_claims": [ - {"path": ["rewards_number"]} + {"id": "current", "path": ["rewards_number"]}, + {"id": "legacy", "path": ["legacy_system_rewards_number"]} + ], + "valid_claim_sets": [ + ["current", "legacy?"] ] } ], @@ -62,6 +66,6 @@ // deliver the pid, or the other_pid, or both pid_reduced_cred1 + 2; nice_to_have is optional in all cases ["pid", "nice_to_have?"], ["other_pid", "nice_to_have?"], - ["pid_reduced_cred_1", "pid_reduced_cred_2"], "nice_to_have?" + ["pid_reduced_cred_1", "pid_reduced_cred_2", "nice_to_have?"] ] } \ No newline at end of file diff --git a/examples/query_lang/value_matching_simple.json b/examples/query_lang/value_matching_simple.json index f61f09ea..0eb89800 100644 --- a/examples/query_lang/value_matching_simple.json +++ b/examples/query_lang/value_matching_simple.json @@ -1,7 +1,7 @@ { "expect_credentials": [ { - "group": "my_credential", + "id": "my_credential", "format": "vc+sd-jwt", "expect_meta": { "vct_values": [ "https://credentials.example.com/identity_credential" ], diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index b52d8b35..760a4db5 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -559,17 +559,24 @@ If the Verifier responds with any HTTP error response, the Wallet MUST terminate The Verifiable Presentation Query Language (VP Query) is a JSON-encoded query language that allows the Verifier to request the Wallet to present Verifiable -Credentials that match the query. The query consists of a set of constraints -that the requested Verifiable Credentials must satisfy. The Wallet evaluates the +Credentials that match the query. The Verifier MAY encode constraints on the +combinations of credentials and claims that may be returned. The Wallet evaluates the query against the Verifiable Credentials it holds and returns the Verifiable Presentations that match the query. A valid VP Query is defined as a JSON-encoded object with the following -top-level property: +top-level properties: `expect_credentials`: -: REQUIRED. An array of Credential Queries that specify the requested -Verifiable Credentials, as defined in (#credential_query). +: REQUIRED. A non-empty array of Credential Queries as defined in (#credential_query) +that specify the requested Verifiable Credentials. + +`valid_credential_sets`: +: OPTIONAL. A non-empty array containing arrays of identifiers for elements in +`expect_credentials` that defines which sets of Credentials may be returned. +The identifier MAY be postfixed by `?`, indicating that +delivery of the the respective credential is optional. For details, see +(#vp_query_lang_processing_rules). Note: While this specification does not define additional top-level properties, future extensions MAY define additional properties that modify the behavior of @@ -578,12 +585,13 @@ the Wallet when processing the query. ## Credential Query {#credential_query} A Credential Query is an object representing a request for one specific -credential. It contains the following properties: +credential. + +It contains the following properties: -`group`: -: REQUIRED. A string identifying the credential in the response, or, if multiple -credentials carry the same group identifier, the group of credentials that the -requested credential belongs to. +`id`: +: REQUIRED. A string identifying the credential in the response and, if provided, +the constraints in `valid_credential_sets`. `format`: : REQUIRED. A string that specifies the format of the requested @@ -599,23 +607,24 @@ no specific restrictions are placed on the metadata or validity of the requested Credential. `expect_claims`: -: OPTIONAL. An array that specifies the claims that the requested -Verifiable Credential must contain. Each entry in the array corresponds to exactly -one claim that is to be returned by the Wallet to fulfill the credential -request. +: OPTIONAL. A non-empty array of objects as defined in (#claims_query) that specifies +claims in the requested Credentials. + +`valid_claim_sets`: +: OPTIONAL. A non-empty array containing arrays of identifiers for elements in +`expect_claims`. The identifier MAY be postfixed by `?`, indicating that +delivery of the the respective claim is OPTIONAL. -`alternative_credentials`: -: OPTIONAL. An array of credential group identifiers that specify alternative -groups of credentials that MAY be returned instead of the credential. Any credential -in a group listed in `alternative_credentials` MUST NOT itself contain an -`alternative_credentials` property. +## Claims Query {#claims_query} -Each entry MUST be an object with the following properties: +Each entry in `expect_claims` MUST be an object with the following properties: -`group`: -: OPTIONAL. A string identifying a group of claims for expressing alternatives -between claims. Multiple claims MAY have the same group identifier. The group -identifier for claims is not reflected in the response. +`id`: +: REQUIRED if `valid_claim_sets` is present; OPTIONAL otherwise. A string +identifying the particular claim. The value MUST be a non-empty string +consisting of alphanumeric, underscore (`_`) or hyphen (`-`) characters. +Within the particular `expected_claims` array, the same `id` MUST NOT +be present more than once. `path`: : REQUIRED if the credential format uses a JSON-based claims structure; MUST NOT @@ -642,26 +651,40 @@ of the claim match the type and value specified in the query. If the `values` property is present, the Wallet MUST return the claim only if the type and value of the claim both match for at least one of the elements in the array. -`alternative_claims`: -: OPTIONAL. An array of claim group identifiers that specify alternative groups of claims -that MAY be returned instead of the claim specified by the `path` or `claim_name` property if -that claim is not present or does not match the restriction expressed by `value` or `values`. Any -claim in a group listed in `alternatives` MUST NOT itself contain an `alternatives` property. +### Selecting Claims and Credentials {#vp_query_lang_processing_rules} + +The same basic logic applies for selecting claims and for selecting credentials, as detailed in the following. + +#### Selecting Claims + +The following rules apply for selecting claims via `expect_claims` and `valid_claim_sets`: + +- If `expect_claims` is not provided, the Verifier expects all claims existing + in the Credential to be returned. +- If `expect_claims` is provided, but `valid_claim_sets` is not provided, + the Verifier expects all claims in `expect_claims` to be returned. +- Otherwise, the Verifier expects one combination of the claims listed in + `valid_claim_sets`, with optional claims marked by the postfix `?`. + +If the Wallet cannot fulfill the request by the Verifier, it MUST NOT +return the respective credential. + +#### Selecting Credentials + +The following rules apply for selecting credentials via `expect_credentials` and `valid_credential_sets`: -### Semantics of `alternative_claims` and `alternative_credentials` +- If `valid_credential_sets` is not provided, the Verifier expects all + credentials in `expect_credentials` to be returned. +- Otherwise, the Verifier expects one combination of the credentials + listed in `valid_credential_sets`, with optional credentials marked by the postfix `?`. -By default, each element within `expect_credentials` or `expect_claims` MUST be returned, unless: +Credentials not matching the respective restrictions expressed within +`expect_credentials` MUST NOT be returned, i.e., they are treated as if +they would not exist in the Wallet. -- The element contains an `alternative_claims` or `alternative_credentials` - property and for at least one of the groups listed as an alternative, all - elements in the group can be returned. -- The element is part of a group that is itself listed as an alternative in - another element and returning the element is not needed to fulfill the - previous rule. +If the Wallet cannot fulfill the request by the Verifier, it MUST NOT +return any credential. -Groups of claims are scoped to the specific credential; i.e., groups with the -same identifier that appear in separate Credential Query in `expect_credentials` -have no relation to each other. ## Format-specific Properties {#format_specific_properties} @@ -791,7 +814,7 @@ Credential of the format `vc+sd-jwt` with a type value of <{{examples/query_lang/simple.json}} -Additional examples can be found in (#vp_query_examples). +Additional, more complex examples can be found in (#vp_query_examples). # Response {#response} @@ -2272,10 +2295,11 @@ Credential in the format `mso_mdoc` with the claims `vehicle_holder` and <{{examples/query_lang/simple_mdoc.json}} -The following is a non-normative example of a VP Query that requests the claim `last_name`, `date_of_birth`, and `email` and +The following is a non-normative example of a VP Query that requests -- either the claim `postal_code`, or -- the claims `locality` and `region`: +- the mandatory claims `last_name` and `date_of_birth`, and +- either the claim `postal_code`, or both of the the claims `locality` and `region`, and +- optionally the claim `email`. <{{examples/query_lang/claims_alternatives.json}} @@ -2284,10 +2308,9 @@ Verifiable Credentials; all of them must be returned: <{{examples/query_lang/multi_credentials.json}} -The following shows a complex query where the Wallet can either deliver -the first credential (here called `pid`, containing all data the Verifier -needs), or a second credential (here called `other_pid`), or present two -credentials that together contain all the data the Verifier needs: +The following shows a complex query where the Wallet is requested to deliver the `pid` credential, or the `other_pid` credential, or both `pid_reduced_cred_1` and `pid_reduced_cred_2`. Additionally, the `nice_to_have` credential may optionally be +delivered. From the latter, the claim `legacy_system_rewards_number` may optionally +be delivered. <{{examples/query_lang/credentials_alternatives.json}} From 12f34a08b4403affd559a58689e4b17e82d89c47 Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Mon, 23 Sep 2024 11:40:03 +0200 Subject: [PATCH 22/49] Apply suggestions from Paul's review Co-authored-by: Paul Bastian --- openid-4-verifiable-presentations-1_0.md | 42 ++++++++++++------------ 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 760a4db5..fb8eac2b 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -560,7 +560,7 @@ If the Verifier responds with any HTTP error response, the Wallet MUST terminate The Verifiable Presentation Query Language (VP Query) is a JSON-encoded query language that allows the Verifier to request the Wallet to present Verifiable Credentials that match the query. The Verifier MAY encode constraints on the -combinations of credentials and claims that may be returned. The Wallet evaluates the +combinations of credentials and claims that are requested. The Wallet evaluates the query against the Verifiable Credentials it holds and returns the Verifiable Presentations that match the query. @@ -572,10 +572,10 @@ top-level properties: that specify the requested Verifiable Credentials. `valid_credential_sets`: -: OPTIONAL. A non-empty array containing arrays of identifiers for elements in +: OPTIONAL. A non-empty array containing arrays of identifiers for Credential Queries defined in `expect_credentials` that defines which sets of Credentials may be returned. The identifier MAY be postfixed by `?`, indicating that -delivery of the the respective credential is optional. For details, see +delivery of the the respective Credential is optional. For details, see (#vp_query_lang_processing_rules). Note: While this specification does not define additional top-level properties, @@ -585,24 +585,24 @@ the Wallet when processing the query. ## Credential Query {#credential_query} A Credential Query is an object representing a request for one specific -credential. +Credential. It contains the following properties: `id`: -: REQUIRED. A string identifying the credential in the response and, if provided, +: REQUIRED. A string identifying the Credential in the response and, if provided, the constraints in `valid_credential_sets`. `format`: : REQUIRED. A string that specifies the format of the requested -Verifiable Credential. Valid Credential format identifier values are defined in +Verifiable Credential. Valid Credential Format Identifier values are defined in Appendix A of [@!OpenID.VCI]. The value of this property MUST be one of the -supported Credential formats as defined in the Wallet's metadata. +supported Credential Formats as defined in the Wallet's metadata. `expect_meta`: : OPTIONAL. An object defining additional properties requested by the Verifier that -apply to the metadata and validity data of the credential. The properties of -this object are defined per format in (#format_specific_properties). If omitted, +apply to the metadata and validity data of the Credential. The properties of +this object are defined per Credential Format in (#format_specific_properties). If omitted, no specific restrictions are placed on the metadata or validity of the requested Credential. @@ -627,17 +627,17 @@ Within the particular `expected_claims` array, the same `id` MUST NOT be present more than once. `path`: -: REQUIRED if the credential format uses a JSON-based claims structure; MUST NOT +: REQUIRED if the Credential Format uses a JSON-based claims structure; MUST NOT be present otherwise. The value MUST be a claims path pointer that specifies the path to the claim within the Verifiable Credential, as defined in (#claims_path_pointer). `namespace`: -: REQUIRED if the credential format is based on ISO 18013-5; MUST NOT be present otherwise. +: REQUIRED if the Credential Format is based on mdoc format defined in ISO 18013-5; MUST NOT be present otherwise. The value MUST be a string that specifies the namespace of the claim within the Verifiable Credential, e.g., `org.iso.18013.5.1`. `claim_name`: -: REQUIRED if the credential format is based on ISO 18013-5; MUST NOT be present otherwise. +: REQUIRED if the Credential Format is based on mdoc format defined in ISO 18013-5; MUST NOT be present otherwise. The value MUST be a string that specifies the name of the claim within the provided namespace in the Verifiable Credential, e.g., `first_name`. @@ -667,15 +667,15 @@ The following rules apply for selecting claims via `expect_claims` and `valid_cl `valid_claim_sets`, with optional claims marked by the postfix `?`. If the Wallet cannot fulfill the request by the Verifier, it MUST NOT -return the respective credential. +return the respective Credential. #### Selecting Credentials -The following rules apply for selecting credentials via `expect_credentials` and `valid_credential_sets`: +The following rules apply for selecting Credentials via `expect_credentials` and `valid_credential_sets`: - If `valid_credential_sets` is not provided, the Verifier expects all - credentials in `expect_credentials` to be returned. -- Otherwise, the Verifier expects one combination of the credentials + Credentials in `expect_credentials` to be returned. +- Otherwise, the Verifier expects one combination of the Credentials listed in `valid_credential_sets`, with optional credentials marked by the postfix `?`. Credentials not matching the respective restrictions expressed within @@ -725,10 +725,10 @@ TBD A claims path pointer is a pointer into the JSON structure of the Verifiable Credential, identifying one or more claims. A claims path pointer MUST be a -non-empty array of strings and non-negative integers. A `*` string value indicates -that all elements of the currently selected array(s) are to be selected; any other -string indicates that the respective key is to be selected; and a non-negative -integer indicates that the respective index in an array is to be selected. The path +non-empty array of strings and non-negative integers. A string value +indicates that the respective key is to be selected, the special string value `*` +indicates that all elements of the currently selected array(s) are to be selected; +and a non-negative integer indicates that the respective index in an array is to be selected. The path is formed as follows: - Start with an empty array. @@ -784,7 +784,7 @@ claims: In detail, the array is processed by the Wallet from left to right as follows: - 1. Select the root element of the credential, i.e., the top-level JSON object. + 1. Select the root element of the Credential, i.e., the top-level JSON object. 2. Process the query components from left to right: 1. If the query component is a string, select the element in the respective key in the currently selected element(s). If any of the currently From 88515896a2fd3e99eb0b141f20505685c69c5392 Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Mon, 23 Sep 2024 11:49:32 +0200 Subject: [PATCH 23/49] Address Paul's comments --- openid-4-verifiable-presentations-1_0.md | 29 +++++++++++++----------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index fb8eac2b..f679dc60 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -591,7 +591,10 @@ It contains the following properties: `id`: : REQUIRED. A string identifying the Credential in the response and, if provided, -the constraints in `valid_credential_sets`. +the constraints in `valid_credential_sets`. The value MUST be a non-empty string +consisting of alphanumeric, underscore (`_`) or hyphen (`-`) characters. +Within the Authorization Request, the same `id` MUST NOT +be present more than once. `format`: : REQUIRED. A string that specifies the format of the requested @@ -603,7 +606,7 @@ supported Credential Formats as defined in the Wallet's metadata. : OPTIONAL. An object defining additional properties requested by the Verifier that apply to the metadata and validity data of the Credential. The properties of this object are defined per Credential Format in (#format_specific_properties). If omitted, -no specific restrictions are placed on the metadata or validity of the requested +no specific constraints are placed on the metadata or validity of the requested Credential. `expect_claims`: @@ -659,14 +662,14 @@ The same basic logic applies for selecting claims and for selecting credentials, The following rules apply for selecting claims via `expect_claims` and `valid_claim_sets`: -- If `expect_claims` is not provided, the Verifier expects all claims existing - in the Credential to be returned. +- If `expect_claims` is not provided, the Verifier requests all claims existing + in the Credential. - If `expect_claims` is provided, but `valid_claim_sets` is not provided, - the Verifier expects all claims in `expect_claims` to be returned. -- Otherwise, the Verifier expects one combination of the claims listed in + the Verifier requests all claims listed in `expect_claims`. +- Otherwise, the Verifier requests one combination of the claims listed in `valid_claim_sets`, with optional claims marked by the postfix `?`. -If the Wallet cannot fulfill the request by the Verifier, it MUST NOT +If the Wallet cannot deliver all claims requested by the Verifier according to these rules, it MUST NOT return the respective Credential. #### Selecting Credentials @@ -678,7 +681,7 @@ The following rules apply for selecting Credentials via `expect_credentials` and - Otherwise, the Verifier expects one combination of the Credentials listed in `valid_credential_sets`, with optional credentials marked by the postfix `?`. -Credentials not matching the respective restrictions expressed within +Credentials not matching the respective constraints expressed within `expect_credentials` MUST NOT be returned, i.e., they are treated as if they would not exist in the Wallet. @@ -785,16 +788,16 @@ claims: In detail, the array is processed by the Wallet from left to right as follows: 1. Select the root element of the Credential, i.e., the top-level JSON object. - 2. Process the query components from left to right: - 1. If the query component is a string, select the element in the respective + 2. Process the query of the claims path query array from left to right: + 1. If the component is a string, select the element in the respective key in the currently selected element(s). If any of the currently selected element(s) is not an object, abort processing and return an error. If the key does not exist in any element currently selected, remove that element from the selection. - 2. If the query component is `*`, select all elements of the currently + 2. If the component is `*`, select all elements of the currently selected array(s). If any of the currently selected element(s) is not an array, abort processing and return an error. - 3. If the query component is a non-negative integer, select the element at + 3. If the component is a non-negative integer, select the element at the respective index in the currently selected array(s). If any of the currently selected element(s) is not an array, abort processing and return an error. If the index does not exist in a selected array, remove @@ -2314,7 +2317,7 @@ be delivered. <{{examples/query_lang/credentials_alternatives.json}} -The following example shows a query that uses the `value` and `values` restrictions +The following example shows a query that uses the `value` and `values` constraints to request a credential with specific values for the `last_name` and `postal_code` claims: <{{examples/query_lang/value_matching_simple.json}} From c7dacb981da90c669ce13803cd675f58034ca3a2 Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Mon, 23 Sep 2024 11:52:28 +0200 Subject: [PATCH 24/49] Clarify returning credentials --- 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 f679dc60..cb381544 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -669,23 +669,23 @@ The following rules apply for selecting claims via `expect_claims` and `valid_cl - Otherwise, the Verifier requests one combination of the claims listed in `valid_claim_sets`, with optional claims marked by the postfix `?`. -If the Wallet cannot deliver all claims requested by the Verifier according to these rules, it MUST NOT +If the Wallet cannot deliver all non-optional claims requested by the Verifier according to these rules, it MUST NOT return the respective Credential. #### Selecting Credentials The following rules apply for selecting Credentials via `expect_credentials` and `valid_credential_sets`: -- If `valid_credential_sets` is not provided, the Verifier expects all +- If `valid_credential_sets` is not provided, the Verifier requests all Credentials in `expect_credentials` to be returned. -- Otherwise, the Verifier expects one combination of the Credentials +- Otherwise, the Verifier requests one combination of the Credentials listed in `valid_credential_sets`, with optional credentials marked by the postfix `?`. Credentials not matching the respective constraints expressed within `expect_credentials` MUST NOT be returned, i.e., they are treated as if they would not exist in the Wallet. -If the Wallet cannot fulfill the request by the Verifier, it MUST NOT +If the Wallet cannot deliver all non-optional Credentials requested by the Verifier according to these rules, it MUST NOT return any credential. From da8a5041ef9087f0e64d1c5a463c0d7c09915089 Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Tue, 8 Oct 2024 15:41:05 +0200 Subject: [PATCH 25/49] Apply suggestions from code review Co-authored-by: Tobias Looker --- 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 51bdb4f6..917a1f8f 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -696,7 +696,7 @@ Credentials not matching the respective constraints expressed within they would not exist in the Wallet. If the Wallet cannot deliver all non-optional Credentials requested by the Verifier according to these rules, it MUST NOT -return any credential. +return any credential(s). ## Format-specific Properties {#format_specific_properties} From f41152509bc2fa02efb9ce866864c6c5c96d0619 Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Wed, 9 Oct 2024 08:55:35 +0200 Subject: [PATCH 26/49] Drop expect_ and valid_ prefixes, remove algorithm matching --- examples/query_lang/claims_alternatives.json | 14 ++-- .../query_lang/credentials_alternatives.json | 26 +++---- examples/query_lang/multi_credentials.json | 14 ++-- examples/query_lang/simple.json | 10 ++- examples/query_lang/simple_mdoc.json | 10 ++- .../query_lang/value_matching_simple.json | 10 ++- openid-4-verifiable-presentations-1_0.md | 67 ++++++++----------- 7 files changed, 65 insertions(+), 86 deletions(-) diff --git a/examples/query_lang/claims_alternatives.json b/examples/query_lang/claims_alternatives.json index 6f418135..84ea5978 100644 --- a/examples/query_lang/claims_alternatives.json +++ b/examples/query_lang/claims_alternatives.json @@ -1,17 +1,15 @@ { - "expect_credentials": [ + "credentials": [ { "group": "pid", "format": "vc+sd-jwt", - "expect_meta": { - "vct_values": [ "https://credentials.example.com/identity_credential" ], - "credential_signing_alg_values": ["ES256", "ES384"], - "sd_alg_values": ["SHA-256"] + "meta": { + "vct_values": [ "https://credentials.example.com/identity_credential" ] }, // Comments in JSON to be removed before merging PR, they are just here to make Brian less sad - "expect_claims": [ // define claims, may add other properties like a purpose to each claims + "claims": [ // define claims, may add other properties like a purpose to each claims { - "id": "a", // required for use in valid_claim_sets below; if that is omitted, the id is optional + "id": "a", // required for use in claim_sets below; if that is omitted, the id is optional "path": ["last_name"] }, {"id": "b", "path": ["postal_code"]}, @@ -20,7 +18,7 @@ {"id": "e", "path": ["date_of_birth"]}, {"id": "f", "path": ["email"]} ], - "valid_claim_sets": [ // defines the rules + "claim_sets": [ // defines the rules // postal code or (locality and region), last_name, and date_of_birth are mandatory; email is optional ["a", "b", "e", "f?"], ["a", "c", "d", "e", "f?"] diff --git a/examples/query_lang/credentials_alternatives.json b/examples/query_lang/credentials_alternatives.json index ff30b644..0e08ce8d 100644 --- a/examples/query_lang/credentials_alternatives.json +++ b/examples/query_lang/credentials_alternatives.json @@ -1,12 +1,12 @@ { - "expect_credentials": [ + "credentials": [ { "id": "pid", "format": "vc+sd-jwt", - "expect_meta": { + "meta": { "vct_values": ["https://credentials.example.com/identity_credential"] }, - "expect_claims": [ + "claims": [ {"path": ["given_name"]}, {"path": ["family_name"]}, {"path": ["address", "street_address"]} @@ -15,10 +15,10 @@ { "id": "other_pid", "format": "vc+sd-jwt", - "expect_meta": { + "meta": { "vct_values": ["https://othercredentials.example/pid"] }, - "expect_claims": [ + "claims": [ {"path": ["given_name"]}, {"path": ["family_name"]}, {"path": ["address", "street_address"]} @@ -27,10 +27,10 @@ { "id": "pid_reduced_cred_1", "format": "vc+sd-jwt", - "expect_meta": { + "meta": { "vct_values": ["https://credentials.example.com/reduced_identity_credential"] }, - "expect_claims": [ + "claims": [ {"path": ["family_name"]}, {"path": ["given_name"]} ] @@ -38,10 +38,10 @@ { "id": "pid_reduced_cred_2", "format": "vc+sd-jwt", - "expect_meta": { + "meta": { "vct_values": ["https://cred.example/residence_credential"] }, - "expect_claims": [ + "claims": [ {"path": ["postal_code"]}, {"path": ["locality"]}, {"path": ["region"]} @@ -50,19 +50,19 @@ { "id": "nice_to_have", "format": "vc+sd-jwt", - "expect_meta": { + "meta": { "vct_values": ["https://company.example/company_rewards"] }, - "expect_claims": [ + "claims": [ {"id": "current", "path": ["rewards_number"]}, {"id": "legacy", "path": ["legacy_system_rewards_number"]} ], - "valid_claim_sets": [ + "claim_sets": [ ["current", "legacy?"] ] } ], - "valid_credential_sets": [ + "credential_sets": [ // deliver the pid, or the other_pid, or both pid_reduced_cred1 + 2; nice_to_have is optional in all cases ["pid", "nice_to_have?"], ["other_pid", "nice_to_have?"], diff --git a/examples/query_lang/multi_credentials.json b/examples/query_lang/multi_credentials.json index 03cb05c5..1a59e594 100644 --- a/examples/query_lang/multi_credentials.json +++ b/examples/query_lang/multi_credentials.json @@ -1,12 +1,12 @@ { - "expect_credentials": [ + "credentials": [ { "id": "pid", "format": "vc+sd-jwt", - "expect_meta": { + "meta": { "vct_values": ["https://credentials.example.com/identity_credential"] }, - "expect_claims": [ + "claims": [ {"path": ["given_name"]}, {"path": ["family_name"]}, {"path": ["address", "street_address"]} @@ -15,12 +15,10 @@ { "id": "mdl", "format": "mso_mdoc", - "expect_meta": { - "doctype_values": ["org.iso.7367.1.mVR"], - "alg_values": [ "EdDSA" ], - "hash_algorithm_values": [ "SHA-384"] + "meta": { + "doctype_values": ["org.iso.7367.1.mVR"] }, - "expect_claims": [ + "claims": [ { "namespace": "org.iso.7367.1", "claim_name": "vehicle_holder" diff --git a/examples/query_lang/simple.json b/examples/query_lang/simple.json index 6b3bfdb9..8c0a00e7 100644 --- a/examples/query_lang/simple.json +++ b/examples/query_lang/simple.json @@ -1,14 +1,12 @@ { - "expect_credentials": [ + "credentials": [ { "id": "my_credential", "format": "vc+sd-jwt", - "expect_meta": { - "vct_values": [ "https://credentials.example.com/identity_credential" ], - "credential_signing_alg_values": ["ES256", "ES384"], - "sd_alg_values": ["SHA-256"] + "meta": { + "vct_values": [ "https://credentials.example.com/identity_credential" ] }, - "expect_claims": [ + "claims": [ {"path": ["last_name"]}, {"path": ["first_name"]}, {"path": ["address", "street_address"]} diff --git a/examples/query_lang/simple_mdoc.json b/examples/query_lang/simple_mdoc.json index b89523f3..ed74f3f0 100644 --- a/examples/query_lang/simple_mdoc.json +++ b/examples/query_lang/simple_mdoc.json @@ -1,14 +1,12 @@ { - "expect_credentials": [ + "credentials": [ { "id": "my_credential", "format": "mso_mdoc", - "expect_meta": { - "doctype_values": ["org.iso.7367.1.mVR"], - "credential_signing_alg_values": [ "EdDSA" ], - "hash_algorithm_values": [ "SHA-384"] + "meta": { + "doctype_values": ["org.iso.7367.1.mVR"] }, - "expect_claims": [ + "claims": [ { "namespace": "org.iso.7367.1", "claim_name": "vehicle_holder" diff --git a/examples/query_lang/value_matching_simple.json b/examples/query_lang/value_matching_simple.json index 0eb89800..b57b7900 100644 --- a/examples/query_lang/value_matching_simple.json +++ b/examples/query_lang/value_matching_simple.json @@ -1,14 +1,12 @@ { - "expect_credentials": [ + "credentials": [ { "id": "my_credential", "format": "vc+sd-jwt", - "expect_meta": { - "vct_values": [ "https://credentials.example.com/identity_credential" ], - "credential_signing_alg_values": ["ES256", "ES384"], - "sd_alg_values": ["SHA-256"] + "meta": { + "vct_values": [ "https://credentials.example.com/identity_credential" ] }, - "expect_claims": [ + "claims": [ { "path": ["last_name"], "value": "Doe" diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 65957fe5..8bd68ab6 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -613,15 +613,15 @@ Presentations that match the query. A valid VP Query is defined as a JSON-encoded object with the following top-level properties: -`expect_credentials`: +`credentials`: : REQUIRED. A non-empty array of Credential Queries as defined in (#credential_query) that specify the requested Verifiable Credentials. -`valid_credential_sets`: +`credential_sets`: : OPTIONAL. A non-empty array containing arrays of identifiers for Credential Queries defined in -`expect_credentials` that defines which sets of Credentials may be returned. +`credentials` that defines which sets of Credentials may be returned. The identifier MAY be postfixed by `?`, indicating that -delivery of the the respective Credential is optional. For details, see +delivery of the respective Credential is optional. For details, see (#vp_query_lang_processing_rules). Note: While this specification does not define additional top-level properties, @@ -637,7 +637,7 @@ It contains the following properties: `id`: : REQUIRED. A string identifying the Credential in the response and, if provided, -the constraints in `valid_credential_sets`. The value MUST be a non-empty string +the constraints in `credential_sets`. The value MUST be a non-empty string consisting of alphanumeric, underscore (`_`) or hyphen (`-`) characters. Within the Authorization Request, the same `id` MUST NOT be present more than once. @@ -645,31 +645,30 @@ be present more than once. `format`: : REQUIRED. A string that specifies the format of the requested Verifiable Credential. Valid Credential Format Identifier values are defined in -Appendix A of [@!OpenID.VCI]. The value of this property MUST be one of the -supported Credential Formats as defined in the Wallet's metadata. +Appendix A of [@!OpenID.VCI]. -`expect_meta`: +`meta`: : OPTIONAL. An object defining additional properties requested by the Verifier that apply to the metadata and validity data of the Credential. The properties of this object are defined per Credential Format in (#format_specific_properties). If omitted, no specific constraints are placed on the metadata or validity of the requested Credential. -`expect_claims`: +`claims`: : OPTIONAL. A non-empty array of objects as defined in (#claims_query) that specifies claims in the requested Credentials. -`valid_claim_sets`: +`claim_sets`: : OPTIONAL. A non-empty array containing arrays of identifiers for elements in -`expect_claims`. The identifier MAY be postfixed by `?`, indicating that +`claims`. The identifier MAY be postfixed by `?`, indicating that delivery of the the respective claim is OPTIONAL. ## Claims Query {#claims_query} -Each entry in `expect_claims` MUST be an object with the following properties: +Each entry in `claims` MUST be an object with the following properties: `id`: -: REQUIRED if `valid_claim_sets` is present; OPTIONAL otherwise. A string +: REQUIRED if `claim_sets` is present; OPTIONAL otherwise. A string identifying the particular claim. The value MUST be a non-empty string consisting of alphanumeric, underscore (`_`) or hyphen (`-`) characters. Within the particular `expected_claims` array, the same `id` MUST NOT @@ -693,12 +692,12 @@ in the Verifiable Credential, e.g., `first_name`. `value`: : OPTIONAL. A string, integer or boolean value that specifies the expected value of the claim. If the `value` property is present, the Wallet MUST return the claim only if the type and value -of the claim match the type and value specified in the query. +of the claim match the type and value specified in the query. This property MUST NOT be present if the `values` property is present. `values`: : OPTIONAL. An array of strings, integers or boolean values that specifies the expected values of the claim. If the `values` property is present, the Wallet MUST return the claim only if the -type and value of the claim both match for at least one of the elements in the array. +type and value of the claim both match for at least one of the elements in the array. This property MUST NOT be present if the `value` property is present. ### Selecting Claims and Credentials {#vp_query_lang_processing_rules} @@ -706,29 +705,29 @@ The same basic logic applies for selecting claims and for selecting credentials, #### Selecting Claims -The following rules apply for selecting claims via `expect_claims` and `valid_claim_sets`: +The following rules apply for selecting claims via `claims` and `claim_sets`: -- If `expect_claims` is not provided, the Verifier requests all claims existing +- If `claims` is not provided, the Verifier requests all claims existing in the Credential. -- If `expect_claims` is provided, but `valid_claim_sets` is not provided, - the Verifier requests all claims listed in `expect_claims`. +- If `claims` is provided, but `claim_sets` is not provided, + the Verifier requests all claims listed in `claims`. - Otherwise, the Verifier requests one combination of the claims listed in - `valid_claim_sets`, with optional claims marked by the postfix `?`. + `claim_sets`, with optional claims marked by the postfix `?`. If the Wallet cannot deliver all non-optional claims requested by the Verifier according to these rules, it MUST NOT return the respective Credential. #### Selecting Credentials -The following rules apply for selecting Credentials via `expect_credentials` and `valid_credential_sets`: +The following rules apply for selecting Credentials via `credentials` and `credential_sets`: -- If `valid_credential_sets` is not provided, the Verifier requests all - Credentials in `expect_credentials` to be returned. +- If `credential_sets` is not provided, the Verifier requests all + Credentials in `credentials` to be returned. - Otherwise, the Verifier requests one combination of the Credentials - listed in `valid_credential_sets`, with optional credentials marked by the postfix `?`. + listed in `credential_sets`, with optional credentials marked by the postfix `?`. Credentials not matching the respective constraints expressed within -`expect_credentials` MUST NOT be returned, i.e., they are treated as if +`credentials` MUST NOT be returned, i.e., they are treated as if they would not exist in the Wallet. If the Wallet cannot deliver all non-optional Credentials requested by the Verifier according to these rules, it MUST NOT @@ -748,22 +747,12 @@ be valid type identifiers as defined in [@!I-D.ietf-oauth-sd-jwt-vc]. The Wallet MAY return credentials that inherit from any of the specified types, following the inheritance logic defined in [@!I-D.ietf-oauth-sd-jwt-vc]. -`credential_signing_alg_values`: -: OPTIONAL. An array of strings that specifies -the allowed algorithms for signing the SD-JWT (i.e., only the issuer-signed part). - -`kbjwt_signing_alg_values`: -: OPTIONAL. An array of strings that specifies the -allowed algorithms for signing the Key-Binding JWT (KB-JWT) (i.e., the part signed -by the holder). - -`sd_alg_values`: -: OPTIONAL. An array of strings that specifies the allowed hash algorithms for -digests in the SD-JWT and KB-JWT. - ### Format `mso_mdoc` {#format_mso_mdoc} -TBD +`doctype_values`: +: OPTIONAL. An array of strings that specifies allowed values for the +doctype of the requested Verifiable Credential. All elements in the array MUST +be valid doctype identifiers as defined in ISO 18013-5. ### Format `jwt_vp*` From 88544727805a5060e2ddfd7d3b5859500f2c151c Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Wed, 9 Oct 2024 09:36:25 +0200 Subject: [PATCH 27/49] Adapt description of ID Token --- openid-4-verifiable-presentations-1_0.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 8bd68ab6..86f5d20a 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -113,7 +113,7 @@ Biometrics-based Holder Binding: : Ability of the Holder to prove legitimate possession of a Verifiable Credential by demonstrating a certain biometric trait, such as finger print or face. One example of a Verifiable Credential with biometric Holder Binding is a mobile driving license [@ISO.18013-5], which contains a portrait of the Holder. VP Token: -: An artifact defined in this specification that contains a single Verifiable Presentation or an array of Verifiable Presentations as defined in (#response-parameters). +: An artifact containing one or more Verifiable Presentations returned as a response to an Authorization Request. The structure of VP Tokens is defined in (#response-parameters). Wallet: : An entity used by the Holder to receive, store, present, and manage Verifiable Credentials and key material. There is no single deployment model of a Wallet: Verifiable Credentials and keys can both be stored/managed locally, or by using a remote self-hosted service, or a remote third-party service. In the context of this specification, the Wallet acts as an OAuth 2.0 Authorization Server (see [@!RFC6749]) towards the Credential Verifier which acts as the OAuth 2.0 Client. @@ -882,7 +882,9 @@ The behavior with respect to the VP Token is unspecified for any other individua When a VP Token is returned, the respective response MUST include the following parameters: `vp_token`: -: REQUIRED. JSON String or JSON object that MUST contain a single Verifiable Presentation or an array of JSON Strings and JSON objects each of them containing a Verifiable Presentations. Each Verifiable Presentation MUST be represented as a JSON string (that is a base64url-encoded value) or a JSON object depending on a format as defined in Appendix A of [@!OpenID.VCI]. When a single Verifiable Presentation is returned, the array syntax MUST NOT be used. If Appendix A of [@!OpenID.VCI] defines a rule for encoding the respective Credential format in the Credential Response, this rules MUST also be followed when encoding Credentials of this format in the `vp_token` response parameter. Otherwise, this specification does not require any additional encoding when a Credential format is already represented as a JSON object or a JSON string. +: REQUIRED. The structure of this parameter depends on the Authorization Request: + * In case Presentation Exchange was used in the Authorization Request, it is a JSON String or JSON object that MUST contain a single Verifiable Presentation or an array of JSON Strings and JSON objects each of them containing a Verifiable Presentations. Each Verifiable Presentation MUST be represented as a JSON string (that is a base64url-encoded value) or a JSON object depending on a format as defined in Appendix A of [@!OpenID.VCI]. When a single Verifiable Presentation is returned, the array syntax MUST NOT be used. If Appendix A of [@!OpenID.VCI] defines a rule for encoding the respective Credential format in the Credential Response, this rules MUST also be followed when encoding Credentials of this format in the `vp_token` response parameter. Otherwise, this specification does not require any additional encoding when a Credential format is already represented as a JSON object or a JSON string. + * In case the `vp_query` parameter was used, this is a JSON-encoded object; the keys are the `id` values used for the Credential Queries in the VP Query, and the values are the Verifiable Presentations that match the respective Credential Query. The Verifiable Presentations are represented as strings or objects depending on the format as defined in Appendix A of [@!OpenID.VCI]. The same rules as above apply for encoding the Verifiable Presentations. `presentation_submission`: : REQUIRED. The `presentation_submission` element as defined in [@!DIF.PresentationExchange]. It contains mappings between the requested Verifiable Credentials and where to find them within the returned VP Token. This is expressed via elements in the `descriptor_map` array, known as Input Descriptor Mapping Objects. These objects contain a field called `path`, which, for this specification, MUST have the value `$` (top level root path) when only one Verifiable Presentation is contained in the VP Token, and MUST have the value `$[n]` (indexed path from root) when there are multiple Verifiable Presentations, where `n` is the index to select. Additional parameters can be defined by Credential Formats, see (#alternative_credential_formats) for details. From 728c41fc115afb9144bb53eca0150fd6c8611390 Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Thu, 10 Oct 2024 13:59:06 +0200 Subject: [PATCH 28/49] Update examples/query_lang/claims_alternatives.json --- examples/query_lang/claims_alternatives.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/query_lang/claims_alternatives.json b/examples/query_lang/claims_alternatives.json index 84ea5978..cf714d93 100644 --- a/examples/query_lang/claims_alternatives.json +++ b/examples/query_lang/claims_alternatives.json @@ -1,7 +1,7 @@ { "credentials": [ { - "group": "pid", + "id": "pid", "format": "vc+sd-jwt", "meta": { "vct_values": [ "https://credentials.example.com/identity_credential" ] From 6d594e7e426d42d0b37e4cc467e047a0c2fe7d2a Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Thu, 10 Oct 2024 17:59:52 +0200 Subject: [PATCH 29/49] Introduce ?! modifier, remove `value` --- openid-4-verifiable-presentations-1_0.md | 31 ++++++++++++++---------- 1 file changed, 18 insertions(+), 13 deletions(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 86f5d20a..353cc345 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -660,8 +660,8 @@ claims in the requested Credentials. `claim_sets`: : OPTIONAL. A non-empty array containing arrays of identifiers for elements in -`claims`. The identifier MAY be postfixed by `?`, indicating that -delivery of the the respective claim is OPTIONAL. +`claims`. The identifier MAY be postfixed by `?` or `?!`, indicating that +delivery of the respective claim is optional under certain conditions, as defined in (#selecting_claims). ## Claims Query {#claims_query} @@ -689,21 +689,23 @@ within the Verifiable Credential, e.g., `org.iso.18013.5.1`. The value MUST be a string that specifies the name of the claim within the provided namespace in the Verifiable Credential, e.g., `first_name`. -`value`: -: OPTIONAL. A string, integer or boolean value that specifies the expected value of the claim. If the -`value` property is present, the Wallet MUST return the claim only if the type and value -of the claim match the type and value specified in the query. This property MUST NOT be present if the `values` property is present. - `values`: : OPTIONAL. An array of strings, integers or boolean values that specifies the expected values of the claim. If the `values` property is present, the Wallet MUST return the claim only if the -type and value of the claim both match for at least one of the elements in the array. This property MUST NOT be present if the `value` property is present. +type and value of the claim both match for at least one of the elements in the array. ### Selecting Claims and Credentials {#vp_query_lang_processing_rules} -The same basic logic applies for selecting claims and for selecting credentials, as detailed in the following. +The same basic logic applies for selecting claims and for selecting credentials, +as detailed in the following. + +Note: While this specification provides the mechanisms for requesting different +sets of claims and credentials and request some of those optionally, it does not +make assumptions about the user interface of the Wallet, for example, if users +can select which claims to present or which combination of credentials to +present. -#### Selecting Claims +#### Selecting Claims {#selecting_claims} The following rules apply for selecting claims via `claims` and `claim_sets`: @@ -712,10 +714,13 @@ The following rules apply for selecting claims via `claims` and `claim_sets`: - If `claims` is provided, but `claim_sets` is not provided, the Verifier requests all claims listed in `claims`. - Otherwise, the Verifier requests one combination of the claims listed in - `claim_sets`, with optional claims marked by the postfix `?`. + `claim_sets`. Claims listed without a postfix are requested unconditionally. + Claims postfixed by `?` are requested optionally, i.e., it is up to the Wallet + to send the claim in the response or not. Claims postfixed by `?!` have to be + provided by the Wallet if they exist in the Credential. -If the Wallet cannot deliver all non-optional claims requested by the Verifier according to these rules, it MUST NOT -return the respective Credential. +If the Wallet cannot deliver all non-optional claims requested by the Verifier +according to these rules, it MUST NOT return the respective Credential. #### Selecting Credentials From 9cd1bbbc379a530b1cdd6cffa36697ffc4754c2d Mon Sep 17 00:00:00 2001 From: Tobias Looker Date: Fri, 18 Oct 2024 05:10:34 +1300 Subject: [PATCH 30/49] Proposed alterations to how optionality is handled in query language (Approach 3) (#281) Agreed on the WG call that in a new query language, we will: 1. remove claim_sets 2. introduce equivalent of ?! in credentials object (`provide_if_available` or something) 3. change `credential_sets` to array of objects 4. add purpose to the object in credential_sets array - it can be a string or an integer, but it has to be shown only if RP is authenticated. (from processing, probably easier to defined purpose_code that is an integer separately? shouldn't matter, we can discuss in the PR) for the sake of making progress, merging this PR and @danielfett will apply full set of these changes in his PR. no consensus on value matching. --- examples/query_lang/claims_alternatives.json | 9 +- examples/query_lang/complex_mdoc.json | 105 ++++++++++++++++++ .../query_lang/credentials_alternatives.json | 23 ++-- openid-4-verifiable-presentations-1_0.md | 84 +++++++++----- 4 files changed, 179 insertions(+), 42 deletions(-) create mode 100644 examples/query_lang/complex_mdoc.json diff --git a/examples/query_lang/claims_alternatives.json b/examples/query_lang/claims_alternatives.json index cf714d93..73b90989 100644 --- a/examples/query_lang/claims_alternatives.json +++ b/examples/query_lang/claims_alternatives.json @@ -19,11 +19,10 @@ {"id": "f", "path": ["email"]} ], "claim_sets": [ // defines the rules - // postal code or (locality and region), last_name, and date_of_birth are mandatory; email is optional - ["a", "b", "e", "f?"], - ["a", "c", "d", "e", "f?"] - - // Note: the ? to mark a claim as optional is syntactical sugar; the rules could be rewritten without it, but that would require a lot of repetition + // postal code or (locality and region), last_name, and date_of_birth are mandatory; email is required if present on the matched credential + ["a", "b", "e", "f?!"], + ["a", "c", "d", "e", "f?!"] + // Note: the ?! to mark a claim as `required if present` is syntactical sugar; the rules could be rewritten without it, but that would require a lot of repetition ] } ] diff --git a/examples/query_lang/complex_mdoc.json b/examples/query_lang/complex_mdoc.json new file mode 100644 index 00000000..120d3f63 --- /dev/null +++ b/examples/query_lang/complex_mdoc.json @@ -0,0 +1,105 @@ +{ + "credentials": [ + { + "id": "mdl-id", + "format": "mso_mdoc", + "meta": { + "doctype_values": ["org.iso.18013.5.1.mdl"] + }, + "claims": [ + { + "id": "given_name", + "namespace": "org.iso.18013.5.1", + "claim_name": "given_name" + }, + { + "id": "family_name", + "namespace": "org.iso.18013.5.1", + "claim_name": "family_name" + }, + { + "id": "portrait", + "namespace": "org.iso.18013.5.1", + "claim_name": "portrait" + } + ] + }, + { + "id": "mdl-address", + "format": "mso_mdoc", + "meta": { + "doctype_values": ["org.iso.18013.5.1.mdl"] + }, + "claims": [ + { + "id": "resident_address", + "namespace": "org.iso.18013.5.1", + "claim_name": "resident_address" + }, + { + "id": "resident_country", + "namespace": "org.iso.18013.5.1", + "claim_name": "resident_country" + } + ] + }, + { + "id": "photo_card-id", + "format": "mso_mdoc", + "meta": { + "doctype_values": ["org.iso.23220.photoid"] + }, + "claims": [ + { + "id": "given_name", + "namespace": "org.iso.23220.1", + "claim_name": "given_name" + }, + { + "id": "family_name", + "namespace": "org.iso.23220.1", + "claim_name": "family_name" + }, + { + "id": "portrait", + "namespace": "org.iso.23220.1", + "claim_name": "portrait" + } + ] + }, + { + "id": "photo_card-address", + "format": "mso_mdoc", + "meta": { + "doctype_values": ["org.iso.23220.photoid"] + }, + "claims": [ + { + "id": "resident_address", + "namespace": "org.iso.23220.1", + "claim_name": "resident_address" + }, + { + "id": "resident_country", + "namespace": "org.iso.23220.1", + "claim_name": "resident_country" + } + ] + } + ], + "credential_sets": [ + { // Purpose of this request is to prove your ID, response to this request is required + "query_options": [ // These options mean you could use either your mDL or Photo Card to respond to the request + [ "mdl-id" ], + [ "photo_card-id" ] + ] + }, + { // Purpose of this request is to prove your address, response to this request is not required + "required": false, + "query_options": [ // These options mean you could use either your mDL or Photo Card to respond to the request + [ "mdl-address" ], + [ "photo_card-address" ] + ] + } + ] +} \ No newline at end of file diff --git a/examples/query_lang/credentials_alternatives.json b/examples/query_lang/credentials_alternatives.json index 0e08ce8d..47180b44 100644 --- a/examples/query_lang/credentials_alternatives.json +++ b/examples/query_lang/credentials_alternatives.json @@ -54,18 +54,27 @@ "vct_values": ["https://company.example/company_rewards"] }, "claims": [ - {"id": "current", "path": ["rewards_number"]}, - {"id": "legacy", "path": ["legacy_system_rewards_number"]} + {"id": "current", "path": ["rewards_number"]} ], "claim_sets": [ - ["current", "legacy?"] + ["current"] ] } ], + // deliver the pid, or the other_pid, or both pid_reduced_cred1 + 2; nice_to_have is optional in all cases "credential_sets": [ - // deliver the pid, or the other_pid, or both pid_reduced_cred1 + 2; nice_to_have is optional in all cases - ["pid", "nice_to_have?"], - ["other_pid", "nice_to_have?"], - ["pid_reduced_cred_1", "pid_reduced_cred_2", "nice_to_have?"] + { + "query_options": [ + [ "pid" ], + [ "other_pid" ], + [ "pid_reduced_cred_1", "pid_reduced_cred_2" ] + ] + }, + { + "required": false, + "query_options": [ + [ "nice_to_have" ] + ] + } ] } \ No newline at end of file diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 353cc345..b67cf597 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -618,11 +618,8 @@ top-level properties: that specify the requested Verifiable Credentials. `credential_sets`: -: OPTIONAL. A non-empty array containing arrays of identifiers for Credential Queries defined in -`credentials` that defines which sets of Credentials may be returned. -The identifier MAY be postfixed by `?`, indicating that -delivery of the respective Credential is optional. For details, see -(#vp_query_lang_processing_rules). +: OPTIONAL. A non-empty array of credential set queries as defined in (#credential_set_query) +that specifies additional constraints on which of the requested Verifiable Credentials to return. Note: While this specification does not define additional top-level properties, future extensions MAY define additional properties that modify the behavior of @@ -631,9 +628,9 @@ the Wallet when processing the query. ## Credential Query {#credential_query} A Credential Query is an object representing a request for one specific -Credential. +Credential. -It contains the following properties: +Each entry in `credentials` MUST be an object with the following properties: `id`: : REQUIRED. A string identifying the Credential in the response and, if provided, @@ -660,8 +657,24 @@ claims in the requested Credentials. `claim_sets`: : OPTIONAL. A non-empty array containing arrays of identifiers for elements in -`claims`. The identifier MAY be postfixed by `?` or `?!`, indicating that -delivery of the respective claim is optional under certain conditions, as defined in (#selecting_claims). +`claims`. The identifier MAY be postfixed by `?!` indicating that +delivery of the respective claim is required if present on the credential, see (#selecting_claims) for more details. + +## Credential Set Query {#credential_set_query} + +A Credential Set Query is an object representing a request for one or more credentials to satisfy +a particular usecase with the Verifier. + +Each entry in `credential_sets` MUST be an object with the following properties: + +`query_options` +: REQUIRED: A non-empty array, where each value in the array represents a distinct query that satisfies +the Usecase. The value of each element in the `query_options` array, is an array of identifiers which reference +elements in `credentials`. + +`required` +: OPTIONAL. A boolean flag which indicates whether the wallet is required to respond to the query. +If omitted, the effective value MUST be processed as `true`. ## Claims Query {#claims_query} @@ -671,7 +684,7 @@ Each entry in `claims` MUST be an object with the following properties: : REQUIRED if `claim_sets` is present; OPTIONAL otherwise. A string identifying the particular claim. The value MUST be a non-empty string consisting of alphanumeric, underscore (`_`) or hyphen (`-`) characters. -Within the particular `expected_claims` array, the same `id` MUST NOT +Within the particular `claims` array, the same `id` MUST NOT be present more than once. `path`: @@ -680,14 +693,14 @@ be present otherwise. The value MUST be a claims path pointer that specifies the within the Verifiable Credential, as defined in (#claims_path_pointer). `namespace`: -: REQUIRED if the Credential Format is based on mdoc format defined in ISO 18013-5; MUST NOT be present otherwise. -The value MUST be a string that specifies the namespace of the claim -within the Verifiable Credential, e.g., `org.iso.18013.5.1`. +: REQUIRED if the Credential Format is based on the mdoc format defined in ISO 18013-5; MUST NOT be present otherwise. +The value MUST be a string that specifies the namespace of the data element +within the mdoc, e.g., `org.iso.18013.5.1`. `claim_name`: : REQUIRED if the Credential Format is based on mdoc format defined in ISO 18013-5; MUST NOT be present otherwise. -The value MUST be a string that specifies the name of the claim within the provided namespace -in the Verifiable Credential, e.g., `first_name`. +The value MUST be a string that specifies the data element identifier of the data element within the provided namespace +in the mdoc, e.g., `first_name`. `values`: : OPTIONAL. An array of strings, integers or boolean values that specifies the expected values of the claim. @@ -696,14 +709,13 @@ type and value of the claim both match for at least one of the elements in the a ### Selecting Claims and Credentials {#vp_query_lang_processing_rules} -The same basic logic applies for selecting claims and for selecting credentials, -as detailed in the following. +The following section describes the logic that applies for selecting claims +and for selecting credentials. Note: While this specification provides the mechanisms for requesting different -sets of claims and credentials and request some of those optionally, it does not -make assumptions about the user interface of the Wallet, for example, if users -can select which claims to present or which combination of credentials to -present. +sets of claims and credentials, it does not make assumptions about the user +interface of the Wallet, for example, if users can select which claims to present +or which combination of credentials to present. #### Selecting Claims {#selecting_claims} @@ -714,12 +726,22 @@ The following rules apply for selecting claims via `claims` and `claim_sets`: - If `claims` is provided, but `claim_sets` is not provided, the Verifier requests all claims listed in `claims`. - Otherwise, the Verifier requests one combination of the claims listed in - `claim_sets`. Claims listed without a postfix are requested unconditionally. - Claims postfixed by `?` are requested optionally, i.e., it is up to the Wallet - to send the claim in the response or not. Claims postfixed by `?!` have to be - provided by the Wallet if they exist in the Credential. - -If the Wallet cannot deliver all non-optional claims requested by the Verifier + `claim_sets`. Claims listed without a postfix are requested unconditionally. + Claims postfixed by `?!` have to be provided by the Wallet if they exist on + the matched Credential. The order of the options conveyed in the `claim_sets` + array expresses the Verifiers preference for what is returned. A wallet MUST + prioritise returning the most preferred option. + +With regard to the `claim_sets` syntax, the purpose of it to provide a way for a +verifier to describe alternative ways a given credential can satisfy their request, +the array ordering should express the Verifiers preference for how the request should +be fulfilled where the first element in the array is the most preferred and the last +element in the array is the least preferred. Verifiers should use the principle of +least information disclosure to influence how they order these options. For example a +proof of age request should prioritise requesting an attribute like `age_over_18` ahead +of requesting an attribute like `birth_date`. + +If the Wallet cannot deliver all unconditional claims requested by the Verifier according to these rules, it MUST NOT return the respective Credential. #### Selecting Credentials @@ -728,8 +750,11 @@ The following rules apply for selecting Credentials via `credentials` and `crede - If `credential_sets` is not provided, the Verifier requests all Credentials in `credentials` to be returned. -- Otherwise, the Verifier requests one combination of the Credentials - listed in `credential_sets`, with optional credentials marked by the postfix `?`. +- Otherwise, the Verifier requests all of the credential set queries in the `credential_sets` array + with `required` evaluated as true to be returned at a minimum and optionally any of the credential set queries + with `required` evaluated as false. +- For each credential set query inside the `credential_sets` array, in order to satisfy the query, the Wallet MUST return +a credential or credentials that match to one of the `query_options` inside the object. Credentials not matching the respective constraints expressed within `credentials` MUST NOT be returned, i.e., they are treated as if @@ -738,7 +763,6 @@ they would not exist in the Wallet. If the Wallet cannot deliver all non-optional Credentials requested by the Verifier according to these rules, it MUST NOT return any credential(s). - ## Format-specific Properties {#format_specific_properties} The following format-specific properties are defined: From ca65bfc563a003061816cedbec35411952046423 Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Fri, 18 Oct 2024 09:00:03 +0200 Subject: [PATCH 31/49] Update openid-4-verifiable-presentations-1_0.md --- openid-4-verifiable-presentations-1_0.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index b67cf597..e00a3821 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -732,14 +732,14 @@ The following rules apply for selecting claims via `claims` and `claim_sets`: array expresses the Verifiers preference for what is returned. A wallet MUST prioritise returning the most preferred option. -With regard to the `claim_sets` syntax, the purpose of it to provide a way for a -verifier to describe alternative ways a given credential can satisfy their request, -the array ordering should express the Verifiers preference for how the request should +The purpose of the `claim_sets` syntax is to provide a way for a +verifier to describe alternative ways a given credential can satisfy the request. +The array ordering expresses the Verifier's preference for how the request should be fulfilled where the first element in the array is the most preferred and the last element in the array is the least preferred. Verifiers should use the principle of -least information disclosure to influence how they order these options. For example a -proof of age request should prioritise requesting an attribute like `age_over_18` ahead -of requesting an attribute like `birth_date`. +least information disclosure to influence how they order these options. For example, a +proof of age request should prioritize requesting an attribute like `age_over_18` over +an attribute like `birth_date`. If the Wallet cannot deliver all unconditional claims requested by the Verifier according to these rules, it MUST NOT return the respective Credential. From f71a2e28005fe127af50361dabd331daff4c9c6c Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Fri, 18 Oct 2024 15:46:22 +0200 Subject: [PATCH 32/49] Remove merge conflict --- openid-4-verifiable-presentations-1_0.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 99e359c9..26ab2af5 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -1861,7 +1861,6 @@ issuers in Self-Sovereign Identity ecosystems using TRAIN -<<<<<<< HEAD BCP47 @@ -1873,7 +1872,6 @@ issuers in Self-Sovereign Identity ecosystems using TRAIN -======= OAuth Parameters @@ -1913,7 +1911,6 @@ issuers in Self-Sovereign Identity ecosystems using TRAIN ->>>>>>> main # 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 d7cacf40a5ef0dc107239cd5719e3ce4675750a8 Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Mon, 21 Oct 2024 15:27:50 +0200 Subject: [PATCH 33/49] Remove question mark notation; add purpose; add/fix example descriptions --- examples/query_lang/claims_alternatives.json | 19 ++-- examples/query_lang/complex_mdoc.json | 8 +- .../query_lang/credentials_alternatives.json | 6 +- .../query_lang/value_matching_simple.json | 2 +- openid-4-verifiable-presentations-1_0.md | 99 +++++++++++-------- 5 files changed, 72 insertions(+), 62 deletions(-) diff --git a/examples/query_lang/claims_alternatives.json b/examples/query_lang/claims_alternatives.json index 73b90989..6c0fbf98 100644 --- a/examples/query_lang/claims_alternatives.json +++ b/examples/query_lang/claims_alternatives.json @@ -6,23 +6,16 @@ "meta": { "vct_values": [ "https://credentials.example.com/identity_credential" ] }, - // Comments in JSON to be removed before merging PR, they are just here to make Brian less sad - "claims": [ // define claims, may add other properties like a purpose to each claims - { - "id": "a", // required for use in claim_sets below; if that is omitted, the id is optional - "path": ["last_name"] - }, + "claims": [ + {"id": "a","path": ["last_name"]}, {"id": "b", "path": ["postal_code"]}, {"id": "c", "path": ["locality"]}, {"id": "d", "path": ["region"]}, - {"id": "e", "path": ["date_of_birth"]}, - {"id": "f", "path": ["email"]} + {"id": "e", "path": ["date_of_birth"]} ], - "claim_sets": [ // defines the rules - // postal code or (locality and region), last_name, and date_of_birth are mandatory; email is required if present on the matched credential - ["a", "b", "e", "f?!"], - ["a", "c", "d", "e", "f?!"] - // Note: the ?! to mark a claim as `required if present` is syntactical sugar; the rules could be rewritten without it, but that would require a lot of repetition + "claim_sets": [ + ["a", "c", "d", "e"], + ["a", "b", "e"] ] } ] diff --git a/examples/query_lang/complex_mdoc.json b/examples/query_lang/complex_mdoc.json index 120d3f63..f9be5d4e 100644 --- a/examples/query_lang/complex_mdoc.json +++ b/examples/query_lang/complex_mdoc.json @@ -88,15 +88,15 @@ } ], "credential_sets": [ - { // Purpose of this request is to prove your ID, response to this request is required - "query_options": [ // These options mean you could use either your mDL or Photo Card to respond to the request + { + "query_options": [ [ "mdl-id" ], [ "photo_card-id" ] ] }, - { // Purpose of this request is to prove your address, response to this request is not required + { "required": false, - "query_options": [ // These options mean you could use either your mDL or Photo Card to respond to the request + "query_options": [ [ "mdl-address" ], [ "photo_card-address" ] ] diff --git a/examples/query_lang/credentials_alternatives.json b/examples/query_lang/credentials_alternatives.json index 47180b44..773554df 100644 --- a/examples/query_lang/credentials_alternatives.json +++ b/examples/query_lang/credentials_alternatives.json @@ -54,14 +54,10 @@ "vct_values": ["https://company.example/company_rewards"] }, "claims": [ - {"id": "current", "path": ["rewards_number"]} - ], - "claim_sets": [ - ["current"] + {"path": ["rewards_number"]} ] } ], - // deliver the pid, or the other_pid, or both pid_reduced_cred1 + 2; nice_to_have is optional in all cases "credential_sets": [ { "query_options": [ diff --git a/examples/query_lang/value_matching_simple.json b/examples/query_lang/value_matching_simple.json index b57b7900..b4d26f3f 100644 --- a/examples/query_lang/value_matching_simple.json +++ b/examples/query_lang/value_matching_simple.json @@ -9,7 +9,7 @@ "claims": [ { "path": ["last_name"], - "value": "Doe" + "values": ["Doe"] }, {"path": ["first_name"]}, {"path": ["address", "street_address"]}, diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 26ab2af5..9ec6f0f4 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -627,7 +627,7 @@ the Wallet when processing the query. ## Credential Query {#credential_query} -A Credential Query is an object representing a request for one specific +A Credential Query is an object representing a request for a presentation of one Credential. Each entry in `credentials` MUST be an object with the following properties: @@ -656,32 +656,40 @@ Credential. claims in the requested Credentials. `claim_sets`: -: OPTIONAL. A non-empty array containing arrays of identifiers for elements in -`claims`. The identifier MAY be postfixed by `?!` indicating that -delivery of the respective claim is required if present on the credential, see (#selecting_claims) for more details. +: OPTIONAL. A non-empty array containing arrays of identifiers for +elements in `claims`. The rules for selecting claims to send are defined in (#selecting_claims). + +Note that multiple Credential Queries in a request MAY request a presentation of the same Credential. ## Credential Set Query {#credential_set_query} A Credential Set Query is an object representing a request for one or more credentials to satisfy -a particular usecase with the Verifier. +a particular use case with the Verifier. Each entry in `credential_sets` MUST be an object with the following properties: -`query_options` +`options` : REQUIRED: A non-empty array, where each value in the array represents a distinct query that satisfies -the Usecase. The value of each element in the `query_options` array, is an array of identifiers which reference +the use case. The value of each element in the `options` array is an array of identifiers which reference elements in `credentials`. `required` : OPTIONAL. A boolean flag which indicates whether the wallet is required to respond to the query. If omitted, the effective value MUST be processed as `true`. +`purpose` +: OPTIONAL. A string, number or object specifying the purpose of the +query. This specification does not define a specific structure or specific values +for this property. The purpose is intended to be used by the Verifier to +communicate the reason for the query to the Wallet. The Wallet MAY use this +information to show the user the reason for the request. + ## Claims Query {#claims_query} Each entry in `claims` MUST be an object with the following properties: `id`: -: REQUIRED if `claim_sets` is present; OPTIONAL otherwise. A string +: REQUIRED if `claim_sets` is present in the Credential Query; OPTIONAL otherwise. A string identifying the particular claim. The value MUST be a non-empty string consisting of alphanumeric, underscore (`_`) or hyphen (`-`) characters. Within the particular `claims` array, the same `id` MUST NOT @@ -704,8 +712,8 @@ in the mdoc, e.g., `first_name`. `values`: : OPTIONAL. An array of strings, integers or boolean values that specifies the expected values of the claim. -If the `values` property is present, the Wallet MUST return the claim only if the -type and value of the claim both match for at least one of the elements in the array. +If the `values` property is present, the Wallet SHOULD return the claim only if the +type and value of the claim both match for at least one of the elements in the array. Details of the processing rules are defined in (#selecting_claims). ### Selecting Claims and Credentials {#vp_query_lang_processing_rules} @@ -726,22 +734,31 @@ The following rules apply for selecting claims via `claims` and `claim_sets`: - If `claims` is provided, but `claim_sets` is not provided, the Verifier requests all claims listed in `claims`. - Otherwise, the Verifier requests one combination of the claims listed in - `claim_sets`. Claims listed without a postfix are requested unconditionally. - Claims postfixed by `?!` have to be provided by the Wallet if they exist on - the matched Credential. The order of the options conveyed in the `claim_sets` - array expresses the Verifiers preference for what is returned. A wallet MUST - prioritise returning the most preferred option. + `claim_sets`. The order of the options conveyed in the `claim_sets` + array expresses the Verifiers' preference for what is returned; the Wallet MUST return + the first option that it can satisfy. If the Wallet cannot satisfy any of the + options, it MUST NOT return any claims. + +When a Claims Query contains a restriction on the values of a claim, the Wallet +SHOULD NOT return the claim if its value does not match at least one of the +elements in `values` i.e., the claim should be treated the same as if it did not +exist in the Credential. Implementing this restriction may not be possible in +all cases, for example, if the Wallet does not have access to the claim value +before presentation or user consent or if another component routing +the request to the Wallet does not have access to the claim value. Therefore, Verifiers +must treat restrictions expressed using `values` as a best-effort way to improve +user privacy, but MUST NOT rely on it for security checks. The purpose of the `claim_sets` syntax is to provide a way for a verifier to describe alternative ways a given credential can satisfy the request. -The array ordering expresses the Verifier's preference for how the request should -be fulfilled where the first element in the array is the most preferred and the last -element in the array is the least preferred. Verifiers should use the principle of +The array ordering expresses the Verifier's preference for how the request must +be fulfilled. The first element in the array is the most preferred and the last +element in the array is the least preferred. Verifiers SHOULD use the principle of least information disclosure to influence how they order these options. For example, a proof of age request should prioritize requesting an attribute like `age_over_18` over an attribute like `birth_date`. -If the Wallet cannot deliver all unconditional claims requested by the Verifier +If the Wallet cannot deliver all claims requested by the Verifier according to these rules, it MUST NOT return the respective Credential. #### Selecting Credentials @@ -753,15 +770,18 @@ The following rules apply for selecting Credentials via `credentials` and `crede - Otherwise, the Verifier requests all of the credential set queries in the `credential_sets` array with `required` evaluated as true to be returned at a minimum and optionally any of the credential set queries with `required` evaluated as false. -- For each credential set query inside the `credential_sets` array, in order to satisfy the query, the Wallet MUST return -a credential or credentials that match to one of the `query_options` inside the object. +- For each credential set query inside the `credential_sets` array, in order to + satisfy the query, the Wallet MUST return a credential or credentials that + match to one of the `options` inside the object. It is typically + expected that the Wallet presents the End-User with a choice of which + credential to present if multiple credentials match the query. Credentials not matching the respective constraints expressed within `credentials` MUST NOT be returned, i.e., they are treated as if they would not exist in the Wallet. -If the Wallet cannot deliver all non-optional Credentials requested by the Verifier according to these rules, it MUST NOT -return any credential(s). +If the Wallet cannot deliver all non-optional Credentials requested by the +Verifier according to these rules, it MUST NOT return any credential(s). ## Format-specific Properties {#format_specific_properties} @@ -783,10 +803,6 @@ the inheritance logic defined in [@!I-D.ietf-oauth-sd-jwt-vc]. doctype of the requested Verifiable Credential. All elements in the array MUST be valid doctype identifiers as defined in ISO 18013-5. -### Format `jwt_vp*` - -TBD - ## Claims Path Pointer {#claims_path_pointer} @@ -2384,26 +2400,31 @@ Credential in the format `mso_mdoc` with the claims `vehicle_holder` and <{{examples/query_lang/simple_mdoc.json}} -The following is a non-normative example of a VP Query that requests - -- the mandatory claims `last_name` and `date_of_birth`, and -- either the claim `postal_code`, or both of the the claims `locality` and `region`, and -- optionally the claim `email`. - -<{{examples/query_lang/claims_alternatives.json}} - The following is a non-normative example of a VP Query that requests multiple Verifiable Credentials; all of them must be returned: <{{examples/query_lang/multi_credentials.json}} -The following shows a complex query where the Wallet is requested to deliver the `pid` credential, or the `other_pid` credential, or both `pid_reduced_cred_1` and `pid_reduced_cred_2`. Additionally, the `nice_to_have` credential may optionally be -delivered. From the latter, the claim `legacy_system_rewards_number` may optionally -be delivered. +The following shows a complex query where the Wallet is requested to deliver the +`pid` credential, or the `other_pid` credential, or both `pid_reduced_cred_1` +and `pid_reduced_cred_2`. Additionally, the `nice_to_have` credential may +optionally be delivered. <{{examples/query_lang/credentials_alternatives.json}} -The following example shows a query that uses the `value` and `values` constraints +The following shows a query where an ID and an address are requested; either can +come from an mDL or a photoid Credential. + +<{{examples/query_lang/complex_mdoc.json}} + +The following is a non-normative example of a VP Query that requests + +- the mandatory claims `last_name` and `date_of_birth`, and +- either the claim `postal_code`, or, if that is not available, both of the claims `locality` and `region`. + +<{{examples/query_lang/claims_alternatives.json}} + +The following example shows a query that uses the `values` constraints to request a credential with specific values for the `last_name` and `postal_code` claims: <{{examples/query_lang/value_matching_simple.json}} From 935b2478615b011eadcc78cc87108c2e8946d041 Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Mon, 21 Oct 2024 17:20:16 +0200 Subject: [PATCH 34/49] Apply suggestions from code review Co-authored-by: Oliver Terbu Co-authored-by: Kristina <52878547+Sakurann@users.noreply.github.com> --- examples/query_lang/complex_mdoc.json | 8 ++++---- examples/query_lang/multi_credentials.json | 2 +- examples/query_lang/simple_mdoc.json | 2 +- openid-4-verifiable-presentations-1_0.md | 4 ++-- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/examples/query_lang/complex_mdoc.json b/examples/query_lang/complex_mdoc.json index f9be5d4e..3ddd200c 100644 --- a/examples/query_lang/complex_mdoc.json +++ b/examples/query_lang/complex_mdoc.json @@ -4,7 +4,7 @@ "id": "mdl-id", "format": "mso_mdoc", "meta": { - "doctype_values": ["org.iso.18013.5.1.mdl"] + "doctype_values": ["org.iso.18013.5.1.mDL"] }, "claims": [ { @@ -28,7 +28,7 @@ "id": "mdl-address", "format": "mso_mdoc", "meta": { - "doctype_values": ["org.iso.18013.5.1.mdl"] + "doctype_values": ["org.iso.18013.5.1.mDL"] }, "claims": [ { @@ -47,7 +47,7 @@ "id": "photo_card-id", "format": "mso_mdoc", "meta": { - "doctype_values": ["org.iso.23220.photoid"] + "doctype_values": ["org.iso.23220.photoid.1"] }, "claims": [ { @@ -71,7 +71,7 @@ "id": "photo_card-address", "format": "mso_mdoc", "meta": { - "doctype_values": ["org.iso.23220.photoid"] + "doctype_values": ["org.iso.23220.photoid.1"] }, "claims": [ { diff --git a/examples/query_lang/multi_credentials.json b/examples/query_lang/multi_credentials.json index 1a59e594..18354943 100644 --- a/examples/query_lang/multi_credentials.json +++ b/examples/query_lang/multi_credentials.json @@ -16,7 +16,7 @@ "id": "mdl", "format": "mso_mdoc", "meta": { - "doctype_values": ["org.iso.7367.1.mVR"] + "doctype_values": ["org.iso.7367.1.mVRC"] }, "claims": [ { diff --git a/examples/query_lang/simple_mdoc.json b/examples/query_lang/simple_mdoc.json index ed74f3f0..cf4f91cb 100644 --- a/examples/query_lang/simple_mdoc.json +++ b/examples/query_lang/simple_mdoc.json @@ -4,7 +4,7 @@ "id": "my_credential", "format": "mso_mdoc", "meta": { - "doctype_values": ["org.iso.7367.1.mVR"] + "doctype_values": ["org.iso.7367.1.mVRC"] }, "claims": [ { diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 9ec6f0f4..616256fd 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -787,7 +787,7 @@ Verifier according to these rules, it MUST NOT return any credential(s). The following format-specific properties are defined: -### Format `vc+sd-jwt` {#format_vc_sd_jwt} +### IETF SD-JWT VC {#format_vc_sd_jwt} `vct_values`: : OPTIONAL. An array of strings that specifies allowed values for @@ -796,7 +796,7 @@ be valid type identifiers as defined in [@!I-D.ietf-oauth-sd-jwt-vc]. The Wallet MAY return credentials that inherit from any of the specified types, following the inheritance logic defined in [@!I-D.ietf-oauth-sd-jwt-vc]. -### Format `mso_mdoc` {#format_mso_mdoc} +### Mobile Documents or mdocs (ISO/IEC 18013 and ISO/IEC 23220 series) {#format_mso_mdoc} `doctype_values`: : OPTIONAL. An array of strings that specifies allowed values for the From ed7c8e2ff88eaedc11de5f6b0947c8c891cb30d4 Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Tue, 22 Oct 2024 08:57:59 +0200 Subject: [PATCH 35/49] Fix examples, adapt language from feedback --- examples/query_lang/complex_mdoc.json | 4 +-- .../query_lang/credentials_alternatives.json | 4 +-- openid-4-verifiable-presentations-1_0.md | 36 ++++++++++++------- 3 files changed, 28 insertions(+), 16 deletions(-) diff --git a/examples/query_lang/complex_mdoc.json b/examples/query_lang/complex_mdoc.json index 3ddd200c..22d2146f 100644 --- a/examples/query_lang/complex_mdoc.json +++ b/examples/query_lang/complex_mdoc.json @@ -89,14 +89,14 @@ ], "credential_sets": [ { - "query_options": [ + "options": [ [ "mdl-id" ], [ "photo_card-id" ] ] }, { "required": false, - "query_options": [ + "options": [ [ "mdl-address" ], [ "photo_card-address" ] ] diff --git a/examples/query_lang/credentials_alternatives.json b/examples/query_lang/credentials_alternatives.json index 773554df..b4fa87c4 100644 --- a/examples/query_lang/credentials_alternatives.json +++ b/examples/query_lang/credentials_alternatives.json @@ -60,7 +60,7 @@ ], "credential_sets": [ { - "query_options": [ + "options": [ [ "pid" ], [ "other_pid" ], [ "pid_reduced_cred_1", "pid_reduced_cred_2" ] @@ -68,7 +68,7 @@ }, { "required": false, - "query_options": [ + "options": [ [ "nice_to_have" ] ] } diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 13a435dd..24f3dc25 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -695,7 +695,8 @@ the use case. The value of each element in the `options` array is an array of id elements in `credentials`. `required` -: OPTIONAL. A boolean flag which indicates whether the wallet is required to respond to the query. +: OPTIONAL. A boolean flag which indicates whether this set of Credentials is required +to satisfy the particular use case at the Verifier. If omitted, the effective value MUST be processed as `true`. `purpose` @@ -741,11 +742,6 @@ type and value of the claim both match for at least one of the elements in the a The following section describes the logic that applies for selecting claims and for selecting credentials. -Note: While this specification provides the mechanisms for requesting different -sets of claims and credentials, it does not make assumptions about the user -interface of the Wallet, for example, if users can select which claims to present -or which combination of credentials to present. - #### Selecting Claims {#selecting_claims} The following rules apply for selecting claims via `claims` and `claim_sets`: @@ -788,14 +784,15 @@ The following rules apply for selecting Credentials via `credentials` and `crede - If `credential_sets` is not provided, the Verifier requests all Credentials in `credentials` to be returned. -- Otherwise, the Verifier requests all of the credential set queries in the `credential_sets` array +- Otherwise, the Verifier requests all of the Credential Set Queries in the `credential_sets` array with `required` evaluated as true to be returned at a minimum and optionally any of the credential set queries with `required` evaluated as false. -- For each credential set query inside the `credential_sets` array, in order to - satisfy the query, the Wallet MUST return a credential or credentials that - match to one of the `options` inside the object. It is typically - expected that the Wallet presents the End-User with a choice of which - credential to present if multiple credentials match the query. + +For each credential set query inside the `credential_sets` array, in order to +satisfy the query, the Wallet MUST return a credential or credentials that +match to one of the `options` inside the object. It is typically +expected that the Wallet presents the End-User with a choice of which +credential to present if multiple credentials match the query. Credentials not matching the respective constraints expressed within `credentials` MUST NOT be returned, i.e., they are treated as if @@ -804,6 +801,21 @@ they would not exist in the Wallet. If the Wallet cannot deliver all non-optional Credentials requested by the Verifier according to these rules, it MUST NOT return any credential(s). +#### User Interface Considerations {#vp_query_ui} + +While this specification provides the mechanisms for requesting different sets +of claims and credentials, it does not make assumptions about the user interface +of the Wallet, for example, if users can select which combination of credentials +to present. + +#### Security Considerations {#vp_query_security} + +While the Verifier can specify various constraints both on the claims level and +the credential level as shown above, it MUST NOT rely on the Wallet to enforce +these constraints. The Wallet is not controlled by the Verifier and the Verifier +MUST perform its own security checks on the returned credentials and +presentations. + ## Format-specific Properties {#format_specific_properties} The following format-specific properties are defined: From 56855acd5f539073990188c208251c1d8f013e7d Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Tue, 22 Oct 2024 10:54:55 +0200 Subject: [PATCH 36/49] Apply suggestions from code review Co-authored-by: Paul Bastian --- examples/query_lang/claims_alternatives.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/query_lang/claims_alternatives.json b/examples/query_lang/claims_alternatives.json index 6c0fbf98..36ac2217 100644 --- a/examples/query_lang/claims_alternatives.json +++ b/examples/query_lang/claims_alternatives.json @@ -7,7 +7,7 @@ "vct_values": [ "https://credentials.example.com/identity_credential" ] }, "claims": [ - {"id": "a","path": ["last_name"]}, + {"id": "a", "path": ["last_name"]}, {"id": "b", "path": ["postal_code"]}, {"id": "c", "path": ["locality"]}, {"id": "d", "path": ["region"]}, From 1511de4cb6e38f4e4a707a8517f370508d341a9f Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Tue, 22 Oct 2024 13:15:41 +0200 Subject: [PATCH 37/49] Apply suggestions from code review Co-authored-by: Kristina <52878547+Sakurann@users.noreply.github.com> --- openid-4-verifiable-presentations-1_0.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 24f3dc25..8ae8a364 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -261,7 +261,7 @@ One exception to this rule is `transaction_data` parameter, and the wallets that This specification defines the following new request parameters: `presentation_definition`: -: A string containing a Presentation Definition JSON object. See (#request_presentation_definition) for more details. Exactly one of `vp_query` or `presentation_definition` or `presentation_definition_uri` MUST be present in the Authorization Request. +: A string containing a Presentation Definition JSON object. See (#request_presentation_definition) for more details. Exactly one of the following parameters MUST be present in the Authorization Request:`vp_query`, `presentation_definition`, `presentation_definition_uri`, or a `scope` value representing a Presentation Definition. `presentation_definition_uri`: : A string containing an HTTPS URL pointing to a resource where a Presentation Definition JSON object can be retrieved. See (#request_presentation_definition_uri) for more details. Exactly one of `vp_query` or `presentation_definition` or `presentation_definition_uri` MUST be present in the Authorizat @@ -768,8 +768,7 @@ user privacy, but MUST NOT rely on it for security checks. The purpose of the `claim_sets` syntax is to provide a way for a verifier to describe alternative ways a given credential can satisfy the request. -The array ordering expresses the Verifier's preference for how the request must -be fulfilled. The first element in the array is the most preferred and the last +The array ordering expresses the Verifier's preference for how to fulfill the request. The first element in the array is the most preferred and the last element in the array is the least preferred. Verifiers SHOULD use the principle of least information disclosure to influence how they order these options. For example, a proof of age request should prioritize requesting an attribute like `age_over_18` over @@ -818,7 +817,7 @@ presentations. ## Format-specific Properties {#format_specific_properties} -The following format-specific properties are defined: +OpenID for Verifiable Presentations is Credential Format agnostic, i.e., it is designed to allow applications to request and receive Verifiable Presentations and Verifiable Credentials in any Credential Format. This section defines Credential Format Profiles for some of the known Credential Formats. Other specifications or deployments can define their own Credential Format Profiles: ### IETF SD-JWT VC {#format_vc_sd_jwt} @@ -831,10 +830,10 @@ the inheritance logic defined in [@!I-D.ietf-oauth-sd-jwt-vc]. ### Mobile Documents or mdocs (ISO/IEC 18013 and ISO/IEC 23220 series) {#format_mso_mdoc} -`doctype_values`: -: OPTIONAL. An array of strings that specifies allowed values for the -doctype of the requested Verifiable Credential. All elements in the array MUST -be valid doctype identifiers as defined in ISO 18013-5. +`doctype_value`: +: OPTIONAL. String that specifies an allowed value for the +doctype of the requested Verifiable Credential. It MUST +be a valid doctype identifier as defined in [@ISO.18013-5]. ## Claims Path Pointer {#claims_path_pointer} From 9c032a93f14bf677db2ecaf9c31157063a3ff01a Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Tue, 22 Oct 2024 13:33:16 +0200 Subject: [PATCH 38/49] Reword how credentials are to be returned, fix definition of request parameters --- openid-4-verifiable-presentations-1_0.md | 41 ++++++++++++------------ 1 file changed, 20 insertions(+), 21 deletions(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 8ae8a364..15d4fe35 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -261,14 +261,15 @@ One exception to this rule is `transaction_data` parameter, and the wallets that This specification defines the following new request parameters: `presentation_definition`: -: A string containing a Presentation Definition JSON object. See (#request_presentation_definition) for more details. Exactly one of the following parameters MUST be present in the Authorization Request:`vp_query`, `presentation_definition`, `presentation_definition_uri`, or a `scope` value representing a Presentation Definition. +: A string containing a Presentation Definition JSON object. See (#request_presentation_definition) for more details. `presentation_definition_uri`: -: A string containing an HTTPS URL pointing to a resource where a Presentation Definition JSON object can be retrieved. See (#request_presentation_definition_uri) for more details. Exactly one of `vp_query` or `presentation_definition` or `presentation_definition_uri` MUST be present in the Authorizat -ion Request. +: A string containing an HTTPS URL pointing to a resource where a Presentation Definition JSON object can be retrieved. See (#request_presentation_definition_uri) for more details. `vp_query`: -: A string containing a JSON-encoded VP Query as defined in (#vp_query). This parameter is OPTIONAL. Exactly one of `vp_query` or `presentation_definition` or `presentation_definition_uri` MUST be present in the Authorization Request. +: A string containing a JSON-encoded VP Query as defined in (#vp_query). + +Exactly one of the following parameters MUST be present in the Authorization Request: `vp_query`, `presentation_definition`, `presentation_definition_uri`, or a `scope` value representing a Presentation Definition. `client_metadata`: : OPTIONAL. A JSON object containing the Verifier metadata values. It MUST be UTF-8 encoded. The following metadata parameters MAY be used: @@ -695,9 +696,8 @@ the use case. The value of each element in the `options` array is an array of id elements in `credentials`. `required` -: OPTIONAL. A boolean flag which indicates whether this set of Credentials is required -to satisfy the particular use case at the Verifier. -If omitted, the effective value MUST be processed as `true`. +: OPTIONAL. A boolean which indicates whether this set of Credentials is required +to satisfy the particular use case at the Verifier. If omitted, the default value is `true`. `purpose` : OPTIONAL. A string, number or object specifying the purpose of the @@ -781,38 +781,37 @@ according to these rules, it MUST NOT return the respective Credential. The following rules apply for selecting Credentials via `credentials` and `credential_sets`: -- If `credential_sets` is not provided, the Verifier requests all +- If `credential_sets` is not provided, the Verifier requests presentations for all Credentials in `credentials` to be returned. -- Otherwise, the Verifier requests all of the Credential Set Queries in the `credential_sets` array - with `required` evaluated as true to be returned at a minimum and optionally any of the credential set queries - with `required` evaluated as false. +- Otherwise, the Verifier requests presentations of Credentials to be returned satisfying + - all of the Credential Set Queries in the `credential_sets` array where the `required` attribute is true or omitted, and + - optionally, any of the other Credential Set Queries. -For each credential set query inside the `credential_sets` array, in order to -satisfy the query, the Wallet MUST return a credential or credentials that -match to one of the `options` inside the object. It is typically +To satisfy a Credential Set Query, the Wallet MUST return a presentation of a Credential or of Credentials that +match to one of the `options` inside the Credential Set Query. It is typically expected that the Wallet presents the End-User with a choice of which -credential to present if multiple credentials match the query. +Credential to present if multiple Credentials match the query. Credentials not matching the respective constraints expressed within `credentials` MUST NOT be returned, i.e., they are treated as if they would not exist in the Wallet. If the Wallet cannot deliver all non-optional Credentials requested by the -Verifier according to these rules, it MUST NOT return any credential(s). +Verifier according to these rules, it MUST NOT return any Credential(s). #### User Interface Considerations {#vp_query_ui} While this specification provides the mechanisms for requesting different sets -of claims and credentials, it does not make assumptions about the user interface -of the Wallet, for example, if users can select which combination of credentials +of claims and Credentials, it does not make assumptions about the user interface +of the Wallet, for example, if users can select which combination of Credentials to present. #### Security Considerations {#vp_query_security} While the Verifier can specify various constraints both on the claims level and -the credential level as shown above, it MUST NOT rely on the Wallet to enforce +the Credential level as shown above, it MUST NOT rely on the Wallet to enforce these constraints. The Wallet is not controlled by the Verifier and the Verifier -MUST perform its own security checks on the returned credentials and +MUST perform its own security checks on the returned Credentials and presentations. ## Format-specific Properties {#format_specific_properties} @@ -934,7 +933,7 @@ Additional, more complex examples can be found in (#vp_query_examples). # Response {#response} -A VP Token is only returned if the corresponding Authorization Request contained a `presentation_definition` parameter, a `presentation_definition_uri` parameter, or a `scope` parameter representing a Presentation Definition (#vp_token_request). +A VP Token is only returned if the corresponding Authorization Request contained a `vp_query` parameter, a `presentation_definition` parameter, a `presentation_definition_uri` parameter, or a `scope` parameter representing a Presentation Definition (#vp_token_request). A VP Token can be returned in the Authorization Response or the Token Response depending on the Response Type used. See (#response_type_vp_token) for more details. From 2abe63c3a78abd3c185e1ca9596785013864ee87 Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Tue, 22 Oct 2024 13:50:58 +0200 Subject: [PATCH 39/49] Some editorial changes --- 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 15d4fe35..77ff4ddc 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -626,8 +626,8 @@ If the Verifier responds with any HTTP error response, the Wallet MUST terminate # Verifiable Presentation Query Language {#vp_query} The Verifiable Presentation Query Language (VP Query) is a JSON-encoded query -language that allows the Verifier to request the Wallet to present Verifiable -Credentials that match the query. The Verifier MAY encode constraints on the +language that allows the Verifier to request Verifiable +Presentations that match the query. The Verifier MAY encode constraints on the combinations of credentials and claims that are requested. The Wallet evaluates the query against the Verifiable Credentials it holds and returns the Verifiable Presentations that match the query. @@ -958,9 +958,9 @@ The behavior with respect to the VP Token is unspecified for any other individua When a VP Token is returned, the respective response MUST include the following parameters: `vp_token`: -: REQUIRED. The structure of this parameter depends on the Authorization Request: +: REQUIRED. The structure of this parameter depends on the query language used to request the presentations in the Authorization Request: * In case Presentation Exchange was used in the Authorization Request, it is a JSON String or JSON object that MUST contain a single Verifiable Presentation or an array of JSON Strings and JSON objects each of them containing a Verifiable Presentations. Each Verifiable Presentation MUST be represented as a JSON string (that is a base64url-encoded value) or a JSON object depending on a format as defined in Appendix A of [@!OpenID.VCI]. When a single Verifiable Presentation is returned, the array syntax MUST NOT be used. If Appendix A of [@!OpenID.VCI] defines a rule for encoding the respective Credential format in the Credential Response, this rules MUST also be followed when encoding Credentials of this format in the `vp_token` response parameter. Otherwise, this specification does not require any additional encoding when a Credential format is already represented as a JSON object or a JSON string. - * In case the `vp_query` parameter was used, this is a JSON-encoded object; the keys are the `id` values used for the Credential Queries in the VP Query, and the values are the Verifiable Presentations that match the respective Credential Query. The Verifiable Presentations are represented as strings or objects depending on the format as defined in Appendix A of [@!OpenID.VCI]. The same rules as above apply for encoding the Verifiable Presentations. + * If VP Query was used, this is a JSON-encoded object; the keys are the `id` values used for the Credential Queries in the VP Query, and the values are the Verifiable Presentations that match the respective Credential Query. The Verifiable Presentations are represented as strings or objects depending on the format as defined in Appendix A of [@!OpenID.VCI]. The same rules as above apply for encoding the Verifiable Presentations. `presentation_submission`: : REQUIRED. The `presentation_submission` element as defined in [@!DIF.PresentationExchange]. It contains mappings between the requested Verifiable Credentials and where to find them within the returned VP Token. This is expressed via elements in the `descriptor_map` array, known as Input Descriptor Mapping Objects. These objects contain a field called `path`, which, for this specification, MUST have the value `$` (top level root path) when only one Verifiable Presentation is contained in the VP Token, and MUST have the value `$[n]` (indexed path from root) when there are multiple Verifiable Presentations, where `n` is the index to select. Additional parameters can be defined by Credential Formats, see (#alternative_credential_formats) for details. From c632c25d7a903433b5d8c0067ff053d78d19e70e Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Tue, 22 Oct 2024 13:53:40 +0200 Subject: [PATCH 40/49] Fix examples --- examples/query_lang/complex_mdoc.json | 8 ++++---- examples/query_lang/multi_credentials.json | 2 +- examples/query_lang/simple_mdoc.json | 2 +- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/examples/query_lang/complex_mdoc.json b/examples/query_lang/complex_mdoc.json index 22d2146f..30326213 100644 --- a/examples/query_lang/complex_mdoc.json +++ b/examples/query_lang/complex_mdoc.json @@ -4,7 +4,7 @@ "id": "mdl-id", "format": "mso_mdoc", "meta": { - "doctype_values": ["org.iso.18013.5.1.mDL"] + "doctype_value": "org.iso.18013.5.1.mDL" }, "claims": [ { @@ -28,7 +28,7 @@ "id": "mdl-address", "format": "mso_mdoc", "meta": { - "doctype_values": ["org.iso.18013.5.1.mDL"] + "doctype_value": "org.iso.18013.5.1.mDL" }, "claims": [ { @@ -47,7 +47,7 @@ "id": "photo_card-id", "format": "mso_mdoc", "meta": { - "doctype_values": ["org.iso.23220.photoid.1"] + "doctype_value": "org.iso.23220.photoid.1" }, "claims": [ { @@ -71,7 +71,7 @@ "id": "photo_card-address", "format": "mso_mdoc", "meta": { - "doctype_values": ["org.iso.23220.photoid.1"] + "doctype_value": "org.iso.23220.photoid.1" }, "claims": [ { diff --git a/examples/query_lang/multi_credentials.json b/examples/query_lang/multi_credentials.json index 18354943..b62b25eb 100644 --- a/examples/query_lang/multi_credentials.json +++ b/examples/query_lang/multi_credentials.json @@ -16,7 +16,7 @@ "id": "mdl", "format": "mso_mdoc", "meta": { - "doctype_values": ["org.iso.7367.1.mVRC"] + "doctype_value": "org.iso.7367.1.mVRC" }, "claims": [ { diff --git a/examples/query_lang/simple_mdoc.json b/examples/query_lang/simple_mdoc.json index cf4f91cb..aa46d304 100644 --- a/examples/query_lang/simple_mdoc.json +++ b/examples/query_lang/simple_mdoc.json @@ -4,7 +4,7 @@ "id": "my_credential", "format": "mso_mdoc", "meta": { - "doctype_values": ["org.iso.7367.1.mVRC"] + "doctype_value": "org.iso.7367.1.mVRC" }, "claims": [ { From 69df934afb58053e58ddc467d10402de5f3dc0d7 Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Tue, 22 Oct 2024 14:17:55 +0200 Subject: [PATCH 41/49] Make presentation submission dependent on the query lang --- openid-4-verifiable-presentations-1_0.md | 35 +++++++++++++----------- 1 file changed, 19 insertions(+), 16 deletions(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 77ff4ddc..0c52c8f2 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -426,17 +426,18 @@ Content-Type: application/json Wallets MAY support requesting presentation of Verifiable Credentials using OAuth 2.0 scope values. -Such a scope value MUST be an alias for a well-defined Presentation Definition that will be -referred to in the `presentation_submission` response parameter. +Such a scope value MUST be an alias for +- a well-defined VP Query, or +- a well-defined Presentation Definition (for Presentation Exchange) that will be referred to in the `presentation_submission` response parameter. The specific scope values, and the mapping between a certain scope value and the respective -Presentation Definition is out of scope of this specification. +VP Query or Presentation Definition is out of scope of this specification. Possible options include normative text in a separate specification defining scope values along with a description of their -semantics or machine readable definitions in the Wallet's server metadata, mapping a scope value to an equivalent +semantics or machine-readable definitions in the Wallet's server metadata, mapping a scope value to an equivalent Presentation Definition JSON object. -Such definition of a scope value MUST allow the Verifier to determine the identifiers of the Presentation Definition and Input Descriptor(s) in the `presentation_submission` response parameter (`definition_id` and `descriptor_map.id` respectively) as well as the Credential formats and types in the `vp_token` response parameter defined in (#response-parameters). +If Presentation Exchange is used, the definition of the scope value MUST allow the Verifier to determine the identifiers of the Presentation Definition and Input Descriptor(s) in the `presentation_submission` response parameter (`definition_id` and `descriptor_map.id` respectively) as well as the Credential formats and types in the `vp_token` response parameter defined in (#response-parameters). It is RECOMMENDED to use collision-resistant scopes values. @@ -881,7 +882,7 @@ The following shows a non-normative, simplified example of a Credential: } ``` -The following shows examples of claims path queries and the respective selected +The following shows examples of claims path pointeres and the respective selected claims: - `["name"]`: The claim `name` with the value `Arthur Dent` is selected. @@ -899,7 +900,7 @@ claims: In detail, the array is processed by the Wallet from left to right as follows: 1. Select the root element of the Credential, i.e., the top-level JSON object. - 2. Process the query of the claims path query array from left to right: + 2. Process the query of the claims path pointer array from left to right: 1. If the component is a string, select the element in the respective key in the currently selected element(s). If any of the currently selected element(s) is not an object, abort processing and return an @@ -955,19 +956,19 @@ The behavior with respect to the VP Token is unspecified for any other individua ## Response Parameters {#response-parameters} -When a VP Token is returned, the respective response MUST include the following parameters: +When a VP Token is returned, the respective response includes the following parameters: `vp_token`: : REQUIRED. The structure of this parameter depends on the query language used to request the presentations in the Authorization Request: - * In case Presentation Exchange was used in the Authorization Request, it is a JSON String or JSON object that MUST contain a single Verifiable Presentation or an array of JSON Strings and JSON objects each of them containing a Verifiable Presentations. Each Verifiable Presentation MUST be represented as a JSON string (that is a base64url-encoded value) or a JSON object depending on a format as defined in Appendix A of [@!OpenID.VCI]. When a single Verifiable Presentation is returned, the array syntax MUST NOT be used. If Appendix A of [@!OpenID.VCI] defines a rule for encoding the respective Credential format in the Credential Response, this rules MUST also be followed when encoding Credentials of this format in the `vp_token` response parameter. Otherwise, this specification does not require any additional encoding when a Credential format is already represented as a JSON object or a JSON string. * If VP Query was used, this is a JSON-encoded object; the keys are the `id` values used for the Credential Queries in the VP Query, and the values are the Verifiable Presentations that match the respective Credential Query. The Verifiable Presentations are represented as strings or objects depending on the format as defined in Appendix A of [@!OpenID.VCI]. The same rules as above apply for encoding the Verifiable Presentations. + * In case Presentation Exchange was used, it is a JSON String or JSON object that MUST contain a single Verifiable Presentation or an array of JSON Strings and JSON objects each of them containing a Verifiable Presentations. Each Verifiable Presentation MUST be represented as a JSON string (that is a base64url-encoded value) or a JSON object depending on a format as defined in Appendix A of [@!OpenID.VCI]. When a single Verifiable Presentation is returned, the array syntax MUST NOT be used. If Appendix A of [@!OpenID.VCI] defines a rule for encoding the respective Credential format in the Credential Response, this rules MUST also be followed when encoding Credentials of this format in the `vp_token` response parameter. Otherwise, this specification does not require any additional encoding when a Credential format is already represented as a JSON object or a JSON string. `presentation_submission`: -: REQUIRED. The `presentation_submission` element as defined in [@!DIF.PresentationExchange]. It contains mappings between the requested Verifiable Credentials and where to find them within the returned VP Token. This is expressed via elements in the `descriptor_map` array, known as Input Descriptor Mapping Objects. These objects contain a field called `path`, which, for this specification, MUST have the value `$` (top level root path) when only one Verifiable Presentation is contained in the VP Token, and MUST have the value `$[n]` (indexed path from root) when there are multiple Verifiable Presentations, where `n` is the index to select. Additional parameters can be defined by Credential Formats, see (#alternative_credential_formats) for details. +: REQUIRED if Presentation Exchange was used for the request; MUST NOT be used otherwise. The `presentation_submission` element as defined in [@!DIF.PresentationExchange]. It contains mappings between the requested Verifiable Credentials and where to find them within the returned VP Token. This is expressed via elements in the `descriptor_map` array, known as Input Descriptor Mapping Objects. These objects contain a field called `path`, which, for this specification, MUST have the value `$` (top level root path) when only one Verifiable Presentation is contained in the VP Token, and MUST have the value `$[n]` (indexed path from root) when there are multiple Verifiable Presentations, where `n` is the index to select. Additional parameters can be defined by Credential Formats, see (#alternative_credential_formats) for details. Other parameters, such as `state` or `code` (from [@!RFC6749]), or `id_token` (from [@!OpenID.Core]), and `iss` (from [@RFC9207]) can be included in the response as defined in the respective specifications. `state` values MUST only contain ASCII URL safe characters (uppercase and lowercase letters, decimal digits, hyphen, period, underscore, and tilde). For the implementation considerations of a `state` parameter, see (#state_management). -The `presentation_submission` element MUST be included as a separate response parameter alongside the VP token. Clients MUST ignore any `presentation_submission` element included inside a Verifiable Presentation. +If Presentation Exchange was used for the request, the `presentation_submission` element MUST be included as a separate response parameter alongside the VP token. Clients MUST ignore any `presentation_submission` element included inside a Verifiable Presentation. Including the `presentation_submission` parameter as a separate response parameter allows the Wallet to provide the Verifier with additional information about the format and structure in advance of the processing of the VP Token, and can be used even with the Credential formats that do not allow for the direct inclusion of `presentation_submission` parameters inside a Credential itself. @@ -1125,7 +1126,7 @@ The following is a non-normative example of the payload of a JWT used in an Auth <{{examples/response/jarm_jwt_enc_only_vc_json_body.json}} -The JWT response document MUST include `vp_token` and `presentation_submission` parameters as defined in (#response-parameters). +The JWT response document MUST include the `vp_token` and, if Presentation Exchange was used in the request, the `presentation_submission` parameters as defined in (#response-parameters). The key material used for encryption and signing SHOULD be determined using existing metadata mechanisms. @@ -1222,10 +1223,12 @@ This document also defines the following additional error codes and error descri Verifiers MUST validate the VP Token in the following manner: -1. Determine the number of VPs returned in the VP Token and identify in which VP which requested VC is included, using the Input Descriptor Mapping Object(s) in the Presentation Submission. +1. Validate the format of the VP Token as defined in (#response-parameters) and verify the contents depending on the language used in the Authorization Request: + 1. If VP Query was used, ensure that the set of VPs returned satisfies all required Credential Sets (and optionally other Credential Sets). + 1. If Presentation Exchange was used, determine the number of VPs returned in the VP Token and identify in which VP which requested VC is included, using the Input Descriptor Mapping Object(s) in the Presentation Submission. 1. Validate the integrity, authenticity, and Holder Binding of any Verifiable Presentation provided in the VP Token according to the rules of the respective Presentation format. See (#preventing-replay) for the checks required to prevent replay of a VP. 1. Perform the checks on the Credential(s) specific to the Credential Format (i.e., validation of the signature(s) on each VC). -1. Confirm that the returned Credential(s) meet all criteria sent in the Presentation Definition in the Authorization Request. +1. Confirm that the returned Credential(s) meet all criteria defined in the query in the Authorization Request (e.g., Claims included in the presentation). 1. Perform the checks required by the Verifier's policy based on the set of trust requirements such as trust frameworks it belongs to (i.e., revocation checks), if applicable. Note: Some of the processing rules of the Presentation Definition and the Presentation Submission are outlined in [@!DIF.PresentationExchange]. @@ -1484,7 +1487,7 @@ Figure: Reference Design for Response Mode `direct_post` (4) The Verifier then sends the Authorization Request with the `request-id` as `state` and the `nonce` value created in step (1) to the Wallet. -(5) After authenticating the End-User and getting her consent to share the request Credentials, the Wallet sends the Authorization Response with the parameters `vp_token`, `presentation_submission` and `state` to the `response_uri` of the Verifier. +(5) After authenticating the End-User and getting her consent to share the request Credentials, the Wallet sends the Authorization Response with the parameters `vp_token`, `presentation_submission` (optional) and `state` to the `response_uri` of the Verifier. (6) The Verifier's Response URI checks whether the `state` value is a valid `request-id`. If so, it stores the Authorization Response data linked to the respective `transaction-id`. It then creates a `response_code` as fresh, cryptographically random number with sufficient entropy that it also links with the respective Authorization Response data. It then returns the `redirect_uri`, which includes the `response_code` to the Wallet. @@ -1521,7 +1524,7 @@ The Verifier MUST validate every individual Verifiable Presentation in an Author The `client_id` is used to detect the presentation of Verifiable Credentials to a party other than the one intended. This allows Verifiers take appropriate action in that case, such as not accepting the Verifiable Presentation. The `nonce` value binds the Presentation to a certain authentication transaction and allows the Verifier to detect injection of a Presentation in the flow, which is especially important in the flows where the Presentation is passed through the front-channel. -Note: Different formats for Verifiable Presentations and signature/proof schemes use different ways to represent the intended audience and the session binding. Some use claims to directly represent those values, others include the values into the calculation of cryptographic proofs. There are also different naming conventions across the different formats. The format of the respective presentation is determined from the format information in the presentation submission in the Authorization Response. +Note: Different formats for Verifiable Presentations and signature/proof schemes use different ways to represent the intended audience and the session binding. Some use claims to directly represent those values, others include the values into the calculation of cryptographic proofs. There are also different naming conventions across the different formats. In case Presentation Exchange is used in the Authorization Request, the format of the respective presentation is determined from the format information in the presentation submission in the Authorization Response. If VP Query was used, the format was defined by the Verifier in the request. The following is a non-normative example of the payload of a Verifiable Presentation of a format identifier `jwt_vp_json`: From 1012ba4393edfd1fffb124a4a012b16c1b1da884 Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Tue, 22 Oct 2024 15:50:16 +0200 Subject: [PATCH 42/49] Add examples --- openid-4-verifiable-presentations-1_0.md | 43 ++++++++++++++++++++---- 1 file changed, 37 insertions(+), 6 deletions(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 0c52c8f2..96c88207 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -920,7 +920,7 @@ In detail, the array is processed by the Wallet from left to right as follows: The result of the processing is the set of elements which is requested for presentation. -## Examples {#vp_query_examples} +## Examples {#vp_query_example} The following is a non-normative example of a VP Query that requests a Verifiable Credential of the format `vc+sd-jwt` with a type value of @@ -929,7 +929,7 @@ Credential of the format `vc+sd-jwt` with a type value of <{{examples/query_lang/simple.json}} -Additional, more complex examples can be found in (#vp_query_examples). +Additional, more complex examples can be found in (#more_vp_query_examples). # Response {#response} @@ -985,11 +985,25 @@ Location: https://client.example.org/cb# &vp_token=... ``` -The following is a non-normative example of a VP Token containing a single Verifiable Presentation: +### Examples (VP Query) {#response_vp_query} + +The following is a non-normative example of the contents of a VP Token +containing a single Verifiable Presentation after a request using VP Query like +the one shown in (#vp_query_example) (shortened for brevity): + +```json +{ + "my_credential": "eyJhbGci...QMA" +} +``` + +### Examples (Presentation Exchange) {#response_presentation_exchange} + +The following is a non-normative example of a VP Token containing a single Verifiable Presentation after a request using Presentation Exchange: <{{examples/response/vp_token_raw_ldp_vp.json}} -The following is a non-normative example of a `presentation_submission` parameter sent alongside a VP Token in the example above. It corresponds to a second Presentation Definition example in (#request_presentation_definition): +The following is a non-normative example of a `presentation_submission` parameter sent alongside a VP Token in the example above. It corresponds to the second Presentation Definition example in (#request_presentation_definition): <{{examples/response/presentation_submission.json}} @@ -999,7 +1013,7 @@ The following is a non-normative example of a VP Token containing multiple Verif <{{examples/response/vp_token_multiple_vps.json}} -The following is a non-normative example of a `presentation_submission` parameter sent alongside a VP Token in the example above. It does not correspond to any Presentation Definition examples in this specification: +The following is a non-normative example of a `presentation_submission` parameter sent alongside a VP Token in the example above. It does not correspond to any Presentation Definition example in this specification: <{{examples/response/presentation_submission_multiple_vps.json}} @@ -2297,6 +2311,16 @@ The profile includes the following elements: * Required Wallet and Verifier Metadata parameters and their values. * Additional restrictions on Authorization Request and Authorization Response parameters to ensure compliance with ISO/IEC TS 18013-7 [@ISO.18013-7] and ISO/IEC 23220-4 [@ISO.23220-4]. For instance, to comply with ISO/IEC TS 18013-7 [@ISO.18013-7], only the same-device flow is supported, the `request_uri` Authorization Request parameter is required, and the Authorization Response has to be encrypted. +### VP Query and Response + +An example request using the mdoc format is shown in (#more_vp_query_examples). The following is a non-normative example for a VP Token in the response: + +```json +{ + "my_credential": "" +} +``` + ### Presentation Request See ISO/IEC TS 18013-7 Annex B [@ISO.18013-7] and ISO/IEC 23220-4 Annex C [@ISO.23220-4] for the latest examples on how to use the `presentation_definition` parameter for requesting Credentials in the mdoc format. @@ -2367,6 +2391,13 @@ The following is a non-normative example of `client_metadata` request parameter <{{examples/client_metadata/sd_jwt_vc_verifier_metadata.json}} +### VP Query and Response + +A non-normative example request using the SD-JWT VC format is shown in (#vp_query_example). +The respective response is shown in (#response_vp_query). + +Additional examples are shown in (#more_vp_query_examples). + ### Presentation Request The following is a non-normative example of an Authorization Request: @@ -2458,7 +2489,7 @@ The following is a non-normative example of the payload of a Self-Issued ID Toke Note: The `nonce` and `aud` are set to the `nonce` of the request and the Client Identifier of the Verifier, respectively, in the same way as for the Verifier, Verifiable Presentations to prevent replay. -# Examples for VP Queries {#vp_query_examples} +# Examples for VP Queries {#more_vp_query_examples} The following is a non-normative example of a VP Query that requests a Verifiable Credential in the format `mso_mdoc` with the claims `vehicle_holder` and From ef8d48764296d42af7f70b42f7c3048307ef8e3c Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Tue, 22 Oct 2024 15:58:44 +0200 Subject: [PATCH 43/49] editorial --- 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 96c88207..79f7db39 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -988,8 +988,9 @@ Location: https://client.example.org/cb# ### Examples (VP Query) {#response_vp_query} The following is a non-normative example of the contents of a VP Token -containing a single Verifiable Presentation after a request using VP Query like -the one shown in (#vp_query_example) (shortened for brevity): +containing a single Verifiable Presentation in the SD-JWT VC format after a +request using VP Query like the one shown in (#vp_query_example) (shortened for +brevity): ```json { From ec4d524861fc820c515ebf137d74a0e4dc40f28d Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Tue, 22 Oct 2024 16:09:05 +0200 Subject: [PATCH 44/49] Update openid-4-verifiable-presentations-1_0.md Co-authored-by: Joseph Heenan --- 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 79f7db39..a1d81b25 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -882,7 +882,7 @@ The following shows a non-normative, simplified example of a Credential: } ``` -The following shows examples of claims path pointeres and the respective selected +The following shows examples of claims path pointers and the respective selected claims: - `["name"]`: The claim `name` with the value `Arthur Dent` is selected. From 92f74b79597f83f48c1ef761accbcece197d3fd0 Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Tue, 22 Oct 2024 16:30:56 +0200 Subject: [PATCH 45/49] Clarify language around selecting credentials --- openid-4-verifiable-presentations-1_0.md | 39 +++++++++++++----------- 1 file changed, 22 insertions(+), 17 deletions(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index a1d81b25..effb4baa 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -692,9 +692,10 @@ a particular use case with the Verifier. Each entry in `credential_sets` MUST be an object with the following properties: `options` -: REQUIRED: A non-empty array, where each value in the array represents a distinct query that satisfies -the use case. The value of each element in the `options` array is an array of identifiers which reference -elements in `credentials`. +: REQUIRED: A non-empty array, where each value in the array is a list +of Credential Query identifiers representing one set of Credentials that +satisfies the use case. The value of each element in the `options` array is an +array of identifiers which reference elements in `credentials`. `required` : OPTIONAL. A boolean which indicates whether this set of Credentials is required @@ -767,13 +768,16 @@ the request to the Wallet does not have access to the claim value. Therefore, Ve must treat restrictions expressed using `values` as a best-effort way to improve user privacy, but MUST NOT rely on it for security checks. -The purpose of the `claim_sets` syntax is to provide a way for a -verifier to describe alternative ways a given credential can satisfy the request. -The array ordering expresses the Verifier's preference for how to fulfill the request. The first element in the array is the most preferred and the last -element in the array is the least preferred. Verifiers SHOULD use the principle of -least information disclosure to influence how they order these options. For example, a -proof of age request should prioritize requesting an attribute like `age_over_18` over -an attribute like `birth_date`. +The purpose of the `claim_sets` syntax is to provide a way for a verifier to +describe alternative ways a given credential can satisfy the request. The array +ordering expresses the Verifier's preference for how to fulfill the request. The +first element in the array is the most preferred and the last element in the +array is the least preferred. Verifiers SHOULD use the principle of least +information disclosure to influence how they order these options. For example, a +proof of age request should prioritize requesting an attribute like +`age_over_18` over an attribute like `birth_date`. The `claim_sets` syntax is +not intended to define options the user can choose from, see (#vp_query_ui) for +more information. If the Wallet cannot deliver all claims requested by the Verifier according to these rules, it MUST NOT return the respective Credential. @@ -788,10 +792,9 @@ The following rules apply for selecting Credentials via `credentials` and `crede - all of the Credential Set Queries in the `credential_sets` array where the `required` attribute is true or omitted, and - optionally, any of the other Credential Set Queries. -To satisfy a Credential Set Query, the Wallet MUST return a presentation of a Credential or of Credentials that -match to one of the `options` inside the Credential Set Query. It is typically -expected that the Wallet presents the End-User with a choice of which -Credential to present if multiple Credentials match the query. +To satisfy a Credential Set Query, the Wallet MUST return a presentation of a +Credential or of Credentials that match to one of the `options` inside the +Credential Set Query. Credentials not matching the respective constraints expressed within `credentials` MUST NOT be returned, i.e., they are treated as if @@ -803,9 +806,11 @@ Verifier according to these rules, it MUST NOT return any Credential(s). #### User Interface Considerations {#vp_query_ui} While this specification provides the mechanisms for requesting different sets -of claims and Credentials, it does not make assumptions about the user interface -of the Wallet, for example, if users can select which combination of Credentials -to present. +of claims and Credentials, it does not define details about the user interface +of the Wallet, for example, if and how users can select which combination of +Credentials to present. However, it is typically expected that the Wallet +presents the End-User with a choice of which Credential(s) to present if +multiple of the sets of Credentials in `options` can satisfy the request. #### Security Considerations {#vp_query_security} From eb353e358e3b9ad94b66afac9578c69ab7fe636b Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Tue, 22 Oct 2024 20:31:06 +0200 Subject: [PATCH 46/49] Apply suggestions from code review Co-authored-by: Paul Bastian --- openid-4-verifiable-presentations-1_0.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index effb4baa..02e997e8 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -680,7 +680,8 @@ claims in the requested Credentials. `claim_sets`: : OPTIONAL. A non-empty array containing arrays of identifiers for -elements in `claims`. The rules for selecting claims to send are defined in (#selecting_claims). +elements in `claims` that specifies which combinations of `claims` for the Credential are requested. +The rules for selecting claims to send are defined in (#selecting_claims). Note that multiple Credential Queries in a request MAY request a presentation of the same Credential. @@ -748,13 +749,13 @@ and for selecting credentials. The following rules apply for selecting claims via `claims` and `claim_sets`: -- If `claims` is not provided, the Verifier requests all claims existing +- If `claims` is absent, the Verifier requests all claims existing in the Credential. -- If `claims` is provided, but `claim_sets` is not provided, +- If `claims` is present, but `claim_sets` is absent, the Verifier requests all claims listed in `claims`. -- Otherwise, the Verifier requests one combination of the claims listed in +- If both `claims` and `claim_sets` are present, the Verifier requests one combination of the claims listed in `claim_sets`. The order of the options conveyed in the `claim_sets` - array expresses the Verifiers' preference for what is returned; the Wallet MUST return + array expresses the Verifier's preference for what is returned; the Wallet MUST return the first option that it can satisfy. If the Wallet cannot satisfy any of the options, it MUST NOT return any claims. From fc06b5b331cd30f0c637fe72b036801362c26e6b Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Tue, 22 Oct 2024 21:45:18 +0200 Subject: [PATCH 47/49] Rename to DCQL, add purpose to examples --- examples/query_lang/complex_mdoc.json | 2 + .../query_lang/credentials_alternatives.json | 2 + openid-4-verifiable-presentations-1_0.md | 82 +++++++++---------- 3 files changed, 45 insertions(+), 41 deletions(-) diff --git a/examples/query_lang/complex_mdoc.json b/examples/query_lang/complex_mdoc.json index 30326213..dd13bb3b 100644 --- a/examples/query_lang/complex_mdoc.json +++ b/examples/query_lang/complex_mdoc.json @@ -89,12 +89,14 @@ ], "credential_sets": [ { + "purpose": "Identification", "options": [ [ "mdl-id" ], [ "photo_card-id" ] ] }, { + "purpose": "Proof of address", "required": false, "options": [ [ "mdl-address" ], diff --git a/examples/query_lang/credentials_alternatives.json b/examples/query_lang/credentials_alternatives.json index b4fa87c4..cdbec8df 100644 --- a/examples/query_lang/credentials_alternatives.json +++ b/examples/query_lang/credentials_alternatives.json @@ -60,6 +60,7 @@ ], "credential_sets": [ { + "purpose": "Identification", "options": [ [ "pid" ], [ "other_pid" ], @@ -67,6 +68,7 @@ ] }, { + "purpose": "Show your rewards card", "required": false, "options": [ [ "nice_to_have" ] diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 02e997e8..8a4907ab 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -222,8 +222,8 @@ Figure: Cross Device Flow OpenID for Verifiable Presentations extends existing OAuth 2.0 mechanisms as following: * A new `presentation_definition` Authorization Request parameter that uses the [@!DIF.PresentationExchange] syntax is defined to request presentation of Verifiable Credentials in arbitrary formats. See (#vp_token_request) for more details. -* A new query language is defined to enable requesting Verifiable Credentials in a more flexible way. See (#vp_query) for more details. -* A new `vp_query` Authorization Request parameter is defined to request presentation of Verifiable Credentials in the JSON-encoded VP Query format. See (#vp_token_request) for more details. +* A new query language, the Digital Credentials Query Language (DCQL), is defined to enable requesting Verifiable Credentials in an easier and more flexible way. See (#dcql_query) for more details. +* A new `dcql_query` Authorization Request parameter is defined to request presentation of Verifiable Credentials in the JSON-encoded DCQL format. See (#vp_token_request) for more details. * A new `vp_token` response parameter is defined to return Verifiable Presentations to the Verifier in either Authorization or Token Response depending on the Response Type. See (#response) for more details. * New Response Types `vp_token` and `vp_token id_token` are defined to request Verifiable Credentials to be returned in the Authorization Response (standalone or along with a Self-Issued ID Token [@!SIOPv2]). See (#response) for more details. * A new OAuth 2.0 Response Mode `direct_post` is defined to support sending the response across devices, or when the size of the response exceeds the redirect URL character size limitation. See (#response_mode_post) for more details. @@ -266,10 +266,10 @@ This specification defines the following new request parameters: `presentation_definition_uri`: : A string containing an HTTPS URL pointing to a resource where a Presentation Definition JSON object can be retrieved. See (#request_presentation_definition_uri) for more details. -`vp_query`: -: A string containing a JSON-encoded VP Query as defined in (#vp_query). +`dcql_query`: +: A string containing a JSON-encoded DCQL query as defined in (#dcql_query). -Exactly one of the following parameters MUST be present in the Authorization Request: `vp_query`, `presentation_definition`, `presentation_definition_uri`, or a `scope` value representing a Presentation Definition. +Exactly one of the following parameters MUST be present in the Authorization Request: `dcql_query`, `presentation_definition`, `presentation_definition_uri`, or a `scope` value representing a Presentation Definition. `client_metadata`: : OPTIONAL. A JSON object containing the Verifier metadata values. It MUST be UTF-8 encoded. The following metadata parameters MAY be used: @@ -427,11 +427,11 @@ Content-Type: application/json Wallets MAY support requesting presentation of Verifiable Credentials using OAuth 2.0 scope values. Such a scope value MUST be an alias for -- a well-defined VP Query, or +- a well-defined DCQL query, or - a well-defined Presentation Definition (for Presentation Exchange) that will be referred to in the `presentation_submission` response parameter. The specific scope values, and the mapping between a certain scope value and the respective -VP Query or Presentation Definition is out of scope of this specification. +DCQL query or Presentation Definition is out of scope of this specification. Possible options include normative text in a separate specification defining scope values along with a description of their semantics or machine-readable definitions in the Wallet's server metadata, mapping a scope value to an equivalent @@ -624,16 +624,16 @@ The Wallet then validates the request as specified in OAuth 2.0 [@RFC6749]. If the Verifier responds with any HTTP error response, the Wallet MUST terminate the process. -# Verifiable Presentation Query Language {#vp_query} +# Digital Credentials Query Language (DCQL) {#dcql_query} -The Verifiable Presentation Query Language (VP Query) is a JSON-encoded query -language that allows the Verifier to request Verifiable +The Digital Credentials Query Language (DCQL, pronounced [ˈdakl̩]) is a +JSON-encoded query language that allows the Verifier to request Verifiable Presentations that match the query. The Verifier MAY encode constraints on the -combinations of credentials and claims that are requested. The Wallet evaluates the -query against the Verifiable Credentials it holds and returns the Verifiable -Presentations that match the query. +combinations of credentials and claims that are requested. The Wallet evaluates +the query against the Verifiable Credentials it holds and returns Verifiable +Presentations matching the query. -A valid VP Query is defined as a JSON-encoded object with the following +A valid DCQL query is defined as a JSON-encoded object with the following top-level properties: `credentials`: @@ -644,9 +644,9 @@ that specify the requested Verifiable Credentials. : OPTIONAL. A non-empty array of credential set queries as defined in (#credential_set_query) that specifies additional constraints on which of the requested Verifiable Credentials to return. -Note: While this specification does not define additional top-level properties, -future extensions MAY define additional properties that modify the behavior of -the Wallet when processing the query. +Note: Future extensions may define additional properties both on the top level +and in the rest of the DCQL data structure. Implementations MUST ignore any +unknown properties. ## Credential Query {#credential_query} @@ -740,7 +740,7 @@ in the mdoc, e.g., `first_name`. If the `values` property is present, the Wallet SHOULD return the claim only if the type and value of the claim both match for at least one of the elements in the array. Details of the processing rules are defined in (#selecting_claims). -### Selecting Claims and Credentials {#vp_query_lang_processing_rules} +### Selecting Claims and Credentials {#dcql_query_lang_processing_rules} The following section describes the logic that applies for selecting claims and for selecting credentials. @@ -777,7 +777,7 @@ array is the least preferred. Verifiers SHOULD use the principle of least information disclosure to influence how they order these options. For example, a proof of age request should prioritize requesting an attribute like `age_over_18` over an attribute like `birth_date`. The `claim_sets` syntax is -not intended to define options the user can choose from, see (#vp_query_ui) for +not intended to define options the user can choose from, see (#dcql_query_ui) for more information. If the Wallet cannot deliver all claims requested by the Verifier @@ -804,7 +804,7 @@ they would not exist in the Wallet. If the Wallet cannot deliver all non-optional Credentials requested by the Verifier according to these rules, it MUST NOT return any Credential(s). -#### User Interface Considerations {#vp_query_ui} +#### User Interface Considerations {#dcql_query_ui} While this specification provides the mechanisms for requesting different sets of claims and Credentials, it does not define details about the user interface @@ -813,7 +813,7 @@ Credentials to present. However, it is typically expected that the Wallet presents the End-User with a choice of which Credential(s) to present if multiple of the sets of Credentials in `options` can satisfy the request. -#### Security Considerations {#vp_query_security} +#### Security Considerations {#dcql_query_security} While the Verifier can specify various constraints both on the claims level and the Credential level as shown above, it MUST NOT rely on the Wallet to enforce @@ -926,21 +926,21 @@ In detail, the array is processed by the Wallet from left to right as follows: The result of the processing is the set of elements which is requested for presentation. -## Examples {#vp_query_example} +## Examples {#dcql_query_example} -The following is a non-normative example of a VP Query that requests a Verifiable +The following is a non-normative example of a DCQL query that requests a Verifiable Credential of the format `vc+sd-jwt` with a type value of `https://credentials.example.com/identity_credential` and the claims `last_name`, `first_name`, and `address.street_address`: <{{examples/query_lang/simple.json}} -Additional, more complex examples can be found in (#more_vp_query_examples). +Additional, more complex examples can be found in (#more_dcql_query_examples). # Response {#response} -A VP Token is only returned if the corresponding Authorization Request contained a `vp_query` parameter, a `presentation_definition` parameter, a `presentation_definition_uri` parameter, or a `scope` parameter representing a Presentation Definition (#vp_token_request). +A VP Token is only returned if the corresponding Authorization Request contained a `dcql_query` parameter, a `presentation_definition` parameter, a `presentation_definition_uri` parameter, or a `scope` parameter representing a Presentation Definition (#vp_token_request). A VP Token can be returned in the Authorization Response or the Token Response depending on the Response Type used. See (#response_type_vp_token) for more details. @@ -966,7 +966,7 @@ When a VP Token is returned, the respective response includes the following para `vp_token`: : REQUIRED. The structure of this parameter depends on the query language used to request the presentations in the Authorization Request: - * If VP Query was used, this is a JSON-encoded object; the keys are the `id` values used for the Credential Queries in the VP Query, and the values are the Verifiable Presentations that match the respective Credential Query. The Verifiable Presentations are represented as strings or objects depending on the format as defined in Appendix A of [@!OpenID.VCI]. The same rules as above apply for encoding the Verifiable Presentations. + * If DCQL was used, this is a JSON-encoded object; the keys are the `id` values used for the Credential Queries in the DCQL query, and the values are the Verifiable Presentations that match the respective Credential Query. The Verifiable Presentations are represented as strings or objects depending on the format as defined in Appendix A of [@!OpenID.VCI]. The same rules as above apply for encoding the Verifiable Presentations. * In case Presentation Exchange was used, it is a JSON String or JSON object that MUST contain a single Verifiable Presentation or an array of JSON Strings and JSON objects each of them containing a Verifiable Presentations. Each Verifiable Presentation MUST be represented as a JSON string (that is a base64url-encoded value) or a JSON object depending on a format as defined in Appendix A of [@!OpenID.VCI]. When a single Verifiable Presentation is returned, the array syntax MUST NOT be used. If Appendix A of [@!OpenID.VCI] defines a rule for encoding the respective Credential format in the Credential Response, this rules MUST also be followed when encoding Credentials of this format in the `vp_token` response parameter. Otherwise, this specification does not require any additional encoding when a Credential format is already represented as a JSON object or a JSON string. `presentation_submission`: @@ -991,11 +991,11 @@ Location: https://client.example.org/cb# &vp_token=... ``` -### Examples (VP Query) {#response_vp_query} +### Examples (DCQL) {#response_dcql_query} The following is a non-normative example of the contents of a VP Token containing a single Verifiable Presentation in the SD-JWT VC format after a -request using VP Query like the one shown in (#vp_query_example) (shortened for +request using DCQL like the one shown in (#dcql_query_example) (shortened for brevity): ```json @@ -1245,7 +1245,7 @@ This document also defines the following additional error codes and error descri Verifiers MUST validate the VP Token in the following manner: 1. Validate the format of the VP Token as defined in (#response-parameters) and verify the contents depending on the language used in the Authorization Request: - 1. If VP Query was used, ensure that the set of VPs returned satisfies all required Credential Sets (and optionally other Credential Sets). + 1. If DCQL was used, ensure that the set of VPs returned satisfies all required Credential Sets (and optionally other Credential Sets). 1. If Presentation Exchange was used, determine the number of VPs returned in the VP Token and identify in which VP which requested VC is included, using the Input Descriptor Mapping Object(s) in the Presentation Submission. 1. Validate the integrity, authenticity, and Holder Binding of any Verifiable Presentation provided in the VP Token according to the rules of the respective Presentation format. See (#preventing-replay) for the checks required to prevent replay of a VP. 1. Perform the checks on the Credential(s) specific to the Credential Format (i.e., validation of the signature(s) on each VC). @@ -1545,7 +1545,7 @@ The Verifier MUST validate every individual Verifiable Presentation in an Author The `client_id` is used to detect the presentation of Verifiable Credentials to a party other than the one intended. This allows Verifiers take appropriate action in that case, such as not accepting the Verifiable Presentation. The `nonce` value binds the Presentation to a certain authentication transaction and allows the Verifier to detect injection of a Presentation in the flow, which is especially important in the flows where the Presentation is passed through the front-channel. -Note: Different formats for Verifiable Presentations and signature/proof schemes use different ways to represent the intended audience and the session binding. Some use claims to directly represent those values, others include the values into the calculation of cryptographic proofs. There are also different naming conventions across the different formats. In case Presentation Exchange is used in the Authorization Request, the format of the respective presentation is determined from the format information in the presentation submission in the Authorization Response. If VP Query was used, the format was defined by the Verifier in the request. +Note: Different formats for Verifiable Presentations and signature/proof schemes use different ways to represent the intended audience and the session binding. Some use claims to directly represent those values, others include the values into the calculation of cryptographic proofs. There are also different naming conventions across the different formats. In case Presentation Exchange is used in the Authorization Request, the format of the respective presentation is determined from the format information in the presentation submission in the Authorization Response. If DCQL was used, the format was defined by the Verifier in the request. The following is a non-normative example of the payload of a Verifiable Presentation of a format identifier `jwt_vp_json`: @@ -2318,9 +2318,9 @@ The profile includes the following elements: * Required Wallet and Verifier Metadata parameters and their values. * Additional restrictions on Authorization Request and Authorization Response parameters to ensure compliance with ISO/IEC TS 18013-7 [@ISO.18013-7] and ISO/IEC 23220-4 [@ISO.23220-4]. For instance, to comply with ISO/IEC TS 18013-7 [@ISO.18013-7], only the same-device flow is supported, the `request_uri` Authorization Request parameter is required, and the Authorization Response has to be encrypted. -### VP Query and Response +### DCQL Query and Response -An example request using the mdoc format is shown in (#more_vp_query_examples). The following is a non-normative example for a VP Token in the response: +An example DCQL query using the mdoc format is shown in (#more_dcql_query_examples). The following is a non-normative example for a VP Token in the response: ```json { @@ -2398,12 +2398,12 @@ The following is a non-normative example of `client_metadata` request parameter <{{examples/client_metadata/sd_jwt_vc_verifier_metadata.json}} -### VP Query and Response +### DCQL Query and Response -A non-normative example request using the SD-JWT VC format is shown in (#vp_query_example). -The respective response is shown in (#response_vp_query). +A non-normative example DCQL query using the SD-JWT VC format is shown in (#dcql_query_example). +The respective response is shown in (#response_dcql_query). -Additional examples are shown in (#more_vp_query_examples). +Additional examples are shown in (#more_dcql_query_examples). ### Presentation Request @@ -2496,15 +2496,15 @@ The following is a non-normative example of the payload of a Self-Issued ID Toke Note: The `nonce` and `aud` are set to the `nonce` of the request and the Client Identifier of the Verifier, respectively, in the same way as for the Verifier, Verifiable Presentations to prevent replay. -# Examples for VP Queries {#more_vp_query_examples} +# Examples for DCQL Queries {#more_dcql_query_examples} -The following is a non-normative example of a VP Query that requests a Verifiable +The following is a non-normative example of a DCQL query that requests a Verifiable Credential in the format `mso_mdoc` with the claims `vehicle_holder` and `first_name`: <{{examples/query_lang/simple_mdoc.json}} -The following is a non-normative example of a VP Query that requests multiple +The following is a non-normative example of a DCQL query that requests multiple Verifiable Credentials; all of them must be returned: <{{examples/query_lang/multi_credentials.json}} @@ -2521,7 +2521,7 @@ come from an mDL or a photoid Credential. <{{examples/query_lang/complex_mdoc.json}} -The following is a non-normative example of a VP Query that requests +The following is a non-normative example of a DCQL query that requests - the mandatory claims `last_name` and `date_of_birth`, and - either the claim `postal_code`, or, if that is not available, both of the claims `locality` and `region`. @@ -2778,7 +2778,7 @@ The technology described in this specification was made available from contribut -22 - * Introduced VP Query Language + * Introduced the Digital Credentials Query Language * add transaction data mechanism * remove `client_id_scheme` and turn it into a prefix of the `client_id`; this addresses a security issue with the previous solution * Clarified what can go in the `client_metadata` parameter From 5e39e18221482498453d630c8ce15af85d8a966e Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Wed, 23 Oct 2024 07:57:13 +0200 Subject: [PATCH 48/49] Apply suggestions from Brian's review Co-authored-by: Brian Campbell <71398439+bc-pi@users.noreply.github.com> --- openid-4-verifiable-presentations-1_0.md | 20 ++++++-------------- 1 file changed, 6 insertions(+), 14 deletions(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 8a4907ab..6d421420 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -676,7 +676,7 @@ Credential. `claims`: : OPTIONAL. A non-empty array of objects as defined in (#claims_query) that specifies -claims in the requested Credentials. +claims in the requested Credential. `claim_sets`: : OPTIONAL. A non-empty array containing arrays of identifiers for @@ -793,8 +793,8 @@ The following rules apply for selecting Credentials via `credentials` and `crede - all of the Credential Set Queries in the `credential_sets` array where the `required` attribute is true or omitted, and - optionally, any of the other Credential Set Queries. -To satisfy a Credential Set Query, the Wallet MUST return a presentation of a -Credential or of Credentials that match to one of the `options` inside the +To satisfy a Credential Set Query, the Wallet MUST return presentations of a +set of Credentials that match to one of the `options` inside the Credential Set Query. Credentials not matching the respective constraints expressed within @@ -852,7 +852,8 @@ indicates that all elements of the currently selected array(s) are to be selecte and a non-negative integer indicates that the respective index in an array is to be selected. The path is formed as follows: - - Start with an empty array. +Start with an empty array and repeat the following until the full path is formed. + - To address a particular claim within an object, append the key (claim name) to the array. - To address an element within an array, append the index to the array (as a @@ -1508,7 +1509,7 @@ Figure: Reference Design for Response Mode `direct_post` (4) The Verifier then sends the Authorization Request with the `request-id` as `state` and the `nonce` value created in step (1) to the Wallet. -(5) After authenticating the End-User and getting her consent to share the request Credentials, the Wallet sends the Authorization Response with the parameters `vp_token`, `presentation_submission` (optional) and `state` to the `response_uri` of the Verifier. +(5) After authenticating the End-User and getting their consent to share the request Credentials, the Wallet sends the Authorization Response with the parameters `vp_token`, `presentation_submission` (optional) and `state` to the `response_uri` of the Verifier. (6) The Verifier's Response URI checks whether the `state` value is a valid `request-id`. If so, it stores the Authorization Response data linked to the respective `transaction-id`. It then creates a `response_code` as fresh, cryptographically random number with sufficient entropy that it also links with the respective Authorization Response data. It then returns the `redirect_uri`, which includes the `response_code` to the Wallet. @@ -1953,15 +1954,6 @@ issuers in Self-Sovereign Identity ecosystems using TRAIN - - - BCP47 - - IETF - - - - From ff62fcff341443bfa95137cad5ba75c002fc6dd9 Mon Sep 17 00:00:00 2001 From: Daniel Fett Date: Wed, 23 Oct 2024 12:03:13 +0200 Subject: [PATCH 49/49] Address Brian's comments --- openid-4-verifiable-presentations-1_0.md | 63 ++++++++++++------------ 1 file changed, 31 insertions(+), 32 deletions(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 6d421420..a6cf5553 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -722,7 +722,7 @@ be present more than once. `path`: : REQUIRED if the Credential Format uses a JSON-based claims structure; MUST NOT -be present otherwise. The value MUST be a claims path pointer that specifies the path to the claim +be present otherwise. The value MUST be a non-empty array representing a claims path pointer that specifies the path to a claim within the Verifiable Credential, as defined in (#claims_path_pointer). `namespace`: @@ -847,7 +847,7 @@ be a valid doctype identifier as defined in [@ISO.18013-5]. A claims path pointer is a pointer into the JSON structure of the Verifiable Credential, identifying one or more claims. A claims path pointer MUST be a non-empty array of strings and non-negative integers. A string value -indicates that the respective key is to be selected, the special string value `*` +indicates that the respective key is to be selected, a null value indicates that all elements of the currently selected array(s) are to be selected; and a non-negative integer indicates that the respective index in an array is to be selected. The path is formed as follows: @@ -858,12 +858,37 @@ Start with an empty array and repeat the following until the full path is formed to the array. - To address an element within an array, append the index to the array (as a non-negative, 0-based integer). - - To address all elements within an array, append the string `*` to the array. + - To address all elements within an array, append a null value to the array. Verifiers MUST NOT point to the same claim more than once in a single query. Wallets SHOULD ignore such duplicate claim queries. -### Example +### Processing + +In detail, the array is processed by the Wallet from left to right as follows: + + 1. Select the root element of the Credential, i.e., the top-level JSON object. + 2. Process the query of the claims path pointer array from left to right: + 1. If the component is a string, select the element in the respective + key in the currently selected element(s). If any of the currently + selected element(s) is not an object, abort processing and return an + error. If the key does not exist in any element currently selected, + remove that element from the selection. + 2. If the component is null, select all elements of the currently + selected array(s). If any of the currently selected element(s) is not an + array, abort processing and return an error. + 3. If the component is a non-negative integer, select the element at + the respective index in the currently selected array(s). If any of the + currently selected element(s) is not an array, abort processing and + return an error. If the index does not exist in a selected array, remove + that array from the selection. + 3. If the set of elements currently selected is empty, abort processing and + return an error. + +The result of the processing is the set of elements which is requested for +presentation. + +### Claims Path Pointer Example {#claims_path_pointer_example} The following shows a non-normative, simplified example of a Credential: @@ -897,37 +922,11 @@ claims: selected. - `["address", "street_address"]`: The claim `street_address` with the value `42 Market Street` is selected. -- `["degrees", "*", "type"]`: All `type` claims in the `degrees` array are +- `["degrees", null, "type"]`: All `type` claims in the `degrees` array are selected. - `["nationalities", 1]`: The second nationality is selected. -- `[]` (empty array): The entire Credential is selected. - -### Processing - -In detail, the array is processed by the Wallet from left to right as follows: - - 1. Select the root element of the Credential, i.e., the top-level JSON object. - 2. Process the query of the claims path pointer array from left to right: - 1. If the component is a string, select the element in the respective - key in the currently selected element(s). If any of the currently - selected element(s) is not an object, abort processing and return an - error. If the key does not exist in any element currently selected, - remove that element from the selection. - 2. If the component is `*`, select all elements of the currently - selected array(s). If any of the currently selected element(s) is not an - array, abort processing and return an error. - 3. If the component is a non-negative integer, select the element at - the respective index in the currently selected array(s). If any of the - currently selected element(s) is not an array, abort processing and - return an error. If the index does not exist in a selected array, remove - that array from the selection. - 3. If the set of elements currently selected is empty, abort processing and - return an error. - -The result of the processing is the set of elements which is requested for -presentation. -## Examples {#dcql_query_example} +## DCQL Examples {#dcql_query_example} The following is a non-normative example of a DCQL query that requests a Verifiable Credential of the format `vc+sd-jwt` with a type value of