From 5ced7387d8637880b41d08464c536825efe4cce0 Mon Sep 17 00:00:00 2001 From: 2byrds <2byrds@gmail.com> Date: Wed, 17 Jan 2024 12:21:47 -0500 Subject: [PATCH 1/9] trying formatting for examples, etc Signed-off-by: 2byrds <2byrds@gmail.com> --- spec/core.md | 139 +++++++++++++++++++-------------------------------- 1 file changed, 52 insertions(+), 87 deletions(-) diff --git a/spec/core.md b/spec/core.md index 2141cec..fa366c2 100644 --- a/spec/core.md +++ b/spec/core.md @@ -2,107 +2,57 @@ ### Method Name -The method name that identifies this DID method SHALL be: `webs`. - -> Note: when pronounced aloud, "webs" SHOULD become two syllables: the word -> "web" and the letter "s" (which stands for "secure"). Separating the final -> letter this way emphasizes that the method offers a security upgrade surpassing -> the one HTTPS gives to HTTP. - -A DID that uses this method MUST begin with the following prefix: `did:webs:`. -Per the DID specification, this string MUST be lower case. The remainder of the -DID, after the prefix, is the case-sensitive [[ref: method-specific identifier]] +1. The method name that identifies this DID method SHALL be: `webs`. +1. A DID that uses this method MUST begin with the following prefix: `did:webs:`. +1. Per the DID specification, this string MUST be lower case. +1. The remainder of the DID, after the prefix, is the case-sensitive [[ref: method-specific identifier]] ([[ref: MSI]]) described [below](#method-specific-identifier). +* > 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` [[ref: method-specific identifier]] has two +1. The `did:webs` [[ref: method-specific identifier]] has two parts, a [[ref: host]] with an optional path (identical to `did:web`), plus a KERI AID (autonomic identifier) that is always the final component of the path. +1. The [[ref: ABNF]] definition of a `did:webs` DID is as follows: + 1. ```webs-did = "did:webs:" host ":" aid``` + 1. ```webs-did = "did:webs:" host * (":" path) ":" aid``` +1. The formal rules describing valid [[ref: host]] syntax are described in +[RFC1035], [RFC1123], and [RFC2181]. +1. A port MAY be included and the colon MUST be percent encoded, like `%3a`, to prevent a conflict with paths. +1. Directories and subdirectories MAY optionally be included, delimited by colons rather than slashes. +1. The KERI AID is a unique identifier and MUST be derived from the inception event of a KERI identifier. +* > The inception event is the first item in the identifier's [[ref: KEL]]. The algorithm used to generate the AID depends on the type of AID. If the AID is transferable (supports key rotation) then the AID is generated by taking a cryptographic digest of the inception event of the KEL of the AID. If the AID is non-transferable (does not support key rotation) the AID is generated by taking a cryptographic digest of the first (and only) public key of the identifier. See the [[ref: KERI Fundamentals]] section for more details. +* > After the [[ref: host]] and optional path in a `did:webs` is a final path component, a colon and the AID. To be compatible with `did:web`, the AID is "just a path", the final (and perhaps only) path element. The presence of the required AID as a path element means that a `did:webs` always has a path,and so the "no path" version of a `did:web` that implicitly uses the `.well-known` folder is not supported by `did:webs`. Any `did:webs` can be expressed as a `did:web` but the inverse is not true--a `did:webs` MUST include an AID. -The [[ref: ABNF]] definition of a `did:webs` DID is as follows: - -``` -webs-did = "did:webs:" host ":" aid -webs-did = "did:webs:" host * (":" path) ":" aid -``` +### Target System(s) -The formal rules describing valid [[ref: host]] syntax are described in -[RFC1035], [RFC1123], and [RFC2181]. A port MAY be included and the colon MUST be percent -encoded to prevent a conflict with paths. Directories and subdirectories MAY -optionally be included, delimited by colons rather than slashes. - -A KERI AID is a unique identifier derived from the -inception event of a KERI identifier. The inception event is the first item in the identifier's [[ref: KEL]]. -The algorithm used to generate the AID depends on -the type of AID. If the AID is transferable (supports key rotation) then the AID is generated by taking a cryptographic -digest of the inception event of the KEL of the AID. If the AID is non-transferable (does not support key rotation) the -AID is generated by taking a cryptographic digest of the first (and only) public key of the identifier. See the [[ref: KERI Fundamentals]] section for more details. - -After the [[ref: host]] and optional path in a `did:webs` is a -final path component, a colon and the AID. To be compatible with `did:web`, the -AID is "just a path", the final (and perhaps only) path element. The presence of -the required AID as a path element means that a `did:webs` always has a path, -and so the "no path" version of a `did:web` that implicitly uses the -`.well-known` folder is not supported by `did:webs`. Any `did:webs` can be -expressed as a `did:web` but the inverse is not true--a `did:webs` MUST include -an AID. +> This method introduces an important nuance about the target system. In many DID methods, the target system equals a [[ref: verifiable data registry]] — besides publishing data, its security attributes make that data trustworthy. In this DID method, the target system's role is more limited. It is expected to serve data about the DID, and to follow acknowledged cybersecurity best practices to preserve good hygiene. +mechanisms — the integrity checks built into the DID value, and the workings of -### Target System(s) +> The authenticity of data is guaranteed by the DID value itself, in conjunction with a digitally signed data structure called a [[ref: KERI event stream]], which includes for a given AID its [[ref: key event log]] ([[ref:KEL]]) and [[ref: transaction event log]] ([[ref: TEL]]). These trustthe [[ref: KERI event stream]] — are defined by [[ref: KERI]]. -As with `did:web`, this method reads data from whatever web server is referenced -when the [[ref: host]] portion of one of its DID is resolved. In fact, a `did:webs` can be resolved to a [[ref: DID document]] +1. As with `did:web`, this method reads data from whatever web server is referenced +when the [[ref: host]] portion of one of its DID is resolved. +1. In fact, a `did:webs` can be resolved to a [[ref: DID document]] using a simple text transformation to an HTTPS URL in the same way as a -`did:web`. By design, a `did:web` and `did:webs` with the same [[ref: method-specific identifier]] will return the same +`did:web`. +1. By design, a `did:web` and `did:webs` with the same [[ref: method-specific identifier]] will return the same DID document, except for minor differences in the `id`, `controller`, and `alsoKnownAs` top-level properties that pertain to the identifiers themselves. - -However, this method introduces an important nuance about the target system. In -many DID methods, the target system equals a [[ref: verifiable data registry]] — -besides publishing data, its security attributes make that data trustworthy. In -this DID method, the target system's role is more limited. It is expected to -serve data about the DID, and to follow acknowledged cybersecurity best -practices to preserve good hygiene. - -However, the authenticity of data is -guaranteed by the DID value itself, in conjunction with a digitally signed -data structure called a [[ref: KERI event stream]], which includes for a given AID its -[[ref: key event log]] ([[ref: KEL]]) and [[ref: transaction event log]] ([[ref: TEL]]). These trust -mechanisms — the integrity checks built into the DID value, and the workings of -the [[ref: KERI event stream]] — are defined by [[ref: KERI]]. - -As with `did:web`, the location of the [[ref: DID document]] is determined by transforming the DID to an +1. As with `did:web`, the location of the [[ref: DID document]] MUST be determined by transforming the DID to an HTTPS URL as follows: - -- Replace `did:webs` with `https://` -- Replace the "`:`"s in the method-specific identifier with path separators, "'/'"s -- Convert the optional port percent encoding ("`%3A`"`) to a colon if present. -- Append "`/did.json`" to the resulting string. - -A GET on that URL MUST return the DID document. - -The location of the [[ref: KERI event stream]] is determined by transforming the previous URL as follows: - -- Replace the trailing "`/did.json`" with "`/keri.cesr`". - -A GET on that URL MUST return the [[ref: KERI event stream]] for the AID in the `did:webs` identifier. -The [[ref: KERI event stream]] MUST be CESR-formatted (media type of application/cesr) and the KERI events must be verifiable using the KERI rules. - -The following are some example `did:webs` DIDs and their corresponding DID documents and [[ref: KERI event stream]] -URLs, based on the examples from the [DID Web Specification](https://github.com/w3c-ccg/did-method-web/), but with the (faked) AID -`12124313423525` added: - -- `did:webs:w3c-ccg.github.io:12124313423525` - - DID document URL: https://w3c-ccg.github.io/12124313423525/did.json - - [[ref: KERI event stream]] URL: https://w3c-ccg.github.io/12124313423525/keri.cesr -- `did:webs:w3c-ccg.github.io:user:alice:12124313423525` - - DID document URL: https://w3c-ccg.github.io/user/alice/12124313423525/did.json - - [[ref: KERI event stream]] URL: https://w3c-ccg.github.io/user/alice/12124313423525/keri.cesr -- `did:webs:example.com%3A3000:user:alice:12124313423525` - - DID document URL: https://example.com:3000/user/alice/12124313423525/did.json - - [[ref: KERI event stream]] URL: https://example.com:3000/user/alice/12124313423525/keri.cesr - -The `did:web` version of the DIDs are the same (minus the `s`) and point + 1. Replace `did:webs` with `https://` + 1. Replace the "`:`"s in the method-specific identifier with path separators, "'/'"s + 1. Convert the optional port percent encoding ("`%3A`"`) to a colon if present. + 1. Append "`/did.json`" to the resulting string. + +1. A GET on that URL MUST return the DID document. +1. The location of the [[ref: KERI event stream]] is determined by transforming the previous URL as follows: + 1. Replace the trailing "`/did.json`" with "`/keri.cesr`". + 1. A GET on that URL MUST return the [[ref: KERI event stream]] for the AID in the `did:webs` identifier. + 1. The [[ref: KERI event stream]] MUST be CESR-formatted (media type of application/cesr) and the KERI events must be verifiable using the KERI rules. +1. The `did:web` version of the DIDs are the same (minus the `s`) and point to the same `did.json` file, but have no knowledge of the `keri.cesr` file. The set of KERI features needed @@ -122,6 +72,21 @@ KERI mechanisms, _together_, that constitutes this method's verifiable data registry. In short, verifying the DID document by processing the [[ref: 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 [[ref: KERI event stream]] +URLs, based on the examples from the [DID Web Specification](https://github.com/w3c-ccg/did-method-web/), but with the (faked) AID +`12124313423525` added: +- `did:webs:w3c-ccg.github.io:12124313423525` + - DID document URL: https://w3c-ccg.github.io/12124313423525/did.json + - [[ref: KERI event stream]] URL: https://w3c-ccg.github.io/12124313423525/keri.cesr +- `did:webs:w3c-ccg.github.io:user:alice:12124313423525` + - DID document URL: https://w3c-ccg.github.io/user/alice/12124313423525/did.json + - [[ref: KERI event stream]] URL: https://w3c-ccg.github.io/user/alice/12124313423525/keri.cesr +- `did:webs:example.com%3A3000:user:alice:12124313423525` + - DID document URL: https://example.com:3000/user/alice/12124313423525/did.json + - [[ref: KERI event stream]] URL: https://example.com:3000/user/alice/12124313423525/keri.cesr +``` + ### Equivalent Identifiers ::: todo From bdc6f729f4e9a9903d86e28ad778ddb961215b16 Mon Sep 17 00:00:00 2001 From: 2byrds <2byrds@gmail.com> Date: Wed, 17 Jan 2024 16:59:31 -0500 Subject: [PATCH 2/9] started Did Document section separate normative and informative statements Signed-off-by: 2byrds <2byrds@gmail.com> --- spec/diddocuments.md | 116 ++++++++++++++++++------------------------- 1 file changed, 47 insertions(+), 69 deletions(-) diff --git a/spec/diddocuments.md b/spec/diddocuments.md index d94ae8d..e7fe764 100644 --- a/spec/diddocuments.md +++ b/spec/diddocuments.md @@ -1,19 +1,11 @@ ## DID Documents -### Introduction -DID documents in this method are generated or derived from the key state of the -corresponding AID. By processing the [[ref: KERI event stream]] of the AID, the generation algorithm will be reading the AID [[ref: KEL]] (and possibly [[ref: TEL]]) -to produce the DID document. +1. `did:webs` DID documents MUST be generated or derived from the [[ref:Keri event stream]] of the corresponding AID. + 1. Processing the [[ref: KERI event stream]] of the AID, the generation algorithm will be reading the AID [[ref: KEL]] and any anchored [[ref: TELs]] to produce the DID document. +1. `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. +1. 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. -DID documents for this method are pure JSON. They may be processed as JSON-LD by -prepending an `@context` if consumers of the documents wish. - -Hashes, cryptographic keys, and signatures are represented as CESR strings. This -is an approach similar to multibase, making them self-describing and terse. - -### DID Document from KERI Events -The [[ref: KERI event stream]] represents a cryptographic chain -of custody from the [[ref: AID]] itself down to the current set of keys and the cryptographic commitment to the next rotation key(s). The [[ref: KERI event stream]] also contains events that do not alter the [[ref: AID]] key state, but are useful for the DID document, such as the supported [[ref: hosts]], current set of service endpoints, etc. A did:webs resolver produces the DID document by processing the [[ref: KERI event stream]] to determine the current key state. We detail the different events in (KERI event details)[#KERI-event-details] below and show how they change the DID Document. The mapping from [[ref: KERI event stream]] to the properties of the DID Document is the core of the did:webs resolver logic. Understanding the optimal way to update and maintain the [[ref: KERI event stream]] (publish static keri.cesr files, dyanamically generate the keri.cesr resource, etc) is beyond the scope of the spec, but a reference implementation of the resolver that details these techniques is being developed alongside this spec. The important concepts are that the entire [[ref: KERI event stream]] is used to produce and verify the DID document. +> The [[ref: KERI event stream]] represents a cryptographic chain of custody from the [[ref: AID]] itself down to the current set of keys and the cryptographic commitment to the next rotation key(s). The [[ref: KERI event stream]] also contains events that do not alter the [[ref: AID]] key state, but are useful for the DID document, such as the supported [[ref: hosts]], current set of service endpoints, etc. A did:webs resolver produces the DID document by processing the [[ref: KERI event stream]] to determine the current key state. We detail the different events in (KERI event details)[#KERI-event-details] below and show how they change the DID Document. The mapping from [[ref: KERI event stream]] to the properties of the DID Document is the core of the did:webs resolver logic. Understanding the optimal way to update and maintain the [[ref: KERI event stream]] (publish static keri.cesr files, dyanamically generate the keri.cesr resource, etc) is beyond the scope of the spec, but a reference implementation of the resolver that details these techniques is being developed alongside this spec. The important concepts are that the entire [[ref: KERI event stream]] is used to produce and verify the DID document. In KERI the calculated values that result from processing the [[ref: 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: @@ -66,12 +58,9 @@ in the DID document. The following table lists the values from the example KSN In several cases above, the value from the key state is not enough by itself to populate the DID document. The following sections detail the algorithm to follow for each case. -#### DID Subject -The value of the `id` property in the DID document MUST be the `did:webs` DID that is being created or resolved. -It reflects the current combined web location and AID of the identifier. -The value from the `i` field MUST be the value after the last `:` in the -[[ref: method-specific identifier]] ([[ref: MSI]]) of the `did:webs` DID, according to the syntax rules in section -[Method-Specific Identifier](#method-specific-identifier). +### DID Subject +1. The value of the `id` property in the DID document MUST be the `did:webs` DID that is being created or resolved. +1. The value from the `i` field MUST be the value after the last `:` in the [[ref: method-specific identifier]] ([[ref: MSI]]) of the `did:webs` DID, according to the syntax rules in section [Method-Specific Identifier](#method-specific-identifier). ```json { @@ -79,7 +68,7 @@ The value from the `i` field MUST be the value after the last `:` in the } ``` -#### DID Controller +### DID Controller The value of the `controller` property MUST be a single string that is the same as the `id` (the DID Subject). ```json @@ -88,19 +77,17 @@ The value of the `controller` property MUST be a single string that is the same } ``` -#### Also Known As -The `alsoKnownAs` property in the root of the DID document MAY contain any DID that has the same AID, see [[ref: AID controlled identifier]]. -See the [[ref: designated aliases]] section for information on how an AID anchors the `alsoKnownAs` identifiers to their [[ref: KERI event stream]]. +### Also Known As -It is anticipated that implementations of this DID method will serve the `did:webs` and corresponding `did:web` -as an `alsoKnownAs` identifier. Likewise, any implementation of `did:webs` will provide the corresponding `did:keri` as an `alsoKnownAs` identifier. -Finally, the same `did:webs` may be served under -multiple domains at the same time but will only be verifiable if they are listed in the [[ref: designated aliases]] attestation. +1. The `alsoKnownAs` property in the root of the DID document MAY contain any DID that has the same AID. See the [[ref: designated aliases]] section for information on how an AID anchors the `alsoKnownAs` identifiers to their [[ref: KERI event stream]]. +1. `did:webs` DIDs SHOULD serve the `did:webs` and corresponding `did:web`as an `alsoKnownAs` identifier. +1. `did:webs` DIDs SHOULD will provide the corresponding `did:keri` as an `alsoKnownAs` identifier. +1. The same AID MAY be associated with multiple `did:webs` DIDs, each with a different [[ref:host]] and/or path, but with the same AID. +1. `did:webs` are only verifiable if they are listed in the [[ref: designated aliases]] attestation of the AID. +1. For each [[ref: AID controlled identifier]] DID defined above an entry in the `alsoKnownAs` array +in the DID document SHOULD be created. -For each [[ref: AID controlled identifier]] DID defined above an entry in the `alsoKnownAs` array -in the DID document should be created. For the DID -`did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M` the following `alsoKnownAs` -entries could be created: +For the example DID `did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M` the following `alsoKnownAs` entries could be created: ```json { @@ -112,18 +99,16 @@ entries could be created: } ``` -#### Verification Methods +### Verification Methods KERI identifiers express public signing keys as Composable Event Streaming Representation (CESR) encoded strings in the `k` field of establishment events and the key state notice. CESR encoding encapsulates all the information needed to -determine the cryptographic algorithm used to generate the key pair. For each key listed in the array value of the `k` field -a corresponding verification method will be generated in the DID document. The 'type' property in the verification method for each -public key will be determined by the algorithm used to generate the public key. At the time of this writing, KERI currently -supports public key generation for Ed25519, Secp256k1 and Secp256r1 keys, and the protocol allows for others to be added at any time. -We must define the subset of public key algorithms for KERI AIDs that this specification will accept, so we can define mappings to existing verification method types as registered in the DID Specification Registries. As KERI evolves with more algorithms, new verification method types must be registered in the DID Specification Registries and added to this specification. - -The `id` property of the verification method must be a relative DID URL and use the KERI key CESR value as the value of the fragment component, e.g., `"id": "#"`. - -The `controller` property of the verification method must be the value of the `id` property of DID document. (TODO: Does the method spec need to specify this?) +determine the cryptographic algorithm used to generate the key pair. +1. For each key listed in the array value of the `k` field of the KSN, a corresponding verification method SHALL be generated in the DID document. +1. The 'type' property in the verification method for each public key SHALL be determined by the algorithm used to generate the public key. + * At the time of this writing, KERI currently supports public key generation for Ed25519, Secp256k1 and Secp256r1 keys, and the protocol allows for others to be added at any time. +1. Verification method types MUST be registered in the [DID Specification Registries](https://w3c.github.io/did-spec-registries/#verification-method-types) and added to this specification. +1. 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": "#"`. +1. The `controller` property of the verification method MUST be the value of the `id` property of the DID document. For example, the key `DFkI8OSUd9fnmdDM7wz9o6GT_pJIvw1K_S21AKZg4VwK` in the DID document for the AID `EDP1vHcw_wc4M__Fj53-cJaBnZZASd-aMTaSyWEQ-PC2` becomes: @@ -137,8 +122,8 @@ For example, the key `DFkI8OSUd9fnmdDM7wz9o6GT_pJIvw1K_S21AKZg4VwK` in the DID d ] ``` -##### Ed25519 -Ed25519 public keys must be converted to a verification method with a type of `JsonWebKey` and `publicKeyJwk` property whose value is generated by decoding the CESR representation of the public key out of the KEL and into its binary form (minus the leading 'B' or 'D' CESR codes) and generating the corresponding representation of the key in JSON Web Key form. +#### Ed25519 +1. Ed25519 public keys MUST be converted to a verification method with a type of `JsonWebKey` and `publicKeyJwk` property whose value is generated by decoding the CESR representation of the public key out of the KEL and into its binary form (minus the leading 'B' or 'D' CESR codes) and generating the corresponding representation of the key in JSON Web Key form. For example, a KERI AID with only the following inception event in its KEL: @@ -175,8 +160,8 @@ For example, a KERI AID with only the following inception event in its KEL: ] ``` -##### Secp256k1 -Secp256k1 public keys must be converted to a verification method with a type of `JsonWebKey` and `publicKeyJwk` property whose value is generated by decoding the CESR representation of the public key out of the KEL and into its binary form (minus the leading '1AAA' or '1AAB' CESR codes) and generating the corresponding representation of the key in JSON Web Key form. +#### Secp256k1 +1. Secp256k1 public keys MUST be converted to a verification method with a type of `JsonWebKey` and `publicKeyJwk` property whose value is generated by decoding the CESR representation of the public key out of the KEL and into its binary form (minus the leading '1AAA' or '1AAB' CESR codes) and generating the corresponding representation of the key in JSON Web Key form. For example, a KERI AID with only the following inception event in its KEL: @@ -214,25 +199,18 @@ For example, a KERI AID with only the following inception event in its KEL: ] ``` -##### Thresholds -If the current signing keys threshold (the value of the `kt` field) is a string containing a number that is greater than 1, +#### Thresholds +1. If the current signing keys threshold (the value of the `kt` field) is a string containing a number that is greater than 1, or if it is an array containing fractionally weighted thresholds, then in addition to the verification methods generated according to the rules in the previous sections, another verification method -with a type of `ConditionalProof2022` will be generated in the DID document. This verification method type is defined here: -https://w3c-ccg.github.io/verifiable-conditions/ (TODO: add proper references). - -It is constructed according to the following rules: - -* 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": "#"`. - -* The `controller` property of the verification method MUST be the value of the `id` property of the DID document. (Does the method spec need to specify this?) - -* If the value of the `kt` field is a string containing a number that is greater than 1: - - * The `threshold` property of the verification method MUST be the integer value of the `kt` 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 the `k` field in the - key state: - * The relative DID URL corresponding to the key MUST be added to the array value of the `conditionThreshold` property. +with a type of `ConditionalProof2022` MUST be generated in the DID document. This verification method type is defined [here](https://w3c-ccg.github.io/verifiable-conditions/). +1. It is constructed according to the following rules: + 1. The `id` property of the verification method MUST be a relative DID URL and use the AID as the value of the fragment component, e.g., `"id": "#"`. + 1. The `controller` property of the verification method MUST be the value of the `id` property of the DID document. (Does the method spec need to specify this?) + 1. If the value of the `kt` field is a string containing a number that is greater than 1: + 1. The `threshold` property of the verification method MUST be the integer value of the `kt` field in the current key state. + 1. The `conditionThreshold` property of the verification method MUST contain an array. For each key listed in the array value of the `k` field in the key state: + 1. The relative DID URL corresponding to the key MUST be added to the array value of the `conditionThreshold` property. For example, a KERI AID with only the following inception event in its KEL: @@ -387,7 +365,7 @@ For example, a KERI AID with only the following inception event in its KEL: } ``` -#### Verification Relationships +### Verification Relationships 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 and credential issuances. It follows that: @@ -407,17 +385,17 @@ If the value of `kt` > 1 or if the value of `kt` is an array containing fraction References to verification methods in the DID document MUST use the relative form of the identifier, e.g., `"authentication": ["#"]`. -##### Key Agreement +#### Key Agreement There are multiple ways to establish key agreement in KERI. We detail common considerations and techniques: * *BADA-RUN for key agreement:* Normally in KERI we would use [[ref: BADA-RUN]], similar to how we specify endpoints, [[ref: host]] migration info, etc. This would allow the controller to specify any Key Agreement key, without unnecessarily adding KERI events to their [[ref: 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. If the 'k' field references a Ed25519 key, then key agreement could be established using the corresponding x25519 key for Diffie-Helman key exchange. Alternatively 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. * *Key agreement anchored in KEL:* It is always possible to anchor arbitrary data, like a key agreement key, to the KEL. Likely the best mechanism is to anchor an ACDC to a [[ref: TEL]] which is anchored to the KEL. -#### Service Endpoints +### Service Endpoints `did:webs` supports service endpoints, including types declared in the DID Specification Registries, such as [DIDCommMessaging](https://www.w3.org/TR/did-spec-registries/#didcommmessaging). For additional details about the mapping between KERI events and the Service Endpoints in the DID Document, see [Service Endpoint KERI events](#service-endpoint-event-details). 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). -##### KERI Service Endpoints as DID Document Metadata +#### KERI Service Endpoints as DID Document Metadata In KERI, service endpoints are defined by 2 sets of signed data using Best Available Data - Read, Update, Nullify ([[ref: BADA-RUN]]) rules for data processing. The protocol ensures that all data is signed in transport and at rest and versioned to ensure only the latest signed data is available. The two data sets used to define service endpoints are called Location Schemes and Endpoint Role Authorizations and are expressed in KERI `rpy` events. Location Schemes define URLs for any URL scheme that an AID has exposed. For example, the following `rpy` method declares that the AID `EIDJUg2eR8YGZssffpuqQyiXcRVz2_Gw_fcAVWpUMie1` exposes the URL `http://localhost:3902` for scheme `http`: @@ -473,7 +451,7 @@ The current set of endpoint roles in KERI is contained in the following table: |`mailbox` | A component authorized to serve as a store and forward mailbox for the source identifier. This component usually provides a persistent internet connection for AID controllers that are usually off line.| |`agent` | A component authorized to serve as an agent running with persistent internet connection. Provides more funcitonality than a `mailbox`| -###### Defining new service types +##### Defining new service types KERI service endpoints roles beyond `witness` can be defined using Location Scheme and Endpoint Authorization records in KERI. This section will map the current roles in KERI to service `type` values in resulting DID documents and propose a new role in KERI to map to the existing [DIDCommMessaging](https://www.w3.org/TR/did-spec-registries/#didcommmessaging) service type declared in DID Specification Registries. ```json @@ -499,7 +477,7 @@ KERI service endpoints roles beyond `witness` can be defined using Location Sche TODO: Detail the transformation -#### Other Key Commitments +### Other Key Commitments Data structures similar to Location Scheme and Endpoint Authorizations and managed in KERI using [[ref: BADA-RUN]] could be created that would be used for declaring other types of keys, for example encryption keys, etc TODO: Propose new data structures in KERI and Detail the transformation @@ -860,4 +838,4 @@ The resulting DID document based on the [[ref: designated aliases]] attestation ] } } -``` +``` \ No newline at end of file From 35175622242b9063f9ce6138ca41ae7d38b4d245 Mon Sep 17 00:00:00 2001 From: 2byrds <2byrds@gmail.com> Date: Thu, 18 Jan 2024 17:05:11 -0500 Subject: [PATCH 3/9] more Did Document section separate normative and informative statements Signed-off-by: 2byrds <2byrds@gmail.com> --- spec/diddocuments.md | 463 +++++++++++++++++++++---------------------- 1 file changed, 222 insertions(+), 241 deletions(-) diff --git a/spec/diddocuments.md b/spec/diddocuments.md index e7fe764..9e3d009 100644 --- a/spec/diddocuments.md +++ b/spec/diddocuments.md @@ -204,241 +204,231 @@ For example, a KERI AID with only the following inception event in its KEL: or if it is an array containing fractionally weighted thresholds, then in addition to the verification methods generated according to the rules in the previous sections, another verification method with a type of `ConditionalProof2022` MUST be generated in the DID document. This verification method type is defined [here](https://w3c-ccg.github.io/verifiable-conditions/). -1. It is constructed according to the following rules: - 1. The `id` property of the verification method MUST be a relative DID URL and use the AID as the value of the fragment component, e.g., `"id": "#"`. - 1. The `controller` property of the verification method MUST be the value of the `id` property of the DID document. (Does the method spec need to specify this?) - 1. If the value of the `kt` field is a string containing a number that is greater than 1: - 1. The `threshold` property of the verification method MUST be the integer value of the `kt` field in the current key state. - 1. The `conditionThreshold` property of the verification method MUST contain an array. For each key listed in the array value of the `k` field in the key state: - 1. The relative DID URL corresponding to the key MUST be added to the array value of the `conditionThreshold` property. - -For example, a KERI AID with only the following inception event in its KEL: - -```json -{ - "v": "KERI10JSON0001b7_", - "t": "icp", - "d": "Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", - "i": "Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", - "s": "0", - "kt": "2", // Signing Threshold - "k": [ - "1AAAAg299p5IMvuw71HW_TlbzGq5cVOQ7bRbeDuhheF-DPYk", // Secp256k1 Key - "DA-vW9ynSkvOWv5e7idtikLANdS6pGO2IHJy7v0rypvE", // Ed25519 Key - "DLWJrsKIHrrn1Q1jy2oEi8Bmv6aEcwuyIqgngVf2nNwu" // Ed25519 Key - ], -} -``` - -... would result in a DID document with the following verification methods array: - -```json -{ - "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" - } - } - ] -} -``` + 1. It is constructed according to the following rules: + 1. The `id` property of the verification method MUST be a relative DID URL and use the AID as the value of the fragment component, e.g., `"id": "#"`. + 1. The `controller` property of the verification method MUST be the value of the `id` property of the DID document. (Does the method spec need to specify this?) + 1. If the value of the `kt` field is a string containing a number that is greater than 1: + 1. The `threshold` property of the verification method MUST be the integer value of the `kt` field in the current key state. + 1. The `conditionThreshold` property of the verification method MUST contain an array. For each key listed in the array value of the `k` field in the key state: + 1. The relative DID URL corresponding to the key MUST be added to the array value of the `conditionThreshold` property. + 1. If the value of the `kt` field is an array containing fractionally weighted thresholds: + 1. The `threshold` property of the verification method MUST be half of the lowest common denominator (LCD) of all the fractions in the `kt` array. + 1. The `conditionWeightedThreshold` property of the verification method MUST contain an array. For each key listed in the array value of the `k` field in the key state, and for each corresponding fraction listed in the array value of the `kt` field: + 1. A JSON object MUST be added to the array value of the `conditionWeightedThreshold` property. + 1. The JSON object MUST contain a property `condition` whose value is the relative DID URL corresponding to the key. + 1. The JSON object MUST contain a property `weight` whose value is the numerator of the fraction after it has been expanded over the lowest common denominator (LCD) of all the fractions. + + * For example, a KERI AID with only the following inception event in its KEL, and with a `kt` value greater than 1: + + ```json + { + "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 + ], + } + ``` -* If the value of the `kt` field is an array containing fractionally weighted thresholds: + * Results in a DID document with the following verification methods array: - * The `threshold` property of the verification method MUST be half of the lowest common denominator (LCD) of all the fractions - in the `kt` array. - * The `conditionWeightedThreshold` property of the verification method MUST contain an array. For each key listed in the array value of the `k` field in the - key state, and for each corresponding fraction listed in the array value of the `kt` field: - * 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. + ```json + { + "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: + * For example, a KERI AID with only the following inception event in its KEL, and a `kt` containing fractionally weighted thresholds: -```json -{ - "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 - ], -} -``` + ```json + { + "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: + * would result in a DID document with the following verification methods array: -```json -{ - "verificationMethod": [ - { - "id": "#Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", - "type": "ConditionalProof2022", - "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", - "threshold": 12, - "conditionWeightedThreshold": [ + ```json { - "condition": "#1AAAAg299p5IMvuw71HW_TlbzGq5cVOQ7bRbeDuhheF-DPYk", - "weight": 6 - }, - { - "condition": "#DA-vW9ynSkvOWv5e7idtikLANdS6pGO2IHJy7v0rypvE", - "weight": 4 - }, - { - "condition": "#DLWJrsKIHrrn1Q1jy2oEi8Bmv6aEcwuyIqgngVf2nNwu", - "weight": 3 + "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" + } + ] } - ] - }, - { - "id": "#1AAAAg299p5IMvuw71HW_TlbzGq5cVOQ7bRbeDuhheF-DPYk", - "type": "EcdsaSecp256k1VerificationKey2019", - "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", - "publicKeyJwk": { - "crv": "secp256k1", - "x": "NtngWpJUr-rlNNbs0u-Aa8e16OwSJu6UiFf0Rdo1oJ4", - "y": "qN1jKupJlFsPFc1UkWinqljv4YE0mq_Ickwnjgasvmo", - "kty": "EC", - "kid": "WjKgJV7VRw3hmgU6--4v15c0Aewbcvat1BsRFTIqa5Q" - } - }, - { - "id": "#DA-vW9ynSkvOWv5e7idtikLANdS6pGO2IHJy7v0rypvE", - "type": "Ed25519VerificationKey2020", - "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", - "publicKeyMultibase": "zH3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV" - }, - { - "id": "#DLWJrsKIHrrn1Q1jy2oEi8Bmv6aEcwuyIqgngVf2nNwu", - "type": "Ed25519VerificationKey2020", - "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", - "publicKeyMultibase": "zDqYpw38nznAUJeeFdhKBQutRKpyDXeXxxi1HjYUQXLas" - } - ] -} -``` + ``` ### Verification Relationships -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 and credential issuances. It follows that: - -If the value of `kt` == 1: -- For each public key in `k` and its corresponding verification method, two verification relationships MUST be generated - in the DID document. One verification relationship of type `authentication` and one - verification relationship of type `assertionMethod`. The `authentication` verification relationship defines that the - DID controller can authenticate using each key, and the `assertionMethod` verification relationship defines that the DID - controller can express claims using each key. - -If the value of `kt` > 1 or if the value of `kt` is an array containing fractionally weighted thresholds: -- For the verification method of type `ConditionalProof2022` (see section [Thresholds](#thresholds)), two verification relationships MUST be generated - in the DID document. One verification relationship of type `authentication` and one - verification relationship of type `assertionMethod`. The `authentication` verification relationship defines that the - DID controller can authenticate using a combination of multiple keys above the threshold, and the `assertionMethod` verification relationship defines that the DID - controller can express claims using a combination of multiple keys above the threshold. +> 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. -References to verification methods in the DID document MUST use the relative form of the identifier, e.g., `"authentication": ["#"]`. +1. If the value of `kt` == 1: + 1. For each public key in `k` and its corresponding verification method, two verification relationships MUST be generated in the DID document. One verification relationship of type `authentication` and one verification relationship of type `assertionMethod`. The `authentication` verification relationship defines that the DID controller can authenticate using each key, and the `assertionMethod` verification relationship defines that the DID controller can express claims using each key. +1. If the value of `kt` > 1 or if the value of `kt` is an array containing fractionally weighted thresholds: + 1. For the verification method of type `ConditionalProof2022` (see section [Thresholds](#thresholds)), two verification relationships MUST be generated in the DID document. One verification relationship of type `authentication` and one verification relationship of type `assertionMethod`. The `authentication` verification relationship defines that the DID controller can authenticate using a combination of multiple keys above the threshold, and the `assertionMethod` verification relationship defines that the DID controller can express claims using a combination of multiple keys above the threshold. +1. References to verification methods in the DID document MUST use the relative form of the identifier, e.g., `"authentication": ["#"]`. #### Key Agreement There are multiple ways to establish key agreement in KERI. We detail common considerations and techniques: -* *BADA-RUN for key agreement:* Normally in KERI we would use [[ref: BADA-RUN]], similar to how we specify endpoints, [[ref: host]] migration info, etc. This would allow the controller to specify any Key Agreement key, without unnecessarily adding KERI events to their [[ref: 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. If the 'k' field references a Ed25519 key, then key agreement could be established using the corresponding x25519 key for Diffie-Helman key exchange. Alternatively 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. -* *Key agreement anchored in KEL:* It is always possible to anchor arbitrary data, like a key agreement key, to the KEL. Likely the best mechanism is to anchor an ACDC to a [[ref: TEL]] which is anchored to the KEL. - -### Service Endpoints -`did:webs` supports service endpoints, including types declared in the DID Specification Registries, such as [DIDCommMessaging](https://www.w3.org/TR/did-spec-registries/#didcommmessaging). For additional details about the mapping between KERI events and the Service Endpoints in the DID Document, see [Service Endpoint KERI events](#service-endpoint-event-details). It is important to note that DID document service endpoints are different than the KERI service endpoints detailed in [KERI Service Endpoints as DID Document Metadata](#keri-service-endpoints-as-did-document-metadata). +1. If the 'k' field references a Ed25519 key, then key agreement MAY be established using the corresponding x25519 key for Diffie-Helman key exchange. +1. 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 [[ref: BADA-RUN]], similar to how we specify endpoints, [[ref: host]] migration info, etc. This would allow the controller to specify any Key Agreement key, without unnecessarily adding KERI events to their [[ref: 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. +> * Likely the best mechanism is to anchor an ACDC to a [[ref: TEL]] which is anchored to the KEL. -#### KERI Service Endpoints as DID Document Metadata -In KERI, service endpoints are defined by 2 sets of signed data using Best Available Data - Read, Update, Nullify ([[ref: 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. +#### Other Key Commitments +1. Data structures similar to Location Scheme and Endpoint Authorizations and managed in KERI using [[ref: BADA-RUN]] MAY be created and used for declaring other types of keys, for example encryption keys, etc + 1. To support new data structures, propose them in KERI and detail the transformation in the spec. -The two data sets used to define service endpoints are called Location Schemes and Endpoint Role Authorizations and are expressed in KERI `rpy` events. Location Schemes define URLs for any URL scheme that an AID has exposed. For example, the following `rpy` method declares that the AID `EIDJUg2eR8YGZssffpuqQyiXcRVz2_Gw_fcAVWpUMie1` exposes the URL `http://localhost:3902` for scheme `http`: +### Service Endpoints +1. `did:webs` supports service endpoints, including types declared in the DID Specification Registries, such as [DIDCommMessaging](https://www.w3.org/TR/did-spec-registries/#didcommmessaging). For additional details about the mapping between KERI events and the Service Endpoints in the DID Document, see [Service Endpoint KERI events](#service-endpoint-event-details). -```json -{ - "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/" - } - } -``` +> 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). -Endpoint Role Authorizations associate a role for one AID in relation to another AID. Endpoint role authorizations are expressed in KERI `rpy` events with the following structure: +#### KERI Service Endpoints as DID Document Metadata +> In KERI, service endpoints are defined by 2 sets of signed data using Best Available Data - Read, Update, Nullify ([[ref: 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. -```json -{ - "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" +1. The two data sets used to define service endpoints are called Location Schemes and Endpoint Role Authorizations and are expressed in KERI `rpy` events. + 1. Location Schemes define URLs for any URL scheme that an AID has exposed. + * For example, the following `rpy` method declares that the AID `EIDJUg2eR8YGZssffpuqQyiXcRVz2_Gw_fcAVWpUMie1` exposes the URL `http://localhost:3902` for scheme `http`: + ```json + { + "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/" + } + } + ``` +1. Endpoint Role Authorizations associate a role for one AID in relation to another AID. Endpoint role authorizations are expressed in KERI `rpy` events. + * For example, the AID listed in `cid` is the source of the authorization, the `role` is the role and the AID listed in the `eid` field is the target of the authorization. So in this example `EOGL1KGpOnRaZDIB11uZDCkhHs52_MtMXHd7EqUqwtA3` is being authorized as an Agent for `EIDJUg2eR8YGZssffpuqQyiXcRVz2_Gw_fcAVWpUMie1`. + ```json + { + "v": "KERI10JSON000116_", + "t": "rpy", + "d": "EBiVyW6jPOeHX5briFYMQ4CefzqIZHgl-rrcXqj_t9ex", + "dt": "2022-01-20T12:57:59.823350+00:00", + "r": "/end/role/add", + "a": { + "cid": "EIDJUg2eR8YGZssffpuqQyiXcRVz2_Gw_fcAVWpUMie1", + "role": "agent", + "eid": "EOGL1KGpOnRaZDIB11uZDCkhHs52_MtMXHd7EqUqwtA3" + } } -} -``` - -The AID listed in `cid` is the source of the authorization, the `role` is the role and the AID listed in the `eid` field is the target of the authorization. So in this example, `EOGL1KGpOnRaZDIB11uZDCkhHs52_MtMXHd7EqUqwtA3` is being authorized as an Agent for `EIDJUg2eR8YGZssffpuqQyiXcRVz2_Gw_fcAVWpUMie1`. - - - -The current set of endpoint roles in KERI is contained in the following table: + ``` +1. KERI service endpoints roles beyond `witness` SHOULD be defined using Location Scheme and Endpoint Authorization records in KERI. +1. The following table contains the current set of endpoint roles in KERI and maps the current roles in KERI to service `type` values in the resulting DID documentsis: | Role | Description | |:-----|:------------| |`controller` | The association of the key controller of an AID. These are always self-referential. | @@ -451,36 +441,27 @@ The current set of endpoint roles in KERI is contained in the following table: |`mailbox` | A component authorized to serve as a store and forward mailbox for the source identifier. This component usually provides a persistent internet connection for AID controllers that are usually off line.| |`agent` | A component authorized to serve as an agent running with persistent internet connection. Provides more funcitonality than a `mailbox`| -##### Defining new service types -KERI service endpoints roles beyond `witness` can be defined using Location Scheme and Endpoint Authorization records in KERI. This section will map the current roles in KERI to service `type` values in resulting DID documents and propose a new role in KERI to map to the existing [DIDCommMessaging](https://www.w3.org/TR/did-spec-registries/#didcommmessaging) service type declared in DID Specification Registries. - -```json -{ - "service": [ - { - "id":"#Bgoq68HCmYNUDgOz4Skvlu306o_NY-NrYuKAVhk3Zh9c", - "type": "DIDCommMessaging", - "serviceEndpoint": "https://bar.example.com" - } - { - "id":"#BuyRFMideczFZoapylLIyCjSdhtqVb31wZkRKvPfNqkw", - "type": "KERIAgent", - "serviceEndpoint": { - "tcp": "tcp://bar.example.com:5542", - "https": "https://bar.example.com" + * TODO: Detail the transformation with an example, for example: + ```json + { + "service": [ + { + "id":"#Bgoq68HCmYNUDgOz4Skvlu306o_NY-NrYuKAVhk3Zh9c", + "type": "DIDCommMessaging", + "serviceEndpoint": "https://bar.example.com" } - } - ] -} -``` - -TODO: Detail the transformation - - -### Other Key Commitments -Data structures similar to Location Scheme and Endpoint Authorizations and managed in KERI using [[ref: BADA-RUN]] could be created that would be used for declaring other types of keys, for example encryption keys, etc - -TODO: Propose new data structures in KERI and Detail the transformation + { + "id":"#BuyRFMideczFZoapylLIyCjSdhtqVb31wZkRKvPfNqkw", + "type": "KERIAgent", + "serviceEndpoint": { + "tcp": "tcp://bar.example.com:5542", + "https": "https://bar.example.com" + } + } + ] + } + ``` + * TODO: Propose a new role in KERI to map to the existing [DIDCommMessaging](https://www.w3.org/TR/did-spec-registries/#didcommmessaging) service type declared in DID Specification Registries. ### Transformation to `did:web` DID Document From 7319ec0eac592e0afba22aa7cec871eec0f9d561 Mon Sep 17 00:00:00 2001 From: 2byrds <2byrds@gmail.com> Date: Thu, 18 Jan 2024 20:10:39 -0500 Subject: [PATCH 4/9] more Did Document section changes to separate normative and informative statements Signed-off-by: 2byrds <2byrds@gmail.com> --- spec/diddocuments.md | 161 ++++++++++++++++++++++--------------------- 1 file changed, 82 insertions(+), 79 deletions(-) diff --git a/spec/diddocuments.md b/spec/diddocuments.md index 9e3d009..f8b8458 100644 --- a/spec/diddocuments.md +++ b/spec/diddocuments.md @@ -465,89 +465,78 @@ There are multiple ways to establish key agreement in KERI. We detail common con ### Transformation to `did:web` DID Document -The DID document that exists as a resource on a webserver is compatible with the `did:web` DID method and therefore -necessarily different from a `did:webs` DID document with regard to the `id`, `controller`, and `alsoKnownAs` properties. This section -defines a simple transformation algorithm from a `did:webs` DID document to a `did:web` DID document. +The DID document that exists as a resource on a webserver is compatible with the `did:web` DID method and therefore necessarily different from a `did:webs` DID document with regard to the `id`, `controller`, and `alsoKnownAs` properties. +1. To transform the `did:web` form of the DID Document to a `did:webs` the transformation MUST do the following: + 1. In the values of the top-level `id` and `controller` properties of the DID document, replace the `did:webs` prefix string with `did:web`. + 1. In the value of the top-level `alsoKnownAs` property, replace the entry that is now the new value of the `id` property (using `did:web`) with the old value of the `id` property (using `did:webs`). + 1. All other content of the DID document MUST not be modified. -Given a `did:webs` DID document, construct a new `did:web` DID document with the following differences: - -- In the values of the top-level `id` and `controller` properties of the DID document, replace the `did:webs` prefix string with `did:web`. -- In the value of the top-level `alsoKnownAs` property, replace the entry that is now the new value of the `id` property (using `did:web`) - with the old value of the `id` property (using `did:webs`). -- All other content of the DID document is simply copied without modifications. - -This transformation is used during the [Create](#create) DID method operation. - -For example, given the following `did:webs` DID document: -```json -{ - "id": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", - "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", - "alsoKnownAs": [ - "did:web:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", - "did:webs:foo.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", - "did:keri:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M" - ], - ... -} -``` - -The result of the transformation algorithm is the following `did:web` DID document: -```json -{ - "id": "did:web:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", - "controller": "did:web:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", - "alsoKnownAs": [ - "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", - "did:webs:foo.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", - "did:keri:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M" - ], - ... -} -``` + * This transformation is used during the [Create](#create) DID method operation. For example, given the following `did:webs` DID document: + ```json + { + "id": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", + "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", + "alsoKnownAs": [ + "did:web:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", + "did:webs:foo.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", + "did:keri:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M" + ], + ... + } + ``` + The result of the transformation algorithm is the following `did:web` DID document: + ```json + { + "id": "did:web:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", + "controller": "did:web:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", + "alsoKnownAs": [ + "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", + "did:webs:foo.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", + "did:keri:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M" + ], + ... + } + ``` ### Transformation to `did:webs` DID Document This section defines an inverse transformation algorithm from a `did:web` DID document to a `did:webs` DID document. +1. Given a `did:web` DID document, a transformation to a `did:webs` DID document MUST have the following differences: + 1. In the values of the top-level `id` and `controller` properties of the DID document, replace the `did:web` prefix string with `did:webs`. + 1. In the value of the top-level `alsoKnownAs` property, replace the entry that is now the new value of the `id` property (using `did:webs`) with the old value of the `id` property (using `did:web`). + 1. All other content of the DID document MUST not be modificatied. +1. A `did:webs` resolver MUST use this transformation during the [Read (Resolve)](#read-resolve) DID method operation. -Given a `did:web` DID document, construct a new `did:webs` DID document with the following differences: - -- In the values of the top-level `id` and `controller` properties of the DID document, replace the `did:web` prefix string with `did:webs`. -- In the value of the top-level `alsoKnownAs` property, replace the entry that is now the new value of the `id` property (using `did:webs`) - with the old value of the `id` property (using `did:web`). -- All other content of the DID document is simply copied without modifications. - -This transformation is used during the [Read (Resolve)](#read-resolve) DID method operation. - -For example, given the following `did:web` DID document: -```json -{ - "id": "did:web:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", - "controller": "did:web:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", - "alsoKnownAs": [ - "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", - "did:webs:foo.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", - "did:keri:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M" - ], - ... -} -``` - -The result of the transformation algorithm is the following `did:webs` DID document: -```json -{ - "id": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", - "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", - "alsoKnownAs": [ - "did:web:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", - "did:webs:foo.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", - "did:keri:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M" - ], - ... -} -``` + * For example, given the following `did:web` DID document: + ```json + { + "id": "did:web:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", + "controller": "did:web:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", + "alsoKnownAs": [ + "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", + "did:webs:foo.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", + "did:keri:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M" + ], + ... + } + ``` + The result of the transformation algorithm is the following `did:webs` DID document: + ```json + { + "id": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", + "controller": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", + "alsoKnownAs": [ + "did:web:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", + "did:webs:foo.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", + "did:keri:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M" + ], + ... + } + ``` ### Full Example +> This section is non-normative + The following blocks contain full annotated examples of a KERI AID with two events, an inception event and an interaction event, some witnesses, multiple public signing and rotation keys and an Agent with the resulting DID document that an implementation would generate assuming the implementation was running on the `example.com` domain with no unique port and no additional path defined: ```json @@ -739,10 +728,24 @@ Resulting DID document: [DID Document from KERI Events](#did-document-from-keri-events) introduced the core [[ref: 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 [[ref: KERI event stream]] there are two broad types of key state events (KERI parlance is 'establishment events') that can alter the key state of the AID. Any change in key state of the AID will be reflected in the DID document. -If a key state event does not commit to a future set of rotation key hashes, then the AID can't be rotated to new keys in the future (KERI parlance is that the key state of the AID becomes 'non-transferrable'). If a key state event does commit to a future set of rotation key hashes, then any future key state rotation must be to those commitment keys. This foundation of [[ref: pre-rotation]] is post-quantum safe and allows the controller to recover from key compromise. -* [[ref: Inception event]]: The inception event is the first event in the [[ref: KEL]] that establishes the AID. This defines the initial key set and 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 [[ref: KERI event stream]], if there are no rotation events after the inception event, then this is the current key state of the AID and will be reflected in the DID Document as specified in [Verification Methods](#verification-methods) and [Verification Relationships](#verification-relationships). You can learn more about the inception event in the [KERI specification](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#name-basic-terminology) and you can see an [example inception event](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#name-inception-event). To learn about future rotation key commitment, see the sections about [pre-rotation](#pre-rotation) and the [KERI specification section on pre-rotation](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#name-key-pre-rotation-concept) -* [[ref: Rotation event]]: Rotation events come after inception events and can only change the key state to the previously committed to rotation keys and if the controller(s) desires future key rotation (transfer) then the rotation event must commit to a set of future rotation key hashes. When processing the [[ref: KERI event stream]], if there are rotation events after the inception event, then the last rotation event is the current key state of the AID and will be reflected in the DID Document as specified in [Verification Methods](#verification-methods) and [Verification Relationships](#verification-relationships). You can learn more about rotation events in the [KERI specification](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#name-basic-terminology) and you can see an [example rotation event](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#name-rotation-event-message-body). To learn about future rotation key commitment, see the sections about [pre-rotation](#pre-rotation) and the [KERI specification section on pre-rotation](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#name-key-pre-rotation-concept) +1. When processing the [[ref: 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. +1. Any change in key state of the AID MUST be reflected in the DID document. +1. If a key state event does not commit to a future set of rotation key hashes, then the AID can't be rotated to new keys in the future (KERI parlance is that the key state of the AID becomes 'non-transferrable'). +1. 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 [[ref: pre-rotation]] is post-quantum safe and allows the `did:webs` controller to recover from key compromise. +1. The [[ref: Inception event]] MUST be the first event in the [[ref: KEL]] that establishes the AID. + 1. This defines the initial key set + 1. If the controller(s) desire future key rotation (transfer) then the inception event MUST commit to a set of future rotation key hashes. + 1. When processing the [[ref: KERI event stream]], if there are no rotation events after the inception event, then this is the current key state of the AID and will be reflected in the DID Document as specified in [Verification Methods](#verification-methods) and [Verification Relationships](#verification-relationships). +1. [[ref: Rotation events]] MUST come after inception events. +1. If the controller(s) desires future key rotation (transfer) then the rotation event must commit to a set of future rotation key hashes. +1. [[ref: Rotation events]] MUST only change the key state to the previously committed to rotation keys. +1. 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](#verification-methods) and [Verification Relationships](#verification-relationships). + +> You can learn more about the inception event in the [KERI specification](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#name-basic-terminology) and you can see an [example inception event](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#name-inception-event). +> To learn about future rotation key commitment, see the sections about [pre-rotation](#pre-rotation) and the [KERI specification section on pre-rotation](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#name-key-pre-rotation-concept) + +> You can learn more about rotation events in the [KERI specification](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#name-basic-terminology) and you can see an [example rotation event](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#name-rotation-event-message-body). +> To learn about future rotation key commitment, see the sections about [pre-rotation](#pre-rotation) and the [KERI specification section on pre-rotation](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#name-key-pre-rotation-concept) ### Delegation KERI event details This section focuses on delegation relationships between KERI AIDs. [DID Document from KERI Events](#did-document-from-keri-events) introduced the core [[ref: 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](#basic-keri-event-details) provides additional details on the basic types of KERI events and how they relate to the DID document. From 8a99821088653724db8ec759999c408c14378fe1 Mon Sep 17 00:00:00 2001 From: 2byrds <2byrds@gmail.com> Date: Mon, 22 Jan 2024 15:01:51 -0500 Subject: [PATCH 5/9] Updated handles to normative references Signed-off-by: 2byrds <2byrds@gmail.com> --- spec/appendix.md | 28 ++++++++++++++-------------- spec/core.md | 7 ++++++- spec/diddocuments.md | 25 +++++++++++++------------ spec/didparameters.md | 4 ++-- spec/keri.md | 6 +++--- spec/normative_references.md | 32 +++++++++++++++++++++++--------- spec/security_considerations.md | 8 ++++---- 7 files changed, 65 insertions(+), 45 deletions(-) diff --git a/spec/appendix.md b/spec/appendix.md index b851966..b43139f 100644 --- a/spec/appendix.md +++ b/spec/appendix.md @@ -25,13 +25,13 @@ See also: decentralized identifier, [ref: self-certifying identifier (SCID)]. ~ Any identifier, including `did:webs` DIDs, that have the same AID are by definition referencing the same identity. As defined by [KERI]() TODO: Add link to KERI documentation here. [[def: authentic chained data container (ACDC), ACDC, ACDCs]] -~ a variant of [the Verifiable Credential (VC) specification](https://www.w3.org/TR/vc-data-model/) that inherits the security model derived from [[ref: KERI]], as defined by the [draft ACDC specification](https://trustoverip.github.io/tswg-acdc-specification/draft-ssmith-acdc.html). See [WebOfTrust glossary](https://weboftrust.github.io/WOT-terms/docs/glossary/authentic-chained-data-container) for more detail. +~ a variant of [[ref: the Verifiable Credential (VC) specification]] that inherits the security model derived from [[ref: KERI]], as defined by the [[ref: ACDC specification]]. See [WebOfTrust glossary](https://weboftrust.github.io/WOT-terms/docs/glossary/authentic-chained-data-container) for more detail. [[def: autonomic identifier (AID), AID, AIDs]] -~ A [[ref: self-certifying identifier (SCID)]] that is cryptographically bound cryptographically bound to a [[ref: key event log]] ([[ref: KEL]]), as defined by the [draft KERI specification](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#name-autonomic-identifier-aid). 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 [[ref: pre-rotation]] mechanism that enables the AID to persist in spite of the evolution of its key state. See [WebOfTrust glossary](https://weboftrust.github.io/WOT-terms/docs/glossary/autonomic-identifier) for more detail. +~ A [[ref: self-certifying identifier (SCID)]] that is cryptographically bound cryptographically bound to a [[ref: key event log]] ([[ref: KEL]]), as defined by the [[ref: 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 [[ref: pre-rotation]] mechanism that enables the AID to persist in spite of the evolution of its key state. See [WebOfTrust glossary](https://weboftrust.github.io/WOT-terms/docs/glossary/autonomic-identifier) for more detail. [[def: compact event streaming representation (CESR), CESR]] -~ An encoding format that enables round-trip text-binary conversion of concatenated cryptographic primitives and general data types, as defined by the [draft CESR specification](https://trustoverip.github.io/tswg-cesr-specification/draft-ssmith-cesr.html) and [draft CESR Proof Signature specification](https://trustoverip.github.io/tswg-cesr-proof-specification/draft-pfeairheller-cesr-proof.html). See [WebOfTrust glossary](https://weboftrust.github.io/WOT-terms/docs/glossary/composable-event-streaming-representation) for more detail. +~ An encoding format that enables round-trip text-binary conversion of concatenated cryptographic primitives and general data types, as defined by the [[ref: CESR specification]] and [[ref: CESR Proof Signature specification]]. See [WebOfTrust glossary](https://weboftrust.github.io/WOT-terms/docs/glossary/composable-event-streaming-representation) for more detail. [[def: controller, constrollers]] ~ A controlling entity that can cryptographically prove the control authority (signing and rotation) over an [[ref: AID]] as well as make changes on the associated [[ref: KEL]]. A controller may consist of multiple controlling entities in a multi-signature scheme. See [WebOfTrust glossary](https://weboftrust.github.io/WOT-terms/docs/glossary/controller) for more detail. @@ -52,28 +52,28 @@ See also: decentralized identifier, [ref: self-certifying identifier (SCID)]. ~ 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. [[def: inception event, inception events]] -~ A key event that provides the incepting information needed to derive an [[ref: AID]] and establish its initial [[ref: key state]], as defined by the [draft KERI specification](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#section-2). See [WebOfTrust glossary](https://weboftrust.github.io/WOT-terms/docs/glossary/inception-event) for more detail. +~ A key event that provides the incepting information needed to derive an [[ref: AID]] and establish its initial [[ref: key state]], as defined by the [[ref: KERI specification]]. See [WebOfTrust glossary](https://weboftrust.github.io/WOT-terms/docs/glossary/inception-event) for more detail. [[def: indirect mode]] ~ An operational mode of the [[ref: KERI]] protocol where the [[ref: KEL]] of an [[ref: AID]] is discovered by a [[ref: verifier]] via [[ref: witnesses]], as defined by the [KERI whitepaper](https://github.com/SmithSamuelM/Papers/blob/master/whitepapers/KERI_WP_2.x.web.pdf). See [WebOfTrust glossary](https://weboftrust.github.io/WOT-terms/docs/glossary/indirect-mode) for more detail. [[def: interaction event, interaction events]] -~ A key event that anchors external data to an [[ref: AID]], as defined by the [draft KERI specification](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#section-2). An interaction event does not change the [[ref: key state]] of the [[ref: AID]]. See [WebOfTrust glossary](https://weboftrust.github.io/WOT-terms/docs/glossary/interaction-event) for more detail. +~ A key event that anchors external data to an [[ref: AID]], as defined by the [[ref: KERI specification]]. An interaction event does not change the [[ref: key state]] of the [[ref: AID]]. See [WebOfTrust glossary](https://weboftrust.github.io/WOT-terms/docs/glossary/interaction-event) for more detail. [[def: key event, key events]] -~ A serialized data structure of an entry in the [[ref: key event log]]([[ref: KEL]]) for an [[ref: AID]], as defined by the [draft KERI specification](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#section-2). There are three types of key events, namely [[ref: inception event]], [[ref: rotation event]], and [[ref: interaction event]]. See [WebOfTrust glossary](https://weboftrust.github.io/WOT-terms/docs/glossary/key-event) for more detail. +~ A serialized data structure of an entry in the [[ref: key event log]]([[ref: KEL]]) for an [[ref: AID]], as defined by the [[ref: KERI specification]]. There are three types of key events, namely [[ref: inception event]], [[ref: rotation event]], and [[ref: interaction event]]. See [WebOfTrust glossary](https://weboftrust.github.io/WOT-terms/docs/glossary/key-event) for more detail. [[def: key event log (KEL), KEL, KELs]] -~ A verifiable append-only log of [[ref: key events]] for an [[ref: AID]] that is both backward and forward-chained, as defined by the [draft KERI specification](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#section-2). See [WebOfTrust glossary](https://weboftrust.github.io/WOT-terms/docs/glossary/key-event-log) for more detail. +~ A verifiable append-only log of [[ref: key events]] for an [[ref: AID]] that is both backward and forward-chained, as defined by the [[ref: KERI specification]]. See [WebOfTrust glossary](https://weboftrust.github.io/WOT-terms/docs/glossary/key-event-log) for more detail. [[def: key event receipt]] -~ A message whose body references a [[ref: key event]] of an [[ref: AID]] and includes one or more signatures on that key event, as defined by the [draft KERI specification](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#section-2). See [WebOfTrust glossary](https://weboftrust.github.io/WOT-terms/docs/glossary/key-event-receipt) for more detail. +~ A message whose body references a [[ref: key event]] of an [[ref: AID]] and includes one or more signatures on that key event, as defined by the [[ref: KERI specification]]. See [WebOfTrust glossary](https://weboftrust.github.io/WOT-terms/docs/glossary/key-event-receipt) for more detail. [[def: key event receipt log (KERL), KERL]] -~ A verifiable append-only log that includes all the consistent [[ref: key event receipt]] messages, as defined by the [draft KERI specification](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#section-2). See [WebOfTrust glossary](https://weboftrust.github.io/WOT-terms/docs/glossary/key-event-receipt-log) for more detail. +~ A verifiable append-only log that includes all the consistent [[ref: key event receipt]] messages, as defined by the [[ref: KERI specification]]. See [WebOfTrust glossary](https://weboftrust.github.io/WOT-terms/docs/glossary/key-event-receipt-log) for more detail. [[def: key event receipt infrastructure (KERI), KERI]] -~ A protocol that provides an identity system-based secure overlay for the internet and uses [[ref: AIDs]] as the primary roots of trust, as defined by the [draft KERI specification](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html). See [WebOfTrust glossary](https://weboftrust.github.io/WOT-terms/docs/glossary/key-event-receipt-infrastructure) for more detail. +~ A protocol that provides an identity system-based secure overlay for the internet and uses [[ref: AIDs]] as the primary roots of trust, as defined by the [[ref: KERI specification]]. See [WebOfTrust glossary](https://weboftrust.github.io/WOT-terms/docs/glossary/key-event-receipt-infrastructure) for more detail. [[def: KERI event stream, KERI event streams]] ~ A stream of verifiable KERI data, consisting of the [[ref: key event log]] ([[ref: KEL]]) and other data such as a [[ref: transaction event log]] ([[ref: TEL]]). This data is a [[ref: CESR]] event stream (TODO: link to IANA application/cesr media type) and may be serialized in a file using [[ref: CESR]] encoding. We refer to these CESR stream resources as KERI event streams to simplify the vocabulary. See [WebOfTrust glossary](https://weboftrust.github.io/WOT-terms/docs/glossary/keri-event-stream) for more detail. @@ -85,16 +85,16 @@ See also: decentralized identifier, [ref: self-certifying identifier (SCID)]. ~ The `method-specific-id` part of DID Syntax, as defined in [DID Core](https://www.w3.org/TR/did-core/#did-syntax). See section [Method-Specific Identifier](#method-specific-identifier). [[def: out-of-band introduction (OOBI), OOBI, OOBIs, OOBI specification]] -~ A protocol for discovering verifiable information on an [[ref: AID]] or a [[ref: SAID]], as defined by the [draft OOBI specification](https://trustoverip.github.io/tswg-oobi-specification/draft-ssmith-oobi.html). The OOBI by itself is insecure, and the information discovered by the OOBI must be verified. See [WebOfTrust glossary](https://weboftrust.github.io/WOT-terms/docs/glossary/out-of-band-introduction) for more detail. +~ A protocol for discovering verifiable information on an [[ref: AID]] or a [[ref: SAID]], as defined by the [[ref: KERI specification]]. The OOBI by itself is insecure, and the information discovered by the OOBI must be verified. See [WebOfTrust glossary](https://weboftrust.github.io/WOT-terms/docs/glossary/out-of-band-introduction) for more detail. [[def: pre-rotation, pre-rotated]] -~ A key rotation mechanism whereby a set of rotation keys are pre-commited using cryptographic digests, as defined by the [draft KERI specification](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#section-2). See [WebOfTrust glossary](https://weboftrust.github.io/WOT-terms/docs/glossary/pre-rotation) for more detail. +~ A key rotation mechanism whereby a set of rotation keys are pre-commited using cryptographic digests, as defined by the [[ref: KERI specification]]. See [WebOfTrust glossary](https://weboftrust.github.io/WOT-terms/docs/glossary/pre-rotation) for more detail. [[def: rotation event, rotation events]] -~ A key event that provides the information needed to change the [[ref: key state]] for an [[ref: AID]] using [[ref: pre-rotation]], as defined by the [draft KERI specification](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#section-2). See [WebOfTrust glossary](https://weboftrust.github.io/WOT-terms/docs/glossary/rotation-event) for more detail. +~ A key event that provides the information needed to change the [[ref: key state]] for an [[ref: AID]] using [[ref: pre-rotation]], as defined by the [[ref: KERI specification]]. See [WebOfTrust glossary](https://weboftrust.github.io/WOT-terms/docs/glossary/rotation-event) for more detail. [[def: self-addressing identifier (SAID), SAID, SAIDs]] -~ An identifier that is uniquely and cryptographically bound to a serialization of data (content-addressable) while also being included as a component in that serialization (self-referential), as defined by the [draft SAID specification](https://trustoverip.github.io/tswg-said-specification/draft-ssmith-said.html). See [WebOfTrust glossary](https://weboftrust.github.io/WOT-terms/docs/glossary/self-addressing-identifier) for more detail. +~ 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 [[ref: CESR specification]]. See [WebOfTrust glossary](https://weboftrust.github.io/WOT-terms/docs/glossary/self-addressing-identifier) for more detail. [[def: transaction event log (TEL), TEL, TELs]] ~ A verifiable append-only log of transaction data that are cryptographically anchored to a [[ref: KEL]]. The transaction events of a TEL may be used to establish the issuance or revocation state of [[ref: ACDCs]]. See [WebOfTrust glossary](https://weboftrust.github.io/WOT-terms/docs/glossary/transaction-event-log) for more detail. diff --git a/spec/core.md b/spec/core.md index 8174ef4..61e2d4e 100644 --- a/spec/core.md +++ b/spec/core.md @@ -53,11 +53,16 @@ DID document, except for minor differences in the `id`, `controller`, and `alsoK > 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](#keri-fundamentals) section of this specification. This specification assumes a working knowledge of the concepts there. The inclusion of KERI in `did:webs` enables a number of capabilities for securing a `did:webs` identifier, including multi-signature support and the creation of [[ref: pre-rotated]] keys to prevent loss of control of the identifier if the current private key were to be compromised. +<<<<<<< Updated upstream > 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 [[ref: KERI event stream]] using KERI puts the "s" of "security" in `did:webs`. +======= +A GET on that URL MUST return the [[ref: KERI event stream]] for the AID in the `did:webs` identifier. +The [[ref: KERI event stream]] MUST be [[ref: CESR]]-formatted (media type of application/cesr) and the KERI events must be verifiable using the KERI rules. +>>>>>>> Stashed changes ``` The following are some example `did:webs` DIDs and their corresponding DID documents and [[ref: KERI event stream]] -URLs, based on the examples from the [DID Web Specification](https://github.com/w3c-ccg/did-method-web/), but with the (faked) AID +URLs, based on the examples from the [[ref: did:web Specification]], but with the (faked) AID `12124313423525` added: - `did:webs:w3c-ccg.github.io:12124313423525` - DID document URL: https://w3c-ccg.github.io/12124313423525/did.json diff --git a/spec/diddocuments.md b/spec/diddocuments.md index f8b8458..ff1248b 100644 --- a/spec/diddocuments.md +++ b/spec/diddocuments.md @@ -3,8 +3,9 @@ 1. `did:webs` DID documents MUST be generated or derived from the [[ref:Keri event stream]] of the corresponding AID. 1. Processing the [[ref: KERI event stream]] of the AID, the generation algorithm will be reading the AID [[ref: KEL]] and any anchored [[ref: TELs]] to produce the DID document. 1. `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. -1. 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. +1. All hashes, cryptographic keys, and signatures MUST be represented as [[ref: CESR]] strings. This is an approach similar to multibase, making them self-describing and terse. +> The [[ref: KERI event stream]] represents a cryptographic chain of custody from the [[ref: AID]] itself down to the current set of keys and the cryptographic commitment to the next rotation key(s). The [[ref: KERI event stream]] also contains events that do not alter the [[ref: AID]] key state, but are useful for the DID document, such as the supported [[ref: hosts]], current set of service endpoints, etc. A did:webs resolver produces the DID document by processing the [[ref: KERI event stream]] to determine the current key state. We detail the different events in (KERI event details)[#KERI-event-details] below and show how they change the DID Document. The mapping from [[ref: KERI event stream]] to the properties of the DID Document is the core of the did:webs resolver logic. Understanding the optimal way to update and maintain the [[ref: KERI event stream]] (publish static keri.cesr files, dyanamically generate the keri.cesr resource, etc) is beyond the scope of the spec, but a reference implementation of the resolver that details these techniques is being developed alongside this spec. The important concepts are that the entire [[ref: KERI event stream]] is used to produce and verify the DID document. > The [[ref: KERI event stream]] represents a cryptographic chain of custody from the [[ref: AID]] itself down to the current set of keys and the cryptographic commitment to the next rotation key(s). The [[ref: KERI event stream]] also contains events that do not alter the [[ref: AID]] key state, but are useful for the DID document, such as the supported [[ref: hosts]], current set of service endpoints, etc. A did:webs resolver produces the DID document by processing the [[ref: KERI event stream]] to determine the current key state. We detail the different events in (KERI event details)[#KERI-event-details] below and show how they change the DID Document. The mapping from [[ref: KERI event stream]] to the properties of the DID Document is the core of the did:webs resolver logic. Understanding the optimal way to update and maintain the [[ref: KERI event stream]] (publish static keri.cesr files, dyanamically generate the keri.cesr resource, etc) is beyond the scope of the spec, but a reference implementation of the resolver that details these techniques is being developed alongside this spec. The important concepts are that the entire [[ref: KERI event stream]] is used to produce and verify the DID document. In KERI the calculated values that result from processing the [[ref: KERI event stream]] are referred to as the "current key state" and expressed @@ -100,14 +101,14 @@ For the example DID `did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq ``` ### Verification Methods -KERI identifiers express public signing keys as Composable Event Streaming Representation (CESR) encoded strings in the -`k` field of establishment events and the key state notice. CESR encoding encapsulates all the information needed to +KERI identifiers express public signing keys as Composable Event Streaming Representation ([[ref: CESR]]) encoded strings in the +`k` field of establishment events and the key state notice. [[ref: CESR]] encoding encapsulates all the information needed to determine the cryptographic algorithm used to generate the key pair. 1. For each key listed in the array value of the `k` field of the KSN, a corresponding verification method SHALL be generated in the DID document. 1. The 'type' property in the verification method for each public key SHALL be determined by the algorithm used to generate the public key. * At the time of this writing, KERI currently supports public key generation for Ed25519, Secp256k1 and Secp256r1 keys, and the protocol allows for others to be added at any time. 1. Verification method types MUST be registered in the [DID Specification Registries](https://w3c.github.io/did-spec-registries/#verification-method-types) and added to this specification. -1. 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": "#"`. +1. The `id` property of the verification method MUST be a relative DID URL and use the KERI key [[ref: CESR]] value as the value of the fragment component, e.g., `"id": "#"`. 1. The `controller` property of the verification method MUST be the value of the `id` property of the DID document. For example, the key `DFkI8OSUd9fnmdDM7wz9o6GT_pJIvw1K_S21AKZg4VwK` in the DID document for the AID `EDP1vHcw_wc4M__Fj53-cJaBnZZASd-aMTaSyWEQ-PC2` becomes: @@ -123,7 +124,7 @@ For example, the key `DFkI8OSUd9fnmdDM7wz9o6GT_pJIvw1K_S21AKZg4VwK` in the DID d ``` #### Ed25519 -1. Ed25519 public keys MUST be converted to a verification method with a type of `JsonWebKey` and `publicKeyJwk` property whose value is generated by decoding the CESR representation of the public key out of the KEL and into its binary form (minus the leading 'B' or 'D' CESR codes) and generating the corresponding representation of the key in JSON Web Key form. +1. Ed25519 public keys MUST be converted to a verification method with a type of `JsonWebKey` and `publicKeyJwk` property whose value is generated by decoding the [[ref: CESR]] representation of the public key out of the KEL and into its binary form (minus the leading 'B' or 'D' [[ref: 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: @@ -161,7 +162,7 @@ For example, a KERI AID with only the following inception event in its KEL: ``` #### Secp256k1 -1. Secp256k1 public keys MUST be converted to a verification method with a type of `JsonWebKey` and `publicKeyJwk` property whose value is generated by decoding the CESR representation of the public key out of the KEL and into its binary form (minus the leading '1AAA' or '1AAB' CESR codes) and generating the corresponding representation of the key in JSON Web Key form. +1. Secp256k1 public keys MUST be converted to a verification method with a type of `JsonWebKey` and `publicKeyJwk` property whose value is generated by decoding the [[ref: CESR]] representation of the public key out of the KEL and into its binary form (minus the leading '1AAA' or '1AAB' [[ref: 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: @@ -378,7 +379,7 @@ There are multiple ways to establish key agreement in KERI. We detail common con > * *BADA-RUN for key agreement:* Normally in KERI we would use [[ref: BADA-RUN]], similar to how we specify endpoints, [[ref: host]] migration info, etc. This would allow the controller to specify any Key Agreement key, without unnecessarily adding KERI events to their [[ref: 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. -> * Likely the best mechanism is to anchor an ACDC to a [[ref: TEL]] which is anchored to the KEL. +> * Likely the best mechanism is to anchor an [[ref: ACDC]] to a [[ref: TEL]] which is anchored to the KEL. #### Other Key Commitments 1. Data structures similar to Location Scheme and Endpoint Authorizations and managed in KERI using [[ref: BADA-RUN]] MAY be created and used for declaring other types of keys, for example encryption keys, etc @@ -741,11 +742,11 @@ Resulting DID document: 1. [[ref: Rotation events]] MUST only change the key state to the previously committed to rotation keys. 1. 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](#verification-methods) and [Verification Relationships](#verification-relationships). -> You can learn more about the inception event in the [KERI specification](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#name-basic-terminology) and you can see an [example inception event](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#name-inception-event). -> To learn about future rotation key commitment, see the sections about [pre-rotation](#pre-rotation) and the [KERI specification section on pre-rotation](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#name-key-pre-rotation-concept) +> You can learn more about the inception event in the [[ref: KERI specification]] and you can see an example inception event. +> To learn about future rotation key commitment, see the sections about [pre-rotation](#pre-rotation) and the [[ref: KERI specification]]. -> You can learn more about rotation events in the [KERI specification](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#name-basic-terminology) and you can see an [example rotation event](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#name-rotation-event-message-body). -> To learn about future rotation key commitment, see the sections about [pre-rotation](#pre-rotation) and the [KERI specification section on pre-rotation](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#name-key-pre-rotation-concept) +> You can learn more about rotation events in the [[ref:KERI specification]] and you can see an example rotation event. +> To learn about future rotation key commitment, see the sections about [pre-rotation](#pre-rotation) and the [[ref: KERI specification]]. ### Delegation KERI event details This section focuses on delegation relationships between KERI AIDs. [DID Document from KERI Events](#did-document-from-keri-events) introduced the core [[ref: 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](#basic-keri-event-details) provides additional details on the basic types of KERI events and how they relate to the DID document. @@ -765,7 +766,7 @@ If the identifier is a DID then it will be listed in the `alsoKnownAs` property. #### Designated Aliases event details -This is an example [[ref: designated aliases]] ACDC attestation showing two designated aliases: +This is an example [[ref: designated aliases]] [[ref: ACDC]] attestation showing two designated aliases: ```json { "v": "ACDC10JSON000514_", diff --git a/spec/didparameters.md b/spec/didparameters.md index e4c57c7..2700d91 100644 --- a/spec/didparameters.md +++ b/spec/didparameters.md @@ -41,13 +41,13 @@ did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M?transformKeys= #### `CesrKey` and `publicKeyCesr` This specification defines the following extensions to the DID document data model in accordance with the -[DID Spec Registries](https://w3c.github.io/did-spec-registries/): +[[ref: DID Spec Registries]]: * Extension verification method type `CesrKey`: This verification method type can be used in a DID document to express a public key encoded in [[ref: CESR]] format. * Extension verification method property `publicKeyCesr`: This verification method property has a string value -whose content is the CESR representation of a public key. +whose content is the [[ref: CESR]] representation of a public key. The verification method type `CesrKey` can be used as the value of the `transformKeys` DID parameter. diff --git a/spec/keri.md b/spec/keri.md index 8b0c496..9efb3ef 100644 --- a/spec/keri.md +++ b/spec/keri.md @@ -51,9 +51,9 @@ Although _this DID method depends on web technology, KERI itself does not_. It's ### Flexible Serialization -[[ref: KELs]] and [[ref: TELs]] of `did:webs` DIDs (i.e., AIDs) are included in the [[ref: KERI event streams]] for verification of the DID documents. The KERI event streams use [[ref: Composable Event Streaming Representation (CESR)]] for data serialization. Although CESR is a deep subject all by itself, at a high level, it has two essential properties: +[[ref: KELs]] and [[ref: TELs]] of `did:webs` DIDs (i.e., AIDs) are included in the [[ref: KERI event streams]] for verification of the DID documents. The KERI event streams use [[ref: Composable Event Streaming Representation ([[ref: CESR]])]] for data serialization. Although [[ref: 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` versus `publicKeyMultibase` versus other; see [section 5.2 of the DID spec](https://www.w3.org/TR/did-core/#verification-material)). +* **Content in [[ref: CESR]] is self-describing and supports serialization as binary and text**: That is in [[ref: CESR]], _a digital signature on a [[ref: 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 [[ref: CESR]] stream because of the self-describing nature of these individual [[ref: 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` versus `publicKeyMultibase` versus other; see the verification material section of the [[ref: 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. diff --git a/spec/normative_references.md b/spec/normative_references.md index defcc00..11f7187 100644 --- a/spec/normative_references.md +++ b/spec/normative_references.md @@ -3,12 +3,26 @@ ### Normative References -* [Trust over IP - Authentic Chained Data Containers (ACDC) specification](https://trustoverip.github.io/tswg-acdc-specification/draft-ssmith-acdc.html) -* [Trust over IP - Composable Event Streaming Representation (CESR)](https://trustoverip.github.io/tswg-cesr-specification/draft-ssmith-cesr.html) -* [Trust over IP - CESR Proof Signatures](https://trustoverip.github.io/tswg-cesr-proof-specification/draft-pfeairheller-cesr-proof.html) -* [Trust over IP - Issuance and Presentation Exchange (IPEX) Protocol](https://trustoverip.github.io/tswg-ipex-specification/draft-ssmith-ipex.html) -* [Trust over IP - Key Event Receipt Infrastructure (KERI)](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html) -* [Trust over IP - Out-of-Band-Introduction (OOBI) Protocol](https://trustoverip.github.io/tswg-oobi-specification/draft-ssmith-oobi.html) -* [W3C - did:web Method Specification](https://w3c-ccg.github.io/did-method-web/) -* [W3C - Decentralized Identifiers (DIDs)](https://www.w3.org/TR/did-core/) -* [W3C - Verifiable Credentials Data Model (VCDM)](https://www.w3.org/TR/vc-data-model/) \ No newline at end of file +[[def: Trust over IP - Authentic Chained Data Containers (ACDC) specification, ACDC specification, ACDC protocol]] +~ The [ACDC specification](https://trustoverip.github.io/tswg-acdc-specification/) details the core ACDC specification including the Issuance and Presentation Exchange (IPEX) Protocol and Public Transaction Event Log (PTEL) specification. + +[[def: Trust over IP - Composable Event Streaming Representation (CESR), CESR specification, CESR protocol]] +~ The [CESR specification](https://trustoverip.github.io/tswg-cesr-specification/) details the core CESR protocol including the Self-Addressing IDentifier (SAID) specification. + +[[def: Trust over IP - CESR Proof Signatures, CESR proof specification, CESR proof signatures, CESR proof protocol]] +~ The [CESR Proof Signatures specification](https://trustoverip.github.io/tswg-cesr-proof-specification/draft-pfeairheller-cesr-proof.html) details the core CESR Proof Signatures. + +[[def: Trust over IP - Key Event Receipt Infrastructure (KERI), KERI specification, KERI specification, KERI protocol]] +~ The [KERI specification](https://trustoverip.github.io/tswg-keri-specification/) details the core Key Event Receipt Infrastructure (KERI) protocol. This includes the Out-of-Band-Introduction (OOBI) specification. + +[[def: W3C - did:web Method Specification, did:web specification, did:web method]] +~ The [did:web specification](https://w3c-ccg.github.io/did-method-web/) details the did:web method specification. + +[[def: W3C - Decentralized Identifiers (DIDs), did specification]] +~ The [DIDs specification](https://w3c.github.io/did-core/) details the core Decentralized Identifiers (DIDs) specification. + +[[def: W3C - DID spec registries, DID spec registries, DID registry]] +~ The [DID Spec Registries](https://w3c.github.io/did-spec-registries/) detail the specs for each registred DID method. + +[[def: W3C - Verifiable Credentials Data Model (VCDM), vcdm specification]] +~ The [W3C - Verifiable Credentials Data Model (VCDM)](https://www.w3.org/TR/vc-data-model/) details the the core Verifiable Credentials Data Model (VCDM) specification. diff --git a/spec/security_considerations.md b/spec/security_considerations.md index bd31351..f150166 100644 --- a/spec/security_considerations.md +++ b/spec/security_considerations.md @@ -92,7 +92,7 @@ Albeit weaker than KEL backing, BADA is a significant performance and security i In [[ref: BADA-RUN]], the RUN stands for Read, Update, Nullify and is a replacement for CRUD in an API. CRUD does not protect from replay attacks on the data-state because a delete erases any record of last seen which destroys the monotonicity of the (date-time, key state) tuple. Likewise Create makes no sense because the API host cannot create a record only the remote client can. Moreover, the function of a secure BADA Update must account for both first seen and last seen so a Create verb would be entirely superflous. Nullify deactivates a record without losing the monotonicy of update guarantee. RUN provides the appropriate verbs for any API that applies the security guarantees of a BADA policy to the data-state of its records. -[Learn more about BADA-RUN here](https://trustoverip.github.io/tswg-oobi-specification/draft-ssmith-oobi.html#name-bada-best-available-data-ac) +See the [[ref: OOBI specification]] to learn more about BADA-RUN here. #### KRAM: Low Security @@ -128,13 +128,13 @@ Unfortunately, what happens in practice is that users are led into a false sense Lets explore the implications of applying these concepts to various `did:webs` elements. -Using [[ref: 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 [[ref: BADA-RUN]] whereas did:web aliases should not because it could lead to an impersonation attack. We could have a DID document that uses [[ref: 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. +Using [[ref: 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 [[ref: BADA-RUN]] whereas did:web aliases should not because it could lead to an impersonation attack. We could have a DID document that uses [[ref: 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 [[ref: 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 [[ref: 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. +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 [[ref: KEL]] backed data you could even use an [[ref: ACDC]] as a data attestation for that data and the did resolver would become a caching store for [[ref: 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 [[ref: 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 [[ref: 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. +In addition, a DID doc can be a discovery mechanism for an [[ref: ACDC]] caching server by including an index (label: said) of the [[ref: SAIDs]] of the [[ref: ACDCs]] held in the resolvers cache. #### Narrowing the attack surface From da48a1633f2a1f5d72fe97871809196460d7e63f Mon Sep 17 00:00:00 2001 From: 2byrds <2byrds@gmail.com> Date: Tue, 23 Jan 2024 15:07:00 -0500 Subject: [PATCH 6/9] update normative/informative (first pass) of delegated identifier events Signed-off-by: 2byrds <2byrds@gmail.com> --- spec/diddocuments.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/spec/diddocuments.md b/spec/diddocuments.md index 3e83d55..8a77be7 100644 --- a/spec/diddocuments.md +++ b/spec/diddocuments.md @@ -752,17 +752,23 @@ Resulting DID document: This section focuses on delegation relationships between KERI AIDs. [DID Document from KERI Events](#did-document-from-keri-events) introduced the core [[ref: 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](#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 -* Delegated [[ref: inception event]]: Establishes a delegated identifier for which either the delegator or the delegate can end the delegation commitment. All delegation relationships start with a delegated inception event. The KERI specification provides [an example of a delegated inception event](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#name-delegated-inception-event-m). -* Delegated [[ref: rotation event]]: Updates the delegated identifier commitment. Either the delegator or the delegate can end the delegation commitment. Any change to the [[ref: Delegated inception event]] key state or delegated rotation event key state requires a delegated rotation event. The KERI specification provides [an example of a delegated rotation event](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#section-8.2) +1. All delegation relationships MUST start with a delegated inception event. +1. Any change to the [[ref: Delegated inception event]] key state or delegated rotation event key state MUST be the result of a delegated rotation event. + +> Delegated [[ref: inception event]]: Establishes a delegated identifier. Either the delegator or the delegate can end the delegation commitment. + +> Delegated [[ref: rotation event]]: Updates the delegated identifier commitment. Either the delegator or the delegate can end the delegation commitment. + +> See the [[ref: 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 can specify the [[ref: designated aliases]] that will be listed in the `equivalentId` and `alsoKnownAs` properties by issuing a [[ref: designated aliases]] verifiable attestation. -This attestation contains a set of [[ref: AID controlled identifiers]] that the AID controller authorizes. -If the identifier is a `did:webs` identifier then it is truly equivalent and will be listed in the `equivalentId` property. -If the identifier is a DID then it will be listed in the `alsoKnownAs` property. +1. An AID controller SHALL specify the [[ref: designated aliases]] that will be listed in the `equivalentId` and `alsoKnownAs` properties by issuing a [[ref: designated aliases]] verifiable attestation. + 1. This attestation MUST contain a set of [[ref: AID controlled identifiers]] that the AID controller authorizes. + 1. If the identifier is a `did:webs` identifier then it is truly equivalent and MUST be listed in the `equivalentId` property. + 1. If the identifier is a DID then it MUST be listed in the `alsoKnownAs` property. #### Designated Aliases event details @@ -799,7 +805,6 @@ This is an example [[ref: designated aliases]] [[ref: ACDC]] attestation showing } } ``` - The resulting DID document based on the [[ref: designated aliases]] attestation above, contains: * An `equivalentId` metadata for the did:webs:foo.com identifier * Three `alsoKnownAs` identifiers: From 17aab3f97ba6ace62a01b6db7e305238d1270d00 Mon Sep 17 00:00:00 2001 From: 2byrds <2byrds@gmail.com> Date: Tue, 23 Jan 2024 16:01:26 -0500 Subject: [PATCH 7/9] another pass at Normative separation from informative Signed-off-by: 2byrds <2byrds@gmail.com> --- spec/diddocuments.md | 185 +++++++++++++++++++++---------------------- 1 file changed, 92 insertions(+), 93 deletions(-) diff --git a/spec/diddocuments.md b/spec/diddocuments.md index 8a77be7..94ea666 100644 --- a/spec/diddocuments.md +++ b/spec/diddocuments.md @@ -81,15 +81,13 @@ The value of the `controller` property MUST be a single string that is the same ### Also Known As 1. The `alsoKnownAs` property in the root of the DID document MAY contain any DID that has the same AID. See the [[ref: designated aliases]] section for information on how an AID anchors the `alsoKnownAs` identifiers to their [[ref: KERI event stream]]. -1. `did:webs` DIDs SHOULD serve the `did:webs` and corresponding `did:web`as an `alsoKnownAs` identifier. -1. `did:webs` DIDs SHOULD will provide the corresponding `did:keri` as an `alsoKnownAs` identifier. +1. `did:webs` DIDs MUST serve the `did:webs` and corresponding `did:web`as an `alsoKnownAs` identifier. +1. `did:webs` DIDs MUST provide the corresponding `did:keri` as an `alsoKnownAs` identifier. 1. The same AID MAY be associated with multiple `did:webs` DIDs, each with a different [[ref:host]] and/or path, but with the same AID. -1. `did:webs` are only verifiable if they are listed in the [[ref: designated aliases]] attestation of the AID. -1. For each [[ref: AID controlled identifier]] DID defined above an entry in the `alsoKnownAs` array -in the DID document SHOULD be created. +1. `did:webs` DIDs MUST be listed in the [[ref: designated aliases]] attestation of the AID. +1. For each [[ref: AID controlled identifier]] DID defined above, an entry in the `alsoKnownAs` array in the DID document MUST be created. For the example DID `did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M` the following `alsoKnownAs` entries could be created: - ```json { "alsoKnownAs": [ @@ -101,16 +99,16 @@ For the example DID `did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq ``` ### Verification Methods -KERI identifiers express public signing keys as Composable Event Streaming Representation ([[ref: CESR]]) encoded strings in the -`k` field of establishment events and the key state notice. [[ref: CESR]] encoding encapsulates all the information needed to -determine the cryptographic algorithm used to generate the key pair. -1. For each key listed in the array value of the `k` field of the KSN, a corresponding verification method SHALL be generated in the DID document. -1. The 'type' property in the verification method for each public key SHALL be determined by the algorithm used to generate the public key. - * At the time of this writing, KERI currently supports public key generation for Ed25519, Secp256k1 and Secp256r1 keys, and the protocol allows for others to be added at any time. -1. Verification method types MUST be registered in the [DID Specification Registries](https://w3c.github.io/did-spec-registries/#verification-method-types) and added to this specification. +1. For each key listed in the array value of the `k` field of the KSN, a corresponding verification method MUST be generated in the DID document. +1. The 'type' property in the verification method for each public key MUST be determined by the algorithm used to generate the public key. +1. The verification method types used MUST be registered in the [DID Specification Registries](https://w3c.github.io/did-spec-registries/#verification-method-types) and added to this specification. 1. The `id` property of the verification method MUST be a relative DID URL and use the KERI key [[ref: CESR]] value as the value of the fragment component, e.g., `"id": "#"`. 1. The `controller` property of the verification method MUST be the value of the `id` property of the DID document. +> KERI identifiers express public signing keys as Composable Event Streaming Representation ([[ref: CESR]]) encoded strings in the `k` field of establishment events and the key state notice. [[ref: CESR]] encoding encapsulates all the information needed to determine the cryptographic algorithm used to generate the key pair. + +> At the time of this writing, KERI currently supports public key generation for Ed25519, Secp256k1 and Secp256r1 keys, and the protocol allows for others to be added at any time. + For example, the key `DFkI8OSUd9fnmdDM7wz9o6GT_pJIvw1K_S21AKZg4VwK` in the DID document for the AID `EDP1vHcw_wc4M__Fj53-cJaBnZZASd-aMTaSyWEQ-PC2` becomes: ```json @@ -127,7 +125,6 @@ For example, the key `DFkI8OSUd9fnmdDM7wz9o6GT_pJIvw1K_S21AKZg4VwK` in the DID d 1. Ed25519 public keys MUST be converted to a verification method with a type of `JsonWebKey` and `publicKeyJwk` property whose value is generated by decoding the [[ref: CESR]] representation of the public key out of the KEL and into its binary form (minus the leading 'B' or 'D' [[ref: 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: - ```json { "v": "KERI10JSON0001ad_", @@ -142,9 +139,7 @@ For example, a KERI AID with only the following inception event in its KEL: // ... } ``` - -... would result in a DID document with the following verification methods array: - +would result in a DID document with the following verification methods array: ```json "verificationMethod": [ { @@ -165,7 +160,6 @@ For example, a KERI AID with only the following inception event in its KEL: 1. Secp256k1 public keys MUST be converted to a verification method with a type of `JsonWebKey` and `publicKeyJwk` property whose value is generated by decoding the [[ref: CESR]] representation of the public key out of the KEL and into its binary form (minus the leading '1AAA' or '1AAB' [[ref: 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: - ```json { "v": "KERI10JSON0001ad_", @@ -180,8 +174,7 @@ For example, a KERI AID with only the following inception event in its KEL: // ... } ``` - -... would result in a DID document with the following verification methods array: +would result in a DID document with the following verification methods array: ```json "verificationMethod": [ @@ -201,10 +194,7 @@ For example, a KERI AID with only the following inception event in its KEL: ``` #### Thresholds -1. If the current signing keys threshold (the value of the `kt` field) is a string containing a number that is greater than 1, -or if it is an array containing fractionally weighted thresholds, then in addition to the verification -methods generated according to the rules in the previous sections, another verification method -with a type of `ConditionalProof2022` MUST be generated in the DID document. This verification method type is defined [here](https://w3c-ccg.github.io/verifiable-conditions/). +1. If the current signing keys threshold (the value of the `kt` field) is a string containing a number that is greater than 1, or if it is an array containing fractionally weighted thresholds, then in addition to the verification methods generated according to the rules in the previous sections, another verification method with a type of `ConditionalProof2022` MUST be generated in the DID document. This verification method type is defined [here](https://w3c-ccg.github.io/verifiable-conditions/). 1. It is constructed according to the following rules: 1. The `id` property of the verification method MUST be a relative DID URL and use the AID as the value of the fragment component, e.g., `"id": "#"`. 1. The `controller` property of the verification method MUST be the value of the `id` property of the DID document. (Does the method spec need to specify this?) @@ -219,8 +209,7 @@ with a type of `ConditionalProof2022` MUST be generated in the DID document. Thi 1. The JSON object MUST contain a property `condition` whose value is the relative DID URL corresponding to the key. 1. The JSON object MUST contain a property `weight` whose value is the numerator of the fraction after it has been expanded over the lowest common denominator (LCD) of all the fractions. - * For example, a KERI AID with only the following inception event in its KEL, and with a `kt` value greater than 1: - + For example, a KERI AID with only the following inception event in its KEL, and with a `kt` value greater than 1: ```json { "v": "KERI10JSON0001b7_", @@ -236,9 +225,7 @@ with a type of `ConditionalProof2022` MUST be generated in the DID document. Thi ], } ``` - - * Results in a DID document with the following verification methods array: - + results in a DID document with the following verification methods array: ```json { "verificationMethod": [ @@ -291,8 +278,7 @@ with a type of `ConditionalProof2022` MUST be generated in the DID document. Thi } ``` - * For example, a KERI AID with only the following inception event in its KEL, and a `kt` containing fractionally weighted thresholds: - + For example, a KERI AID with only the following inception event in its KEL, and a `kt` containing fractionally weighted thresholds: ```json { "v": "KERI10JSON0001b7_", @@ -308,8 +294,7 @@ with a type of `ConditionalProof2022` MUST be generated in the DID document. Thi ], } ``` - - * would result in a DID document with the following verification methods array: + would result in a DID document with the following verification methods array: ```json { @@ -363,56 +348,67 @@ with a type of `ConditionalProof2022` MUST be generated in the DID document. Thi ``` ### Verification Relationships -> 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. - 1. If the value of `kt` == 1: - 1. For each public key in `k` and its corresponding verification method, two verification relationships MUST be generated in the DID document. One verification relationship of type `authentication` and one verification relationship of type `assertionMethod`. The `authentication` verification relationship defines that the DID controller can authenticate using each key, and the `assertionMethod` verification relationship defines that the DID controller can express claims using each key. + 1. For each public key in `k` and its corresponding verification method, two verification relationships MUST be generated in the DID document. One verification relationship of type `authentication` and one verification relationship of type `assertionMethod`. + 1. The `authentication` verification relationship defines that the DID controller can authenticate using each key. + 1. The `assertionMethod` verification relationship defines that the DID controller can express claims using each key. 1. If the value of `kt` > 1 or if the value of `kt` is an array containing fractionally weighted thresholds: - 1. For the verification method of type `ConditionalProof2022` (see section [Thresholds](#thresholds)), two verification relationships MUST be generated in the DID document. One verification relationship of type `authentication` and one verification relationship of type `assertionMethod`. The `authentication` verification relationship defines that the DID controller can authenticate using a combination of multiple keys above the threshold, and the `assertionMethod` verification relationship defines that the DID controller can express claims using a combination of multiple keys above the threshold. + 1. For the verification method of type `ConditionalProof2022` (see section [Thresholds](#thresholds)), two verification relationships MUST be generated in the DID document. One verification relationship of type `authentication` and one verification relationship of type `assertionMethod`. + 1. The `authentication` verification relationship defines that the DID controller can authenticate using a combination of multiple keys above the threshold. + 1. The `assertionMethod` verification relationship defines that the DID controller can express claims using a combination of multiple keys above the threshold. 1. References to verification methods in the DID document MUST use the relative form of the identifier, e.g., `"authentication": ["#"]`. +> Private keys of a KERI AID can be used to sign a variety of data. This includes but is not limited to logging into a website, challenge-response exchanges, credential issuances, etc. + #### Key Agreement +This section is non-normative: + There are multiple ways to establish key agreement in KERI. We detail common considerations and techniques: -1. If the 'k' field references a Ed25519 key, then key agreement MAY be established using the corresponding x25519 key for Diffie-Helman key exchange. -1. 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. +* 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 [[ref: BADA-RUN]], similar to how we specify endpoints, [[ref: host]] migration info, etc. This would allow the controller to specify any Key Agreement key, without unnecessarily adding KERI events to their [[ref: 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. -> * Likely the best mechanism is to anchor an [[ref: ACDC]] to a [[ref: TEL]] which is anchored to the KEL. +* *BADA-RUN for key agreement:* Normally in KERI we would use [[ref: BADA-RUN]], similar to how we specify endpoints, [[ref: host]] migration info, etc. This would allow the controller to specify any Key Agreement key, without unnecessarily adding KERI events to their [[ref: 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. + * Likely the best mechanism is to anchor an [[ref: ACDC]] to a [[ref: TEL]] which is anchored to the KEL. #### Other Key Commitments -1. Data structures similar to Location Scheme and Endpoint Authorizations and managed in KERI using [[ref: BADA-RUN]] MAY be created and used for declaring other types of keys, for example encryption keys, etc - 1. To support new data structures, propose them in KERI and detail the transformation in the spec. +This section is non-normative: + +Data structures similar to Location Scheme and Endpoint Authorizations and managed in KERI using [[ref: BADA-RUN]] MAY be created and used for declaring other types of keys, for example encryption keys, etc + +To support new data structures, propose them in KERI and detail the transformation in the spec. ### Service Endpoints -1. `did:webs` supports service endpoints, including types declared in the DID Specification Registries, such as [DIDCommMessaging](https://www.w3.org/TR/did-spec-registries/#didcommmessaging). For additional details about the mapping between KERI events and the Service Endpoints in the DID Document, see [Service Endpoint KERI events](#service-endpoint-event-details). +1. `did:webs` DIDs MUST support service endpoints, including types declared in the DID Specification Registries, such as [DIDCommMessaging](https://www.w3.org/TR/did-spec-registries/#didcommmessaging). + +> For additional details about the mapping between KERI events and the Service Endpoints in the DID Document, see [Service Endpoint KERI events](#service-endpoint-event-details). > 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). #### KERI Service Endpoints as DID Document Metadata -> In KERI, service endpoints are defined by 2 sets of signed data using Best Available Data - Read, Update, Nullify ([[ref: 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. +1. `did:webs` endpoints must be specified using the two data sets KERI uses to define service endpoints; Location Schemes and Endpoint Role Authorizations. + 1. Both MUST be expressed in KERI `rpy` events. + 1. For URL scheme endpoints that an AID has exposed, `did:webs` DIDs MUST use Location Schemes URLs. + 1. For endpoints that relate a role of one AID to another, `did:webs` DIDs MUST use KERI Endpoint Role Authorizations. -1. The two data sets used to define service endpoints are called Location Schemes and Endpoint Role Authorizations and are expressed in KERI `rpy` events. - 1. Location Schemes define URLs for any URL scheme that an AID has exposed. - * For example, the following `rpy` method declares that the AID `EIDJUg2eR8YGZssffpuqQyiXcRVz2_Gw_fcAVWpUMie1` exposes the URL `http://localhost:3902` for scheme `http`: - ```json - { - "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 following `rpy` method declares that the AID `EIDJUg2eR8YGZssffpuqQyiXcRVz2_Gw_fcAVWpUMie1` exposes the URL `http://localhost:3902` for scheme `http`: + ```json + { + "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/" } - ``` -1. Endpoint Role Authorizations associate a role for one AID in relation to another AID. Endpoint role authorizations are expressed in KERI `rpy` events. - * For example, the AID listed in `cid` is the source of the authorization, the `role` is the role and the AID listed in the `eid` field is the target of the authorization. So in this example `EOGL1KGpOnRaZDIB11uZDCkhHs52_MtMXHd7EqUqwtA3` is being authorized as an Agent for `EIDJUg2eR8YGZssffpuqQyiXcRVz2_Gw_fcAVWpUMie1`. + } + ``` + For example, the AID listed in `cid` is the source of the authorization, the `role` is the role and the AID listed in the `eid` field is the target of the authorization. So in this example `EOGL1KGpOnRaZDIB11uZDCkhHs52_MtMXHd7EqUqwtA3` is being authorized as an Agent for `EIDJUg2eR8YGZssffpuqQyiXcRVz2_Gw_fcAVWpUMie1`. ```json { "v": "KERI10JSON000116_", @@ -429,7 +425,8 @@ There are multiple ways to establish key agreement in KERI. We detail common con ``` 1. KERI service endpoints roles beyond `witness` SHOULD be defined using Location Scheme and Endpoint Authorization records in KERI. -1. The following table contains the current set of endpoint roles in KERI and maps the current roles in KERI to service `type` values in the resulting DID documentsis: + +The following table contains the current set of endpoint roles in KERI and maps the current roles in KERI to service `type` values in the resulting DID documentsis: | Role | Description | |:-----|:------------| |`controller` | The association of the key controller of an AID. These are always self-referential. | @@ -442,27 +439,29 @@ There are multiple ways to establish key agreement in KERI. We detail common con |`mailbox` | A component authorized to serve as a store and forward mailbox for the source identifier. This component usually provides a persistent internet connection for AID controllers that are usually off line.| |`agent` | A component authorized to serve as an agent running with persistent internet connection. Provides more funcitonality than a `mailbox`| - * TODO: Detail the transformation with an example, for example: - ```json - { - "service": [ - { - "id":"#Bgoq68HCmYNUDgOz4Skvlu306o_NY-NrYuKAVhk3Zh9c", - "type": "DIDCommMessaging", - "serviceEndpoint": "https://bar.example.com" - } - { - "id":"#BuyRFMideczFZoapylLIyCjSdhtqVb31wZkRKvPfNqkw", - "type": "KERIAgent", - "serviceEndpoint": { - "tcp": "tcp://bar.example.com:5542", - "https": "https://bar.example.com" - } +TODO: Detail the transformation with an example, for example: +```json +{ + "service": [ + { + "id":"#Bgoq68HCmYNUDgOz4Skvlu306o_NY-NrYuKAVhk3Zh9c", + "type": "DIDCommMessaging", + "serviceEndpoint": "https://bar.example.com" + } + { + "id":"#BuyRFMideczFZoapylLIyCjSdhtqVb31wZkRKvPfNqkw", + "type": "KERIAgent", + "serviceEndpoint": { + "tcp": "tcp://bar.example.com:5542", + "https": "https://bar.example.com" } - ] - } - ``` - * TODO: Propose a new role in KERI to map to the existing [DIDCommMessaging](https://www.w3.org/TR/did-spec-registries/#didcommmessaging) service type declared in DID Specification Registries. + } + ] +} +``` +TODO: Propose a new role in KERI to map to the existing [DIDCommMessaging](https://www.w3.org/TR/did-spec-registries/#didcommmessaging) service type declared in DID Specification Registries. + +> In KERI, service endpoints are defined by 2 sets of signed data using Best Available Data - Read, Update, Nullify ([[ref: 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 @@ -472,7 +471,7 @@ The DID document that exists as a resource on a webserver is compatible with the 1. In the value of the top-level `alsoKnownAs` property, replace the entry that is now the new value of the `id` property (using `did:web`) with the old value of the `id` property (using `did:webs`). 1. All other content of the DID document MUST not be modified. - * This transformation is used during the [Create](#create) DID method operation. For example, given the following `did:webs` DID document: + For example, this transformation is used during the [Create](#create) DID method operation, given the following `did:webs` DID document: ```json { "id": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", @@ -485,7 +484,7 @@ The DID document that exists as a resource on a webserver is compatible with the ... } ``` - The result of the transformation algorithm is the following `did:web` DID document: + the result of the transformation algorithm is the following `did:web` DID document: ```json { "id": "did:web:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", @@ -497,18 +496,18 @@ The DID document that exists as a resource on a webserver is compatible with the ], ... } - ``` + ``` ### Transformation to `did:webs` DID Document This section defines an inverse transformation algorithm from a `did:web` DID document to a `did:webs` DID document. 1. Given a `did:web` DID document, a transformation to a `did:webs` DID document MUST have the following differences: - 1. In the values of the top-level `id` and `controller` properties of the DID document, replace the `did:web` prefix string with `did:webs`. - 1. In the value of the top-level `alsoKnownAs` property, replace the entry that is now the new value of the `id` property (using `did:webs`) with the old value of the `id` property (using `did:web`). + 1. The values of the top-level `id` and `controller` properties of the DID document MUST be replaced; the `did:web` prefix string with `did:webs`. + 1. The value of the top-level `alsoKnownAs` property MUST replace the entry that is now the new value of the `id` property (using `did:webs`) with the old value of the `id` property (using `did:web`). 1. All other content of the DID document MUST not be modificatied. 1. A `did:webs` resolver MUST use this transformation during the [Read (Resolve)](#read-resolve) DID method operation. - * For example, given the following `did:web` DID document: + For example, given the following `did:web` DID document: ```json { "id": "did:web:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", @@ -521,7 +520,7 @@ This section defines an inverse transformation algorithm from a `did:web` DID do ... } ``` - The result of the transformation algorithm is the following `did:webs` DID document: + the result of the transformation algorithm is the following `did:webs` DID document: ```json { "id": "did:webs:example.com:Ew-o5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M", From 64ed01ab353fd4d168b3cc7e4f2135b7464cf210 Mon Sep 17 00:00:00 2001 From: 2byrds <2byrds@gmail.com> Date: Tue, 23 Jan 2024 17:01:57 -0500 Subject: [PATCH 8/9] another pass at core Normative separation from informative Signed-off-by: 2byrds <2byrds@gmail.com> --- spec/core.md | 40 ++++++++++++++++++---------------------- 1 file changed, 18 insertions(+), 22 deletions(-) diff --git a/spec/core.md b/spec/core.md index ab8bc56..431fced 100644 --- a/spec/core.md +++ b/spec/core.md @@ -7,7 +7,8 @@ 1. Per the DID specification, this string MUST be lower case. 1. The remainder of the DID, after the prefix, is the case-sensitive [[ref: method-specific identifier]] ([[ref: MSI]]) described [below](#method-specific-identifier). -* > 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. + +> 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 @@ -41,33 +42,26 @@ component of the path. ; ALPHA, DIGIT are standard ABNF primitives for alphabetic and numeric characters ``` -1. The formal rules describing valid [[ref: host]] syntax are described in -[RFC1035], [RFC1123], and [RFC2181]. +1. The formal rules describing valid [[ref: host]] syntax are described in [RFC1035], [RFC1123], and [RFC2181]. 1. A port MAY be included and the colon MUST be percent encoded, like `%3a`, to prevent a conflict with paths. 1. Directories and subdirectories MAY optionally be included, delimited by colons rather than slashes. 1. The KERI AID is a unique identifier and MUST be derived from the inception event of a KERI identifier. + > The inception event is the first item in the identifier's [[ref: KEL]]. The algorithm used to generate the AID depends on the type of AID. If the AID is transferable (supports key rotation) then the AID is generated by taking a cryptographic digest of the inception event of the KEL of the AID. If the AID is non-transferable (does not support key rotation) the AID is generated by taking a cryptographic digest of the first (and only) public key of the identifier. See the [[ref: KERI Fundamentals]] section for more details. > After the [[ref: host]] and optional path in a `did:webs` is a final path component, a colon and the AID. To be compatible with `did:web`, the AID is "just a path", the final (and perhaps only) path element. The presence of the required AID as a path element means that a `did:webs` always has a path,and so the "no path" version of a `did:web` that implicitly uses the `.well-known` folder is not supported by `did:webs`. Any `did:webs` can be expressed as a `did:web` but the inverse is not true--a `did:webs` MUST include an AID. ### Target System(s) - -> This method introduces an important nuance about the target system. In many DID methods, the target system equals a [[ref: verifiable data registry]] — besides publishing data, its security attributes make that data trustworthy. In this DID method, the target system's role is more limited. It is expected to serve data about the DID, and to follow acknowledged cybersecurity best practices to preserve good hygiene. -mechanisms — the integrity checks built into the DID value, and the workings of - -> The authenticity of data is guaranteed by the DID value itself, in conjunction with a digitally signed data structure called a [[ref: KERI event stream]], which includes for a given AID its [[ref: key event log]] ([[ref:KEL]]) and [[ref: transaction event log]] ([[ref: TEL]]). These trustthe [[ref: KERI event stream]] — are defined by [[ref: KERI]]. - -1. As with `did:web`, this method reads data from whatever web server is referenced when the [[ref: host]] portion of one of its DID is resolved. -1. In fact, a `did:webs` can be resolved to a [[ref: DID document]] using a simple text transformation to an HTTPS URL in the same way as a `did:web`. -1. By design, a `did:web` and `did:webs` with the same [[ref: method-specific identifier]] will return the same +1. As with `did:web`, `did:webs` MUST read data from whatever web server is referenced when the [[ref: host]] portion of one of its DID is resolved. +1. A `did:webs` DID MUST resolve to a [[ref: DID document]] using a simple text transformation to an HTTPS URL in the same way as a `did:web` DID. +1. A `did:web` DID and `did:webs` DID with the same [[ref: method-specific identifier]] will return the same DID document, except for minor differences in the `id`, `controller`, and `alsoKnownAs` top-level properties that pertain to the identifiers themselves. 1. As with `did:web`, the location of the [[ref: DID document]] MUST be determined by transforming the DID to an HTTPS URL as follows: 1. Replace `did:webs` with `https://` 1. Replace the "`:`"s in the method-specific identifier with path separators, "'/'"s 1. Convert the optional port percent encoding ("`%3A`"`) to a colon if present. 1. Append "`/did.json`" to the resulting string. - 1. A GET on that URL MUST return the DID document. 1. The location of the [[ref: KERI event stream]] is determined by transforming the previous URL as follows: 1. Replace the trailing "`/did.json`" with "`/keri.cesr`". @@ -96,6 +90,8 @@ URLs, based on the examples from the [[ref: did:web Specification]], but with th ### AID controlled identifiers +This section is non-normative. + > Since an AID is a unique cryptographic identifier that is inseparably bound to the [[ref: KERI event stream]] it is associated with, any AIDs and any `did:webs` DIDs that have the same AID component have the same controller(s). [[ref: AID controlled identifiers]] may vary in how quickly they reflect the current identity information, DID document and [[ref: KERI event stream]]. Notably, as defined in section [Identifiers in a `did:webs` DID document](#identifiers-in-a-didwebs-did-document), the `id` property in the DID document will differ based on the web location of the DID document. As well, different versions of the DID document and [[ref: KERI event stream]] may reside in different locations depending on the replication capabilities of the controlling entity. If the [[ref: KERI event streams]] differ for `did:webs` DIDs with the same AID, the smaller [[ref: KERI event stream]] MUST be a prefix of the larger [[ref: KERI event stream]] (e.g., the only difference in the [[ref: KERI event streams]] being the extra events in one of the [[ref: KERI event streams]], not yet reflected in the other). If the [[ref: KERI event streams]] diverge from one other (e.g., one is not a subset of the other), both the [[ref: KERI event streams]] and the DIDs MUST be considered invalid. @@ -106,16 +102,16 @@ URLs, based on the examples from the [[ref: did:web Specification]], but with th ### Handling Web Redirection 1. A `did:webs` MAY be a "stable" (long-lasting) identifier that can be put into documents such as verifiable credentials, to be useful for a very long time -- generations. -1. When a `did:webs` is updated for another location, its AID SHALL not change. - 1. The same [[ref: KERI event stream]] is used to verify the DID document, with the only change being the designated aliases list reflecting the new location identifier. +1. When a `did:webs` is updated for another location: + 1. Its AID MUST not change. + 1. The same [[ref: 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. 1. If a resolver can find a newly named DID that uses the same AID, and the [[ref: KERI event stream]] verifies the DID, then they have resolved the DID. -The following are the capabilities in `did:webs` to help in the face of resolution uncertainty. - -1. The `did:webs` DID is bound to other [[ref: designated aliases]] DID(s) that are anchored to the [[ref: KERI event stream]]. +The following reslution paths that `did:webs` identfiers SHALL leverage to help in the face of resolution uncertainty: +1. The `did:webs` DID SHALL provide other [[ref: designated aliases]] DID(s) that are anchored to the [[ref: KERI event stream]]. 1. When a `did:webs` is permanently moved to some other location the resolver MAY redirect to any other `equivalentId` [[ref: designated aliases]]. - 1. The `id` in the DID document is set to the new location. - 1. An `equivalentId` entry of the old location SHALL remain for historical purposes and anchored to the [[ref: KERI event stream]] using [[ref: designated aliases]]. See section [Use of `equivalentId`](#use-of-equivalentid) for more details. + 1. The `id` in the DID document MUST be set to the new location. + 1. An `equivalentId` entry of the old location SHOULD remain for historical purposes and anchored to the [[ref: KERI event stream]] using [[ref: designated aliases]]. See section [Use of `equivalentId`](#use-of-equivalentid) for more details. 1. 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 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. @@ -149,7 +145,7 @@ Creating a `did:webs` DID involves the following steps: #### Read (Resolve) -Resolving a `did:webs` DID involves the following steps: +Resolving a `did:webs` DID must follow these steps: 1. Convert the `did:webs` DID back to HTTPS URLs as described in section [Target System(s)](#target-systems). 1. Execute HTTP GET requests on both the URL for the DID document (ending in `/did.json`) and the URL for the [[ref: KERI event stream]] (ending in `/keri.cesr`). 1. Process the [[ref: KERI event stream]] using [KERI Rules] to verify it, then derive the `did:webs` [[ref: DID document]] by processing the [[ref: KERI event stream]] according to section [DID Document from KERI Events](#did-document-from-keri-events). @@ -168,5 +164,5 @@ the [[ref: KERI event stream]]. #### Deactivate 1. To deactivate a `did:webs` DID, A controller SHOULD execute a KERI event that has the effect of rotating the key(s) to null and continue to publish the DID document and [[ref: KERI event stream]]. - 1. Once the deactivation events have been applied, derive the DID document from the [[ref: KERI event stream]] and republish both documents (did.json and keri.cesr) to the web server, overwriting the existing files. + 1. Once the deactivation events have been applied, the controller should regenerate the DID document from the [[ref: KERI event stream]] and republish both documents (did.json and keri.cesr) to the web server, overwriting the existing files. 1. 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. \ No newline at end of file From 3f0636100dcf4e25659f977f17bea9402e672096 Mon Sep 17 00:00:00 2001 From: 2byrds <2byrds@gmail.com> Date: Tue, 23 Jan 2024 18:52:38 -0500 Subject: [PATCH 9/9] fix example formatting Signed-off-by: 2byrds <2byrds@gmail.com> --- spec/core.md | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/spec/core.md b/spec/core.md index 431fced..a942562 100644 --- a/spec/core.md +++ b/spec/core.md @@ -73,20 +73,18 @@ DID document, except for minor differences in the `id`, `controller`, and `alsoK > 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 [[ref: 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 [[ref: KERI event stream]] URLs, based on the examples from the [[ref: did:web Specification]], but with the (faked) AID `12124313423525` added: -- `did:webs:w3c-ccg.github.io:12124313423525` - - DID document URL: https://w3c-ccg.github.io/12124313423525/did.json - - [[ref: KERI event stream]] URL: https://w3c-ccg.github.io/12124313423525/keri.cesr -- `did:webs:w3c-ccg.github.io:user:alice:12124313423525` - - DID document URL: https://w3c-ccg.github.io/user/alice/12124313423525/did.json - - [[ref: KERI event stream]] URL: https://w3c-ccg.github.io/user/alice/12124313423525/keri.cesr -- `did:webs:example.com%3A3000:user:alice:12124313423525` - - DID document URL: https://example.com:3000/user/alice/12124313423525/did.json - - [[ref: KERI event stream]] URL: https://example.com:3000/user/alice/12124313423525/keri.cesr -``` +* `did:webs:w3c-ccg.github.io:12124313423525` + * The DID document URL would look like: `https://w3c-ccg.github.io/12124313423525/did.json` + * [[ref: KERI event stream]] URL would look like: `https://w3c-ccg.github.io/12124313423525/keri.cesr` +* `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` + * [[ref: KERI event stream]] URL would look like: `https://w3c-ccg.github.io/user/alice/12124313423525/keri.cesr` +* `did:webs:example.com%3A3000:user:alice:12124313423525` + * DID document URL would look like: `https://example.com:3000/user/alice/12124313423525/did.json` + * [[ref: KERI event stream]] URL would look like: `https://example.com:3000/user/alice/12124313423525/keri.cesr` ### AID controlled identifiers