Copyright © 2020 W3C ® ( MIT , ERCIM , Keio , Beihang ). W3C liability , trademark and permissive document license rules apply.
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. DID s 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.
As individuals and organizations, many of us use globally unique identifiers in a wide variety of contexts. They serve as communications addresses (telephone numbers, email addresses, usernames on social media), ID numbers (for passports, drivers licenses, tax IDs, health insurance), and product identifiers (serial numbers, barcodes, RFIDs). Resources on the Internet are identified by globally unique identifiers in the form of MAC addresses; URIs (Uniform Resource Identfiers) are used for resources on the Web and each web page you view in a browser has a globally unique URL (Uniform Resource Locators).
The vast majority of these globally unique identifiers are not under our control. They are issued by external authorities that decide who or what they identify and when they can be revoked. They are useful only in certain contexts and recognised only by certain bodies (not of our choosing). They may disappear or cease to be valid with the failure of an organization. They may unnecessarily reveal personal information. And in many cases they can be fraudulently replicated and asserted by a malicious third-party ("identity theft").
The Decentralized Identifiers (DIDs) defined in this specification are a new type of globally unique identifier designed to enable individuals and organizations to generate our own identifiers using systems we trust, and to prove control of those identifiers (authenticate) using cryptographic proofs (for example, digital signatures, privacy-preserving biometric protocols, and so on).
Because we control the generation and assertion of these identifiers, each of us can have as many DIDs as we need to respect our desired separation of identities, personas, and contexts (in the everyday sense of these words). We can scope the use of these identifiers to the most appropriate contexts. We can interact with other people, institutions or systems that require us to identify ourselves (or things we control) while maintaining control over how much personal or private data should be revealed, and without depending on a central authority to guarantee the continued existence of the identifier.
This specification does not require any particular technology or cryptography to underpin the generation, persistence, resolution or interpretation of DIDs. Rather, it defines: a) the generic syntax for all DIDs, and b) the generic requirements for performing the four basic CRUD operations (create, read, update, deactivate) on the metadata associated with a DID (called the DID document).
This enables implementers to design specific types of DIDs to work with the computing infrastructure they trust (e.g., blockchain, distributed ledger, decentralized file system, distributed database, peer-to-peer network). The specification for a specific type of DID is called a DID method. Implementers of applications or systems using DIDs can choose to support the DID methods most appropriate for their particular use cases.
This specification is for:
DID methods can also be developed for identifiers registered in federated or centralized identity management systems. Indeed, almost all types of identifier systems can add support for DIDs. This creates an interoperability bridge between the worlds of centralized, federated, and decentralized identifiers.
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 DID controller , as well as services that can be used to interact with the DID subject .
{ "@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 controllers 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. |
This section provides a basic understanding of the major elements of DID architecture. Formal definitions of terms are provided in § 2. Terminology .
id
property.
The
generic
properties
supported
in
a
DID
document
are
specified
in
§
5.
Core
Properties
.
The
properties
present
in
a
DID
document
may
be
updated
according
to
the
applicable
operations
outlined
in
§
7.
Methods
.
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 creating, resolving, updating, and deactivating DIDs and DID documents using a specific type of verifiable data registry .
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.
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 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).
A conforming DID is any concrete expression of the rules specified in Section § 3. 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 § 4. Data Model and § 5. Core Properties . A serialization format for the conforming document MUST be deterministic, bi-directional, and lossless as described in Section § 6. 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 § 7. Methods .
A producer is any algorithm realized as software and/or hardware and conforms to this specification if it generates conforming DID s or conforming DID Document s. 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 DID s or conforming DID Document s. A consumer that is conformant with this specification MUST produce errors when consuming non-conforming DIDs or DID Documents .
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 set of parameters that can be used to independently verify a proof according to a particular method. For example, a public key can be used as a verification method with respect to a digital signature; in such usage, it verifies that the signer possessed the associated private key.
"Verification" and "proof" in this definition are intended to apply broadly. A public key might be used during Diffie-Hellman key exchange to negotiate a shared symmetric key for encryption. This guarantees the integrity of the key agreement process. It is thus another type of verification method, even though descriptions of the process might not use the words "verification" and "proof."
Verification methods might take many parameters. An example of this is a set of five cryptographic keys from which any three are required to contribute to a threshold signature. Methods need not be cryptographic. An example of this might be the contact information for a biometric service provider that compares a purported DID controller against a candidate biometric vector.
This section describes the formal syntax for DIDs and DID URLs. The term "generic" is used to differentiate the syntax defined here from syntax defined by specific DID methods in their respective specifications.
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
§
7.
Methods
.
For the broadest interoperability, make DID normalization as simple and universal as possible:
method-specific-id
rule
in
Section
§
3.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
§
3.1.1
Generic
DID
Syntax
.
The
path-abempty
and
fragment
components
are
identical
to
the
ABNF
rules
defined
in
[
RFC3986
],
and
the
did-query
component
is
derived
from
the
query
ABNF
rule.
did-url = did path-abempty [ "?" did-query ] [ "#" fragment ] did-query = param *( "&" param ) param = param-name "=" param-value param-name = 1*pchar param-value = *pchar
This
specification
reserves
the
semicolon
(
;
)
character
for
possible
future
use
as
a
sub-delimiter
for
parameters
as
described
in
[
MATRIX-URIS
].
The
DID
URL
syntax
supports
a
simple,
generalized
format
for
parameters
based
on
the
query
component
(See
§
3.2.5
Query
).
The
ABNF
above
specifies
the
basic
syntax
(the
param
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 § 3.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 . |
Additional considerations for processing these parameters are discussed 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 functions can also be influenced by passing input metadata to a DID resolver that are not part of the DID URL. (See § 8.3 Metadata Structure ). 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 resolution options that are not part of the DID URL should be use to control how that resource is resolved or 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
DID
path
is
identical
to
a
generic
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
§
5.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
DID
query
is
derived
from
a
generic
URI
query
and
MUST
conform
to
the
did-query
ABNF
rule
in
Section
§
3.2.1
Generic
DID
URL
Syntax
.
If
a
DID
query
is
present,
it
MUST
be
used
as
described
in
Sections
§
3.2.2
Generic
DID
URL
Parameters
and
§
3.2.3
Method-Specific
DID
URL
Parameters
.
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 dereference a DID fragment , the complete DID URL including the DID fragment MUST be used as input to the DID URL dereferencing function for the target component in the DID document object. For more information, see § 8.2 DID URL Dereferencing .
A specific DID scheme MAY specify ABNF rules for DID fragments that are more restrictive than the generic rules in this section.
did:example:123456#public-key-1
In order to maximize interoperability, implementers are urged to ensure that DID fragments are interpreted in the same way across representations (as described in § 6. Core Representations ). For example, while JSON Pointer [ RFC6901 ] can be used in a DID fragment , it will not be interpreted in the same way across representations.
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 .
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
§
3.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
§
5.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
§
3.2.4
Path
,
Section
§
3.2.5
Query
,
and
Section
§
3.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 specification defines an abstract data model for DID documents , independent of any specific representation. This section provides a high-level description of the data model, a set of requirements for representations, and a set of requirements for extensibility.
A DID document consists of a collection of property-value pairs. The definitions of each of these properties are specified in section § 5. Core Properties . Specific representations are defined in section § 6. Core Representations .
Following are the requirements for representations.
The core representations are specified in section § 6. Core Representations .
The data model supports two types of extensibility.
It is always possible for two specific implementations to agree out-of-band to use a mutually understood extension or representation that is not recorded in the DID Core Registries [ DID-CORE-REGISTRIES ]; interoperability between such implementations and the larger ecosystem will be less reliable.
A DID points to a DID document . DID documents are the serialization of the data model outlined in Section § 4. 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
DID
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 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 § 5.4 Authentication ) or establishing secure communication with service endpoints (see Section § 5.6 Service Endpoints ). As well, public keys can play a role in authorization mechanisms of DID method operations (see Section § 7.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
relationship
s
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
§
5.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
§
5.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
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
document
MAY
MUST
NOT
contain
express
revoked
keys.
keys
using
a
verification
relationship
.
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 § 8. 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
§
5.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
§
5.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 although this is discouraged. See § 10.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.
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 § 7.1 Method Schemes and § 5.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
§
5.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 § 9.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 § 4. Data Model and § 5. Core Properties ) 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
the
content-type
DID
resolver
metadata
field.
(See
§
8.1
DID
Resolution
).
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 § 4.3 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
indicated
by
a
content-type
of
application/did+json
in
the
resolver
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 § 4. 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
indicated
by
a
content-type
of
application/did+ld+json
in
the
resolver
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
§
3.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 § 7.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
§
3.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 § 8. 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.
Interoperability for DID methods will be determined by evaluating each DID method specification to determine, at a minimum, that the:
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 § 7.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 § 5.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 § 10. 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.
This section defines the inputs and outputs of the DID resolution and DID URL dereferencing processes. The exact implementation of these functions is out of scope for this specification, but some considerations for implementors are available 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 § 9.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 § 5.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 § 5.7 Created and § 5.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 , 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.
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 § 7.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 § 5.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 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 GDPR right to be forgotten , because no personal data 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.
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.
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 among the most censorship-resistant transaction ordering systems at the present, 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 § 9.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 § 5.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 .
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 ].