feat(AutoTLS): opt-in WSS certs from p2p-forge at libp2p.direct (#10521)

Co-authored-by: Marcin Rataj <[email protected]>

config/autotls.go

@@ -0,0 +1,30 @@
+package config
+
+import p2pforge "github.com/ipshipyard/p2p-forge/client"
+
+// AutoTLS includes optional configuration of p2p-forge client of service
+// for obtaining a domain and TLS certificate to improve connectivity for web
+// browser clients. More: https://github.com/ipshipyard/p2p-forge#readme
+type AutoTLS struct {
+	// Enables the p2p-forge feature
+	Enabled Flag `json:",omitempty"`
+
+	// Optional override of the parent domain that will be used
+	DomainSuffix *OptionalString `json:",omitempty"`
+
+	// Optional override of HTTP API that acts as ACME DNS-01 Challenge broker
+	RegistrationEndpoint *OptionalString `json:",omitempty"`
+
+	// Optional Authorization token, used with private/test instances of p2p-forge
+	RegistrationToken *OptionalString `json:",omitempty"`
+
+	// Optional override of CA ACME API used by p2p-forge system
+	CAEndpoint *OptionalString `json:",omitempty"`
+}
+
+const (
+	DefaultAutoTLSEnabled       = false // experimental, opt-in for now (https://github.com/ipfs/kubo/pull/10521)
+	DefaultDomainSuffix         = p2pforge.DefaultForgeDomain
+	DefaultRegistrationEndpoint = p2pforge.DefaultForgeEndpoint
+	DefaultCAEndpoint           = p2pforge.DefaultCAEndpoint
+)

config/config.go

@@ -26,6 +26,7 @@ type Config struct {
 	API       API       // local node's API settings
 	Swarm     SwarmConfig
 	AutoNAT   AutoNATConfig
+	AutoTLS   AutoTLS
 	Pubsub    PubsubConfig
 	Peering   Peering
 	DNS       DNS

core/node/groups.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"strings"
 	"time"
 
 	"github.com/dustin/go-humanize"
@@ -113,6 +114,7 @@ func LibP2P(bcfg *BuildCfg, cfg *config.Config, userResourceOverrides rcmgr.Part
 	enableRelayTransport := cfg.Swarm.Transports.Network.Relay.WithDefault(true) // nolint
 	enableRelayService := cfg.Swarm.RelayService.Enabled.WithDefault(enableRelayTransport)
 	enableRelayClient := cfg.Swarm.RelayClient.Enabled.WithDefault(enableRelayTransport)
+	enableAutoTLS := cfg.AutoTLS.Enabled.WithDefault(config.DefaultAutoTLSEnabled)
 
 	// Log error when relay subsystem could not be initialized due to missing dependency
 	if !enableRelayTransport {
@@ -123,6 +125,23 @@ func LibP2P(bcfg *BuildCfg, cfg *config.Config, userResourceOverrides rcmgr.Part
 			logger.Fatal("Failed to enable `Swarm.RelayClient`, it requires `Swarm.Transports.Network.Relay` to be true.")
 		}
 	}
+	if enableAutoTLS {
+		if !cfg.Swarm.Transports.Network.Websocket.WithDefault(true) {
+			logger.Fatal("Invalid configuration: AutoTLS.Enabled=true requires Swarm.Transports.Network.Websocket to be true as well.")
+		}
+
+		wssWildcard := fmt.Sprintf("/tls/sni/*.%s/ws", cfg.AutoTLS.DomainSuffix.WithDefault(config.DefaultDomainSuffix))
+		wssWildcardPresent := false
+		for _, listener := range cfg.Addresses.Swarm {
+			if strings.Contains(listener, wssWildcard) {
+				wssWildcardPresent = true
+				break
+			}
+		}
+		if !wssWildcardPresent {
+			logger.Fatal(fmt.Sprintf("Invalid configuration: AutoTLS.Enabled=true requires a catch-all Addresses.Swarm listener ending with %q to be present, see https://github.com/ipfs/kubo/blob/master/docs/config.md#autotls", wssWildcard))
+		}
+	}
 
 	// Gather all the options
 	opts := fx.Options(
@@ -133,6 +152,8 @@ func LibP2P(bcfg *BuildCfg, cfg *config.Config, userResourceOverrides rcmgr.Part
 
 		// Services (resource management)
 		fx.Provide(libp2p.ResourceManager(bcfg.Repo.Path(), cfg.Swarm, userResourceOverrides)),
+		maybeProvide(libp2p.P2PForgeCertMgr(cfg.AutoTLS), enableAutoTLS),
+		maybeInvoke(libp2p.StartP2PAutoTLS, enableAutoTLS),
 		fx.Provide(libp2p.AddrFilters(cfg.Swarm.AddrFilters)),
 		fx.Provide(libp2p.AddrsFactory(cfg.Addresses.Announce, cfg.Addresses.AppendAnnounce, cfg.Addresses.NoAnnounce)),
 		fx.Provide(libp2p.SmuxTransport(cfg.Swarm.Transports)),

core/node/libp2p/addrs.go

@@ -1,12 +1,22 @@
 package libp2p
 
 import (
+	"context"
 	"fmt"
+	"os"
 
+	logging "github.com/ipfs/go-log"
+	version "github.com/ipfs/kubo"
+	"github.com/ipfs/kubo/config"
+	p2pforge "github.com/ipshipyard/p2p-forge/client"
 	"github.com/libp2p/go-libp2p"
+	"github.com/libp2p/go-libp2p/core/host"
 	p2pbhost "github.com/libp2p/go-libp2p/p2p/host/basic"
 	ma "github.com/multiformats/go-multiaddr"
 	mamask "github.com/whyrusleeping/multiaddr-filter"
+
+	"github.com/caddyserver/certmagic"
+	"go.uber.org/fx"
 )
 
 func AddrFilters(filters []string) func() (*ma.Filters, Libp2pOpts, error) {
@@ -87,12 +97,26 @@ func makeAddrsFactory(announce []string, appendAnnouce []string, noAnnounce []st
 	}, nil
 }
 
-func AddrsFactory(announce []string, appendAnnouce []string, noAnnounce []string) func() (opts Libp2pOpts, err error) {
-	return func() (opts Libp2pOpts, err error) {
-		addrsFactory, err := makeAddrsFactory(announce, appendAnnouce, noAnnounce)
+func AddrsFactory(announce []string, appendAnnouce []string, noAnnounce []string) interface{} {
+	return func(params struct {
+		fx.In
+		ForgeMgr *p2pforge.P2PForgeCertMgr `optional:"true"`
+	},
+	) (opts Libp2pOpts, err error) {
+		var addrsFactory p2pbhost.AddrsFactory
+		announceAddrsFactory, err := makeAddrsFactory(announce, appendAnnouce, noAnnounce)
 		if err != nil {
 			return opts, err
 		}
+		if params.ForgeMgr == nil {
+			addrsFactory = announceAddrsFactory
+		} else {
+			addrsFactory = func(multiaddrs []ma.Multiaddr) []ma.Multiaddr {
+				forgeProcessing := params.ForgeMgr.AddressFactory()(multiaddrs)
+				annouceProcessing := announceAddrsFactory(forgeProcessing)
+				return annouceProcessing
+			}
+		}
 		opts.Opts = append(opts.Opts, libp2p.AddrsFactory(addrsFactory))
 		return
 	}
@@ -107,3 +131,42 @@ func ListenOn(addresses []string) interface{} {
 		}
 	}
 }
+
+func P2PForgeCertMgr(cfg config.AutoTLS) interface{} {
+	return func() (*p2pforge.P2PForgeCertMgr, error) {
+		storagePath, err := config.Path("", "p2p-forge-certs")
+		if err != nil {
+			return nil, err
+		}
+
+		forgeLogger := logging.Logger("autotls").Desugar()
+		certStorage := &certmagic.FileStorage{Path: storagePath}
+		certMgr, err := p2pforge.NewP2PForgeCertMgr(
+			p2pforge.WithLogger(forgeLogger.Sugar()),
+			p2pforge.WithForgeDomain(cfg.DomainSuffix.WithDefault(config.DefaultDomainSuffix)),
+			p2pforge.WithForgeRegistrationEndpoint(cfg.RegistrationEndpoint.WithDefault(config.DefaultRegistrationEndpoint)),
+			p2pforge.WithCAEndpoint(cfg.CAEndpoint.WithDefault(config.DefaultCAEndpoint)),
+			p2pforge.WithForgeAuth(cfg.RegistrationToken.WithDefault(os.Getenv(p2pforge.ForgeAuthEnv))),
+			p2pforge.WithUserAgent(version.GetUserAgentVersion()),
+			p2pforge.WithCertificateStorage(certStorage),
+		)
+		if err != nil {
+			return nil, err
+		}
+
+		return certMgr, nil
+	}
+}
+
+func StartP2PAutoTLS(lc fx.Lifecycle, certMgr *p2pforge.P2PForgeCertMgr, h host.Host) {
+	lc.Append(fx.Hook{
+		OnStart: func(ctx context.Context) error {
+			certMgr.ProvideHost(h)
+			return certMgr.Start()
+		},
+		OnStop: func(ctx context.Context) error {
+			certMgr.Stop()
+			return nil
+		},
+	})
+}

core/node/libp2p/transport.go

@@ -2,8 +2,8 @@ package libp2p
 
 import (
 	"fmt"
-
 	"github.com/ipfs/kubo/config"
+	"github.com/ipshipyard/p2p-forge/client"
 	"github.com/libp2p/go-libp2p"
 	"github.com/libp2p/go-libp2p/core/metrics"
 	quic "github.com/libp2p/go-libp2p/p2p/transport/quic"
@@ -16,20 +16,25 @@ import (
 )
 
 func Transports(tptConfig config.Transports) interface{} {
-	return func(pnet struct {
+	return func(params struct {
 		fx.In
-		Fprint PNetFingerprint `optional:"true"`
+		Fprint   PNetFingerprint         `optional:"true"`
+		ForgeMgr *client.P2PForgeCertMgr `optional:"true"`
 	},
 	) (opts Libp2pOpts, err error) {
-		privateNetworkEnabled := pnet.Fprint != nil
+		privateNetworkEnabled := params.Fprint != nil
 
 		if tptConfig.Network.TCP.WithDefault(true) {
 			// TODO(9290): Make WithMetrics configurable
 			opts.Opts = append(opts.Opts, libp2p.Transport(tcp.NewTCPTransport, tcp.WithMetrics()))
 		}
 
 		if tptConfig.Network.Websocket.WithDefault(true) {
-			opts.Opts = append(opts.Opts, libp2p.Transport(websocket.New))
+			if params.ForgeMgr == nil {
+				opts.Opts = append(opts.Opts, libp2p.Transport(websocket.New))
+			} else {
+				opts.Opts = append(opts.Opts, libp2p.Transport(websocket.New, websocket.WithTLSConfig(params.ForgeMgr.TLSConfig())))
+			}
 		}
 
 		if tptConfig.Network.QUIC.WithDefault(!privateNetworkEnabled) {

docs/changelogs/v0.32.md

@@ -1,32 +1,35 @@
 # Kubo changelog v0.32
 
-- [v0.31.0](#v0320)
+- [v0.32.0](#v0310)
 
 ## v0.32.0
 
 - [Overview](#overview)
 - [🔦 Highlights](#-highlights)
-  - [go-libp2p updates](#go-libp2p-updated)
-  - [update boxo](#update-boxo)
+  - [🎯 AutoTLS: Automatic Certificates for libp2p WebSockets via `libp2p.direct`](#-autotls-automatic-certificates-for-libp2p-websockets-via-libp2pdirect)
+  - [📦️ Boxo and go-libp2p updates](#-boxo-and-go-libp2p-updates)
 - [📝 Changelog](#-changelog)
 - [👨‍👩‍👧‍👦 Contributors](#-contributors)
 
 ### Overview
 
 ### 🔦 Highlights
 
+#### 🎯 AutoTLS: Automatic Certificates for libp2p WebSockets via `libp2p.direct`
 
-#### go-libp2p updates
+This release introduces an experimental feature that significantly improves how browsers can connect to Kubo node.
+Opt-in configuration allows Kubo nodes to obtain CA-signed TLS certificates for [libp2p Secure WebSocket (WSS)](https://github.com/libp2p/specs/blob/master/websockets/README.md) connections automatically.
 
+See [`AutoTLS`](https://github.com/ipfs/kubo/blob/master/docs/config.md#autotls) configuration for details how to enable it. We appreciate you testing and providing an early feedback in [kubo#10560](https://github.com/ipfs/kubo/issues/10560).
+
+#### 📦️ Boxo and go-libp2p updates
+
+- update `boxo` to [v0.24.2](https://github.com/ipfs/boxo/releases/tag/v0.24.2). This includes a number of fixes and bitswap improvements.
 - update `go-libp2p` to [v0.37.0](https://github.com/libp2p/go-libp2p/releases/tag/v0.37.0)
   - This update required removal of `Swarm.RelayService.MaxReservationsPerPeer` configuration option from Kubo. If you had it set, remove it from your configuration file.
 - update `go-libp2p-kad-dht` to [v0.27.0](https://github.com/libp2p/go-libp2p-kad-dht/releases/tag/v0.27.0)
 - update `go-libp2p-pubsub` to [v0.12.0](https://github.com/libp2p/go-libp2p-pubsub/releases/tag/v0.12.0)
 
-#### Update Boxo
-
-Update boxo to [v0.24.2](https://github.com/ipfs/boxo/releases/tag/v0.24.2). This includes a number of fixes and bitswap improvements.
-
 ### 📝 Changelog
 
 ### 👨‍👩‍👧‍👦 Contributors

docs/config.md

@@ -27,6 +27,12 @@ config file at runtime.
     - [`AutoNAT.Throttle.GlobalLimit`](#autonatthrottlegloballimit)
     - [`AutoNAT.Throttle.PeerLimit`](#autonatthrottlepeerlimit)
     - [`AutoNAT.Throttle.Interval`](#autonatthrottleinterval)
+  - [`AutoTLS`](#autotls)
+    - [`AutoTLS.Enabled`](#autotlsenabled)
+    - [`AutoTLS.DomainSuffix`](#autotlsdomainsuffix)
+    - [`AutoTLS.RegistrationEndpoint`](#autotlsregistrationendpoint)
+    - [`AutoTLS.RegistrationToken`](#autotlsregistrationtoken)
+    - [`AutoTLS.CAEndpoint`](#autotlscaendpoint)
   - [`Bootstrap`](#bootstrap)
   - [`Datastore`](#datastore)
     - [`Datastore.StorageMax`](#datastorestoragemax)
@@ -449,6 +455,109 @@ Default: 1 Minute
 
 Type: `duration` (when `0`/unset, the default value is used)
 
+## `AutoTLS`
+
+> [!CAUTION]
+> This is an **EXPERIMENTAL** opt-in feature and should not be used in production yet.
+> Feel free to enable it and [report issues](https://github.com/ipfs/kubo/issues/new/choose) if you want to help with testing.
+> Track progress in [kubo#10560](https://github.com/ipfs/kubo/issues/10560).
+
+AutoTLS feature enables publicly reachable Kubo nodes (those dialable from the public
+internet) to automatically obtain a wildcard TLS certificate for a DNS name
+unique to their PeerID at `*.[PeerID].libp2p.direct`. This enables direct
+libp2p connections and retrieval of IPFS content from browsers [Secure Context](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts)
+using transports such as [Secure WebSockets](https://github.com/libp2p/specs/blob/master/websockets/README.md),
+without requiring user to do any manual domain registration and ceritficate configuration.
+
+Under the hood, [p2p-forge] client uses public utility service at `libp2p.direct` as an [ACME DNS-01 Challenge](https://letsencrypt.org/docs/challenge-types/#dns-01-challenge)
+broker enabling peer to obtain a wildcard TLS certificate tied to public key of their [PeerID](https://docs.libp2p.io/concepts/fundamentals/peers/#peer-id).
+
+By default, the certificates are requested from Let's Encrypt. Origin and rationale for this project can be found in [community.letsencrypt.org discussion](https://community.letsencrypt.org/t/feedback-on-raising-certificates-per-registered-domain-to-enable-peer-to-peer-networking/223003).
+
+> [!NOTE]
+> Public good DNS and [p2p-forge] infrastructure at `libp2p.direct` is run by the team at [Interplanetary Shipyard](https://ipshipyard.com).
+>
+> <a href="https://ipshipyard.com/"><img src="https://github.com/user-attachments/assets/39ed3504-bb71-47f6-9bf8-cb9a1698f272" /></a>
+
+[p2p-forge]: https://github.com/ipshipyard/p2p-forge
+
+Default: `{}`
+
+Type: `object`
+
+### `AutoTLS.Enabled`
+
+> [!CAUTION]
+> This is an **EXPERIMENTAL** opt-in feature and should not be used in production yet.
+> Feel free to enable it and [report issues](https://github.com/ipfs/kubo/issues/new/choose) if you want to help with testing.
+> Track progress in [kubo#10560](https://github.com/ipfs/kubo/issues/10560).
+
+Enables AutoTLS feature to get DNS+TLS for [libp2p Secure WebSocket](https://github.com/libp2p/specs/blob/master/websockets/README.md) listeners defined in [`Addresses.Swarm`](#addressesswarm), such as `/ip4/0.0.0.0/tcp/4002/tls/sni/*.libp2p.direct/ws` and `/ip6/::/tcp/4002/tls/sni/*.libp2p.direct/ws`.
+
+If `.../tls/sni/*.libp2p.direct/ws` [multiaddr] is present in [`Addresses.Swarm`](#addressesswarm)
+with SNI segment ending with [`AutoTLS.DomainSuffix`](#autotlsdomainsuffix),
+Kubo will obtain and set up a trusted PKI TLS certificate for it, making it diallable from web browser's [Secure Contexts](https://w3c.github.io/webappsec-secure-contexts/).
+
+> [!IMPORTANT]
+> Caveats:
+> - Requires your Kubo node to be publicly diallable.
+>   - If you want to test this with a node that is behind a NAT and uses manual port forwarding or UPnP (`Swarm.DisableNatPortMap=false`),
+>     add catch-all `/ip4/0.0.0.0/tcp/4002/tls/sni/*.libp2p.direct/ws` and `/ip6/::/tcp/4002/tls/sni/*.libp2p.direct/ws` to [`Addresses.Swarm`](#addressesswarm)
+>     and **wait 5-15 minutes** for libp2p node to set up and learn about own public addresses via [AutoNAT](#autonat).
+>   - If your node is fresh and just started, the [p2p-forge] client may produce and log ERRORs during this time, but once a publicly diallable addresses are set up, a subsequent retry should be successful.
+> - Requires manually updating [`Addresses.Swarm`](#addressesswarm) and opening a new port
+>   - A separate port has to be used instead of `4001` because we wait for TCP port sharing ([go-libp2p#2984](https://github.com/libp2p/go-libp2p/issues/2684)) to be implemented.
+>   - If you use manual port forwarding, make sure incoming connections to this additional port are allowed the same way `4001` ones already are.
+> - The TLS certificate is used only for [libp2p WebSocket](https://github.com/libp2p/specs/blob/master/websockets/README.md) connections.
+>   - Right now, this is NOT used for hosting a [Gateway](#gateway) over HTTPS (that use case still requires manual TLS setup on reverse proxy, and your own domain).
+
+> [!TIP]
+> Debugging can be enabled by setting environment variable `GOLOG_LOG_LEVEL="error,autotls=debug,p2p-forge/client=debug"`
+
+Default: `false`
+
+Type: `flag`
+
+### `AutoTLS.DomainSuffix`
+
+Optional override of the parent domain suffix that will be used in DNS+TLS+WebSockets multiaddrs generated by [p2p-forge] client.
+Do not change this unless you self-host [p2p-forge].
+
+Default: `libp2p.direct` (public good run by [Interplanetary Shipyard](https://ipshipyard.com))
+
+Type: `optionalString`
+
+### `AutoTLS.RegistrationEndpoint`
+
+Optional override of [p2p-forge] HTTP registration API.
+Do not change this unless you self-host [p2p-forge].
+
+> [!IMPORTANT]
+> The default endpoint performs [libp2p Peer ID Authentication over HTTP](https://github.com/libp2p/specs/blob/master/http/peer-id-auth.md)
+> (prooving ownership of PeerID), probes if your Kubo node can correctly answer to a [libp2p Identify](https://github.com/libp2p/specs/tree/master/identify) query.
+> This ensures only a correctly configured, publicly diallable Kubo can initiate [ACME DNS-01 challenge](https://letsencrypt.org/docs/challenge-types/#dns-01-challenge) for `peerid.libp2p.direct`.
+
+Default: `https://registration.libp2p.direct` (public good run by [Interplanetary Shipyard](https://ipshipyard.com))
+
+Type: `optionalString`
+
+### `AutoTLS.RegistrationToken`
+
+Optional value for `Forge-Authorization` token sent with request to `RegistrationEndpoint`
+(useful for private/self-hosted/test instances of [p2p-forge], unset by default).
+
+Default: `""`
+
+Type: `optionalString`
+
+### `AutoTLS.CAEndpoint`
+
+Optional override of CA ACME API used by [p2p-forge] system.
+
+Default: [certmagic.LetsEncryptProductionCA](https://pkg.go.dev/github.com/caddyserver/certmagic#pkg-constants) (see [community.letsencrypt.org discussion](https://community.letsencrypt.org/t/feedback-on-raising-certificates-per-registered-domain-to-enable-peer-to-peer-networking/223003))
+
+Type: `optionalString`
+
 ## `Bootstrap`
 
 Bootstrap is an array of [multiaddrs][multiaddr] of trusted nodes that your node connects to, to fetch other nodes of the network on startup.
@@ -1835,7 +1944,7 @@ Type: `optionalInteger`
 
 #### `Swarm.RelayService.MaxReservationsPerPeer`
 
-**REMOVED in kubo 0.32 due to removal from go-libp2p v0.37**
+**REMOVED in kubo 0.32 due to [go-libp2p#2974](https://github.com/libp2p/go-libp2p/pull/2974)**
 
 #### `Swarm.RelayService.MaxReservationsPerIP`