§ ToIP did:webs Method Specification V1.0

Specification Status: Public Review Draft 01

Latest Draft:

https://github.com/trustoverip/tswg-did-method-webs-specification

Editors:

Contributors:

Participate:
GitHub repo
Commit history

§ Abstract

This document specifies a DID Method, did:webs, that is web-based but innovatively secure. Like its interoperable cousin, did:web, the did:webs method uses traditional web infrastructure to publish DIDs and make them discoverable. Unlike did:web, this method’s trust is not rooted in DNS, webmasters, X509, and certificate authorities. Instead, it uses KERI to provide a secure chain of cryptographic key events by those who control the identifier.

The did:webs method does not need blockchains to establish trust. However, its use of KERI allows for arbitrary blockchains to be referenced as an extra, optional publication mechanism. This offers a potentital interoperability bridge from (or between) blockchain ecosystems. Also, without directly supporting environments where the web is not practical (e.g., IOT, Lo-Ra, Bluetooth, NFC), the method builds on a foundation that can fully support those environments, making future interop of identifiers between web and non-web a manageable step for users of did:webs identifiers.

All DID methods make tradeoffs. The ones in did:webs result in a method that is cheap, easy to implement, and scalable. No exotic or unproven cryptography is required. Deployment is straightforward. Cryptographic trust is strongly decentralized and governance is transparent. Regulatory challenges around the issue of blockchains vanish. Any tech community or legal jurisdiction can use it. However, did:webs does depend on the web for publication and discovery. This may color its decentralization and privacy. For its security, it adds KERI, imposing a modest - to significant learning curve as a result. For users, the method also raises the bar of accountability, thoughtfulness, and autonomy; this can be viewed as either a drawback or a benefit (or both).

§ Status of This Memo

This document contains the specification for the did:webs DID method.

Information about the current status of this document, any errata, and how to provide feedback on it, may be obtained at https://github.com/trustoverip/tswg-did-method-webs-specification.

This specification is subject to the OWF Contributor License Agreement 1.0 - Copyright available at https://www.openwebfoundation.org/the-agreements/the-owf-1-0-agreements-granted-claims/owf-contributor-license-agreement-1-0-copyright.

If source code is included in the specification, that code is subject to the Apache 2.0 license unless otherwise marked. In the case of any conflict or confusion within this specification between the OWF Contributor License and the designated source code license, the terms of the OWF Contributor License shall apply.

These terms are inherited from the Technical Stack Working Group at the Trust over IP Foundation. Working Group Charter

§ Introduction

This section is informative.

DID methods answer many questions. Two noteworthy ones are:

The previously released did:web method merges these two questions, giving one answer: Information is published and secured using familiar web mechanisms. This has wonderful adoption benefits, because the processes and tooling are familiar to millions of developers.

Unfortunately, this answer works better for the first question than the second. The current web is simply not very trustworthy. Websites get hacked. Sysadmins are sometimes malicious. DNS can be hijacked. X509 certs often prove less than clients wish. Browser validation checks are imperfect. Different certificate authorities have different quality standards. The processes that browser vendors use to pre-approve certificate authorities in browsers are opaque and centralized. TLS is susceptible to man-in-the-middle attacks on intranets with customized certificate chains. Governance is weak and inconsistent…

Furthermore, familiar web mechanisms are almost always operated by corporate IT staff. This makes them an awkward fit for the ideal of decentralized autonomy — even if individuals can publish a DID on corporate web servers, those individuals are at the mercy of IT personnel for their security.

The did:webs method described in this spec separates these two questions and answers them distinctively. Information about DIDs is still published on the web, but its trustworthiness derives from mechanisms entirely governed by individual DID controllers. This preserves most of the delightful convenience of did:web, while drastically upgrading security through authentic data that is end-verifiable.

Within the context of did:webs the term decentralized trust includes verifiability, confidentiality, and privacy, but excludes veracity of the content. The latter is always a matter of (personal) evaluation of available reputational data and verifiable credentials (VCs).

§ Requirements, Notation and Conventions

This section is normative.

§ Keywords

The following key words in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here:

  1. “MUST”
  2. “MUST NOT”
  3. “REQUIRED”
  4. “SHALL”
  5. “SHALL NOT”
  6. “SHOULD”
  7. “SHOULD NOT”
  8. “RECOMMENDED”
  9. “NOT RECOMMENDED”
  10. “MAY”
  11. “OPTIONAL”

§ Conventions

  1. Normative sections MUST start with “This section is normative.”
  2. Normative statements SHOULD read in a way that can be implemented.
  3. Normative statements MUST be numbered so that they are easily referenced and addressed in discussions, issues, pull requests, etc.
  4. Informative sections MUST start with “This section is informative.”
  5. Informative statements MUST NOT be numbered. Instead they can use prose or bulleted points.
  6. If informative statements accompany normative statements then they MUST be separated like:

    This is informative text accompanying but separated from the normative statements.

  7. If a normative section contains an informative sub-section then the sub-section MUST be marked with “This section is informative.”

§ Core Characteristics

This section is normative.

§ Method Name

  1. The method name that identifies this DID method SHALL be: webs.
  2. A DID that uses this method MUST begin with the following prefix: did:webs:.
  3. Per the DID specification, this string MUST be lower case.
  4. The remainder of the DID, after the prefix, MUST be the case-sensitive method-specific identifier (MSI) described below.

Note: when pronounced aloud, “webs” should become two syllables: the word “web” and the letter “s” (which stands for “secure”). Separating the final letter this way emphasizes that the method offers a security upgrade surpassing the one HTTPS gives to HTTP.

§ Method-Specific Identifier

  1. The did:webs method-specific identifier MUST have two parts, a host with an optional path (identical to did:web), plus a KERI AID (autonomic identifier) that is always the final component of the path.

  2. The ABNF definition of a did:webs DID MUST be as follows:

    webs-did = "did:webs:" host [pct-encoded-colon port] *(":" path) ":" aid
    
    ; 'host' as defined in RFC 1035 and RFC 1123
    host = *( ALPHA / DIGIT / "-" / "." )  ; Simplified representation, actual RFCs
                                          ; have more complex rules for domains and IP addresses.
                                          ; IN ACTUAL IMPLEMENTATIONS REPLACE WITH A MATURE 
                                          ; HOST PARSING LIBRARY.
    
    ; 'pct-encoded-colon' represents a percent-encoded colon
    pct-encoded-colon = "%3A" / "%3a"  ; Percent encoding for ':'
    
    ; 'port' number (simplified version)
    port = 1*5(DIGIT)
    
    ; 'path' definition
    path = 1*(ALPHA / DIGIT / "-" / "_" / "~" / "." / "/")
    
    ; 'aid' as base64 encoded value
    aid = 1*(ALPHA / DIGIT / "+" / "/" / "=") ; Base64 characters
    
    ; ALPHA, DIGIT are standard ABNF primitives for alphabetic and numeric characters
    
  3. The host MUST abide by the formal rules describing valid syntax found in RFC1035, RFC1123, and RFC2181.

  4. A port MAY be included and the colon MUST be percent encoded, like %3a, to prevent a conflict with paths.

  5. Directories and subdirectories MAY optionally be included, delimited by colons rather than slashes.

  6. The KERI AID is a unique identifier and MUST be derived from the inception event of a KERI identifier.

The inception event is the first item in the identifier’s KEL. The algorithm used to generate the AID depends on the type of AID. If the AID is transferable (supports key rotation) then the AID is generated by taking a cryptographic digest of the inception event of the KEL of the AID. If the AID is non-transferable (does not support key rotation) the AID is generated by taking a cryptographic digest of the first (and only) public key of the identifier. See the KERI Fundamentals section for more details.

To be compatible with did:web, the AID is “just a path”, the final (and perhaps only) path element. The presence of the required AID as a path element means that a did:webs always has a path,and so the “no path” version of a did:web that implicitly uses the .well-known folder is not supported by did:webs. Any did:webs can be expressed as a did:web but the inverse is not true–a did:webs must include an AID.

§ Target System(s)

  1. As with did:web, did:webs MUST read data from whatever web server is referenced when the host portion of one of its DID is resolved.
  2. A did:webs DID MUST resolve to a DID document using a simple text transformation to an HTTPS URL in the same way as a did:web DID.
  3. A did:web DID and did:webs DID with the same method-specific identifier SHOULD return the same DID document, except for minor differences in the id, controller, and alsoKnownAs top-level properties that pertain to the identifiers themselves.
  4. As with did:web, the location of the DID document MUST be determined by transforming the DID to an HTTPS URL as follows:
    1. MUST replace did:webs with https://
    2. MUST replace the ":"s in the method-specific identifier with path separators, "‘/’"s
    3. MUST convert the optional port percent encoding (“%3A”`) to a colon if present.
    4. MUST append “/did.json” to the resulting string.
  5. A GET on that URL MUST return the DID document.
  6. The location of the KERI event stream MUST be determined by transforming the previous URL as follows:
    1. MUST replace the trailing “/did.json” with “/keri.cesr”.
    2. A GET on that URL MUST return the KERI event stream for the AID in the did:webs identifier.
    3. The KERI event stream MUST be CESR-formatted (media type of application/cesr) and the KERI events must be verifiable using the KERI rules.
  7. The did:web version of the DIDs MUST be the same (minus the s) and point to the same did.json file, but have no knowledge of the keri.cesr file.

The set of KERI features needed for most did:webs use cases is modest, with limited dependencies. These basics are summarized in the KERI Fundamentals section of this specification. This specification assumes a working knowledge of the concepts there. The inclusion of KERI in did:webs enables a number of capabilities for securing a did:webs identifier, including multi-signature support and the creation of pre-rotated keys to prevent loss of control of the identifier if the current private key were to be compromised.

A target system cannot forge or tamper with data protected by KERI, and if it deliberately serves an outdated copy, the duplicity is often detectable. Thus, any given target system in isolation can be viewed by this method as a dumb, untrusted server of content. It is the combination of target systems and some KERI mechanisms, together, that constitutes this method’s verifiable data registry. In short, verifying the DID document by processing the KERI event stream using KERI puts the “s” of “security” in did:webs.

The following are some example did:webs DIDs and their corresponding DID documents and KERI event stream URLs, based on the examples from the did:web Specification, but with the (faked) AID 12124313423525 added:

§ AID controlled identifiers

  1. AID controlled identifiers MAY vary in how quickly they reflect the current identity information, DID document and KERI event stream. Notably, as defined in section Identifiers in a did:webs DID document, the id property in the DID document will differ based on the web location of the DID document.
  2. Different versions of the DID document and KERI event stream MAY reside in different locations depending on the replication capabilities of the controlling entity.
  3. If the KERI event streams differ for did:webs DIDs with the same AID, the smaller KERI event stream MUST be a prefix of the larger KERI event stream (e.g., the only difference in the KERI event streams being the extra events in one of the KERI event streams, not yet reflected in the other).
  4. If the KERI event streams diverge from one other (e.g., one is not a subset of the other), both the KERI event streams and the DIDs MUST be considered invalid.
  5. The verification of the KERI event stream SHOULD provide mechanisms for detecting the forking of the KERI event stream by using mechanisms such as KERI witnesses and watchers.

Since an AID is a unique cryptographic identifier that is inseparably bound to the KERI event stream it is associated with any AIDs and any did:webs DIDs that have the same AID component. It can be verifiably proven that they have the same controller(s).

The web supports a number of ways to redirect users. See the section on Handling Web Redirections later in this specification.

KERI anticipates the possibility of a duplicitous actor with an AID that forks a KERI event stream and shares different versions of the KERI event stream containing different events, such as publishing different versions of the KERI event stream on different web servers.

§ Handling Web Redirection

  1. A did:webs MAY be a “stable” (long-lasting) identifier that can be put into documents such as verifiable credentials, to be useful for a very long time – generations.

  2. When a did:webs is updated for another location the following rules MUST apply:

    1. Its AID MUST not change.
    2. The same KERI event stream MUST be used to verify the DID document, with the only change being the designated aliases list reflecting the new location identifier.
    3. If a resolver can find a newly named DID that uses the same AID, and the KERI event stream verifies the DID, then the resolver MAY consider the resolution to be successful and should note it in the resolution metadata.
  3. The following resolution paths that did:webs identfiers SHALL leverage to help in the face of resolution uncertainty:

    1. The did:webs DID SHALL provide other designated aliases DID(s) that are anchored to the KERI event stream.
    2. When a did:webs is permanently moved to some other location the resolver MAY redirect to any other equivalentId designated aliases.
      1. The id in the DID document MUST be set to the new location.
      2. An equivalentId entry of the old location SHOULD remain for historical purposes and anchored to the KERI event stream using designated aliases. See section Use of equivalentId for more details.
      3. If possible, the controller of the DID MAY use web redirects to allow resolution of the old location of the DID to the new location.
    3. If the previously published location of a did:webs is not redirected, an entity trying to resolve the DID MAY be able to find the data for the DID somewhere else using just the AID.

The web is not a very stable place, and documents are moved around and copied frequently. When two or more companies merge, often the web presence of some of the merged entities “disappears”. It may not be possible to retain a permanent did:webs web location.

The purpose of the history of designated aliases for the AID is so that if the did:webs DID has been put in long-lasting documents, and its URL instantiation is redirected or disappears, the controller can explicitly indicate that the new DID is an equivalentId to the old one.

Since the AID is globally unique and references the same identifier, regardless of the rest of the string that is the full did:webs, web searching could yield either the current location of the DID document, or a copy of the DID that may be useful. For example, even the Internet Archive: Wayback Machine could be used to find a copy of the DID document and the KERI event stream at some point in the past that may be sufficient for the purposes of the entity trying to resolve the DID. This specification does not rely on the Wayback Machine, but it might be a useful did:webs discovery tool.

The DID document, KERI event stream and other files related to a DID may be copied to other web locations. For example, someone might want to keep a cache of DIDs they use, or an entity might want to run a registry of “useful” DIDs for a cooperating group. While the combination of DID document and KERI event stream make the DID and DID document verifiable, just as when published in their “intended” location, the absence of the did:webs in the designated aliases for those locations in the DID document equivalentId means that the controller of the DID is not self-asserting any sort of tie between the DID and the location to which the DID-related documents have been copied. In contrast, if the controller confirms the link between the source and the copy with an equivalentId, the related copies will have to be kept in sync.

Were the AID of a did:webs identifier to change, it would be an altogether new DID, unconnected to the first DID.

A did:webs could be moved to use another DID method that uses the AID for uniqueness and the KERI event stream for validity, but that is beyond the scope of this specification.

§ DID Method Operations

§ Create

  1. Creating a did:webs DID MUST follow these rules:
    1. MUST choose the web URL where the DID document for the DID will be published, excluding the last element that will be the AID, once defined.
    2. MUST create a KERI AID and add it as the last element of the web URL for the DID.
    3. MUST add the appropriate KERI events to the AID’s KERI logs that will correspond to properties of the DID document, such as verification methods and service endpoints.
    4. MUST derive the did:webs DID document by processing the KERI event stream according to section DID Document from KERI Events.
    5. For compatibility reasons, transformation of the derived did:webs DID document to the corresponding did:web DID document MUST be according to section Transformation to did:web DID Document.
    6. MUST create the AID folder on the web server at the selected location, and place the did:web DID document resource (did.json) and the KERI event stream resource (keri.cesr) into that folder. See section Target System(s) for further details about the locations of these resources.

Of course, the web server that serves the resources when asked might be a simple file server (as implied above) or an active component that generates them dynamically. Further, the publisher of the resources placed on the web can use capabilities like [CDNs] to distribute the resources. How the resources are posted at the required location is not defined by this spec; complying implementations need not support any HTTP methods other than GET.

An active component might be used by the controller of the DID to automate the process of publishing and updating the DID document and KERI event stream resources.

§ Read (Resolve)

  1. Resolving a did:webs DID MUST follow these steps:
    1. MUST convert the did:webs DID back to HTTPS URLs as described in section Target System(s).
    2. MUST execute HTTP GET requests on both the URL for the DID document (ending in /did.json) and the URL for the KERI event stream (ending in /keri.cesr).
    3. MUST process the KERI event stream using [KERI Rules] to verify it, then derive the did:webs DID document by processing the KERI event stream according to section DID Document from KERI Events.
    4. MUST transform the retrieved did:web DID document to the corresponding did:webs DID document according to section Transformation to did:webs DID Document.
    5. MUST verify that the derived did:webs DID document equals the transformed DID document.
    6. KERI-aware applications MAY use the KERI event stream to make use of additional capabilities enabled by the use of KERI.

Capabilities beyond the verification of the DID document and KERI event stream are outside the scope of this specification.

§ Update

  1. If the AID of the did:webs DID is updatable, updates MUST be made to the AID by adding KERI events to the KERI event stream.
  2. Updates to the KERI event stream that relate to the did:webs DID MUST be reflected in the DID Document as soon as possible.
    1. If the did:webs DID files are statically hosted then they MUST be republished to the web server, overwriting the existing files.

§ Deactivate

  1. To deactivate a did:webs DID, A controller SHOULD execute a KERI event that has the effect of rotating the key(s) to null and continue to publish the DID document and KERI event stream.
    1. Once the deactivation events have been applied, the controller SHOULD regenerate the DID document from the KERI event stream and republish both documents (did.json and keri.cesr) to the web server, overwriting the existing files.
    2. A controller SHOULD NOT remove the DID folder and files from the web server on which it has been published. This is considered to be a bad approach, as those resolving the DID will not be able to determine if the web service is offline or the DID has been deactivated.

§ DID Documents

This section is normative.

  1. did:webs DID documents MUST be generated or derived from the Keri event stream of the corresponding AID.
    1. Processing the KERI event stream of the AID, the generation algorithm MUST read the AID KEL and any anchored TELs to produce the DID document.
  2. did:webs DID documents MUST be pure JSON. They MAY be processed as JSON-LD by prepending an @context if consumers of the documents wish.
  3. All hashes, cryptographic keys, and signatures MUST be represented as CESR strings. This is an approach similar to multibase, making them self-describing and terse.

The KERI event stream represents a cryptographic chain of custody from the AID itself down to the current set of keys and the cryptographic commitment to the next rotation key(s). The KERI event stream also contains events that do not alter the AID key state, but are useful for the DID document, such as the supported hosts, current set of service endpoints, etc. A did:webs resolver produces the DID document by processing the KERI event stream to determine the current key state. We detail the different events in (KERI event details)[#KERI-event-details] below and show how they change the DID Document. The mapping from KERI event stream to the properties of the DID Document is the core of the did:webs resolver logic. Understanding the optimal way to update and maintain the KERI event stream (publish static keri.cesr files, dyanamically generate the keri.cesr resource, etc) is beyond the scope of the spec, but a reference implementation of the resolver that details these techniques is being developed alongside this spec. The important concepts are that the entire KERI event stream is used to produce and verify the DID document. The KERI event stream represents a cryptographic chain of custody from the AID itself down to the current set of keys and the cryptographic commitment to the next rotation key(s). The KERI event stream also contains events that do not alter the AID key state, but are useful for the DID document, such as the supported hosts, current set of service endpoints, etc. A did:webs resolver produces the DID document by processing the KERI event stream to determine the current key state. We detail the different events in (KERI event details)[#KERI-event-details] below and show how they change the DID Document. The mapping from KERI event stream to the properties of the DID Document is the core of the did:webs resolver logic. Understanding the optimal way to update and maintain the KERI event stream (publish static keri.cesr files, dyanamically generate the keri.cesr resource, etc) is beyond the scope of the spec, but a reference implementation of the resolver that details these techniques is being developed alongside this spec. The important concepts are that the entire KERI event stream is used to produce and verify the DID document.

In KERI the calculated values that result from processing the KERI event stream are referred to as the “current key state” and expressed in the Key State Notice (KSN) record. An example of a KERI KSN record can be seen here:

{
    "v": "KERI10JSON000274_",
    "i": "EeS834LMlGVEOGR8WU3rzZ9M6HUv_vtF32pSXQXKP7jg",
    "s": "1",
    "t": "ksn",
    "p": "ESORkffLV3qHZljOcnijzhCyRT0aXM2XHGVoyd5ST-Iw",
    "d": "EtgNGVxYd6W0LViISr7RSn6ul8Yn92uyj2kiWzt51mHc",
    "f": "1",
    "dt": "2021-11-04T12:55:14.480038+00:00",
    "et": "ixn",
    "kt": "1",
    "k": [
      "DTH0PwWwsrcO_4zGe7bUR-LJX_ZGBTRsmP-ZeJ7fVg_4"
    ],
    "nt": 1,
    "n": [
      "E6qpfz7HeczuU3dAd1O9gPPS6-h_dCxZGYhU8UaDY2pc"
    ],
    "bt": "3",
    "b": [
      "BGKVzj4ve0VSd8z_AmvhLg4lqcC_9WYX90k03q-R_Ydo",
      "BuyRFMideczFZoapylLIyCjSdhtqVb31wZkRKvPfNqkw",
      "Bgoq68HCmYNUDgOz4Skvlu306o_NY-NrYuKAVhk3Zh9c"
    ],
    "c": [],
    "ee": {
      "s": "0",
      "d": "ESORkffLV3qHZljOcnijzhCyRT0aXM2XHGVoyd5ST-Iw",
      "br": [],
      "ba": []
    },
    "di": ""
}

Using this key state as reference, we can identify the fields from the current key state that will translate to values in the DID document. The following table lists the values from the example KSN and their associated values in a DID document:

Key State Field Definition DID Document Value
i The AID value The DID Subject and DID Controller
k The current set of public signing keys Verification Methods with associated authentication and assertion verification relationships
kt The current signing keys threshold The threshold in a Verification Method of type ConditionalProof2022

In several cases above, the value from the key state is not enough by itself to populate the DID document. The following sections detail the algorithm to follow for each case.

§ DID Subject

  1. The value of the id property in the DID document MUST be the did:webs DID that is being created or resolved.
  2. The value from the i field MUST be the value after the last : in the method-specific identifier (MSI) of the did:webs DID, according to the syntax rules in section Method-Specific Identifier.
{
  "id": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M"
}

§ DID Controller

  1. The value of the controller property MUST be a single string that is the same as the id (the DID Subject).
{
  "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M"
}

§ Also Known As

  1. The alsoKnownAs property in the root of the DID document MAY contain any DID that has the same AID. See the designated aliases section for information on how an AID anchors the alsoKnownAs identifiers to their KERI event stream.
  2. did:webs DIDs MUST serve the did:webs and corresponding did:webas an alsoKnownAs identifier.
  3. did:webs DIDs MUST provide the corresponding did:keri as an alsoKnownAs identifier.
  4. The same AID MAY be associated with multiple did:webs DIDs, each with a different host and/or path, but with the same AID.
  5. did:webs DIDs MUST be listed in the designated aliases attestation of the AID.
  6. For each AID controlled identifier DID defined above, an entry in the alsoKnownAs array in the DID document MUST be created.

For the example DID did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M the following alsoKnownAs entries could be created:

{
  "alsoKnownAs": [
    "did:web:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
    "did:webs:foo.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
    "did:keri:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M"
  ]
}

§ Verification Methods

  1. For each key listed in the array value of the k field of the KSN, a corresponding verification method MUST be generated in the DID document.
  2. The ‘type’ property in the verification method for each public key MUST be determined by the algorithm used to generate the public key.
  3. The verification method types used MUST be registered in the DID Specification Registries and added to this specification.
  4. The id property of the verification method MUST be a relative DID URL and use the KERI key CESR value as the value of the fragment component, e.g., "id": "#<identifier>".
  5. The controller property of the verification method MUST be the value of the id property of the DID document.

KERI identifiers express public signing keys as Composable Event Streaming Representation (CESR) encoded strings in the k field of establishment events and the key state notice. CESR encoding encapsulates all the information needed to determine the cryptographic algorithm used to generate the key pair.

At the time of this writing, KERI currently supports public key generation for Ed25519, Secp256k1 and Secp256r1 keys, and the protocol allows for others to be added at any time.

For example, the key DFkI8OSUd9fnmdDM7wz9o6GT_pJIvw1K_S21AKZg4VwK in the DID document for the AID EDP1vHcw_wc4M__Fj53-cJaBnZZASd-aMTaSyWEQ-PC2 becomes:

  "verificationMethod": [
    {
      "id": "#DFkI8OSUd9fnmdDM7wz9o6GT_pJIvw1K_S21AKZg4VwK",
      "controller": "did:webs:example.com:EDP1vHcw_wc4M__Fj53-cJaBnZZASd-aMTaSyWEQ-PC2",
      ...
    }
  ]

§ Ed25519

  1. Ed25519 public keys MUST be converted to a verification method with a type of JsonWebKey and publicKeyJwk property whose value is generated by decoding the CESR representation of the public key out of the KEL and into its binary form (minus the leading ‘B’ or ‘D’ CESR codes) and generating the corresponding representation of the key in JSON Web Key form.

For example, a KERI AID with only the following inception event in its KEL:

{
  "v": "KERI10JSON0001ad_",
  "t": "icp",
  "d": "EDP1vHcw_wc4M__Fj53-cJaBnZZASd-aMTaSyWEQ-PC2",
  "i": "EDP1vHcw_wc4M__Fj53-cJaBnZZASd-aMTaSyWEQ-PC2",
  "s": "0",
  "kt": "1",
  "k": [
    "DFkI8OSUd9fnmdDM7wz9o6GT_pJIvw1K_S21AKZg4VwK",
  ]
  // ...
}

would result in a DID document with the following verification methods array:

  "verificationMethod": [
    {
      "id": "#DFkI8OSUd9fnmdDM7wz9o6GT_pJIvw1K_S21AKZg4VwK",
      "type": "JsonWebKey",
      "controller": "did:webs:example.com:EDP1vHcw_wc4M__Fj53-cJaBnZZASd-aMTaSyWEQ-PC2",
      "publicKeyJwk": {
        "kid": "DFkI8OSUd9fnmdDM7wz9o6GT_pJIvw1K_S21AKZg4VwK",
        "kty": "OKP",
        "crv": "Ed25519",
        "x": "FkI8OSUd9fnmdDM7wz9o6GT_pJIvw1K_S21AKZg4VwI"
      }
    }
  ]

§ Secp256k1

  1. Secp256k1 public keys MUST be converted to a verification method with a type of JsonWebKey and publicKeyJwk property whose value is generated by decoding the CESR representation of the public key out of the KEL and into its binary form (minus the leading ‘1AAA’ or ‘1AAB’ CESR codes) and generating the corresponding representation of the key in JSON Web Key form.

For example, a KERI AID with only the following inception event in its KEL:

{
  "v": "KERI10JSON0001ad_",
  "t": "icp",
  "d": "EDP1vHcw_wc4M__Fj53-cJaBnZZASd-aMTaSyWEQ-PC2",
  "i": "EDP1vHcw_wc4M__Fj53-cJaBnZZASd-aMTaSyWEQ-PC2",
  "s": "0",
  "kt": "1",
  "k": [
    "1AAAAmbFVu-Wf8NCd63B9V0zsy7EgB_ocX2_n_Nh1FCmgF0Y",
  ]
  // ...
}

would result in a DID document with the following verification methods array:

  "verificationMethod": [
    {
      "id": "#1AAAAmbFVu-Wf8NCd63B9V0zsy7EgB_ocX2_n_Nh1FCmgF0Y",
      "type": "JsonWebKey",
      "controller": "did:webs:example.com:EDP1vHcw_wc4M__Fj53-cJaBnZZASd-aMTaSyWEQ-PC2",
      "publicKeyJwk": {
        "kid": "1AAAAmbFVu-Wf8NCd63B9V0zsy7EgB_ocX2_n_Nh1FCmgF0Y",
        "kty": "EC",
        "crv": "secp256k1",
        "x": "ZsVW75Z_w0J3rcH1XTOzLsSAH-hxfb-Q82HUUKaAXRg",
        "y": "Lu6Uw785U3K05D-NPNoUInHPNUz9cGqWwjKjm5KL8FI"
      }
    }
  ]

§ Thresholds

  1. If the current signing keys threshold (the value of the kt field) is a string containing a number that is greater than 1, or if it is an array containing fractionally weighted thresholds, then in addition to the verification methods generated according to the rules in the previous sections, another verification method with a type of ConditionalProof2022 MUST be generated in the DID document. This verification method type is defined here.
    1. It MUST be constructed according to the following rules:

      1. The id property of the verification method MUST be a relative DID URL and use the AID as the value of the fragment component, e.g., "id": "#<aid>".
      2. The controller property of the verification method MUST be the value of the id property of the DID document. (Does the method spec need to specify this?)
      3. If the value of the kt field is a string containing a number that is greater than 1 then the following rules MUST be applied:
        1. The threshold property of the verification method MUST be the integer value of the kt field in the current key state.
        2. The conditionThreshold property of the verification method MUST contain an array. For each key listed in the array value of the k field in the key state:
          1. The relative DID URL corresponding to the key MUST be added to the array value of the conditionThreshold property.
      4. If the value of the kt field is an array containing fractionally weighted thresholds then the following rules MUST be applied:
        1. The threshold property of the verification method MUST be half of the lowest common denominator (LCD) of all the fractions in the kt array.
        2. The conditionWeightedThreshold property of the verification method MUST contain an array. For each key listed in the array value of the k field in the key state, and for each corresponding fraction listed in the array value of the kt field:
          1. A JSON object MUST be added to the array value of the conditionWeightedThreshold property.
          2. The JSON object MUST contain a property condition whose value is the relative DID URL corresponding to the key.
          3. The JSON object MUST contain a property weight whose value is the numerator of the fraction after it has been expanded over the lowest common denominator (LCD) of all the fractions.

      For example, a KERI AID with only the following inception event in its KEL, and with a kt value greater than 1:

      {
        "v": "KERI10JSON0001b7_",
        "t": "icp",
        "d": "Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
        "i": "Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
        "s": "0",
        "kt": "2",  // Signing Threshold
        "k": [
          "1AAAAg299p5IMvuw71HW_TlbzGq5cVOQ7bRbeDuhheF-DPYk",  // Secp256k1 Key
          "DA-vW9ynSkvOWv5e7idtikLANdS6pGO2IHJy7v0rypvE",      // Ed25519 Key
          "DLWJrsKIHrrn1Q1jy2oEi8Bmv6aEcwuyIqgngVf2nNwu"       // Ed25519 Key
        ],
      }
      

      results in a DID document with the following verification methods array:

      {
        "verificationMethod": [
          {
            "id": "#Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
            "type": "ConditionalProof2022",
            "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
            "threshold": 2,
            "conditionThreshold": [
              "#1AAAAg299p5IMvuw71HW_TlbzGq5cVOQ7bRbeDuhheF-DPYk",
              "#DA-vW9ynSkvOWv5e7idtikLANdS6pGO2IHJy7v0rypvE",
              "#DLWJrsKIHrrn1Q1jy2oEi8Bmv6aEcwuyIqgngVf2nNwu"
            ]
          },
          {
            "id": "#1AAAAg299p5IMvuw71HW_TlbzGq5cVOQ7bRbeDuhheF-DPYk",
            "type": "JsonWebKey",
            "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
            "publicKeyJwk": {
              "kid": "1AAAAg299p5IMvuw71HW_TlbzGq5cVOQ7bRbeDuhheF-DPYk",
              "kty": "EC",
              "crv": "secp256k1",
              "x": "NtngWpJUr-rlNNbs0u-Aa8e16OwSJu6UiFf0Rdo1oJ4",
              "y": "qN1jKupJlFsPFc1UkWinqljv4YE0mq_Ickwnjgasvmo"
            }
          },
          {
            "id": "#DA-vW9ynSkvOWv5e7idtikLANdS6pGO2IHJy7v0rypvE",
            "type": "JsonWebKey",
            "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
            "publicKeyJwk": {
              "kid": "DA-vW9ynSkvOWv5e7idtikLANdS6pGO2IHJy7v0rypvE",
              "kty": "OKP",
              "crv": "Ed25519",
              "x": "A-vW9ynSkvOWv5e7idtikLANdS6pGO2IHJy7v0rypvE"
            }
          },
          {
            "id": "#DLWJrsKIHrrn1Q1jy2oEi8Bmv6aEcwuyIqgngVf2nNwu",
            "type": "JsonWebKey",
            "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
            "publicKeyJwk": {
              "kid": "DLWJrsKIHrrn1Q1jy2oEi8Bmv6aEcwuyIqgngVf2nNwu",
              "kty": "OKP",
              "crv": "Ed25519",
              "x": "LWJrsKIHrrn1Q1jy2oEi8Bmv6aEcwuyIqgngVf2nNws"
            }
          }
        ]
      }
      

      For example, a KERI AID with only the following inception event in its KEL, and a kt containing fractionally weighted thresholds:

      {
        "v": "KERI10JSON0001b7_",
        "t": "icp",
        "d": "Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
        "i": "Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
        "s": "0",
        "kt": ["1/2", "1/3", "1/4"],  // Signing Threshold
        "k": [
          "1AAAAg299p5IMvuw71HW_TlbzGq5cVOQ7bRbeDuhheF-DPYk",  // Secp256k1 Key
          "DA-vW9ynSkvOWv5e7idtikLANdS6pGO2IHJy7v0rypvE",      // Ed25519 Key
          "DLWJrsKIHrrn1Q1jy2oEi8Bmv6aEcwuyIqgngVf2nNwu"       // Ed25519 Key
        ],
      }
      

      would result in a DID document with the following verification methods array:

      {
        "verificationMethod": [
          {
            "id": "#Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
            "type": "ConditionalProof2022",
            "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
            "threshold": 12,
            "conditionWeightedThreshold": [
              {
                "condition": "#1AAAAg299p5IMvuw71HW_TlbzGq5cVOQ7bRbeDuhheF-DPYk",
                "weight": 6
              },
              {
                "condition": "#DA-vW9ynSkvOWv5e7idtikLANdS6pGO2IHJy7v0rypvE",
                "weight": 4
              },
              {
                "condition": "#DLWJrsKIHrrn1Q1jy2oEi8Bmv6aEcwuyIqgngVf2nNwu",
                "weight": 3
              }
            ]
          },
          {
            "id": "#1AAAAg299p5IMvuw71HW_TlbzGq5cVOQ7bRbeDuhheF-DPYk",
            "type": "EcdsaSecp256k1VerificationKey2019",
            "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
            "publicKeyJwk": {
              "crv": "secp256k1",
              "x": "NtngWpJUr-rlNNbs0u-Aa8e16OwSJu6UiFf0Rdo1oJ4",
              "y": "qN1jKupJlFsPFc1UkWinqljv4YE0mq_Ickwnjgasvmo",
              "kty": "EC",
              "kid": "WjKgJV7VRw3hmgU6--4v15c0Aewbcvat1BsRFTIqa5Q"
            }
          },
          {
            "id": "#DA-vW9ynSkvOWv5e7idtikLANdS6pGO2IHJy7v0rypvE",
            "type": "Ed25519VerificationKey2020",
            "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
            "publicKeyMultibase": "zH3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
          },
          {
            "id": "#DLWJrsKIHrrn1Q1jy2oEi8Bmv6aEcwuyIqgngVf2nNwu",
            "type": "Ed25519VerificationKey2020",
            "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
            "publicKeyMultibase": "zDqYpw38nznAUJeeFdhKBQutRKpyDXeXxxi1HjYUQXLas"
          }
        ]
      }
      

§ Verification Relationships

  1. If the value of kt == 1 then the following rules MUST be applied:
    1. For each public key in k and its corresponding verification method, two verification relationships MUST be generated in the DID document. One verification relationship of type authentication and one verification relationship of type assertionMethod.
      1. The authentication verification relationship SHALL define that the DID controller can authenticate using each key.
      2. The assertionMethod verification relationship SHALL define that the DID controller can express claims using each key.
  2. If the value of kt > 1 or if the value of kt is an array containing fractionally weighted thresholds then the following rules MUST be applied:
    1. For the verification method of type ConditionalProof2022 (see section Thresholds), two verification relationships MUST be generated in the DID document. One verification relationship of type authentication and one verification relationship of type assertionMethod.
      1. The authentication verification relationship SHALL define that the DID controller can authenticate using a combination of multiple keys above the threshold.
      2. The assertionMethod verification relationship SHALL define that the DID controller can express claims using a combination of multiple keys above the threshold.
  3. References to verification methods in the DID document MUST use the relative form of the identifier, e.g., "authentication": ["#<identifier>"].

Private keys of a KERI AID can be used to sign a variety of data. This includes but is not limited to logging into a website, challenge-response exchanges, credential issuances, etc.

§ Key Agreement

This section is informative:

There are multiple ways to establish key agreement in KERI. We detail common considerations and techniques:

§ Other Key Commitments

This section is informative.

Data structures similar to Location Scheme and Endpoint Authorizations and managed in KERI using BADA-RUN may be created and used for declaring other types of keys, for example encryption keys, etc

To support new data structures, propose them in KERI and detail the transformation in the spec.

§ Service Endpoints

  1. did:webs DIDs MUST support service endpoints, including types declared in the DID Specification Registries, such as DIDCommMessaging.

For additional details about the mapping between KERI events and the Service Endpoints in the DID Document, see Service Endpoint KERI events.

It is important to note that DID document service endpoints are different than the KERI service endpoints detailed in KERI Service Endpoints as DID Document Metadata.

§ KERI Service Endpoints as DID Document Metadata

  1. did:webs endpoints MUST be specified using the two data sets KERI uses to define service endpoints; Location Schemes and Endpoint Role Authorizations.

    1. Both MUST be expressed in KERI rpy events.
    2. For URL scheme endpoints that an AID has exposed, did:webs DIDs MUST use Location Schemes URLs.
    3. For endpoints that relate a role of one AID to another, did:webs DIDs MUST use KERI Endpoint Role Authorizations.

    For example, the following rpy method declares that the AID EIDJUg2eR8YGZssffpuqQyiXcRVz2_Gw_fcAVWpUMie1 exposes the URL http://localhost:3902 for scheme http:

    {
        "v": "KERI10JSON0000fa_",
        "t": "rpy",
        "d": "EOGL1KGpOnRaZDIB11uZDCkhHs52_MtMXHd7EqUqwtA3",
        "dt": "2022-01-20T12:57:59.823350+00:00",
        "r": "/loc/scheme",
        "a": {
          "eid": "EIDJUg2eR8YGZssffpuqQyiXcRVz2_Gw_fcAVWpUMie1",
          "scheme": "http",
          "url": "http://127.0.0.1:3901/"
        }
      }
    

    For example, the AID listed in cid is the source of the authorization, the role is the role and the AID listed in the eid field is the target of the authorization. So in this example EOGL1KGpOnRaZDIB11uZDCkhHs52_MtMXHd7EqUqwtA3 is being authorized as an Agent for EIDJUg2eR8YGZssffpuqQyiXcRVz2_Gw_fcAVWpUMie1.

    {
        "v": "KERI10JSON000116_",
        "t": "rpy",
        "d": "EBiVyW6jPOeHX5briFYMQ4CefzqIZHgl-rrcXqj_t9ex",
        "dt": "2022-01-20T12:57:59.823350+00:00",
        "r": "/end/role/add",
        "a": {
          "cid": "EIDJUg2eR8YGZssffpuqQyiXcRVz2_Gw_fcAVWpUMie1",
          "role": "agent",
          "eid": "EOGL1KGpOnRaZDIB11uZDCkhHs52_MtMXHd7EqUqwtA3"
        }
    }
    
  2. KERI service endpoints roles beyond witness SHOULD be defined using Location Scheme and Endpoint Authorization records in KERI.

The following table contains the current set of endpoint roles in KERI and maps the current roles in KERI to service type values in the resulting DID documentsis:

Role Description
controller The association of the key controller of an AID. These are always self-referential.
witness A witness for an AID. This role is already cryptographically committed to the KEL of the source AID and thus does not require and explicit rpy authroization event.
registrar Currently unused.
watcher A componenet serving as a Watcher as defined by the KERI protocol (beyond the scope of this document).
judge Currently unused.
juror Currently unused.
peer Currently unused.
mailbox A component authorized to serve as a store and forward mailbox for the source identifier. This component usually provides a persistent internet connection for AID controllers that are usually off line.
agent A component authorized to serve as an agent running with persistent internet connection. Provides more funcitonality than a mailbox

TODO: Detail the transformation with an example, for example:

{
  "service": [
      {
        "id":"#Bgoq68HCmYNUDgOz4Skvlu306o_NY-NrYuKAVhk3Zh9c",
        "type": "DIDCommMessaging", 
        "serviceEndpoint": "https://bar.example.com"
      }
      {
        "id":"#BuyRFMideczFZoapylLIyCjSdhtqVb31wZkRKvPfNqkw",
        "type": "KERIAgent", 
        "serviceEndpoint": {
          "tcp": "tcp://bar.example.com:5542",
          "https": "https://bar.example.com" 
        }
      }
  ]
}

TODO: Propose a new role in KERI to map to the existing DIDCommMessaging service type declared in DID Specification Registries.

In KERI, service endpoints are defined by 2 sets of signed data using Best Available Data - Read, Update, Nullify (BADA-RUN) rules for data processing. The protocol ensures that all data is signed in transport and at rest and versioned to ensure only the latest signed data is available.

§ Transformation to did:web DID Document

The DID document that exists as a resource on a webserver is compatible with the did:web DID method and therefore necessarily different from a did:webs DID document with regard to the id, controller, and alsoKnownAs properties.

  1. To transform the did:web form of the DID Document to a did:webs the transformation MUST do the following:

    1. In the values of the top-level id and controller properties of the DID document, the transformation MUST replace the did:webs prefix string with did:web.
    2. In the value of the top-level alsoKnownAs property, the transformation MUST replace the entry that is now the new value of the id property (using did:web) with the old value of the id property (using did:webs).
    3. All other content of the DID document MUST not be modified.

    For example, this transformation is used during the Create DID method operation, given the following did:webs DID document:

    {
      "id": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
      "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
      "alsoKnownAs": [
        "did:web:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
        "did:webs:foo.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
        "did:keri:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M"
      ],
      ...
    }
    

    the result of the transformation algorithm is the following did:web DID document:

    {
      "id": "did:web:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
      "controller": "did:web:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
      "alsoKnownAs": [
        "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
        "did:webs:foo.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
        "did:keri:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M"
      ],
      ...
    }
    

§ Transformation to did:webs DID Document

This section defines an inverse transformation algorithm from a did:web DID document to a did:webs DID document.

  1. Given a did:web DID document, a transformation to a did:webs DID document MUST have the following differences:

    1. The values of the top-level id and controller properties of the DID document MUST be replaced; the did:web prefix string with did:webs.
    2. The value of the top-level alsoKnownAs property MUST replace the entry that is now the new value of the id property (using did:webs) with the old value of the id property (using did:web).
    3. All other content of the DID document MUST not be modificatied.
  2. A did:webs resolver MUST use this transformation during the Read (Resolve) DID method operation.

    For example, given the following did:web DID document:

    {
      "id": "did:web:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
      "controller": "did:web:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
      "alsoKnownAs": [
        "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
        "did:webs:foo.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
        "did:keri:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M"
      ],
      ...
    }
    

    the result of the transformation algorithm is the following did:webs DID document:

    {
      "id": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
      "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
      "alsoKnownAs": [
        "did:web:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
        "did:webs:foo.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
        "did:keri:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M"
      ],
      ...
    }
    

§ Full Example

This section is informative.

The following blocks contain full annotated examples of a KERI AID with two events, an inception event and an interaction event, some witnesses, multiple public signing and rotation keys and an Agent with the resulting DID document that an implementation would generate assuming the implementation was running on the example.com domain with no unique port and no additional path defined:

{
    "v": "KERI10JSON0001b7_",
    "t": "icp",
    "d": "Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
    "i": "Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
    "s": "0",
    "kt": "2",  // Signing Threshold
    "k": [
      "1AAAAg299p5IMvuw71HW_TlbzGq5cVOQ7bRbeDuhheF-DPYk",  // Secp256k1 Key
      "DA-vW9ynSkvOWv5e7idtikLANdS6pGO2IHJy7v0rypvE",      // Ed25519 Key
      "DLWJrsKIHrrn1Q1jy2oEi8Bmv6aEcwuyIqgngVf2nNwu"       // Ed25519 Key
    ],
    "nt": "2",
    "n": [
      "Eao8tZQinzilol20Ot-PPlVz6ta8C4z-NpDOeVs63U8s",
      "EAcNrjXFeGay9qqMj96FIiDdXqdWjX17QXzdJvq58Zco",
      "EPoly9Tq4IPx41U-AGDShLDdtbFVzt7EqJUHmCrDxBdb"
    ],
    "bt": "3",
    "b": [
      "BGKVzj4ve0VSd8z_AmvhLg4lqcC_9WYX90k03q-R_Ydo",
      "BuyRFMideczFZoapylLIyCjSdhtqVb31wZkRKvPfNqkw",
      "Bgoq68HCmYNUDgOz4Skvlu306o_NY-NrYuKAVhk3Zh9c"
    ],
    "c": [],
    "a": []
  }
...
{
  "v": "KERI10JSON00013a_",
  "t": "ixn",
  "d": "Ek48ahzTIUA1ynJIiRd3H0WymilgqDbj8zZp4zzrad-w",
  "i": "Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
  "s": "1",
  "p": "Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
  "a": [
    {
      "i": "EoLNCdag8PlHpsIwzbwe7uVNcPE1mTr-e1o9nCIDPWgM",
      "s": "0",
      "d": "EoLNCdag8PlHpsIwzbwe7uVNcPE1mTr-e1o9nCIDPWgM"
    }
  ]
}
...
{
  "v": "KERI10JSON000116_",
  "t": "rpy",
  "d": "EBiVyW6jPOeHX5briFYMQ4CefzqIZHgl-rrcXqj_t9ex",
  "dt": "2022-01-20T12:57:59.823350+00:00",
  "r": "/end/role/add",
  "a": {
    "cid": "Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
    "role": "agent",
    "eid": "EIDJUg2eR8YGZssffpuqQyiXcRVz2_Gw_fcAVWpUMie1"
  }
}
...
{
  "v": "KERI10JSON000116_",
  "t": "rpy",
  "d": "EBiVyW6jPOeHX5briFYMQ4CefzqIZHgl-rrcXqj_t9ex",
  "dt": "2022-01-20T12:57:59.823350+00:00",
  "r": "/end/role/add",
  "a": {
    "cid": "EIDJUg2eR8YGZssffpuqQyiXcRVz2_Gw_fcAVWpUMie1",
    "role": "controller",
    "eid": "EIDJUg2eR8YGZssffpuqQyiXcRVz2_Gw_fcAVWpUMie1"
  }
}
...
{
  "v": "KERI10JSON0000fa_",
  "t": "rpy",
  "d": "EOGL1KGpOnRaZDIB11uZDCkhHs52_MtMXHd7EqUqwtA3",
  "dt": "2022-01-20T12:57:59.823350+00:00",
  "r": "/loc/scheme",
  "a": {
    "eid": "EIDJUg2eR8YGZssffpuqQyiXcRVz2_Gw_fcAVWpUMie1",
    "scheme": "http",
    "url": "http://foo.example.com:3901/"
  }
}


...
{
  "v": "KERI10JSON000116_",
  "t": "rpy",
  "d": "EBiVyW6jPOeHX5briFYMQ4CefzqIZHgl-rrcXqj_t9ex",
  "dt": "2022-01-20T12:57:59.823350+00:00",
  "r": "/end/role/add",
  "a": {
    "cid": "EIDJUg2eR8YGZssffpuqQyiXcRVz2_Gw_fcAVWpUMie1",
    "role": "controller",
    "eid": "EIDJUg2eR8YGZssffpuqQyiXcRVz2_Gw_fcAVWpUMie1"
  }
}
...
{
  "v": "KERI10JSON0000fa_",
  "t": "rpy",
  "d": "EOGL1KGpOnRaZDIB11uZDCkhHs52_MtMXHd7EqUqwtA3",
  "dt": "2022-01-20T12:57:59.823350+00:00",
  "r": "/loc/scheme",
  "a": {
    "eid": "EIDJUg2eR8YGZssffpuqQyiXcRVz2_Gw_fcAVWpUMie1",
    "scheme": "http",
    "url": "http://foo.example.com:3901/"
  }
}

Resulting DID document:

  "didDocument": {
    "id": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
    "alsoKnownAs": [
      "did:web:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
      "did:keri:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M"
    ],
    "verificationMethod": [
      {
        "id": "#Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
        "type": "ConditionalProof2022",
        "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
        "threshold": 2,
        "conditionThreshold": [
          "#1AAAAg299p5IMvuw71HW_TlbzGq5cVOQ7bRbeDuhheF-DPYk",
          "#DA-vW9ynSkvOWv5e7idtikLANdS6pGO2IHJy7v0rypvE",
          "#DLWJrsKIHrrn1Q1jy2oEi8Bmv6aEcwuyIqgngVf2nNwu"
        ]
      },
      {
        "id": "#1AAAAg299p5IMvuw71HW_TlbzGq5cVOQ7bRbeDuhheF-DPYk",
        "type": "JsonWebKey",
        "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
        "publicKeyJwk": {
          "kid": "1AAAAg299p5IMvuw71HW_TlbzGq5cVOQ7bRbeDuhheF-DPYk",
          "kty": "EC",
          "crv": "secp256k1",
          "x": "NtngWpJUr-rlNNbs0u-Aa8e16OwSJu6UiFf0Rdo1oJ4",
          "y": "qN1jKupJlFsPFc1UkWinqljv4YE0mq_Ickwnjgasvmo"
        }
      },
      {
        "id": "#DA-vW9ynSkvOWv5e7idtikLANdS6pGO2IHJy7v0rypvE",
        "type": "JsonWebKey",
        "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
        "publicKeyJwk": {
          "kid": "DA-vW9ynSkvOWv5e7idtikLANdS6pGO2IHJy7v0rypvE",
          "kty": "OKP",
          "crv": "Ed25519",
          "x": "A-vW9ynSkvOWv5e7idtikLANdS6pGO2IHJy7v0rypvE"
        }
      },
      {
        "id": "#DLWJrsKIHrrn1Q1jy2oEi8Bmv6aEcwuyIqgngVf2nNwu",
        "type": "JsonWebKey",
        "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
        "publicKeyJwk": {
          "kid": "DLWJrsKIHrrn1Q1jy2oEi8Bmv6aEcwuyIqgngVf2nNwu",
          "kty": "OKP",
          "crv": "Ed25519",
          "x": "LWJrsKIHrrn1Q1jy2oEi8Bmv6aEcwuyIqgngVf2nNws"
        }
      }
    ],
    "authentication": [
      "#Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M"
    ],
    "assertionMethod": [
      "#Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M"
    ],
    "service": [
      {
        "id": "#EIDJUg2eR8YGZssffpuqQyiXcRVz2_Gw_fcAVWpUMie1",
        "type": "KeriAgent",
        "serviceEndpoint": "http://foo.example.com:3901/"
      }
    ]
  }...

§ Basic KERI event details

DID Document from KERI Events introduced the core KERI event stream and related DID Document concepts. This section provides additional details regarding the basic types of KERI events and how they relate to the DID document.

§ Key state events

  1. When processing the KERI event stream did:webs MUST account for two broad types of key state events (KERI parlance is ‘establishment events’) that can alter the key state of the AID.
  2. Any change in key state of the AID MUST be reflected in the DID document.
  3. If a key state event does not commit to a future set of rotation key hashes, then the AID SHALL NOT be rotated to new keys in the future (KERI parlance is that the key state of the AID becomes ‘non-transferrable’).
  4. If a key state event does commit to a future set of rotation key hashes, then any future key state rotation MUST be to those commitment keys. This foundation of pre-rotation is post-quantum safe and allows the did:webs controller to recover from key compromise.
  5. The Inception event MUST be the first event in the KEL that establishes the AID.
    1. This MUST define the initial key set
    2. If the controller(s) desire future key rotation (transfer) then the inception event MUST commit to a set of future rotation key hashes.
    3. When processing the KERI event stream, if there are no rotation events after the inception event, then this is the current key state of the AID and MUST be reflected in the DID Document as specified in Verification Methods and Verification Relationships.
  6. Rotation events MUST come after inception events.
  7. If the controller(s) desires future key rotation (transfer) then the rotation event MUST commit to a set of future rotation key hashes.
  8. Rotation events MUST only change the key state to the previously committed to rotation keys.
  9. The last rotation event is the current key state of the AID and MUST be reflected in the DID Document as specified in Verification Methods and Verification Relationships.

You can learn more about the inception event in the KERI specification and you can see an example inception event. To learn about future rotation key commitment, see the sections about pre-rotation and the KERI specification.

You can learn more about rotation events in the KERI specification and you can see an example rotation event. To learn about future rotation key commitment, see the sections about pre-rotation and the KERI specification.

§ Delegation KERI event details

This section focuses on delegation relationships between KERI AIDs. DID Document from KERI Events introduced the core KERI event stream and related DID Document concepts. This section provides additional details regarding the basic types of KERI events and how they relate to the DID document. Basic KERI event details provides additional details on the basic types of KERI events and how they relate to the DID document.

§ Delegation key state events

  1. All delegation relationships MUST start with a delegated inception event.
  2. Any change to the Delegated inception event key state or delegated rotation event key state MUST be the result of a delegated rotation event.

Delegated inception event: Establishes a delegated identifier. Either the delegator or the delegate can end the delegation commitment.

Delegated rotation event: Updates the delegated identifier commitment. Either the delegator or the delegate can end the delegation commitment.

See the KERI specification for an example of a delegated inception and rotation events.

§ Service Endpoint event details

TODO: Define and detail the service endpoint events

§ Designated Aliases

  1. An AID controller SHALL specify the designated aliases that will be listed in the equivalentId and alsoKnownAs properties by issuing a designated aliases verifiable attestation.
    1. This attestation MUST contain a set of AID controlled identifiers that the AID controller authorizes.
    2. If the identifier is a did:webs identifier then it is truly equivalent and MUST be listed in the equivalentId property.
    3. If the identifier is a DID then it MUST be listed in the alsoKnownAs property.

§ Designated Aliases event details

This is an example designated aliases ACDC attestation showing two designated aliases:

{
    "v": "ACDC10JSON000514_",
    "d": "EMVnFMfhcw67coSNnH5nqi5fWtFreCNuw6pGVGdMFuSx",
    "i": "ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
    "ri": "EFfjfmq3DiHAbVWiF4VA24fP5OEIV1EhWoO-v3ZqmVG6",
    "s": "EN6Oh5XSD5_q2Hgu-aqpdfbVepdpYpFlgz6zvJL5b_r5",
    "a": {
        "d": "EHQgqNNSueVmVjlErrGtzjl-HJya9rMUiNadDSkZQ1kV",
        "dt": "2023-11-13T17:41:37.710691+00:00",
        "ids": [
            "did:webs:foo.com:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
            "did:web:example.com:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe"
        ]
    },
    "r": {
        "d": "EEVTx0jLLZDQq8a5bXrXgVP0JDP7j8iDym9Avfo8luLw",
        "aliasDesignation": {
            "l": "The issuer of this ACDC designates the identifiers in the ids field as the only allowed namespaced aliases of the issuer's AID."
        },
        "usageDisclaimer": {
            "l": "This attestation only asserts designated aliases of the controller of the AID, that the AID controlled namespaced alias has been designated by the controller. It does not assert that the controller of this AID has control over the infrastructure or anything else related to the namespace other than the included AID."
        },
        "issuanceDisclaimer": {
            "l": "All information in a valid and non-revoked alias designation assertion is accurate as of the date specified."
        },
        "termsOfUse": {
            "l": "Designated aliases of the AID must only be used in a manner consistent with the expressed intent of the AID controller."
        }
    }
}

The resulting DID document based on the designated aliases attestation above, contains:

{
  "didDocument": {
    "id": "did:webs:example.com:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
    "alsoKnownAs": [
      "did:webs:foo.com:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
      "did:web:example.com:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
      "did:keri:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe"
    ],
    "verificationMethod": [...
  }
  "didDocumentMetadata": {
    "equivalentId": [
      "did:webs:foo.com:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
    ]
  }
}

§ DID Parameters

This section is normative.

This section describes the support of the did:webs method for certain DID parameters.

§ Support for versionId

The did:webs DID method supports the versionId DID parameter. This DID parameter is defined here.

This allows clients to instruct a DID Resolver to return a specific version of a DID document, as opposed to the latest version. The did:webs DID method is ideally suited for this functionality, since a continuous, self-certifying stream of events lies at the heart of the DID method’s design, see section KERI Fundamentals.

  1. Valid values for this DID parameter MUST be the sequence numbers of events in the KERI event stream.
  2. When a did:webs DID is resolved with this DID parameter, a did:webs resolver MUST constructs the DID document based on an AID’s associated KERI events from the KERI event stream only up to (and including) the event with the sequence number (i.e. the s field) that corresponds to the value of the versionId DID parameter.

See section DID Document from KERI Events for details.

Example:

did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M?versionId=1

§ Support for transformKeys

The did:webs DID method supports the transformKeys DID parameter. This DID parameter is defined here.

  1. This parameter MUST be implemented for a DID Resolver to return verification methods in a DID document in a desired format, such as JsonWebKey or Ed25519VerificationKey2020.

Example:

did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M?transformKeys=CesrKey

§ CesrKey and publicKeyCesr

This specification defines the following extensions to the DID document data model in accordance with the DID Spec Registries:

  1. Extension verification method type CesrKey MAY be available in a did:webs DID document to express a public key encoded in CESR format.
  2. Extension verification method property publicKeyCesr MAY be available in a did:webs DID document to provide a string value whose content is the CESR representation of a public key.
  3. The verification method type CesrKey MAY be used as the value of the transformKeys DID parameter.

For example, a KERI AID with only the following inception event in its KEL:

{
  "v": "KERI10JSON0001b7_",
  "t": "icp",
  "d": "Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
  "i": "Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
  "s": "0",
  "kt": "1",
  "k": [
    "1AAAAg299p5IMvuw71HW_TlbzGq5cVOQ7bRbeDuhheF-DPYk",  // Secp256k1 Key
    "DA-vW9ynSkvOWv5e7idtikLANdS6pGO2IHJy7v0rypvE",      // Ed25519 Key
    "DLWJrsKIHrrn1Q1jy2oEi8Bmv6aEcwuyIqgngVf2nNwu"       // Ed25519 Key
  ],
  // ...
}

and given the following the DID URL:

did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M?transformKeys=CesrKey

would result in a DID document with the following verification methods array:

{
  "verificationMethod": [
    {
      "id": "#1AAAAg299p5IMvuw71HW_TlbzGq5cVOQ7bRbeDuhheF-DPYk",
      "type": "CesrKey",
      "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
      "publicKeyCesr": "1AAAAg299p5IMvuw71HW_TlbzGq5cVOQ7bRbeDuhheF-DPYk"
    },
    {
      "id": "#DA-vW9ynSkvOWv5e7idtikLANdS6pGO2IHJy7v0rypvE",
      "type": "CesrKey",
      "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
      "publicKeyCesr": "DA-vW9ynSkvOWv5e7idtikLANdS6pGO2IHJy7v0rypvE"
    },
    {
      "id": "#DLWJrsKIHrrn1Q1jy2oEi8Bmv6aEcwuyIqgngVf2nNwu",
      "type": "CesrKey",
      "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
      "publicKeyCesr": "DLWJrsKIHrrn1Q1jy2oEi8Bmv6aEcwuyIqgngVf2nNwu"
    }
  ]
}

§ DID Metadata

This section is normative.

This section describes the support of the did:webs method for metadata, including DID resolution metadata and DID document metadata. This metadata is returned by a DID Resolver in addition to the DID document. Also see the DID Resolution specification for further details.

§ DID Resolution Metadata

At the moment, this specification does not define the use of any specific DID resolution metadata properties in the did:webs method, but may in the future include various metadata, such as which KERI Watchers were used during the resolution process.

§ DID Document Metadata

This section of the specification defines how various DID document metadata properties are used by the did:webs method.

§ Use of versionId

The versionId DID document metadata property indicates the current version of the DID document that has been resolved.

  1. The did:webs versionId MUST be the sequence number (i.e. the s field) of the last event in the KERI event stream that was used to construct the DID document according to the rules in section DID Document from KERI Events.
  2. If the DID parameter versionId (see section Support for versionId) was used when resolving the did:webs DID, and if the DID Resolution process was successful, then this corresponding DID document metadata property MUST be guaranteed to be equal to the value of the DID parameter.

Example:

{
  "didDocument": {
    "id": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M"
    // ... other properties
  },
  "didResolutionMetadata": {
  },
  "didDocumentMetadata": {
    "versionId": "2"
  }
}

§ Use of nextVersionId

The nextVersionId DID document metadata property indicates the next version of the DID document after the version that has been resolved.

  1. The did:webs nextVersionId MUST be the sequence number (i.e. the s field) of the next event in the KERI event stream after the last one that was used to construct the DID document according to the rules in section DID Document from KERI Events.
  2. This DID document metadata property MUST be present if the DID parameter versionId (see section Support for versionId) was used when resolving the did:webs DID, and if the value of that DID parameter was not the sequence number of the last event in the KERI event stream.

Example:

{
  "didDocument": {
    "id": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M"
    // ... other properties
  },
  "didResolutionMetadata": {
  },
  "didDocumentMetadata": {
    "versionId": "1",
    "nextVersionId": "2"
  }
}

§ Use of equivalentId

The equivalentId DID document metadata property indicates other DIDs that refer to the same subject and are logically equivalent to the DID that has been resolved. It is similar to the alsoKnownAs DID document property (see section Also Known As), but it has even stronger semantics, insofar as the logical equivalence is guaranteed by the DID method itself.

  1. The did:webs equivalentId metadata property SHOULD contain a list of the controller AID designated aliases did:webs DIDs that differ in the host and/or port portion of the method-specific identifier but share the same AID. Also see section AID controlled identifiers.
  2. equivalentId depends on the controller AIDs array of designated aliases. A did:webs identifier MUST not verify unless it is found in the equivalentId metadata that corresponds to the designated aliases.

Note that AID controlled identifiers like did:web and did:keri identifiers with the same AID are not listed in equivalentId because they do not have the same DID method. A did:web identifier with the same domain and AID does not have the same security characteristics as the did:webs identifier. Conversely, a did:keri identifier with the same AID has the same security characterisitcs but not the same dependence on the web. For these reasons, they are not listed in equivalentId.

Example:

{
  "didDocument": {
    "id": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M"
    // ... other properties
  },
  "didResolutionMetadata": {
  },
  "didDocumentMetadata": {
    "equivalentId": [
      "did:webs:example.com%3A8080:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
      "did:webs:foo.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
      "did:webs:bar.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M"
    ]    
  }
}

§ Signed Files

This section is normative.

did:webs signed files combine the semantics of folders of files on web servers, and the DID Specification's DID URL path semantics to enable the controller of the DID to publish documents cryptographically signed using the verification key(s) of the DID. This kind of signed file capability has been implemented in a variety of ways in the past, such as with hashlinks. The value of including this as part of the did:webs DID method is that it ensures consistency in its application, including how the signed files can be verified when using a multisig-enabled DID, and in the face of rotations of the DID’s key(s).

  1. In publishing a file, the controller of the DID MAY use the KERI TEL to record the signing event, prior to publishing the file. In that case, in processing the KERI Audit log, the publication event MUST be found, verified, and ordered relative to key state changes and other signing events.

  2. If the file is NOT KEL backed data or if the controller would like to provide additional signature, the controller MUST do the following:

    1. The controller of the DID MAY place arbitrary files into the folder structure below the root did:webs folder.
    2. The DID URL for the signed file MUST be of the form <did:webs DID>/<path to file>.
    3. The HTTPS path to the file MUST be <HTTPS URL conversion of did:webs identifier>/<path to file>.
    4. To be a valid did:webs signed file, each file MUST have an associated JSON Web Signature file named <filename>.jws beside (in the same Web folder as) the file. For example, a file revocation_registry.bin MUST have a file revocation_registry.bin.jws beside it.
    5. The HTTPS path to the associated JWS file MUST be <HTTPS URL conversion of did:webs identifier>/<path to file>.jws.
    6. The JWS web signature MUST apply the following rules:
      1. MUST use the JSON Serialization form of the JWS. This is necessary to support multi-signatures in the JWS.
      2. MUST have a payload that is the [multiformat multihash] hash of the content of the associated signed file.
      3. MUST be signed with a verification key(s) that is (are) either currently in the DIDDoc of the DID, or found in the KEL associated with the DID. A verification key found in a valid KEL represents a key that had been in use previously, but has been rotated away.
      4. MUST be verified such that:
        1. A calculated hash of the file MUST match the hash in the JWS.
        2. The signature(s) in the JWS MUST be valid.
        3. If the DID has (or had at the time of signing) multisig requirements, those requirements MUST be met.

See:

The following is informative. Examples:

The core use case for this feature is providing an easy way for a DID controller to publish files such that those receiving the file can be confident that the file was explicitly published by the DID controller (they signed it), and has not been tampered with since it was published. A few examples of where this might be useful in verifiable credential-related use cases include:

See:

§ The whois DID URL

This convention enables those that receive the DID to retrieve and verify the verifiable presentation (and embedded Verifiable Credentials) the DID controller has decided to publish about itself. The intention is that anyone interested in a particular did:webs DID can see if there is a whois Verifiable Presentation, and if so, if it contains any useful (to the resolver) Verifiable Credentials that might help in learning more about who is the controller of the DID.

§ whois DID URL Conventions

  1. The whois object, if it exists, MUST be directly beside the did.json file, the DID Document for the DID.
  2. The DID URL path to whois MUST be <did:webs DID>/whois.
  3. The HTTPS path to the whois MUST be like <HTTPS URL conversion of did:webs identifier>/whois.vp.
  4. If the whois is present, the web server that serves the did:webs documents MUST respond to a request for the HTTPS whois URL with the verifiable presentation published there by the DID controller.
  5. If the controller of the did:webs DID has not published a whois verifiable presentation, the web server MUST respond with an HTTP 404 response (“Not Found”).
  6. The resolved whois DID URL MUST resolve to a verifiable presentation in which the presentation proof is signed by a key or keys from the current did:webs DID Document or a valid previous version of the DID Document.
  7. All of the verifiable credentials in the verifiable presentation MUST have the did:webs DID as the credential subject.
  8. The verifiable presentation MUST be in one of three formats:
    1. A W3C Verifiable Credentials Data Model Standard JSON-LD Data Integrity Proof Verifiable Presentation MAY be used.
    2. A W3C Verifiable Credentials Data Model Standard JSON Web Token Verifiable Presentation MAY be used.
    3. An ACDC or ACDC IPEX disclosure MAY be used.
  9. When the verifiable presentation is requested, the resolved object MUST contain the appropriate MIME type of the verifiable presentation format.

It is up to the DID Controller to decide to publish a verifiable presentation and if so, which Verifiable Credentials to put into the verifiable presentation.

§ whois Use Case

This section is informative.

The following is a use case for this capability. Consider an example of the did:webs controller being an educational institution that issues “degree” verifiable credentials to its graduate students. A graduate from the school submits as part of their job application to a company a Verifiable Presentation derived from the verifiable credential they received from the school. The company receiving the presentation can verify the cryptography of the presentation, but can they trust the school that issued the verifiable credential? If the school issued the verifiable credential using its did:webs DID, the company can resolve the DID. It can also resolve the DID’s whois DID URL where it might find VCs from issuers it trusts with the did:webs DID as the subject. For example:

Such checks can all be done with a handful of HTTPS requests and the processing of the DIDs and verifiable presentations. The result is an efficient, verifiable, credential-based, decentralized, multi-domain trust registry.

§ KERI Fundamentals

This section is informative.

Key Event Receipt Infrastructure (KERI) is a protocol for managing cryptographic keys, identifiers, and associated verifiable data structures. KERI was first described in an academic paper, and its specification is currently incubated under Trust Over IP Foundation. The open source community that develops KERI-related technologies can be found at https://github.com/WebOfTrust. This section outlines the fundamentals and components of the KERI protocol that are related to the did:webs method.

§ Autonomic Identifier (AID)

An autonomic identifier (AID) is a globally-unique persistent self-certifying identifier that serves as the primary root-of-trust of the KERI protocol. An AID is cryptographically bound to a KEL that determines the evolution of its key state using the pre-rotation mechanism. AIDs and the underlying KERI protocol, by themselves, satisfy most of the properties that DIDs require, including decentralization, control, security, proof-based, and portability. For example, DIDs that have the same AID component are considered equivalent, allowing AIDs to be portable across different DID methods such as did:webs and did:keri.

§ Key Event Log (KEL)

The binding between an AID and its cryptographic keys is proved by a data structure called a key event log (KEL) that allows the key states of the AID to evolve. For a did:webs DID, a KEL is an essential component in the KERI event stream that is used to verify its authenticity.

A KEL is a hash-chain append-only log and can be considered a variant of blockchain. However, a KEL differs from the traditional blockchain technology in at least two important ways:

These properties allows a KEL to be published anywhere, without special guarantees from its storage mechanism. For example, a KEL of an AID could be published and migrated between different KERI-compatible blockchain networks that use different DID methods. A KEL also records changes to key types and cryptographic algorithms, providing the AID portability and adaptability to multiple ecosystems throughout its lifecycle.

§ AID Derivation

The value of an AID is derived from the first key event, called the inception event, of a KEL. The inception event includes inital public key(s), called the current key(s), that can be used to control the AID. The cryptographic relationship between the AID and its keys eliminates an early chain-of-custody risk that plagues many other DID methods where an attacker uses compromised keys to create a DID without the DID controller’s knowledge. This derivation process is similar to techniques used by did:key, did:peer, did:sov, and did:v1.

The simplest AIDs, called non-transferrable direct mode AIDs, have no additional input to the derivation function, and expose a degenerate KEL that can hold only the inception event. This KEL is entirely derivable from the AID itself, and thus requires no external data. Non-transferrable direct mode AIDs are ideal for ephemeral use cases and are excellent analogs to did:key and did:peer with numalgo=0. This is by no means not the only option as KERI offers richer choices that are especially valuable if an AID is intended to have a long lifespan.

§ Pre-rotation

Public keys in the Verification Methods of a did:webs DID can be changed via a mechanism called pre-rotation. With pre-rotation, the inception event of the associated AID also includes the hash(s) of the next key(s) that can be used to change the key state of the AID. AIDs with one or more pre-rotated next keys are called transferrable AIDs because their control can be transferred to new keys. AIDs that do not use pre-rotation cannot change their keys and are thus non-transferrable.

Pre-rotation has profound security benefits. If a malicious party steals the current private key for a transferrable AID, they only accomplish temporary mischief, because the already-existing KEL contains a commitment to a future state. This prevents them from rotating the stolen AID’s key to an arbitrary value of their choosing. As soon as the AID controller suspects a compromise, they can change the key state of the AID using the pre-rotated next key and locks the attacker out again.

§ Weighted Multisig

The KERI protocol supports weighted multi-signature scheme that allows for conditional proof in the Verification Methods. A multisig AID distribute its control among multiple key holders. This includes simple M-of-N rules such as “3 of 5 keys must sign to change the AID’s key state”. More sophisticated configurations are also supported: “Acme Corp’s AID is controlled by the keys of 4 of 7 board members, or by the keys of the CEO and 2 board members, or by the keys of the CEO and the Chief Counsel.”

The security and recovery benefits of this feature are obvious when an AID references organizational identity. However, even individuals can benefit from this, when stakes are high. They simply store different keys on different devices, and then configure how their devices constitute a management quorum. This decreases risks from lost phones, for example.

§ Witnesses

In the direct mode, the controller of an AID is responsible for the distribution of its KEL. Since the controller may not be highly available, the controller may designate additional supporting infrastructure, called witnesses, for the indirect mode distribution of the KELs. Witnessess may or may not be under direct control of the AID’s controller and could be deployed on either centralized or decentralized architectures, including blockchains. The witnesses are embedded in the AID’s key event and, if included in the inception event, alter the AID value.

Unlike a blockchain with a distributed consensus mechanism, witnesses do not coordinate or come to consensus with one another during an update to its AID’s key event history. Hence, they need not be deeply trustworthy; merely by existing, they improve trust. This is because anyone changing an AID’s key state or its set of witnesses, including the AID’s legitimate controller, has to report those changes to the witnesses that are currently active, to produce a valid evolution of the KEL. The AID controller and all witnesses thus hold one another accountable. Further, it becomes possible to distinguish between duplicity and imperfect replication of key states.

§ Transaction Event Log (TEL)

KERI supports an official verifiable data structure, called the transaction event log (TEL), that binds an AID to important, non-repudiable actions that must relate with deterministic order to the key event history in the KEL. Transactions that are recorded in a TEL include, for instance, issuance and revocation of verifiable credentials, or the starting or stopping of listeners on a service endpoint. Like KELs, TELs are self-certifying and may also be published by witnesses to enhance discoverability and accountability.

§ Web Independence

Although this DID method depends on web technology, KERI itself does not. It’s as easy to create AIDs on IOT devices as it is on the web. AIDs offer the same features regardless of their origin and besides HTTP, they are shareable over Lo-Ra, Bluetooth, NFC, Low Earth Orbit satellite protocols, service buses on medical devices, and so forth. Thus, KERI’s AIDs offer a bridge between a web-centric DID method and lower-level IOT ecosystems.

§ Flexible Serialization

KELs and TELs of did:webs DIDs (i.e., AIDs) are included in the KERI event streams for verification of the DID documents. The KERI event streams use Composable Event Streaming Representation ([[ref: CESR)]] for data serialization. Although CESR is a deep subject all by itself, at a high level, it has two essential properties:

Despite this rich set of features, KERI imposes only light dependencies on developers. The cryptography it uses is familiar and battle-hardened, exactly what one would find in standard cryptography toolkits. For example, the python implementation (keripy) only depends on the pysodium, blake3, and cryptography python packages. Libraries for KERI exist in javascript, rust, and python.

§ IANA Considerations

This section is normative.

  1. This document has no IANA actions.

§ Security Considerations

This section is normative.

There are many security considerations related to web requests, storing information securely, etc. It is useful to address these considerations along with the common security threats found on the web.

§ Common security threats

  1. All did:webs features MUST reduce the attack surface against common threats:
    1. Broken Object Level Authorization (BOLA) attacks MUST be eliminated or reduced.
    2. Denial of service (DoS) attacks MUST be eliminated or reduced.
    3. Deletion attacks MUST be eliminated or reduced.
    4. Duplicity detection MUST be available and reliable.
    5. Eclipse attacks MUST be eliminated or reduced.
    6. Forgery attacks MUST be eliminated or reduced.
    7. Impersonation attacks MUST be eliminated or reduced.
    8. Key Compromise attacks MUST be eliminated or reduced.
    9. Malleability attacks MUST be eliminated or reduced.
    10. Replay attacks MUST be eliminated or reduced.

§ Using HTTPS

Perfect protection from eavesdropping is not possible with HTTPS, for various reasons.

  1. URLs of DID documents and KERI event streams SHOULD be hosted in a way that embodies accepted cybersecurity best practice. This is not strictly necessary to guarantee the authenticity of the data. However, the usage:
    1. MUST safeguard privacy
    2. MUST discourage denial of service
    3. MUST work in concert with defense-in-depth mindset
    4. MUST aid regulatory compliance
    5. MUST allow for high-confidence fetches of the DID document and a KERI event stream
  2. A host that uses a fully qualified domain name of the method-specific identifier MUST be secured by a TLS/SSL certificate.
    1. The fully qualified domain name MUST match the common name used in the SSL/TLS certificate.
    2. The common name in the SSL/TLS certificate from the server MUST correspond to the way the server is referenced in the URL. This means that if the URL includes www.example.com, the common name in the SSL/TLS certificate must be www.example.com as well.
  3. Unlike did:web, the URL MAY use an IP address instead.
    1. If it does, then the common name in the certificate MUST be the IP address as well.
  4. Essentially, the URL and the certificate MUST NOT identify the server in contradictory ways; subject to that constraint, how the server is identified is flexible.
    1. The server certificate MAY be self-issued
    2. OR it MAY chain back to an unknown certificate authority. However, to ensure reasonable security hygiene, it MUST be valid. This has two meanings, both of which are required:
  5. The certificate MUST satisfy whatever requirements are active in the client, such that the client does accept the certificate and use it to build and communicate over the encrypted HTTPS session where a DID document and KERI event stream are fetched.
  6. The certificate MUST pass some common-sense validity tests, even if the client is very permissive:
    1. It MUST have a valid signature
    2. It MUST NOT be expired or revoked or deny-listed
    3. It MUST NOT have any broken links in its chain of trust.
  7. If a URL of a DID document or KERI event streams results in a redirect, each URL MUST satisfy the same security requirements. www.example.com as well.

§ International Domain Names

  1. As with did:web, implementers of did:webs SHOULD consider how non-ASCII characters manifest in URLs and DIDs.
    1. did:webs MUST follow the DID-CORE identifier syntax which does not allow the direct representation of such characters in method name or method specific identifiers. This prevents a did:webs value from embodying a homograph attack.
    2. However, did:webs MAY hold data encoded with punycode or percent encoding. This means that IRIs constructed from DID values could contain non-ASCII characters that were not obvious in the DID, surprising a casual human reader.
    3. Caution is RECOMMENDED when treating a did:webs as the equivalent of an IRI.
    4. Treating it as the equivalent of a URL, instead, is RECOMMENDED as it preserves the punycode and percent encoding and is therefore safe.

§ Concepts for securing did:webs information

The following security concepts are used to secure the data, files, signatures and other information in did:webs.

  1. All security features and concepts in did:webs MUST be use one or more of the following mechanisms:
    1. All data that requires the highest security MUST be KEL backed. This includes any information that needs to be end-verifiably authentic over time:
      1. All ACDCs used by a did:webs identifier MUST be one of the following:
        1. MAY be anchored to a KEL directly.
        2. MAY be anchored indirectly through a TEL that itself is anchored to a KEL.
    2. All data that does not need to incur the cost of KEL backing for secuirty but can benefit from the latest data-state such as a distributed data-base MUST use Best Available Data - Read, Update, Nullify (BADA-RUN).
      1. BADA-RUN information MUST be ordered in a consistent way, using the following:
        1. date-time MUST be used.
        2. key state MUST be used.
      2. Discovery information MAY use BADA-RUN because the worst-case attack on discovery information is a DDoS attack where nothing gets discovered.
        1. The controller(s) of the AID for a did:webs identifier MAY use BADA-RUN for service end-points as discovery mechanisms.
    3. All data that does not need the security of being KEL backed nor BADA-RUN SHOULD be served using KERI Request Authentication Mechanism (KRAM).
      1. For a did:webs resolver to be trusted it SHOULD use KRAM to access the service endpoints providing KERI event streams for verification of the DID document.

§ On-Disk Storage

This section is informative.

Both KEL backed data and BADA-RUN security approaches are suitable for storing information on disk because both provide a link between the keystate and date-time on some data when a signature by the source of the data was created. BADA-RUN is too weak for important information because an attacker who has access to the database on disk can overwrite data on disk without being detected by a verifier hosting the on-disk data either through a replay of stale data (data regression attack) or if in addition to disk access the attacker has compromised a given key state, then the attacker can forge new data with a new date-time stamp for a given compromised key and do a regression attack so that the last seen key state is the compromised key state.

With BADA, protection from a deletion (regression) attack requires redundant disk storage. At any point in time where there is a suspicion of loss of custody of the disk, a comparison to the redundant disks is made and if any disk has a later event given BADA-RUN rules then recovery from the deletion attack is possible.

KRAM on a query is not usable for on disk storage by itself. Because it’s just a bare signature (the datetime is not of the querier but of the host at the time of a query). However, the reply to a query can be stored on disk if the querier applies BADA to the reply. To elaborate, Data obtained via a KRAMed query-reply may be protected on-disk by being using BADA on the reply. This is how KERI stores service endpoints. However, KERI currently only uses BADA for discovery data not more important data. More important data should be wrapped (containerized) in an ACDC that is KEL backed and then stored on-disk

In the hierarchy of attack surfaces, exposure as on disk (unencrypted) is the weakest. Much stronger is exposure that is only in-memory. To attack in-memory usually means compromising the code supply chain which is harder than merely gaining disk access. Encrypting data on disk does not necessarily solve attacks that require a key compromise (because decryption keys can be compromised), and it does not prevent a deletion attack. Encryption does not provide authentication protection. However, encryption does protect the confidentiality of data.

The use of DH key exchange as a weak form of authentication is no more secure than an HMAC for authentication. It is sharing secrets, so anyone with the secret can impersonate any other member of the group that has the shared secret.

Often, DID methods have focused on features that erode security characteristics. The paper Five DID Attacks highlights some attacks to which did:webs should NOT be vulnerable. So when a pull request exposes did:webs to a known attack, it should not be accepted.

§ Alignment of Information to Security Posture

This section is informative.

As a general security principle each block of information should have the same security posture for all the sub-blocks. One should not attempt to secure a block of information that mixes security postures across is constituent sub-blocks. The reason is that the security of the block can be no stronger than the weakest security posture of any sub-block in the block. Mixing security postures forces all to have the lowest common denominator security. The only exception to this rule is if the block of information is purely informational for discovery purposes and where it is expected that each constituent sub-block is meant to be verified independently.

This means that any recipient of such a block information with mixed security postures across its constituent sub-blocks must explode the block into sub-blocks and then independently verify the security of each sub-block. However, this is only possible if the authentication factors for each sub-block are provided independently. Usually when information is provided in a block of sub-blocks, only one set of authentication factors are provided for the block as a whole and therefore there is no way to independently verify each sub-block of information.

Unfortunately, what happens in practice is that users are led into a false sense of security because they assume that they don’t have to explode and re-verify, but merely may accept the lowest common denominator verification on the whole block of information. This creates a pernicious problem for downstream use of the data. A downstream use of a constituent sub-block doesn’t know that it was not independently verified to its higher level of security. This widens the attack surface to any point of down-stream usage. This is a root cause of the most prevalent type of attack called a BOLA.

§ Applying the concepts

This section is informative.

Lets explore the implications of applying these concepts to various did:webs elements.

Using KEL backed elements in a DID doc simplifies the security concerns. However, future discovery features related to endpoints might consider BADA-RUN. For instance, ‘whois’ data could be used with BADA-RUN whereas did:web aliases should not because it could lead to an impersonation attack. We could have a DID document that uses BADA-RUN if we modify the DID CRUD semantics to be RUN semantics without necessarily changing the verbs but by changing the semantics of the verbs. Then any data that fits the security policy of BADA (i.e. where BADA is secure enough) can be stored in a DID document as a database in the sky. For sure this includes service endpoints for discovery. One can sign with CESR or JWS signatures. The payloads are essentially KERI reply messages in terms of the fields (with modifications as needed to be more palatable), but are semantically the same. The DID doc just relays those replies. Anyone reading from the DID document is essentially getting a KERI reply message, and they then should apply the BADA rules to their local copy of the reply message.

To elaborate, these security concepts point us to modify the DID CRUD semantics to replicate RUN semantics. Create becomes synonymous with Update where Update uses the RUN update. Delete is modified to use the Nullify semantics. Read data is modified so that any recipient of the Read response can apply BADA to its data (Read is a GET). So we map the CRUD of DID docs to RUN for the did:webs method. Now you have reasonable security for things like signed data. If its KEL backed data you could even use an ACDC as a data attestation for that data and the did resolver would become a caching store for ACDCs issued by the AID controller.

Architecturally, a Read (GET) from the did resolver acts like how KERI reply messages are handled for resolving service endpoint discovery from an OOBI. The query is the read in RUN and so uses KRAM. The reply is the response to the READ request. The controller of the AID updates the DID resolvers cache with updates(unsolicited reply messages). A trustworthy DID resolver applies the BADA rules to any updates it receives. Optionally the DID resolver may apply KRAM rules to any READ requests to protect it from replay attacks.

In addition, a DID doc can be a discovery mechanism for an ACDC caching server by including an index (label: said) of the SAIDs of the ACDCs held in the resolvers cache.

§ Reducing the attack surface

This section is informative.

The above considerations have lead us to focus on KEL backed DID document blocks and data (whois files, signatures, etc) so that the trusted (local) did:webs resolver is secure. Any future features that could leverage BADA-RUN and KRAM should be considered carefully according to the above considerations.

§ Privacy Considerations

This section is informative.

This section addresses the privacy considerations from RFC6973 section 5. For privacy considerations related to web infrastructure, see did:web privacy considerations. Below we discuss privacy considerations related the KERI infrastructure.

§ Surveillance

In KERI, a robust witness network along with consistent witness rotation provides protection from monitoring and association of an individual’s activity inside a KERI network.

§ Stored Data Compromise

For resolvers that simply discover the Key State endorsed by another party in a discovery network, caching policies of that network would guide stored data security considerations. In the event that a resolver is also the endorsing party, meaning they have their own KERI identifier and are verifying the KEL and signing the Key State themselves, leveraging the facilities provided by the KERI protocol (key rotation, witness maintenance, multi-sig) should be used to protect the identities used to sign the Key State.

§ Unsolicited Traffic

DID Documents are not required to provide endpoints and thus not subject to unsolicited traffic.

§ Misattribution

This DID Method relies on KERI’s duplicity detection to determine when the non-repudiable controller of a DID has been inconsistent and can no longer be trusted. This establishment of non-repudiation enables consistent attribution.

§ Correlation

The root of trust for KERI identifiers is entropy and therefore offers no direct means of correlation. In addition, KERI provides two modes of communication, direct mode and indirect mode. Direct mode allows for pairwise (n-wise as well) relationships that can be used to establish private relationships.

TODO: link to KERI docs for additional information about direct and indirect modes.

§ Identification

The root of trust for KERI identifiers is entropy and therefore offers no direct means of identification. In addition, KERI provides two modes of communication, direct mode and indirect mode. Direct mode allows for pairwise (n-wise as well) relationships that can be used to establish private relationships.

TODO: link to KERI docs for additional information regarding prefix generation and for a comparison between Direct and Indirect modes.

§ Secondary Use

The Key State made available in the metadata of this DID method is generally available and can be used by any party to retrieve and verify the state of the KERL for the given identifier.

§ Disclosure

No data beyond the Key State for the identifier is provided by this DID method.

§ Exclusion

This DID method provides no opportunity for correlation, identification or disclosure and therefore there is no opportunity to exclude the controller from knowing about data that others have about them.

§ References

§ Normative References

Data Integrity Proof
The data integrity proof defined in the Verifiable Credential Data Model spec. See https://www.w3.org/TR/vc-data-model/#data-integrity-proofs.
JSON Serialization
See https://datatracker.ietf.org/doc/html/rfc7515#section-3.2.
multiformat multihash
See https://github.com/multiformats/multihash.
RFC1035
Domain names - implementation and specification. See https://www.rfc-editor.org/info/rfc1035.
RFC1123
Requirements for Internet Hosts – Application and Support. See https://datatracker.ietf.org/doc/html/rfc1123.
RFC2181
Clarifications to the DNS Specification. See https://www.rfc-editor.org/info/rfc2181.
Trust over IP - Authentic Chained Data Containers (ACDC) specification
The ACDC specification details the core ACDC specification including the Issuance and Presentation Exchange (IPEX) Protocol and Public Transaction Event Log (PTEL) specification.
Trust over IP - Composable Event Streaming Representation (CESR)
The CESR specification details the core CESR protocol including the Self-Addressing IDentifier (SAID) specification.
Trust over IP - CESR Proof Signatures
The CESR Proof Signatures specification details the core CESR Proof Signatures.
Trust over IP - Key Event Receipt Infrastructure (KERI)
The KERI specification details the core Key Event Receipt Infrastructure (KERI) protocol. This includes the Out-of-Band-Introduction (OOBI) specification.
W3C - did:web Method Specification
The did:web specification details the did:web method specification.
W3C - Decentralized Identifiers (DIDs)
The DIDs specification details the core Decentralized Identifiers (DIDs) specification.
W3C - DID spec registries
The DID Spec Registries detail the specs for each registred DID method.
W3C - DID URL path
See https://www.w3.org/TR/did-core/#path.
W3C - Verifiable Credentials Data Model (VCDM)
The W3C - Verifiable Credentials Data Model (VCDM) details the the core Verifiable Credentials Data Model (VCDM) specification.
W3C - verifiable presentation
See (https://www.w3.org/TR/vc-data-model/#presentations-0).
ACDC IPEX
ACDC Verifiable Credential Issuance and Presentation Excchange as defined in the KERI ACDC spec https://trustoverip.github.io/tswg-acdc-specification/#ipex-validation.

§ Informative References

StatusList2021
See https://w3c.github.io/vc-status-list-2021/.
Hyperledger AnonCreds
See https://www.hyperledger.org/projects/anoncreds. And Setting up to publish AnonCreds verifiable credential.
W3C VC Rendering Methods specification
See https://w3c-ccg.github.io/vc-render-method/.
Overlay Capture Architecture
See Aries RFC.

§ Acknowledgements

TODO

Add Acknowledgements

§ Authors’ Addresses

TODO

Add authors’ addresses.

§ Appendix

§ Trust Over IP Glossary - Controlled Terms

autonomous identifier
Another term for self-certifying identifier (SCID).
cryptographically verifiable
A property of a data structure that has been digitally signed using a private key such that the digital signature can be verified using the public key. Verifiable data, verifiable messages, verifiable credentials, and verifiable data registries are all cryptographically verifiable. Cryptographic verifiability is a primary goal of the ToIP Technology Stack.
identifier
A single attribute—typically a character string—that uniquely identifies an entity within a specific context (which may be a global context). Examples include the name of a party, the URL of an organization, or a serial number for a man-made thing. Supporting definitions: eSSIF-Lab: a character string that is being used for the identification of some entity (yet may refer to 0, 1, or more entities, depending on the context within which it is being used).
self-certifying identifier (SCID)
A subclass of verifiable identifier (VID) that is cryptographically verifiable without the need to rely on any third party for verification because the identifier is cryptographically bound to the cryptographic keys from which it was generated. Also known as: autonomous identifier.
verifiable identifier (VID)
An identifier over which the controller can provide cryptographic proof of control. See also: decentralized identifier, self-certifying identifier (SCID).

§ Terminology

AID controlled identifiers
Any identifier, including did:webs DIDs, that have the same AID are by definition referencing the same identity. As defined by KERI TODO: Add link to KERI documentation here.
authentic chained data container (ACDC)
a variant of the Verifiable Credential (VC) specification that inherits the security model derived from KERI, as defined by the ACDC specification. See WebOfTrust glossary for more detail.
autonomic identifier (AID)
A self-certifying identifier (SCID) that is cryptographically bound cryptographically bound to a key event log (KEL), as defined by the KERI specification. An AID is either non-transferable or transferable. A non-transferable AID does not support key rotation while a transferable AID supports key rotation using a key pre-rotation mechanism that enables the AID to persist in spite of the evolution of its key state. See WebOfTrust glossary for more detail.
BADA-RUN
Best available data acceptance - Read/Update/Nullify provides a medium level of security because events are ordered in a consistent way, using a combination of date-time and a key state. The latest event is the one with the latest date-time for the latest key state. See The KERI spec for more detail.
compact event streaming representation (CESR)
An encoding format that enables round-trip text-binary conversion of concatenated cryptographic primitives and general data types, as defined by the CESR specification and CESR Proof Signature specification. See WebOfTrust glossary for more detail.
controller
A controlling entity that can cryptographically prove the control authority (signing and rotation) over an AID as well as make changes on the associated KEL. A controller may consist of multiple controlling entities in a multi-signature scheme. See WebOfTrust glossary for more detail.
decentralized identifier (DID)
A globally unique persistent identifier, as defined by DID Core.
designated aliases
An array of AID controlled identifiers that have been designated by the AID controller to be used as aliases for equivalentId and alsoKnownAs DID document metadata and to foster verification of redirection to different did:webs identifiers. See WebOfTrust glossary for more detail.
DID document
A set of data describing the subject of a DID, as defined by DID Core. See also section DID Documents.
DID resolution metadata
DID resolution metadata is metadata about the DID Resolution process that was performed in order to obtain the DID document for a given DID. See also DID Resolution Metadata in the DID Core specification.
DID document metadata
DID document metadata is metadata about the DID and the DID document that is the result of the DID Resolution process. See also DID Document Metadata in the DID Core specification.
direct mode
an operational mode of the KERI protocol where a controller and a verifier of an AID exchange the KEL of the AID directly, as defined by the KERI whitepaper. See WebOfTrust glossary for more detail.
host
The part of a URL that can be either a domain name or an IP address. This component specifies the server that the client needs to communicate with in order to access the desired resource on the web.
inception event
A key event that provides the incepting information needed to derive an AID and establish its initial key state, as defined by the KERI specification. See WebOfTrust glossary for more detail.
indirect mode
An operational mode of the KERI protocol where the KEL of an AID is discovered by a verifier via witnesses, as defined by the KERI whitepaper. See WebOfTrust glossary for more detail.
interaction event
A key event that anchors external data to an AID, as defined by the KERI specification. An interaction event does not change the key state of the AID. See WebOfTrust glossary for more detail.
key event
A serialized data structure of an entry in the key event log(KEL) for an AID, as defined by the KERI specification. There are three types of key events, namely inception event, rotation event, and interaction event. See WebOfTrust glossary for more detail.
key event log (KEL)
A verifiable append-only log of key events for an AID that is both backward and forward-chained, as defined by the KERI specification. See WebOfTrust glossary for more detail.
KEL backed data
KEL backed data in did:webs provides the highest level of data security assurance and such data can be found either in the KEL or anchored to an event in the KEL. This means that the signatures on the events in the KEL are strongly bound to the key state at the time the events are entered in the KEL, that is the data. This provides strong guarantees of non-duplicity to any verifiers receiving a presentation as the KELs are protected and can be watched by agents (watcher) of the verifiers. The information is end-verifiable and any evidence of duplicity in the events is evidence that the data or presentation should not be trusted. See WebOfTrust glossary for more detail.
key event receipt
A message whose body references a key event of an AID and includes one or more signatures on that key event, as defined by the KERI specification. See WebOfTrust glossary for more detail.
key event receipt log (KERL)
A verifiable append-only log that includes all the consistent key event receipt messages, as defined by the KERI specification. See WebOfTrust glossary for more detail.
key event receipt infrastructure (KERI)
A protocol that provides an identity system-based secure overlay for the internet and uses AIDs as the primary roots of trust, as defined by the KERI specification. See WebOfTrust glossary for more detail.
KERI event stream
A stream of verifiable KERI data, consisting of the key event log (KEL) and other data such as a transaction event log (TEL). This data is a CESR event stream (TODO: link to IANA application/cesr media type) and may be serialized in a file using CESR encoding. We refer to these CESR stream resources as KERI event streams to simplify the vocabulary. See WebOfTrust glossary for more detail.
key state
The set of currently authoritative key pairs (current keys) for an AID and any other information necessary to secure or establish control authority over the AID. See WebOfTrust glossary for more detail.
KERI Request Authentication Mechanism
A non-interactive replay attack protection algorithm that uses a sliding window of date-time stamps and key state (similar to the tuple in BADA-RUN) but the date-time is the replier’s not the querier’s. KRAM is meant to protect a host. See the WebOfTrust glossary for more detail.
method-specific identifier
The method-specific-id part of DID Syntax, as defined in DID Core. See section Method-Specific Identifier.
multi-signature
A mechanism that enables multiple parties to sign a message, as defined by the KERI specification. See Controller Application in the KERI spec for more detail.
out-of-band introduction (OOBI)
A protocol for discovering verifiable information on an AID or a SAID, as defined by the KERI specification. The OOBI by itself is insecure, and the information discovered by the OOBI must be verified. See WebOfTrust glossary for more detail.
pre-rotation
A key rotation mechanism whereby a set of rotation keys are pre-commited using cryptographic digests, as defined by the KERI specification. See WebOfTrust glossary for more detail.
rotation event
A key event that provides the information needed to change the key state for an AID using pre-rotation, as defined by the KERI specification. See WebOfTrust glossary for more detail.
self-addressing identifier (SAID)
An identifier that is uniquely and cryptographically bound to a serialization of data (content-addressable) while also being included as a component in that serialization (self-referential), as defined by the CESR specification. See WebOfTrust glossary for more detail.
transaction event log (TEL)
A verifiable append-only log of transaction data that are cryptographically anchored to a KEL. The transaction events of a TEL may be used to establish the issuance or revocation state of ACDCs. See WebOfTrust glossary for more detail.
verifier
An entity or component that cryptographically verifies the signature(s) on an event message. See WebOfTrust glossary for more detail.
watcher
An entity that keeps a copy of a KERL of an AID to detect duplicity of key events, as defined by the KERI whitepaper. See WebOfTrust glossary for more detail.
witness
An entity that is designated by the controller of an AID to verify, sign, and keep the key events associated with the AID, as defined by the KERI whitepaper. See WebOfTrust glossary for more detail.
Table of Contents