did:web Decentralized Identifier Method Specification

Editor’s Draft,

This version:
Issue Tracking:

1. `did:web` Method Specification

1.1. Preface

The Web DID method specification conforms to the requirements specified in the [DID specification](https://w3c-ccg.github.io/did-spec/), currently published by the W3C Credentials Community Group. For more information about DIDs and DID method specifications, please see the [DID Primer](https://github.com/WebOfTrustInfo/rebooting-the-web-of-trust-fall2017/blob/master/topics-and-advance-readings/did-primer.md)

1.2. Abstract

DIDs that target a distributed ledger face significant practical challenges in bootstrapping enough meaningful trusted data around identities to incentivize mass adoption. We propose using a new DID method in conjunction with blockchain-based DIDs that allows them to bootstrap trust using a web domain’s existing reputation.

1.3. Example

Add non-ethereum example keys (ed25519, RSA, etc)

  "@context": "https://w3id.org/did/v1",
  "id": "did:web:example.com",
  "publicKey": [{
       "id": "did:web:example.com#owner",
       "type": "Secp256k1VerificationKey2018",
       "owner": "did:web:example.com",
       "ethereumAddress": "0xb9c5714089478a327f09197987f16f9e5d936e8a"
  "authentication": [{
       "type": "Secp256k1SignatureAuthentication2018",
       "publicKey": "did:web:example.com#owner"

1.4. Target System

Explain the difference from / relationship with the [Decentralized Identifier in DNS](https://tools.ietf.org/html/draft-mayrhofer-did-dns-01) spec

The target system of the Web DID method is the web host that the domain name described by the DID resolves to when queried through the Domain Name System (DNS).

1.5. DID Method Name

The namestring that shall identify this DID method is: `web`

A DID that uses this method MUST begin with the following prefix: `did:web`. Per the DID specification, this string MUST be in lowercase. The remainder of the DID, after the prefix, is specified below.

1.6. Method Specific Identifier

The method specific identifier is a fully qualified domain name that is secured by a TLS/SSL certificate with an optional path to the DID document. The formal rules describing valid domain name syntax are described in [RFC 1035](https://tools.ietf.org/html/rfc1035), [RFC 1123](https://tools.ietf.org/html/rfc1123), and [RFC 2181](https://tools.ietf.org/html/rfc2181).

The method specific identifier must match the common name used in the SSL/TLS certificate, and it must not include IP addresses or port numbers. Directories and subdirectories may optionally be included, delimited by colons rather than slashes.

web-did = "did:web:" domain-name

web-did = "did:web:" domain-name * (":" path)

1.6.1. Examples


1.7. JSON-LD Context Definition

Add example usage of non-secp keys (ed25519, RSA, etc)

Note this DID example uses the `Secp256k1VerificationKey2018`, `Secp256k1SignatureAuthentication2018` types and an `ethereumAddress` instead of a `publicKeyHex`.

The definition of the Web DID JSON-LD context is:

{ "@context": { "ethereumAddress": "https://github.com/uport-project/ethr-did-resolver#ethereumAddress", "Secp256k1VerificationKey2018": "https://github.com/uport-project/ethr-did-resolver#Secp256k1VerificationKey2018", "Secp256k1SignatureAuthentication2018": "https://github.com/uport-project/ethr-did-resolver#Secp256k1VerificationKey2018", } }

1.8. CRUD Operation Definitions

1.8.1. Create (Register)

Creating a DID is done by

  1. applying at a domain name registrar for use of a domain name and

  2. storing the location of a hosting service, the IP address at a DNS lookup service

  3. creating the DID document JSON-LD file including a suitable keypair, e.g., using the Koblitz Curve, and storing the `did.json` file under the well-known URL to represent the entire domain, or under the specified path if many DIDs will be resolved in this domain.

For the domain name `w3c-ccg.github.io`, the `did.json` will be available under the following URL:


If an optional path is specified rather the bare domain, the `did.json` will be available under the specified path:


1.8.2. Read (Resolve)

The following steps must be executed to resolve the DID document from a Web DID:

  1. Replace ":" with "/" in the method specific identifier to obtain the fully qualified domain name and optional path.

  2. Generate an HTTPS URL to the expected location of the DID document by prepending `https://`.

  3. If no path has been specified in the URL, append `/.well-known`.

  4. Append `/did.json` to complete the URL.

  5. Perform an HTTP `GET` request to the URL using an agent that can successfully negotiate a secure HTTPS connection, which enforces the security requirements as described in [Security Considerations](Security-Considerations).

1.8.3. Update

To update the DID document, the `did.json`has to be updated. Please note that the DID will remain the same, but the contents of the DID document could change, e.g., by including a new verification key or adding service endpoints.

1.8.4. Delete (Revoke)

To delete the DID document, the `did.json`has to be removed or has to be no longer publicly available due to any other means.

1.9. Security and Privacy Considerations

1.9.1. DNS Considerations

Add warning - all resolutions of a did:web identifier using DNS are centrally logged, enabling pervasive tracking mechanisms.

Add discussion of DNSCrypt and DNS Security Extensions (DNSSEC) and similar methods as possible mitigation tools.

1.9.2. DID Document Integrity Verification

Add discussion of using Hashlinks to aid integrity protection and verification of the DID document.

1.9.3. In-transit Security

At least TLS 1.2 should be configured to use only strong ciphers suites and to use sufficiently large key sizes. As recommendations may be volatile these days, only the very latest recommendations should be used. However, as a rule of thumb, the following must be used:

Examples of strong SSL/TLS configurations for now are:

It is recommended to adhere to [OWASP’s](https://www.owasp.org/index.php/Transport_Layer_Protection_Cheat_Sheet) latest recommendations for hardening TLS configurations.

Delete action can be performed by domain name registrars or DNS lookup services.

1.9.4. Optional Path Considerations

When optional paths to DID documents are used to resolve documents rather than bare domains, verification with signed data proves that the entity in control of the file indicated in the path has the private keys. It does not prove that the domain operator has the private keys.

This example:


resolves to the DID document at:


In this scenario, it is probable that example.com has given user Bob control over the DID in question, and proofs of control refer to Bob rather than all of example.com.

1.10. Reference Implementations

The code at [https://github.com/uport-project/https-did-resolver](https://github.com/uport-project/https-did-resolver) is intended to present a reference implementation of this DID method. Any other implementations should ensure that they pass the test suite described in `/src/__tests__` before claiming compatibility.


Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.


Normative References

S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119