Learn

Create a Decentralized Identifier

Overview

As we covered in the MATTR VII DIDs introduction, Decentralized Identifiers (DIDs) provide a standards-based way of allowing a person, group or organisation (or even a thing) to uniquely identify themselves.

This tutorial will demonstrate how to use Decentralized Identifiers on the MATTR VII Core, which generally means they will be used in Issue and Verify VC flows. The sorts of DID that can be issued on MATTR VII have different properties and some are better suited to some use cases over others. There isn't a DID method yet that should be universally applied to every situation so getting a good understanding of the different offerings will help you decide which is going to work best for your use cases.

Note: W3C DIDs are an emerging standard at the W3C, DIDs issued during a trial on the MATTR VII platform may be subject to change. As you move into production workloads please get in touch to discuss your needs.

Outline of a DID

DIDs are actually URIs, they follow a certain pattern and they resolve to a DID Document.

Example of a basic did:key

http
Copy to clipboard. 
1did:key:z6MkjBWPPa1njEKygyr3LR3pRKkqv714vyTkfnUdP6ToFSH5

DID Document

A fully resolved DID Document contains information like public keys and additional metadata which can be used with the DID.

json
Copy to clipboard. 
1{
2    "@context": "https://w3.org/ns/did/v1",
3    "id": "did:key:z6MkjBWPPa1njEKygyr3LR3pRKkqv714vyTkfnUdP6ToFSH5",
4    "publicKey": [
5      {
6        "id": "did:key:z6MkjBWPPa1njEKygyr3LR3pRKkqv714vyTkfnUdP6ToFSH5#z6Mkn9kQbVXdeDW3h3GvYUV5BzTQDw5oh26CGDqS7sZq3kBN",
7        "type": "Ed25519VerificationKey2018",
8        "controller": "did:key:z6MkjBWPPa1njEKygyr3LR3pRKkqv714vyTkfnUdP6ToFSH5",
9        "publicKeyBase58": "8hVN1FHCJg1aaYSDruXELtuQQMoxH8qqaCvWHbbp8XPz"
10      }
11    ],
12    "authentication": [
13      "did:key:z6MkjBWPPa1njEKygyr3LR3pRKkqv714vyTkfnUdP6ToFSH5#z6Mkn9kQbVXdeDW3h3GvYUV5BzTQDw5oh26CGDqS7sZq3kBN"
14    ],
15    "assertionMethod": [
16      "did:key:z6MkjBWPPa1njEKygyr3LR3pRKkqv714vyTkfnUdP6ToFSH5#z6Mkn9kQbVXdeDW3h3GvYUV5BzTQDw5oh26CGDqS7sZq3kBN"
17    ],
18    "capabilityDelegation": [
19      "did:key:z6MkjBWPPa1njEKygyr3LR3pRKkqv714vyTkfnUdP6ToFSH5#z6Mkn9kQbVXdeDW3h3GvYUV5BzTQDw5oh26CGDqS7sZq3kBN"
20    ],
21    "capabilityInvocation": [
22      "did:key:z6MkjBWPPa1njEKygyr3LR3pRKkqv714vyTkfnUdP6ToFSH5#z6Mkn9kQbVXdeDW3h3GvYUV5BzTQDw5oh26CGDqS7sZq3kBN"
23    ],
24    "keyAgreement": [
25      {
26        "id": "did:key:z6MkjBWPPa1njEKygyr3LR3pRKkqv714vyTkfnUdP6ToFSH5#z6LSq5sCpaMQb4rphP2dfrEEwgRBQSwSDXUgkcq1vwrkYm8c",
27        "type": "X25519KeyAgreementKey2019",
28        "controller": "did:key:z6MkjBWPPa1njEKygyr3LR3pRKkqv714vyTkfnUdP6ToFSH5",
29        "publicKeyBase58": "EQh3JGYYVc95bzes9CiHd6ChZJQKWvJXse7LSVDDqPMr"
30      }
31    ]
32  }

DID URL

When referencing a specific sub-resource inside a did document, we use the common pattern of URLs like they’re used today on the web. For example, a key in the document can be referenced using a fragment #. When a key in a DID is specified in a single string, this is usually known as a DID URL.

Copy to clipboard. 
1did:key:z6MkjBWPPa1njEKygyr3LR3pRKkqv714vyTkfnUdP6ToFSH5#z6Mkn9kQbVXdeDW3h3GvYUV5BzTQDw5oh26CGDqS7sZq3kBN

Strictly speaking, any DID is a URL, however generally we have used the term DID URL to mean the more specific version, so in our API Reference, didUrl would mean providing a value of the DID with the # to reference the exact key.

Verification relationships

Verification relationships are the base building blocks in a DID Document to understand the relationship of a key to the different capabilities it can be used for with the did. Today in DID Documents in use by the MATTR VII platform, there are 3 main verification relationships;

  1. assertionMethod

  2. authentication

  3. keyAgreement

For example, when a Credential proof is created, the private key used will have a DID URL that is linked to the corresponding public key as referenced in the assertionMethod section of the DID Document.

So by resolving the DID Document for the Issuer DID it’s possible for anyone to validate the proof of the Credential, verifying that the Issuer has asserted the data in the credential to be true.

json
Copy to clipboard. 
1"assertionMethod": [
2  "did:key:z6MkjBWPPa1njEKygyr3LR3pRKkqv714vyTkfnUdP6ToFSH5#z6Mkn9kQbVXdeDW3h3GvYUV5BzTQDw5oh26CGDqS7sZq3kBN"
3],

During a verification flow, these checks are handled automatically using secure industry-leading methods, allowing you to retrieve a simple result.

DID Purposes

A DID can be created and used in different ways, this section explains how they are used by the platform for different purposes and common names they are referred to when being used in these ways.

Note a DID of a certain ‘method’ can be used for any purpose but practically some are better suited than others.

Issuer DID - When a DID, that has been created on the Platform by an issuer, is used to create a proof for a credential, either directly on the create/sign a credential endpoints or via the OIDC Bridge Issuer, it can be referred to as an Issuer DID.

The DID Document needs to be publicly discoverable by Verifiers so they can know that the keys in the DID used for the proof of the Credential are from someone they trust (could be via Government backed Trust framework, large enterprise or another organisation they already know).
Both did:web and did:ion allow for ed22159 and BLS keys (used to create ZKP-enabled credentials) as well as future-proofing for key-rotation if required. Currently, p-256 keys are only supported on did:web for the use of signing compact credentials.

A did:key with ed22159 or BLS keys can be used but pose limitations for long-lived credentials, as there is no abstraction between the DID and the key.

Verifier DID - When a DID is created on the Platform by a verifier and used in the messaging for a presentation exchange, it can be referred to as a Verifier DID.

The credential holder needs to know that the Presentation Request from a verifier is valid before sending their personal credential data in the response.

Even if other forms of trust are in place (e.g. if the journey started from a website that the Holder trusts) the mobile wallet will still check the DID to Domain linkage at the DID Configuration endpoint to validate the domain against the values used in the message.

All DID methods did:web, did:ion and did:key with ed25519 key types can be used.

DIDs with BLS keys which are used for creating ZKP-enabled credentials are best avoided for Verifier DIDs, and offer no advantage over an ed25519 key in messaging.
A did:key with BLS cannot be used for Verifier DIDs as it does not support message signing or encryption. did:web and did:ion with BLS can support message encryption but not signing.

MATTR Mobile Wallet DIDs

When someone uses their MATTR Mobile wallet app to interact with a new domain, a DID is created for that interaction.

Subject DID - When a DID from a mobile wallet user is used in subject-bound Credentials, it can be considered a Subject DID.

For OIDC Credential issuance flow, the Subject DID is used to sign the request object in the authorization request, proving the client has control of the DID for the request.

Holder DID - When a DID is used in creating presentations in response to verifier requests, it is referred to as the Holder DID.

MATTR Wallet generates a new DID for each new interaction of either a Verifier or Issuer domain.

Note: if a Verifier is on the same domain as the Issuer, then the mobile wallet will use the same DID for both Holder and Subject.

As part of the W3C Verifiable Credential data model specification, the verifiable presentation model is used to wrap all Credentials inside a presentation and apply cryptographic proofs. The Subject DID from each Credential is used to sign the presentation, as well as the Holder DID (even if they are the same). The Holder DID is the only DID presented to the verifier during DID auth requests.

Public DID - The MATTR mobile wallet has also introduced a way to obtain a did:key DID for ease of use that you can share with others, allowing them to send you secure messages and create credentials for you. Go to Menu > Settings > Public DID copy to clipboard and share with others.

Currently only did:key is available on the mobile wallet, it has the advantage of being lightweight and easy to manage, however making future did methods available on the mobile wallet is being considered.