S2S Federation

xmppd supports server-to-server (S2S) federation, allowing users on your server to communicate with users on other XMPP servers worldwide.

DANE-First Trust Model#

Unlike most XMPP servers that rely on the Certificate Authority (CA/PKIX) system, xmppd uses DANE (DNS-Based Authentication of Named Entities) as the primary trust mechanism for S2S connections.

Trust order:

1. DANE-EE (TLSA usage 3) — direct certificate pinning via DNS
2. DANE-TA (TLSA usage 2) — trust anchor pinning via DNS
3. PKIX/CA — traditional certificate authority (fallback)
4. Dialback (XEP-0220) — legacy verification when no TLS auth available

Why DANE?#

• No CA dependency — you don't need to trust hundreds of certificate authorities
• Domain operator control — the domain owner publishes TLSA records in their DNS
• MITM resistant — when combined with DNSSEC, the TLS certificate is cryptographically bound to the domain
• Self-signed friendly — DANE-EE works with self-signed certificates

Setting Up DANE#

1. Obtain a TLS certificate (self-signed or CA-issued)
2. Generate the SPKI SHA-256 hash:

openssl x509 -in server.pem -pubkey -noout | \
  openssl pkey -pubin -outform DER | \
  openssl dgst -sha256 -hex | awk '{print $2}'

3. Publish a TLSA record:

_5269._tcp.xmpp.example.com. 86400 IN TLSA 3 1 1 <hash>

4. Sign your zone with DNSSEC (recommended but not required by xmppd)

Authentication Methods#

SASL EXTERNAL#

When DANE verification succeeds, xmppd uses SASL EXTERNAL for authentication in both directions:

• Outbound: xmppd presents its TLS client certificate and offers SASL EXTERNAL
• Inbound: xmppd verifies the remote server's certificate via DANE, then accepts SASL EXTERNAL

Server Dialback (XEP-0220)#

For servers without DANE or valid TLS certificates, xmppd supports the legacy dialback protocol:

1. Originating server sends a dialback key (HMAC-SHA256)
2. Receiving server makes a callback connection to verify the key
3. On successful verification, the connection is authorized

Dialback provides weaker security than DANE (it only proves domain ownership, not identity) but ensures interoperability with older servers.

Connection Flow#

Outbound (xmppd → remote server)#

1. DNS SRV lookup: _xmpp-server._tcp.remote.com
2. DNS TLSA lookup: _5269._tcp.{target}.
3. TCP connect to resolved host:port
4. Stream open
5. STARTTLS
6. TLS handshake + DANE verification
7. Post-TLS stream restart
8. SASL EXTERNAL (if DANE passed) or dialback
9. Post-auth stream restart
10. Ready for stanza delivery

Inbound (remote server → xmppd)#

1. TCP accept on port 5269
2. Stream open (extract 'from' domain)
3. Advertise STARTTLS
4. TLS handshake
5. DANE verification of remote certificate
6. Post-TLS stream restart
7. SASL EXTERNAL or dialback verification
8. Post-auth stream restart
9. Forward inbound stanzas to xmppd-core via IPC

Interoperability#

xmppd has been tested against:

Troubleshooting#

No federation connections#

1. Verify port 5269 is open in your firewall
2. Check DNS SRV records: dig _xmpp-server._tcp.example.com SRV
3. Check TLSA records: dig _5269._tcp.xmpp.example.com TLSA
4. Verify the certificate matches the TLSA record

"DANE verification failed" in logs#

The TLSA record hash doesn't match the certificate's SPKI. Regenerate the hash and update your DNS record. Remember that hash changes when you renew your certificate.