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..d590f33 --- /dev/null +++ b/index.html @@ -0,0 +1,1977 @@ + + + + + + + + + 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:

+ +

Contributors:

+ + +
+
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 a manageable 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 straightforward. 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 - 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 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 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

+

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

+
+
authentic chained data container (ACDC)
+
a variant of the Verifiable Credential (VC) specification that inherit the security model derived from KERI, as defined by the draft ACDC specification. See WebOfTrust wiki for more detail.
+
autonomic identifier (AID)
+
A DID that is self-certifying and cryptographically bound to a key event log (KEL), as defined by the draft 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 wiki 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 draft CESR specification and draft CESR Proof Signature specification. See WebOfTrust wiki 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 wiki for more detail.
+
decentralized identifier (DID)
+
A globally unique persistent identifier, as defined by the DID Core.
+
DID document
+
A set of data describing the subject of a DID, as defined by DID Core. See also section DID Documents.
+
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 wiki for more detail.
+
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 draft KERI specification. See WebOfTrust wiki 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 wiki for more detail.
+
interaction event
+
A key event that anchors external data to an AID, as defined by the draft KERI specification. An interaction event does not change the key state of the AID. See WebOfTrust wiki 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 draft KERI specification. There are three types of key events, namely inception event, rotation event, and interaction event. See WebOfTrust wiki for more detail.
+
key event log
+
A verifiable append-only log of key events for an AID that is both backward and forward-chained, as defined by the draft KERI specification. See WebOfTrust wiki 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 draft KERI specification. See WebOfTrust wiki 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 draft KERI specification. See WebOfTrust wiki 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 draft KERI specification. See WebOfTrust wiki 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 wiki 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 wiki for more detail.
+
method-specific identifier
+
The method-specific-id part of DID Syntax, as defined in DID Core. See section Method-Specific Identifier.
+
out-of-band introduction (OOBI)
+
A protocol for discovering verifiable information on an AID or a SAID, as defined by the draft OOBI specification. The OOBI by itself is insecure, and the information discovered by the OOBI must be verified. See WebOfTrust wiki 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 draft KERI specification. See WebOfTrust wiki 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 draft KERI specification. See WebOfTrust wiki 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 draft SAID specification. See WebOfTrust wiki 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 wiki for more detail.
+
verifier
+
An entity or component that cryptographically verifies the signature(s) on an event message. See WebOfTrust wiki 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 wiki 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 wiki for more detail.
+
+

§ 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 surpassing +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 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.

+

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, except for minor differences in the id, controller, and alsoKnownAs top-level properties that pertain to the identifiers themselves.

+

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 KERI event stream MUST be CESR-formatted (media type of application/cesr) and the KERI events must be verifiable using the KERI rules.

+

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 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 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” of “security” 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 inseparably 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 on 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. In contrast, if the controller confirms the link between the source and the copy with an AlsoKnownAs, the related copies will have to be looked after.

+

§ DID Method Operations

+

§ Create

+

Creating a did:webs DID involves the following steps:

+
    +
  1. 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. +
  2. Create a KERI AID and add it as the last element of the web URL for the DID.
    3. +
  3. 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. +
  4. Derive the did:webs DID document by processing the KERI event stream +according to section DID Document from KERI Events.
    5. +
  5. For compatibility reasons, transform the derived did:webs DID document to the corresponding did:web DID document according to section Transformation to did:web DID Document.
    6. +
  6. 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.
    7. +
+

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.

+

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

+

§ Read (Resolve)

+

Resolving a did:webs DID involves the following steps:

+
    +
  1. Convert the did:webs DID back to HTTPS URLs as described in section Target System(s).
    2. +
  2. 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. +
  3. 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. +
  4. Transform the retrieved did:web DID document to the corresponding did:webs DID document according +to section Transformation to did:webs DID Document.
    5. +
  5. Verify that the derived did:webs DID document (from step 3) equals the transformed DID document (from step 4).
    6. +
+

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. +We use KEL-backed security for the highest possible security of on-disk storage, but also the most costly because it uses space in KELs. BADA-RUN is medium security and makes sure events are ordered in a consistent way, using a combination of date-time and a key state. Without having to negotiate security in did:webs we use a lower level of security when appropriate.

+

§ 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). By design 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-verifiably 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 specification. It makes sure 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. This level of security is sufficient for discovery information because the worst-case attack on discovery information is a DDoS attack 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 attack is to have redundant discovery sources. We use BADA-RUN for service end-points as discovery mechanisms. Of course we could anchor service endpoints to KELs and make them more secure. All things considered, due to the dynamics of discovery mechanisms we decided to not bloat the KEL with discovery anchors. Because the worst case can be mitigated with redundant discovery, BADA-RUN is a defensible choice.

+

Monotonicity (or consistent ordering) 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 compromise 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.

+

Albeit weaker than KEL backing, BADA is a significant performance and security improvement 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 record 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 guarantees 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. By processing the KERI event stream of the AID, the generation algorithm will be reading the AID KEL (and possibly TEL) +to produce the DID document.

+

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 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 domains, 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 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
ktThe current signing keys thresholdThe 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

+

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

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 will be generated in the DID document. This verification method type is defined here: +https://w3c-ccg.github.io/verifiable-conditions/ (TODO: add proper references).

+

It is constructed according to the following rules:

+ +

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": "2",  // 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": 2,
+      "conditionThreshold": [
+        "#1AAAAg299p5IMvuw71HW_TlbzGq5cVOQ7bRbeDuhheF-DPYk",
+        "#DA-vW9ynSkvOWv5e7idtikLANdS6pGO2IHJy7v0rypvE",
+        "#DLWJrsKIHrrn1Q1jy2oEi8Bmv6aEcwuyIqgngVf2nNwu"
+      ]
+    },
+    {
+      "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:

+
{
+  "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": 6,
+      "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

+

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:

+

If the value of kt == 1:

+ +

If the value of kt > 1 or if the value of kt is an array containing fractionally weighted thresholds:

+ +

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

+
§ Key Agreement
+

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

+ +

§ Service Endpoints

+

did:webs supports 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
+

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.

+

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
+
§ Defining new service types
+

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

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

+

§ 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. This section +defines a simple transformation algorithm from a did:webs DID document to a did:web DID document.

+

Given a did:webs DID document, construct a new did:web DID document with the following differences:

+ +

This transformation is used during the Create DID method operation.

+

For example, 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.

+

Given a did:web DID document, construct a new did:webs DID document with the following differences:

+ +

This transformation is used 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

+

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": "#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

+

When processing the KERI event stream there are two broad types of key state events (KERI parlance is ‘establishment events’) that can alter the key state of the AID. Any change in key state of the AID will be reflected in the DID document. +If a key state event does not commit to a future set of rotation key hashes, then the AID can’t be rotated to new keys in the future (KERI parlance is that the key state of the AID becomes ‘non-transferrable’). 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 is the foundation of pre-rotation, is post-quantum safe, and allows the controller to recover from key compromise.

+ +

§ 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

+ +

§ Service Endpoint event details

+

TODO: Define and detail the service endpoint events

+

§ DID Parameters

+

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. (TODO: Add proper references to external documents).

+

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.

+

Valid values for this DID parameter are sequence numbers of events in the KERI event stream. When a did:webs +DID is resolved with this DID parameter, then the DID Resolver 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. (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.

+

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:

+ +

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

§ DID Metadata

+

This section describes the support of the did:webs method for metadata, as described in sections +DID Resolution Metadata and +DID Document Metadata in the DID Core specification.

+

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

+

DID resolution metadata is metadata about the DID Resolution process that was performed in order to obtain +the DID document for a given DID.

+

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

+

DID document metadata is metadata about the DID and the DID document that is the result of the DID +Resolution process. This specification defines how various DID document metadata properties are used +by the did:webs method.

+

§ Use of versionId

+

This DID document metadata property indicates the current version of the DID document that has been +resolved.

+

In the case of did:webs, this is defined to 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.

+

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 is 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

+

This DID document metadata property indicates the next version of the DID document after the version that has been +resolved.

+

In the case of did:webs, this is defined to 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.

+

This DID document metadata property is only 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

+

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

+

In the case of did:webs, this metadata property SHOULD contain a list of other known did:webs DIDs that differ +in the domain name and/or port portion of the method-specific identifier +but share the same AID. Also see section Equivalent Identifiers.

+

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

+

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 DID URL

+

The did:webs method defines that a controller MAY publish a W3C Verifiable +Credentials Data Model Standard Verifiable Presentation beside the DID +Doc (did.json). The Verifiable Presentation is referenced using the DID <did>/whois and can be resolved using the HTTPS DID path <DID URL>/whois.vp. The Verifiable Presentation MUST ONLY contain Verifiable +Credentials where the did:webs DID is the subject of the Credential.

+

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

+

§ whois DID URL Conventions

+

The whois object, if it exists, MUST be directly beside the did:json +file, the DID Document for 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.vp. The Web Server that serves the did:webs documents +MUST respond to a request for the HTTPS whois URL the Verifiable Presentation published there by the DID Controller. 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”).

+

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. All of the +Verifiable Credentials in the Verifiable Presentation MUST have the did:webs +DID as the credential subject.

+

The Verifiable Presentation may be in one of three formats:

+ +

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.

+

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

+

In this spec we generically refer to the CESR event stream of KEL and TEL events as the KERI event stream which is used to verify the did:webs DID document.

+

§ 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

+

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

+
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