Diagram

Description

The process starts with a DID User (E1) who has a DID URL (D1) they would like to dereference.

Using a DID User Client Device (C1), the user directs the device to use the DID URL through some gesture, clicking on a link, entering a DID manually, or scanning a QR code (F0). This input to the DID Enabled Application (P1) triggers a call to Resolve (F1), which then resolves the DID URL according to its DID method, returning the authoritative DID Document (D3) according to the parameters passed in.

How the client device gets a DID URL and how the user interacts with application is outside the scope of this specification.

Each device in the diagram represents a different trust container, each representing a specific set of code running on a particular device. Each code object (D4, D6, and D8) is maintained by at least one human maintainer (E2, E5, E8, respectively). Each device (C1, C2, C3) is administered by at least one human administrator (E3, E6, E9, respectively) on behalf of a service provider (E4, E7, E10, respectively) who, as a legal person, holds operational authority over each device.

It is understood that each device is operated by a service provider, administered by a human, using code maintained by a human. In the case that either the maintenance or administration is AI-driven, we consider the human configuring and running that AI to be the maintainer or administrator, respectively. When discussing different deployment strategies, it is important to consider how these entities change and how those changes impact security of the system.

It is also worth noting that the resolve method call (F1) crosses a fundamental trust boundary (T1), where the result of the resolver *is* necessarily taken as authoritative. Regardless of the complexity of the resolver and VDR systems, the DID user chooses the resolvers they trust; it is understood that the choice of resolver is an unavoidable build versus buy decision. However that resolver achieves the result is up to the quality of its own implementation of each supported DID method.

DID Resolution, as defined in this specification, begins after the Resolver (P2) receives a Base DID URL (D2)—the DID URL minus the fragment&mdsh; and associated parameters. The resolver (P2) then queries the VDR Node(P3) with Read VDR State (F3) based on that state, generates the canonical DID Document (D3) and associated metadata (D10 and D11) which is returned to the application (P1). The application takes that result and depending on whether or not a secondary resource is indicated, it either returns the DID document or dereferences the secondary resource.

How the VDR maintains state (D9) and how the resolver reads that state (F3) are DID-method specific, defined in each DID method specification and otherwise out of scope of this specification.

Dictionary

E1 DID URL User

The primary end user for DID resolution is an individual human seeking to use a DID URL for some purpose. There are two major variations of this [=DID URL User=]:

1. Someone who controls a [=DID document=], and presumably is able to update the DID document should its DID method support it.
2. Someone who has received or seen a DID URL in a particular context and wants to perform a DID related function with it,
   1. Verifying a proof signed by the DID
   2. Verifying an authorization invocation
   3. Interacting with the DID controller by sending a message to a service endpoint
   4. Retrieving a resource indicated by a DID

The [=DID URL User=] is primarily concerned with the integrity and reliability of the system. They may be just about anyone on the planet with a computation device at their disposal: a smart phone, a desktop, even a shared device at a library or internet cafe. The User could also be a corporate employee or agent, who has received a DID from a supplier or customer and wants to use it to verify a verifiable presentation or satisfy a confidence method to increase their confidence that a given actor is the subject of a particular Verifiable Credential.

As a technical layperson, the DID URL User requires a certain reliability and simplicity; the system should “just work” in the manner they have become accustomed to on the Web. When their software encounters a DID URL, it should work just like any URL, without additional interactions, when possible.

Perhaps most importantly, the DID URL User SHOULD retain complete control over which software and services they use for DID resolution.

In practice, most individuals will make choices based on brand confidence and peer recommendations. End users choose the software they want to run and the services they access, including which resolvers to use for specific DID methods. Just like a web browser enables end users to choose which website they want to visit, DID URL users MUST be able to direct their DID client software to use the resolvers they trust. In practice, software will be delivered with default services and many users will never see the difference, just as some users may start on a browser's default home page and only click on links, never typing a URL into an address bar. However, it is a fundamental security decision that end users get to decide which resolvers are trusted.

Finally, the DID URL User may have any number of accessibility challenges, from visual impairments to language gaps. While it is important that DID resolution works seamlessly without a lot of cognitive burden, implementations should take care to ensure that the broadest number of users can effectively use the technology, especially when interactive prompts are used to confirm or direct intermediary behavior. For example, did:btcr has an iterative resolution process, where the data required to complete resolution may not be known–even as a requirement–when the DID URL is initially presented.

E2 Client Code Maintainer

The client code maintainer cares about the integrity of their software code base.

E3 Client Administrator

The client administrator cares about a reliably working client device. They want to know the software configuration on the device aligns with individual and/or corporate policy, especially with regard to resolver selection and library adoption.

E4 Client Service Provider

If the client service provider is primarily concerned with the integrity, usability, and profitability/cost of the service. For typical consumer usage, the end user is the client service provider, but when the client is run on behalf of a corporation for its employees, that employer is the client service provider.

The Client Service Provider cares about the code and configuration on the device is as the administrator has established, based on the service provider’s policies.

E5 Resolver Code Maintainer

The resolver code maintainer wants to ensure that their code is provably executing the resolution function as defined in the DID methods it supports.

E6 Resolver Administrator

The resolver administrator wants to ensure that the resolution service is configured as intended and that any libraries or original software is reliably performing as needed and expected.

E7 Resolver Service Provider

The resolver administrator wants to ensure that the resolution service is running as configured and without errors.

Fundamentally, the resolver service must be trustworthy enough for users to be willing to rely on its service for cryptographically anchored interactions. Since DIDs can be used to secure information and transactions of arbitrary value, the service provider necessarily wants to be perceived as reliable, friendly, and easy to use.

At the end of the day, it's the resolver service provider that the DID URL User is trusting to return the real, authoritative DID document.

E8 VDR Code Maintainer

The VDR Code Maintainer cares primarily about the quality of their code. Many VDRs are open source, but there is no expectation that this is always true. Whether open or closed source, the code maintainer wants to be able to maintain code quality so that those who rely on their software can rest assured that the software is doing exactly what is promised, and no more.

That said, the VDR Code Maintainer may only care about the Verifiable Data Registry, without any expectation of use beyond that. To wit, BTCR2 can use a VDR device that is directly running a full bitcoin node; in that configuration, the VDR code maintainer is a bitcoin core developer. Bitcoin core developers care primarily about the integrity of the bitcoin network as maintained by bitcoin core. They don't care about DIDs, nor do they need to.

E9 VDR Administrator

The VDR administrator runs the actual VDR device queried by the resolver. In most configurations, they care primarily (perhaps ONLY) about the reliable operation of the VDR device.

E10 VDR Service Provider

VDR service providers care about providing a reliable verifiable data registry, for whatever purpose that VDR is used for. Often a VDR service provider stands up a VDR device as a public service, such as bitcoin nodes that are accessible by others. Some service providers may offer VDR capability as a paid service.

Adding a threat

To add a new threat to the model, we need several components.

1. A good name
2. A unique ID
3. A description
4. One or more responses
5. List of affected elements
6. The analytic framework

We discuss each of these below.

C1

Adding to this repo

1. Create A threat file
2. Give it a good name
3. Add javascript element
4. Add threat to outline

Create a threat file

Create a JavaScript file that defines and registers your threat, formatted like the following template. Make sure you retain the opening immediate function execution wrapper and that you register with the ThreatModel object.

// wrap your data definition in an Immediately Invoked Function Expression
(function () {
  
  // then define a single threat
  var threat = {
    id: "T0",
    name: "Template Threat",
    description: "This is a template threat. It is not a real threat.",
    responses: [{
      id: "R0",
      name: "Template Response",
      description: "This is a template response. It is not a real response."
    }],
    elements: ["C1", "P1"],
    framework: {
      name: "Fake Framework",
      type: "Fake Type"
    }
  };

  // then register that threat with the global ThreatModel object 
  window.ThreatModel.registerThreat(threat);

})();  // Finish the Immediately Invoked Function Expression


       

Give the file a good name

Name the file uniquely, preferably with the following pattern based on the ID and name, all in lower-case kebab style

          var id = `${threat.id}-${threat.name}`;
          id = id.toLowerCase();
          id = id.replace(/ /g, "-");
          return id;
      

For example, T0. Template Threat becomes t0-template-threat

Add javascript element

Add a new <script> tag

        <script src="threats/t0-template-threat.js"></script>
      

Add threat to outline

Update the outline.js file, adding the id of your threat, e.g., T0 to the threats array.

Test & Submit

Open the index.html locally and you should see your threat added to the list. Propose your working change as a PR, for consideration by the editors.