SD-JWT-based Verifiable Credentials (SD-JWT VC)

Internet-Draft	SD-JWT VC	December 2024
Terbu, et al.	Expires 6 June 2025	[Page]

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 6 June 2025.¶

Copyright Notice

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

1. Introduction

1.1. Issuer-Holder-Verifier Model

In the so-called Issuer-Holder-Verifier Model, Issuers issue so-called Verifiable Credentials to a Holder, who can then present the Verifiable Credentials to Verifiers. Verifiable Credentials are cryptographically secured statements about a Subject, typically the Holder.¶

         +------------+
         |            |
         |   Issuer   |
         |            |
         +------------+
               |
    Issues Verifiable Credential
               |
               v
         +------------+
         |            |
         |   Holder   |
         |            |
         +------------+
               |
  Presents Verifiable Credential
               |
               v
         +-------------+
         |             |+                          +------------+
         |  Verifiers  ||+                         |   Status   |
         |             |||----- optionally ------->|  Provider  |
         +-------------+||   retrieve status of    |            |
          +-------------+|  Verifiable Credential  +------------+
           +-------------+

Figure 1: Issuer-Holder-Verifier Model with optional Status Provider

Verifiers can check the authenticity of the data in the Verifiable Credentials and optionally enforce Key Binding, i.e., ask the Holder to prove that they are the intended holder of the Verifiable Credential, for example, by proving possession of a cryptographic key referenced in the credential. This process is further described in [I-D.ietf-oauth-selective-disclosure-jwt].¶

To support revocation of Verifiable Credentials, revocation information can optionally be retrieved from a Status Provider. The role of a Status Provider can be fulfilled by either a fourth party or by the Issuer.¶

1.2. SD-JWT as a Credential Format

JSON Web Tokens (JWTs) [RFC7519] can in principle be used to express Verifiable Credentials in a way that is easy to understand and process as it builds upon established web primitives.¶

Selective Disclosure JWT (SD-JWT) [I-D.ietf-oauth-selective-disclosure-jwt] is a specification that introduces conventions to support selective disclosure for JWTs: For an SD-JWT document, a Holder can decide which claims to release (within bounds defined by the Issuer).¶

SD-JWT is a superset of JWT as it can also be used when there are no selectively disclosable claims and also supports JWS JSON serialization, which is useful for long term archiving and multi signatures. However, SD-JWT itself does not define the claims that must be used within the payload or their semantics.¶

This specification uses SD-JWT and the well-established JWT content rules and extensibility model as basis for representing Verifiable Credentials with JSON payloads. These Verifiable Credentials are called SD-JWT VCs. The use of selective disclosure in SD-JWT VCs is OPTIONAL.¶

SD-JWTs VC can contain claims that are registered in "JSON Web Token Claims" registry as defined in [RFC7519], as well as public and private claims.¶

Note: This specification does not utilize the W3C's Verifiable Credentials Data Model v1.0, v1.1, or v2.0.¶

1.3. Requirements Notation and Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119].¶

1.4. Terms and Definitions

This specification uses the terms "Holder", "Issuer", "Verifier", "Key Binding", and "Key Binding JWT" defined by [I-D.ietf-oauth-selective-disclosure-jwt].¶

Consumer:: Applications using the Type Metadata specified in Section 6 are called Consumer. This typically includes Issuers, Verifiers, and Wallets.¶
Verifiable Credential (VC):: An assertion with claims about a Subject that is cryptographically secured by an Issuer (usually by a digital signature).¶
SD-JWT-based Verifiable Credential (SD-JWT VC):: A Verifiable Credential encoded using the format defined in [I-D.ietf-oauth-selective-disclosure-jwt]. It may or may not contain selectively disclosable claims.¶
Unsecured Payload of an SD-JWT VC:: A JSON object containing all selectively disclosable and non-selectively disclosable claims of the SD-JWT VC. The Unsecured Payload acts as the input JSON object to issue an SD-JWT VC complying to this specification.¶
Status Provider:: An entity that provides status information (e.g. revocation) about a Verifiable Credential.¶

2. Scope

This specification defines¶
- Data model and media types for Verifiable Credentials based on SD-JWTs.¶
- Validation and processing rules for Verifiers and Holders.¶

3. Verifiable Credentials based on SD-JWT

This section defines encoding, validation and processing rules for SD-JWT VCs.¶

3.1. Media Type

SD-JWT VCs compliant with this specification MUST use the media type application/dc+sd-jwt as defined in Section 3.1.¶

The base subtype name dc is meant to stand for "digital credential", which is a term that is emerging as a conceptual synonym for "verifiable credential".¶

3.2. Data Format

SD-JWT VCs MUST be encoded using the SD-JWT format defined in Section 4 of [I-D.ietf-oauth-selective-disclosure-jwt]. A presentation of an SD-JWT VC MAY contain a Key Binding JWT.¶

Note that in some cases, an SD-JWT VC MAY have no selectively disclosable claims, and therefore the encoded SD-JWT will not contain any Disclosures.¶

3.2.1. JOSE Header

This section defines JWT header parameters for the SD-JWT component of the SD-JWT VC.¶

The typ header parameter of the SD-JWT MUST be present. The typ value MUST use dc+sd-jwt. This indicates that the payload of the SD-JWT contains plain JSON and follows the rules as defined in this specification. It further indicates that the SD-JWT is a SD-JWT component of a SD-JWT VC.¶

The following is a non-normative example of a decoded SD-JWT header:¶

{
  "alg": "ES256",
  "typ": "dc+sd-jwt"
}

Note that this draft used vc+sd-jwt as the value of the typ header from its inception in July 2023 until November 2024 when it was changed to dc+sd-jwt to avoid conflict with the vc media type name registered by the W3C's Verifiable Credentials Data Model draft. In order to facilitate a minimally disruptive transition, it is RECOMMENDED that Verifiers and Holders accept both vc+sd-jwt and dc+sd-jwt as the value of the typ header for a reasonable transitional period.¶

3.2.2. JWT Claims Set

This section defines the claims that can be included in the payload of SD-JWT VCs.¶

3.2.2.1. New JWT Claims

3.2.2.1.1. Verifiable Credential Type - `vct` Claim

This specification defines the JWT claim vct (for verifiable credential type). The vct value MUST be a case-sensitive StringOrURI (see [RFC7519]) value serving as an identifier for the type of the SD-JWT VC. The vct value MUST be a Collision-Resistant Name as defined in Section 2 of [RFC7515].¶

A type is associated with rules defining which claims may or must appear in the Unsecured Payload of the SD-JWT VC and whether they may, must, or must not be selectively disclosable. This specification does not define any vct values; instead it is expected that ecosystems using SD-JWT VCs define such values including the semantics of the respective claims and associated rules (e.g., policies for issuing and validating credentials beyond what is defined in this specification).¶

The following is a non-normative example of how vct is used to express a type:¶

{
  "vct": "https://credentials.example.com/identity_credential"
}

For example, a value of https://credentials.example.com/identity_credential can be associated with rules that define that at least the registered JWT claims given_name, family_name, birthdate, and address must appear in the Unsecured Payload. Additionally, the registered JWT claims email and phone_number, and the private claims is_over_18, is_over_21, and is_over_65 may be used. The type might also indicate that any of the aforementioned claims can be selectively disclosable.¶

3.2.2.2. Registered JWT Claims

SD-JWT VCs MAY use any claim registered in the "JSON Web Token Claims" registry as defined in [RFC7519].¶

If present, the following registered JWT claims MUST be included in the SD-JWT and MUST NOT be included in the Disclosures, i.e. cannot be selectively disclosed:¶

iss¶
- REQUIRED. The Issuer of the Verifiable Credential. The value of iss MUST be a URI. See [RFC7519] for more information.¶
nbf¶
- OPTIONAL. The time before which the Verifiable Credential MUST NOT be accepted before validating. See [RFC7519] for more information.¶
exp¶
- OPTIONAL. The expiry time of the Verifiable Credential after which the Verifiable Credential is no longer valid. See [RFC7519] for more information.¶
cnf¶
- OPTIONAL unless cryptographic Key Binding is to be supported, in which case it is REQUIRED. Contains the confirmation method identifying the proof of possession key as defined in [RFC7800]. It is RECOMMENDED that this contains a JWK as defined in Section 3.2 of [RFC7800]. For proof of cryptographic Key Binding, the Key Binding JWT in the presentation of the SD-JWT MUST be secured by the key identified in this claim.¶
vct¶
- REQUIRED. The type of the Verifiable Credential, e.g., https://credentials.example.com/identity_credential, as defined in Section 3.2.2.1.1.¶
status¶
- OPTIONAL. The information on how to read the status of the Verifiable Credential. See [I-D.ietf-oauth-status-list] for more information.¶

The following registered JWT claims MAY be contained in the SD-JWT or in the Disclosures and MAY be selectively disclosed:¶

sub¶
- OPTIONAL. The identifier of the Subject of the Verifiable Credential. The Issuer MAY use it to provide the Subject identifier known by the Issuer. There is no requirement for a binding to exist between sub and cnf claims.¶
iat¶
- OPTIONAL. The time of issuance of the Verifiable Credential. See [RFC7519] for more information.¶

3.2.2.3. Public JWT claims

Additional public claims MAY be used in SD-JWT VCs depending on the application.¶

3.2.2.4. SD-JWT VC without Selectively Disclosable Claims

An SD-JWT VC MAY have no selectively disclosable claims. In that case, the SD-JWT VC MUST NOT contain the _sd claim in the JWT body. It also MUST NOT have any Disclosures.¶

3.3. Example

The following is a non-normative example of the user data of an unsecured payload of an SD-JWT VC.¶

{
  "vct": "https://credentials.example.com/identity_credential",
  "given_name": "John",
  "family_name": "Doe",
  "email": "johndoe@example.com",
  "phone_number": "+1-202-555-0101",
  "address": {
    "street_address": "123 Main St",
    "locality": "Anytown",
    "region": "Anystate",
    "country": "US"
  },
  "birthdate": "1940-01-01",
  "is_over_18": true,
  "is_over_21": true,
  "is_over_65": true
}

The following is a non-normative example of how the unsecured payload of the SD-JWT VC above can be used in an SD-JWT where the resulting SD-JWT VC contains only claims about the Subject that are selectively disclosable:¶

{
  "_sd": [
    "09vKrJMOlyTWM0sjpu_pdOBVBQ2M1y3KhpH515nXkpY",
    "2rsjGbaC0ky8mT0pJrPioWTq0_daw1sX76poUlgCwbI",
    "EkO8dhW0dHEJbvUHlE_VCeuC9uRELOieLZhh7XbUTtA",
    "IlDzIKeiZdDwpqpK6ZfbyphFvz5FgnWa-sN6wqQXCiw",
    "JzYjH4svliH0R3PyEMfeZu6Jt69u5qehZo7F7EPYlSE",
    "PorFbpKuVu6xymJagvkFsFXAbRoc2JGlAUA2BA4o7cI",
    "TGf4oLbgwd5JQaHyKVQZU9UdGE0w5rtDsrZzfUaomLo",
    "jdrTE8YcbY4EifugihiAe_BPekxJQZICeiUQwY9QqxI",
    "jsu9yVulwQQlhFlM_3JlzMaSFzglhQG0DpfayQwLUK4"
  ],
  "iss": "https://example.com/issuer",
  "iat": 1683000000,
  "exp": 1883000000,
  "vct": "https://credentials.example.com/identity_credential",
  "_sd_alg": "sha-256",
  "cnf": {
    "jwk": {
      "kty": "EC",
      "crv": "P-256",
      "x": "TCAER19Zvu3OHF4j4W4vfSVoHIP1ILilDls7vCeGemc",
      "y": "ZxjiWWbZMQGHVWKVQ4hbSIirsVfuecCE6t4jT9F2HZQ"
    }
  }
}

Note that a cnf claim has been added to the SD-JWT payload to express the confirmation method of the Key Binding.¶

The following are the Disclosures belonging to the SD-JWT payload above:¶

Claim given_name:¶

SHA-256 Hash: jsu9yVulwQQlhFlM_3JlzMaSFzglhQG0DpfayQwLUK4¶
Disclosure:
WyIyR0xDNDJzS1F2ZUNmR2ZyeU5STjl3IiwgImdpdmVuX25hbWUiLCAiSm9o
biJd¶
Contents: ["2GLC42sKQveCfGfryNRN9w", "given_name", "John"]¶

Claim family_name:¶

SHA-256 Hash: TGf4oLbgwd5JQaHyKVQZU9UdGE0w5rtDsrZzfUaomLo¶
Disclosure:
WyJlbHVWNU9nM2dTTklJOEVZbnN4QV9BIiwgImZhbWlseV9uYW1lIiwgIkRv
ZSJd¶
Contents: ["eluV5Og3gSNII8EYnsxA_A", "family_name", "Doe"]¶

Claim email:¶

SHA-256 Hash: JzYjH4svliH0R3PyEMfeZu6Jt69u5qehZo7F7EPYlSE¶
Disclosure:
WyI2SWo3dE0tYTVpVlBHYm9TNXRtdlZBIiwgImVtYWlsIiwgImpvaG5kb2VA
ZXhhbXBsZS5jb20iXQ¶
Contents: ["6Ij7tM-a5iVPGboS5tmvVA", "email", "johndoe@example.com"]¶

Claim phone_number:¶

SHA-256 Hash: PorFbpKuVu6xymJagvkFsFXAbRoc2JGlAUA2BA4o7cI¶
Disclosure:
WyJlSThaV205UW5LUHBOUGVOZW5IZGhRIiwgInBob25lX251bWJlciIsICIr
MS0yMDItNTU1LTAxMDEiXQ¶
Contents: ["eI8ZWm9QnKPpNPeNenHdhQ", "phone_number",
"+1-202-555-0101"]¶

Claim address:¶

SHA-256 Hash: IlDzIKeiZdDwpqpK6ZfbyphFvz5FgnWa-sN6wqQXCiw¶
Disclosure:
WyJRZ19PNjR6cUF4ZTQxMmExMDhpcm9BIiwgImFkZHJlc3MiLCB7InN0cmVl
dF9hZGRyZXNzIjogIjEyMyBNYWluIFN0IiwgImxvY2FsaXR5IjogIkFueXRv
d24iLCAicmVnaW9uIjogIkFueXN0YXRlIiwgImNvdW50cnkiOiAiVVMifV0¶
Contents: ["Qg_O64zqAxe412a108iroA", "address", {"street_address":
"123 Main St", "locality": "Anytown", "region": "Anystate",
"country": "US"}]¶

Claim birthdate:¶

SHA-256 Hash: jdrTE8YcbY4EifugihiAe_BPekxJQZICeiUQwY9QqxI¶
Disclosure:
WyJBSngtMDk1VlBycFR0TjRRTU9xUk9BIiwgImJpcnRoZGF0ZSIsICIxOTQw
LTAxLTAxIl0¶
Contents: ["AJx-095VPrpTtN4QMOqROA", "birthdate", "1940-01-01"]¶

Claim is_over_18:¶

SHA-256 Hash: 09vKrJMOlyTWM0sjpu_pdOBVBQ2M1y3KhpH515nXkpY¶
Disclosure:
WyJQYzMzSk0yTGNoY1VfbEhnZ3ZfdWZRIiwgImlzX292ZXJfMTgiLCB0cnVl
XQ¶
Contents: ["Pc33JM2LchcU_lHggv_ufQ", "is_over_18", true]¶

Claim is_over_21:¶

SHA-256 Hash: 2rsjGbaC0ky8mT0pJrPioWTq0_daw1sX76poUlgCwbI¶
Disclosure:
WyJHMDJOU3JRZmpGWFE3SW8wOXN5YWpBIiwgImlzX292ZXJfMjEiLCB0cnVl
XQ¶
Contents: ["G02NSrQfjFXQ7Io09syajA", "is_over_21", true]¶

Claim is_over_65:¶

SHA-256 Hash: EkO8dhW0dHEJbvUHlE_VCeuC9uRELOieLZhh7XbUTtA¶
Disclosure:
WyJsa2x4RjVqTVlsR1RQVW92TU5JdkNBIiwgImlzX292ZXJfNjUiLCB0cnVl
XQ¶
Contents: ["lklxF5jMYlGTPUovMNIvCA", "is_over_65", true]¶

The SD-JWT and the Disclosures would then be serialized by the Issuer into the following format for issuance to the Holder:¶

eyJhbGciOiAiRVMyNTYiLCAidHlwIjogImRjK3NkLWp3dCIsICJraWQiOiAiZG9jLXNp
Z25lci0wNS0yNS0yMDIyIn0.eyJfc2QiOiBbIjA5dktySk1PbHlUV00wc2pwdV9wZE9C
VkJRMk0xeTNLaHBINTE1blhrcFkiLCAiMnJzakdiYUMwa3k4bVQwcEpyUGlvV1RxMF9k
YXcxc1g3NnBvVWxnQ3diSSIsICJFa084ZGhXMGRIRUpidlVIbEVfVkNldUM5dVJFTE9p
ZUxaaGg3WGJVVHRBIiwgIklsRHpJS2VpWmREd3BxcEs2WmZieXBoRnZ6NUZnbldhLXNO
NndxUVhDaXciLCAiSnpZakg0c3ZsaUgwUjNQeUVNZmVadTZKdDY5dTVxZWhabzdGN0VQ
WWxTRSIsICJQb3JGYnBLdVZ1Nnh5bUphZ3ZrRnNGWEFiUm9jMkpHbEFVQTJCQTRvN2NJ
IiwgIlRHZjRvTGJnd2Q1SlFhSHlLVlFaVTlVZEdFMHc1cnREc3JaemZVYW9tTG8iLCAi
amRyVEU4WWNiWTRFaWZ1Z2loaUFlX0JQZWt4SlFaSUNlaVVRd1k5UXF4SSIsICJqc3U5
eVZ1bHdRUWxoRmxNXzNKbHpNYVNGemdsaFFHMERwZmF5UXdMVUs0Il0sICJpc3MiOiAi
aHR0cHM6Ly9leGFtcGxlLmNvbS9pc3N1ZXIiLCAiaWF0IjogMTY4MzAwMDAwMCwgImV4
cCI6IDE4ODMwMDAwMDAsICJ2Y3QiOiAiaHR0cHM6Ly9jcmVkZW50aWFscy5leGFtcGxl
LmNvbS9pZGVudGl0eV9jcmVkZW50aWFsIiwgIl9zZF9hbGciOiAic2hhLTI1NiIsICJj
bmYiOiB7Imp3ayI6IHsia3R5IjogIkVDIiwgImNydiI6ICJQLTI1NiIsICJ4IjogIlRD
QUVSMTladnUzT0hGNGo0VzR2ZlNWb0hJUDFJTGlsRGxzN3ZDZUdlbWMiLCAieSI6ICJa
eGppV1diWk1RR0hWV0tWUTRoYlNJaXJzVmZ1ZWNDRTZ0NGpUOUYySFpRIn19fQ.2CyX0
v3AAFG9y-A_Z46uz9hHsNbr0yWTbDQaajLCrsxo-JxVh4a9dAMFVYZ8GFG2wgj2jKnA4
2wSgv7xVM64PA~WyIyR0xDNDJzS1F2ZUNmR2ZyeU5STjl3IiwgImdpdmVuX25hbWUiLC
AiSm9obiJd~WyJlbHVWNU9nM2dTTklJOEVZbnN4QV9BIiwgImZhbWlseV9uYW1lIiwgI
kRvZSJd~WyI2SWo3dE0tYTVpVlBHYm9TNXRtdlZBIiwgImVtYWlsIiwgImpvaG5kb2VA
ZXhhbXBsZS5jb20iXQ~WyJlSThaV205UW5LUHBOUGVOZW5IZGhRIiwgInBob25lX251b
WJlciIsICIrMS0yMDItNTU1LTAxMDEiXQ~WyJRZ19PNjR6cUF4ZTQxMmExMDhpcm9BIi
wgImFkZHJlc3MiLCB7InN0cmVldF9hZGRyZXNzIjogIjEyMyBNYWluIFN0IiwgImxvY2
FsaXR5IjogIkFueXRvd24iLCAicmVnaW9uIjogIkFueXN0YXRlIiwgImNvdW50cnkiOi
AiVVMifV0~WyJBSngtMDk1VlBycFR0TjRRTU9xUk9BIiwgImJpcnRoZGF0ZSIsICIxOT
QwLTAxLTAxIl0~WyJQYzMzSk0yTGNoY1VfbEhnZ3ZfdWZRIiwgImlzX292ZXJfMTgiLC
B0cnVlXQ~WyJHMDJOU3JRZmpGWFE3SW8wOXN5YWpBIiwgImlzX292ZXJfMjEiLCB0cnV
lXQ~WyJsa2x4RjVqTVlsR1RQVW92TU5JdkNBIiwgImlzX292ZXJfNjUiLCB0cnVlXQ~

Examples of what presentations of SD-JWT VCs might look like are provided in Section 4.2.¶

3.4. Verification and Processing

The recipient (Holder or Verifier) of an SD-JWT VC MUST process and verify an SD-JWT VC as described in Section 8 of [I-D.ietf-oauth-selective-disclosure-jwt].¶

If Key Binding is required (refer to the security considerations in Section 9.5 of [I-D.ietf-oauth-selective-disclosure-jwt]), the Verifier MUST verify the Key Binding JWT according to Section 7 of [I-D.ietf-oauth-selective-disclosure-jwt]. To verify the Key Binding JWT, the cnf claim of the SD-JWT MUST be used.¶

Furthermore, the recipient of the SD-JWT VC MUST validate the public verification key for the Issuer-signed JWT as defined in Section 3.5.¶

If a schema is provided in the Type Metadata, a recipient MUST validate the schema as defined in Section 6.5.¶

If there are no selectively disclosable claims, there is no need to process the _sd claim nor any Disclosures.¶

If status is present in the verified payload of the SD-JWT, the status SHOULD be checked. It depends on the Verifier policy to reject or accept a presentation of a SD-JWT VC based on the status of the Verifiable Credential.¶

Any claims used that are not understood MUST be ignored.¶

Additional validation rules MAY apply, but their use is out of the scope of this specification.¶

3.5. Issuer-signed JWT Verification Key Validation

A recipient of an SD-JWT VC MUST apply the following rules to validate that the public verification key for the Issuer-signed JWT corresponds to the iss value:¶

JWT VC Issuer Metadata: If a recipient supports JWT VC Issuer Metadata and if the iss value contains an HTTPS URI, the recipient MUST obtain the public key using JWT VC Issuer Metadata as defined in Section 5.¶
X.509 Certificates: If the recipient supports X.509 Certificates and the iss value contains an HTTPS URI, the recipient MUST¶
1. obtain the public key from the end-entity certificate of the certificates from the x5c header parameter of the Issuer-signed JWT and validate the X.509 certificate chain accordingly, and¶
2. ensure that the iss value matches a uniformResourceIdentifier SAN entry of the end-entity certificate or that the domain name in the iss value matches the dNSName SAN entry of the end-entity certificate.¶
DID Document Resolution: If a recipient supports DID Document Resolution and if the iss value contains a DID [W3C.DID], the recipient MUST retrieve the public key from the DID Document resolved from the DID in the iss value. In this case, if the kid JWT header parameter is present, the kid MUST be a relative or absolute DID URL of the DID in the iss value, identifying the public key.¶

Separate specifications or ecosystem regulations MAY define rules complementing the rules defined above, but such rules are out of scope of this specification. See Section 10.2 for security considerations.¶

If a recipient cannot validate that the public verification key corresponds to the iss value of the Issuer-signed JWT, the SD-JWT VC MUST be rejected.¶

4. Presenting Verifiable Credentials

This section defines encoding, validation and processing rules for presentations of SD-JWT VCs.¶

4.1. Key Binding JWT

If the presentation of the SD-JWT VC includes a Key Binding JWT, the Key Binding JWT MUST adhere to the rules defined in Section 4.3 of [I-D.ietf-oauth-selective-disclosure-jwt].¶

The Key Binding JWT MAY include additional claims which, when not understood, MUST be ignored by the Verifier.¶

4.2. Examples

The following is a non-normative example of a presentation of the SD-JWT shown in Section 3.3 including a Key Binding JWT. In this presentation, the Holder provides only the Disclosures for the address and is_over_65 claims. Other claims are not disclosed to the Verifier.¶

eyJhbGciOiAiRVMyNTYiLCAidHlwIjogImRjK3NkLWp3dCIsICJraWQiOiAiZG9jLXNp
Z25lci0wNS0yNS0yMDIyIn0.eyJfc2QiOiBbIjA5dktySk1PbHlUV00wc2pwdV9wZE9C
VkJRMk0xeTNLaHBINTE1blhrcFkiLCAiMnJzakdiYUMwa3k4bVQwcEpyUGlvV1RxMF9k
YXcxc1g3NnBvVWxnQ3diSSIsICJFa084ZGhXMGRIRUpidlVIbEVfVkNldUM5dVJFTE9p
ZUxaaGg3WGJVVHRBIiwgIklsRHpJS2VpWmREd3BxcEs2WmZieXBoRnZ6NUZnbldhLXNO
NndxUVhDaXciLCAiSnpZakg0c3ZsaUgwUjNQeUVNZmVadTZKdDY5dTVxZWhabzdGN0VQ
WWxTRSIsICJQb3JGYnBLdVZ1Nnh5bUphZ3ZrRnNGWEFiUm9jMkpHbEFVQTJCQTRvN2NJ
IiwgIlRHZjRvTGJnd2Q1SlFhSHlLVlFaVTlVZEdFMHc1cnREc3JaemZVYW9tTG8iLCAi
amRyVEU4WWNiWTRFaWZ1Z2loaUFlX0JQZWt4SlFaSUNlaVVRd1k5UXF4SSIsICJqc3U5
eVZ1bHdRUWxoRmxNXzNKbHpNYVNGemdsaFFHMERwZmF5UXdMVUs0Il0sICJpc3MiOiAi
aHR0cHM6Ly9leGFtcGxlLmNvbS9pc3N1ZXIiLCAiaWF0IjogMTY4MzAwMDAwMCwgImV4
cCI6IDE4ODMwMDAwMDAsICJ2Y3QiOiAiaHR0cHM6Ly9jcmVkZW50aWFscy5leGFtcGxl
LmNvbS9pZGVudGl0eV9jcmVkZW50aWFsIiwgIl9zZF9hbGciOiAic2hhLTI1NiIsICJj
bmYiOiB7Imp3ayI6IHsia3R5IjogIkVDIiwgImNydiI6ICJQLTI1NiIsICJ4IjogIlRD
QUVSMTladnUzT0hGNGo0VzR2ZlNWb0hJUDFJTGlsRGxzN3ZDZUdlbWMiLCAieSI6ICJa
eGppV1diWk1RR0hWV0tWUTRoYlNJaXJzVmZ1ZWNDRTZ0NGpUOUYySFpRIn19fQ.2CyX0
v3AAFG9y-A_Z46uz9hHsNbr0yWTbDQaajLCrsxo-JxVh4a9dAMFVYZ8GFG2wgj2jKnA4
2wSgv7xVM64PA~WyJsa2x4RjVqTVlsR1RQVW92TU5JdkNBIiwgImlzX292ZXJfNjUiLC
B0cnVlXQ~WyJRZ19PNjR6cUF4ZTQxMmExMDhpcm9BIiwgImFkZHJlc3MiLCB7InN0cmV
ldF9hZGRyZXNzIjogIjEyMyBNYWluIFN0IiwgImxvY2FsaXR5IjogIkFueXRvd24iLCA
icmVnaW9uIjogIkFueXN0YXRlIiwgImNvdW50cnkiOiAiVVMifV0~eyJhbGciOiAiRVM
yNTYiLCAidHlwIjogImtiK2p3dCJ9.eyJub25jZSI6ICIxMjM0NTY3ODkwIiwgImF1ZC
I6ICJodHRwczovL2V4YW1wbGUuY29tL3ZlcmlmaWVyIiwgImlhdCI6IDE3MzMyMzAxND
AsICJzZF9oYXNoIjogIkhWVjBCcG5FTHlHTnRVVFlCLU5nWHhmN2pvTjZBekprYVdEOU
VkNVo1VjgifQ.FJLPPlBB2wOWEYLLtwd7WYlaTpIz0ALlRuskPi0fSYFDEn25gGkXSSJ
sQxjhryxqN4aLbwMRRfcvDdk1A_eLHQ

After validation, the Verifier will have the following processed SD-JWT payload available for further handling:¶

{
  "iss": "https://example.com/issuer",
  "iat": 1683000000,
  "exp": 1883000000,
  "vct": "https://credentials.example.com/identity_credential",
  "cnf": {
    "jwk": {
      "kty": "EC",
      "crv": "P-256",
      "x": "TCAER19Zvu3OHF4j4W4vfSVoHIP1ILilDls7vCeGemc",
      "y": "ZxjiWWbZMQGHVWKVQ4hbSIirsVfuecCE6t4jT9F2HZQ"
    }
  },
  "is_over_65": true,
  "address": {
    "street_address": "123 Main St",
    "locality": "Anytown",
    "region": "Anystate",
    "country": "US"
  }
}

The following example shows a presentation of a (similar but different) SD-JWT without a Key Binding JWT:¶

eyJhbGciOiAiRVMyNTYiLCAidHlwIjogImRjK3NkLWp3dCJ9.eyJfc2QiOiBbIjA5dkt
ySk1PbHlUV00wc2pwdV9wZE9CVkJRMk0xeTNLaHBINTE1blhrcFkiLCAiMnJzakdiYUM
wa3k4bVQwcEpyUGlvV1RxMF9kYXcxc1g3NnBvVWxnQ3diSSIsICJFa084ZGhXMGRIRUp
idlVIbEVfVkNldUM5dVJFTE9pZUxaaGg3WGJVVHRBIiwgIklsRHpJS2VpWmREd3BxcEs
2WmZieXBoRnZ6NUZnbldhLXNONndxUVhDaXciLCAiSnpZakg0c3ZsaUgwUjNQeUVNZmV
adTZKdDY5dTVxZWhabzdGN0VQWWxTRSIsICJQb3JGYnBLdVZ1Nnh5bUphZ3ZrRnNGWEF
iUm9jMkpHbEFVQTJCQTRvN2NJIiwgIlRHZjRvTGJnd2Q1SlFhSHlLVlFaVTlVZEdFMHc
1cnREc3JaemZVYW9tTG8iLCAiamRyVEU4WWNiWTRFaWZ1Z2loaUFlX0JQZWt4SlFaSUN
laVVRd1k5UXF4SSIsICJqc3U5eVZ1bHdRUWxoRmxNXzNKbHpNYVNGemdsaFFHMERwZmF
5UXdMVUs0Il0sICJpc3MiOiAiaHR0cHM6Ly9leGFtcGxlLmNvbS9pc3N1ZXIiLCAiaWF
0IjogMTY4MzAwMDAwMCwgImV4cCI6IDE4ODMwMDAwMDAsICJ2Y3QiOiAiaHR0cHM6Ly9
jcmVkZW50aWFscy5leGFtcGxlLmNvbS9pZGVudGl0eV9jcmVkZW50aWFsIiwgIl9zZF9
hbGciOiAic2hhLTI1NiJ9.GetJdLXOuLJJrbBYR0zYlMq97qmmLoInT5-Vcq2gXQytHn
ERrQ-W_7Bf2TWme58A1dPgK98-nTDPz00oigMstA~WyJsa2x4RjVqTVlsR1RQVW92TU5
JdkNBIiwgImlzX292ZXJfNjUiLCB0cnVlXQ~WyJRZ19PNjR6cUF4ZTQxMmExMDhpcm9B
IiwgImFkZHJlc3MiLCB7InN0cmVldF9hZGRyZXNzIjogIjEyMyBNYWluIFN0IiwgImxv
Y2FsaXR5IjogIkFueXRvd24iLCAicmVnaW9uIjogIkFueXN0YXRlIiwgImNvdW50cnki
OiAiVVMifV0~

The Verifier will have the following processed SD-JWT payload after validation:¶

{
  "iss": "https://example.com/issuer",
  "iat": 1683000000,
  "exp": 1883000000,
  "vct": "https://credentials.example.com/identity_credential",
  "is_over_65": true,
  "address": {
    "street_address": "123 Main St",
    "locality": "Anytown",
    "region": "Anystate",
    "country": "US"
  }
}

5. JWT VC Issuer Metadata

This specification defines the JWT VC Issuer Metadata to retrieve the JWT VC Issuer Metadata configuration of the Issuer of the SD-JWT VC. The Issuer is identified by the iss claim in the JWT. Use of the JWT VC Issuer Metadata is OPTIONAL.¶

Issuers publishing JWT VC Issuer Metadata MUST make a JWT VC Issuer Metadata configuration available at the location formed by inserting the well-known string /.well-known/jwt-vc-issuer between the host component and the path component (if any) of the iss claim value in the JWT. The iss MUST be a case-sensitive URL using the HTTPS scheme that contains scheme, host and, optionally, port number and path components, but no query or fragment components.¶

5.1. JWT VC Issuer Metadata Request

A JWT VC Issuer Metadata configuration MUST be queried using an HTTP GET request at the path defined in Section 5.¶

The following is a non-normative example of an HTTP request for the JWT VC Issuer Metadata configuration when iss is set to https://example.com:¶

GET /.well-known/jwt-vc-issuer HTTP/1.1
Host: example.com

If the iss value contains a path component, any terminating / MUST be removed before inserting /.well-known/ and the well-known URI suffix between the host component and the path component.¶

The following is a non-normative example of a HTTP request for the JWT VC Issuer Metadata configuration when iss is set to https://example.com/tenant/1234:¶

GET /.well-known/jwt-vc-issuer/tenant/1234 HTTP/1.1
Host: example.com

5.2. JWT VC Issuer Metadata Response

A successful response MUST use the 200 OK HTTP and return the JWT VC Issuer Metadata configuration using the application/json content type.¶

An error response uses the applicable HTTP status code value.¶

This specification defines the following JWT VC Issuer Metadata configuration parameters:¶

issuer¶
- REQUIRED. The Issuer identifier, which MUST be identical to the iss value in the JWT.¶
jwks_uri¶
- OPTIONAL. URL string referencing the Issuer's JSON Web Key (JWK) Set [RFC7517] document which contains the Issuer's public keys. The value of this field MUST point to a valid JWK Set document.¶
jwks¶
- OPTIONAL. Issuer's JSON Web Key Set [RFC7517] document value, which contains the Issuer's public keys. The value of this field MUST be a JSON object containing a valid JWK Set.¶

JWT VC Issuer Metadata MUST include either jwks_uri or jwks in their JWT VC Issuer Metadata, but not both.¶

It is RECOMMENDED that the JWT contains a kid JWT header parameter that can be used to look up the public key in the JWK Set included by value or referenced in the JWT VC Issuer Metadata.¶

The following is a non-normative example of a JWT VC Issuer Metadata configuration including jwks:¶

{
   "issuer":"https://example.com",
   "jwks":{
      "keys":[
         {
            "kid":"doc-signer-05-25-2022",
            "e":"AQAB",
            "n":"nj3YJwsLUFl9BmpAbkOswCNVx17Eh9wMO-_AReZwBqfaWFcfG
   HrZXsIV2VMCNVNU8Tpb4obUaSXcRcQ-VMsfQPJm9IzgtRdAY8NN8Xb7PEcYyk
   lBjvTtuPbpzIaqyiUepzUXNDFuAOOkrIol3WmflPUUgMKULBN0EUd1fpOD70p
   RM0rlp_gg_WNUKoW1V-3keYUJoXH9NztEDm_D2MQXj9eGOJJ8yPgGL8PAZMLe
   2R7jb9TxOCPDED7tY_TU4nFPlxptw59A42mldEmViXsKQt60s1SLboazxFKve
   qXC_jpLUt22OC6GUG63p-REw-ZOr3r845z50wMuzifQrMI9bQ",
            "kty":"RSA"
         }
      ]
   }
}

The following is a non-normative example of a JWT VC Issuer Metadata configuration including jwks_uri:¶

{
   "issuer":"https://example.com",
   "jwks_uri":"https://jwt-vc-issuer.example.org/my_public_keys.jwks"
}

Additional JWT VC Issuer Metadata configuration parameters MAY also be used.¶

5.3. JWT VC Issuer Metadata Validation

The issuer value returned MUST be identical to the iss value of the JWT. If these values are not identical, the data contained in the response MUST NOT be used.¶

6. SD-JWT VC Type Metadata

An SD-JWT VC type, i.e., the vct value, is associated with Type Metadata defining, for example, information about the type or a schema defining (see Section 6.5.1) which claims MAY or MUST appear in the SD-JWT VC, and how credentials are displayed.¶

This section defines Type Metadata that can be associated with a type of an SD-JWT VC, as well as a method for retrieving the Type Metadata and processing rules. This Type Metadata is intended to be used, among other things, for the following purposes:¶

Developers of Issuers and Verifiers can use the Type Metadata to understand the semantics of the type and the associated rules. While in some cases, Issuers are the parties that define types, this is not always the case. For example, a type can be defined by a standardization body or a community.¶
Verifiers can use the Type Metadata to determine whether a credential is valid according to the rules of the type. For example, a Verifier can check whether a credential contains all required claims and whether the claims are selectively disclosable.¶
Wallets can use the metadata to display the credential in a way that is consistent with the intent of the provider of the Type Metadata.¶

Type Metadata can be retrieved as described in Section 6.3.¶

6.1. Type Metadata Example

All examples in this section are non-normative.¶

The following is an example of an SD-JWT VC payload, containing a vct claim with the value https://betelgeuse.example.com/education_credential:¶

{
  "vct": "https://betelgeuse.example.com/education_credential",
  "vct#integrity": "sha256-WRL5ca_xGgX3c1VLmXfh-9cLlJNXN-TsMk-PmKjZ5t0",
  ...
}

Type Metadata for the type https://betelgeuse.example.com/education_credential can be retrieved using various mechanisms as described in Section 6.3. For this example, the vct value is a URL as defined in Section 6.3.1 and the following Type Metadata Document is retrieved from it:¶

{
  "vct":"https://betelgeuse.example.com/education_credential",
  "name":"Betelgeuse Education Credential - Preliminary Version",
  "description":"This is our development version of the education credential. Don't panic.",
  "extends":"https://galaxy.example.com/galactic-education-credential-0.9",
  "extends#integrity":"sha256-9cLlJNXN-TsMk-PmKjZ5t0WRL5ca_xGgX3c1VLmXfh-WRL5",
  "schema_uri":"https://exampleuniversity.com/public/credential-schema-0.9",
  "schema_uri#integrity":"sha256-o984vn819a48ui1llkwPmKjZ5t0WRL5ca_xGgX3c1VLmXfh"
}

This example is shortened for presentation, a full Type Metadata example can be found in Appendix B.2.¶

Note: The hash of the Type Metadata document shown in the second example must be equal to the one in the vct#integrity claim in the SD-JWT VC payload, WRL5ca_xGgX3c1VLmXfh-9cLlJNXN-TsMk-PmKjZ5t0.¶

6.2. Type Metadata Format

The Type Metadata document MUST be a JSON object. The following properties are defined:¶

name¶
- OPTIONAL. A human-readable name for the type, intended for developers reading the JSON document.¶
description¶
- OPTIONAL. A human-readable description for the type, intended for developers reading the JSON document.¶
extends¶
- OPTIONAL. A URI of another type that this type extends, as described in Section 6.4.¶
display: An array of objects containing display information for the type, as described in Section 8. This property is OPTIONAL.¶
claims: An array of objects containing claim information for the type, as described in Section 9. This property is OPTIONAL.¶
schema¶
- OPTIONAL. An embedded JSON Schema document describing the structure of the Verifiable Credential as described in Section 6.5.1. schema MUST NOT be used if schema_uri is present.¶
schema_uri¶
- OPTIONAL. A URL pointing to a JSON Schema document describing the structure of the Verifiable Credential as described in Section 6.5.1. schema_uri MUST NOT be used if schema is present.¶

An example of a Type Metadata document is shown in Appendix B.2.¶

6.3. Retrieving Type Metadata

6.3.1. From a URL in the `vct` Claim

A URI in the vct claim can be used to express a type. If the type is a URL using the HTTPS scheme, Type Metadata MAY be retrieved from it.¶

The Type Metadata is retrieved using the HTTP GET method. The response MUST be a JSON object as defined in Section 6.2.¶

If the claim vct#integrity is present in the SD-JWT VC, its value vct#integrity MUST be an "integrity metadata" string as defined in Section Section 7.¶

6.3.2. From a Registry

A Consumer MAY use a registry to retrieve Type Metadata for a SD-JWT VC type, e.g., if the type is not an HTTPS URL or if the Consumer does not have access to the URL. The registry MUST be a trusted registry, i.e., the Consumer MUST trust the registry to provide correct Type Metadata for the type.¶

The registry MUST provide the Type Metadata in the same format as described in Section 6.2.¶

6.3.3. Using a Defined Retrieval Method

Ecosystems MAY define additional methods for retrieving Type Metadata. For example, a standardization body or a community MAY define a service which has to be used to retrieve Type Metadata based on a URN in the vct claim.¶

6.3.4. From a Local Cache

A Consumer MAY cache Type Metadata for a SD-JWT VC type. If a hash for integrity protection is present in the Type Metadata as defined in Section 7, the Consumer MAY assume that the Type Metadata is static and can be cached indefinitely. Otherwise, the Consumer MUST use the Cache-Control header of the HTTP response to determine how long the metadata can be cached.¶

6.3.5. From Type Metadata Glue Documents

Credentials MAY encode Type Metadata directly, providing it as "glue information" to the Consumer.¶

For JSON-serialized JWS-based credentials, such Type Metadata documents MAY be included in the unprotected header of the JWS. In this case, the key vctm MUST be used in the unprotected header and its value MUST be an array of base64url-encoded Type Metadata documents as defined in this specification. Multiple documents MAY be included for providing a whole chain of types to the Consumer (see Section 6.4).¶

A Consumer of a credential MAY use the documents in the vctm array instead of retrieving the respective Type Metadata elsewhere as follows:¶

When resolving a vct in a credential, the Consumer MUST ensure that the vct claim in the credential matches the one in the Type Metadata document, and it MUST verify the integrity of the Type Metadata document as defined in Section 7. The Consumer MUST NOT use the Type Metadata if no hash for integrity protection was provided in vct#integrity.¶
When resolving an extends property in a Type Metadata document, the Consumer MUST ensure that the value of the extends property in the Type Metadata document matches that of the vct in the Type Metadata document, and it MUST verify the integrity of the Type Metadata document as defined in Section 7. The Consumer MUST NOT use the Type Metadata if no hash for integrity protection was provided.¶

6.4. Extending Type Metadata

An SD-JWT VC type can extend another type. The extended type is identified by the URI in the extends property. Consumers MUST retrieve and process Type Metadata for the extended type before processing the Type Metadata for the extending type.¶

The extended type MAY itself extend another type. This can be used to create a chain or hierarchy of types. The security considerations described in Section 10.3 apply in order to avoid problems with circular dependencies.¶

6.5. Schema Type Metadata

6.5.1. Schema Definition

Schemas for Verifiable Credentials are contained in the schema or retrieved via the schema_uri Type Metadata parameters (as defined in Section 6.2). A schema MUST be represented by a JSON Schema document according to draft version 2020-12 [JSON.SCHEMA.2020-12] or above.¶

The schema of a Verifiable Credential MUST include all properties that are required by this specification and MUST NOT override their cardinality, JSON data type, or semantic intent.¶

The following is a non-normative example of a JSON Schema document for the example in Section 3.3 requiring the presence of the cnf claim in an SD-JWT VC presentation:¶

{
  "$schema":"https://json-schema.org/draft/2020-12/schema",
  "type":"object",
  "properties":{
    "vct":{
      "type":"string"
    },
    "iss":{
      "type":"string"
    },
    "nbf":{
      "type":"number"
    },
    "exp":{
      "type":"number"
    },
    "cnf":{
      "type":"object"
    },
    "status":{
      "type":"object"
    },
    "given_name":{
      "type":"string"
    },
    "family_name":{
      "type":"string"
    },
    "email":{
      "type":"string"
    },
    "phone_number":{
      "type":"string"
    },
    "address":{
      "type":"object",
      "properties":{
        "street_address":{
          "type":"string"
        },
        "locality":{
          "type":"string"
        },
        "region":{
          "type":"string"
        },
        "country":{
          "type":"string"
        }
      }
    },
    "birthdate":{
      "type":"string"
    },
    "is_over_18":{
      "type":"boolean"
    },
    "is_over_21":{
      "type":"boolean"
    },
    "is_over_65":{
      "type":"boolean"
    }
  },
  "required":[
    "iss",
    "vct",
    "cnf"
  ]
}

Note that iss and vct are always required by this specification.¶

6.5.2. Schema Validation

If a schema or schema_uri property is present, a Consumer MUST validate the JSON document resulting from the SD-JWT verification algorithm (as defined in Section 7 of [I-D.ietf-oauth-selective-disclosure-jwt]) against the JSON Schema document provided by the schema or schema_uri property.¶

If an extends property is present, the schema of the extended type MUST also be validated in the same manner. This process includes validating all subsequent extended types recursively until a type is encountered that does not contain an extends property in its Type Metadata. Each schema in this chain MUST be evaluated for a specific Verifiable Credential.¶

If the schema validation fails for any of the types in the chain, the Consumer MUST reject the Verifiable Credential.¶

The following is a non-normative example of a result JSON document after executing the SD-JWT verification algorithm that is validated against the JSON Schema document in the example provided in Section 6.5.1:¶

{
  "vct":"https://credentials.example.com/identity_credential",
  "iss":"https://example.com/issuer",
  "iat":1683000000,
  "exp":1883000000,
  "sub":"6c5c0a49-b589-431d-bae7-219122a9ec2c",
  "address":{
    "country":"DE"
  },
  "cnf":{
    "jwk":{
      "kty":"EC",
      "crv":"P-256",
      "x":"TCAER19Zvu3OHF4j4W4vfSVoHIP1ILilDls7vCeGemc",
      "y":"ZxjiWWbZMQGHVWKVQ4hbSIirsVfuecCE6t4jT9F2HZQ"
    }
  }
}

Note, the example above does not contain any _sd_alg, _sd, or ... claims.¶

7. Document Integrity

Both the vct claim in the SD-JWT VC and the various URIs in the Type Metadata MAY be accompanied by a respective claim suffixed with #integrity, in particular:¶

vct as defined in Section 3.2.2.2,¶
extends as defined in Section 6.4 ¶
uri as used in two places in Section 8.1 ¶
schema_uri as defined in Section 6.5 ¶

The value MUST be an "integrity metadata" string as defined in Section 3 of [W3C.SRI]. A Consumer of the respective documents MUST verify the integrity of the retrieved document as defined in Section 3.3.5 of [W3C.SRI].¶

8. Display Metadata

The display property is an array containing display information for the type. The array MUST contain an object for each language that is supported by the type. The consuming application MUST use the language tag it considers most appropriate for the user.¶

The objects in the array have the following properties:¶

lang: A language tag as defined in Section 2 of [RFC5646]. This property is REQUIRED.¶
name: A human-readable name for the type, intended for end users. This property is REQUIRED.¶
description: A human-readable description for the type, intended for end users. This property is OPTIONAL.¶
rendering: An object containing rendering information for the type, as described in Section 8.1. This property is OPTIONAL.¶

8.1. Rendering Metadata

The rendering property is an object containing rendering information for the type. The object MUST contain a property for each rendering method that is supported by the type. The property name MUST be a rendering method identifier and the property value MUST be an object containing the properties defined for the rendering method.¶

8.1.1. Rendering Method "simple"

The simple rendering method is intended for use in applications that do not support SVG rendering. The object contains the following properties:¶

logo: An object containing information about the logo to be displayed for the type, as described in Section 8.1.1.1. This property is OPTIONAL.¶
background_color: An RGB color value as defined in [W3C.CSS-COLOR] for the background of the credential. This property is OPTIONAL.¶
text_color: An RGB color value as defined in [W3C.CSS-COLOR] value for the text of the credential. This property is OPTIONAL.¶

8.1.1.1. Logo Metadata

The logo property is an object containing information about the logo to be displayed for the type. The object contains the following properties:¶

uri: A URI pointing to the logo image. This property is REQUIRED.¶
uri#integrity: An "integrity metadata" string as described in Section 7. This property is OPTIONAL.¶
alt_text: A string containing alternative text for the logo image. This property is OPTIONAL.¶

8.1.2. Rendering Method "svg_template"

The svg_template rendering method is intended for use in applications that support SVG rendering. The object MUST contain an array of objects containing information about the SVG templates available for the type. Each object contains the following properties:¶

uri: A URI pointing to the SVG template. This property is REQUIRED.¶
uri#integrity: An "integrity metadata" string as described in Section 7. This property is OPTIONAL.¶
properties: An object containing properties for the SVG template, as described in Section 8.1.2.1. This property is REQUIRED if more than one SVG template is present, otherwise it is OPTIONAL.¶

8.1.2.1. SVG Template Properties

The properties property is an object containing properties for the SVG template. Consuming applications MUST use these properties to find the best SVG template available for display to the user based on the display properties (landscape/portrait) and user preferences (color scheme, contrast). The object MUST contain at least one of the following properties:¶

orientation: The orientation for which the SVG template is optimized, with valid values being portrait and landscape. This property is OPTIONAL.¶
color_scheme: The color scheme for which the SVG template is optimized, with valid values being light and dark. This property is OPTIONAL.¶
contrast: The contrast for which the SVG template is optimized, with valid values being normal and high. This property is OPTIONAL.¶

8.1.2.2. SVG Rendering

Consuming application MUST preprocess the SVG template by replacing placeholders in the SVG template with properly escaped values of the claims in the credential. The placeholders MUST be defined in the SVG template using the syntax {{svg_id}}, where svg_id is an identifier defined in the claim metadata as described in Section 9.¶

Placeholders MUST only be used in the text content of the SVG template and MUST NOT be used in any other part of the SVG template, e.g., in attributes or comments.¶

A consuming application MUST ensure that all special characters in the claim values are properly escaped before inserting them into the SVG template. At least the following characters MUST be escaped:¶

& as &¶
< as <¶
> as >¶
" as "¶
' as '¶

If the svg_id is not present in the claim metadata, the consuming application SHOULD reject not render the SVG template. If the svg_id is present in the claim metadata, but the claim is not present in the credential, the placeholder MUST be replaced with an empty string or a string appropriate to indicate that the value is absent.¶

The following non-normative example shows a minimal SVG with one placeholder using the svg_id value address_street_address which is defined in the example in Appendix B.2:¶

<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100">
  <text x="10" y="20">Street address: {{address_street_address}}</text>
</svg>

When rendering the SVG template, the consuming application MUST ensure that malicious schema providers or issuers cannot inject executable code into the SVG template and thereby compromise the security of the consuming application. The consuming application MUST NOT execute any code in the SVG template. If code execution cannot be prevented reliably, the SVG display MUST be sandboxed.¶

9. Claim Metadata

The claims property is an array of objects containing information about particular claims for displaying and validating the claims.¶

The array MAY contain an object for each claim that is supported by the type. Each object contains the following properties:¶

path: An array indicating the claim or claims that are being addressed, as described below. This property is REQUIRED.¶
display: An object containing display information for the claim, as described in Section 9.2. This property is OPTIONAL.¶
sd: A string indicating whether the claim is selectively disclosable, as described in Section 9.3. This property is OPTIONAL.¶
svg_id: A string defining the ID of the claim for reference in the SVG template, as described in Section 8.1.2.2. The ID MUST be unique within the type metadata. It MUST consist of only alphanumeric characters and underscores and MUST NOT start with a digit. This property is OPTIONAL.¶

9.1. Claim Path

The path property MUST be a non-empty array of strings, null values, or non-negative integers. It is used to select a particular claim in the credential or a set of claims. A string indicates that the respective key is to be selected, a null value indicates that all elements of the currently selected array(s) are to be selected, and a non-negative integer indicates that the respective index in an array is to be selected.¶

The following shows a non-normative, reduced example of a credential:¶

{
  "vct": "https://betelgeuse.example.com/education_credential",
  "name": "Arthur Dent",
  "address": {
    "street_address": "42 Market Street",
    "city": "Milliways",
    "postal_code": "12345"
  },
  "degrees": [
    {
      "type": "Bachelor of Science",
      "university": "University of Betelgeuse"
    },
    {
      "type": "Master of Science",
      "university": "University of Betelgeuse"
    }
  ],
  "nationalities": ["British", "Betelgeusian"]
}

The following shows examples of path values and the respective selected claims in the credential above:¶

["name"]: The claim name with the value Arthur Dent is selected.¶
["address"]: The claim address with its sub-claims as the value is selected.¶
["address", "street_address"]: The claim street_address with the value 42 Market Street is selected.¶
["degrees", null, "type"]: All type claims in the degrees array are selected.¶

In detail, the array is processed from left to right as follows:¶

Select the root element of the credential, i.e., the top-level JSON object.¶
Process the path components from left to right:¶
1. If the path component is a string, select the element in the respective key in the currently selected element(s). If any of the currently selected element(s) is not an object, abort processing and return an error. If the key does not exist in any element currently selected, remove that element from the selection.¶
2. If the path component is null, select all elements of the currently selected array(s). If any of the currently selected element(s) is not an array, abort processing and return an error.¶
3. If the path component is a non-negative integer, select the element at the respective index in the currently selected array(s). If any of the currently selected element(s) is not an array, abort processing and return an error. If the index does not exist in a selected array, remove that array from the selection.¶
4. If the set of elements currently selected is empty, abort processing and return an error.¶

The result of the processing is the set of elements to which the respective claim metadata applies.¶

The path property MUST point to the respective claim as if all selectively disclosable claims were disclosed to a Verifier. That means that a consuming application which does not have access to all disclosures may not be able to identify the claim which is being addressed.¶

9.2. Claim Display Metadata

The display property is an array containing display information for the claim. The array MUST contain an object for each language that is supported by the type. The consuming application MUST use the language tag it considers most appropriate for the user.¶

The objects in the array have the following properties:¶

lang: A language tag as defined in Section 2 of [RFC5646]. This property is REQUIRED.¶
label: A human-readable label for the claim, intended for end users. This property is REQUIRED.¶
description: A human-readable description for the claim, intended for end users. This property is OPTIONAL.¶

9.3. Claim Selective Disclosure Metadata

The sd property is a string indicating whether the claim is selectively disclosable. The following values are defined:¶

always: The Issuer MUST make the claim selectively disclosable.¶
allowed: The Issuer MAY make the claim selectively disclosable.¶
never: The Issuer MUST NOT make the claim selectively disclosable.¶

If omitted, the default value is allowed.¶

10. Security Considerations

The Security Considerations in the SD-JWT specification [I-D.ietf-oauth-selective-disclosure-jwt] apply to this specification. Additionally, the following security considerations need to be taken into account when using SD-JWT VCs:¶

10.1. Server-Side Request Forgery

The JWT VC Issuer Metadata configuration is retrieved from the JWT VC Issuer by the Holder or Verifier. Similar to other metadata endpoints, the URL for the retrieval MUST be considered an untrusted value and could be a vector for Server-Side Request Forgery (SSRF) attacks.¶

Before making a request to the JWT VC Issuer Metadata endpoint, the Holder or Verifier MUST validate the URL to ensure that it is a valid HTTPS URL and that it does not point to internal resources. This requires, in particular, ensuring that the host part of the URL does not address an internal service (by IP address or an internal host name) and that, if an external DNS name is used, the resolved DNS name does not point to an internal IPv4 or IPv6 address.¶

When retrieving the metadata, the Holder or Verifier MUST ensure that the request is made in a time-bound and size-bound manner to prevent denial of service attacks. The Holder or Verifier MUST also ensure that the response is a valid JWT VC Issuer Metadata configuration document before processing it.¶

Additional considerations can be found in [OWASP_SSRF].¶

10.2. Ecosystem-specific Public Key Verification Methods

When defining ecosystem-specific rules for the verification of the public key, as outlined in Section 3.5, it is critical that those rules maintain the integrity of the relationship between the iss value within the Issuer-signed JWT and the public keys of the Issuer.¶

It MUST be ensured that for any given iss value, an attacker cannot influence the type of verification process used. Otherwise, an attacker could attempt to make the Verifier use a verification process not intended by the Issuer, allowing the attacker to potentially manipulate the verification result to their advantage.¶

10.3. Circular "extends" Dependencies of Types

A type MUST NOT extend another type that extends (either directly or with steps in-between) the first type. This would result in a circular dependency that could lead to infinite recursion when retrieving and processing the metadata.¶

Consumers MUST detect such circular dependencies and reject the credential.¶

10.4. Robust Retrieval of Type Metadata

In Section 6.3, various methods for distributing and retrieving metadata are described. Methods relying on a network connection may fail due to network issues or unavailability of a network connection due to offline usage of credentials, temporary server outages, or denial of service attacks on the metadata server.¶

Consumers SHOULD therefore implement a local cache as described in Section 6.3.4 if possible. Such a cache MAY be populated with metadata before the credential is used.¶

Issuers MAY provide glue documents as described in Section 6.3.5 to provide metadata directly with the credential and avoid the need for network requests.¶

These measures allow the Consumers to continue to function even if the metadata server is temporarily unavailable and avoid privacy issues as described in Section 12.1.¶

11. Privacy Considerations

The Privacy Considerations in the SD-JWT specification [I-D.ietf-oauth-selective-disclosure-jwt] apply to this specification. Additionally, the following privacy considerations need to be taken into account when using SD-JWT VCs.¶

11.1. Unlinkability

The Privacy Considerations in Section 10.1 of [I-D.ietf-oauth-selective-disclosure-jwt] apply especially to the cnf claim.¶

11.2. Verifiable Credential Type Identifier

Issuers and Holders have to be aware that while this specification supports selective disclosure of claims of a given SD-JWT VC, the vct claim is not selectively disclosable. In certain situations this could lead to unwanted leakage of additional context information.¶

In general, Issuers are advised to choose vct values following data minimization principles. For example, government Issuers issuing an SD-JWT VC to their citizens to enable them to prove their age, might consider using a vct value that does not allow third-parties to infer additional personal information about the Holder, e.g., country of residency or citizenship.¶

Additionally, Holders have to be informed that, besides the actual requested claims, the vct information is shared with the Verifier.¶

11.3. Issuer Phone-Home

A malicious Issuer can choose the Issuer identifier of the SD-JWT VC to enable tracking the usage behavior of the Holder if the Issuer identifier is Holder-specific and if the resolution of the key material to verify the Issuer-signed JWT requires the Verifier to phone home to the Issuer.¶

For example, a malicious Issuer could generate a unique value for the Issuer identifier per Holder, e.g., https://example.com/issuer/holder-1234 and host the JWT VC Issuer Metadata. The Verifier would create a HTTPS GET request to the Holder-specific well-known URI when the SD-JWT VC is verified. This would allow the malicious Issuer to keep track where and how often the SD-JWT VC was used.¶

Verifiers are advised to establish trust in an SD-JWT VC by pinning specific Issuer identifiers and should monitor suspicious behaviour such as frequently rotating Issuer identifiers. If such behaviour was detected, Verifiers are advised to reject SD-JWT VCs issued by such Issuers.¶

Holders are advised to reject SD-JWT VCs if they contain easily correlatable information in the Issuer identifier.¶

12. Relationships to Other Documents

This specification defines validation and processing rules for verifiable credentials using JSON payloads and secured by SD-JWT [I-D.ietf-oauth-selective-disclosure-jwt]. Other specifications exist that define their own verifiable credential formats; for example, W3C Verifiable Credential Data Model (VCDM) 2.0 [W3C.VCDM] defines a data model for verifiable credentials encoded as JSON-LD, and ISO/IEC 18013-5:2021 [ISO.18013-5] defines a representation of verifiable credentials in the mobile document (mdoc) format encoded as CBOR and secured using COSE.¶

12.1. Privacy-Preserving Retrieval of Type Metadata

In Section 6.3, various methods for distributing and retrieving Type Metadata are described. For methods which rely on a network connection to a URL (e.g., provided by an Issuer), third parties (like the Issuer) may be able to track the usage of a credential by observing requests to the Type Metadata URL.¶

Consumers SHOULD prefer methods for retrieving Type Metadata that do not leak information about the usage of a credential to third parties. The recommendations in Section 10.4 apply.¶

Appendix A. IANA Considerations

A.1. JSON Web Token Claims Registration

Claim Name: "vct"¶
Claim Description: Verifiable credential type identifier¶
Change Controller: IETF¶
Specification Document(s): [[ Section 3.2.2.1.1 of this specification ]]¶
Claim Name: "vct#integrity"¶
Claim Description: SD-JWT VC vct claim "integrity metadata" value¶
Change Controller: IETF¶
Specification Document(s): [[ Section 7 of this specification ]]¶

A.2. Media Types Registry

A.2.1. application/dc+sd-jwt

The Internet media type for an SD-JWT VC is application/dc+sd-jwt.¶

Type name: application¶
Subtype name: dc+sd-jwt¶
Required parameters: n/a¶
Optional parameters: n/a¶
Encoding considerations: 8-bit code points; SD-JWT VC values are encoded as a series of base64url-encoded values (some of which may be the empty string) separated by period ('.') and tilde ('~') characters.¶
Security considerations: See Security Considerations in Section 10.¶
Interoperability considerations: n/a¶
Published specification: [[ this specification ]]¶
Applications that use this media type: Applications that issue, present, and verify SD-JWT-based verifiable credentials.¶
Additional information:¶
- Magic number(s): n/a¶
- File extension(s): n/a¶
- Macintosh file type code(s): n/a¶
Person & email address to contact for further information: Oliver Terbu oliver.terbu@mattr.global ¶
Intended usage: COMMON¶
Restrictions on usage: none¶
Author: Oliver Terbu oliver.terbu@mattr.global ¶
Change controller: IETF¶

A.3. Well-Known URI Registry

This specification requests the well-known URI defined in Section 5 in the IANA "Well-Known URIs" registry [IANA.well-known] established by [RFC5785].¶

A.3.1. Registry Contents

URI suffix: jwt-vc-issuer¶
Change controller: IETF¶
Specification document: [[ Section 5 of this specification ]]¶
Related information: (none)¶
Status: permanent¶

Appendix B. Examples

Important: The following examples are not normative and provided for illustrative purposes only. In particular, neither the structure of the claims nor the selection of selectively disclosable claims are normative.¶

Line breaks have been added for readability.¶

B.1. Example 1: Person Identification Data (PID) Credential

This example shows how the artifacts defined in this specification could be used to represent the concept of a Person Identification Data (PID) [EUDIW.ARF] using the data of a German citizen.¶

Key Binding is applied using the Holder's public key passed in a cnf claim in the SD-JWT.¶

The following data about the citizen comprises the input JWT Claims Set used by the Issuer:¶

{
  "vct": "https://bmi.bund.example/credential/pid/1.0",
  "given_name": "Erika",
  "family_name": "Mustermann",
  "birthdate": "1963-08-12",
  "source_document_type": "id_card",
  "address": {
    "street_address": "Heidestraße 17",
    "locality": "Köln",
    "postal_code": "51147",
    "country": "DE"
  },
  "nationalities": [
    "DE"
  ],
  "gender": "female",
  "birth_family_name": "Gabler",
  "place_of_birth": {
    "locality": "Berlin",
    "country": "DE"
  },
  "also_known_as": "Schwester Agnes",
  "age_equal_or_over": {
    "12": true,
    "14": true,
    "16": true,
    "18": true,
    "21": true,
    "65": false
  }
}

The following is the issued SD-JWT:¶

eyJhbGciOiAiRVMyNTYiLCAidHlwIjogImRjK3NkLWp3dCJ9.eyJfc2QiOiBbIjBIWm1
uU0lQejMzN2tTV2U3QzM0bC0tODhnekppLWVCSjJWel9ISndBVGciLCAiOVpicGxDN1R
kRVc3cWFsNkJCWmxNdHFKZG1lRU9pWGV2ZEpsb1hWSmRSUSIsICJJMDBmY0ZVb0RYQ3V
jcDV5eTJ1anFQc3NEVkdhV05pVWxpTnpfYXdEMGdjIiwgIklFQllTSkdOaFhJbHJRbzU
4eWtYbTJaeDN5bGw5WmxUdFRvUG8xN1FRaVkiLCAiTGFpNklVNmQ3R1FhZ1hSN0F2R1R
yblhnU2xkM3o4RUlnX2Z2M2ZPWjFXZyIsICJodkRYaHdtR2NKUXNCQ0EyT3RqdUxBY3d
BTXBEc2FVMG5rb3ZjS09xV05FIiwgImlrdXVyOFE0azhxM1ZjeUE3ZEMtbU5qWkJrUmV
EVFUtQ0c0bmlURTdPVFUiLCAicXZ6TkxqMnZoOW80U0VYT2ZNaVlEdXZUeWtkc1dDTmc
wd1RkbHIwQUVJTSIsICJ3elcxNWJoQ2t2a3N4VnZ1SjhSRjN4aThpNjRsbjFqb183NkJ
DMm9hMXVnIiwgInpPZUJYaHh2SVM0WnptUWNMbHhLdUVBT0dHQnlqT3FhMXoySW9WeF9
ZRFEiXSwgImlzcyI6ICJodHRwczovL2V4YW1wbGUuY29tL2lzc3VlciIsICJpYXQiOiA
xNjgzMDAwMDAwLCAiZXhwIjogMTg4MzAwMDAwMCwgInZjdCI6ICJodHRwczovL2JtaS5
idW5kLmV4YW1wbGUvY3JlZGVudGlhbC9waWQvMS4wIiwgImFnZV9lcXVhbF9vcl9vdmV
yIjogeyJfc2QiOiBbIkZjOElfMDdMT2NnUHdyREpLUXlJR085N3dWc09wbE1Makh2UkM
0UjQtV2ciLCAiWEx0TGphZFVXYzl6Tl85aE1KUm9xeTQ2VXNDS2IxSXNoWnV1cVVGS1N
DQSIsICJhb0NDenNDN3A0cWhaSUFoX2lkUkNTQ2E2NDF1eWNuYzh6UGZOV3o4bngwIiw
gImYxLVAwQTJkS1dhdnYxdUZuTVgyQTctRVh4dmhveHY1YUhodUVJTi1XNjQiLCAiazV
oeTJyMDE4dnJzSmpvLVZqZDZnNnl0N0Fhb25Lb25uaXVKOXplbDNqbyIsICJxcDdaX0t
5MVlpcDBzWWdETzN6VnVnMk1GdVBOakh4a3NCRG5KWjRhSS1jIl19LCAiX3NkX2FsZyI
6ICJzaGEtMjU2IiwgImNuZiI6IHsiandrIjogeyJrdHkiOiAiRUMiLCAiY3J2IjogIlA
tMjU2IiwgIngiOiAiVENBRVIxOVp2dTNPSEY0ajRXNHZmU1ZvSElQMUlMaWxEbHM3dkN
lR2VtYyIsICJ5IjogIlp4amlXV2JaTVFHSFZXS1ZRNGhiU0lpcnNWZnVlY0NFNnQ0alQ
5RjJIWlEifX19.GpFPbIEEgUGopARZQ0IyasBufd1KzTqq7qTjfla0PDmAlGD9W56Mfh
VGysuuq0FPv-hnLD7EU43r5ybMxWTQhw~WyIyR0xDNDJzS1F2ZUNmR2ZyeU5STjl3Iiw
gImdpdmVuX25hbWUiLCAiRXJpa2EiXQ~WyJlbHVWNU9nM2dTTklJOEVZbnN4QV9BIiwg
ImZhbWlseV9uYW1lIiwgIk11c3Rlcm1hbm4iXQ~WyI2SWo3dE0tYTVpVlBHYm9TNXRtd
lZBIiwgImJpcnRoZGF0ZSIsICIxOTYzLTA4LTEyIl0~WyJlSThaV205UW5LUHBOUGVOZ
W5IZGhRIiwgInNvdXJjZV9kb2N1bWVudF90eXBlIiwgImlkX2NhcmQiXQ~WyJRZ19PNj
R6cUF4ZTQxMmExMDhpcm9BIiwgInN0cmVldF9hZGRyZXNzIiwgIkhlaWRlc3RyYVx1MD
BkZmUgMTciXQ~WyJBSngtMDk1VlBycFR0TjRRTU9xUk9BIiwgImxvY2FsaXR5IiwgIkt
cdTAwZjZsbiJd~WyJQYzMzSk0yTGNoY1VfbEhnZ3ZfdWZRIiwgInBvc3RhbF9jb2RlIi
wgIjUxMTQ3Il0~WyJHMDJOU3JRZmpGWFE3SW8wOXN5YWpBIiwgImNvdW50cnkiLCAiRE
UiXQ~WyJsa2x4RjVqTVlsR1RQVW92TU5JdkNBIiwgImFkZHJlc3MiLCB7Il9zZCI6IFs
iWEZjN3pYUG03enpWZE15d20yRXVCZmxrYTVISHF2ZjhVcF9zek5HcXZpZyIsICJiZDF
FVnpnTm9wVWs0RVczX2VRMm4zX05VNGl1WE9IdjlYYkdITjNnMVRFIiwgImZfRlFZZ3Z
RV3Z5VnFObklYc0FSbE55ZTdZR3A4RTc3Z1JBamFxLXd2bnciLCAidjRra2JfcFAxamx
2VWJTanR5YzVicWNXeUEtaThYTHZoVllZN1pUMHRiMCJdfV0~WyJuUHVvUW5rUkZxM0J
JZUFtN0FuWEZBIiwgIm5hdGlvbmFsaXRpZXMiLCBbIkRFIl1d~WyI1YlBzMUlxdVpOYT
Boa2FGenp6Wk53IiwgImdlbmRlciIsICJmZW1hbGUiXQ~WyI1YTJXMF9OcmxFWnpmcW1
rXzdQcS13IiwgImJpcnRoX2ZhbWlseV9uYW1lIiwgIkdhYmxlciJd~WyJ5MXNWVTV3ZG
ZKYWhWZGd3UGdTN1JRIiwgImxvY2FsaXR5IiwgIkJlcmxpbiJd~WyJIYlE0WDhzclZXM
1FEeG5JSmRxeU9BIiwgInBsYWNlX29mX2JpcnRoIiwgeyJfc2QiOiBbIldwaEhvSUR5b
1diQXBEQzR6YnV3UjQweGwweExoRENfY3Y0dHNTNzFyRUEiXSwgImNvdW50cnkiOiAiR
EUifV0~WyJDOUdTb3VqdmlKcXVFZ1lmb2pDYjFBIiwgImFsc29fa25vd25fYXMiLCAiU
2Nod2VzdGVyIEFnbmVzIl0~WyJreDVrRjE3Vi14MEptd1V4OXZndnR3IiwgIjEyIiwgd
HJ1ZV0~WyJIM28xdXN3UDc2MEZpMnllR2RWQ0VRIiwgIjE0IiwgdHJ1ZV0~WyJPQktsV
FZsdkxnLUFkd3FZR2JQOFpBIiwgIjE2IiwgdHJ1ZV0~WyJNMEpiNTd0NDF1YnJrU3V5c
kRUM3hBIiwgIjE4IiwgdHJ1ZV0~WyJEc210S05ncFY0ZEFIcGpyY2Fvc0F3IiwgIjIxI
iwgdHJ1ZV0~WyJlSzVvNXBIZmd1cFBwbHRqMXFoQUp3IiwgIjY1IiwgZmFsc2Vd~

This is the payload of that SD-JWT:¶

{
  "_sd": [
    "0HZmnSIPz337kSWe7C34l--88gzJi-eBJ2Vz_HJwATg",
    "9ZbplC7TdEW7qal6BBZlMtqJdmeEOiXevdJloXVJdRQ",
    "I00fcFUoDXCucp5yy2ujqPssDVGaWNiUliNz_awD0gc",
    "IEBYSJGNhXIlrQo58ykXm2Zx3yll9ZlTtToPo17QQiY",
    "Lai6IU6d7GQagXR7AvGTrnXgSld3z8EIg_fv3fOZ1Wg",
    "hvDXhwmGcJQsBCA2OtjuLAcwAMpDsaU0nkovcKOqWNE",
    "ikuur8Q4k8q3VcyA7dC-mNjZBkReDTU-CG4niTE7OTU",
    "qvzNLj2vh9o4SEXOfMiYDuvTykdsWCNg0wTdlr0AEIM",
    "wzW15bhCkvksxVvuJ8RF3xi8i64ln1jo_76BC2oa1ug",
    "zOeBXhxvIS4ZzmQcLlxKuEAOGGByjOqa1z2IoVx_YDQ"
  ],
  "iss": "https://example.com/issuer",
  "iat": 1683000000,
  "exp": 1883000000,
  "vct": "https://bmi.bund.example/credential/pid/1.0",
  "age_equal_or_over": {
    "_sd": [
      "Fc8I_07LOcgPwrDJKQyIGO97wVsOplMLjHvRC4R4-Wg",
      "XLtLjadUWc9zN_9hMJRoqy46UsCKb1IshZuuqUFKSCA",
      "aoCCzsC7p4qhZIAh_idRCSCa641uycnc8zPfNWz8nx0",
      "f1-P0A2dKWavv1uFnMX2A7-EXxvhoxv5aHhuEIN-W64",
      "k5hy2r018vrsJjo-Vjd6g6yt7AaonKonniuJ9zel3jo",
      "qp7Z_Ky1Yip0sYgDO3zVug2MFuPNjHxksBDnJZ4aI-c"
    ]
  },
  "_sd_alg": "sha-256",
  "cnf": {
    "jwk": {
      "kty": "EC",
      "crv": "P-256",
      "x": "TCAER19Zvu3OHF4j4W4vfSVoHIP1ILilDls7vCeGemc",
      "y": "ZxjiWWbZMQGHVWKVQ4hbSIirsVfuecCE6t4jT9F2HZQ"
    }
  }
}

The digests in the SD-JWT payload reference the following Disclosures:¶

Claim given_name:¶

SHA-256 Hash: 0HZmnSIPz337kSWe7C34l--88gzJi-eBJ2Vz_HJwATg¶
Disclosure:
WyIyR0xDNDJzS1F2ZUNmR2ZyeU5STjl3IiwgImdpdmVuX25hbWUiLCAiRXJp
a2EiXQ¶
Contents: ["2GLC42sKQveCfGfryNRN9w", "given_name", "Erika"]¶

Claim family_name:¶

SHA-256 Hash: I00fcFUoDXCucp5yy2ujqPssDVGaWNiUliNz_awD0gc¶
Disclosure:
WyJlbHVWNU9nM2dTTklJOEVZbnN4QV9BIiwgImZhbWlseV9uYW1lIiwgIk11
c3Rlcm1hbm4iXQ¶
Contents: ["eluV5Og3gSNII8EYnsxA_A", "family_name", "Mustermann"]¶

Claim birthdate:¶

SHA-256 Hash: Lai6IU6d7GQagXR7AvGTrnXgSld3z8EIg_fv3fOZ1Wg¶
Disclosure:
WyI2SWo3dE0tYTVpVlBHYm9TNXRtdlZBIiwgImJpcnRoZGF0ZSIsICIxOTYz
LTA4LTEyIl0¶
Contents: ["6Ij7tM-a5iVPGboS5tmvVA", "birthdate", "1963-08-12"]¶

Claim source_document_type:¶

SHA-256 Hash: qvzNLj2vh9o4SEXOfMiYDuvTykdsWCNg0wTdlr0AEIM¶
Disclosure:
WyJlSThaV205UW5LUHBOUGVOZW5IZGhRIiwgInNvdXJjZV9kb2N1bWVudF90
eXBlIiwgImlkX2NhcmQiXQ¶
Contents: ["eI8ZWm9QnKPpNPeNenHdhQ", "source_document_type",
"id_card"]¶

Claim street_address:¶

SHA-256 Hash: bd1EVzgNopUk4EW3_eQ2n3_NU4iuXOHv9XbGHN3g1TE¶
Disclosure:
WyJRZ19PNjR6cUF4ZTQxMmExMDhpcm9BIiwgInN0cmVldF9hZGRyZXNzIiwg
IkhlaWRlc3RyYVx1MDBkZmUgMTciXQ¶
Contents: ["Qg_O64zqAxe412a108iroA", "street_address",
"Heidestra\u00dfe 17"]¶

Claim locality:¶

SHA-256 Hash: f_FQYgvQWvyVqNnIXsARlNye7YGp8E77gRAjaq-wvnw¶
Disclosure:
WyJBSngtMDk1VlBycFR0TjRRTU9xUk9BIiwgImxvY2FsaXR5IiwgIktcdTAw
ZjZsbiJd¶
Contents: ["AJx-095VPrpTtN4QMOqROA", "locality", "K\u00f6ln"]¶

Claim postal_code:¶

SHA-256 Hash: XFc7zXPm7zzVdMywm2EuBflka5HHqvf8Up_szNGqvig¶
Disclosure:
WyJQYzMzSk0yTGNoY1VfbEhnZ3ZfdWZRIiwgInBvc3RhbF9jb2RlIiwgIjUx
MTQ3Il0¶
Contents: ["Pc33JM2LchcU_lHggv_ufQ", "postal_code", "51147"]¶

Claim country:¶

SHA-256 Hash: v4kkb_pP1jlvUbSjtyc5bqcWyA-i8XLvhVYY7ZT0tb0¶
Disclosure:
WyJHMDJOU3JRZmpGWFE3SW8wOXN5YWpBIiwgImNvdW50cnkiLCAiREUiXQ¶
Contents: ["G02NSrQfjFXQ7Io09syajA", "country", "DE"]¶

Claim address:¶

SHA-256 Hash: zOeBXhxvIS4ZzmQcLlxKuEAOGGByjOqa1z2IoVx_YDQ¶
Disclosure:
WyJsa2x4RjVqTVlsR1RQVW92TU5JdkNBIiwgImFkZHJlc3MiLCB7Il9zZCI6
IFsiWEZjN3pYUG03enpWZE15d20yRXVCZmxrYTVISHF2ZjhVcF9zek5HcXZp
ZyIsICJiZDFFVnpnTm9wVWs0RVczX2VRMm4zX05VNGl1WE9IdjlYYkdITjNn
MVRFIiwgImZfRlFZZ3ZRV3Z5VnFObklYc0FSbE55ZTdZR3A4RTc3Z1JBamFx
LXd2bnciLCAidjRra2JfcFAxamx2VWJTanR5YzVicWNXeUEtaThYTHZoVllZ
N1pUMHRiMCJdfV0¶
Contents: ["lklxF5jMYlGTPUovMNIvCA", "address", {"_sd":
["XFc7zXPm7zzVdMywm2EuBflka5HHqvf8Up_szNGqvig",
"bd1EVzgNopUk4EW3_eQ2n3_NU4iuXOHv9XbGHN3g1TE",
"f_FQYgvQWvyVqNnIXsARlNye7YGp8E77gRAjaq-wvnw",
"v4kkb_pP1jlvUbSjtyc5bqcWyA-i8XLvhVYY7ZT0tb0"]}]¶

Claim nationalities:¶

SHA-256 Hash: hvDXhwmGcJQsBCA2OtjuLAcwAMpDsaU0nkovcKOqWNE¶
Disclosure:
WyJuUHVvUW5rUkZxM0JJZUFtN0FuWEZBIiwgIm5hdGlvbmFsaXRpZXMiLCBb
IkRFIl1d¶
Contents: ["nPuoQnkRFq3BIeAm7AnXFA", "nationalities", ["DE"]]¶

Claim gender:¶

SHA-256 Hash: IEBYSJGNhXIlrQo58ykXm2Zx3yll9ZlTtToPo17QQiY¶
Disclosure:
WyI1YlBzMUlxdVpOYTBoa2FGenp6Wk53IiwgImdlbmRlciIsICJmZW1hbGUi
XQ¶
Contents: ["5bPs1IquZNa0hkaFzzzZNw", "gender", "female"]¶

Claim birth_family_name:¶

SHA-256 Hash: ikuur8Q4k8q3VcyA7dC-mNjZBkReDTU-CG4niTE7OTU¶
Disclosure:
WyI1YTJXMF9OcmxFWnpmcW1rXzdQcS13IiwgImJpcnRoX2ZhbWlseV9uYW1l
IiwgIkdhYmxlciJd¶
Contents: ["5a2W0_NrlEZzfqmk_7Pq-w", "birth_family_name", "Gabler"]¶

Claim locality:¶

SHA-256 Hash: WphHoIDyoWbApDC4zbuwR40xl0xLhDC_cv4tsS71rEA¶
Disclosure:
WyJ5MXNWVTV3ZGZKYWhWZGd3UGdTN1JRIiwgImxvY2FsaXR5IiwgIkJlcmxp
biJd¶
Contents: ["y1sVU5wdfJahVdgwPgS7RQ", "locality", "Berlin"]¶

Claim place_of_birth:¶

SHA-256 Hash: wzW15bhCkvksxVvuJ8RF3xi8i64ln1jo_76BC2oa1ug¶
Disclosure:
WyJIYlE0WDhzclZXM1FEeG5JSmRxeU9BIiwgInBsYWNlX29mX2JpcnRoIiwg
eyJfc2QiOiBbIldwaEhvSUR5b1diQXBEQzR6YnV3UjQweGwweExoRENfY3Y0
dHNTNzFyRUEiXSwgImNvdW50cnkiOiAiREUifV0¶
Contents: ["HbQ4X8srVW3QDxnIJdqyOA", "place_of_birth", {"_sd":
["WphHoIDyoWbApDC4zbuwR40xl0xLhDC_cv4tsS71rEA"], "country":
"DE"}]¶

Claim also_known_as:¶

SHA-256 Hash: 9ZbplC7TdEW7qal6BBZlMtqJdmeEOiXevdJloXVJdRQ¶
Disclosure:
WyJDOUdTb3VqdmlKcXVFZ1lmb2pDYjFBIiwgImFsc29fa25vd25fYXMiLCAi
U2Nod2VzdGVyIEFnbmVzIl0¶
Contents: ["C9GSoujviJquEgYfojCb1A", "also_known_as", "Schwester
Agnes"]¶

Claim 12:¶

SHA-256 Hash: Fc8I_07LOcgPwrDJKQyIGO97wVsOplMLjHvRC4R4-Wg¶
Disclosure:
WyJreDVrRjE3Vi14MEptd1V4OXZndnR3IiwgIjEyIiwgdHJ1ZV0¶
Contents: ["kx5kF17V-x0JmwUx9vgvtw", "12", true]¶

Claim 14:¶

SHA-256 Hash: f1-P0A2dKWavv1uFnMX2A7-EXxvhoxv5aHhuEIN-W64¶
Disclosure:
WyJIM28xdXN3UDc2MEZpMnllR2RWQ0VRIiwgIjE0IiwgdHJ1ZV0¶
Contents: ["H3o1uswP760Fi2yeGdVCEQ", "14", true]¶

Claim 16:¶

SHA-256 Hash: k5hy2r018vrsJjo-Vjd6g6yt7AaonKonniuJ9zel3jo¶
Disclosure:
WyJPQktsVFZsdkxnLUFkd3FZR2JQOFpBIiwgIjE2IiwgdHJ1ZV0¶
Contents: ["OBKlTVlvLg-AdwqYGbP8ZA", "16", true]¶

Claim 18:¶

SHA-256 Hash: qp7Z_Ky1Yip0sYgDO3zVug2MFuPNjHxksBDnJZ4aI-c¶
Disclosure:
WyJNMEpiNTd0NDF1YnJrU3V5ckRUM3hBIiwgIjE4IiwgdHJ1ZV0¶
Contents: ["M0Jb57t41ubrkSuyrDT3xA", "18", true]¶

Claim 21:¶

SHA-256 Hash: aoCCzsC7p4qhZIAh_idRCSCa641uycnc8zPfNWz8nx0¶
Disclosure:
WyJEc210S05ncFY0ZEFIcGpyY2Fvc0F3IiwgIjIxIiwgdHJ1ZV0¶
Contents: ["DsmtKNgpV4dAHpjrcaosAw", "21", true]¶

Claim 65:¶

SHA-256 Hash: XLtLjadUWc9zN_9hMJRoqy46UsCKb1IshZuuqUFKSCA¶
Disclosure:
WyJlSzVvNXBIZmd1cFBwbHRqMXFoQUp3IiwgIjY1IiwgZmFsc2Vd¶
Contents: ["eK5o5pHfgupPpltj1qhAJw", "65", false]¶

This shows a presentation of the SD-JWT with a Key Binding JWT that discloses only nationality and the fact that the person is over 18 years old:¶

eyJhbGciOiAiRVMyNTYiLCAidHlwIjogImRjK3NkLWp3dCJ9.eyJfc2QiOiBbIjBIWm1
uU0lQejMzN2tTV2U3QzM0bC0tODhnekppLWVCSjJWel9ISndBVGciLCAiOVpicGxDN1R
kRVc3cWFsNkJCWmxNdHFKZG1lRU9pWGV2ZEpsb1hWSmRSUSIsICJJMDBmY0ZVb0RYQ3V
jcDV5eTJ1anFQc3NEVkdhV05pVWxpTnpfYXdEMGdjIiwgIklFQllTSkdOaFhJbHJRbzU
4eWtYbTJaeDN5bGw5WmxUdFRvUG8xN1FRaVkiLCAiTGFpNklVNmQ3R1FhZ1hSN0F2R1R
yblhnU2xkM3o4RUlnX2Z2M2ZPWjFXZyIsICJodkRYaHdtR2NKUXNCQ0EyT3RqdUxBY3d
BTXBEc2FVMG5rb3ZjS09xV05FIiwgImlrdXVyOFE0azhxM1ZjeUE3ZEMtbU5qWkJrUmV
EVFUtQ0c0bmlURTdPVFUiLCAicXZ6TkxqMnZoOW80U0VYT2ZNaVlEdXZUeWtkc1dDTmc
wd1RkbHIwQUVJTSIsICJ3elcxNWJoQ2t2a3N4VnZ1SjhSRjN4aThpNjRsbjFqb183NkJ
DMm9hMXVnIiwgInpPZUJYaHh2SVM0WnptUWNMbHhLdUVBT0dHQnlqT3FhMXoySW9WeF9
ZRFEiXSwgImlzcyI6ICJodHRwczovL2V4YW1wbGUuY29tL2lzc3VlciIsICJpYXQiOiA
xNjgzMDAwMDAwLCAiZXhwIjogMTg4MzAwMDAwMCwgInZjdCI6ICJodHRwczovL2JtaS5
idW5kLmV4YW1wbGUvY3JlZGVudGlhbC9waWQvMS4wIiwgImFnZV9lcXVhbF9vcl9vdmV
yIjogeyJfc2QiOiBbIkZjOElfMDdMT2NnUHdyREpLUXlJR085N3dWc09wbE1Makh2UkM
0UjQtV2ciLCAiWEx0TGphZFVXYzl6Tl85aE1KUm9xeTQ2VXNDS2IxSXNoWnV1cVVGS1N
DQSIsICJhb0NDenNDN3A0cWhaSUFoX2lkUkNTQ2E2NDF1eWNuYzh6UGZOV3o4bngwIiw
gImYxLVAwQTJkS1dhdnYxdUZuTVgyQTctRVh4dmhveHY1YUhodUVJTi1XNjQiLCAiazV
oeTJyMDE4dnJzSmpvLVZqZDZnNnl0N0Fhb25Lb25uaXVKOXplbDNqbyIsICJxcDdaX0t
5MVlpcDBzWWdETzN6VnVnMk1GdVBOakh4a3NCRG5KWjRhSS1jIl19LCAiX3NkX2FsZyI
6ICJzaGEtMjU2IiwgImNuZiI6IHsiandrIjogeyJrdHkiOiAiRUMiLCAiY3J2IjogIlA
tMjU2IiwgIngiOiAiVENBRVIxOVp2dTNPSEY0ajRXNHZmU1ZvSElQMUlMaWxEbHM3dkN
lR2VtYyIsICJ5IjogIlp4amlXV2JaTVFHSFZXS1ZRNGhiU0lpcnNWZnVlY0NFNnQ0alQ
5RjJIWlEifX19.GpFPbIEEgUGopARZQ0IyasBufd1KzTqq7qTjfla0PDmAlGD9W56Mfh
VGysuuq0FPv-hnLD7EU43r5ybMxWTQhw~WyJuUHVvUW5rUkZxM0JJZUFtN0FuWEZBIiw
gIm5hdGlvbmFsaXRpZXMiLCBbIkRFIl1d~WyJNMEpiNTd0NDF1YnJrU3V5ckRUM3hBIi
wgIjE4IiwgdHJ1ZV0~eyJhbGciOiAiRVMyNTYiLCAidHlwIjogImtiK2p3dCJ9.eyJub
25jZSI6ICIxMjM0NTY3ODkwIiwgImF1ZCI6ICJodHRwczovL2V4YW1wbGUuY29tL3Zlc
mlmaWVyIiwgImlhdCI6IDE3MzMyMzAxNDAsICJzZF9oYXNoIjogInRNd0FJV3hOQWtRN
E1ER2ctclVTbzVtdlVUWHhtTnVmUVkwbFJVeTlTY1EifQ.y-vNhbUIO0henLfhl-99D0
R6G84jixoBrQIfm7cHvAnSES0XTikftyN151NNBvjE2lXVp42eK8bCNGF1x7R-lg

The following is the payload of a corresponding Key Binding JWT:¶

{
  "nonce": "1234567890",
  "aud": "https://example.com/verifier",
  "iat": 1733230140,
  "sd_hash": "tMwAIWxNAkQ4MDGg-rUSo5mvUTXxmNufQY0lRUy9ScQ"
}

After validation, the Verifier will have the following processed SD-JWT payload available for further handling:¶

{
  "iss": "https://example.com/issuer",
  "iat": 1683000000,
  "exp": 1883000000,
  "vct": "https://bmi.bund.example/credential/pid/1.0",
  "age_equal_or_over": {
    "18": true
  },
  "cnf": {
    "jwk": {
      "kty": "EC",
      "crv": "P-256",
      "x": "TCAER19Zvu3OHF4j4W4vfSVoHIP1ILilDls7vCeGemc",
      "y": "ZxjiWWbZMQGHVWKVQ4hbSIirsVfuecCE6t4jT9F2HZQ"
    }
  },
  "nationalities": [
    "DE"
  ]
}

B.2. Example 2: Type Metadata

{
  "vct": "https://betelgeuse.example.com/education_credential",
  "name": "Betelgeuse Education Credential - Preliminary Version",
  "description": "This is our development version of the education credential. Don't panic.",
  "extends": "https://galaxy.example.com/galactic-education-credential-0.9",
  "extends#integrity": "sha256-9cLlJNXN-TsMk-PmKjZ5t0WRL5ca_xGgX3c1VLmXfh-WRL5",
  "display": [
    {
      "lang": "en-US",
      "name": "Betelgeuse Education Credential",
      "description": "An education credential for all carbon-based life forms on Betelgeusians",
      "rendering": {
        "simple": {
          "logo": {
            "uri": "https://betelgeuse.example.com/public/education-logo.png",
            "uri#integrity": "sha256-LmXfh-9cLlJNXN-TsMk-PmKjZ5t0WRL5ca_xGgX3c1V",
            "alt_text": "Betelgeuse Ministry of Education logo"
          },
          "background_color": "#12107c",
          "text_color": "#FFFFFF"
        },
        "svg_templates": [
          {
            "uri": "https://betelgeuse.example.com/public/credential-english.svg",
            "uri#integrity": "sha256-8cLlJNXN-TsMk-PmKjZ5t0WRL5ca_xGgX3c1VLmXfh-9c",
            "properties": {
              "orientation": "landscape",
              "color_scheme": "light",
              "contrast": "high"
            }
          }
        ]
      }
    },
    {
      "lang": "de-DE",
      "name": "Betelgeuse-Bildungsnachweis",
      "rendering": {
        "simple": {
          "logo": {
            "uri": "https://betelgeuse.example.com/public/education-logo-de.png",
            "uri#integrity": "sha256-LmXfh-9cLlJNXN-TsMk-PmKjZ5t0WRL5ca_xGgX3c1V",
            "alt_text": "Logo des Betelgeusischen Bildungsministeriums"
          },
          "background_color": "#12107c",
          "text_color": "#FFFFFF"
        },
        "svg_templates": [
          {
            "uri": "https://betelgeuse.example.com/public/credential-german.svg",
            "uri#integrity": "sha256-8cLlJNXN-TsMk-PmKjZ5t0WRL5ca_xGgX3c1VLmXfh-9c",
            "properties": {
              "orientation": "landscape",
              "color_scheme": "light",
              "contrast": "high"
            }
          }
        ]
      }
    }
  ],
  "claims": [
    {
      "path": ["name"],
      "display": [
        {
          "lang": "de-DE",
          "label": "Vor- und Nachname",
          "description": "Der Name des Studenten"
        },
        {
          "lang": "en-US",
          "label": "Name",
          "description": "The name of the student"
        }
      ],
      "sd": "allowed"
    },
    {
      "path": ["address"],
      "display": [
        {
          "lang": "de-DE",
          "label": "Adresse",
          "description": "Adresse zum Zeitpunkt des Abschlusses"
        },
        {
          "lang": "en-US",
          "label": "Address",
          "description": "Address at the time of graduation"
        }
      ],
      "sd": "always"
    },
    {
      "path": ["address", "street_address"],
      "display": [
        {
          "lang": "de-DE",
          "label": "Straße"
        },
        {
          "lang": "en-US",
          "label": "Street Address"
        }
      ],
      "sd": "always",
      "svg_id": "address_street_address"
    },
    {
      "path": ["degrees", null],
      "display": [
        {
          "lang": "de-DE",
          "label": "Abschluss",
          "description": "Der Abschluss des Studenten"
        },
        {
          "lang": "en-US",
          "label": "Degree",
          "description": "Degree earned by the student"
        }
      ],
      "sd": "allowed"
    }
  ],
  "schema_uri": "https://exampleuniversity.com/public/credential-schema-0.9",
  "schema_uri#integrity": "sha256-o984vn819a48ui1llkwPmKjZ5t0WRL5ca_xGgX3c1VLmXfh"
}

Appendix C. Acknowledgements

We would like to thank Alen Horvat, Andres Uribe, Christian Bormann, George J Padayatti, Giuseppe De Marco, Lukas J Han, Leif Johansson, Michael B. Jones, Mike Prorock, Orie Steele, Paul Bastian, Torsten Lodderstedt, Tobias Looker, and Kristina Yasuda for their contributions (some of which substantial) to this draft and to the initial set of implementations.¶

Appendix D. Document History

-08¶

Fix formatting issue introduced by the reintroduction of the DID paragraph in -07¶

-07¶

Revert change from previous release that removed explicit mention of DIDs in the Issuer-signed JWT Verification Key Validation section¶
Remove the requirement to insert a .well-known part for vct URLs¶
fix section numbering in SD-JWT references to align with the latest -14 version¶

-06¶

Update the anticipated media type registration request from application/vc+sd-jwt to application/dc+sd-jwt¶
Tightened the exposition of the Issuer-signed JWT Verification Key Validation section¶
Add the “Status” field for the well-known URI registration per IANA early review¶

-05¶

Include display and claim type metadata¶
Added example for type metadata¶
Clarify, add context, or otherwise improved the examples¶

-04¶

update reference to IETF Status List¶
Include Type Metadata¶
Include schema Type Metadata¶
Editorial changes¶
Updated terminology to clarify digital signatures are one way to secure VCs and presentations¶
Rework key resolution/validation for x5c¶

-03¶

Include disclosure of age_equal_or_over/18 in the PID example¶

-02¶

Made specific rules for public verification key validation conditional¶
Finetuned rules for obtaining public verification key¶
Editorial changes¶
added Brian Campbell as co-author¶
Renamed JWT Issuer Metadata to JWT VC Issuer Metadata¶
'iat' is now optional and allowed to be selectively disclosable¶
Fix inconstancy in the .well-known path construction¶
Added registration request to IANA for the well-known URI¶
Fix some formatting and text in the media type and JWT claim registration requests¶
Clarify the optionality of the cnf claim¶
Added relationships to other documents¶
Added PID example¶