Copyright © 2020 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.
This document is undergoing a major structural refactoring and will not be easy to read. A previously published version that has a better topical flow may be a better read for people new to this work. When this document has been updated to have a better flow, this comment will be removed.
Decentralized identifiers (DIDs) are a new type of identifier that enables verifiable, decentralized digital identity. A DID identifies any subject (e.g., a person, organization, thing, data model, abstract entity, etc.) that the controller of the DID decides that it identifies. These new identifiers are designed to enable the controller of a DID to prove control over it and to be implemented independently of any centralized registry, identity provider, or certificate authority. DIDs are URLs that associate a DID subject with a DID document allowing trustable interactions associated with that subject. Each DID document can express cryptographic material, verification methods, or service endpoints, which provide a set of mechanisms enabling a DID controller to prove control of the DID. Service endpoints enable trusted interactions associated with the DID subject. A DID document might contain semantics about the subject that it identifies. A DID document might contain the DID subject itself (e.g. a data model).
This document specifies a common data model, a URL format, and a set of operations for DIDs, DID documents, and DID methods.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
This specification is under active development and implementers are advised against implementing the specification unless they are directly involved with the W3C DID Working Group. There are use cases [DID-USE-CASES] in active development that establish requirements for this document.
At present, there exist 40 experimental implementations and a preliminary test suite that will eventually determine whether or not implementations are conformant. Readers are advised that Appendix § C. Current Issues contains a list of concerns and proposed changes that will most likely result in alterations to this specification.
Comments regarding this document are welcome. Please file issues directly on GitHub, or send them to public-did-wg@w3.org ( subscribe, archives).
Portions of the work on this specification have been funded by the United States Department of Homeland Security's Science and Technology Directorate under contracts HSHQDC-16-R00012-H-SB2016-1-002 and HSHQDC-17-C-00019. The content of this specification does not necessarily reflect the position or the policy of the U.S. Government and no official endorsement should be inferred.
Work on this specification has also been supported by the Rebooting the Web of Trust community facilitated by Christopher Allen, Shannon Appelcline, Kiara Robles, Brian Weller, Betty Dhamers, Kaliya Young, Kim Hamilton Duffy, Manu Sporny, Drummond Reed, Joe Andrieu, and Heather Vescent.
This document was published by the Decentralized Identifier Working Group as a Working Draft. This document is intended to become a W3C Recommendation.
GitHub Issues are preferred for discussion of this specification. Alternatively, you can send comments to our mailing list. Please send them to public-did-wg@w3.org (archives).
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 1 March 2019 W3C Process Document.
This section is non-normative.
Conventional identity management systems are based on centralized authorities such as corporate directory services, certificate authorities, or domain name registries. From the standpoint of cryptographic trust verification, each of these centralized authorities serves as its own root of trust. To make identity management work across these systems requires implementing federated identity management.
The emergence of distributed ledger technology (DLT) and blockchain technology provides the opportunity for fully decentralized identity management. In a decentralized identity system, entities (that is, discrete identifiable units such as, but not limited to, people, organizations, and things) are free to use any shared root of trust. Globally distributed ledgers, decentralized P2P networks, or other systems with similar capabilities, provide the means for managing a root of trust without introducing a centralized authority or a single point of failure. In combination, DLTs and decentralized identity management systems enable any entity to create and manage their own identifiers on any number of distributed, independent roots of trust.
Entities are identified by decentralized identifiers (DIDs), and can authenticate using proofs (for example, digital signatures, privacy-preserving biometric protocols, and so on). DIDs point to DID documents. A DID document contains a set of service endpoints for interacting with the entity that the DID identifies (that is, the DID subject). Following the guidelines of Privacy by Design, any entity can have as many DIDs (and corresponding DID documents and service endpoints) as necessary to respect the entity’s desired separation of identities, personas, and contexts (in the everyday sense of these words).
DID methods are the mechanism by which a DID and its associated DID document are created, read, updated, and deactivated on a specific distributed ledger or network. DID methods are defined using separate DID method specifications.
This design eliminates dependence on centralized registries for identifiers as well as centralized certificate authorities for key management, which is the standard in hierarchical PKI (public key infrastructure). In cases where the DID registry is a distributed ledger, each entity can serve as its own root authority. This architecture is referred to as DPKI (decentralized PKI).
DID methods can also be developed for identifiers registered in federated or centralized identity management systems. Indeed, all types of identifier systems can add support for DIDs. This creates an interoperability bridge between the worlds of centralized, federated, and decentralized identifiers.
The first purpose of this specification is to define the generic DID scheme and a generic set of operations on DID documents that can be implemented for any DID registry. The second purpose of this specification is to define the conformance requirements for a DID method specification. The DID method specification is a separate document that defines a specific DID scheme and specific set of DID document operations for a specific DID registry.
Conceptually, the relationship between this specification and a DID method specification is similar to the relationship between the IETF generic URI specification ([RFC3986]) and a specific URI scheme ([IANA-URI-SCHEMES] (such as the http: and https: schemes specified in [RFC7230]). It is also similar to the relationship between the IETF generic URN specification ([RFC8141]) and a specific URN namespace definition, (such as the UUID URN namespace defined in [RFC4122]). The difference is that a DID method specification, as well as defining a specific DID scheme, also specifies the methods for resolving and deactivating DIDs on, and writing DID documents to, the appropriate DID registry.
The hierarchical design of a generic DID specification with specific DID method specifications introduces some of the same concepts as the URI specification:
For a list of DID methods and their corresponding specifications, see the DID Method Registry [DID-METHOD-REGISTRY].
This section is non-normative.
A DID is a simple text string consisting of three parts, the:
did
)
did:example:123456789abcdefghi
The example DID above resolves to a DID document. A DID document contains information associated with the DID, such as ways to cryptographically authenticate the entity in control of the DID, as well as services that can be used to interact with the entity.
{ "@context": "https://www.w3.org/ns/did/v1", "id": "did:example:123456789abcdefghi", "authentication": [{ // used to authenticate as did:...fghi "id": "did:example:123456789abcdefghi#keys-1", "type": "RsaVerificationKey2018", "controller": "did:example:123456789abcdefghi", "publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n" }], "service": [{ // used to retrieve Verifiable Credentials associated with the DID "id":"did:example:123456789abcdefghi#vcs", "type": "VerifiableCredentialService", "serviceEndpoint": "https://example.com/vc/" }] }
This section is non-normative.
Decentralized Identifiers are a component of larger systems, such as the Verifiable Credentials ecosystem [VC-DATA-MODEL], which drove the design goals for this specification. This section summarizes the primary design goals for this specification.
Goal | Description |
---|---|
Decentralization | Eliminate the requirement for centralized authorities or single point failure in identifier management, including the registration of globally unique identifiers, public verification keys, service endpoints, and other metadata. |
Control | Give entities, both human and non-human, the power to directly control their digital identifiers without the need to rely on external authorities. |
Privacy | Enable entities to control the privacy of their information, including minimal, selective, and progressive disclosure of attributes or other data. |
Security | Enable sufficient security for relying parties to depend on DID documents for their required level of assurance. |
Proof-based | Enable DID subjects to provide cryptographic proof when interacting with other entities. |
Discoverability | Make it possible for entities to discover DIDs for other entities to learn more about or interact with those entities. |
Interoperability | Use interoperable standards so DID infrastructure can make use of existing tools and software libraries designed for interoperability. |
Portability | Be system and network-independent and enable entities to use their digital identifiers with any system that supports DIDs and DID methods. |
Simplicity | Favor a reduced set of simple features to make the technology easier to understand, implement, and deploy. |
Extensibility | Where possible, enable extensibility provided it does not greatly hinder interoperability, portability, or simplicity. |
Interoperability of implementations for DIDs and DID documents will be tested by evaluating an implementation's ability to create and parse DIDs and DID documents that conform to the specification. Interoperability for DID methods will be determined by evaluating each DID method specification to determine, at a minimum, that the:
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 must be interoperable for that method.
This section is non-normative.
This document attempts to communicate the concepts outlined in the decentralized identifier space by using specialized terms to discuss specific concepts. This terminology is included below and linked to throughout the document to aid the reader:
controller
property on the top level of the DID
document. Note that the DID controller(s) might include the
DID subject.
#
). DID fragment syntax is identical to the URI fragment syntax.
/
). DID path syntax is identical to the URI path
syntax.
?
). DID query syntax is identical to the URI query syntax.
?
character
followed by a DID query, and optional #
character followed
by a DID fragment.
A DID document is the resource that is associated with a decentralized identifier (DID). DID documents typically express verification methods (such as public keys) and services that can be used to interact with a DID controller.
A DID document is serialized according to a particular syntax, as
outlined in Section § 8. Core Representations). The DID itself
is contained in the id
property.
The properties that can be present in a DID document are outlined in Section § 3.3 DID Documents.
The properties present in a DID document can be updated according to the applicable operations outlined in Section § 9. Methods.
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, NOT RECOMMENDED, 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, CBOR, 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, CBOR,
or JSON-LD.
A conforming DID is any concrete expression of the rules specified in Section § 5. Identifier and MUST comply with relevant normative statements in that section.
A conforming DID Document is any concrete expression of the data model described in this specification and MUST comply with the relevant normative statements in Sections § 6. Data Model and § 7. Core Properties. A serialization format for the conforming document MUST be deterministic, bi-directional, and lossless as described in Section § 8. Core Representations. The conforming DID document MAY be transmitted or stored in any such serialization format.
A conforming DID Method is any specification that complies with the relevant normative statements in Section § 9. Methods.
A producer is any algorithm realized as software and/or hardware and conforms to this specification if it generates conforming DIDs or conforming DID Documents. A producer that is conformant with this specification MUST NOT produce non-conforming DIDs or DID Documents.
A consumer is any algorithm realized as software and/or hardware and conforms to this specification if it consumes conforming DIDs or conforming DID Documents. A consumer that is conformant with this specification MUST produce errors when consuming non-conforming DIDs or DID Documents.
The concept of a globally unique decentralized identifier is not new. Universally Unique Identifiers (UUIDs) were first developed in the 1980s and later became a standard feature of the Open Software Foundation’s Distributed Computing Environment. UUIDs achieve global uniqueness without a centralized registry service by using an algorithm that generates 128-bit values with sufficient entropy that the chance of collision are infinitesimally small. UUIDs are formally specified in [RFC4122] as a specific type of Unified Resource Name (URN).
A DID is similar to a UUID except that:
The generic DID scheme is a URI scheme conformant with [RFC3986].
A DID always identifies the DID subject.
The following is the ABNF definition using the syntax in [RFC5234], which
defines ALPHA
and DIGIT
. All other rule names not
defined in this ABNF are defined in [RFC3986].
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 / "." / "-" / "_"
The grammar currently allows an empty method-specific-id
,
e.g., did:example:
would be a valid DID that could identify
the DID method itself.
A DID method specification MUST further restrict the generic DID
syntax by defining its own method-name
and its own
method-specific-id
syntax. For more information, see Section
§ 9. Methods.
For the broadest interoperability, make DID normalization as simple and universal as possible:
method-specific-id
rule in Section
§ 5.1.1 Generic DID Syntax MUST be defined by the governing
DID method specification.
A DID is expected to be persistent and immutable. That is, a DID is bound exclusively and permanently to its one and only subject. Even after a DID is deactivated, it is intended that it never be repurposed.
Ideally, a DID would be a completely abstract decentralized identifier (like a UUID) that could be bound to multiple underlying DID registries over time, thus maintaining its persistence independent of any particular system. However, registering the same identifier on multiple DID registries introduces extremely hard entityship and start-of-authority (SOA) problems. It also greatly increases implementation complexity for developers.
To avoid these issues, developers should refer to the Decentralized Characteristics Rubric [DID-RUBRIC] to decide which DID method best addresses the needs of the use case.
Although not included in this version, future versions of this specification
might support a DID document equivID
property to establish
verifiable equivalence relations between DIDs representing the same
subject on multiple DID registries. Such equivalence relations can
produce the practical equivalent of a single persistent abstract DID. For
more information, see Section § D.
Future Work
.
A DID URL always identifies a resource to be located. It can be used, for example, to identify a specific part of a DID document.
This following is the ABNF definition using the syntax in [RFC5324]. It builds on the did
scheme defined in § 5.1.1 Generic DID Syntax. The path-abempty
, query
, and
fragment
components are identical to the ABNF rules defined in
[RFC3986].
did-url = did *( ";" param ) path-abempty [ "?" query ] [ "#" fragment ] param = param-name [ "=" param-value ] param-name = 1*param-char param-value = *param-char param-char = ALPHA / DIGIT / "." / "-" / "_" / ":" / pct-encoded
The DID URL syntax supports a simple, generalized format for parameters
based on the matrix parameter syntax ([MATRIX-URIS]). The ABNF above
specifies the basic syntax (the param-name
rule) but does not
specify any concrete parameter names.
Some generic DID parameter names (for example, for service selection) are completely independent of any specific DID method and MUST always function the same way for all DIDs. Other DID parameter names (for example, for versioning) MAY be supported by certain DID methods, but MUST operate uniformly across those DID methods that do support them.
Parameter names that are completely method-specific are described in Section § 5.1.2 Method-Specific Syntax.
The following table defines a set of generic DID parameter names.
Generic DID Parameter Name | Description |
---|---|
hl
|
A resource hash of the DID document to add integrity protection, as specified in [HASHLINK]. |
service
|
Identifies a service from the DID document by service ID. |
version-id
|
Identifies a specific version of a DID document to be resolved (the version ID could be sequential, or a UUID, or method-specific). Note that this parameter might not be supported by all DID methods. |
version-time
|
Identifies a certain version timestamp of a DID document to be resolved. That is, the DID document that was valid for a DID at a certain time. Note that this parameter might not be supported by all DID methods. |
The exact processing rules for these parameters are specified in [DID-RESOLUTION].
Adding a DID parameter to a DID URL means that the parameter becomes part of an identifier for a resource (the DID document or other). Alternatively, the DID resolution and the DID URL dereferencing processes can also be influenced by passing options to a DID resolver that are not part of the DID URL. Such options could for example control caching or the desired encoding of a resolution result. This is comparable to HTTP, where certain parameters could either be included in an HTTP URL, or alternatively passed as HTTP headers during the dereferencing process. The important distinction is that DID parameters that are part of the DID URL should be used to specify what resource is being identified, whereas DID resolver options that are not part of the DID URL should be use to control how that resource is dereferenced.
DID parameters MAY be used if there is a clear use case where the parameter needs to be part of a URI that can be used as a link, or as a resource in RDF / JSON-LD documents.
DID parameters SHOULD NOT be used if there are already other, equivalent ways of constructing URIs that fulfill the same purpose (for example, using other syntactical constructs such as URI query strings or URI fragments).
DID parameters SHOULD NOT be used if the same functionality can be expressed by passing options to a DID resolver, and if there is no need to construct a URI for use as a link, or as a resource in RDF / JSON-LD documents.
A DID method specification MAY specify additional method-specific
parameter names. A method-specific parameter name MUST be prefixed by the method
name, as defined by the method-name
rule.
For example, if the method did:foo:
defines the parameter bar, the
parameter name must be foo:bar
. An example DID URL using
this method and this method-specific parameter would be as shown below.
did:foo:21tDAKCERh95uGgKbJNHYp;foo:bar=high
A method-specific parameter name defined by one DID method MAY be used by other DID methods.
did:example:21tDAKCERh95uGgKbJNHYp;foo:bar=low
Method-specific parameter names MAY be combined with generic parameter names in any order.
did:example:21tDAKCERh95uGgKbJNHYp;service=agent;foo:bar=high
Both DID method namespaces and method-specific parameter namespaces MAY include colons, so they might be partitioned hierarchically, as defined by a DID method specification. The following example DID URL illustrates both.
did:foo:baz:21tDAKCERh95uGgKbJNHYp;foo:baz:hex=b612
A generic DID path is identical to a URI path and MUST conform to the
path-abempty
ABNF rule in [RFC3986]. A DID path SHOULD be
used to address resources available through a service endpoint. For more
information, see Section § 7.6 Service Endpoints.
A specific DID scheme MAY specify ABNF rules for DID paths that are more restrictive than the generic rules in this section.
did:example:123456/path
A generic DID query is identical to a URI query and MUST conform to the
query
ABNF rule in [RFC3986]. A DID query SHOULD be used
to address resources available through a service endpoint. For more
information, see Section § 7.6 Service Endpoints.
A specific DID scheme MAY specify ABNF rules for DID queries that are more restrictive than the generic rules in this section.
did:example:123456?query=true
A DID fragment is used as method-independent reference into the DID document to identify a component of the document (for example, a unique public key description or service endpoint). DID fragment syntax and semantics are identical to a generic URI fragment and MUST conform to RFC 3986, section 3.5. To resolve a DID fragment reference, the complete DID URL including the DID fragment MUST be used as input to the DID URL dereferencing algorithm for the target component in the DID document object. For more information, see [DID-RESOLUTION].
A specific DID scheme MAY specify ABNF rules for DID fragments that are more restrictive than the generic rules in this section.
Implementations need not rely on graph-based processing of DID documents to locate metadata contained in the DID document when the DID includes a DID fragment. Tree-based processing can be used instead.
Implementations SHOULD NOT prevent the use of JSON Pointer ([RFC6901]).
did:example:123456#public-key-1
Additional semantics for fragment identifiers, which are compatible with and layered upon the semantics in this section, are described for JSON-LD representations in Section § F.2 application/did+ld+json.
A relative DID URL is any URL value in a DID document that does not start
with did:<method-name>:<method-specific-id>
. More
specifically, it is any URL value that does not start with the ABNF defined in
Section § 5.1.1 Generic DID Syntax. The contents of the URL typically
refers to a resource in the same DID document. Relative DID URLs MAY
contain relative path components, query parameters, and fragment identifiers.
When resolving a relative DID URL reference, the algorithm specified in RFC3986 Section 5: Reference Resolution MUST
be used. The base URI value is the DID that is
associated with the DID subject, see Section § 7.2 DID Subject.
The scheme is did
. The authority
is a combination of <method-name>:<method-specific-id>
, and
the path, query, and fragment
values are those defined in Section § 5.2.4 Path, Section § 5.2.5 Query, and Section § 5.2.6 Fragment, respectively.
Relative DID URLs are often used to identify verification methods and services in a DID Document without having to use absolute URLs, which tend to be more verbose than necessary.
{ "@context": "https://www.w3.org/ns/did/v1", "id": "did:example:123456789abcdefghi", "publicKey": [{ "id": "did:example:123456789abcdefghi#key-1", "type": "RsaVerificationKey2018", "controller": "did:example:123456789abcdefghi", "publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n" }, ...], "authentication": [ // a relative DID URL used to reference a verification method above "#key-1" ] }
In the example above, the relative DID URL value will be transformed to an
absolute DID URL value of did:example:123456789abcdefghi#key-1
.
This section is non-normative.
A DID points to a DID document. DID documents are the serialization of the data model outlined in Section § 6. Data Model. The following sections define the properties in a DID document, including whether these properties are required or optional.
Identifiers are used in the data model to identify specific instances of people, organizations, devices, keys, services, and things in general. Identifiers are typically URLs, or more generally, URIs. Non-URI-based identifiers are not advised because, while the data model supports them, they are not easy to use with other Internet-based identifiers.
The DID subject is denoted with the id
property. The
DID subject is the entity that the DID document is about. That is,
it is the entity identified by the DID and described by the
DID document.
DID documents MUST include the id
property.
id
MUST be a single valid DID.
{ "id": "did:example:21tDAKCERh95uGgKbJNHYp" }
DID method specifications can create intermediate representations of a
DID document that do not contain the id
key, such as when a
DID resolver is performing resolution. However, the fully resolved
DID document always contains a valid id
property. The value
of id
in the resolved DID document is expected to match the
DID that was resolved.
A DID document can express cryptographic keys and other verification methods, which can be used to authenticate or authorize interactions with the DID subject or associated parties. The information expressed often includes globally unambiguous identifiers and public key material, which can be used to verify digital signatures. Other information can be expressed, such as status information for the key (for example, whether it is suspended or revoked), or other attributes that enable one to determine whether it is a hardware-backed cryptographic key.
Regarding cryptographic key material, public keys can be included in a
DID document using, for example, the publicKey
or
authentication
properties, depending on what they are to be used
for. Each public key has an identifier (id
) of its own, a
type
, and a controller
, as well as other properties
that depend on the type of key it is.
This specification strives to limit the number of formats for expressing public key material in a DID Document to the fewest possible, to increase the likelihood of interoperability. The fewer formats that implementers have to implement, the more likely it will be that they will support all of them. This approach attempts to strike a delicate balance between ease of implementation and supporting formats that have historically had broad deployment. The specific types of key formats that are supported in this specification are listed below.
A public key is a verification method. Public keys are used for digital signatures, encryption and other cryptographic operations, which in turn are the basis for purposes such as authentication (see Section § 7.4 Authentication) or establishing secure communication with service endpoints (see Section § 7.6 Service Endpoints). As well, public keys can play a role in authorization mechanisms of DID method operations (see Section § 9.2 Method Operations), which can be defined by DID method specifications.
A public key is just one type of verification method. A DID
document expresses the relationship between the DID subject and a
verification method using a verification relationship.
Examples of verification relationships include:
authentication
, capabilityInvocation
,
capabilityDelegation
, keyAgreement
, and
assertionMethod
. A DID controller MUST be explicit about the
verification relationship between the DID subject and the verification
method. Verification methods that are not associated with a
particular verification relationship MUST NOT be used for that
verification relationship. See Section § 7.4 Authentication
for a more detailed example of a verification relationship.
A DID document MAY include a publicKey
property.
publicKey
property, the value
of the property MUST be an array of public key objects. Each public key object
MUST have the type
, controller
, and specific public
key properties, and MUST have an id
property. The public key
objects MAY include additional properties.
The value of the id
property MUST be a URI. The
array of public keys MUST NOT contain multiple entries with the same
id
. In this case, a DID document processor MUST produce an
error.
The value of the type
property MUST be exactly one public key type.
For a registry of available key types and formats, see Appendix
§ A.
Interoperability Registries
.
The value of the controller
property, which identifies the
controller of the corresponding private key, MUST be a valid DID.
The semantics of the controller
property are the same when the
subject of the relationship is the DID document as when the subject
of the relationship is a key. Since a key can't control itself, and the
key controller cannot be inferred from the DID document, it is
necessary to explicitly express the identity of the controller of the key
(which may be the DID controller or DID subject). The
difference is that the value of controller
on a key is not
necessarily a DID controller. DID controller(s) are
expressed using the controller
property on the top level of
the DID document; see Section § 7.5
Authorization and Delegation
.
The value of the id
property MAY be structured as a compound key.
This is especially useful for integrating with existing key management systems and key formats such as JWK.
It is RECOMMENDED that JWK kid
values are set to the public key fingerprint.
It is RECOMMENDED that verification methods that use JWKs to represent their
public keys utilize the value of kid
as their fragment identifier.
See the first key in EXAMPLE 11 for an example of a public key with a compound key identifier.
All public key properties MUST be from the Linked Data Cryptographic Suite Registry. For a registry of key types and formats, see Appendix § A. Interoperability Registries .
If a public key does not exist in the DID document, it MUST be assumed the key was revoked or is invalid. The DID document MAY contain revoked keys. A DID document containing a revoked key MUST also contain or refer to the revocation information for the key (for example, a revocation list). Each DID method specification is expected to detail how revocation is performed and tracked.
Public keys of all types MUST be expressed in either JSON Web Key (JWK) format
using the publicKeyJwk
property or one of the formats listed in the
table below. Public key expression MUST NOT use any other key format.
The Working Group is still debating whether the base encoding format used will be Base58 (Bitcoin) [BASE58], base64url [RFC7515], or base16 (hex) [RFC4648]. The entries in the table below currently assume PEM and Base58 (Bitcoin), but might change to base64url and/or base16 (hex) after the group achieves consensus on this particular issue.
The Working Group is still debating whether secp256k1 Schnorr public key values will be elaborated upon in this specification and if so, how they will be expressed and encoded.
Key Type | Support |
---|---|
RSA |
RSA public key values MUST either be encoded as a JWK or be encoded in
Privacy Enhanced Mail (PEM) format using the publicKeyPem property.
|
ed25519 |
Ed25519 public key values MUST either be encoded as a JWK or be encoded as
the raw 32-byte public key value in Base58 Bitcoin format using the
publicKeyBase58 property.
|
secp256k1-koblitz |
Secp256k1 Koblitz public key values MUST either be encoded as a JWK or be
encoded as the raw 33-byte public key value in Base58 Bitcoin format using the
publicKeyBase58 property.
|
secp256r1 |
Secp256r1 public key values MUST either be encoded as a JWK or be encoded as
the raw 32-byte public key value encoded in Base58 Bitcoin format using the
publicKeyBase58 property.
|
Curve25519 |
Curve25519 (also known as X25519) public key values MUST either be encoded as
a JWK or be encoded as the raw 32-byte public key value in Base58 Bitcoin format
using the publicKeyBase58 property.
|
Example:
{ "@context": ["https://www.w3.org/ns/did/v1", "https://w3id.org/security/v1"], "id": "did:example:123456789abcdefghi", ... "publicKey": [{ "id": "did:example:123#_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A", "type": "JwsVerificationKey2020", "controller": "did:example:123", "publicKeyJwk": { "crv": "Ed25519", "x": "VCpo2LMLhn6iWku8MKvSLg2ZAoC-nlOyPVQaO3FxVeQ", "kty": "OKP", "kid": "_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A" } }, { "id": "did:example:123456789abcdefghi#keys-1", "type": "RsaVerificationKey2018", "controller": "did:example:123456789abcdefghi", "publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n" }, { "id": "did:example:123456789abcdefghi#keys-2", "type": "Ed25519VerificationKey2018", "controller": "did:example:pqrstuvwxyz0987654321", "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV" }, { "id": "did:example:123456789abcdefghi#keys-3", "type": "Secp256k1VerificationKey2018", "controller": "did:example:123456789abcdefghi", "publicKeyHex": "02b97c30de767f084ce3080168ee293053ba33b235d7116a3263d29f1450936b71" }], ... }
A key MAY be embedded or referenced in a DID document.
For example, the authentication
property might refer to keys in
both ways, as shown in the example below.
{ ... "authentication": [ // this key is referenced, it may be used with more than one verification relationship "did:example:123456789abcdefghi#keys-1", // this key is embedded and may *only* be used for authentication { "id": "did:example:123456789abcdefghi#keys-2", "type": "Ed25519VerificationKey2018", "controller": "did:example:123456789abcdefghi", "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV" } ], ... }
The steps to use when processing a publicKey
property in a
DID document are:
publicKey
property and initialize result to null
.
publicKey
properties
associated with the URL. For example, process the publicKey
property at the top-level of the dereferenced document.
id
property of the
object matches value, set result to the object.
id
,
type
, and controller
properties, as well as any
mandatory public cryptographic material, as determined by the type
property of result, throw an error.
Caching and expiration of the keys in a DID document is entirely the responsibility of DID resolvers and other clients. For more information, see Section § 10. Resolution .
Authentication is a mechanism by which an entity can prove it is the DID subject. The verifier of an authentication attempt can check if the authenticating party is presenting a valid proof of authentication, that is, that they are who they say they are. Note that a successful authentication on its own may or may not confer authority; that is up to the verifying application.
If authentication is established, it is up to the DID method or other application to decide what to do with that information. A particular DID method could decide that authenticating as a DID controller is sufficient to, for example, update or delete the DID document. Another DID method could require different keys, or a different verification method entirely, to be presented in order to update or delete the DID document than that used to authenticate. In other words, what is done after the authentication check is out of scope for the DID data model, but DID methods and applications are expected to define this themselves.
A DID document MAY include an authentication
property.
authentication
property is a relationship between the
DID subject and a set of verification methods (such as, but not
limited to, public keys). It means that the DID subject has authorized
some set of verification methods (per the value of the
authentication
property) for the purpose of authentication. The value
of the authentication
property SHOULD be an array of
verification methods. Each verification method MAY be embedded
or referenced. An example of a verification method is a public key
(see Section § 7.3 Public Keys).
This statement is useful to any "authentication verifier" that needs to check
to see if an entity that is attempting to authenticate is, in fact, presenting
a valid proof of authentication. When a verifier receives some data (in some
protocol-specific format) that contains a proof that was made for the purpose
of "authentication", and that says that an entity is identified by the DID,
then that verifier checks to ensure that the proof can be verified using a
verification method (e.g., public key) listed under
authentication
in the DID Document.
The verification method indicated by the authentication
property of a DID document can only be used to authenticate the
DID subject. To authenticate the DID controller (in cases
where the DID controller is not also the DID subject)
the entity associated with the value of controller
(see
Section § 7.5
Authorization and Delegation
) needs to
authenticate itself with its own DID document and attached
authentication
verification method relationship.
Example:
{ "@context": "https://www.w3.org/ns/did/v1", "id": "did:example:123456789abcdefghi", ... "authentication": [ // this method can be used to authenticate as did:...fghi "did:example:123456789abcdefghi#keys-1", // this method can be used to authenticate as did:...fghi "did:example:123456789abcdefghi#biometric-1", // this method is *only* authorized for authentication, it may not // be used for any other proof purpose, so its full description is // embedded here rather than using only a reference { "id": "did:example:123456789abcdefghi#keys-2", "type": "Ed25519VerificationKey2018", "controller": "did:example:123456789abcdefghi", "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV" } ], ... }
Service endpoints are used in DID documents to express ways of communicating with the DID subject or associated entities. Services listed in the DID document can contain information about privacy preserving messaging services, or more public information, such as social media accounts, personal websites, and email addresses. The metadata associated with services are often service-specific. For example, the metadata associated with an encrypted messaging service can express how to initiate the encrypted link before messaging begins.
Pointers to services are expressed using the service
property.
Each service has its own id
and type
, as well as a
serviceEndpoint
with a URI or other properties describing
the service.
One of the primary purposes of a DID document is to enable discovery of service endpoints. A service endpoint can be any type of service the DID subject wants to advertise, including decentralized identity management services for further discovery, authentication, authorization, or interaction.
A DID document MAY include a service
property.
service
property, the value of
the property SHOULD be an array of service endpoint objects. Each
service endpoint MUST have id
, type
, and
serviceEndpoint
properties, and MAY include additional properties.
The value of the id
property MUST be a URI.
The array of service endpoints MUST NOT contain multiple entries
with the same id
. In this case, a DID document processor
MUST produce an error.
The value of the serviceEndpoint
property MUST be a JSON-LD object
or a valid URI conforming to [RFC3986] and normalized according to the
rules in section 6 of [RFC3986] and to any normalization rules in its
applicable URI scheme specification.
It is expected that the service endpoint protocol is published in an open standard specification.
{ "service": [{ "id": "did:example:123456789abcdefghi#openid", "type": "OpenIdConnectVersion1.0Service", "serviceEndpoint": "https://openid.example.com/" }, { "id": "did:example:123456789abcdefghi#vcr", "type": "CredentialRepositoryService", "serviceEndpoint": "https://repository.example.com/service/8377464" }, { "id": "did:example:123456789abcdefghi#xdi", "type": "XdiService", "serviceEndpoint": "https://xdi.example.com/8377464" }, { "id": "did:example:123456789abcdefghi#agent", "type": "AgentService", "serviceEndpoint": "https://agent.example.com/8377464" }, { "id": "did:example:123456789abcdefghi#hub", "type": "IdentityHub", "publicKey": "did:example:123456789abcdefghi#key-1", "serviceEndpoint": { "@context": "https://schema.identity.foundation/hub", "type": "UserHubEndpoint", "instances": ["did:example:456", "did:example:789"] } }, { "id": "did:example:123456789abcdefghi#messages", "type": "MessagingService", "serviceEndpoint": "https://example.com/messages/8377464" }, { "id": "did:example:123456789abcdefghi#inbox", "type": "SocialWebInboxService", "serviceEndpoint": "https://social.example.com/83hfh37dj", "description": "My public social inbox", "spamCost": { "amount": "0.50", "currency": "USD" } }, { "id": "did:example:123456789abcdefghi#authpush", "type": "DidAuthPushModeVersion1", "serviceEndpoint": "http://auth.example.com/did:example:123456789abcdefg" }] }
For more information about security considerations regarding authentication service endpoints see Sections § 9.1 Method Schemes and § 7.4 Authentication.
A DID document SHOULD include a created
property.
created
property, the value of
the property MUST be a valid XML datetime value, as defined in section 3.3.7 of
W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes
[XMLSCHEMA11-2]. This datetime value MUST be normalized to UTC 00:00, as
indicated by the trailing "Z".
{ "created": "2002-10-10T17:00:00Z" }
Standard metadata for identifier records includes a timestamp of the most recent change.
A DID document SHOULD include an updated
property.
updated
property, the value of
the property MUST follow the same formatting rules as the created
property, as outlined in Section § 7.7 Created.
{ "updated": "2016-10-17T02:41:00Z" }
A proof
on a DID document is cryptographic proof of the
integrity of the DID document according to either the:
This proof is NOT proof of the binding between a DID and a DID document. For more information, see Section § 11.2 Binding of Identity .
A DID document MAY include a proof
property.
proof
property, the value of
the property MUST be a valid JSON-LD proof, as defined by Linked Data Proofs
[LD-PROOFS].
{ "proof": { "type": "LinkedDataSignature2015", "created": "2016-02-08T16:02:20Z", "creator": "did:example:8uQhQMGzWxR8vw5P3UWH1ja#keys-1", "signatureValue": "QNB13Y7Q9...1tzjn4w==" } }
All concrete representations of a DID document MUST be serialized using a deterministic mapping that is able to be unambiguously parsed into the data model defined in this specification. All serialization methods MUST define rules for the bidirectional translation of a DID document both into and out of the representation in question. As a consequence, translation between any two representations MUST be done by parsing the source format into a DID document model (described in Sections § 6. Data Model and § 3.3 DID Documents) and then serializing the DID document model into the target representation. An implementation MUST NOT convert between representations without first parsing to a DID document model.
Although syntactic mappings are provided for JSON, JSON-LD, and CBOR here, applications and services MAY use any other data representation syntax that is capable of expressing the data model, such as XML or YAML.
Producers MUST indicate which representation of a document has been used via a media type in the document's metadata. Consumers MUST determine which representation a document is in via a media type in the document's metadata. Consumers MUST NOT determine the representation of a document through its content alone.
This requirement depends on the return of DID document metadata that still needs to be defined by this specification. Once defined, that should be linked from here.
The production and consumption rules in this section apply to all implementations seeking to be fully compatible with independent implementations of the specification. Deployments of this specification MAY use a custom agreed-upon representation, including localized rules for handling properties not listed in the registry. See section ?? on Extensibility for more information.
A link to a section on extensibility and conformance as it applies to data representations should be added here once that section has been written.
When producing and consuming DID documents that are in plain JSON (as noted by the document metadata), the following rules MUST be followed.
A DID document MUST be a single JSON object conforming to [RFC8259]. All top-level properties of the DID document MUST be represented by using the property name as the name of the member of the JSON object. The values of properties of the data model described in Section § 6. Data Model, including all extensions, MUST be encoded in JSON [RFC8259] by mapping property values to JSON types as follows:
In this section we use the term "property name" to refer to the string that represents the property itself, but this specification still needs to define a concrete term for such aspects of a property of a DID document.
An "empty" value is not specified by this document. It seems to imply a null value, but this is unclear.
All properties of the DID document MUST be included in the root object. Properties MAY define additional data sub structures subject to the value representation rules in the list above.
The member name @context
MUST NOT be used as this property is reserved
for JSON-LD producers.
In this section and we use the term "property name" to refer to the string that represents the property itself, but this specification still needs to define a concrete term for such aspects of a property of a DID document. We also need a concrete term for "the document itself" as opposed to "the collection or properties of the document".
The top-level element MUST be a JSON object. Any other data type at the top level is an error and MUST be rejected. The top-level JSON object represents the DID document, and all members of this object are properties of the DID document. The object member name is the property name, and the member value is interpreted as follows:
An "empty" value is not specified by this document. It seems to imply a null value, but this is unclear.
The value of the @context
object member MUST be ignored as this is
reserved for JSON-LD consumers.
Unknown object member names MUST be ignored as unknown properties.
This specification needs to define clear and consistent rules for how to handle unknown data members on consumption, and this section needs to be updated with that decision.
[JSON-LD] is a JSON-based format used to serialize Linked Data.
When producing and consuming DID documents that are in JSON-LD (as noted by the document metadata), the following rules MUST be followed.
@id
and @type
keywords are aliased to
id
and type
respectively, enabling developers to use
this specification as idiomatic JSON.
id
MUST be a valid DID and not any other kind of IRI.
The DID document is serialized following the rules in the JSON processor, with
one addition: DID documents MUST include the @context
property.
@context
property MUST be one or more URIs,
where the value of the first URI is
https://www.w3.org/ns/did/v1
. All members of the @context
property MUST exist be in the DID properties extension registry.
This specification defines globally interoperable documents, and the requirement that the context value be in the DID registry means that different JSON-LD processors can consume the document without having to dereference anything in the context field. However, a pair of producers and consumers can have local extension agreements. This needs to be clarified in a section on extensibility and linked here when available.
The top-level element MUST be a JSON object. Any other data type at the top
level is an error and MUST be rejected. This top-level JSON object is interpreted
using JSON-LD processing under the rules of the defined @context
fields.
@context
property MUST be one or more URIs,
where the value of the first URI is
https://www.w3.org/ns/did/v1
. If more than one URI is
provided, the URIs MUST be interpreted as an ordered set. It is
RECOMMENDED that dereferencing each URI results in a document containing
machine-readable information about the context.
Unknown object member names MUST be ignored as unknown properties.
This specification needs to define clear and consistent rules for how to handle unknown data members on consumption, and this section needs to be updated with that decision.
A DID method specification MUST define exactly one method-specific
DID scheme, identified by exactly one method name. For more information,
see the method-name
rule in Section
§ 5.1.1 Generic DID Syntax.
Because the method name is part of the DID, short method names are preferred; the method name SHOULD be five characters or less. The method name might reflect the name of the DID registry to which the DID method specification applies. For more information, see Section § 9.1 Method Schemes.
The DID method specification for the method-specific DID scheme
MUST specify how to generate the method-specific-id
component of a
DID. The method-specific-id
value MUST be able to be
generated without the use of a centralized registry service. The
method-specific-id
value SHOULD be globally unique by itself. The
DID, as defined by the did
rule in Section
§ 5.1.1 Generic DID Syntax, MUST be globally unique.
If needed, a method-specific DID scheme MAY define multiple
method-specific-id
formats. It is RECOMMENDED that a
method-specific DID scheme define as few method-specific-id
formats as possible.
The method-specific-id
format MAY include colons, which might be
used by DID methods for various purposes, such as establishing
hierarchically partitioned namespaces, or identifying specific instances or
parts of the DID registry. The use of colons MUST comply syntactically
with the method-specific-id
ABNF rule and their use is entirely
method-specific. Implementers are advised to avoid
assuming any meanings or behaviors associated with a colon that are
generically applicable to all DID methods.
The authors of a new DID method specification SHOULD use a method name that is unique among all DID method names known to them at the time of publication.
Because there is no central authority for allocating or approving DID method names, there is no way to know for certain if a specific DID method name is unique. To help with this challenge, the W3C Credentials Community Group maintains a non-authoritative list of known DID method names and their associated specifications. For more information, see Appendix § A. Interoperability Registries .
The [DID-METHOD-REGISTRY] is a tool for implementors to use when coming to consensus on a new method name, as well as an informative reference for software developers implementing DID resolvers for different DID methods. For more information about DID resolvers see Section § 10. Resolution . The [DID-METHOD-REGISTRY] is not a definitive or official list of DID methods. Nonetheless, adding DID method names to the [DID-METHOD-REGISTRY] is encouraged so that other implementors and members of the community have a place to see an overview of existing DID methods. The lightweight criteria for inclusion are documented in the [DID-METHOD-REGISTRY].
To enable the full functionality of DIDs and DID documents on a particular DID registry, a DID method specification MUST specify how a client might be used to perform the create, read, update, and deactivate operations. Each operation ought to be specified to the level of detail necessary to build and test interoperable client implementations. In the event that an operation is not supported, such as update or deactivate, then it is RECOMMENDED that the DID Method specification state that it is not supported. These operations can be used to perform all the operations required of a cryptographic key management system (CKMS), e.g.: key registration, key replacement, key rotation, key recovery, and key expiration.
Determining the authority of a party to carry out the operations is method-specific. For example, a DID method MAY:
The DID method specification MUST specify how a client creates a DID and its associated DID document on the DID registry, including all cryptographic operations necessary to establish proof of control.
The DID method specification MUST specify how a client uses a DID to request a DID document from the DID registry, including how the client can verify the authenticity of the response.
The DID method specification MUST specify how a client can update a DID document on the DID registry, including all cryptographic operations necessary to establish proof of control, or state that updates are not possible.
An update to a DID is any change, after creation, in the data used to produce a DID document. DID Method implementers are responsible for defining what constitutes an update, and what properties of the DID document are supported by a given DID method. For example, an update operation which replaces key material without changing it could be a valid update that does not result in changes to the DID document.
The DID method specification MUST specify how a client can deactivate a DID on the DID registry, including all cryptographic operations necessary to establish proof of deactivation, or state that deactivation is not possible.
DID method specifications MUST include their own Security Considerations sections. This section MUST consider all the requirements mentioned in section 5 of [RFC3552] (page 27) for the DID operations defined in the specification.
At least the following forms of attack MUST be considered: eavesdropping, replay, message insertion, deletion, modification, and man-in-the-middle. Potential denial of service attacks MUST be identified as well.
If the protocol incorporates cryptographic protection mechanisms, the DID method specification MUST clearly indicate which portions of the data are protected and what the protections are, and SHOULD give an indication to what sorts of attacks the cryptographic protection is susceptible. For example, integrity only, confidentiality, endpoint authentication, and so on.
Data which is to be held secret (keying material, random seeds, and so on) SHOULD be clearly labeled.
If the technology involves authentication, particularly user-host authentication, the security of the authentication method MUST be clearly specified.
This section MUST discuss, per Section 5 of [RFC3552], residual risks (such as the risks from compromise in a related protocol, incorrect implementation, or cipher) after threat mitigation was deployed.
This section MUST provide integrity protection and update authentication for all operations required by Section § 9.2 Method Operations.
Where DID methods make use of 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.
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.
DID methods MUST discuss the policy mechanism by which DIDs are proven to be uniquely assigned. A DID fits the functional definition of a URN, as defined in [RFC8141]. That is, a DID is a persistent identifier that is assigned once to a resource and never reassigned to a different resource. This is particularly important in a security context because a DID might be used to identify a specific party subject to a specific set of authorization rights.
DID methods that introduce new authentication service endpoint types (see Section § 7.6 Service Endpoints) SHOULD consider the security requirements of the supported authentication protocol.
DID method specifications MUST include their own Privacy Considerations sections, if only to point to § 12. Privacy Considerations .
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, exclusion.
A DID resolver is a software or hardware component with an API for resolving DIDs of at least one DID method. It executes the read operation for the DID method corresponding to the DID being resolved to obtain the authoritative DID document. For more information, see Section § 9.2.2 Read/Verify .
The interfaces and algorithms for resolving DIDs and dereferencing DID URLs are specified in [DID-RESOLUTION].
This section is non-normative.
During the Working Draft stage, this section focuses on security topics that should be important in early implementations. The editors are seeking feedback on threats and threat mitigations that should be reflected in this section or elsewhere in the spec. DIDs are designed to operate under the general Internet threat model used by many IETF standards. We assume uncompromised endpoints, but anticipate that messages could be read or corrupted on the network. Protecting against an attack when a system is compromised requires external key-signing hardware (see Section § 11.7 Key Revocation and Recovery ).
The [DID-METHOD-REGISTRY] is an informative list of DID method names and their corresponding DID method specifications. Implementors 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, but can use the [DID-METHOD-REGISTRY] to make an informed decision when choosing which DID resolver implementations to use.
The following sections describe binding identities to DIDs and DID documents.
Signatures are one way to allow DID documents to be cryptographically verifiable.
By itself, a verified signature on a self-signed DID document does not prove control of a DID. It only proves that the:
Proving control of a DID, that is, the binding between the DID and the DID document that describes it, requires a two step process:
id
property of the resulting DID document
matches the DID that was resolved.
It should be noted that this process proves control of a DID and DID document regardless of whether the DID document is signed.
Signatures on DID documents are optional. DID method specifications SHOULD explain and specify their implementation if applicable.
It is good practice to combine timestamps with signatures.
There are two methods for proving control of the private key corresponding to a public key description in the DID document: static and dynamic.
The static method is to sign the DID document with the private key. This proves control of the private key at a time no later than the DID document was registered. If the DID document is not signed, control of a public key described in the DID document can still be proven dynamically as follows:
A DID and DID document do not inherently carry any PII (personally-identifiable information). The process of binding a DID to something in the real world, such as a person or a company, for example with credentials with the same subject as that DID, is out of scope for this specification. For more information, see the [VC-DATA-MODEL] instead.
If a DID document publishes a service endpoint intended for authentication or authorization of the DID subject (see Section § 7.6 Service Endpoints), it is the responsibility of the service endpoint provider, subject, or relying party to comply with the requirements of the authentication protocols supported at that service endpoint.
Non-repudiation of DIDs and DID document updates is supported under the assumption that the subject:
Non-repudiation is further supported if timestamps are included (see Sections § 7.7 Created and § 7.8 Updated) and the target DLT system supports timestamps.
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, where there is no intermediary registrar or account provider to generate the notification, the following approaches are suggested:
In a decentralized identifier architecture, there are no centralized authorities to enforce key or signature expiration policies. Therefore DID resolvers and other client applications need to validate that keys were not expired at the time they were used. Because some use cases might have legitimate reasons why already-expired keys can be extended, make sure a key expiration does not prevent any further use of the key, and implementations of a resolver ought to be compatible with such extension behavior.
Section § 9.2 Method Operations specifies the DID operations to be supported by a DID method specification, including deactivation of a DID document by replacing it with an updated DID document. It is also up to the DID method to define how revocation of cryptographic keys might occur. Additionally, DID method specifications are also expected to enable support for a quorum of trusted parties to enable key recovery. Some of the facilities to do so are suggested in Section § 7.5 Authorization and Delegation . 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 key 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. Further specification of this type of control is a matter for future work (see Section § D.4 Time Locks and DID Document Recovery ).
DIDs achieve global uniqueness without the need for a central registration authority. This comes, however, at the cost of human memorability. The algorithms capable of generating globally unique identifiers automatically produce random strings of characters that have no human meaning. This demonstrates the axiom about identifiers described in Zooko's Triangle: "human-meaningful, decentralized, secure — pick any two".
There are of course many 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, Twitter handle, 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 (and there are many) should be defined in separate specifications that reference this specification. It is strongly recommended that such specifications carefully consider the:
Many cybersecurity abuses hinge on exploiting gaps between reality and the assumptions of rational, good-faith actors. Like any ecosystem, the DID ecosystem has some potential for this to occur. Because this specification is focused on a data model instead of a protocol, it offers no opinion about many aspects of how that model is put to use. However, individual DID methods might want 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 the flexibility that the data model offers with respect
to updating. A single edit to a DID document can change anything and
everything except the root id
property of the document. And any
individual JSON object in the data model can change all of its properties except
its id
. But is it actually desirable for a service endpoint
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 web site
often aim for an outcome where the site keeps its identifier (the host name),
but gets subtle, dangerous changes underneath. If certain properties of the site
were required by the specification to be immutable (for example, the
ASN
associated with its IP address), such attacks might be much harder and more
expensive to carry out, and anomaly detection would be easier.
The notion that immutability provides some cybersecurity benefits is particularly relevant because of caching. 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 client 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.
DID documents are typically publicly available. 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.
Encrypting all or parts of DID documents is not an appropriate means to protect data in the long term. Similarly, placing encrypted data in DID documents is not an appropriate means to include personally identifiable information.
Given the caveats above, if encrypted data is included in a DID document, implementers are advised to not encrypt with the public keys of entities that do not wish to be correlated with the DID.
This section is non-normative.
It is critically important to apply the principles of Privacy by Design to all aspects of the decentralized identifier architecture, because DIDs and DID documents are, by design, administered directly by the DID controller(s). There is no registrar, hosting company, or other intermediate service provider to recommend or apply additional privacy safeguards. The authors of this specification have applied all seven Privacy by Design principles throughout its development. For example, privacy in this specification is preventative not remedial, and privacy is an embedded default. Furthermore, the decentralized identifier architecture by itself embodies principle #7, "Respect for user privacy — keep it user-centric."
This section lists additional privacy considerations that implementers, delegates, and DID subjects should keep in mind.
If a DID method specification is written for a public DID registry where all DIDs and DID documents are publicly available, it is critical that DID documents contain no PII. All PII should be kept behind service endpoints under the control of the DID subject. With this privacy architecture, PII can be exchanged on a private, peer-to-peer basis using communications channels identified and secured by public key descriptions in DID documents. This also enables DID subjects and relying parties to implement the GDPR right to be forgotten, because no PII is written to an immutable distributed ledger.
Like any type of globally unique identifier, DIDs might be used for correlation. DID controllers can mitigate this privacy risk by using pairwise unique DIDs, that is, sharing a different private DID for every relationship. In effect, each DID acts as a pseudonym. A pseudonymous DID need only be shared with more than one party when the DID subject explicitly authorizes correlation between those parties. If pseudonymous DIDs are the default, then the only need for a public DID (a DID published openly or shared with a large number of parties) is when the DID subject explicitly desires public identification.
The anti-correlation protections of pseudonymous DIDs are easily defeated if the data in the corresponding DID documents can be correlated. For example, using same public key descriptions 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 pseudonymous DID also needs to use pairwise unique public keys. It might seem natural to also use pairwise unique service endpoints in the DID document for a pseudonymous 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 thousands or millions of DIDs controlled by many different subjects.
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 client implementations, keep negotiated options to a minimum on wire protocols, use encrypted transport layers, and pad messages to standard lengths.
There are multiple registries that define DID methods and extensions to this specification. These registries are:
Registry | Purpose |
---|---|
DID Method Registry | Lists all known DID methods and contains links to their specifications. |
Linked Data Cryptography Suite Registry | Defines all known Linked Data Cryptography Suites and Key Formats. |
A future-facing real-world context is provided below:
{ "@context": "https://w3id.org/future-method/v1", "id": "did:example:123456789abcdefghi", "publicKey": [{ "id": "did:example:123456789abcdefghi#keys-1", "type": "RsaVerificationKey2018", "controller": "did:example:123456789abcdefghi", "publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n" }, { "id": "did:example:123456789abcdefghi#keys-3", "type": "Ieee2410VerificationKey2018", "controller": "did:example:123456789abcdefghi", "publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n" }], "authentication": [ // this mechanism can be used to authenticate as did:...fghi "did:example:123456789abcdefghi#keys-1", // this mechanism can be used to biometrically authenticate as did:...fghi "did:example:123456789abcdefghi#keys-3", // this mechanism is *only* authorized for authentication, it may not // be used for any other proof purpose, so its full description is // embedded here rather than using only a reference { "id": "did:example:123456789abcdefghi#keys-2", "type": "Ed25519VerificationKey2018", "controller": "did:example:123456789abcdefghi", "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV" } ], "service": [{ "id": "did:example:123456789abcdefghi#oidc", "type": "OpenIdConnectVersion1.0Service", "serviceEndpoint": "https://openid.example.com/" }, { "id": "did:example:123456789abcdefghi#vcStore", "type": "CredentialRepositoryService", "serviceEndpoint": "https://repository.example.com/service/8377464" }, { "id": "did:example:123456789abcdefghi#xdi", "type": "XdiService", "serviceEndpoint": "https://xdi.example.com/8377464" }, { "id": "did:example:123456789abcdefghi#hub", "type": "HubService", "serviceEndpoint": "https://hub.example.com/.identity/did:example:0123456789abcdef/" }, { "id": "did:example:123456789abcdefghi#messaging", "type": "MessagingService", "serviceEndpoint": "https://example.com/messages/8377464" }, { "type": "SocialWebInboxService", "id": "did:example:123456789abcdefghi#inbox", "serviceEndpoint": "https://social.example.com/83hfh37dj", "description": "My public social inbox", "spamCost": { "amount": "0.50", "currency": "USD" } }, { "type": "DidAuthPushModeVersion1", "id": "did:example:123456789abcdefghi#push", "serviceEndpoint": "http://auth.example.com/did:example:123456789abcdefghi" }, { "id": "did:example:123456789abcdefghi#bops", "type": "BopsService", "serviceEndpoint": "https://bops.example.com/enterprise/" }] }
The list of issues below are under active discussion and are likely to result in changes to this specification.
initial-values
matrix parameter to Generic DID ParametersThe current specification does not take a position on maximum length of a DID. The maximum interoperable URL length is currently about 2K characters. QR codes can handle about 4K characters. Clients using DIDs will be responsible for storing many DIDs, and some methods would be able to externalize some of their costs onto clients by relying on more complicated signature schemes or by adding state into DIDs intended for temporary use. A future version of this specification should set reasonable limits on DID character length to minimize externalities.
Including an equivalence property, such as equivID
, in DID documents
whose value is an array of DIDs would allow subjects to assert two or
more DIDs that represent the same subject. This capability has
numerous uses, including supporting migration between DID registries and
providing forward compatibility of existing DIDs to future DID
registries. In
theory, equivalent DIDs should have the same identifier rights,
allowing verifiable claims
made against one DID to apply to equivalent DIDs. Equivalence was not
included in the current specification due to the complexity of
verifying equivalence across different DLTs and different DID
methods, and also of aggregating properties of equivalent DID
documents. However equivalence should be supported in a future
version of this specification.
Verifiable timestamps have significant utility for identifier records. This is a good fit for DLTs, since most offer some type of timestamp mechanism. Despite some transactional cost, they are the most censorship-resistant transaction ordering systems in the world, so they are nearly ideal for DID document timestamping. In some cases a DLT's immediate timing is approximate, however their sense of "median time past" (see Bitcoin BIP 113) can be precisely defined. A generic DID document timestamping mechanism could would work across all DLTs and might operate via a mechanism including either individual transactions or transaction batches. The generic mechanism was deemed out of scope for this version, although it may be included in a future version of this specification.
Section § 11.7 Key Revocation and Recovery mentions one possible clever use of time locks to recover control of a DID after a key compromise. The technique relies on an ability to override the most recent update to a DID document with Authorization applied by an earlier version of the DID document in order to defeat the attacker. This protection depends on adding a time lock (see Bitcoin BIP 65) to protect part of the transaction chain, enabling a Authorization block to be used to recover control. We plan to add support for time locks in a future version of this specification.
Not all DLTs can support the Authorization logic in section § 7.5 Authorization and Delegation . Therefore, in this version of the specification, all Authorization logic is delegated to DID method specifications. A potential future solution is a Smart Signature specification that specifies the code any conformant DLT may implement to process signature control logic.
Although DIDs and DID documents form a foundation for decentralized identity, they are only the first step in describing their subjects. The rest of the descriptive power comes through collecting and selectively using Verifiable Credentials [VC-DATA-MODEL]. Future versions of the specification will describe in more detail how DIDs and DID document can be integrated with — and help enable — the Verifiable Credentials ecosystem.
This version of the specification relies on JSON-LD and the RDF graph model for expressing a DID document. Future versions of this specification might specify other semantic graph formats for a DID document.
The following text was previously in the section on serialized representations. It has been moved to this appendix to allow the text to be re-incorporated into the document in more appropriate sections or removed entirely, as required by the working group.
[JSON-LD] is a JSON-based format used to serialize Linked Data. The syntax is designed to easily integrate into deployed systems already using JSON, and provides a smooth upgrade path from JSON to JSON-LD. It is primarily intended to be a way to use Linked Data in Web-based programming environments, to build interoperable Web services, and to store Linked Data in JSON-based storage engines.
JSON-LD is useful when extending the data model described in this specification.
Instances of the data model are encoded in JSON-LD in the same way they are
encoded in JSON (see Section § 8.1
JSON
), with the addition of
the @context
property. The
JSON-LD Context
is described in detail in the [JSON-LD] specification and its use is
elaborated on in Section § 6.2 Extensibility.
In general, the data model and syntaxes described in this document are designed such that developers can copy and paste examples into their software systems. The design goal of this approach is to provide a low barrier to entry while still ensuring global interoperability between a heterogeneous set of software systems. This section describes some of these approaches, which will likely go unnoticed by most developers, but whose details will be of interest to implementers. Noteworthy features provided by JSON-LD are:
@id
and @type
keywords are aliased to
id
and type
respectively, enabling developers to use
this specification as idiomatic JSON.
@protected
properties feature of JSON-LD 1.1 is used to ensure
that terms defined by this specification cannot be overridden. This means that
as long as the same @context
declaration is made at the top of a
DID document, interoperability is guaranteed between implementations
that use a JSON-LD processor and implementations that do not.
When two software systems need to exchange data, they need to use terminology
and a protocol that both systems understand. The @context
property ensures that two systems operating on the same DID document are using
mutually agreed terminology.
DID documents MUST include the @context
property.
More information about the JSON-LD Context in general can be found in the [JSON-LD] specification.
@context
property MUST be one or more URIs,
where the value of the first URI is
https://www.w3.org/ns/did/v1
. If more than one URI is
provided, the URIs MUST be interpreted as an ordered set. It is
RECOMMENDED that dereferencing each URI results in a document containing
machine-readable information about the context.
{ "@context": "https://www.w3.org/ns/did/v1" }
DID method specifications MAY define their own JSON-LD contexts. However, it is NOT RECOMMENDED to define a new context unless the context is necessary to properly implement the method. Method-specific contexts MUST NOT override the terms defined in the generic DID context.
One of the goals of the decentralized identifiers data model is to enable permissionless innovation. The data model needs to be extensible in a number of different ways, including:
This approach to data modeling is often called an open worldassumption, meaning that anyone can say anything about any other thing. This approach often seems in conflict with building simple and predictable software systems. Balancing extensibility with program correctness is always more challenging with an open world assumption than it is with closed software systems.
The rest of this section describes how both extensibility and program correctness are achieved through a series of examples.
Let us assume that we start with the following DID document.
{ "@context": "https://example.org/example-method/v1", "id": "did:example:123456789abcdefghi", "publicKey": [{ ... }], "authentication": [{ ... }], "service": [{ ... }] }
The contents of the publicKey
, authentication
, and
service
properties are not important for the purpose of this
section. What is important is that the object above is a valid
DID document. Now assume that a developer wants to extend the
DID document to express an additional piece of information, the subject's
public photo stream.
The first thing that a developer would do is create a JSON-LD Context containing the new term.
{ "@context": { "PhotoStreamService": "https://example.com/vocab#PhotoStreamService" } }
Now that the JSON-LD Context is created, the developer MUST publish it somewhere
that is accessible to any DID document processor. For this example,
assume that the JSON-LD Context above is published at
did:example:contexts:987654321
. At this point, extending the first
example in this section is just a matter of including the context above and
adding the new property to the DID document.
{ "@context": "https://example.org/example-method/v1", "id": "did:example:123456789abcdefghi", "authentication": [ ... ], "service": [{ "@context": "did:example:contexts:987654321", "id": "did:example:123456789abcdefghi#photos", "type": "PhotoStreamService", "serviceEndpoint": "https://example.org/photos/379283" }] }
The examples so far show that it is easy to extend the decentralized identifiers data model in a permissionless and decentralized way. The mechanism also ensures that decentralized identifiers created in this way prevent namespace conflicts and semantic ambiguity.
An extensibility model this dynamic does increase the implementation burden. Software written for such a system needs to determine if accepting DID documents with extensions is acceptable based on the risk profile of the application. Some applications might choose to accept but ignore extensions, others might choose to only accept certain extensions, while highly secure environments might disallow extensions. These decisions are up to the application developers and are specifically not the domain of this specification.
Implementations MUST produce an error when an extension JSON-LD Context
overrides the expanded URL for a term specified in this specification. To avoid
the possibility of accidentally overriding terms, developers SHOULD scope their
extensions. For example, the following extension scopes the new
PhotoStreamService
term so that it can only be used within the
service
property:
{
"@context": {
"service": {
"@id": "https://w3id.org/did#service",
"@context": {
"PhotoStreamService": "https://example.com/vocab#PhotoStreamService"
}
}
}
}
Developers are urged to ensure that extension JSON-LD Contexts are highly available. Implementations that cannot fetch a context will produce an error. Strategies for ensuring that extension JSON-LD Contexts are always available include using content-addressed URLs for contexts, bundling context documents with implementations, or enabling aggressive caching of contexts.
This section will be submitted to the Internet Engineering Steering Group (IESG) for review, approval, and registration with IANA when this specification becomes a W3C Proposed Recommendation.
Fragment identifiers used with application/did+json are treated according to the rules defined in DID Core v1.0, Fragment [DID-CORE].
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].