§ ToIP did:webs
Method Specification v0.9.15
+Specification Status: Implementors Draft
+In order to further validate and improve the specification and to demonstrate interoperability between multiple implementations of did:webs, we encourage additional did:webs implementations to the original did:webs Reference Implementation.
+Latest Draft:
+https://github.com/trustoverip/tswg-did-method-webs-specification
+Editors:
+-
+
- Phil Feairheller, GLEIF +
- Daniel Hardman, Provenant, Inc +
- Sam Smith, Prosapien +
- Lance Byrd, GLEIF and RootsID +
Contributors:
+-
+
- Markus Sabadello, Danube Tech and DIF +
- Kevin Griffin, GLEIF +
- Charles Lanahan +
- Nuttawut Kongsuwan, Finema +
- Darrell O’Donnell, Continuum Loop Inc. +
-
+
- Participate: +
- GitHub repo +
- Commit history +
+
§ Abstract
+This document specifies a DID
+Method,
+did:webs
, that is web-based but innovatively secure. Like its
+interoperable cousin, did:web
, the
+did:webs
method uses traditional web infrastructure to publish DIDs and
+make them discoverable. Unlike did:web
, this method’s trust is not rooted in
+DNS, webmasters, X509, and certificate authorities. Instead, it uses KERI to provide a secure chain of cryptographic key events by those who
+control the identifier.
The did:webs
method does not need blockchains to establish trust. However, its use of
+KERI allows for arbitrary blockchains to be referenced as an extra, optional
+publication mechanism. This offers a potentital interoperability bridge from (or between)
+blockchain ecosystems. Also, without directly supporting environments where the
+web is not practical (e.g., IOT, Lo-Ra, Bluetooth, NFC), the method builds on a
+foundation that can fully support those environments, making future interop of
+identifiers between web and non-web a manageable step for users of did:webs
identifiers.
All DID methods make tradeoffs. The ones in did:webs
result in a method that
+is cheap, easy to implement, and scalable. No exotic or unproven cryptography is
+required. Deployment is straightforward. Cryptographic trust is strongly
+decentralized and governance is transparent. Regulatory challenges around the issue of
+blockchains vanish. Any tech community or legal jurisdiction can use it. However,
+did:webs
does depend on the web for publication and discovery. This may
+color its decentralization and privacy. For its security, it adds KERI,
+imposing a modest - to significant learning curve as a result. For users, the method also raises
+the bar of accountability, thoughtfulness, and autonomy; this can be viewed as
+either a drawback or a benefit (or both).
§ Status of This Memo
+This document contains the specification for the did:webs
DID method.
Information about the current status of this document, any errata, +and how to provide feedback on it, may be obtained at +https://github.com/trustoverip/tswg-did-method-webs-specification.
+§ Copyright Notice
+This specification is subject to the OWF Contributor License Agreement 1.0 - Copyright +available at +https://www.openwebfoundation.org/the-agreements/the-owf-1-0-agreements-granted-claims/owf-contributor-license-agreement-1-0-copyright.
+If source code is included in the specification, that code is subject to the +Apache 2.0 license unless otherwise marked. In the case of any conflict or +confusion within this specification between the OWF Contributor License +and the designated source code license, the terms of the OWF Contributor License shall apply.
+These terms are inherited from the Technical Stack Working Group at the Trust over IP Foundation. Working Group Charter
+§ Introduction
+This section is informative.
+DID methods answer many questions. Two noteworthy ones are:
+-
+
- How is information about DIDs (in the form of DID documents) published and discovered? +
- How is the trustworthiness of this information evaluated? +
The previously released did:web
method merges these two questions, giving one answer: Information is published and secured using familiar web mechanisms. This has wonderful adoption benefits, because the processes and tooling are familiar to millions of developers.
Unfortunately, this answer works better for the first question than the second. The current web is simply not very trustworthy. Websites get hacked. Sysadmins are sometimes malicious. DNS can be hijacked. X509 certs often prove less than clients wish. Browser validation checks are imperfect. Different certificate authorities have different quality standards. The processes that browser vendors use to pre-approve certificate authorities in browsers are opaque and centralized. TLS is susceptible to man-in-the-middle attacks on intranets with customized certificate chains. Governance is weak and inconsistent…
+Furthermore, familiar web mechanisms are almost always operated by corporate IT staff. This makes them an awkward fit for the ideal of decentralized autonomy — even if individuals can publish a DID on corporate web servers, those individuals are at the mercy of IT personnel for their security.
+The did:webs
method described in this spec separates these two questions and answers them distinctively. Information about DIDs is still published on the web, but its trustworthiness derives from mechanisms entirely governed by individual DID controllers. This preserves most of the delightful convenience of did:web
, while drastically upgrading security through authentic data that is end-verifiable.
Within the context of did:webs
the term decentralized trust includes verifiability, confidentiality, and privacy, but excludes veracity of the content. The latter is always a matter of (personal) evaluation of available reputational data and verifiable credentials (VCs).
§ Requirements, Notation and Conventions
+This section is normative.
+§ Keywords
+The following key words in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here:
+-
+
- “MUST” +
- “MUST NOT” +
- “REQUIRED” +
- “SHALL” +
- “SHALL NOT” +
- “SHOULD” +
- “SHOULD NOT” +
- “RECOMMENDED” +
- “NOT RECOMMENDED” +
- “MAY” +
- “OPTIONAL” +
§ Conventions
+-
+
- Normative sections MUST start with “This section is normative.” +
- Normative statements SHOULD read in a way that can be implemented. +
- Normative statements MUST be numbered so that they are easily referenced and addressed in discussions, issues, pull requests, etc. +
- Informative sections MUST start with “This section is informative.” +
- Informative statements MUST NOT be numbered. Instead they can use prose or bulleted points. +
- If informative statements accompany normative statements then they MUST be separated like:
+
+
+This is informative text accompanying but separated from the normative statements.
+
+ - If a normative section contains an informative sub-section then the sub-section MUST be marked with “This section is informative.” +
§ Core Characteristics
+This section is normative.
+§ Method Name
+-
+
- The method name that identifies this DID method SHALL be:
webs
.
+ - 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, MUST be the case-sensitive method-specific identifier +(MSI) described below. +
++Note: when pronounced aloud, “webs” should become two syllables: the word “web” and the letter “s” (which stands for “secure”). Separating the final letter this way emphasizes that the method offers a security upgrade surpassing the one HTTPS gives to HTTP.
+
§ Method-Specific Identifier
+-
+
-
+
The
+did:webs
method-specific identifier MUST have two parts, a host with an optional path (identical todid:web
), plus a KERI AID (autonomic identifier) that is always the final component of the path.
+ -
+
The ABNF definition of a
+did:webs
DID MUST be as follows:
+webs-did = "did:webs:" host [pct-encoded-colon port] *(":" path) ":" aid + +; 'host' as defined in RFC 1035 and RFC 1123 +host = *( ALPHA / DIGIT / "-" / "." ) ; Simplified representation, actual RFCs + ; have more complex rules for domains and IP addresses. + ; IN ACTUAL IMPLEMENTATIONS REPLACE WITH A MATURE + ; HOST PARSING LIBRARY. + +; 'pct-encoded-colon' represents a percent-encoded colon +pct-encoded-colon = "%3A" / "%3a" ; Percent encoding for ':' + +; 'port' number (simplified version) +port = 1*5(DIGIT) + +; 'path' definition +path = 1*(ALPHA / DIGIT / "-" / "_" / "~" / "." / "/") + +; 'aid' as base64 encoded value +aid = 1*(ALPHA / DIGIT / "+" / "/" / "=") ; Base64 characters + +; ALPHA, DIGIT are standard ABNF primitives for alphabetic and numeric characters +
+ -
+
The host MUST abide by the formal rules describing valid syntax found in RFC1035, RFC1123, and RFC2181.
+
+ -
+
A port MAY be included and the colon MUST be percent encoded, like
+%3a
, to prevent a conflict with paths.
+ -
+
Directories and subdirectories MAY optionally be included, delimited by colons rather than slashes.
+
+ -
+
The KERI AID is a unique identifier and MUST be derived from the inception event of a KERI identifier.
+
+
++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 adid:webs
always has a path,and so the “no path” version of adid:web
that implicitly uses the.well-known
folder is not supported bydid:webs
. Anydid:webs
can be expressed as adid:web
but the inverse is not true–adid:webs
must include an AID.
§ Target System(s)
+-
+
- As with
did:web
,did:webs
MUST read data from whatever web server is referenced when the host portion of one of its DID is resolved.
+ - A
did:webs
DID MUST resolve to a DID document using a simple text transformation to an HTTPS URL in the same way as adid:web
DID.
+ - A
did:web
DID anddid:webs
DID with the same method-specific identifier SHOULD return the same DID document, except for minor differences in theid
,controller
, andalsoKnownAs
top-level properties that pertain to the identifiers themselves.
+ - As with
did:web
, the location of the DID document MUST be determined by transforming the DID to an HTTPS URL as follows: +-
+
- MUST replace
did:webs
withhttps://
+ - MUST replace the "
:
"s in the method-specific identifier with path separators, "‘/’"s
+ - MUST convert the optional port percent encoding (“
%3A
”`) to a colon if present.
+ - MUST append “
/did.json
” to the resulting string.
+
+ - MUST replace
- A GET on that URL MUST return the DID document. +
- The location of the KERI event stream MUST be determined by transforming the previous URL as follows:
+
-
+
- MUST replace the trailing “
/did.json
” with “/keri.cesr
”.
+ - 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. +
+ - MUST replace the trailing “
- The
did:web
version of the DIDs MUST be the same (minus thes
) and point to the samedid.json
file, but have no knowledge of thekeri.cesr
file.
+
For more information, see the following sections in the implementors guide:
+-
+
- the set of KERI features needed to support
did:webs
+
++A target system cannot forge or tamper with data protected by KERI, and if it deliberately serves an outdated copy, the duplicity is often detectable. Thus, any given target system in isolation can be viewed by this method as a dumb, untrusted server of content. It is the combination of target systems and some KERI mechanisms, together, that constitutes this method’s verifiable data registry. In short, verifying the DID document by processing the KERI event stream using KERI puts the “s” of “security” in
+did:webs
.
The following are some example did:webs
DIDs and their corresponding DID documents and KERI event stream
+URLs, based on the examples from the did:web Specification, but with the (faked) AID
+12124313423525
added:
-
+
did:webs:w3c-ccg.github.io:12124313423525
+-
+
- The DID document URL would look like:
https://w3c-ccg.github.io/12124313423525/did.json
+ - KERI event stream URL would look like:
https://w3c-ccg.github.io/12124313423525/keri.cesr
+
+- The DID document URL would look like:
did:webs:w3c-ccg.github.io:user:alice:12124313423525
+-
+
- DID document URL would look like:
https://w3c-ccg.github.io/user/alice/12124313423525/did.json
+ - KERI event stream URL would look like:
https://w3c-ccg.github.io/user/alice/12124313423525/keri.cesr
+
+- DID document URL would look like:
did:webs:example.com%3A3000:user:alice:12124313423525
+-
+
- DID document URL would look like:
https://example.com:3000/user/alice/12124313423525/did.json
+ - KERI event stream URL would look like:
https://example.com:3000/user/alice/12124313423525/keri.cesr
+
+- DID document URL would look like:
§ AID controlled identifiers
+-
+
- AID controlled identifiers MAY vary in how quickly they reflect the current identity information, DID document and KERI event stream. Notably, as defined in section Identifiers in a
did:webs
DID document, theid
property in the DID document will differ based on the web location of the DID document.
+ - 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 verification of the KERI event stream SHOULD provide mechanisms for detecting the forking of the KERI event stream by using mechanisms such as KERI witnesses and watchers. +
++Since an AID is a unique cryptographic identifier that is inseparably bound to the KERI event stream it is associated with any AIDs and any
+did:webs
DIDs that have the same AID component. It can be verifiably proven that they have the same controller(s).
§ Handling Web Redirection
+-
+
-
+
A
+did:webs
MAY be a “stable” (long-lasting) identifier that can be put into documents such as verifiable credentials, to be useful for a very long time – generations.
+ -
+
When a
+did:webs
is updated for another location the following rules MUST apply:-
+
- Its AID MUST not change. +
- The same KERI event stream MUST be used to verify the DID document, with the only change being the designated aliases list reflecting the new location identifier. +
- If a resolver can find a newly named DID that uses the same AID, and the KERI event stream verifies the DID, then the resolver MAY consider the resolution to be successful and should note it in the resolution metadata. +
+ -
+
The following resolution paths that
+did:webs
identfiers SHALL leverage to help in the face of resolution uncertainty:-
+
- The
did:webs
DID SHALL provide other designated aliases DID(s) that are anchored to the KERI event stream.
+ - When a
did:webs
is permanently moved to some other location the resolver MAY redirect to any otherequivalentId
designated aliases. +-
+
- The
id
in the DID document MUST be set to the new location.
+ - An
equivalentId
entry of the old location SHOULD remain for historical purposes and anchored to the KERI event stream using designated aliases. See section Use ofequivalentId
for more details.
+ - If possible, the controller of the DID MAY use web redirects to allow resolution of the old location of the DID to the new location. +
+ - The
- If the previously published location of a
did:webs
is not redirected, an entity trying to resolve the DID MAY be able to find the data for the DID somewhere else using just the AID.
+
+ - The
-
+
- The implementors guide contains more information about
did:webs
stable identifiers on an unstable web.
+
§ DID Method Operations
+§ Create
+-
+
- Creating a
did:webs
DID MUST follow these rules: +-
+
- MUST choose the web URL where the DID document for the DID will be published, excluding the last element that will be the AID, once defined. +
- MUST create a KERI AID and add it as the last element of the web URL for the DID. +
- MUST add the appropriate KERI events to the AID’s KERI logs that will correspond to properties of the DID document, such as verification methods and service endpoints. +
- MUST derive the
did:webs
DID document by processing the KERI event stream according to section DID Document from KERI Events.
+ - For compatibility reasons, transformation of the derived
did:webs
DID document to the correspondingdid:web
DID document MUST be according to section Transformation to did:web DID Document.
+ - MUST create the AID folder on the web server at the selected location, and place the
did:web
DID document resource (did.json
) and the KERI event stream resource (keri.cesr
) into that folder. See section Target System(s) for further details about the locations of these resources.
+
+
++Of course, the web server that serves the resources when asked might be a simple file server (as implied above) or an active component that generates them dynamically. Further, the publisher of the resources placed on the web can use capabilities like [CDNs] to distribute the resources. How the resources are posted at the required location is not defined by this spec; complying implementations need not support any HTTP methods other than GET.
+
++An active component might be used by the controller of the DID to automate the process of publishing and updating the DID document and KERI event stream resources.
+
§ Read (Resolve)
+-
+
- Resolving a
did:webs
DID MUST follow these steps: +-
+
- MUST convert the
did:webs
DID back to HTTPS URLs as described in section Target System(s).
+ - MUST execute HTTP GET requests on both the URL for the DID document (ending in
/did.json
) and the URL for the KERI event stream (ending in/keri.cesr
).
+ - MUST process the KERI event stream using [KERI Rules] to verify it, then derive the
did:webs
DID document by processing the KERI event stream according to section DID Document from KERI Events.
+ - MUST transform the retrieved
did:web
DID document to the correspondingdid:webs
DID document according to section Transformation to did:webs DID Document.
+ - MUST verify that the derived
did:webs
DID document equals the transformed DID document.
+ - KERI-aware applications MAY use the KERI event stream to make use of additional capabilities enabled by the use of KERI. +
+ - MUST convert the
++Capabilities beyond the verification of the DID document and KERI event stream are outside the scope of this specification.
+
§ Update
+-
+
- If the AID of the
did:webs
DID is updatable, updates MUST be made to the AID by adding KERI events to +the KERI event stream.
+ - Updates to the KERI event stream that relate to the
did:webs
DID MUST be reflected in the DID Document as soon as possible. +-
+
- If the
did:webs
DID files are statically hosted then they MUST be republished to the web server, overwriting the existing files.
+
+ - If the
§ Deactivate
+-
+
- To deactivate a
did:webs
DID, A controller SHOULD execute a KERI event that has the effect of rotating the key(s) to null and continue to publish the DID document and KERI event stream. +-
+
- Once the deactivation events have been applied, the controller SHOULD regenerate the DID document from the KERI event stream and republish both documents (did.json and keri.cesr) to the web server, overwriting the existing files. +
- A controller SHOULD NOT remove the DID folder and files from the web server on which it has been published. This is considered to be a bad approach, as those resolving the DID will not be able to determine if the web service is offline or the DID has been deactivated. +
+
§ DID Documents
+This section is normative.
+-
+
did:webs
DID documents MUST be generated or derived from the Keri event stream of the corresponding AID. +-
+
- Processing the KERI event stream of the AID, the generation algorithm MUST read the AID KEL and any anchored TELs to produce the DID document. +
+did:webs
DID documents MUST be pure JSON. They MAY be processed as JSON-LD by prepending an@context
if consumers of the documents wish.
+- All hashes, cryptographic keys, and signatures MUST be represented as CESR strings. This is an approach similar to multibase, making them self-describing and terse. +
To better understand the cryptographically verifiable data structures used, see the implementors guide description of the KERI event stream chain of custody
+To understand the KERI AID commands resulting in the KERI Event Stream and the corresponding did:webs
DID document see the original did:webs Reference Implementation GETTING STARTED guide.
In KERI the calculated values that result from processing the KERI event stream are referred to as the “current key state” and expressed +in the Key State Notice (KSN) record. An example of a KERI KSN record can be seen here:
+{
+ "v": "KERI10JSON000274_",
+ "i": "EeS834LMlGVEOGR8WU3rzZ9M6HUv_vtF32pSXQXKP7jg",
+ "s": "1",
+ "t": "ksn",
+ "p": "ESORkffLV3qHZljOcnijzhCyRT0aXM2XHGVoyd5ST-Iw",
+ "d": "EtgNGVxYd6W0LViISr7RSn6ul8Yn92uyj2kiWzt51mHc",
+ "f": "1",
+ "dt": "2021-11-04T12:55:14.480038+00:00",
+ "et": "ixn",
+ "kt": "1",
+ "k": [
+ "DTH0PwWwsrcO_4zGe7bUR-LJX_ZGBTRsmP-ZeJ7fVg_4"
+ ],
+ "nt": 1,
+ "n": [
+ "E6qpfz7HeczuU3dAd1O9gPPS6-h_dCxZGYhU8UaDY2pc"
+ ],
+ "bt": "3",
+ "b": [
+ "BGKVzj4ve0VSd8z_AmvhLg4lqcC_9WYX90k03q-R_Ydo",
+ "BuyRFMideczFZoapylLIyCjSdhtqVb31wZkRKvPfNqkw",
+ "Bgoq68HCmYNUDgOz4Skvlu306o_NY-NrYuKAVhk3Zh9c"
+ ],
+ "c": [],
+ "ee": {
+ "s": "0",
+ "d": "ESORkffLV3qHZljOcnijzhCyRT0aXM2XHGVoyd5ST-Iw",
+ "br": [],
+ "ba": []
+ },
+ "di": ""
+}
+
+Using this key state as reference, we can identify the fields from the current key state that will translate to values +in the DID document. The following table lists the values from the example KSN and their associated values in a DID document:
+Key State Field | +Definition | +DID Document Value | +
---|---|---|
i |
+The AID value | +The DID Subject and DID Controller | +
k |
+The current set of public signing keys | +Verification Methods with associated authentication and assertion verification relationships | +
kt |
+The current signing keys threshold | +The threshold in a Verification Method of type ConditionalProof2022 |
+
In several cases above, the value from the key state is not enough by itself to populate the DID document. The following +sections detail the algorithm to follow for each case.
+§ DID Subject
+-
+
- The value of the
id
property in the DID document MUST be thedid:webs
DID that is being created or resolved.
+ - The value from the
i
field MUST be the value after the last:
in the method-specific identifier (MSI) of thedid: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 theid
(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 any DID that has the same AID. See the designated aliases section for information on how an AID anchors thealsoKnownAs
identifiers to their KERI event stream.
+ did:webs
DIDs MUST serve thedid:webs
and correspondingdid:web
as analsoKnownAs
identifier.
+did:webs
DIDs MUST provide the correspondingdid:keri
as analsoKnownAs
identifier.
+- The same AID MAY be associated with multiple
did:webs
DIDs, each with a different host and/or path, but with the same AID.
+ did:webs
DIDs MUST be listed in the designated aliases attestation of the AID.
+- For each AID controlled identifier DID defined above, an entry in the
alsoKnownAs
array in the DID document MUST be created.
+
For the example DID did:webs:did-webs-service%3a7676:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe
the following alsoKnownAs
entries could be created:
{
+ "alsoKnownAs": [
+ "did:web:did-webs-service%3a7676:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "did:webs:did-webs-service%3a7676:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "did:web:example.com:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "did:web:foo.com:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "did:webs:foo.com:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe"
+ ]
+}
+
+§ Verification Methods
+-
+
- For each key listed in the array value of the
k
field of the KSN, a corresponding verification method MUST be generated in the DID document.
+ - The ‘type’ property in the verification method for each public key MUST be determined by the algorithm used to generate the public key. +
- The verification method types used 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 theid
property of the DID document.
+
++KERI identifiers express public signing keys as Composable Event Streaming Representation (CESR) encoded strings in the
+k
field of establishment events and the key state notice. CESR encoding encapsulates all the information needed to determine the cryptographic algorithm used to generate the key pair.
++At the time of this writing, KERI currently supports public key generation for Ed25519, Secp256k1 and Secp256r1 keys, and the protocol allows for others to be added at any time.
+
For example, the key DHr0-I-mMN7h6cLMOTRJkkfPuMd0vgQPrOk4Y3edaHjr
in the DID document for the AID ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe
becomes:
"verificationMethod": [
+ {"id": "#DHr0-I-mMN7h6cLMOTRJkkfPuMd0vgQPrOk4Y3edaHjr",
+ "type": "JsonWebKey",
+ "controller": "did:webs:did-webs-service%3a7676:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "publicKeyJwk": {
+ "kid": "DHr0-I-mMN7h6cLMOTRJkkfPuMd0vgQPrOk4Y3edaHjr",
+ "kty": "OKP",
+ "crv": "Ed25519",
+ "x": "evT4j6Yw3uHpwsw5NEmSR8-4x3S-BA-s6Thjd51oeOs"
+ }
+ }
+ ]
+
+§ Ed25519
+-
+
- Ed25519 public keys MUST be converted to a verification method with a type of
JsonWebKey
andpublicKeyJwk
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":"KERI10JSON00012b_",
+ "t":"icp",
+ "d":"ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe","i":"ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "s":"0",
+ "kt":"1",
+ "k":["DHr0-I-mMN7h6cLMOTRJkkfPuMd0vgQPrOk4Y3edaHjr"],
+ "nt":"1",
+ "n":["ELa775aLyane1vdiJEuexP8zrueiIoG995pZPGJiBzGX"],
+ "bt":"0",
+ "b":[],
+ "c":[],
+ "a":[]
+}
+
+would result in a DID document with the following verification methods array:
+ "verificationMethod": [
+ {
+ "id": "#DHr0-I-mMN7h6cLMOTRJkkfPuMd0vgQPrOk4Y3edaHjr",
+ "type": "JsonWebKey",
+ "controller": "did:webs:did-webs-service%3a7676:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe", "publicKeyJwk": {
+ "kid": "DHr0-I-mMN7h6cLMOTRJkkfPuMd0vgQPrOk4Y3edaHjr",
+ "kty": "OKP",
+ "crv": "Ed25519",
+ "x": "evT4j6Yw3uHpwsw5NEmSR8-4x3S-BA-s6Thjd51oeOs"
+ }
+ }
+ ]
+
+§ Secp256k1
+-
+
- Secp256k1 public keys MUST be converted to a verification method with a type of
JsonWebKey
andpublicKeyJwk
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 ofConditionalProof2022
MUST be generated in the DID document. This verification method type is defined here. +-
+
-
+
It MUST be constructed according to the following rules:
+-
+
- The
id
property of the verification method MUST be a relative DID URL and use the AID as the value of the fragment component, e.g.,"id": "#<aid>"
.
+ - The
controller
property of the verification method MUST be the value of theid
property of the DID document. (Does the method spec need to specify this?)
+ - If the value of the
kt
field is a string containing a number that is greater than 1 then the following rules MUST be applied: +-
+
- The
threshold
property of the verification method MUST be the integer value of thekt
field in the current key state.
+ - The
conditionThreshold
property of the verification method MUST contain an array. For each key listed in the array value of thek
field in the key state: +-
+
- The relative DID URL corresponding to the key MUST be added to the array value of the
conditionThreshold
property.
+
+ - The relative DID URL corresponding to the key MUST be added to the array value of the
+ - The
- If the value of the
kt
field is an array containing fractionally weighted thresholds then the following rules MUST be applied: +-
+
- The
threshold
property of the verification method MUST be half of the lowest common denominator (LCD) of all the fractions in thekt
array.
+ - The
conditionWeightedThreshold
property of the verification method MUST contain an array. For each key listed in the array value of thek
field in the key state, and for each corresponding fraction listed in the array value of thekt
field: +-
+
- A JSON object MUST be added to the array value of the
conditionWeightedThreshold
property.
+ - The JSON object MUST contain a property
condition
whose value is the relative DID URL corresponding to the key.
+ - The JSON object MUST contain a property
weight
whose value is the numerator of the fraction after it has been expanded over the lowest common denominator (LCD) of all the fractions.
+
+ - A JSON object MUST be added to the array value of the
+ - The
For example, a KERI AID with only the following inception event in its KEL, and with a
+kt
value greater than 1:
+{ + "v": "KERI10JSON0001b7_", + "t": "icp", + "d": "Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", + "i": "Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", + "s": "0", + "kt": "2", // Signing Threshold + "k": [ + "1AAAAg299p5IMvuw71HW_TlbzGq5cVOQ7bRbeDuhheF-DPYk", // Secp256k1 Key + "DA-vW9ynSkvOWv5e7idtikLANdS6pGO2IHJy7v0rypvE", // Ed25519 Key + "DLWJrsKIHrrn1Q1jy2oEi8Bmv6aEcwuyIqgngVf2nNwu" // Ed25519 Key + ], +} +
results in a DID document with the following verification methods array:
+
+{ + "verificationMethod": [ + { + "id": "#Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", + "type": "ConditionalProof2022", + "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", + "threshold": 2, + "conditionThreshold": [ + "#1AAAAg299p5IMvuw71HW_TlbzGq5cVOQ7bRbeDuhheF-DPYk", + "#DA-vW9ynSkvOWv5e7idtikLANdS6pGO2IHJy7v0rypvE", + "#DLWJrsKIHrrn1Q1jy2oEi8Bmv6aEcwuyIqgngVf2nNwu" + ] + }, + { + "id": "#1AAAAg299p5IMvuw71HW_TlbzGq5cVOQ7bRbeDuhheF-DPYk", + "type": "JsonWebKey", + "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", + "publicKeyJwk": { + "kid": "1AAAAg299p5IMvuw71HW_TlbzGq5cVOQ7bRbeDuhheF-DPYk", + "kty": "EC", + "crv": "secp256k1", + "x": "NtngWpJUr-rlNNbs0u-Aa8e16OwSJu6UiFf0Rdo1oJ4", + "y": "qN1jKupJlFsPFc1UkWinqljv4YE0mq_Ickwnjgasvmo" + } + }, + { + "id": "#DA-vW9ynSkvOWv5e7idtikLANdS6pGO2IHJy7v0rypvE", + "type": "JsonWebKey", + "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", + "publicKeyJwk": { + "kid": "DA-vW9ynSkvOWv5e7idtikLANdS6pGO2IHJy7v0rypvE", + "kty": "OKP", + "crv": "Ed25519", + "x": "A-vW9ynSkvOWv5e7idtikLANdS6pGO2IHJy7v0rypvE" + } + }, + { + "id": "#DLWJrsKIHrrn1Q1jy2oEi8Bmv6aEcwuyIqgngVf2nNwu", + "type": "JsonWebKey", + "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", + "publicKeyJwk": { + "kid": "DLWJrsKIHrrn1Q1jy2oEi8Bmv6aEcwuyIqgngVf2nNwu", + "kty": "OKP", + "crv": "Ed25519", + "x": "LWJrsKIHrrn1Q1jy2oEi8Bmv6aEcwuyIqgngVf2nNws" + } + } + ] +} +
For example, a KERI AID with only the following inception event in its KEL, and a
+kt
containing fractionally weighted thresholds:
+{ + "v": "KERI10JSON0001b7_", + "t": "icp", + "d": "Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", + "i": "Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", + "s": "0", + "kt": ["1/2", "1/3", "1/4"], // Signing Threshold + "k": [ + "1AAAAg299p5IMvuw71HW_TlbzGq5cVOQ7bRbeDuhheF-DPYk", // Secp256k1 Key + "DA-vW9ynSkvOWv5e7idtikLANdS6pGO2IHJy7v0rypvE", // Ed25519 Key + "DLWJrsKIHrrn1Q1jy2oEi8Bmv6aEcwuyIqgngVf2nNwu" // Ed25519 Key + ], +} +
would result in a DID document with the following verification methods array:
+
+{ + "verificationMethod": [ + { + "id": "#Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", + "type": "ConditionalProof2022", + "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", + "threshold": 12, + "conditionWeightedThreshold": [ + { + "condition": "#1AAAAg299p5IMvuw71HW_TlbzGq5cVOQ7bRbeDuhheF-DPYk", + "weight": 6 + }, + { + "condition": "#DA-vW9ynSkvOWv5e7idtikLANdS6pGO2IHJy7v0rypvE", + "weight": 4 + }, + { + "condition": "#DLWJrsKIHrrn1Q1jy2oEi8Bmv6aEcwuyIqgngVf2nNwu", + "weight": 3 + } + ] + }, + { + "id": "#1AAAAg299p5IMvuw71HW_TlbzGq5cVOQ7bRbeDuhheF-DPYk", + "type": "EcdsaSecp256k1VerificationKey2019", + "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", + "publicKeyJwk": { + "crv": "secp256k1", + "x": "NtngWpJUr-rlNNbs0u-Aa8e16OwSJu6UiFf0Rdo1oJ4", + "y": "qN1jKupJlFsPFc1UkWinqljv4YE0mq_Ickwnjgasvmo", + "kty": "EC", + "kid": "WjKgJV7VRw3hmgU6--4v15c0Aewbcvat1BsRFTIqa5Q" + } + }, + { + "id": "#DA-vW9ynSkvOWv5e7idtikLANdS6pGO2IHJy7v0rypvE", + "type": "Ed25519VerificationKey2020", + "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", + "publicKeyMultibase": "zH3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV" + }, + { + "id": "#DLWJrsKIHrrn1Q1jy2oEi8Bmv6aEcwuyIqgngVf2nNwu", + "type": "Ed25519VerificationKey2020", + "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", + "publicKeyMultibase": "zDqYpw38nznAUJeeFdhKBQutRKpyDXeXxxi1HjYUQXLas" + } + ] +} +
+ - The
+ -
+
§ Verification Relationships
+-
+
- If the value of
kt
== 1 then the following rules MUST be applied: +-
+
- For each public key in
k
and its corresponding verification method, two verification relationships MUST be generated in the DID document. One verification relationship of typeauthentication
and one verification relationship of typeassertionMethod
. +-
+
- The
authentication
verification relationship SHALL define that the DID controller can authenticate using each key.
+ - The
assertionMethod
verification relationship SHALL define that the DID controller can express claims using each key.
+
+ - The
+ - For each public key in
- If the value of
kt
> 1 or if the value ofkt
is an array containing fractionally weighted thresholds then the following rules MUST be applied: +-
+
- For the verification method of type
ConditionalProof2022
(see section Thresholds), two verification relationships MUST be generated in the DID document. One verification relationship of typeauthentication
and one verification relationship of typeassertionMethod
. +-
+
- The
authentication
verification relationship SHALL define that the DID controller can authenticate using a combination of multiple keys above the threshold.
+ - The
assertionMethod
verification relationship SHALL define that the DID controller can express claims using a combination of multiple keys above the threshold.
+
+ - The
+ - For the verification method of type
- References to verification methods in the DID document MUST use the relative form of the identifier, e.g.,
"authentication": ["#<identifier>"]
.
+
++Private keys of a KERI AID can be used to sign a variety of data. This includes but is not limited to logging into a website, challenge-response exchanges, credential issuances, etc.
+
For more information, see the key agreement and other key commitments section in the Implementors Guide.
+§ Service Endpoints
+-
+
did:webs
DIDs MUST support service endpoints, including types declared in the DID Specification Registries, such as DIDCommMessaging.
+
++For additional details about the mapping between KERI events and the Service Endpoints in the DID Document, see Service Endpoint KERI events.
+
++It is important to note that DID document service endpoints are different than the KERI service endpoints detailed in KERI Service Endpoints as DID Document Metadata.
+
§ KERI Service Endpoints as DID Document Metadata
+-
+
-
+
+did:webs
endpoints MUST be specified using the two data sets KERI uses to define service endpoints; Location Schemes and Endpoint Role Authorizations.-
+
- Both MUST be expressed in KERI
rpy
events.
+ - For URL scheme endpoints that an AID has exposed,
did:webs
DIDs MUST use Location Schemes URLs.
+ - For endpoints that relate a role of one AID to another,
did:webs
DIDs MUST use KERI Endpoint Role Authorizations.
+
For example, the following
+rpy
method declares that the AIDEIDJUg2eR8YGZssffpuqQyiXcRVz2_Gw_fcAVWpUMie1
exposes the URLhttp://localhost:3902
for schemehttp
:
+{ + "v": "KERI10JSON0000fa_", + "t": "rpy", + "d": "EOGL1KGpOnRaZDIB11uZDCkhHs52_MtMXHd7EqUqwtA3", + "dt": "2022-01-20T12:57:59.823350+00:00", + "r": "/loc/scheme", + "a": { + "eid": "EIDJUg2eR8YGZssffpuqQyiXcRVz2_Gw_fcAVWpUMie1", + "scheme": "http", + "url": "http://127.0.0.1:3901/" + } + } +
For example, the AID listed in
+cid
is the source of the authorization, therole
is the role and the AID listed in theeid
field is the target of the authorization. So in this exampleEOGL1KGpOnRaZDIB11uZDCkhHs52_MtMXHd7EqUqwtA3
is being authorized as an Agent forEIDJUg2eR8YGZssffpuqQyiXcRVz2_Gw_fcAVWpUMie1
.
+{ + "v": "KERI10JSON000116_", + "t": "rpy", + "d": "EBiVyW6jPOeHX5briFYMQ4CefzqIZHgl-rrcXqj_t9ex", + "dt": "2022-01-20T12:57:59.823350+00:00", + "r": "/end/role/add", + "a": { + "cid": "EIDJUg2eR8YGZssffpuqQyiXcRVz2_Gw_fcAVWpUMie1", + "role": "agent", + "eid": "EOGL1KGpOnRaZDIB11uZDCkhHs52_MtMXHd7EqUqwtA3" + } +} +
+ - Both MUST be expressed in KERI
-
+
KERI service endpoints roles beyond
+witness
SHOULD be defined using Location Scheme and Endpoint Authorization records in KERI. See the KERI specification For more information about KERI roles.
+
++In KERI, service endpoints are defined by 2 sets of signed data using Best Available Data - Read, Update, Nullify (BADA-RUN) rules for data processing. The protocol ensures that all data is signed in transport and at rest and versioned to ensure only the latest signed data is available.
+
§ Transformation to did:web
DID Document
+The DID document that exists as a resource on a webserver is compatible with the did:web
DID method and therefore necessarily different from a did:webs
DID document with regard to the id
, controller
, and alsoKnownAs
properties.
-
+
-
+
To transform the
+did:web
form of the DID Document to adid:webs
the transformation MUST do the following:-
+
- In the values of the top-level
id
andcontroller
properties of the DID document, the transformation MUST replace thedid:webs
prefix string withdid:web
.
+ - In the value of the top-level
alsoKnownAs
property, the transformation MUST replace the entry that is now the new value of theid
property (usingdid:web
) with the old value of theid
property (usingdid:webs
).
+ - All other content of the DID document MUST not be modified. +
For example, this transformation is used during the Create DID method operation, given the following
+did:webs
DID document:
+{ + "id": "did:webs:did-webs-service%3a7676:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe", + "verificationMethod": [ + { + "id": "#DHr0-I-mMN7h6cLMOTRJkkfPuMd0vgQPrOk4Y3edaHjr", + "type": "JsonWebKey", + "controller": "did:webs:did-webs-service%3a7676:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe", + "publicKeyJwk": { + "kid": "DHr0-I-mMN7h6cLMOTRJkkfPuMd0vgQPrOk4Y3edaHjr", + "kty": "OKP", + "crv": "Ed25519", + "x": "evT4j6Yw3uHpwsw5NEmSR8-4x3S-BA-s6Thjd51oeOs" + } + } + ], + "service": [], + "alsoKnownAs": [ + "did:web:did-webs-service%3a7676:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe", + "did:web:example.com:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe", + "did:web:foo.com:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe", + "did:webs:foo.com:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe" + ] +} +
the result of the transformation algorithm is the following
+did:web
DID document:
+{ + "id": "did:web:did-webs-service%3a7676:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe", + "verificationMethod": [ + { + "id": "#DHr0-I-mMN7h6cLMOTRJkkfPuMd0vgQPrOk4Y3edaHjr", + "type": "JsonWebKey", + "controller": "did:web:did-webs-service%3a7676:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe", + "publicKeyJwk": { + "kid": "DHr0-I-mMN7h6cLMOTRJkkfPuMd0vgQPrOk4Y3edaHjr", + "kty": "OKP", + "crv": "Ed25519", + "x": "evT4j6Yw3uHpwsw5NEmSR8-4x3S-BA-s6Thjd51oeOs" + } + } + ], + "service": [], + "alsoKnownAs": [ + "did:webs:did-webs-service%3a7676:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe", + "did:web:example.com:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe", + "did:web:foo.com:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe", + "did:webs:foo.com:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe" + ] +} +
+ - In the values of the top-level
§ 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, a transformation to adid:webs
DID document MUST have the following differences:-
+
- The values of the top-level
id
andcontroller
properties of the DID document MUST be replaced; thedid:web
prefix string withdid:webs
.
+ - The value of the top-level
alsoKnownAs
property MUST replace the entry that is now the new value of theid
property (usingdid:webs
) with the old value of theid
property (usingdid:web
).
+ - All other content of the DID document MUST not be modificatied. +
+ - The values of the top-level
-
+
A
+did:webs
resolver MUST use this transformation during the Read (Resolve) DID method operation.For example, given the following
+did:web
DID document:
+{ + "id": "did:web:did-webs-service%3a7676:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe", + "verificationMethod": [ + { + "id": "#DHr0-I-mMN7h6cLMOTRJkkfPuMd0vgQPrOk4Y3edaHjr", + "type": "JsonWebKey", + "controller": "did:web:did-webs-service%3a7676:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe", + "publicKeyJwk": { + "kid": "DHr0-I-mMN7h6cLMOTRJkkfPuMd0vgQPrOk4Y3edaHjr", + "kty": "OKP", + "crv": "Ed25519", + "x": "evT4j6Yw3uHpwsw5NEmSR8-4x3S-BA-s6Thjd51oeOs" + } + } + ], + "service": [], + "alsoKnownAs": [ + "did:webs:did-webs-service%3a7676:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe", + "did:web:example.com:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe", + "did:web:foo.com:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe", + "did:webs:foo.com:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe" + ] +} +
the result of the transformation algorithm is the following
+did:webs
DID document:
+{ + "id": "did:webs:did-webs-service%3a7676:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe", + "verificationMethod": [ + { + "id": "#DHr0-I-mMN7h6cLMOTRJkkfPuMd0vgQPrOk4Y3edaHjr", + "type": "JsonWebKey", + "controller": "did:webs:did-webs-service%3a7676:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe", + "publicKeyJwk": { + "kid": "DHr0-I-mMN7h6cLMOTRJkkfPuMd0vgQPrOk4Y3edaHjr", + "kty": "OKP", + "crv": "Ed25519", + "x": "evT4j6Yw3uHpwsw5NEmSR8-4x3S-BA-s6Thjd51oeOs" + } + } + ], + "service": [], + "alsoKnownAs": [ + "did:web:did-webs-service%3a7676:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe", + "did:web:example.com:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe", + "did:web:foo.com:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe", + "did:webs:foo.com:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe" + ] +} +
+
§ Full Example
+This section is informative.
+To walk through a real-world example, please see the GETTING STARTED guide in the did:webs Reference Implementation as it walks users through many did:webs related tasks (and associated KERI commands) to demonstrate how they work together.
+The following blocks contain fully annotated examples of a KERI AID with two events, an inception event and an interaction event.
+-
+
- The inception event designates some witnesses in the
b
field.
+ - The inception event designates multiple public signing keys in the
k
field.
+ - The inception event designates multiple rotation keys in the
n
field.
+ - The interaction event cryptographically anchors data associated with the SAID
EoLNCdag8PlHpsIwzbwe7uVNcPE1mTr-e1o9nCIDPWgM
.
+ - The reply ‘rpy’ events specify an Agent endpoint, etc. +
Below, we show the KERI Event Stream that will be associated with the resulting generated DID document. These documents were generated for the example.com
domain with no associated port or additional path defined:
{
+ "v": "KERI10JSON0001b7_",
+ "t": "icp",
+ "d": "Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
+ "i": "Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
+ "s": "0",
+ "kt": "2", // Signing Threshold
+ "k": [
+ "1AAAAg299p5IMvuw71HW_TlbzGq5cVOQ7bRbeDuhheF-DPYk", // Secp256k1 Key
+ "DA-vW9ynSkvOWv5e7idtikLANdS6pGO2IHJy7v0rypvE", // Ed25519 Key
+ "DLWJrsKIHrrn1Q1jy2oEi8Bmv6aEcwuyIqgngVf2nNwu" // Ed25519 Key
+ ],
+ "nt": "2",
+ "n": [
+ "Eao8tZQinzilol20Ot-PPlVz6ta8C4z-NpDOeVs63U8s",
+ "EAcNrjXFeGay9qqMj96FIiDdXqdWjX17QXzdJvq58Zco",
+ "EPoly9Tq4IPx41U-AGDShLDdtbFVzt7EqJUHmCrDxBdb"
+ ],
+ "bt": "3",
+ "b": [
+ "BGKVzj4ve0VSd8z_AmvhLg4lqcC_9WYX90k03q-R_Ydo",
+ "BuyRFMideczFZoapylLIyCjSdhtqVb31wZkRKvPfNqkw",
+ "Bgoq68HCmYNUDgOz4Skvlu306o_NY-NrYuKAVhk3Zh9c"
+ ],
+ "c": [],
+ "a": []
+ }
+...
+{
+ "v": "KERI10JSON00013a_",
+ "t": "ixn",
+ "d": "Ek48ahzTIUA1ynJIiRd3H0WymilgqDbj8zZp4zzrad-w",
+ "i": "Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
+ "s": "1",
+ "p": "Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
+ "a": [
+ {
+ "i": "EoLNCdag8PlHpsIwzbwe7uVNcPE1mTr-e1o9nCIDPWgM",
+ "s": "0",
+ "d": "EoLNCdag8PlHpsIwzbwe7uVNcPE1mTr-e1o9nCIDPWgM"
+ }
+ ]
+}
+...
+{
+ "v": "KERI10JSON000116_",
+ "t": "rpy",
+ "d": "EBiVyW6jPOeHX5briFYMQ4CefzqIZHgl-rrcXqj_t9ex",
+ "dt": "2022-01-20T12:57:59.823350+00:00",
+ "r": "/end/role/add",
+ "a": {
+ "cid": "Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
+ "role": "agent",
+ "eid": "EIDJUg2eR8YGZssffpuqQyiXcRVz2_Gw_fcAVWpUMie1"
+ }
+}
+...
+{
+ "v": "KERI10JSON000116_",
+ "t": "rpy",
+ "d": "EBiVyW6jPOeHX5briFYMQ4CefzqIZHgl-rrcXqj_t9ex",
+ "dt": "2022-01-20T12:57:59.823350+00:00",
+ "r": "/end/role/add",
+ "a": {
+ "cid": "EIDJUg2eR8YGZssffpuqQyiXcRVz2_Gw_fcAVWpUMie1",
+ "role": "controller",
+ "eid": "EIDJUg2eR8YGZssffpuqQyiXcRVz2_Gw_fcAVWpUMie1"
+ }
+}
+...
+{
+ "v": "KERI10JSON0000fa_",
+ "t": "rpy",
+ "d": "EOGL1KGpOnRaZDIB11uZDCkhHs52_MtMXHd7EqUqwtA3",
+ "dt": "2022-01-20T12:57:59.823350+00:00",
+ "r": "/loc/scheme",
+ "a": {
+ "eid": "EIDJUg2eR8YGZssffpuqQyiXcRVz2_Gw_fcAVWpUMie1",
+ "scheme": "http",
+ "url": "http://foo.example.com:3901/"
+ }
+}
+
+
+...
+{
+ "v": "KERI10JSON000116_",
+ "t": "rpy",
+ "d": "EBiVyW6jPOeHX5briFYMQ4CefzqIZHgl-rrcXqj_t9ex",
+ "dt": "2022-01-20T12:57:59.823350+00:00",
+ "r": "/end/role/add",
+ "a": {
+ "cid": "EIDJUg2eR8YGZssffpuqQyiXcRVz2_Gw_fcAVWpUMie1",
+ "role": "controller",
+ "eid": "EIDJUg2eR8YGZssffpuqQyiXcRVz2_Gw_fcAVWpUMie1"
+ }
+}
+...
+{
+ "v": "KERI10JSON0000fa_",
+ "t": "rpy",
+ "d": "EOGL1KGpOnRaZDIB11uZDCkhHs52_MtMXHd7EqUqwtA3",
+ "dt": "2022-01-20T12:57:59.823350+00:00",
+ "r": "/loc/scheme",
+ "a": {
+ "eid": "EIDJUg2eR8YGZssffpuqQyiXcRVz2_Gw_fcAVWpUMie1",
+ "scheme": "http",
+ "url": "http://foo.example.com:3901/"
+ }
+}
+
+
+Resulting DID document:
+ "didDocument": {
+ "id": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
+ "alsoKnownAs": [
+ "did:web:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
+ "did:keri:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M"
+ ],
+ "verificationMethod": [
+ {
+ "id": "#Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
+ "type": "ConditionalProof2022",
+ "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
+ "threshold": 2,
+ "conditionThreshold": [
+ "#1AAAAg299p5IMvuw71HW_TlbzGq5cVOQ7bRbeDuhheF-DPYk",
+ "#DA-vW9ynSkvOWv5e7idtikLANdS6pGO2IHJy7v0rypvE",
+ "#DLWJrsKIHrrn1Q1jy2oEi8Bmv6aEcwuyIqgngVf2nNwu"
+ ]
+ },
+ {
+ "id": "#1AAAAg299p5IMvuw71HW_TlbzGq5cVOQ7bRbeDuhheF-DPYk",
+ "type": "JsonWebKey",
+ "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
+ "publicKeyJwk": {
+ "kid": "1AAAAg299p5IMvuw71HW_TlbzGq5cVOQ7bRbeDuhheF-DPYk",
+ "kty": "EC",
+ "crv": "secp256k1",
+ "x": "NtngWpJUr-rlNNbs0u-Aa8e16OwSJu6UiFf0Rdo1oJ4",
+ "y": "qN1jKupJlFsPFc1UkWinqljv4YE0mq_Ickwnjgasvmo"
+ }
+ },
+ {
+ "id": "#DA-vW9ynSkvOWv5e7idtikLANdS6pGO2IHJy7v0rypvE",
+ "type": "JsonWebKey",
+ "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
+ "publicKeyJwk": {
+ "kid": "DA-vW9ynSkvOWv5e7idtikLANdS6pGO2IHJy7v0rypvE",
+ "kty": "OKP",
+ "crv": "Ed25519",
+ "x": "A-vW9ynSkvOWv5e7idtikLANdS6pGO2IHJy7v0rypvE"
+ }
+ },
+ {
+ "id": "#DLWJrsKIHrrn1Q1jy2oEi8Bmv6aEcwuyIqgngVf2nNwu",
+ "type": "JsonWebKey",
+ "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
+ "publicKeyJwk": {
+ "kid": "DLWJrsKIHrrn1Q1jy2oEi8Bmv6aEcwuyIqgngVf2nNwu",
+ "kty": "OKP",
+ "crv": "Ed25519",
+ "x": "LWJrsKIHrrn1Q1jy2oEi8Bmv6aEcwuyIqgngVf2nNws"
+ }
+ }
+ ],
+ "authentication": [
+ "#Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M"
+ ],
+ "assertionMethod": [
+ "#Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M"
+ ],
+ "service": [
+ {
+ "id": "#EIDJUg2eR8YGZssffpuqQyiXcRVz2_Gw_fcAVWpUMie1",
+ "type": "KeriAgent",
+ "serviceEndpoint": "http://foo.example.com:3901/"
+ }
+ ]
+ }...
+
+§ Basic KERI event details
+DID Document from KERI Events introduced the core KERI event stream and related DID Document concepts. This section provides additional details regarding the basic types of KERI events and how they relate to the DID document.
+§ Key state events
+-
+
- When processing the KERI event stream
did:webs
MUST account for two broad types of key state events (KERI parlance is ‘establishment events’) that can alter the key state of the AID.
+ - Any change in key state of the AID MUST 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 SHALL NOT 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 foundation of pre-rotation is post-quantum safe and allows the
did:webs
controller to recover from key compromise.
+ - The Inception event MUST be the first event in the KEL that establishes the AID.
+
-
+
- This MUST define the initial key set +
- If the controller(s) desire future key rotation (transfer) then the inception event MUST commit to a set of future rotation key hashes. +
- When processing the KERI event stream, if there are no rotation events after the inception event, then this is the current key state of the AID and MUST be reflected in the DID Document as specified in Verification Methods and Verification Relationships. +
+ - Rotation events MUST come after inception events. +
- If the controller(s) desires future key rotation (transfer) then the rotation event MUST commit to a set of future rotation key hashes. +
- Rotation events MUST only change the key state to the previously committed to rotation keys. +
- The last rotation event is the current key state of the AID and MUST be reflected in the DID Document as specified in Verification Methods and Verification Relationships. +
++You can learn more about the inception event in the KERI specification and you can see an example inception event. +To learn about future rotation key commitment, see the sections about pre-rotation and the KERI specification.
+
++You can learn more about rotation events in the KERI specification and you can see an example rotation event. +To learn about future rotation key commitment, see the sections about pre-rotation and the KERI specification.
+
§ Delegation KERI event details
+This section focuses on delegation relationships between KERI AIDs. DID Document from KERI Events introduced the core KERI event stream and related DID Document concepts. This section provides additional details regarding the basic types of KERI events and how they relate to the DID document. Basic KERI event details provides additional details on the basic types of KERI events and how they relate to the DID document.
+§ Delegation key state events
+-
+
- All delegation relationships MUST start with a delegated inception event. +
- Any change to the Delegated inception event key state or delegated rotation event key state MUST be the result of a delegated rotation event. +
++Delegated inception event: Establishes a delegated identifier. Either the delegator or the delegate can end the delegation commitment.
+
++Delegated rotation event: Updates the delegated identifier commitment. Either the delegator or the delegate can end the delegation commitment.
+
++See the KERI specification for an example of a delegated inception and rotation events.
+
§ Service Endpoint event details
+TODO: Define and detail the service endpoint events
+§ Designated Aliases
+-
+
- An AID controller SHALL specify the designated aliases that will be listed in the
equivalentId
andalsoKnownAs
properties by issuing a designated aliases verifiable attestation. +-
+
- This attestation MUST contain a set of AID controlled identifiers that the AID controller authorizes. +
- If the identifier is a
did:webs
identifier then it is truly equivalent and MUST be listed in theequivalentId
property.
+ - If the identifier is a DID then it MUST be listed in the
alsoKnownAs
property.
+
+
§ Designated Aliases event details
+This is an example designated aliases ACDC attestation showing five designated aliases:
+{
+ "v": "ACDC10JSON0005f2_",
+ "d": "EIGWggWL2IHiUzj1P2YuPA0-Uh55LTIu14KTvVQGrfvT",
+ "i": "ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "ri": "EAtQJEQMkkvlWxyfLbcLyv4kNeAI5Qsqe65vKIWnHKpx",
+ "s": "EN6Oh5XSD5_q2Hgu-aqpdfbVepdpYpFlgz6zvJL5b_r5",
+ "a": {
+ "d": "EJJjtYa6D4LWe_fqtm1p78wz-8jNAzNX6aPDkrQcz27Q",
+ "dt": "2023-11-13T17:41:37.710691+00:00",
+ "ids": [
+ "did:web:did-webs-service%3a7676:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "did:webs:did-webs-service%3a7676:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "did:web:example.com:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "did:web:foo.com:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "did:webs:foo.com:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe"
+ ]
+ },
+ "r": {
+ "d": "EEVTx0jLLZDQq8a5bXrXgVP0JDP7j8iDym9Avfo8luLw",
+ "aliasDesignation": {
+ "l": "The issuer of this ACDC designates the identifiers in the ids field as the only allowed namespaced aliases of the issuer's AID."
+ },
+ "usageDisclaimer": {
+ "l": "This attestation only asserts designated aliases of the controller of the AID, that the AID controlled namespaced alias has been designated by the controller. It does not assert that the controller of this AID has control over the infrastructure or anything else related to the namespace other than the included AID."
+ },
+ "issuanceDisclaimer": {
+ "l": "All information in a valid and non-revoked alias designation assertion is accurate as of the date specified."
+ },
+ "termsOfUse": {
+ "l": "Designated aliases of the AID must only be used in a manner consistent with the expressed intent of the AID controller."
+ }
+ }
+}
+
+The resulting DID document based on the designated aliases attestation above, contains:
+-
+
- An
equivalentId
metadata for the did:webs:foo.com identifier
+ - Three
alsoKnownAs
identifiers: +-
+
- the did:webs:foo.com identifier is a designated alias which is also in the equivalentId did document metadata. +
- the did:web:example.com is a designated alias +
- NOTE: if the did:keri identifier were automatically generated and included from the AID then that would be a valid designated alias and alsoKnownAs value based on the AID +
+
{
+ "didDocument": {
+ "id": "did:webs:did-webs-service%3a7676:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "verificationMethod": [
+ {
+ "id": "#DHr0-I-mMN7h6cLMOTRJkkfPuMd0vgQPrOk4Y3edaHjr",
+ "type": "JsonWebKey",
+ "controller": "did:webs:did-webs-service%3a7676:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "publicKeyJwk": {
+ "kid": "DHr0-I-mMN7h6cLMOTRJkkfPuMd0vgQPrOk4Y3edaHjr",
+ "kty": "OKP",
+ "crv": "Ed25519",
+ "x": "evT4j6Yw3uHpwsw5NEmSR8-4x3S-BA-s6Thjd51oeOs"
+ }
+ }
+ ],
+ "service": [],
+ "alsoKnownAs": [
+ "did:web:did-webs-service%3a7676:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "did:webs:did-webs-service%3a7676:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "did:web:example.com:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "did:web:foo.com:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "did:webs:foo.com:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe"
+ ]
+ },
+ "didResolutionMetadata": {
+ "contentType": "application/did+json",
+ "retrieved": "2024-04-01T17:43:24Z"
+ },
+ "didDocumentMetadata": {
+ "witnesses": [],
+ "versionId": "2",
+ "equivalentId": [
+ "did:webs:did-webs-service%3a7676:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "did:webs:foo.com:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe"
+ ],
+ "didDocUrl": "http://did-webs-service:7676/ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe/did.json",
+ "keriCesrUrl": "http://did-webs-service:7676/ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe/keri.cesr"
+ }
+}
+
+§ DID Parameters
+This section is normative.
+This section describes the support of the did:webs
method for certain DID parameters.
§ Support for versionId
+The did:webs
DID method supports the versionId
DID parameter. This DID parameter is defined here.
This allows clients to instruct a DID Resolver to return a specific version of a DID document, as opposed to the latest version. The did:webs
DID method is ideally suited for this functionality, since a continuous, self-certifying stream of events lies at the heart of the DID method’s design, see section KERI Fundamentals.
-
+
- Valid values for this DID parameter MUST be the sequence numbers of events in the KERI event stream. +
- When a
did:webs
DID is resolved with this DID parameter, adid:webs
resolver MUST constructs the DID document based on an AID’s associated KERI events from the KERI event stream only up to (and including) the event with the sequence +number (i.e. thes
field) that corresponds to the value of theversionId
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.
-
+
- This parameter MUST be implemented for a DID Resolver to return verification methods in a DID document in a desired format, such as
JsonWebKey
orEd25519VerificationKey2020
.
+
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:
+-
+
- Extension verification method
type
CesrKey
MAY be available in adid:webs
DID document to express a public key encoded in CESR format.
+ - Extension verification method property
publicKeyCesr
MAY be available in adid:webs
DID document to provide a string value whose content is the CESR representation of a public key.
+ - The verification method type
CesrKey
MAY be used as the value of thetransformKeys
DID parameter.
+
For example, a KERI AID with only the following inception event in its KEL:
+{
+ "v": "KERI10JSON0001b7_",
+ "t": "icp",
+ "d": "Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
+ "i": "Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
+ "s": "0",
+ "kt": "1",
+ "k": [
+ "1AAAAg299p5IMvuw71HW_TlbzGq5cVOQ7bRbeDuhheF-DPYk", // Secp256k1 Key
+ "DA-vW9ynSkvOWv5e7idtikLANdS6pGO2IHJy7v0rypvE", // Ed25519 Key
+ "DLWJrsKIHrrn1Q1jy2oEi8Bmv6aEcwuyIqgngVf2nNwu" // Ed25519 Key
+ ],
+ // ...
+}
+
+and given the following the DID URL:
+did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M?transformKeys=CesrKey
+
+would result in a DID document with the following verification methods array:
+{
+ "verificationMethod": [
+ {
+ "id": "#1AAAAg299p5IMvuw71HW_TlbzGq5cVOQ7bRbeDuhheF-DPYk",
+ "type": "CesrKey",
+ "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
+ "publicKeyCesr": "1AAAAg299p5IMvuw71HW_TlbzGq5cVOQ7bRbeDuhheF-DPYk"
+ },
+ {
+ "id": "#DA-vW9ynSkvOWv5e7idtikLANdS6pGO2IHJy7v0rypvE",
+ "type": "CesrKey",
+ "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
+ "publicKeyCesr": "DA-vW9ynSkvOWv5e7idtikLANdS6pGO2IHJy7v0rypvE"
+ },
+ {
+ "id": "#DLWJrsKIHrrn1Q1jy2oEi8Bmv6aEcwuyIqgngVf2nNwu",
+ "type": "CesrKey",
+ "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
+ "publicKeyCesr": "DLWJrsKIHrrn1Q1jy2oEi8Bmv6aEcwuyIqgngVf2nNwu"
+ }
+ ]
+}
+
+§ DID Metadata
+This section is normative.
+This section describes the support of the did:webs
method for metadata, including DID resolution metadata and DID document metadata. This metadata is returned by a DID Resolver in addition to the DID document. Also see the DID Resolution specification for further details.
§ DID Resolution Metadata
+At the moment, this specification does not define the use of any specific DID resolution metadata properties in the did:webs
method, but may in the future include various metadata, such as which KERI Watchers were used during the resolution process.
§ DID Document Metadata
+This section of the specification defines how various DID document metadata properties are used by the did:webs
method.
§ Use of versionId
+The versionId
DID document metadata property indicates the current version of the DID document that has been resolved.
-
+
- The
did:webs
versionId MUST be the sequence number (i.e. thes
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 forversionId
) was used when resolving thedid:webs
DID, and if the DID Resolution process was successful, then this corresponding DID document metadata property MUST be guaranteed to be equal to the value of the DID parameter.
+
Example:
+{
+ "didDocument": {
+ "id": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M"
+ // ... other properties
+ },
+ "didResolutionMetadata": {
+ },
+ "didDocumentMetadata": {
+ "versionId": "2"
+ }
+}
+
+§ Use of nextVersionId
+The nextVersionId
DID document metadata property indicates the next version of the DID document after the version that has been resolved.
-
+
- The
did:webs
nextVersionId
MUST be the sequence number (i.e. thes
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 MUST be present if the DID parameter
versionId
+(see section Support forversionId
) was used when resolving thedid:webs
DID, and if the value of that DID parameter was not the sequence number of the last event in the KERI event stream.
+
Example:
+{
+ "didDocument": {
+ "id": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M"
+ // ... other properties
+ },
+ "didResolutionMetadata": {
+ },
+ "didDocumentMetadata": {
+ "versionId": "1",
+ "nextVersionId": "2"
+ }
+}
+
+§ Use of equivalentId
+The equivalentId
DID document metadata property indicates other DIDs that refer to the same subject and are logically equivalent to the DID that has been resolved. It is similar to the alsoKnownAs
DID document property (see section Also Known As), but it has even stronger semantics, insofar as the logical equivalence is guaranteed by the DID method itself.
-
+
- The
did:webs
equivalentId
metadata property SHOULD contain a list of the controller AID designated aliasesdid:webs
DIDs that differ in the host and/or port portion of the method-specific identifier but share the same AID. Also see section AID controlled identifiers.
+ equivalentId
depends on the controller AIDs array of designated aliases. Adid:webs
identifier MUST not verify unless it is found in theequivalentId
metadata that corresponds to the designated aliases.
+
++Note that AID controlled identifiers like
+did:web
anddid:keri
identifiers with the same AID are not listed inequivalentId
because they do not have the same DID method. Adid:web
identifier with the same domain and AID does not have the same security characteristics as thedid:webs
identifier. Conversely, adid:keri
identifier with the same AID has the same security characterisitcs but not the same dependence on the web. For these reasons, they are not listed inequivalentId
.
Example:
+{
+ "didDocument": {
+ "id": "did:webs:did-webs-service%3a7676:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "verificationMethod": [
+ {
+ "id": "#DHr0-I-mMN7h6cLMOTRJkkfPuMd0vgQPrOk4Y3edaHjr",
+ "type": "JsonWebKey",
+ "controller": "did:webs:did-webs-service%3a7676:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "publicKeyJwk": {
+ "kid": "DHr0-I-mMN7h6cLMOTRJkkfPuMd0vgQPrOk4Y3edaHjr",
+ "kty": "OKP",
+ "crv": "Ed25519",
+ "x": "evT4j6Yw3uHpwsw5NEmSR8-4x3S-BA-s6Thjd51oeOs"
+ }
+ }
+ ],
+ "service": [],
+ "alsoKnownAs": [
+ "did:web:did-webs-service%3a7676:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "did:webs:did-webs-service%3a7676:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "did:web:example.com:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "did:web:foo.com:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "did:webs:foo.com:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe"
+ ]
+ },
+ "didResolutionMetadata": {
+ "contentType": "application/did+json",
+ "retrieved": "2024-04-01T17:43:24Z"
+ },
+ "didDocumentMetadata": {
+ "witnesses": [],
+ "versionId": "2",
+ "equivalentId": [
+ "did:webs:did-webs-service%3a7676:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "did:webs:foo.com:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe"
+ ],
+ "didDocUrl": "http://did-webs-service:7676/ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe/did.json",
+ "keriCesrUrl": "http://did-webs-service:7676/ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe/keri.cesr"
+ }
+}
+
+§ Signed Files
+This section is normative.
+did:webs
signed files combine the semantics of folders of files on web servers, and the DID Specification's DID URL path semantics to enable the controller of the DID to publish documents cryptographically signed using the verification key(s) of the DID. This kind of signed file capability has been implemented in a variety of ways in the past, such as with hashlinks. The value of including this as part of the did:webs
DID method is that it ensures consistency in its application, including how the signed files can be verified when using a multisig-enabled DID, and in the face of rotations of the DID’s key(s).
-
+
-
+
In publishing a file, the controller of the DID MAY use the KERI TEL to record the signing event, prior to publishing the file. In that case, in processing the KERI Audit log, the publication event MUST be found, verified, and ordered relative to key state changes and other signing events. For example, see how we anchor designated aliases as verifiable data on a TEL.
+
+ -
+
If the file is NOT KEL backed data or if the controller would like to provide additional signature, the controller MUST do the following:
+-
+
- The controller of the DID MAY place arbitrary files into the folder structure below the root did:webs folder. +
- The DID URL for the signed file MUST be of the form
<did:webs DID>/<path to file>
.
+ - The HTTPS path to the file MUST be
<HTTPS URL conversion of did:webs identifier>/<path to file>
.
+ - To be a valid
did:webs
signed file, each file MUST have an associated JSON Web Signature file named<filename>.jws
beside (in the same Web folder as) the file. For example, a filerevocation_registry.bin
MUST have a filerevocation_registry.bin.jws
beside it.
+ - The HTTPS path to the associated JWS file MUST be
<HTTPS URL conversion of did:webs identifier>/<path to file>.jws
.
+ - The JWS web signature MUST apply the following rules:
+
-
+
- MUST use the JSON Serialization form of the JWS. This is necessary to support multi-signatures in the JWS. +
- MUST have a payload that is the [multiformat multihash] hash of the content of the associated signed file. +
- MUST be signed with a verification key(s) that is (are) either currently in the DIDDoc of the DID, or found in the KEL associated with the DID. A verification key found in a valid KEL represents a key that had been in use previously, but has been rotated away. +
- MUST be verified such that:
+
-
+
- A calculated hash of the file MUST match the hash in the JWS. +
- The signature(s) in the JWS MUST be valid. +
- If the DID has (or had at the time of signing) multisig requirements, those requirements MUST be met. +
+
+
+
See:
+ +The following is informative. +Examples:
+-
+
- DID URL:
did:webs:w3c-ccg.github.io:12124313423525/members-list.txt
+-
+
- HTTPS URL:
https://w3c-ccg.github.io/12124313423525/members-list.txt
+ - HTTPS JWS URL:
https://w3c-ccg.github.io/12124313423525/members-list.txt.jws
+
+ - HTTPS URL:
- DID URL:
did:webs:mines.gov.bc.ca:VCissuer:12124313423525/mines-permit/v1.0/schema.json
+-
+
- HTTPS URL:
https://mines.gov.bc.ca/VCissuer/12124313423525/mines-permit/v1.0/schema.json
+ - HTTPS JWS URL:
https://mines.gov.bc.ca/VCissuer/12124313423525/mines-permit/v1.0/schema.json.jws
+
+ - HTTPS URL:
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:
+-
+
- Revocation registries such as StatusList2021 published by the issuer (and revoker) of a set of revocable credentials. +
- Hyperledger AnonCreds objects such as those published by an Issuer when [setting up to publish AnonCreds verifiable credential] +
- JSON-LD context files. +
- Verifiable Credential rendering data files and images published by verifiable credential issuers, such as those proposed in the W3C VC Rendering Methods specification and used in the Overlay Capture Architecture (OCA) for Aries specification. +
§ The whois
DID URL
+This convention enables those that receive the DID to retrieve and verify the verifiable presentation (and embedded Verifiable Credentials) the DID controller has decided to publish about itself. The intention is that anyone interested in a particular did:webs
DID can see if there is a whois
Verifiable Presentation, and if so, if it contains any useful (to the resolver) Verifiable Credentials that might help in learning more about who is the controller of the DID.
§ whois
DID URL Conventions
+-
+
- The
whois
object, if it exists, MUST be directly beside thedid.json
file, the DID Document for the DID.
+ - The DID URL path to
whois
MUST be<did:webs DID>/whois
.
+ - The HTTPS path to the
whois
MUST be like<HTTPS URL conversion of did:webs identifier>/whois.vp
.
+ - If the
whois
is present, the web server that serves thedid:webs
documents MUST respond to a request for the HTTPSwhois
URL with the verifiable presentation published there by the DID controller.
+ - If the controller of the
did:webs
DID has not published awhois
verifiable presentation, the web server MUST respond with an HTTP404
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 currentdid: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 MUST be in one of three formats:
+
-
+
- A W3C Verifiable Credentials Data Model Standard JSON-LD Data Integrity Proof Verifiable Presentation MAY be used. +
- A W3C Verifiable Credentials Data Model Standard JSON Web Token Verifiable Presentation MAY be used. +
- An ACDC or ACDC IPEX disclosure MAY be used. +
+ - When the verifiable presentation is requested, the resolved object MUST contain the appropriate MIME type of the verifiable presentation format. +
++It is up to the DID Controller to decide to publish a verifiable presentation and if so, which Verifiable Credentials to put into the verifiable presentation.
+
§ whois
Use Case
+This section is informative.
+The following is a use case for this capability. Consider an example of the did:webs
controller being an educational institution that issues “degree” verifiable credentials to its graduate students. A graduate from the school submits as part of their job application to a company a Verifiable Presentation derived from the verifiable credential they received from the school. The company receiving the presentation can verify the cryptography of the presentation, but can they trust the school that issued the verifiable credential? If the school issued the verifiable credential using its did:webs
DID, the company can resolve the DID. It can also resolve the DID’s whois
DID URL where it might find VCs from issuers it trusts with the did:webs
DID as the subject. For example:
-
+
- A verifiable credential issued by the Legal Entity Registrar for the jurisdiction in which the school is headquartered.
+
-
+
- Since the company knows about the Legal Entity Registrar, they can automate this lookup to get more information about the school from the verifiable credential – its legal name, when it was registered, contact information, etc. +
+ - A verifiable credential issued by the “Association of Colleges and Universities” for the jurisdiction of the school.
+
-
+
- Perhaps the company does not know about the Association for that jurisdiction. The company can repeat the
whois
resolution process for the issuer of that credential. The company might (for example), resolve and verify thedid:webs
DID for the Association, and then resolve thewhois
DID URL to find a verifiable credential issued by the government of the jurisdiction. The company recognizes and trusts that government’s authority, and so can decide to recognize and trust the Association.
+
+ - Perhaps the company does not know about the Association for that jurisdiction. The company can repeat the
- A verifiable credential issued by US News magazine about the school’s placement on th US News Rankings of Colleges and Universities. +
Such checks can all be done with a handful of HTTPS requests and the processing of the DIDs and verifiable presentations. The result is an efficient, verifiable, credential-based, decentralized, multi-domain trust registry.
+§ KERI Fundamentals
+This section is informative.
+Key Event Receipt Infrastructure (KERI) is a protocol for managing cryptographic keys, identifiers, and associated verifiable data structures. KERI was first described in an academic paper, and its specification is currently incubated under Trust Over IP Foundation. The open source community that develops KERI-related technologies can be found at https://github.com/WebOfTrust. This section outlines the fundamentals and components of the KERI protocol that are related to the did:webs
method.
§ Autonomic Identifier (AID)
+An autonomic identifier (AID) is a globally-unique persistent self-certifying identifier that serves as the primary root-of-trust of the KERI protocol. An AID is cryptographically bound to a KEL that determines the evolution of its key state using the pre-rotation mechanism. AIDs and the underlying KERI protocol, by themselves, satisfy most of the properties that DIDs require, including decentralization, control, security, proof-based, and portability. For example, DIDs that have the same AID component are considered equivalent, allowing AIDs to be portable across different DID methods such as did:webs
and did:keri
.
§ Key Event Log (KEL)
+The binding between an AID and its cryptographic keys is proved by a data structure called a key event log (KEL) that allows the key states of the AID to evolve. For a did:webs
DID, a KEL is an essential component in the KERI event stream that is used to verify its authenticity.
A KEL is a hash-chain append-only log and can be considered a variant of blockchain. However, a KEL differs from the traditional blockchain technology in at least two important ways:
+-
+
- It records the key event history of a single AID with a single controller, instead of an arbitrarily large collection updated by other participants in the network. This makes a KEL memory-efficient, fast, cheap, and trivially scalable. +
- It is fully self-certifying, meaning its correctness can be proved by direct inspection, without a distributed consensus algorithm or assumptions about trust in an external data source or its governance. +
These properties allows a KEL to be published anywhere, without special guarantees from its storage mechanism. For example, a KEL of an AID could be published and migrated between different KERI-compatible blockchain networks that use different DID methods. A KEL also records changes to key types and cryptographic algorithms, providing the AID portability and adaptability to multiple ecosystems throughout its lifecycle.
+§ AID Derivation
+The value of an AID is derived from the first key event, called the inception event, of a KEL. The inception event includes inital public key(s), called the current key(s), that can be used to control the AID. The cryptographic relationship between the AID and its keys eliminates an early chain-of-custody risk that plagues many other DID methods where an attacker uses compromised keys to create a DID without the DID controller’s knowledge. This derivation process is similar to techniques used by did:key
, did:peer
, did:sov
, and did:v1
.
The simplest AIDs, called non-transferrable direct mode AIDs, have no additional input to the derivation function, and expose a degenerate KEL that can hold only the inception event. This KEL is entirely derivable from the AID itself, and thus requires no external data. Non-transferrable direct mode AIDs are ideal for ephemeral use cases and are excellent analogs to did:key
and did:peer
with numalgo=0
. This is by no means not the only option as KERI offers richer choices that are especially valuable if an AID is intended to have a long lifespan.
§ Pre-rotation
+Public keys in the Verification Methods of a did:webs
DID can be changed via a mechanism called pre-rotation. With pre-rotation, the inception event of the associated AID also includes the hash(s) of the next key(s) that can be used to change the key state of the AID. AIDs with one or more pre-rotated next keys are called transferrable AIDs because their control can be transferred to new keys. AIDs that do not use pre-rotation cannot change their keys and are thus non-transferrable.
Pre-rotation has profound security benefits. If a malicious party steals the current private key for a transferrable AID, they only accomplish temporary mischief, because the already-existing KEL contains a commitment to a future state. This prevents them from rotating the stolen AID’s key to an arbitrary value of their choosing. As soon as the AID controller suspects a compromise, they can change the key state of the AID using the pre-rotated next key and locks the attacker out again.
+§ Weighted Multisig
+The KERI protocol supports weighted multi-signature scheme that allows for conditional proof in the Verification Methods. A multisig AID distribute its control among multiple key holders. This includes simple M-of-N rules such as “3 of 5 keys must sign to change the AID’s key state”. More sophisticated configurations are also supported: “Acme Corp’s AID is controlled by the keys of 4 of 7 board members, or by the keys of the CEO and 2 board members, or by the keys of the CEO and the Chief Counsel.”
+The security and recovery benefits of this feature are obvious when an AID references organizational identity. However, even individuals can benefit from this, when stakes are high. They simply store different keys on different devices, and then configure how their devices constitute a management quorum. This decreases risks from lost phones, for example.
+§ Witnesses
+In the direct mode, the controller of an AID is responsible for the distribution of its KEL. Since the controller may not be highly available, the controller may designate additional supporting infrastructure, called witnesses, for the indirect mode distribution of the KELs. Witnessess may or may not be under direct control of the AID’s controller and could be deployed on either centralized or decentralized architectures, including blockchains. The witnesses are embedded in the AID’s key event and, if included in the inception event, alter the AID value.
+Unlike a blockchain with a distributed consensus mechanism, witnesses do not coordinate or come to consensus with one another during an update to its AID’s key event history. Hence, they need not be deeply trustworthy; merely by existing, they improve trust. This is because anyone changing an AID’s key state or its set of witnesses, including the AID’s legitimate controller, has to report those changes to the witnesses that are currently active, to produce a valid evolution of the KEL. The AID controller and all witnesses thus hold one another accountable. Further, it becomes possible to distinguish between duplicity and imperfect replication of key states.
+§ Transaction Event Log (TEL)
+The KERI protocol supports a verifiable data structure, called the transaction event log (TEL), that binds an AID to non-repudiable data that is deterministically bound to the key event history in the KEL. Transactions that are recorded in a TEL may include things like the issuance and revocation of verifiable credentials or the fact that listeners on various service endpoints started or stopped. Like KELs, TELs are self-certifying and may also be published by KERI witnesses to enhance discoverability and provide watcher networks the ability to detect duplicity. For example, we demonstrate that in this spec in how we anchor designated aliases as verifiable data on a TEL.
+§ Web Independence
+Although this DID method depends on web technology, KERI itself does not. It’s as easy to create AIDs on IOT devices as it is on the web. AIDs offer the same features regardless of their origin and besides HTTP, they are shareable over Lo-Ra, Bluetooth, NFC, Low Earth Orbit satellite protocols, service buses on medical devices, and so forth. Thus, KERI’s AIDs offer a bridge between a web-centric DID method and lower-level IOT ecosystems.
+§ Flexible Serialization
+KELs and TELs of did:webs
DIDs (i.e., AIDs) are included in the KERI event streams for verification of the DID documents. The KERI event streams use Composable Event Streaming Representation ([[ref: CESR)]] for data serialization. Although CESR is a deep subject all by itself, at a high level, it has two essential properties:
-
+
- Content in CESR is self-describing and supports serialization as binary and text: That is in CESR, a digital signature on a CESR data structure is stable no matter which underlying serialization format is used. In effect it supports multiple popular serialization formats like JSON, CBOR, and MsgPack with room for many more. These formats can be freely mixed and combined in a CESR stream because of the self-describing nature of these individual CESR data structures. The practical effect is that developers get the best of both worlds: they can produce and consume data as text to display and debug in a human-friendly form and they can store and transmit this data in its tersest form, all without changing the signature on the data structures. +
- Cryptographic primitives are structured into compact standard representations: Cryptographic primitives such as keys, hashes, digests, sealed-boxes, signatures, etc… are structured strings with a recognizable data type prefix and a standard representation in the stream. This means they are very terse and there is no need for the variety of representation methods that create interoperability challenges in other DID methods (
publicKeyJwk
versuspublicKeyMultibase
versus other; see the verification material section of the DID specification.
+
Despite this rich set of features, KERI imposes only light dependencies on developers. The cryptography it uses is familiar and battle-hardened, exactly what one would find in standard cryptography toolkits. For example, the python implementation (keripy) only depends on the pysodium
, blake3
, and cryptography
python packages. Libraries for KERI exist in javascript, rust, and python.
§ IANA Considerations
+This section is normative.
+-
+
- KERI event streams use the registered application/cesr media type with IANA. The media type is
application/cesr
. The registration follows the template in RFC6838.
+
§ Security Considerations
+This section is normative.
+There are many security considerations related to web requests, storing information securely, etc. It is useful to address these considerations along with the common security threats found on the web.
+§ Common security threats
+-
+
- All
did:webs
features MUST reduce the attack surface against common threats: +-
+
- Broken Object Level Authorization (BOLA) attacks MUST be eliminated or reduced. +
- Denial of service (DoS) attacks MUST be eliminated or reduced. +
- Deletion attacks MUST be eliminated or reduced. +
- Duplicity detection MUST be available and reliable. +
- Eclipse attacks MUST be eliminated or reduced. +
- Forgery attacks MUST be eliminated or reduced. +
- Impersonation attacks MUST be eliminated or reduced. +
- Key Compromise attacks MUST be eliminated or reduced. +
- Malleability attacks MUST be eliminated or reduced. +
- Replay attacks MUST be eliminated or reduced. +
+
§ Using HTTPS
+Perfect protection from eavesdropping is not possible with HTTPS, for various +reasons.
+-
+
- URLs of DID documents and KERI event streams SHOULD be hosted in a way that embodies accepted cybersecurity best practice. This is not strictly necessary to guarantee the authenticity of the data. However, the usage:
+
-
+
- MUST safeguard privacy +
- MUST discourage denial of service +
- MUST work in concert with defense-in-depth mindset +
- MUST aid regulatory compliance +
- MUST allow for high-confidence fetches of the DID document and a KERI event stream +
+ - A host that uses a fully qualified domain name of the method-specific identifier MUST be 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 bewww.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: +
+ - The certificate MUST satisfy whatever requirements are active in the client, such that the client does accept the certificate and use it to build and communicate over the encrypted HTTPS session where a DID document and KERI event stream are fetched. +
- The certificate MUST pass some common-sense validity tests, even if the client is very permissive:
+
-
+
- It MUST have a valid signature +
- It MUST NOT be expired or revoked or deny-listed +
- It MUST NOT have any broken links in its chain of trust. +
+ - If a URL of a DID document or KERI event streams results in a redirect, each URL MUST satisfy the same security requirements.
+
www.example.com
as well.
+
§ International Domain Names
+-
+
- As with
did:web
, implementers ofdid:webs
SHOULD consider how non-ASCII characters manifest in URLs and DIDs. +-
+
did:webs
MUST follow the DID-CORE identifier syntax which does not allow the direct representation of such characters in method name or method specific identifiers. This prevents adid:webs
value from embodying a homograph attack.
+- However,
did:webs
MAY hold data encoded with punycode or percent encoding. This means that IRIs constructed from DID values could contain non-ASCII characters that were not obvious in the DID, surprising a casual human reader.
+ - Caution is RECOMMENDED when treating a
did:webs
as the equivalent of an IRI.
+ - Treating it as the equivalent of a URL, instead, is RECOMMENDED as it preserves the punycode and percent encoding and is therefore safe. +
+
§ Concepts for securing did:webs
information
+The following security concepts are used to secure the data, files, signatures and other information in did:webs
.
-
+
- All security features and concepts in
did:webs
MUST use one or more of the following mechanisms: +-
+
- All data that requires the highest security MUST be KEL backed. This includes any information that needs to be end-verifiably authentic over time: + + +
- All data that does not need to incur the cost of KEL backing for secuirty but can benefit from the latest data-state such as a distributed data-base MUST use Best Available Data - Read, Update, Nullify (BADA-RUN).
+
-
+
- BADA-RUN information MUST be ordered in a consistent way, using the following:
+
-
+
- date-time MUST be used. +
- key state MUST be used. +
+ - Discovery information MAY use BADA-RUN because the worst-case attack on discovery information is a DDoS attack where nothing gets discovered.
+
-
+
- The controller(s) of the AID for a
did:webs
identifier MAY use BADA-RUN for service end-points as discovery mechanisms.
+
+ - The controller(s) of the AID for a
+ - BADA-RUN information MUST be ordered in a consistent way, using the following:
+
- All data that does not need the security of being KEL backed nor BADA-RUN SHOULD be served using KERI Request Authentication Mechanism (KRAM).
+
-
+
- For a
did:webs
resolver to be trusted it SHOULD use KRAM to access the service endpoints providing KERI event streams for verification of the DID document.
+
+ - For a
+
§ Reducing the attack surface
+This section is informative.
+The above considerations have lead us to focus on KEL backed DID document blocks and data (whois files, signatures, etc) so that the trusted (local) did:webs resolver is secure. Any future features that could leverage BADA-RUN and KRAM should be considered carefully according to the above considerations.
+See the implementors guide for more details about KEL backed, BADA-RUN, and KRAM:
+ +§ Privacy Considerations
+This section is informative.
+This section addresses the privacy considerations from RFC6973 section 5.
+For privacy considerations related to web infrastructure, see did:web
privacy considerations.
+Below we discuss privacy considerations related the KERI infrastructure.
§ Surveillance
+In KERI, a robust witness network along with consistent witness rotation provides protection from monitoring and association of +an individual’s activity inside a KERI network.
+§ Stored Data Compromise
+For resolvers that simply discover the Key State endorsed by another party in a discovery network, caching policies +of that network would guide stored data security considerations. In the event that a resolver is also the endorsing party, +meaning they have their own KERI identifier and are verifying the KEL and signing the Key State themselves, leveraging the +facilities provided by the KERI protocol (key rotation, witness maintenance, multi-sig) should be used to protect the identities +used to sign the Key State.
+§ Unsolicited Traffic
+DID Documents are not required to provide endpoints and thus not subject to unsolicited traffic.
+§ Misattribution
+This DID Method relies on KERI’s duplicity detection to determine when the non-repudiable controller of a DID +has been inconsistent and can no longer be trusted. This establishment of non-repudiation enables consistent attribution.
+§ Correlation
+The root of trust for KERI identifiers is entropy and therefore offers no direct means of correlation. In addition, KERI provides +two modes of communication, direct mode and indirect mode. Direct mode allows for pairwise (n-wise as well) relationships that +can be used to establish private relationships.
+See the KERI specification for more 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.
+See the KERI specification for more information about secure bindings and prefix derivation
+§ 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.
+§ Interoperability Profiles
+This section is normative.
+The following interoperability profiles define the requirements necessary for a did:webs implementation and the did:webs identifiers that use that implementation to interoperate with other did:webs identifiers. The profiles will also help to fascilate an automated test suite for did:webs implementations to validate their interoperability profile achievement.
+§ Minimal interoperability profile
+This profile defines the absolute minimal implementation to create and interoperate with a did:webs identifier.
+-
+
- Coming Soon +
§ References
+§ Normative References
+-
+
- Data Integrity Proof +
- The data integrity proof defined in the Verifiable Credential Data Model spec. See https://www.w3.org/TR/vc-data-model/#data-integrity-proofs. +
- JSON Serialization +
- See https://datatracker.ietf.org/doc/html/rfc7515#section-3.2. +
- multiformat multihash +
- See https://github.com/multiformats/multihash. +
- RFC1035 +
- Domain names - implementation and specification. See https://www.rfc-editor.org/info/rfc1035. +
- RFC1123 +
- Requirements for Internet Hosts – Application and Support. See https://datatracker.ietf.org/doc/html/rfc1123. +
- RFC2181 +
- Clarifications to the DNS Specification. See https://www.rfc-editor.org/info/rfc2181. +
- Trust over IP - Authentic Chained Data Containers (ACDC) specification +
- The ACDC specification details the core ACDC specification including the Issuance and Presentation Exchange (IPEX) Protocol and Public Transaction Event Log (PTEL) specification. +
- Trust over IP - Composable Event Streaming Representation (CESR) +
- The CESR specification details the core CESR protocol including the Self-Addressing IDentifier (SAID) specification. +
- Trust over IP - CESR Proof Signatures +
- The CESR Proof Signatures specification details the core CESR Proof Signatures. +
- Trust over IP - Key Event Receipt Infrastructure (KERI) +
- The KERI specification details the core Key Event Receipt Infrastructure (KERI) protocol. This includes the Out-of-Band-Introduction (OOBI) specification. +
- W3C - did:web Method Specification +
- The did:web specification details the did:web method specification. +
- W3C - Decentralized Identifiers (DIDs) +
- The DIDs specification details the core Decentralized Identifiers (DIDs) specification. +
- W3C - DID spec registries +
- The DID Spec Registries detail the specs for each registred DID method. +
- W3C - DID URL path +
- See https://www.w3.org/TR/did-core/#path. +
- W3C - Verifiable Credentials Data Model (VCDM) +
- The W3C - Verifiable Credentials Data Model (VCDM) details the the core Verifiable Credentials Data Model (VCDM) specification. +
- W3C - verifiable presentation +
- See (https://www.w3.org/TR/vc-data-model/#presentations-0). +
- ACDC IPEX +
- ACDC Verifiable Credential Issuance and Presentation Excchange as defined in the KERI ACDC spec https://trustoverip.github.io/tswg-acdc-specification/#ipex-validation. +
§ Informative References
+-
+
- did:webs Reference Implementation +
- See the python reference implementation of did:webs. The GETTING STARTED guide was created for new users and is the source that many of the examples in this specification were copied from. +
- Hyperledger AnonCreds +
- See https://www.hyperledger.org/projects/anoncreds. And Setting up to publish AnonCreds verifiable credential. +
- Overlay Capture Architecture +
- See Aries RFC. +
- rfc5895 +
- See https://www.rfc-editor.org/info/rfc5895. +
- StatusList2021 +
- See https://w3c.github.io/vc-status-list-2021/. +
- UTS-46 +
- See https://unicode.org/reports/tr46/. +
- W3C VC Rendering Methods specification +
- See https://w3c-ccg.github.io/vc-render-method/. +
§ Appendix
+§ Trust Over IP Glossary - Controlled Terms
+-
+
- autonomous identifier +
- Another term for self-certifying identifier (SCID). +
- cryptographically verifiable +
- A property of a data structure that has been digitally signed using a private key such that the digital signature can be verified using the public key. Verifiable data, verifiable messages, verifiable credentials, and verifiable data registries are all cryptographically verifiable. Cryptographic verifiability is a primary goal of the ToIP Technology Stack. +
- identifier +
- A single attribute—typically a character string—that uniquely identifies an entity within a specific context (which may be a global context). Examples include the name of a party, the URL of an organization, or a serial number for a man-made thing. Supporting definitions: eSSIF-Lab: a character string that is being used for the identification of some entity (yet may refer to 0, 1, or more entities, depending on the context within which it is being used). +
- self-certifying identifier (SCID) +
- A subclass of verifiable identifier (VID) that is cryptographically verifiable without the need to rely on any third party for verification because the identifier is cryptographically bound to the cryptographic keys from which it was generated. Also known as: autonomous identifier. +
- verifiable identifier (VID) +
- An identifier over which the controller can provide cryptographic proof of control. +See also: decentralized identifier, self-certifying identifier (SCID). +
§ Terminology
+-
+
- AID controlled identifiers +
- Any identifier, including
did:webs
DIDs, that have the same AID are by definition referencing the same identity. As defined in the KERI specification
+ - authentic chained data container (ACDC) +
- a variant of the Verifiable Credential (VC) specification that inherits the security model derived from KERI, as defined by the ACDC specification. See WebOfTrust glossary for more detail. +
- autonomic identifier (AID) +
- A self-certifying identifier (SCID) that is cryptographically bound cryptographically bound to a key event log (KEL), as defined by the KERI specification. An AID is either non-transferable or transferable. A non-transferable AID does not support key rotation while a transferable AID supports key rotation using a key pre-rotation mechanism that enables the AID to persist in spite of the evolution of its key state. See WebOfTrust glossary for more detail. +
- BADA-RUN +
- Best available data acceptance - Read/Update/Nullify provides a medium level of security because events are ordered in a consistent way, using a combination of date-time and a key state. The latest event is the one with the latest date-time for the latest key state. See The KERI spec for more detail. +
- compact event streaming representation (CESR) +
- An encoding format that enables round-trip text-binary conversion of concatenated cryptographic primitives and general data types, as defined by the CESR specification and CESR Proof Signature specification. See WebOfTrust glossary for more detail. +
- controller +
- A controlling entity that can cryptographically prove the control authority (signing and rotation) over an AID as well as make changes on the associated KEL. A controller may consist of multiple controlling entities in a multi-signature scheme. See WebOfTrust glossary for more detail. +
- decentralized identifier (DID) +
- A globally unique persistent identifier, as defined by DID Core. +
- designated aliases +
- An array of AID controlled identifiers that have been designated by the AID controller to be used as aliases for
equivalentId
andalsoKnownAs
DID document metadata and to foster verification of redirection to different did:webs identifiers. See WebOfTrust glossary for more detail.
+ - DID document +
- A set of data describing the subject of a DID, as defined by DID Core. See also section DID Documents. +
- DID resolution metadata +
- DID resolution metadata is metadata about the DID Resolution process that was performed in order to obtain the DID document for a given DID. See also DID Resolution Metadata in the DID Core specification. +
- DID document metadata +
- DID document metadata is metadata about the DID and the DID document that is the result of the DID Resolution process. See also DID Document Metadata in the DID Core specification. +
- direct mode +
- an operational mode of the KERI protocol where a controller and a verifier of an AID exchange the KEL of the AID directly, as defined by the KERI whitepaper. See WebOfTrust glossary for more detail. +
- host +
- The part of a URL that can be either a domain name or an IP address. This component specifies the server that the client needs to communicate with in order to access the desired resource on the web. +
- inception event +
- A key event that provides the incepting information needed to derive an AID and establish its initial key state, as defined by the KERI specification. See WebOfTrust glossary for more detail. +
- indirect mode +
- An operational mode of the KERI protocol where the KEL of an AID is discovered by a verifier via witnesses, as defined by the KERI whitepaper. See WebOfTrust glossary for more detail. +
- interaction event +
- A key event that anchors external data to an AID, as defined by the KERI specification. An interaction event does not change the key state of the AID. See WebOfTrust glossary for more detail. +
- key event +
- A serialized data structure of an entry in the key event log(KEL) for an AID, as defined by the KERI specification. There are three types of key events, namely inception event, rotation event, and interaction event. See WebOfTrust glossary for more detail. +
- key event log (KEL) +
- A verifiable append-only log of key events for an AID that is both backward and forward-chained, as defined by the KERI specification. See WebOfTrust glossary for more detail. +
- KEL backed data +
- KEL backed data in
did:webs
provides the highest level of data security assurance and such data can be found either in the KEL or anchored to an event in the KEL. This means that the signatures on the events in the KEL are strongly bound to the key state at the time the events are entered in the KEL, that is the data. This provides strong guarantees of non-duplicity to any verifiers receiving a presentation as the KELs are protected and can be watched by agents (watcher) of the verifiers. The information is end-verifiable and any evidence of duplicity in the events is evidence that the data or presentation should not be trusted. See WebOfTrust glossary for more detail.
+ - key event receipt +
- A message whose body references a key event of an AID and includes one or more signatures on that key event, as defined by the KERI specification. See WebOfTrust glossary for more detail. +
- key event receipt log (KERL) +
- A verifiable append-only log that includes all the consistent key event receipt messages, as defined by the KERI specification. See WebOfTrust glossary for more detail. +
- key event receipt infrastructure (KERI) +
- A protocol that provides an identity system-based secure overlay for the internet and uses AIDs as the primary roots of trust, as defined by the KERI specification. See WebOfTrust glossary for more detail. +
- KERI event stream +
- A stream of verifiable KERI data, consisting of the key event log (KEL) and other data such as a transaction event log (TEL). This data is a CESR event stream, with media type application/cesr, and may be serialized in a file using CESR encoding. We refer to these CESR stream resources as KERI event streams to simplify the vocabulary. See WebOfTrust glossary for more detail. +
- key state +
- The set of currently authoritative key pairs (current keys) for an AID and any other information necessary to secure or establish control authority over the AID. See WebOfTrust glossary for more detail. +
- KERI Request Authentication Mechanism +
- A non-interactive replay attack protection algorithm that uses a sliding window of date-time stamps and key state (similar to the tuple in BADA-RUN) but the date-time is the replier’s not the querier’s. KRAM is meant to protect a host. See the WebOfTrust glossary for more detail. +
- method-specific identifier +
- The
method-specific-id
part of DID Syntax, as defined in DID Core. See section Method-Specific Identifier.
+ - multi-signature +
- A mechanism that enables multiple parties to sign a message, as defined by the KERI specification. See Controller Application in the KERI spec for more detail. +
- out-of-band introduction (OOBI) +
- A protocol for discovering verifiable information on an AID or a SAID, as defined by the KERI specification. The OOBI by itself is insecure, and the information discovered by the OOBI must be verified. See WebOfTrust glossary for more detail. +
- pre-rotation +
- A key rotation mechanism whereby a set of rotation keys are pre-commited using cryptographic digests, as defined by the KERI specification. See WebOfTrust glossary for more detail. +
- rotation event +
- A key event that provides the information needed to change the key state for an AID using pre-rotation, as defined by the KERI specification. See WebOfTrust glossary for more detail. +
- self-addressing identifier (SAID) +
- An identifier that is uniquely and cryptographically bound to a serialization of data (content-addressable) while also being included as a component in that serialization (self-referential), as defined by the CESR specification. See WebOfTrust glossary for more detail. +
- transaction event log (TEL) +
- A verifiable append-only log of transaction data that are cryptographically anchored to a KEL. The transaction events of a TEL may be used to establish the issuance or revocation state of ACDCs. See WebOfTrust glossary for more detail. +
- verifier +
- An entity or component that cryptographically verifies the signature(s) on an event message. See WebOfTrust glossary for more detail. +
- watcher +
- An entity that keeps a copy of a KERL of an AID to detect duplicity of key events, as defined by the KERI whitepaper. See WebOfTrust glossary for more detail. +
- witness +
- An entity that is designated by the controller of an AID to verify, sign, and keep the key events associated with the AID, as defined by the KERI whitepaper. See WebOfTrust glossary for more detail. +
§ Implementors Guide
+These sections are informative.
+§ Key Agreement
+-
+
- key agreement +
- This section is informative: +There are multiple ways to establish key agreement in KERI. We detail common considerations and techniques: +
-
+
-
+
If the ‘k’ field references a Ed25519 key, then key agreement may be established using the corresponding x25519 key for Diffie-Helman key exchange.
+
+ -
+
If the key is an ECDSA or other NIST algorithms key then it will be the same key for signatures and encryption and can be used for key agreement.
+
+ -
+
BADA-RUN for key agreement: Normally in KERI we would use BADA-RUN, similar to how we specify endpoints, host migration info, etc. This would allow the controller to specify any Key Agreement key, without unnecessarily adding KERI events to their KEL.
+
+ -
+
Key agreement from
+k
field keys: It is important to note that KERI is cryptographically agile and can support a variety of keys and signatures.
+ -
+
Key agreement anchored in KEL: It is always possible to anchor arbitrary data, like a key agreement key, to the KEL.
+-
+
- The best mechanism is to anchor an ACDC to a TEL which is anchored to the KEL. The data would be the basis of the key agreement information. The concept is similar to how we anchor designated aliases as verifiable data on a TEL. +
+
§ Other Key Commitments
+-
+
- Other Key Commitments +
- This section is informative. +Data structures similar to Location Scheme and Endpoint Authorizations and managed in KERI using BADA-RUN may be created and used for declaring other types of keys, for example encryption keys, etc +
To support new data structures, propose them in KERI and detail the transformation in the spec.
+§ On-Disk Storage
+-
+
- On-Disk Storage +
- This section is informative. +Both KEL backed data and BADA-RUN security approaches are suitable for storing information on disk because both provide a link between the keystate and date-time on some data when a signature by the source of the data was created. BADA-RUN is too weak for important information because an attacker who has access to the database on disk can overwrite data on disk without being detected by a verifier hosting the on-disk data either through a replay of stale data (data regression attack) or if in addition to disk access the attacker has compromised a given key state, then the attacker can forge new data with a new date-time stamp for a given compromised key and do a regression attack so that the last seen key state is the compromised key state. +
With BADA, protection from a deletion (regression) attack requires redundant disk storage. At any point in time where there is a suspicion of loss of custody of the disk, a comparison to the redundant disks is made and if any disk has a later event given BADA-RUN rules then recovery from the deletion attack is possible.
+KRAM on a query is not usable for on disk storage by itself. Because it’s just a bare signature (the datetime is not of the querier but of the host at the time of a query). However, the reply to a query can be stored on disk if the querier applies BADA to the reply. To elaborate, Data obtained via a KRAMed query-reply may be protected on-disk by being using BADA on the reply. This is how KERI stores service endpoints. However, KERI currently only uses BADA for discovery data not more important data. More important data should be wrapped (containerized) in an ACDC that is KEL backed and then stored on-disk
+In the hierarchy of attack surfaces, exposure as on disk (unencrypted) is the weakest. Much stronger is exposure that is only in-memory. To attack in-memory usually means compromising the code supply chain which is harder than merely gaining disk access. Encrypting data on disk does not necessarily solve attacks that require a key compromise (because decryption keys can be compromised), and it does not prevent a deletion attack. Encryption does not provide authentication protection. However, encryption does protect the confidentiality of data.
+The use of DH key exchange as a weak form of authentication is no more secure than an HMAC for authentication. It is sharing secrets, so anyone with the secret can impersonate any other member of the group that has the shared secret.
+Often, DID methods have focused on features that erode security characteristics. The paper Five DID Attacks highlights some attacks to which did:webs
should NOT be vulnerable. So when a pull request exposes did:webs
to a known attack, it should not be accepted.
§ Alignment of Information to Security Posture
+-
+
- Alignment of Information to Security Posture +
- This section is informative. +As a general security principle each block of information should have the same security posture for all the sub-blocks. One should not attempt to secure a block of information that mixes security postures across is constituent sub-blocks. The reason is that the security of the block can be no stronger than the weakest security posture of any sub-block in the block. Mixing security postures forces all to have the lowest common denominator security. The only exception to this rule is if the block of information is purely informational for discovery purposes and where it is expected that each constituent sub-block is meant to be verified independently. +
This means that any recipient of such a block information with mixed security postures across its constituent sub-blocks must explode the block into sub-blocks and then independently verify the security of each sub-block. However, this is only possible if the authentication factors for each sub-block are provided independently. Usually when information is provided in a block of sub-blocks, only one set of authentication factors are provided for the block as a whole and therefore there is no way to independently verify each sub-block of information.
+Unfortunately, what happens in practice is that users are led into a false sense of security because they assume that they don’t have to explode and re-verify, but merely may accept the lowest common denominator verification on the whole block of information. This creates a pernicious problem for downstream use of the data. A downstream use of a constituent sub-block doesn’t know that it was not independently verified to its higher level of security. This widens the attack surface to any point of down-stream usage. This is a root cause of the most prevalent type of attack called a BOLA.
+§ Applying the concepts of KEL, BADA-RUN, and KRAM to did:webs
+-
+
- Applying the concepts of KEL +
- This section is informative.
+Lets explore the implications of applying these concepts to various
did:webs
elements. +Using KEL backed elements in a DID doc simplifies the security concerns. However, future discovery features related to endpoints might consider BADA-RUN. For instance, ‘whois’ data could be used with BADA-RUN whereas did:web aliases should not because it could lead to an impersonation attack. We could have a DID document that uses BADA-RUN if we modify the DID CRUD semantics to be RUN semantics without necessarily changing the verbs but by changing the semantics of the verbs. Then any data that fits the security policy of BADA (i.e. where BADA is secure enough) can be stored in a DID document as a database in the sky. For sure this includes service endpoints for discovery. One can sign with CESR or JWS signatures. The payloads are essentially KERI reply messages in terms of the fields (with modifications as needed to be more palatable), but are semantically the same. The DID doc just relays those replies. Anyone reading from the DID document is essentially getting a KERI reply message, and they then should apply the BADA rules to their local copy of the reply message.
+
To elaborate, these security concepts point us to modify the DID CRUD semantics to replicate RUN semantics. Create becomes synonymous with Update where Update uses the RUN update. Delete is modified to use the Nullify semantics. Read data is modified so that any recipient of the Read response can apply BADA to its data (Read is a GET). So we map the CRUD of DID docs to RUN for the did:webs
method. Now you have reasonable security for things like signed data. If its KEL backed data you could even use an ACDC as a data attestation for that data and the did resolver would become a caching store for ACDCs issued by the AID controller.
Architecturally, a Read (GET) from the did resolver acts like how KERI reply messages are handled for resolving service endpoint discovery from an OOBI. The query is the read in RUN and so uses KRAM. The reply is the response to the READ request. The controller of the AID updates the DID resolvers cache with updates(unsolicited reply messages). A trustworthy DID resolver applies the BADA rules to any updates it receives. Optionally the DID resolver may apply KRAM rules to any READ requests to protect it from replay attacks.
+In addition, a DID doc can be a discovery mechanism for an ACDC caching server by including an index (label: said) of the SAIDs of the ACDCs held in the resolvers cache.
+§ The set of KERI features needed
+-
+
- The set of KERI features needed +
- This section is informative.
+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 indid:webs
enables a number of capabilities for securing adid:webs
identifier, including multi-signature support and the creation of pre-rotated keys to prevent loss of control of the identifier if the current private key were to be compromised. +You may find the did:webs feature dependency diagram helpful as a visual guide to the features and dependencies ofdid:webs
.
+
§ Stable identifiers on an unstable web
+-
+
- Stable identifiers on an unstable web +
- This section is informative.
+The web is not a very stable place, and documents are moved around and copied frequently. When two or more companies merge, often the web presence of some of the merged entities “disappears”. It may not be possible to retain a permanent
did:webs
web location. +The purpose of the history of designated aliases for the AID is so that if thedid:webs
DID has been put in long-lasting documents, and its URL instantiation is redirected or disappears, the controller can explicitly indicate that the new DID is anequivalentId
to the old one.
+
Since the AID is globally unique and references the same identifier, regardless of the rest of the string that is the full did:webs
, web searching could yield either the current location of the DID document, or a copy of the DID that may be useful. For example, even the Internet Archive: Wayback Machine could be used to find a copy of the DID document and the KERI event stream at some point in the past that may be sufficient for the purposes of the entity trying to resolve the DID. This specification does not rely on the Wayback Machine, but it might be a useful did:webs
discovery tool.
The DID document, KERI event stream and other files related to a DID may be copied to other web locations. For example, someone might want to keep a cache of DIDs they use, or an entity might want to run a registry of “useful” DIDs for a cooperating group. While the combination of DID document and KERI event stream make the DID and DID document verifiable, just as when published in their “intended” location, the absence of the did:webs
in the designated aliases for those locations in the DID document equivalentId
means that the controller of the DID is not self-asserting any sort of tie between the DID and the location to which the DID-related documents have been copied. In contrast, if the controller confirms the link between the source and the copy with an equivalentId
, the related copies will have to be kept in sync.
Were the AID of a did:webs
identifier to change, it would be an altogether new DID, unconnected to the first DID.
+A did:webs
could be moved to use another DID method that uses the AID for uniqueness and the KERI event stream for validity, but that is beyond the scope of this specification.
§ KERI event stream chain of custody
+-
+
- KERI event stream chain of custody +
- This section is informative. +The KERI event stream represents a cryptographic chain of trust originating from the AID of the controller to the current operational set of keys (signing and otherwise) as well as the cryptographic commitments to the keys the controller will rotate to in the future. The KERI event stream also contains events that do not alter the AID key state, but are useful metadata for the DID document such as, the supported hosts, the 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 “Basic KERI event details” and show how they change the DID Document. The mapping from the KERI event stream to the DID Document properties compose 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, dynamically generate the keri.cesr resource, etc) is beyond the scope of the spec, but the did:webs Reference Implementation of the resolver demonstrate some of these techniques. The important concept is that the entire KERI event stream is used to produce and verify the DID document. +
§ Verifiable data on a TEL
+-
+
- verifiable data on a TEL +
- This section is informative. +Below is an example highlighting how verifiable data is anchored to a KEL using a TEL. We use this spec’s designated aliases feature as a real-world example. You can walk through this example in the did:webs Reference Implementation. +The attestation (self-issued credential) is as follows: +
{
+ "v": "ACDC10JSON0005f2_",
+ "d": "EIGWggWL2IHiUzj1P2YuPA0-Uh55LTIu14KTvVQGrfvT",
+ "i": "ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "ri": "EAtQJEQMkkvlWxyfLbcLyv4kNeAI5Qsqe65vKIWnHKpx",
+ "s": "EN6Oh5XSD5_q2Hgu-aqpdfbVepdpYpFlgz6zvJL5b_r5",
+ "a": {
+ "d": "EJJjtYa6D4LWe_fqtm1p78wz-8jNAzNX6aPDkrQcz27Q",
+ "dt": "2023-11-13T17:41:37.710691+00:00",
+ "ids": [
+ "did:web:did-webs-service%3a7676:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "did:webs:did-webs-service%3a7676:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "did:web:example.com:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "did:web:foo.com:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "did:webs:foo.com:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe"
+ ]
+ },
+ "r": {
+ "d": "EEVTx0jLLZDQq8a5bXrXgVP0JDP7j8iDym9Avfo8luLw",
+ "aliasDesignation": {
+ "l": "The issuer of this ACDC designates the identifiers in the ids field as the only allowed namespaced aliases of the issuer's AID."
+ },
+ "usageDisclaimer": {
+ "l": "This attestation only asserts designated aliases of the controller of the AID, that the AID controlled namespaced alias has been designated by the controller. It does not assert that the controller of this AID has control over the infrastructure or anything else related to the namespace other than the included AID."
+ },
+ "issuanceDisclaimer": {
+ "l": "All information in a valid and non-revoked alias designation assertion is accurate as of the date specified."
+ },
+ "termsOfUse": {
+ "l": "Designated aliases of the AID must only be used in a manner consistent with the expressed intent of the AID controller."
+ }
+ }
+}
+
+Now we show that the information is anchored to the KEL in a way that allows for changes in key state while not invalidating it. We will:
+-
+
- chain an interaction event on the KEL, to a registry we call a TEL +
- The TEL maintains the ‘state’ of issued or revoked for the attestation. If the controller wants to update the list they would revoke the attestation and issue a new attestation with the updated list of aliases that they want to designate. +
- The TEL must chain to the attestation itself. +This is what forms the end-to-end verifiability from the attestation to the AID itself. Here is the KERI Event Stream of each part: +
§ The interaction event on the KEL
+This interaction event connects the TEL registry to the KEL. Notice the a
field with the nested i
field that references the registry
"v": "KERI10JSON00013a_",
+ "t": "ixn",
+ "d": "ED-4iQIVxwMcrTOW6fVs9oPpLTIxtqh_vcvLmE999zsU",
+ "i": "ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "s": "1",
+ "p": "ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "a": [
+ {
+ "i": "EAtQJEQMkkvlWxyfLbcLyv4kNeAI5Qsqe65vKIWnHKpx",
+ "s": "0",
+ "d": "EAtQJEQMkkvlWxyfLbcLyv4kNeAI5Qsqe65vKIWnHKpx"
+ }
+ ]
+
+§ The TEL registry
+This TEL registry connects the KEL interaction event to the registry status. Notice the d
field matches the nested i
field of the a
field of the interaction event demonstrating that they are cryptographically chained together.
"v": "KERI10JSON000113_",
+ "t": "vcp",
+ "d": "EAtQJEQMkkvlWxyfLbcLyv4kNeAI5Qsqe65vKIWnHKpx",
+ "i": "EAtQJEQMkkvlWxyfLbcLyv4kNeAI5Qsqe65vKIWnHKpx",
+ "ii": "ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "s": "0",
+ "c": [
+ "NB"
+ ],
+ "bt": "0",
+ "b": [],
+ "n": "AAfqHwMDdBoIWk_4Z6hvVJuhtvjA_gk8Y9bEUoP_rC_p"
+
+§ The attestation status
+The current status of the attestation is in the t
field. iss
means issued. Notice the ri
field cryptographically binds this issued status to the registry above. Likewise, the i
field cryptographically binds to the attestation d
field.
"v": "KERI10JSON0000ed_",
+ "t": "iss",
+ "d": "EJQvCZQYn8oO1z3_f8qhxXjk7TcLol4G3RdHVTwfGV3L",
+ "i": "EIGWggWL2IHiUzj1P2YuPA0-Uh55LTIu14KTvVQGrfvT",
+ "s": "0",
+ "ri": "EAtQJEQMkkvlWxyfLbcLyv4kNeAI5Qsqe65vKIWnHKpx",
+ "dt": "2023-11-13T17:41:37.710691+00:00"
+
+§ The full KERI Event Stream
+This snippet demonstrates how these events occur in the full keri.cesr file. Notice the CESR encoded verifiable signatures that are interleaved between events.
+{
+ "v": "KERI10JSON00012b_",
+ "t": "icp",
+ "d": "ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "i": "ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "s": "0",
+ "kt": "1",
+ "k": [
+ "DHr0-I-mMN7h6cLMOTRJkkfPuMd0vgQPrOk4Y3edaHjr"
+ ],
+ "nt": "1",
+ "n": [
+ "ELa775aLyane1vdiJEuexP8zrueiIoG995pZPGJiBzGX"
+ ],
+ "bt": "0",
+ "b": [],
+ "c": [],
+ "a": []
+}-VAn-AABAADjfOjbPu9OWce59OQIc-y3Su4kvfC2BAd_e_NLHbXcOK8-3s6do5vBfrxQ1kDyvFGCPMcSl620dLMZ4QDYlvME-EAB0AAAAAAAAAAAAAAAAAAAAAAA1AAG2024-04-01T17c40c48d329209p00c00{
+ "v": "KERI10JSON00013a_",
+ "t": "ixn",
+ "d": "ED-4iQIVxwMcrTOW6fVs9oPpLTIxtqh_vcvLmE999zsU",
+ "i": "ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "s": "1",
+ "p": "ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "a": [
+ {
+ "i": "EAtQJEQMkkvlWxyfLbcLyv4kNeAI5Qsqe65vKIWnHKpx",
+ "s": "0",
+ "d": "EAtQJEQMkkvlWxyfLbcLyv4kNeAI5Qsqe65vKIWnHKpx"
+ }
+ ]
+}-VAn-AABAACNra5mDg7YHFtBeXiwIGqnHkyq7F55FGNYG1wH95akjSWCb1HzNI3E05ufT0HffClDxnJF_DmAUW2SBb0EJeoO-EAB0AAAAAAAAAAAAAAAAAAAAAAB1AAG2024-04-01T17c42c37d704426p00c00{
+ "v": "KERI10JSON00013a_",
+ "t": "ixn",
+ "d": "EBjw0a_L8M0F4xYND99dvahlrkpxODi9Wc9VzUvkhD0t",
+ "i": "ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "s": "2",
+ "p": "ED-4iQIVxwMcrTOW6fVs9oPpLTIxtqh_vcvLmE999zsU",
+ "a": [
+ {
+ "i": "EIGWggWL2IHiUzj1P2YuPA0-Uh55LTIu14KTvVQGrfvT",
+ "s": "0",
+ "d": "EJQvCZQYn8oO1z3_f8qhxXjk7TcLol4G3RdHVTwfGV3L"
+ }
+ ]
+}-VAn-AABAABo_okwAmWIYWI93EtUONZiEvsGuSRkKnj0mopX_RoXwWHZ_1V5hQ0BxcntsmAi21DbusyCmK-fHwTNtSxUSsoN-EAB0AAAAAAAAAAAAAAAAAAAAAAC1AAG2024-04-01T17c42c39d995867p00c00{
+ "v": "KERI10JSON000113_",
+ "t": "vcp",
+ "d": "EAtQJEQMkkvlWxyfLbcLyv4kNeAI5Qsqe65vKIWnHKpx",
+ "i": "EAtQJEQMkkvlWxyfLbcLyv4kNeAI5Qsqe65vKIWnHKpx",
+ "ii": "ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "s": "0",
+ "c": [
+ "NB"
+ ],
+ "bt": "0",
+ "b": [],
+ "n": "AAfqHwMDdBoIWk_4Z6hvVJuhtvjA_gk8Y9bEUoP_rC_p"
+}-VAS-GAB0AAAAAAAAAAAAAAAAAAAAAABED-4iQIVxwMcrTOW6fVs9oPpLTIxtqh_vcvLmE999zsU{
+ "v": "KERI10JSON0000ed_",
+ "t": "iss",
+ "d": "EJQvCZQYn8oO1z3_f8qhxXjk7TcLol4G3RdHVTwfGV3L",
+ "i": "EIGWggWL2IHiUzj1P2YuPA0-Uh55LTIu14KTvVQGrfvT",
+ "s": "0",
+ "ri": "EAtQJEQMkkvlWxyfLbcLyv4kNeAI5Qsqe65vKIWnHKpx",
+ "dt": "2023-11-13T17:41:37.710691+00:00"
+}-VAS-GAB0AAAAAAAAAAAAAAAAAAAAAACEBjw0a_L8M0F4xYND99dvahlrkpxODi9Wc9VzUvkhD0t{
+ "v": "ACDC10JSON0005f2_",
+ "d": "EIGWggWL2IHiUzj1P2YuPA0-Uh55LTIu14KTvVQGrfvT",
+ "i": "ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "ri": "EAtQJEQMkkvlWxyfLbcLyv4kNeAI5Qsqe65vKIWnHKpx",
+ "s": "EN6Oh5XSD5_q2Hgu-aqpdfbVepdpYpFlgz6zvJL5b_r5",
+ "a": {
+ "d": "EJJjtYa6D4LWe_fqtm1p78wz-8jNAzNX6aPDkrQcz27Q",
+ "dt": "2023-11-13T17:41:37.710691+00:00",
+ "ids": [
+ "did:web:did-webs-service%3a7676:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "did:webs:did-webs-service%3a7676:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "did:web:example.com:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "did:web:foo.com:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe",
+ "did:webs:foo.com:ENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe"
+ ]
+ },
+ "r": {
+ "d": "EEVTx0jLLZDQq8a5bXrXgVP0JDP7j8iDym9Avfo8luLw",
+ "aliasDesignation": {
+ "l": "The issuer of this ACDC designates the identifiers in the ids field as the only allowed namespaced aliases of the issuer's AID."
+ },
+ "usageDisclaimer": {
+ "l": "This attestation only asserts designated aliases of the controller of the AID, that the AID controlled namespaced alias has been designated by the controller. It does not assert that the controller of this AID has control over the infrastructure or anything else related to the namespace other than the included AID."
+ },
+ "issuanceDisclaimer": {
+ "l": "All information in a valid and non-revoked alias designation assertion is accurate as of the date specified."
+ },
+ "termsOfUse": {
+ "l": "Designated aliases of the AID must only be used in a manner consistent with the expressed intent of the AID controller."
+ }
+ }
+}-VA0-FABENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe0AAAAAAAAAAAAAAAAAAAAAAAENro7uf0ePmiK3jdTo2YCdXLqW7z7xoP6qhhBou6gBLe-AABAADQOX208DAmZEPb2v0XXF0N6WgxOdOxB3AsCBJds_vbAr7v1PQBA4MWNsXc8unk5UykbB8j538XGkzLtujekvIP
+
+§ Adding service endpoint roles in KERI
+-
+
- A hypothetical new role that could be submitted to KERI, would be the DIDCommMessaging role. It could be specified +
{
+ "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"
+ }
+ }
+ ]
+}
+
+
+