#11460·kubo

Support manual TLS certificate/key for custom domain WSS listeners

Author: karawitanCreated Sep 10, 2026Updated Sep 10, 2026

Context

Kubo's AutoTLS feature (introduced in #10521) automatically obtains TLS certificates for /wss listeners via p2p-forge, but only for *.{peerid}.libp2p.direct domains.

There is currently no built-in way to use WSS with a user-supplied TLS certificate for a custom domain (e.g., example.net). Operators who want WSS on their own domain must run a reverse proxy (nginx, Caddy, etc.) in front of kubo.

This was originally raised by @lidel in #8740:

What if we do the same thing we did for private swarm and if one adds /dns/example.net/.../wss addr, check if $IPFS_PATH/example.net.crt and $IPFS_PATH/example.net.key exist and use them if present? (and if not, do ACME)

Proposal

Add support for manual TLS certificate/key files for custom domain WSS, following the convention used for private networks:

  • When a /dns/example.net/.../wss (or /tls/sni/example.net/.../ws) address is configured in Addresses.Swarm, check for $IPFS_PATH/example.net.crt and $IPFS_PATH/example.net.key.
  • If both files exist, use them as the TLS certificate for that WSS listener.
  • If not, fall back to AutoTLS (for *.libp2p.direct domains) or skip WSS.

This would allow operators to use WSS with their own domains and certificates (e.g., from their own ACME client, or a commercial CA) without a reverse proxy.

Related

  • #8740 (original PR, superseded by #10521)
  • #10521 (merged: AutoTLS via p2p-forge)
  • #10560 (epic: enabling AutoTLS by default)