§ The did:webvh DID Method v0.5

did:webvh Logo

Specification Status: CURRENT STABLE

Specification Version: v0.5 (see Changelog)

With this version of the specification the DID Method hame is changed to did:webvh (“did:web + Verifiable History”). It used to be named did:tdw.

Next Version: Editors Draft

NOTE

You are looking at the current stable version of the specification. At this time, the Editors Draft contains only clarifications to this version, with no breaking changes. Should that change, this message will be updated.

Source For This Version: https://github.com/decentralized-identity/didwebvh/tree/main/spec-v0.5

Previous Versions:

Information Site: https://didwebvh.info/

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

DID Web + Verifiable History (did:webvh) is an enhancement to the did:web DID method, providing complementary features that address did:web’s limitations as a long-lasting DID. did:webvh features include:

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

For information beyond this specification about the (did:webvh) DID method and how (and where) it is used in practice, please visit https://didwebvh.info/

§ 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:webvh (did:web + Verifiable History) 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:webvh, 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:webvh. 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:webvh 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:webvh is 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 provides a more decentralized approach by ensuring that the security of the embedded SCID does not depend on DNS. did:webvh 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 by offering a higher level of assurance for cryptographic key publishing and management.

For backwards compatibility, and for verifiers that “trust” did:web, a did:webvh can be trivially modified and published with a parallel did:web DID. For resolvers that want more assurance, did:webvh provides a way to verify a did:web using the features listed in the Abstract.

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

  1. did:webvh uses the same DID-to-HTTPS transformation as did:web, so did:webvh’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:webvh.
  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:webvh 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.
    6. If the DID Controller enables support for DID [[witnesses]], an extra file (did-witness.json) in the same web location contains Data Integrity proofs from witness for DID Log entries.
  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). This is done by using the string "{SCID}" everywhere the actual SCID is to be placed in order to generate the hash. The DID Controller 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 must be verified by the resolvers, to verify that the inception event has not been tampered with. The SCID also enables an optional portability capability, allowing a DID’s web location to be moved, while retaining the SCID and verifiable history of the identifier.
  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 DID’s identifier.
  6. Given a did:webvh DID, a resolver converts the DID to an HTTPS URL, retrieves, and processes the DID Log did.jsonl file, 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, and in the past. This enables resolving both current and past versions of the DID and keys.
  7. did:webvh 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. A DID Controller can easily generate and publish a did:web DIDDoc from the latest did:webvh DIDDoc in parallel with the did:webvh DID Log.
WARNING
A resolver settling for just the `did:web` version of the DID does not get the
verifiability of the `did:webvh` log.

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

§ The /whois Use Case

The did:webvh 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:webvh, 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:webvh 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:

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:webvh DID Method Specification

§ Target System

The target system of the did:webvh 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: webvh. A DID that uses this method MUST begin with the following prefix: did:webvh. 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:webvh 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 is performed such that the DID Log for the did:webvh DID can be 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:webvh 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.

webvh-did = "did:webvh:" 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:webvh is almost identical to that of did:web, with changes only to the DID Method (webvh instead of web), and the addition of the <scid>: (defined in the SCID) section of this specification) element in did:webvh that is not in did:web. As specified in the DID-to-HTTPS Transformation section of this specification, did:webvh 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:webvh. For did:webvh DIDs using witnesses, another file did-witness.json is also found (logically) beside the did.jsonl web server file. See the witnesses section of this specification for details.

§ The DID to HTTPS Transformation

The did:webvh 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:webvh, 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:webvh: 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. If the DID is using witnesses, an extra JSON file containing the witness proofs for the DID Log Entries must be published and retrieved during resolution. The URL for the extra file is defined by replacing the /did.jsonl at the end of the DID Log URL with /did-witness.json.
    2. 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), append the DID URL path instead.
  8. The content type for the did.jsonl file SHOULD be text/jsonl.

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

EXAMPLE

did:webvh DIDs and the corresponding web locations of their did:webvh log file. In the examples,{SCID} is a placeholder for where the generated SCID will be placed in the actual DIDs and HTTPS URLs. Note that when the {SCID} follows the literal did:webvh: as a separate element, the {SCID} is not part of the HTTPS URL.

domain/did:web-compatible

did:webvh:{SCID}:example.com -->

https://example.com/.well-known/did.jsonl

subdomain

did:webvh:{SCID}:issuer.example.com -->

https://issuer.example.com/.well-known/did.jsonl

path

did:webvh:{SCID}:example.com:dids:issuer -->

https://example.com/dids/issuer/did.jsonl

path w/ port

did:webvh:{SCID}:example.com%3A3000:dids:issuer -->

https://example.com:3000/dids/issuer/did.jsonl

The location of the did:webvh did.jsonl DID Log file is the same as where the comparable did:web’s did.json file is published. A DID MAY 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:webvh 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 created for the entry and signed by a 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 Examples section on the did:webvh information website.

§ DID Method Operations

§ Create (Register)

Creating a did:webvh 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:webvh:{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:webvh DID as per the ABNF of a did:webvh DID defined in the Method-Specific Identifier section of this specification.

    1. Note: the SCID for a did:webvh 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. At the same time, generate 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:webvh:{SCID}:example.com#key-1, did:webvh:{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.

    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.

    If the DID Controller has opted to use witnesses for the DID, the required proofs from the DID’s witnesses MUST be collected and published in the did-witness.json file before the DID with the new version is published. See the DID Witnesses section of this specification.

  7. Publish the DID Log The complete DID Log file MUST be published at the appropriate Web location defined by the did:webvh 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:webvh. Verifiers using the did:web lose the verifiable properties and history of the did:webvh 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:webvh 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 for the log entry.

For each entry:

  1. Update the currently active parameters with the parameters from the entry (if any). The parameters MUST adhere to the did:webvh DID Method Parameters section of this specification. 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, updating the nextKeys and witnesses arrays take 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 resolvers MUST retrieve and verify the DID’s did-witness.json file. 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. 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.
  6. Get the value of the log entry property state, which is the DIDDoc for the version.
  7. If Key Pre-Rotation is being used, the hash of all updateKeys entries in the parameters property MUST match a hash in the array of nextKeyHashes parameter from the previous DID log entry, with exception of the first entry, as defined in the Pre-Rotation[Key Pre-Rotation Hash Generation and Verification](#pre-rotation-key-hash-generation-and-verification) section of this specification.
  8. 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 keys that must be used in the updateKeys list of the next DID log entry. The pre-rotation hashes are in the nextKeyHashes list in the parameters.
    6. All other did:webvh processing configuration settings as defined by in the parameters object.
  9. If the parameters for any of the versions define that some or all of the DID Log entries must be witnessed, further verification of the witness proofs must be carried out, as defined in the DID Witnesses section of this specification.
  10. If any of the DID verifications outlined in this process fail, discard the DID as invalid with an error message.

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.

TODO

Document the full list of error codes that can be generated in resolving a DID.

§ Reading did:webvh DID URLs

A did:webvh resolver MUST resolve the [DID-CORE] versionId and versionTime DID URL query parameters. The versionId query argument value MUST match the full versionId from a DID Log entry for the resolver to return that version of the DIDDoc. If a DID Log entry with that versionId is not found, a NotFound MUST be returned. A specified time in ISO8601 format as the query argument for versionTime MUST return the DIDDoc from the DID Log entry that was active at that time, if any. If the DID was not active at the specified time, a NotFound MUST be returned.

A did:webvh resolver SHOULD resolve the DID URL query parameter versionNumber with an integer value if there is a DID Log entry with a versionId with a matching integer prior to the literal - – the versionNumber for that DID Log entry as defined in the process for setting the versionId in the creating the DID section of this specification. The versionNumber query parameter is not in the [DID-CORE] specification.

A did:webvh 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:webvh 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:webvh 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 Key Pre-Rotation is being used, the hash of all updateKeys entries in the parameters property MUST match a hash in the array of nextKeyHashes parameter from the previous DID log entry with exception of the first entry, as defined in the Pre-Rotation[Key Pre-Rotation Hash Generation and Verification](#pre-rotation-key-hash-generation-and-verification) 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. If the DID Controller has opted to use witnesses for the DID, the DID Controller MUST collect the threshold of proofs from the DID’s witnesses, and update and publish the DID’s did-witness.json file. The updated did-witness.json file MUST be published BEFORE the updated DID Log file is published. See the DID Witnesses section of this specification.
  11. The new log entry MUST be appended to the existing contents of the DID Log file did.jsonl.
  12. The updated DID Log file MUST be published the appropriate location defined by the did:webvh 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 Controller SHOULD update the DIDDoc and parameters object to further indicate the deactivation of the DID, such as setting to null the updateKeys in the parameters, preventing further versions of the DID. If the DID is using pre-rotation, two DID log entries are required, the first to stop the use of pre-rotation, and the second for setting updateKeys to null. For additional details about turning off pre-rotation see the pre-rotation section of this specification.

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:webvh DID Method Parameters

Entries in the did:webvh 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.

EXAMPLE

An example of the JSON prettified parameters property in the first DID Log entry for a DID:

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

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

§ 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:webvh 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:webvh 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:webvh 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:webvh 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:webvh 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:webvh 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:webvh:0.5", "scid": "QmfGEUAcMpzo25kF2Rhn8L5FAXysfGnkzjwdKoNPi615XQ"}, "state": {"@context": ["https://www.w3.org/ns/did/v1"], "id": "did:webvh:QmfGEUAcMpzo25kF2Rhn8L5FAXysfGnkzjwdKoNPi615XQ:domain.example"}}

Resulting entryHash: QmQq6Kg4ZZ1p49znzxnWmes4LkkWgMWLrnrfPre8UD56bz

§ Verify The Entry Hash

To verify the entryHash for a given did:webvh 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:webvh 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:webvh 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.

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:webvh Implementation Guide contains further discussion on the management of keys authorized to update the DID.

The active updateKeys for subsequent entries depends if the Pre-Rotation is active or not.

§ No Key Prerotation

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.

§ Prerotation

For all subsequent entries, the active list is the updateKeys from the current log entry to be verified. Thus, the general case is that each log entry is signed by the keys from the current log entry.

§ DID Portability

As noted in the Update (rotate) section of the specification, a did:webvh 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.

§ Pre-Rotation Key Hash Generation and Verification

Pre-rotation requires a DID Controller to commit to the authorization keys that will be used (“rotated to”) in the next log entry 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 did:webvh Implementer’s Guide for additional guidance.

As described in the parameters section of this specification, a DID Controller MAY include the parameter nextKeyHashes with a non-empty list in any DID log entry to activate the pre-rotation feature. When pre-rotation is active, all multikey representations of the public keys in the updateKeys parameters property in other than the initial version of the DID log MUST have their hash in the nextKeyHashes array from the previous DID log entry. If not, terminate the resolution process with an error.

A DID Controller may turn off the use of pre-rotation by setting the parameter nextKeyHashes to null in any DID log entry. If there is an active set of nextKeyHashes at the time, the pre-rotation requirements remains in effect for the DID Log entry. The subsequent DID Log entry MUST use the non-pre-rotation rules.

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. The key type MUST be one that can be used as a did:webvh authorization key.
  2. Generate a multikey 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:webvh 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 the next log entry 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 and the private key can be used to sign the log entry's 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 pre-rotation feature is active, a did:webvh 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 multihash multikey.
  2. The hash algorithm MUST be one listed in the parameters defined by the version of the did:webvh specification being used by the DID Controller.
  3. The resultant hash MUST be in the nextKeyHashes array from the previous log entry prior to being processed. If not, terminate the resolution process with an error.
  4. A new nextKeyHashes list MUST be in the parameters of the log entry currently being processed. If not, terminate the resolution process with an error.

§ DID Witnesses

The witness process for a did:webvh DID provides a way for collaborators to work with the DID Controller to “witness” the publication of new versions of the DID. This specification defines the technical mechanism for using witnesses. Governance and policy questions about when and how to use the technical mechanism are outside the scope of this specification.

Witnesses can prevent a DID Controller from updating/removing versions of a DID without detection by the witnesses. 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's web site where the DID log is published. With both compromises, a malicious actor might be able to take control over the DID by rewriting the DID Log using the keys they have compromised. By adding witnesses to monitor and approve each version update, a malicious actor cannot rewrite the previous history without having compromised a sufficient number of witnesses, the DID Controller's key(s), and the Web Server on which the DID Log is published.

§ Witness Lists

The list of DIDs that witness DID updates are defined in the witness parameter, as described in the Parameters section of this specification. After the first witness parameter has been added to a DID log entry, and while there are active witnesses, a threshold of the active witnesses must provide valid proofs associated with each DID log entry before the DID log entry can be published. If a DID log entry contains a new (replacement) list of witnesses (by including a new witness parameter) that new list becomes active AFTER the new DID log entry has been published. Such a replacement MAY be a null. Once a witness set to null becomes active, updates to the DID are not witnessed.

§ Witness DIDs and Reputation

did:webvh witness DIDs MUST be did:key DIDs.

If there is a need in an ecosystem to identify who the witnesses are, a mechanism should be defined by the governance of the ecosystem, such as the entry of the DID in a trust registry. Such mechanisms are outside the scope of this specification.

§ The witness Parameter

The witness element in a parameters object of a DID Log entry has the following data structure:


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

where:

§ Witness Threshold Algorithm

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 met, all participants MUST sum the weight integer of the received approvals. and if it is equal to or more than the threshold MUST be accepted as “witnessed”.

For example, if there are three witnesses with a weight of 1, a fourth with a weight of 2, and a threshold of 3, the threshold is met by either the fourth plus any one of the other witnesses (2+1), or all of the first three witness (1+1+1) providing an approving proof.

§ The Witness Proofs File

Proofs from witnesses are placed into a separate file (did-witness.json) from the DID Log. The same DID to HTTPS Transformation used for the DID Log is used to locate the did-witness.json resource, with only the last element changed (did.jsonl to did-witness.json). The media type of the file SHOULD be application/json.

The data model for the did-witness.json file is:

[
  {
    "versionId": "1-Qmba111111...",
    "proof": [{ ... }, { ... }]
  },
  {
    "versionId": "2-Qzmb222222...",
    "proof": [{ ... }, { ... }]
  }
]

Where:

A valid proof from a witness carries the implication that all prior DID Log entries are also approved by that witness. To maintain a manageable did-witness.json file size, the DID Controller SHOULD remove all older proofs for published DID Log entries, keeping only the latest proof for each witness.

To eliminate the race condition in publishing the DID Log and did-witness.json files, when a new DID Log entry is being added, witness proofs MUST be added to the did-witness.json file and that file published BEFORE publishing the DID Log file containing the new DID Log entry. As a result, did:webvh resolvers may find proofs for unpublished DID log entries in the did-witness.json file. Resolvers MUST ignore proofs with versionIds not in the DID Log file. Since resolvers cannot verify an unpublished DID log entry, the witness proofs on unpublished DID log entries do not carry the implication of approval of prior DID Log entries. Therefore, at times there may be two proofs in the did-witness.json file for a witness:

To ensure file cleanliness and avoid unnecessary clutter any did-witness.json array entry without proofs (containing only the versionId) SHOULD be removed.

§ Witnessing a DID Version Update

The following process is used to witness a DID version update:

§ Verifying Witness Proofs During Resolution

A did:webvh resolver MUST verify that all DID Log entries that have active witnesses have a threshold of active witnesses approving the log entry. To do so, resolvers must:

If you want to learn more about the practical application of witnesses, see the Implementer’s Guide section on Witnesses on the did:webvh 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:webvh version is created, the DID Controller MAY generate a corresponding did:web to publish along with the did:webvh. To do so, the DID Controller MUST:

  1. Start with the resolved version of the DIDDoc from did:webvh.
  2. Execute a text replacement across the DIDDoc of did:webvh:<SCID>: to did:web:, where <scid> is the actual did:webvh SCID.
  3. Add to the DIDDoc alsoKnownAs array, the full did:webvh 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:webvh can continue to resolve the DID Controller's DIDs. did:web resolvers that are aware of did:webvh features can use that knowledge, and the existence of the alsoKnownAs did:webvh data in the DIDDoc to get the verifiable history of the DID.

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

§ DID URL Resolution

The did:webvh 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:webvh implementation MUST:

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

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

§ whois LinkedVP Service

The #whois service enables those that receive a did:webvh DID to retrieve and a Verifiable Presentation (and embedded Verifiable Credentials) the DID Controller has decided to publish about itself. The intention is that anyone wanting to learn more about a particular did:webvh DID can resolve the <did>/whois DID URL to retrieve a Verifiable Presentation 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 Controller.

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 Controller.

did:webvh 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:webvh 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 presentation 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:webvh 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 VCDM format, they MUST explicitly add to their DIDDoc a service with the "id": "#whois" to specify the name and implied format of the verifiable presentation.

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

  1. Resolve the given did:webvh DID by retrieving, processing, and verifying the DID log for the did:webvh 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:webvh DID URL paths follows the [DID-CORE] relativeRef specification, as follows:

Thus, the implicit service for DID did:webvh: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:webvh DID>/path/to/file, the resolver MUST:

  1. Resolve the given did:webvh DID by retrieving, processing, and verifying the DID log for the did:webvh 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:webvh 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:

§ Cross-Origin Resource Sharing (CORS) Policy Considerations

To support scenarios where DID resolution is performed by client applications running in a web browser, the file served for the DID Log needs to be accessible by any origin. To enable this, the DID Log HTTP response MUST include the following header:

Access-Control-Allow-Origin: *

§ Definitions

base58btc
Applies [[spec:draft-msporny-base58-03]] to convert data to a base58 encoding. Used in did:webvh 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 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:webvh.
DID Portability
did:webvh 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, security and verifiability. did:web provides a starting point for did:webvh, which complements did:web with specific features to address its 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:webvh 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 presentation about the DID subject can be found. The Decentralized Identity Foundation hosts the Linked VP Specification.
multibase
A specification for encoding binary data as a string using a prefix that indicates the encoding.
multikey
A verification method that encodes key types into a single binary stream that is then encoded as a multibase value.
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.
parameters
did:webvh 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:webvh 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:webvh 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:webvh 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.
threshold
An algorithm that defines when a sufficient number of witnesses have submitted valid Data Integrity proofs for a DID Log entry such that it is approved and can be published. The algorithm details are in the Witness Threshold Algorithm section of this specification.
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:webvh Version Changelog

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

✕
Table of Contents ✕