§ Trust DID Web - did:tdw - v0.4

Specification Status: HISTORICAL – THIS IS NOT THE CURRENT VERSION OF THE SPECIFICATION

This version of the specification was released at the time the OLD name for the DID Method was in use. The DID Method hame has since changed to did:webvh (“did:web + Verifiable History”).

Specification Version: 0.4 (see Changelog)

Latest Version:

• Specification: https://identity.foundation/didwebvh/
• Repository: https://github.com/decentralized-identity/didwebvh

Previous Versions:

• v0.3

Information Site: https://didtdw.org/

Editors:

Stephen Curran

John Jordan, BC Gov

Andrew Whitehead

Brian Richter

Michel Sahli

Martina Kolpondinos

Dmitri Zagdulin

Participate:

GitHub repo

File a bug

Commit history

Implementations:

TypeScript

Python

Go

DIDTDW Server in Python

§ Abstract

Trust DID Web (did:tdw) is an enhancement to the did:web DID method, providing complementary features that address did:web’s limitations. did:tdw features include:

• Ongoing publishing of all DID Document (DIDDoc) versions for a DID instead of, or alongside a current did:web DID/DIDDoc.
• The same DID-to-HTTPS transformation as did:web.
• Supports the same High Assurance DIDs with DNS mechanism.
• The ability to resolve the full history of the DID using a verifiable chain of updates to the DIDDoc from genesis to deactivation.
• A self-certifying identifier (SCID) for the DID. The SCID, globally unique and embedded in the DID, is derived from the initial DID log entry. It ensures the integrity of the DID’s history mitigating the risk of attackers creating a new object with the same identifier.
• An optional mechanism for enabling DID portability via the SCID, allowing the DID’s web location to be moved and the DID string to be updated, both while retaining a connection to the predecessor DID(s) and preserving the DID’s verifiable history.
• DIDDoc updates contain a proof signed by the DID Controllers authorized to update the DID.
• An optional mechanism for publishing “pre-rotation” keys to prevent the loss of control of a DID in cases where an active private key is compromised.
• An optional mechanism for having collaborating witnesses that approve of updates to the DID by a DID Controller before publication.
• DID URL path handling that defaults (but can be overridden) to automatically resolving <did>/path/to/file by using a comparable DID-to-HTTPS translation as for the DIDDoc.
• A DID URL path <did>/whois that defaults to automatically returning (if published by the DID controller) a Verifiable Presentation containing Verifiable Credentials with the DID as the credentialSubject, signed by the DID. It draws inspiration from the traditional WHOIS protocol [RFC3912], offering an easy-to-use, decentralized, trust registry.

Combined, the additional features enable greater trust and security without compromising the simplicity of did:web.

For more information about the Trust DID Web (did:tdw) DID method and how (and where) it is used in practice, please visit https://didtdw.org/

§ Overview

The emergence of Decentralized Identifiers (DIDs) and with them the evolution of DID Methods continues to be a dynamic area of development in the quest for trusted, secure and private digital identity management where the users are in control of their own data.

The did:web method, for example, leverages the Domain Name System (DNS) to perform the DID operations. This approach is praised for its simplicity and ease of deployment, including DID-to-HTTPS transformation and addressing some aspects of trust by allowing for DIDs to be associated with a domain’s reputation or published on platforms such as GitHub. However, it is not without its challenges– from trust layers inherited from the web and the absence of a verifiable history for the DID.

Tackling these concerns, the did:tdw (Trust DID Web) DID method aims to enhance did:web by introducing features such as a self-certifying identifiers (SCIDs), update key(s) and a verifiable history, akin to what is available with ledger-based DIDs, but without relying on a ledger.

This approach not only maintains backward compatibility but also offers an additional layer of assurance for those requiring more robust verification processes. By publishing the resulting DID as both did:web and did:tdw, it caters to a broader range of trust requirements, from those who are comfortable with the existing did:web infrastructure to those seeking greater security assurances provided by did:tdw. This innovative step represents a significant stride towards a more trusted and secure web, where the integrity of cryptographic key publishing is paramount.

The key differences between did:web and did:tdw revolve around the core issues of decentralization and security. did:web is recognized for its simplicity and cost-effectiveness, allowing for easy establishment of a credential ecosystem. However, it is not inherently decentralized as it relies on DNS domain names, which require centralized registries. Furthermore, it lacks a cryptographically verifiable, tamper-resistant, and persistently stored DID document. In contrast, did:tdw (Trust DID Web) is proposed as an enhancement to did:web, aiming to address these limitations by adding a verifiable history to the DID without the need for a ledger. This method seeks to provide a more decentralized approach by ensuring that the security of the embedded SCID does not depend on DNS. Additionally, did:tdw is capable of resolving a cryptographically verifiable trust registry and status lists, using DID-Linked Resources, which did:web lacks. These features are designed to build a trusted web, offering a higher level of assurance for cryptographic key publishing and management.

For backwards compatibility, and for verifiers that “trust” did:web, a did:tdw can be trivially modified and published in parallel to a did:web DID. For resolvers that want more assurance, did:tdw provides a way to “trust did:web” (or to enable a “trusted web” if you say it fast) enabled by the features listed in the Abstract.

The following is a tl;dr summary of how did:tdw works:

1. did:tdw uses the same DID-to-HTTPS transformation as did:web, so did:tdw’s did.jsonl (JSON Lines) file is found in the same location as did:web’s did.json file, and supports an easy transition from did:web to gain the added benefits of did:tdw.
2. The did.jsonl is a list of JSON DID log entries, one per line, whitespace removed (per JSON Lines). Each entry contains the information needed to derive a version of the DIDDoc from its preceding version. The did.jsonl is also referred to as the DID Log.
3. Each DID log entry is a JSON object containing the following properties:
   1. versionId – a value that combines the version number (starting at 1 and incremented by one per version), a literal dash -, and a hash of the entry. The entry hash calculation links each entry to its predecessor in a ledger-like chain.
   2. versionTime – as asserted by the DID Controller.
   3. parameters – a set of parameters that impact the processing of the current and future log entries.
      • Example parameters are the version of the did:tdw specification and hash algorithm being used as well as the SCID and update key(s).
   4. state – the new version of the DIDDoc.
   5. A Data Integrity (DI) proof across the entry, signed by a DID Controller authorized key to update the DIDDoc, and optionally, a set of witnesses that monitor the actions of the DID Controller.
4. In generating the first version of the DIDDoc, the DID calculates the SCID for the DID from the first log entry (which includes the DIDDoc) by using the string "{SCID}" everywhere the actual SCID is to be placed. The DID then replaces the placeholders with the calculated SCID, including it as a parameter in the first log entry, and inserting it where needed in the initial (and all subsequent) DIDDocs. The SCID enables an optional portability capability, allowing a DID’s web location to be moved, while retaining the DID and version history of the DID.
5. A DID Controller generates and publishes the new/updated DID Log file by making it available at the appropriate location on the web, based on the identifier of the DID.
6. Given a did:tdw DID, a resolver converts the DID to an HTTPS URL, retrieves, and processes the DID Log did.jsonl, generating and verifying each log entry as per the requirements outlined in this specification.
   • In the process, the resolver collects all the DIDDoc versions and public keys used by the DID currently, or in the past. This enables resolving both current and past versions of the DID.
7. did:tdw DID URLs with paths and /whois are resolved to documents published by the DID Controller that are by default in the web location relative to the did.jsonl file. See the note below about the powerful capability enabled by the /whois DID URL path.
8. Optionally, a DID Controller can easily generate and publish a did:web DIDDoc from the latest did:tdw DIDDoc in parallel with the did:tdw DID Log.

A resolver settling for just the `did:web` version of the DID does not get the
verifiability of the `did:tdw` log.

An example of a did:tdw evolving through a series of versions can be seen in the did:tdw Examples on the did:tdw information site.

§ The /whois Use Case

This DID Method introduces what we hope will be a widely embraced convention for all DID Methods – the /whois path. This feature harkens back to the WHOIS protocol that was created in the 1970s to provide a directory about people and entities in the early days of ARPANET. In the 80’s, whois evolved into [RFC920] that has expanded into the global whois feature we know today as [RFC3912]. Submit a whois request about a domain name, and get back the information published about that domain.

We propose that the /whois path for a DID enable a comparable, decentralized, version of the WHOIS protocol for DIDs. Notably, when <did>/whois is resolved (using a standard DID service that follows the Linked-VP specification), a Verifiable Presentation (VP) may be returned (if published by the DID Controller) containing Verifiable Credentials with the DID as the credentialSubject, and the VP signed by the DID. Given a DID, one can gather verifiable data about the DID Controller by resolving <did>/whois and processing the returned VP. That’s powerful – an efficient, highly decentralized, trust registry. For did:tdw, the approach is very simple – transform the DID to its HTTPS equivalent, and execute a GET <https>/whois. Need to know who issued the VCs in the VP? Get the issuer DIDs from those VCs, and resolve <issuer did>/whois for each. This is comparable to walking a CA (Certificate Authority) hierarchy, but self-managed by the DID Controllers – and the issuers that attest to them.

The following is a use case for the /whois capability. Consider an example of the did:tdw controller being a mining company that has exported a shipment and created a “Product Passport” Verifiable Credential with information about the shipment. A country importing the shipment (the Importer) might want to know more about the issuer of the VC, and hence, the details of the shipment. They resolve the <did>/whois of the entity and get back a Verifiable Presentation about that DID. It might contain:

• A verifiable credential issued by the Legal Entity Registrar for the jurisdiction in which the mining company is headquartered.
  • Since the Importer knows about the Legal Entity Registrar, they can automate this lookup to get more information about the company from the VC – its legal name, when it was registered, contact information, etc.
• A verifiable credential for a “Mining Permit” issued by the mining authority for the jurisdiction in which the company operates.
  • Perhaps the Importer does not know about the mining authority for that jurisdiction. The Importer can repeat the /whois resolution process for the issuer of that credential. The Importer might (for example), resolve and verify the did:tdw DID for the Authority, and then resolve the /whois DID URL to find a verifiable credential issued by the government of the jurisdiction. The Importer recognizes and trusts that government’s authority, and so can decide to recognize and trust the mining permit authority.
• A verifiable credential about the auditing of the mining practices of the mining company. Again, the Importer doesn’t know about the issuer of the audit VC, so they resolve the /whois for the DID of the issuer, get its VP and find that it is accredited to audit mining companies by the London Metal Exchange according to one of its mining standards. As the Importer knows about both the London Metal Exchange and the standard, it can make a trust decision about the original Product Passport Verifiable Credential.

Such checks can all be done with a handful of HTTPS requests and the processing of the DIDs and verifiable presentations. If the system cannot automatically make a trust decision, lots of information has been quickly collected that can be passed to a person to make such a decision.

The result is an efficient, verifiable, credential-based, decentralized, multi-domain trust registry, empowering individuals and organizations to verify the authenticity and legitimacy of DIDs. The convention promotes a decentralized trust model where trust is established through cryptographic verification rather than reliance on centralized authorities. By enabling anyone to access and validate the information associated with a DID, the “/whois” path contributes to the overall security and integrity of decentralized networks.

§ did:tdw DID Method Specification

§ Target System

The target system of the Trust DID Web (TDW) DID method is the host (or domain) name when the domain specified by the DID is resolved through the Domain Name System (DNS) and verified by processing a log of DID versions.

§ Method Name

The namestring that identifies this DID method is: tdw. A DID that uses this method MUST begin with the following prefix: did:tdw. Per the DID specification, this string MUST be in lowercase. The remainder of the DID, after the prefix, is the method-specific identifier, specified below.

§ Method-Specific Identifier

The did:tdw method-specific identifier contains both the self-certifying identifier (SCID) for the DID, and a fully qualified domain name (with an optional path) that is secured by a TLS/SSL certificate. Given the DID, a transformation to an HTTPS URL can be performed such that the DID Log for the did:tdw DID is retrieved (via an HTTP GET) and processed to produce the DIDDoc for the DID. As per the Augmented Backus-Naur Form (ABNF) notation below, the SCID MUST be the first element of the method-specific identifier.

Formal rules describing valid domain name syntax are described in [RFC1035], [RFC1123], and [RFC2181]. Each did:tdw DID’s globally unique SCID MUST be generated during the creation of the DID based on its initial content and placed into the DID identifier for publication and use.

The domain name element of the method-specific identifier MUST match the name found in the SSL/TLS certificate per [RFC6125] and the its replacement [RFC9525], and it MUST NOT include IP addresses. A port MAY be included and the colon MUST be percent encoded to prevent a conflict with paths. Directories and subdirectories MAY optionally be included, delimited by colons rather than slashes.

As specified in the following Augmented Backus-Naur Form (ABNF) notation [RFC2234] the SCID MUST be present in the DID string. See examples below. The domain-segment and path-segment elements refer to [RFC3986]’s ABNF for a Generic URL (page 49). Attempting to replicate here the full ABNF of those elements from that RFC would inevitably be wrong.

tdw-did = "did:tdw:" scid ":" domain-segment 1+( "." domain-segment ) [ percent-encoded-port ] *( ":" path-segment )
scid = 46(base58-alphabet) ; The characters in the base58-btc-alphabet are as defined in the referenced W3C "Controller Documents" specification 
domain-segment = ; A part of a domain name as defined in RFC3986, such as "example" and "com" in "example.com"
percent-encoded-port = "%3A" ( "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ) 1*4( DIGIT )
path-segment= ; A part of a URL path as defined in RFC3986, such as "path", "to", "folder" in "path/to/folder"

The ABNF for a did:tdw is almost identical to that of did:web, with changes only to the DID Method (tdw instead of web), and the addition of the <scid>: (defined in the SCID) section of this specification) element in did:tdw that is not in did:web. As specified in the DID-to-HTTPS Transformation section of this specification, did:tdw and did:web DIDs that have the same fully qualified domain and path transform to the same HTTPS URL, with the exception of the final file – did.json for did:web and did.jsonl for did:tdw.

§ The DID to HTTPS Transformation

The did:tdw method-specific identifier is defined to enable a transformation of the DID to an HTTPS URL for publishing and retrieving the DID Log. This section defines the transformation from DID to HTTPS URL, including a number of examples.

Given a did:tdw, the HTTPS URL for the DID Log is generated by carrying out the following steps. The steps are carried out by the DID to determine where to publish the DID Log, and by all resolvers to retrieve the DID Log.

1. Remove the literal did:tdw: prefix from the DID, leaving the method specific identifier.
2. Remove the SCID by removing the text up to and including the first colon (<scid>:) from the method-specific identifier and continue processing.
3. Replace : with / in the method-specific identifier to obtain the fully qualified domain name and optional path.
4. If there is no optional path, append /.well-known to the URL.
   1. When this algorithm is used for resolving a DID path (such as <did>/whois or <did>/path/to/file as defined in the section [DID URL Handling](#did-url-resolution)), the /.well-known` MUST NOT be included in the HTTPS URL.
5. If the domain contains a port, percent decode the colon.
6. Generate an HTTPS URL to the expected location of the DIDDoc by prepending https://.
7. Append /did.jsonl to complete the URL.
   1. When this algorithm is used for resolving a DID path (such as <did>/whois or `/path/to/file as defined in the section DID URL Handling), append the DID URL path instead.

The following are some examples of various DID-to-HTTPS transformations based on the processing steps specified above.

The location of the did:tdw did.jsonl DID Log file is the same as where the comparable did:web’s did.json file is published. A DID MAY choose to publish both DIDs and so, both files. The process to do so is described in the publishing a parallel did:web DID section of this specification.

§ The DID Log File

The DID log file contains a list of entries, one for each version of the DID. A version of the DID is an update to the contents of the resolved DIDDoc for the DID, and/or a change to the parameters that control the generation and verification of the DID.

Each entry is a JSON object consisting of the following properties.

{ "versionId": "", "versionTime": "", "parameters": {}, "state": {}, "proof" : [] }

1. The value of versionId MUST be a string consisting of the DID version number (starting at 1 and incrementing by one per DID version), a literal dash -, and the entryHash, a hash calculated across the log entry content. The input to the hash is chosen so as to link each entry to its predecessor in a ledger-like chain. The input to the hash is specified in the Entry Hash Generation and Verification section of this specification.
2. The value of versionTime MUST be a timestamp in UTC of the entry in ISO8601 format, as asserted by the DID Controller. The timestamp MUST be the time the DID will be retrieved by a witness or resolver, or before.
3. The JSON object parameters contains the configurations/options set by the DID Controller to be used in the processing of current and future log entries. Permitted parameters are defined in the did:tdw DID Method Parameters section of this specification.
4. The JSON object state contains the DIDDoc for this version of the DID.
5. The JSON array proof contains a Data Integrity proof calculated across the entry and signed by key authorized to update the DIDDoc.

After creation, each entry has (per the JSON Lines specification) all extra whitespace removed, a \n character appended, and the result added to the DID Log file for publication.

A more comprehensive description of how to create and update a DID log is given in steps 4 - 6 of the create DID section.

Examples of DID Logs and DID log entries can be found in the did:tdw` Examples section of this specification.

§ DID Method Operations

§ Create (Register)

Creating a did:tdw DID is done by carrying out the following steps.

1. Define the DID string The start of the DID MUST be the literal string “did:tdw:{SCID}:”, where the {SCID} is a placeholder that will be replaced by the calculated SCID later in the process (see step 5). This first part of the DID string is followed by a fully qualified domain name (with an optional path) that is secured by a TLS/SSL certificate and reflects the web location at which the DID Log (did.jsonl) will be published

   The DID MUST be a valid did:tdw DID as per the ABNF of a did:tdw DID defined in the Method-Specific Identifier section of this specification.

   1. Note: the SCID for a did:tdw DID is not by default in the HTTPS URL for the DID. A DID Controller MAY include the SCID in the HTTPS URL by inserting additional placeholder {SCID} strings into the domain name or path components of the method-specific identifier when creating the DID. Additional instance(s) of the SCID in the domain and/or path parts of the DID does not alter the DID-to-HTTPS transformation.

2. Generate the authorization key pair(s) Authorized keys are authorized to control (create, update, deactivate) the DID. This includes generating any other key pairs that will be placed into the initial DIDDoc for the DID.

   1. If the DID is to use pre-rotation, additional key generation will be necessary to generate the required “next” authorization keys and their corresponding pre-rotation hashes.
   2. For each authorization key pair, generate a multikey based on the key pair’s public key. The multikey representations of the public keys are placed in the updateKeys property in parameters.
   3. The public key(s) of the authorization key pair(s) MAY be used in the DIDDoc as well, but that is not required.

3. Create the initial DIDDoc for the DID The DIDDoc MUST contain the top level id property which MUST be the DID string from step 1, including the placement of the {SICD} placeholder for the SCID. Other DIDDoc verifications SHOULD be performed.

   All other absolute reference’s to the DID in the DIDDoc must use the form defined in step 1, with the identified placeholder for the SCID (e.g., did:tdw:{SCID}:example.com#key-1, did:tdw:{SCID}:example.com:dids:issuer#key-1, etc.).

   The DIDDoc can contain any other content as deemed necessary by the DID Controller.

   1. Note: The placeholder (the string {SCID}) MUST be in every place in the DIDDoc where the SCID is to be placed.

4. Generate a preliminary DID Log Entry JSON object containing the same JSON properties that will be in the published DID log entry, but with some values preset, pending calculation of the SCID and entryHash and without the proof.

   1. The value of versionId string MUST be the placeholder literal "{SCID}".
   2. The value of versionTime string MUST be a valid UTC ISO8601 date/time string, and the represented time MUST be before or equal to the current time.
   3. The value of the parameters property MUST be a JSON object defined at the discretion of the DID Controller. The properties in this nested JSON object MUST be as permitted in the DID Generation and Verification Parameters section of this specification, and all required values in the first version of the DID MUST be present. In addition, where the SCID of the DID is referenced in the parameters, the placeholder literal string {SCID} MUST be used in place of the to-be-calculated SCID.
   4. The value of the state property MUST be the initial DIDDoc as defined in the previous step 3 of this process.

5. Update the preliminary DID Log Entry to the initial DID Log Entry Use the preliminary DID log entry to perform the consecutive steps:

   1. Calculate the SCID The preliminary JSON object MUST be used to calculate the SCID for the DID as defined in the SCID Generation and Verification section of this specification.
   2. Replace the placeholder {SCID} Replace throughout the preliminary JSON object the placeholder “{SCID}” with the calculated SCID from the previous step.
   3. Calculate the Entry Hash The preliminary JSON object updated in the previous step MUST be used to calculate the Entry Hash (entryHash) for the log entry, as defined in the Entry Hash Generation and Verification section of this specification.
   4. Replace the preliminary versionId value The value of the versionId property MUST be updated with the literal string 1 (for version number 1), a literal -, followed by the entryHash value calculated in the previous step.
   5. Generate the Data Integrity proof A Data Integrity proof on the preliminary JSON object as updated in the previous step MUST be generated using an authorized key in the required updateKeys property in the parameters object.

   If the DID Controller has opted to use witnesses for the DID, the required approvals from the DID’s witnesses MUST be collected and added to the Data Integrity proof property. See the DID Witnesses section of this specification.

   6. Add the Data Integrity proof The Data Integrity proof is added to the preliminary JSON object. The resultant JSON object is the initial DID log entry for the DID.

6. Generate the first JSON Line The DID log entry MUST be updated to be a JSON Lines entry by removing extraneous white space and appending a carriage return, and the result stored as the contents of the file did.jsonl.

7. Publish the DID Log The complete DID Log file MUST be published at the appropriate Web location defined by the did:tdw DID identifier (see step 1)

   • This is a logical operation – how a deployment serves the did.jsonl content is not constrained.
   • Use the DID-to-HTTPS Transformation steps to transform the DID into the Web location of the DID Log file.

A controller MAY generate an equivalent did:web DIDDoc and publish it as defined in the Publishing a Parallel did:web DID section of this specification. The did:web DIDDoc could be used for backwards compatibility as a transition is made from did:web to did:tdw. Verifiers using the did:web lose the verifiable properties and history of the did:tdw for the convenience of the simple retrieval of the did:web DIDDoc.

§ Read (Resolve)

The following steps MUST be executed to resolve the DIDDoc for a did:tdw DID:

1. The DID-to-HTTPS Transformation steps MUST be used to transform the DID into an HTTPS URL for the DID file.
2. Perform an HTTPS GET request to the URL using an agent that can successfully negotiate a secure HTTPS connection, which enforces the security requirements as described in Security and privacy considerations.
3. When performing the DNS resolution during the HTTPS GET request, the client SHOULD utilize [RFC8484] in order to prevent tracking of the identity being resolved.
4. The DID Log file MUST be processed as described below.

To process the retrieved DID Log file, the resolver MUST carry out the following steps on each of the log entries in the order they appear in the file, applying the parameters set from the current and previous entries. As noted in the DID Log File section, log entries are each a JSON object with the following properties:

1. versionId
2. versionTime
3. parameters
4. state – the version’s DIDDoc.
5. proof – a Data Integrity proof across the log entry.

For each entry:

1. Update the currently active parameters with the parameters from the entry (if any). Continue processing using the now active set of parameters.
   • While all parameters in the first Log Entry take effect immediately, some kinds of parameters defined in later entries only take effect after that entry has been published. For example, rotating the authorized keys to update a DID takes effect only after the entry in which they are defined has been published.
2. The Data Integrity proof in the entry MUST be valid and signed by an authorized key as defined in the Authorized Keys section of this specification.
   1. If the DID Controller has opted to use witnesses and the last entry of the log is being processed, the witness Data proofs MUST be valid and MUST be signed by a threshold of witnesses. For details, see the DID Witnesses section of this specification.
3. Verify the versionId for the entry. The versionId is the concatenation of the version number, a dash (-), and the entryHash.
   1. The version number MUST be 1 for the the first log entry and MUST be incremented by one for each subsequent log entry.
   2. A dash - MUST follow the version number.
   3. The entryHash MUST follow the dash, and MUST be verified using the process defined in the Entry Hash Generation and Verification section of this specification.
4. The versionTime MUST be a valid UTC ISO8601 date/time string. The versionTime for each log entry MUST be greater than the previous entry’s time. The versionTime of the last entry MUST be earlier than the current time.
5. Parse and apply the did:tdw DID Method configuration parameters. Note that in versions after the first, some parameters apply to immediately and impact the process of the current DID version, while others, such as updateKeys and witnesses apply after the current version has been published. The parameters MUST adhere to the did:tdw DID Method Parameters section of this specification.
6. When processing the first DID log entry, verify the SCID (defined in the parameters) according to the SCID Generation and Verification section of this specification.
7. Get the value of the log entry property state, which is the DIDDoc for the version.
8. If Key Pre-Rotation is being used, the hash of all updateKeys entries in the parameters property MUST match a hash in the active array of nextKeyHashes parameter, as defined in the Pre-Rotation[Key Pre-Rotation Hash Generation and Verification](#pre-rotation-key-hash-generation-and-verification) section of this specification.
9. If any verifications fail, discard the DID as invalid with an error message.
10. As each log entry is processed and verified, collect the following information about each version:
    1. The DIDDoc.
    2. The versionId of the DIDDoc.
    3. The UTC versionTimeof the DIDDoc.
    4. The latest list of active multikey formatted public keys authorized to update the DID, from the updateKeys lists in the parameters.
    5. If pre-rotation is being used, the hashes of authorized DIDs that may be used in later updateKeys lists. The pre-rotation hashes are in the nextKeyHashes list in the parameters.
    6. All other did:tdw processing configuration settings as defined by in the parameters object.

On completing the processing and successful verification of all entries in the DID Log, respond to the DID resolution request, including the application of DID query parameters such as ?versionId= and ?versionTime= with the appropriate DIDDoc version and content.

The following error codes and descriptions may be returned when resolving a DID.

• Code 404: The did:tdw DID Log file did.jsonl was not found.

§ Reading did:tdw DID URLs

A did:tdw resolver MAY implement the resolution of the /whois and a DID URL Path using the whois LinkedVP Service and DID URL Path Resolution Service as defined in this specification by processing the DID Log and then dereferencing the DID URL based on the contents of the DIDDoc. The client of a resolver that does not implement those capabilities must use the resolver to resolve the appropriate DIDDoc, and then process the resulting DID URLs themselves. Since the default DID-to-HTTPS URL transformation is trivial, did:tdw DID Controllers are strongly encouraged to use the default behavior for DID URL Path resolution.

§ Update (Rotate)

To update a DID, a new, verifiable DID Log Entry must be generated, witnessed (if necessary), appended to the existing DID Log (did.jsonl), and published to the web location defined by the DID. The process to generate a verifiable DID Log Entry follows a similar process to the Create process, as follows:

1. Make the desired changes to the DIDDoc. While the contents of a new DIDDoc version are (mostly) up to the DID controller, there are some limitations:
   1. If the DID is configured to support portability, the root id property in the DIDDoc MAY be changed when the DID Controller wants to (or is forced to) publish the DID at a different Internet location and wants to retain the SCID and history of the DID. For details, see the DID Portability section of this specification.
2. Define the parameters JSON object to include the properties that affect the evolution of the DID. The parameters MUST be from those listed in the did:tdw DID Method Parameters section of this specification. Any parameters defined in the JSON object override the previously active value, while any parameters not included imply the existing values remain in effect. If no changes to the parameters are needed, an empty JSON object {} MUST be used.
   • While all parameters in the first Log Entry take effect immediately, some types of parameters defined in later entries only take effect after the entry has been published. For example, rotating the keys authorized to update a DID or changing the witnesses for a DID take effect only after the entry in which they are defined has been published.
3. Generate a preliminary DID log entry JSON object containing the following properties:
   1. The value of versionId MUST be the value of versionId from the previous DID log entry.
   2. The versionTime value MUST be a string that is an ISO8601 format UTC timestamp. The time MUST be greater than the time of the previous log entry, and MUST be the time the DID will be retrieved by a witness or resolver, or before.
   3. The parameters passed in as a JSON object.
   4. Set the state JSON object to be the new version of the DIDDoc.
4. Calculate the new versionId of the new DID Log Entry, including incrementing the version number integer and using the process described in the Entry Hash Generation and Verification section of this specification.
5. Replace the value of the versionId property in the preliminary DID Log with the value produced in the previous step.
6. Generate a Data Integrity proof on the DID log entry using an authorized key, as defined in the Authorized Keys section of this specification.
7. If the DID Controller has opted to use witnesses for the DID, collect the required approvals from the DID’s witnesses, adding their proofs to the data integrity proof. See the DID Witnesses section of this specification.
8. The proof JSON object MUST be added as the value of the proof property in the log entry.
9. The entry MUST be made a JSON Line by removing extra whitespace, adding a \n to the entry.
10. The new log entry MUST be appended to the existing contents of the DID Log file did.jsonl.
11. The updated DID Log file MUST be published the appropriate location defined by the did:tdw identifier.
    • This is a logical operation – how a deployment serves the did.jsonl content is not constrained.

A controller MAY generate an equivalent, updated did:web DIDDoc and publish it as defined in the Publishing a Parallel did:web DID section of this specification.

§ Deactivate (Revoke)

To deactivate the DID, the DID Controller MUST add to the DID log entry parameters the property name and value "deactivated": true. A DID SHOULD update the DIDDoc and parameters object to further indicate the deactivation of the DID, such as including an empty updateKeys list ("updateKeys": []) in the parameters, preventing further versions of the DID.

A resolver encountering in the DID log entry parameters the property key:value pair "deactivated": true MUST return in the DIDDoc Metadata the property key:value "deactivated": true, as per the [[spec:DID-RESOLUTION]] specification.

§ DID Method Processes

The DID Method Operations reference several processes that are executed during DIDDoc generation and DID resolution verification. Each of those processes is specified in the following sections.

§ did:tdw DID Method Parameters

Entries in the did:tdw DID Log contain the JSON object parameters that define the DID processing parameters being used by the DID when publishing the current and subsequent DID log. A DID Resolver MUST use the same parameters when processing the DID Log to resolve the DID. The parameters object MUST only include properties defined in this specification.

{
    "prerotation": true,
    "portable": false,
    "updateKeys": [
      "z82LkqR25TU88tztBEiFydNf4fUPn8oWBANckcmuqgonz9TAbK9a7WGQ5dm7jyqyRMpaRAe"
    ],
    "nextKeyHashes": [
      "enkkrohe5ccxyc7zghic6qux5inyzthg2tqka4b57kvtorysc3aa"
    ],
    "method": "did:tdw:0.3",
    "scid": "{SCID}"
}

The allowed parameter properties and (where applicable) enumerated values for those properties are defined below.

• method: Defines the did:tdw specification version to use when processing a given DID’s log file. As new versions of this specifications are defined, additional parameters and enumerated values will be associated with the method values. This allows a long lasting DID to evolve the settings being used by the DID over time, such as changing the hash algorithms permitted, or allowing other Data Integrity cryptosuites.
  • This property MUST appear in the first DID log entry.
  • This property MAY appear in later DID log entries to indicate that the processing rules for that and later log entries have been changed to a different specification version.
  • Acceptable values for this specification are:
    • did:tdw:0.4: Requires that the rules defined in this version of the specification be used in processing the log. Implied by the value are the following:
      • The permitted hash algorithms used by the DID Controller MUST be SHA-256 as defined in [RFC6234].
      • The permitted Data Integrity cryptosuites used by the DID Controller MUST be eddsa-jcs-2022 as referenced in eddsa-jcs-2022.
• scid: The value of the SCID for this DID.
  • This property MUST appear in the first DID log entry.
• updateKeys: An array of multikey formatted public keys associated with the private keys that are authorized to sign the log entries that update the DID from one version to the next. An instance of the list in an entry replaces the previously active list. If an entry does not have the updateKeys property, the currently active list continues to apply. See the Authorized Keys section of this specification for additional details.
  • This property MUST appear in the first DID log entry and MAY appear in subsequent entries, at the discretion of the DID Controller.
  • A key from the updateKeys array in the first DID log entry MUST be used to authorize the initial log entry. In all other DID log entries, an updateKeys property becomes active after the publication of its entry – meaning its log entry MUST be signed by a key the most recent updateKeys list from a prior DID log entry.
• portable: A boolean (true / false) indicating if the DID is portable and thus can be renamed to change the Web location of the DID.
  • The value can ONLY be set to true in the first log entry, the initial version of the DID.
  • If not explicitly set in the first log entry, it is set to false.
  • Once the value has been set to false, it cannot be set back to true.
  • See the section of this specification on DID Portability for more details about renaming a did:tdw DID.
• prerotation: A boolean value indicating that subsequent authentication keys added to the DIDDoc (after this version) MUST have their hash included in a nextKeyHashes parameter property.
  • The value is initialized to false until the property is included in a DID log entry.
  • Once the value is set to true in a DID log entry it MUST NOT be set to false in a subsequent entry.
• nextKeyHashes: An array of strings that are hashes of multikey formatted public keys that MAY be added to the updateKeys list in the log entry of a future version of the DID.
  • The process for generating the hashes and additional details for using pre-rotation are defined in the Pre-Rotation Key Hash Generation and Verification section of this specification.
  • If the parameter prerotation has been set to true, all multikey formatted public keys added in a new updateKeys list MUST have their hashes listed in the currently active nextKeyHashes list.
  • A DID Controller MAY put extra strings in the nextKeyHashes array that are not subsequently used in an updateKeys entry.
  • When prerotation is active and the updateKeys parameter is included in a parameters property, a nextKeyHashes property with a new set of hashes MUST be included in the same parameters property. Any unused hashes in the prior nextKeyHashes are ignored.
• witness: A JSON object containing the parameters for declaring the witnesses for the DID, and the parameters for the process of updating a DID via a collaboration with witnesses prior to publication. For details of this data and its usage in the approvals process, see the DID Witnesses section of this specification.
  • A witness property in the first DID log entry is used to define the witnesses and necessary threshold for that initial log entry. In all other DID log entries, a witness property becomes active after the publication of its entry – meaning its log entry MUST be witnessed by the most recent witnesses from a prior DID log entry.
• deactivated: A JSON boolean that SHOULD be set to true when the DID is to be deactivated. See the deactivate (revoke) section of this specification for more details.
• ttl: A number, the number of seconds that a cache entry for a resolved did:tdw DID SHOULD last, as recommended by the DID Controller. A resolver can use this value in deciding whether to retrieve a new version of the DID’s did.jsonl file. If not specified, resolvers MAY set a default based on the business needs of the resolver clients.
  • Caching a did:tdw can be valuable in places where the business rules require resolving a number of DID URLs for the same DID. For example, a client might want call the resolver to the current DIDDoc, and then make repeated calls to get all of the previous versions of the DIDDoc. By caching the DIDDoc state, the resolver would not have to retrieve and process the DID Log on each call.
  • A Web Server handling one or more did.jsonl files MAY be configured to use a comparable HTTP TTL per [RFC9111].

§ SCID Generation and Verification

The self-certifying identifier or SCID is a required parameter in the first DID log entry and is the hash of the DID’s inception event.

§ Generate SCID

To generate the SCID for a did:tdw DID, the DID Controller MUST execute the following function:

base58btc(multihash(JCS(preliminary log entry with placeholders), <hash algorithm>))

Where:

1. The preliminary [[ref: log entry]] with placeholders consists of the following pre-publication JSON object of what will become the first log entry. The placeholder is the literal string “{SCID}”.

   • The versionId entry, which MUST be {SCID}.
   • The versionTime entry, which MUST be a string that is the current time in UTC ISO8601 format, e.g., "2024-04-05T07:32:58Z"
   • The complete parameters for the initial log entry as defined by the DID Controller, with the placeholder wherever the SCID will eventually be placed.
   • The state JSON object with the value being the initial DIDDoc with placeholders (the literal string “{SCID}”) wherever the SCID will eventually be placed in the DIDDoc.

2. JCS is an implementation of the JSON Canonicalization Scheme [RFC8785]. It outputs a canonicalized representation of its JSON input.

3. multihash is an implementation of the multihash specification. Its output is a hash of the input using the associated <hash algorithm>, prefixed with a hash algorithm identifier and the hash size.

4. <hash algorithm> is the hash algorithm used by the DID Controller. The hash algorithm MUST be one listed in the parameters defined by the version of the did:tdw specification being used by the DID Controller.

5. base58btc is an implementation of the base58btc function. Its output is the base58 encoded string of its input.

§ Verify SCID

To verify the SCID of a did:tdw DID being resolved, the resolver MUST execute the following process:

1. Extract the first DID log entry and use it for the rest of the steps in this process.
2. Extract the scid property value from the parameters in the DID log entry.
3. Determine the hash algorithm used by the DID Controller from the multihash scid value.
   • The hash algorithm MUST be one listed in the parameters defined by the version of the did:tdw specification being used by the DID Controller based on the method parameters property.
4. Remove the data integrity proof property from the DID log entry.
5. Replace the versionId property value with the literal "{SCID}".
6. Treat the resulting log entry as a string and do a text replacement of the scid value from Step 2 with the literal string {SCID}.
7. Use the result and the hash algorithm (from Step 3) as input to the function defined in the Generate SCID section (above).
8. The output string MUST match the scid extracted in Step 2. If not, terminate the resolution process with an error.

§ Entry Hash Generation and Verification

The entryHash follows the version number and dash character - in the versionId property in each DID log entry. Each entryHash is calculated across its log entry, excluding the Data Integrity proof. The versionId used in the input to the hash is a predecessor value to the current log entry, ensuring that the entries are cryptographically “chained” together in a microledger. For the first log entry, the predecessor versionId is the SCID (itself a hash), while for all other entries it is the versionId property from the previous log entry.

§ Generate Entry Hash

To generate the required hash for a did:tdw log entry, the DID Controller MUST execute the process base58btc(multihash(JCS(entry), <hash algorithm>)) given a preliminary log entry as the string entry, where:

1. JCS is an implementation of the JSON Canonicalization Scheme ([RFC8785]). Its output is a canonicalized representation of its input.
2. multihash is an implementation of the multihash specification. Its output is a hash of the input using the associated <hash algorithm>, prefixed with a hash algorithm identifier and the hash size.
3. <hash algorithm> is the hash algorithm used by the DID Controller. The hash algorithm MUST be one listed in the parameters defined by the version of the did:tdw specification being used by the DID Controller.
4. base58btc is an implementation of the base58btc function. Its output is the base58 encoded string of its input.

The following is an example of a preliminary log entry that is processed to produce an entry hash. As this is a first entry in a DID Log, the input versionId is the SCID of the DID.

{"versionId": "QmfGEUAcMpzo25kF2Rhn8L5FAXysfGnkzjwdKoNPi615XQ", "versionTime": "2024-09-26T23:22:26Z", "parameters": {"prerotation": true, "updateKeys": ["z6MkhbNRN2Q9BaY9TvTc2K3izkhfVwgHiXL7VWZnTqxEvc3R"], "nextKeyHashes": ["QmXC3vvStVVzCBHRHGUsksGxn6BNmkdETXJGDBXwNSTL33"], "method": "did:tdw:0.4", "scid": "QmfGEUAcMpzo25kF2Rhn8L5FAXysfGnkzjwdKoNPi615XQ"}, "state": {"@context": ["https://www.w3.org/ns/did/v1"], "id": "did:tdw:QmfGEUAcMpzo25kF2Rhn8L5FAXysfGnkzjwdKoNPi615XQ:domain.example"}}

Resulting entryHash: QmQq6Kg4ZZ1p49znzxnWmes4LkkWgMWLrnrfPre8UD56bz

§ Verify The Entry Hash

To verify the entryHash for a given did:tdw DID log entry, a DID Resolver MUST execute the following process:

1. Extract the versionId in the DID log entry, and remove from it the version number and dash prefix, leaving the log entry entryHash value.
2. Determine the hash algorithm used by the DID Controller from the multihash entryHash value.
   • The hash algorithm MUST be one listed in the parameters defined by the version of the did:tdw specification being used by the DID Controller based on the method parameters property set in the current or most recent prior log entry.
3. Remove the Data Integrity proof from the log entry.
4. Set the versionId in the entry object to be the versionId from the previous log entry. If this is the first entry in the log, set the value to <scid>, the value of the SCID of the DID.
5. Calculate the hash string as base58btc(multihash(JCS(entry), <hash algorithm>)), where:
   1. entry is the data from the previous step.
   2. JCS is an implementation of the JSON Canonicalization Scheme ([RFC8785]). Its output is a canonicalized representation of its input.
   3. multihash is an implementation of the multihash specification. Its output is a hash of the input using the associated <hash algorithm>, prefixed with a hash algorithm identifier and the hash size.
   4. <hash algorithm> is the hash algorithm from Step 2.
   5. base58btc is an implementation of the base58btc function. Its output is the base58 encoded string of its input.
6. Verify that the calculated value matches the extracted entryHash value from Step 1. If not, terminate the resolution process with an error.

§ Authorized Keys

Each entry in the DID Log MUST include a Data Integrity proof property signed by a key authorized to control (create, update, deactivate) the DID. The authorized verification keys for did:tdw are the multikey-formatted public keys in the active updateKeys list from the parameters property of the log entries. Any of the authorized verification keys may be referenced in the Data Integrity proof.

For the first log entry the active updateKeys list is the one in that first log entry. For all subsequent entries, the active list is the most recent updateKeys before the log entry to be verified. Thus, the general case is that each log entry is signed by the keys from the previous log entry. Once a log entry containing an updateKeys list is published, that updateKeys becomes the active list, and previous updateKeys are ignored.

A resolver of the DID MUST verify the signature and the key used for signing each DID Log entry MUST be one from the list of active updateKeys. If not, terminate the resolution process with an error.

The did:tdw Implementation Guide contains further discussion on the management of keys authorized to update the DID.

§ DID Portability

As noted in the Update (rotate) section of the specification, a did:tdw DID can be renamed by changing the id DID string in the DIDDoc to one that resolves to a different HTTPS URL if the following conditions are met.

• The DID Log of the renamed DID MUST contain all of the log from the creation of the DID.
• The log entry in which the DID is renamed MUST be a valid DID entry building on the prior DID log entries, per this specification.
• The parameter portable MUST be set to true, as defined in the DID Method Parameters section.
• The SCID MUST be the same in the original and renamed DID.
• The DIDDoc MUST contain the prior DID string as an alsoKnownAs entry.

§ Pre-Rotation Key Hash Generation and Verification

Pre-rotation requires a DID Controller to commit to the authorization keys that will later be used (“rotated to”) for updating the DIDDoc. The purpose of committing to future keys is that if the currently authorized keys are compromised by an attacker, the attacker should not be able to take control of the DID by using the compromised keys to rotate to new keys the attacker controls. Assuming the attacker has not also compromised the committed key pairs, they cannot rotate the authorization keys without detection. See the non-normative section about Pre-Rotation[Using Pre-Rotation Keys](#using-pre-rotation-keys) in the Implementer’s Guide for additional guidance.

As described in the parameters section of this specification, a DID Controller MAY define that prerotation is active for the DID (value true). When pre-rotation is active, all verification multikeys in the updateKeys parameters property in other than the initial version of the DIDDoc MUST have their hash in the currently active nextKeyHashes` array from a previous DID log entry. If not, terminate the resolution process with an error.

To create a hash to be included in the nextKeyHashes array, the DID MUST execute the following process for each possible future authorization key.

1. Generate a new key pair.
2. Generate a multikeys representation of the public key of the new key pair.
3. Calculate the hash string as base58btc(multihash(multikey)), where:
   1. multikey is the multikey representation of the public key from Step 2.
   2. multihash is an implementation of the multihash specification. Its output is a hash of the input using the associated <hash algorithm>, prefixed with a hash algorithm identifier and the hash size.
   3. <hash algorithm> is the hash algorithm used by the DID Controller. The hash algorithm MUST be one listed in the parameters defined by the version of the did:tdw specification being used by the DID Controller.
   4. base58btc is an implementation of the base58btc function. Its output is the base58 encoded string of its input.
4. Insert the calculated hash into the nextKeyHashes array being built up within the parameters property.
5. The generated key pair SHOULD be safely stored so that it can be used in a later DID version to become a DID authorization key. At that time, the multikey representation of the public key will be inserted into the updateKeys property in the parameters. After that log entry is published, the private key can be used to sign DID update authorizations proofs.

A DID Controller MAY add include extra entries (for keys or just random strings) in a nextKeyHashes array.

When processing other than the first DID log entry where the prerotation parameter is active, a did:tdw resolver MUST:

1. For each multikey in the updateKeys property in the parameters of the log entry, calculate the hash and hash algorithm for the mulithash multikey.
2. The hash algorithm MUST be one listed in the parameters defined by the version of the did:tdw specification being used by the DID Controller.
3. The resultant hash MUST be in the most recently set nextKeyHashes prior to the log entry being processed. If not, terminate the resolution process with an error.
4. A new nextKeyHashes list MUST be in the parameters of the log currently being processed. If not, terminate the resolution process with an error.

§ DID Witnesses

The witness process for a DID provides a way for other collaborators to work with the DID Controller to “witness” the publication of a new version of the DID. Including witnesses can prevent malicious updates to the DID by both the DID Controller and external parties. This specification defines the mechanism for using witnesses but leaves the governance and policy questions about when and how to use the mechanism to implementers.

Witnesses can prevent a DID Controller from updating/removing DID versions of a DID without detection. Witnesses are also a further mitigation against malicious actors compromising both a DID Controller's authorization key(s) to update the DID, and the DID Controller's web site where the DID log is published. With both compromises, a malicious actor could take control over the DID by rewriting the DID Log using the keys they have comprised. By adding witnesses that monitor and approve each version update, a malicious actor cannot rewrite the previous history without also compromising a sufficient number of witnesses.

An overview of the witness mechanism is as follows:

• The DID Controller specifies (in the parameters of a log) a list of witnesses, DIDs that together with the DID will contribute to “approving” all subsequent versions of the DID.
  • Ideally, the DID Controller does that in the inception event for the DID.
  • Over time, the list of witnesses may evolve, with each change being approved by the declared list of witnesses from before such a change.
• The DID Controller prepares a DID Log Entry and shares it with the witnesses.
  • The specification leaves to implementers how the log entry data is provided to the witnesses.
• Each witness verifies the DID Log Entry, as defined by this specification. If not, the witnesses MUST NOT approve the log entry.
  • The witnesses *MUST have their own copy of the current DID Log.
• Each witness determines (based on the governance of the ecosystem) if they approve of the DID version update.
  • This specification has no opinion on what “approve” means for any deployment of did:tdw. That is up to the ecosystem in which the DID and witnesses are participating.
• If the verification is successful and the approval granted, the witness sends a Data Integrity proof across the DID log entry to the DID Controller, similar to that generated by the DID Controller, but signed by the witness's key.
• When a weighted threshold of proofs are received, the DID Controller inserts the witnesses's proofs into the proof array in the DID Log Entry and publishes the updated version of the DID.
  • In publishing a new version of the DID Log, the DID SHOULD remove the witness Data Integrity proofs from earlier entries to reduce the size of the log. Only the set of approval proofs on the last log entry are needed because of the chaining of the proofs via the use of the entryHash challenge.
  • Removing the prior entry witness proofs does not affect the verifiability of the DID because the entryHash calculation does not include the proof property.
  • The specification leaves to implementers how the proofs are conveyed to the DID Controller.

As with the handling of the updateKeys, DID Log Entry changes require proofs from the the witnesses active prior to the publication of a new version. If a new version changes the list of witnesses, that change must be approved by the prior witnesses. For the first entry in the DID Log, the witnesses listed in that entry must approve the version, since there are no “prior” witnesses.

The data model for the witness parameter is as follows. The threshold design borrows from the verifiable conditions specification.

"witness" : {
  "threshold": n,
  "selfWeight": n,
  "witnesses" : [
      {
         "id": "<DID of witness>",
         "weight": n
      }
   ]
}

where:

• threshold: an integer that must be attained or surpassed by the sum of the witnesses and DID Controller's weights for a DID log entry to be considered approved.
• selfWeight: an integer that is the weight given the DID Controller's verified proof, in determining if the threshold has been surpassed.
• witnesses: an array of witnesses, each including the required fields:
  • id: the DID of the witness
  • weight: the weight of this witness's approval

The use of the threshold and weighted approvals (versus needing approvals from all witnesses) is to prevent faulty witnesses from blocking the publishing of a new version of the DID. To determine if the threshold has been passed, sum the weight integer of the received approvals, plus the selfWeight of the DID, and if it equal to or more than threshold, the update can be published. The calculation MUST also be executed by resolvers processing a DID Log. For example, if there are three witnesses, each with a weight of 1, the DID Controller with a selfWeight of 2, and a threshold of 4, the threshold will be met by two witnesses approving the change, plus the DID.

If you want to learn about the practical application of witnesses, see the Implementer’s Guide section on Witnesses on the did:tdw information site for more discussion on the witness capability and using it in production scenarios.

§ Publishing a Parallel did:web DID

Each time a did:tdw version is created, the DID Controller MAY generate a corresponding did:web to publish along with the did:tdw. To do so, the DID Controller MUST:

1. Start with the resolved version of the DIDDoc from did:tdw.
2. Execute a text replacement across the DIDDoc of did:tdw:<SCID>: to did:web:, where <scid> is the actual did:tdw SCID.
3. Add to the DIDDoc alsoKnownAs array, the full did:tdw DID. If the alsoKnownAs array does not exist in the DIDDoc, it MUST be added.
4. Publish the resulting DIDDoc as the file did.json at the web location determined by the specified did:web DID-to-HTTPS transformation.

The benefit of doing this is that resolvers that have not been updated to support did:tdw can continue to resolve the DID Controller's DIDs. did:web resolvers that are aware of did:tdw features can use that knowledge, and the existence of the alsoKnownAs did:tdw data in the DIDDoc to get the verifiable history of the DID.

The risk of publishing the did:web in parallel with the did:tdw is that the added security and convenience of using did:tdw are lost.

§ DID URL Resolution

The did:tdw DID Method embraces the power and usefulness of DID URLs, along with the semantic simplicity of using them with a web-based DID method. Specifically, a did:tdw implementation MUST:

• Resolve the /whois DID URL path using a [[spec:LINKED-VP]] service, whether or not it exists in the did:tdw DIDDoc, returning a Verifiable Presentation, if published by the DID Controller, found at the same path as the did.jsonl file (excluding the .well-known folder, if present), using the /whois.vp filename component, and the `application/vp’ media type, as per the IANA Verifiable Presentation Assignment.
  • For example, did:tdw:{SCID}:example.com/whois returns the verifiable presentation from https://example.com/whois.vp.
• Resolve any did:tdw DID URL using a [DID-CORE] relativeRef DID parameter, whether or not a supporting service exists in the did:tdw DIDDoc, returning the file found at web location corresponding to the DID-to-HTTPS transformation (excluding the .well-known folder, if present).
  • For example, resolving did:{SCID}:tdw:example.com/governance/issuers.json returns the file https://example.com/governance/issuer.json

In both cases, a DID Controller MAY define services in the DIDDoc that override the default services that MUST be resolved by the did:tdw DID Method.

The sections below formalize the services that exist by default in did:tdw and how a DID Controller can override them.

§ whois LinkedVP Service

The #whois service enables those that receive a did:tdw DID to retrieve and a Verifiable Presentation (and embedded Verifiable) the DID Controller has decided to publish about itself. The intention is that anyone wanting to learn more about a particular did:tdw DID can resolve the <did>/whois DID URL to retrieve a Verifiable published by the DID Controller that contains Verifiable Credentials with the DID as the subject. The DID Controller includes in the Verifiable Presentation any Verifiable Credentials that it thinks might be helpful for resolvers in making a trust decision about the DID.

It is up to the DID Controller to decide to publish a whois verifiable presentation, and which verifiable credentials to put into the verifiable presentation. It is up to a DID resolver to decide what attestations from third parties are useful in making a trust decision about the DID.

did:tdw DIDs automatically supports a /whois service endpoint with the following definition based on the [[spec:LINKED-VP]] specification, with the serviceEndpoint defining a similar did:tdw DID-to-HTTPS DID Log transformation with did.jsonl changed to whois.vp. Differing from the DID-to-HTTPS transformation is that the .well-known/ component of the did.jsonl transformation is dropped from the whois.vp resolution.

{
   "@context": "https://identity.foundation/linked-vp/contexts/v1",
   "id": "#whois",
   "type": "LinkedVerifiablePresentation",
   "serviceEndpoint": "<did-to-https-translation>/whois.vp"
}

The returned whois.vp MUST contain a W3C VCDM verifiable signed by the DID and containing verifiable credentials that MUST have the DID as the credentialSubject.

A DID Controller MAY explicitly add to their DIDDoc a did:tdw service with the "id": "#whois". Such an entry MUST override the implicit service above. If the DID Controller wants to publish the whois verifiable presentation in a different format than the W3C format, they MUST explicitly add to their DIDDoc a service with the "id": "#whois" to specify the name and implied format of the verifiable.

To resolve the DID URL <did:tdw DID>/whois, the resolver MUST:

1. Resolve the given did:tdw DID by retrieving, processing, and verifying the DID log for the did:tdw as defined in this specification.
2. Find the DIDDoc service with the id #whois, if any, or use the implicit service (above).
3. Resolve the serviceEndpoint URL, if possible, and return the document found.
   1. If the serviceEndpoint URL can’t be resolved by the resolver (such as if the URL protocol is not supported by the resolver), the error Error XXX: YYY MUST be returned.
   2. If the file at the defined serviceEndpoint is not found, Error 404: Not Found MUST be returned.

§ DID URL Path Resolution Service

The automatic resolution of did:tdw DID URL paths follows the [DID-CORE] relativeRef specification, as follows:

• a DID path, such as example 2 in section 3.2 DID URL Syntax gives the example: did:example:123456/resume.pdf
• In turn, that can be treated as the following, as shown in example 8 in the same section: did:example:123456?service=files&relativeRef=/resume.pdf
• The #files service defined below then defines the serviceEndpoint for the relativeRef.
  • For did:tdw, that service is implicitly defined, with the serviceEndpoint matching the did:tdw DID-to-HTTPS transformation and did.jsonl replaced by the DID URL Path. If .well-known/ is part of the HTTPS URL, it is removed from the URL before resolving the URL.

Thus, the implicit service for DID did:tdw:example.com:dids:<scid> is:

{
   "id": "#files",
   "type": "relativeRef",
   "serviceEndpoint": "https://example.com/dids/<scid>"
}

A DID Controller MAY explicitly add to their DIDDoc a service with the "id": "#files". Such an entry MUST override the implicit service defined above.

To resolve the DID URL <did:tdw DID>/path/to/file, the resolver MUST:

1. Resolve the given did:tdw DID by retrieving, processing, and verifying the DID log for the did:tdw as defined in this specification.
2. Find the DIDDoc service with the id #files, if any, or use the implicit service (above).
3. Resolve the serviceEndpoint URL with the DID URL Path appended, if possible, and return the document found at that location.
   1. If the serviceEndpoint URL can’t be resolved by the resolver (such as if the URL protocol is not supported by the resolver), the error Error XXX: YYY MUST be returned.
   2. If the file at the path appended to the defined serviceEndpoint is not found, the error Error 404: Not Found MUST be returned.

§ Security and Privacy Considerations

§ DNS Considerations

§ DNS Security Considerations

Implementers must secure DNS resolution to protect against attacks like Man in the Middle, following the detailed guidance in the did:web specification. The use of DNSSEC [RFC4033], [RFC4034], [RFC4035] is essential to prevent spoofing and ensure authenticity of DNS records.

§ DNS Privacy Considerations

Resolving a did:tdw identifier can expose users to tracking by DNS providers and web servers. To mitigate this risk, it’s recommended to use privacy-enhancing technologies such as VPNs, TOR, or trusted universal resolver services, in line with strategies outlined in the did:web specification including emerging RFCs such as Oblivious DNS over HTTPS for DNS privacy.

§ In-transit Security

For in-transit security, the guidance provided in the did:web specification regarding the encryption of traffic between the server and client should be followed.

§ International Domain Names

[DID-CORE] identifier syntax does not allow Unicode in method name nor method specific identifiers.

Implementers should be cautious when implementing support for DID URLs that rely on domain names or path components that contain Unicode characters.

See also:

• UTS-46
• [RFC5895]

§ Definitions

base58btc

Applies [[spec:draft-msporny-base58-03]] to convert data to a base58 encoding. Used in did:tdw for encoding hashes for SCIDs and entry hashes.

Data Integrity

W3C Data Integrity is a specification of mechanisms for ensuring the authenticity and integrity of structured digital documents using cryptography, such as digital signatures and other digital mathematical proofs.

Decentralized Identifier

Decentralized Identifiers (DIDs) [DID-CORE] are a type of identifier that enable verifiable, decentralized digital identities. A DID refers to any subject (e.g., a person, organization, thing, data model, abstract entity, etc.) as determined by the controller of the DID.

DID Controller

The entity that controls (create, updates, deletes) a given DID, as defined in the [DID-CORE].

DIDDoc

A DID Document as defined by the [DID-CORE] – the document returned when a DID is resolved.

did:key

DID:key…

DID Log

A DID Log is a list of Entries, with an entry added for each update of the DID, including new versions of the DIDDoc or changed information necessary to generate or validate the DID.

DID Log Entry

A DID Log Entry is a JSON object that defines the authorized transformation of a DIDDoc from one version to the next. The initial entry establishes the DID and version 1 of the DIDDoc. All entries are stored in the DID Log.

DID Method

DID methods are the mechanism by which a particular type of DID and its associated DID document are created, resolved, updated, and deactivated. DID methods are defined using separate DID method specifications. This document is the DID Method Specification for DID:tdw.

DID Portability

did:tdw portability is the capability to change the DID string for the DID while retaining the SCID and the history of the DID. This is useful when forced to change (such as when an organization is acquired by another, resulting in a change of domain names) and when changing DID hosting service providers.

did:web

did:web as described in the W3C specification is a DID method that leverages the Domain Name System (DNS) to perform the DID operations. It is valued for its simplicity and ease of deployment compared to DID methods that are based on distributed ledgers or blockchain technology, but also comes with increased challenges related to trust and security. did:web provides a starting point for did:tdw, which complements did:web with specific features to address the challenges while still providing ease of deployment.

eddsa-jcs-2022

A cryptosuite defined for producing a Data Integrity proof for an unsecured input data document and verifying the Data Integrity proof of the secured document. More information on further operations and applications of the cryptosuite can be found in the specification, here: eddsa-jcs-2022

Entry Hash

A DID:tdw entry hash is a hash generated using a formally defined process over the input data to a log entry, excluding the Data Integrity proof. The input data includes content from the predecessor to the version of the DID, ensuring that all the versions are “chained” together in a sort of microledger. The generated entry hash is subsequently included in the versionId of the log entry and MUST be verified by a resolver.

ISO8601

A date/time expressed using the ISO8601 Standard.

JSON Canonicalization Scheme

[RFC8785] defines a method for canonicalizing a JSON structure such that is suitable for verifiable hashing or signing.

JSON Lines

A file of JSON Lines, as described on the site https://jsonlines.org/. In short, JSONL is lines of JSON with whitespace removed and separated by a newline that is convenient for handling streaming JSON data or log files.

Pre-Rotation

A technique for a controller of a cryptographic key to commit to the public key it will rotate to next, without exposing that actual public key. It protects from an attacker that gains knowledge of the current private key from being able to rotate to a new key known only to the attacker.

Linked-VP

A [DID-CORE] service entry that specifies where a verifiable about the DID subject can be found. The Decentralized Identity Foundation hosts the Linked VP Specification.

multihash

Per the [MULTIFORMATS], multihash is a specification for differentiating instances of hashes. Software creating a hash prefixes (according to the specification) data to the hash indicating the algorithm used and the length of the hash, so that software receiving the hash knows how to verify it. Although multihash supports many hash algorithms, for interoperability, DID Controllers MUST only use the hash algorithms defined in this specification as permitted.

multi-sig

A cryptographic signature that to be valid MUST contain a defined threshold (for example, 4 of 7) individual signatures to be considered valid. The multi-signature key reference points to a verification method that defines what keys may contribute to the signature, and under what conditions the multi-signature is considered valid.

parameters

did:tdw parameters are a defined set of configurations that control how the issuer has generated the DID, and how the resolver must process the DID Log entries. The use of parameters allows for the controlled evolution of did:tdw log handling, such as evolving the set of permitted hash algorithms or cryptosuites. This enables support for very long lasting identifiers – decades.

self-certifying identifier

An object identifier derived from initial data such that an attacker could not create a new object with the same identifier. The input for a DID:tdw SCID is the initial DIDDoc with the placeholder {SCID} wherever the SCID is to be placed.

Verifiable Credential

A verifiable credential can represent all of the same information that a physical credential represents, adding technologies such as digital signatures, to make the credentials more tamper-evident and so more trustworthy than their physical counterparts. The Verifiable Credential Data Model is a W3C Standard.

Verifiable Presentation

A verifiable presentation data model is part W3C’s Verifiable Credential Data Model that contains a set of verifiable credentials about a credentialSubject, and a signature across the verifiable credentials generated by that subject. In this specification, the use case of primary interest is where the DID is the credentialSubject and the DID signs the verifiable presentation.

witness

Witnesses are participants in the process of creating and verifying a version of a DID:tdw DIDDoc. Notably, a witness receives from the DID Controller a DID entry ready for publication, verifies it according to this specification, and approves it according to its ecosystem governance (whatever that might be). If the verification and approval process results are positive, witnesses returns to the DID Controller a Data Integrity proof attesting to that positive result.

W3C VCDM

A Verifiable Credential that uses the Data Model defined by the W3C [[spec: W3C-VC]] specification.

§ References

DID-CORE

Decentralized Identifiers (DIDs) v1.0. Manu Sporny; Amy Guy; Markus Sabadello; Drummond Reed; 2022-07-19. Status: REC.

MULTIFORMATS

Multiformats. Juan Benet; Manu Sporny; 2024-02-21. Status: Internet Draft.

RFC1035

Domain names - implementation and specification. P. Mockapetris; 1987-11. Status: Internet Standard.

RFC1123

Requirements for Internet Hosts - Application and Support. R. Braden, Ed.; 1989-10. Status: Internet Standard.

RFC2181

Clarifications to the DNS Specification. R. Elz; R. Bush; 1997-07. Status: Proposed Standard.

RFC2234

Augmented BNF for Syntax Specifications: ABNF. D. Crocker, Ed.; P. Overell; 1997-11. Status: Proposed Standard.

RFC3912

WHOIS Protocol Specification. L. Daigle; 2004-09. Status: Draft Standard.

RFC3986

Uniform Resource Identifier (URI): Generic Syntax. T. Berners-Lee; R. Fielding; L. Masinter; 2005-01. Status: Internet Standard.

RFC4033

DNS Security Introduction and Requirements. R. Arends; R. Austein; M. Larson; D. Massey; S. Rose; 2005-03. Status: Proposed Standard.

RFC4034

Resource Records for the DNS Security Extensions. R. Arends; R. Austein; M. Larson; D. Massey; S. Rose; 2005-03. Status: Proposed Standard.

RFC4035

Protocol Modifications for the DNS Security Extensions. R. Arends; R. Austein; M. Larson; D. Massey; S. Rose; 2005-03. Status: Proposed Standard.

RFC5895

Mapping Characters for Internationalized Domain Names in Applications (IDNA) 2008. P. Resnick; P. Hoffman; 2010-09. Status: Informational.

RFC6125

Representation and Verification of Domain-Based Application Service Identity within Internet Public Key Infrastructure Using X.509 (PKIX) Certificates in the Context of Transport Layer Security (TLS). P. Saint-Andre; J. Hodges; 2011-03. Status: Proposed Standard.

RFC6234

US Secure Hash Algorithms (SHA and SHA-based HMAC and HKDF). D. Eastlake 3rd; T. Hansen; 2011-05. Status: Informational.

RFC8484

DNS Queries over HTTPS (DoH). P. Hoffman; P. McManus; 2018-10. Status: Proposed Standard.

RFC8785

JSON Canonicalization Scheme (JCS). A. Rundgren; B. Jordan; S. Erdtman; 2020-06. Status: Informational.

RFC9525

Service Identity in TLS. P. Saint-Andre; R. Salz; 2023-11. Status: Proposed Standard.

§ did:tdw Version Changelog

The following lists the substantive changes in each version of the specification.

• Version 0.4
  • Removes large non-normative sections, such as the implementer’s guide, as they are now published on the https://didtdw.org/ information site.
  • Removes the use of JSON Patch from the specification. The full DIDDoc is included in each DID log entry.
  • Changes the data format of the DID log entries from an array to an object. The DID Log remains in the JSON Lines format.
  • Changes the DID log entry array to be named JSON objects or properties.
  • Makes each DID version’s Data Integrity proof apply across the JSON DID log entry object, as is typical with DID Integrity. Previously, the Data Integrity proof was generated across the current DIDDoc version, with the versionId as the challenge.
  • Specified that the versionTime must be recorded as a UTC time zone timestamp.
• Version 0.3
  • Removes the cryptosuite parameter, moving it to implied based on the method parameter.
  • Change base32 encoding with base58btc, as it offers a better expansion rate.
  • Remove the step to extract part of the base58btc result during the generation of the SCID.
  • Use multihash in the SCID to differentiate the different hash function outputs.
• Version 0.2
  • Changes the location of the SCID in the DID to always be the first component after the DID Method prefix – did:tdw:<scid>:....
  • Adds the parameter portable to enable the capability to move a did:tdw during the creation of the DID.
  • Removes the first two Log Entry items entryHash and versionId and replacing them with the new versionId as the first item in each log. The new versionId takes the form <version number>-<entryHash>, where <version number> is the incrementing integer of version of the entry: 1, 2, 3, etc.
  • The <did>/whois media type is changed to application/vp and the file is changed to whois.vp to match the IANA registration of a Verifiable.