Verifier requests, holder shares selective disclosures, verifier verifies hashes and signature.
Selective Disclosure Sharing: During the verification process, the verifier asked for a certain set of claims. The selective disclosure sharing mechanism allows the holder then to only share does require claims through sending the whole SD-JWT plus the disclosures which are needed for verification. This process therefore helps with privacy by not revealing more identity information than what's specifically requested.
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 in the same manner as the issuer did during the issuance process.
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 SD-JWT.
Transfer Format: Transferring the credential from holder to verifier happens through the sharing of the SD-JWT with the concatenated disclosures which were chosen to be revealed using the ~ sign. An example of this format would be:
Using either the CLI, Kotlin or REST option, you can start verifying your SD-JWT credential.
We create a presentation to provide the verifier with the holder's credentials for verification. The presentation can include data from multiple credentials, making verification easier as only one interaction is required. We provide the holder DID and the disclosures to create a presentation, which we can then present to a verifier, via the present command. Example Command
Options:
-i, --holder-did: DID of the holder (owner of the VC)
-c, --challange: Challenge to be used in the LD proof
--sd, --selective-disclosure: Path to selectively disclosed fields, in a simplified JsonPath format. Can be specified multiple times. By default NONE of the sd fields are disclosed, for multiple credentials, the path can be prefixed with the index of the presented credential, e.g. "credentialSubject.familyName", "0.credentialSubject.familyName", "1.credentialSubject.dateOfBirth".
other options
--sd-all-for: Selects all selective disclosures for the credential at the specified index to be disclosed. Overrides --sd flags!
--sd-all: Selects all selective disclosures for all presented credentials to be disclosed.
Example Response
Parseing the presentation to JSON
Using the parse command, you can print the presenation as a JSON object.
Options:
-r: Recursively parse credentials in presentation
-c: Credential content or file path
We can check the validity of the presentation by providing the verify command with it. Use the storage location printed at the end of the last command.
Example Command
Example Output
coming soon
Guide to SD-JWTs for selective disclosure; create, verify.
Intro - Learn about selective disclosure and its importance in the context of digital identity, and how SD-JWTs can be used for implementing it.
Issuing a SD-JWT Credential - Learn how to issue a Verifiable Credential using the SD-JWT format.
Verifying a SD-JWT Credential - Learn how to verify a Verifiable Credential using the SD-JWT format.
Selective Disclosure allows holders to reveal only necessary information.
Selective disclosure enables a holder to choose which pieces of information contained in a Verifiable Credential will be revealed to a verifier, rather than being forced to reveal all the data present in a Verifiable Credential.
For example, Alice could now only share her age to verify being old enough to purchase products offered in an ecommerce shop, without revealing other personal information present in her Verifiable ID document used for verification. This allows for greater privacy and control over personal data.
Selective disclosure is a critical aspect of SSI because it enables individuals to share only the minimum amount of personal information necessary to complete a transaction or interaction, while keeping the rest of their personal data private. This reduces the risk of identity theft and other types of fraud.
Our implementation of selective disclosure currently does not follow any specific standard, as standards in the field are still under development. As reference, we used the Selective Disclosure for JWTs (SD-JWT) reference by IETF. Please note that our implementation is subject to change.
A Selective Disclosure JSON Web Token (SD-JWT) is a type of in which the claims in the body are hashed, making them unreadable without disclosure. By providing the necessary disclosures, the original values of the claims can be revealed.
When presenting a classical credential via JWT, claims are visible to the verifier in plain text. With an SD-JWT credential, claims are encrypted in a hashed format, making them unreadable. This allows the holder to choose which claims to reveal to the verifier by providing the plain text key-value pairs (known as disclosures) next to the SD-JWT. The verifier can then hash these disclosures and compare them to the values in the SD-JWT, verifying that the claim was part of the SD-JWT. Additionally, SD-JWTs also allow for decoy hashes to be included in the credential, which are dummy values to conceal the actual number of claims in the credential.
In the following section, we will see how to issue and verify SD-JWT credentials.
Learn about issuing SD-JWT credentials which includes hashing, creating disclosures and adding decoy hashes
Credential Creation: The issuer first creates the credential, as usual.
Conversion to SD-JWT Credential: The issuer then transforms the credential into an SD-JWT. This is done by hashing all or only a subset of claims, adding decoy hashes, and preparing disclosures. At the end, the SD-JWT credential can contain plain-text claims next to disclosable ones.
Claim Hashing: The claim is transformed into a disclosure, which is a plain-text representations of the claim, by concatenating the attribute name and value, then prefixing it with a salt. The salt prevents attackers from guessing plain-text values via dictionary attacks. This is then converted to a base64 string, which will represent the disclosure. For example, the disclosure may look like this (salt + attribute name + value): [ “dC12Y2xpYi9tYXN0ZXI”, “given_name”, “John” ]. The disclosure is then put into a hash function, and the result gets included in the SD-JWT.
Adding Decoy Hashes: At this point, decoy hashes are also added to the SD-JWT. These decoy hashes are essentially dummy values that help conceal the actual number of claims a credential holds. By using decoy hashes, the issuer can prevent potential observers from determining how many claims are contained within the credential based on the number of hashes.
SD-JWT Credential Transfer to Holder: The issuer sends the SD-JWT and all disclosures to the holder. Because the holder now has the SD-JWT credential as well as all the disclosures, he can read the entire content of the credential. This allows the holder to decide which disclosures to send alongside the SD-JWT in a transaction with a verifier.
Transfer Format: On transfer, the SD-JWT is shared with the concatenated disclosures using the ~ sign. An example of this format would be:
Using either the CLI, Kotlin or REST option, you can start issuing your SD-JWT credential.
Setup section, if you never used the SSi-Kit before.
I will be using ssikit as an alias for ./ssikit.sh in this section.
Creating a did:key for our SD-JWT credential. Please refer to DIDs section for all options.
Example Response
We will be using the VerifiableId credential template for this example, but you can use whatever template you want. When issuing we specify the format of the VC as SD-JWT, the fields which we want to make selectily discloable and the number of decoy digests we want to include (optiona).
Options:
-s, --subject-did: DID of the subject
-i, --issuer-did: DID of the issuer
-y, --proof-type: Either JWT, LD_PROOF or SD_JWT
-t, --template: VC template, e.g VerifiableId
--sd, --selective-disclosure: Path to selectively disclosable fields (if supported by chosen proof type), in a simplified JsonPath format, can be specified multiple times, e.g credentialSubject.dataOfBirth
--num-decoys: Number of SD-JWT decoy digests to add (fixed mode), or max num of decoy digests (random mode)
--interactive: Interactively prompt for VC data to fill in
vc.txt: Path to output the generated VC
Example Response
Receiving a JWT token with disclosures appended via '~'.
Viewing body of SD-JWT in JSON format
Options:
-c: credential content or file path
Example Responsen
coming soon