From 06631116830cb420768819bfefbe1cbddd6bd043 Mon Sep 17 00:00:00 2001 From: Gabe <7622243+decentralgabe@users.noreply.github.com> Date: Thu, 23 Nov 2023 00:42:09 +0100 Subject: [PATCH] add interop with jwk and key (#56) --- spec/api.yaml | 2 -- spec/registry/spec.md | 74 +++++++++++++++++++++++++++++++++++++++++-- spec/spec.md | 24 ++++++++++---- 3 files changed, 90 insertions(+), 10 deletions(-) diff --git a/spec/api.yaml b/spec/api.yaml index 1a4f8ffb..5a7ac863 100644 --- a/spec/api.yaml +++ b/spec/api.yaml @@ -150,7 +150,6 @@ paths: required: true schema: type: string - format: did:dht:* - name: seq in: query description: Sequence number of the DID to resolve. @@ -229,7 +228,6 @@ paths: type: array items: type: string - format: did:dht:* /difficulty: get: tags: diff --git a/spec/registry/spec.md b/spec/registry/spec.md index b834273a..10e02348 100644 --- a/spec/registry/spec.md +++ b/spec/registry/spec.md @@ -5,7 +5,7 @@ The DID DHT Method Specification Registry 1.0 **Latest Draft:** [tbd54566975.github.io/did-dht-method](https://tbd54566975.github.io/did-dht-method) -**Latest Update:** November 20, 2023 +**Latest Update:** November 22, 2023 **Editors:** ~ [Gabe Cohen](https://github.com/decentralgabe) @@ -62,6 +62,58 @@ themselves discoverable via a [[ref:Gateway]]'s API. | Web App | https://schema.org/WebApplication | 6 | | Financial Institution | https://schema.org/FinancialService | 7 | +### Interoperable DID Methods + +As an **OPTIONAL** extension, some existing DID methods can leverage `did:dht` to broaden their feature set. This registry serves +to define such DID methods that are interoperable with `did:dht`. To enter into the registry each DID method ****MUST**** define +sections on _publishing_ and _resolving_ interoperable DIDs. + +#### did:key + +DID DHT is interoperable with the [[ref:DID Key method]] when using [[ref:Ed25519]] keys represented as JWKs [[spec:RFC7517]]. + +##### Publishing + +To publish a [[ref:DID Key]] to the DHT, the process is as follows: + +1. Verify the `did:key` value begins with the prefix `z6Mk`. +2. Decode the [[ref:Ed25519]] key in the `did:key` identifier, and re-encode it using [[ref:z-base-32]]. +3. Expand the `did:key` using the [process outlined in the did:key spec](https://w3c-ccg.github.io/did-method-key/#read), +with `options.publicKeyFormat` set to `JsonWebKey2020`. +4. Optionally, amend the [[ref:DID Document]] with additional properties (Verification Methods, Services, etc.). +5. Follow steps 3 onward in as outlined in the [create section of the spec](../index.html#create), using the identifier from step 2. + +##### Resolving + +To resolve a DID Key, the process is as follows: + +1. Verify the `did:key` value begins with the prefix `z6Mk`. +2. Decode the [[ref:Ed25519]] key in the `did:key` identifier, and re-encode it using [[ref:z-base-32]]. +3. Follow the process outlined in the [read section of the spec](../index.html#read) using the identifier from the prior step. +4. If lookup fails, fallback to the [guidance provided in the did:key spec](https://w3c-ccg.github.io/did-method-key/#read). + +#### did:jwk + +DID DHT is interoperable with the [[ref:DID JWK method]] when using JWKS [[spec:RFC7517]] representing [[ref:Ed25519]] keys. + +##### Publishing + +To publish a [[ref:DID JWK]] to the DHT, the process is as follows: + +1. Expand the `did:jwk` using the [process outlined in the did:jwk spec](https://github.com/quartzjer/did-jwk/blob/main/spec.md#read). +2. Verify that the JWK represents an [[ref:Ed25519]] key. +3. Transform the [[ref:Ed25519]] key to its bytes representation and re-encode it using [[ref:z-base-32]]. +4. Optionally, amend the [[ref:DID Document]] with additional properties (Verification Methods, Services, etc.). +5. Follow steps 3 onward in as outlined in the [create section](#create) above, using the identifier from step 3. + +##### Resolving + +1. Expand the `did:jwk` using the [process outlined in the did:jwk spec](https://github.com/quartzjer/did-jwk/blob/main/spec.md#read). +2. Verify that the JWK represents an [[ref:Ed25519]] key. +3. Transform the [[ref:Ed25519]] key to its bytes representation and re-encode it using [[ref:z-base-32]]. +4. Follow the process outlined in the [Read section](#read) above using the identifier from the prior step. +5. If lookup fails, fallback to the [guidance provided in the did:jwk spec](https://github.com/quartzjer/did-jwk/blob/main/spec.md#read). + ### Gateways As an **OPTIONAL** feature of the DID DHT Method, Gateway operators have the opportunity to make their [gateways](../index.html#gateways) discoverable. This serves as a registry for such gateways. @@ -98,4 +150,22 @@ To discover Bitcoin Anchored Gateways one must follow the following steps: [[def:Timelock]] ~ [Timelock](https://github.com/bitcoin/bips/blob/master/bip-0065.mediawiki). P. Todd. 01 October 2014. -[Bitcoin](https://github.com/bitcoin). \ No newline at end of file +[Bitcoin](https://github.com/bitcoin). + +[[def:DID Key, DID Key Method]] +~ [The did:key Method v0.7](https://w3c-ccg.github.io/did-method-key/). A DID Method for Static Cryptograhpic Keys. +D. Longley, D. Zagidulin, M. Sporny. [W3C CCG](https://w3c-ccg.github.io/). + +[[def:DID JWK, DID JWK Method]] +~ [did:jwk](https://github.com/quartzjer/did-jwk/blob/main/spec.md). did:jwk is a deterministic transformation of a +JWK into a DID Document. J. Miller. + +[[def:Ed25519]] +~ [Ed25519](https://ed25519.cr.yp.to/). D. J. Bernstein, N. Duif, T. Lange, P. Schwabe, B.-Y. Yang; 26 September 2011. +[ed25519.cr.yp.to](https://ed25519.cr.yp.to/). + +[[def:z-base-32]] +~ [z-base-32](https://philzimmermann.com/docs/human-oriented-base-32-encoding.txt). Human-oriented base-32 encoding. +Z. O'Whielacronx; November 2002. + +[[spec]] \ No newline at end of file diff --git a/spec/spec.md b/spec/spec.md index 16feb852..64ab026a 100644 --- a/spec/spec.md +++ b/spec/spec.md @@ -7,7 +7,7 @@ The DID DHT Method Specification 1.0 **Registry:** [https://did-dht.com/registry](https://did-dht.com/registry) -**Latest Update:** November 20, 2023 +**Latest Update:** November 22, 2023 **Editors:** ~ [Gabe Cohen](https://github.com/decentralgabe) @@ -318,7 +318,7 @@ To create a `did:dht`, the process is as follows: 2. Construct a compliant 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 _identifier key_ encoded as a `publicKeyJwk` as per [[spec:RFC7517]] with an `id` of ``#0`` and `type` of + the _identifier key_ encoded as a `publicKeyJwk` as per [[spec:RFC7517]] with an `id` of `#0` and `type` of `JsonWebKey2020` as per [[ref:VC-JWS-2020]]. b. The document can include any number of other [core properties](https://www.w3.org/TR/did-core/#core-properties); @@ -328,7 +328,7 @@ To create a `did:dht`, the process is as follows: 4. Construct a signed [[ref:BEP44]] put message with the `v` value as a [[ref:bencode]]d DNS packet from the prior step. -5. Submit the result of to the [[ref:DHT]] via a [[ref:Pkarr]] relay, or a [[ref:Gateway]]. +5. Submit the result of to the [[ref:DHT]] via a [[ref:Pkarr]] relay, or a [[ref:Gateway]], with the identifier created in step 1. #### Read @@ -384,10 +384,24 @@ An example type record is as follows: Types can be found and registered in the [DID DHT Registry](registry/index.html#indexed-types). +## Interoperability With Other DID Methods + +As an **OPTIONAL** extension, some existing DID methods can leverage `did:dht` to broaden their feature set. This enhancement is most useful for DID +methods that operated based on a single key, compatable with an [[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 data from [[ref:Mainline]]. + +Interoperable DID methods ****MUST**** be registered in [the corresponding registry](registry/index.html#interoperable-did-methods). + ## Gateways Gateways serve as specialized nodes within the network, providing a range of DID-centric functionalities that extend beyond the capabilities of a standard [[ref:Mainline DHT]] node. This section elaborates on these unique features, outlines the operational prerequisites for managing a gateway, and discusses various other facets, including the optional integration of these gateways into a registry system. +::: note +[[ref:Gateways]] may choose to support interoperable methods in addition to `did:dht` as outlined in the +[section on interoperability](#interoperability-with-other-did-methods). +::: + ### Discovering Gateways As an **OPTIONAL** feature of the DID DHT Method, operators of a [[ref:Gateway]] have the opportunity to make it to a [[ref:Registered Gateway]]. A [[ref:Registered Gateway]] distinguishes itself by being discoverable through a [[ref:Gateway Registry]]. This feature allows for easy location through various internet-based discovery mechanisms. The primary purpose of [[ref:Registered Gateways]] is to simplify the process of finding [[ref:Gateways]], accessible to any entity utilizing a [[ref:Gateway Registry]] to locate registered [[ref:Nodes]]. The [[ref:Gateway Registries]] can vary in nature, encompassing a spectrum from centrally managed directories to diverse decentralized systems including databases, ledgers, or other structures. [[ref:Registered Gateways]] are exposed through the [Gateway Registry](registry/index.html#gateways). @@ -400,7 +414,7 @@ A [[ref:Retained DID Set]] refers to the set of DIDs a [[ref:Gateway]] retains a A [[ref:Retention Proof]] is a form of [Proof of Work](https://en.bitcoin.it/wiki/Proof_of_work) performed over a DID's identifier concatenated with the `retention` value of a given DID operation. The `retention` value is composed of a hash value specified [in the gateway registry](registry/index.html#gateways), and a random [nonce](https://en.wikipedia.org/wiki/Cryptographic_nonce) using the [SHA-256 hashing algorithm](https://en.wikipedia.org/wiki/SHA-2). The resulting _Retention Proof Hash_ is used to determine the retention duration based on the number of leading zeros of the hash, referred to as the _difficulty_, which ****MUST**** be no less than 26 bits of the 256-bit hash value. The algorithm, in detail, is as follows: -1. Obtain a `did:dht` identifier and set it to `DID`. +1. Obtain a did identifier and set it to `DID`. 2. Get the difficulty and recent hash from the server set to `DIFFICULTY` and `HASH`, respectively. 2. Generate a random 32-bit integer nonce value set to `NONCE`. 3. Compute the [SHA-256](https://en.wikipedia.org/wiki/SHA-2) hash over `ATTEMPT` where `ATTEMPT` = (`DID` + `HASH` + `NONCE`). @@ -409,7 +423,6 @@ A [[ref:Retention Proof]] is a form of [Proof of Work](https://en.bitcoin.it/wik b. Else, regenerate `NONCE` and go to step 3. 5. Submit the `RETENTION_PROOF` to the [Gateway API](#register=or-update-a-did). - #### Managing the Retained DID Set [[ref:Nodes]] following the [[ref:Retention Set]] rules ****SHOULD**** sort DIDs they are retaining by the number of _leading 0s_ in their [[ref:Retention Proofs]] in descending order, followed by block hash's index number in descending order. When a [[ref:node]] needs to reduce its [[ref:retained set]] of DID entries, it ****SHOULD**** remove entries from the bottom of the list following this sort. @@ -521,7 +534,6 @@ packet, with its signature data, is required it is ****RECOMMENDED**** to use th [Relay API](https://github.com/Nuhvi/pkarr/blob/main/design/relays.md) directly. ::: - ##### Historical Resolution [[ref:Nodes]] ****MAY**** choose to support historical resolution, which is to surface different version of the same [[ref:DID Document]],