Abstract

Issue

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

Status of This Document

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.

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.

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.

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.

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.

Note

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:

DIDs from different DID methods might not be interoperable, just
as URIs from different URI schemes might not be interoperable.

Entities might need multiple DIDs to support different relationships
because the other party might only support certain DID methods, in the
same way that some browsers might only support certain URI schemes.

Entities might need multiple DIDs to support the different cryptographic
schemes of different DID methods because not all parties will support the
same cryptographic schemes, in the same way that not all browsers support the
same URI schemes.

Managing multiple DIDs, and tracking which DID belongs to which
relationship, under which cryptographic scheme, introduces similar logistical
challenges as managing multiple web addresses and tracking which address belongs
to which website, or tracking which email address belongs to which relationship.

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.

1.2
Design Goals

This section is non-normative.

Decentralized Identifiers are a component of larger systems, such as
the Verifiable Credentials ecosystem [VC-DATA-MODEL], which 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.

1.3
Interoperability

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.

2.
Terminology

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:

blockchain

A specific type of distributed ledger technology (DLT) that stores ledger
entries in blocks of transactions, which are grouped together and hashed into a
cryptographic chain. Because this type of DLT was introduced by
Bitcoin, the term
blockchain is sometimes used to refer specifically to the Bitcoin
ledger.

decentralized identifier (DID)

A globally unique identifier that does not require a centralized registration
authority because it is registered with distributed ledger technology
(DLT) or other form of decentralized network. The generic format of a DID is
defined in this specification. A specific DID scheme is defined in a
DID method specification.

A set of data describing the DID subject, including mechanisms, such as
public keys and pseudonymous biometrics, that the DID subject can use to
authenticate itself and prove their association with the DID. A DID
document might also contain other
attributes or
claims
describing the subject. These documents are graph-based data structures that
are typically expressed using [JSON-LD], but can be expressed using other
compatible graph-based data formats.

DID fragment

The portion of a DID URL that follows the first hash sign character
(#). DID fragment syntax is identical to the URI fragment syntax.

The portion of a DID URL that begins with and includes the first forward
slash character (/). DID path syntax is identical to the URI path
syntax.

DID query

The portion of a DID URL that follows the first question mark character
(?). DID query syntax is identical to the URI query syntax.

DID registry

A role a system performs to mediate the creation, verification, updating, and
deactivation of decentralized identifiers. A DID registry is a type of
verifiable data registry. For more information, see [VC-DATA-MODEL].

DID resolver

A system that is capable of retrieving a DID document for a given
DID. These systems are specified in the DID Resolution specification
[DID-RESOLUTION].

Defines a string syntax for identifying a specific value within a JavaScript
Object Notation (JSON) document, as defined in [RFC6901].

public key description

A JSON object contained inside a DID document that contains all the
metadata necessary to use a public key or verification key.

resource

The term resource is used in the same way as defined for HTTP in [RFC7231];
that is, a resource is the target of a request and is identified by a URI.
This specification does not limit the nature of a resource, but defines an
interface that might be used to interact with resources when identified by
a DID.

service endpoint

A network address at which a service operates on behalf of a DID subject.
Examples of specific services include discovery services, social networks, file
storage services, and verifiable claim repository services. Service endpoints
might also be provided by a generalized data interchange protocol, such as
extensible data interchange.

The properties present in a DID document can be updated according to
the applicable operations outlined in Section § 9. Methods.

3.4 DID Resolvers and DID Resolution

3.5 Security and Privacy

4. Conformance

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

The key words MAY, MUST, MUST NOT, 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 documentMAY 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.

5. Identifier

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

5.1.4 Persistence

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.

Note

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.

Note

Although not included in this version, future versions of this specification
might support a DID documentequivID 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
.

5.2 DID URL Syntax

5.2.1 Generic DID URL Syntax

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

5.2.2 Generic DID URL Parameters

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.

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.

5.2.3 Method-Specific DID URL Parameters

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.

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.

Review what exactly we want to say about method-specific parameters
defined by one method but used in a DID URL with a different method.
Also discuss hierarchical method namespaces in DID parameter names.

A specific DID schemeMAY 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.

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 § E.2 application/did+ld+json.

5.2.7 Relative DID URLs

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.

7.1
Identifiers

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.

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.

7.3 Public Keys

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.

If a DID document includes a 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 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 JWKkid 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 12 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 documentMAY 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.

Issue

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.

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.

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

Let value be the data associated with the publicKey
property and initialize result to null.

If value is an object, the key material is embedded. Set
result to value.

If value is a string, the key is included by reference. Assume
value is a URL.

Dereference the URL and retrieve the publicKey properties
associated with the URL. For example, process the publicKey
property at the top-level of the dereferenced document.

Iterating through each public key object, if the id property of the
object matches value, set result to the object.

If result does not contain at least the id,
type, and controller properties, as well as any
mandatory public cryptographic material, as determined by the type
property of result, throw an error.

7.4 Authentication

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.

Note: Uses of authentication

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.

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.

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

7.5
Authorization and Delegation

Authorization is the mechanism used to state how operations may be
performed on behalf of the DID subject. Delegation is the
mechanism that the subject uses to authorize others to act
on their behalf.

Note: Authorization vs authentication

Note that Authorization is separate from § 7.4 Authentication.
This is particularly important for key recovery in the case of key loss,
when the subject no longer has access to their keys, or key compromise,
where the DID controller's trusted third parties need to override
malicious activity by an attacker. See Section § 11.
Security Considerations
.

The value of the controller property MUST be a valid DID
or an array of valid DIDs. The corresponding DID document(s)
SHOULD contain authorization relations that explicitly permit the use of
certain verification methods for specific purposes.

Each DID methodMUST define how authorization and delegation are
implemented, including any necessary cryptographic operations.

There are at least two suggested methods for implementing Authorization and
Delegation, which may be layered:

7.6 Service Endpoints

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 although this is discouraged.
See § 12.1
Keep Personally-Identifiable Information (PII) Private
for
additional details. 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.

If a DID document includes a service property, the value of
the property SHOULD be an array of service endpoint objects. Each
service endpointMUST 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 endpointsMUST 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.

8. Core Representations

All concrete representations of a DID documentMUST 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.

8.1
JSON

When producing and consuming DID documents that are in plain JSON (as noted by
the document metadata), the following rules MUST be followed.

8.1.1 Production

A DID documentMUST be a single JSON object conforming to [RFC8259]. All
top-level properties of the DID documentMUST 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.

Numeric values representable as IEEE754 MUST be represented as a Number type.

8.1.2
Consumption

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:

Number typesMUST interpreted as numeric values representable as IEEE754.

String typesMUST be interpreted as Strings, which may be further parsed
depending on the definition of the property for this value into more specific data types such as URIs,
date stamps, or other values.

8.2
JSON-LD

When producing and consuming DID documents that are in JSON-LD (as noted by
the document metadata), the following rules MUST be followed.

The @id and @type keywords are aliased to
id and type respectively, enabling developers to use
this specification as idiomatic JSON.

Even though JSON-LD allows any IRI as node identifiers, DID documents
are explicitly restricted to only describe DIDs. This means that the value of
idMUST be a valid DID and not any other kind of IRI.

Data types, such as integers, dates, units of measure, and URLs, are
automatically typed to provide stronger type guarantees for use cases that
require them.

8.2.1
Production

The DID document is serialized following the rules in the JSON processor, with
one addition: DID documentsMUST include the @context property.

@context

The value of the @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.

8.2.2
Consumption

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

The value of the @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 URIsMUST be interpreted as an ordered set. It is
RECOMMENDED that dereferencing each URI results in a document containing
machine-readable information about the context.

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 schemeMUST 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 schemeMAY 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.

9.2 Method Operations

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 methodMAY:

use other constructs in the DID Document to decide this, for example,
a verification method specified under capabilityInvocation could be used to
verify the invocation of a capability to update the DID Document.; or

not use the DID Document at all to decide this, but have rules that are
"built into" the method.

9.2.1
Create

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.

9.2.2
Read/Verify

9.2.3
Update

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.

9.2.4
Deactivate

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.

9.3 Extensibility

9.4
Security Requirements

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 methodMUST be
discussed.

DID methodsMUST 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.

11.
Security Considerations

This section is non-normative.

Note: Note to implementers

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

11.2.2
Proving Control of a Public Key

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:

11.2.3
Authentication and Verifiable Claims

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.

11.4
Non-Repudiation

Has had adequate opportunity to revert malicious updates according to the
access control mechanism for the DID method (see Section
§ 7.4 Authentication).

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.

11.5
Notification of DID Document Changes

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

In the case of a DID, there is no intermediary registrar or account
provider to generate such notifications. However, if the DID 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 DID registry itself), this introduces another vector of
attack.

11.6
Key and Signature Expiration

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.

11.7
Key Revocation and Recovery

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

11.8
The Role of Human-Friendly Identifiers

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:

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.

Note

A draft specification for discovering a DID from domain names and email
addresses using DNS lookups is available at [DNS-DID].

11.9
Immutability

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.

11.10
Encrypted Data in DID Documents

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.

12.
Privacy Considerations

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.

12.1
Keep Personally-Identifiable Information (PII) Private

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
personal data. All personal data should be kept behind service
endpoints under the control of the DID subject. Additional due
diligence should be taken around the use of URLs in service endpoints as well
to prevent leakage of unintentional personal data or correlation within a URL
of a service endpoint. For example, a URL that contains a username is likely
dangerous to include in a DID Document because the username is likely
to be human-meaningful in a way that can unintentionally reveal information
that the DID subject did not consent to sharing. With this privacy
architecture, personal data 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 GDPRright to be
forgotten, because no personal data is written to an immutable
distributed ledger.

12.2
DID Correlation Risks and Pseudonymous DIDs

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.

12.3
DID Document Correlation Risks

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.

12.4
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 client implementations, keep negotiated options to
a minimum on wire protocols, use encrypted transport layers, and pad messages to
standard lengths.

A.
Interoperability Registries

There are multiple registries that define DID methods and extensions to
this specification. These registries are:

D.
Future Work

D.1
Upper Limits on DID Character Length

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

D.2
Equivalence

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.

D.3
Timestamps

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.

D.4
Time Locks and DID Document Recovery

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.

D.5
Smart Signatures

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.

D.6
Verifiable Credentials

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.

D.7
Alternate Serializations and Graph Models

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.

E.
IANA Considerations

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.

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

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