mod_s2s_v6mesh

Overview

There are various virtual network overlay projects which provide peers with stable IPv6 addresses, including Yggdrasil, CJDNS, and others.

One problem is that these systems are generally peer-to-peer, and there is typically no standard DNS root for the private networks. Public DNS can be used, but that adds a dependency on the public internet which can cause problems, e.g. if the public internet becomes inaccessible.

The “obvious” solution is to skip domain names, and just federate between IP addresses directly. Unfortunately this brings a lot of problems, such as the inability for IP addresses to have subdomains, which are used extensively in XMPP to allow hosting multiple services on a single IP address.

This module provides an alternative solution. For every possible IPv6 address, it can generate an encoded hostname, which supports subdomains, and can be resolved to an IPv6 address without any external DNS server infrastructure.

The domain names end with .v6.alt. The .alt TLD was defined by RFC 9476 specifically for non-DNS use cases such as this. .v6.alt is our own scheme.

Usage

For this module to be useful for federation:

• Both servers must have this module loaded
• Both servers must have stable IPv6 addresses (if the IP address changes, the hostname changes, and your XMPP identity changes - a new hostname is like starting fresh).

Although this module was designed with virtual/mesh networks in mind, it is possible to use it between any two servers with IPv6 addresses (check the section on connection security below if you are using it over unencrypted networks such as the public internet).

Discover your hostname with the prosodyctl command (our example will use the IP address 2a00:1098:3a0::1 but you should replace it with your own):

$ prosodyctl shell v6alt get_domain localhost 2a00:1098:3a0::1
OK: Encoded hostname: fiabbgadu-e.v6.alt

In this command, “localhost” must be an existing domain in your Prosody config (“localhost” is in the default config), however it’s required just to make the command work and has no effect on the output.

You can then use this domain name in your config file, for example:

VirtualHost "fiabbgadu-e.v6.alt" -- Main host, for user accounts

Component "groups.fiabbgadu-e.v6.alt" "muc" -- MUC on a subdomain

Connection security

By default, Prosody requires TLS for server-to-server connections. However, it is not possible to obtain CA-issued certificates for .v6.alt domains. This module disables certificate validation (it treats all certificates as trusted) for all v6.alt domains where the IP address matches the domain name that the remote server is claiming to be (the actual certificate contents are irrelevant and never checked, so self-signed certificates are fine).

Additionally, if the IP is within one of the CIDR ranges listed in the s2s_v6mesh_secure_ranges configuration option, then the module will tell Prosody to not even perform TLS for the connection. Prosody will treat the connections as totally secure, so be very sure you trust the underlying network’s security layer before adding an IP range to this list. If you want similar behaviour for non-v6.alt domains, look at mod_secure_interfaces and configure it with your mesh interface’s address.

Because of the above mechanisms in place, it is strongly recommended to keep Prosody’s default settings of s2s_require_encryption = true and s2s_secure_auth = true so that connections not covered by this module are always encrypted and authenticated properly.

Connecting from clients

Note that although Prosody supports .v6.alt domains for federation when this module is loaded, this domain scheme is not (currently?) supported by clients, and you’ll need to specify the connection IP manually in order to connect.

Your JID should always be entered as <username>@<domain.v6.alt>, and you should specify the server’s IPv6 address in your client’s advanced connection configuration screen.

HTTP

Services that use HTTP such as file sharing, web clients, etc. will need to use the IP address in the URL, as clients and browsers won’t be able to resolve the .v6.alt domain names. You will need to configure Prosody’s HTTP server appropriately for your deployment, e.g.

http_external_url = "https://[2a00:1098:3a0::1]:5281"

Configuration

Compatibility

Developers

This section is for developers who want to encode/decode v6.alt addresses in their own code.

Encoding scheme

1. Take an IPv6 address as raw packed bytes

2. Encode it using base32 (RFC 4648), remove ==== padding from the end.

3. Lowercase the output

4. Find the first longest sequence of ‘a’ characters that is:

   1. Not at the start of the string (start scanning from second position)
   2. Two or more characters in length
   3. Not including the end character

   If found, replace this sequence with a hyphen (-).

5. Append .v6.alt

Decoding scheme

1. Take a hostname ending with .v6.alt
2. Remove .v6.alt
3. Remove any ‘.’ characters and all content before them (foo.bar -> bar)
4. If the string contains a hyphen, replace that hyphen with sufficient ‘a’ characters to make the string 26 characters in length. Strings with multiple hyphen characters are invalid and must be rejected.
5. Uppercase the string
6. Decode using base32

Test vectors

sudo prosodyctl install --server=https://modules.prosody.im/rocks/ mod_s2s_v6mesh