Decentralized Identifiers

January 28, 2023

Introduction

As individuals or organizations, We use globally unique identifiers in various contexts, they serve as communication address (eg. phone numbers, mail address and usernames), identification numbers (eg. passports, driver license, ensurance) and products identification (barcode, serial numbers, RFIDs).

The majority of these globally unique identifiers are out of our control, and they are assigned by the authorities that decides who or what they refer to and when the can be revoked. To put an end to this power centralization over identities, decentralized identifiers emerged, but what are decentralized identifiers? Decentralized Identifiers or DIDs are a new type of identifiers that enables verifiable and decentralized digital identity. A DID refers to any object, be it a person, organization, a data model, an abstract entity, among others. It's a simple string that consists in three parts:

  1. The did URI scheme identifier
  2. The DID Method
  3. The DID method-specific identifier

Descentralized identifier simple example

The did example above resolves to an DID document. A DID document contains information associated with the DID, such as ways to cryptographically authenticate a DID controller.

Simple example of a DID document:

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/ed25519-2020/v1"
  ]
  "id": "did:example:123456789abcdefghi",
  "authentication": [{
    
    "id": "did:example:123456789abcdefghi#keys-1",
    "type": "Ed25519VerificationKey2020",
    "controller": "did:example:123456789abcdefghi",
    "publicKeyMultibase": "zH3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
  }]
}

Project goals

The project goals for decentralized identifiers are:

  • Decentralization
  • Control
  • Privacy
  • Security
  • Proof-based
  • Discovery
  • Interoperability
  • Portability
  • Simplicity
  • Extensibility

DID Architecture

DIDs (Decentralized Identifiers) were designed to be decoupled from centralized records, identity providers, and certification authorities. The design allows the DID controller to prove control over it without requiring permission from any other party. DIDs are URIs that associate a DID object with a DID document, allowing for trustful interactions associated with this object.

DID object is the entity identified by the Decentralized Identifier.

DID document is a set of data describing a DID object, including mechanisms, such as public cryptographic keys, that the DID object or DID delegate can use to authenticate and prove association to the DID.

DID URL extends the basic DID syntax to incorporate other standard URI components such as path, query, and fragment in order to locate a particular resource within the DID document.

DID controller is an entity capable of making changes to a DID document, a DID can have more than one DID controller, DID controllers can be denoted by the "controller" property at the top of the DID document, a DID controller can also be a DID object.

Each DID document can express a cryptographic material, verification method, or services that provide a set of mechanisms that allow a DID controller to prove control of the DID. The services allow for trustful interactions associated with the DID object. A DID may provide means to return the DID object itself if the DID object is an information resource such as a data model.

Identifier

DID Syntax

The DID generic scheme is an URI scheme in conformity with RFC3986. All DIDs must form to the following syntax rules:

did                = "did:" method-name ":" method-specific-id
method-name        = 1*method-char
method-char        = %x61-7A / DIGIT
method-specific-id = *( *idchar ":" ) 1*idchar
idchar             = ALPHA / DIGIT / "." / "-" / "_" / pct-encoded
pct-encoded        = "%" HEXDIG HEXDIG

DID URL Syntax

A DID URL is a network location identifier for a specific resource, and can be used to return things like DID object representations, verification methods, services, and specific parts of the DID document or other resources. It uses syntax that conforms to RFC5234. All DID URLs must conform to the syntax rules:

did-url = did path-abempty [ "?" query ] [ "#" fragment ]

Relative DID URLs

It´s any URL value into DID document that doesn't start with did:<method>:<method-specific-id>. Relative DID URLs are used to references verification methods and services inside a DID document without absolute URLS. DID methods where the storage size is a consideration have to use relative URLS to reduce the size of DID documents.

Relative DID URL example:

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/ed25519-2020/v1"
  ]
  "id": "did:example:123456789abcdefghi",
  "verificationMethod": [{
    "id": "did:example:123456789abcdefghi#key-1",
    "type": "Ed25519VerificationKey2020", // external (property value)
    "controller": "did:example:123456789abcdefghi",
    "publicKeyMultibase": "zH3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
  }, ...],
  "authentication": [
    // a relative DID URL used to reference a verification method above
    "#key-1"
  ]

The relative DID URL value will be transformed to an absolute DID URL: did:example:123456789abcdefghi#key-1

Data Model

An DID document consists of a map of entries, where each entry consists of a key/value pair, and the data model contains at least two different classes of entries:

  1. Properties.
  2. Representation-specific entries.

Core Properties

A DID is associated with a DID document. DID documents are expressed using data model and can be serialized into a representation. In this section you will get the core properties of DID documents.

Identifiers

DID Subject: is expressed using the property id inside a DID document.

{
  "id": "did:example:123456789abcdefghijk"
}

**DID Controller: ** is an entity authorized to make changes inside a DID document, the process for this authorization is defined by the DID method. DID controller is expressed by the property controller inside a DID document.

## DID document with unique controller
{
  "@context": "https://www.w3.org/ns/did/v1",
  "id": "did:example:123456789abcdefghi",
  "controller": "did:example:bcehfew7h32f32h7af3",
}

## DID document with 2 controllers
{
  "@context": "https://www.w3.org/ns/did/v1",
  "id": "did:example:123456789abcdefghi",
  "controller": [
			"did:example:bcehfew7h32f32h7af3",
			"did:example:zQ3shoUhBRLB6mBD6L2"
	],
}

Also Known As: An DID subject can have multiple identifiers for different purposes, or in different times, one of them can be the also Known As, it's expressed by the property alsoKnownAs inside a DID document.

{
  "@context": "https://www.w3.org/ns/did/v1",
  "id": "did:example:123456789abcdefghi",
  "alsoKnownAs":"Américo Júnior",
  "controller": "did:example:bcehfew7h32f32h7af3",
}

Verification Methods

The DID document can express verification methods, such as public cryptographic keys, that can be used to authenticate and authorize interactions with DID subject or associated parts. Verification methods can receive various parameters, it's designated by verificationMethod inside a DID document and must contain id, type and controller.

Verification method structure:

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/jws-2020/v1"
    "https://w3id.org/security/suites/ed25519-2020/v1"
  ]
  "id": "did:example:123456789abcdefghi",
  ...
  "verificationMethod": [{
    "id": ...,
    "type": ...,
    "controller": ...,
    "publicKeyJwk": ...
  }, {
    "id": ...,
    "type": ...,
    "controller": ...,
    "publicKeyMultibase": ...
  }]
}

Verification Material

Verification Material is any information used by the process that applies a verification method, the verification method type is expected to be used to determine its compatibility with such processes. Examples of verification materials are:

  • publicKeyJew
  • publicKeyMultibase

Note: An verification method cannot contain multiple verification materials.

A example of an DID document with verification methods using the properties quoted above:

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/jws-2020/v1",
    "https://w3id.org/security/suites/ed25519-2020/v1"
  ]
  "id": "did:example:123456789abcdefghi",
  ...
  "verificationMethod": [{
    "id": "did:example:123#_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A",
    "type": "JsonWebKey2020", // external (property value)
    "controller": "did:example:123",
    "publicKeyJwk": {
      "crv": "Ed25519", // external (property name)
      "x": "VCpo2LMLhn6iWku8MKvSLg2ZAoC-nlOyPVQaO3FxVeQ", // external (property name)
      "kty": "OKP", // external (property name)
      "kid": "_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A" // external (property name)
    }
  }, {
    "id": "did:example:123456789abcdefghi#keys-1",
    "type": "Ed25519VerificationKey2020", // external (property value)
    "controller": "did:example:pqrstuvwxyz0987654321",
    "publicKeyMultibase": "zH3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
  }],
  ...
}

Referring to Verification Methods

Verification methods can be embed or referenced by associated properties with various verification relationships. Referencing verification methods allows them to be used by more than one verification relationship.

If the verification method is map, it has been embedded and its properties can be accessed directly, but if the value of the verification method be a string URL, the verification method will be included by reference, and its properties will need to be retrieved from elsewhere in the DID document or another DID document. This is done by dereferencing the URl and searching the resulting resource for an verification method map by id.

Example of embedded or referenced verification methods:

{
...

  "authentication": [
    // this key is referenced and might be used by
    // more than one verification relationship
    "did:example:123456789abcdefghi#keys-1",
    // this key is embedded and may *only* be used for authentication
    {
      "id": "did:example:123456789abcdefghi#keys-2",
      "type": "Ed25519VerificationKey2020", // external (property value)
      "controller": "did:example:123456789abcdefghi",
      "publicKeyMultibase": "zH3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
    }
  ],

...
}

Verification Relationships

The verification relationship express the relation between DID subject and verification method. Different verification relationships enables associated verification methods to be used in different purposes. It is up to a verifier to verify the validity of a verification attempt by verifying that the verification method used is contained in the appropriate verification relationship property of the DID document.

Authentication

The authentication is used to specify how the DID subject have to be authenticated, for purposes such as login into websites or in any type of challenge-response protocol.

Example of authentication with 2 verification methods:

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/ed25519-2020/v1"
  ],
  "id": "did:example:123456789abcdefghi",
  ...
  "authentication": [
    // this method can be used to authenticate as did:...fghi
    "did:example:123456789abcdefghi#keys-1",
    // this method is *only* approved for authentication, it may not
    // be used for any other proof purpose, so its full description is
    // embedded here rather than using only a reference
    {
      "id": "did:example:123456789abcdefghi#keys-2",
      "type": "Ed25519VerificationKey2020",
      "controller": "did:example:123456789abcdefghi",
      "publicKeyMultibase": "zH3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
    }
  ],
  ...
}

If the authentication is established, will be ready to the DID method or another application decides what to do with the information. A particular DID method may decide whether authenticating itself as a DID controller is sufficient, for example, to update or delete a DID document, another DID method may require different keys, or an entire verification method, for the DID document to be updated or deleted.

Assertion

The assertionMethod is used to specify how the DID subject is expected to express claims, such as for purposes of requesting a verifiable credential. This property is usefulness, for example, in a process of verifiable credential, during the verification, the verifier verifies if the verifiable credential contains the proof created by the DID subject checking if the verification method used for the assert is associated with the verification method correspondent in DID document.

Example of Assertion Method with two verification methods:

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/ed25519-2020/v1"
  ],
  "id": "did:example:123456789abcdefghi",
  ...
  "assertionMethod": [
    // this method can be used to assert statements as did:...fghi
    "did:example:123456789abcdefghi#keys-1",
    // this method is *only* approved for assertion of statements, it is not
    // used for any other verification relationship, so its full description is
    // embedded here rather than using a reference
    {
      "id": "did:example:123456789abcdefghi#keys-2",
      "type": "Ed25519VerificationKey2020", // external (property value)
      "controller": "did:example:123456789abcdefghi",
      "publicKeyMultibase": "zH3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
    }
  ],
  ...
}

Key Agreement

The keyAgreement is used to specify how an entity can generate encryption material to transmit confidential information to an DID subject, such as to establish a secure communication channel with recipient.

An example of it's usefulness is when a message is encrypted to a DID subject, in this case, the third parts uses the public cryptographic key in the verification method to group an decryption key to the recipient.

Example of key agreement with 2 verification methods:

{
  "@context": "https://www.w3.org/ns/did/v1",
  "id": "did:example:123456789abcdefghi",
  ...
  "keyAgreement": [
    // this method can be used to perform key agreement as did:...fghi
    "did:example:123456789abcdefghi#keys-1",
    // this method is *only* approved for key agreement usage, it will not
    // be used for any other verification relationship, so its full description is
    // embedded here rather than using only a reference
    {
      "id": "did:example:123#zC9ByQ8aJs8vrNXyDhPHHNNMSHPcaSgNpjjsBYpMMjsTdS",
      "type": "X25519KeyAgreementKey2019", // external (property value)
      "controller": "did:example:123",
      "publicKeyMultibase": "z9hFgmPVfmBZwRvFEyniQDBkz9LmV7gDEqytWyGZLmDXE"
    }
  ],
  ...
}

Capability Invocation

The capabilityInvocation is used to specify the verification method that should be used by the DID subject to invoke the cryptographic capability, such as for authorization to update the DID document.

An example of its usefulness would be when the DID subject needs to access an protected HTTP API that requires authorization to be used, to authorize, the DID subject uses the capability associated with the URL exposed by the HTTP API. The capability invocation can be expressed in various ways, for example, digitally signed message inserted into HTTP Headers.

The HTTP API server is the capability verifier and needs to verify the referenced verification method to invoke the existent capability in the property capabilityInvocation at DID document. The verifier also have to verify if the performed action is valid and the capability is appropriated to the accessed resource. If the verification succeeds, the server cryptographically determines that the invocator is authorized to access the protected resource.

Example of the capability invocation with two verification methods:

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/ed25519-2020/v1"
  ],
  "id": "did:example:123456789abcdefghi",
  ...
  "capabilityInvocation": [
    // this method can be used to invoke capabilities as did:...fghi
    "did:example:123456789abcdefghi#keys-1",
    // this method is *only* approved for capability invocation usage, it will not
    // be used for any other verification relationship, so its full description is
    // embedded here rather than using only a reference
    {
    "id": "did:example:123456789abcdefghi#keys-2",
    "type": "Ed25519VerificationKey2020", // external (property value)
    "controller": "did:example:123456789abcdefghi",
    "publicKeyMultibase": "zH3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
    }
  ],
  ...
}

Capability Delegation

The capabilityDelegation is used to specify the mechanism that have to be used by the DID subject to delegate the cryptographic capability to another part, such as delegate the authority to access an specific HTTP API to an subordinate.

An example of its usefulness would be when the DID controller chooses to delegate its ability to access an HTTP API to another entity. To delegate a capability, the DID subject have to use the verification method associated with the verification relationship capabilityDelegate to cryptographically sign an another DID subject. The delegate should use the capability in similarly to the capability invocation.

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/ed25519-2020/v1"
  ],
  "id": "did:example:123456789abcdefghi",
  ...
  "capabilityDelegation": [
    // this method can be used to perform capability delegation as did:...fghi
    "did:example:123456789abcdefghi#keys-1",
    // this method is *only* approved for granting capabilities; it will not
    // be used for any other verification relationship, so its full description is
    // embedded here rather than using only a reference
    {
    "id": "did:example:123456789abcdefghi#keys-2",
    "type": "Ed25519VerificationKey2020", // external (property value)
    "controller": "did:example:123456789abcdefghi",
    "publicKeyMultibase": "zH3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
    }
  ],
  ...
}

Services

Services are used in DID documents to express ways of communicating with DID subjects or associated entities. A service can be any type of service that the DID subject wants to advertise, including decentralized identities managment services for further discovery, authentication, authorization or interaction.

Due to privacy questions, reveal public information through services, such as social media, personal websites and email address, is not recommended.

Example of service:

{
  "service": [{
    "id":"did:example:123#linked-domain",
    "type": "LinkedDomains", // external (property value)
    "serviceEndpoint": "https://americo.example.com"
  }]
}

Representations

Representation is a concrete serialization of an DID document, it's created by the serialization of data model through a process called as Production. The representation is transformed into a data model through a process called as Consumption.

The production and consumptions enables the information conversion of an representation to another. This specification defines representations to JSON and JSON-LD, and developers can use any other representation, such as XML or YAML.

Production and Consumption

Conclusion

These article is based in W3C Decentralized Identifiers specification, and with it I was able to explain the deeper concepts about DIDs and how they work.

A lot has been covered here, it's time to connect the concepts:

The Decentralized Identifiers (DIDs) are a new type of globally unique identifier. They are designed to enable individuals and organizations to generate their own identifiers using systems they trust. These new identifiers enable entities to prove control over them by authenticating using cryptographic proofs such as digital signatures.

An DID subject resolves to an DID document, a document that contains all information about the DID subject, these information are:

  • Identifiers
  • Also Known As
  • Verification methods
  • Verification relationships
  • Services

I'll stop here, I hope you enjoyed it, be prepared to receive the following content by subscribing to my newsletter.