From b826172f6c4984be6cb4930c6cbecad94c5a07d8 Mon Sep 17 00:00:00 2001 From: Gabe <7622243+decentralgabe@users.noreply.github.com> Date: Thu, 25 Jul 2024 12:20:41 -0400 Subject: [PATCH] grammar, punctuation, link fixes (#261) --- spec/spec.md | 156 +++++++++++++++++++++++++-------------------------- 1 file changed, 78 insertions(+), 78 deletions(-) diff --git a/spec/spec.md b/spec/spec.md index 61b4f546..a2b79a65 100644 --- a/spec/spec.md +++ b/spec/spec.md @@ -9,7 +9,7 @@ The DID DHT Method Specification 1.0 **Draft Created**: October 20, 2023 -**Last Updated**: May 31, 2024 +**Last Updated**: July 25, 2024 **Editors**: ~ [Gabe Cohen](https://github.com/decentralgabe) @@ -88,7 +88,7 @@ decentralized digital identity_. A DID identifier is associated with a JSON docu services, and other properties outlined in the specification. [[def:DID Suffix, Suffix]] -~ The unique identifier string within a DID URI (e.g. the part after `did:dht:`). For DID DHT the suffix is +~ The unique identifier string within a DID URI (e.g., the part after `did:dht:`). For DID DHT the suffix is the [[ref:z-base-32]] encoded public key portion of the [[ref:Identity Key]]. [[def:Identity Key Pair, Identity Key]] @@ -98,15 +98,15 @@ The public key, also known as the [[ref:Identity Key]] is guaranteed to be prese [[def:DNS Resource Records, DNS Resource Record, DNS Packet]] ~ An efficient format for representing [[ref:DID Documents]] and providing semantics pertinent to DID DHT, -such as TTLs, caching, and different record types (e.g. `NS`, `TXT`). Follows [[spec:RFC1035]]. +such as TTLs, caching, and different record types (e.g., `NS`, `TXT`). Follows [[spec:RFC1035]]. [[def:Mainline DHT, DHT, Mainline, Mainline Server]] ~ [Mainline DHT](https://en.wikipedia.org/wiki/Mainline_DHT) is the name given to the [Distributed Hash Table](https://en.wikipedia.org/wiki/Distributed_hash_table) used by the [BitTorrent protocol](https://github.com/bittorrent/bittorrent.org). It is a distributed system for storing and finding data on a peer-to-peer network. It is based on [Kademlia](https://en.wikipedia.org/wiki/Kademlia) and is -primarily used to store and retrieve peer data. It is estimated to consistently have tens of millions of concurrent -active users. +primarily used to store and retrieve peer data. It is estimated to have tens of millions of concurrent +active users consistently. [[def:Gateway, Gateways, DID DHT, Bitcoin-anchored Gateway, DID DHT Service]] ~ A server that that facilitates [[ref:Mainline]] and DID DHT operations. The gateway may offer a set of @@ -116,7 +116,7 @@ discoverable via a [[ref:Gateway Registry]]. [[def:Gateway Registry, Gateway Registries]] ~ A system used to aid in the discovery of [[ref:Gateways]]. One such system is the -[registry provided by this specification]((registry/index.html#gateways)). +[registry provided by this specification](registry/index.html#gateways). [[def:Republish, Republishing, Republishes]] ~ The action that keeps a record alive in [[ref:Mainline]], which offers a limited duration (approximately 2 hours) @@ -167,21 +167,21 @@ did-dht-format := did:dht:Z-BASE-32(raw-public-key-bytes) ### Identity Key Pair -A unique property of DID DHT is its dependence on an a single non-rotatable key which we refer to as an _Identity Key Pair_, +A unique property of DID DHT is its dependence on a single non-rotatable key, which we refer to as an _Identity Key Pair_, whose public key is referred to as the _Identity Key_. This requirement stems from [[ref:BEP44]], particularly within the section on _Mutable Items_: > Mutable items can be updated, without changing their DHT keys. To authenticate that only the original publisher can update an item, it is signed by a private key generated by the original publisher. The target ID mutable items are -stored under is the SHA-1 hash of the public key (as it appears in the put message). +stored under the SHA-1 hash of the public key (as it appears in the put message). This mechanism, as detailed in [[ref:BEP44]], ensures that all entries in the DHT are authenticated through a private key unique to the initial publisher. Consequently, DHT records, including DID DHT Documents, are _independently verifiable_. This independence implies that trust in a specific [[ref:Mainline]] or [[ref:Gateway]] server for providing unaltered messages is unnecessary. Instead, all clients have the ability to verify messages themselves. This approach significantly mitigates risks associated with other DID methods, where a compromised server or -[DID resolver](https://www.w3.org/TR/did-core/#choosing-did-resolvers) has the ability tamper with a [[ref:DID Document]], -in a manner which could be undetectable by a client. +[DID resolver](https://www.w3.org/TR/did-core/#choosing-did-resolvers) has the ability to tamper with a [[ref:DID Document]], +in a manner that could be undetectable by a client. At present, [[ref:Mainline]] exclusively supports the [[ref:Ed25519]] signature system. In turn, [[ref:Ed25519]]-based keys are required by DID DHT and used to uniquely identify DID DHT Documents. DID DHT identifiers are formed by @@ -218,7 +218,7 @@ The ****RECOMMENDED**** TTL value is 7200 seconds (2 hours), the default TTL for ::: - The [Root Record](#root-record) serves as a "map" to reconstruct a [[ref:DID Document]] from a DNS packet. -This record contains a _version_ number, indicating the version of this specification a given record is created against. +This record contains a _version_ number indicating the version of this specification against which it is created. - Additional records like `svc` (services), `vm` ([Verification Methods](#verification-methods)), and [Verification Relationships](#verification-relationships) (e.g., authentication, assertion, etc.) are @@ -231,7 +231,7 @@ each `key` or `service` as attributes. - The DNS packet ****MUST**** set the _Authoritative Answer_ flag since this is always an _Authoritative_ packet. - `TXT` records ****MAY**** exceed 255 characters as per [[spec:RFC1035]]. Records exceeding 255 characters are -represented as multiple strings, which upon DID Document reconstruction, can be concatenated to a single value. +represented as multiple strings, which can be concatenated to a single value upon DID Document reconstruction. - DNS packets ****MUST**** be compressed as per [[spec:RFC1035]] [section 4.1.4](https://datatracker.ietf.org/doc/html/rfc1035#section-4.1.4) before transmission. @@ -245,19 +245,19 @@ metadata such as a version identifier. - The root record's **name** ****MUST**** be of the form, `_did..`, where `ID` is the [[ref:Mainline]] identifier associated with the DID (i.e. `did:dht:` becomes `_did..`). -- The root record's **type** is `TXT`, indicating a Text record. +- The root record's **type** is `TXT` indicating a Text record. - The root record's **rdata** is represented by the form `v=M;vm=N;auth=O;asm=P;inv=Q;del=R;svc=S` where `M` is the version of the DNS packet representation defined by this specification. `N` is the set -[Verification Method](#verification-methods) identifiers (e.g. `k0,k1`) present in the document, always +[Verification Method](#verification-methods) identifiers (e.g., `k0,k1`) present in the document, always containing at least `k0`. `O`, `P`, `Q`, and `R` contain the set of Verification Method resource -aliases (e.g. `k0`) for each [Verification Relationship](#verification-relationships). `S` contains -the set of Service resource aliases (e.g. `s0`) for each [Service](#services). +aliases (e.g., `k0`) for each [Verification Relationship](#verification-relationships). `S` contains +the set of Service resource aliases (e.g., `s0`) for each [Service](#services). Additionally: - A version number ****MUST**** be present. The version number for this specification version - is **0** (e.g. `v=0`). The version number is not present in the corresponding DID Document. + is **0** (e.g., `v=0`). The version number is not present in the corresponding DID Document. - The `vm` property ****MUST**** always contain _at least_ the [[ref:Identity Key]] represented by `k0`. @@ -275,7 +275,7 @@ Additionally: The following section describes mapping a [[ref:DID Document]] to a DNS packet's **rdata**. -- Resource names are aliased with zero-indexed values (e.g. `k0`, `k1`, `s0`, `s1`). +- Resource names are aliased with zero-indexed values (e.g., `k0`, `k1`, `s0`, `s1`). - Verification Methods, Verification Relationships, and Services are separated by a semicolon (`;`), while values within each property are separated by a comma (`,`). @@ -298,7 +298,7 @@ A [DID controller](https://www.w3.org/TR/did-core/#did-controller) ****MAY**** b - The [Controller](https://www.w3.org/TR/did-core/#did-controller) record's **name** is represented as a `_cnt._did.`. -- The [Controller](https://www.w3.org/TR/did-core/#did-controller) record's **type** is `TXT`, indicating a Text record. +- The [Controller](https://www.w3.org/TR/did-core/#did-controller) record's **type** is `TXT` indicating a Text record. - The [Controller](https://www.w3.org/TR/did-core/#did-controller) record's **data** is represented as a comma-separated list of controller DID identifiers. @@ -318,7 +318,7 @@ A `did:dht` document ****MAY**** have multiple identifiers using the [alsoKnownA - The [Also Known As](https://www.w3.org/TR/did-core/#also-known-as) record's **name** is represented as a `_aka._did.`. -- The [Also Known As](https://www.w3.org/TR/did-core/#also-known-as) record's **type** is `TXT`, indicating a Text record. +- The [Also Known As](https://www.w3.org/TR/did-core/#also-known-as) record's **type** is `TXT` indicating a Text record. - The [Also Known As](https://www.w3.org/TR/did-core/#also-known-as) record's **data** is represented as a comma-separated list of DID identifiers. @@ -332,16 +332,16 @@ comma-separated list of DID identifiers. #### Verification Methods - Each [Verification Method](https://www.w3.org/TR/did-core/#verification-methods) record's **name** is represented -as a `_kN._did.` record where `N` is the zero-indexed positional index of a given Verification Method (e.g. `_k0`, `_k1`). +as a `_kN._did.` record where `N` is the zero-indexed positional index of a given Verification Method (e.g., `_k0`, `_k1`). -- Each [Verification Method]((https://www.w3.org/TR/did-core/#verification-methods)) record's **type** is `TXT`, +- Each [Verification Method](https://www.w3.org/TR/did-core/#verification-methods) record's **type** is `TXT`, indicating a Text record. - Each [Verification Method](https://www.w3.org/TR/did-core/#verification-methods) record's **rdata** is represented by the form `id=M;t=N;k=O;a=P` where `M` is an **optional** Verification Method Identifier, `N` is the index of the key's type from the [key type index](registry/index.html#key-type-index), `O` is the unpadded base64URL [[spec:RFC4648]] representation of the public key, and `P` is the `JWK` `alg` identifier of the key. It is important to note that the value of `O` represents the byte -representation of the public key itself, rather than an encoded JWK. +representation of the public key itself rather than an encoded JWK. - The [[ref:Identity Key]] ****MUST**** always be at index `_k0`. @@ -359,13 +359,13 @@ representation of the public key itself, rather than an encoded JWK. ****MUST**** be present. - [Verification Methods](https://www.w3.org/TR/did-core/#verification-methods) ****MAY**** have an _optional_ **controller** -property represented by `c=C` where `C` is the identifier of the verification method's controller (e.g. `t=N;k=O;c=C`). If +property represented by `c=C` where `C` is the identifier of the verification method's controller (e.g., `t=N;k=O;c=C`). If omitted, it is assumed that the controller of the Verification Method is the [[ref:Identity Key]]. ::: note Controllers are not cryptographically verified by [[ref:Gateways]] or this DID method. This means any DID may choose to list a controller, even if there is no relationship between the identifiers. As such, DID controllers should be interrogated to -assert the veracity of their relations. +assert the integrity of their relations. ::: #### Verification Relationships @@ -401,17 +401,17 @@ represented as a comma-separated list of key references. #### Services - Each [Service](https://www.w3.org/TR/did-core/#services) record's **name** is represented as a `_sN._did.` record where `N` is -the zero-indexed positional index of the Service (e.g. `_s0`, `_s1`). +the zero-indexed positional index of the Service (e.g., `_s0`, `_s1`). -- Each [Service](https://www.w3.org/TR/did-core/#services) record's **type** is `TXT`, indicating a Text record. +- Each [Service](https://www.w3.org/TR/did-core/#services) record's **type** is `TXT` indicating a Text record. - Each [Service](https://www.w3.org/TR/did-core/#services) record's **data** is represented with the form `id=M;t=N;se=O` where `M` is the Service's ID, `N` is the Service's `type` and `O` is the Service's URI. - Multiple service endpoints ****MAY**** be present. If present, they ****MUST**** be represented as an - array (e.g. `id=dwn;t=DecentralizedWebNode;se=https://dwn.org/dwn1,https://dwn.org/dwn2`). + array (e.g., `id=dwn;t=DecentralizedWebNode;se=https://dwn.org/dwn1,https://dwn.org/dwn2`). - - Additional properties ****MAY**** be present (e.g. `id=dwn;t=DecentralizedWebNode;se=https://dwn.org/dwn1;sig=1;enc=2`) if the + - Additional properties ****MAY**** be present (e.g., `id=dwn;t=DecentralizedWebNode;se=https://dwn.org/dwn1;sig=1;enc=2`) if the properties are registered in the [additional properties registry](registry/index.html#additional-properties). **Example Service Record**: @@ -510,7 +510,7 @@ To create a `did:dht` document, the process is as follows: 2. Construct a conformant JSON representation of a [[ref:DID Document]]. a. The document ****MUST**** include a [Verification Method](https://www.w3.org/TR/did-core/#verification-methods) with - the [[ref:Identity Key]]. The `id` property of this Verification Method ****MUST**** be `0` and type of `JsonWebKey` + the [[ref:Identity Key]]. The `id` property of this Verification Method ****MUST**** be `0` and the type of `JsonWebKey` as defined by [[ref:VC-JOSE-COSE]]. The key ****MUST**** be represented as a `publicKeyJwk` as per [[spec:RFC7517]] with a `kid` of `0`. @@ -520,7 +520,7 @@ To create a `did:dht` document, the process is as follows: c. The document can include any number of other [core properties](https://www.w3.org/TR/did-core/#core-properties); always representing key material as a `JWK` as per [[spec:RFC7517]]. In addition to the properties required by the `JWK` specification, the `alg` property ****MUST**** always be present in the DID Document representation. - Default algorithm values are defined per key type in the [indexed types registry](registry/index.html#indexed-types). + The [indexed types registry](registry/index.html#indexed-types) defines default algorithm values per key type. 3. Map the output [[ref:DID Document]] to a DNS packet as outlined in [property mapping](#property-mapping). @@ -536,7 +536,7 @@ To create a `did:dht` document, the process is as follows: in step 1. ::: note -This specification **does not** make use of [JSON-LD](https://json-ld.org/). As such DID DHT Documents ****MUST NOT**** +This specification **does not** make use of [JSON-LD](https://json-ld.org/). As such, DID DHT Documents ****MUST NOT**** include the `@context` property. ::: @@ -560,11 +560,11 @@ To read a `did:dht` document, the process is as follows: i. If an `id` value is provided, use that value as the Verification Method ID and JWK `kid`. - ii. If no `id` value is specified, calculate the key's JWK Thumbprint according to [[spec:RFC7638]] - and use it as the Verification Method ID and JWK `kid`. + ii. If no `id` value is set, the JWK Thumbprint [[spec:RFC7638]] is used as the Verification Method ID + and JWK `kid`. c. Expand all identifiers (i.e. Verification Methods, Services, etc. `id`s ) to their fully-qualified - form (e.g. `did:dht:uodqi99wuzxsz6yx445zxkp8ddwj9q54ocbcg8yifsqru45x63kj#0` + form (e.g., `did:dht:uodqi99wuzxsz6yx445zxkp8ddwj9q54ocbcg8yifsqru45x63kj#0` as opposed to `0` or `#0`, `did:dht:uodqi99wuzxsz6yx445zxkp8ddwj9q54ocbcg8yifsqru45x63kj#service-1` as opposed to `#service-1`). @@ -581,14 +581,14 @@ As a fallback, if a `did:dht` value cannot be resolved via the network, it can b #### Update Any valid [[ref:BEP44]] record written to the DHT is an update. As long as control of the -[[ref:Identity Key]] is retained any update is made possibly by signing and writing records with a unique incremental +[[ref:Identity Key]] is retained any update is made possible by signing and writing records with a unique incremental [[ref:sequence number]] with [mutable items](https://www.bittorrent.org/beps/bep_0044.html). -It is ****RECOMMENDED**** that updates are infrequent — at least every 2 hours — as DHT caching is highly encouraged. +It is ****RECOMMENDED**** that updates be infrequent — at least every 2 hours — as DHT caching is highly encouraged. #### Deactivate -To deactivate a `did:dht` document, controllers have multiple options: +To deactivate a `did:dht` document controllers have multiple options: 1. Let the DHT record expire and cease to publish it. @@ -627,24 +627,24 @@ A `did:dht` Document ****MUST NOT**** have more than **one** _Previous_ record. - The Previous record's **name** is represented as a `_prv._did.` record. -- The Previous record's **type** is `TXT`, indicating a Text record. +- The Previous record's **type** is `TXT` indicating a Text record. - The Previous record's **data** is represented with the form `id=M;s=N` where `M` is the identifier of the previous DID, -and `N` is the the unpadded base64URL signature from step (3) above. +and `N` is the unpadded base64URL signature from step (3) above. | Name | Type | TTL | Rdata | | ---------- | ---- | ----- | -------------------------------------------------------------------------------------- | | _prv._did. | TXT | 7200 | id=did:dht:pxoem5sfzxxxrnrwfgiu5i5wc7epouy1jk9zb7ad159dsxbxy8io;s=ol5LbUydL3_PdChE8tVYH-z_NhyFDQlop0agYtjyYbKz_-CYrj_3JGLiFne1e7PruOwf-b91uEFq9R_PgBn-Bg | -The DID controller ****MAY**** include a statement in the old [[ref:DID Document]] indicating the rotation to the new identifier, +The DID controller ****MAY**** include a statement in the old [[ref:DID Document]] indicating the rotation to the new identifier by setting the [controller property](#controller) to the new DID. Without the previous record present in the new DID's record set, the linkage ****MUST NOT**** be considered legitimate. ### Designating Authoritative Gateways [Gateways](#gateways) provide additional benefits to `did:dht`, such as the ability to -[resolve historical DID Documents](#historical-resolution), or support [type indexing](#type-indexing). To enable the -usage of these additional features, `did:dht` documents need to be published to Gateway(s) that with the necessary +[resolve historical DID Documents](#historical-resolution) or support [type indexing](#type-indexing). To enable +these additional features, `did:dht` documents need to be published to Gateway(s) that with the necessary capabilities. Whether it's accessing historical states, engaging with type indexes, or utilizing other specialized features, the [resolution process](#resolving-a-did) must be directed towards a [[ref:Gateway]] that maintains this supplementary data. @@ -658,7 +658,7 @@ records is outlined as follows: - Each Gateway record's **name** is represented as `_did..` record, where `ID` represents the suffix of the `did:dht` identifier. -- Each Gateway record's **type** is `NS`, indicating a Name Server record. +- Each Gateway record's **type** is `NS` indicating a Name Server record. - Each Gateway record's **data** is represented as a [Fully Qualified Domain Name (FQDN)](https://en.wikipedia.org/wiki/Fully_qualified_domain_name). @@ -670,7 +670,7 @@ records is outlined as follows: ### Type Indexing Type indexing is an **optional** feature that enables DIDs to become **discoverable**, by flagging themselves as being -of a particular type. Types are not included as a part of the DID Document, but rather as part of the DNS packet. This +of a particular type. Types are not included as part of the DID Document, but rather as part of the DNS packet. This allows for DIDs to be indexed by type by [[ref:Gateways]], and for DIDs to be resolved by type. DIDs can be indexed by type by adding a `_typ._did.` record to the DNS packet. A DID ****MAY**** have **at most** one @@ -678,7 +678,7 @@ type index record. This record is of the following format: - The Type Index record's **name** is represented as a `_typ._did.` record. -- The Type Index record's **type** is `TXT`, indicating a Text record. +- The Type Index record's **type** is `TXT` indicating a Text record. - The Type Index record's **data** is represented with the form `id=H,I,J,...N` where the value is a comma-separated list of integer types from the [indexed types registry](registry/index.html#indexed-types). @@ -689,7 +689,7 @@ list of integer types from the [indexed types registry](registry/index.html#inde | ---------- | ---- | ---- | --------- | | _typ._did. | TXT | 7200 | id=0,1,2 | -Types can be discovered, and registered, in the [indexed types registry](registry/index.html#indexed-types). +Types can be discovered and registered in the [indexed types registry](registry/index.html#indexed-types). ::: note Identifying entities through type-based indexing is a relatively unreliable practice. It serves @@ -731,7 +731,7 @@ by a [[ref:Retention Challenge]], which requires clients to generate a solution — in order to have their write requests accepted. [[ref:Retention Solutions]] act as proof of an amount of work completed in exchange for a retention guarantee provided by a [[ref:Gateway]] (via the `expiry` property). -The [[ref:Retained DID Set]] aims to provide a fair mechanism which provides numerous benefits for clients while giving +The [[ref:Retained DID Set]] aims to provide a fair mechanism that provides numerous benefits for clients while giving [[ref:Gateway]] operators anti-spam prevention, and control over the rate at which they accept new DIDs, thus enhancing the overall reliability and effectiveness of [[ref:Gateways]] in managing DIDs. @@ -739,7 +739,7 @@ the overall reliability and effectiveness of [[ref:Gateways]] in managing DIDs. A [[ref:Retention Solution]] is a form of [proof of work](https://en.bitcoin.it/wiki/Proof_of_work) bound to a specific DID identifier, using input values supplied by a given [gateway](registry/index.html#gateways). The proof of work is -performed using the [SHA-256 hashing algorithm](https://en.wikipedia.org/wiki/SHA-2) over the concatenation of a the +performed using the [SHA-256 hashing algorithm](https://en.wikipedia.org/wiki/SHA-2) over the concatenation of the `did` identifier and random [`nonce`](https://en.wikipedia.org/wiki/Cryptographic_nonce) supplied by the user, and a `hash` value [supplied by the gateway](#get-the-current-challenge). The source of a given `hash` referred to as a `hash_source` ****MUST**** be one of the values specified in the [Hash Source Registry](registry/index.html#hash-source). @@ -747,13 +747,13 @@ The result of a given proof of work attempt is referred to as the `retention` va The resulting `retention` value is determined to be a valid [[ref:Retention Solution]] based on whether it has the requisite number of leading zeros defined by the `difficulty`. Difficulty values are -[supplied by the gateway](#get-the-current-challenge) and ****MUST**** be no less than 26 bits of the 256-bit hash value. +[supplied by the gateway](#get-the-current-challenge), and ****MUST**** be no less than 26 bits of the 256-bit hash value. The algorithm for generating a [[ref:Retention Solution]] is as follows: 1. Obtain a DID identifier and set it to `DID`. -2. Get the `difficulty` and `hash` value from the server set to `DIFFICULTY` and `HASH`, respectively. +2. Get the `difficulty` and `hash` value from the server set to `DIFFICULTY` and `HASH` respectively. 3. Generate a random 32-bit integer nonce value set to `NONCE`. @@ -769,7 +769,7 @@ The algorithm for generating a [[ref:Retention Solution]] is as follows: 7. Set `RETENTION_SOLUTION` equal to the concatenation of `ATTEMPT` and `NONCE` separated by a colon (e.g., `ATTEMPT`:`NONCE`). -8. Submit the `RETENTION_SOLUTION` to the [Gateway API](#register=or-update-a-did) for write operations. +8. Submit the `RETENTION_SOLUTION` to the [Gateway API](#register-or-update-a-did) for write operations. :::note When a [[ref:Client]] submits a valid [[ref:Retention Solution]], conformant [[ref:Gateways]] respond with an `expiry` @@ -816,8 +816,8 @@ retention policy and includes it in the response to the [[ref:Client]]. By validating the [[ref:Retention Solution]], the [[ref:Gateway]] ensures that the [[ref:Client]] has performed the necessary proof of work and is eligible for the retention guarantee. This validation process helps maintain the integrity and fairness of the [[ref:Retained DID Set]] system. It is important for [[ref:Gateways]] to consistently -apply the validation logic and reject any write requests that do not include a valid [[ref:Retention Solution]]. This -helps prevent abuse and ensures that only [[ref:Clients]] who have invested the required computational effort can benefit +apply the validation logic and reject any write requests that do not include a valid [[ref:Retention Solution]]. Retention +solutions help prevent abuse and ensures that only [[ref:Clients]] who have invested the required computational effort can benefit from the retention feature. [[ref:Gateways]] ****SHOULD**** regularly update their hash value to prevent pre-computation attacks and ensure the uniqueness and freshness of the [[ref:Retention Solutions]]. The recommended hash refresh window is **10 minutes**. @@ -848,7 +848,7 @@ When a [[ref:Client]] submits a fresh [[ref:Retention Solution]] for a DID alrea renewed retention period. * When a [[ref:Gateway]] reaches its storage capacity or experiences high load, it is ****RECOMMENDED**** that it -significantly increases the `difficulty` parameter for [[ref:Retention Challenges]]. By raising the `difficulty`, the +significantly increases the `difficulty` parameter for [[ref:Retention Challenges]]. By raising the `difficulty` the [[ref:Gateway]] can effectively limit the acceptance of new DIDs into its [[ref:Retained DID Set]], ensuring the stability and performance of the server under resource constraints. @@ -856,7 +856,7 @@ stability and performance of the server under resource constraints. A conformant [[ref:Gateway]] ****MUST**** support the API defined in the following sections. -As a convenience this API is made available via an [OpenAPI document](#open-api-definition). +As a convenience, this API is made available via an [OpenAPI document](#open-api-definition). #### DHT @@ -883,7 +883,7 @@ On receiving a `PUT` request the server verifiers the `sig` and submits a mutabl - The binary representation of `[]` where: - `sig` - represents the 64-byte [[ref:BEP44]] payload signature. - `seq` - represents the 8-byte unsigned 64-bit integer big-endian representation of a [[ref:BEP44]] sequence number. - - `v` - represents between 0-1000 bytes of a [[ref:bencoded]] compressed DNS packet. + - `v` - represents 0-1000 bytes of a [[ref:bencoded]] compressed DNS packet. - **Returns**: `application/json` - `200` - Success. - `400` - Bad request if the `sig` is not valid. @@ -891,7 +891,7 @@ On receiving a `PUT` request the server verifiers the `sig` and submits a mutabl ##### Get -On receiving a `GET` request the server submits a mutable get query to [[ref:Mainline]] as per [[ref:BEP44]]. +When it receives a `GET` request the server submits a mutable get query to [[ref:Mainline]] as per [[ref:BEP44]]. - **Method**: `GET` - **Path**: `/:id` @@ -901,7 +901,7 @@ On receiving a `GET` request the server submits a mutable get query to [[ref:Mai - `200` - Success. The binary representation of `[]` where: - `sig` - represents the 64-byte [[ref:BEP44]] payload signature. - `seq` - represents the 8-byte unsigned 64-bit integer big-endian representation of a [[ref:BEP44]] sequence number. - - `v` - represents between 0-1000 bytes of a [[ref:bencoded]] compressed DNS packet. + - `v` - represents 0-1000 bytes of a [[ref:bencoded]] compressed DNS packet. - `404` - Record not found. #### Get the Current Challenge @@ -915,7 +915,7 @@ surfacing a [[ref:Retention Challenge]]. - `200` - Success. - `hash` - **string** - **REQUIRED** - The current hash which is to be used as input for computing a [[ref:Retention Solution]]. - `hash_source` - **string** - **REQUIRED** - The source of the hash as defined by the [Hash Source Registry](registry/index.html#hash-source). - - `difficulty` - **integer** - **REQUIRED** - The current difficulty of the challenge, representing the number of + - `difficulty` - **integer** - **REQUIRED** - The challenge's current difficulty represents the number of bits of leading zeros the resulting hash must contain. - `expiry` - **integer** - An _approximate_ expiry date-time value, if a valid [[ref:Retention Solution]] is submitted against this challenge, which ****MUST**** be a [[ref:Unix Timestamp]] in seconds. The _precise_ expiry @@ -1157,8 +1157,8 @@ returned. If no DIDs match the type, an empty array is returned. As an **optional** extension, some existing DID methods can leverage `did:dht` to expand their feature set. This enhancement is most useful for DID methods that operate based on a single key and are compatible with the [[ref:Ed25519]] -key format. By adopting this optional extension, users can maintain their current DIDs without any changes. Additionally, -they gain the ability to add extra information to their DIDs. This is achieved by either publishing or retrieving +key format. Users can maintain their current DIDs without any changes by adopting this optional extension. Additionally, +they gain the ability to add extra information to their DIDs by either publishing or retrieving data from [[ref:Mainline]]. Interoperable DID methods ****MUST**** be registered in @@ -1190,9 +1190,9 @@ encoding format, we recommend additional considerations to minimize payload size The following guidance on representations of keys and their identifiers using the `JsonWebKey` type defined by [[ref:VC-JOSE-COSE]] are ****REQUIRED****: -- For the [[ref:Identity Key]], both the Verification Method `id` and JWK `id` ****MUST**** be set to `0`. +- For the [[ref:Identity Key]], the Verification Method `id` and JWK `id` properties ****MUST**** be set to `0`. -- For all keys besides the [[ref:Identity Key]], the Verification Method `id` and the JWK `kid` is set to the +- For all keys besides the [[ref:Identity Key]], the Verification Method `id` and the JWK `kid` are set to the provided `id` value, if present. If no `id` value is specified, the Verification Method's `id` value and the JWK `kid` values are set to the key's JWK Thumbprint calculated according to [[spec:RFC7638]]. @@ -1201,14 +1201,14 @@ To conserve space in the DNS packet representation, compressed point encoding ** x-coordinate and a sign bit for the y-coordinate. This practice reduces each public key's size from 65 to 33 bytes. - [[ref:DID Document]] representations ****MUST**** always use fully-qualified identifiers when referring -to Verification Methods (e.g. `did:dht:uodqi99wuzxsz6yx445zxkp8ddwj9q54ocbcg8yifsqru45x63kj#0` as opposed to `0` or `#0`). +to Verification Methods (e.g., `did:dht:uodqi99wuzxsz6yx445zxkp8ddwj9q54ocbcg8yifsqru45x63kj#0` as opposed to `0` or `#0`). #### Historical Key State Rotating keys is a widely recommended security practice. However, if you frequently rotate keys in a -[[ref:DID Document]], this leads to an increase in the document's size due to the accumulation of old keys. -This, in turn, increases the size of the corresponding DNS packet. To manage this overhead, while still distinguishing -between currently active keys and those that are no longer in use (but were valid in the past), users ****MAY**** +[[ref:DID Document]], this increases the document's size due to the accumulation of old keys. +Storage of old keys, in turn, increases the size of the corresponding DNS packet. To manage this overhead while still +distinguishing between currently active keys and those that are no longer in use (but were valid in the past), users ****MAY**** utilize the [service property](https://www.w3.org/TR/did-core/#services). This property allows for the specification of services that are dedicated to storing signed records of the historical key states. Following this practice helps to keep the [[ref:DID Document]] more concise. @@ -1225,13 +1225,13 @@ with [[ref:Gateways]]. To reduce the risk of [Denial of Service Attacks](https://www.cisa.gov/news-events/news/understanding-denial-service-attacks), spam, and other unwanted traffic, it is ****RECOMMENDED**** that [[ref:Gateways]] require [[ref:Retention Challenges]] for all requests. The use of [[ref:Retention Challenges]] can act as an attack prevention measure, as it would be -costly to scale retention challenge calculations. [[ref:Gateways]] ****MAY**** choose to explore other rate limiting -techniques, such as IP-limiting, or an access-token-based approaches. +costly to scale retention challenge calculations. [[ref:Gateways]] ****MAY**** choose to explore other rate-limiting +techniques, such as IP limiting, or access-token-based approaches. ### DID Resolution The process for resolving a DID DHT Document via a [[ref:Gateway]] is outlined in the [read section above](#read). -However, we provide additional guidance for [DID Resolvers](https://www.w3.org/TR/did-core/#dfn-did-resolvers) supplying +However, we provide additional guidance for [DID Resolvers](https://www.w3.org/TR/did-core/#dfn-did-resolvers), supplying [DID Document Metadata](https://www.w3.org/TR/did-core/#did-document-metadata) and [DID Resolution Metadata](https://www.w3.org/TR/did-core/#did-resolution-metadata) as follows: @@ -1256,7 +1256,7 @@ for the DID. * If the [[ref:DID Document]] has [been deactivated](#deactivate) the [`deactivated` property](https://www.w3.org/TR/did-core/#dfn-deactivated) ****MUST**** be set to `true`. -* The metadata `types` property ****MUST**** be set to the array of strings representing type values, if +* The metadata `types` property ****MUST**** be set to the array of strings representing type values if [type data](#type-indexing) is present in the [[ref:DID Document]]'s packet. * The metadata `expiry` property ****MUST**** be set to the integer representing the expiry date-time value @@ -1264,8 +1264,8 @@ for the DID in the [[ref:Gateway]]'s [Retained DID Set](#retained-did-set). #### DID Resolution Metadata -* The metaata `gateway` property ****MUST**** be set to the string representing the [[ref:Gateway]]'s URI -from which the DID was resolved. This is useful in cases where a [DID Resolvers](https://www.w3.org/TR/did-core/#dfn-did-resolvers) +* The metadata `gateway` property ****MUST**** be set to the string representing the [[ref:Gateway]]'s URI +from which the DID was resolved. This property is useful in cases where a [DID Resolvers](https://www.w3.org/TR/did-core/#dfn-did-resolvers) performs resolution against an [Authoritative Gateway](#designating-authoritative-gateways). ## Security and Privacy Considerations @@ -1283,7 +1283,7 @@ associated with a record set. There are three such cases to be aware of: record, the record with the latest sequence number must be selected. If the server has encountered greater [[ref:sequence numbers]] before, the server ****MAY**** reject the record set. If the server supports [historical resolution](#historical-resolution) it ****MAY**** choose to accept the request and insert the record into -its historical ordered state. +its historically ordered state. - **Conflicting Sequence Number** - When a malicious actor publishes _valid but conflicting_ records to two different [[ref:Mainline Servers]] or [[ref:Gateways]]. Implementers are encouraged to follow the guidance outlined in [conflict @@ -1296,7 +1296,7 @@ timestamps greater than **2 hours** into the future to mitigate [timing attack]( ### Data Availability Given the nature of decentralized distributed systems, there are no firm guarantees that all [[ref:Gateways]] have access -to the same state. It is ****RECOMMENDED**** to publish and read from multiple [[ref:Gateways]] to reduce such risks. +to the same state. To reduce such risks, it is ****RECOMMENDED**** to publish and read from multiple [[ref:Gateways]]. As an **optional** enhancement [[ref:Gateways]] ****MAY**** choose to share state amongst themselves via mechanisms such as a [gossip protocol](https://en.wikipedia.org/wiki/Gossip_protocol). @@ -1305,7 +1305,7 @@ such as a [gossip protocol](https://en.wikipedia.org/wiki/Gossip_protocol). To enter into the DHT using [[ref:BEP44]] records ****MUST**** be signed by an [[ref:Ed25519]] private key, known as the [[ref:Identity Key]]. When retrieving records either through a [[ref:Mainline Server]] or a [[ref:Gateway]] is it ****RECOMMENDED**** that one verifies the cryptographic integrity of the record themselves instead of trusting a server -to have done the validation. Servers that do not return a signature value ****MUST NOT**** be trusted. +to have done the validation. Implementers ****MUST NOT**** trust servers that do not return a signature value. ### Key Compromise @@ -1316,7 +1316,7 @@ such as the mechanism for [rotation](#rotation) noted in this specification. ### Public Data -[[ref:Mainline]] is a public network. As such, there is risk in storing private, sensitive, or personally identifying +[[ref:Mainline]] is a public network. As such, there is a risk in storing private, sensitive, or personally identifying information (PII) on such a network. Storing such sensitive information on the network or in the contents of a `did:dht` document is strongly discouraged.