DIDs

Overview

Decentralised identifiers (DIDs) are globally unique, highly available and cryptographically verifiable digital identifiers. They are typically represented as a Unique Resource Identifier (URI) that can point to a person, organisation, data model or any abstract entity.

The main difference between DIDs and traditional identifiers (e.g. email address or user account) is that they are not owned by any service provider or organisation. As such, they can be used across platforms and prevent vendor lock-in.

DIDs are a W3C standard and can be extremely effective at preserving user privacy, enhancing transparency and consent, enabling data portability and enforcing user control. DIDs can be used in identity management systems and provide superior security and encryption compared to passwords by using public/private key pairs instead. Thus, DIDs offer a different trust model to centralised identifiers. Specifically, DIDs form the basis of a Decentralised Public Key Infrastructure (DPKI) for the web.

DIDs are classified according to their DID method. Each method defines a CRUD model to describe how a specific DID scheme works with a specific verifiable data registry such as a distributed ledger or blockchain. There are many dozens of DID methods that defined their own specifications and contributed their DID scheme to the W3C.

DIDs are used through a process known as DID resolution, which locates the registry where the DID is anchored (based on its DID method) and retrieves its corresponding DID document. This is a JSON document that contains cryptographic material such as public keys as well as ways to interact with the DID subject via service endpoints.

Structure

DIDs are Unique Resource Identifiers (URIs) that follow the following pattern:

did:key example

did:key:z6MkjBWPPa1njEKygyr3LR3pRKkqv714vyTkfnUdP6ToFSH5

Methods

Different DID methods have different properties and are better suited to some use cases over others. There isn’t a DID method 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.

MATTR VII currently supports the following DID methods:

did:key : The most basic type of DID. The public key forms the DID and has no further data associated with it. Example: did:key:z6MkjBWPPa1njEKygyr3LR3pRKkqv714vyTkfnUdP6ToFSH5
did:web : This type of DID hosts requires hosting the DID document on a publicly accessible domain in order to make the document and contents available. Example: did:web:learn.vii.au01.mattr.global

`did:key`

DIDs with a method of key are the most basic type of DID. The public key forms the DID and has no further data associated with it.

MATTR VII automatically registers created DIDs when applicable. Any did:key will always have a registrationStatus of COMPLETED as it is instantly available to be used and resolved.

Constraints

This DID method does not support key rotation, and therefore there are limitations on using it in a long-term setting. When keys need to be rotated for any reason, all credentials issued using this DID must be revoked and reissued using the new key.
This DID method does not advertise a service endpoint, where a DID document advertises a public endpoint that could be used to send messages intended for the DID owner. As this DID method does not support this capability, any messages will need to be routed by different means. MATTR VII capabilities enable registering a did:key with a static inbox, so that all messages intended for the DID owner are routed to that mailbox.

Key types

Supported keyType for did:key are Ed25519 and Bls12381G2.
If the keyType is omitted, the default keyType is Ed25519. This keyType can be used as a Verifier DID.
If the keyType is set to Bls12381G2 the created DID supports BBS+ signatures for creating ZKP and selective disclosure enabled credentials.
As did:key only support Ed25519 or Bls12381G2 key types, you can only use it to create JSON credentials. If you wish to create CWT credentials, create a DID using a keyType of P-256, such as did:web.
Bls12381G2 cannot be used as a Verifier DID as it does not support symmetric key signing required to verify messages.

`did:web`

DIDs using the web method host the DID document on a publicly accessible domain in order to make the document and contents available.

For example, MATTR has a did:web using our own domain did:web:mattr.global. This DID is hosted on our website at https://mattr.global/.well-known/did.json. DIDs may also be hosted at specific paths on your website.

Constraints

did:webs inherently rely on the security of the website the DID Document is hosted on. We would only recommend the use of this type of DID on trusted and known sites/domains, such as government agencies and enterprises.
Message signing is not possible at this time using DIDs that only contain a bls12381g2 key type. Note that MATTR VII creates did:webs with multiple key types by default to overcome this constraint.
When you create a new credential configuration and don’t specify an explicit issuer DID, the most recently created did:web on your tenant is used as an issuer DID by default.

Key types

MATTR VII creates all did:web with multiple key types by default. This enables issuers to issue different types of credentials from a single DID, making use of the different key types features:

P-256 : This is the default option for signing CWT credentials.
Bls12381G2Key2020 : This is the default option for signing JSON credentials.
- Supports ZKP-enabled credentials.
- Supports key rotation.
X25519 suite:
- Ed25519 : Recommended when the web:did is used as a Verifier DID, as it supports symmetric key signing required for verifying messages.

Hosting

To make use of your did:web, you must make its DID document publicly available. It is important to understand that verifiers will rely on accessing the DID document to verify credentials issued using your did:web.

Therefore, the did.json file needs to be highly available. DID documents are not expected to change very often, so caching is encouraged using standard caching headers. A global CDN is also highly recommended to reduce latency during verification, as wallets may make multiple calls from across the world (use-case dependent).

Furthermore, if the DID is tied to an issuing infrastructure, when the latter is taken down for maintenance it will prevent both issuing and verifying during that downtime.

Taking these considerations into account, you can either host your did:web on your MATTR VII tenant, or on your own domain.

Resolving

MATTR VII can resolve hosted did:webs by retrieving their hosted DID document. The tenant can prove ownership of the keys associated with the DID Document through the https://{your_tenant_url}/.well-known/did-configuration endpoint. The fact that the DID Document is hosted on the domain links it to the DID.

DID document

Every DID can be resolved to a DID document. A fully resolved DID document typically includes information such as public keys, service endpoints and authentication mechanisms. It can include multiple public keys of different types to support various cryptographic algorithms or use cases

{
    "id": "did:web:learn.vii.au01.mattr.global",
    "@context": [
        "https://w3.org/ns/did/v1",
        "https://w3id.org/security/suites/x25519-2019/v1",
        "https://w3id.org/security/suites/jws-2020/v1",
        "https://w3id.org/security/suites/ed25519-2018/v1",
        "https://w3id.org/security/bbs/v1"
    ],
    "keyAgreement": [
        {
            "id": "did:web:learn.vii.au01.mattr.global#FZXtUmNERo",
            "type": "X25519KeyAgreementKey2019",
            "controller": "did:web:learn.vii.au01.mattr.global",
            "publicKeyBase58": "FZXtUmNERow4qGYb4LnLAVETodg7j7LrGyR78keGemWk"
        }
    ],
    "authentication": ["did:web:learn.vii.au01.mattr.global#Fo5mW6ivUV"],
    "assertionMethod": [
        "did:web:learn.vii.au01.mattr.global#z12L6Q6v",
        "did:web:learn.vii.au01.mattr.global#Fo5mW6ivUV",
        "did:web:learn.vii.au01.mattr.global#24QqAnwtn4"
    ],
    "verificationMethod": [
        {
            "id": "did:web:learn.vii.au01.mattr.global#z12L6Q6v",
            "type": "JsonWebKey2020",
            "controller": "did:web:learn.vii.au01.mattr.global",
            "publicKeyJwk": {
                "x": "hLdNSMnIaT1h-fjft9zX-nd_khjG7LERGImyNhzAlqU",
                "y": "ofu7wybOMA8ltzS3gYgdr0DMhlmJNmjhdYpwcHT1_O8",
                "crv": "P-256",
                "kty": "EC"
            }
        },
        {
            "id": "did:web:learn.vii.au01.mattr.global#Fo5mW6ivUV",
            "type": "Ed25519VerificationKey2018",
            "controller": "did:web:learn.vii.au01.mattr.global",
            "publicKeyBase58": "Fo5mW6ivUVsVS8e6EWuTFguQxTGFDMAZ7JBLuVqPsf1e"
        },
        {
            "id": "did:web:learn.vii.au01.mattr.global#24QqAnwtn4",
            "type": "Bls12381G2Key2020",
            "controller": "did:web:learn.vii.au01.mattr.global",
            "publicKeyBase58": "24QqAnwtn4AkCwiJHyBBe1eiyo6UegLx6AK8c3XSDUnopaNJP3EZvzgn8fLTaSWFY9T59PxdMp5RqoBBpCg8nGUdJnTVcTX7BPs8ubu516CNxNUehzwyTYzNdRt6YVqQSRMw"
        }
    ],
    "capabilityDelegation": [
        "did:web:learn.vii.au01.mattr.global#z12L6Q6v",
        "did:web:learn.vii.au01.mattr.global#Fo5mW6ivUV",
        "did:web:learn.vii.au01.mattr.global#24QqAnwtn4"
    ],
    "capabilityInvocation": [
        "did:web:learn.vii.au01.mattr.global#z12L6Q6v",
        "did:web:learn.vii.au01.mattr.global#Fo5mW6ivUV",
        "did:web:learn.vii.au01.mattr.global#24QqAnwtn4"
    ]
}

Verification relationships

Verification relationships are the building blocks in a DID document. They determine the relationship between a key and the different capabilities it can be used for. DID documents include the following verification relationships:

assertionMethod
authentication
keyAgreement

For example, when a credential proof is created, the used private key will be linked to the corresponding public key as referenced in the assertionMethod section. By resolving the DID document for the Issuer DID it’s possible for anyone to validate the credential proof, verifying that the Issuer has asserted the data in the credential to be true.

During a verification flow, these checks are handled automatically using secure industry-leading methods, providing a simple result.

DID URL

When referencing a specific sub-resource inside a DID document, we use the common fragment URLs pattern. When a DID key is specified in a single string, this is usually known as a DID URL, as shown in the following example:

did:key:z6MkjBWPPa1njEKygyr3LR3pRKkqv714vyTkfnUdP6ToFSH5#z6Mkn9kQbVXdeDW3h3GvYUV5BzTQDw5oh26CGDqS7sZq3kBN

Strictly speaking, any DID is a URL. However, we generally 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 an exact key.

Usage

MATTR VII tenants support managing DIDs, which includes creating, retrieving and deleting DIDs. When creating a new DID, MATTR VII generates the required keys and metadata and registers the DID on a public ledger (if applicable). When retrieving DIDs, the tenant resolves them to get the latest key and service information.

MATTR VII establishes a verifiable relationship between your tenant domain and DIDs created by your tenant, enabling linkage between an internet domain owner and a DID owner. This approach creates a bridge that connects the traditional trust model of the internet with a distributed trust model. This follows the Well Known DID Configuration open standard developed by the Decentralized Identity Foundation (DIF).

Common DID usages in MATTR VII

Issuer DID

MATTR VII can be used by issuers to create DIDs that are used in CWT, Semantic CWT and JSON credential proofs. These are referred to as Issuer DIDs for these credential formats.

The DID document must be publicly discoverable by verifiers so they can know that the DID keys used for the credential proof are from an issuer they trust. This could be via a government backed or large enterprise ecosystem, or another organisation they already know and trust.

Issuer DIDs private keys are stored in the MATTR VII Key Management System (KMS), and published on

the DID Configuration endpoint. They can be used to create different types of credentials, as well as support revocable credentials.

Verifier DID

MATTR VII can be used by verifiers to create DIDs that are used in a credential presentation exchange. These are referred to as Verifier DIDs. The credential holder needs to be sure that the received presentation request is from a valid verifier before sending their personal credential data in the response.

Even if other forms of trust are in place (e.g. the journey started from a website that the holder trusts) the DID to domain linkage must still be verified to validate the domain against the values used in the request.

Verifier DIDs private keys are stored in the MATTR VII KMS, and published on the DID Configuration endpoint. They must support message signing or key agreement for encryption.

MATTR wallets

When someone uses their MATTR wallet app to interact with a new domain (either issuer or verifier), a unique DID is created for that interaction.

Subject DID

Verifiable credentials that are linked to a specific holder (e.g. an education certificate) are referred to as subject-bound credentials. When a DID from a wallet user is used in subject-bound credentials, it is referred to as a Subject DID.

Holder DID

When a DID is used to create presentations in response to verifier requests, it is referred to as a Holder DID. MATTR VII generates a unique and new Holder DID for each issuer/verifier interaction.

If the verifier and the issuer are hosted on the same domain and using the same MATTR VII tenant, the same DID will be used for both the Holder DID and the Subject DID.

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 presentation requests.

Public DID

DIDs enable sending messages and data directly to the DID owner, assuming the sender has a way of retrieving the intended recipient DID. One such example is a Public DID that can be used to send secure messages and issue credentials to a specific digital wallet that is linked to this DID.

Additional resources

Guides

Create a `did:key`Create a `did:web`Self-host a `did:web`

API Reference

Create a DID

Revocation Implementation