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 2a00:1098:3a0::1
OK: Encoded hostname: fiabbgadu-e.v6.alt

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

Prosody typically requires TLS for server-to-server connections. However, it is not possible to obtain CA-issued certificates for .v6.alt domains. This raises challenges around authentication of peers.

By default, this module 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). This provides a decent balance between convenience and security.

Connections using v6.alt are automatically safe from whole categories of attacks such as DNS spoofing/poisoning (because such domains do not use DNS resolvers). However, any attack which enables an attacker to route an IP address to their own machine, for example, may be susceptible to a machine-in-the-middle attack, which cannot be ruled out on the internet.

For ultimate security across untrusted networks, use self-signed certificates and pin fingerprints in the configuration on both sides using mod_s2s_auth_fingerprint.

If you do this, or if you only want v6.alt certificates to be trusted within explicitly configured network ranges, you can disable the default certificate trusting behaviour using s2s_v6mesh_trust_all_certs = false.

You can configure connection security and trust settings per range, using the s2s_v6mesh_ranges configuration option (more details below).

Regardless of any other options, we always recommend keeping 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

Range configuration

By default, this module will use TLS, and trust any certificate from a v6.alt domain if the IP address matches. You can override this behaviour on a per-range basis:

s2s_v6mesh_ranges = {
    ["200::/7"] = {
        -- disable TLS requirement for this IP range (overrides s2s_require_encryption)
        use_tls = false;
        -- trust all certificates (even self-signed) within this range (overrides s2s_secure_auth)
        trust_all_certs = true;
    };
}

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