diff --git a/.nojekyll b/.nojekyll new file mode 100644 index 0000000..e69de29 diff --git a/fonts/KaTeX_AMS-Regular.ttf b/fonts/KaTeX_AMS-Regular.ttf new file mode 100644 index 0000000..737cf8e Binary files /dev/null and b/fonts/KaTeX_AMS-Regular.ttf differ diff --git a/fonts/KaTeX_AMS-Regular.woff b/fonts/KaTeX_AMS-Regular.woff new file mode 100644 index 0000000..38378bf Binary files /dev/null and b/fonts/KaTeX_AMS-Regular.woff differ diff --git a/fonts/KaTeX_AMS-Regular.woff2 b/fonts/KaTeX_AMS-Regular.woff2 new file mode 100644 index 0000000..a4d1ba6 Binary files /dev/null and b/fonts/KaTeX_AMS-Regular.woff2 differ diff --git a/fonts/KaTeX_Caligraphic-Bold.ttf b/fonts/KaTeX_Caligraphic-Bold.ttf new file mode 100644 index 0000000..04d28ab Binary files /dev/null and b/fonts/KaTeX_Caligraphic-Bold.ttf differ diff --git a/fonts/KaTeX_Caligraphic-Bold.woff b/fonts/KaTeX_Caligraphic-Bold.woff new file mode 100644 index 0000000..a01ce90 Binary files /dev/null and b/fonts/KaTeX_Caligraphic-Bold.woff differ diff --git a/fonts/KaTeX_Caligraphic-Bold.woff2 b/fonts/KaTeX_Caligraphic-Bold.woff2 new file mode 100644 index 0000000..3792727 Binary files /dev/null and b/fonts/KaTeX_Caligraphic-Bold.woff2 differ diff --git a/fonts/KaTeX_Caligraphic-Regular.ttf b/fonts/KaTeX_Caligraphic-Regular.ttf new file mode 100644 index 0000000..b2ce555 Binary files /dev/null and b/fonts/KaTeX_Caligraphic-Regular.ttf differ diff --git a/fonts/KaTeX_Caligraphic-Regular.woff b/fonts/KaTeX_Caligraphic-Regular.woff new file mode 100644 index 0000000..bc169b7 Binary files /dev/null and b/fonts/KaTeX_Caligraphic-Regular.woff differ diff --git a/fonts/KaTeX_Caligraphic-Regular.woff2 b/fonts/KaTeX_Caligraphic-Regular.woff2 new file mode 100644 index 0000000..f1e38bb Binary files /dev/null and b/fonts/KaTeX_Caligraphic-Regular.woff2 differ diff --git a/fonts/KaTeX_Fraktur-Bold.ttf b/fonts/KaTeX_Fraktur-Bold.ttf new file mode 100644 index 0000000..c42d169 Binary files /dev/null and b/fonts/KaTeX_Fraktur-Bold.ttf differ diff --git a/fonts/KaTeX_Fraktur-Bold.woff b/fonts/KaTeX_Fraktur-Bold.woff new file mode 100644 index 0000000..f30b54b Binary files /dev/null and b/fonts/KaTeX_Fraktur-Bold.woff differ diff --git a/fonts/KaTeX_Fraktur-Bold.woff2 b/fonts/KaTeX_Fraktur-Bold.woff2 new file mode 100644 index 0000000..b7a8359 Binary files /dev/null and b/fonts/KaTeX_Fraktur-Bold.woff2 differ diff --git a/fonts/KaTeX_Fraktur-Regular.ttf b/fonts/KaTeX_Fraktur-Regular.ttf new file mode 100644 index 0000000..4133228 Binary files /dev/null and b/fonts/KaTeX_Fraktur-Regular.ttf differ diff --git a/fonts/KaTeX_Fraktur-Regular.woff b/fonts/KaTeX_Fraktur-Regular.woff new file mode 100644 index 0000000..5af51de Binary files /dev/null and b/fonts/KaTeX_Fraktur-Regular.woff differ diff --git a/fonts/KaTeX_Fraktur-Regular.woff2 b/fonts/KaTeX_Fraktur-Regular.woff2 new file mode 100644 index 0000000..3874f93 Binary files /dev/null and b/fonts/KaTeX_Fraktur-Regular.woff2 differ diff --git a/fonts/KaTeX_Main-Bold.ttf b/fonts/KaTeX_Main-Bold.ttf new file mode 100644 index 0000000..14390e0 Binary files /dev/null and b/fonts/KaTeX_Main-Bold.ttf differ diff --git a/fonts/KaTeX_Main-Bold.woff b/fonts/KaTeX_Main-Bold.woff new file mode 100644 index 0000000..33b4199 Binary files /dev/null and b/fonts/KaTeX_Main-Bold.woff differ diff --git a/fonts/KaTeX_Main-Bold.woff2 b/fonts/KaTeX_Main-Bold.woff2 new file mode 100644 index 0000000..f9b71cb Binary files /dev/null and b/fonts/KaTeX_Main-Bold.woff2 differ diff --git a/fonts/KaTeX_Main-BoldItalic.ttf b/fonts/KaTeX_Main-BoldItalic.ttf new file mode 100644 index 0000000..ad0761f Binary files /dev/null and b/fonts/KaTeX_Main-BoldItalic.ttf differ diff --git a/fonts/KaTeX_Main-BoldItalic.woff b/fonts/KaTeX_Main-BoldItalic.woff new file mode 100644 index 0000000..115af4f Binary files /dev/null and b/fonts/KaTeX_Main-BoldItalic.woff differ diff --git a/fonts/KaTeX_Main-BoldItalic.woff2 b/fonts/KaTeX_Main-BoldItalic.woff2 new file mode 100644 index 0000000..5c500c2 Binary files /dev/null and b/fonts/KaTeX_Main-BoldItalic.woff2 differ diff --git a/fonts/KaTeX_Main-Italic.ttf b/fonts/KaTeX_Main-Italic.ttf new file mode 100644 index 0000000..fc8625c Binary files /dev/null and b/fonts/KaTeX_Main-Italic.ttf differ diff --git a/fonts/KaTeX_Main-Italic.woff b/fonts/KaTeX_Main-Italic.woff new file mode 100644 index 0000000..2d3087a Binary files /dev/null and b/fonts/KaTeX_Main-Italic.woff differ diff --git a/fonts/KaTeX_Main-Italic.woff2 b/fonts/KaTeX_Main-Italic.woff2 new file mode 100644 index 0000000..08510d8 Binary files /dev/null and b/fonts/KaTeX_Main-Italic.woff2 differ diff --git a/fonts/KaTeX_Main-Regular.ttf b/fonts/KaTeX_Main-Regular.ttf new file mode 100644 index 0000000..5115a04 Binary files /dev/null and b/fonts/KaTeX_Main-Regular.ttf differ diff --git a/fonts/KaTeX_Main-Regular.woff b/fonts/KaTeX_Main-Regular.woff new file mode 100644 index 0000000..42b74ab Binary files /dev/null and b/fonts/KaTeX_Main-Regular.woff differ diff --git a/fonts/KaTeX_Main-Regular.woff2 b/fonts/KaTeX_Main-Regular.woff2 new file mode 100644 index 0000000..18647fa Binary files /dev/null and b/fonts/KaTeX_Main-Regular.woff2 differ diff --git a/fonts/KaTeX_Math-BoldItalic.ttf b/fonts/KaTeX_Math-BoldItalic.ttf new file mode 100644 index 0000000..326b523 Binary files /dev/null and b/fonts/KaTeX_Math-BoldItalic.ttf differ diff --git a/fonts/KaTeX_Math-BoldItalic.woff b/fonts/KaTeX_Math-BoldItalic.woff new file mode 100644 index 0000000..5b4041a Binary files /dev/null and b/fonts/KaTeX_Math-BoldItalic.woff differ diff --git a/fonts/KaTeX_Math-BoldItalic.woff2 b/fonts/KaTeX_Math-BoldItalic.woff2 new file mode 100644 index 0000000..ba55276 Binary files /dev/null and b/fonts/KaTeX_Math-BoldItalic.woff2 differ diff --git a/fonts/KaTeX_Math-Italic.ttf b/fonts/KaTeX_Math-Italic.ttf new file mode 100644 index 0000000..f148fce Binary files /dev/null and b/fonts/KaTeX_Math-Italic.ttf differ diff --git a/fonts/KaTeX_Math-Italic.woff b/fonts/KaTeX_Math-Italic.woff new file mode 100644 index 0000000..31d0038 Binary files /dev/null and b/fonts/KaTeX_Math-Italic.woff differ diff --git a/fonts/KaTeX_Math-Italic.woff2 b/fonts/KaTeX_Math-Italic.woff2 new file mode 100644 index 0000000..9871ab6 Binary files /dev/null and b/fonts/KaTeX_Math-Italic.woff2 differ diff --git a/fonts/KaTeX_SansSerif-Bold.ttf b/fonts/KaTeX_SansSerif-Bold.ttf new file mode 100644 index 0000000..dce35c8 Binary files /dev/null and b/fonts/KaTeX_SansSerif-Bold.ttf differ diff --git a/fonts/KaTeX_SansSerif-Bold.woff b/fonts/KaTeX_SansSerif-Bold.woff new file mode 100644 index 0000000..992cb3d Binary files /dev/null and b/fonts/KaTeX_SansSerif-Bold.woff differ diff --git a/fonts/KaTeX_SansSerif-Bold.woff2 b/fonts/KaTeX_SansSerif-Bold.woff2 new file mode 100644 index 0000000..6dd1038 Binary files /dev/null and b/fonts/KaTeX_SansSerif-Bold.woff2 differ diff --git a/fonts/KaTeX_SansSerif-Italic.ttf b/fonts/KaTeX_SansSerif-Italic.ttf new file mode 100644 index 0000000..a3eb86c Binary files /dev/null and b/fonts/KaTeX_SansSerif-Italic.ttf differ diff --git a/fonts/KaTeX_SansSerif-Italic.woff b/fonts/KaTeX_SansSerif-Italic.woff new file mode 100644 index 0000000..f4fa252 Binary files /dev/null and b/fonts/KaTeX_SansSerif-Italic.woff differ diff --git a/fonts/KaTeX_SansSerif-Italic.woff2 b/fonts/KaTeX_SansSerif-Italic.woff2 new file mode 100644 index 0000000..9f2501a Binary files /dev/null and b/fonts/KaTeX_SansSerif-Italic.woff2 differ diff --git a/fonts/KaTeX_SansSerif-Regular.ttf b/fonts/KaTeX_SansSerif-Regular.ttf new file mode 100644 index 0000000..3be73ce Binary files /dev/null and b/fonts/KaTeX_SansSerif-Regular.ttf differ diff --git a/fonts/KaTeX_SansSerif-Regular.woff b/fonts/KaTeX_SansSerif-Regular.woff new file mode 100644 index 0000000..ec283f4 Binary files /dev/null and b/fonts/KaTeX_SansSerif-Regular.woff differ diff --git a/fonts/KaTeX_SansSerif-Regular.woff2 b/fonts/KaTeX_SansSerif-Regular.woff2 new file mode 100644 index 0000000..e46094f Binary files /dev/null and b/fonts/KaTeX_SansSerif-Regular.woff2 differ diff --git a/fonts/KaTeX_Script-Regular.ttf b/fonts/KaTeX_Script-Regular.ttf new file mode 100644 index 0000000..40c8a99 Binary files /dev/null and b/fonts/KaTeX_Script-Regular.ttf differ diff --git a/fonts/KaTeX_Script-Regular.woff b/fonts/KaTeX_Script-Regular.woff new file mode 100644 index 0000000..4eafae7 Binary files /dev/null and b/fonts/KaTeX_Script-Regular.woff differ diff --git a/fonts/KaTeX_Script-Regular.woff2 b/fonts/KaTeX_Script-Regular.woff2 new file mode 100644 index 0000000..69b1754 Binary files /dev/null and b/fonts/KaTeX_Script-Regular.woff2 differ diff --git a/fonts/KaTeX_Size1-Regular.ttf b/fonts/KaTeX_Size1-Regular.ttf new file mode 100644 index 0000000..f0aff83 Binary files /dev/null and b/fonts/KaTeX_Size1-Regular.ttf differ diff --git a/fonts/KaTeX_Size1-Regular.woff b/fonts/KaTeX_Size1-Regular.woff new file mode 100644 index 0000000..0358ee4 Binary files /dev/null and b/fonts/KaTeX_Size1-Regular.woff differ diff --git a/fonts/KaTeX_Size1-Regular.woff2 b/fonts/KaTeX_Size1-Regular.woff2 new file mode 100644 index 0000000..f951ed0 Binary files /dev/null and b/fonts/KaTeX_Size1-Regular.woff2 differ diff --git a/fonts/KaTeX_Size2-Regular.ttf b/fonts/KaTeX_Size2-Regular.ttf new file mode 100644 index 0000000..4f72f16 Binary files /dev/null and b/fonts/KaTeX_Size2-Regular.ttf differ diff --git a/fonts/KaTeX_Size2-Regular.woff b/fonts/KaTeX_Size2-Regular.woff new file mode 100644 index 0000000..8a053d2 Binary files /dev/null and b/fonts/KaTeX_Size2-Regular.woff differ diff --git a/fonts/KaTeX_Size2-Regular.woff2 b/fonts/KaTeX_Size2-Regular.woff2 new file mode 100644 index 0000000..181d962 Binary files /dev/null and b/fonts/KaTeX_Size2-Regular.woff2 differ diff --git a/fonts/KaTeX_Size3-Regular.ttf b/fonts/KaTeX_Size3-Regular.ttf new file mode 100644 index 0000000..56d2dc6 Binary files /dev/null and b/fonts/KaTeX_Size3-Regular.ttf differ diff --git a/fonts/KaTeX_Size3-Regular.woff b/fonts/KaTeX_Size3-Regular.woff new file mode 100644 index 0000000..0ec99ad Binary files /dev/null and b/fonts/KaTeX_Size3-Regular.woff differ diff --git a/fonts/KaTeX_Size3-Regular.woff2 b/fonts/KaTeX_Size3-Regular.woff2 new file mode 100644 index 0000000..c2985cd Binary files /dev/null and b/fonts/KaTeX_Size3-Regular.woff2 differ diff --git a/fonts/KaTeX_Size4-Regular.ttf b/fonts/KaTeX_Size4-Regular.ttf new file mode 100644 index 0000000..baf0209 Binary files /dev/null and b/fonts/KaTeX_Size4-Regular.ttf differ diff --git a/fonts/KaTeX_Size4-Regular.woff b/fonts/KaTeX_Size4-Regular.woff new file mode 100644 index 0000000..ff67319 Binary files /dev/null and b/fonts/KaTeX_Size4-Regular.woff differ diff --git a/fonts/KaTeX_Size4-Regular.woff2 b/fonts/KaTeX_Size4-Regular.woff2 new file mode 100644 index 0000000..a4e810d Binary files /dev/null and b/fonts/KaTeX_Size4-Regular.woff2 differ diff --git a/fonts/KaTeX_Typewriter-Regular.ttf b/fonts/KaTeX_Typewriter-Regular.ttf new file mode 100644 index 0000000..e66c218 Binary files /dev/null and b/fonts/KaTeX_Typewriter-Regular.ttf differ diff --git a/fonts/KaTeX_Typewriter-Regular.woff b/fonts/KaTeX_Typewriter-Regular.woff new file mode 100644 index 0000000..c66d149 Binary files /dev/null and b/fonts/KaTeX_Typewriter-Regular.woff differ diff --git a/fonts/KaTeX_Typewriter-Regular.woff2 b/fonts/KaTeX_Typewriter-Regular.woff2 new file mode 100644 index 0000000..e5bf2ce Binary files /dev/null and b/fonts/KaTeX_Typewriter-Regular.woff2 differ diff --git a/index.html b/index.html new file mode 100644 index 0000000..82f8f09 --- /dev/null +++ b/index.html @@ -0,0 +1,1452 @@ + + + + + + + + + DID Method did:webs Specification + + + + + + + + + + + + + + + + + + + + + +
+ + + +
+

§ DID Method did:webs Specification

+

Specification Status: v1.0 Draft

+

Latest Draft:

+

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

+

Editors:

+ + +
+
Participate:
+
GitHub repo
+
Commit history
+
+
+

§ Abstract

+

This document specifies a DID +Method, +did:webs, that is web-based but also highly and innovatively secure. Like its +interoperable cousin, did:web, the +did:webs method uses websites and popular, mature tooling 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 keys events by those who +control the identifier.

+

The did:webs method does not need blockchains for trust. However, its use of +KERI allows for the referencing of arbitrary blockchains as an extra, optional +publication mechanism. This offers an 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 fully supports those environments, making future interop of +identifiers between web and non-web an easy step.

+

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 straight forward. Cryptographic trust is strongly +decentralized, and governance is transparent. Regulatory challenges around +blockchain 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 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 specifications is subject to the Community Specification License 1.0 +available at +https://github.com/CommunitySpecification/1.0.

+

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 Community Specification License +and the designated source code license, the terms of the Community Specification +License shall apply.

+

§ Introduction

+

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, that 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 IT’s web servers, those individuals are at the mercy of IT for their security.

+

The did:webs method described in this spec separates these two questions, and gives them different answers. 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 and decentralized trust.

+

§ Requirements, Notation and Conventions

+

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL +NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, +“MAY”, and “OPTIONAL” 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.

+

§ Terminology

+ +
+
method-specific identifier
+
The method-specific-id part of DID Syntax, as defined in DID Core. See section Method-Specific Identifier.
+
DID document
+
As defined by DID Core. See section DID Documents.
+
key event log
+
As defined by KERI.
+
transaction event log
+
As defined by KERI.
+
KERI event stream
+
A stream of verifiable KERI data, consisting of the key event log (KEL) and other data such as transaction event log (TEL). This data may be serialized in a file using CESR encoding.
+
+

§ Core Characteristics

+

§ Method Name

+

The method name that identifies this DID method SHALL be: webs.

+
+

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 analogous +to the one HTTPS gives to HTTP.

+
+

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

+

§ Method-Specific Identifier

+

The did:webs method-specific identifier has two +parts, a fully qualified domain name with an optional path (identical to +did:web), plus a KERI AID (autonomic identifier) that is always the final +component of the path.

+

The ABNF definition of a did:webs DID is as follows:

+
webs-did = "did:webs:" domain-name ":" aid
+webs-did = "did:webs:" domain-name * (":" path) ":" aid
+
+
TODO
+

TODO: what about intl chars? Does DID spec allow them like URL spec does? What +about localhost vs. 127.0.0.1 vs. ::1?

+
+
+

The formal rules describing valid domain name syntax are described in +[RFC1035], [RFC1123], and [RFC2181]. The fully qualified domain MUST NOT +include IP addresses. A port MAY be included and the colon MUST be percent +encoded to prevent a conflict with paths. Directories and subdirectories MAY +optionally be included, delimited by colons rather than slashes.

+

A KERI AID is a unique identifier derived from the +inception event of a KERI identifier–the first item in the KEL. +The algorithm used to generate the AID depends on +the type of AID. If the AID is transferable (supports key rotation) 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.

+

After the fully qualified domain name and optional path in a did:webs is a +final path component, a colon and the AID. 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)

+

As with did:web, this method reads data from whatever web server is referenced +when the domain name portion of one of its DIDs is resolved through the Domain +Name System (DNS). In fact, a did:webs can be resolved to a DID document +using a simple text transformation to an HTTPS URL in the same way as a +did:web. By design, a did:web and did:webs with the same method-specific identifier will return the same DID document.

+

However, this method introduces an important nuance about the target system. In +many DID methods, the target system equals a verifiable data registry — +besides publishing data, its security attributes make that data trustworthy. In +this DID method, the target system’s role is more limited. It is expected to +serve data about the DID, and to follow acknowledged cybersecurity best +practices to preserve good hygiene. However, the authenticity of data is +guaranteed by the DID value itself, in conjunction with a digitally signed +data structure called a KERI event stream, which includes the +key event log (KEL) and transaction event log (TEL). These trust +mechanisms — the integrity checks built into the DID value, and the workings of +the KERI event stream — are defined by KERI.

+

As with did:web, the location of the DID document is determined by transforming the DID to an +HTTPS URL as follows:

+ +

A GET on that URL MUST return the DID document.

+

The location of the KERI event stream is determined by transforming the previous URL as follows:

+ +

A GET on that URL MUST return the KERI event stream for the AID in the did:webs identifier.

+

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

+ +

The did:web version of the DIDs are the same (minus the s) and point +to the same did.json file, but have no knowledge of the did.keri 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 is 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” in did:webs.

+

§ Equivalent Identifiers

+
TODO

TODO: Consider merging this and section Handling Web Redirections +and propose that an entity +SHOULD only publish one “current” did:webs, with defined support for redirects. +Copies of a the did:webs data should be just that – copies.

+
+

Since an AID is a unique identifier that is inextricably bound to the KERI event stream from +which it is associated, any AIDs and any did:webs DIDs that have the same AID component +MUST be considered equivalent identifiers. Any did:webs DIDs that have the same AID +are by definition synonyms of one another, and MUST +return an equivalent, although not necessarily identical, 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 the web location of the DID document. As +well, different versions of the DID document and KERI event stream may reside in different locations +depending on the replication capabilities of the controlling entity. 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). 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.

+

The web supports a number of ways to redirect users. Please 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. The +verification of the KERI event stream MAY provide mechanisms for detecting such behavior, such +as KERI witnesses and watchers.

+

§ Handling Web Redirection

+

A did:webs is intended to be a “stable” (long-lasting) identifier that can be +put into documents, such as verifiable credentials, that are intended to be +useful for a very long time – generations. However, 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.

+

When a did:webs moves, its AID does not change. The same KERI event stream is used to verify +the DID document. Were the AID to change, it would be an altogether new DID, +unconnected to the first DID. So if a resolver can find a newly named DID that +uses the same AID, and the KERI event stream verifies the DID, then they have resolved the +DID. In fact, a did:webs could be moved to use another DID method that uses +the AID for uniqueness and the KERI event stream for validity.

+

The following are the capabilities in did:webs to help in the face of +resolution uncertainty.

+ +

The purpose of the history of “official” (according to the controller) locations +for the DID documents is so that if the 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 equivalent to the old one.

+

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. 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 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 resolver 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 DIDs equivalent to those locations +in the DID document (id or AlsoKnownAs) 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.

+

§ DID Method Operations

+

§ Create (Register)

+

Creating a DID involves these steps:

+ +

Of course, the web server that serves the files when asked might be a simple +file server (as implied above) or an active component that retrieves them +dynamically. Further, the publisher of the files placed on the web can use +capabilities like [CDNs] to distribute the files.

+

Likewise, 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.

+

§ Read (Resolve)

+

Before a did:webs DID can undergo standard resolution, it must be converted +back to an HTTPS URL as described above. The +reader then does a GET on both the URL for the DID document (ending in /did.json) +and on the URL for the KERI event stream (ending in /did.keri)

+

On receipt of the two documents, the KERI event stream is processed using [KERI Rules] to +verify the validity of the KERI event stream itself, and of the DID document.

+

After retrieval, the KERI event stream SHOULD BE processed using KERI rules by anyone +resolving the DID document to verify its contents. Further, 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

+

If an AID is updatable, updates are made to the AID by adding KERI events to +the KERI event stream. Some of those events may cause the DID document to be updated. Once +a set of events have been applied, derive the DID document from the KERI event stream and republish +both documents to the web server, overwriting the existing files.

+

§ Deactivate

+

Execute a KERI event that has the effect of rotating the key(s) to null. Once +the deactivation events have been applied, derive the DID document from the KERI event stream and +republish both documents to the web server, overwriting the existing files.

+

A controller may choose to simply remove the DID folder and files from the web +server on which it has been published. This is considered to 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. It is a much better practice to rotate +the keys to null and continuing to publish the DID document and KERI event stream.

+

§ Security Characteristics

+

There are several security characteristics necessary for did:webs to sufficiently address the common security threats related to DID methods and documents.

+

§ Common security threats

+

did:webs strives to narrow the attack surface against these common threats:

+ +

§ Concepts for securing did:webs information

+

The following security concepts are used to secure the data, files, signatures and other information in did:webs. We characterize each concept with high, medium and low security to orient readers to the situational relevance.

+

§ KEL backed data: High Security

+

KEL backed information in did:webs can either be found in the KEL or found anchored to the KEL. This means 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. This provides the strongest guarantee of duplicity evidence so that any verifier is protected. The information is end-verifiable and any evidence of duplicity means do not trust. A key compromise of a stale key can not result in an exploit because that would require forging an alternate version of the KEL which would be exposed as duplicity. Key compromise of the current key-state is recoverable with a rotation to the pre-rotated key(s) (single-sig or multi-sig) and pre-rotated keys are post-quantum proof. A compromise of a current key-state is guaranteed to be detectable by the AID’s controller because the compromise requires publication of a new KEL event in infrastructure (i.e. witnesses) controlled by the AID controller. This limits the exposure of a successful compromise of the current key-state to the time it takes for the AID controller to observe the compromised publication and execute a recovery rotation.

+

The ordering of events in the KEL is strictly verifiable because the KEL is a hash chain (block chain). All events are end-verifiable. Any data anchored to these events is also end-verifiable. All of these properties are guaranteed when data is anchored to a KEL, i.e., KEL backed. Any information that wants to be end-verifiablly authentic over time should be at this highest level of security. ACDCs when anchored to a KEL directly or indirectly through a TEL that itself is anchored to a KEL have this level of security.

+

§ BADA-RUN: Medium Security

+

BADA-RUN stands for Best available data acceptance - Read/Update/Nullify and is described in the ToIP KERI OOBI spec. It imposes a monotonicity on order of events using a tuple of date-time and key-state. The latest event is the one with the latest date-time for the latest key-state. This level of security is sufficient for discovery information because the worst case attack on discovery information is a DDoS where nothing gets discovered. This is because what gets discovered in KERI must be end-verifiable (anchored to a KEL). So a malicious discovery (mal-discovery) is no different than a mis-discovery or a non-discovery. The mitigation for such a DDoS is to have redundant discovery sources. We use BADA-RUN for service end-points as discovery mechanisms. We of course could anchor service endpoints to KELs and make them more secure but we want to make a trade-off due to the dynamism of discovery mechanisms and not bloat the KEL with discovery anchors. Because the worst case can be mitigated with redundant discovery its a viable trade-off.

+

Monotonicity protects against replay attacks and stale key compromise impersonation attacks. It does not provide strict ordering because there may be missed events and stale events but the last seen event always wins. So the only event that is end-verifiable is the last seen event but that event may be stale.

+

BADA policy provides guarantees that the latest data-state cannot be compromised via a replay of an earlier data-state where early is determined by the monotonicity of the associated (date-time, key-state) tuple. It also protects against forgery of new data-state given the compromise of any state key-state. It does not protect against the forgery of new data-state given a compromised of the current key-state. It does not provide ordering of all data-states but ensures that the data-state last seen by a given verifier cannot be replaced with an earlier data-state without compromising either the latest key-state of the source or by compromising the storage of the verifier.

+

To reiterate, because the monotonic (date-time, key-state) tuple includes key-state then a verifier is protected from any compromise of an earlier key-state relative to that which has been last seen by a verifier.

+

To elaborate, the only key-compromise that can succeed is that which corresponds to the latest key-state seen by the verifier. The exposure to exploit of the source’s latest key-state is then bounded by the time it takes for the source to detect key compromise and then perform a rotation recovery. An eco-system governance framework could impose liability on the source for any compromise of the latest data-state for a given latest key-state since it is entirely under the control of the source to protect its key-state from compromise. The difference between BADA and KEL backing is that with KEL backed update a compromise of the current key state is always detectable because the attacker must publish a new event to the KEL on infrastructure (such as witnesses) controlled by the AID’s legitimate controller. Whereas with BADA there is no mechanism that guarantees the AID’s legitimate controller can detect that its current key has been compromised.

+

One way to mitigate this exploit (non-detectability of current key-state compromise) is to periodically KEL anchor a batch of BADA signed data. This then imposes a maximum time for exploit of the current signing key-state. Any BADA verified data that is the latest seen data by a verifier but whose time stamp is older than the current batch time period window could then be reverified against the batch anchor for its appropriate time window. If that data is not included in its time window’s batch anchor then this could be flagged by the verifier as likely duplicitous data and the verifier would not trust and could re-request an update from the AID controller. This is a hybrid of KEL-backed and BADA-RUN security.

+

To elaborate, because BADA only protects that latest data-state it is only appropriate for data where only the latest data-state is important. Unlike token based systems, however, BADA does not invalidate all latest data-states every time the key-state is updated (rotated) where such invalidation would thereby force a refresh of all latest data-states. This property of not forcing auto-invalidation upon key rotation makes BADA suitable for asynchronous broadcast or gossip of the latest data-state in support of an authenticatable distributed data base. Whereas the forced auto-invalidation of data-state with token based systems limit their usefulness to access control applications (e.g. not data-bases). With BADA, however, an update of data-state only automatically auto-invalidates prior data-states. But that means that it is not useful for verifiable credentials or similar applications that must have verifiable provenance of old data-states. For example when old data-states must still be valid such as a credential issued under a now stale key-state that must still be valid unless explicitly revoked.

+

Abeit weaker than KEL backing, BADA is a significant performance and security improvment over token based systems. It also has performance advantages over KEL backing. As a result BADA is approapriate for information that does not benefit from verifiable ordering of all data-states but only the latest data-state such as a distributed data-base.

+

In BADA-RUN, the RUN stands for Read, Update, Nullify and is a replacement for CRUD in an API. CRUD does not protect from replay attacks on the data-state because a delete erases any record of last seen which destroys the monotonicity of the (date-time, key-state) tuple. Likewise Create makes no sense because the API host cannot create a recored only the remote client can. Moreover, the function of a secure BADA Update must account for both first seen and last seen so a Create verb would be entirely superflous. Nullify deactivates a record without losing the monotonicy of update guarantee. RUN provides the appropriate verbs for any API that applies the security gurantees of a BADA policy to the data-state of its records.

+

§ KRAM: Low Security

+

KERI Request Authentication Mechanism (KRAM) is the lowest security requirement and can only be used for ephemeral query/reply mechanisms that protect against replay attacks and key compromise attacks at the moment, not over time. This is done with KRAM which is a non-interactive replay attack protection algorithm that uses a sliding window of date-time stamps and key state (similar to the the tuple as in BADA-RUN) but the date-time is the replier’s not the querier’s. KRAM is meant to protect a host when providing access to information to a client from replay attacks by a malicious client. It is not meant to protect the information provided by the host. For that we must use BADA-RUN or KEL backing. Thus, by itself KRAM is not suitable to protect on-disk storage (see On-Disk Storage section below).

+

The did:webs resolver should be using KRAM to access the service endpoints providing KERI event streams for verification of the did document. This is part of what makes the local resolver trusted, it must control who has access and KRAM provides the necessary “non-interactive” basis for non-replay attackable access.

+

§ On-Disk Storage

+

Both KEL-backed and BADA-RUN 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 its just a bare signature (the datetime is not of the querier but of the host at the time of a query). But 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. But 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. But 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. Its sharing secrets and 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

+

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. But 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 down stream use of the data. A down stream 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

+

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

+

KEL backed elements in a did doc simplifies the security concerns. But 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 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.

+

§ Narrowing the attack surface

+

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.

+

§ DID Documents

+

§ Introduction

+

DID documents in this method are generated or derived from the key state of the +corresponding AID. If the AID in question is non-transferrable, then the +DID document is generated algorithmically from the DID value itself, and nothing +else. If the AID is transferrable, then the KEL and the TEL +are also required inputs to the generation algorithm.

+

DID documents for this method are pure JSON. They may be processed as JSON-LD by +prepending an @context if consumers of the documents wish.

+

Hashes, cryptographic keys, and signatures are represented as CESR strings. This +is an approach similar to multibase, making them self-describing and terse.

+

§ DID Document from KERI Events

+

The KERI event stream represents a cryptographic chain +of custody from the AID itself down to the current set of signing keys and next rotation key commitments, +as well as other data such as service endpoints. When generating a +DID document an implementation must “walk the KEL” (follow the chain of key events) to determine the current key state. Due to the fact that the KERI protocol +allows for non-establishment event (events that don’t change key state) to be intermixed in a KERI event stream with establishment +events (those that change key state), the last event may not be an establishment event and thus can not be relied on to +provide key information. In addition, the current set of witnesses is calculated from the initial set declared in the +inception event and “adds” and “cuts” declared in rotation events.

+

In KERI the calculated values that result from walking the KEL are referred to as the “current key state” and expressed +in the Key State Notice (KSN) record. An example of a KSN 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 FieldDefinitionDID Document Value
iThe AID valueThe DID Subject and DID Controller
kThe current set of public signing keysVerification Methods with associated authentication and assertion verification relationships
+

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

+

The value of the id property in the DID document MUST be the did:webs DID that is being created or resolved. +It reflects the current combined web location and AID of the identifier. +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

+

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

+

The alsoKnownAs property in the root of the DID document MAY contain other equivalent, +resolvable did:webs DIDs. The alsoKnownAs property MAY contain did:web versions of the did:webs DID(s).

+

It is anticipated that implementations of this DID method will be able to serve the same AID +as multiple DIDs, all of which are synonymous for each other. Any implementation will be able +to provide the URL endpoint required to serve any AID it is serving as a did:webs DID as for +did:web resolution. Likewise, any implementation should be able to serve any AID it is serving +as a did:webs DID and as a did:keri DID as well. Finally, the same AID may be served under +multiple domains at the same time and they should be considered the same DID since the AID portion +of the DIDs are the same.

+

For each synonymous DID defined above (we need a way in KERI to declare other domains it is being +served under, unless this is an implementation specific detail) an entry in the alsoKnownAs array +in the DID document should be created. For the 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

+

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. For each key listed in the array value of the k field +a corresponding verification method will be generated in the DID document. The ‘type’ property in the verification method for each +public key will be determined by the algorithm used to generate the public key. At the time of this writing, KERI currently +supports public key generation for Ed25519, Secp256k1 and Secp256r1 keys, however the protocol allows for others to be added at any time. +We must define the subset of public key algorithms for KERI AIDs that this specification will accept, so we can define mappings to existing verification method types as registered in the DID Specification Registries. As KERI evolves with more algorithms, new verification method types must be registered in the DID Specification Registries and added to this specification.

+

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

+

The controller property of the verification method must be the value of the id property of DID document. (Does the method spec need to specify this?)

+

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
+

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
+

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"
+      }
+    }
+  ]
+
+

§ Verification Relationships

+

KERI AID public keys can be used to sign a variety of data. This includes but is not limited to logging into a website, challenge-response exchanges and credential issuances. It follows that for each public key in k two verification relationships must be generated in the DID document. One verification relationship of type authentication and one verification relationship of type assertionMethod. The authentication verification relationship defines that the DID controller can authenticate using each key and the assertionMethod verification relationship defines that the DID controller can express claims with each key (should we address multisig and thresholds here?).

+

References to verification methods in the DID document MUST use the relative form of the identifier, e.g., "authentication": ["#<identifier>"].

+

§ Service Endpoints

+

In KERI, service endpoints are defined by 2 sets of signed data that follow the Best Available Data - Read, Update, Nullify (BADA-RUN) (ref?) rules for data processing. Detailing the rules of BADA-RUN is beyond the scope of this document but to summarize, the protocol ensures that all data is signed in transport and at rest and versioned to ensure only the latest signed data is available.

+

The two data sets used to define service endpoints are called Location Schemes and Endpoint Role Authorizations and are expressed in KERI rpy events. Location Schemes define URLs for any URL scheme that an AID has exposed. 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/"
+    }
+  }
+
+

Endpoint Role Authorizations associate a role for one AID in relation to another AID. Endpoint role authorizations are expressed in KERI rpy events with the following structure:

+
{
+    "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"
+    }
+}
+
+

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.

+

The current set of endpoint roles in KERI is contained in the following table:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
RoleDescription
controllerThe association of the key controller of an AID. These are always self-referential.
witnessA 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.
registrarCurrently unused.
watcherA componenet serving as a Watcher as defined by the KERI protocol (beyond the scope of this document).
judgeCurrently unused.
jurorCurrently unused.
peerCurrently unused.
mailboxA 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.
agentA component authorized to serve as an agent running with persistent internet connection. Provides more funcitonality than a mailbox
+
§ KERI Service Endpoints as Services
+

As defined above in KERI Service Endpoints service endpoints roles beyond witness can be defined using Location Scheme and Endpoint Authorization records in KERI. This section will map the current roles in KERI to service type values in resulting DID documents and propose a new role in KERI to map to the existing DIDCommMessaging service type declared in DID Specification Registries (ref?).

+
{
+  "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: Detail the transformation

+

§ Other Key Commitments

+

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

+

TODO: Propose new data structures in KERI and Detail the transformation

+

§ Full Example

+

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:

+
{
+  "id": "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"
+  ],
+  "verificationMethod": [
+    {
+      "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": [
+    "#1AAAAg299p5IMvuw71HW_TlbzGq5cVOQ7bRbeDuhheF-DPYk",
+    "#DA-vW9ynSkvOWv5e7idtikLANdS6pGO2IHJy7v0rypvE",
+    "#DLWJrsKIHrrn1Q1jy2oEi8Bmv6aEcwuyIqgngVf2nNwu"
+  ],
+  "assertionMethod": [
+    "#1AAAAg299p5IMvuw71HW_TlbzGq5cVOQ7bRbeDuhheF-DPYk",
+    "#DA-vW9ynSkvOWv5e7idtikLANdS6pGO2IHJy7v0rypvE",
+    "#DLWJrsKIHrrn1Q1jy2oEi8Bmv6aEcwuyIqgngVf2nNwu"
+  ],
+  "service": [
+    {
+      "id": "#EIDJUg2eR8YGZssffpuqQyiXcRVz2_Gw_fcAVWpUMie1",
+      "type": "KeriAgent",
+      "serviceEndpoint": "http://foo.example.com:3901/"
+    }
+  ]
+}
+
+

§ DID Parameters

+

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

+

§ Support for versionId

+

TODO, see https://github.com/trustoverip/tswg-did-method-webs-specification/issues/24

+

§ Support for transformKeys

+

The did:webs DID method supports the transformKeys DID parameter. This DID parameter is defined +here. (TODO: +Add proper references to external documents).

+

This allows clients to instruct a DID Resolver to return verification methods in a DID document in a desired format, +such as JsonWebKey or Ed25519VerificationKey2020.

+

§ CesrKey and publicKeyCesr

+

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

+ +

The verification method type CesrKey can 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"
+    }
+  ]
+}
+
+

§ Signed Files

+

did:webs signed files combine the semantics of folders of files on +web servers, and the DID Core 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).

+

did:webs signed files work as follows:

+ +

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:

+ +

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 can be found, verified, and +ordered relative to key state changes and other signing events.

+

§ The whois Folder

+

The did:webs method defines that a controller MAY place a folder called +whois within the root folder of the did:webs web location and place into +that signed files that are [verifiable credentials] (VCs) or +[verifiable presentations] (VPs) in which the did:webs DID is the subject of the +verifiable credential. This convention enables those that have the DID for the +controller to retrieve and verify any VCs or VPs 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 web folder, and if so, +see if it contains any useful (to the resolver) VCs or VPs that might help +in learning more about the controller of the DID (the subject of the VCs or VPs).

+

§ whois Use Case

+

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 (included in the verifiable presentation +from the student), and verify the KEL. Then it can look in the DID’s +whois folder where it might find a couple of useful VCs or VPs 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 verifiable presentations. The result is an efficient, verifiable +credential-based, decentralized, multi-domain trust registry.

+

§ whois folder Conventions

+

The whois folder, if it exists, MUST be directly below the web root folder of +the DID. The DID URL path to the folder MUST be <did:webs DID>/whois.

+

The HTTPS path to the whois folder MUST be <HTTPS URL conversion of did:webs identifier>/whois. The Web Server that serves the did:webs documents MUST +respond to a request for the HTTPS path to the whois folder with a list of the +files within the folder so that an entity looking for information about the +controller of the did:webs DID can see what verifiable credentials or +verifiable presentations are available for review.

+

The files in the whois folder must be signed files, each with +an associated [JSON Web Signature] file. The files in the folder must be either +[verifiable credentials] or [verifiable presentations] with the verifiable +credential subject id being the did:webs DID. If the file is a verifiable +presentation, the verifiable presentation proof must be signed with the +did:webs DID key(s). As with any signed files, the +accompanying [JSON Web Signature] file MUST be signed by the did:webs DID +key(s).

+
TODO

Rationalize/explain the redundant signature of the subject of the verifiable +credential in a verifiable presentation, and the signed files signature of the +controller of the DID in the JWS file beside the verifiable presentation. By +definition, both must come from keys in the the DID, although perhaps at +different points in the history of the DID, and that is verifiable by the +resolver via the KEL/TEL.

+
+

The verifiable credential or verifiable presentation format of the files can be +(at least partially) identified by the file extension. The following extensions +are recognized:

+ +

When the files are requested, the web server SHOULD be configured to include +the applicable IANA media types in the response content header.

+

The naming of the [verifiable credentials] or [verifiable presentations] files +(other than the file extension) is up to the DID controller. A future version of +this specification may define rules that DID controllers should use to make it +easier for those processing the presentations to understand them (issuer, +purpose, etc.). Similarly, verifiable credential issuers and trust communities +may define naming conventions for these files as used in their community. For +example, a registry might be created for the name of a whois file as an +“authority to issue” a specific type of credential, for any type of credential. +Or, the Education Community might develop naming conventions specifically for +the authority to issue an education credential.

+

§ KERI Fundamentals

+

KERI (Key Event Receipt Infrastructure) is a methodology for managing cryptographic keys, plus the identifiers and verifiable data structures that depend on them. KERI was first described in an academic paper, and is now a draft IETF RFC. The open source community that develops KERI-related technologies can be found at https://github.com/WebOfTrust.

+

Autonomic Identifier

+

A globally unique string that is bound to cryptographic keys in a special way. AIDs and the associated structures, the KEL and TEL, have most of the properties that DIDs require, plus a few that give them unusually special security and decentralization.

+

Key Event Log

+

The binding between an AID and its cryptographic keys is proved by a data structure called a key event log (KEL). This data structure has certain blockchain-like properties. However, a KEL differs from blockchain technology in at least two important ways:

+
    +
  1. It records the history of a single AID with a single owner, instead of an arbitrarily large collection updated by the public. This makes it tiny (a few KB), fast, cheap, and trivially scalable.
    2. +
  2. It is fully self-certifying, meaning its correctness can be proved by direct inspection, without a consensus algorithm or assumptions about trust in an external data source or its governance.
    3. +
+

Because of these properties, a KEL can be published anywhere, without special guarantees from its storage mechanism. Also, since KELs can be shared directly by the owner of an AID, and can be deleted from a particular location as needed, they avoid thorny regulatory issues like GDPR’s right of erasure.

+

A KEL allows the state of the AID to evolve. Importantly, it can record changes to key types and cryptographic algorithms. This lets an AID adapt itself to more than one blockchain ecosystem over its lifecycle. It also lets an AID adopt quantum-safe mechanisms without having to upgrade a whole blockchain ecosystem; AIDs are not locked into the cryptography used to create them.

+

Derived from Public Key

+

The KEL begins with an inception event. This event derives the AID value from the initial public key that will be used to control it. Conceptually: derive( initial_pub_key ) → AID. Forcing a relationship between AID and key in this way eliminates an early chain-of-custody risk that plagues many DID methods (an attacker creates a DID without a key-owner’s knowledge, using compromised keys). It is similar to techniques used by did:key, did:peer, did:sov, and did:v1.

+

The simplest AIDs (called direct mode AIDs in KERI) 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. Direct mode AIDs are ideal for ephemeral use cases and are excellent analogs (and convenient interop tools) to did:key and did:peer with numalgo=0 (see Transformations.) However, this is not the only option. KERI offers richer choices that are especially valuable if an AID is intended to have a long lifespan.

+

Pre-rotation

+

Optionally, the inception event of an AID can also reference the hash of the next key that will be used to control the AID. This changes how the AID is derived: derive( initial_public_key, next_key_hash ). KERI calls this feature pre-rotation; AIDs that use it 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 thus non-transferrable.

+

Pre-rotation has profound security benefits. If a malicious party steals the private key for an AID with this feature, they only accomplish temporary mischief, because the already-existing KEL contains a commitment to future state. This prevents them from rotating the stolen AID’s key to an arbitrary value of their choosing. As soon as the AID owner suspects a compromise, they can do a valid rotation that locks the attacker out again.

+

Weighted Multisig

+

KELs can enforce the choice to distribute control among multiple key-holders. This includes simple M-of-N rules like “3 of 5 keys must sign to change the AID’s state,” but also more sophisticated configurations: “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 addition, KELs allow an AID owner to declare that an AID has witnesses. This choice also changes how the AID value is derived: derive( initial_public_key, next_key_hash, witnesses ). Witnesses are independent, highly decentralized parties (web sites, blockchains, etc.) that each publish a copy of the KEL.

+

Witnesses do not coordinate or come to consensus with one another, and 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 owner) has to report those changes to the witnesses that are currently active, to produce a valid evolution of the KEL. The AID owner and all witnesses thus hold one another accountable. Further, it becomes possible to distinguish between duplicity and imperfect replication of state.

+

Transaction Event Log

+

KERI supports an official mechanism for binding an identifier to important, non-repudible actions that must relate with deterministic order to the key rotation events in the KEL. This transaction event log (TEL) is how an AID can tell the world it has issued and revoked credentials, started or stopped listening on a service endpoint, and so forth. TELs are self-certifying, just like KELs, but are also 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

+

KERI uses CESR ](https://weboftrust.github.io/ietf-cesr/draft-ssmith-cesr.html)(Composable Event Streaming Representation) to serialize data. This is a deep subject all by itself, but at a high level, it means two things:

+ +

Despite this rich set of features, KERI imposes only light dependencies on developers. The cryptography it uses is familiar and battle-hardened — exactly what you’d find in standard toolkits for big numbers and elliptic curves. For example, the python implementation uses just the pysodium, blake3, and cryptography packages. Libraries for KERI exist in javascript, rust, and python.

+

§ Transformations

+

Some DIDs created with other DID methods can be deterministically transformed into a did:webs. This allows identifiers to function transparently in more than a pure did:webs ecosystem, and facilitates migration and upgrade. To a lesser extent, equivalency transformations may also be possible the other direction, although potential lossiness in security is a concern.

+

§ did:key

+

A did:key can be transformed into a did:webs by using its public key as the sole input to an inception event for a KERI direct mode AID. Essentially this re-expresses the entropy from did:key’s SHA256 hash as the Blake-3 hash of the CESR encoding of the same key. The result is an AID that has no witnesses and that cannot rotate keys. Both methods are self-certifying, inception inputs are mappable, and semantics match.

+

The opposite transformation is also generally valid, with the caveat that KERI supports more key types than did:key. As long as the key types map, a KERI direct mode AID can be expressed as a did:key with zero information loss.

+

Theoretically, a transferrable AID could also be transformed into a did:key. However, the conversion would be lossy, because the controller of the AID intends semantics (pre-rotation protections) that did:key cannot express. If an AID has witnesses (whether the AID is transferrable or not), there is a similar problem with lost protections. Therefore, this transformation is discouraged as an interop strategy, even if the AID has nothing but an inception event.

+

§ did:peer

+

Since did:peer with numalgo=0 exactly matches the format, semantics, and intent of did:key, such peer DIDs have exactly the same transformation potential, in both directions, as did:key.

+

Fancier peer DIDs have a numeric basis other than numalgo=0. Static peer DIDs in this category can store service endpoints and additional keys in a DID document. A did:webs can express these same semantics via its TEL. Thus, static peer DIDs may be transformable to non-transferrable did:webs without witnesses. Dynamic peer DIDs cannot be transformed to a did:webs because they are transferrable yet lack a next key to satisfies KERI’s pre-rotation feature.

+

§ Other DIDs using KERI AIDs as MSI

+

Any DID method that uses a KERI AID as its MSI is trivially and losslessly transformable in both directions, since the did:webs method defines all DID documents with the same AID to be instances of metadata for the same identifier. This could be the basis of future work on a DID method for environments using extremely constrained hardware or exotic transport protocols, for example.

+

§ Additional DID Methods

+

A did:webs may also be transformable to or from other DID types as well (e.g., ones using a blockchain as a VDR). However, caveats apply:

+ + + + + + + + + + + + + + + + + +
DirectionCaveats
other → did:websThe other method MUST be self-certifying. The resulting AID will either use direct mode or be non-transferrable, without witnesses.
did:webs → otherThe KEL MUST contain only an inception event. The other method MUST NOT require an inception input that’s unavailable to KERI (e.g., a payment address or user handle). The AID MUST be non-transferrable (unless the other method supports pre-rotation). The AID MUST NOT use weighted multi-sig (unless the other method supports it).
+

§ IANA Considerations

+

This document has no IANA actions.

+

§ Security Considerations

+

Perfect protection from eavesdropping is not possible with HTTPS, for various +reasons. However, 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, it safeguards privacy, discourages denial of +service, accords with a defense-in-depth mindset, aids regulatory compliance, +and makes it easier to troubleshoot. How a URL is hosted should let clients +fetch a DID document and a KERI event stream with roughly the same confidence that’s associated +with properly implemented online banking.

+

The fully qualified domain name of the method-specific identifier is +secured by a TLS/SSL certificate. The fully qualified domain name MUST match the common name used +in the SSL/TLS certificate.

+

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. Unlike did:web, the URL MAY use an IP address +instead. If it does, then the common name in the certificate must be the IP +address as well. 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.

+

The server certificate MAY be self-issued, 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:

+ +

If a URL of a DID document or KERI event streams results in a redirect, each URL MUST satisfy the same security +requirements. A URL MAY come from a URL shortener.

+

§ Privacy Considerations

+
TODO

TODO: talk about ephemeral vs. long-lived identifiers, and about using witnesses.

+
+

§ References

+

§ Normative References

+
TODO

Add normative references

+
+

§ Informative References

+
TODO

Add informative references

+
+

§ Acknowledgements

+
TODO

Add Acknowledgements

+
+

§ Authors’ Addresses

+
TODO

Add authors’ addresses.

+
+ +
+ +
+ + + +
+ + + + + ✕ +
+ + + + +
+ Table of Contents + ✕ +
+
+ + +
+ + + + + + + + + + \ No newline at end of file