-
Notifications
You must be signed in to change notification settings - Fork 27
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
DC API: Always use Origin for binding response #448
Open
jogu
wants to merge
4
commits into
main
Choose a base branch
from
dc-api-remove-clientid-in-responses
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
4 commits
Select commit
Hold shift + click to select a range
995152a
DC API: Always use Origin for binding response
jogu 87e010b
Apply (part of) Kristina's suggestion
jogu be943cf
Further revisions to attempt to address feedback on the PR
jogu 49633ee
Apply suggestions from Kristina with a few modifications
jogu File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change | ||||
---|---|---|---|---|---|---|
|
@@ -574,7 +574,7 @@ Body | |||||
|
||||||
* `x509_san_dns`: When the Client Identifier Scheme is `x509_san_dns`, the Client Identifier MUST be a DNS name and match a `dNSName` Subject Alternative Name (SAN) [@!RFC5280] entry in the leaf certificate passed with the request. The request MUST be signed with the private key corresponding to the public key in the leaf X.509 certificate of the certificate chain added to the request in the `x5c` JOSE header [@!RFC7515] of the signed request object. The Wallet MUST validate the signature and the trust chain of the X.509 certificate. All Verifier metadata other than the public key MUST be obtained from the `client_metadata` parameter. If the Wallet can establish trust in the Client Identifier authenticated through the certificate, e.g. because the Client Identifier is contained in a list of trusted Client Identifiers, it may allow the client to freely choose the `redirect_uri` value. If not, the FQDN of the `redirect_uri` value MUST match the Client Identifier without the prefix `x509_san_dns:`. Example Client Identifier: `x509_san_dns:client.example.org`. | ||||||
|
||||||
* `web-origin`: This Client Identifier Scheme is defined in (#dc_api_request). The Wallet MUST NOT accept this Client Identifier Scheme if the request is not sent via the Digital Credentials API defined in (#dc_api). | ||||||
* `origin`: This Client Identifier Scheme is defined in (#dc_api_request). The Wallet MUST NOT accept this Client Identifier Scheme in requests. In OpenID4VP over the Digital Credentials API, the audience of the Credential Presentation is always the origin value prefixed by `origin:`, for example `origin:https://verifier.example.com/`. | ||||||
|
||||||
* `x509_hash`: When the Client Identifier Scheme is `x509_hash`, the Client Identifier MUST be a hash and match the hash of the leaf certificate passed with the request. The request MUST be signed with the private key corresponding to the public key in the leaf X.509 certificate of the certificate chain added to the request in the `x5c` JOSE header parameter [@!RFC7515] of the signed request object. The value of `x509_hash` is the base64url encoded value of the SHA-256 hash of the DER-encoded X.509 certificate. The Wallet MUST validate the signature and the trust chain of the X.509 leaf certificate. All verifier metadata other than the public key MUST be obtained from the `client_metadata` parameter. Example Client Identifier: `x509_hash:Uvo3HtuIxuhC92rShpgqcT3YXwrqRxWEviRiA0OZszk` | ||||||
|
||||||
|
@@ -1994,7 +1994,7 @@ In the event that another component is invoked instead of the Wallet, the End-Us | |||||
|
||||||
This section defines how to use OpenID4VP with the Digital Credentials API. | ||||||
|
||||||
The name "Digital Credentials API" (DC API) encomposes the W3C Digital Credentials API [@!W3C.Digital_Credentials_API] | ||||||
The name "Digital Credentials API" (DC API) encompasses the W3C Digital Credentials API [@!W3C.Digital_Credentials_API] | ||||||
as well as its native App Platform equivalents in operating systems (such as [Credential Manager on Android](https://developer.android.com/jetpack/androidx/releases/credentials)). | ||||||
The DC API allows web sites and native apps acting as Verifiers to request the presentation of verifiable credentials. | ||||||
The API itself is agnostic to the Credential exchange protocol and can be used with different protocols. | ||||||
|
@@ -2052,14 +2052,18 @@ Out of the Authorization Request parameters defined in [@!RFC6749] and (#vp_toke | |||||
* `transaction_data` | ||||||
* `dcql_query` | ||||||
|
||||||
The `client_id` parameter MUST be omitted in unsigned requests defined in (#unsigned_request). The Wallet determines the effective Client Identifier from the Origin. The effective Client Identifier is composed of a synthetic Client Identifier Scheme of `web-origin` and the Origin itself. For example, an Origin of `https://verifier.example.com` would result in an effective Client Identifier of `web-origin:https://verifier.example.com`. The transport of the request and Origin to the Wallet is platform-specific and is out of scope of OpenID4VP over the W3C Digital Credentials API. The Wallet MUST ignore any `client_id` parameter that is present in an unsigned request. | ||||||
The `client_id` parameter MUST be omitted in unsigned requests defined in (#unsigned_request). The Wallet MUST ignore any `client_id` parameter that is present in an unsigned request. | ||||||
jogu marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
|
||||||
The `client_id` parameter MUST be present in signed requests defined in (#signed_request), as it communicates to the wallet which Client Identifier Scheme and Client Identifier to use when verifying the request signature or retrieving client metadata. | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
|
||||||
The value of the `response_mode` parameter MUST be `dc_api` when the response is neither signed nor encrypted and `dc_api.jwt` when the response is signed and/or encrypted as defined in (#jarm). | ||||||
|
||||||
In addition to the above-mentioned parameters, a new parameter is introduced for OpenID4VP over the W3C Digital Credentials API: | ||||||
|
||||||
* `expected_origins`: REQUIRED when signed requests defined in (#signed_request) are used with the Digital Credentials API (DC API). An array of strings, each string representing an Origin of the Verifier that is making the request. The Wallet can detect replay of the request from a malicious Verifier by comparing values in this parameter to the Origin. This parameter is not for use in unsigned requests and therefore a Wallet MUST ignore this parameter if it is present in an unsigned request. | ||||||
|
||||||
The transport of the request and Origin to the Wallet is platform-specific and is out of scope of OpenID4VP over the Digital Credentials API. | ||||||
|
||||||
Additional request parameters MAY be defined and used with OpenID4VP over the DC API. | ||||||
|
||||||
The Wallet MUST ignore any unrecognized parameters. | ||||||
|
@@ -2070,8 +2074,7 @@ Any OpenID4VP request compliant to this section of this specification can be use | |||||
|
||||||
### Unsigned Request {#unsigned_request} | ||||||
|
||||||
The Verifier MAY send all the OpenID4VP request parameters as members in the request member passed to the API. In this case, the Wallet will use the Verifier's Origin to determine the Verifier's effective Client Identifier. | ||||||
|
||||||
The Verifier MAY send all the OpenID4VP request parameters as members in the request member passed to the API. | ||||||
|
||||||
### Signed Request {#signed_request} | ||||||
|
||||||
|
@@ -2091,10 +2094,14 @@ This is an example of the payload of a signed OpenID4VP request used with the DC | |||||
|
||||||
The signed request allows the Wallet to authenticate the Verifier using a trust framework other than the Web PKI utilized by the browser. An example of such a trust framework is the Verifier (RP) management infrastructure set up in the context of the eIDAS regulation in the European Union, in which case, the Wallet can no longer rely only on the Origin of the Verifier. This Origin MAY still be used to further strengthen the security of the flow. The external trust framework could, for example, map the Client Identifier to registered Origins. | ||||||
|
||||||
## Response | ||||||
## Response {#dc_api_response} | ||||||
|
||||||
Every OpenID4VP Authorization Request results in a response being provided through the Digital Credentials API (DC API). The response is an instance of the `DigitalCredential` interface, as defined in [@!W3C.Digital_Credentials_API], and the OpenID4VP Authorization Response parameters as defined for the Response Type are represented as an object within the `data` attribute. | ||||||
|
||||||
The security properties that are normally provided by the Client Identifier are achieved by binding the response to the Origin it was received from. | ||||||
|
||||||
The audience for the response (for example, the `aud` value in a Key Binding JWT) MUST be the Origin, prefixed with `origin:`, for example `origin:https://verifier.example.com/`. This is the case even for signed requests. Therefore, when using OpenID4VP over the DC API, the Client Identifier is not used as the audience for the response. | ||||||
|
||||||
# Credential Format Specific Parameters {#format_specific_parameters} | ||||||
|
||||||
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 a set of Credential Format specific parameters for some of the known Credential Formats. For the Credential Formats that are not mentioned in this specification, other specifications or deployments can define their own set of Credential Format specific parameters. | ||||||
|
@@ -2136,7 +2143,7 @@ This `presentation_definition` parameter contains a single `input_descriptor` el | |||||
The following requirements apply to the `nonce` and `aud` claims of the Verifiable Presentation: | ||||||
|
||||||
- the `nonce` claim MUST be the value of `nonce` from the Authorization Request; | ||||||
- the `aud` claim MUST be the value of the Client Identifier; or effective Client Identifier for an unsigned Authorization Request over the DC API, as described in (#dc_api_request). | ||||||
- the `aud` claim MUST be the value of the Client Identifier, except for requests over the DC API where it MUST be the Origin prefixed with `origin:`, as described in (#dc_api_response). | ||||||
|
||||||
The following is a non-normative example of an Authorization Response: | ||||||
|
||||||
|
@@ -2181,7 +2188,7 @@ This `presentation_definition` parameter contains a single `input_descriptor` el | |||||
The following requirements apply to the `challenge` and `domain` claims within the `proof` object in the Verifiable Presentation: | ||||||
|
||||||
- the `challenge` claim MUST be the value of `nonce` from the Authorization Request; | ||||||
- the `domain` claim MUST be the value of the Client Identifier; or effective Client Identifier for an unsigned Authorization Request over the DC API, as described in (#dc_api_request). | ||||||
- the `domain` claim MUST be the value of the Client Identifier, except for requests over the DC API where it MUST be the Origin prefixed with `origin:`, as described in (#dc_api_response). | ||||||
|
||||||
The following is a non-normative example of an Authorization Response: | ||||||
|
||||||
|
@@ -2336,12 +2343,9 @@ OpenID4VPDCAPIHandoverInfoBytes = bstr .cbor OpenID4VPDCAPIHandoverInfo | |||||
|
||||||
OpenID4VPDCAPIHandoverInfo = [ | ||||||
origin, | ||||||
client_id, | ||||||
nonce | ||||||
] ; Array containing handover parameters | ||||||
|
||||||
client_id = tstr | ||||||
|
||||||
origin = tstr | ||||||
|
||||||
nonce = tstr | ||||||
|
@@ -2352,9 +2356,8 @@ The `OpenID4VPDCAPIHandover` structure has the following elements: | |||||
* The first element MUST be the string `OpenID4VPDCAPIHandover`. This serves as a unique identifier for the handover structure to prevent misinterpretation or confusion. | ||||||
* The second element MUST be a bytestring which contains the sha-256 hash of the bytes of `OpenID4VPDCAPIHandoverInfo` when encoded as CBOR. | ||||||
* The `OpenID4VPDCAPIHandoverInfo` has the following elements: | ||||||
* The first element MUST be the string representing the origin of the request as described in (#dc_api_request). | ||||||
* The second element MUST be the value of the effective Client Identifier as defined in (#dc_api_request). | ||||||
* The third element MUST be the value of the `nonce` request parameter. | ||||||
* The first element MUST be the string representing the Origin of the request as described in (#dc_api_request). It MUST NOT be prefixed with `origin:`. | ||||||
* The second element MUST be the value of the `nonce` request parameter. | ||||||
|
||||||
#### Invocation via other methods {#non-dc-api-invocation} | ||||||
|
||||||
|
@@ -2463,9 +2466,7 @@ A non-normative example of the Authorization Response would look the same as in | |||||
The following requirements apply to the `nonce` and `aud` claims in the Key Binding JWT: | ||||||
|
||||||
- the `nonce` claim MUST be the value of `nonce` from the Authorization Request; | ||||||
- the `aud` claim MUST be the value of the Client Identifier; | ||||||
|
||||||
Note that for an unsigned Authorization Request over the DC API, the `client_id` parameter is not used. Instead, the effective Client Identifier is derived from the Origin, as described in (#dc_api_request). | ||||||
- the `aud` claim MUST be the value of the Client Identifier, except for requests over the DC API where it MUST be the Origin prefixed with `origin:`, as described in (#dc_api_response). | ||||||
|
||||||
The `transaction_data_hashes` response parameter defined in (#transaction_data) MUST be included in the Key Binding JWT as a top level claim. This means that transaction data mechanism cannot be used with SD-JWT VCs without cryptographic key binding and, therefore, do not use KB JWT. | ||||||
|
||||||
|
@@ -2836,6 +2837,7 @@ The technology described in this specification was made available from contribut | |||||
|
||||||
* clarify DCQL case of `claims` and `claim_sets` being absent | ||||||
* add language on client ID and nonce binding for ISO mdocs and W3C VCs | ||||||
* for DC API, always use Origin for binding the response (e.g. in Key Binding JWT `aud` and sessionTranscript in mdoc) | ||||||
* clarify the behavior is not to sign when authorization_signed_response_alg is omitted | ||||||
* add a note on the use of apu/apv in the JWE header of encrypted responses | ||||||
* add x509_hash client identifier scheme | ||||||
|
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Do we still need this scheme?