Skip to content

Commit

Permalink
editorials: Crypto Suites - Closes #69
Browse files Browse the repository at this point in the history
  • Loading branch information
peppelinux committed Dec 13, 2023
1 parent 75a1722 commit 3d6a8f0
Showing 1 changed file with 42 additions and 27 deletions.
69 changes: 42 additions & 27 deletions draft-oid4vc-haip-sd-jwt-vc.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,9 @@ The audience of the document is implementers that require a high level of securi

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

Wallet Instance Attestation:
: Proof or assertion that the Wallet Instance is genuine, has not been tampered with, and can be trusted to securely handle Verifiable Credentials. The Wallet Instance Attestation MUST be issued by a trustwhorty entity or entity for which it is possible to evaluate trust in relation to a trust framework and a regulatory framework shared among all participants.

# Scope

The following aspects are in scope of this interoperability profile:
Expand All @@ -70,20 +73,20 @@ The following aspects are in scope of this interoperability profile:

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.

## Scenarios/Business Requirements

* Combined Issuance of SD-JWT VC and mdoc
* Combined Issuance of 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 Down Expand Up @@ -112,7 +115,7 @@ 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).
* 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 @@ -162,7 +165,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 attestions MUST support web-based key resolution as defined in Section 5 of [@!I-D.terbu-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.terbu-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 @@ -174,7 +177,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 @@ -209,7 +212,7 @@ This is an example of a Wallet Instance Attestation:
* 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.
* 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):

Expand Down Expand Up @@ -237,18 +240,18 @@ In addition, this profile defines the following additional requirements.
|:--- |:--- |:--- |
|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 |
| 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]|
|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 [@!I-D.ietf-oauth-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 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.

Expand All @@ -260,12 +263,12 @@ Note: In some credential types, it is not desirable to include an expiration dat

## 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 Down Expand Up @@ -339,8 +342,8 @@ The following is a non-normative example of a Credential Response with Credentia

The Verifier SHOULD add a `vp_formats` element to its metadata (e.g. in the `client_metadata` authorization request parameter) to let the wallet know what protection algorithms it supports in conjunction with SD-JWT VCs. The format element MUST have the key `vc+sd-jwt`, the value is an object consisting of the following elements:

* `sd-jwt_alg_values`: OPTIONAL. A JSON array containing identifiers of cryptographic algorithms the verifier supports for protection of a SD-JWT. If present, the `alg` JOSE header (as defined in [@!RFC7515]) of the presented SD-JWT MUST match one of the array values.
* `kb-jwt_alg_values`: OPTIONAL. A JSON array containing identifiers of cryptographic algorithms the verifier supports for protection of a KB-JWT. If present, the `alg` JOSE header (as defined in [@!RFC7515]) of the presented KB-JWT MUST match one of the array values.
* `sd-jwt_alg_values`: OPTIONAL. A JSON array containing identifiers of cryptographic algorithms the Verifier supports for protection of a SD-JWT. If present, the `alg` JOSE header (as defined in [@!RFC7515]) of the presented SD-JWT MUST match one of the array values.
* `kb-jwt_alg_values`: OPTIONAL. A JSON array containing identifiers of cryptographic algorithms the Verifier supports for protection of a KB-JWT. If present, the `alg` JOSE header (as defined in [@!RFC7515]) of the presented KB-JWT MUST match one of the array values.

The following is a non-normative example of `client_metadata` request parameter value in a request to present a SD-JWT VC.

Expand All @@ -356,17 +359,29 @@ The following is a non-normative example of a presentation definition for a SD-J

# 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:
The cryptographic features are required by the following operations:

- Attestation of trust with the entities of the ecosystem.
- Issuance and presentation using the cryptografic proof of possession of the Wallet Instance Attestations.
- Issuance of the Verifiable Credentials.
- Presentation Authorization requests: the process where a Verifier requests to the Holder the presentation of the Verifiable Credentials.
- Presentation using the cryptografic proof of possession of the Credentials.

With the aim to ensure a secure interoperability model for all ecosystem participants,
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 signatures,
This requirement is also in accordance with the following specifications, which complement the High Assurance Interoperability Profile:

- SD-JWT-VC [@!I-D.ietf-oauth-sd-jwt-vc]
- DPoP [@!RFC9449]
- OAuth 2.0 Attestation-Based Client Authentication [@!I-D.looker-oauth-attestation-based-client-auth]

When using this profile alongside other cryptosuites, each entity SHOULD explicit the supported algorithms and key types in its metadata for the processes of the signature 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 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 explicit the supported algorithms in its metadata.

# Implementations Considerations

Expand Down

0 comments on commit 3d6a8f0

Please sign in to comment.