Digitally Validate a Degree
In this tutorial, you will use the WASM binding of the IOTA Identity framework to digitally prove the existence and validity of a university degree. To follow along please clone this repository.
src/ directory contains scripts that can be run separately by providing command line arguments. Make sure that the npm dependencies - which include
the wasm bindings for the IOTA Identity Framework - are installed by running:
Alice recently graduated from the University of Oslo with a Bachelor of Computer Science. Now, she wants to apply for a remote job at the IOTA Foundation and needs to digitally prove the existence and validity of her degree. What she needs is an immutable and verifiable credential, approved by both the University of Oslo and herself, before presenting it to her potential employer.
As described in the Digital Identities Solution, IOTA Identity builds on the W3C's proposed standards for a digital identity framework based on three roles:
- Holder: Alice
- Issuer: University of Oslo
- Verifier: IOTA Foundation
|Decentralized Identifier (DID)||A globally unique persistent identifier that does not require a centralized registration authority and is often generated and/or registered cryptographically.|
|DID Subject||The entity identified by a DID and described by a DID document. Anything can be a DID subject: person, group, organization, physical thing, digital thing, logical thing, etc.|
|DID Document||A set of data describing the DID subject, including mechanisms, such as cryptographic public keys, that the DID subject or a DID delegate can use to authenticate itself and prove its association with the DID|
|Verification Method||A set of parameters that can be used together with a process to independently verify a proof. For example, a cryptographic public key can be used as a verification method for a digital signature; in such usage, it verifies that the signer possessed the associated cryptographic private key.|
|Verifiable Credential||A standard data model and representation format for cryptographically-verifiable digital credentials. It is signed by the issuer, to prove control over the Verifiable Credential with a nonce or timestamp.|
|Verifiable Presentation||A Verifiable Presentation is the format in which a (collection of) Verifiable Credential(s) gets shared. It is signed by the subject, to prove control over the Verifiable Credential with a nonce or timestamp.|
|DID Resolution||The process that takes as its input a DID and a set of resolution options and returns a DID document in a conforming representation plus additional metadata.|
In this tutorial, Stronghold will be used to securely store private keys. The Identity Framework already has Stronghold bindings for Node.js. We will be using them in this tutorial. For simplicity, each stronghold file will be responsible for storing only one DID.
In this process, you will complete the different steps from the perspective of one of the mentioned roles above:
1. Holder: Create a DID
The first thing you will need to do in this tutorial is to create a DID (Decentralized Identifier) Document for Alice. The script createDid.ts can be used to create DIDs using the command:
npm run start create-did <name> <stronghold-password>
For Alice, a DID can be created using:
npm run start create-did alice alice-password
This will create a minimal DID document for alice, and publish it to the Tangle. A Stronghold file
alice.hodl will be created under
/stronghold-files which contains the Account's state and the private key of the main verification method of the DID.
alice-password will be used as a password for the stronghold storage. Obviously this password must be more secure in production applications.
See Creating a Decentralized Identity for more information about generating DIDs.
2. Issuer: Create a DID
Once you have created Alice's DID, you should do the same for the University of Oslo.
npm run start create-did uni-of-oslo uni-password
uni-of-oslo.hodl will be created under
3. Issuer: Add a Verification Method
Since the university will need to issue a signed verifiable credential for Alice, a verification method should be added to the university's DID document. Read more about adding verification methods in update DID Documents.
To add a Verification Method the following command can be used:
npm run start create-vm <identity-name> <stronghold-password> <verification-fragment>
This command will invoke verificationMethods.ts.
identity-name is used to identify the Stronghold file location in
verification-fragment is used to identify the Verification Method inside the DID Document.
To create a Verification Method for the issuer, use the following command:
npm run start create-vm uni-of-oslo uni-password key-1
4. Holder: Add a Verification Method
Alice will need a verification method to sign verifiable presentations before sending them to third parties. Hence a verification method also needs to be added to her DID document.
Similar to the issuer, the following command can be run to add a verification method to Alice's DID Document.
npm run start create-vm alice alice-password key-1
5: Issuer: Create Revocation list
In order for the issuer to be able to revoke credentials in the future, a revocation list is needed. See Verifiable Credential Revocation for further details. The following command can be used to create a revocation list:
npm run start add-revocation-list <identity-name> <stronghold-password> <revocation-fragment>
This will invoke revocationBitmap.ts.
For the University of Oslo use:
npm run start add-revocation-list uni-of-oslo uni-password rev-1
rev-1 is used to identity this revocation list inside the DID document.
5 Issuer: Create Verifiable Credential
University of Oslo can now issue a verifiable credential to Alice. The following command can be used to create a verifiable credential:
npm run start create-vc <issuer-name> <issuerPassword> <subjectName> <subjectDid> <verificationMethodFragment> <revocationBitmapFragment> <revocationIndex>
This will invoke verifiableCredentials.ts.
To create a verifiable credential for Alice, run the following command:
npm run start create-vc uni-of-oslo uni-password alice <subjectDid> key-1 rev-1 5
<subjectDid> needs to be replaced with Alice's DID. The reason we didn't use Alice's Stronghold file, is that the issuer doesn't have access to it in a real world scenario.
If you didn't note Alice's DID upon creating the DID, use
npm run start get-did alice alice-password to log the DID saved in Alice's Stronghold file.
This verifiable credential is given a revocation index of
5, this will be used later when the verifiable credential will be revoked. \
The command will execute the script in verifiableCredentials.ts which creates a verifiable credential using values provided as arguments
and hard-coded values to describe the issued degree. This credential will be tied to
rev-1 revocation list and then signed with
key-1 verification method.\
Once the script execution finishes, the file
alice-credential.json will be created in the
credentials/ directory. The file contains the credential in JSON format
and is usually sent back to Alice to store and enable her to prove her degree.
6 Holder: Create Verifiable Presentation
After Alice received the verifiable credential from the university, she applies for a job at the IOTA Foundation. The foundation requests a verifiable presentation to be signed by alice that includes the challenge 'xyz123'. The script verifiablePresentation.ts can be run with the command:
npm run start create-vp <holder-name> <holder-password> <credential-file> <verification-method-fragment> <challenge>
For Alice's case:
npm run start create-vp alice alice-password alice-credential.json key-1 xyz123
This will create a verifiable presentation of Alice's credential that includes the challenge and signed by Alice's
key-1 verification method.
The resulted presentation is saved in
7 Verifier: Verification
Now alice sends the signed verifiable presentation to the IOTA Foundation. The foundation now has to verify if everything is correct and the credential is valid.
The script checkVerifiablePresentation can be run with the command:
npm run start verify-vp <presentation-file> <challenge>
So the foundation can run:
npm run start verify-vp alice-presentation.json xyz123
Since everything was signed correctly, the verification should succeed.
8 Issuer: Revocation
Unfortunately the university found out, that Alice had cheated on her final exam. Therefore, the university wants to revoke the validity of Alice's credential.
Since the revocation list
rev-1 with revocation index
5 were used upon creating the verifiable credential, revocation is now possible by updating the revocation list.
revocation.ts can be run with the command:
npm run start revoke-vc <issuer-name> <issuer-password> <revocation-bitmap-fragment> <revocation-index>
To revoke Alice's Credential you can run:
npm run start revoke-vc uni-of-oslo uni-password rev-1 5
This will update the revocation list inside the issuer's DID Document and publish it to the tangle. Now if the IOTA Foundation tries to verify the credential again
e.g. by running
npm run start verify-vp alice-presentation.json xyz123, This will throw an error since the verification now fails.