From 55d221f86f232315eb82b465f3b2c8463cb2d6e6 Mon Sep 17 00:00:00 2001 From: Torsten Lodderstedt Date: Wed, 27 Sep 2023 10:18:01 +0200 Subject: [PATCH 01/37] added sequence diagram --- diagrams/advanced_flow.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 diagrams/advanced_flow.md diff --git a/diagrams/advanced_flow.md b/diagrams/advanced_flow.md new file mode 100644 index 00000000..4dabc9c8 --- /dev/null +++ b/diagrams/advanced_flow.md @@ -0,0 +1,39 @@ +```plantuml +@startuml + +autonumber + +participant "User Agent" as u + +participant "Verifier" as r + +participant "Verifier Backend" as rb + +participant "Wallet" as w + +u --> r : use +activate r +r --> r: generate context_id + +r --> u: **discover request**\n(presentation_uri, context_id) +deactivate r +u --> w: **discover request**\n(presentation_uri, context_id) +activate w +w --> rb: **create presentation request** (context_id, iss, ..., w_nonce, \neph_key, wallet attestation, **wallet attestation pop(v_nonce)**) +rb --> w: **signed request object** (client_id, w_nonce, nonce, response_uri, \npresentation_definition, state) +w -> w: authenticate and\n authorize Verifier + +note over u, w: user authentication and credential selection/confirmation + +w -> w: create verifiable\npresentation (credential) +w --> rb: post response \n(vp_token, presentation_submission, state) +rb --> w: redirect_url +w --> u: response (response_code) +u --> r: response (response_code) +activate r +r --> rb: get presentation response\n (transaction_id, response_code) +rb --> r: presentation response +r -> r: validate presentation \n(incl. nonce binding) +r -> r: use presented credential +@enduml +``` \ No newline at end of file From b3dbced4fd96349f13da0dc5ee66fd482245ced1 Mon Sep 17 00:00:00 2001 From: Torsten Lodderstedt Date: Wed, 27 Sep 2023 11:48:15 +0200 Subject: [PATCH 02/37] first draft of the advanced flow --- diagrams/advanced_flow.md | 27 +++-- openid-4-verifiable-presentations-1_0.md | 127 ++++++++++++++++++++++- 2 files changed, 144 insertions(+), 10 deletions(-) diff --git a/diagrams/advanced_flow.md b/diagrams/advanced_flow.md index 4dabc9c8..d0aef279 100644 --- a/diagrams/advanced_flow.md +++ b/diagrams/advanced_flow.md @@ -5,22 +5,31 @@ autonumber participant "User Agent" as u -participant "Verifier" as r +box "Verifier" +participant "Frontend" as r +participant "Presentation Endpoint" as rp +participant "Response Endpoint" as rb +end box -participant "Verifier Backend" as rb - -participant "Wallet" as w +box "Wallet" +participant "Discovery Endpoint" as w +participant "Metadata" as wm +end box u --> r : use activate r -r --> r: generate context_id -r --> u: **discover request**\n(presentation_uri, context_id) +r --> u: **discover request**\n(presentation_uri, context) deactivate r -u --> w: **discover request**\n(presentation_uri, context_id) +u --> w: **discover request**\n(presentation_uri, context) activate w -w --> rb: **create presentation request** (context_id, iss, ..., w_nonce, \neph_key, wallet attestation, **wallet attestation pop(v_nonce)**) -rb --> w: **signed request object** (client_id, w_nonce, nonce, response_uri, \npresentation_definition, state) +w --> rp: **create presentation request** (context, iss, w_nonce, \nwallet attestation, **wallet attestation pop(v_nonce)**) +note over u, w: HTTP status code 401 signals need to authenticate +rp --> wm: get wallet metadata +wm --> rp: wallet metadata +rp -> rp: create and sign presentation request object (client_id, w_nonce, nonce, response_uri, \npresentation_definition, state) +rp --> w: **signed request object** (client_id, w_nonce, nonce, response_uri, \npresentation_definition, state) +note over u, w: do we want to allow unsigned presentation request objects, too? w -> w: authenticate and\n authorize Verifier note over u, w: user authentication and credential selection/confirmation diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index dd7a4c03..6bacd4c7 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -126,7 +126,7 @@ This specification supports any Credential format used in the Issuer-Holder-Veri Implementations can use any pre-existing OAuth 2.0 Grant Type and Response Type in conjunction with this specification to support different deployment architectures. -OpenID for Verifiable Presentations supports scenarios where the Authorization Request is sent both when the Verifier is interacting with the End-User using the device that is the same or different from the device on which requested Credential(s) are stored. +OpenID for Verifiable Presentations supports scenarios where the Authorization Request is sent both when the Verifier is interacting with the End-User using the device that is the same or different from the device on which requested Credential(s) are stored. It also allows the Verifier to first discover the Wallet's capabilities before the actual presentation request is created and passed to the wallet. This specification supports the response being sent using a redirect but also using an HTTPS POST request. This enables the response to be sent across devices, or when the response size exceeds the redirect URL character size limitation. @@ -215,6 +215,53 @@ Figure: Cross Device Flow (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. +## Advanced Flow with Wallet Capabilities Discovery {#adv_flow} + +Below is a diagram of a flow where the End-User presents a Credential to a Verifier interacting with the End-User on a different device as the device the Wallet resides on. In this case, the Verifier starts the flow by discovering the Wallet's capabilities through an additional message exchange. This is especially useful, if the Verifier starts the process using a URL serving as alias for a group of wallets (e.g. a custom scheme) but would like to tailor the presentation request to the particular wallet. + +In this flow, the Verifier first prepares a discovery request and sends it to the Wallet. The Wallet answers this request by sending an HTTP POST request to the Verifier, providing the Verifier with its Issuer URL and further parameters. The Verifier then creates a presentation request tailored to the capabilities and trust domain of the partiular Wallet and passes the request object in the HTTP POST response. The rest of the flow works like described in (#same_device). The discovery request can also be used in cross device scenarios, the Verifier would render the disovery message in a QR code. + +Note: The diagram does not illustrate all the optional features of this specification. + +Note: The usage of the Request URI as defined in [@!RFC9101] does not depend on any other choices made in the protocol extensibility points, i.e., it can be used in the Same Device Flow, too. + +!--- +~~~ ascii-art +~~~ ascii-art ++--------------+ +--------------+ +--------------+ +| User | | Verifier | | Wallet | ++--------------+ +--------------+ +--------------+ + | | | + | Interacts | | + |---------------->| | + | | (1) Discovery Request | + | | (Presentation Request URI) | + | |-------------------------------------------------->| + | | | + | | (2) Request the Request Object | + | |<--------------------------------------------------| + | | | + | | (2.5) Respond with the Request Object | + | | (Presentation Definition) | + | |-------------------------------------------------->| + | | | + | User Authentication / Consent | + | | | + | | (3) Authorization Response | + | | (VP Token with Verifiable Presentation(s)) | + | |<--------------------------------------------------| +~~~ +!--- +Figure: Cross Device Flow + +(1) The Verifier sends to the Wallet a Discovery Request that contains a Presentation URI from where to obtain the Request Object containing the actual Authorization Request object. + +(2) The Wallet sends an HTTPS POST request to the Presentation URI to retrieve the Request Object. + +(2.5) The HTTPS POST 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. + # Scope OpenID for Verifiable Presentations extends existing OAuth 2.0 mechanisms as following: @@ -228,6 +275,84 @@ OpenID for Verifiable Presentations extends existing OAuth 2.0 mechanisms as fol Presentation of Verifiable Credentials using OpenID for Verifiable Presentations can be combined with the user authentication using [@SIOPv2], and the issuance of OAuth 2.0 Access Tokens. +# Discovery Request + +The Discovery Request allows Verifers to discover the Wallet's capabilities before they create the actual presentation request. It also allows the Wallet to authenticate towards the Verifier and to provide the Verifier with additional data used in the creation of the request signature and to encrypt the request at the application layer (if needed). + +The Discovery Request message has the following parameters: + +`presentation_request_uri`: +: A string containing an HTTPS URL pointing to a resource under the control of the Verifier where the Wallet is supposed to obtain the presentation request object. + +`context`: +: A string identifying the context of the discovery request from the perspective of the Verifier. The value is opqaue to the Wallet, it MUST pass this value to the Presentation Endpoint Request (see below). + +The Discovery Request is represented as a JSON object, where all parameters are top level JSON claims. + +The following is an example request: + +```JSON +{ + "presentation_request_uri": "verifier.example.com/presentation_request", + "context": "register_kyc" +} +``` + +The Discovery Request is either send the Discovery Endpoint of the Wallet or it is rendered as a QR Code and scanned with the Wallet or a camera app. + +Note: the Discovery Request intentionally does not use OAuth parameters, such as a `client_id`. The idea is to allow the Verifier to select the Client Identifier it wants to use for interacting with the Wallet after it has determined the trust mechanisms and domains the wallet supports. + +## Discovery Endpoint + +This is an HTTPS endpoint offered by the Wallet. The Discovery Request MUST be sent as a HTTPS GET request or an HTTP redirect to the Discovery Endpoint URL defined in (#wallet-metadata) + +The HTTPS URL contains a single URI query parameter `discovery` where the value is the JSON object as defined above. + +## Presentation Endpoint + +The Presentation Endpoint is an HTTPS endpoint exposed by the Verifier. + +### Presentation Request + +Presentation Requests MUST be HTTPS POST requests with the "application/json" media type. + +The follwowing parameters are defined: + +`context`: +: A JSON String containing the value of the corresponding Discovery Request's `context` parameter. + +`issuer`: +: A JSON containg a HTTPS URL designating the Issuer URL of the Wallet. + +`w_nonce`: +: A JSON String containg a cryptographic nonce the Verifier MUST use when creating the signed presentation request object. + +`client_assertion` +: A JSON String containing a wallet attestation along with a proof of posession of the confiration key as defined in [@!I-D.ietf-oauth-attestation-based-client-auth]. This assertion is used to authenticate the Wallet towards the Verifier. + +### Presentation Response + +Presentation Response MUST be HTTPS POST response with the "application/json" media type. + +The follwowing parameters are defined: + +`request`: +: A JSON String containing the signed request object as defined in [@RFC9101]. It MUST fulfill the requirements as defined in (#vp_token_request). + + +### Presentation Error Response + +The error code `401` signals to the wallet that it needs to authenticate to the Verifier. In this case, the error response SHOULD contain a `WWW-Authenticate` header for every attestation method the Verifier supports. + +This is an example for the wallet attestation method as specified above. The `WWW-Authenticate` contains the nonce value the Wallet MUST use in the calculation of the proof of possession of the respective wallet attestation. + +``` +HTTP/1.1 401 Unauthorized + WWW-Authenticate: wallet-attestation error="use_nonce", \ + error_description="Verifier requires wallet attestation" + Nonce: eyJ7S_zG.eyJH0-Z.HX4w-7v +``` + # Authorization Request {#vp_token_request} The Authorization Request follows the definition given in [@!RFC6749] taking into account the recommendations given in [@!I-D.ietf-oauth-security-topics]. From f261533ed732a084f8267cc7b5e33bf15cf907c6 Mon Sep 17 00:00:00 2001 From: Torsten Lodderstedt Date: Wed, 27 Sep 2023 11:48:44 +0200 Subject: [PATCH 03/37] discovery example --- examples/discovery/discover.json | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 examples/discovery/discover.json diff --git a/examples/discovery/discover.json b/examples/discovery/discover.json new file mode 100644 index 00000000..ab8522f3 --- /dev/null +++ b/examples/discovery/discover.json @@ -0,0 +1,4 @@ +{ + "presentation_request_uri": "verifier.example.com/presentation_request", + "context": "register_kyc" +} \ No newline at end of file From 2758f55537a418a062c4bdff5489df1c278b3540 Mon Sep 17 00:00:00 2001 From: Torsten Lodderstedt Date: Wed, 4 Oct 2023 13:08:31 +0200 Subject: [PATCH 04/37] Update openid-4-verifiable-presentations-1_0.md Co-authored-by: Kristina <52878547+Sakurann@users.noreply.github.com> --- openid-4-verifiable-presentations-1_0.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 6bacd4c7..82e5e087 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -126,7 +126,9 @@ This specification supports any Credential format used in the Issuer-Holder-Veri Implementations can use any pre-existing OAuth 2.0 Grant Type and Response Type in conjunction with this specification to support different deployment architectures. -OpenID for Verifiable Presentations supports scenarios where the Authorization Request is sent both when the Verifier is interacting with the End-User using the device that is the same or different from the device on which requested Credential(s) are stored. It also allows the Verifier to first discover the Wallet's capabilities before the actual presentation request is created and passed to the wallet. +OpenID for Verifiable Presentations supports scenarios where the Authorization Request is sent both when the Verifier is interacting with the End-User using the device that is the same or different from the device on which requested Credential(s) are stored. + +This specification also provides the Verifier an option to first discover the Wallet's capabilities before the actual presentation request is created and passed to the Wallet. This specification supports the response being sent using a redirect but also using an HTTPS POST request. This enables the response to be sent across devices, or when the response size exceeds the redirect URL character size limitation. From f64854e5137b728c2ef3bb987a4efc979bb1938c Mon Sep 17 00:00:00 2001 From: Torsten Lodderstedt Date: Wed, 4 Oct 2023 13:16:14 +0200 Subject: [PATCH 05/37] changed into to overall description --- openid-4-verifiable-presentations-1_0.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 6bacd4c7..19408495 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -217,7 +217,9 @@ Figure: Cross Device Flow ## Advanced Flow with Wallet Capabilities Discovery {#adv_flow} -Below is a diagram of a flow where the End-User presents a Credential to a Verifier interacting with the End-User on a different device as the device the Wallet resides on. In this case, the Verifier starts the flow by discovering the Wallet's capabilities through an additional message exchange. This is especially useful, if the Verifier starts the process using a URL serving as alias for a group of wallets (e.g. a custom scheme) but would like to tailor the presentation request to the particular wallet. +Below is a diagram shows an advanced flow based on what is describe in ({#same_device}). + +In this case, the Verifier starts the flow by discovering the Wallet's capabilities through an additional message exchange. This is especially useful, if the Verifier starts the process using a URL serving as alias for a group of wallets (e.g. a custom scheme) but would like to tailor the presentation request to the particular wallet. In this flow, the Verifier first prepares a discovery request and sends it to the Wallet. The Wallet answers this request by sending an HTTP POST request to the Verifier, providing the Verifier with its Issuer URL and further parameters. The Verifier then creates a presentation request tailored to the capabilities and trust domain of the partiular Wallet and passes the request object in the HTTP POST response. The rest of the flow works like described in (#same_device). The discovery request can also be used in cross device scenarios, the Verifier would render the disovery message in a QR code. From c3cbb890fe18d789acb045b4ae47c378d4487952 Mon Sep 17 00:00:00 2001 From: Torsten Lodderstedt Date: Wed, 4 Oct 2023 13:20:41 +0200 Subject: [PATCH 06/37] Update openid-4-verifiable-presentations-1_0.md Co-authored-by: Giuseppe De Marco --- 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 81f517c2..5831528b 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -223,7 +223,7 @@ Below is a diagram shows an advanced flow based on what is describe in ({#same_d In this case, the Verifier starts the flow by discovering the Wallet's capabilities through an additional message exchange. This is especially useful, if the Verifier starts the process using a URL serving as alias for a group of wallets (e.g. a custom scheme) but would like to tailor the presentation request to the particular wallet. -In this flow, the Verifier first prepares a discovery request and sends it to the Wallet. The Wallet answers this request by sending an HTTP POST request to the Verifier, providing the Verifier with its Issuer URL and further parameters. The Verifier then creates a presentation request tailored to the capabilities and trust domain of the partiular Wallet and passes the request object in the HTTP POST response. The rest of the flow works like described in (#same_device). The discovery request can also be used in cross device scenarios, the Verifier would render the disovery message in a QR code. +In this flow, the Verifier first prepares a discovery request to be provided to the Wallet. The Wallet answers this request by sending an HTTP POST request to the Verifier, providing the Verifier with its Issuer URL and further parameters. The Verifier then creates a presentation request tailored to the capabilities and trust domain of the particular Wallet and passes the request object in the HTTP POST response. The rest of the flow works like described in (#same_device). The discovery request can also be used in cross device scenarios where the Verifier would render the discovery message in a QR code. Note: The diagram does not illustrate all the optional features of this specification. From 92579f6b667dd5eccf343993456fb052c00dc42b Mon Sep 17 00:00:00 2001 From: Torsten Lodderstedt Date: Wed, 4 Oct 2023 13:22:05 +0200 Subject: [PATCH 07/37] added text re issuer URL --- 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 5831528b..9d6c6baf 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -223,7 +223,7 @@ Below is a diagram shows an advanced flow based on what is describe in ({#same_d In this case, the Verifier starts the flow by discovering the Wallet's capabilities through an additional message exchange. This is especially useful, if the Verifier starts the process using a URL serving as alias for a group of wallets (e.g. a custom scheme) but would like to tailor the presentation request to the particular wallet. -In this flow, the Verifier first prepares a discovery request to be provided to the Wallet. The Wallet answers this request by sending an HTTP POST request to the Verifier, providing the Verifier with its Issuer URL and further parameters. The Verifier then creates a presentation request tailored to the capabilities and trust domain of the particular Wallet and passes the request object in the HTTP POST response. The rest of the flow works like described in (#same_device). The discovery request can also be used in cross device scenarios where the Verifier would render the discovery message in a QR code. +In this flow, the Verifier first prepares a discovery request to be provided to the Wallet. The Wallet answers this request by sending an HTTP POST request to the Verifier, providing the Verifier with its Issuer URL (identifying the wallet provider and used to fetch wallet metadata) and further parameters. The Verifier then creates a presentation request tailored to the capabilities and trust domain of the particular Wallet and passes the request object in the HTTP POST response. The rest of the flow works like described in (#same_device). The discovery request can also be used in cross device scenarios where the Verifier would render the discovery message in a QR code. Note: The diagram does not illustrate all the optional features of this specification. From 77c2af29656a5916b25a56c1f67d3f5736c7a69c Mon Sep 17 00:00:00 2001 From: Torsten Lodderstedt Date: Wed, 4 Oct 2023 13:22:51 +0200 Subject: [PATCH 08/37] Update openid-4-verifiable-presentations-1_0.md Co-authored-by: Giuseppe De Marco --- 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 9d6c6baf..a640b1ee 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -304,7 +304,7 @@ The following is an example request: The Discovery Request is either send the Discovery Endpoint of the Wallet or it is rendered as a QR Code and scanned with the Wallet or a camera app. -Note: the Discovery Request intentionally does not use OAuth parameters, such as a `client_id`. The idea is to allow the Verifier to select the Client Identifier it wants to use for interacting with the Wallet after it has determined the trust mechanisms and domains the wallet supports. +Note: the Discovery Request intentionally does not use OAuth parameters, such as a `client_id`. The idea is to allow the Verifier to select the Client Identifier it wants to use for interacting with the Wallet after it has determined the trust mechanisms and domains the Wallet supports. ## Discovery Endpoint From 2763e59a312d282f643aa104fb93b9c697868e4c Mon Sep 17 00:00:00 2001 From: Torsten Lodderstedt Date: Wed, 4 Oct 2023 13:23:17 +0200 Subject: [PATCH 09/37] Update openid-4-verifiable-presentations-1_0.md Co-authored-by: Giuseppe De Marco --- 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 a640b1ee..6397cc89 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -308,7 +308,7 @@ Note: the Discovery Request intentionally does not use OAuth parameters, such as ## Discovery Endpoint -This is an HTTPS endpoint offered by the Wallet. The Discovery Request MUST be sent as a HTTPS GET request or an HTTP redirect to the Discovery Endpoint URL defined in (#wallet-metadata) +This is an HTTPS endpoint offered by the Wallet. The Discovery Request MUST be sent as an HTTPS GET request or an HTTP redirect to the Discovery Endpoint URL defined in (#wallet-metadata). The HTTPS URL contains a single URI query parameter `discovery` where the value is the JSON object as defined above. From e0a72b14e539ddfc60cc34ddf483cb19d862cb16 Mon Sep 17 00:00:00 2001 From: Torsten Lodderstedt Date: Wed, 4 Oct 2023 13:25:54 +0200 Subject: [PATCH 10/37] Update openid-4-verifiable-presentations-1_0.md Co-authored-by: Giuseppe De Marco --- 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 6397cc89..048bd965 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -326,7 +326,7 @@ The follwowing parameters are defined: : A JSON String containing the value of the corresponding Discovery Request's `context` parameter. `issuer`: -: A JSON containg a HTTPS URL designating the Issuer URL of the Wallet. +: A JSON containing an HTTPS URL designating the Issuer URL of the Wallet. `w_nonce`: : A JSON String containg a cryptographic nonce the Verifier MUST use when creating the signed presentation request object. From ef1773c4573d88a4e4f930f7e0ab92106747aad3 Mon Sep 17 00:00:00 2001 From: Torsten Lodderstedt Date: Wed, 4 Oct 2023 13:26:18 +0200 Subject: [PATCH 11/37] Update openid-4-verifiable-presentations-1_0.md Co-authored-by: Giuseppe De Marco --- 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 048bd965..cb9b2bc3 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -310,7 +310,7 @@ Note: the Discovery Request intentionally does not use OAuth parameters, such as This is an HTTPS endpoint offered by the Wallet. The Discovery Request MUST be sent as an HTTPS GET request or an HTTP redirect to the Discovery Endpoint URL defined in (#wallet-metadata). -The HTTPS URL contains a single URI query parameter `discovery` where the value is the JSON object as defined above. +The HTTPS URL MUST contain a single URI query parameter `discovery` where the value is the JSON object as defined above. ## Presentation Endpoint From dd4831f5f8f583ec440cbc8ac193f4921663672d Mon Sep 17 00:00:00 2001 From: Torsten Lodderstedt Date: Wed, 4 Oct 2023 13:27:07 +0200 Subject: [PATCH 12/37] Update openid-4-verifiable-presentations-1_0.md Co-authored-by: Giuseppe De Marco --- 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 cb9b2bc3..b98792e0 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -332,7 +332,7 @@ The follwowing parameters are defined: : A JSON String containg a cryptographic nonce the Verifier MUST use when creating the signed presentation request object. `client_assertion` -: A JSON String containing a wallet attestation along with a proof of posession of the confiration key as defined in [@!I-D.ietf-oauth-attestation-based-client-auth]. This assertion is used to authenticate the Wallet towards the Verifier. +: A JSON String containing a Wallet attestation along with a proof of possession of the configuration key as defined in [@!I-D.ietf-oauth-attestation-based-client-auth]. This assertion is used to authenticate the Wallet towards the Verifier. ### Presentation Response From 540e6c8a61389c0aa8e4bbdbd49de7a359f2dfaf Mon Sep 17 00:00:00 2001 From: Torsten Lodderstedt Date: Wed, 4 Oct 2023 13:27:20 +0200 Subject: [PATCH 13/37] Update openid-4-verifiable-presentations-1_0.md Co-authored-by: Giuseppe De Marco --- 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 b98792e0..8aeae470 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -346,7 +346,7 @@ The follwowing parameters are defined: ### Presentation Error Response -The error code `401` signals to the wallet that it needs to authenticate to the Verifier. In this case, the error response SHOULD contain a `WWW-Authenticate` header for every attestation method the Verifier supports. +The error code `401` signals to the Wallet that it needs to authenticate to the Verifier. In this case, the error response SHOULD contain a `WWW-Authenticate` header for every attestation method the Verifier supports. This is an example for the wallet attestation method as specified above. The `WWW-Authenticate` contains the nonce value the Wallet MUST use in the calculation of the proof of possession of the respective wallet attestation. From b73cd104e1d4618ac2200a04941aaf49e53b01c2 Mon Sep 17 00:00:00 2001 From: Torsten Lodderstedt Date: Wed, 4 Oct 2023 13:27:45 +0200 Subject: [PATCH 14/37] Update openid-4-verifiable-presentations-1_0.md Co-authored-by: Giuseppe De Marco --- 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 8aeae470..74308969 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -348,7 +348,7 @@ The follwowing parameters are defined: The error code `401` signals to the Wallet that it needs to authenticate to the Verifier. In this case, the error response SHOULD contain a `WWW-Authenticate` header for every attestation method the Verifier supports. -This is an example for the wallet attestation method as specified above. The `WWW-Authenticate` contains the nonce value the Wallet MUST use in the calculation of the proof of possession of the respective wallet attestation. +Below a non-normative example for the Wallet attestation method as specified above. The `WWW-Authenticate` contains the nonce value the Wallet MUST use in the calculation of the proof of possession of the wallet attestation. ``` HTTP/1.1 401 Unauthorized From 47e91d3fdeebcc844e8c71e4df984288ac2a9364 Mon Sep 17 00:00:00 2001 From: Torsten Lodderstedt Date: Wed, 4 Oct 2023 13:31:41 +0200 Subject: [PATCH 15/37] changed section title and first sentence --- openid-4-verifiable-presentations-1_0.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 74308969..96ef7418 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -217,9 +217,9 @@ Figure: Cross Device Flow (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. -## Advanced Flow with Wallet Capabilities Discovery {#adv_flow} +## Same Device Flow with Wallet Capabilities Discovery {#adv_flow} -Below is a diagram shows an advanced flow based on what is describe in ({#same_device}). +Below is a diagram shows a flow a describe in ({#same_device}) with an additional pre-step used to discover the Wallet's capabilities and tailor the actual request to it. In this case, the Verifier starts the flow by discovering the Wallet's capabilities through an additional message exchange. This is especially useful, if the Verifier starts the process using a URL serving as alias for a group of wallets (e.g. a custom scheme) but would like to tailor the presentation request to the particular wallet. From 3ca1dc0584172cbb04b0f8f5bef1e4761861efee Mon Sep 17 00:00:00 2001 From: Torsten Lodderstedt Date: Wed, 4 Oct 2023 13:34:47 +0200 Subject: [PATCH 16/37] Update openid-4-verifiable-presentations-1_0.md Co-authored-by: Kristina <52878547+Sakurann@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 96ef7418..5be3b0c2 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -258,7 +258,7 @@ 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 a Discovery Request that contains a Presentation URI from where to obtain the Request Object containing the actual Authorization Request object. +(1) The Verifier sends to the Wallet a Discovery Request that contains a Presentation URI to where Wallet can send information about itself and obtain the Request Object containing the actual Authorization Request. (2) The Wallet sends an HTTPS POST request to the Presentation URI to retrieve the Request Object. From 47752aa1c16fcae101a310348e94429291c7703e Mon Sep 17 00:00:00 2001 From: Torsten Lodderstedt Date: Wed, 4 Oct 2023 13:35:18 +0200 Subject: [PATCH 17/37] Update openid-4-verifiable-presentations-1_0.md Co-authored-by: Kristina <52878547+Sakurann@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 5be3b0c2..1cfb9a3b 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -260,7 +260,7 @@ Figure: Cross Device Flow (1) The Verifier sends to the Wallet a Discovery Request that contains a Presentation URI to where Wallet can send information about itself and obtain the Request Object containing the actual Authorization Request. -(2) The Wallet sends an HTTPS POST request to the Presentation URI to retrieve the Request Object. +(2) The Wallet sends an HTTPS POST request to the Presentation URI that can contain information about wallet's endpoint, capabilities and attestation. (2.5) The HTTPS POST 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. From 9ae3e302fb04eb8322c75ec11d631dbceceb7daa Mon Sep 17 00:00:00 2001 From: Torsten Lodderstedt Date: Wed, 4 Oct 2023 13:39:09 +0200 Subject: [PATCH 18/37] detailed step 2 --- 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 1cfb9a3b..fdf9dd39 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -260,7 +260,7 @@ Figure: Cross Device Flow (1) The Verifier sends to the Wallet a Discovery Request that contains a Presentation URI to where Wallet can send information about itself and obtain the Request Object containing the actual Authorization Request. -(2) The Wallet sends an HTTPS POST request to the Presentation URI that can contain information about wallet's endpoint, capabilities and attestation. +(2) The Wallet sends an HTTPS POST request to the Presentation URI. The request contains information about the context as defined by the Verifier, the wallet's Issuer URL and may contain further parameters (including a wallet attestation). (2.5) The HTTPS POST 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. From 03d291ff88a0a8bdf3190e267ee4732e20e1539f Mon Sep 17 00:00:00 2001 From: Torsten Lodderstedt Date: Wed, 4 Oct 2023 13:40:45 +0200 Subject: [PATCH 19/37] Update openid-4-verifiable-presentations-1_0.md Co-authored-by: Kristina <52878547+Sakurann@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 fdf9dd39..81b9ea09 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -262,7 +262,7 @@ Figure: Cross Device Flow (2) The Wallet sends an HTTPS POST request to the Presentation URI. The request contains information about the context as defined by the Verifier, the wallet's Issuer URL and may contain further parameters (including a wallet attestation). -(2.5) The HTTPS POST 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 HTTPS POST response returns the Request Object containing Authorization Request parameters based on the information specific to the Wallet that it received in step (2). 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. From ed383468a1ab5cfa975caf15cb471781ac840256 Mon Sep 17 00:00:00 2001 From: Torsten Lodderstedt Date: Wed, 4 Oct 2023 13:46:12 +0200 Subject: [PATCH 20/37] Update openid-4-verifiable-presentations-1_0.md Co-authored-by: Kristina <52878547+Sakurann@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 81b9ea09..97242ca1 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -283,7 +283,7 @@ Presentation of Verifiable Credentials using OpenID for Verifiable Presentations The Discovery Request allows Verifers to discover the Wallet's capabilities before they create the actual presentation request. It also allows the Wallet to authenticate towards the Verifier and to provide the Verifier with additional data used in the creation of the request signature and to encrypt the request at the application layer (if needed). -The Discovery Request message has the following parameters: +This specification defines the following new parameters for the Discovery Request message: `presentation_request_uri`: : A string containing an HTTPS URL pointing to a resource under the control of the Verifier where the Wallet is supposed to obtain the presentation request object. From 95fcfb9e66a7470d6da760d1ce301f10ce72eb8a Mon Sep 17 00:00:00 2001 From: Torsten Lodderstedt Date: Thu, 5 Oct 2023 11:10:19 +0200 Subject: [PATCH 21/37] Update openid-4-verifiable-presentations-1_0.md Co-authored-by: Kristina <52878547+Sakurann@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 97242ca1..34eb815b 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -291,7 +291,7 @@ This specification defines the following new parameters for the Discovery Reques `context`: : A string identifying the context of the discovery request from the perspective of the Verifier. The value is opqaue to the Wallet, it MUST pass this value to the Presentation Endpoint Request (see below). -The Discovery Request is represented as a JSON object, where all parameters are top level JSON claims. +The Discovery Request MUST be represented as a JSON object with all parameters as top-level JSON claims. The following is an example request: From 78345d455f83430096df3437d9cc717cc685bfb0 Mon Sep 17 00:00:00 2001 From: Torsten Lodderstedt Date: Thu, 5 Oct 2023 11:16:31 +0200 Subject: [PATCH 22/37] Update openid-4-verifiable-presentations-1_0.md Co-authored-by: Kristina <52878547+Sakurann@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 34eb815b..260cb98b 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -302,7 +302,7 @@ The following is an example request: } ``` -The Discovery Request is either send the Discovery Endpoint of the Wallet or it is rendered as a QR Code and scanned with the Wallet or a camera app. +The Discovery Request is either sent to the Discovery Endpoint of the Wallet or is rendered as a QR Code. Note: the Discovery Request intentionally does not use OAuth parameters, such as a `client_id`. The idea is to allow the Verifier to select the Client Identifier it wants to use for interacting with the Wallet after it has determined the trust mechanisms and domains the Wallet supports. From 72c2967f6f61c5c66e9edb6e26707fac74aac78b Mon Sep 17 00:00:00 2001 From: Torsten Lodderstedt Date: Thu, 5 Oct 2023 11:22:32 +0200 Subject: [PATCH 23/37] text on well-known location --- 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 260cb98b..eb354856 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -326,7 +326,7 @@ The follwowing parameters are defined: : A JSON String containing the value of the corresponding Discovery Request's `context` parameter. `issuer`: -: A JSON containing an HTTPS URL designating the Issuer URL of the Wallet. +: A JSON containing an HTTPS URL designating the Issuer URL of the Wallet. The Verifier can obtain the Wallet's metadata by adding the well-know location `oauth-authorization-server` as specifid in [@!RFC8414]. `w_nonce`: : A JSON String containg a cryptographic nonce the Verifier MUST use when creating the signed presentation request object. From 0873d4a8db7c3812b1306b0c934095dcecdde65b Mon Sep 17 00:00:00 2001 From: Torsten Lodderstedt Date: Thu, 5 Oct 2023 11:24:34 +0200 Subject: [PATCH 24/37] Update openid-4-verifiable-presentations-1_0.md Co-authored-by: Kristina <52878547+Sakurann@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 eb354856..2fff1be1 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -219,7 +219,7 @@ Figure: Cross Device Flow ## Same Device Flow with Wallet Capabilities Discovery {#adv_flow} -Below is a diagram shows a flow a describe in ({#same_device}) with an additional pre-step used to discover the Wallet's capabilities and tailor the actual request to it. +Below is a diagram that shows a flow described in (#same_device), but with an additional pre-step used that allows the Verifier to discover the Wallet's capabilities and tailor the actual request. In this case, the Verifier starts the flow by discovering the Wallet's capabilities through an additional message exchange. This is especially useful, if the Verifier starts the process using a URL serving as alias for a group of wallets (e.g. a custom scheme) but would like to tailor the presentation request to the particular wallet. From 874f13c8bcec75f9ea437800be7c4384cfe096c1 Mon Sep 17 00:00:00 2001 From: Torsten Lodderstedt Date: Thu, 5 Oct 2023 11:25:01 +0200 Subject: [PATCH 25/37] nits --- 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 2fff1be1..a187a55b 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -219,7 +219,7 @@ Figure: Cross Device Flow ## Same Device Flow with Wallet Capabilities Discovery {#adv_flow} -Below is a diagram that shows a flow described in (#same_device), but with an additional pre-step used that allows the Verifier to discover the Wallet's capabilities and tailor the actual request. +Below is a diagram that shows the flow as described in (#same_device), but with an additional pre-step used that allows the Verifier to discover the Wallet's capabilities and tailor the actual request. In this case, the Verifier starts the flow by discovering the Wallet's capabilities through an additional message exchange. This is especially useful, if the Verifier starts the process using a URL serving as alias for a group of wallets (e.g. a custom scheme) but would like to tailor the presentation request to the particular wallet. From 01339f951b372496b6cf71ee2514c382215d5a64 Mon Sep 17 00:00:00 2001 From: Torsten Lodderstedt Date: Thu, 5 Oct 2023 11:26:30 +0200 Subject: [PATCH 26/37] changed label of overview section --- 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 a187a55b..61a9011e 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -217,7 +217,7 @@ Figure: Cross Device Flow (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. -## Same Device Flow with Wallet Capabilities Discovery {#adv_flow} +## Same Device Flow with Wallet Capabilities Discovery {#same_device_with_discovery} Below is a diagram that shows the flow as described in (#same_device), but with an additional pre-step used that allows the Verifier to discover the Wallet's capabilities and tailor the actual request. From ba781a156c7d860ee5d854eab3942088fea95a3c Mon Sep 17 00:00:00 2001 From: Torsten Lodderstedt Date: Mon, 16 Oct 2023 16:24:37 +0200 Subject: [PATCH 27/37] Update openid-4-verifiable-presentations-1_0.md Co-authored-by: Daniel Fett --- 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 61a9011e..2bda5dd0 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -217,7 +217,7 @@ Figure: Cross Device Flow (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. -## Same Device Flow with Wallet Capabilities Discovery {#same_device_with_discovery} +## Same-Device Flow with Wallet Capabilities Discovery {#same_device_with_discovery} Below is a diagram that shows the flow as described in (#same_device), but with an additional pre-step used that allows the Verifier to discover the Wallet's capabilities and tailor the actual request. From 03649aa543998878512e562fd3eb83b1a6586e08 Mon Sep 17 00:00:00 2001 From: Torsten Lodderstedt Date: Mon, 16 Oct 2023 16:26:05 +0200 Subject: [PATCH 28/37] Update openid-4-verifiable-presentations-1_0.md Co-authored-by: Daniel Fett --- 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 2bda5dd0..810853fe 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -221,7 +221,7 @@ Figure: Cross Device Flow Below is a diagram that shows the flow as described in (#same_device), but with an additional pre-step used that allows the Verifier to discover the Wallet's capabilities and tailor the actual request. -In this case, the Verifier starts the flow by discovering the Wallet's capabilities through an additional message exchange. This is especially useful, if the Verifier starts the process using a URL serving as alias for a group of wallets (e.g. a custom scheme) but would like to tailor the presentation request to the particular wallet. +Essentially, the Verifier starts the flow by discovering the Wallet's capabilities through an additional message exchange. This is especially useful if the Verifier starts the process using a URL serving as an alias for a group of wallets (e.g., a custom scheme) but would like to tailor the presentation request to the particular wallet. In this flow, the Verifier first prepares a discovery request to be provided to the Wallet. The Wallet answers this request by sending an HTTP POST request to the Verifier, providing the Verifier with its Issuer URL (identifying the wallet provider and used to fetch wallet metadata) and further parameters. The Verifier then creates a presentation request tailored to the capabilities and trust domain of the particular Wallet and passes the request object in the HTTP POST response. The rest of the flow works like described in (#same_device). The discovery request can also be used in cross device scenarios where the Verifier would render the discovery message in a QR code. From 67420e6463699f2d798d4544cfd5eb52d33fc749 Mon Sep 17 00:00:00 2001 From: Torsten Lodderstedt Date: Mon, 16 Oct 2023 16:29:01 +0200 Subject: [PATCH 29/37] Update openid-4-verifiable-presentations-1_0.md Co-authored-by: Daniel Fett --- 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 810853fe..cb4a8c85 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -334,7 +334,7 @@ The follwowing parameters are defined: `client_assertion` : A JSON String containing a Wallet attestation along with a proof of possession of the configuration key as defined in [@!I-D.ietf-oauth-attestation-based-client-auth]. This assertion is used to authenticate the Wallet towards the Verifier. -### Presentation Response +### Presentation Request Response Presentation Response MUST be HTTPS POST response with the "application/json" media type. From cafba20f16db95aeeb21fb714abbf69b51fc4a0a Mon Sep 17 00:00:00 2001 From: Torsten Lodderstedt Date: Mon, 16 Oct 2023 16:34:53 +0200 Subject: [PATCH 30/37] modified presentation request response to provide request object in response body --- diagrams/advanced_flow.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/diagrams/advanced_flow.md b/diagrams/advanced_flow.md index d0aef279..6adc3542 100644 --- a/diagrams/advanced_flow.md +++ b/diagrams/advanced_flow.md @@ -3,6 +3,11 @@ autonumber +box "Wallet" +participant "Metadata" as wm +participant "Discovery Endpoint" as w +end box + participant "User Agent" as u box "Verifier" @@ -11,11 +16,6 @@ participant "Presentation Endpoint" as rp participant "Response Endpoint" as rb end box -box "Wallet" -participant "Discovery Endpoint" as w -participant "Metadata" as wm -end box - u --> r : use activate r @@ -25,8 +25,8 @@ u --> w: **discover request**\n(presentation_uri, context) activate w w --> rp: **create presentation request** (context, iss, w_nonce, \nwallet attestation, **wallet attestation pop(v_nonce)**) note over u, w: HTTP status code 401 signals need to authenticate -rp --> wm: get wallet metadata -wm --> rp: wallet metadata +rp --> wm: [OPTIONAL] get wallet metadata +wm --> rp: [OPTIONAL] wallet metadata rp -> rp: create and sign presentation request object (client_id, w_nonce, nonce, response_uri, \npresentation_definition, state) rp --> w: **signed request object** (client_id, w_nonce, nonce, response_uri, \npresentation_definition, state) note over u, w: do we want to allow unsigned presentation request objects, too? From fff23fcb4682bd8f18a0cd496971be48bd919de4 Mon Sep 17 00:00:00 2001 From: Torsten Lodderstedt Date: Mon, 16 Oct 2023 16:36:45 +0200 Subject: [PATCH 31/37] Update openid-4-verifiable-presentations-1_0.md Co-authored-by: Giuseppe De Marco --- 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 cb4a8c85..f4ffee30 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -219,7 +219,7 @@ Figure: Cross Device Flow ## Same-Device Flow with Wallet Capabilities Discovery {#same_device_with_discovery} -Below is a diagram that shows the flow as described in (#same_device), but with an additional pre-step used that allows the Verifier to discover the Wallet's capabilities and tailor the actual request. +Below is a diagram that shows the flow as described in (#same_device), with an additional preliminary step that allows the Verifier to discover the Wallet's capabilities before tailoring the actual request. Essentially, the Verifier starts the flow by discovering the Wallet's capabilities through an additional message exchange. This is especially useful if the Verifier starts the process using a URL serving as an alias for a group of wallets (e.g., a custom scheme) but would like to tailor the presentation request to the particular wallet. From 08d02a006cb16124f6088317638f0e6f590edfc2 Mon Sep 17 00:00:00 2001 From: Torsten Lodderstedt Date: Mon, 16 Oct 2023 16:38:20 +0200 Subject: [PATCH 32/37] Update openid-4-verifiable-presentations-1_0.md Co-authored-by: Giuseppe De Marco --- 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 f4ffee30..78ad05e8 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -227,7 +227,7 @@ In this flow, the Verifier first prepares a discovery request to be provided to Note: The diagram does not illustrate all the optional features of this specification. -Note: The usage of the Request URI as defined in [@!RFC9101] does not depend on any other choices made in the protocol extensibility points, i.e., it can be used in the Same Device Flow, too. +Note: The usage of the Request URI as defined in [@!RFC9101] does not depend on any other choices made in the protocol extensibility points, i.e., it can be used in the Same-Device Flow as well. !--- ~~~ ascii-art From ad91012b7d6e80352dce9304b3434294669e2d3d Mon Sep 17 00:00:00 2001 From: Torsten Lodderstedt Date: Mon, 16 Oct 2023 16:42:07 +0200 Subject: [PATCH 33/37] rewrote Discovery Endpoint section to not require a HTTPS endpoint --- openid-4-verifiable-presentations-1_0.md | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index cb4a8c85..c5133a74 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -308,9 +308,9 @@ Note: the Discovery Request intentionally does not use OAuth parameters, such as ## Discovery Endpoint -This is an HTTPS endpoint offered by the Wallet. The Discovery Request MUST be sent as an HTTPS GET request or an HTTP redirect to the Discovery Endpoint URL defined in (#wallet-metadata). +This is an endpoint offered by the Wallet. The Discovery Request can be sent as a HTTPS GET or a HTTP redirect or via a platform specific mechanims, i.e. Android Intents, to the Discovery Endpoint URL defined in (#wallet-metadata). -The HTTPS URL MUST contain a single URI query parameter `discovery` where the value is the JSON object as defined above. +The request URI contains a single query parameter `discovery` where the value is the JSON object as defined above. ## Presentation Endpoint @@ -320,7 +320,7 @@ The Presentation Endpoint is an HTTPS endpoint exposed by the Verifier. Presentation Requests MUST be HTTPS POST requests with the "application/json" media type. -The follwowing parameters are defined: +The following parameters are defined: `context`: : A JSON String containing the value of the corresponding Discovery Request's `context` parameter. @@ -336,15 +336,9 @@ The follwowing parameters are defined: ### Presentation Request Response -Presentation Response MUST be HTTPS POST response with the "application/json" media type. +Presentation Response MUST be HTTPS POST response with the "application/oauth-authz-req+jwt" media type and contain a signed request object as defined in [@RFC9101]. It MUST fulfill the requirements as defined in (#vp_token_request). -The follwowing parameters are defined: - -`request`: -: A JSON String containing the signed request object as defined in [@RFC9101]. It MUST fulfill the requirements as defined in (#vp_token_request). - - -### Presentation Error Response +### Presentation Request Error Response The error code `401` signals to the Wallet that it needs to authenticate to the Verifier. In this case, the error response SHOULD contain a `WWW-Authenticate` header for every attestation method the Verifier supports. From b469b1f08a22d7ecee8fc3c6f3f4cb5572af234d Mon Sep 17 00:00:00 2001 From: Torsten Lodderstedt Date: Mon, 16 Oct 2023 16:50:26 +0200 Subject: [PATCH 34/37] modified w_nonce definition to incorporate Giuseppe's comment --- openid-4-verifiable-presentations-1_0.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index fba3bbe8..28472c6c 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -326,10 +326,10 @@ The following parameters are defined: : A JSON String containing the value of the corresponding Discovery Request's `context` parameter. `issuer`: -: A JSON containing an HTTPS URL designating the Issuer URL of the Wallet. The Verifier can obtain the Wallet's metadata by adding the well-know location `oauth-authorization-server` as specifid in [@!RFC8414]. +: A JSON containing an HTTPS URL designating the Issuer URL of the Wallet (acting as a OAuth Authorization Server). The Verifier MAY obtain the Wallet's metadata by adding the well-know location `oauth-authorization-server` as specifid in [@!RFC8414]. Metadata can also be provided by other means, for example in the wallet attestation. `w_nonce`: -: A JSON String containg a cryptographic nonce the Verifier MUST use when creating the signed presentation request object. +: A JSON String containing as fresh, cryptographically random number with sufficient entropy the Verifier MUST use when creating the signed presentation request object. `client_assertion` : A JSON String containing a Wallet attestation along with a proof of possession of the configuration key as defined in [@!I-D.ietf-oauth-attestation-based-client-auth]. This assertion is used to authenticate the Wallet towards the Verifier. From a25840ae3b245175045fe0914d28d3cec0028e31 Mon Sep 17 00:00:00 2001 From: Torsten Lodderstedt Date: Mon, 16 Oct 2023 16:50:50 +0200 Subject: [PATCH 35/37] Update openid-4-verifiable-presentations-1_0.md Co-authored-by: Giuseppe De Marco --- 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 28472c6c..5719bd1f 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -332,7 +332,7 @@ The following parameters are defined: : A JSON String containing as fresh, cryptographically random number with sufficient entropy the Verifier MUST use when creating the signed presentation request object. `client_assertion` -: A JSON String containing a Wallet attestation along with a proof of possession of the configuration key as defined in [@!I-D.ietf-oauth-attestation-based-client-auth]. This assertion is used to authenticate the Wallet towards the Verifier. +: A JSON String containing a Wallet attestation along with a proof of possession of the public key as defined in [@!I-D.ietf-oauth-attestation-based-client-auth]. This assertion is used to authenticate the Wallet towards the Verifier. ### Presentation Request Response From 0a85508b7950b8917a5b955156d8f1dd117f6f17 Mon Sep 17 00:00:00 2001 From: Torsten Lodderstedt Date: Mon, 16 Oct 2023 16:55:46 +0200 Subject: [PATCH 36/37] changed context to interaction --- 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 28472c6c..a9613417 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -288,7 +288,7 @@ This specification defines the following new parameters for the Discovery Reques `presentation_request_uri`: : A string containing an HTTPS URL pointing to a resource under the control of the Verifier where the Wallet is supposed to obtain the presentation request object. -`context`: +`interaction`: : A string identifying the context of the discovery request from the perspective of the Verifier. The value is opqaue to the Wallet, it MUST pass this value to the Presentation Endpoint Request (see below). The Discovery Request MUST be represented as a JSON object with all parameters as top-level JSON claims. @@ -322,11 +322,11 @@ Presentation Requests MUST be HTTPS POST requests with the "application/json" me The following parameters are defined: -`context`: -: A JSON String containing the value of the corresponding Discovery Request's `context` parameter. +`interaction`: +: A JSON String containing the value of the corresponding Discovery Request's `interaction` parameter. `issuer`: -: A JSON containing an HTTPS URL designating the Issuer URL of the Wallet (acting as a OAuth Authorization Server). The Verifier MAY obtain the Wallet's metadata by adding the well-know location `oauth-authorization-server` as specifid in [@!RFC8414]. Metadata can also be provided by other means, for example in the wallet attestation. +: A JSON containing an HTTPS URL designating the Issuer URL of the Wallet (acting as a OAuth Authorization Server). The Verifier MAY obtain the Wallet's metadata by adding the well-know location `oauth-authorization-server` as specifid in [@!RFC8414]. Metadata MAY also be provided by other means, for example in the wallet attestation. `w_nonce`: : A JSON String containing as fresh, cryptographically random number with sufficient entropy the Verifier MUST use when creating the signed presentation request object. From e8f97aca7c18f88e0831aa9193584eb30cbc411a Mon Sep 17 00:00:00 2001 From: Torsten Lodderstedt Date: Wed, 25 Oct 2023 15:46:24 +0200 Subject: [PATCH 37/37] Update openid-4-verifiable-presentations-1_0.md Co-authored-by: Brian Campbell <71398439+bc-pi@users.noreply.github.com> --- openid-4-verifiable-presentations-1_0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openid-4-verifiable-presentations-1_0.md b/openid-4-verifiable-presentations-1_0.md index 2565a568..40f9509c 100644 --- a/openid-4-verifiable-presentations-1_0.md +++ b/openid-4-verifiable-presentations-1_0.md @@ -298,7 +298,7 @@ The following is an example request: ```JSON { "presentation_request_uri": "verifier.example.com/presentation_request", - "context": "register_kyc" + "interaction": "register_kyc" } ```