RFC 6156: TURN Extension for IPv6

This PR implements RFC 6156: Traversal Using Relays around NAT
(TURN) Extension for IPv6 enabling UDP and TCP relay allocations
on IPv6 addresses.

Author: adrianosela

README.md

@@ -71,8 +71,6 @@ Yes.
 * **RFC 5389**: [Session Traversal Utilities for NAT (STUN)][rfc5389]
 * **RFC 5766**: [Traversal Using Relays around NAT (TURN): Relay Extensions to Session Traversal Utilities for NAT (STUN)][rfc5766]
 * **RFC 6062**: [Traversal Using Relays around NAT (TURN) Extensions for TCP Allocations][rfc6062]
-
-#### Planned
 * **RFC 6156**: [Traversal Using Relays around NAT (TURN) Extension for IPv6][rfc6156]
 
 [rfc5389]: https://tools.ietf.org/html/rfc5389

addr_family.go

@@ -0,0 +1,16 @@
+// SPDX-FileCopyrightText: 2026 The Pion community <https://pion.ly>
+// SPDX-License-Identifier: MIT
+
+package turn
+
+import "github.com/pion/turn/v4/internal/proto"
+
+// RequestedAddressFamily represents the REQUESTED-ADDRESS-FAMILY Attribute as
+// defined in RFC 6156 Section 4.1.1.
+type RequestedAddressFamily = proto.RequestedAddressFamily
+
+// Values for RequestedAddressFamily as defined in RFC 6156 Section 4.1.1.
+const (
+	RequestedAddressFamilyIPv4 = proto.RequestedFamilyIPv4
+	RequestedAddressFamilyIPv6 = proto.RequestedFamilyIPv6
+)

client.go

@@ -51,6 +51,11 @@ type ClientConfig struct {
 	// PermissionTimeout sets the refresh interval of permissions. Defaults to 2 minutes.
 	PermissionRefreshInterval time.Duration
 
+	// RequestedAddressFamily is the address family to request in allocations (IPv4 or IPv6).
+	// If not specified (zero value), the client will attempt to infer from the PacketConn's
+	// local address, falling back to IPv4 if inference fails. See RFC 6156.
+	RequestedAddressFamily RequestedAddressFamily
+
 	evenPort               bool   // If EVEN-PORT Attribute should be sent in Allocation
 	reservationToken       []byte // If Server responds with RESERVATION-TOKEN or if Client wishes to send one
 	bindingRefreshInterval time.Duration
@@ -79,16 +84,76 @@ type Client struct {
 	mutexTrMap    sync.Mutex             // Thread-safe
 	log           logging.LeveledLogger  // Read-only
 
-	evenPort                  bool   // If EVEN-PORT Attribute should be sent in Allocation
-	reservationToken          []byte // If Server responds with RESERVATION-TOKEN or if Client wishes to send one
+	// If EVEN-PORT Attribute should be sent in Allocation
+	evenPort bool
+
+	// If Server responds with RESERVATION-TOKEN or if Client wishes to send one
+	reservationToken []byte
+
+	// REQUESTED-ADDRESS-FAMILY attribute for allocations (RFC 6156)
+	requestedAddressFamily proto.RequestedAddressFamily
+
 	permissionRefreshInterval time.Duration
 	bindingRefreshInterval    time.Duration
 	bindingCheckInterval      time.Duration
 }
 
+// inferAddressFamilyFromConn attempts to determine the address
+// family (IPv4 or IPv6) from a PacketConn's local address.
+// Returns an error if the address type is not IP-based.
+func inferAddressFamilyFromConn(
+	conn net.PacketConn,
+) (proto.RequestedAddressFamily, error) {
+	addr := conn.LocalAddr()
+
+	switch a := addr.(type) {
+	case *net.UDPAddr:
+		if a.IP.To4() != nil {
+			return proto.RequestedFamilyIPv4, nil
+		}
+
+		return proto.RequestedFamilyIPv6, nil
+	case *net.TCPAddr:
+		if a.IP.To4() != nil {
+			return proto.RequestedFamilyIPv4, nil
+		}
+
+		return proto.RequestedFamilyIPv6, nil
+	default:
+		return 0, fmt.Errorf("cannot infer address family from %T", addr) //nolint:err113
+	}
+}
+
+// getRequestedAddressFamily determines the address family to use
+// for TURN allocations. It follows this priority:
+//  1. Use explicitly configured RequestedAddressFamily if set
+//  2. Try to infer from the PacketConn's local address
+//  3. Fall back to IPv4 default per RFC 6156
+func getRequestedAddressFamily(
+	log logging.LeveledLogger,
+	config *ClientConfig,
+) proto.RequestedAddressFamily {
+	// If explicitly set, use it
+	if config.RequestedAddressFamily != 0 {
+		return config.RequestedAddressFamily
+	}
+
+	// Try to infer from the PacketConn
+	if inferred, err := inferAddressFamilyFromConn(config.Conn); err == nil {
+		log.Debugf("Inferred address family %v from connection", inferred)
+
+		return inferred
+	}
+
+	log.Debugf("Could not infer address family, defaulting to IPv4")
+
+	// Default to IPv4 per RFC 6156
+	return proto.RequestedFamilyIPv4
+}
+
 // NewClient returns a new Client instance. listeningAddress is the address and port to listen on,
 // default "0.0.0.0:0".
-func NewClient(config *ClientConfig) (*Client, error) {
+func NewClient(config *ClientConfig) (*Client, error) { //nolint:gocyclo,cyclop
 	loggerFactory := config.LoggerFactory
 	if loggerFactory == nil {
 		loggerFactory = logging.NewDefaultLoggerFactory()
@@ -113,11 +178,14 @@ func NewClient(config *ClientConfig) (*Client, error) {
 		config.Net = n
 	}
 
+	// Determine the requested address family (RFC 6156)
+	requestedAddressFamily := getRequestedAddressFamily(log, config)
+
 	var stunServ, turnServ net.Addr
 	var err error
 
 	if len(config.STUNServerAddr) > 0 {
-		stunServ, err = config.Net.ResolveUDPAddr("udp4", config.STUNServerAddr)
+		stunServ, err = config.Net.ResolveUDPAddr("udp", config.STUNServerAddr)
 		if err != nil {
 			return nil, err
 		}
@@ -126,7 +194,7 @@ func NewClient(config *ClientConfig) (*Client, error) {
 	}
 
 	if len(config.TURNServerAddr) > 0 {
-		turnServ, err = config.Net.ResolveUDPAddr("udp4", config.TURNServerAddr)
+		turnServ, err = config.Net.ResolveUDPAddr("udp", config.TURNServerAddr)
 		if err != nil {
 			return nil, err
 		}
@@ -148,6 +216,7 @@ func NewClient(config *ClientConfig) (*Client, error) {
 		log:                       log,
 		evenPort:                  config.evenPort,
 		reservationToken:          config.reservationToken,
+		requestedAddressFamily:    requestedAddressFamily,
 		permissionRefreshInterval: config.PermissionRefreshInterval,
 		bindingRefreshInterval:    config.bindingRefreshInterval,
 		bindingCheckInterval:      config.bindingCheckInterval,
@@ -272,11 +341,14 @@ func (c *Client) sendAllocateRequest(protocol proto.Protocol) ( //nolint:cyclop
 		proto.RequestedTransport{Protocol: protocol},
 		stun.Fingerprint,
 	}
-	if c.evenPort {
-		allocationSetters = append(allocationSetters, proto.EvenPort{ReservePort: true})
-	}
+	// RFC 6156: REQUESTED-ADDRESS-FAMILY and RESERVATION-TOKEN are mutually exclusive.
 	if len(c.reservationToken) != 0 {
 		allocationSetters = append(allocationSetters, proto.ReservationToken(c.reservationToken))
+	} else {
+		allocationSetters = append(allocationSetters, c.requestedAddressFamily)
+	}
+	if c.evenPort {
+		allocationSetters = append(allocationSetters, proto.EvenPort{ReservePort: true})
 	}
 
 	msg, err := stun.Build(allocationSetters...)
@@ -313,11 +385,14 @@ func (c *Client) sendAllocateRequest(protocol proto.Protocol) ( //nolint:cyclop
 		&c.integrity,
 		stun.Fingerprint,
 	}
-	if c.evenPort {
-		allocationSetters = append(allocationSetters, proto.EvenPort{ReservePort: true})
-	}
+	// RFC 6156: REQUESTED-ADDRESS-FAMILY and RESERVATION-TOKEN are mutually exclusive.
 	if len(c.reservationToken) != 0 {
 		allocationSetters = append(allocationSetters, proto.ReservationToken(c.reservationToken))
+	} else {
+		allocationSetters = append(allocationSetters, c.requestedAddressFamily)
+	}
+	if c.evenPort {
+		allocationSetters = append(allocationSetters, proto.EvenPort{ReservePort: true})
 	}
 
 	msg, err = stun.Build(allocationSetters...)

client_test.go

@@ -698,6 +698,92 @@ func TestTCPClientMultipleConns(t *testing.T) {
 	assert.NoError(t, clientConn.Close())
 }
 
+func TestInferAddressFamilyFromConn(t *testing.T) {
+	t.Run("IPv4 UDP connection", func(t *testing.T) {
+		conn, err := net.ListenPacket("udp4", "0.0.0.0:0") //nolint:noctx
+		assert.NoError(t, err)
+		defer conn.Close() //nolint:errcheck
+
+		family, err := inferAddressFamilyFromConn(conn)
+		assert.NoError(t, err)
+		assert.Equal(t, proto.RequestedFamilyIPv4, family)
+	})
+
+	t.Run("IPv6 UDP connection", func(t *testing.T) {
+		conn, err := net.ListenPacket("udp6", "[::]:0") //nolint:noctx
+		assert.NoError(t, err)
+		defer conn.Close() //nolint:errcheck
+
+		family, err := inferAddressFamilyFromConn(conn)
+		assert.NoError(t, err)
+		assert.Equal(t, proto.RequestedFamilyIPv6, family)
+	})
+}
+
+func TestGetRequestedAddressFamily(t *testing.T) {
+	log := logging.NewDefaultLoggerFactory().NewLogger("test")
+
+	t.Run("Explicit IPv4 in config", func(t *testing.T) {
+		conn, err := net.ListenPacket("udp6", "[::]:0") //nolint:noctx
+		assert.NoError(t, err)
+		defer conn.Close() //nolint:errcheck
+
+		config := &ClientConfig{
+			Conn:                   conn,
+			RequestedAddressFamily: proto.RequestedFamilyIPv4,
+		}
+
+		// Should use explicit config even though conn is IPv6
+		family := getRequestedAddressFamily(log, config)
+		assert.Equal(t, proto.RequestedFamilyIPv4, family)
+	})
+
+	t.Run("Explicit IPv6 in config", func(t *testing.T) {
+		conn, err := net.ListenPacket("udp4", "0.0.0.0:0") //nolint:noctx
+		assert.NoError(t, err)
+		defer conn.Close() //nolint:errcheck
+
+		config := &ClientConfig{
+			Conn:                   conn,
+			RequestedAddressFamily: proto.RequestedFamilyIPv6,
+		}
+
+		// Should use explicit config even though conn is IPv4
+		family := getRequestedAddressFamily(log, config)
+		assert.Equal(t, proto.RequestedFamilyIPv6, family)
+	})
+
+	t.Run("Infer IPv4 from connection", func(t *testing.T) {
+		conn, err := net.ListenPacket("udp4", "0.0.0.0:0") //nolint:noctx
+		assert.NoError(t, err)
+		defer conn.Close() //nolint:errcheck
+
+		config := &ClientConfig{
+			Conn: conn,
+			// RequestedAddressFamily not set (zero value)
+		}
+
+		// Should infer IPv4 from connection
+		family := getRequestedAddressFamily(log, config)
+		assert.Equal(t, proto.RequestedFamilyIPv4, family)
+	})
+
+	t.Run("Infer IPv6 from connection", func(t *testing.T) {
+		conn, err := net.ListenPacket("udp6", "[::]:0") //nolint:noctx
+		assert.NoError(t, err)
+		defer conn.Close() //nolint:errcheck
+
+		config := &ClientConfig{
+			Conn: conn,
+			// RequestedAddressFamily not set (zero value)
+		}
+
+		// Should infer IPv6 from connection
+		family := getRequestedAddressFamily(log, config)
+		assert.Equal(t, proto.RequestedFamilyIPv6, family)
+	})
+}
+
 type channelBindFilterConn struct {
 	net.PacketConn
 

examples/README.md

@@ -103,6 +103,28 @@ This example demonstrates listening on TLS. You could combine this
 example with `simple` and you will have a Pion TURN instance that is
 available via TLS and UDP.
 
+#### ipv6 (server)
+
+This example demonstrates a TURN server with IPv6 support (RFC 6156).
+The server listens on all IPv6 interfaces (`[::]`) and allocates IPv6
+relay addresses to clients that request them.
+
+``` sh
+$ cd ipv6
+$ go build
+$ ./ipv6 -public-ip 2001:db8::1 -users username=password
+```
+
+For local testing with IPv6 localhost:
+
+``` sh
+$ ./ipv6 -public-ip ::1 -users username=password
+```
+
+This example shows how to configure a TURN server for IPv6 clients,
+which is essential for environments where IPv4 addresses are limited or
+IPv6-only networks.
+
 #### lt-creds
 
 This example shows how to use long term credentials. You can issue
@@ -172,6 +194,33 @@ $ go build
 ./turn-client -host <turn-server-name> -user=user=pass -ping
 ```
 
+#### ipv6 (client)
+
+Dials the requested TURN server via IPv6 (RFC 6156). This example
+demonstrates how to request IPv6 relay allocations from a TURN server.
+
+``` sh
+$ cd ipv6
+$ go build
+$ ./ipv6 -host 2001:db8::1 -user username=password
+```
+
+For local testing with IPv6 localhost:
+
+``` sh
+$ ./ipv6 -host ::1 -user username=password
+```
+
+With `-ping`, it will perform a ping test over IPv6:
+
+``` sh
+$ ./ipv6 -host ::1 -user username=password -ping
+```
+
+This client sets `RequestedAddressFamily` to `proto.RequestedFamilyIPv6`
+to request an IPv6 relay allocation. The server must support IPv6 and be
+configured to listen on IPv6 addresses.
+
 Following diagram shows what turn-client does:
 
               +----------------+