Add TURN REST format support

Author: giavac

examples/README.md

@@ -48,6 +48,18 @@ The only downside is that you can't revoke a single username/password. You need
 
 * -authSecret     : Shared secret for the Long Term Credential Mechanism
 
+#### lt-cred-turn-rest
+
+This example shows how to use ephemeral credentials, generated by a REST API, with the user part formatted as `timestamp:username`.
+
+The REST API and TURN server use the same shared secret to compute the credentials.
+
+The timestamp part specifies when the credentials will expire.
+
+This mechanism is described in https://datatracker.ietf.org/doc/html/draft-uberti-behave-turn-rest-00
+
+* -authSecret     : Shared secret for the ephemeral Credential Mechanism
+
 #### perm-filter
 
 This example demonstrates the use of a permission handler in the PION TURN server. The example implements a filtering policy that lets clients to connect back to their own host or server-reflexive address but will drop everything else. This will let the client ping-test through but will block essentially all other peer connection attempts.

examples/turn-server/lt-cred-turn-rest/main.go

@@ -0,0 +1,72 @@
+// SPDX-FileCopyrightText: 2024 The Pion community <https://pion.ly>
+// SPDX-License-Identifier: MIT
+
+// Package main implements a TURN server using
+// ephemeral credentials.
+package main
+
+import (
+	"flag"
+	"log"
+	"net"
+	"os"
+	"os/signal"
+	"strconv"
+	"syscall"
+
+	"github.com/pion/logging"
+	"github.com/pion/turn/v3"
+)
+
+func main() {
+	publicIP := flag.String("public-ip", "", "IP Address that TURN can be contacted by.")
+	port := flag.Int("port", 3478, "Listening port.")
+	authSecret := flag.String("authSecret", "", "Shared secret for the Long Term Credential Mechanism")
+	realm := flag.String("realm", "pion.ly", "Realm (defaults to \"pion.ly\")")
+	flag.Parse()
+
+	if len(*publicIP) == 0 {
+		log.Fatalf("'public-ip' is required")
+	} else if len(*authSecret) == 0 {
+		log.Fatalf("'authSecret' is required")
+	}
+
+	// Create a UDP listener to pass into pion/turn
+	// pion/turn itself doesn't allocate any UDP sockets, but lets the user pass them in
+	// this allows us to add logging, storage or modify inbound/outbound traffic
+	udpListener, err := net.ListenPacket("udp4", "0.0.0.0:"+strconv.Itoa(*port))
+	if err != nil {
+		log.Panicf("Failed to create TURN server listener: %s", err)
+	}
+
+	// NewLongTermAuthHandler takes a pion.LeveledLogger. This allows you to intercept messages
+	// and process them yourself.
+	logger := logging.NewDefaultLeveledLoggerForScope("lt-creds", logging.LogLevelTrace, os.Stdout)
+
+	s, err := turn.NewServer(turn.ServerConfig{
+		Realm:       *realm,
+		AuthHandler: turn.LongTermTURNRESTAuthHandler(*authSecret, logger),
+		// PacketConnConfigs is a list of UDP Listeners and the configuration around them
+		PacketConnConfigs: []turn.PacketConnConfig{
+			{
+				PacketConn: udpListener,
+				RelayAddressGenerator: &turn.RelayAddressGeneratorStatic{
+					RelayAddress: net.ParseIP(*publicIP), // Claim that we are listening on IP passed by user (This should be your Public IP)
+					Address:      "0.0.0.0",              // But actually be listening on every interface
+				},
+			},
+		},
+	})
+	if err != nil {
+		log.Panic(err)
+	}
+
+	// Block until user sends SIGINT or SIGTERM
+	sigs := make(chan os.Signal, 1)
+	signal.Notify(sigs, syscall.SIGINT, syscall.SIGTERM)
+	<-sigs
+
+	if err = s.Close(); err != nil {
+		log.Panic(err)
+	}
+}

lt_cred.go

@@ -9,6 +9,7 @@ import ( //nolint:gci
 	"encoding/base64"
 	"net"
 	"strconv"
+	"strings"
 	"time"
 
 	"github.com/pion/logging"
@@ -22,6 +23,15 @@ func GenerateLongTermCredentials(sharedSecret string, duration time.Duration) (s
 	return username, password, err
 }
 
+// GenerateLongTermTURNRESTCredentials can be used to create credentials valid for [duration] time
+func GenerateLongTermTURNRESTCredentials(sharedSecret string, user string, duration time.Duration) (string, string, error) {
+	t := time.Now().Add(duration).Unix()
+	timestamp := strconv.FormatInt(t, 10)
+	username := timestamp + ":" + user
+	password, err := longTermCredentials(username, sharedSecret)
+	return username, password, err
+}
+
 func longTermCredentials(username string, sharedSecret string) (string, error) {
 	mac := hmac.New(sha1.New, []byte(sharedSecret))
 	_, err := mac.Write([]byte(username))
@@ -33,7 +43,7 @@ func longTermCredentials(username string, sharedSecret string) (string, error) {
 }
 
 // NewLongTermAuthHandler returns a turn.AuthAuthHandler used with Long Term (or Time Windowed) Credentials.
-// See: https://tools.ietf.org/search/rfc5389#section-10.2
+// See: https://datatracker.ietf.org/doc/html/rfc8489#section-9.2
 func NewLongTermAuthHandler(sharedSecret string, l logging.LeveledLogger) AuthHandler {
 	if l == nil {
 		l = logging.NewDefaultLoggerFactory().NewLogger("turn")
@@ -57,3 +67,34 @@ func NewLongTermAuthHandler(sharedSecret string, l logging.LeveledLogger) AuthHa
 		return GenerateAuthKey(username, realm, password), true
 	}
 }
+
+// LongTermTURNRESTAuthHandler returns a turn.AuthAuthHandler that can be used to authenticate
+// time-windowed ephemeral credentials generated by the TURN REST API as described in
+// https://datatracker.ietf.org/doc/html/draft-uberti-behave-turn-rest-00
+//
+// The supported format of is timestamp:username, where username is an arbitrary user id and the
+// timestamp specifies the expiry of the credential.
+func LongTermTURNRESTAuthHandler(sharedSecret string, l logging.LeveledLogger) AuthHandler {
+	if l == nil {
+		l = logging.NewDefaultLoggerFactory().NewLogger("turn")
+	}
+	return func(username, realm string, srcAddr net.Addr) (key []byte, ok bool) {
+		l.Tracef("Authentication username=%q realm=%q srcAddr=%v\n", username, realm, srcAddr)
+		timestamp := strings.Split(username, ":")[0]
+		t, err := strconv.Atoi(timestamp)
+		if err != nil {
+			l.Errorf("Invalid time-windowed username %q", username)
+			return nil, false
+		}
+		if int64(t) < time.Now().Unix() {
+			l.Errorf("Expired time-windowed username %q", username)
+			return nil, false
+		}
+		password, err := longTermCredentials(username, sharedSecret)
+		if err != nil {
+			l.Error(err.Error())
+			return nil, false
+		}
+		return GenerateAuthKey(username, realm, password), true
+	}
+}

lt_cred_test.go

@@ -75,3 +75,51 @@ func TestNewLongTermAuthHandler(t *testing.T) {
 	assert.NoError(t, conn.Close())
 	assert.NoError(t, server.Close())
 }
+
+func TestLongTermTURNRESTAuthHandler(t *testing.T) {
+	const sharedSecret = "HELLO_WORLD"
+
+	serverListener, err := net.ListenPacket("udp4", "0.0.0.0:3478")
+	assert.NoError(t, err)
+
+	server, err := NewServer(ServerConfig{
+		AuthHandler: LongTermTURNRESTAuthHandler(sharedSecret, nil),
+		PacketConnConfigs: []PacketConnConfig{
+			{
+				PacketConn: serverListener,
+				RelayAddressGenerator: &RelayAddressGeneratorStatic{
+					RelayAddress: net.ParseIP("127.0.0.1"),
+					Address:      "0.0.0.0",
+				},
+			},
+		},
+		Realm:         "pion.ly",
+		LoggerFactory: logging.NewDefaultLoggerFactory(),
+	})
+	assert.NoError(t, err)
+
+	conn, err := net.ListenPacket("udp4", "0.0.0.0:0")
+	assert.NoError(t, err)
+
+	username, password, err := GenerateLongTermTURNRESTCredentials(sharedSecret, "testuser", time.Minute)
+	assert.NoError(t, err)
+
+	client, err := NewClient(&ClientConfig{
+		STUNServerAddr: "0.0.0.0:3478",
+		TURNServerAddr: "0.0.0.0:3478",
+		Conn:           conn,
+		Username:       username,
+		Password:       password,
+		LoggerFactory:  logging.NewDefaultLoggerFactory(),
+	})
+	assert.NoError(t, err)
+	assert.NoError(t, client.Listen())
+
+	relayConn, err := client.Allocate()
+	assert.NoError(t, err)
+
+	client.Close()
+	assert.NoError(t, relayConn.Close())
+	assert.NoError(t, conn.Close())
+	assert.NoError(t, server.Close())
+}