+ Equivalence Properties +
+
+ The three equivalence properties defined in Core Properties
+ —alsoKnownAs, equivalentId, and
+ canonicalId—are subject to special security
+ considerations related to attacks against DIDs that are asserted to be
+ equivalent. Each of the equivalence property sections describes relevant
+ mitigation instructions. In general, they are:
+
+ The equivalentId and canonicalId properties
+ that constrain equivalence assertions to variants of a single DID produced by
+ the same DID method (e.g. did:foo:123 ≡ did:foo:hash(123))
+ can be trusted to the extent the resolving party trusts the DID method (and a
+ conforming producer) itself.
+
+ The alsoKnownAs property that permits an equivalence assertion
+ to URIs that are not governed by the same DID method (or may not be DIDs at
+ all) cannot be trusted without performing verification steps outside of the governing
+ DID method. See Section 5.1.1 for the recommendation to verify inverse relationships.
+
+ As with any other sensitive properties in the DID Document (e.g. public key references), + parties relying on any equivalence statement in a DID Document should guard against the + values of these properties being substituted by an attacker after the proper verification + has been performed. Any write access to a DID document stored in memory or disk after + verification has been performed is an attack vector that will circumvent verification + unless the DID document is re-verified. +
+ +Current Issues
What Does a DID Identify?
++ The DID Core specification states that a DID identifies the + DID subject—and that a DID subject can be anything that can be + identified with a URI. However some applications of DIDs, particularly + those involving the Semantic Web, may need a more precise definition of how + DID identification works. That is the purpose of this Appendix. +
+What types of resources can a DID identify?
++ Since a DID is a specific type of URI, the answer to this question is + provided by section 1.1 of the URI specification [[!RFC3986]]: +
++ This specification does not limit the scope of what might be a resource; + rather, the term "resource" is used in a general sense for whatever might be + identified by a URI. Familiar examples include an electronic document, an + image, a source of information with a consistent purpose (e.g., "today's + weather report for Los Angeles"), a service (e.g., an HTTP-to-SMS gateway), + and a collection of other resources. A resource is not necessarily + accessible via the Internet; e.g., human beings, corporations, and bound + books in a library can also be resources. Likewise, abstract concepts can + be resources, such as the operators and operands of a mathematical equation, + the types of a relationship (e.g., "parent" or "employee"), or numeric + values (e.g., zero, one, and infinity). ++
+ In other words, it does not matter whether a resource is “on” or “off” the + Internet—if it can be identified, it can be assigned a URI, and therefore it + can be assigned a DID. +
+How do you know what a DID identifies?
++ For any DID, the DID controller determines the DID subject. + Unfortunately it is all but impossible to determine the DID subject + from looking at the DID itself. The reason is that, in order to satisfy + several core properties of a DID as an identifier—especially + decentralization and cryptographic verifiability—DIDs are generally + only meaningful to machines, not humans. To illustrate, compare the following + two URIs: +
+
+ https://www.w3.org/2019/did-wg/WorkMode/getting-started
+
+ did:example:8uQhQMGzWxR8vw5P3UWH1j
+
+ The first is the URL of the Getting Started page of the W3C DID Working + Group. This is a human-meaningful identifier (at least to someone who + understands the English language). In this sense, the reader can be said to + “know” what the URL identifies without having to dereference it (provided + the reader trusts the publisher’s label). +
++ The second URI—the example DID—is meaningless to humans no matter what + language you speak. What it identifies is anyone’s guess in the absence of + further information describing the DID subject. So further information + about the DID subject is only discoverable by resolving the DID + to the DID document, obtaining a verifiable credential about the + DID, or via some other description of the DID. +
+Does the DID identify the DID document?
++ No. To be very precise, the DID identifies the DID subject and + resolves to the DID document (by following the protocol + specified by the DID method). The DID document is not a + separate resource from the DID subject and does not have a URI + separate from the DID. Rather the DID document is an artifact + of DID resolution controlled by the DID controller for the + purpose of describing the DID subject. +
++ This distinction is illustrated by the graph model shown in figure 2. +
+
+ How does the DID document describe the DID subject?
++ Each property in a DID document is a statement by the + DID controller that describes: +
+-
+
-
+ The DID subject itself (e.g., the
idand +alsoKnownAsproperties) +
+ -
+ How to interact with the DID subject (e.g., the
+
verificationMethodandservice+ properties). +
+ -
+ How to to interpret the specific representation of the DID document
+ (e.g., the
@contextproperty for a JSON-LD representation). +
+
+ There is only one required property in a DID document—the id
+ property—so that is the only statement guaranteed to be in a DID document.
+ That statement is illustrated by the solid red arrow in figure 2 asserting
+ that the DID identifies the DID subject.
+
How can you discover more information about the DID subject?
+
+ This is the purpose of the alsoKnownAs property. The
+ DID controller can use it to provide a list of other URIs (including
+ DIDs) that identify the same DID subject. Resolving or
+ dereferencing these URIs may yield other descriptions or representations of
+ the DID subject as illustrated in figure 3.
+
+ + This mechanism is how DID identification can fulfill a longstanding + recommendation from the W3C in Cool + URIs for the Semantic Web: +
++ Given only a URI, machines and people should be able to retrieve a + description about the resource identified by the URI from the Web. Such + a look-up mechanism is important to establish shared understanding of + what a URI identifies. Machines should get RDF data and humans should + get a readable representation, such as HTML. ++
+ Note that, although it is not required that a DID document use an + RDF-based representation such as JSON-LD, that format would meet the letter + of this W3C recommendation. +
+ +Can the DID document serve as a representation of the DID subject?
++ If the DID subject is an information resource that can be retrieved + from the Internet, then yes, the DID document can serve as a + representation of the DID subject. For example, a data schema that + needs a persistent, cryptographically verifiable identifier could be + assigned a DID, and its DID document could be used as a + standard way to retrieve a representation of that schema. +
+ +Can existing web resources also be assigned DIDs?
++ Yes, if the controller of a web page or any other web resource wants to + assign it a persistent, cryptographically verifiable identifier, the + controller can give it a DID. For example, the author of a blog + hosted by a blog hosting company (under that hosting company’s own URL) + could create a DID for the blog. In the DID document, the + author can include an alsoKnownAs property pointing to the current URL of + the blog: +
+
+ “alsoKnownAs”: [“https://myblog.blogging-host.example.com/home”]
+
+ + If the author subsequently moves the blog to a different hosting company + (or to the author’s own domain), the author can update the DID document + to point to the new URL for the blog: +
+
+ “alsoKnownAs”: [“https://myblog.example.com/”]
+
+ + The DID effectively adds a layer of indirection for the blog URL. + This layer of indirection is under the control of the author instead of + under external administrative authority such as a blog hosting company. This + is how DIDs can effectively function as + URNs (Uniform Resource + Names)—persistent identifiers for information resources whose network + location may change over time. +
++ DID Controllers and DID Subjects +
++ To avoid confusion about the relationship between DID controllers and + DID subjects, the DID Working Group has found it helpful to classify + DID subjects into two disjoint sets based on their relationship to + the DID controller. +
+Set 1: The DID subject is the DID controller
++ The first case, shown in figure 4, is the common scenario where the + DID subject is also the DID controller. This is the case when + an individual or organization creates a DID to self-identify. +
+
+ + From a graph model perspective, even though the nodes identified as the + DID controller and DID subject in figure 4 are distinct, + there is a logical arc connecting them to express a semantic equivalence + relationship (in RDF/OWL, this is expressed using the owl:sameAs predicate). +
+Set 2: The DID subject is not the DID controller
++ The second case, shown in figure 2 in the previous appendix, is when the + DID subject is a separate entity from the DID controller. This + is the case when, for example, a parent creates a DID for a child; a + corporation creates a DID for a subsidiary; or a manufacturer creates + a DID for a product, an IoT device, or a digital file. +
++ From a graph model perspective, the only difference between figure 2 and + figure 4 is that in the latter there is an equivalence arc relationship + between the DID subject and DID controller nodes. +
++Multiple DID Controllers +
++ A DID document may have more than one DID controller. In this + situation there are two basic options available for how control is shared. +
+Option #1: Independent Control
++ In the first option, shown in figure 5, each of the DID controllers + may act on its own, i.e., each one has full power to update the + DID document independently. From a graph model perspective, in this + configuration: +
+-
+
- + Each additional DID controller is another distinct graph node + (which may be identified by its own DID). + +
- + The same arcs (“controls” and “controller”) exist between each + DID controller and the DID document. + +
+ Option #2: Group Control
++ In the second option, the DID controllers must act together in some + fashion, such as when using a cryptographic algorithm that requires multiple + digital signatures (“multi-sig”) or a threshold number of digital + signatures (“m-of-n”). From a functional standpoint, this option is similar + to a single DID controller because, although each of the + DID controllers in the DID controller group has its own graph + node, the actual control collapses into a single logical graph node + representing the DID controller group as shown in figure 6: +
+
+ + This configuration will often apply when the DID subject is an + organization, corporation, government agency, community, or any other group + that is not controlled by a single individual. +
+