lib/nat, lib/upnp: IPv6 UPnP support (#9010)

This pull request allows syncthing to request an IPv6
[pinhole](https://en.wikipedia.org/wiki/Firewall_pinhole), addressing
issue #7406. This helps users who prefer to use IPv6 for hosting their
services or are forced to do so because of
[CGNAT](https://en.wikipedia.org/wiki/Carrier-grade_NAT). Otherwise,
such users would have to configure their firewall manually to allow
syncthing traffic to pass through while IPv4 users can use UPnP to take
care of network configuration already.

### Testing

I have tested this in a virtual machine setup with miniupnpd running on
the virtualized router. It successfully added an IPv6 pinhole when used
with IPv6 only, an IPv4 port mapping when used with IPv4 only and both
when dual-stack (IPv4 and IPv6) is used.

Automated tests could be added for SOAP responses from the router but
automatically testing this with a real network is likely infeasible.

### Documentation

https://docs.syncthing.net/users/firewall.html could be updated to
mention the fact that UPnP now works with IPv6, although this change is
more "behind the scenes".

---------

Co-authored-by: Simon Frei <freisim93@gmail.com>
Co-authored-by: bt90 <btom1990@googlemail.com>
Co-authored-by: André Colomb <github.com@andre.colomb.de>

lib/nat/interface.go

@@ -19,9 +19,19 @@ const (
 	UDP Protocol = "UDP"
 )
 
+type IPVersion int8
+
+const (
+	IPvAny = iota
+	IPv4Only
+	IPv6Only
+)
+
 type Device interface {
 	ID() string
-	GetLocalIPAddress() net.IP
+	GetLocalIPv4Address() net.IP
 	AddPortMapping(ctx context.Context, protocol Protocol, internalPort, externalPort int, description string, duration time.Duration) (int, error)
-	GetExternalIPAddress(ctx context.Context) (net.IP, error)
+	AddPinhole(ctx context.Context, protocol Protocol, addr Address, duration time.Duration) ([]net.IP, error)
+	GetExternalIPv4Address(ctx context.Context) (net.IP, error)
+	SupportsIPVersion(version IPVersion) bool
 }

lib/nat/service.go

@@ -162,15 +162,16 @@ func (s *Service) scheduleProcess() {
 	}
 }
 
-func (s *Service) NewMapping(protocol Protocol, ip net.IP, port int) *Mapping {
+func (s *Service) NewMapping(protocol Protocol, ipVersion IPVersion, ip net.IP, port int) *Mapping {
 	mapping := &Mapping{
 		protocol: protocol,
 		address: Address{
 			IP:   ip,
 			Port: port,
 		},
-		extAddresses: make(map[string]Address),
+		extAddresses: make(map[string][]Address),
 		mut:          sync.NewRWMutex(),
+		ipVersion:    ipVersion,
 	}
 
 	s.mut.Lock()
@@ -224,7 +225,7 @@ func (s *Service) updateMapping(ctx context.Context, mapping *Mapping, nats map[
 func (s *Service) verifyExistingLocked(ctx context.Context, mapping *Mapping, nats map[string]Device, renew bool) (change bool) {
 	leaseTime := time.Duration(s.cfg.Options().NATLeaseM) * time.Minute
 
-	for id, address := range mapping.extAddresses {
+	for id, extAddrs := range mapping.extAddresses {
 		select {
 		case <-ctx.Done():
 			return false
@@ -239,28 +240,37 @@ func (s *Service) verifyExistingLocked(ctx context.Context, mapping *Mapping, na
 			continue
 		} else if renew {
 			// Only perform renewals on the nat's that have the right local IP
-			// address
-			localIP := nat.GetLocalIPAddress()
-			if !mapping.validGateway(localIP) {
+			// address. For IPv6 the IP addresses are discovered by the service itself,
+			// so this check is skipped.
+			localIP := nat.GetLocalIPv4Address()
+			if !mapping.validGateway(localIP) && nat.SupportsIPVersion(IPv4Only) {
 				l.Debugf("Skipping %s for %s because of IP mismatch. %s != %s", id, mapping, mapping.address.IP, localIP)
 				continue
 			}
 
-			l.Debugf("Renewing %s -> %s mapping on %s", mapping, address, id)
+			if !nat.SupportsIPVersion(mapping.ipVersion) {
+				l.Debugf("Skipping renew on gateway %s because it doesn't match the listener address family", nat.ID())
+				continue
+			}
 
-			addr, err := s.tryNATDevice(ctx, nat, mapping.address.Port, address.Port, leaseTime)
+			l.Debugf("Renewing %s -> %v open port on %s", mapping, extAddrs, id)
+			// extAddrs either contains one IPv4 address, or possibly several
+			// IPv6 addresses all using the same port.  Therefore the first
+			// entry always has the external port.
+			responseAddrs, err := s.tryNATDevice(ctx, nat, mapping.address, extAddrs[0].Port, leaseTime)
 			if err != nil {
-				l.Debugf("Failed to renew %s -> mapping on %s", mapping, address, id)
+				l.Debugf("Failed to renew %s -> %v open port on %s", mapping, extAddrs, id)
 				mapping.removeAddressLocked(id)
 				change = true
 				continue
 			}
 
-			l.Debugf("Renewed %s -> %s mapping on %s", mapping, address, id)
+			l.Debugf("Renewed %s -> %v open port on %s", mapping, extAddrs, id)
 
-			if !addr.Equal(address) {
-				mapping.removeAddressLocked(id)
-				mapping.setAddressLocked(id, addr)
+			// We shouldn't rely on the order in which the addresses are returned.
+			// Therefore, we test for set equality and report change if there is any difference.
+			if !addrSetsEqual(responseAddrs, extAddrs) {
+				mapping.setAddressLocked(id, responseAddrs)
 				change = true
 			}
 		}
@@ -286,23 +296,27 @@ func (s *Service) acquireNewLocked(ctx context.Context, mapping *Mapping, nats m
 
 		// Only perform mappings on the nat's that have the right local IP
 		// address
-		localIP := nat.GetLocalIPAddress()
-		if !mapping.validGateway(localIP) {
+		localIP := nat.GetLocalIPv4Address()
+		if !mapping.validGateway(localIP) && nat.SupportsIPVersion(IPv4Only) {
 			l.Debugf("Skipping %s for %s because of IP mismatch. %s != %s", id, mapping, mapping.address.IP, localIP)
 			continue
 		}
 
-		l.Debugf("Acquiring %s mapping on %s", mapping, id)
+		l.Debugf("Trying to open port %s on %s", mapping, id)
 
-		addr, err := s.tryNATDevice(ctx, nat, mapping.address.Port, 0, leaseTime)
-		if err != nil {
-			l.Debugf("Failed to acquire %s mapping on %s", mapping, id)
+		if !nat.SupportsIPVersion(mapping.ipVersion) {
+			l.Debugf("Skipping firewall traversal on gateway %s because it doesn't match the listener address family", nat.ID())
 			continue
 		}
 
-		l.Debugf("Acquired %s -> %s mapping on %s", mapping, addr, id)
+		addrs, err := s.tryNATDevice(ctx, nat, mapping.address, 0, leaseTime)
+		if err != nil {
+			l.Debugf("Failed to acquire %s open port on %s", mapping, id)
+			continue
+		}
 
-		mapping.setAddressLocked(id, addr)
+		l.Debugf("Opened port %s -> %v on %s", mapping, addrs, id)
+		mapping.setAddressLocked(id, addrs)
 		change = true
 	}
 
@@ -311,19 +325,36 @@ func (s *Service) acquireNewLocked(ctx context.Context, mapping *Mapping, nats m
 
 // tryNATDevice tries to acquire a port mapping for the given internal address to
 // the given external port. If external port is 0, picks a pseudo-random port.
-func (s *Service) tryNATDevice(ctx context.Context, natd Device, intPort, extPort int, leaseTime time.Duration) (Address, error) {
+func (s *Service) tryNATDevice(ctx context.Context, natd Device, intAddr Address, extPort int, leaseTime time.Duration) ([]Address, error) {
 	var err error
 	var port int
+	// For IPv6, we just try to create the pinhole. If it fails, nothing can be done (probably no IGDv2 support).
+	// If it already exists, the relevant UPnP standard requires that the gateway recognizes this and updates the lease time.
+	// Since we usually have a global unicast IPv6 address so no conflicting mappings, we just request the port we're running on
+	if natd.SupportsIPVersion(IPv6Only) {
+		ipaddrs, err := natd.AddPinhole(ctx, TCP, intAddr, leaseTime)
+		var addrs []Address
+		for _, ipaddr := range ipaddrs {
+			addrs = append(addrs, Address{
+				ipaddr,
+				intAddr.Port,
+			})
+		}
 
+		if err != nil {
+			l.Debugln("Error extending lease on", natd.ID(), err)
+		}
+		return addrs, err
+	}
 	// Generate a predictable random which is based on device ID + local port + hash of the device ID
 	// number so that the ports we'd try to acquire for the mapping would always be the same for the
 	// same device trying to get the same internal port.
-	predictableRand := rand.New(rand.NewSource(int64(s.id.Short()) + int64(intPort) + hash(natd.ID())))
+	predictableRand := rand.New(rand.NewSource(int64(s.id.Short()) + int64(intAddr.Port) + hash(natd.ID())))
 
 	if extPort != 0 {
 		// First try renewing our existing mapping, if we have one.
 		name := fmt.Sprintf("syncthing-%d", extPort)
-		port, err = natd.AddPortMapping(ctx, TCP, intPort, extPort, name, leaseTime)
+		port, err = natd.AddPortMapping(ctx, TCP, intAddr.Port, extPort, name, leaseTime)
 		if err == nil {
 			extPort = port
 			goto findIP
@@ -334,32 +365,34 @@ func (s *Service) tryNATDevice(ctx context.Context, natd Device, intPort, extPor
 	for i := 0; i < 10; i++ {
 		select {
 		case <-ctx.Done():
-			return Address{}, ctx.Err()
+			return []Address{}, ctx.Err()
 		default:
 		}
 
 		// Then try up to ten random ports.
 		extPort = 1024 + predictableRand.Intn(65535-1024)
 		name := fmt.Sprintf("syncthing-%d", extPort)
-		port, err = natd.AddPortMapping(ctx, TCP, intPort, extPort, name, leaseTime)
+		port, err = natd.AddPortMapping(ctx, TCP, intAddr.Port, extPort, name, leaseTime)
 		if err == nil {
 			extPort = port
 			goto findIP
 		}
-		l.Debugln("Error getting new lease on", natd.ID(), err)
+		l.Debugf("Error getting new lease on %s: %s", natd.ID(), err)
 	}
 
-	return Address{}, err
+	return nil, err
 
 findIP:
-	ip, err := natd.GetExternalIPAddress(ctx)
+	ip, err := natd.GetExternalIPv4Address(ctx)
 	if err != nil {
-		l.Debugln("Error getting external ip on", natd.ID(), err)
+		l.Debugf("Error getting external ip on %s: %s", natd.ID(), err)
 		ip = nil
 	}
-	return Address{
-		IP:   ip,
-		Port: extPort,
+	return []Address{
+		{
+			IP:   ip,
+			Port: extPort,
+		},
 	}, nil
 }
 
@@ -372,3 +405,27 @@ func hash(input string) int64 {
 	h.Write([]byte(input))
 	return int64(h.Sum64())
 }
+
+func addrSetsEqual(a []Address, b []Address) bool {
+	if len(a) != len(b) {
+		return false
+	}
+
+	// TODO: Rewrite this using slice.Contains once Go 1.21 is the minimum Go version.
+	for _, aElem := range a {
+		aElemFound := false
+		for _, bElem := range b {
+			if bElem.Equal(aElem) {
+				aElemFound = true
+				break
+			}
+		}
+		if !aElemFound {
+			// Found element in a that is not in b.
+			return false
+		}
+	}
+
+	// b contains all elements of a and their lengths are equal, so the sets are equal.
+	return true
+}

lib/nat/structs.go

@@ -17,24 +17,25 @@ import (
 type MappingChangeSubscriber func()
 
 type Mapping struct {
-	protocol Protocol
-	address  Address
+	protocol  Protocol
+	ipVersion IPVersion
+	address   Address
 
-	extAddresses map[string]Address // NAT ID -> Address
+	extAddresses map[string][]Address // NAT ID -> Address
 	expires      time.Time
 	subscribers  []MappingChangeSubscriber
 	mut          sync.RWMutex
 }
 
-func (m *Mapping) setAddressLocked(id string, address Address) {
-	l.Infof("New NAT port mapping: external %s address %s to local address %s.", m.protocol, address, m.address)
-	m.extAddresses[id] = address
+func (m *Mapping) setAddressLocked(id string, addresses []Address) {
+	l.Infof("New external port opened: external %s address(es) %v to local address %s.", m.protocol, addresses, m.address)
+	m.extAddresses[id] = addresses
 }
 
 func (m *Mapping) removeAddressLocked(id string) {
-	addr, ok := m.extAddresses[id]
+	addresses, ok := m.extAddresses[id]
 	if ok {
-		l.Infof("Removing NAT port mapping: external %s address %s, NAT %s is no longer available.", m.protocol, addr, id)
+		l.Infof("Removing external open port: %s address(es) %v for gateway %s.", m.protocol, addresses, id)
 		delete(m.extAddresses, id)
 	}
 }
@@ -73,7 +74,7 @@ func (m *Mapping) ExternalAddresses() []Address {
 	m.mut.RLock()
 	addrs := make([]Address, 0, len(m.extAddresses))
 	for _, addr := range m.extAddresses {
-		addrs = append(addrs, addr)
+		addrs = append(addrs, addr...)
 	}
 	m.mut.RUnlock()
 	return addrs
@@ -86,7 +87,7 @@ func (m *Mapping) OnChanged(subscribed MappingChangeSubscriber) {
 }
 
 func (m *Mapping) String() string {
-	return fmt.Sprintf("%s %s", m.protocol, m.address)
+	return fmt.Sprintf("%s/%s", m.address, m.protocol)
 }
 
 func (m *Mapping) GoString() string {

lib/nat/structs_test.go

@@ -71,10 +71,10 @@ func TestMappingClearAddresses(t *testing.T) {
 	// Mock a mapped port; avoids the need to actually map a port
 	ip := net.ParseIP("192.168.0.1")
 	m := natSvc.NewMapping(TCP, ip, 1024)
-	m.extAddresses["test"] = Address{
+	m.extAddresses["test"] = []Address{{
 		IP:   ip,
 		Port: 1024,
-	}
+	}}
 	// Now try and remove the mapped port; prior to #4829 this deadlocked
 	natSvc.RemoveMapping(m)
 }