├── did-primer-diagrams ├── did-format.png └── urn-format.png ├── README.md ├── CODEOWNERS ├── LICENSE.md ├── CONTRIBUTING.md └── index.html /did-primer-diagrams/did-format.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/w3c-ccg/did-primer/HEAD/did-primer-diagrams/did-format.png -------------------------------------------------------------------------------- /did-primer-diagrams/urn-format.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/w3c-ccg/did-primer/HEAD/did-primer-diagrams/urn-format.png -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Primer for Decentralized Identifiers 2 | 3 | This [document](https://w3c-ccg.github.io/did-primer/) is a primer for decentralized identifiers. 4 | 5 | -------------------------------------------------------------------------------- /CODEOWNERS: -------------------------------------------------------------------------------- 1 | # These owners will be the default owners for everything in 2 | # the repo. Unless a later match takes precedence, 3 | # they will be requested for review when someone opens a 4 | # pull request. 5 | * @msporny @talltree @andrewhughes3000 6 | 7 | # See CODEOWNERS syntax here: https://help.github.com/articles/about-codeowners/#codeowners-syntax 8 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | All Reports in this Repository are licensed by Contributors under the [W3C Software and Document 2 | License](https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document). 3 | 4 | Contributions to Specifications are made under the 5 | [W3C CLA](https://www.w3.org/community/about/agreements/cla/). 6 | 7 | Contributions to Software, including sample implementations, are under the 8 | [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0). 9 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # W3C Credentials Community Group 2 | 3 | Contributions to this repository are intended to become part of 4 | Recommendation-track documents governed by the 5 | [W3C Patent Policy](https://www.w3.org/Consortium/Patent-Policy-20040205/) and 6 | [Software and Document License](https://www.w3.org/Consortium/Legal/copyright-software). 7 | To make substantive contributions to specifications, you must either participate 8 | in the relevant W3C Working Group or make a non-member patent licensing commitment. 9 | 10 | If you are not the sole contributor to a contribution (pull request), please 11 | identify all contributors in the pull request comment. 12 | 13 | To add a contributor (other than yourself, that's automatic), mark them one 14 | per line as follows: 15 | 16 | ``` 17 | +@github_username 18 | ``` 19 | 20 | If you added a contributor by mistake, you can remove them in a comment with: 21 | 22 | ``` 23 | -@github_username 24 | ``` 25 | 26 | If you are making a pull request on behalf of someone else but you had no 27 | part in designing the feature, you can remove yourself with the above syntax. 28 | -------------------------------------------------------------------------------- /index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 6 | A Primer for Decentralized Identifiers 7 | 13 | 14 | 16 | 85 | 86 | 87 | 88 | 89 |
90 |

91 | A Decentralized Identifier (DID) is a new type of identifier that is 92 | globally unique, resolvable with high availability, and cryptographically 93 | verifiable. DIDs are typically associated with cryptographic material, such 94 | as public keys, and service endpoints, for establishing secure communication 95 | channels. DIDs are useful for any application that benefits from 96 | self-administered, cryptographically verifiable identifiers such as 97 | personal identifiers, organizational identifiers, and identifiers for 98 | Internet of Things scenarios. For example, current commercial deployments of 99 | W3C Verifiable Credentials heavily utilize Decentralized Identifiers to 100 | identify people, organizations, and things and to achieve a number of 101 | security and privacy-protecting guarantees. This document is an introduction 102 | to the concept of Decentralized Identifiers. 103 |

104 |
105 |
106 |

Comments regarding this document are welcome. Please file 107 | issues directly on GitHub, or 109 | send them to public-credentials@w3.org 111 | (subscribe, 113 | archives).

115 |

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

122 |

Work on this specification has also been supported by the Rebooting 123 | the Web of Trust community facilitated by Christopher Allen, 124 | Shannon Appelcline, Kiara Robles, Brian Weller, Betty Dhamers, 125 | Kaliya Young, Manu Sporny, Drummond Reed, Joe Andrieu, Kim Duffy, and 126 | Heather Vescent.

127 |
128 | 129 |
130 |

Introduction

131 |

At a superficial level, a decentralized 132 | identifier (DID) is simply a new type 133 | of globally unique identifier. But at a deeper level, DIDs are 134 | the core component of an entirely new layer of decentralized 135 | digital identity and public key infrastructure (PKI) for the 136 | Internet. This 138 | decentralized public key 139 | infrastructure (DPKI) could have as much 140 | impact on global cybersecurity and cyberprivacy as the 141 | development of the SSL/TLS 143 | protocol for encrypted Web traffic (now the largest 144 | PKI in the world).

145 |

This primer is designed to give newcomers to DID 146 | architecture the background they need to understand not just 147 | the DID specification, but the overall architecture for 148 | decentralized identity represented by the family of DID-related 149 | specifications currently under development. It covers:

150 | 179 |
180 |
181 |

How 183 | DIDs Differ from Other Globally Unique Identifiers

184 |

The need for globally unique identifiers that do not require 185 | a centralized registration authority is not new. 187 | UUIDs (Universally Unique Identifiers, also called 188 | GUIDs, Globally Unique Identifiers) were developed for this 189 | purpose in the 1980s and standardized first by the Open 190 | Software Foundation and then by IETF RFC 192 | 4122.

193 |

The need for persistent identifiers (identifiers that can be 194 | assigned once to an entity and never need to change) is also 195 | not new. This class of identifiers was standardized as URNs 197 | (Uniform Resource Names) first by IETF RFC 2141 199 | and more recently by RFC 201 | 8141.

202 |

As a rule, however, UUIDs are not globally resolvable and 203 | URNs – if resolvable – require a centralized registration 204 | authority. In addition, neither UUIDs or URNs inherently 205 | address a third characteristic – the ability to 206 | cryptographically verify ownership of the 207 | identifier.

208 |

For self-sovereign identity, which can be 209 | defined as a lifetime portable digital identity that does not 210 | depend on any centralized authority, we need a new class of 211 | identifier that fulfills all four requirements: persistence, 212 | global resolvability, cryptographic verifiability, and 213 | decentralization.

214 |
215 |
216 |

The Format of a DID

217 |

In 2016 the developers of the DID specification agreed with 218 | a suggestion from Christopher Allen that DIDs could be adapted 219 | to work with multiple blockchains by following the same basic 220 | pattern as the URN specification:

221 |
222 | 223 224 |
225 | urn:uuid:fe0cde11-59d2-4621-887f-23013499f905 226 |
227 |
228 |

The key difference is that with DIDs the namespace component 229 | identifies a DID method, and a DID 230 | method specification specifies the format of the 231 | method-specific identifier.

232 |
233 | 234 235 |
236 | did:example:12345abcde 237 |
238 |
239 |

DID methods (further explained below) define how DIDs work 240 | with a specific blockchain. All DID method specs must define 241 | the format and generation of the method-specific identifier. 242 | Note that the method specific identifier string 243 | must be unique in the namespace of that DID 244 | method.

245 |
246 |
247 |

DID Documents

248 |

DID infrastructure can be thought of as a global key-value 250 | database in which the database is all DID-compatible 251 | blockchains, distributed ledgers, or decentralized networks. In 252 | this virtual database, the key is a DID, and the value is a 253 | DID document. The purpose of the DID document 254 | is to describe the public keys, authentication protocols, and 255 | service endpoints necessary to bootstrap 256 | cryptographically-verifiable interactions with the identified 257 | entity.

258 |

A DID document is a valid JSON-LD 260 | object that uses the DID context (the 261 | RDF vocabulary of property names) defined in the DID 262 | specification. This includes six components (all optional):

263 |
    264 |
  1. 265 |

    The DID itself, so the DID document is 266 | fully self-describing.

    267 |
    2. 268 |
  2. 269 |

    A set of cryptographic material, such 270 | as public keys, that can be used for authentication or 271 | interaction with the DID subject.

    272 |
    3. 273 |
  3. 274 |

    A set of cryptographic protocols for 275 | interacting with the DID subject, such as authentication 276 | and capability delegation.

    277 |
    4. 278 |
  4. 279 |

    A set of service endpoints that 280 | describe where and how to interact with the DID 281 | subject.

    282 |
    5. 283 |
  5. 284 |

    Timestamps for auditing.

    285 |
    6. 286 |
  6. 287 |

    A optional JSON-LD signature if needed 288 | to verify the integrity of the DID document.

    289 |
    7. 290 |
291 |

See the DID 293 | specification for several examples of DID 294 | documents.

295 |
296 |
297 |

DID Methods

298 |

DIDs and DID documents can be adapted to any modern 299 | blockchain, distributed ledger, or other decentralized network 300 | capable of resolving a unique key into a unique value. It does 301 | not matter whether the blockchain is public, private, 302 | permissionless, or permissioned.

303 |

Defining how a DID and DID document are created, resolved, 304 | and managed on a specific blockchain or “target system” is the 305 | role of a DID method specification. DID method 306 | specifications are to the generic DID specification as URN 307 | namespace specifications (UUID, ISBN, OID, LSID, etc.) are to 308 | the generic IETF URN specification (RFC 310 | 8141).

311 |

DID method specifications typically define at least the 312 | following operations for a particular target system:

313 |
    314 |
  1. 315 |

    Create. Some DID methods may generate a 316 | DID directly from a cryptographic key pair. Others may use 317 | the address of a transaction or a smart contract on the 318 | blockchain itself.

    319 |
    2. 320 |
  2. 321 |

    Read. Some DID methods use blockchains 322 | that can store DID documents directly on the blockchain. 323 | Others may instruct DID resolvers to construct them 324 | dynamically based on attributes of a blockchain record. 325 | Still others may store a pointer on the blockchain to a DID 326 | document stored in one or more parts on other decentralized 327 | storage networks such as 329 | IPFS or STORJ.

    331 |
    3. 332 |
  3. 333 |

    Update. The update operation is the 334 | most critical from a security standpoint because control of 335 | a DID document represents control of the public keys or 336 | proofs necessary to authenticate an entity (and therefore 337 | for an attacker to impersonate the entity). Since 338 | verification of DID document update permissions can only be 339 | enforced by the target blockchain, the DID method 340 | specification must define precisely how authentication and 341 | authorization are performed for any update operation.

    342 |
    4. 343 |
  4. 344 |

    Delete. DID entries on a blockchain are 345 | by definition immutable, so they can never be “deleted” in 346 | the conventional database sense. However they can be 347 | revoked in the cryptographic sense. A DID 348 | method specification must define how this termination is 349 | performed, e.g., by writing a null DID document.

    350 |
    5. 351 |
352 |

See the DID Method 354 | Registry for a complete list of all known DID Method 355 | specifications.

356 |
357 |
358 |

DIDs and Privacy by 359 | Design

360 |

Privacy is an essential component of any identity management 361 | solution; it is especially critical for a global identity 362 | system that uses immutable public blockchains. Thankfully DID 363 | architecture can incorporate Privacy 365 | by Design at the very lowest levels of infrastructure 366 | and thus become a powerful, new, privacy-preserving technology 367 | if deployed using best practices such as:

368 |
    369 |
  1. 370 |

    Pairwise-pseudonymous DIDs. While DIDs 371 | can be used as well-known public identifiers, they can also 372 | be used as private identifiers issued on a per-relationship 373 | basis. So rather than a person having a single DID, like a 374 | cell phone number or national ID number, she can have 375 | thousands of pairwise-unique DIDs that cannot be correlated 376 | without her consent, yet can still be managed as easily as 377 | an address book.

    378 |
    2. 379 |
  2. 380 |

    Off-chain private data. Storing any 381 | type of PII on a public blockchain, even encrypted or 382 | hashed, is dangerous for two reasons: 1) the encrypted or 383 | hashed data is a global correlation point when the data is 384 | shared with multiple parties, and 2) if the encryption is 385 | eventually broken (e.g., quantum 387 | computing), the data will be forever accessible on 388 | an immutable public ledger. So the best practice is to 389 | store all private data off-chain and exchange it only over 390 | encrypted, private, peer-to-peer connections.

    391 |
    3. 392 |
  3. 393 |

    Selective disclosure. The decentralized 394 | PKI (DPKI) that DIDs make possible opens the door to 395 | individuals gaining greater control over their personal 396 | data in two ways. First, it enables it to be shared using 397 | encrypted digital credentials (see below). Second, these 398 | credentials can use zero-knowledge 400 | proof cryptography for 402 | data minimization, e.g., you can disclose that 403 | you are over a certain age without disclosing your exact 404 | birthdate.

    405 |
    4. 406 |
407 |
408 |
409 |

DIDs and Verifiable 410 | Credentials

411 |

DIDs are only the base layer of decentralized identity 412 | infrastructure. The next higher layer – where most of the value 413 | is unlocked – is verifiable credentials. This 414 | is the technical term for a digitally signed electronic 415 | credential that conforms to the interoperability standards 416 | being developed by the W3C Verifiable 418 | Claims Working Group.

419 |

DIDs can be used to identify various entities in the 420 | Verifiable Credentials ecosystem such as issuers, holders, 421 | subjects, and verifiers. More generally, DIDs can be used as 422 | identifiers for people, devices, and organizations.

423 |

See the Verifiable Credentials 425 | Primer for a brief introduction to the topic.

426 |
427 |
428 |

Appendix A: DID 429 | Community Resources

430 |

Besides the links throughout this primer, these additional 431 | resources are available to anyone interested in joining the 432 | communities that are actively developing specifications, 433 | experiments, and pilot projects.

434 | 460 |
461 | 462 | 463 | 464 | --------------------------------------------------------------------------------