Archived: Decentralized Identifiers (DIDs) v1.0

1.1 A Simple Example

This section is non-normative.

A DID is a simple text string consisting of three parts: 1) the did URI scheme identifier, 2) the identifier for the DID method, and 3) the DID method-specific identifier.

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

{
  "@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"
  }]
}

1.2 Design Goals

This section is non-normative.

Decentralized Identifiers are a component of larger systems, such as the Verifiable Credentials ecosystem [VC-DATA-MODEL], which influenced the design goals for this specification. The design goals for Decentralized Identifiers are summarized here.

1.3 Architecture Overview

This section is non-normative.

This section provides a basic overview of the major components of Decentralized Identifier architecture.

DIDs and DID URLs

A Decentralized Identifier, or DID, is a URI composed of three parts: the scheme did:, a method identifier, and a unique, method-specific identifier specified by the DID method. DIDs are resolvable to DID documents. A DID URL extends the syntax of a basic DID to incorporate other standard URI components such as path, query, and fragment in order to locate a particular resource—for example, a cryptographic public key inside a DID document, or a resource external to the DID document. These concepts are elaborated upon in § 3.1 DID Syntax and § 3.2 DID URL Syntax.

DID subjects

The subject of a DID is, by definition, the entity identified by the DID. The DID subject might also be the DID controller. Anything can be the subject of a DID: person, group, organization, thing, or concept. This is further defined in § 5.1.1 DID Subject.

DID controllers

The controller of a DID is the entity (person, organization, or autonomous software) that has the capability—as defined by a DID method—to make changes to a DID document. This capability is typically asserted by the control of a set of cryptographic keys used by software acting on behalf of the controller, though it might also be asserted via other mechanisms. Note that a DID might have more than one controller, and the DID subject can be the DID controller, or one of them. This concept is documented in § 5.1.2 DID Controller.

Verifiable data registries

In order to be resolvable to DID documents, DIDs are typically recorded on an underlying system or network of some kind. Regardless of the specific technology used, any such system that supports recording DIDs and returning data necessary to produce DID documents is called a verifiable data registry. Examples include distributed ledgers, decentralized file systems, databases of any kind, peer-to-peer networks, and other forms of trusted data storage. This concept is further elaborated upon in § 8. Methods.

DID documents

DID documents contain information associated with a DID. They typically express verification methods, such as cryptographic public keys, and services relevant to interactions with the DID subject. The generic properties supported in a DID document are specified in § 5. Core Properties. A DID document can be serialized to a byte stream (see § 6. Representations). The properties present in a DID document can be updated according to the applicable operations outlined in § 8. Methods.

DID methods

DID methods are the mechanism by which a particular type of DID and its associated DID document are created, resolved, updated, and deactivated. DID methods are defined using separate DID method specifications as defined in § 8. Methods.

DID resolvers and DID resolution

A DID resolver is a system component that takes a DID as input and produces a conforming DID document as output. This process is called DID resolution. The steps for resolving a specific type of DID are defined by the relevant DID method specification. The process of DID resolution is elaborated upon in § 7. Resolution.

DID URL dereferencers and DID URL dereferencing

A DID URL dereferencer is a system component that takes a DID URL as input and produces a resource as output. This process is called DID URL dereferencing. The process of DID URL dereferencing is elaborated upon in § 7.2 DID URL Dereferencing.

1.4 Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, SHOULD, and SHOULD NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

This document contains examples that contain JSON and JSON-LD content. Some of these examples contain characters that are invalid, such as inline comments (//) and the use of ellipsis (...) to denote information that adds little value to the example. Implementers are cautioned to remove this content if they desire to use the information as valid JSON or JSON-LD.

Some examples contain terms, both property names and values, that are not defined in this specification. These are indicated with a comment (// external (property name|value)). Such terms, when used in a DID document, are expected to be registered in the DID Specification Registries [DID-SPEC-REGISTRIES] with links to both a formal definition and a JSON-LD context.

Interoperability of implementations for DIDs and DID documents is tested by evaluating an implementation's ability to create and parse DIDs and DID documents that conform to this specification. Interoperability for producers and consumers of DIDs and DID documents is provided by ensuring the DIDs and DID documents conform. Interoperability for DID method specifications is provided by the details in each DID method specification. It is understood that, in the same way that a web browser is not required to implement all known URI schemes, conformant software that works with DIDs is not required to implement all known DID methods. However, all implementations of a given DID method are expected to be interoperable for that method.

A conforming DID is any concrete expression of the rules specified in § 3. Identifier which complies with relevant normative statements in that section.

A conforming DID document is any concrete expression of the data model described in this specification which complies with the relevant normative statements in § 4. Data Model and § 5. Core Properties. A serialization format for the conforming document is deterministic, bi-directional, and lossless, as described in § 6. Representations.

A conforming producer is any algorithm realized as software and/or hardware that generates conforming DIDs or conforming DID Documents and complies with the relevant normative statements in § 6. Representations.

A conforming consumer is any algorithm realized as software and/or hardware that consumes conforming DIDs or conforming DID documents and complies with the relevant normative statements in § 6. Representations.

A conforming DID resolver is any algorithm realized as software and/or hardware that complies with the relevant normative statements in § 7.1 DID Resolution.

A conforming DID URL dereferencer is any algorithm realized as software and/or hardware that complies with the relevant normative statements in § 7.2 DID URL Dereferencing.

A conforming DID method is any specification that complies with the relevant normative statements in § 8. Methods.

3.1 DID Syntax

The generic DID scheme is a URI scheme conformant with [RFC3986]. The ABNF definition can be found below, which uses the syntax in [RFC5234] and the corresponding definitions for ALPHA and DIGIT. All other rule names not defined in the ABNF below are defined in [RFC3986]. All DIDs MUST conform to the DID Syntax ABNF 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

For requirements on DID methods relating to the DID syntax, see Section § 8.1 Method Syntax.

3.2 DID URL Syntax

A DID URL is a network location identifier for a specific resource. It can be used to retrieve things like representations of DID subjects, verification methods, services, specific parts of a DID document, or other resources.

The following is the ABNF definition using the syntax in [RFC5234]. It builds on the did scheme defined in § 3.1 DID Syntax. The path-abempty, query, and fragment components are defined in [RFC3986]. All DID URLs MUST conform to the DID URL Syntax ABNF Rules. DID methods can further restrict these rules, as described in § 8.1 Method Syntax.

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

did:example:123456/path

did:example:123456?versionId=1

did:example:123#public-key-0

did:example:123#agent

did:example:123?service=agent&relativeRef=/credentials#degree

did:example:123?versionTime=2021-05-10T17:00:00Z

did:example:123?service=files&relativeRef=/resume.pdf

{
  "@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", 
    "controller": "did:example:123456789abcdefghi",
    "publicKeyMultibase": "zH3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
  }, ...],
  "authentication": [

    "#key-1"
  ]
}

4.1 Extensibility

The data model supports two types of extensibility.

1. For maximum interoperability, it is RECOMMENDED that extensions use the W3C DID Specification Registries mechanism [DID-SPEC-REGISTRIES]. The use of this mechanism for new properties or other extensions is the only specified mechanism that ensures that two different representations will be able to work together.
2. Representations MAY define other extensibility mechanisms, including ones that do not require the use of the DID Specification Registries. Such extension mechanisms SHOULD support lossless conversion into any other conformant representation. Extension mechanisms for a representation SHOULD define a mapping of all properties and representation syntax into the data model and its type system.

DID Document properties

Verification Method properties

Service properties

5.1 Identifiers

This section describes the mechanisms by which DID documents include identifiers for DID subjects and DID controllers.

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

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

5.2 Verification Methods

A DID document can express verification methods, such as cryptographic public keys, which can be used to authenticate or authorize interactions with the DID subject or associated parties. For example, a cryptographic public key can be used as a verification method with respect to a digital signature; in such usage, it verifies that the signer could use the associated cryptographic private key. Verification methods might take many parameters. An example of this is a set of five cryptographic keys from which any three are required to contribute to a cryptographic threshold signature.

verificationMethod

The verificationMethod property is OPTIONAL. If present, the value MUST be a set of verification methods, where each verification method is expressed using a map. The verification method map MUST include the id, type, controller, and specific verification material properties that are determined by the value of type and are defined in § 5.2.1 Verification Material. A verification method MAY include additional properties. Verification methods SHOULD be registered in the DID Specification Registries [DID-SPEC-REGISTRIES].

id

The value of the id property for a verification method MUST be a string that conforms to the rules in Section § 3.2 DID URL Syntax.

type

The value of the type property MUST be a string that references exactly one verification method type. In order to maximize global interoperability, the verification method type SHOULD be registered in the DID Specification Registries [DID-SPEC-REGISTRIES].

controller

The value of the controller property MUST be a string that conforms to the rules in § 3.1 DID Syntax.

{
  "@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": ...
  }]
}

{
  "@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", 
    "controller": "did:example:123",
    "publicKeyJwk": {
      "crv": "Ed25519", 
      "x": "VCpo2LMLhn6iWku8MKvSLg2ZAoC-nlOyPVQaO3FxVeQ", 
      "kty": "OKP", 
      "kid": "_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A" 
    }
  }, {
    "id": "did:example:123456789abcdefghi#keys-1",
    "type": "Ed25519VerificationKey2020", 
    "controller": "did:example:pqrstuvwxyz0987654321",
    "publicKeyMultibase": "zH3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
  }],
  
}

{


  "authentication": [
    
    
    "did:example:123456789abcdefghi#keys-1",
    
    {
      "id": "did:example:123456789abcdefghi#keys-2",
      "type": "Ed25519VerificationKey2020", 
      "controller": "did:example:123456789abcdefghi",
      "publicKeyMultibase": "zH3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
    }
  ],


}

5.3 Verification Relationships

A verification relationship expresses the relationship between the DID subject and a verification method.

Different verification relationships enable the associated verification methods to be used for different purposes. It is up to a verifier to ascertain the validity of a verification attempt by checking that the verification method used is contained in the appropriate verification relationship property of the DID Document.

The verification relationship between the DID subject and the verification method is explicit in the DID document. Verification methods that are not associated with a particular verification relationship cannot be used for that verification relationship. For example, a verification method in the value of the authentication property cannot be used to engage in key agreement protocols with the DID subject—the value of the keyAgreement property needs to be used for that.

The DID document does not express revoked keys using a verification relationship. If a referenced verification method is not in the latest DID Document used to dereference it, then that verification method is considered invalid or revoked. Each DID method specification is expected to detail how revocation is performed and tracked.

The following sections define several useful verification relationships. A DID document MAY include any of these, or other properties, to express a specific verification relationship. In order to maximize global interoperability, any such properties used SHOULD be registered in the DID Specification Registries [DID-SPEC-REGISTRIES].

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

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

{
  "@context": "https://www.w3.org/ns/did/v1",
  "id": "did:example:123456789abcdefghi",
  
  "keyAgreement": [
    
    "did:example:123456789abcdefghi#keys-1",
    
    
    
    {
      "id": "did:example:123#zC9ByQ8aJs8vrNXyDhPHHNNMSHPcaSgNpjjsBYpMMjsTdS",
      "type": "X25519KeyAgreementKey2019", 
      "controller": "did:example:123",
      "publicKeyMultibase": "z9hFgmPVfmBZwRvFEyniQDBkz9LmV7gDEqytWyGZLmDXE"
    }
  ],
  
}

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

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

5.4 Services

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

Due to privacy concerns, revealing public information through services, such as social media accounts, personal websites, and email addresses, is discouraged. Further exploration of privacy concerns can be found in § 10.1 Keep Personal Data Private and § 10.6 Service Privacy. The information associated with services is often service specific. For example, the information associated with an encrypted messaging service can express how to initiate the encrypted link before messaging begins.

Services are expressed using the service property, which is described below:

service

The service property is OPTIONAL. If present, the associated value MUST be a set of services, where each service is described by a map. Each service map MUST contain id, type, and serviceEndpoint properties. Each service extension MAY include additional properties and MAY further restrict the properties associated with the extension.

id

The value of the id property MUST be a URI conforming to [RFC3986]. A conforming producer MUST NOT produce multiple service entries with the same id. A conforming consumer MUST produce an error if it detects multiple service entries with the same id.

type

The value of the type property MUST be a string or a set of strings. In order to maximize interoperability, the service type and its associated properties SHOULD be registered in the DID Specification Registries [DID-SPEC-REGISTRIES].

serviceEndpoint

The value of the serviceEndpoint property MUST be a string, a map, or a set composed of one or more strings and/or maps. All string values MUST be valid URIs conforming to [RFC3986] and normalized according to the Normalization and Comparison rules in RFC3986 and to any normalization rules in its applicable URI scheme specification.

For more information regarding privacy and security considerations related to services see § 10.6 Service Privacy, § 10.1 Keep Personal Data Private, § 10.3 DID Document Correlation Risks, and § 9.3 Authentication Service Endpoints.

{
  "service": [{
    "id":"did:example:123#linked-domain",
    "type": "LinkedDomains", 
    "serviceEndpoint": "https://bar.example.com"
  }]
}

6.1 Production and Consumption

In addition to the representations defined in this specification, implementers can use other representations, providing each such representation is properly specified (including rules for interoperable handling of properties not listed in the DID Specification Registries [DID-SPEC-REGISTRIES]). See § 4.1 Extensibility for more information.

The requirements for all representations are as follows:

1. A representation MUST define deterministic production and consumption rules for all data types specified in § 4. Data Model.
2. A representation MUST be uniquely associated with an IANA-registered Media Type.
3. A representation MUST define fragment processing rules for its Media Type that are conformant with the fragment processing rules defined in § Fragment.
4. A representation SHOULD use the lexical representation of data model data types. For example, JSON and JSON-LD use the XML Schema dateTime lexical serialization to represent datetimes. A representation MAY choose to serialize the data model data types using a different lexical serializations as long as the consumption process back into the data model is lossless. For example, some CBOR-based representations express datetime values using integers to represent the number of seconds since the Unix epoch.
5. A representation MAY define representation-specific entries that are stored in a representation-specific entries map for use during the production and consumption process. These entries are used when consuming or producing to aid in ensuring lossless conversion.
6. In order to maximize interoperability, representation specification authors SHOULD register their representation in the DID Specification Registries [DID-SPEC-REGISTRIES].

The requirements for all conforming producers are as follows:

1. A conforming producer MUST take a DID document data model and a representation-specific entries map as input into the production process. The conforming producer MAY accept additional options as input into the production process.
2. A conforming producer MUST serialize all entries in the DID document data model, and the representation-specific entries map, that do not have explicit processing rules for the representation being produced using only the representation's data type processing rules and return the serialization after the production process completes.
3. A conforming producer MUST return the Media Type string associated with the representation after the production process completes.
4. A conforming producer MUST NOT produce non-conforming DIDs or DID documents.

The requirements for all conforming consumers are as follows:

1. A conforming consumer MUST take a representation and Media Type string as input into the consumption process. A conforming consumer MAY accept additional options as input into the consumption process.
2. A conforming consumer MUST determine the representation of a DID document using the Media Type input string.
3. A conforming consumer MUST detect any representation-specific entry across all known representations and place the entry into a representation-specific entries map which is returned after the consumption process completes. A list of all known representation-specific entries is available in the DID Specification Registries [DID-SPEC-REGISTRIES].
4. A conforming consumer MUST add all non-representation-specific entries that do not have explicit processing rules for the representation being consumed to the DID document data model using only the representation's data type processing rules and return the DID document data model after the consumption process completes.
5. A conforming consumer MUST produce errors when consuming non-conforming DIDs or DID documents.

«[
  "id" → "example:123",
  "verificationMethod" → « «[
    "id": "did:example:123#keys-1",
    "controller": "did:example:123",
    "type": "Ed25519VerificationKey2018",
    "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVA"
  ]» »,
  "authentication" → «
    "did:example:123#keys-1"
  »
]»

«[ "@context" → "https://www.w3.org/ns/did/v1" ]»

{
  "id": "did:example:123",
  "verificationMethod": [{
    "id": "did:example:123#keys-1",
    "controller": "did:example:123",
    "type": "Ed25519VerificationKey2018",
    "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVA"
  }],
  "authentication": [
    "did:example:123#keys-1"
  ]
}

{
  "@context": ["https://www.w3.org/ns/did/v1"],
  "id": "did:example:123",
  "verificationMethod": [{
    "id": "did:example:123#keys-1",
    "controller": "did:example:123",
    "type": "Ed25519VerificationKey2018",
    "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVA"
  }],
  "authentication": [
    "did:example:123#keys-1"
  ]
}

6.2 JSON

This section defines the production and consumption rules for the JSON representation.

{
  "id": "did:example:123456789abcdefghi",
  "authentication": [{
    "id": "did:example:123456789abcdefghi#keys-1",
    "type": "Ed25519VerificationKey2018",
    "controller": "did:example:123456789abcdefghi",
    "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
  }]
}

6.3 JSON-LD

JSON-LD [JSON-LD11] is a JSON-based format used to serialize Linked Data. This section defines the production and consumption rules for the JSON-LD representation.

The JSON-LD representation defines the following representation-specific entries:

@context

The JSON-LD Context is either a string or a list containing any combination of strings and/or ordered maps.

{
  "@context": "https://www.w3.org/ns/did/v1",
  ...
}

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://did-method-extension.example/v1"
  ],
  ...
}

7.1 DID Resolution

The DID resolution functions resolve a DID into a DID document by using the "Read" operation of the applicable DID method as described in § 8.2 Method Operations. The details of how this process is accomplished are outside the scope of this specification, but all conforming DID resolvers implement the functions below, which have the following abstract forms:

resolve(did, resolutionOptions) →
   « didResolutionMetadata, didDocument, didDocumentMetadata »

resolveRepresentation(did, resolutionOptions) →
   « didResolutionMetadata, didDocumentStream, didDocumentMetadata »

The resolve function returns the DID document in its abstract form (a map). The resolveRepresentation function returns a byte stream of the DID Document formatted in the corresponding representation.

«[
  "id" → "example:123",
  "verificationMethod" → « «[
    "id": "did:example:123#keys-1",
    "controller": "did:example:123",
    "type": "Ed25519VerificationKey2018",
    "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVA"
  ]» »,
  "authentication" → «
    "did:example:123#keys-1"
  »
]»

«[ "@context" → "https://www.w3.org/ns/did/v1" ]»

{
  "@context": ["https://www.w3.org/ns/did/v1"],
  "id": "did:example:123",
  "verificationMethod": [{
    "id": "did:example:123#keys-1",
    "controller": "did:example:123",
    "type": "Ed25519VerificationKey2018",
    "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVA"
  }],
  "authentication": [
    "did:example:123#keys-1"
  ]
}

{
  "id": "did:example:123",
  "verificationMethod": [{
    "id": "did:example:123#keys-1",
    "controller": "did:example:123",
    "type": "Ed25519VerificationKey2018",
    "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVA"
  }],
  "authentication": [
    "did:example:123#keys-1"
  ]
}

The input variables of the resolve and resolveRepresentation functions are as follows:

did

This is the DID to resolve. This input is REQUIRED and the value MUST be a conformant DID as defined in § 3.1 DID Syntax.

resolutionOptions

A metadata structure containing properties defined in § 7.1.1 DID Resolution Options. This input is REQUIRED, but the structure MAY be empty.

These functions each return multiple values, and no limitations are placed on how these values are returned together. The return values of resolve are didResolutionMetadata, didDocument, and didDocumentMetadata. The return values of resolveRepresentation are didResolutionMetadata, didDocumentStream, and didDocumentMetadata. These values are described below:

didResolutionMetadata

A metadata structure consisting of values relating to the results of the DID resolution process which typically changes between invocations of the resolve and resolveRepresentation functions, as it represents data about the resolution process itself. This structure is REQUIRED, and in the case of an error in the resolution process, this MUST NOT be empty. This metadata is defined by § 7.1.2 DID Resolution Metadata. If resolveRepresentation was called, this structure MUST contain a contentType property containing the Media Type of the representation found in the didDocumentStream. If the resolution is not successful, this structure MUST contain an error property describing the error.

didDocument

If the resolution is successful, and if the resolve function was called, this MUST be a DID document abstract data model (a map) as described in § 4. Data Model that is capable of being transformed into a conforming DID Document (representation), using the production rules specified by the representation. The value of id in the resolved DID document MUST match the DID that was resolved. If the resolution is unsuccessful, this value MUST be empty.

didDocumentStream

If the resolution is successful, and if the resolveRepresentation function was called, this MUST be a byte stream of the resolved DID document in one of the conformant representations. The byte stream might then be parsed by the caller of the resolveRepresentation function into a data model, which can in turn be validated and processed. If the resolution is unsuccessful, this value MUST be an empty stream.

didDocumentMetadata

If the resolution is successful, this MUST be a metadata structure. This structure contains metadata about the DID document contained in the didDocument property. This metadata typically does not change between invocations of the resolve and resolveRepresentation functions unless the DID document changes, as it represents metadata about the DID document. If the resolution is unsuccessful, this output MUST be an empty metadata structure. Properties defined by this specification are in § 7.1.3 DID Document Metadata.

Conforming DID resolver implementations do not alter the signature of these functions in any way. DID resolver implementations might map the resolve and resolveRepresentation functions to a method-specific internal function to perform the actual DID resolution process. DID resolver implementations might implement and expose additional functions with different signatures in addition to the resolve and resolveRepresentation functions specified here.

7.2 DID URL Dereferencing

The DID URL dereferencing function dereferences a DID URL into a resource with contents depending on the DID URL's components, including the DID method, method-specific identifier, path, query, and fragment. This process depends on DID resolution of the DID contained in the DID URL. DID URL dereferencing might involve multiple steps (e.g., when the DID URL being dereferenced includes a fragment), and the function is defined to return the final resource after all steps are completed. The details of how this process is accomplished are outside the scope of this specification. The following figure depicts the relationship described above.

All conforming DID resolvers implement the following function which has the following abstract form:

dereference(didUrl, dereferenceOptions) →
   « dereferencingMetadata, contentStream, contentMetadata »

The input variables of the dereference function are as follows:

didUrl

A conformant DID URL as a single string. This is the DID URL to dereference. To dereference a DID fragment, the complete DID URL including the DID fragment MUST be used. This input is REQUIRED.

Note: DID URL dereferencer patterns

While it is valid for any didUrl to be passed to a DID URL dereferencer, implementers are expected to refer to [DID-RESOLUTION] to further understand common patterns for how a DID URL is expected to be dereferenced.

dereferencingOptions

A metadata structure consisting of input options to the dereference function in addition to the didUrl itself. Properties defined by this specification are in § 7.2.1 DID URL Dereferencing Options. This input is REQUIRED, but the structure MAY be empty.

This function returns multiple values, and no limitations are placed on how these values are returned together. The return values of the dereference include dereferencingMetadata, contentStream, and contentMetadata:

dereferencingMetadata

A metadata structure consisting of values relating to the results of the DID URL dereferencing process. This structure is REQUIRED, and in the case of an error in the dereferencing process, this MUST NOT be empty. Properties defined by this specification are in § 7.2.2 DID URL Dereferencing Metadata. If the dereferencing is not successful, this structure MUST contain an error property describing the error.

contentStream

If the dereferencing function was called and successful, this MUST contain a resource corresponding to the DID URL. The contentStream MAY be a resource such as a DID document that is serializable in one of the conformant representations, a Verification Method, a service, or any other resource format that can be identified via a Media Type and obtained through the resolution process. If the dereferencing is unsuccessful, this value MUST be empty.

contentMetadata

If the dereferencing is successful, this MUST be a metadata structure, but the structure MAY be empty. This structure contains metadata about the contentStream. If the contentStream is a DID document, this MUST be a didDocumentMetadata structure as described in DID Resolution. If the dereferencing is unsuccessful, this output MUST be an empty metadata structure.

Conforming DID URL dereferencing implementations do not alter the signature of these functions in any way. DID URL dereferencing implementations might map the dereference function to a method-specific internal function to perform the actual DID URL dereferencing process. DID URL dereferencing implementations might implement and expose additional functions with different signatures in addition to the dereference function specified here.

7.3 Metadata Structure

Input and output metadata is often involved during the DID Resolution, DID URL dereferencing, and other DID-related processes. The structure used to communicate this metadata MUST be a map of properties. Each property name MUST be a string. Each property value MUST be a string, map, list, set, boolean, or null. The values within any complex data structures such as maps and lists MUST be one of these data types as well. All metadata property definitions registered in the DID Specification Registries [DID-SPEC-REGISTRIES] MUST define the value type, including any additional formats or restrictions to that value (for example, a string formatted as a date or as a decimal integer). It is RECOMMENDED that property definitions use strings for values. The entire metadata structure MUST be serializable according to the JSON serialization rules in the [INFRA] specification. Implementations MAY serialize the metadata structure to other data formats.

All implementations of functions that use metadata structures as either input or output are able to fully represent all data types described here in a deterministic fashion. As inputs and outputs using metadata structures are defined in terms of data types and not their serialization, the method for representation is internal to the implementation of the function and is out of scope of this specification.

The following example demonstrates a JSON-encoded metadata structure that might be used as DID resolution input metadata.

This example corresponds to a metadata structure of the following format:

The next example demonstrates a JSON-encoded metadata structure that might be used as DID resolution metadata if a DID was not found.

This example corresponds to a metadata structure of the following format:

The next example demonstrates a JSON-encoded metadata structure that might be used as DID document metadata to describe timestamps associated with the DID document.

This example corresponds to a metadata structure of the following format:

8.1 Method Syntax

The requirements for all DID method specifications when defining the method-specific DID Syntax are as follows:

1. A DID method specification MUST define exactly one method-specific DID scheme that is identified by exactly one method name as specified by the method-name rule in § 3.1 DID Syntax.
2. The DID method specification MUST specify how to generate the method-specific-id component of a DID.
3. The DID method specification MUST define sensitivity and normalization of the value of the method-specific-id.
4. The method-specific-id value MUST be unique within a DID method. The method-specific-id value itself might be globally unique.
5. Any DID generated by a DID method MUST be globally unique.
6. To reduce the chances of method-name conflicts, a DID method specification SHOULD be registered in the DID Specification Registries [DID-SPEC-REGISTRIES].
7. A DID method MAY define multiple method-specific-id formats.
8. The method-specific-id format MAY include colons. The use of colons MUST comply syntactically with the method-specific-id ABNF rule.
9. A DID method specification MAY specify ABNF rules for DID paths that are more restrictive than the generic rules in § Path.
10. A DID method specification MAY specify ABNF rules for DID queries that are more restrictive than the generic rules in this section.
11. A DID method specification MAY specify ABNF rules for DID fragments that are more restrictive than the generic rules in this section.

8.2 Method Operations

The requirements for all DID method specifications when defining the method operations are as follows:

1. A DID method specification MUST define how authorization is performed to execute all operations, including any necessary cryptographic processes.
2. A DID method specification MUST specify how a DID controller creates a DID and its associated DID document.
3. A DID method specification MUST specify how a DID resolver uses a DID to resolve a DID document, including how the DID resolver can verify the authenticity of the response.
4. A DID method specification MUST specify what constitutes an update to a DID document and how a DID controller can update a DID document or state that updates are not possible.
5. The DID method specification MUST specify how a DID controller can deactivate a DID or state that deactivation is not possible.

The authority of a party that is performing authorization to carry out the operations is specific to a DID method. For example, a DID method might —

• make use of the controller property.
• use the verification methods listed under authentication.
• use other constructs in the DID Document such as the verification method specified via the capabilityInvocation verification relationship.
• not use the DID document for this decision at all, and depend on an out-of-band mechanism, instead.

8.3 Security Requirements

The requirements for all DID method specifications when authoring the Security Considerations section are as follows:

1. A DID method specifications MUST follow all guidelines and normative language provided in RFC3552: Writing Security Considerations Sections for the DID operations defined in the DID method specification.
2. The Security Considerations section MUST document the following forms of attack for the DID operations defined in the DID method specification: eavesdropping, replay, message insertion, deletion, modification, denial of service, amplification, and man-in-the-middle. Other known forms of attack SHOULD also be documented.
3. The Security Considerations section MUST discuss residual risks, such as the risks from compromise in a related protocol, incorrect implementation, or cipher after threat mitigation was deployed.
4. The Security Considerations section MUST provide integrity protection and update authentication for all operations required by Section § 8.2 Method Operations.
5. If authentication is involved, particularly user-host authentication, the security characteristics of the authentication method MUST be clearly documented.
6. The Security Considerations section MUST discuss the policy mechanism by which DIDs are proven to be uniquely assigned.
7. Method-specific endpoint authentication MUST be discussed. Where DID methods make use of DLTs with varying network topology, sometimes offered as light node or thin client implementations to reduce required computing resources, the security assumptions of the topology available to implementations of the DID method MUST be discussed.
8. If a protocol incorporates cryptographic protection mechanisms, the DID method specification MUST clearly indicate which portions of the data are protected and by what protections, and it SHOULD give an indication of the sorts of attacks to which the cryptographic protection is susceptible. Some examples are integrity only, confidentiality, and endpoint authentication.
9. Data which is to be held secret (keying material, random seeds, and so on) SHOULD be clearly labeled.
10. DID method specifications SHOULD explain and specify the implementation of signatures on DID documents, if applicable.
11. Where DID methods use peer-to-peer computing resources, such as with all known DLTs, the expected burdens of those resources SHOULD be discussed in relation to denial of service.
12. DID methods that introduce new authentication service types, as described in § 5.4 Services, SHOULD consider the security requirements of the supported authentication protocol.

8.4 Privacy Requirements

The requirements for all DID method specifications when authoring the Privacy Considerations section are:

1. The DID method specification's Privacy Considerations section MUST discuss any subsection of Section 5 of [RFC6973] that could apply in a method-specific manner. The subsections to consider are: surveillance, stored data compromise, unsolicited traffic, misattribution, correlation, identification, secondary use, disclosure, and exclusion.

9.1 Choosing DID Resolvers

The DID Specification Registries [DID-SPEC-REGISTRIES] contains an informative list of DID method names and their corresponding DID method specifications. Implementers need to bear in mind that there is no central authority to mandate which DID method specification is to be used with any specific DID method name. If there is doubt on whether or not a specific DID resolver implements a DID method correctly, the DID Specification Registries can be used to look up the registered specification and make an informed decision regarding which DID resolver implementation to use.

9.2 Proving Control and Binding

Binding an entity in the digital world or the physical world to a DID, to a DID document, or to cryptographic material requires, the use of security protocols contemplated by this specification. The following sections describe some possible scenarios and how an entity therein might prove control over a DID or a DID document for the purposes of authentication or authorization.

9.3 Authentication Service Endpoints

If a DID document publishes a service intended for authentication or authorization of the DID subject (see Section § 5.4 Services), it is the responsibility of the service endpoint provider, subject, or requesting party to comply with the requirements of the authentication protocols supported at that service endpoint.

9.4 Non-Repudiation

Non-repudiation of DIDs and DID document updates is supported if:

• The verifiable data registry supports verifiable timestamps. See § 7.1.3 DID Document Metadata for further information on useful timestamps that can be used during the DID resolution process.
• The subject is monitoring for unauthorized updates as elaborated upon in § 9.5 Notification of DID Document Changes.
• The subject has had adequate opportunity to revert malicious updates according to the authorization mechanism for the DID method.

9.5 Notification of DID Document Changes

One mitigation against unauthorized changes to a DID document is monitoring and actively notifying the DID subject when there are changes. This is analogous to helping prevent account takeover on conventional username/password accounts by sending password reset notifications to the email addresses on file.

In the case of a DID, there is no intermediary registrar or account provider to generate such notifications. However, if the verifiable data registry on which the DID is registered directly supports change notifications, a subscription service can be offered to DID controllers. Notifications could be sent directly to the relevant service endpoints listed in an existing DID.

If a DID controller chooses to rely on a third-party monitoring service (other than the verifiable data registry itself), this introduces another vector of attack.

9.6 Key and Signature Expiration

In a decentralized identifier architecture, there might not be centralized authorities to enforce cryptographic material or cryptographic digital signature expiration policies. Therefore, it is with supporting software such as DID resolvers and verification libraries that requesting parties validate that cryptographic material were not expired at the time they were used. Requesting parties might employ their own expiration policies in addition to inputs into their verification processes. For example, some requesting parties might accept authentications from five minutes in the past, while others with access to high precision time sources might require authentications to be time stamped within the last 500 milliseconds.

There are some requesting parties that have legitimate needs to extend the use of already-expired cryptographic material, such as verifying legacy cryptographic digital signatures. In these scenarios, a requesting party might instruct their verification software to ignore cryptographic key material expiration or determine if the cryptographic key material was expired at the time it was used.

9.7 Verification Method Rotation

Rotation is a management process that enables the secret cryptographic material associated with an existing verification method to be deactivated or destroyed once a new verification method has been added to the DID document. Going forward, any new proofs that a controller would have generated using the old secret cryptographic material can now instead be generated using the new cryptographic material and can be verified using the new verification method.

Rotation is a useful mechanism for protecting against verification method compromise, since frequent rotation of a verification method by the controller reduces the value of a single compromised verification method to an attacker. Performing revocation immediately after rotation is useful for verification methods that a controller designates for short-lived verifications, such as those involved in encrypting messages and authentication.

The following considerations might be of use when contemplating the use of verification method rotation:

• Verification method rotation is a proactive security measure.
• It is generally considered a best practice to perform verification method rotation on a regular basis.
• Higher security environments tend to employ more frequent verification method rotation.
• Verification method rotation manifests only as changes to the current or latest version of a DID document.
• When a verification method has been active for a long time, or used for many operations, a controller might wish to perform a rotation.
• Frequent rotation of a verification method might be frustrating for parties that are forced to continuously renew or refresh associated credentials.
• Proofs or signatures that rely on verification methods that are not present in the latest version of a DID document are not impacted by rotation. In these cases, verification software might require additional information, such as when a particular verification method was expected to be valid as well as access to a verifiable data registry containing a historical record, to determine the validity of the proof or signature. This option might not be available in all DID methods.
• The section on DID method operations specifies the DID operations to be supported by a DID method specification, including update which is expected to be used to perform a verification method rotation.
• A controller performs a rotation when they add a new verification method that is meant to replace an existing verification method after some time.
• Not all DID methods support verification method rotation.

9.8 Verification Method Revocation

Revocation is a management process that enables the secret cryptographic material associated with an existing verification method to be deactivated such that it ceases to be a valid form of creating new proofs of digital signatures.

Revocation is a useful mechanism for reacting to a verification method compromise. Performing revocation immediately after rotation is useful for verification methods that a controller designates for short-lived verifications, such as those involved in encrypting messages and authentication.

Compromise of the secrets associated with a verification method allows the attacker to use them according to the verification relationship expressed by controller in the DID document, for example, for authentication. The attacker's use of the secrets might be indistinguishable from the legitimate controller's use starting from the time the verification method was registered, to the time it was revoked.

The following considerations might be of use when contemplating the use of verification method revocation:

• Verification method revocation is a reactive security measure.
• It is considered a best practice to support key revocation.
• A controller is expected to immediately revoke any verification method that is known to be compromised.
• Verification method revocation can only be embodied in changes to the latest version of a DID Document; it cannot retroactively adjust previous versions.
• As described in § 5.2.1 Verification Material, absence of a verification method is the only form of revocation that applies to all DID Methods that support revocation.
• If a verification method is no longer exclusively accessible to the controller or parties trusted to act on behalf of the controller, it is expected to be revoked immediately to reduce the risk of compromises such as masquerading, theft, and fraud.
• Revocation is expected to be understood as a controller expressing that proofs or signatures associated with a revoked verification method created after its revocation should be treated as invalid. It could also imply a concern that existing proofs or signatures might have been created by an attacker, but this is not necessarily the case. Verifiers, however, might still choose to accept or reject any such proofs or signatures at their own discretion.
• The section on DID method operations specifies the DID operations to be supported by a DID method specification, including update and deactivate, which might be used to remove a verification method from a DID document.
• Not all DID methods support verification method revocation.
• Even if a verification method is present in a DID document, additional information, such as a public key revocation certificate, or an external allow or deny list, could be used to determine whether a verification method has been revoked.
• The day-to-day operation of any software relying on a compromised verification method, such as an individual's operating system, antivirus, or endpoint protection software, could be impacted when the verification method is publicly revoked.

9.9 DID Recovery

Recovery is a reactive security measure whereby a controller that has lost the ability to perform DID operations, such as through the loss of a device, is able to regain the ability to perform DID operations.

The following considerations might be of use when contemplating the use of DID recovery:

• Performing recovery proactively on an infrequent but regular basis, can help to ensure that control has not been lost.
• It is considered a best practice to never reuse cryptographic material associated with recovery for any other purposes.
• Recovery is commonly performed in conjunction with verification method rotation and verification method revocation.
• Recovery is advised when a controller or services trusted to act on their behalf no longer have the exclusive ability to perform DID operations as described in § 8.2 Method Operations.
• DID method specifications might choose to enable support for a quorum of trusted parties to facilitate recovery. Some of the facilities to do so are suggested in § 5.1.2 DID Controller.
• Not all DID method specifications will recognize control from DIDs registered using other DID methods and they might restrict third-party control to DIDs that use the same method.
• Access control and recovery in a DID method specification can also include a time lock feature to protect against key compromise by maintaining a second track of control for recovery.
• There are currently no common recovery mechanisms that apply to all DID methods.

9.10 The Role of Human-Friendly Identifiers

DIDs achieve global uniqueness without the need for a central registration authority. This comes at the cost of human memorability. Algorithms capable of generating globally unambiguous identifiers produce random strings of characters that have no human meaning. This trade-off is often referred to as Zooko's Triangle.

There are use cases where it is desirable to discover a DID when starting from a human-friendly identifier. For example, a natural language name, a domain name, or a conventional address for a DID controller, such as a mobile telephone number, email address, social media username, or blog URL. However, the problem of mapping human-friendly identifiers to DIDs, and doing so in a way that can be verified and trusted, is outside the scope of this specification.

Solutions to this problem are defined in separate specifications, such as [DNS-DID], that reference this specification. It is strongly recommended that such specifications carefully consider the:

• Numerous security attacks based on deceiving users about the true human-friendly identifier for a target entity.
• Privacy consequences of using human-friendly identifiers that are inherently correlatable, especially if they are globally unique.

9.11 DIDs as Enhanced URNs

If desired by a DID controller, a DID or a DID URL is capable of acting as persistent, location-independent resource identifier. These sorts of identifiers are classified as Uniform Resource Names (URNs) and are defined in [RFC8141]. DIDs are an enhanced form of URN that provide a cryptographically secure, location-independent identifier for a digital resource, while also providing metadata that enables retrieval. Due to the indirection between the DID document and the DID itself, the DID controller can adjust the actual location of the resource — or even provide the resource directly — without adjusting the DID. DIDs of this type can definitively verify that the resource retrieved is, in fact, the resource identified.

A DID controller who intends to use a DID for this purpose is advised to follow the security considerations in [RFC8141]. In particular:

• The DID controller is expected to choose a DID method that supports the controller's requirements for persistence. The Decentralized Characteristics Rubric [DID-RUBRIC] is one tool available to help implementers decide upon the most suitable DID method.
• The DID controller is expected to publish its operational policies so requesting parties can determine the degree to which they can rely on the persistence of a DID controlled by that DID controller. In the absence of such policies, requesting parties are not expected to make any assumption about whether a DID is a persistent identifier for the same DID subject.

9.12 Immutability

Many cybersecurity abuses hinge on exploiting gaps between reality and the assumptions of rational, good-faith actors. Immutability of DID documents can provide some security benefits. Individual DID methods ought to consider constraints that would eliminate behaviors or semantics they do not need. The more locked down a DID method is, while providing the same set of features, the less it can be manipulated by malicious actors.

As an example, consider that a single edit to a DID document can change anything except the root id property of the document. But is it actually desirable for a service to change its type after it is defined? Or for a key to change its value? Or would it be better to require a new id when certain fundamental properties of an object change? Malicious takeovers of a website often aim for an outcome where the site keeps its host name identifier, but is subtly changed underneath. If certain properties of the site, such as the ASN associated with its IP address, were required by the specification to be immutable, anomaly detection would be easier, and attacks would be much harder and more expensive to carry out.

For DID methods tied to a global source of truth, a direct, just-in-time lookup of the latest version of a DID document is always possible. However, it seems likely that layers of cache might eventually sit between a DID resolver and that source of truth. If they do, believing the attributes of an object in the DID document to have a given state when they are actually subtly different might invite exploits. This is particularly true if some lookups are of a full DID document, and others are of partial data where the larger context is assumed.

9.13 Encrypted Data in DID Documents

Encryption algorithms have been known to fail due to advances in cryptography and computing power. Implementers are advised to assume that any encrypted data placed in a DID document might eventually be made available in clear text to the same audience to which the encrypted data is available. This is particularly pertinent if the DID document is public.

Encrypting all or parts of a DID document is not an appropriate means to protect data in the long term. Similarly, placing encrypted data in a DID document is not an appropriate means to protect personal data.

Given the caveats above, if encrypted data is included in a DID document, implementers are advised to not associate any correlatable information that could be used to infer a relationship between the encrypted data and an associated party. Examples of correlatable information include public keys of a receiving party, identifiers to digital assets known to be under the control of a receiving party, or human readable descriptions of a receiving party.

9.14 Equivalence Properties

Given the equivalentId and canonicalId properties are generated by DID methods themselves, the same security and accuracy guarantees that apply to the resolved DID present in the id field of a DID document also apply to these properties. The alsoKnownAs property is not guaranteed to be an accurate statement of equivalence, and should not be relied upon without performing validation steps beyond the resolution of the DID document.

The equivalentId and canonicalId properties express equivalence assertions to variants of a single DID produced by the same DID method and can be trusted to the extent the requesting party trusts the DID method and a conforming producer and resolver.

The alsoKnownAs property permits an equivalence assertion to URIs that are not governed by the same DID method and cannot be trusted without performing verification steps outside of the governing DID method. See additional guidance in § 5.1.3 Also Known As.

As with any other security-related properties in the DID document, parties relying on any equivalence statement in a DID document should guard against the values of these properties being substituted by an attacker after the proper verification has been performed. Any write access to a DID document stored in memory or disk after verification has been performed is an attack vector that might circumvent verification unless the DID document is re-verified.

9.15 Content Integrity Protection

DID documents which include links to external machine-readable content such as images, web pages, or schemas are vulnerable to tampering. It is strongly advised that external links are integrity protected using solutions such as a hashlink [HASHLINK]. External links are to be avoided if they cannot be integrity protected and the DID document's integrity is dependent on the external link.

One example of an external link where the integrity of the DID document itself could be affected is the JSON-LD Context [JSON-LD11]. To protect against compromise, DID document consumers are advised to cache local static copies of JSON-LD contexts and/or verify the integrity of external contexts against a cryptographic hash that is known to be associated with a safe version of the external JSON-LD Context.

9.16 Persistence

DIDs are designed to be persistent such that a controller need not rely upon a single trusted third party or administrator to maintain their identifiers. In an ideal case, no administrator can take control away from the controller, nor can an administrator prevent their identifiers' use for any particular purpose such as authentication, authorization, and attestation. No third party can act on behalf of a controller to remove or render inoperable an entity's identifier without the controller's consent.

However, it is important to note that in all DID methods that enable cryptographic proof-of-control, the means of proving control can always be transferred to another party by transferring the secret cryptographic material. Therefore, it is vital that systems relying on the persistence of an identifier over time regularly check to ensure that the identifier is, in fact, still under the control of the intended party.

Unfortunately, it is impossible to determine from the cryptography alone whether or not the secret cryptographic material associated with a given verification method has been compromised. It might well be that the expected controller still has access to the secret cryptographic material — and as such can execute a proof-of-control as part of a verification process — while at the same time, a bad actor also has access to those same keys, or to a copy thereof.

As such, cryptographic proof-of-control is expected to only be used as one factor in evaluating the level of identity assurance required for high-stakes scenarios. DID-based authentication provides much greater assurance than a username and password, thanks to the ability to determine control over a cryptographic secret without transmitting that secret between systems. However, it is not infallible. Scenarios that involve sensitive, high value, or life-critical operations are expected to use additional factors as appropriate.

In addition to potential ambiguity from use by different controllers, it is impossible to guarantee, in general, that a given DID is being used in reference to the same subject at any given point in time. It is technically possible for the controller to reuse a DID for different subjects and, more subtly, for the precise definition of the subject to either change over time or be misunderstood.

For example, consider a DID used for a sole proprietorship, receiving various credentials used for financial transactions. To the controller, that identifier referred to the business. As the business grows, it eventually gets incorporated as a Limited Liability Company. The controller continues using that same DID, because to them the DID refers to the business. However, to the state, the tax authority, and the local municipality, the DID no longer refers to the same entity. Whether or not the subtle shift in meaning matters to a credit provider or supplier is necessarily up to them to decide. In many cases, as long as the bills get paid and collections can be enforced, the shift is immaterial.

Due to these potential ambiguities, DIDs are to be considered valid contextually rather than absolutely. Their persistence does not imply that they refer to the exact same subject, nor that they are under the control of the same controller. Instead, one needs to understand the context in which the DID was created, how it is used, and consider the likely shifts in their meaning, and adopt procedures and policies to address both potential and inevitable semantic drift.

9.17 Level of Assurance

Additional information about the security context of authentication events is often required for compliance reasons, especially in regulated areas such as the financial and public sectors. This information is often referred to as a Level of Assurance (LOA). Examples include the protection of secret cryptographic material, the identity proofing process, and the form-factor of the authenticator.

Payment services (PSD 2) and eIDAS introduce such requirements to the security context. Level of assurance frameworks are classified and defined by regulations and standards such as eIDAS, NIST 800-63-3 and ISO/IEC 29115:2013, including their requirements for the security context, and making recommendations on how to achieve them. This might include strong user authentication where FIDO2/WebAuthn can fulfill the requirement.

Some regulated scenarios require the implementation of a specific level of assurance. Since verification relationships such as assertionMethod and authentication might be used in some of these situations, information about the applied security context might need to be expressed and provided to a verifier. Whether and how to encode this information in the DID document data model is out of scope for this specification. Interested readers might note that 1) the information could be transmitted using Verifiable Credentials [VC-DATA-MODEL], and 2) the DID document data model can be extended to incorporate this information as described in § 4.1 Extensibility, and where § 10. Privacy Considerations is applicable for such extensions.

10.1 Keep Personal Data Private

If a DID method specification is written for a public-facing verifiable data registry where corresponding DIDs and DID documents might be made publicly available, it is critical that those DID documents contain no personal data. Personal data can instead be transmitted through other means such as 1) Verifiable Credentials [VC-DATA-MODEL], or 2) service endpoints under control of the DID subject or DID controller.

Due diligence is expected to be taken around the use of URLs in service endpoints to prevent leakage of personal data or correlation within a URL of a service endpoint. For example, a URL that contains a username is dangerous to include in a DID Document because the username is likely to be human-meaningful in a way that can reveal information that the DID subject did not consent to sharing. With the privacy architecture suggested by this specification, personal data can be exchanged on a private, peer-to-peer basis using communication channels identified and secured by verification methods in DID documents. This also enables DID subjects and requesting parties to implement the GDPR right to be forgotten, because no personal data is written to an immutable distributed ledger.

10.2 DID Correlation Risks

Like any type of globally unambiguous identifier, DIDs might be used for correlation. DID controllers can mitigate this privacy risk by using pairwise DIDs that are unique to each relationship; in effect, each DID acts as a pseudonym. A pairwise DID need only be shared with more than one party when correlation is explicitly desired. If pairwise DIDs are the default, then the only need to publish a DID openly, or to share it with multiple parties, is when the DID controller(s) and/or DID subject explicitly desires public identification and correlation.

10.3 DID Document Correlation Risks

The anti-correlation protections of pairwise DIDs are easily defeated if the data in the corresponding DID documents can be correlated. For example, using identical verification methods or bespoke service endpoints in multiple DID documents can provide as much correlation information as using the same DID. Therefore, the DID document for a pairwise DID also needs to use pairwise unique information, such as ensuring that verification methods are unique to the pairwise relationship.

It might seem natural to also use pairwise unique service endpoints in the DID document for a pairwise DID. However, unique endpoints allow all traffic between two DIDs to be isolated perfectly into unique buckets, where timing correlation and similar analysis is easy. Therefore, a better strategy for endpoint privacy might be to share an endpoint among a large number of DIDs controlled by many different subjects (see § 10.5 Herd Privacy).

10.4 DID Subject Classification

It is dangerous to add properties to the DID document that can be used to indicate, explicitly or through inference, what type or nature of thing the DID subject is, particularly if the DID subject is a person.

Not only do such properties potentially result in personal data (see § 10.1 Keep Personal Data Private) or correlatable data (see §  10.2 DID Correlation Risks and § 10.3 DID Document Correlation Risks) being present in the DID document, but they can be used for grouping particular DIDs in such a way that they are included in or excluded from certain operations or functionalities.

Including type information in a DID Document can result in personal privacy harms even for DID Subjects that are non-person entities, such as IoT devices. The aggregation of such information around a DID Controller could serve as a form of digital fingerprint and this is best avoided.

To minimize these risks, all properties in a DID document ought to be for expressing cryptographic material, endpoints, or verification methods related to using the DID.

10.5 Herd Privacy

When a DID subject is indistinguishable from others in the herd, privacy is available. When the act of engaging privately with another party is by itself a recognizable flag, privacy is greatly diminished.

DIDs and DID methods need to work to improve herd privacy, particularly for those who legitimately need it most. Choose technologies and human interfaces that default to preserving anonymity and pseudonymity. To reduce digital fingerprints, share common settings across requesting party implementations, keep negotiated options to a minimum on wire protocols, use encrypted transport layers, and pad messages to standard lengths.

10.6 Service Privacy

The ability for a controller to optionally express at least one service endpoint in the DID document increases their control and agency. Each additional endpoint in the DID document adds privacy risk either due to correlation, such as across endpoint descriptions, or because the services are not protected by an authorization mechanism, or both.

DID documents are often public and, since they are standardized, will be stored and indexed efficiently by their very standards-based nature. This risk is worse if DID documents are published to immutable verifiable data registries. Access to a history of the DID documents referenced by a DID represents a form of traffic analysis made more efficient through the use of standards.

The degree of additional privacy risk caused by using multiple service endpoints in one DID document can be difficult to estimate. Privacy harms are typically unintended consequences. DIDs can refer to documents, services, schemas, and other things that might be associated with individual people, households, clubs, and employers — and correlation of their service endpoints could become a powerful surveillance and inference tool. An example of this potential harm can be seen when multiple common country-level top level domains such as https://example.co.uk might be used to infer the approximate location of the DID subject with a greater degree of probability.

A.1 DID Documents

This section is non-normative.

See Verification Method Types [DID-SPEC-REGISTRIES] for optional extensions and other verification method types.

  {
    "@context": [
      "https://www.w3.org/ns/did/v1",
      "https://w3id.org/security/suites/ed25519-2020/v1"
    ],
    "id": "did:example:123",
    "authentication": [
      {
        "id": "did:example:123#z6MkecaLyHuYWkayBDLw5ihndj3T1m6zKTGqau3A51G7RBf3",
        "type": "Ed25519VerificationKey2020", // external (property value)
        "controller": "did:example:123",
        "publicKeyMultibase": "zAKJP3f7BD6W4iWEQ9jwndVTCBq8ua2Utt8EEjJ6Vxsf"
      }
    ],
    "capabilityInvocation": [
      {
        "id": "did:example:123#z6MkhdmzFu659ZJ4XKj31vtEDmjvsi5yDZG5L7Caz63oP39k",
        "type": "Ed25519VerificationKey2020", // external (property value)
        "controller": "did:example:123",
        "publicKeyMultibase": "z4BWwfeqdp1obQptLLMvPNgBw48p7og1ie6Hf9p5nTpNN"
      }
    ],
    "capabilityDelegation": [
      {
        "id": "did:example:123#z6Mkw94ByR26zMSkNdCUi6FNRsWnc2DFEeDXyBGJ5KTzSWyi",
        "type": "Ed25519VerificationKey2020", // external (property value)
        "controller": "did:example:123",
        "publicKeyMultibase": "zHgo9PAmfeoxHG8Mn2XHXamxnnSwPpkyBHAMNF3VyXJCL"
      }
    ],
    "assertionMethod": [
      {
        "id": "did:example:123#z6MkiukuAuQAE8ozxvmahnQGzApvtW7KT5XXKfojjwbdEomY",
        "type": "Ed25519VerificationKey2020", // external (property value)
        "controller": "did:example:123",
        "publicKeyMultibase": "z5TVraf9itbKXrRvt2DSS95Gw4vqU3CHAdetoufdcKazA"
      }
    ]
}

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/jws-2020/v1"
  ],
  "verificationMethod": [
    {
      "id": "did:example:123#key-0",
      "type": "JsonWebKey2020",
      "controller": "did:example:123",
      "publicKeyJwk": {
        "kty": "OKP", // external (property name)
        "crv": "Ed25519", // external (property name)
        "x": "VCpo2LMLhn6iWku8MKvSLg2ZAoC-nlOyPVQaO3FxVeQ" // external (property name)
      }
    },
    {
      "id": "did:example:123#key-1",
      "type": "JsonWebKey2020",
      "controller": "did:example:123",
      "publicKeyJwk": {
        "kty": "OKP", // external (property name)
        "crv": "X25519", // external (property name)
        "x": "pE_mG098rdQjY3MKK2D5SUQ6ZOEW3a6Z6T7Z4SgnzCE" // external (property name)
      }
    },
    {
      "id": "did:example:123#key-2",
      "type": "JsonWebKey2020",
      "controller": "did:example:123",
      "publicKeyJwk": {
        "kty": "EC", // external (property name)
        "crv": "secp256k1", // external (property name)
        "x": "Z4Y3NNOxv0J6tCgqOBFnHnaZhJF6LdulT7z8A-2D5_8", // external (property name)
        "y": "i5a2NtJoUKXkLm6q8nOEu9WOkso1Ag6FTUT6k_LMnGk" // external (property name)
      }
    },
    {
      "id": "did:example:123#key-3",
      "type": "JsonWebKey2020",
      "controller": "did:example:123",
      "publicKeyJwk": {
        "kty": "EC", // external (property name)
        "crv": "secp256k1", // external (property name)
        "x": "U1V4TVZVMUpUa0ZVU1NBcU9CRm5IbmFaaEpGNkxkdWx", // external (property name)
        "y": "i5a2NtJoUKXkLm6q8nOEu9WOkso1Ag6FTUT6k_LMnGk" // external (property name)
      }
    },
    {
      "id": "did:example:123#key-4",
      "type": "JsonWebKey2020",
      "controller": "did:example:123",
      "publicKeyJwk": {
        "kty": "EC", // external (property name)
        "crv": "P-256", // external (property name)
        "x": "Ums5WVgwRkRTVVFnU3k5c2xvZllMbEcwM3NPRW91ZzN", // external (property name)
        "y": "nDQW6XZ7b_u2Sy9slofYLlG03sOEoug3I0aAPQ0exs4" // external (property name)
      }
    },
    {
      "id": "did:example:123#key-5",
      "type": "JsonWebKey2020",
      "controller": "did:example:123",
      "publicKeyJwk": {
        "kty": "EC", // external (property name)
        "crv": "P-384", // external (property name)
        "x": "VUZKSlUwMGdpSXplekRwODhzX2N4U1BYdHVYWUZsaXVDR25kZ1U0UXA4bDkxeHpE", // external (property name)
        "y": "jq4QoAHKiIzezDp88s_cxSPXtuXYFliuCGndgU4Qp8l91xzD1spCmFIzQgVjqvcP" // external (property name)
      }
    },
    {
      "id": "did:example:123#key-6",
      "type": "JsonWebKey2020",
      "controller": "did:example:123",
      "publicKeyJwk": {
        "kty": "EC", // external (property name)
        "crv": "P-521", // external (property name)
        "x": "VTI5c1lYSmZWMmx1WkhNZ0dQTXhaYkhtSnBEU3UtSXZwdUtpZ0VOMnB6Z1d0U28tLVJ3ZC1uNzhuclduWnplRGMx", // external (property name)
        "y": "UW5WNVgwSnBkR052YVc0Z1VqY1B6LVpoZWNaRnliT3FMSUpqVk9sTEVUSDd1UGx5RzBnRW9NV25JWlhoUVZ5cFB5" // external (property name)
      }
    },
    {
      "id": "did:example:123#key-7",
      "type": "JsonWebKey2020",
      "controller": "did:example:123",
      "publicKeyJwk": {
        "kty": "RSA", // external (property name)
        "e": "AQAB", // external (property name)
        "n": "UkhWaGJGOUZRMTlFVWtKSElBdENGV2hlU1F2djFNRXh1NVJMQ01UNGpWazlraEpLdjhKZU1YV2UzYldIYXRqUHNrZGYyZGxhR2tXNVFqdE9uVUtMNzQybXZyNHRDbGRLUzNVTElhVDFoSkluTUhIeGoyZ2N1Yk82ZUVlZ0FDUTRRU3U5TE8wSC1MTV9MM0RzUkFCQjdRamE4SGVjcHl1c3BXMVR1X0RicXhjU253ZW5kYW13TDUyVjE3ZUtobE80dVh3djJIRmx4dWZGSE0wS21DSnVqSUt5QXhqRF9tM3FfX0lpSFVWSEQxdERJRXZMUGhHOUF6c24zajk1ZC1zYU" // external (property name)
      }
    }
  ]
}

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/ed25519-2018/v1",
    "https://w3id.org/security/suites/x25519-2019/v1",
    "https://w3id.org/security/suites/secp256k1-2019/v1",
    "https://w3id.org/security/suites/jws-2020/v1"
  ],
  "verificationMethod": [
    {
      "id": "did:example:123#key-0",
      "type": "Ed25519VerificationKey2018",
      "controller": "did:example:123",
      "publicKeyBase58": "3M5RCDjPTWPkKSN3sxUmmMqHbmRPegYP1tjcKyrDbt9J" // external (property name)
    },
    {
      "id": "did:example:123#key-1",
      "type": "X25519KeyAgreementKey2019",
      "controller": "did:example:123",
      "publicKeyBase58": "FbQWLPRhTH95MCkQUeFYdiSoQt8zMwetqfWoxqPgaq7x" // external (property name)
    },
    {
      "id": "did:example:123#key-2",
      "type": "EcdsaSecp256k1VerificationKey2019",
      "controller": "did:example:123",
      "publicKeyBase58": "ns2aFDq25fEV1NUd3wZ65sgj5QjFW8JCAHdUJfLwfodt" // external (property name)
    },
    {
      "id": "did:example:123#key-3",
      "type": "JsonWebKey2020",
      "controller": "did:example:123",
      "publicKeyJwk": {
        "kty": "EC", // external (property name)
        "crv": "P-256", // external (property name)
        "x": "Er6KSSnAjI70ObRWhlaMgqyIOQYrDJTE94ej5hybQ2M", // external (property name)
        "y": "pPVzCOTJwgikPjuUE6UebfZySqEJ0ZtsWFpj7YSPGEk" // external (property name)
      }
    }
  ]
}

A.2 Proving

This section is non-normative.

{  // external (all terms in this example)
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://w3id.org/citizenship/v1"
  ],
  "type": [
    "VerifiableCredential",
    "PermanentResidentCard"
  ],
  "credentialSubject": {
    "id": "did:example:123",
    "type": [
      "PermanentResident",
      "Person"
    ],
    "givenName": "JOHN",
    "familyName": "SMITH",
    "gender": "Male",
    "image": "data:image/png;base64,iVBORw0KGgo...kJggg==",
    "residentSince": "2015-01-01",
    "lprCategory": "C09",
    "lprNumber": "000-000-204",
    "commuterClassification": "C1",
    "birthCountry": "Bahamas",
    "birthDate": "1958-08-17"
  },
  "issuer": "did:example:456",
  "issuanceDate": "2020-04-22T10:37:22Z",
  "identifier": "83627465",
  "name": "Permanent Resident Card",
  "description": "Government of Example Permanent Resident Card.",
  "proof": {
    "type": "Ed25519Signature2018",
    "created": "2020-04-22T10:37:22Z",
    "proofPurpose": "assertionMethod",
    "verificationMethod": "did:example:456#key-1",
    "jws": "eyJjcml0IjpbImI2NCJdLCJiNjQiOmZhbHNlLCJhbGciOiJFZERTQSJ9..BhWew0x-txcroGjgdtK-yBCqoetg9DD9SgV4245TmXJi-PmqFzux6Cwaph0r-mbqzlE17yLebjfqbRT275U1AA"
  }
}

{  // external (all terms in this example)
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "http://example.gov/credentials/3732",
  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
  "issuer": { "id": "did:example:123" },
  "issuanceDate": "2020-03-10T04:24:12.164Z",
  "credentialSubject": {
    "id": "did:example:456",
    "degree": {
      "type": "BachelorDegree",
      "name": "Bachelor of Science and Arts"
    }
  },
  "proof": {
    "type": "JsonWebSignature2020",
    "created": "2020-02-15T17:13:18Z",
    "verificationMethod": "did:example:123#_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A",
    "proofPurpose": "assertionMethod",
    "jws": "eyJiNjQiOmZhbHNlLCJjcml0IjpbImI2NCJdLCJhbGciOiJFZERTQSJ9..Y0KqovWCPAeeFhkJxfQ22pbVl43Z7UI-X-1JX32CA9MkFHkmNprcNj9Da4Q4QOl0cY3obF8cdDRdnKr0IwNrAw"
  }
}

{  // external (all terms in this example)
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://w3id.org/security/bbs/v1",
    {
      "name": "https://schema.org/name",
      "birthDate": "https://schema.org/birthDate"
    }
  ],
  "id": "urn:uuid:c499e122-3ba9-4e95-8d4d-c0ebfcf8c51a",
  "type": ["VerifiableCredential"],
  "issuanceDate": "2021-02-07T16:02:08.571Z",
  "issuer": {
    "id": "did:example:123"
  },
  "credentialSubject": {
    "id": "did:example:456",
    "name": "John Smith",
    "birthDate": "2021-02-07"
  },
  "proof": {
    "type": "BbsBlsSignature2020",
    "created": "2021-02-07T16:02:10Z",
    "proofPurpose": "assertionMethod",
    "proofValue": "o7zD2eNTp657YzkJLub+IO4Zqy/R3Lv/AWmtSA/kUlEAOa73BNyP1vOeoow35jkABolx4kYMKkp/ZsFDweuKwe/p9vxv9wrMJ9GpiOZjHcpjelDRRJLBiccg9Yv7608mHgH0N1Qrj14PZ2saUlfhpQ==",
    "verificationMethod": "did:example:123#bls12381-g2-key"
  }
}

{  // external (all terms in this example)
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://w3id.org/security/bbs/v1",
    {
      "name": "https://schema.org/name",
      "birthDate": "https://schema.org/birthDate"
    }
  ],
  "id": "urn:uuid:c499e122-3ba9-4e95-8d4d-c0ebfcf8c51a",
  "type": "VerifiableCredential",
  "issuanceDate": "2021-02-07T16:02:08.571Z",
  "issuer": {
    "id": "did:example:123"
  },
  "credentialSubject": {
    "id": "did:example:456",
    "birthDate": "2021-02-07"
  },
  "proof": {
    "type": "BbsBlsSignatureProof2020",
    "created": "2021-02-07T16:02:10Z",
    "nonce": "OqZHsV/aunS34BhLaSoxiHWK+SUaG4iozM3V+1jO06zRRNcDWID+I0uwtPJJ767Yo8Q=",
    "proofPurpose": "assertionMethod",
    "proofValue": "AAsH34lcKsqaqPaLQWcnLMe3mDM+K7fZM0t4Iesfj7BhD//HBtuWCmZE946BqW7OHYU106MP8mLntutqB8FyGwS7AOyK+5/7iW6JwLNVCvh4Nt3IaF3AN47fqVs2VikD9DiCsaFAUU6ISj5pbad8O+6jiT9Yw6ug8t8vJn3XHvMUhCPnDZJeBEdKD1qo4Z0LOq3L8QAAAHSEgtC9BoZL2MLjz4QuPxpwbhTTRC08MIUjdJnP4JUtz6163Lsl3rpadGu2d3Te7loAAAACZBD4YWOgV0xpPoYZ5vywNA5/NTeDHDbX36gvoV5RDJtY1SLU2LN/IDPZGrfhEiASbD1/QXqj8dod6FbjBs9m/LchBcy7z4yDBv/8DnBzDJ9dEaM4bDjpwmqtgJqha2kwtlyNog67xG9tNjnp5rrbIgAAAANMVanwWmlkg5I/f1M2QJ5GRvQiBL4lyL5sttxwIOalbTZP8VqWtFJI54xMNjTiK71aFWWN8SlNEwfVIX34HO5zBIb6fvc+Or21ubYllT9eXv1epl2o2CojuieCZyxE8/Q=",
    "verificationMethod": "did:example:123#bls12381-g2-key"
  }
}

{ // external (all terms in this example)
  "protected": {
    "kid": "did:example:123#_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A",
    "alg": "EdDSA"
  },
  "payload": {
    "iss": "did:example:123",
    "sub": "did:example:456",
    "vc": {
      "@context": [
        "https://www.w3.org/2018/credentials/v1",
        "https://www.w3.org/2018/credentials/examples/v1"
      ],
      "id": "http://example.gov/credentials/3732",
      "type": [
        "VerifiableCredential",
        "UniversityDegreeCredential"
      ],
      "issuer": {
        "id": "did:example:123"
      },
      "issuanceDate": "2020-03-10T04:24:12.164Z",
      "credentialSubject": {
        "id": "did:example:456",
        "degree": {
          "type": "BachelorDegree",
          "name": "Bachelor of Science and Arts"
        }
      }
    },
    "jti": "http://example.gov/credentials/3732",
    "nbf": 1583814252
  },
  "signature": "qSv6dpZJGFybtcifLwGf4ujzlEu-fam_M7HPxinCbVhz9iIJCg70UMeQbPa1ex6BmQ2tnSS7F11FHnMB2bJRAw"
}

A.3 Encrypting

This section is non-normative.

{ // external (all terms in this example)
  "ciphertext": "3SHQQJajNH6q0fyAHmw...",
  "iv": "QldSPLVnFf2-VXcNLza6mbylYwphW57Q",
  "protected": "eyJlbmMiOiJYQzIwUCJ9",
  "recipients": [
    {
      "encrypted_key": "BMJ19zK12YHftJ4sr6Pz1rX1HtYni_L9DZvO1cEZfRWDN2vXeOYlwA",
      "header": {
        "alg": "ECDH-ES+A256KW",
        "apu": "Tx9qG69ZfodhRos-8qfhTPc6ZFnNUcgNDVdHqX1UR3s",
        "apv": "ZGlkOmVsZW06cm9wc3RlbjpFa...",
        "epk": {
          "crv": "X25519",
          "kty": "OKP",
          "x": "Tx9qG69ZfodhRos-8qfhTPc6ZFnNUcgNDVdHqX1UR3s"
        },
        "kid": "did:example:123#zC1Rnuvw9rVa6E5TKF4uQVRuQuaCpVgB81Um2u17Fu7UK"
      }
    }
  ],
  "tag": "xbfwwDkzOAJfSVem0jr1bA"
}

B.1 Detailed Architecture Diagram

Following is a diagram showing the relationships among § 4. Data Model, § 5. Core Properties, and § 8. Methods, and § 7. Resolution.

B.2 Creation of a DID

The creation of a DID is a process that is defined by each DID Method. Some DID Methods, such as did:key, are purely generative, such that a DID and a DID document are generated by transforming a single piece of cryptographic material into a conformant representation. Other DID methods might require the use of a verifiable data registry, where the DID and DID document are recognized to exist by third parties only when the registration has been completed, as defined by the respective DID method. Other processes might be defined by the respective DID method.

B.3 Determining the DID subject

A DID is a specific type of URI (Uniform Resource Identifier), so a DID can refer to any resource. Per [RFC3986]:

the term "resource" is used in a general sense for whatever might be identified by a URI. [...] A resource is not necessarily accessible via the Internet.

Resources can be digital or physical, abstract or concrete. Any resource that can be assigned a URI can be assigned a DID. The resource referred to by the DID is the DID subject.

The DID controller determines the DID subject. It is not expected to be possible to determine the DID subject from looking at the DID itself, as DIDs are generally only meaningful to machines, not human. A DID is unlikely to contain any information about the DID subject, so further information about the DID subject is only discoverable by resolving the DID to the DID document, obtaining a verifiable credential about the DID, or via some other description of the DID.

While the value of the id property in the retrieved DID document must always match the DID being resolved, whether or not the actual resource to which the DID refers can change over time is dependent upon the DID method. For example, a DID method that permits the DID subject to change could be used to generate a DID for the current occupant of a particular role—such as the CEO of a company—where the actual person occupying the role can be different depending on when the DID is resolved.

B.4 Referring to the DID document

The DID refers to the DID subject and resolves to the DID document (by following the protocol specified by the DID method). The DID document is not a separate resource from the DID subject and does not have a URI separate from the DID. Rather the DID document is an artifact of DID resolution controlled by the DID controller for the purpose of describing the DID subject.

This distinction is illustrated by the graph model shown below.

Two filled black circles appear at the top of the diagram, one on the left, labeled "DID Controller", and one on the right, labeled "DID Subject". A rectangle, with lower right corner bent inwards to form a small triangle, appears below, containing the label "DID Document". Arrows extend between these three items, as follows. A solid red arrow points directly from the DID Controller circle, rightwards to the DID Subject circle, labeled "DID" above it in large font, and "Identifies" below it in small italic font. The other arrow labels are also in small italic font. A dotted red arrow, labeled "Resolves to", extends from DID Controller, starting in the same line as the first arrow, then curving downward to point to the DID Document rectangle. A green arrow, labeled "Controls", points directly from DID Controller to DID Document. A green arrow labeled "Controller" points in the opposite direction, from DID Document to DID Controller, making an arc outward to the left of the diagram. A blue arrow, labeled, "Describes" points directly from DID Document to DID Subject.

B.5 Statements in the DID document

Each property in a DID document is a statement by the DID controller that describes:

• The string of characters defining identifiers for the DID subject (e.g., the id and alsoKnownAs properties)
• How to interact with the DID subject (e.g., the verificationMethod and service properties).
• How to interpret the specific representation of the DID document (e.g., the @context property for a JSON-LD representation).

The only required property in a DID document is id, so that is the only statement guaranteed to be in a DID document. That statement is illustrated in Figure 8 with a direct link between the DID and the DID subject.

B.6 Discovering more information about the DID subject

Options for discovering more information about the DID subject depend on the properties present in the DID document. If the service property is present, more information can be requested from a service endpoint. For example, by querying a service endpoint that supports verifiable credentials for one or more claims (attributes) describing the DID subject.

Another option is to use the alsoKnownAs property if it is present in the DID document. The DID controller can use it to provide a list of other URIs (including other DIDs) that refer to the same DID subject. Resolving or dereferencing these URIs might yield other descriptions or representations of the DID subject as illustrated in the figure below.

The diagram contains three small black filled circles, two rectangles with bent corners, arrows between them, and labels, as follows. On the upper left is a circle labeled "DID Controller". On the upper right is a circle labeled "DID Subject". On the lower-middle right is a circle without a label. On the lower right is a rectangle labeled "Description". In the center of the diagram is a rectangle labeled "DID Document". Inside the DID Document rectangle, beneath its label, is two lines of code: "alsoKnownAs: [", and "URI]". A black arrow extends from the second line, to the right, crossing the rectangle border, pointing to the unlabeled circle at the right of the diagram. This arrow is labeled above it in large font, "URI", and below it in italic, "Identifies". A black arrow points from the unlabeled circle downwards to the Description rectangle, labeled "Dereferences to". A dotted blue arrow, labeled "Describes", extends from Description, arcing on the right, pointing up to DID Subject. A blue arrow, also labeled "Describes", points directly from the Describes rectangle in the center of the diagram, up and to the right to the DID Subject circle. A red arrow, labeled "alsoKnownAs", points from DID Subject down to the unlabeled circle. A red arrow, labeled "DID" above it in large font, and "Identifies" below it in italic font, lies at the top of the image, pointing from DID Controller to DID Subject. A dotted red line starts in the same place but branches off and curves downward to point to the DID Document rectangle at the center of the image. A green arrow, labeled "Controls", points directly from DID Controller to DID Document. Another green arrow points in the opposite direction, labeled "Controller", curving outwards on the left of the image, from DID Document to DID Controller.

B.7 Serving a representation of the DID subject

If the DID subject is a digital resource that can be retrieved from the internet, a DID method can choose to construct a DID URL which returns a representation of the DID subject itself. For example, a data schema that needs a persistent, cryptographically verifiable identifier could be assigned a DID, and passing a specified DID parameter (see § 3.2.1 DID Parameters) could be used as a standard way to retrieve a representation of that schema.

Similarly, a DID can be used to refer to a digital resource (such as an image) that can be returned directly from a verifiable data registry if that functionality is supported by the applicable DID method.

B.8 Assigning DIDs to existing web resources

If the controller of a web page or any other web resource wants to assign it a persistent, cryptographically verifiable identifier, the controller can give it a DID. For example, the author of a blog hosted by a blog hosting company (under that hosting company's domain) could create a DID for the blog. In the DID document, the author can include the alsoKnownAs property pointing to the current URL of the blog, e.g.:

If the author subsequently moves the blog to a different hosting company (or to the author's own domain), the author can update the DID document to point to the new URL for the blog, e.g.:

The DID effectively adds a layer of indirection for the blog URL. This layer of indirection is under the control of the author instead of under the control of an external administrative authority such as the blog hosting company. This is how a DID can effectively function as an enhanced URN (Uniform Resource Name)—a persistent identifier for an information resource whose network location might change over time.

B.9 The relationship between DID controllers and DID subjects

To avoid confusion, it is helpful to classify DID subjects into two disjoint sets based on their relationship to the DID controller.

B.9.1 Set #1: The DID subject is the DID controller

The first case, shown in Figure 10, is the common scenario where the DID subject is also the DID controller. This is the case when an individual or organization creates a DID to self-identify.

Two small black circles appear in the diagram, one on the upper left, labeled, "DID Controller", and one on the upper right, labeled "DID Subject". A solid red arrow extends from the DID Controller circle to the DID Subject circle, labeled "DID" in large bold text above the arrow, and "Identifies" in small italic text beneath the arrow. A dotted red double-ended arrow, labeled "Equivalence", extends between the two circles, forming an arc in the space between and above them. In the lower part of the diagram is a rectangle with bent corner, outlined in black, containing the label "DID Document". Arrows point between this DID Document rectangle and the small black circles for DID Controller and DID Subject, with italic labels, as follows. A blue arrow points from the DID Document to the DID Subject, labeled, "Describes". A green arrow points from the DID Controller to the DID Document, labeled "Controls". A green points from the DID Document to the DID Controller, in an outward arc, labeled, "Controller". A dotted red arrow, labeled "Resolves to", extends from the DID controller starting to the right, branching off from the arrow to the DID Subject, then curving downward to point to the DID Document.

From a graph model perspective, even though the nodes identified as the DID controller and DID subject in Figure 10 are distinct, there is a logical arc connecting them to express a semantic equivalence relationship.

B.10 Multiple DID controllers

A DID document might have more than one DID controller. This can happen in one of two ways.

B.10.1 Independent Control

In this case, each of the DID controllers might act on its own, i.e., each one has full power to update the DID document independently. From a graph model perspective, in this configuration:

• Each additional DID controller is another distinct graph node (which might be identified by its own DID).
• The same arcs ("controls" and "controller") exist between each DID controller and the DID document.

Three black circles appear on the left, vertically, each labeled "DID Controller". From each of these circles, a pair of green arrows extends towards the center of the diagram, to a single rectangle, labeled "DID Document". The rectangle has the lower right corner cut and bent inward to form a small triangle, as if to represent a physical piece of paper with curled corner. Each pair of green arrows consists of one arrow pointing from the black circle to the rectangle, labeled "Controls", and one pointing in the opposite direction, from the rectangle to the black circle, labeled "Controller". From the right of the rectangle extends a blue arrow, labeled, "Describes", pointing to a black circle labeled, "DID Subject".

B.10.2 Group Control

In the case of group control, the DID controllers are expected to act together in some fashion, such as when using a cryptographic algorithm that requires multiple digital signatures ("multi-sig") or a threshold number of digital signatures ("m-of-n"). From a functional standpoint, this option is similar to a single DID controller because, although each of the DID controllers in the DID controller group has its own graph node, the actual control collapses into a single logical graph node representing the DID controller group as shown in Figure 12.

On the left are three black filled circles, labeled "DID Controller Group" by a brace on the left. From each of these three circles, a green arrow extends to the center right. These three arrows converge towards a single filled white circle. A pair of horizontal green arrows connects this white circle on its right to a rectangle shaped like a page with a curled corner, labeled "DID Document". The upper arrow points right, from the white circle to the rectangle, and is labeled "Controls". The lower arrow points left, from the rectangle to the white circle, and is labeled "Controller". From the right of the rectangle extends a blue arrow, labeled "Describes", pointing to a black circle, labeled "DID Subject".

This configuration will often apply when the DID subject is an organization, corporation, government agency, community, or other group that is not controlled by a single individual.

B.11 Changing the DID subject

A DID document has exactly one DID which refers to the DID subject. The DID is expressed as the value of the id property. This property value is immutable for the lifetime of the DID document.

However, it is possible that the resource identified by the DID, the DID subject, may change over time. This is under the exclusive authority of the DID controller. For more details, see section § 9.16 Persistence.

B.12 Changing the DID controller

The DID controller for a DID document might change over time. However, depending on how it is implemented, a change in the DID controller might not be made apparent by changes to the DID document itself. For example, if the change is implemented through a shift in ownership of the underlying cryptographic keys or other controls used for one or more of the verification methods in the DID document, it might be indistinguishable from a standard key rotation.

On the other hand, if the change is implemented by changing the value of the controller property, it will be transparent.

If it is important to verify a change of DID controller, implementers are advised to authenticate the new DID controller against the verification methods in the revised DID document.

E.1 application/did+json

Type name:

application

Subtype name:

did+json

Required parameters:

None

Optional parameters:

None

Encoding considerations:

See RFC 8259, section 11.

Security considerations:

See RFC 8259, section 12 [RFC8259].

Interoperability considerations:

Not Applicable

Published specification:

https://www.w3.org/TR/did-core/

Applications that use this media type:

Any application that requires an identifier that is decentralized, persistent, cryptographically verifiable, and resolvable. Applications typically consist of cryptographic identity systems, decentralized networks of devices, and websites that issue or verify W3C Verifiable Credentials.

Additional information:

Magic number(s):

Not Applicable

File extension(s):

.didjson

Macintosh file type code(s):

TEXT

Person & email address to contact for further information:

Ivan Herman <ivan@w3.org>

Intended usage:

Common

Restrictions on usage:

None

Author(s):

Drummond Reed, Manu Sporny, Markus Sabadello, Dave Longley, Christopher Allen

Change controller:

W3C

Fragment identifiers used with application/did+json are treated according to the rules defined in § Fragment.

E.2 application/did+ld+json

Type name:

application

Subtype name:

did+ld+json

Required parameters:

None

Optional parameters:

None

Encoding considerations:

See RFC 8259, section 11.

Security considerations:

See JSON-LD 1.1, Security Considerations [JSON-LD11].

Interoperability considerations:

Not Applicable

Published specification:

https://www.w3.org/TR/did-core/

Applications that use this media type:

Any application that requires an identifier that is decentralized, persistent, cryptographically verifiable, and resolvable. Applications typically consist of cryptographic identity systems, decentralized networks of devices, and websites that issue or verify W3C Verifiable Credentials.

Additional information:

Magic number(s):

Not Applicable

File extension(s):

.didjsonld

Macintosh file type code(s):

TEXT

Person & email address to contact for further information:

Ivan Herman <ivan@w3.org>

Intended usage:

Common

Restrictions on usage:

None

Author(s):

Drummond Reed, Manu Sporny, Markus Sabadello, Dave Longley, Christopher Allen

Change controller:

W3C

Fragment identifiers used with application/did+ld+json are treated according to the rules associated with the JSON-LD 1.1: application/ld+json media type [JSON-LD11].

F.1 Normative references

[INFRA]

Infra Standard. Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/

[JSON-LD11]

JSON-LD 1.1. Gregg Kellogg; Pierre-Antoine Champin; Dave Longley. W3C. 12 December 2019. W3C Candidate Recommendation. URL: https://www.w3.org/TR/json-ld11/

[RFC2119]

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

[RFC3552]

Guidelines for Writing RFC Text on Security Considerations. E. Rescorla; B. Korver. IETF. July 2003. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc3552

[RFC3986]

Uniform Resource Identifier (URI): Generic Syntax. T. Berners-Lee; R. Fielding; L. Masinter. IETF. January 2005. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc3986

[RFC5234]

Augmented BNF for Syntax Specifications: ABNF. D. Crocker, Ed.; P. Overell. IETF. January 2008. Internet Standard. URL: https://tools.ietf.org/html/rfc5234

[RFC7517]

JSON Web Key (JWK). M. Jones. IETF. May 2015. Proposed Standard. URL: https://tools.ietf.org/html/rfc7517

[RFC7638]

JSON Web Key (JWK) Thumbprint. M. Jones; N. Sakimura. IETF. September 2015. Proposed Standard. URL: https://tools.ietf.org/html/rfc7638

[RFC8174]

Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://tools.ietf.org/html/rfc8174

[RFC8259]

The JavaScript Object Notation (JSON) Data Interchange Format. T. Bray, Ed.. IETF. December 2017. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc8259

[url]

URL Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://url.spec.whatwg.org/

[XMLSCHEMA11-2]

W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes. David Peterson; Sandy Gao; Ashok Malhotra; Michael Sperberg-McQueen; Henry Thompson; Paul V. Biron et al. W3C. 5 April 2012. W3C Recommendation. URL: https://www.w3.org/TR/xmlschema11-2/

F.2 Informative references

[DID-RESOLUTION]

Decentralized Identifier Resolution. Markus Sabadello; Dmitri Zagidulin. Credentials Community Group. Draft Community Group Report. URL: https://w3c-ccg.github.io/did-resolution/

[DID-RUBRIC]

Decentralized Characteristics Rubric v1.0. Joe Andrieu. Credentials Community Group. Draft Community Group Report. URL: https://w3c.github.io/did-rubric/

[DID-SPEC-REGISTRIES]

DID Specification Registries. Orie Steele; Manu Sporny. W3C. 24 June 2021. W3C Note. URL: https://www.w3.org/TR/did-spec-registries/

[DID-USE-CASES]

Use Cases and Requirements for Decentralized Identifiers. Joe Andrieu; Phil Archer; Kim Duffy; Ryan Grant; Adrian Gropper. W3C. 17 March 2021. W3C Note. URL: https://www.w3.org/TR/did-use-cases/

[DNS-DID]

The Decentralized Identifier (DID) in the DNS. Alexander Mayrhofer; Dimitrij Klesev; Markus Sabadello. February 2019. Internet-Draft. URL: https://datatracker.ietf.org/doc/draft-mayrhofer-did-dns/

[HASHLINK]

Cryptographic Hyperlinks. Manu Sporny. IETF. December 2018. Internet-Draft. URL: https://tools.ietf.org/html/draft-sporny-hashlink-05

[IANA-URI-SCHEMES]

Uniform Resource Identifier (URI) Schemes. IANA. URL: https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml

[MATRIX-URIS]

Matrix URIs - Ideas about Web Architecture. Tim Berners-Lee. December 1996. Personal View. URL: https://www.w3.org/DesignIssues/MatrixURIs.html

[MULTIBASE]

The Multibase Encoding Scheme. Juan Benet; Manu Sporny. IETF. February 2021. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-multiformats-multibase-03

[PRIVACY-BY-DESIGN]

Privacy by Design. Ann Cavoukian. Information and Privacy Commissioner. 2011. URL: https://iapp.org/media/pdf/resource_center/pbd_implement_7found_principles.pdf

[RFC4122]

A Universally Unique IDentifier (UUID) URN Namespace. P. Leach; M. Mealling; R. Salz. IETF. July 2005. Proposed Standard. URL: https://tools.ietf.org/html/rfc4122

[RFC6901]

JavaScript Object Notation (JSON) Pointer. P. Bryan, Ed.; K. Zyp; M. Nottingham, Ed.. IETF. April 2013. Proposed Standard. URL: https://tools.ietf.org/html/rfc6901

[RFC6973]

Privacy Considerations for Internet Protocols. A. Cooper; H. Tschofenig; B. Aboba; J. Peterson; J. Morris; M. Hansen; R. Smith. IETF. July 2013. Informational. URL: https://tools.ietf.org/html/rfc6973

[RFC7230]

Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7230.html

[RFC7231]

Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7231.html

[RFC8141]

Uniform Resource Names (URNs). P. Saint-Andre; J. Klensin. IETF. April 2017. Proposed Standard. URL: https://tools.ietf.org/html/rfc8141

[VC-DATA-MODEL]

Verifiable Credentials Data Model 1.0. Manu Sporny; Grant Noble; Dave Longley; Daniel Burnett; Brent Zundel. W3C. 19 November 2019. W3C Recommendation. URL: https://www.w3.org/TR/vc-data-model/