sd-jwt vc profile for oid4vc

draft-oid4vc-haip-sd-jwt-vc.md

@@ -30,7 +30,7 @@ organization="yes.com"
 
 .# Abstract
 
-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.terbu-sd-jwt-vc].
+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].
 
 {mainmatter}
 
@@ -41,7 +41,7 @@ This document defines a set of requirements for the existing specifications to e
 
 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.terbu-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.
+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).
 
@@ -51,7 +51,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.terbu-sd-jwt-vc].
+This specification uses the terms "Holder", "Issuer", "Verifier", and "Verifiable Credential" as defined in [@!I-D.ietf-oauth-sd-jwt-vc].
 
 # Scope
 
@@ -96,14 +96,14 @@ Unless explicitly stated, all normative requirements apply to all participating
 |OID4VP| N/A |MUST|MUST|
 |OID4VCI| MUST|MUST|N/A|
 |SIOPv2|N/A|MUST|SHOULD|
-|SD-JWT VC|MUST|MUST|MUST|
+|SD-JWT VC profile as defined in (#sd-jwt-vc) |MUST|MUST|MUST|
 
 # OpenID for Verifiable Credential Issuance
 
 Implementations of this profile:
 
 * MUST support both pre-auth code flow and authorization code flow.
-* MUST support SD-JWT VC profile as defined in OID4VCI specification.
+* MUST support protocol extensions for SD-JWT VC credential format profile as defined in this specification (##vc_sd_jwt_profile).
 * MUST support sender-constrained Tokens using a mechanism as defined in [@!I-D.ietf-oauth-dpop].
 * MUST support [@!RFC7636] with `S256` as the code challenge method.
 
@@ -151,6 +151,7 @@ Note: Issuers should be mindful of how long the usage of the refresh token is al
 
 # OpenID for Verifiable Presentations
 
+   * 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` with `redirect_uri` as defined in Section 6.2 of [@!OIDF.OID4VP].
@@ -174,7 +175,7 @@ To authenticate the user, subject identifier in a Self-Issued ID Token MUST be u
 
 # SD-JWT VCs {#sd-jwt-vc}
 
-As credential format, SD-JWT VCs as defined in [@!I-D.terbu-sd-jwt-vc] MUST be used.
+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.
 
@@ -187,37 +188,120 @@ In addition, this profile defines the following additional requirements.
 |iat |MUST |[@!RFC7519], Section 4.1.6 |
 | exp | SHOULD (at the discretion of the issuer) | [@!RFC7519], Section 4.1.4 |
 |cnf|	MUST|	[@!RFC7800]|
-|type|	MUST| [@!I-D.terbu-sd-jwt-vc]|
+|type|	MUST| [@!I-D.ietf-oauth-sd-jwt-vc]|
 |status|SHOULD (at the discretion of the issuer)| [@!I-D.looker-oauth-jwt-cwt-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 `type` JWT claim as defined in [@!I-D.terbu-sd-jwt-vc].
-* The `cnf` claim [@!RFC7800] MUST conform to the definition given in [@!I-D.terbu-sd-jwt-vc]. Implementations conforming to this profile MUST include the JSON Web Key [@!RFC7517] in the `jwk` sub claim.
+* The `type` 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: 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 section X in [@!I-D.terbu-sd-jwt-vc] for implementation considerations.
+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.
 
 ## Issuer identification and key resolution to validate an issued Credential {#issuer-key-resolution}
 
-This profile supports two ways to represent and resolves the key required to validate the issuer signature of a SD-JWT VC, web PKI-based key resolution and 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.terbu-sd-jwt-vc]. The JOSE header `kid` MUST be used to identify the respective key.
+* 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.
 
 ### Cryptographic Holder Binding between VC and VP
 
-* For Cryptographic Holder Binding, an HB-JWT as defined in [@!I-D.terbu-sd-jwt-vc] MUST always be present when presenting a SD-JWT VC.
+* For Cryptographic Holder Binding, a KB-JWT as defined in [@!I-D.ietf-oauth-sd-jwt-vc] MUST always be present when presenting an SD-JWT VC.
+
+## OpenID4VC Credential Format Profile {#vc_sd_jwt_profile}
+
+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.
+
+### Format Identifier
+
+The Credential format identifier is `vc+sd-jwt`. This format identifier is used in issuance and presentation requests.
+
+### Credential Issuer Metadata {#server_metadata_vc_sd-jwt}
+
+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 two sub elements:
+  * `type`: 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:
+        * `name`: OPTIONAL. String value of a display name for the claim.
+        * `locale`: OPTIONAL. String value that identifies language of this object represented as language tag values defined in BCP47 [@!RFC5646]. There MUST be only one object for each language identifier.
+* `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`.
+
+<{{examples/credential_metadata_sd_jwt_vc.json}}
+
+### Credential Offer
+
+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 (#server_metadata_vc_sd-jwt).
+
+The following is a non-normative example of an object comprising `credentials_supported` parameter of Credential format `vc+sd-jwt`.
+
+<{{examples/credential_offer_sd_jwt_vc.json}}
+
+### Authorization Details {#authorization_vc_sd-jwt}
+
+The following additional claims are defined for authorization details of type `openid_credential` and 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 (#server_metadata_vc_sd-jwt). It MAY contain `claims` property as defined in (#server_metadata_vc_sd-jwt).
+
+The following is a non-normative example of an authorization details object with Credential format `vc+sd-jwt`.
+
+<{{examples/authorization_details_sd_jwt_vc.json}}
+
+### Credential Request
+
+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 `type` property as defined in (#server_metadata_vc_sd-jwt). It MAY contain `claims` property as defined in (#server_metadata_vc_sd-jwt).
+
+The following is a non-normative example of a Credential Request with Credential format `vc+sd-jwt`.
+
+<{{examples/credential_request_sd_jwt_vc.json}}
+
+### Credential Response {#credential_response_jwt_vc_json}
+
+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`.
+
+<{{examples/credential_response_sd_jwt_vc.txt}}
+
+### Verifier Metadata
+
+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.
+
+<{{examples/client_metadata_sd_jwt_vc.json}}
+
+### Presentation Definition
+
+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.
+
+<{{examples/presentation_definition_sd_jwt_vc.json}}
 
 # Crypto Suites
 

examples/authorization_details_sd_jwt_vc.json

@@ -0,0 +1,9 @@
+[
+    {
+        "type": "openid_credential",
+        "format": "vc+sd-jwt",
+        "credential_definition": {
+            "type": "IdentityCredential"
+        }
+    }
+]

examples/client_metadata_sd_jwt_vc.json

@@ -0,0 +1,14 @@
+{
+    "vp_formats": {
+        "vc+sd-jwt": {
+            "sd-jwt_alg_values": [
+                "ES256",
+                "ES384"
+            ],
+            "kb-jwt_alg_values": [
+                "ES256",
+                "ES384"
+            ]
+        }
+    }
+}

examples/credential_metadata_sd_jwt_vc.json

@@ -0,0 +1,66 @@
+{
+    "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",
+}

examples/credential_offer_sd_jwt_vc.json

@@ -0,0 +1,16 @@
+{
+    "credential_issuer": "https://credential-issuer.example.com",
+    "credentials": [
+        {
+            "format": "vc+sd-jwt",
+            "credential_definition": {
+                "type": "IdentityCredential"
+            }
+        }
+    ],
+    "grants": {
+        "authorization_code": {
+            "issuer_state": "eyJhbGciOiJSU0Et...FYUaBy"
+        }
+    }
+}

examples/credential_request_sd_jwt_vc.json

@@ -0,0 +1,13 @@
+{
+   "format": "vc+sd-jwt",
+   "credential_definition": {
+      "type": "IdentityCredential"
+   },
+   "proof": {
+      "proof_type": "jwt",
+      "jwt":"eyJraWQiOiJkaWQ6ZXhhbXBsZTplYmZlYjFmNzEyZWJjNmYxYzI3NmUxMmVjMjEva2V5cy8
+      xIiwiYWxnIjoiRVMyNTYiLCJ0eXAiOiJKV1QifQ.eyJpc3MiOiJzNkJoZFJrcXQzIiwiYXVkIjoiaHR
+      0cHM6Ly9zZXJ2ZXIuZXhhbXBsZS5jb20iLCJpYXQiOiIyMDE4LTA5LTE0VDIxOjE5OjEwWiIsIm5vbm
+      NlIjoidFppZ25zbkZicCJ9.ewdkIkPV50iOeBUqMXCC_aZKPxgihac0aW9EkL1nOzM"
+   }
+}