Skip to content

6. Announcing hostnames

Date: 2025-02-27

Status

Accepted

Context

There is no consistent approach for hostname resolution across VPN providers such as Tailscale, zerotier and so on. As Clan wishes to support as many of them as practical, we therefore require a common solution for announcing and resolving hostnames.

Claiming a hostname

A host should be able to claim one or more hostnames, with support for multiple IP addresses, both IPV4 and IPV6.

For example, a host with ip addresses 10.0.0.1 and 2606:4700:4700::1111 that wants to be resolvable with hostnames mercury and venus.

Logical network

Hosts should be grouped under a logical network, independent of the underlying VPN solution, with an associated top-level domain e.g. mercury.sol, venus.sol, with sol being the top-level domain.

This is to support host resolution across multiple Clans in the future.

Hostname TTL

Hosts will be required to periodically re-assert their claims. Failure to do so will result in a host losing those hostnames after a configurable network-specific time-to-live.

The first host to claim a hostname should retain that claim until such time as it fails to re-assert it within the required timeframe.

Distributed control

Changing a network's top-level domain, hostname TTL and other properties should be possible via any node participating in the network.

Decision

We will start by introducing the concept of a Network with the following properties:

  • an associated ED25519 key pair, with the base64-encoded public key being used as a unique identifier.
  • a settings object containing values such as the top-level domain, hostname TTL and any other properties to be applied across the whole network.
  • settings need to be signed by the network's ED25519 private key.
  • signed settings can be provided to any node within the network for distribution as the signature can be verified against the network's id (public key).

Here is an example of signed network settings:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
{
    "networks": {
        "Kx6uxNJy6oQkgZ2pG41QBWmiK3AkK4b7MfHstGHn1XU=": {
            "settings": {
                "tld": "jup",
                "host_ttl": 60000000000,
                "signing_keys": [
                    "uD6UZzmMqr7spmAYTO9UI6qCCfsHClFjMGRqxLN6Fjs=",
                    "kQBNwxqD9e4r4VqSSDK6gN0IGChuFRqWO4rFuioi3Ug="
                ],
                "signature": {
                    "signed_at": "2025-03-04T10:48:45.424Z",
                    "signed_by": "Kx6uxNJy6oQkgZ2pG41QBWmiK3AkK4b7MfHstGHn1XU=",
                    "signature": "2onB1pD+XNcXstgieDR4vC+KHkAt2JbCDa+WijLHxDULhSigPV9fIopzxXvBNZAtqeJ4EYmTvUXXw7A2+ItmCw=="
                }
            }
        }
    }
}

Next we will introduce a Host with the following properties:

  • an associated ED25519 key pair, with the base64-encoded public key being used as a unique identifier.
  • a host may report one or more IP addresses, signed by the host's private key.
  • a host may claim one or more hostnames, signed by the host's private key.
  • updates for a given host are ignored unless first signed by the host's private key.
  • each host and hostname may be signed by one or more nodes within the network (chronology-through-trusted-attestation).

The model looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
{
    "networks": {
        "Kx6uxNJy6oQkgZ2pG41QBWmiK3AkK4b7MfHstGHn1XU=": {
            "hosts": {
                "4/rs1S8OqrcB1m6OTyQ/9L5W9mJ7hmknqnQ+ZQVHmS4=": {
                    "ips": ["10.0.1.5"],
                    "signatures": {
                        "4/rs1S8OqrcB1m6OTyQ/9L5W9mJ7hmknqnQ+ZQVHmS4=": {
                            "signed_at": "2025-03-04T10:49:35.169Z",
                            "signature": "QH9K4Zcq65sa89g3zeNwuzNzfG4Dm3Z4Dr6+wOSMnPPlDGoACqhyjHpSKa+bTIv7BTKPflngLHHqVhh6OdUABA=="
                        },
                        "uD6UZzmMqr7spmAYTO9UI6qCCfsHClFjMGRqxLN6Fjs=": {
                            "signed_at": "2025-03-04T10:49:36.191Z",
                            "signature": "QO0obMWrNmyL4ttTHEEltosgTRub8iPNpLOkiiXAtQoi3ufOvPj+6NmomVm4n4ddmcbpTsGu+yc2jQWO8ktqBA=="
                        }
                    },
                    "hostnames": {
                        "amalthea": {
                            "host_id": "4/rs1S8OqrcB1m6OTyQ/9L5W9mJ7hmknqnQ+ZQVHmS4=",
                            "signatures": {
                                "4/rs1S8OqrcB1m6OTyQ/9L5W9mJ7hmknqnQ+ZQVHmS4=": {
                                    "signed_at": "2025-03-04T10:48:53.155Z",
                                    "signature": "dafgLEC9kALyvuNEDGydSFqJqGDTpXBhyronXae8PALrX+49PqzFPc9GFyXhHlvL0JnIglHk09b/TzzASKzuCw=="
                                },
                                "kQBNwxqD9e4r4VqSSDK6gN0IGChuFRqWO4rFuioi3Ug=": {
                                    "signed_at": "2025-03-04T10:48:53.26Z",
                                    "signature": "TEJ/+1ldYkkZFNXUpIFNFihTYhrd+ehjks4DWTqimF9X/NSzWBlpKO8Kg+toUlRuMzYigqr1axW37EowoSWlAQ=="
                                },
                                "uD6UZzmMqr7spmAYTO9UI6qCCfsHClFjMGRqxLN6Fjs=": {
                                    "signed_at": "2025-03-04T10:48:53.373Z",
                                    "signature": "HRWk8kJCIOBJJ2FgaKm9tx2HUgHl6RtqfCOGkLbpFoxBnDuKDJj6Rhrf+IC/GXJdzO+ZTHseBMbYpUv4WlWuCg=="
                                }
                            }
                        },
                        "callisto": {
                            "host_id": "4/rs1S8OqrcB1m6OTyQ/9L5W9mJ7hmknqnQ+ZQVHmS4=",
                            "signatures": {
                                "4/rs1S8OqrcB1m6OTyQ/9L5W9mJ7hmknqnQ+ZQVHmS4=": {
                                    "signed_at": "2025-03-04T10:48:53.155Z",
                                    "signature": "tCmxtbDJXhL0nAsOPnRYORj9sI4OMI2o0/Yy1IktP/8v1rDDTNZZTzssdRW6N1YZnZWzdouAUfj9L4muzzo4Cw=="
                                },
                                "kQBNwxqD9e4r4VqSSDK6gN0IGChuFRqWO4rFuioi3Ug=": {
                                    "signed_at": "2025-03-04T10:48:53.259Z",
                                    "signature": "d22ZBoXTdRFTkzWnhHk9WjlLcb/5rOIjq8iJQGWLmcY72i5me9//SZHIJR94yKVrEITKsa8TEYc/yN7cu9Y1AQ=="
                                },
                                "uD6UZzmMqr7spmAYTO9UI6qCCfsHClFjMGRqxLN6Fjs=": {
                                    "signed_at": "2025-03-04T10:48:53.373Z",
                                    "signature": "g7vhn9pM9NnXBn8prvaIHiLV3dUWHmiiZmvusBjjISH8y3Np8/g59ITf14WeWfBugpWlR5kYkNyLYk605osmCQ=="
                                }
                            }
                        },
                        "ganymede": {
                            "host_id": "4/rs1S8OqrcB1m6OTyQ/9L5W9mJ7hmknqnQ+ZQVHmS4=",
                            "signatures": {
                                "4/rs1S8OqrcB1m6OTyQ/9L5W9mJ7hmknqnQ+ZQVHmS4=": {
                                    "signed_at": "2025-03-04T10:48:53.155Z",
                                    "signature": "94gddLr+VOTpKlXjHlWPqE8p9KTYZX7sBfP9kaAWLwK2KDrzr4Wd5aBHrmzEYi2NvP9QnbWLPcoRHXkjGHNuCA=="
                                },
                                "kQBNwxqD9e4r4VqSSDK6gN0IGChuFRqWO4rFuioi3Ug=": {
                                    "signed_at": "2025-03-04T10:48:53.26Z",
                                    "signature": "nibbkW4JqCgH8AEy2Y6doRmvZ45SYb3w5j4eEGil9K/Rmi57uVc+YFAUogOucP9dGqDNMof8K86vx4GLE0SDCw=="
                                },
                                "uD6UZzmMqr7spmAYTO9UI6qCCfsHClFjMGRqxLN6Fjs=": {
                                    "signed_at": "2025-03-04T10:48:53.373Z",
                                    "signature": "zzXA0wsVl+xPeACssl4TJJ8MGS8uPNiWCxcwvNrHwL1fy2WKvSykrKL1u9cPLWqwP5qqjuxFcMO4NlKBCYO3BA=="
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

We include the hostname claims as separately indexed and signed subitems within the Host model. This is to allow us to facilitate allowing the earliest claimant to retain a hostname.

A Host may change the hostnames they are claiming. We need to keep track of when each was first seen by nodes within the network. Therefore, we require them to be signed individually, thereby retaining that history.

Merging Host entries

When merging two entries for the same Host, we will do the following:

  • verify each has been signed by the host, using the host's id as the ED25519 public key, disregarding otherwise.
  • verify each has been signed by at least one of the network's signing_keys, disregarding otherwise.
  • retain the values from the entry with the latest signed_at as per the host signature.

NOTE: In this scenario, we are trusting the clock of the signer.

Merging Hostnames

When merging two hostnames for the same host, we will do the following:

  • verify it has been signed by the Host, using the Host's id as the ED25519 public key.
  • combine the signature list between both entries, retaining only those which have been signed by the network's signing_keys.

Determining DNS entries

Determining the earliest claim for each respective hostname requires us to take a view across all the available state.

We must iterate through the hostname claims within each Host, combining them with the Network's top-level domain, and compiling a list of signatures for each fully qualified domain name.

The Host with the earliest signature is the Host to which that fully qualified domain name should point to

This will then be captured in a JSON lines encoded file called dns.json.

Resolving DNS entries

To facilitate seamless integration of our DNS entries, we will create an NSS module supporting gethostbyname which will integrate the contents of dns.json into the NSS hosts database.

Expiring DNS entries

As per the Network's hostname TTL setting, nodes will periodically examine their local state and remove any Host entries which have not recently been signed within the required timeframe.

After expiry (and merging), the dns.json file is re-generated to reflect the new state of the world. Hostname claims by expired Hosts are immediately released.

Consequences

Hostname resolution irrespective of VPN provider becomes possible, as it is now an orthogonal concern rather than implementation specific.