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 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 and . A serialization format for the conforming document is deterministic, bi-directional, and lossless, as described in .

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 .

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 .

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

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.

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.

Authentication Service Endpoints

If a DID document publishes a service intended for authentication or authorization of the DID subject (see Section ), 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.

Non-Repudiation

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 .
• The subject has had adequate opportunity to revert malicious updates according to the authorization mechanism for the DID method.

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.

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.

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.

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 , 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.

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 .
• 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 .
• 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.

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.

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.

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.

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.

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 .

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.

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.

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.

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 , and where is applicable for such extensions.

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.

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.

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 ).

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 ) or correlatable data (see and ) 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.

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.

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.