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

Editorials, defined terms #85

Open
wants to merge 11 commits into
base: main
Choose a base branch
from
Open

Editorials, defined terms #85

Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
3d6a8f0
editorials: Crypto Suites - Closes https://github.com/openid/oid4vc-h…
peppelinux Dec 13, 2023
3eba3e5
fix: trailing spaces
peppelinux Dec 13, 2023
182e81b
Apply suggestions from code review
Dec 14, 2023
7d5d576
Apply suggestions from code review - Torsten's
Jan 6, 2024
0b1f972
Apply suggestions from code review
Jan 6, 2024
d5f5f04
Apply suggestions from code review
May 24, 2024
869e039
Apply suggestions from code review
May 24, 2024
0b847eb
Merge branch 'main' into sec8
peppelinux May 24, 2024
77136cf
fix: terminology
peppelinux Feb 6, 2025
d52312d
Apply suggestions from code review
peppelinux Feb 6, 2025
55b0391
Apply suggestions from code review
peppelinux Feb 7, 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
76 changes: 41 additions & 35 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", "Wallet", and "Verifiable Credential" as defined in @!OIDF.OID4VCI] and [@!OIDF.OID4VP].
This specification uses the terms "Holder", "Issuer", "Verifier", "Wallet", "Wallet Attestation", "Credential Type" and "Verifiable Credential" as defined in @!OIDF.OID4VCI] and [@!OIDF.OID4VP].
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should split this into terminology defined by specific specs ( termy x,y,z in VCI and a,b,c in VP) similar to how it is done in VCI and VP currently.

Copy link

@scvenema scvenema Feb 18, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@c2bo: Not sure what you are asking for here. I did a side-by-side comparison of the terms defined in the Terminology sections of the VP and VCI specs: there is a lot of overlap, but not 100%. Perhaps you are saying that a reference to clause 2 is needed in the references in this text? In any case, I think the first part of this this sentence should read "This specification uses terms such as..."


# Scope

Expand All @@ -74,23 +74,24 @@ 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)
* There are mechanisms in place for the verifiers and issuers to discover each other’s capability
* 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

The following items are out of scope for the current version of this document, but might be added in future versions:

* Trust Management, i.e. authorization of an issuer to issue certain types of credentials, authorization of the Wallet to be issued certain types of credentials, authorization of the Verifier to receive certain types of credentials.
* Trust Management, i.e. authorization of an Issuer to issue certain types of Credentials, authorization of the Wallet to be issued certain types of Credentials, authorization of the Verifier to receive certain types of Credentials.
* Protocol for presentation of Verifiable Credentials for offline use-cases, e.g. over BLE.
* Profile of OpenID4VCI to issue ISO mdoc [@!ISO.18013-5] is defined in ISO 23220-3.
* Profile of OpenID4VP without using W3C Digital Credentials API to present ISO mdocs is
defined in [@ISO.18013-7]. For more details, also see Annex B.3 in [@!OIDF.OID4VP].

## Scenarios/Business Requirements

* Combined Issuance of SD-JWT VC and mdoc
* Combined Issuance of IETF SD-JWT VC and ISO mdoc
* Both issuer-initiated and wallet-initiated issuance
* eIDAS PID and (Q)EAA as defined in eIDAS ARF 1.0

Expand All @@ -112,7 +113,7 @@ A parameter that is listed as optional to be implemented in a specification that
Both the Wallet and the Credential Issuer:

* MUST support the authorization code flow.
* MUST support protocol extensions for the SD-JWT VC credential format profile as defined in (#vc_sd_jwt_profile).
* MUST support protocol extensions for the SD-JWT VC Credential format profile as defined in (#vc_sd_jwt_profile).
* MUST support sender-constrained tokens using the mechanism defined in [@!RFC9449].
* MUST support [@!RFC7636] with `S256` as the code challenge method.

Expand All @@ -132,21 +133,21 @@ Both sending Credential Offer same-device and cross-device is supported.

* MUST use Pushed Authorization Requests (PAR) [@!RFC9126] to send the Authorization Request.
* Wallets MUST authenticate itself at the PAR endpoint using the same rules as defined in (#token-endpoint) for client authentication at the token endpoint.
* MUST use the `scope` parameter to communicate credential type(s) to be issued. The scope value MUST map to a specific Credential type. The scope value may be pre-agreed, obtained from the Credential Offer, or the Credential Issuer Metadata.
* MUST use the `scope` parameter to communicate Credential Type(s) to be issued. The scope value MUST map to a specific Credential Type. The scope value may be pre-agreed, obtained from the Credential Offer, or the Credential Issuer Metadata.
* The `client_id` value in the PAR request MUST be a string that the Wallet has used as the `sub` value in the client attestation JWT.

## Token Endpoint {#token-endpoint}

* The Wallets MUST perform client authentication as defined in (#wallet-attestation).
* Refresh tokens are RECOMMENDED to be supported for credential refresh. For details, see Section 13.5 in [@!OIDF.OID4VCI].
* Refresh tokens are RECOMMENDED to be supported for Credential refresh. For details, see Section 13.5 in [@!OIDF.OID4VCI].

Note: It is RECOMMENDED to use ephemeral client attestation JWTs for client authentication in order to prevent linkability across Credential Issuers.

Note: Issuers should be mindful of how long the usage of the refresh token is allowed to refresh a credential, as opposed to starting the issuance flow from the beginning. For example, if the User is trying to refresh a credential more than a year after its original issuance, the usage of the refresh tokens is NOT RECOMMENDED.
Note: Issuers SHOULD be mindful of how long the usage of the refresh token is allowed to refresh a credential, as opposed to starting the issuance flow from the beginning. For example, if the User is trying to refresh a Credential more than a year after its original issuance, the usage of the refresh tokens is NOT RECOMMENDED.

### Wallet Attestation {#wallet-attestation}

Wallets MUST use wallet attestations as defined in Annex E of [@!OIDF.OID4VCI].
Wallets MUST use Wallet Attestations as defined in Annex E of [@!OIDF.OID4VCI].

The public key, and optionally a trust chain, used to validate the signature on the Wallet Attestation MUST be included in the `x5c` JOSE header.

Expand All @@ -162,12 +163,12 @@ The public key, and optionally a trust chain, used to validate the signature on

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.
* 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 8.2 of [@!OIDF.OID4VP]. Implementation considerations for the response mode `direct_post.jwt` are given in Section 14.3 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.
* 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.
* The DCQL query and response as defined in Section 6 of [@!OIDF.OID4VP] MUST be used.

# OpenID for Verifiable Presentations over W3C Digital Credentials API
Expand Down Expand Up @@ -203,7 +204,7 @@ Requirements for both the Wallet and the Verifier:

# Self-Issued OP v2

To authenticate the user, subject identifier in a Self-Issued ID Token MUST be used as defined in [@!OIDF.SIOPv2].
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`
Expand All @@ -217,37 +218,37 @@ This profile defines the following additional requirements for IETF SD-JWT VCs a

| Claim | SD-JWT as issued by the Issuer | Normative Definition |
|:--- |:--- |:--- |
|iss |MUST |[@!RFC7519], Section 4.1.1 |
|iat |MUST |[@!RFC7519], Section 4.1.6 |
| exp | SHOULD (at the discretion of the issuer) | [@!RFC7519], Section 4.1.4 |
|cnf| MUST| [@!RFC7800]|
|vct| MUST| [@!I-D.ietf-oauth-sd-jwt-vc]|
|status|SHOULD (at the discretion of the issuer)| [@!I-D.ietf-oauth-status-list]|
| iss | MUST |[@!RFC7519], Section 4.1.1 |
| iat | MUST |[@!RFC7519], Section 4.1.6 |
| exp | SHOULD (at the discretion of the Issuer) | [@!RFC7519], Section 4.1.4 |
| cnf | MUST | [@!RFC7800]|
| vct | MUST | [@!I-D.ietf-oauth-sd-jwt-vc]|
|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.
* 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.

Note: Currently this profile only supports presentation of credentials with cryptographic Holder Binding: the holder's signature is required to proof the credential is presented by the holder it was issued to. This profile might support claim-based and biometrics-based holder binding once OpenID for Verifiable Credentials adds support for other forms of Holder Binding. See https://bitbucket.org/openid/connect/issues/1537/presenting-vc-without-a-vp-using-openid4vp
Note: Currently this profile only supports presentation of Credentials with cryptographic Holder Binding: the Holder's signature is required to proof the Credential is presented by the Holder it was issued to. This profile might support claim-based and biometrics-based Holder binding once OpenID for Verifiable Credentials adds support for other forms of Holder Binding. See [Presenting a VC without a VP using OpenID4VP](https://bitbucket.org/openid/connect/issues/1537/presenting-vc-without-a-vp-using-openid4vp).

Note: Re-using the same Credential across Verifiers, or re-using the same JWK value across multiple Credentials gives colluding Verifiers a mechanism to correlate the User. There are currently two known ways to address this with SD-JWT VCs. First is to issue multiple instances of the same credentials with different JWK values, so that if each instance of the credential is used at only one Verifier, it can be reused multiple times. Another is to use each credential only once (ephemeral credentials). It is RECOMMENDED to adopt one of these mechanisms.
Note: Re-using the same Credential across Verifiers, or re-using the same JWK value across multiple Credentials gives colluding Verifiers a mechanism to correlate the User. There are currently two known ways to address this with SD-JWT VCs. First is to issue multiple instances of the same Credentials with different JWK values, so that if each instance of the Credential is used at only one Verifier, it can be reused multiple times. Another is to use each Credential only once (ephemeral Credentials). It is RECOMMENDED to adopt one of these mechanisms.

Note: If there is a requirement to communicate information about the verification status and identity assurance data of the claims about the subject, the syntax defined by [@!OIDF.ekyc-ida] SHOULD be used. It is up to each jurisdiction and ecosystem, whether to require it to the implementers of this profile.

Note: If there is a requirement to provide the Subject’s identifier assigned and maintained by the Issuer, the `sub` claim MAY be used. There is no requirement for a binding to exist between the `sub` and `cnf` claims. See the Implementation Considerations section in [@!I-D.ietf-oauth-sd-jwt-vc].

Note: In some credential types, it is not desirable to include an expiration date (eg: diploma attestation). Therefore, this profile leaves its inclusion to the Issuer, or the body defining the respective credential type.
Note: In some Credential Types, it is not desirable to include an expiration date (eg: diploma attestation). Therefore, this profile leaves its inclusion to the Issuer, or the body defining the respective Credential Type.

## Issuer identification and key resolution to validate an issued Credential {#issuer-key-resolution}

This profile supports two ways to represent and resolve the key required to validate the issuer signature of an SD-JWT VC, the web PKI-based key resolution and the x.509 certificates.
This profile supports two ways to represent and resolve the key required to validate the Issuer signature of an SD-JWT VC, the web PKI-based key resolution and the x.509 certificates.

* Web-based key resolution: The key used to validate the Issuer’s signature on the SD-JWT VC MUST be obtained from the SD-JWT VC issuer's metadata 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.
* x.509 certificates: the SD-JWT VC contains the issuer's certificate along with a trust chain in the `x5c` JOSE header. In this case, the `iss` value MUST be an URL with a FQDN matching a `dNSName` Subject Alternative Name (SAN) [@!RFC5280] entry in the leaf certificate.
* Web-based key resolution: The key used to validate the Issuer’s signature on the SD-JWT VC MUST be obtained from the SD-JWT VC Issuer's metadata 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.
* x.509 certificates: the SD-JWT VC contains the Issuer's certificate along with a trust chain in the `x5c` JOSE header. In this case, the `iss` value MUST be an URL with a FQDN matching a `dNSName` Subject Alternative Name (SAN) [@!RFC5280] entry in the leaf certificate.

Note: The issuer MAY decide to support both options. In which case, it is at the discretion of the Wallet and the Verifier which key to use for the issuer signature validation.
Note: The Issuer MAY decide to support both options. In which case, it is at the discretion of the Wallet and the Verifier which key to use for the Issuer signature validation.

### Cryptographic Holder Binding between VC and VP

Expand All @@ -259,17 +260,22 @@ A Credential Format Profile for Credentials complying with IETF SD-JWT VCs [@!I-

# Crypto Suites

Issuers, holders and verifiers MUST support P-256 (secp256r1) as a key type with ES256 JWT algorithm for signing and signature validation whenever this profiles requires to do so:
Cryptography is required by the following operations:

- to sign and validate the signature on the Wallet Attestation and its proof of possession
- to sign and validate the Issuer's signature on the Verifiable Credential
- to sign and validate the Holder's signature on the Verifiable Presentation
- to sign and validate the Verifier's signature on the Presentation Request

Issuers, Holders, and Verifiers MUST support P-256 (secp256r1) as a key type with the ES256 JWT algorithm [@!RFC7518] for the creation and the verification of the above signatures.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Issuers, Holders, and Verifiers MUST support P-256 (secp256r1) as a key type with the ES256 JWT algorithm [@!RFC7518] for the creation and the verification of the above signatures.
Issuers, Holders, and Verifiers MUST at least support P-256 (secp256r1) as a key type with the ES256 JWT algorithm [@!RFC7518] for the creation and the verification of the above signatures.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • the intent is to allow using non P-256 algs. credential does not have to be signed using P-256. if credentials signed using other algs wants to use HAIP, they need to define
  • this intends to say P256 is a fall back and is minimum mandatory to implement
  • there might be secure areas that might have to add P256 compliance just to be HAIP compliant? which might be limiting
  • these requirements might make sense for issuance but not presentation?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • for the key for issuer signed data, Wallet has to accept P256 for SD-JWT/IssuerSigned (issuer communicates what it supports in the issuer metadata, can be P384).for the key for holder binding, issuer has to accept P256 for KB JWT/DeviceSigned;
  • for presentation, for RP, mandate P256 to use it to validate. no requirement for the wallet has the credential, it already has it.


When using this profile alongside other cryptosuites, each entity SHOULD make it explicit in its metadata which other algorithms and key types are supported for the cryptographic operations.

* SD-JWT-VC
* Wallet Instance Attestation
* DPoP
* HB JWT
* Authorization request during presentation
# Hash Algoritms

SHA256 MUST be supported by all the entities as the hash algorithm to generate and validate the digests in the SD-JWT VC.
The hash algorithm SHA256 MUST be supported by all the entities to generate and validate the digests in the IETF SD-JWT VC and ISO mdoc.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The hash algorithm SHA256 MUST be supported by all the entities to generate and validate the digests in the IETF SD-JWT VC and ISO mdoc.
The hash algorithm SHA-256 MUST be supported by all the entities to generate and validate the digests in the IETF SD-JWT VC and ISO mdoc.


Note: When using this profile with other cryptosuites, it is recommended to be explicit about which entity is required to support which curve for signing and/or signature validation
When using this profile alongside other hash algorithms, each entity SHOULD make it explicit in its metadata which other algorithms are supported.

# Implementations Considerations

Expand Down