diff --git a/index.html b/index.html index d86727d..8bb4ab6 100644 --- a/index.html +++ b/index.html @@ -24,6 +24,15 @@
oid4vc-haip-sd-jwt-vc | +plain text | +diff with main | +
+ | oid4vc-haip-sd-jwt-vc | +November 2023 | +
Yasuda & Lodderstedt | +Standards Track | +[Page] | +
This document defines a profile of OpenID for Verifiable Credentials in combination with the credential format SD-JWT VC. The aim is to select features and to define a set of requirements for the existing specifications to enable interoperability among Issuers, Wallets and Verifiers of Credentials where a high level of security and privacy is required. The profiled specifications include OpenID for Verifiable Credential Issuance [OIDF.OID4VCI], OpenID for Verifiable Presentations [OIDF.OID4VP], Self-Issued OpenID Provider v2 [OIDF.SIOPv2], and SD-JWT VC [I-D.ietf-oauth-sd-jwt-vc].¶
+This document defines a set of requirements for the existing specifications to enable interoperability among Issuers, Wallets and Verifiers of Credentials where a high level of security and privacy is required. This document is an interoperability profile that can be used by implementations in various contexts, be it a certain industry or a certain regulatory environment.¶
+This document is not a specification, but a profile. It refers to the specifications required for implementations to interoperate among each other and for the optionalities mentioned in the referenced specifications, defines the set of features to be mandatory to implement.¶
+The profile uses OpenID for Verifiable Credential Issuance [OIDF.OID4VCI] and OpenID for Verifiable Presentations [OIDF.OID4VP] as the base protocols for issuance and presentation of Credentials, respectively. The credential format used is SD-JWT VC as specified in [I-D.ietf-oauth-sd-jwt-vc]. Additionally, considerations are given on how deployments can perform a combined issuance of credentials in both SD-JWT VC and ISO mdoc [ISO.18013-5] formats.¶
+A full list of the open standards used in this profile can be found in Overview of the Open Standards Requirements (reference).¶
+The audience of the document is implementers that require a high level of security and privacy for their solutions. A non-exhaustive list of the interested parties includes eIDAS 2.0, California Department of Motor Vehicles, Open Wallet Foundation (OWF), IDunion, GAIN, and the Trusted Web project of the Japanese government, but is expected to grow to include other jurisdictions and private sector companies.¶
+This specification uses the terms "Holder", "Issuer", "Verifier", and "Verifiable Credential" as defined in [I-D.ietf-oauth-sd-jwt-vc].¶
+The following aspects are in scope of this interoperability profile:¶
+Assumptions made are the following:¶
+The following items are out of scope for the current version of this document, but might be added in future versions:¶
+Unless explicitly stated, all normative requirements apply to all participating entities: Issuers, Wallets and Verifiers.¶
+(as defined in this profile) | +Issuer | +Wallet | +Verifier | +
---|---|---|---|
OID4VP | +N/A | +MUST | +MUST | +
OID4VCI | +MUST | +MUST | +N/A | +
SIOPv2 | +N/A | +MUST | +SHOULD | +
SD-JWT VC profile as defined in Section 7 + | +MUST | +MUST | +MUST | +
Implementations of this profile:¶
+S256
as the code challenge method.¶
+Both Wallet initiated and Issuer initiated issuance is supported.¶
+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]¶
+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). (pending OID4VCI PR#519)¶
+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.¶
+Both sending Credential Offer same-device and cross-device is supported.¶
+authorization_pending
and slow_down
, and the credential offer parameter interval
.¶
+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.¶
+Wallets MUST use attestations following the definition given in [I-D.ietf-oauth-attestation-based-client-auth].¶
+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 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
:¶
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.¶
+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.¶
+secure_element
: It SHOULD be used when the Wallet uses a Secure Element for key management.¶
+hsm
: It SHOULD be used when the Wallet uses Hardware Security Module (HSM).¶
+user_authentication
: OPTIONAL. JSON String that asserts the security mechanism the Wallet uses to authenticate the user to authorize access to the private key associated with the public key given in the cnf
claim. This specification defines the following values for user_authentication
:¶
system_biometry
: It MUST be used when the key usage is authorized by the mobile operating system using a biometric factor.¶
+system_pin
: It MUST be used when the key usage is authorized by the mobile operating system using personal identification number (PIN).¶
+internal_biometry
: It MUST be used when the key usage is authorized by the Wallet using a biometric factor.¶
+internal_pin
: It MUST be used when the key usage is authorized by the Wallet using PIN.¶
+secure_element_pin
It MUST be used when the key usage is authorized by the secure element managing the key itself using PIN.¶
+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.¶
This is an example of a Wallet Instance Attestation:¶
+{ + "typ": "wallet-attestation+jwt", + "alg": "ES256", + "kid": "1" +} +. +{ + "iss": "<identifier of the issuer of this wallet attestation>", + "sub": "<`client_id` of the OAuth client>", + "iat": 1516247022, + "exp": 1541493724, + "aal" : "https://trust-list.eu/aal/high", + "cnf": { + "jwk": { + "kty": "EC", + "crv": "P-256", + "x": "TCAER19Zvu3OHF4j4W4vfSVoHIP1ILilDls7vCeGemc", + "y": "ZxjiWWbZMQGHVWKVQ4hbSIirsVfuecCE6t4jT9F2HZQ" + }, + "key_type": "strong_box", + "user_authentication": "system_pin", + } +} + +¶ +
JWT
proof type MUST be supported.¶
+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.¶
+vp_token
.¶
+direct_post
with redirect_uri
as defined in Section 6.2 of [OIDF.OID4VP].¶
+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
. Wallet MUST support both. Verifier MUST support at least one. (pending OID4VCI PR #524 for verifier_attestation)¶
+kid
MUST be used to identify the respective key.¶
+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 Appendix B:¶
+presentation_definition
object, id
, input_descriptors
and submission_requirements
properties MUST be supported.¶
+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.¶
+submission_requirements
object, name
, rule (
pickonly)
, count
, from
properties MUST be supported.¶
+To authenticate the user, subject identifier in a Self-Issued ID Token MUST be used as defined in [OIDF.SIOPv2].¶
+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 credential format, SD-JWT VCs as defined in [I-D.ietf-oauth-sd-jwt-vc] MUST be used.¶
+In addition, this profile defines the following additional requirements.¶
+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.looker-oauth-jwt-cwt-status-list] + | +
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.¶
+iss
claim MUST be an HTTPS URL. The iss
value is used to obtain Issuer’s signing key as defined in Section 7.1.¶
+vct
JWT claim as defined in [I-D.ietf-oauth-sd-jwt-vc].¶
+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: 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, sub
claim MAY be used. There is no requirement for a binding to exist between sub
and cnf
claims. See 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.¶
+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.¶
+kid
MUST be used to identify the respective key.¶
+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.¶
+This section specifies how SD-JWT VCs as defined in [I-D.ietf-oauth-sd-jwt-vc] are used in conjunction with the OpenID4VC specifications.¶
+The Credential format identifier is vc+sd-jwt
. This format identifier is used in issuance and presentation requests.¶
The following additional Credential Issuer metadata are defined for this Credential format to be used in addition to those defined in Section 10.2 of [OIDF.OID4VCI].¶
+credential_definition
: REQUIRED. JSON object containing the detailed description of the credential type. It consists at least of the following three sub elements:¶
vct
: REQUIRED. JSON string designating the type of a credential as defined in [I-D.ietf-oauth-sd-jwt-vc], Section 4.2.2.1.¶
+claims
: OPTIONAL. A JSON object containing a list of name/value pairs, where each name identifies a claim offered in the Credential. The value can be another such object (nested data structures), or an array of such objects. To express the specifics about the claim, the most deeply nested value MAY be a JSON object that includes a following non-exhaustive list of parameters defined by this specification:¶
mandatory
: OPTIONAL. Boolean which when set to true
indicates the claim MUST be present in the issued Credential. If the mandatory
property is omitted its default should be assumed to be false
.¶
+value_type
: OPTIONAL. String value determining type of value of the claim. A non-exhaustive list of valid values defined by this specification are string
, number
, and image media types such as image/jpeg
as defined in IANA media type registry for images (https://www.iana.org/assignments/media-types/media-types.xhtml#image).¶
+display
: OPTIONAL. An array of objects, where each object contains display properties of a certain claim in the Credential for a certain language. Below is a non-exhaustive list of valid parameters that MAY be included:¶
order
: OPTIONAL. An array of claims.display.name values that lists them in the order they should be displayed by the Wallet.¶
+The following is a non-normative example of an object comprising credentials_supported
parameter of Credential format vc+sd-jwt
.¶
{ + "format": "vc+sd-jwt", + "scope": "IdentityCredential_SD-JWT-VC", + "cryptographic_binding_methods_supported": [ + "did:example" + ], + "cryptographic_suites_supported": [ + "ES256K" + ], + "display": [ + { + "name": "IdentityCredential", + "locale": "en-US", + "background_color": "#12107c", + "text_color": "#FFFFFF" + } + ], + "credential_definition": { + "type": "IdentityCredential", + "claims": { + "given_name": { + "display": [ + { + "name": "Given Name", + "locale": "en-US" + }, + { + "name": "Vorname", + "locale": "de-DE" + } + ] + }, + "last_name": { + "display": [ + { + "name": "Surname", + "locale": "en-US" + }, + { + "name": "Nachname", + "locale": "de-DE" + } + ] + }, + "email": {}, + "phone_number": {}, + "address": { + "street_address": {}, + "locality": {}, + "region": {}, + "country": {} + }, + "birthdate": {}, + "is_over_18": {}, + "is_over_21": {}, + "is_over_65": {} + } + } +} + + +{ + "type": "IdentityCredential", + "given_name": "John", + "family_name": "Doe", +} + +¶ +
The following additional claims are defined for this Credential format.¶
+credential_definition
: REQUIRED. JSON object containing the detailed description of the credential type. It MUST contain at least type
property as defined in Section 7.2.2.¶
+The following is a non-normative example of an object comprising credentials_supported
parameter of Credential format vc+sd-jwt
.¶
{ + "credential_issuer": "https://credential-issuer.example.com", + "credentials": [ + "IdentityCredential_SD-JWT-VC" + ], + "grants": { + "authorization_code": { + "issuer_state": "eyJhbGciOiJSU0Et...FYUaBy" + } + } +} + +¶ +
The following additional parameters are defined for Credential Requests and this Credential format.¶
+credential_definition
: REQUIRED. JSON object containing the detailed description of the credential type. It MUST contain at least vct
property as defined in Section 7.2.2. It MAY contain claims
property as defined in Section 7.2.2.¶
+The following is a non-normative example of a Credential Request with Credential format vc+sd-jwt
.¶
{ + "format": "vc+sd-jwt", + "credential_definition": { + "type": "IdentityCredential" + }, + "proof": { + "proof_type": "jwt", + "jwt":"eyJraWQiOiJkaWQ6ZXhhbXBsZTplYmZlYjFmNzEyZWJjNmYxYzI3NmUxMmVjMjEva2V5cy8 + xIiwiYWxnIjoiRVMyNTYiLCJ0eXAiOiJKV1QifQ.eyJpc3MiOiJzNkJoZFJrcXQzIiwiYXVkIjoiaHR + 0cHM6Ly9zZXJ2ZXIuZXhhbXBsZS5jb20iLCJpYXQiOiIyMDE4LTA5LTE0VDIxOjE5OjEwWiIsIm5vbm + NlIjoidFppZ25zbkZicCJ9.ewdkIkPV50iOeBUqMXCC_aZKPxgihac0aW9EkL1nOzM" + } +} + +¶ +
The value of the credential
claim in the Credential Response MUST be a JSON string that is an SD-JWT VC. Credentials of this format are already suitable for transfer and, therefore, they need not and MUST NOT be re-encoded.¶
The following is a non-normative example of a Credential Response with Credential format vc+sd-jwt
.¶
The Verifier SHOULD add a vp_formats_supported
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.¶
+The following is a non-normative example of client_metadata
request parameter value in a request to present a SD-JWT VC.¶
{ + "vp_formats": { + "vc+sd-jwt": { + "sd-jwt_alg_values": [ + "ES256", + "ES384" + ], + "kb-jwt_alg_values": [ + "ES256", + "ES384" + ] + } + } +} + +¶ +
The presentation of a SD-JWT VC is requested by adding an object named vc+sd-jwt
to the format
object of an input_descriptor
. The object is empty.¶
The following is a non-normative example of a presentation definition for a SD-JWT VC.¶
+{ + "id": "d76c51b7-ea90-49bb-8368-6b3d194fc131", + "input_descriptors": [ + { + "id": "IdentityCredential", + "format": { + "vc+sd-jwt": {} + }, + "constraints": { + "limit_disclosure": "required", + "fields": [ + { + "path": [ + "$.type" + ], + "filter": { + "type": "string", + "const": "IdentityCredential" + } + }, + { + "path": [ + "$.family_name" + ] + }, + { + "path": [ + "$.given_name" + ] + } + ] + } + } + ] +} + +¶ +
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:¶
+SHA256 MUST be supported by all the entities as the hash algorithm to generate and validate the digests in the SD-JWT VC.¶
+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¶
+iat
and exp
JWT claims express both the validity period of both the signature and the claims about the subject, unless there is a separate claim used to express the validity of the claims.¶
{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "Presentation Definition for a High Assurance Profile", + "type": "object", + "properties": { + "presentation_definition": { + "$ref": "#/definitions/presentation_definition" + } + }, + "definitions": { + "presentation_definition": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "input_descriptors": { + "type": "array", + "items": { + "$ref": "#/definitions/input_descriptor" + } + }, + "submission_requirements": { + "type": "array", + "items": { + "$ref": "#/definitions/submission_requirement" + } + } + }, + "required": [ + "id", + "input_descriptors" + ], + "additionalProperties": false + }, + "input_descriptor": { + "type": "object", + "additionalProperties": false, + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "purpose": { + "type": "string" + }, + "format": { + "$ref": "http://identity.foundation/claim-format-registry/schemas/presentation-definition-claim-format-designations.json" + }, + "group": { + "type": "array", + "items": { + "type": "string" + } + }, + "constraints": { + "type": "object", + "additionalProperties": false, + "properties": { + "limit_disclosure": { + "type": "string", + "enum": [ + "required", + "preferred" + ] + }, + "fields": { + "type": "array", + "items": { + "path": { + "type": "array", + "items": { + "type": "string" + } + }, + "filter": { + "$ref": "http://json-schema.org/draft-07/schema#" + } + } + } + } + } + }, + "required": [ + "id", + "constraints" + ] + }, + "submission_requirement": { + "type": "object", + "oneOf": [ + { + "properties": { + "name": { + "type": "string" + }, + "rule": { + "type": "string", + "enum": [ + "pick" + ] + }, + "count": { + "type": "integer", + "minimum": 1 + }, + "from": { + "type": "string" + } + }, + "required": [ + "rule", + "from" + ], + "additionalProperties": false + } + ] + } + } + } + + +¶ +
oid4vc-haip-sd-jwt-vc | +plain text | +same as main | +