Decentralized Identifiers (DIDs) v1.1

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, RECOMMENDED, 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 repository of DID Extensions [DID-EXTENSIONS] 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 method is any specification that complies with the relevant normative statements in 7. Methods.

The repository of DID Extensions [DID-EXTENSIONS] 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.

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

• The verifiable data registry supports verifiable timestamps. See "DID Document Metadata" in [DID-RESOLUTION] 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 8.3 Notification of DID Document Changes.
• The subject has had adequate opportunity to revert malicious updates according to the authorization mechanism for the DID method.

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.

Trustless systems are those where all trust is derived from cryptographically provable assertions, and more specifically, where no metadata outside of the cryptographic system is factored into the determination of trust in the system. To verify a signature of proof for a verification method which has been revoked in a trustless system, a DID method needs to support either or both of the versionId or versionTime, as well as both the updated and nextUpdate, DID document metadata properties. A verifier can validate a signature or proof of a revoked key if and only if all of the following are true:

• The proof or signature includes the versionId or versionTime of the DID document that was used at the point in time at which the signature or proof was made.
• The verifier can determine the point in time at which the signature or proof was made; for example, it was anchored on a blockchain.
• In the resolved DID document metadata, the updated timestamp is before, and the nextUpdate timestamp is after, the point in time at which the signature or proof was made.

Similar trust may be achieved in systems that are willing to accept metadata beyond that which constitutes cryptographic input -- but this always requires a careful judgment about whether a DID document's content included the expected content at the moment of a signing event.

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:

• Proactively performing recovery, on an infrequent but regular basis, can help to prevent loss of control.
• 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 any service trusted to act on their behalf no longer has the exclusive ability to perform DID operations as described in 7.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.

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.

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.

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.

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.

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 Section 2.1.3: Also Known As of the Controlled Identifiers v1.0 specification.

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.

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.

When a DID subject is indistinguishable from others in the group, 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 group 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.