Table of contents
Author
Verifiable Credentials are changing the digital identity space and will soon become part of our daily lives.
In Europe, the new eIDAS 2.0 regulation mandates the creation of the EU Digital Identity Wallet (EUDI Wallet) for handling Verifiable Credentials. This means that all EU member states will have to provide a digital identity wallet to interested citizens by 2026. As a result of this commitment, the relevant standards and technical specifications are rapidly evolving.
Enter the SD-JWT standard and its application in the SD-JWT-based Verifiable Credentials.
JWT and SD-JWT: Understanding the Difference
If you've worked with identity and authentication systems before, you've probably encountered JSON Web Tokens (JWTs). JWTs have become the go-to standard for traditional web authentication: They're widely adopted, easy to use, and reliable.
However, one limitation of JWTs is that all the information they contain in JWT claims is shared with whoever receives them. The need for a more privacy-preserving solution led to the development of a new SD JWT (Selective Disclosure JWT) format. Unlike traditional JWTs, SD-JWTs are designed to reveal only the necessary information.
What is selective disclosure?
Selective disclosure lets individuals decide which information they want to reveal to a third party. This differs from standard methods where all data must be disclosed at once.
The image above illustrates this difference by comparing the traditional JWT and the SD-JWT: in SD-JWT, the claims are hashed and therefore hidden, requiring additional information to access them, one at a time. (We'll see how this is achieved later on.)
Selective disclosure ensures greater privacy and control over personal data. It aligns with evolving privacy regulations and fits well with the decentralized identity model, granting individuals greater autonomy over their personal information.
SD-JWT-based Verifiable Credentials
The SD-JWT-based Verifiable Credentials (SD-JWT VC) is a newly developed format for expressing Verifiable Credentials, based on the SD-JWT standard we just discussed.
Its primary feature is the ability to enable selective disclosure. This allows credential Holders—individuals who possess or utilize digital credentials—to only share specific information, instead of being forced to reveal all the data contained in a Verifiable Credential.
The use of selective disclosure in SD-JWT VCs is optional: The format can be used without any selective disclosable claims, too.
Check out our Verifiable Credentials Glossary if you’re new to the topic. It explains the Issuer-Holder-Verifier model and other terms used in this article.
How it works: a brief technical overview
In short, when issuing an SD-JWT VC to a Holder, an Issuer only includes the hashed claim values in the signed portion of the credential. Then, the cleartext forms of all hidden claims, known as Disclosures, are appended to the signed portion of the SD-JWT.
When presenting information to a Verifier, the Holder can decide which claims to reveal, including only the corresponding Disclosures in an SD-JWT provided to that Verifier. The Verifier verifies hashes and the signature to confirm that all disclosed claims were initially part of the JWT signed by the Issuer. But the Verifier does not gain access to any claim values not included in the provided Disclosures.
Now, let's take a closer look at how this process works.
Issuing an SD-JWT VC
1. Creating JWT claims: The Issuer starts by creating JWT claims with personal information to be included in a credential issued to the Holder. The claims may appear as follows:
2. Creating Disclosures: The Issuer chooses which of the claims are eligible for selective disclosure (or doesn’t pick any if selective disclosure is not required by the use case). Each eligible claim is transformed into a Disclosure by concatenating the attribute name and value and prefixing it with a salt: salt + attribute name + value. The salt prevents attackers from guessing plain-text values via dictionary attacks.
The result is put into a JSON array. For instance, if the firstname, lastname, and ssn are designated for selective disclosure, the result might look like this:
Note that we’re not adding the Disclosure for the “id” claim: This means the “id” claim will always be available to the Verifier.
The JSON arrays are then converted to base64 strings, which will represent the Disclosures:
Later, when it's time to send the credential to the Holder, the Issuer will include the Disclosures into an SD-JWT VC by concatenating them to the signed portion of the credential with a tilde sign (~).
3. Creating Issuer-signed JWT: The Issuer creates an SD-JWT payload including the hashed versions of the Disclosures (instead of the plaintext claims) in an array named "_sd". The resulting payload may appear as follows:
The plaintext claims from Step 1 have now been replaced by the hashed values of the corresponding Disclosures. Note that the SD-JWT credential can contain plaintext claims (e.g. "id") next to the disclosable ones.
_sd_alg specifies the algorithm used for hashing.
Once the payload is updated, the Issuer adds an SD-JWT Header with the typ value vc+sd-jwt and an algorithm of choice, e.g.:
and signs the token. This forms the so-called Issuer-signed JWT.
4. Optional Key Binding: Optionally, before signing the SD-JWT payload in the previous step, the Issuer can include a public key associated with the Holder—or a reference to it—in the payload section of the Issuer-signed JWT. This is a prerequisite for the Holder to create a Key Binding JWT (KB-JWT) at the time of verification.
In other words, the presence of the KB JWT enables the Holder to confirm they’re the same person the credential has been issued to when presenting the data to the Verifier. Additionally, it ensures that the Disclosures were indeed selected by the Holder.
5. SD-JWT VC is sent to Holder: Finally, the Issuer combines the Issuer-signed JWT with the Disclosures separated by tildes ('~') and sends the credential to the Holder:
The Holder will have access to both the SD-JWT credential and all the Disclosures. This means the Holder will be able to review the credential's content and choose which Disclosures to share during transactions with Verifiers.
Sharing an SD-JWT VC
When the Holder is ready to present the information to a Verifier, they share the original SD-JWT along with the chosen Disclosures and an optional Key Binding JWT concatenated with a tilde ('~') sign in an SD-JWT Presentation:
For instance, if our Holder, Alice, opts to share only her first name, the Verifier would receive:
Verifying an SD-JWT VP
1. Selective Disclosure Sharing: During the verification process, the Verifier requests a certain set of claims. The selective disclosure sharing mechanism allows the Holder to only share the required claims by sending the original SD-JWT along with the Disclosures necessary for verification.
2. Disclosure Verification: The Verifier, upon receiving the shared Disclosures and the SD-JWT, can confirm that the shared Disclosures are a part of the SD-JWT. This is done by hashing the received Disclosures using the same algorithm the Issuer used during the issuance process.
3. Hash Comparison and Tamper Check: The Verifier then compares the hashed values of the shared disclosures with the values present in the SD-JWT. If the hashed values match, the Verifier can be confident that the shared values haven't been tampered with and are actually part of the original SD-JWT.
4. Checking the Key Binding JWT: If the Verifier requires Key Binding to prove that the Holder is the legitimate owner of the credential, the Holder will be asked to prove possession of a cryptographic key referenced in the credential.
The SD-JWT VC issuance and presentation are illustrated in the diagrams below:
Real-World Use Cases
Selective disclosure can be valuable in many situations. For instance:
Age Verification: Consider an individual attending an event or making a purchase where age verification is mandatory. Instead of sharing all personal information, they can opt to disclose only e.g. their birthdate. This lets individuals comply with the event’s requirements while maintaining their privacy.
Banking: Customers can share only the information required to securely complete a financial transaction.
Education: Students can selectively disclose their academic history by only sharing the relevant transcripts, diplomas, or other information when applying for internships, jobs, or further education.
Employment: Hiring managers can leverage selective disclosure to verify the education and employment history of job applicants while accessing only the minimum information necessary to make informed hiring decisions.
Healthcare: Patients can disclose their medical history selectively, providing only the information required for a specific procedure or treatment.
Selective disclosure is particularly beneficial in situations where certain personal details are sensitive or irrelevant to the recipient. By selectively sharing information, the Holder reduces the risk of exposing sensitive information while still meeting the Verifier’s requirements.
Summary
SD-JWT builds upon a well-established JWT format and provides a foundation for creating Verifiable Credentials that are both easy to process and capable of selective disclosure.
While it’s not the only format offering selective disclosure, SD-JWT has become an integral component of the latest EUDI Wallet Architecture and Reference Framework and has already gained widespread adoption across Europe. As more organizations implement SD-JWT VC solutions, the new standard is likely to remain prevalent in the foreseeable future.
Author
