Skip to main content

Announcing Public Review of the did:webs Method Specification

By December 15, 2023December 22nd, 2023News
Close-up of part of a spider web covered in dew, with a green blurred background

The ToIP Foundation is pleased to announce a 30 day public review of the did:webs Method Specification. This blog post will explain the motivations for creating this new method for creating and resolving decentralized identifiers (DIDs), and also how to participate in the public review process.


When DIDs were first invented, the inventors thought that someday there might be perhaps a dozen or so different types of DIDs, called DID methods. Their reasoning was that DIDs solved a very narrow problem—how to create a cryptographically-verifiable identifier—an identifier over which the controller (person, organization, device, bot, etc.) could prove control by virtue of having the associated private key. This new type of identifier would not need to be registered with any centralized authority and could not be spoofed or taken away by some other party (unless they could steal the private key).

Each DID method was simply a different way of specifying how the DID could be securely bound to a public/private key pair. While there are of course multiple ways to do that, what the DID inventors didn’t anticipate is: a) how badly cryptographically verifiable identifiers were needed, and, as a consequence, b) how many DID methods would be created. By the time the DID specification reached a final vote at the W3C in 2022, 112 DID methods had been registered in the W3C DID Spec Registries. As of this writing, there are now 184.

The did:web method

That’s 184 different ways to create a DID and resolve it to its corresponding DID document (which is where you find the current public key together with other metadata such as the network service endpoint where you can communicate with the controller). Given this massive number of options, it is no surprise that many developers threw up their hands and chose the one that seemed the easiest and most familiar: the did:web method.

What makes the did:web method so intuitive is that all it requires is posting a DID document on a web server. The resulting DID is simply: a) the string did:web: followed by the domain name of the web server and—optionally—the path name to the DID document (with each forward slash turned into a colon). Here’s a simple example: if the DID document will be stored at the URL:

…then the corresponding did:web DID is:

It is that easy. The irony is that the did:web method was very nearly rejected by the W3C DID Working Group for two reasons:

  1. It is a stretch to call it decentralized since it depends on DNS domain names which require centralized registries.
  2. As a result, it inherits all of the security flaws of DNS, and then adds the additional vulnerabilities of storing a “naked” DID document on a web server. Since the DID document contains the public key associated with the DID, anyone who can manage to replace the real DID document with their own version can completely hijack the DID.

For these reasons, once DID adoption started to kick in, it came as somewhat of a shock that did:web was proving to be so popular. In fact, some DID proponents became quite worried that the security issues with did:web might lead to a breach whose ensuing publicity might give all DIDs a bad name.

The light bulb

Thankfully, as those concerns mounted, by the summer of 2023, no less than four independent groups all had the same basic insight: the flaws in did:web could be fixed by tunneling a self-certifying identifier inside a did:web string.

What is a self-certifying identifier? See the following diagram that categorizes the three overall types of DIDs by the approach they take to how the DID is bound to the key pair:

A diagram showing the three types of DID: Administrative, Algorithmic and Autonomous

In short, a conventional did:web DID is a category 1 administrative DID whose security depends on: a) a TLS certificate administered by a certificate authority, and b) the administrator of the web server. That’s two humans-in-the-loop, either of whose defenses can be penetrated to compromise the DID.

By contrast, a category 3 self-certifying DID, also called an autonomous DID is generated directly inside a digital wallet or hardware security module (HSM) and cryptographically bound to the associated DID. That means there are zero humans-in-the-loop. Anyone with a copy of the DID document can instantly verify—using only a cryptographic proof—that it is bound to that DID and only that DID.

The did:webs method

What the different groups realized is that all it takes to “tunnel” a self-certifying identifier inside a conventional did:web DID is to include it as the final path segment. So if the self-certifying identifier is:


…and the URL of the folder that will contain the DID document is…

…then the resulting did:webs DID is:

In short, a did:webs DID is a valid did:web DID that has special cryptographic properties Thankfully, those properties solve both of the key challenges with the did:web method:

  1. did:webs is more decentralized because, even though resolution of the did:web domain name depends on DNS, the security of the embedded self-certifying identifier does not. It can be generated and maintained in any digital wallet or key management system anywhere. In fact the same self-certifying identifier can be included in multiple did:webs DIDs stored on different web servers around the web, and they all serve as synonyms for each other (which can be explicitly declared in the did:webs DID document—see the did:webs specification for details).
  2. did:webs is more secure because security does NOT depend on the web server. If the web server is hacked and an attacker replaces the did:webs DID document with their own, the fake DID document will not verify because (unless the attacker has stolen the private key), it will not be cryptographically bound to the did:webs DID.

The did:webs Method Task Force

Armed with this insight that the simplicity and ease of implementation of did:web could be combined with the decentralization and security properties of self-certifying identifiers, the did:webs Method Task Force was formed in July 2023. The mission was to develop a specification for the did:webs DID method that met the requirements defined in the W3C Decentralized Identifiers (DIDs) 1.0 specification, including creation, resolution, updating, and deactivation of did:webs DID documents.

Given that self-certifying identifiers have always been a foundational feature of the KERI family of specifications being developed by the ToIP ACDC Task Force, the new did:webs Method Task Force was able to rapidly draft a specification based on the autonomic identifiers (AIDs) used by KERI.

The task force previewed their draft did:webs specification at the 37th Internet Identity workshop in Mountain View, California. First Markus Sabadello and Lance Byrd presented did:webs for Muggles, then Markus gave his did:webs IIW37 Tutorial which covered:

  • how to create a did:webs identifier, 
  • how the associated KERI self-certifying identifier secures the DID document, 
  • how to host the information on Github or any other web server, and 
  • how the DIF Universal Resolver resolves both the did:web and did:webs versions of the DID document.

Following the feedback received at IIW, the task force further refined the specification and verified it with several implementations. By early December, the task force was ready to request a full public review.

How to participate in the public review process

The full did:webs Method Specification is publicly available on the ToIP Github. We invite anyone interested in helping to improve this specification to comment via the public review process open to anyone. Just follow these steps:

  1. Identify the section(s) of the specification upon which you wish to make a comment or suggest an improvement.
  2. Go to the GitHub Issues page for the did:webs Method Specification.
  3. Review the list of open issues to see if there is already one pertaining to the section(s) upon which you wish to comment. If so, just click on that issue, scroll to the bottom, type your comment, and click “Comment”.
  4. Otherwise, follow these instructions for creating a new issue. Please prefix the name of your new issue with the section number to which it pertains, e.g., “Section 6.4:…”
  5. The first time you submit a comment or a new issue, you will need to agree to the Contributor License Agreement in order to keep the specification open and royalty free for all.

If you do not wish to comment, but rather to ask a question or start a discussion related to the did:webs Method Specification, you can do so via the Github Discussions page. If you wish to become directly involved in drafting future versions of this or any other related ToIP specification, we invite you to become a member of the ToIP Foundation.

Photo by Vivienne Nieuwenhuizen on Unsplash