This document provides guidance to DID Method developers, related to serialization, cryptographic primitive selection, governance and interoperability.
Guidance provided in this document does reflect the consenus of the W3C DID WG, although some members of the WG have contributed to it.
See [[DID-CORE]] for normative requirements associated with developing DID Methods.
Avoid introducing requirements in your did method specification that are not described in [[DID-CORE]], or registered in the [[DID-SPEC-REGISTRIES]].
Avoid constructing a new DID Method that is nearly identical to existing DID Methods.
There are several "families" of DID Methods, including Hyperledger Indy, Sidetree and various methods that share similar smart contracts or rely on shared content addressing technology.
Implementers are cautioned to write and regularly run integration and interoperability tests that span these "families", in order to ensure methods have sufficient support for open standards and real interoperability.
The primary user facing aspects of a DID Method are its DID Syntax and it's Verifiable Data Registry. Together these determine most of the unique properties of a DID Method, and its privacy and security properties compared to other methods.
See [[DID-CORE]] for normative requirements associated with developing DID Syntax.
Avoid allowing users to control the structure of the DID Unique
Suffix, also referred to as the id-char in the ABNF. This
can be accomplished by coupling the create operation canonical
representation to the the id-char. It can also be
accomplished by leveraging sources of entropy.
Avoid vanity DIDs, for example,
did:example:deadbeef1f236..., the structure of the
identifier should not be relied on for anything other than collision
resistance. Be especially careful of trusting a relationship between a
did subject and did controller without relying on a cryptographically
secure verification relationship for
authentication.
Anyone can claim a DID, but only someone who controlls the associated
keys can authenticate as it.
For example `did:example:wallmart` should not be assumed to belong to
Wallmart.
Depending on the nature of the
VDR, publishing
type or kind might be advantageous for
decentralized discovery or mass surveilance. Implementers are not to
rely on conformance to specification text while implementing
decentralized identifiers.
See [[DID-CORE]] for normative requirements associated with developing Verifiable Data Registry.
The VDR is the system to which DID Operations such as Create, Resolve, Update and Deactivate are applied.
Typically a globally unique tamper evident immutable log is used to produce a verifiable data registry.
Blockchains or distributed ledgers are popular choices for building verifiable data registries, but there are other solutions which yield unique security pros and cons.
Some DID methods rely on centralized trusted service providers and merkle proofs, to provide tamper evident logs without the costs associated with distributeted consensus.
Some DID methods rely on multiple registries, that may not be globally available.
Some DID methods might rely on legacy security infrastructure, such as TLS or TOR.
Few DID methods support portability accross verifiable data registries, and altering the VDR associated with a DID will almost certainly impact Privacy and Security considerations.
Intead of designing complex DID Methods with registry portability, consider supporting multiple did methods that have each been designed to support disjoint security or privacy consideration, for example: globally discoverable, offline, pairwise unique, linked to existing roots of trust such as websites, etc...
Depending on the nature of the VDR, it may be desirable to store data other than DID Documents, for example: verifiable credentials, templates or schemas for credentials, discovery meta data or integrity or content addresable identifiers for related information.
In order to create secure DID systems, it is important to consider the process of establishing a Decentralized Identifier.
Establishing cryptographic assurances for the identifier from the inception of the identifier is critical to ensuring that the security of the system isn't compromised through attacks against the creation process.
A commonly observed process for establishing a decentralized identifier is:
entropy from a source of randomness that is as close to actually random as possible.
entropy.The Create Operation will often use the first verification or a determinsitc function, such as a hash of it to construct and register the DID.
True randomness is hard to get. Sources such as the NIST Randomness Beacon are reliable, but should not be used directly as a secret key.
{
"@context": "https://w3id.org/did-resolution/v1",
"didDocument": {
"@context": [
"https://www.w3.org/ns/did/v1",
{
"@base": "did:example:123"
}
],
"id": "did:example:123",
"verificationMethod": [
{
"id": "#key-g1",
"controller": "did:example:123",
"type": "JsonWebKey2020",
"publicKeyJwk": {
"kty": "EC",
"crv": "BLS12381_G1",
"x": "kIf1PZ8UJzZySnCsZx14cHS3AxiWO2jH26MeJu_WdAF1varePeXYlpr-Qo_dLVJ-"
}
},
{
"id": "#key-g2",
"controller": "did:example:123",
"type": "JsonWebKey2020",
"publicKeyJwk": {
"kty": "EC",
"crv": "BLS12381_G2",
"x": "lc0FEvffl8o9bKhwVM2bZOzt_p4lz4vTIBtYDyFPQHh1GIx7wmwaSfbgot3eEvi2BS_7ncWoFnoAYBOyIAqMyCDIYHmjs2-LVagsZx-f14je_wGOB1ThaFlUdoA4UAOX"
}
}
],
"authentication": ["#key-g1", "#key-g2"],
"assertionMethod": ["#key-g1", "#key-g2"],
"capabilityInvocation": ["#key-g1", "#key-g2"],
"capabilityDelegation": ["#key-g1", "#key-g2"]
},
"didDocumentMetadata": {
"content-type": "application/did+json"
},
"didResolutionMetadata": {}
}
{
"@context": "https://w3id.org/did-resolution/v1",
"didDocument": {
"@context": [
"https://www.w3.org/ns/did/v1",
{
"@base": "did:example:456"
}
],
"id": "did:example:456",
"verificationMethod": [
{
"id": "#key-g1",
"type": "Bls12381G1Key2020",
"controller": "did:example:456",
"publicKeyBase58": "7c98uRcPAjWbPJ7GeHc4Csd3qGKYsbHGjE3G8v2YX6Te3g6Ur2PfDcrpmoBoBmV8yT"
},
{
"id": "#key-g2",
"type": "Bls12381G2Key2020",
"controller": "did:example:456",
"publicKeyBase58": "yuTSz1w31UYhoAN6v2D16dLtPg2kMGkwbptoZ5z96bpuHrvBNAshsLsgX9GvE6bnG95WPWuRkQJ9oUmL1ytEjfojWPsQBmwKXhd6gxkwHkHfakMNYzGMgyH76rigsu4E62o"
}
],
"authentication": ["#key-g1", "#key-g2"],
"assertionMethod": ["#key-g1", "#key-g2"],
"capabilityInvocation": ["#key-g1", "#key-g2"],
"capabilityDelegation": ["#key-g1", "#key-g2"]
},
"didDocumentMetadata": {
"content-type": "application/did+ld+json"
},
"didResolutionMetadata": {}
}
See [[DID-CORE]] for normative requirements associated with developing DID Resolution.
DID resolution is a function which takes a DID, and produces a DID Resolution response in a representation, most commonly JSON.
{
"@context": "https://w3id.org/did-resolution/v1",
"didDocument": {
"@context": [
"https://www.w3.org/ns/did/v1",
],
"id": "did:example:123",
},
"didDocumentMetadata": {
"content-type": "application/did+json"
},
"didResolutionMetadata": {}
}
DID resolution can be proxied through intermediaries such as command line tools or http servers. Because the DID Document contains key material, such intermediaries represent excellent targets for attackers, because these systems can be used to tamper with verification relationships.
Avoid tampering with a DID Document that as been returned by did method software. It is better to throw an error than attempt to solve problems in the underlying DID Method.
Avoid transforming DID Documents without the consent of the did subject or controller.
Whenever possible, run all software necessary to support a DID Method yourself.
See [[DID-CORE]] for normative requirements associated with developing DID URL Syntax.
DID URLs can be used to identify sub resources inside a DID Document, older versions of a DID Document, or resources outside of a DID Document.
did:example:123#primary
did:example:123#agent
did:example:123?service=packages@relativeRef=/jose/versions/v0.1.2/archive.zip
Adjusting any part of a DID URL, including the did,
path, query, changes the identifier.
The resource identifiers did:example:123,
did:example:123/path and
did:example:123?args=1 are for unique resources.
See [[DID-CORE]] for normative requirements associated with developing Path.
Avoid using path, there are not enough implementations
that rely on it.
did:example:123/ephemeral/77d66171-b290-489c-abf1-95ae10725201#primary
See [[DID-CORE]] for normative requirements associated with developing Query.
Avoid using query, there are not enough implementations
that rely on it.
did:example:123?version-id=77d66171-b290-489c-abf1-95ae10725201#primary
See [[DID-CORE]] for normative requirements associated with developing Fragment.
did:example:123#primary
Fragments identify sub resources of a resource identified with a DID URL.
The interpretation of the fragment is determined by the mime type.
See [[DID-CORE]] for normative requirements associated with developing Representations.
The [[DID-CORE]] specification describes representations and the [[DID-SPEC-REGISTRIES]] supports the registration of an unbounded number of alternative representations.
Each representation has unique pros and cons.
DID Methods are responsible for producing a DID Document in the requested representation.
DID Method implementers may choose to return verification methods in
alternate formats for representations, for example, an implementer
might prefer to return verification material encoded with
publicKeyJwk for application/did+json and
publicKeyBase58 for application/did+ld+json.
If a DID Method supports both application/did+json and
application/did+ld+json if it recommended that they both
include an @context and that both be capable of
supporting linked data proofs.
Avoid allowing arbitrary unknown properties into
application/did+json such as __proto__ or
other characters that might be used to attack JSON parsing.
While application/did+json is very flexible, and allows
for arbitrary JSON, implementers are cautioned to implement security
in depth.
Implementers are cautioned to review OWASP Top 10
Implementers should confirm that each representation they decide to support is interoperable with the same representation in other did methods.
Implementers should avoid guessing about conformance to [[DID-CORE]].
See [[DID-CORE]] for normative requirements associated with developing DID URL Dereferencing.
Dereferencing is critical to integrating with cryptographic toolkits such as Linked Data Proofs, JOSE, PGP or Anon Creds.
See [[DID-CORE]] for normative requirements associated with developing Verification Relationships.
Verification relationships are loosely equivalent to the concept of key purpose.
It is considered a security best practice not to reuse the same key for multiple purposes.
See [[DID-CORE]] for normative requirements associated with developing Authentication.
Implementers are advised to implement support for this relationship.
This relationship should be used for proofs or signatures associated with did subject authentication.
Avoid conflating authentication and authorization.
Avoid leveraging alternative relationships for the purpose of authentication.
See [[DID-CORE]] for normative requirements associated with developing Assertion.
Implementers are advised to implement support for this relationship.
This relationship should be used for proofs or signatures associated with claims issued by this did subject about another identifier, which might be a DID.
This method is described in the [[VC-DATA-MODEL], see Proofs
Avoid leveraging alternative relationships for the purpose of issuing credentials.
Decentralized Identifiers, like any other technology, can be used to enhance privacy as well as harm privacy. This section speaks to topics that implementers might consider when thinking about the privacy characteristics of their software systems.
Never store PII, even in an encrypted format on any immutable storage backed verifiable data registry.
It is the DID method implementer's responsibility to think about and identify the extent to which PII may be included in a DID document
Software should at least display a warning and ask for confirmation before creating or updating any properties of a did document that depend on user provided inputs
A DID method specification should have a PII dedicated section covering the extend to which information published on the corresponding ledger can be updated or deleted. It should provide specific instructions on how to do so if it is possible. It should clearly state that it is not possible otherwise.
Avoid reusing verification methods across did methods.
Avoid reusing services with unique parameters across did methods.
Any anonymous identifier, even if it is generated randomly can be used to infer sensitive information about a DID subject if it is reused enough times.
A DID method implementer should rotate keys and identifiers as often as possible to avoid correlation
Consider formally modeling the privacy implications associated with your implementation using t-closeness or other mechanisms.
If DID Method supports globaly enumeration and indexing, consider exposing this information publically. You may wish to provide alerts similar to servicess that watch version control systems for sensitive information that is accidentally leaked.
Review any applicable local law when considering developing or operating a decentralized identifier method.
Consider GDPR.
Consider CCPA.
Decentralized Identifiers are security primitives that are often used to secure important systems. This section speaks to topics that implementers might consider when thinking about the security characteristics of their software systems.
Consider defense in depth, cryptographic agility and political acceptability of any cryptography you rely on for did method security.
Avoid complex or slow signature formats, especially if they are poorly documented, or do not have an open standard with well documented test vectors.
Avoid open source implementations that are declared a "defacto standard", but lack open standard technical specification.
Add support for legacy crypto systems such as jose and Open PGP.
Competition, direct substitutability, interoperability and mutual feature support are key to reducing the barrier to adoption, and confidence in your DID Method.
Avoid inventing "new features", work with others to find a common way to express any new features that is not unique to your did method.
Avoid hard coupling to specific networks, such as Bitcoin or Hyper Ledger Fabric. Design your method such that it may be adapted to support multiple ledger systems.
Review safecurves.cr.yp.to before selecting eliptic curve types.
Avoid secp256k1, RSA, P-256, P-384, P-521.
Avoid relying on smart contracts for complex data mangement. If you must use a smart contract, keep it simple and architect a solution that supports data migration.
Avoid MD5.
Consider using BBS+ Signatures for selective disclosure and linked secret based JSON-LD verifiable credentials.
Avoid zero knowledge proofs as described in the AnonCredDerivedCredentialv1. This proof format is coupled to specific ledger technologies, similar to the concept of an ethereum virtual machine smart contract only running on EVM compatible ledgers. Ledger specific technologies should be avoided when designing forportable, interoperable and open standards based zero knowledge proofs.
Avoid storing credential schemas on ledgers. Many DID methods cannot store information other than a DID Document, which reduces the direct interoperabiility, substitutability and cost effectiveness of solutions that make use of rare or poorly supported features such as credential schema defintion storage.
Avoid relying exclusively on biometrics.
Hardware isolated keys protected by biometrics on devices may increase the usability of DIDs.
This section was copied from w3c/did-imp-guide, and adjusted based on changes made to did core.
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.
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.
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.