Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add interop with jwk and key #56

Merged
merged 2 commits into from
Nov 22, 2023
Merged

add interop with jwk and key #56

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
261b22a
add interop with jwk and key
Nov 22, 2023
bd411a8
spec text
Nov 22, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 0 additions & 2 deletions spec/api.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -229,7 +228,6 @@ paths:
type: array
items:
type: string
format: did:dht:*
/difficulty:
get:
tags:
Expand Down
74 changes: 72 additions & 2 deletions spec/registry/spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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.
Comment on lines +79 to +84
Copy link

@msporny msporny Nov 25, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We'll want to modify this slightly to:

  1. Use the different prefix for a did:dht Ed25519 key (that just makes sure we bind the Ed25519 key to a resolution network -- did:dht). We can register the Multikey prefix pretty quickly to do that.
  2. did:key can take an argument and you can get your keys back as either Multikey or JsonWebKey, so no need to be specific here. JsonWebKey2020 is definitely out of date and is not going to survive standardization. We should be using JsonWebKey anywhere that we were using JsonWebKey2020 before.
  3. If you wanted the did:key to be encoded in z-base-32, we could do that... though I don't think there's a Multibase encoding for that yet? If there is interest there, we could look into that (this is one of the reasons Multibase exists -- because the base-encoding you use is largely driven by what the protocols are optimized for -- humans, ASCII, glyph compression, or some combination of the previous).

None of the feedback above is blocking for now, but wanted to just make sure it was registered as feedback so we can adjust going forward.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

agree with 1 + 2 will update when the did:key spec is updated ... (#57)

for 3 I think this is a good idea as it reduces the need to re-encode/decode here for resolvers...but that raises a question. Is it preferable to reduce the impact on existing implementations (i.e. not need to support z-base-32) and just keep the translation a function of resolvers/registrars?

Copy link

@msporny msporny Nov 26, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

re: 3 -- yes, it's a good question. I haven't had enough time to think about it in detail... my gut tells me to not add the z-base-32 requirement for did:key implementations... but then again, it's a fairly trivial piece of code to write (it's just general base-encoding w/ a specific base-32 alphabet). Most implementations should just treat the did:key value as text until it's handed to a resolver/registrar/verifier... someone will have to do a deeper analysis on the benefits/drawbacks.


##### 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.
Expand Down Expand Up @@ -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).
[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]]
24 changes: 18 additions & 6 deletions spec/spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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);
Expand All @@ -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

Expand Down Expand Up @@ -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).
Expand All @@ -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`).
Expand All @@ -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.
Expand Down Expand Up @@ -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]],
Expand Down
Loading