Skip to content
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.

Sign up for GitHub

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

editorial: Wallet is a defined term #82

Merged
merged 10 commits into from
Jan 16, 2025
Merged

editorial: Wallet is a defined term #82

Changes from 6 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
4c168f5
editorial: Wallet is a defined term
peppelinux Dec 13, 2023
ab16885
capitalize "wallet"
Sakurann Mar 23, 2024
900442a
Apply suggestions from code review
May 24, 2024
1f91c8a
Merge branch 'main' into wa
peppelinux May 24, 2024
666a488
Merge branch 'wa' of https://github.com/peppelinux/oid4vc-haip-sd-jwt…
peppelinux May 24, 2024
935f2bd
Merge branch 'main' of https://github.com/openid/oid4vc-haip-sd-jwt-v…
peppelinux Jan 15, 2025
48e8f12
fix: regressions due to merge conflicts
peppelinux Jan 15, 2025
0dfcf5c
Apply suggestions from code review
peppelinux Jan 15, 2025
e97e960
Apply suggestions from code review
peppelinux Jan 15, 2025
59dbdfe
Apply suggestions from code review
peppelinux Jan 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 22 additions & 55 deletions openid4vc-high-assurance-interoperability-profile-1_0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ The audience of the document is implementers that require a high level of securi

# Terminology

This specification uses the terms "Holder", "Issuer", "Verifier", and "Verifiable Credential" as defined in [@!I-D.ietf-oauth-sd-jwt-vc].
This specification uses the terms "Holder", "Issuer", "Verifier", "Wallet", and "Verifiable Credential" as defined in @!OIDF.OID4VCI] and [@!OIDF.OID4VP].

# Scope

Expand All @@ -74,8 +74,8 @@ Note that when OpenID4VP is used, the Wallet and the Verifier can either be remo

Assumptions made are the following:

* The issuers and verifiers cannot pre-discover wallet’s capability
* The issuer is talking to the wallet supporting the features defined in this profile (via wallet invocation mechanism)
* The issuers and verifiers cannot pre-discover Wallet’s capability
* The issuer is talking to the Wallet supporting the features defined in this profile (via Wallet invocation mechanism)
* There are mechanisms in place for the verifiers and issuers to discover each other’s capability

## Out of Scope
Expand Down Expand Up @@ -119,8 +119,8 @@ Both Wallet initiated and Issuer initiated issuance is supported.
## Credential Offer

* The Grant Types `authorization_code` and `urn:ietf:params:oauth:grant-type:pre-authorized_code` MUST be supported as defined in Section 4.1.1 in [@!OIDF.OID4VCI]
* For Grant Type `authorization_code`, the Issuer MUST include a scope value in order to allow the Wallet to identify the desired credential type. The wallet MUST use that value in the `scope` Authorization parameter. For Grant Type `urn:ietf:params:oauth:grant-type:pre-authorized_code`, the pre-authorized code is used by the issuer to identify the credential type(s).
* As a way to invoke the Wallet, at least a custom URL scheme `haip://` MUST be supported. Implementations MAY support other ways to invoke the wallets as agreed by trust frameworks/ecosystems/jurisdictions, not limited to using other custom URL schemes.
* For Grant Type `authorization_code`, the Issuer MUST include a scope value in order to allow the Wallet to identify the desired credential type. The Wallet MUST use that value in the `scope` Authorization parameter. For Grant Type `urn:ietf:params:oauth:grant-type:pre-authorized_code`, the pre-authorized code is used by the issuer to identify the credential type(s).
* As a way to invoke the Wallet, at least a custom URL scheme `haip://` MUST be supported. Implementations MAY support other ways to invoke the Wallets as agreed by trust frameworks/ecosystems/jurisdictions, not limited to using other custom URL schemes.

Note: The Authorization Code flow does not require a Credential Offer from the Issuer to the Wallet. However, it is included in the feature set of the Credential Offer because it might be easier to implement with existing libraries and on top of existing implementations than the pre-authorized code Grant Type.

Expand Down Expand Up @@ -149,9 +149,9 @@ Wallets MUST use attestations following the definition given in [@!I-D.ietf-oaut

In addition to this definition, the Wallet Attestation MAY contain the following claims in the `cnf` element:

* `key_type`: OPTIONAL. JSON String that asserts the security mechanism the Wallet uses to manage the private key associated with the public key given in the `cnf` claim. This mechanism is based on the capabilities of the execution environment of the Wallet, this might be a secure element (in case of a wallet residing on a smartphone) or a Cloud-HSM (in case of a cloud Wallet). This specification defines the following values for `key_type`:
* `key_type`: OPTIONAL. JSON String that asserts the security mechanism the Wallet uses to manage the private key associated with the public key given in the `cnf` claim. This mechanism is based on the capabilities of the execution environent of the Wallet, this might be a secure element (in case of a Wallet residing on a smartphone) or a Cloud-HSM (in case of a cloud Wallet). This specification defines the following values for `key_type`:
peppelinux marked this conversation as resolved.
Show resolved Hide resolved
* `software`: It MUST be used when the Wallet uses software-based key management.
* `hardware`: It MUST be used when the wallet uses hardware-based key management.
* `hardware`: It MUST be used when the Wallet uses hardware-based key management.
* `tee`: It SHOULD be used when the Wallet uses the Trusted Execution Environment for key management.
* `secure_enclave`: It SHOULD be used when the Wallet uses the Secure Enclave for key management.
* `strong_box`: It SHOULD be used when the Wallet uses the Strongbox for key management.
Expand All @@ -168,7 +168,7 @@ The Wallet Attestation MAY also contain the following claim:

* `aal`: OPTIONAL. JSON String asserting the authentication level of the Wallet and the key as asserted in the `cnf` claim.

To obtain the issuer's Public key for verification, wallet attestations MUST support web-based key resolution as defined in Section 5 of [@!I-D.ietf-oauth-sd-jwt-vc]. The JOSE header `kid` MUST be used to identify the respective key.
To obtain the Issuer's Public key for verification, Wallet attestions MUST support web-based key resolution as defined in Section 5 of [@!I-D.ietf-oauth-sd-jwt-vc]. The JOSE header `kid` MUST be used to identify the respective key.

This is an example of a Wallet Instance Attestation:

Expand All @@ -180,7 +180,7 @@ This is an example of a Wallet Instance Attestation:
}
.
{
"iss": "<identifier of the issuer of this wallet attestation>",
"iss": "<identifier of the issuer of this Wallet attestation>",
"sub": "<`client_id` of the OAuth client>",
"iat": 1516247022,
"exp": 1541493724,
Expand Down Expand Up @@ -208,56 +208,23 @@ This is an example of a Wallet Instance Attestation:

# OpenID for Verifiable Presentations profile for IETF SD-JWT VC

Requirements for both the Wallet and the Verifier:

* As a way to invoke the Wallet, at least a custom URL scheme `haip://` MUST be supported. Implementations MAY support other ways to invoke the wallets as agreed by trust frameworks/ecosystems/jurisdictions, not limited to using other custom URL schemes.
* Response type MUST be `vp_token`.
* Response mode MUST be `direct_post.jwt`. The Verifier MUST return `redirect_uri` in response to the HTTP POST request from the Wallet, where the Wallet redirects the User to, as defined in Section 7.2 of [@!OIDF.OID4VP]. Implementation considerations for the response mode `direct_post.jwt` are given in Section 12.4 of [@!OIDF.OID4VP].
* Authorization Request MUST be sent using the `request_uri` parameter as defined in JWT-Secured Authorization Request (JAR) [@!RFC9101].
* The Client Identifier Scheme as introduced in Section 5.10 of [@!OIDF.OID4VP] MUST be either `x509_san_dns` or `verifier_attestation`. The Wallet MUST support both. The Verifier MUST support at least one.
* To obtain the issuer's public key for verification, verifiers MUST support Web-based key resolution, as defined in Section 5 of [@!I-D.ietf-oauth-sd-jwt-vc]. The JOSE header `kid` MUST be used to identify the respective key.
* Presentation Definition JSON object MUST be sent using a `presentation_definition` parameter.
* The following features from the DIF Presentation Exchange v2.0.0 MUST be supported. A JSON schema for the supported features is in (#presentation-definition-schema):
* In the `presentation_definition` object, `id`, `input_descriptors` and `submission_requirements` properties MUST be supported.
* In the `input-descriptors` object, `id`, `name`, `purpose`, `group`, `format`, and `constraints` properties MUST be supported. In the `constraints` object, `limit_disclosure`, and `fields` properties MUST be supported. In the `fields` object, `path` and `filter` properties MUST be supported. A `path` MUST contain exactly one entry with a static path to a certain claim. A `filter` MUST only contain `type` elements of value `string` and `const` elements.
* In the `submission_requirements` object, `name`, `rule (`pick` only)`, `count`, `from` properties MUST be supported.

# OpenID for Verifiable Presentations over W3C Digital Credentials API

The following requirements apply for both, the Wallet and the Verifier, unless specified otherwise:

* MUST support Annex A in [@!OIDF.OID4VP] that defines how to use OpenID4VP over the W3C Digital Credentials API.
* The Wallet MUST support both signed and unsigned requests as defined in Annex A.3.1 and A.3.2 of [@!OIDF.OID4VP]. The Verifier MAY support signed requests, unsigned requests, or both.
* Wallet Invocation is done via the W3C Digital Credentials API or an equivalent platform API. Any other mechanism, including Custom URL schemes, MUST NOT be used.
* Response Mode MUST be `dc_api.jwt`. The response MUST be encrypted.
* Specific requirements for the response encryption are tbd (https://github.com/openid/oid4vc-haip/issues/131).
* The DCQL query and response as defined in Section 6 of [@!OIDF.OID4VP] MUST be used. Presentation Exchange as defined in Sections 5.4 and 5.5 of [@!OIDF.OID4VP] MUST NOT be used. Below is the list of features in the DCQL query and response that MUST be supported:
* tbd (https://github.com/openid/oid4vc-haip/issues/142)

## ISO mdoc specific requirements for OpenID for Verifiable Presentations over W3C Digital Credentials API

Requirements for both the Wallet and the Verifier:

* The Credential Format Identifier MUST be `mso_mdoc`.
* ISO mdoc Credential Format specific DCQL parameters as defined in Annex B.3.1 of [@!OIDF.OID4VP] MUST be used.
* Verifier MAY request more than one Credential in the same request.
* When multiple ISO mdocs are being returned, each ISO mdoc MUST be returned in a separate `DeviceResponse` (as defined in 8.3.2.1.2.2 of [@!ISO.18013-5]), each matching to a respective DCQL query. Therefore, the resulting `vp_token` contains multiple `DeviceResponse` instances.
* The `SessionTranscript` and `Handover` CBOR structures MUST be generated in accordance with Annex B.3.4.1 of [@!OIDF.OID4VP].

## IETF SD-JWT VC specific requirements for OpenID for Verifiable Presentations over W3C Digital Credentials API

Requirements for both the Wallet and the Verifier:

* The Credential Format identifier MUST be `dc+sd-jwt`.
* IETF SD-JWT VC Credential Format specific DCQL parameters as defined in Section 6.4.1 of [@!OIDF.OID4VP] MUST be used.

* MUST support protocol extensions for SD-JWT VC credential format profile as defined in this specification (#vc_sd_jwt_profile).
* As a way to invoke the Wallet, at least a custom URL scheme `haip://` MUST be supported. Implementations MAY support other ways to invoke the Wallets as agreed by trust frameworks/ecosystems/jurisdictions, not limited to using other custom URL schemes.
* Response type MUST be `vp_token`.
* Response mode MUST be `direct_post`. The Verifier MUST return `redirect_uri` in response to the HTTP POST request from the Wallet, where the Wallet redirects the User to, as defined in Section 6.2 of [@!OIDF.OID4VP]. Implementation considerations for the response mode `direct_post` are given in Section 11.5 of [@!OIDF.OID4VP].
* Authorization Request MUST be sent using the `request_uri` parameter as defined in JWT-Secured Authorization Request (JAR) [@!RFC9101].
* `client_id_scheme` parameter MUST be present in the Authorization Request.
* `client_id_scheme` value MUST be either `x509_san_dns` or `verifier_attestation`. The Wallet MUST support both. The Verifier MUST support at least one.
* To obtain the issuer's public key for verification, verifiers MUST support Web-based key resolution, as defined in Section 5 of [@!I-D.ietf-oauth-sd-jwt-vc]. The JOSE header `kid` MUST be used to identify the respective key.
* Presentation Definition JSON object MUST be sent using a `presentation_definition` parameter.
* The following features from the DIF Presentation Exchange v2.0.0 MUST be supported. A JSON schema for the supported features is in (#presentation-definition-schema):

# Self-Issued OP v2

To authenticate the user, subject identifier in a Self-Issued ID Token MUST be used as defined in [@!OIDF.SIOPv2].

* As a way to invoke the Wallet, at least a custom URL scheme `haip://` MUST be supported. Implementations MAY support other ways to invoke the wallets as agreed by trust frameworks/ecosystems/jurisdictions, not limited to using other custom URL schemes.
* `subject_syntax_types_supported` value MUST be `urn:ietf:params:oauth:jwk-thumbprint`
* As a way to invoke the Wallet, at least a custom URL scheme `haip://` MUST be supported. Implementations MAY support other ways to invoke the Wallets as agreed by trust frameworks/ecosystems/jurisdictions, not limited to using other custom URL schemes.
* `subject_syntax_types_supported` value MUST be `urn:ietf:params:oauth:jwk-thumbprint`

# SD-JWT VCs {#sd-jwt-vc}

Expand All @@ -276,7 +243,7 @@ This profile defines the following additional requirements for IETF SD-JWT VCs a
|status|SHOULD (at the discretion of the issuer)| [@!I-D.ietf-oauth-status-list]|

* The Issuer MUST NOT make any of the JWT Claims in the table above to be selectively disclosable, so that they are always present in the SD-JWT-VC presented by the Holder.
* It is at the discretion of the Issuer whether to use `exp` claim and/or a `status` claim to express the validity period of an SD-JWT-VC. The wallet and the verifier MUST support both mechanisms.
* It is at the discretion of the Issuer whether to use `exp` claim and/or a `status` claim to express the validity period of an SD-JWT-VC. The Wallet and the verifier MUST support both mechanisms.
* The `iss` claim MUST be an HTTPS URL. The `iss` value is used to obtain Issuer’s signing key as defined in (#issuer-key-resolution).
* The `vct` JWT claim as defined in [@!I-D.ietf-oauth-sd-jwt-vc].
* The `cnf` claim [@!RFC7800] MUST conform to the definition given in [@!I-D.ietf-oauth-sd-jwt-vc]. Implementations conforming to this profile MUST include the JSON Web Key [@!RFC7517] in the `jwk` sub claim.
Expand Down