diff --git a/spec/package-lock.json b/spec/package-lock.json index 1f131124..046bb3db 100644 --- a/spec/package-lock.json +++ b/spec/package-lock.json @@ -9,7 +9,7 @@ "version": "1.0.0", "license": "Apache 2.0", "dependencies": { - "spec-up": "^0.10.6" + "spec-up": "^0.10.7" }, "devDependencies": { "del-cli": "^4.0.1" @@ -1209,9 +1209,9 @@ } }, "node_modules/escalade": { - "version": "3.1.1", - "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.1.1.tgz", - "integrity": "sha512-k0er2gUkLf8O0zKJiAhmkTnJlTvINGv7ygDNPbeIsX/TJjGJZHuh9B2UxbsaEkmlEo9MfhrSzmhIlhRlI2GXnw==", + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.1.2.tgz", + "integrity": "sha512-ErCHMCae19vR8vQGe50xIsVomy19rg6gFu3+r3jkEO46suLMWBksvVyoGgQV+jOfl84ZSOSlmv6Gxa89PmTGmA==", "engines": { "node": ">=6" } @@ -4555,9 +4555,9 @@ "integrity": "sha512-eWN+LnM3GR6gPu35WxNgbGl8rmY1AEmoMDvL/QD6zYmPWgywxWqJWNdLGT+ke8dKNWrcYgYjPpG5gbTfghP8rw==" }, "node_modules/spec-up": { - "version": "0.10.6", - "resolved": "https://registry.npmjs.org/spec-up/-/spec-up-0.10.6.tgz", - "integrity": "sha512-lut8YJXdL1vcpU/BCZO1oBNbj07Lf3bfwXQ2xUsqQ/ihY5dJqSerBxIUjoXkMRVujLW0vnAp56LCAv8xaEer2Q==", + "version": "0.10.7", + "resolved": "https://registry.npmjs.org/spec-up/-/spec-up-0.10.7.tgz", + "integrity": "sha512-4rTGz4x6WtbnF2+uVSxJsOs55JikKPmqGEgHXZ/ecMImn4HAC3nJEM9JDTVLhnTLavf6gKn+q5n7jXG0vq6RPQ==", "dependencies": { "@traptitech/markdown-it-katex": "3.3.0", "axios": "0.21.2", diff --git a/spec/package.json b/spec/package.json index e9d3be03..4a586575 100644 --- a/spec/package.json +++ b/spec/package.json @@ -9,7 +9,7 @@ "url": "git://github.com/TBD54566975/did-dht-method" }, "dependencies": { - "spec-up": "^0.10.6" + "spec-up": "^0.10.7" }, "devDependencies": { "del-cli": "^4.0.1" diff --git a/spec/registry/spec.md b/spec/registry/spec.md index bd728f5a..5d4be54e 100644 --- a/spec/registry/spec.md +++ b/spec/registry/spec.md @@ -9,7 +9,7 @@ The DID DHT Method Specification Registry 1.0 **Draft Created:** November 20, 2023 -**Latest Update:** January 26, 2024 +**Latest Update:** March 28, 2024 **Editors:** ~ [Gabe Cohen](https://github.com/decentralgabe) @@ -35,12 +35,14 @@ All are welcome to propose changes to this registry. ### Key Type Index Corresponds to the mapping, for a DID Document's DNS packet representation, of a cryptographic key type to its index value. +For each key type a default algorithm is provided to be used with the key's `JWK` [[spec:RFC7517]] representation. -| Index | Key Type | -| ----- | ------------------------------------------------------ | -| 0 | [Ed25519](https://ed25519.cr.yp.to/) | -| 1 | [secp256k1](https://datatracker.ietf.org/doc/html/rfc8812#section-3.1) | -| 2 | [secp256r1](https://neuromancer.sk/std/secg/secp256r1) / [P-256](https://neuromancer.sk/std/nist/P-256) | +| Index | Key Type | Default Algorithm | +| ----- | ------------------------------------------------------ | ----------------- | +| 0 | [Ed25519](https://ed25519.cr.yp.to/) | [EdDSA](https://datatracker.ietf.org/doc/draft-ietf-jose-fully-specified-algorithms/) [[ref:Fully-Specified Algorithms for JOSE and COSE]] | +| 1 | [secp256k1](https://datatracker.ietf.org/doc/html/rfc8812#section-3.1) | [ES256K](https://www.rfc-editor.org/rfc/rfc8812.html) [[spec:RFC8812]] | +| 2 | [secp256r1](https://neuromancer.sk/std/secg/secp256r1) / [P-256](https://neuromancer.sk/std/nist/P-256) | [ES256](https://www.rfc-editor.org/rfc/rfc7518.html) [[spec:RFC7518]] | +| 3 | [X25519](https://www.rfc-editor.org/rfc/rfc7748) [[spec:RFC7748]] | [ECDH-ES+A256KW](https://datatracker.ietf.org/doc/html/rfc7518#section-4.6) [[spec:RFC7518]] | ::: note All keys are represented as JWKs [[spec:RFC7517]] in their **uncompressed** form. @@ -208,4 +210,8 @@ JWK into a DID Document. J. Miller. ~ [z-base-32](https://philzimmermann.com/docs/human-oriented-base-32-encoding.txt). Human-oriented base-32 encoding. Z. O'Whielacronx; November 2002. +[[def:Fully-Specified Algorithms for JOSE and COSE]] +~ [Fully-Specified Algorithms for JOSE and COSE](https://datatracker.ietf.org/doc/draft-ietf-jose-fully-specified-algorithms/). +M. Jones, O. Steele; 28 February 2024. [Internet Engineering Task Force](https://ietf.org). + [[spec]] \ No newline at end of file diff --git a/spec/spec.md b/spec/spec.md index 6791ab8d..95041299 100644 --- a/spec/spec.md +++ b/spec/spec.md @@ -171,9 +171,12 @@ which would be undecetable by a client. Currently, [[ref:Mainline]] exclusively supports the [[ref:Ed25519]] key type. In turn, [[ref:Ed25519]] is required by DID DHT and is used to uniquely identify DID DHT Documents. DID DHT identifiers are formed by concatenating the `did:dht:` prefix with a [[ref:z-base-32]] -encoded Identity Key, which acts as its [[ref:suffix]]. Identity Keys always have the identifier `0` as both its Verification Method `id` and -JWK `kid` [[spec:RFC7517]]. While the system requires at least one [[ref:Ed25519]], a DID DHT Document can include any number of additional keys. -However, these additional key's types ****MUST**** be registered in the [Key Type Index](registry/index.html##key-type-index). +encoded Identity Key, which acts as its [[ref:suffix]]. Identity Keys ****MUST**** have the identifier `0` as both its Verification Method +`id` and JWK `kid` [[spec:RFC7517]]. Identity Keys ****MUST**** have the [Verification Relationships](#verification-relationships) +_Authentication_, _Assertion_, _Capabilitiy Invocation_, and _Capability Delegation_. + +While the system requires at least one [[ref:Ed25519]], a DID DHT Document can include any number of additional keys. Additional key +types ****MUST**** be registered in the [Key Type Index](registry/index.html##key-type-index). As a unique consequence of the requirement of the Identity Key, DID DHT Documents are able to be partially-resolved without contacting [[ref:Maineline]] or [[ref:Gateway]] servers, though it is ****RECOMMENDED**** that deterministic resolution is only used as a fallback mechanism. @@ -279,18 +282,21 @@ as a `_kN._did.` record where `N` is the zero-indexed positional index of a give - Each [Verification Method's]((https://www.w3.org/TR/did-core/#verification-methods)) record **type** is `TXT`, indicating a Text record. - Each [Verification Method's](https://www.w3.org/TR/did-core/#verification-methods) **rdata** is represented by the form -`id=M;t=N;k=O` where `M` is the Verification Method's `id`, `N` is the index of the key's type from the -[key type index](registry/index.html#key-type-index), and `N` is the unpadded base64URL [[spec:RFC4648]] representation of -the public key. +`id=M;t=N;k=O;a=P` where `M` is the Verification Method's `id`, `N` is the index of the key's type from the +[key type index](registry/index.html#key-type-index), `N` is the unpadded base64URL [[spec:RFC4648]] representation of +the public key, and `P` is the `JWK` `alg` identifier of the key. - Verification Method `id`s ****MAY**** be omitted. If omitted, they can be computed according to the rules specified in the section on [representing keys](#representing-keys) when reconstructing the DID Document. + - `alg` identifiers ****MAY**** be ommitted. If omimtted, they are assigned to the default value specified in the + [key type index](registry/index.html#key-type-index). + - The [[ref:Identity Key]] ****MUST**** always be at index `_k0` with `id` `0`. -- [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 omitted, -it is assumed that the controller of the Verification Method is the [[ref:Identity Key]]. +- [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 +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 @@ -369,7 +375,7 @@ A sample transformation of a fully-featured DID Document to a DNS packet is exem "controller": "did:dht:i9xkp8ddcbcg8jwq54ox699wuzxyifsqx4jru45zodqu453ksz6y", "publicKeyJwk": { "kid": "0", - "alg": "EdDSA", + "alg": "Ed25519", "crv": "Ed25519", "kty": "OKP", "x": "r96mnGNgWGOmjt6g_3_0nd4Kls5-kknrd4DdPW8qtfw" @@ -420,7 +426,7 @@ A sample transformation of a fully-featured DID Document to a DNS packet is exem | _did.``. | TXT | 7200 | v=0;vm=k0,k1;auth=k0,k1;asm=k0,k1;inv=k0;del=k0;srv=s1 | | _cnt.did. | TXT | 7200 | did:example:abcd | | _aka.did. | TXT | 7200 | did:example:efgh,did:example:ijkl | -| _k0._did. | TXT | 7200 | t=0;k=afdea69c63605863a68edea0ff7ff49dde0a96ce7e9249eb7780dd3d6f2ab5fc | +| _k0._did. | TXT | 7200 | t=0;k=afdea69c63605863a68edea0ff7ff49dde0a96ce7e9249eb7780dd3d6f2ab5fc;a=Ed25519 | | _k1._did. | TXT | 7200 | t=1;k=AyiNAz7y-XBr853PBAzgAOU_c0Hyw0Gb69Hr9jTC3MQ8 | | _s0._did. | TXT | 7200 | id=dwn;t=DecentralizedWebNode;se=https://example.com/dwn1,https://example.com/dwn2 | @@ -442,7 +448,9 @@ To create a `did:dht`, the process is as follows: `JsonWebKey` defined by [[ref:VC-JOSE-COSE]]. b. 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]]. + 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. Default algorithms are defined per key type in + the [indexed types registry](registry/index.html#indexed-types). 3. Map the output [[ref:DID Document]] to a DNS packet as outlined in [property mapping](#property-mapping). @@ -733,7 +741,7 @@ DID by its type. "controller": "did:dht:i9xkp8ddcbcg8jwq54ox699wuzxyifsqx4jru45zodqu453ksz6y", "publicKeyJwk": { "kid": "0", - "alg": "EdDSA", + "alg": "Ed25519", "crv": "Ed25519", "kty": "OKP", "x": "r96mnGNgWGOmjt6g_3_0nd4Kls5-kknrd4DdPW8qtfw" @@ -1019,11 +1027,11 @@ A minimal DID Document. ```json { - "kty": "OKP", + "kid": "0", + "alg": "Ed25519", "crv": "Ed25519", - "x": "YCcHYL2sYNPDlKaALcEmll2HHyT968M4UWbr-9CFGWE", - "alg": "EdDSA", - "kid": "0" + "kty": "OKP", + "x": "YCcHYL2sYNPDlKaALcEmll2HHyT968M4UWbr-9CFGWE" } ``` @@ -1038,11 +1046,11 @@ A minimal DID Document. "type": "JsonWebKey", "controller": "did:dht:cyuoqaf7itop8ohww4yn5ojg13qaq83r9zihgqntc5i9zwrfdfoo", "publicKeyJwk": { - "kty": "OKP", + "kid": "0", + "alg": "Ed25519", "crv": "Ed25519", - "x": "YCcHYL2sYNPDlKaALcEmll2HHyT968M4UWbr-9CFGWE", - "alg": "EdDSA", - "kid": "0" + "kty": "OKP", + "x": "YCcHYL2sYNPDlKaALcEmll2HHyT968M4UWbr-9CFGWE" } } ], @@ -1077,11 +1085,11 @@ two types to index, an aka, and controller properties. ```json { - "kty": "OKP", + "kid": "0", + "alg": "Ed25519", "crv": "Ed25519", - "x": "YCcHYL2sYNPDlKaALcEmll2HHyT968M4UWbr-9CFGWE", - "alg": "EdDSA", - "kid": "0" + "kty": "OKP", + "x": "YCcHYL2sYNPDlKaALcEmll2HHyT968M4UWbr-9CFGWE" } ``` @@ -1091,12 +1099,12 @@ With controller: `did:dht:i9xkp8ddcbcg8jwq54ox699wuzxyifsqx4jru45zodqu453ksz6y`. ```json { - "kty": "EC", + "kid": "0GkvkdCGu3DL7Mkv0W1DhTMCBT9-z0CkFqZoJQtw7vw", + "alg": "ES256K", "crv": "secp256k1", + "kty": "EC", "x": "1_o0IKHGNamet8-3VYNUTiKlhVK-LilcKrhJSPHSNP0", - "y": "qzU8qqh0wKB6JC_9HCu8pHE-ZPkDpw4AdJ-MsV2InVY", - "alg": "ES256K", - "kid": "0GkvkdCGu3DL7Mkv0W1DhTMCBT9-z0CkFqZoJQtw7vw" + "y": "qzU8qqh0wKB6JC_9HCu8pHE-ZPkDpw4AdJ-MsV2InVY" } ``` @@ -1129,11 +1137,11 @@ With controller: `did:dht:i9xkp8ddcbcg8jwq54ox699wuzxyifsqx4jru45zodqu453ksz6y`. "type": "JsonWebKey", "controller": "did:dht:cyuoqaf7itop8ohww4yn5ojg13qaq83r9zihgqntc5i9zwrfdfoo", "publicKeyJwk": { - "kty": "OKP", + "kid": "0", + "alg": "Ed25519", "crv": "Ed25519", - "x": "YCcHYL2sYNPDlKaALcEmll2HHyT968M4UWbr-9CFGWE", - "alg": "EdDSA", - "kid": "0" + "kty": "OKP", + "x": "YCcHYL2sYNPDlKaALcEmll2HHyT968M4UWbr-9CFGWE" } }, { @@ -1141,12 +1149,12 @@ With controller: `did:dht:i9xkp8ddcbcg8jwq54ox699wuzxyifsqx4jru45zodqu453ksz6y`. "type": "JsonWebKey", "controller": "did:dht:i9xkp8ddcbcg8jwq54ox699wuzxyifsqx4jru45zodqu453ksz6y", "publicKeyJwk": { - "kty": "EC", + "kid": "0GkvkdCGu3DL7Mkv0W1DhTMCBT9-z0CkFqZoJQtw7vw", + "alg": "ES256K", "crv": "secp256k1", + "kty": "EC", "x": "1_o0IKHGNamet8-3VYNUTiKlhVK-LilcKrhJSPHSNP0", - "y": "qzU8qqh0wKB6JC_9HCu8pHE-ZPkDpw4AdJ-MsV2InVY", - "alg": "ES256K", - "kid": "0GkvkdCGu3DL7Mkv0W1DhTMCBT9-z0CkFqZoJQtw7vw" + "y": "qzU8qqh0wKB6JC_9HCu8pHE-ZPkDpw4AdJ-MsV2InVY" } } ], @@ -1184,6 +1192,7 @@ With controller: `did:dht:i9xkp8ddcbcg8jwq54ox699wuzxyifsqx4jru45zodqu453ksz6y`. | _aka.did. | TXT | 7200 | did:example:efgh,did:example:ijkl | | _k0.did. | TXT | 7200 | id=0;t=0;k=YCcHYL2sYNPDlKaALcEmll2HHyT968M4UWbr-9CFGWE;c=did:example:abcd | | _k1.did. | TXT | 7200 | t=1;k=Atf6NCChxjWpnrfPt1WDVE4ipYVSvi4pXCq4SUjx0jT9 | +| _k1.did. | TXT | 7200 | t=1;k=Atf6NCChxjWpnrfPt1WDVE4ipYVSvi4pXCq4SUjx0jT9;a=ES256K | | _s0.did. | TXT | 7200 | id=service-1;t=TestService;se=https://test-service.com/1,https://test-service.com/2 | | _typ.did. | TXT | 7200 | id=1,2,3 |