From c27d8e0854f6299d25202c9c11356a754d918b53 Mon Sep 17 00:00:00 2001 From: Felix Lange Date: Sat, 29 Sep 2018 22:27:47 +0200 Subject: [PATCH] EIP-1459: Node Discovery via DNS (#1459) --- EIPS/eip-1459.md | 150 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 150 insertions(+) create mode 100644 EIPS/eip-1459.md diff --git a/EIPS/eip-1459.md b/EIPS/eip-1459.md new file mode 100644 index 0000000000000..4c05b41fab20c --- /dev/null +++ b/EIPS/eip-1459.md @@ -0,0 +1,150 @@ +--- +eip: 1459 +title: Node Discovery via DNS +author: Felix Lange , Péter Szilágyi +type: Standards Track +category: Networking +status: Draft +created: 2018-09-26 +requires: 778 +discussions-to: https://github.com/ethereum/devp2p/issues/50 +--- + +# Abstract + +This document describes a scheme for authenticated, updateable Ethereum node lists +retrievable via DNS. + +# Motivation + +Many Ethereum clients contain hard-coded bootstrap node lists. Updating those +lists requires a software update. The current lists are small, giving the client +little choice of initial entry point into the Ethereum network. We would like to +maintain larger node lists containing hundreds of nodes, and update them +regularly. + +The scheme described here is a replacement for client bootstrap node lists with +equivalent security and many additional benefits. DNS node lists may also be +useful to Ethereum peering providers because their customers can configure the +client to use the provider's list. Finally, the scheme serves as a fallback +option for nodes which can't join the node discovery DHT. + +# Specification + +### DNS Record Structure + +Node lists are encoded as TXT records. The records form a merkle tree. The root +of the tree is a record with content: + + enrtree-root=v1 hash= seq= sig= + +`roothash` is the abbreviated root hash of the tree in base32 encoding. `seqnum` +is the tree's update sequence number, a decimal integer. `signature` is a +65-byte secp256k1 EC signature over the keccak256 hash of the record content, +encoded as URL-safe base64. + +Further TXT records on subdomains map hashes to one of three entry types. The +subdomain name of any entry is the base32 encoding of the abbreviated keccak256 +hash of its text content. + +- `enrtree=,,...,` is an intermediate tree containing further hash + subdomains. +- `enrtree-link=@` is a leaf pointing to a different list located at + another fully qualified domain name. The key is the expected signer of the + remote list, a base32 encoded secp256k1 public key, +- `enr=` is a leaf containing a node record [as defined in EIP-778][eip-778]. + The node record is encoded as a URL-safe base64 string. + +No particular ordering or structure is defined for the tree. Whenever the tree +is updated, its sequence number should increase. The content of any TXT record +should be small enough to fit into the 512 byte limit imposed on UDP DNS +packets. This limits the number of hashes that can be placed into a `enrtree=` +entry. + +Example in zone file format: + +```text +; name ttl class type content +@ 60 IN TXT "enrtree-root=v1 hash=TO4Q75OQ2N7DX4EOOR7X66A6OM seq=3 sig=N-YY6UB9xD0hFx1Gmnt7v0RfSxch5tKyry2SRDoLx7B4GfPXagwLxQqyf7gAMvApFn_ORwZQekMWa_pXrcGCtwE=" +TO4Q75OQ2N7DX4EOOR7X66A6OM 86900 IN TXT "enrtree=F4YWVKW4N6B2DDZWFS4XCUQBHY,JTNOVTCP6XZUMXDRANXA6SWXTM,JGUFMSAGI7KZYB3P7IZW4S5Y3A" +F4YWVKW4N6B2DDZWFS4XCUQBHY 86900 IN TXT "enr=-H24QI0fqW39CMBZjJvV-EJZKyBYIoqvh69kfkF4X8DsJuXOZC6emn53SrrZD8P4v9Wp7NxgDYwtEUs3zQkxesaGc6UBgmlkgnY0gmlwhMsAcQGJc2VjcDI1NmsxoQPKY0yuDUmstAHYpMa2_oxVtw0RW_QAdpzBQA8yWM0xOA==" +JTNOVTCP6XZUMXDRANXA6SWXTM 86900 IN TXT "enr=-H24QDquAsLj8mCMzJh8ka2BhVFg3n4V9efBJBiaXHcoL31vRJJef-lAseMhuQBEVpM_8Zrin0ReuUXJE7Fs8jy9FtwBgmlkgnY0gmlwhMYzZGOJc2VjcDI1NmsxoQLtfC0F55K2s1egRhrc6wWX5dOYjqla-OuKCELP92O3kA==" +JGUFMSAGI7KZYB3P7IZW4S5Y3A 86900 IN TXT "enrtree-link=AM5FCQLWIZX2QFPNJAP7VUERCCRNGRHWZG3YYHIUV7BVDQ5FDPRT2@morenodes.example.org" +``` + +### Referencing Trees by URL + +When referencing a record tree, e.g. in source code, the preferred form is a +URL. References should use the scheme `enrtree://` and encode the DNS domain in +the hostname. The expected public key that signs the tree should be encoded in +33-byte compressed form as a base32 string in the username portion of the URL. + +Example: + +```text +enrtree://AP62DT7WOTEQZGQZOU474PP3KMEGVTTE7A7NPRXKX3DUD57TQHGIA@nodes.example.org +``` + +### Client Protocol + +To find nodes at a given DNS name, say "mynodes.org": + +1. Resolve the TXT record of the name and check whether it contains a valid + "enrtree-root=v1" entry. Let's say the root hash contained in the entry is + "CFZUWDU7JNQR4VTCZVOJZ5ROV4". +2. Optionally verify the signature on the root against a known public key and + check whether the sequence number is larger than or equal to any previous + number seen for that name. +3. Resolve the TXT record of the hash subdomain, e.g. "CFZUWDU7JNQR4VTCZVOJZ5ROV4.mynodes.org" + and verify whether the content matches the hash. +4. The next step depends on the entry type found: + - for `enrtree`: parse the list of hashes and continue resolving those (step 3). + - for `enrtree-link`: continue traversal on the linked domain (step 1). + - for `enr`: decode, verify the node record and import it to local node storage. + +During traversal, the client should track hashes and domains which are already +resolved to avoid going into an infinite loop. + +# Rationale + +### Why DNS? + +We have chosen DNS as the distribution medium because it is always available, +even under restrictive network conditions. The protocol provides low latency and +answers to DNS queries can be cached by intermediate resolvers. No custom server +software is needed. Node lists can be deployed to any DNS provider such as +CloudFlare DNS, dnsimple, Amazon Route 53 using their respective client +libraries. + +### Why is this a merkle tree? + +Being a merkle tree, any node list can be authenticated by a single signature on +the root. Hash subdomains protect the integrity of the list. At worst +intermediate resolvers can block access to the list or disallow updates to it, +but cannot corrupt its content. The sequence number prevents replacing the root +with an older version. + +Synchronizing updates on the client side can be done incrementally, which +matters for large lists. Individual entries of the tree are small enough to fit +into a single UDP packet, ensuring compatibility with environments where only +basic UDP DNS is available. The tree format also works well with caching +resolvers: only the root of the tree needs a short TTL. Intermediate entries and +leaves can be cached for days. + +### Why does `enrtree-link` exist? + +Links between lists enable federation and web-of-trust functionality. The +operator of a large list can delegate maintenance to other list providers. If +two node lists link to each other, users can use either list and get nodes from +both. + +# References + +1. The base64 and base32 encodings used to represent binary data are defined in + RFC 4648 (https://tools.ietf.org/html/rfc4648). No padding is used for base32. + +[eip-778]: https://eips.ethereum.org/EIPS/eip-778 + +# Copyright + +Copyright and related rights waived via CC0.