Digitally Validate a Degree

Outdated

This turorial uses the legacy method of the identity library.

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.

The 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:

npm install

Degree Validation

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.

Roles

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

Terms

Term	Definition
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.

Sequence-Chart

Storage

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.

Steps

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

with that uni-of-oslo.hodl will be created under /stronhold-files.

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.

Note that identity-name is used to identify the Stronghold file location in /stronghold-files while 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

Notice that 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

Notice that <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 presentations/alice-presentation.json.

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.