├── .pr-preview.json ├── ECHIDNA ├── w3c.json ├── LICENSE.md ├── CODE_OF_CONDUCT.md ├── ietf-registration.txt ├── CONTRIBUTING.md ├── .travis.yml ├── README.md ├── FPWD └── 2019-11-07 │ └── contexts │ ├── did-v0.11.jsonld │ └── did-v1.jsonld ├── terms.html ├── common.js └── index.html /.pr-preview.json: -------------------------------------------------------------------------------- 1 | { 2 | "src_file": "index.html", 3 | "type": "respec" 4 | } 5 | -------------------------------------------------------------------------------- /ECHIDNA: -------------------------------------------------------------------------------- 1 | # ECHIDNA configuration 2 | index.html?specStatus=WD&shortName=did-core respec 3 | -------------------------------------------------------------------------------- /w3c.json: -------------------------------------------------------------------------------- 1 | { 2 | "group": [117488] 3 | , "contacts": ["iherman"] 4 | , "repo-type": "rec-track" 5 | , "shortName": "did-spec" 6 | } 7 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | All documents in this Repository are licensed by contributors 2 | under the 3 | [W3C Software and Document License](https://www.w3.org/Consortium/Legal/copyright-software). 4 | 5 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Code of Conduct 2 | 3 | All documentation, code and communication under this repository are covered by the [W3C Code of Ethics and Professional Conduct](https://www.w3.org/Consortium/cepc/). 4 | -------------------------------------------------------------------------------- /ietf-registration.txt: -------------------------------------------------------------------------------- 1 | Scheme name: did 2 | Status: Provisional 3 | 4 | Applications/protocols that use this scheme name: 5 | 6 | A "did" URI is used to express an identifier that is conformant to the 7 | Decentralized Identifier[1] specification. The specification details how 8 | identifiers conformant to the "did" URI Scheme can be implemented using 9 | decentralized ledgers, decentralized hashtables, and other types of 10 | decentralized networks. 11 | 12 | This specification is currently under development by the W3C Decentralized 13 | Identifiers Working Group and is expected to transition to the W3C standards 14 | track at the end of 2018 or early 2019 calendar year. 15 | 16 | Contact: 17 | 18 | Manu Sporny 19 | 20 | Change controller: 21 | 22 | Manu Sporny 23 | W3C Decentralized Identifiers Working Group 24 | 25 | References: 26 | 27 | [1] https://w3c.github.io/did-spec/ 28 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Decentralized Identifier Working Group 2 | 3 | Contributions to this repository are intended to become part of Recommendation-track documents governed by the 4 | [W3C Patent Policy](https://www.w3.org/Consortium/Patent-Policy-20040205/) and 5 | [Software and Document License](https://www.w3.org/Consortium/Legal/copyright-software). To make substantive contributions to specifications, you must either participate 6 | in the relevant W3C Working Group or make a non-member patent licensing commitment. 7 | 8 | If you are not the sole contributor to a contribution (pull request), please identify all 9 | contributors in the pull request comment. 10 | 11 | To add a contributor (other than yourself, that's automatic), mark them one per line as follows: 12 | 13 | ``` 14 | +@github_username 15 | ``` 16 | 17 | If you added a contributor by mistake, you can remove them in a comment with: 18 | 19 | ``` 20 | -@github_username 21 | ``` 22 | 23 | If you are making a pull request on behalf of someone else but you had no part in designing the 24 | feature, you can remove yourself with the above syntax. 25 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | language: node_js 2 | 3 | branches: 4 | only: 5 | - master 6 | 7 | env: 8 | global: 9 | - URL="https://w3c.github.io/did-core/ECHIDNA" 10 | - DECISION="https://www.w3.org/2019/did-wg/Meetings/Minutes/2019-10-22-did#resolution1" 11 | - secure: "XB1q1xJNjGnW77S9dQTXDqlZNLUDYLQeotLMnrdIxTx9uwRrVWTCDZ6WmUKjJ3dWKeoU9YF2aL8V9AK8DejDsoYp9NVBk4Vyym6R3o62v2k4lClUo9sDuNwSTBHw6mmIdzXL4ihjwyGaIhkyGWb0EFNTPu31m1PEAoE0kjeLM2aRXYOZD0p2Zo4oStz+uHNk+6Za8aLMLq+zP/XYksWuNr0FqdHFddsdFhSMzEEVpjnzWnP+ix5+mOPsoYJgPJ0S2NSa7q+wHCtI8Dr0pyK1CiMdnGR18z3W67MftaLiLiRSVj7JqxninFRViu/4ZIyqG2tr34Yo2SC3E4CCECNYQ/XktKeu02q6pS87XRuHCgmrBcMkmDM6rFwicBBceq49zXFp46GPbrJuVQCMM8tVgMRzu5llsDyyQRr2QHbOSfxN15lmacygEegjHBro9iWv+181FGeXxU42ffL8RTq6JH3ZW256sFZVNszdnUo/EXM5x4ZKXVLFd7WmK32bR+2/ZO1VhMyjTSCIGX7qi0FKj373TwfuJQQG/IFOueR+K56DaY7+v+qFQq48ueyuZZvLOp665L5Z0oTR1BAu3NONQfICHl9BoA5rEywNjobuQ2+ZpgE2hAiA9l58/8zlklG/JtoaEq3xIZq7/O2r7lmq8yuFVsJKmDVRDjojo7831zE=" 12 | 13 | script: 14 | - echo "ok" 15 | 16 | after_success: 17 | - test $TRAVIS_PULL_REQUEST = false && curl "https://labs.w3.org/echidna/api/request" --data "url=$URL" --data "decision=$DECISION" --data "token=$TOKEN" 18 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | 2 | ![W3C Logo](https://www.w3.org/Icons/w3c_home) 3 | 4 | # Decentralized Identifier Specification v1.0 5 | 6 | This is the repository of the W3C’s specification on Decentralized Identifier Specification v1.0, developed by the [DID Working Group](https://www.w3.org/2019/did-wg/). The editors’ draft of the specification can also be [read directly](https://w3c.github.io/did-core/). 7 | 8 | ## Contributing to the Repository 9 | 10 | Use the standard fork, branch, and pull request workflow to propose changes to the specification. Please make branch names informative—by including the issue or bug number for example. 11 | 12 | Editorial changes that improve the readability of the spec or correct spelling or grammatical mistakes are welcome. 13 | 14 | Please read [CONTRIBUTING.md](CONTRIBUTING.md), about licensing contributions. 15 | 16 | ## Code of Conduct 17 | 18 | W3C functions under a [code of conduct](https://www.w3.org/Consortium/cepc/). 19 | 20 | ## DID Working Group Repositories 21 | 22 | * [W3C Decentralized Identifier Specification v1.0](https://github.com/w3c/did-core) 23 | * [Home page of the Decentralized Identifier Working Group](https://github.com/w3c/did-wg) 24 | * [Specs and documentation for all DID-related /.well-known resources](https://github.com/decentralized-identity/.well-known) 25 | * [W3C Decentralized Characteristics Rubric v1.0](https://github.com/w3c/did-rubric) 26 | * [Decentralized Identifier Use Cases v1.0](https://github.com/w3c/did-use-cases) 27 | * [W3C DID Test Suite and Implementation Report](https://github.com/w3c/did-test-suite) 28 | -------------------------------------------------------------------------------- /FPWD/2019-11-07/contexts/did-v0.11.jsonld: -------------------------------------------------------------------------------- 1 | { 2 | "@context": { 3 | "@version": 1.1, 4 | "id": "@id", 5 | "type": "@type", 6 | 7 | "dc": "http://purl.org/dc/terms/", 8 | "schema": "http://schema.org/", 9 | "sec": "https://w3id.org/security#", 10 | "didv": "https://w3id.org/did#", 11 | "xsd": "http://www.w3.org/2001/XMLSchema#", 12 | 13 | "EcdsaSecp256k1Signature2019": "sec:EcdsaSecp256k1Signature2019", 14 | "EcdsaSecp256k1VerificationKey2019": "sec:EcdsaSecp256k1VerificationKey2019", 15 | "Ed25519Signature2018": "sec:Ed25519Signature2018", 16 | "Ed25519VerificationKey2018": "sec:Ed25519VerificationKey2018", 17 | "RsaSignature2018": "sec:RsaSignature2018", 18 | "RsaVerificationKey2018": "sec:RsaVerificationKey2018", 19 | "SchnorrSecp256k1Signature2019": "sec:SchnorrSecp256k1Signature2019", 20 | "SchnorrSecp256k1VerificationKey2019": "sec:SchnorrSecp256k1VerificationKey2019", 21 | "ServiceEndpointProxyService": "didv:ServiceEndpointProxyService", 22 | 23 | "allowedAction": "sec:allowedAction", 24 | "assertionMethod": {"@id": "sec:assertionMethod", "@type": "@id", "@container": "@set"}, 25 | "authentication": {"@id": "sec:authenticationMethod", "@type": "@id", "@container": "@set"}, 26 | "capability": {"@id": "sec:capability", "@type": "@id"}, 27 | "capabilityAction": "sec:capabilityAction", 28 | "capabilityChain": {"@id": "sec:capabilityChain", "@type": "@id", "@container": "@list"}, 29 | "capabilityDelegation": {"@id": "sec:capabilityDelegationMethod", "@type": "@id", "@container": "@set"}, 30 | "capabilityInvocation": {"@id": "sec:capabilityInvocationMethod", "@type": "@id", "@container": "@set"}, 31 | "capabilityStatusList": {"@id": "sec:capabilityStatusList", "@type": "@id"}, 32 | "canonicalizationAlgorithm": "sec:canonicalizationAlgorithm", 33 | "caveat": {"@id": "sec:caveat", "@type": "@id", "@container": "@set"}, 34 | "challenge": "sec:challenge", 35 | "controller": {"@id": "sec:controller", "@type": "@id"}, 36 | "created": {"@id": "dc:created", "@type": "xsd:dateTime"}, 37 | "creator": {"@id": "dc:creator", "@type": "@id"}, 38 | "delegator": {"@id": "sec:delegator", "@type": "@id"}, 39 | "domain": "sec:domain", 40 | "expirationDate": {"@id": "sec:expiration", "@type": "xsd:dateTime"}, 41 | "invocationTarget": {"@id": "sec:invocationTarget", "@type": "@id"}, 42 | "invoker": {"@id": "sec:invoker", "@type": "@id"}, 43 | "jws": "sec:jws", 44 | "keyAgreement": {"@id": "sec:keyAgreementMethod", "@type": "@id", "@container": "@set"}, 45 | "nonce": "sec:nonce", 46 | "owner": {"@id": "sec:owner", "@type": "@id"}, 47 | "proof": {"@id": "sec:proof", "@type": "@id", "@container": "@graph"}, 48 | "proofPurpose": {"@id": "sec:proofPurpose", "@type": "@vocab"}, 49 | "proofValue": "sec:proofValue", 50 | "publicKey": {"@id": "sec:publicKey", "@type": "@id", "@container": "@set"}, 51 | "publicKeyBase58": "sec:publicKeyBase58", 52 | "publicKeyPem": "sec:publicKeyPem", 53 | "revoked": {"@id": "sec:revoked", "@type": "xsd:dateTime"}, 54 | "service": {"@id": "didv:service", "@type": "@id", "@container": "@set"}, 55 | "serviceEndpoint": {"@id": "didv:serviceEndpoint", "@type": "@id"}, 56 | "verificationMethod": {"@id": "sec:verificationMethod", "@type": "@id"} 57 | } 58 | } 59 | -------------------------------------------------------------------------------- /FPWD/2019-11-07/contexts/did-v1.jsonld: -------------------------------------------------------------------------------- 1 | { 2 | "@context": { 3 | "@version": 1.1, 4 | "id": "@id", 5 | "type": "@type", 6 | 7 | "dc": "http://purl.org/dc/terms/", 8 | "schema": "http://schema.org/", 9 | "sec": "https://w3id.org/security#", 10 | "didv": "https://w3id.org/did#", 11 | "xsd": "http://www.w3.org/2001/XMLSchema#", 12 | 13 | "EcdsaSecp256k1Signature2019": "sec:EcdsaSecp256k1Signature2019", 14 | "EcdsaSecp256k1VerificationKey2019": "sec:EcdsaSecp256k1VerificationKey2019", 15 | "Ed25519Signature2018": "sec:Ed25519Signature2018", 16 | "Ed25519VerificationKey2018": "sec:Ed25519VerificationKey2018", 17 | "RsaSignature2018": "sec:RsaSignature2018", 18 | "RsaVerificationKey2018": "sec:RsaVerificationKey2018", 19 | "SchnorrSecp256k1Signature2019": "sec:SchnorrSecp256k1Signature2019", 20 | "SchnorrSecp256k1VerificationKey2019": "sec:SchnorrSecp256k1VerificationKey2019", 21 | "ServiceEndpointProxyService": "didv:ServiceEndpointProxyService", 22 | 23 | "allowedAction": "sec:allowedAction", 24 | "assertionMethod": {"@id": "sec:assertionMethod", "@type": "@id", "@container": "@set"}, 25 | "authentication": {"@id": "sec:authenticationMethod", "@type": "@id", "@container": "@set"}, 26 | "capability": {"@id": "sec:capability", "@type": "@id"}, 27 | "capabilityAction": "sec:capabilityAction", 28 | "capabilityChain": {"@id": "sec:capabilityChain", "@type": "@id", "@container": "@list"}, 29 | "capabilityDelegation": {"@id": "sec:capabilityDelegationMethod", "@type": "@id", "@container": "@set"}, 30 | "capabilityInvocation": {"@id": "sec:capabilityInvocationMethod", "@type": "@id", "@container": "@set"}, 31 | "capabilityStatusList": {"@id": "sec:capabilityStatusList", "@type": "@id"}, 32 | "canonicalizationAlgorithm": "sec:canonicalizationAlgorithm", 33 | "caveat": {"@id": "sec:caveat", "@type": "@id", "@container": "@set"}, 34 | "challenge": "sec:challenge", 35 | "controller": {"@id": "sec:controller", "@type": "@id"}, 36 | "created": {"@id": "dc:created", "@type": "xsd:dateTime"}, 37 | "creator": {"@id": "dc:creator", "@type": "@id"}, 38 | "delegator": {"@id": "sec:delegator", "@type": "@id"}, 39 | "domain": "sec:domain", 40 | "expirationDate": {"@id": "sec:expiration", "@type": "xsd:dateTime"}, 41 | "invocationTarget": {"@id": "sec:invocationTarget", "@type": "@id"}, 42 | "invoker": {"@id": "sec:invoker", "@type": "@id"}, 43 | "jws": "sec:jws", 44 | "keyAgreement": {"@id": "sec:keyAgreementMethod", "@type": "@id", "@container": "@set"}, 45 | "nonce": "sec:nonce", 46 | "owner": {"@id": "sec:owner", "@type": "@id"}, 47 | "proof": {"@id": "sec:proof", "@type": "@id", "@container": "@graph"}, 48 | "proofPurpose": {"@id": "sec:proofPurpose", "@type": "@vocab"}, 49 | "proofValue": "sec:proofValue", 50 | "publicKey": {"@id": "sec:publicKey", "@type": "@id", "@container": "@set"}, 51 | "publicKeyBase58": "sec:publicKeyBase58", 52 | "publicKeyPem": "sec:publicKeyPem", 53 | "revoked": {"@id": "sec:revoked", "@type": "xsd:dateTime"}, 54 | "service": {"@id": "didv:service", "@type": "@id", "@container": "@set"}, 55 | "serviceEndpoint": {"@id": "didv:serviceEndpoint", "@type": "@id"}, 56 | "verificationMethod": {"@id": "sec:verificationMethod", "@type": "@id"} 57 | } 58 | } 59 | -------------------------------------------------------------------------------- /terms.html: -------------------------------------------------------------------------------- 1 |

2 | This document attempts to communicate the concepts outlined in the 3 | decentralized identifier space by using specialized terms to discuss 4 | specific concepts. This terminology is included below and linked to throughout 5 | the document to aid the reader: 6 |

7 | 8 |
9 | 10 |
blockchain
11 | 12 |
13 | A specific type of distributed ledger technology (DLT) that stores ledger 14 | entries in blocks of transactions, which are grouped together and hashed into a 15 | cryptographic chain. Because this type of DLT was introduced by 16 | Bitcoin, the term 17 | blockchain is sometimes used to refer specifically to the Bitcoin 18 | ledger. 19 |
20 | 21 |
decentralized identifier (DID)
22 | 23 |
24 | A globally unique identifier that does not require a centralized registration 25 | authority because it is registered with distributed ledger technology 26 | (DLT) or other form of decentralized network. The generic format of a DID is 27 | defined in this specification. A specific DID scheme is defined in a 28 | DID method specification. 29 |
30 | 31 |
decentralized identity management
32 | 33 |
34 | Identity 35 | management based on decentralized identifiers. Decentralized identity 36 | management extends the identifier creation authority beyond the traditional 37 | roots of trust required by 38 | X.500 directory services, 39 | the Domain Name System, 40 | and most national identification systems. 41 |
42 | 43 |
decentralized public key infrastructure (DPKI)
44 | 45 |
46 | Public key infrastructure based on decentralized identifiers and identity 47 | records (for example, DID documents) containing verifiable 48 | public key descriptions. 49 |
50 | 51 |
DID controller
52 | 53 |
54 | The entity that has the ability to make changes to a DID document. 55 | A DID can have more than one controller. The DID controller(s) 56 | are denoted by the `controller` property on the top level of the DID 57 | document. Note that the DID controller(s) might include the 58 | DID subject. 59 |
60 | 61 |
DID delegate
62 | 63 |
64 | An entity that the DID controller has approved to use cryptographic 65 | material associated with the DID document. For example, a parent 66 | that controls a child's DID document might approve the child 67 | to use their personal device for authentication purposes. In this case, the 68 | child is the DID delegate and their personal device contains 69 | private cryptographic material to enable the child to authenticate as the DID, 70 | but not to add new personal devices without the parent's approval. 71 |
72 | 73 |
DID document
74 | 75 |
76 | A set of data describing the DID subject, including mechanisms, such as 77 | public keys and pseudonymous biometrics, that the DID subject can use to 78 | authenticate itself and prove their association with the DID. A DID 79 | document might also contain other 80 | attributes or 81 | claims 82 | describing the subject. These documents are graph-based data structures that 83 | are typically expressed using [[JSON-LD]], but can be expressed using other 84 | compatible graph-based data formats. 85 |
86 | 87 |
DID fragment
88 | 89 |
90 | The portion of a DID URL that follows the first hash sign character 91 | (#). DID fragment syntax is identical to the URI fragment syntax. 92 |
93 | 94 |
DID method
95 | 96 |
97 | A definition of how a specific DID scheme can be implemented on a 98 | specific distributed ledger or network, including the precise methods by 99 | which DIDs are resolved and deactivated and DID documents are 100 | written and updated. 101 |
102 | 103 |
DID path
104 | 105 |
106 | The portion of a DID URL that begins with and includes the first forward 107 | slash character (/). DID path syntax is identical to the URI path 108 | syntax. 109 |
110 | 111 |
DID query
112 | 113 |
114 | The portion of a DID URL that follows the first question mark character 115 | (?). DID query syntax is identical to the URI query syntax. 116 |
117 | 118 |
DID registry
119 | 120 |
121 | A role a system performs to mediate the creation, verification, updating, and 122 | deactivation of decentralized identifiers. A DID registry is a type of 123 | verifiable data registry. For more information, see [[VC-DATA-MODEL]]. 124 |
125 | 126 |
DID resolver
127 | 128 |
129 | A system that is capable of retrieving a DID document for a given 130 | DID. These systems are specified in the DID Resolution specification 131 | [[DID-RESOLUTION]]. 132 |
133 | 134 |
DID scheme
135 | 136 |
137 | The formal syntax of a decentralized identifier. The generic DID scheme 138 | is defined in this specification. Separate DID method specifications 139 | define a specific DID scheme that works with that specific DID method. 140 |
141 | 142 |
DID subject
143 | 144 |
145 | The entity the DID document is about. That is, the entity identified by 146 | the DID and described by the DID document. 147 |
148 | 149 |
DID URL
150 | 151 |
152 | A DID plus an optional DID path, optional ? character 153 | followed by a DID query, and optional # character followed 154 | by a DID fragment. 155 |
156 | 157 |
distributed ledger (DLT)
158 | 159 |
160 | A distributed database 161 | in which the various nodes use a 162 | consensus protocol 163 | to maintain a shared ledger in which each transaction is cryptographically 164 | signed and chained to the previous transaction. 165 |
166 | 167 |
extensible data interchange (XDI)
168 | 169 |
170 | A semantic graph format and semantic data interchange protocol defined by the 171 | OASIS XDI Technical Committee. 172 |
173 | 174 |
identity owner
175 | 176 |
177 | The natural person, party, organization, or thing whose identity is represented 178 | by a DID and who directly controls the private keys to control the 179 | DID document. Note that this specification avoids the term user 180 | since a DID subject is not always an individual person. 181 |
182 | 183 |
proof purpose
184 | 185 |
186 | The specific intent for a proof, the reason why an entity created it. 187 | Acts as a safeguard to prevent the proof from being misused for a purpose 188 | other than the one it was intended for. 189 |
190 | 191 |
JSON Pointer
192 | 193 |
194 | Defines a string syntax for identifying a specific value within a JavaScript 195 | Object Notation (JSON) document, as defined in [[RFC6901]]. 196 |
197 | 198 |
public key description
199 | 200 |
201 | A JSON object contained inside a DID document that contains all the 202 | metadata necessary to use a public key or verification key. 203 |
204 | 205 |
service endpoint
206 | 207 |
208 | A network address at which a service operates on behalf of a DID subject. 209 | Examples of specific services include discovery services, social networks, file 210 | storage services, and verifiable claim repository services. Service endpoints 211 | might also be provided by a generalized data interchange protocol, such as 212 | extensible data interchange. 213 |
214 | 215 |
Uniform Resource Identifier (URI)
216 | 217 |
218 | An identifier, as defined by [[RFC3986]]. 219 |
220 | 221 |
verification method
222 | 223 |
224 | A set of parameters required to independently verify a proof, such 225 | as an identifier for a public/private key pair that would be used in the 226 | proof. 227 |
228 |
Universally Unique Identifier (UUID)
229 | 230 |
231 | An identifier, as defined by [[RFC4122]]. 232 |
233 | 234 |
235 | -------------------------------------------------------------------------------- /common.js: -------------------------------------------------------------------------------- 1 | /* globals omitTerms, respecConfig, $, require */ 2 | /* DID WG common Javascript ReSpec functions */ 3 | /* ... stolen from Gregg Kellogg of the JSON-LD 1.1 Working Group */ 4 | /* ... who stole it from Manu Sporny of the JSON-LD 1.0 Working Group */ 5 | /* ... who stole it from Shane McCarron, that beautiful, beautiful man. */ 6 | /* exported restrictReferences */ 7 | 8 | var ccg = { 9 | // Add as the respecConfig localBiblio variable 10 | // Extend or override global respec references 11 | localBiblio: { 12 | "REST": { 13 | title: "Architectural Styles and the Design of Network-based Software Architectures", 14 | date: "2000", 15 | href: "http://www.ics.uci.edu/~fielding/pubs/dissertation/", 16 | authors: [ 17 | "Fielding, Roy Thomas" 18 | ], 19 | publisher: "University of California, Irvine." 20 | }, 21 | "VC-USECASES": { 22 | title: "Verifiable Claims Use Cases", 23 | href: "https://www.w3.org/TR/verifiable-claims-use-cases/", 24 | authors: [ 25 | "Shane McCarron", 26 | "Daniel Burnett", 27 | "Gregg Kellogg", 28 | "Brian Sletten", 29 | "Manu Sporny" 30 | ], 31 | status: "FPWD", 32 | publisher: "Verifiable Claims Working Group" 33 | }, 34 | "DID-USE-CASES": { 35 | title: "Decentralized Identifier Use Cases", 36 | href: "https://w3c.github.io/did-use-cases/", 37 | authors: [ 38 | "Joe Andrieu", 39 | "Kim Hamilton Duffy", 40 | "Ryan Grant", 41 | "Adrian Gropper" 42 | ], 43 | status: "ED", 44 | publisher: "Decentralized Identifier Working Group" 45 | }, 46 | // aliases to known references 47 | "HTTP-SIGNATURES": { 48 | aliasOf: "http-signatures" 49 | }, 50 | "MACAROONS": { 51 | title: 'Macaroons', 52 | // TODO: create spec 53 | href: 'http://macaroons.io/', 54 | authors: ['Arnar Birgisson', 'Joe Gibbs Politz', 'Úlfar Erlingsson', 55 | 'Ankur Taly', 'Michael Vrable', 'Mark Lentczner'], 56 | status: 'unofficial', 57 | publisher: 'Credentials Community Group' 58 | }, 59 | 'OPEN-BADGES': { 60 | title: 'Open Badges', 61 | href: 'https://github.com/openbadges/openbadges-specification', 62 | authors: ['Brian Brennan', 'Mike Larsson', 'Chris McAvoy', 63 | 'Nate Otto', 'Kerri Lemoie'], 64 | status: 'BA-DRAFT', 65 | publisher: 'Badge Alliance Standard Working Group' 66 | }, 67 | 'RDF-NORMALIZATION': { 68 | title: 'RDF Dataset Normalization', 69 | href: 'http://json-ld.github.io/normalization/spec/', 70 | authors: ['Dave Longley', 'Manu Sporny'], 71 | status: 'CG-DRAFT', 72 | publisher: 'Credentials W3C Community Group' 73 | }, 74 | "LD-PROOFS": { 75 | title: "Linked Data Proofs", 76 | href: "https://w3c-dvcg.github.io/ld-proofs/", 77 | authors: [ 78 | "Manu Sporny", 79 | "Dave Longley" 80 | ], 81 | status: "CG-DRAFT", 82 | publisher: "Digital Verification Community Group" 83 | }, 84 | "LD-SIGNATURES": { 85 | title: "Linked Data Signatures", 86 | href: "https://w3c-dvcg.github.io/ld-signatures/", 87 | authors: [ 88 | "Manu Sporny", 89 | "Dave Longley" 90 | ], 91 | status: "CG-DRAFT", 92 | publisher: "Digital Verification Community Group" 93 | }, 94 | "DID-METHOD-REGISTRY": { 95 | title: "The Decentralized Identifier Method Registry", 96 | href: "https://w3c-ccg.github.io/did-method-registry/", 97 | authors: [ 98 | "Manu Sporny", 99 | "Drummond Reed" 100 | ], 101 | status: "CG-DRAFT", 102 | publisher: "Credentials Community Group" 103 | }, 104 | "MATRIX-URIS": { 105 | title: "Matrix URIs - Ideas about Web Architecture", 106 | date: "December 1996", 107 | href: "https://www.w3.org/DesignIssues/MatrixURIs.html", 108 | authors: [ 109 | "Tim Berners-Lee" 110 | ], 111 | status: "Personal View" 112 | }, 113 | "HASHLINK": { 114 | title: "Cryptographic Hyperlinks", 115 | date: "December 2018", 116 | href: "https://tools.ietf.org/html/draft-sporny-hashlink-02", 117 | authors: [ 118 | "Manu Sporny" 119 | ], 120 | status: "Internet-Draft", 121 | publisher: "IETF" 122 | }, 123 | "BASE58": { 124 | title: "The Base58 Encoding Scheme", 125 | date: "December 2019", 126 | href: "https://tools.ietf.org/html/draft-msporny-base58", 127 | authors: [ 128 | "Manu Sporny" 129 | ], 130 | status: "Internet-Draft", 131 | publisher: "IETF" 132 | }, 133 | "DNS-DID": { 134 | title: "The Decentralized Identifier (DID) in the DNS", 135 | date: "February 2019", 136 | href: "https://datatracker.ietf.org/doc/draft-mayrhofer-did-dns/", 137 | authors: [ 138 | "Alexander Mayrhofer", 139 | "Dimitrij Klesev", 140 | "Markus Sabadello" 141 | ], 142 | status: "Internet-Draft" 143 | }, 144 | "DID-RESOLUTION": { 145 | title: "Decentralized Identifier Resolution", 146 | href: "https://w3c-ccg.github.io/did-resolution/", 147 | authors: [ 148 | "Markus Sabadello", 149 | "Dmitri Zagidulin" 150 | ], 151 | status: "Draft Community Group Report", 152 | publisher: "Credentials Community Group" 153 | }, 154 | "DID-RUBRIC": { 155 | title: "Decentralized Characteristics Rubric v1.0", 156 | href: "https://w3c.github.io/did-rubric/", 157 | authors: [ 158 | "Joe Andrieu" 159 | ], 160 | status: "Draft Community Group Report", 161 | publisher: "Credentials Community Group" 162 | } 163 | } 164 | }; 165 | 166 | // We should be able to remove terms that are not actually 167 | // referenced from the common definitions 168 | // 169 | // Add class "preserve" to a definition to ensure it is not removed. 170 | // 171 | // the termlist is in a block of class "termlist". 172 | const termNames = [] ; 173 | const termsReferencedByTerms = [] ; 174 | 175 | function restrictReferences(utils, content) { 176 | const base = document.createElement("div"); 177 | base.innerHTML = content; 178 | 179 | // New new logic: 180 | // 181 | // 1. build a list of all term-internal references 182 | // 2. When ready to process, for each reference INTO the terms, 183 | // remove any terms they reference from the termNames array too. 184 | const noPreserve = base.querySelectorAll("dfn:not(.preserve)"); 185 | for (const item of noPreserve) { 186 | const $t = $(item); 187 | const titles = $t.getDfnTitles(); 188 | const n = $t.makeID("dfn", titles[0]); 189 | if (n) { 190 | termNames[n] = $t.parent(); 191 | } 192 | } 193 | 194 | const $container = $(".termlist", base) ; 195 | const containerID = $container.makeID("", "terms") ; 196 | return (base.innerHTML); 197 | } 198 | 199 | require(["core/pubsubhub"], (respecEvents) => { 200 | "use strict"; 201 | 202 | respecEvents.sub('end', (message) => { 203 | // remove data-cite on where the citation is to ourselves. 204 | const selfDfns = document.querySelectorAll("dfn[data-cite^='" + respecConfig.shortName.toUpperCase() + "#']"); 205 | for (const dfn of selfDfns) { 206 | delete dfn.dataset.cite; 207 | } 208 | 209 | // Update data-cite references to ourselves. 210 | const selfRefs = document.querySelectorAll("a[data-cite^='" + respecConfig.shortName.toUpperCase() + "#']"); 211 | for (const anchor of selfRefs) { 212 | anchor.href= anchor.dataset.cite.replace(/^.*#/,"#"); 213 | delete anchor.dataset.cite; 214 | } 215 | }); 216 | 217 | // add a handler to come in after all the definitions are resolved 218 | // 219 | // New logic: If the reference is within a 'dl' element of 220 | // class 'termlist', and if the target of that reference is 221 | // also within a 'dl' element of class 'termlist', then 222 | // consider it an internal reference and ignore it. 223 | respecEvents.sub('end', (message) => { 224 | if (message === 'core/link-to-dfn') { 225 | // all definitions are linked; find any internal references 226 | const internalTerms = document.querySelectorAll(".termlist a.internalDFN"); 227 | for (const item of internalTerms) { 228 | const idref = item.getAttribute('href').replace(/^#/,"") ; 229 | if (termNames[idref]) { 230 | // this is a reference to another term 231 | // what is the idref of THIS term? 232 | const def = item.closest('dd'); 233 | if (def) { 234 | const tid = def.previousElementSibling 235 | .querySelector('dfn') 236 | .getAttribute('id'); 237 | if (tid) { 238 | if (termsReferencedByTerms[tid] === undefined) termsReferencedByTerms[tid] = []; 239 | termsReferencedByTerms[tid].push(idref); 240 | } 241 | } 242 | } 243 | } 244 | 245 | // clearRefs is recursive. Walk down the tree of 246 | // references to ensure that all references are resolved. 247 | const clearRefs = (theTerm) => { 248 | if (termsReferencedByTerms[theTerm] ) { 249 | for (const item of termsReferencedByTerms[theTerm]) { 250 | if (termNames[item]) { 251 | delete termNames[item]; 252 | clearRefs(item); 253 | } 254 | } 255 | }; 256 | // make sure this term doesn't get removed 257 | if (termNames[theTerm]) { 258 | delete termNames[theTerm]; 259 | } 260 | }; 261 | 262 | // now termsReferencedByTerms has ALL terms that 263 | // reference other terms, and a list of the 264 | // terms that they reference 265 | const internalRefs = document.querySelectorAll("a[data-link-type='dfn']"); 266 | for (const item of internalRefs) { 267 | const idref = item.getAttribute('href').replace(/^.*#/,"") ; 268 | // if the item is outside the term list 269 | if (!item.closest('dl.termlist')) { 270 | clearRefs(idref); 271 | } 272 | } 273 | 274 | // delete any terms that were not referenced. 275 | for (const term in termNames) { 276 | const $p = $("#"+term); 277 | // Remove term definitions inside a dt, where data-cite does not start with shortname 278 | if ($p === undefined) { continue; } 279 | if (!$p.parent().is("dt")) { continue; } 280 | if (($p.data("cite") || "").toLowerCase().startsWith(respecConfig.shortName)) { continue; } 281 | 282 | const $dt = $p.parent(); 283 | const $dd = $dt.next(); 284 | 285 | // If the associated dd contains a dfn which is _not_ in termNames, warn 286 | if ($dd.children("dfn").length > 0) { 287 | console.log(term + " definition contains definitions " + $dd.children("dfn").attr("id")) 288 | } 289 | console.log("drop term " + term); 290 | const tList = $p.getDfnTitles(); 291 | $dd.remove(); // remove dd 292 | $dt.remove(); // remove dt 293 | } 294 | } 295 | }); 296 | }); 297 | 298 | function _esc(s) { 299 | return s.replace(/&/g,'&') 300 | .replace(/>/g,'>') 301 | .replace(/"/g,'"') 302 | .replace(/ s.trim()).map(s => s.search(/[^\s]/)); 312 | const leastIndent = Math.min(...indents); 313 | return lines.map(s => s.slice(leastIndent)).join("\n"); 314 | } 315 | 316 | function updateExample(doc, content) { 317 | // perform transformations to make it render and prettier 318 | return _esc(reindent(unComment(doc, content))); 319 | } 320 | 321 | function unComment(doc, content) { 322 | // perform transformations to make it render and prettier 323 | return content 324 | .replace(//, '') 326 | .replace(/< !\s*-\s*-/g, '') 328 | .replace(/-\s*-\s*>/g, '-->'); 329 | } 330 | -------------------------------------------------------------------------------- /index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Decentralized Identifiers (DIDs) v1.0 6 | 7 | 12 | 13 | 16 | 17 | 19 | 129 | 142 | 143 | 144 |
145 |

146 | This document is undergoing a major structural refactoring and will not be easy 147 | to read. A previously 148 | published version that has a better topical flow may be a better read for 149 | people new to this work. When this document has been updated to have a 150 | better flow, this comment will be removed. 151 |

152 | 153 |

154 | Decentralized identifiers (DIDs) are a new type of identifier that 155 | enables verifiable, decentralized digital identity. A DID identifies 156 | any subject (e.g., a person, organization, thing, data model, abstract entity, etc.) 157 | that the controller of the DID decides that it 158 | identifies. These new identifiers are designed to enable the controller 159 | of a DID to prove control over it and to be implemented independently 160 | of any centralized registry, identity provider, or certificate authority. 161 | DIDs are URLs that associate a DID subject with a 162 | DID document allowing trustable interactions associated with that subject. 163 | Each DID document can express cryptographic material, verification methods, 164 | or service endpoints, which provide a set of mechanisms enabling a 165 | DID controller to prove control of the DID. Service 166 | endpoints enable trusted interactions associated with the DID 167 | subject. A DID document might contain semantics about the subject 168 | that it identifies. A DID document might contain the DID subject 169 | itself (e.g. a data model). 170 |

171 |

172 | This document specifies a common data model, a URL format, and a set of 173 | operations for DIDs, DID documents, and DID methods. 174 |

175 |
176 | 177 |
178 | 179 |

180 | This specification is under active development and implementers are advised 181 | against implementing the specification unless they are directly involved 182 | with the W3C DID Working Group. There are use cases [[?DID-USE-CASES]] in active 183 | development that establish requirements for this document. 184 |

185 | 186 |

187 | At present, there exist 188 | 40 189 | experimental implementations and a preliminary 190 | test suite 191 | that will eventually determine whether or not implementations are conformant. 192 | Readers are advised that Appendix contains a 193 | list of concerns and proposed changes that will most likely result in 194 | alterations to this specification. 195 |

196 | 197 |

198 | Comments regarding this document are welcome. Please file issues 199 | directly on GitHub, 200 | or send them 201 | to public-did-wg@w3.org ( 202 | subscribe, 203 | archives). 204 |

205 | 206 |

207 | Portions of the work on this specification have been funded by the 208 | United States Department of Homeland Security's Science and Technology 209 | Directorate under contracts HSHQDC-16-R00012-H-SB2016-1-002 and 210 | HSHQDC-17-C-00019. The content of this specification does not 211 | necessarily reflect the position or the policy of the U.S. Government 212 | and no official endorsement should be inferred. 213 |

214 | 215 |

216 | Work on this specification has also been supported by the Rebooting the 217 | Web of Trust community facilitated by Christopher Allen, Shannon 218 | Appelcline, Kiara Robles, Brian Weller, Betty Dhamers, Kaliya Young, 219 | Kim Hamilton Duffy, Manu Sporny, Drummond Reed, Joe Andrieu, and 220 | Heather Vescent. 221 |

222 |
223 | 224 |
225 |

226 | Introduction 227 |

228 | 229 |

230 | Conventional identity management 231 | systems are based on centralized authorities such as corporate 232 | directory services, 233 | certificate authorities, 234 | or domain name registries. 235 | From the standpoint of cryptographic trust verification, each of these 236 | centralized authorities serves as its own 237 | root of trust. To make 238 | identity management work across these systems requires implementing 239 | federated identity management. 240 |

241 | 242 |

243 | The emergence of distributed ledger technology (DLT) and 244 | blockchain technology provides the opportunity for fully 245 | decentralized identity management. In a decentralized identity system, 246 | entities (that is, discrete identifiable units such as, but not limited to, 247 | people, organizations, and things) are free to use any shared root of trust. 248 | Globally distributed ledgers, decentralized P2P networks, or other systems 249 | with similar capabilities, provide the means for managing a root of 250 | trust without introducing a centralized authority or a single point of 251 | failure. In combination, DLTs and 252 | decentralized identity management systems enable any entity to create and 253 | manage their own identifiers on any number of distributed, independent roots of 254 | trust. 255 |

256 | 257 |

258 | Entities are identified by decentralized identifiers (DIDs), and 259 | can authenticate using proofs (for example, digital signatures, 260 | privacy-preserving biometric protocols, and so on). DIDs point to 261 | DID documents. A DID document contains a set of 262 | service endpoints for interacting with the entity that the DID 263 | identifies (that is, the DID subject). Following the guidelines of 264 | Privacy by 265 | Design, any entity can have as many DIDs (and corresponding 266 | DID documents and service endpoints) as necessary to respect the 267 | entity’s desired separation of identities, personas, and contexts (in the 268 | everyday sense of these words). 269 |

270 | 271 |

272 | DID methods are the mechanism by which a DID and its associated 273 | DID document are created, read, updated, and deactivated on a specific 274 | distributed ledger or network. DID methods are defined using 275 | separate DID method specifications. 276 |

277 | 278 |

279 | This design eliminates dependence on centralized registries for 280 | identifiers as well as centralized certificate authorities for key 281 | management, which is the standard in hierarchical 282 | PKI (public key infrastructure). 283 | In cases where the DID registry is a distributed ledger, each 284 | entity can serve as its own root authority. This architecture is referred to as 285 | DPKI (decentralized PKI). 286 |

287 | 288 |

289 | DID methods can also be developed for identifiers registered in federated 290 | or centralized identity management systems. Indeed, all types of identifier 291 | systems can add support for DIDs. This creates an interoperability bridge 292 | between the worlds of centralized, federated, and 293 | decentralized identifiers. 294 |

295 | 296 |

297 | The first purpose of this specification is to define the generic 298 | DID scheme and a generic set of operations on DID documents that 299 | can be implemented for any DID registry. The second purpose of this 300 | specification is to define the conformance requirements for a DID method 301 | specification. The DID method specification is a separate document that 302 | defines a specific DID scheme and specific set of DID document 303 | operations for a specific DID registry. 304 |

305 | 306 |

307 | Conceptually, the relationship between this specification and a 308 | DID method specification is similar to the relationship between the IETF 309 | generic URI specification ([[RFC3986]]) and a specific URI scheme 310 | ([[IANA-URI-SCHEMES]] (such as the http: and https: schemes specified in 311 | [[RFC7230]]). It is also similar to the relationship between the IETF generic 312 | URN specification ([[RFC8141]]) and a specific URN namespace definition, (such 313 | as the UUID URN namespace defined in [[RFC4122]]). The difference is that 314 | a DID method specification, as well as defining a specific 315 | DID scheme, also specifies the methods for resolving and deactivating 316 | DIDs on, and writing DID documents to, the appropriate 317 | DID registry. 318 |

319 | 320 |

321 | The hierarchical design of a generic DID specification with specific 322 | DID method specifications introduces some of the same concepts as the 323 | URI specification: 324 |

325 |
    326 |
  • 327 | DIDs from different DID methods might not be interoperable, just 328 | as URIs from different URI schemes might not be interoperable. 329 |
    • 330 |
  • 331 | Entities might need multiple DIDs to support different relationships 332 | because the other party might only support certain DID methods, in the 333 | same way that some browsers might only support certain URI schemes. 334 |
    • 335 |
  • 336 | Entities might need multiple DIDs to support the different cryptographic 337 | schemes of different DID methods because not all parties will support the 338 | same cryptographic schemes, in the same way that not all browsers support the 339 | same URI schemes. 340 |
    • 341 |
  • 342 | Managing multiple DIDs, and tracking which DID belongs to which 343 | relationship, under which cryptographic scheme, introduces similar logistical 344 | challenges as managing multiple web addresses and tracking which address belongs 345 | to which website, or tracking which email address belongs to which relationship. 346 |
    • 347 |
348 | 349 |

350 | For a list of DID methods and their corresponding specifications, 351 | see the DID Method Registry [[?DID-METHOD-REGISTRY]]. 352 |

353 | 354 |
355 |

356 | A Simple Example 357 |

358 | 359 |

360 | A DID is a simple text string consisting of three parts, the: 361 |

362 |
    363 |
  • 364 | URL scheme identifier (did) 365 |
    • 366 |
  • 367 | Identifier for the DID method 368 |
    • 369 |
  • 370 | DID method-specific identifier. 371 |
    • 372 |
373 | 374 | 
 375 | did:example:123456789abcdefghi
 376 |
377 | 378 |

379 | The example DID above resolves to a DID document. A 380 | DID document contains information associated with the DID, such as 381 | ways to cryptographically authenticate the entity in control of the DID, 382 | as well as services that can be used to interact with the entity. 383 |

384 | 385 | 
 386 | {
 387 |   "@context": "https://www.w3.org/ns/did/v1",
 388 |   "id": "did:example:123456789abcdefghi",
 389 |   "authentication": [{
 390 |     // used to authenticate as did:...fghi
 391 |     "id": "did:example:123456789abcdefghi#keys-1",
 392 |     "type": "RsaVerificationKey2018",
 393 |     "controller": "did:example:123456789abcdefghi",
 394 |     "publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n"
 395 |   }],
 396 |   "service": [{
 397 |     // used to retrieve Verifiable Credentials associated with the DID
 398 |     "id":"did:example:123456789abcdefghi#vcs",
 399 |     "type": "VerifiableCredentialService",
 400 |     "serviceEndpoint": "https://example.com/vc/"
 401 |   }]
 402 | }
 403 |
404 |
405 | 406 |
407 |

408 | Design Goals 409 |

410 | 411 |

412 | Decentralized Identifiers are a component of larger systems, such as 413 | the Verifiable Credentials ecosystem [[VC-DATA-MODEL]], which drove the design 414 | goals for this specification. This section summarizes the primary design goals 415 | for this specification. 416 |

417 | 418 | 419 | 420 | 421 | 424 | 427 | 428 | 429 | 430 | 431 | 432 | 435 | 441 | 442 | 443 | 444 | 447 | 451 | 452 | 453 | 454 | 457 | 461 | 462 | 463 | 464 | 467 | 471 | 472 | 473 | 474 | 477 | 481 | 482 | 483 | 484 | 487 | 491 | 492 | 493 | 494 | 497 | 501 | 502 | 503 | 504 | 507 | 511 | 512 | 513 | 514 | 517 | 521 | 522 | 523 | 524 | 527 | 531 | 532 | 533 |
422 | Goal 423 | 425 | Description 426 |
433 | Decentralization 434 | 436 | Eliminate the requirement for centralized authorities or single point 437 | failure in identifier management, including the registration of globally unique 438 | identifiers, public verification keys, service endpoints, and other 439 | metadata. 440 |
445 | Control 446 | 448 | Give entities, both human and non-human, the power to directly control their 449 | digital identifiers without the need to rely on external authorities. 450 |
455 | Privacy 456 | 458 | Enable entities to control the privacy of their information, including minimal, 459 | selective, and progressive disclosure of attributes or other data. 460 |
465 | Security 466 | 468 | Enable sufficient security for relying parties to depend on DID documents 469 | for their required level of assurance. 470 |
475 | Proof-based 476 | 478 | Enable DID subjects to provide cryptographic proof when interacting with 479 | other entities. 480 |
485 | Discoverability 486 | 488 | Make it possible for entities to discover DIDs for other entities to 489 | learn more about or interact with those entities. 490 |
495 | Interoperability 496 | 498 | Use interoperable standards so DID infrastructure can make use of 499 | existing tools and software libraries designed for interoperability. 500 |
505 | Portability 506 | 508 | Be system and network-independent and enable entities to use their digital 509 | identifiers with any system that supports DIDs and DID methods. 510 |
515 | Simplicity 516 | 518 | Favor a reduced set of simple features to make the technology easier to 519 | understand, implement, and deploy. 520 |
525 | Extensibility 526 | 528 | Where possible, enable extensibility provided it does not greatly hinder 529 | interoperability, portability, or simplicity. 530 |
534 |
535 | 536 |
537 |

538 | Interoperability 539 |

540 | 541 |

542 | Interoperability of implementations for DIDs and DID documents 543 | will be tested by evaluating an implementation's ability to create and parse 544 | DIDs and DID documents that conform to the specification. 545 | Interoperability for DID methods will be determined by evaluating each 546 | DID method specification to determine, at a minimum, that the: 547 |

548 |
    549 |
  • 550 | DID method name is unique and not used by an existing, incompatible 551 | DID method. 552 |
    • 553 |
  • 554 | Required operations are supported. 555 |
    • 556 |
  • 557 | Operations requiring descriptions are described. 558 |
    • 559 |
  • 560 | Specification is specific, detailed, and complete enough for independent 561 | implementation. 562 |
    • 563 |
  • 564 | Specification contains sections describing security and privacy considerations. 565 |
    • 566 |
567 | 568 |

569 | Interoperability for producers and consumers of DIDs and 570 | DID documents is provided by ensuring the DIDs and 571 | DID documents conform. Interoperability for DID method 572 | specifications is provided by the details in each DID method 573 | specification. It is understood that, in the same way that a web browser is not 574 | required to implement all known URI schemes, conformant software that works 575 | with DIDs is not required to implement all known DID methods. 576 | However, all implementations of a given DID method must be interoperable 577 | for that method. 578 |

579 |
580 | 581 |
582 | 583 |
584 |

585 | Terminology 586 |

587 | 588 |
589 |
590 | 591 |
592 | 593 |
594 |

Overall Architecture

595 | 596 |
597 |

DIDs

598 |
599 | 600 |
601 |

DID Registries

602 |
603 | 604 |
605 |

DID Documents

606 | 607 |

608 | A DID document is the resource that is associated with a 609 | decentralized identifier (DID). DID documents typically express 610 | verification methods (such as public keys) and services that can be used to 611 | interact with a DID controller. 612 |

613 | 614 |

615 | A DID document is serialized according to a particular syntax, as 616 | outlined in Section ). The DID itself 617 | is contained in the id property. 618 |

619 | 620 |

621 | The properties that can be present in a DID document are outlined in 622 | Section . 623 |

624 | 625 |

626 | The properties present in a DID document can be updated according to 627 | the applicable operations outlined in Section . 628 |

629 | 630 |
631 | 632 |
633 |

DID Resolvers and DID Resolution

634 |
635 | 636 |
637 |

Security and Privacy

638 |
639 | 640 |
641 | 642 |
643 | 644 |

645 | This document contains examples that contain JSON, CBOR, and JSON-LD content. 646 | Some of these examples contain characters that are invalid, such as inline 647 | comments (//) and the use of ellipsis (...) to denote 648 | information that adds little value to the example. Implementers are cautioned to 649 | remove this content if they desire to use the information as valid JSON, CBOR, 650 | or JSON-LD. 651 |

652 | 653 |

654 | A conforming DID is any concrete expression of the rules 655 | specified in Section and MUST comply with relevant 656 | normative statements in that section. 657 |

658 | 659 |

660 | A conforming DID Document is any concrete expression of the data 661 | model described in this specification and MUST comply with the relevant 662 | normative statements in Sections and . A serialization format for the conforming document 664 | MUST be deterministic, bi-directional, and lossless as described in Section . The conforming DID document MAY be 666 | transmitted or stored in any such serialization format. 667 |

668 | 669 |

670 | A conforming DID Method is any specification that complies with the 671 | relevant normative statements in Section . 672 |

673 | 674 |

675 | A producer is any algorithm realized as software and/or 676 | hardware and conforms to this specification if it generates 677 | conforming DIDs or conforming DID Documents. 678 | A producer that is conformant with this specification MUST NOT produce 679 | non-conforming DIDs or DID Documents. 680 |

681 | 682 |

683 | A consumer is any algorithm realized as software and/or 684 | hardware and conforms to this specification if it consumes 685 | conforming DIDs or conforming DID Documents. A 686 | consumer that is conformant with this specification MUST produce errors 687 | when consuming non-conforming DIDs or DID Documents. 688 |

689 | 690 |
691 | 692 |
693 |

Identifier

694 | 695 |

696 | The concept of a globally unique decentralized identifier is not new. 697 | Universally Unique Identifiers (UUIDs) were first developed in the 1980s 698 | and later became a standard feature of the Open Software Foundation’s 699 | Distributed Computing Environment. 700 | UUIDs achieve global uniqueness without a centralized registry service by 701 | using an algorithm that generates 128-bit values with sufficient entropy that 702 | the chance of collision are infinitesimally small. UUIDs are formally 703 | specified in [[RFC4122]] as a specific type of Unified Resource Name (URN). 704 |

705 | 706 |

707 | A DID is similar to a UUID except that: 708 |

709 |
    710 |
  • 711 | Like a URL, it can be resolved or dereferenced to a standard resource describing 712 | the subject. That is, a DID document. For more information, see Section 713 | . 714 |
    • 715 |
  • 716 | Unlike most resources returned when dereferencing URLs, a DID document 717 | usually contains cryptographic material enabling authentication of the 718 | DID subject. 719 |
    • 720 |
721 | 722 |
723 |

DID Syntax

724 |
725 |

Generic DID Syntax

726 | 727 |

728 | The generic DID scheme is a URI scheme conformant with [[!RFC3986]]. 729 | 730 |

731 | A DID always identifies the DID subject. 732 |

733 | 734 |

735 | The following is the ABNF definition using the syntax in [[!RFC5234]], which 736 | defines ALPHA and DIGIT. All other rule names not 737 | defined in this ABNF are defined in [[RFC3986]]. 738 |

739 | 740 | 
 741 |   did                = "did:" method-name ":" method-specific-id
 742 |   method-name        = 1*method-char
 743 |   method-char        = %x61-7A / DIGIT
 744 |   method-specific-id = *( ":" *idchar ) 1*idchar
 745 |   idchar             = ALPHA / DIGIT / "." / "-" / "_"
 746 |
747 | 748 |

749 | The grammar currently allows an empty method-specific-id, 750 | e.g., did:example: would be a valid DID that could identify 751 | the DID method itself. 752 |

753 |
754 |
755 |

Method-Specific Syntax

756 | 757 |

758 | A DID method specification MUST further restrict the generic DID 759 | syntax by defining its own method-name and its own 760 | method-specific-id syntax. For more information, see Section 761 | . 762 |

763 | 764 |
765 |
766 |

Normalization

767 | 768 |

769 | For the broadest interoperability, make DID normalization as simple and 770 | universal as possible: 771 |

772 |
    773 |
  • 774 | The DID scheme name MUST be lowercase. 775 |
    • 776 | 777 |
  • 778 | The DID method name MUST be lowercase. 779 |
    • 780 | 781 |
  • 782 | Case sensitivity and normalization of the value of the 783 | method-specific-id rule in Section 784 | MUST be defined by the governing 785 | DID method specification. 786 |
    • 787 |
788 |
789 | 790 |
791 |

Persistence

792 | 793 |

794 | A DID is expected to be persistent and immutable. That is, a DID 795 | is bound exclusively and permanently to its one and only subject. Even after a 796 | DID is deactivated, it is intended that it never be repurposed. 797 |

798 | 799 |

800 | Ideally, a DID would be a completely abstract decentralized identifier 801 | (like a UUID) that could be bound to multiple underlying 802 | DID registries over time, thus maintaining its persistence independent of 803 | any particular system. However, registering the same identifier on multiple 804 | DID registries introduces extremely hard entityship and 805 | start-of-authority 806 | (SOA) problems. It also greatly increases implementation complexity for 807 | developers. 808 |

809 | 810 |

811 | To avoid these issues, developers should refer to the Decentralized Characteristics 812 | Rubric [[?DID-RUBRIC]] to decide which DID method best addresses the needs of 813 | the use case. 814 |

815 | 816 |

817 | Although not included in this version, future versions of this specification 818 | might support a DID document equivID property to establish 819 | verifiable equivalence relations between DIDs representing the same 820 | subject on multiple DID registries. Such equivalence relations can 821 | produce the practical equivalent of a single persistent abstract DID. For 822 | more information, see Section . 823 |

824 |
825 |
826 | 827 |
828 |

DID URL Syntax

829 | 830 |
831 |

Generic DID URL Syntax

832 | 833 |

834 | A DID URL always identifies a resource to 835 | be located. It can be used, for example, to identify a specific part of a DID document. 836 |

837 | 838 |

839 | This following is the ABNF definition using the syntax in [[!RFC5324]]. It builds on the did scheme defined in . The path-abempty, query, and 840 | fragment components are identical to the ABNF rules defined in 841 | [[!RFC3986]]. 842 |

843 | 844 | 845 | 
 846 |   did-url            = did *( ";" param ) path-abempty [ "?" query ]
 847 |                        [ "#" fragment ]
 848 |   param              = param-name [ "=" param-value ]
 849 |   param-name         = 1*param-char
 850 |   param-value        = *param-char
 851 |   param-char         = ALPHA / DIGIT / "." / "-" / "_" / ":" /
 852 |                        pct-encoded
 853 |
854 | 855 |
856 | 857 |
858 |

Generic DID URL Parameters

859 | 860 |

861 | The DID URL syntax supports a simple, generalized format for parameters 862 | based on the matrix parameter syntax ([[?MATRIX-URIS]]). The ABNF above 863 | specifies the basic syntax (the param-name rule) but does not 864 | specify any concrete parameter names. 865 |

866 |

867 | Some generic DID parameter names (for example, for service selection) are 868 | completely independent of any specific DID method and MUST always 869 | function the same way for all DIDs. Other DID parameter names (for 870 | example, for versioning) MAY be supported by certain DID methods, but 871 | MUST operate uniformly across those DID methods that do support them. 872 |

873 |

874 | Parameter names that are completely method-specific are described in Section 875 | . 876 |

877 |

878 | The following table defines a set of generic DID parameter names. 879 |

880 | 881 | 882 | 883 | 884 | 887 | 890 | 891 | 892 | 893 | 894 | 895 | 898 | 902 | 903 | 904 | 907 | 910 | 911 | 912 | 915 | 920 | 921 | 922 | 923 | 926 | 931 | 932 | 933 |
885 | Generic DID Parameter Name 886 | 888 | Description 889 |
896 | hl 897 | 899 | A resource hash of the DID document to add integrity protection, as 900 | specified in [[?HASHLINK]]. 901 |
905 | service 906 | 908 | Identifies a service from the DID document by service ID. 909 |
913 | version-id 914 | 916 | Identifies a specific version of a DID document to be resolved (the 917 | version ID could be sequential, or a UUID, or method-specific). Note that 918 | this parameter might not be supported by all DID methods. 919 |
924 | version-time 925 | 927 | Identifies a certain version timestamp of a DID document to be resolved. 928 | That is, the DID document that was valid for a DID at a certain 929 | time. Note that this parameter might not be supported by all DID methods. 930 |
934 | 935 |

936 | The exact processing rules for these parameters are specified in 937 | [[?DID-RESOLUTION]]. 938 |

939 | 940 |

941 | Adding a DID parameter to a DID URL means that the parameter becomes part of 942 | an identifier for a resource (the DID document or other). Alternatively, the 943 | DID resolution and the DID URL dereferencing processes can also be influenced 944 | by passing options to a DID resolver that are not part of the DID URL. 945 | Such options could for example control caching or the desired encoding of a 946 | resolution result. This is comparable to HTTP, where certain parameters could 947 | either be included in an HTTP URL, or alternatively passed as HTTP headers 948 | during the dereferencing process. The important distinction is that DID 949 | parameters that are part of the DID URL should be used to specify 950 | what resource is being identified, whereas DID resolver options 951 | that are not part of the DID URL should be use to control how that 952 | resource is dereferenced. 953 |

954 | 955 |

956 | DID parameters MAY be used if there is a clear use case where 957 | the parameter needs to be part of a URI that can be used as a link, or 958 | as a resource in RDF / JSON-LD documents. 959 |

960 | 961 |

962 | DID parameters SHOULD NOT be used if there are already other, equivalent 963 | ways of constructing URIs that fulfill the same purpose (for example, using 964 | other syntactical constructs such as URI query strings or URI fragments). 965 |

966 | 967 |

968 | DID parameters SHOULD NOT be used if the same functionality can be expressed 969 | by passing options to a DID resolver, and if there is no need to 970 | construct a URI for use as a link, or as a resource in RDF / JSON-LD documents. 971 |

972 | 973 |
974 | 975 |
976 |

Method-Specific DID URL Parameters

977 | 978 |

979 | A DID method specification MAY specify additional method-specific 980 | parameter names. A method-specific parameter name MUST be prefixed by the method 981 | name, as defined by the method-name rule. 982 |

983 | 984 |

985 | For example, if the method did:foo: defines the parameter bar, the 986 | parameter name must be foo:bar. An example DID URL using 987 | this method and this method-specific parameter would be as shown below. 988 |

989 | 990 | 
 991 |   did:foo:21tDAKCERh95uGgKbJNHYp;foo:bar=high
 992 |
993 | 994 |

995 | A method-specific parameter name defined by one DID method MAY be used by 996 | other DID methods. 997 |

998 | 999 | 
1000 |   did:example:21tDAKCERh95uGgKbJNHYp;foo:bar=low
1001 |
1002 | 1003 |

1004 | Method-specific parameter names MAY be combined with generic parameter names in 1005 | any order. 1006 |

1007 | 1008 | 
1009 |   did:example:21tDAKCERh95uGgKbJNHYp;service=agent;foo:bar=high
1010 |
1011 | 1012 |

1013 | Both DID method namespaces and method-specific parameter namespaces MAY 1014 | include colons, so they might be partitioned hierarchically, as defined by a 1015 | DID method specification. The following example DID URL 1016 | illustrates both. 1017 |

1018 | 1019 | 
1020 |   did:foo:baz:21tDAKCERh95uGgKbJNHYp;foo:baz:hex=b612
1021 |
1022 | 1023 |

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

1028 | 1029 |
1030 | 1031 |
1032 |

Path

1033 | 1034 |

1035 | A generic DID path is identical to a URI path and MUST conform to the 1036 | path-abempty ABNF rule in [[!RFC3986]]. A DID path SHOULD be 1037 | used to address resources available through a service endpoint. For more 1038 | information, see Section . 1039 |

1040 | 1041 |

1042 | A specific DID scheme MAY specify ABNF rules for DID paths that 1043 | are more restrictive than the generic rules in this section. 1044 |

1045 | 1046 | 
1047 |   did:example:123456/path
1048 |
1049 |
1050 | 1051 |
1052 |

Query

1053 | 1054 |

1055 | A generic DID query is identical to a URI query and MUST conform to the 1056 | query ABNF rule in [[!RFC3986]]. A DID query SHOULD be used 1057 | to address resources available through a service endpoint. For more 1058 | information, see Section . 1059 |

1060 | 1061 |

1062 | A specific DID scheme MAY specify ABNF rules for DID queries that 1063 | are more restrictive than the generic rules in this section. 1064 |

1065 | 1066 | 
1067 |   did:example:123456?query=true
1068 |
1069 |
1070 | 1071 |
1072 |

Fragment

1073 | 1074 |

1075 | A DID fragment is used as method-independent reference into the DID 1076 | document to identify a component of the document (for example, a unique 1077 | public key description or service endpoint). DID fragment 1078 | syntax and semantics are identical to a generic URI fragment and MUST conform 1079 | to RFC 3986, section 3.5. To resolve 1080 | a DID fragment reference, the complete DID URL including the 1081 | DID fragment MUST be used as input to the DID URL dereferencing 1082 | algorithm for the target component in the DID document object. For more 1083 | information, see [[?DID-RESOLUTION]]. 1084 |

1085 | 1086 |

1087 | A specific DID scheme MAY specify ABNF rules for DID fragments 1088 | that are more restrictive than the generic rules in this section. 1089 |

1090 | 1091 |

1092 | Implementations need not rely on graph-based processing of DID documents 1093 | to locate metadata contained in the DID document when the DID 1094 | includes a DID fragment. Tree-based processing can be used instead. 1095 |

1096 | 1097 |

1098 | Implementations SHOULD NOT prevent the use of JSON Pointer 1099 | ([[!RFC6901]]). 1100 |

1101 | 1102 | 
1103 |   did:example:123456#public-key-1
1104 |
1105 | 1106 |

1107 | Additional semantics for fragment identifiers, which are compatible with and 1108 | layered upon the semantics in this section, are described for JSON-LD 1109 | representations in Section . 1110 |

1111 | 1112 |
1113 | 1114 |
1115 |

Relative DID URLs

1116 | 1117 |

1118 | A relative DID URL is any URL value in a DID document that does not start 1119 | with did:<method-name>:<method-specific-id>. More 1120 | specifically, it is any URL value that does not start with the ABNF defined in 1121 | Section . The contents of the URL typically 1122 | refers to a resource in the same DID document. Relative DID URLs MAY 1123 | contain relative path components, query parameters, and fragment identifiers. 1124 |

1125 | 1126 |

1127 | When resolving a relative DID URL reference, the algorithm specified in RFC3986 Section 5: Reference Resolution MUST 1129 | be used. The base URI value is the DID that is 1130 | associated with the DID subject, see Section . 1131 | The scheme is did. The authority 1132 | is a combination of <method-name>:<method-specific-id>, and 1133 | the path, query, and fragment 1134 | values are those defined in Section , Section , and Section , respectively. 1136 |

1137 | 1138 |

1139 | Relative DID URLs are often used to identify verification methods and 1140 | services in a DID Document without having to use absolute URLs, which 1141 | tend to be more verbose than necessary. 1142 |

1143 | 1144 | 
1145 | {
1146 |   "@context": "https://www.w3.org/ns/did/v1",
1147 |   "id": "did:example:123456789abcdefghi",
1148 |   "publicKey": [{
1149 |     "id": "did:example:123456789abcdefghi#key-1",
1150 |     "type": "RsaVerificationKey2018",
1151 |     "controller": "did:example:123456789abcdefghi",
1152 |     "publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n"
1153 |   }, ...],
1154 |   "authentication": [
1155 |     // a relative DID URL used to reference a verification method above
1156 |     "#key-1"
1157 |   ]
1158 | }
1159 |
1160 | 1161 |

1162 | In the example above, the relative DID URL value will be transformed to an 1163 | absolute DID URL value of did:example:123456789abcdefghi#key-1. 1164 |

1165 |
1166 | 1167 |
1168 | 1169 |
1170 | 1171 |
1172 |

Data Model

1173 | 1174 |
1175 |

Definition

1176 |
1177 | 1178 |
1179 |

Extensibility

1180 |
1181 | 1182 |
1183 |

Representation Requirements

1184 |
1185 | 1186 |
1187 | 1188 |
1189 |

Core Properties

1190 | 1191 |

1192 | A DID points to a DID document. DID documents are the 1193 | serialization of the data model outlined in Section . 1194 | The following sections define the properties in a DID document, 1195 | including whether these properties are required or optional. 1196 |

1197 | 1198 |
1199 |

1200 | Identifiers 1201 |

1202 |

1203 | Identifiers are used in the data model to identify specific instances of people, 1204 | organizations, devices, keys, services, and things in general. Identifiers are 1205 | typically URLs, or more generally, URIs. Non-URI-based identifiers 1206 | are not advised because, while the data model supports them, they are not easy 1207 | to use with other Internet-based identifiers. 1208 |

1209 |
1210 | 1211 |
1212 |

DID Subject

1213 | 1214 |

1215 | The DID subject is denoted with the id property. The 1216 | DID subject is the entity that the DID document is about. That is, 1217 | it is the entity identified by the DID and described by the 1218 | DID document. 1219 |

1220 | 1221 |

1222 | DID documents MUST include the id property. 1223 |

1224 | 1225 |
1226 |
id
1227 |
1228 | The value of id MUST be a single valid DID. 1229 |
1230 |
1231 | 1232 | 
1233 | {
1234 |   "id": "did:example:21tDAKCERh95uGgKbJNHYp"
1235 | }
1236 |
1237 | 1238 |

1239 | DID method specifications can create intermediate representations of a 1240 | DID document that do not contain the id key, such as when a 1241 | DID resolver is performing resolution. However, the fully resolved 1242 | DID document always contains a valid id property. The value 1243 | of id in the resolved DID document is expected to match the 1244 | DID that was resolved. 1245 |

1246 |
1247 | 1248 |
1249 |

Public Keys

1250 | 1251 |

1252 | A DID document can express cryptographic keys and other verification 1253 | methods, which can be used to authenticate or authorize interactions with the 1254 | DID subject or associated parties. The information expressed often 1255 | includes globally unambiguous identifiers and public key material, which can be 1256 | used to verify digital signatures. Other information can be expressed, such as 1257 | status information for the key (for example, whether it is suspended or 1258 | revoked), or other attributes that enable one to determine whether it is a 1259 | hardware-backed cryptographic key. 1260 |

1261 | 1262 |

1263 | Regarding cryptographic key material, public keys can be included in a 1264 | DID document using, for example, the publicKey or 1265 | authentication properties, depending on what they are to be used 1266 | for. Each public key has an identifier (id) of its own, a 1267 | type, and a controller, as well as other properties 1268 | that depend on the type of key it is. 1269 |

1270 | 1271 |

1272 | This specification strives to limit the number of formats for expressing public 1273 | key material in a DID Document to the fewest possible, to increase the 1274 | likelihood of interoperability. The fewer formats that implementers have to 1275 | implement, the more likely it will be that they will support all of them. This 1276 | approach attempts to strike a delicate balance between ease of implementation 1277 | and supporting formats that have historically had broad deployment. The specific 1278 | types of key formats that are supported in this specification are listed below. 1279 |

1280 | 1281 |

1282 | A public key is a verification method. 1283 | Public keys are used for digital signatures, encryption and other cryptographic 1284 | operations, which in turn are the basis for purposes such as authentication 1285 | (see Section ) or establishing secure 1286 | communication with service endpoints (see Section 1287 | ). As well, public keys can play a role in 1288 | authorization mechanisms of DID method operations (see Section 1289 | ), which can be defined by DID method 1290 | specifications. 1291 |

1292 | 1293 |

1294 | A public key is just one type of verification method. A DID 1295 | document expresses the relationship between the DID subject and a 1296 | verification method using a verification relationship. 1297 | Examples of verification relationships include: 1298 | authentication, capabilityInvocation, 1299 | capabilityDelegation, keyAgreement, and 1300 | assertionMethod. A DID controller MUST be explicit about the 1301 | verification relationship between the DID subject and the verification 1302 | method. Verification methods that are not associated with a 1303 | particular verification relationship MUST NOT be used for that 1304 | verification relationship. See Section 1305 | for a more detailed example of a verification relationship. 1306 |

1307 | 1308 |

1309 | A DID document MAY include a publicKey property. 1310 |

1311 | 1312 |
1313 |
publicKey
1314 |
1315 | If a DID document includes a publicKey property, the value 1316 | of the property MUST be an array of public key objects. Each public key object 1317 | MUST have the type, controller, and specific public 1318 | key properties, and MUST have an id property. The public key 1319 | objects MAY include additional properties. 1320 |
1321 |
1322 | 1323 |

1324 | The value of the id property MUST be a URI. The 1325 | array of public keys MUST NOT contain multiple entries with the same 1326 | id. In this case, a DID document processor MUST produce an 1327 | error. 1328 |

1329 | 1330 |

1331 | The value of the type property MUST be exactly one public key type. 1332 | For a registry of available key types and formats, see Appendix 1333 | . 1334 |

1335 | 1336 |

1337 | The value of the controller property, which identifies the 1338 | controller of the corresponding private key, MUST be a valid DID. 1339 |

1340 | 1341 |

1342 | The semantics of the controller property are the same when the 1343 | subject of the relationship is the DID document as when the subject 1344 | of the relationship is a key. Since a key can't control itself, and the 1345 | key controller cannot be inferred from the DID document, it is 1346 | necessary to explicitly express the identity of the controller of the key 1347 | (which may be the DID controller or DID subject). The 1348 | difference is that the value of controller on a key is not 1349 | necessarily a DID controller. DID controller(s) are 1350 | expressed using the controller property on the top level of 1351 | the DID document; see Section . 1352 |

1353 | 1354 |

1355 | The value of the id property MAY be structured as a compound key. 1356 | This is especially useful for integrating with existing key management systems and key formats such as JWK. 1357 | It is RECOMMENDED that JWK kid values are set to the public key fingerprint. 1358 | It is RECOMMENDED that verification methods that use JWKs to represent their 1359 | public keys utilize the value of kid as their fragment identifier. 1360 | See the first key in EXAMPLE 12 for an example of a public key with a compound key identifier. 1361 |

1362 | 1363 |

1364 | All public key properties MUST be from the Linked Data Cryptographic Suite 1365 | Registry. For a registry of key types and formats, see Appendix 1366 | . 1367 |

1368 | 1369 |

1370 | If a public key does not exist in the DID document, it MUST be assumed 1371 | the key was revoked or is invalid. The DID document MAY contain revoked 1372 | keys. A DID document containing a revoked key MUST also contain or refer 1373 | to the revocation information for the key (for example, a revocation list). Each 1374 | DID method specification is expected to detail how revocation is 1375 | performed and tracked. 1376 |

1377 | 1378 |

1379 | Public keys of all types MUST be expressed in either JSON Web Key (JWK) format 1380 | using the publicKeyJwk property or one of the formats listed in the 1381 | table below. Public key expression MUST NOT use any other key format. 1382 |

1383 | 1384 |

1385 | The Working Group is still debating whether the base encoding format used will be 1386 | Base58 (Bitcoin) [[BASE58]], base64url [[RFC7515]], or base16 (hex) [[RFC4648]]. 1387 | The entries in the table below currently assume PEM and Base58 (Bitcoin), but might 1388 | change to base64url and/or base16 (hex) after the group achieves consensus on this 1389 | particular issue. 1390 |

1391 | 1392 |

1393 | The Working Group is still debating whether secp256k1 Schnorr public key values 1394 | will be elaborated upon in this specification and if so, how they will be 1395 | expressed and encoded. 1396 |

1397 | 1398 | 1399 | 1400 | 1401 | 1404 | 1407 | 1408 | 1409 | 1410 | 1411 | 1412 | 1415 | 1419 | 1420 | 1421 | 1424 | 1429 | 1430 | 1431 | 1434 | 1439 | 1440 | 1441 | 1444 | 1449 | 1450 | 1451 | 1454 | 1459 | 1460 | 1461 |
1402 | Key Type 1403 | 1405 | Support 1406 |
1413 | RSA 1414 | 1416 | RSA public key values MUST either be encoded as a JWK or be encoded in 1417 | Privacy Enhanced Mail (PEM) format using the publicKeyPem property. 1418 |
1422 | ed25519 1423 | 1425 | Ed25519 public key values MUST either be encoded as a JWK or be encoded as 1426 | the raw 32-byte public key value in Base58 Bitcoin format using the 1427 | publicKeyBase58 property. 1428 |
1432 | secp256k1-koblitz 1433 | 1435 | Secp256k1 Koblitz public key values MUST either be encoded as a JWK or be 1436 | encoded as the raw 33-byte public key value in Base58 Bitcoin format using the 1437 | publicKeyBase58 property. 1438 |
1442 | secp256r1 1443 | 1445 | Secp256r1 public key values MUST either be encoded as a JWK or be encoded as 1446 | the raw 32-byte public key value encoded in Base58 Bitcoin format using the 1447 | publicKeyBase58 property. 1448 |
1452 | Curve25519 1453 | 1455 | Curve25519 (also known as X25519) public key values MUST either be encoded as 1456 | a JWK or be encoded as the raw 32-byte public key value in Base58 Bitcoin format 1457 | using the publicKeyBase58 property. 1458 |
1462 | 1463 |

1464 | Example: 1465 |

1466 | 1467 | 
1468 | {
1469 |   "@context": ["https://www.w3.org/ns/did/v1", "https://w3id.org/security/v1"],
1470 |   "id": "did:example:123456789abcdefghi",
1471 |   ...
1472 |   "publicKey": [{
1473 |     "id": "did:example:123#_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A",
1474 |     "type": "JwsVerificationKey2020",
1475 |     "controller": "did:example:123",
1476 |     "publicKeyJwk": {
1477 |       "crv": "Ed25519",
1478 |       "x": "VCpo2LMLhn6iWku8MKvSLg2ZAoC-nlOyPVQaO3FxVeQ",
1479 |       "kty": "OKP",
1480 |       "kid": "_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A"
1481 |     }
1482 |   }, {
1483 |     "id": "did:example:123456789abcdefghi#keys-1",
1484 |     "type": "RsaVerificationKey2018",
1485 |     "controller": "did:example:123456789abcdefghi",
1486 |     "publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n"
1487 |   }, {
1488 |     "id": "did:example:123456789abcdefghi#keys-2",
1489 |     "type": "Ed25519VerificationKey2018",
1490 |     "controller": "did:example:pqrstuvwxyz0987654321",
1491 |     "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
1492 |   }, {
1493 |     "id": "did:example:123456789abcdefghi#keys-3",
1494 |     "type": "Secp256k1VerificationKey2018",
1495 |     "controller": "did:example:123456789abcdefghi",
1496 |     "publicKeyHex": "02b97c30de767f084ce3080168ee293053ba33b235d7116a3263d29f1450936b71"
1497 |   }],
1498 |   ...
1499 | }
1500 |
1501 | 1502 |

1503 | A key MAY be embedded or referenced in a DID document. 1504 | For example, the authentication property might refer to keys in 1505 | both ways, as shown in the example below. 1506 |

1507 | 1508 | 
1509 | {
1510 | ...
1511 | 
1512 |   "authentication": [
1513 |     // this key is referenced, it may be used with more than one verification relationship
1514 |     "did:example:123456789abcdefghi#keys-1",
1515 |     // this key is embedded and may *only* be used for authentication
1516 |     {
1517 |       "id": "did:example:123456789abcdefghi#keys-2",
1518 |       "type": "Ed25519VerificationKey2018",
1519 |       "controller": "did:example:123456789abcdefghi",
1520 |       "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
1521 |     }
1522 |   ],
1523 | 
1524 | ...
1525 | }
1526 |
1527 | 1528 |

1529 | The steps to use when processing a publicKey property in a 1530 | DID document are: 1531 |

1532 | 1533 |
    1534 |
  1. 1535 | Let value be the data associated with the publicKey 1536 | property and initialize result to null. 1537 |
    2. 1538 | 1539 |
  2. 1540 | If value is an object, the key material is embedded. Set 1541 | result to value. 1542 |
    3. 1543 | 1544 |
  3. 1545 | If value is a string, the key is included by reference. Assume 1546 | value is a URL. 1547 |
      1548 |
    1. 1549 | Dereference the URL and retrieve the publicKey properties 1550 | associated with the URL. For example, process the publicKey 1551 | property at the top-level of the dereferenced document. 1552 |
      2. 1553 | 1554 |
    2. 1555 | Iterating through each public key object, if the id property of the 1556 | object matches value, set result to the object. 1557 |
      3. 1558 |
    1559 |
    4. 1560 | 1561 |
  4. 1562 | If result does not contain at least the id, 1563 | type, and controller properties, as well as any 1564 | mandatory public cryptographic material, as determined by the type 1565 | property of result, throw an error. 1566 |
    5. 1567 |
1568 | 1569 |

1570 | Caching and expiration of the keys in a DID document is entirely the 1571 | responsibility of DID resolvers and other clients. For more information, 1572 | see Section . 1573 |

1574 | 1575 |
1576 | 1577 |
1578 |

Authentication

1579 | 1580 |

1581 | Authentication is a mechanism by which an entity can prove it is the 1582 | DID subject. The verifier of an authentication attempt 1583 | can check if the authenticating party is presenting a valid proof of 1584 | authentication, that is, that they are who they say they are. Note that 1585 | a successful authentication on its own may or may not confer authority; 1586 | that is up to the verifying application. 1587 |

1588 | 1589 |

1590 | If authentication is established, it is up to the DID method or other 1591 | application to decide what to do with that information. A particular DID 1592 | method could decide that authenticating as a DID controller is 1593 | sufficient to, for example, update or delete the DID document. Another 1594 | DID method could require different keys, or a different verification 1595 | method entirely, to be presented in order to update or delete the DID 1596 | document than that used to authenticate. In other words, what is done 1597 | after the authentication check is out of scope for the DID data 1598 | model, but DID methods and applications are expected to define this 1599 | themselves. 1600 |

1601 | 1602 |

1603 | A DID document MAY include an authentication property. 1604 |

1605 | 1606 |
1607 |
authentication
1608 |
1609 | The authentication property is a relationship between the 1610 | DID subject and a set of verification methods (such as, but not 1611 | limited to, public keys). It means that the DID subject has authorized 1612 | some set of verification methods (per the value of the 1613 | authentication property) for the purpose of authentication. The value 1614 | of the authentication property SHOULD be an array of 1615 | verification methods. Each verification method MAY be embedded 1616 | or referenced. An example of a verification method is a public key 1617 | (see Section ). 1618 |
1619 |
1620 | 1621 |

1622 | This statement is useful to any "authentication verifier" that needs to check 1623 | to see if an entity that is attempting to authenticate is, in fact, presenting 1624 | a valid proof of authentication. When a verifier receives some data (in some 1625 | protocol-specific format) that contains a proof that was made for the purpose 1626 | of "authentication", and that says that an entity is identified by the DID, 1627 | then that verifier checks to ensure that the proof can be verified using a 1628 | verification method (e.g., public key) listed under 1629 | authentication in the DID Document. 1630 |

1631 | 1632 |

1633 | The verification method indicated by the authentication 1634 | property of a DID document can only be used to authenticate the 1635 | DID subject. To authenticate the DID controller (in cases 1636 | where the DID controller is not also the DID subject) 1637 | the entity associated with the value of controller (see 1638 | Section ) needs to 1639 | authenticate itself with its own DID document and attached 1640 | authentication verification method relationship. 1641 |

1642 | 1643 |

1644 | Example: 1645 |

1646 | 1647 | 
1648 | {
1649 |   "@context": "https://www.w3.org/ns/did/v1",
1650 |   "id": "did:example:123456789abcdefghi",
1651 |   ...
1652 |   "authentication": [
1653 |     // this method can be used to authenticate as did:...fghi
1654 |     "did:example:123456789abcdefghi#keys-1",
1655 |     // this method can be used to authenticate as did:...fghi
1656 |     "did:example:123456789abcdefghi#biometric-1",
1657 |     // this method is *only* authorized for authentication, it may not
1658 |     // be used for any other proof purpose, so its full description is
1659 |     // embedded here rather than using only a reference
1660 |     {
1661 |       "id": "did:example:123456789abcdefghi#keys-2",
1662 |       "type": "Ed25519VerificationKey2018",
1663 |       "controller": "did:example:123456789abcdefghi",
1664 |       "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
1665 |     }
1666 |   ],
1667 |   ...
1668 | }
1669 |
1670 |
1671 | 1672 |
1673 |

1674 | Authorization and Delegation 1675 |

1676 | 1677 |

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

1683 | 1684 |

1685 | Note that Authorization is separate from . 1686 | This is particularly important for key recovery in the case of key loss, 1687 | when the subject no longer has access to their keys, or key compromise, 1688 | where the DID controller's trusted third parties need to override 1689 | malicious activity by an attacker. See Section . 1690 |

1691 | 1692 |

1693 | A DID document MAY include a controller property to indicate 1694 | that there are DID controller(s) other than the DID subject. 1695 | If so: 1696 |

1697 | 1698 |
1699 |
controller
1700 |
1701 | The value of the controller property MUST be a valid DID 1702 | or an array of valid DIDs. The corresponding DID document(s) 1703 | SHOULD contain authorization relations that explicitly permit the use of 1704 | certain verification methods for specific purposes. 1705 |
1706 |
1707 | 1708 |

1709 | Each DID method MUST define how authorization and delegation are 1710 | implemented, including any necessary cryptographic operations. 1711 |

1712 | 1713 |

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

1717 | 1718 |
    1719 |
  • 1720 | A DID registry could implement a coarse-grained controller 1721 | pattern by enabling DID documents to express the DID of another 1722 | DID controller that controls it, or 1723 | additionally, 1724 |
    • 1725 | 1726 |
  • 1727 | A DID registry could implement a capabilities-based approach enabling 1728 | further fine-grained control of authorization and delegation. 1729 |
    • 1730 |
1731 | 1732 | 
1733 | {
1734 |   "@context": "https://www.w3.org/ns/did/v1",
1735 |   "id": "did:example:123456789abcdefghi",
1736 |   "controller": "did:example:bcehfew7h32f32h7af3",
1737 |   "service": [{
1738 |     // used to retrieve Verifiable Credentials associated with the DID
1739 |     "type": "VerifiableCredentialService",
1740 |     "serviceEndpoint": "https://example.com/vc/"
1741 |   }]
1742 | }
1743 |
1744 |
1745 | 1746 |
1747 |

Service Endpoints

1748 | 1749 |

1750 | Service endpoints are used in DID documents to express ways of 1751 | communicating with the DID subject or associated entities. Services 1752 | listed in the DID document can contain information about privacy 1753 | preserving messaging services, or more public information, such as social media 1754 | accounts, personal websites, and email addresses although this is discouraged. 1755 | See for 1756 | additional details. The metadata associated with services are often 1757 | service-specific. For example, the metadata associated with an encrypted 1758 | messaging service can express how to initiate the encrypted link before 1759 | messaging begins. 1760 |

1761 |

1762 | Pointers to services are expressed using the service property. 1763 | Each service has its own id and type, as well as a 1764 | serviceEndpoint with a URI or other properties describing 1765 | the service. 1766 |

1767 | 1768 |

1769 | One of the primary purposes of a DID document is to enable discovery of 1770 | service endpoints. A service endpoint can be any type of service 1771 | the DID subject wants to advertise, including 1772 | decentralized identity management services for further discovery, 1773 | authentication, authorization, or interaction. 1774 |

1775 | 1776 |

1777 | A DID document MAY include a service property. 1778 |

1779 | 1780 |
1781 |
service
1782 |
1783 | If a DID document includes a service property, the value of 1784 | the property SHOULD be an array of service endpoint objects. Each 1785 | service endpoint MUST have id, type, and 1786 | serviceEndpoint properties, and MAY include additional properties. 1787 |
1788 |
1789 | 1790 |

1791 | The value of the id property MUST be a URI. 1792 | The array of service endpoints MUST NOT contain multiple entries 1793 | with the same id. In this case, a DID document processor 1794 | MUST produce an error. 1795 |

1796 | 1797 |

1798 | The value of the serviceEndpoint property MUST be a JSON-LD object 1799 | or a valid URI conforming to [[RFC3986]] and normalized according to the 1800 | rules in section 6 of [[RFC3986]] and to any normalization rules in its 1801 | applicable URI scheme specification. 1802 |

1803 | 1804 |

1805 | It is expected that the service endpoint protocol is published in an open 1806 | standard specification. 1807 |

1808 | 1809 | 
1810 | {
1811 |   "service": [{
1812 |     "id": "did:example:123456789abcdefghi#openid",
1813 |     "type": "OpenIdConnectVersion1.0Service",
1814 |     "serviceEndpoint": "https://openid.example.com/"
1815 |   }, {
1816 |     "id": "did:example:123456789abcdefghi#vcr",
1817 |     "type": "CredentialRepositoryService",
1818 |     "serviceEndpoint": "https://repository.example.com/service/8377464"
1819 |   }, {
1820 |     "id": "did:example:123456789abcdefghi#xdi",
1821 |     "type": "XdiService",
1822 |     "serviceEndpoint": "https://xdi.example.com/8377464"
1823 |   }, {
1824 |     "id": "did:example:123456789abcdefghi#agent",
1825 |     "type": "AgentService",
1826 |     "serviceEndpoint": "https://agent.example.com/8377464"
1827 |   }, {
1828 |     "id": "did:example:123456789abcdefghi#hub",
1829 |     "type": "IdentityHub",
1830 |     "publicKey": "did:example:123456789abcdefghi#key-1",
1831 |     "serviceEndpoint": {
1832 |       "@context": "https://schema.identity.foundation/hub",
1833 |       "type": "UserHubEndpoint",
1834 |       "instances": ["did:example:456", "did:example:789"]
1835 |     }
1836 |   }, {
1837 |     "id": "did:example:123456789abcdefghi#messages",
1838 |     "type": "MessagingService",
1839 |     "serviceEndpoint": "https://example.com/messages/8377464"
1840 |   }, {
1841 |     "id": "did:example:123456789abcdefghi#inbox",
1842 |     "type": "SocialWebInboxService",
1843 |     "serviceEndpoint": "https://social.example.com/83hfh37dj",
1844 |     "description": "My public social inbox",
1845 |     "spamCost": {
1846 |       "amount": "0.50",
1847 |       "currency": "USD"
1848 |     }
1849 |   }, {
1850 |     "id": "did:example:123456789abcdefghi#authpush",
1851 |     "type": "DidAuthPushModeVersion1",
1852 |     "serviceEndpoint": "http://auth.example.com/did:example:123456789abcdefg"
1853 |   }]
1854 | }
1855 |
1856 | 1857 |

1858 | For more information about security considerations regarding authentication 1859 | service endpoints see Sections 1860 | and . 1861 |

1862 |
1863 | 1864 |
1865 |

Created

1866 | 1867 |

1868 | A DID document SHOULD include a created property. 1869 |

1870 | 1871 |
1872 |
created
1873 |
1874 | If a DID document includes a created property, the value of 1875 | the property MUST be a valid XML datetime value, as defined in section 3.3.7 of 1876 | W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes 1877 | [[!XMLSCHEMA11-2]]. This datetime value MUST be normalized to UTC 00:00, as 1878 | indicated by the trailing "Z". 1879 |
1880 |
1881 | 1882 | 
1883 | {
1884 |   "created": "2002-10-10T17:00:00Z"
1885 | }
1886 |
1887 |
1888 | 1889 |
1890 |

Updated

1891 | 1892 |

1893 | Standard metadata for identifier records includes a timestamp of the most recent 1894 | change. 1895 |

1896 | 1897 |

1898 | A DID document SHOULD include an updated property. 1899 |

1900 | 1901 |
1902 |
updated
1903 |
1904 | If a DID document includes an updated property, the value of 1905 | the property MUST follow the same formatting rules as the created 1906 | property, as outlined in Section . 1907 |
1908 |
1909 | 1910 | 
1911 | {
1912 |   "updated": "2016-10-17T02:41:00Z"
1913 | }
1914 |
1915 |
1916 | 1917 |
1918 |

Proof

1919 | 1920 |

1921 | A proof on a DID document is cryptographic proof of the 1922 | integrity of the DID document according to either the: 1923 |

1924 | 1925 |
    1926 |
  • 1927 | DID subject, as defined in Section 1928 |
    • 1929 | 1930 |
  • 1931 | DID controller, as defined in Section 1932 | , if present. 1933 |
    • 1934 |
1935 | 1936 |

1937 | This proof is NOT proof of the binding between a DID and a 1938 | DID document. For more information, see Section 1939 | . 1940 |

1941 | 1942 |

1943 | A DID document MAY include a proof property. 1944 |

1945 | 1946 |
1947 |
proof
1948 |
1949 | If a DID document includes a proof property, the value of 1950 | the property MUST be a valid JSON-LD proof, as defined by Linked Data Proofs 1951 | [[?LD-PROOFS]]. 1952 |
1953 |
1954 | 1955 | 
1956 | {
1957 |   "proof": {
1958 |     "type": "LinkedDataSignature2015",
1959 |     "created": "2016-02-08T16:02:20Z",
1960 |     "creator": "did:example:8uQhQMGzWxR8vw5P3UWH1ja#keys-1",
1961 |     "signatureValue": "QNB13Y7Q9...1tzjn4w=="
1962 |   }
1963 | }
1964 |
1965 |
1966 | 1967 |
1968 | 1969 |
1970 |

Core Representations

1971 | 1972 |

1973 | All concrete representations of a DID document MUST be serialized using a 1974 | deterministic mapping that is able to be unambiguously parsed into the data model 1975 | defined in this specification. All serialization methods MUST define rules for 1976 | the bidirectional translation of a DID document both into and out of the 1977 | representation in question. As a consequence, translation between any two representations 1978 | MUST be done by parsing the source format into a DID document model 1979 | (described in Sections and ) 1980 | and then serializing the DID document model into the target representation. An 1981 | implementation MUST NOT convert between representations without first parsing to a 1982 | DID document model. 1983 |

1984 | 1985 |

1986 | Although syntactic mappings are provided for JSON, JSON-LD, and CBOR here, applications 1987 | and services MAY use any other data representation syntax that is capable of expressing 1988 | the data model, such as XML or YAML. 1989 |

1990 | 1991 |

1992 | Producers MUST indicate which representation of a document has been used via a media type 1993 | in the document's metadata. Consumers MUST determine which representation a document is in 1994 | via a media type in the document's metadata. Consumers MUST NOT determine the representation 1995 | of a document through its content alone. 1996 |

1997 | 1998 |

1999 | This requirement depends on the return of DID document metadata that still needs to be 2000 | defined by this specification. Once defined, that should be linked from here. 2001 |

2002 | 2003 |

2004 | The production and consumption rules in this section apply to all implementations 2005 | seeking to be fully compatible with independent implementations of the specification. 2006 | Deployments of this specification MAY use a custom agreed-upon representation, including 2007 | localized rules for handling properties not listed in the registry. 2008 | See section ?? on Extensibility for more information. 2009 |

2010 | 2011 |

2012 | A link to a section on extensibility and conformance as it applies to data representations 2013 | should be added here once that section has been written. 2014 |

2015 | 2016 |
2017 |

2018 | JSON 2019 |

2020 | 2021 |

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

2025 | 2026 |
2027 |

Production

2028 | 2029 |

2030 | A DID document MUST be a single JSON object conforming to [[!RFC8259]]. All 2031 | top-level properties of the DID document MUST be represented by using the 2032 | property name as the name of the member of the JSON object. The values of 2033 | properties of the data model described in Section , 2034 | including all extensions, MUST be encoded in JSON [[RFC8259]] by mapping property 2035 | values to JSON types as follows: 2036 |

2037 | 2038 |

2039 | In this section we use the term "property name" to refer to the string that represents 2040 | the property itself, but this specification still needs to define a concrete term for 2041 | such aspects of a property of a DID document. 2042 |

2043 | 2044 |
    2045 |
  • 2046 | Numeric values representable as IEEE754 MUST be represented as a Number type. 2047 |
    • 2048 |
  • 2049 | Boolean values MUST be represented as a Boolean literal. 2050 |
    • 2051 |
  • 2052 | Sequence value MUST be represented as an Array type. 2053 |
    • 2054 |
  • 2055 | Unordered sets of values MUST be represented as an Array type. 2056 |
    • 2057 |
  • 2058 | Sets of properties MUST be represented as an Object type. 2059 |
    • 2060 |
  • 2061 | Empty values MUST be represented as a null literal. 2062 |
    • 2063 |
  • 2064 | Other values MUST be represented as a String type. 2065 |
    • 2066 |
2067 | 2068 |

2069 | An "empty" value is not specified by this document. It seems to imply a null 2070 | value, but this is unclear. 2071 |

2072 | 2073 |

2074 | All properties of the DID document MUST be included in 2075 | the root object. Properties MAY define additional data sub structures subject 2076 | to the value representation rules in the list above. 2077 |

2078 | 2079 |

2080 | The member name @context MUST NOT be used as this property is reserved 2081 | for JSON-LD producers. 2082 |

2083 | 2084 |
2085 | 2086 |
2087 |

2088 | Consumption 2089 |

2090 | 2091 |

2092 | In this section and we use the term "property name" to refer to the string that represents 2093 | the property itself, but this specification still needs to define a concrete term for 2094 | such aspects of a property of a DID document. We also need a concrete term for "the document 2095 | itself" as opposed to "the collection or properties of the document". 2096 |

2097 | 2098 |

2099 | The top-level element MUST be a JSON object. Any other data type at the top 2100 | level is an error and MUST be rejected. The top-level JSON object represents 2101 | the DID document, and all members of this object are properties of the 2102 | DID document. The object member name is the property name, and the 2103 | member value is interpreted as follows: 2104 |

2105 | 2106 |
    2107 |
  • 2108 | Number types MUST interpreted as numeric values representable as IEEE754. 2109 |
    • 2110 |
  • 2111 | Boolean literals MUST be interpreted as a Boolean value. 2112 |
    • 2113 |
  • 2114 | An Array type MUST be interpreted as a Sequence or Unordered set, depending on the 2115 | definition of the property for this value. 2116 |
    • 2117 |
  • 2118 | An Object type MUST be interpreted as a sets of properties. 2119 |
    • 2120 |
  • 2121 | A null literal MUST be interpreted as an Empty value. 2122 |
    • 2123 |
  • 2124 | String types MUST be interpreted as Strings, which may be further parsed 2125 | depending on the definition of the property for this value into more specific data types such as URIs, 2126 | date stamps, or other values. 2127 |
    • 2128 |
2129 | 2130 |

2131 | An "empty" value is not specified by this document. It seems to imply a null 2132 | value, but this is unclear. 2133 |

2134 | 2135 |

2136 | The value of the @context object member MUST be ignored as this is 2137 | reserved for JSON-LD consumers. 2138 |

2139 | 2140 |

2141 | Unknown object member names MUST be ignored as unknown properties. 2142 |

2143 | 2144 |

2145 | This specification needs to define clear and consistent rules for how to handle unknown 2146 | data members on consumption, and this section needs to be updated with that decision. 2147 |

2148 | 2149 |
2150 | 2151 |
2152 | 2153 |
2154 |

2155 | JSON-LD 2156 |

2157 | 2158 |

2159 | [[!JSON-LD]] is a JSON-based format used to serialize 2160 | Linked Data. 2161 |

2162 | 2163 |

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

2167 | 2168 |
    2169 |
  • 2170 | The @id and @type keywords are aliased to 2171 | id and type respectively, enabling developers to use 2172 | this specification as idiomatic JSON. 2173 |
    • 2174 |
  • 2175 | Even though JSON-LD allows any IRI as node identifiers, DID documents 2176 | are explicitly restricted to only describe DIDs. This means that the value of 2177 | id MUST be a valid DID and not any other kind of IRI. 2178 |
    • 2179 |
  • 2180 | Data types, such as integers, dates, units of measure, and URLs, are 2181 | automatically typed to provide stronger type guarantees for use cases that 2182 | require them. 2183 |
    • 2184 |
2185 | 2186 |
2187 |

2188 | Production 2189 |

2190 | 2191 |

2192 | The DID document is serialized following the rules in the JSON processor, with 2193 | one addition: DID documents MUST include the @context property. 2194 |

2195 | 2196 |
2197 |
@context
2198 |
2199 | The value of the @context property MUST be one or more URIs, 2200 | where the value of the first URI is 2201 | https://www.w3.org/ns/did/v1. All members of the @context 2202 | property MUST exist be in the DID properties extension registry. 2203 |
2204 |
2205 | 2206 |

2207 | This specification defines globally interoperable documents, and the requirement that the 2208 | context value be in the DID registry means that different JSON-LD processors can consume 2209 | the document without having to dereference anything in the context field. However, 2210 | a pair of producers and consumers can have local extension agreements. This needs to be 2211 | clarified in a section on extensibility and linked here when available. 2212 |

2213 | 2214 |
2215 | 2216 |
2217 |

2218 | Consumption 2219 |

2220 | 2221 |

2222 | The top-level element MUST be a JSON object. Any other data type at the top 2223 | level is an error and MUST be rejected. This top-level JSON object is interpreted 2224 | using JSON-LD processing under the rules of the defined @context fields. 2225 |

2226 | 2227 |
2228 |
@context
2229 |
2230 | The value of the @context property MUST be one or more URIs, 2231 | where the value of the first URI is 2232 | https://www.w3.org/ns/did/v1. If more than one URI is 2233 | provided, the URIs MUST be interpreted as an ordered set. It is 2234 | RECOMMENDED that dereferencing each URI results in a document containing 2235 | machine-readable information about the context. 2236 |
2237 |
2238 | 2239 | 2240 |

2241 | Unknown object member names MUST be ignored as unknown properties. 2242 |

2243 | 2244 |

2245 | This specification needs to define clear and consistent rules for how to handle unknown 2246 | data members on consumption, and this section needs to be updated with that decision. 2247 |

2248 | 2249 |
2250 | 2251 |
2252 | 2253 |
2254 |

2255 | CBOR 2256 |

2257 | 2258 |
2259 |

2260 | Production 2261 |

2262 |
2263 | 2264 |
2265 |

2266 | Consumption 2267 |

2268 |
2269 | 2270 |
2271 |
2272 | 2273 |
2274 |

Methods

2275 | 2276 |
2277 |

Method Schemes

2278 | 2279 |

2280 | A DID method specification MUST define exactly one method-specific 2281 | DID scheme, identified by exactly one method name. For more information, 2282 | see the method-name rule in Section 2283 | . 2284 |

2285 | 2286 |

2287 | Because the method name is part of the DID, short method names are 2288 | preferred; the method name SHOULD be five characters or less. The method name 2289 | might reflect the name of the DID registry to which the DID method 2290 | specification applies. For more information, see Section 2291 | . 2292 |

2293 | 2294 |

2295 | The DID method specification for the method-specific DID scheme 2296 | MUST specify how to generate the method-specific-id component of a 2297 | DID. The method-specific-id value MUST be able to be 2298 | generated without the use of a centralized registry service. The 2299 | method-specific-id value SHOULD be globally unique by itself. The 2300 | DID, as defined by the did rule in Section 2301 | , MUST be globally unique. 2302 |

2303 | 2304 |

2305 | If needed, a method-specific DID scheme MAY define multiple 2306 | method-specific-id formats. It is RECOMMENDED that a 2307 | method-specific DID scheme define as few method-specific-id 2308 | formats as possible. 2309 |

2310 | 2311 |

2312 | The method-specific-id format MAY include colons, which might be 2313 | used by DID methods for various purposes, such as establishing 2314 | hierarchically partitioned namespaces, or identifying specific instances or 2315 | parts of the DID registry. The use of colons MUST comply syntactically 2316 | with the method-specific-id ABNF rule and their use is entirely 2317 | method-specific. Implementers are advised to avoid 2318 | assuming any meanings or behaviors associated with a colon that are 2319 | generically applicable to all DID methods. 2320 |

2321 | 2322 |

2323 | The authors of a new DID method specification SHOULD use a method name 2324 | that is unique among all DID method names known to them at the time of 2325 | publication. 2326 |

2327 |

2328 | Because there is no central authority for allocating or approving 2329 | DID method names, there is no way to know for certain if a specific 2330 | DID method name is unique. To help with this challenge, the 2331 | W3C Credentials Community Group 2332 | maintains a non-authoritative list of known DID method names and their 2333 | associated specifications. For more information, see Appendix 2334 | . 2335 |

2336 |

2337 | The [[?DID-METHOD-REGISTRY]] is a tool for implementors to use when coming to 2338 | consensus on a new method name, as well as an informative reference for software 2339 | developers implementing DID resolvers for different DID methods. 2340 | For more information about DID resolvers see Section 2341 | . The [[?DID-METHOD-REGISTRY]] is not a definitive 2342 | or official list of DID methods. Nonetheless, adding DID method 2343 | names to the [[?DID-METHOD-REGISTRY]] is encouraged so that other implementors 2344 | and members of the community have a place to see an overview of existing 2345 | DID methods. The lightweight criteria for inclusion are documented in the 2346 | [[?DID-METHOD-REGISTRY]]. 2347 |

2348 |
2349 | 2350 |
2351 |

Method Operations

2352 | 2353 |

2354 | To enable the full functionality of DIDs and DID documents on a 2355 | particular DID registry, a DID method specification MUST specify 2356 | how a client might be used to perform the create, read, update, and deactivate 2357 | operations. Each operation ought to be specified to the level of detail 2358 | necessary to build and test interoperable client implementations. In the event 2359 | that an operation is not supported, such as update or deactivate, then it is 2360 | RECOMMENDED that the DID Method specification state that it is not 2361 | supported. These operations can be used to perform all the operations required 2362 | of a cryptographic key management system (CKMS), e.g.: key registration, key 2363 | replacement, key rotation, key recovery, and key expiration. 2364 |

2365 | 2366 |

2367 | Determining the authority of a party to carry out the operations is method-specific. 2368 | For example, a DID method MAY: 2369 |

2370 |
    2371 |
  • 2372 | use the verification methods listed under authentication to 2373 | decide whether an update/deactivate operation is allowed; or 2374 |
    • 2375 |
  • 2376 | use other constructs in the DID Document to decide this, for example, 2377 | a verification method specified under capabilityInvocation could be used to 2378 | verify the invocation of a capability to update the DID Document.; or 2379 |
    • 2380 |
  • 2381 | not use the DID Document at all to decide this, but have rules that are 2382 | "built into" the method. 2383 |
    • 2384 |
2385 | 2386 |
2387 |

2388 | Create 2389 |

2390 | 2391 |

2392 | The DID method specification MUST specify how a client creates a 2393 | DID and its associated DID document on the DID registry, 2394 | including all cryptographic operations necessary to establish proof of control. 2395 |

2396 |
2397 | 2398 |
2399 |

2400 | Read/Verify 2401 |

2402 | 2403 |

2404 | The DID method specification MUST specify how a client uses a DID 2405 | to request a DID document from the DID registry, including how the 2406 | client can verify the authenticity of the response. 2407 |

2408 |
2409 | 2410 |
2411 |

2412 | Update 2413 |

2414 | 2415 |

2416 | The DID method specification MUST specify how a client can update a 2417 | DID document on the DID registry, including all cryptographic 2418 | operations necessary to establish proof of control, or state that 2419 | updates are not possible. 2420 |

2421 | 2422 |

2423 | An update to a DID is any change, after creation, in the data used to produce a DID document. 2424 | DID Method implementers are responsible for defining what constitutes an update, 2425 | and what properties of the DID document are supported by a given DID method. 2426 | 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. 2427 |

2428 |
2429 | 2430 |
2431 |

2432 | Deactivate 2433 |

2434 | 2435 |

2436 | The DID method specification MUST specify how a client can deactivate a 2437 | DID on the DID registry, including all cryptographic operations 2438 | necessary to establish proof of deactivation, or state that 2439 | deactivation is not possible. 2440 |

2441 |
2442 |
2443 | 2444 |
2445 |

Extensibility

2446 |
2447 | 2448 |
2449 |

2450 | Security Requirements 2451 |

2452 |

2453 | DID method specifications MUST include their own Security 2454 | Considerations sections. This section MUST consider all the requirements 2455 | mentioned in section 5 of [[RFC3552]] (page 27) for the DID operations 2456 | defined in the specification. 2457 |

2458 |

2459 | At least the following forms of attack MUST be considered: eavesdropping, 2460 | replay, message insertion, deletion, modification, and man-in-the-middle. 2461 | Potential denial of service attacks MUST be identified as well. 2462 |

2463 |

2464 | If the protocol incorporates cryptographic protection mechanisms, the 2465 | DID method specification MUST clearly indicate which portions of the 2466 | data are protected and what the protections are, and SHOULD give an indication 2467 | to what sorts of attacks the cryptographic protection is susceptible. 2468 | For example, integrity only, confidentiality, endpoint authentication, and so 2469 | on. 2470 |

2471 | Data which is to be held secret (keying material, random seeds, and so on) SHOULD 2472 | be clearly labeled. 2473 |

2474 |

2475 | If the technology involves authentication, particularly user-host 2476 | authentication, the security of the authentication method MUST be clearly 2477 | specified. 2478 |

2479 |

2480 | This section MUST discuss, per Section 5 of [[RFC3552]], residual risks (such as 2481 | the risks from compromise in a related protocol, incorrect implementation, or 2482 | cipher) after threat mitigation was deployed. 2483 |

2484 |

2485 | This section MUST provide integrity protection and update authentication for all 2486 | operations required by Section . 2487 |

2488 |

2489 | Where DID methods make use of peer-to-peer computing resources, such as 2490 | with all known DLTs, the expected burdens of those resources SHOULD be 2491 | discussed in relation to denial of service. 2492 |

2493 |

2494 | Method-specific endpoint authentication MUST be discussed. Where 2495 | DID methods make use of DLTs with varying network topology, 2496 | sometimes offered as light node or 2497 | thin client 2498 | implementations to reduce required computing resources, the security assumptions 2499 | of the topology available to implementations of the DID method MUST be 2500 | discussed. 2501 |

2502 |

2503 | DID methods MUST discuss the policy mechanism by which DIDs are 2504 | proven to be uniquely assigned. A DID fits the functional definition 2505 | of a URN, as defined in [[RFC8141]]. That is, a DID is a persistent 2506 | identifier that is assigned once to a resource and never reassigned to a 2507 | different resource. This is particularly important in a security context because 2508 | a DID might be used to identify a specific party subject to a specific 2509 | set of authorization rights. 2510 |

2511 |

2512 | DID methods that introduce new authentication service endpoint 2513 | types (see Section ) SHOULD consider the 2514 | security requirements of the supported authentication protocol. 2515 |

2516 | 2517 |
2518 | 2519 |
2520 |

2521 | Privacy Requirements 2522 |

2523 | 2524 |

2525 | DID method specifications MUST include their own Privacy 2526 | Considerations sections, if only to point to 2527 | . 2528 |

2529 | 2530 |

2531 | The DID method specification's Privacy Considerations section 2532 | MUST discuss any subsection of section 5 of [[RFC6973]] that could 2533 | apply in a method-specific manner. The subsections to consider are: 2534 | surveillance, stored data compromise, unsolicited traffic, misattribution, 2535 | correlation, identification, secondary use, disclosure, exclusion. 2536 |

2537 |
2538 |
2539 | 2540 | 2541 |
2542 |

2543 | Resolution 2544 |

2545 | 2546 |

2547 | A DID resolver is a software or hardware component with an API for 2548 | resolving DIDs of at least one DID method. It executes the read 2549 | operation for the DID method corresponding to the DID being 2550 | resolved to obtain the authoritative DID document. For more information, 2551 | see Section . 2552 |

2553 | 2554 |

2555 | The interfaces and algorithms for resolving DIDs and dereferencing 2556 | DID URLs are specified in [[?DID-RESOLUTION]]. 2557 |

2558 | 2559 |
2560 | 2561 |
2562 |

2563 | Security Considerations 2564 |

2565 | 2566 |

2567 | During the Working Draft stage, this section focuses on security topics that 2568 | should be important in early implementations. The editors are seeking feedback 2569 | on threats and threat mitigations that should be reflected in this section or 2570 | elsewhere in the spec. DIDs are designed to operate under the general 2571 | Internet threat model used by many IETF standards. We assume uncompromised 2572 | endpoints, but anticipate that messages could be read or corrupted on the network. 2573 | Protecting against an attack when a system is compromised requires external 2574 | key-signing hardware (see Section ). 2575 |

2576 | 2577 |
2578 |

2579 | Choosing DID Resolvers 2580 |

2581 | 2582 |

2583 | The [[?DID-METHOD-REGISTRY]] is an informative list of DID method names 2584 | and their corresponding DID method specifications. Implementors need to 2585 | bear in mind that there is no central authority to mandate which 2586 | DID method specification is to be used with any specific 2587 | DID method name, but can use the [[?DID-METHOD-REGISTRY]] to make an 2588 | informed decision when choosing which DID resolver implementations to 2589 | use. 2590 |

2591 |
2592 | 2593 |
2594 |

2595 | Binding of Identity 2596 |

2597 | 2598 |

2599 | The following sections describe binding identities to DIDs and 2600 | DID documents. 2601 |

2602 | 2603 |
2604 |

2605 | Proving Control of a DID and DID Document 2606 |

2607 | 2608 |

2609 | Signatures are one way to allow DID documents to be cryptographically 2610 | verifiable. 2611 |

2612 | 2613 |

2614 | By itself, a verified signature on a self-signed DID document does not 2615 | prove control of a DID. It only proves that the: 2616 |

2617 | 2618 |
    2619 |
  • 2620 | DID document was not tampered with since it was registered. 2621 |
    • 2622 | 2623 |
  • 2624 | DID controller(s) controlled the private key used for the signature at 2625 | the time the signature was generated. 2626 |
    • 2627 |
2628 | 2629 |

2630 | Proving control of a DID, that is, the binding between the DID and 2631 | the DID document that describes it, requires a two step process: 2632 |

2633 | 2634 |
    2635 |
  1. 2636 | Resolving the DID to a DID document according to its 2637 | DID method specification. 2638 |
    2. 2639 | 2640 |
  2. 2641 | Verifying that the id property of the resulting DID document 2642 | matches the DID that was resolved. 2643 |
    3. 2644 |
2645 | 2646 |

2647 | It should be noted that this process proves control of a DID and 2648 | DID document regardless of whether the DID document is signed. 2649 |

2650 | 2651 |

2652 | Signatures on DID documents are optional. DID method 2653 | specifications SHOULD explain and specify their implementation if applicable. 2654 |

2655 | 2656 |

2657 | It is good practice to combine timestamps with signatures. 2658 |

2659 |
2660 | 2661 |
2662 |

2663 | Proving Control of a Public Key 2664 |

2665 | 2666 |

2667 | There are two methods for proving control of the private key corresponding to a 2668 | public key description in the DID document: static and dynamic. 2669 |

2670 | 2671 |

2672 | The static method is to sign the DID document with the private key. This 2673 | proves control of the private key at a time no later than the 2674 | DID document was registered. If the DID document is not signed, 2675 | control of a public key described in the DID document can still be proven 2676 | dynamically as follows: 2677 |

2678 | 2679 |
    2680 |
  1. 2681 | Send a challenge message containing a public key description from the 2682 | DID document and a nonce to an appropriate service endpoint 2683 | described in the DID document. 2684 |
    2. 2685 | 2686 |
  2. 2687 | Verify the signature of the response message against the 2688 | public key description. 2689 |
    3. 2690 |
2691 |
2692 | 2693 |
2694 |

2695 | Authentication and Verifiable Claims 2696 |

2697 | 2698 |

2699 | A DID and DID document do not inherently carry any 2700 | PII 2701 | (personally-identifiable information). The process of binding a DID to 2702 | something in the real world, such as a person or a company, for example with 2703 | credentials with the same subject as that DID, is out of scope for this 2704 | specification. For more information, see the [[VC-DATA-MODEL]] instead. 2705 |

2706 |
2707 |
2708 | 2709 |
2710 |

2711 | Authentication Service Endpoints 2712 |

2713 | 2714 |

2715 | If a DID document publishes a service endpoint intended for 2716 | authentication or authorization of the DID subject (see Section 2717 | ), it is the responsibility of the 2718 | service endpoint provider, subject, or relying party to comply with the 2719 | requirements of the authentication protocols supported at that 2720 | service endpoint. 2721 |

2722 |
2723 | 2724 |
2725 |

2726 | Non-Repudiation 2727 |

2728 | 2729 |

2730 | Non-repudiation of DIDs and DID document updates is supported 2731 | under the assumption that the subject: 2732 |

2733 | 2734 |
    2735 |
  • 2736 | Is monitoring for unauthorized updates (see Section 2737 | ). 2738 |
    • 2739 |
  • 2740 | Has had adequate opportunity to revert malicious updates according to the 2741 | access control mechanism for the DID method (see Section 2742 | ). 2743 |
    • 2744 |
2745 | 2746 |

2747 | Non-repudiation is further supported if timestamps are included (see Sections 2748 | and ) and the target DLT 2749 | system supports timestamps. 2750 |

2751 |
2752 | 2753 |
2754 |

2755 | Notification of DID Document Changes 2756 |

2757 | 2758 |

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

2765 |

2766 | In the case of a DID, there is no intermediary registrar or account 2767 | provider to generate such notifications. However, if the DID registry 2768 | on which the DID is registered directly supports change notifications, 2769 | a subscription service can be offered to DID controllers. Notifications 2770 | could be sent directly to the relevant service endpoints listed in an 2771 | existing DID. 2772 |

2773 |

2774 | If a DID controller chooses to rely on a third-party monitoring service 2775 | (other than the DID registry itself), this introduces another vector of 2776 | attack. 2777 |

2778 |
2779 | 2780 |
2781 |

2782 | Key and Signature Expiration 2783 |

2784 | 2785 |

2786 | In a decentralized identifier architecture, there are no centralized 2787 | authorities to enforce key or signature expiration policies. Therefore 2788 | DID resolvers and other client applications need to validate that keys 2789 | were not expired at the time they were used. Because some use cases might have 2790 | legitimate reasons why already-expired keys can be extended, make sure a key 2791 | expiration does not prevent any further use of the key, and implementations 2792 | of a resolver ought to be compatible with such extension behavior. 2793 |

2794 |
2795 | 2796 |
2797 |

2798 | Key Revocation and Recovery 2799 |

2800 | 2801 |

2802 | Section specifies the DID operations to 2803 | be supported by a DID method specification, including deactivation of a 2804 | DID document by replacing it with an updated DID document. It is 2805 | also up to the DID method to define how revocation of cryptographic keys 2806 | might occur. Additionally, DID method specifications are also expected 2807 | to enable support for a quorum of trusted parties to enable key recovery. Some 2808 | of the facilities to do so are suggested in Section 2809 | . Not all DID method 2810 | specifications will recognize control from DIDs registered using other 2811 | DID methods and they might restrict third-party control to DIDs 2812 | that use the same method. Access control and key recovery in a DID method 2813 | specification can also include a time lock feature to protect against key 2814 | compromise by maintaining a second track of control for recovery. Further 2815 | specification of this type of control is a matter for future work (see Section 2816 | ). 2817 |

2818 |
2819 | 2820 |
2821 |

2822 | The Role of Human-Friendly Identifiers 2823 |

2824 | 2825 |

2826 | DIDs achieve global uniqueness without the need for a central 2827 | registration authority. This comes, however, at the cost of human memorability. 2828 | The algorithms capable of generating globally unique identifiers automatically 2829 | produce random strings of characters that have no human meaning. This 2830 | demonstrates the axiom about identifiers described in 2831 | Zooko's Triangle: 2832 | "human-meaningful, decentralized, secure — pick any two". 2833 |

2834 | 2835 |

2836 | There are of course many use cases where it is desirable to 2837 | discover a DID when starting from a human-friendly identifier. For 2838 | example, a natural language name, a domain name, or a conventional address for 2839 | a DID controller, such as a mobile telephone number, email address, 2840 | Twitter handle, or blog URL. However, the problem of mapping human-friendly 2841 | identifiers to DIDs (and doing so in a way that can be verified and 2842 | trusted) is outside the scope of this specification. 2843 |

2844 | 2845 |

2846 | Solutions to this problem (and there are many) should be defined in separate 2847 | specifications that reference this specification. It is strongly recommended 2848 | that such specifications carefully consider the: 2849 |

2850 | 2851 |
    2852 |
  • 2853 | Numerous security attacks based on deceiving users about the true human-friendly 2854 | identifier for a target entity. 2855 |
    • 2856 |
  • 2857 | Privacy consequences of using human-friendly identifiers that are inherently 2858 | correlatable, especially if they are globally unique. 2859 |
    • 2860 |
2861 | 2862 |

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

2866 |
2867 | 2868 |
2869 |

2870 | Immutability 2871 |

2872 | 2873 |

2874 | Many cybersecurity abuses hinge on exploiting gaps between reality and the 2875 | assumptions of rational, good-faith actors. Like any ecosystem, the DID 2876 | ecosystem has some potential for this to occur. Because this specification is 2877 | focused on a data model instead of a protocol, it offers no opinion about many 2878 | aspects of how that model is put to use. However, individual DID methods 2879 | might want to consider constraints that would eliminate behaviors or semantics 2880 | they do not need. The more locked down a DID method is, while 2881 | providing the same set of features, the less it can be manipulated by malicious 2882 | actors. 2883 |

2884 |

2885 | As an example, consider the flexibility that the data model offers with respect 2886 | to updating. A single edit to a DID document can change anything and 2887 | everything except the root id property of the document. And any 2888 | individual JSON object in the data model can change all of its properties except 2889 | its id. But is it actually desirable for a service endpoint 2890 | to change its type after it is defined? Or for a key to change its 2891 | value? Or would it be better to require a new id when certain 2892 | fundamental properties of an object change? Malicious takeovers of a web site 2893 | often aim for an outcome where the site keeps its identifier (the host name), 2894 | but gets subtle, dangerous changes underneath. If certain properties of the site 2895 | were required by the specification to be immutable (for example, the 2896 | ASN 2897 | associated with its IP address), such attacks might be much harder and more 2898 | expensive to carry out, and anomaly detection would be easier. 2899 |

2900 |

2901 | The notion that immutability provides some cybersecurity benefits is 2902 | particularly relevant because of caching. For DID methods tied to a 2903 | global source of truth, a direct, just-in-time lookup of the latest version of a 2904 | DID document is always possible. However, it seems likely that layers of 2905 | cache might eventually sit between a client and that source of truth. If they 2906 | do, believing the attributes of an object in the DID document to have a 2907 | given state, when they are actually subtly different, might invite exploits. 2908 | This is particularly true if some lookups are of a full DID document, and 2909 | others are of partial data, where the larger context is assumed. 2910 |

2911 |
2912 | 2913 |
2914 |

2915 | Encrypted Data in DID Documents 2916 |

2917 |

2918 | DID documents are typically publicly available. Encryption algorithms have been 2919 | known to fail due to advances in cryptography and computing power. 2920 | Implementers are advised to assume that any 2921 | encrypted data placed in a DID document might eventually be made available in clear 2922 | text to the same audience to which the encrypted data is available. 2923 |

2924 |

2925 | Encrypting all or parts of DID documents is not an appropriate means to protect data 2926 | in the long term. Similarly, placing encrypted data in DID documents is not an appropriate 2927 | means to include personally identifiable information. 2928 |

2929 |

2930 | Given the caveats above, if encrypted data is included in a DID document, implementers are advised to not 2931 | encrypt with the public keys of entities that do not wish to be correlated with the 2932 | DID. 2933 |

2934 | 2935 |
2936 | 2937 |
2938 | 2939 |
2940 |

2941 | Privacy Considerations 2942 |

2943 | 2944 |

2945 | It is critically important to apply the principles of Privacy by Design 2946 | to all aspects of the decentralized identifier architecture, because 2947 | DIDs and DID documents are, by design, administered directly by 2948 | the DID controller(s). There is no registrar, hosting company, or other 2949 | intermediate service provider to recommend or apply additional privacy 2950 | safeguards. The authors of this specification have applied all seven Privacy by 2951 | Design principles throughout its development. For example, privacy in this 2952 | specification is preventative not remedial, and privacy is an embedded default. 2953 | Furthermore, the decentralized identifier architecture by itself embodies 2954 | principle #7, "Respect for user privacy — keep it user-centric." 2955 |

2956 | 2957 |

2958 | This section lists additional privacy considerations that implementers, 2959 | delegates, and DID subjects should keep in mind. 2960 |

2961 | 2962 |
2963 |

2964 | Keep Personally-Identifiable Information (PII) Private 2965 |

2966 | 2967 |

2968 | If a DID method specification is written for a public DID 2969 | registry where all DIDs and DID documents are publicly 2970 | available, it is critical that DID documents contain no 2971 | personal data. All personal data should be kept behind service 2972 | endpoints under the control of the DID subject. Additional due 2973 | diligence should be taken around the use of URLs in service endpoints as well 2974 | to prevent leakage of unintentional personal data or correlation within a URL 2975 | of a service endpoint. For example, a URL that contains a username is likely 2976 | dangerous to include in a DID Document because the username is likely 2977 | to be human-meaningful in a way that can unintentionally reveal information 2978 | that the DID subject did not consent to sharing. With this privacy 2979 | architecture, personal data can be exchanged on a private, peer-to-peer basis 2980 | using communications channels identified and secured by public key 2981 | descriptions in DID documents. This also enables DID 2982 | subjects and relying parties to implement the GDPR right to be 2985 | forgotten, because no personal data is written to an immutable 2986 | distributed ledger. 2987 |

2988 |
2989 | 2990 |
2991 |

2992 | DID Correlation Risks and Pseudonymous DIDs 2993 |

2994 | 2995 |

2996 | Like any type of globally unique identifier, DIDs might be used for 2997 | correlation. DID controllers can mitigate this privacy risk by using 2998 | pairwise unique DIDs, that is, sharing a different private DID for 2999 | every relationship. In effect, each DID acts as a pseudonym. A 3000 | pseudonymous DID need only be shared with more than one party when 3001 | the DID subject explicitly authorizes correlation between those parties. 3002 | If pseudonymous DIDs are the default, then the only need for a public 3003 | DID (a DID published openly or shared with a large number of 3004 | parties) is when the DID subject explicitly desires public 3005 | identification. 3006 |

3007 |
3008 | 3009 |
3010 |

3011 | DID Document Correlation Risks 3012 |

3013 | 3014 |

3015 | The anti-correlation protections of pseudonymous DIDs are easily defeated 3016 | if the data in the corresponding DID documents can be correlated. For 3017 | example, using same public key descriptions or bespoke 3018 | service endpoints in multiple DID documents can provide as much 3019 | correlation information as using the same DID. Therefore the 3020 | DID document for a pseudonymous DID also needs to use pairwise 3021 | unique public keys. 3022 | 3023 | It might seem natural to also use pairwise unique service endpoints in 3024 | the DID document for a pseudonymous DID. However, unique endpoints 3025 | allow all traffic between two DIDs to be isolated perfectly into unique 3026 | buckets, where timing correlation and similar analysis is easy. Therefore, a 3027 | better strategy for endpoint privacy might be to share an endpoint among 3028 | thousands or millions of DIDs controlled by many different subjects. 3029 |

3030 |
3031 | 3032 |
3033 |

3034 | Herd Privacy 3035 |

3036 | 3037 |

3038 | When a DID subject is indistinguishable from others in the herd, privacy 3039 | is available. When the act of engaging privately with another party 3040 | is by itself a recognizable flag, privacy is greatly diminished. DIDs 3041 | and DID methods need to work to improve herd privacy, particularly for 3042 | those who legitimately need it most. Choose technologies and human interfaces 3043 | that default to preserving anonymity and pseudonymity. To reduce 3044 | digital fingerprints, 3045 | share common settings across client implementations, keep negotiated options to 3046 | a minimum on wire protocols, use encrypted transport layers, and pad messages to 3047 | standard lengths. 3048 |

3049 |
3050 |
3051 | 3052 |
3053 |

3054 | Interoperability Registries 3055 |

3056 | 3057 |

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

3061 | 3062 | 3063 | 3064 | 3065 | 3068 | 3071 | 3072 | 3073 | 3074 | 3075 | 3076 | 3080 | 3084 | 3085 | 3086 | 3087 | 3091 | 3095 | 3096 | 3097 |
3066 | Registry 3067 | 3069 | Purpose 3070 |
3077 | DID 3078 | Method Registry 3079 | 3081 | Lists all known DID methods and contains links to their 3082 | specifications. 3083 |
3088 | Linked Data 3089 | Cryptography Suite Registry 3090 | 3092 | Defines all known Linked Data Cryptography Suites and Key 3093 | Formats. 3094 |
3098 |
3099 | 3100 |
3101 |

3102 | Real World Example 3103 |

3104 | 3105 |

3106 | A future-facing real-world context is provided below: 3107 |

3108 | 3109 | 
3110 | {
3111 |   "@context": "https://w3id.org/future-method/v1",
3112 |   "id": "did:example:123456789abcdefghi",
3113 | 
3114 |   "publicKey": [{
3115 |     "id": "did:example:123456789abcdefghi#keys-1",
3116 |     "type": "RsaVerificationKey2018",
3117 |     "controller": "did:example:123456789abcdefghi",
3118 |     "publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n"
3119 |   }, {
3120 |     "id": "did:example:123456789abcdefghi#keys-3",
3121 |     "type": "Ieee2410VerificationKey2018",
3122 |     "controller": "did:example:123456789abcdefghi",
3123 |     "publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n"
3124 |   }],
3125 | 
3126 |   "authentication": [
3127 |     // this mechanism can be used to authenticate as did:...fghi
3128 |     "did:example:123456789abcdefghi#keys-1",
3129 |     // this mechanism can be used to biometrically authenticate as did:...fghi
3130 |     "did:example:123456789abcdefghi#keys-3",
3131 |     // this mechanism is *only* authorized for authentication, it may not
3132 |     // be used for any other proof purpose, so its full description is
3133 |     // embedded here rather than using only a reference
3134 |     {
3135 |       "id": "did:example:123456789abcdefghi#keys-2",
3136 |       "type": "Ed25519VerificationKey2018",
3137 |       "controller": "did:example:123456789abcdefghi",
3138 |       "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
3139 |     }
3140 |   ],
3141 | 
3142 |   "service": [{
3143 |     "id": "did:example:123456789abcdefghi#oidc",
3144 |     "type": "OpenIdConnectVersion1.0Service",
3145 |     "serviceEndpoint": "https://openid.example.com/"
3146 |   }, {
3147 |     "id": "did:example:123456789abcdefghi#vcStore",
3148 |     "type": "CredentialRepositoryService",
3149 |     "serviceEndpoint": "https://repository.example.com/service/8377464"
3150 |   }, {
3151 |     "id": "did:example:123456789abcdefghi#xdi",
3152 |     "type": "XdiService",
3153 |     "serviceEndpoint": "https://xdi.example.com/8377464"
3154 |   }, {
3155 |     "id": "did:example:123456789abcdefghi#hub",
3156 |     "type": "HubService",
3157 |     "serviceEndpoint": "https://hub.example.com/.identity/did:example:0123456789abcdef/"
3158 |   }, {
3159 |     "id": "did:example:123456789abcdefghi#messaging",
3160 |     "type": "MessagingService",
3161 |     "serviceEndpoint": "https://example.com/messages/8377464"
3162 |   }, {
3163 |     "type": "SocialWebInboxService",
3164 |     "id": "did:example:123456789abcdefghi#inbox",
3165 |     "serviceEndpoint": "https://social.example.com/83hfh37dj",
3166 |     "description": "My public social inbox",
3167 |     "spamCost": {
3168 |       "amount": "0.50",
3169 |       "currency": "USD"
3170 |     }
3171 |   }, {
3172 |     "type": "DidAuthPushModeVersion1",
3173 |     "id": "did:example:123456789abcdefghi#push",
3174 |     "serviceEndpoint": "http://auth.example.com/did:example:123456789abcdefghi"
3175 |   }, {
3176 |     "id": "did:example:123456789abcdefghi#bops",
3177 |     "type": "BopsService",
3178 |     "serviceEndpoint": "https://bops.example.com/enterprise/"
3179 |   }]
3180 | }
3181 |
3182 |
3183 | 3184 |
3185 |

Current Issues

3186 | 3187 |

3188 | The list of issues below are under active discussion and are likely to 3189 | result in changes to this specification. 3190 |

3191 | 3192 |
Syntactically differentiate data about the DID versus application data
3193 |
Add `initial-values` matrix parameter to Generic DID Parameters
3194 |
tracking revocation of public keys
3195 |
Privacy Considerations - Specifically call out GDPR
3196 |
Enable instant DID use/resolution for DID Methods that include a propagation delay
3197 |
Does DID Document metadata belong in the Document?
3198 |
Add publicKeyHex as a valid publicKey format
3199 |
Add "service-type" DID URL matrix parameter.
3200 |
Add "content-type" and "content-id" DID URL matrix parameters.
3201 |
Add "key-type" DID URL matrix parameter.
3202 |
Add "key" DID URL matrix parameter.
3203 |
Registry handling
3204 |
Clarification of other verification methods in authentication section missing
3205 |
Added support for ethereumAddress in context - fixed #55
3206 |
Add support for ethereumAddress public key type in @context
3207 |
Normative vs. non-normative references
3208 |
Is method-specific-id supposed to be equivalent to param-char?
3209 |
3210 | 3211 |
3212 |

3213 | Future Work 3214 |

3215 | 3216 |
3217 |

3218 | Upper Limits on DID Character Length 3219 |

3220 | 3221 |

3222 | The current specification does not take a position on maximum length 3223 | of a DID. The maximum interoperable URL length is currently about 2K 3224 | characters. QR codes can handle about 4K characters. Clients using 3225 | DIDs will be responsible for storing many DIDs, and some methods 3226 | would be able to externalize some of their costs onto clients by 3227 | relying on more complicated signature schemes or by adding state into 3228 | DIDs intended for temporary use. A future version of this 3229 | specification should set reasonable limits on DID character length to 3230 | minimize externalities. 3231 |

3232 |
3233 | 3234 |
3235 |

3236 | Equivalence 3237 |

3238 | 3239 |

3240 | Including an equivalence property, such as equivID, in DID documents 3241 | whose value is an array of DIDs would allow subjects to assert two or 3242 | more DIDs that represent the same subject. This capability has 3243 | numerous uses, including supporting migration between DID registries and 3244 | providing forward compatibility of existing DIDs to future DID 3245 | registries. In 3246 | theory, equivalent DIDs should have the same identifier rights, 3247 | allowing verifiable claims 3248 | made against one DID to apply to equivalent DIDs. Equivalence was not 3249 | included in the current specification due to the complexity of 3250 | verifying equivalence across different DLTs and different DID 3251 | methods, and also of aggregating properties of equivalent DID 3252 | documents. However equivalence should be supported in a future 3253 | version of this specification. 3254 |

3255 |
3256 | 3257 |
3258 |

3259 | Timestamps 3260 |

3261 | 3262 |

3263 | Verifiable timestamps have significant utility for identifier 3264 | records. This is a good fit for DLTs, since most offer some type of 3265 | timestamp mechanism. Despite some transactional cost, they are the 3266 | most censorship-resistant transaction ordering systems in the world, 3267 | so they are nearly ideal for DID document timestamping. In some cases 3268 | a DLT's immediate timing is approximate, however their sense of 3269 | 3270 | "median time past" (see Bitcoin BIP 113) can be precisely 3271 | defined. A generic DID document timestamping mechanism could would 3272 | work across all DLTs and might operate via a mechanism including 3273 | either individual transactions or transaction batches. The generic 3274 | mechanism was deemed out of scope for this version, although it may 3275 | be included in a future version of this specification. 3276 |

3277 |
3278 | 3279 |
3280 |

3281 | Time Locks and DID Document Recovery 3282 |

3283 | 3284 |

3285 | Section mentions one 3286 | possible clever use of time locks to recover control of a DID after a 3287 | key compromise. The technique relies on an ability to override the 3288 | most recent update to a DID document with Authorization applied by an 3289 | earlier version of the DID document in order to defeat the attacker. 3290 | This protection depends on adding a 3291 | time lock (see Bitcoin BIP 65) to protect part of the transaction 3292 | chain, enabling a Authorization block to be used to recover control. 3293 | We plan to add support for time locks in a future version of this 3294 | specification. 3295 |

3296 |
3297 | 3298 |
3299 |

3300 | Smart Signatures 3301 |

3302 | 3303 |

3304 | Not all DLTs can support the Authorization logic in section 3305 | . 3306 | Therefore, in this version of the specification, all Authorization 3307 | logic is delegated to DID method specifications. A potential 3308 | future solution is a Smart 3309 | Signature specification that specifies the code any conformant 3310 | DLT may implement to process signature control logic. 3311 |

3312 |
3313 | 3314 |
3315 |

3316 | Verifiable Credentials 3317 |

3318 | 3319 |

3320 | Although DIDs and DID documents form a foundation for 3321 | decentralized identity, they are only the first step in describing their 3322 | subjects. The rest of the descriptive power comes through collecting and 3323 | selectively using Verifiable Credentials [[!VC-DATA-MODEL]]. Future versions of 3324 | the specification will describe in more detail how DIDs and DID 3325 | document can be integrated with — and help enable — the 3326 | Verifiable Credentials ecosystem. 3327 |

3328 |
3329 | 3330 |
3331 |

3332 | Alternate Serializations and Graph Models 3333 |

3334 | 3335 |

3336 | This version of the specification relies on JSON-LD and the RDF graph 3337 | model for expressing a DID document. Future versions of this 3338 | specification might specify other semantic graph formats for a DID 3339 | document. 3340 |

3341 |
3342 |
3343 | 3344 |
3345 |

3346 | IANA Considerations 3347 |

3348 | 3349 |

3350 | This section will be submitted to the Internet Engineering Steering Group 3351 | (IESG) for review, approval, and registration with IANA when this specification 3352 | becomes a W3C Proposed Recommendation. 3353 |

3354 | 3355 |
3356 |

application/did+json

3357 |
3358 |
Type name:
3359 |
application
3360 |
Subtype name:
3361 |
did+json
3362 |
Required parameters:
3363 |
None
3364 |
Optional parameters:
3365 |
None
3366 |
Encoding considerations:
3367 |
3368 | See RFC 8259, section 11. 3369 |
3370 |
Security considerations:
3371 |
3372 | See RFC 8259, section 12 [[RFC8259]]. 3373 |
3374 |
Interoperability considerations:
3375 |
Not Applicable
3376 |
Published specification:
3377 |
http://www.w3.org/TR/did-core/
3378 |
Applications that use this media type:
3379 |
3380 | Any application that requires an identifier that is decentralized, persistent, 3381 | cryptographically verifiable, and resolvable. Applications typically consist of 3382 | cryptographic identity systems, decentralized networks of devices, and 3383 | websites that issue or verify W3C Verifiable Credentials. 3384 |
3385 |
Additional information:
3386 |
3387 |
3388 |
Magic number(s):
3389 |
Not Applicable
3390 |
File extension(s):
3391 |
.did
3392 |
Macintosh file type code(s):
3393 |
TEXT
3394 |
3395 |
3396 |
Person & email address to contact for further information:
3397 |
Ivan Herman <ivan@w3.org>
3398 |
Intended usage:
3399 |
Common
3400 |
Restrictions on usage:
3401 |
None
3402 |
Author(s):
3403 |
Drummond Reed, Manu Sporny, Markus Sabadello, Dave Longley, Christopher Allen
3404 |
Change controller:
3405 |
W3C
3406 |
3407 | 3408 |

3409 | Fragment identifiers used with 3410 | application/did+json are treated 3411 | according to the rules defined in 3412 | DID Core v1.0, Fragment [[DID-CORE]]. 3413 |

3414 |
3415 | 3416 |
3417 |

application/did+ld+json

3418 |
3419 |
Type name:
3420 |
application
3421 |
Subtype name:
3422 |
did+ld+json
3423 |
Required parameters:
3424 |
None
3425 |
Optional parameters:
3426 |
None
3427 |
Encoding considerations:
3428 |
3429 | See RFC 8259, section 11. 3430 |
3431 |
Security considerations:
3432 |
3433 | See JSON-LD 1.1, Security Considerations 3434 | [[JSON-LD11]]. 3435 |
3436 |
Interoperability considerations:
3437 |
Not Applicable
3438 |
Published specification:
3439 |
http://www.w3.org/TR/did-core/
3440 |
Applications that use this media type:
3441 |
3442 | Any application that requires an identifier that is decentralized, persistent, 3443 | cryptographically verifiable, and resolvable. Applications typically consist of 3444 | cryptographic identity systems, decentralized networks of devices, and 3445 | websites that issue or verify W3C Verifiable Credentials. 3446 |
3447 |
Additional information:
3448 |
3449 |
3450 |
Magic number(s):
3451 |
Not Applicable
3452 |
File extension(s):
3453 |
.did
3454 |
Macintosh file type code(s):
3455 |
TEXT
3456 |
3457 |
3458 |
Person & email address to contact for further information:
3459 |
Ivan Herman <ivan@w3.org>
3460 |
Intended usage:
3461 |
Common
3462 |
Restrictions on usage:
3463 |
None
3464 |
Author(s):
3465 |
Drummond Reed, Manu Sporny, Markus Sabadello, Dave Longley, Christopher Allen
3466 |
Change controller:
3467 |
W3C
3468 |
3469 | 3470 |

3471 | Fragment identifiers used with 3472 | application/did+ld+json are treated 3473 | according to the rules associated with the 3474 | JSON-LD 1.1: application/ld+json 3475 | media type [[JSON-LD11]]. 3476 |

3477 |
3478 | 3479 |
3480 | 3481 | 3482 | 3483 | --------------------------------------------------------------------------------