Making it possible to connect existing systems and Decentralized Identifiers (DIDs) is an important undertaking that can aid in bootstrapping adoption and usefulness of DIDs. One such form of connection is the ability of a DID controller to prove they are the same entity that controls an Internet domain.

The DID Configuration resource provides proof of a bi-directional relationship between the controller of an Internet domain and a DID via cryptographically verifiable signatures that are linked to a DID's key material. This document describes the data format of the resource and the resource location at which Internet domain controllers can publish their DID Configuration.

Due to the location of the DID Configuration resource, discovery of associated Decentralized Identifiers against a domain is trivial. However, the inverse (i.e given a DID-URI discover the associated domains) is deemed out of scope.

DID Configuration is a draft specification being developed within the Decentralized Identity Foundation (DIF), and intended for registration with IANA as a Well-Known resource. This spec will be updated to reflect relevant changes, and participants are encouraged to contribute at the following repository location: https://github.com/decentralized-identity/.well-known

Terminology

Resource Location

The DID Configuration resource MUST exist at the domain root, in the IETF 8615 Well-Known Resource directory, as follows: `/.well-known/did-configuration`

Resource Definition

The DID Configuration resource MUST be a valid JSON object containing Domain Linkage Assertions, which contain cryptographically verifiable claims that prove the same entity controls both the included DIDs and the domain the resource is located under. The resource MUST NOT exceed 8 kilobytes in total size; resources that exceed this maximum size are to be ignored by the processing entity.

Example

{
  "entries": [
    {
      "did": "did:btcr:123...",
      "jwt": "ewogICJAY29udGV4dCI..."
              ↑ EXAMPLE OF DECODED JWT VALUE
              {
                "iss": "did:btcr:123...",
                "domain": "example.com",
                "exp": 1475878357
              }
    },
    {
      "did": "did:ethr:456...",
      "jwt": "73hf3unAY29udGc3dvH..."
    },
    {
      "did": "did:sov:789...",
      "jwt": "uC75Xsdcgbd73Cdeqc8..."
    }
  ]
}

Top-Level Properties

The following properties are defined for use at the top-level of the resource - all other properties that are not defined below MUST be ignored:

• `entries` - The resource MUST contain this property, and its value MUST be an array of Domain Linkage Assertion objects.

Domain Linkage Assertions

The following properties are defined for Domain Linkage Assertion objects - all other properties that are not defined below MUST be ignored:

• `did` - MUST be present, and the DID string MUST match the DID string specified in the `iss` property of the assertion's decoded `jwt` value
• `jwt` - MUST be present, and MUST be a JWT signed by the keys currently associated with the specified DID. The JWT assertion defines the following claims:
  • `iss` - MUST be present, and MUST be a DID string that matches the DID string asserted in the DID Entry Object.
  • `domain` - MUST be present, and MUST match the domain the DID Configuration resource is located at
  • `exp` - SHOULD be defined to indicate a time after which the assertion of domain linkage MUST NOT be deemed valid

Resource Fetch and Validation

1. Given a domain, `example.com`, fetch the DID Configuration resource via a `GET` request over secure HTTP connection (`https`) to the well-known location: `https://example.com/.well-known/did-configuration`
2. Provided the call returns a successful response, ensure the body is no larger than `8 kilobytes` in size.
3. Parse the body as JSON in accordance with IETF RFC 8259

Validation of Domain Linkage Assertions

After fetching and validating the resource via the Resource Fetch and Validation process enumerated above, the processing entity MAY choose to validate any of Domain Linkage Assertions it contains. Domain Linkage Assertions are independent from one another, thus one being valid or invalid does not affect the state of the others. For a Domain Linkage Assertions to be deemed valid, it MUST be successfully processed in accordance with the following steps:

1. The assertion object MUST contain the property `did`, and the value MUST be a valid DID URI
2. The assertion object MUST contain the property `jwt`, and the value MUST be a compact serialization form of a JWT
3. The JWT object MUST contain the `iss` property, and its value MUST match the DID URI present in the assertion's outer `did` property value (as noted in step 1 above)
4. The JWT object MUST contain the `domain` property, and its value MUST match the host portion of the URL the resource was requested from.
5. The JWT object SHOULD contain the `exp` property, and if present, the value MUST be an epoch time that is greater than the current epoch time. If this property is not present, the assertion's future expiry is based on its continued presence in the resource (or its replacement with updated assertion that contains an expiry value).
6. Once all properties in the JWT have been parsed in accordance with the preceding rules, the implementer MUST perform DID resolution on the DID URI specified in the `iss` property to obtain the associated DID document.
7. Using the retrieved DID document, the implementer MUST validate the signature of the JWT against key material referenced in the authentication section of the DID document.

In the case an entry fails validation against any of the criteria enumerated above, the single entry that failed will be deemed invalid, and the validation implementation MUST produce an error to that effect. If an entry fails validation during an iteration of the entries by the processing entity, there is no normative implication about the validity of other entries, and the choice to continue iteration and validation of further entries is at the election of the processing entity.

Processing Order of Domain Linkage Assertion Entries

If the resource processing entity is not looking for the presence of a specific DID, or intending to validate a specific DID in the `entries` array of Domain Linkage Assertions, the resource processing entity SHOULD iterate the array of Domain Linkage Assertions beginning at 0 index. This normative iteration from 0 index is intended to allow domain controllers to order their Domain Linkage Assertions in accordance with a known processing order, in cases where order may matter to the domain controller. An example of this is the case where a domain controller has a primary signing DID that is the likely target of interest for the vast majority of relying parties who seek to validate an assertion based on the DIDs associated with a domain.