turn

package module
v4.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 12, 2024 License: MIT Imports: 22 Imported by: 9

README

Pion TURN
Pion TURN

A toolkit for building TURN clients and servers in Go

Pion TURN Slack Widget
GitHub Workflow Status Go Reference Coverage Status Go Report Card


Pion TURN is a Go toolkit for building TURN servers and clients. We wrote it to solve problems we had when building RTC projects.

  • Deployable - Use modern tooling of the Go ecosystem. Stop generating config files.
  • Embeddable - Include pion/turn in your existing applications. No need to manage another service.
  • Extendable - TURN as an API so you can easily integrate with your existing monitoring and metrics.
  • Maintainable - pion/turn is simple and well documented. Designed for learning and easy debugging.
  • Portable - Quickly deploy to multiple architectures/platforms just by setting an environment variable.
  • Safe - Stability and safety is important for network services. Go provides everything we need.
  • Scalable - Create allocations and mutate state at runtime. Designed to make scaling easy.

Using

pion/turn is an API for building STUN/TURN clients and servers, not a binary you deploy then configure. It may require copying our examples and making minor modifications to fit your need, no knowledge of Go is required however. You may be able to download the pre-made binaries of our examples if you wish to get started quickly.

The advantage of this is that you don't need to deal with complicated config files, or custom APIs to modify the state of Pion TURN. After you instantiate an instance of a Pion TURN server or client you interact with it like any library. The quickest way to get started is to look at the examples or GoDoc

Examples

We try to cover most common use cases in examples. If more examples could be helpful please file an issue, we are always looking to expand and improve pion/turn to make it easier for developers.

To build any example you just need to run go build in the directory of the example you care about. It is also very easy to cross compile Go programs.

You can also see pion/turn usage in pion/ice

FAQ

Also take a look at the Pion WebRTC FAQ

Will pion/turn also act as a STUN server?

Yes.

How do I implement token-based authentication?

Replace the username with a token in the AuthHandler. The password sent by the client can be any non-empty string, as long as it matches that used by the GenerateAuthKey function.

Will WebRTC prioritize using STUN over TURN?

Yes.

RFCs

Implemented

Planned

Roadmap

The library is used as a part of our WebRTC implementation. Please refer to that roadmap to track our major milestones.

Community

Pion has an active community on the Slack.

Follow the Pion Twitter for project updates and important WebRTC news.

We are always looking to support your projects. Please reach out if you have something to build! If you need commercial support or don't want to use public methods you can contact us at team@pion.ly

Contributing

Check out the contributing wiki to join the group of amazing people making this project possible

License

MIT License - see LICENSE for full text

Documentation

Overview

Package turn contains the public API for pion/turn, a toolkit for building TURN clients and servers

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DefaultPermissionHandler 

func DefaultPermissionHandler(net.Addr, net.IP) (ok bool)

DefaultPermissionHandler is convince function that grants permission to all peers

func GenerateAuthKey 

func GenerateAuthKey(username, realm, password string) []byte

GenerateAuthKey is a convenience function to easily generate keys in the format used by AuthHandler

func GenerateLongTermCredentials 

func GenerateLongTermCredentials(sharedSecret string, duration time.Duration) (string, string, error)

GenerateLongTermCredentials can be used to create credentials valid for [duration] time

func GenerateLongTermTURNRESTCredentials 

func GenerateLongTermTURNRESTCredentials(sharedSecret string, user string, duration time.Duration) (string, string, error)

GenerateLongTermTURNRESTCredentials can be used to create credentials valid for [duration] time

Types

type AuthHandler 

type AuthHandler func(username, realm string, srcAddr net.Addr) (key []byte, ok bool)

AuthHandler is a callback used to handle incoming auth requests, allowing users to customize Pion TURN with custom behavior

func LongTermTURNRESTAuthHandler 

func LongTermTURNRESTAuthHandler(sharedSecret string, l logging.LeveledLogger) AuthHandler

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 NewLongTermAuthHandler 

func NewLongTermAuthHandler(sharedSecret string, l logging.LeveledLogger) AuthHandler

NewLongTermAuthHandler returns a turn.AuthAuthHandler used with Long Term (or Time Windowed) Credentials. See: https://datatracker.ietf.org/doc/html/rfc8489#section-9.2

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is a STUN server client

func NewClient 

func NewClient(config *ClientConfig) (*Client, error)

NewClient returns a new Client instance. listeningAddress is the address and port to listen on, default "0.0.0.0:0"

func (*Client) Allocate 

func (c *Client) Allocate() (net.PacketConn, error)

Allocate sends a TURN allocation request to the given transport address

func (*Client) AllocateTCP 

func (c *Client) AllocateTCP() (*client.TCPAllocation, error)

AllocateTCP creates a new TCP allocation at the TURN server.

func (*Client) Close 

func (c *Client) Close()

Close closes this client

func (*Client) CreatePermission 

func (c *Client) CreatePermission(addrs ...net.Addr) error

CreatePermission Issues a CreatePermission request for the supplied addresses as described in https://datatracker.ietf.org/doc/html/rfc5766#section-9

func (*Client) HandleInbound 

func (c *Client) HandleInbound(data []byte, from net.Addr) (bool, error)

HandleInbound handles data received. This method handles incoming packet de-multiplex it by the source address and the types of the message. This return a boolean (handled or not) and if there was an error. Caller should check if the packet was handled by this client or not. If not handled, it is assumed that the packet is application data. If an error is returned, the caller should discard the packet regardless.

func (*Client) Listen 

func (c *Client) Listen() error

Listen will have this client start listening on the conn provided via the config. This is optional. If not used, you will need to call HandleInbound method to supply incoming data, instead.

func (*Client) OnDeallocated 

func (c *Client) OnDeallocated(net.Addr)

OnDeallocated is called when de-allocation of relay address has been complete. (Called by UDPConn)

func (*Client) PerformTransaction 

func (c *Client) PerformTransaction(msg *stun.Message, to net.Addr, ignoreResult bool) (client.TransactionResult,
	error,
)

PerformTransaction performs STUN transaction

func (*Client) Realm 

func (c *Client) Realm() stun.Realm

Realm return realm

func (*Client) STUNServerAddr 

func (c *Client) STUNServerAddr() net.Addr

STUNServerAddr return the STUN server address

func (*Client) SendBindingRequest 

func (c *Client) SendBindingRequest() (net.Addr, error)

SendBindingRequest sends a new STUN request to the STUN server

func (*Client) SendBindingRequestTo 

func (c *Client) SendBindingRequestTo(to net.Addr) (net.Addr, error)

SendBindingRequestTo sends a new STUN request to the given transport address

func (*Client) TURNServerAddr 

func (c *Client) TURNServerAddr() net.Addr

TURNServerAddr return the TURN server address

func (*Client) Username 

func (c *Client) Username() stun.Username

Username returns username

func (*Client) WriteTo 

func (c *Client) WriteTo(data []byte, to net.Addr) (int, error)

WriteTo sends data to the specified destination using the base socket.

type ClientConfig 

type ClientConfig struct {
	STUNServerAddr string // STUN server address (e.g. "stun.abc.com:3478")
	TURNServerAddr string // TURN server address (e.g. "turn.abc.com:3478")
	Username       string
	Password       string
	Realm          string
	Software       string
	RTO            time.Duration
	Conn           net.PacketConn // Listening socket (net.PacketConn)
	Net            transport.Net
	LoggerFactory  logging.LoggerFactory
}

ClientConfig is a bag of config parameters for Client.

type ListenerConfig 

type ListenerConfig struct {
	Listener net.Listener

	// When an allocation is generated the RelayAddressGenerator
	// creates the net.PacketConn and returns the IP/Port it is available at
	RelayAddressGenerator RelayAddressGenerator

	// PermissionHandler is a callback to filter peer addresses. Can be set as nil, in which
	// case the DefaultPermissionHandler is automatically instantiated to admit all peer
	// connections
	PermissionHandler PermissionHandler
}

ListenerConfig is a single net.Listener to accept connections on. This will be used for TCP, TLS and DTLS listeners

type PacketConnConfig 

type PacketConnConfig struct {
	PacketConn net.PacketConn

	// When an allocation is generated the RelayAddressGenerator
	// creates the net.PacketConn and returns the IP/Port it is available at
	RelayAddressGenerator RelayAddressGenerator

	// PermissionHandler is a callback to filter peer addresses. Can be set as nil, in which
	// case the DefaultPermissionHandler is automatically instantiated to admit all peer
	// connections
	PermissionHandler PermissionHandler
}

PacketConnConfig is a single net.PacketConn to listen/write on. This will be used for UDP listeners

type PermissionHandler 

type PermissionHandler func(clientAddr net.Addr, peerIP net.IP) (ok bool)

PermissionHandler is a callback to filter incoming CreatePermission and ChannelBindRequest requests based on the client IP address and port and the peer IP address the client intends to connect to. If the client is behind a NAT then the filter acts on the server reflexive ("mapped") address instead of the real client IP address and port. Note that TURN permissions are per-allocation and per-peer-IP-address, to mimic the address-restricted filtering mechanism of NATs that comply with [RFC4787], see https://tools.ietf.org/html/rfc5766#section-2.3.

type RelayAddressGenerator 

type RelayAddressGenerator interface {
	// Validate confirms that the RelayAddressGenerator is properly initialized
	Validate() error

	// Allocate a PacketConn (UDP) RelayAddress
	AllocatePacketConn(network string, requestedPort int) (net.PacketConn, net.Addr, error)

	// Allocate a Conn (TCP) RelayAddress
	AllocateConn(network string, requestedPort int) (net.Conn, net.Addr, error)
}

RelayAddressGenerator is used to generate a RelayAddress when creating an allocation. You can use one of the provided ones or provide your own.

type RelayAddressGeneratorNone 

type RelayAddressGeneratorNone struct {
	// Address is passed to Listen/ListenPacket when creating the Relay
	Address string

	Net transport.Net
}

RelayAddressGeneratorNone returns the listener with no modifications

func (*RelayAddressGeneratorNone) AllocateConn 

func (r *RelayAddressGeneratorNone) AllocateConn(string, int) (net.Conn, net.Addr, error)

AllocateConn generates a new Conn to receive traffic on and the IP/Port to populate the allocation response with

func (*RelayAddressGeneratorNone) AllocatePacketConn 

func (r *RelayAddressGeneratorNone) AllocatePacketConn(network string, requestedPort int) (net.PacketConn, net.Addr, error)

AllocatePacketConn generates a new PacketConn to receive traffic on and the IP/Port to populate the allocation response with

func (*RelayAddressGeneratorNone) Validate 

func (r *RelayAddressGeneratorNone) Validate() error

Validate is called on server startup and confirms the RelayAddressGenerator is properly configured

type RelayAddressGeneratorPortRange 

type RelayAddressGeneratorPortRange struct {
	// RelayAddress is the IP returned to the user when the relay is created
	RelayAddress net.IP

	// MinPort the minimum port to allocate
	MinPort uint16
	// MaxPort the maximum (inclusive) port to allocate
	MaxPort uint16

	// MaxRetries the amount of tries to allocate a random port in the defined range
	MaxRetries int

	// Rand the random source of numbers
	Rand randutil.MathRandomGenerator

	// Address is passed to Listen/ListenPacket when creating the Relay
	Address string

	Net transport.Net
}

RelayAddressGeneratorPortRange can be used to only allocate connections inside a defined port range. Similar to the RelayAddressGeneratorStatic a static ip address can be set.

func (*RelayAddressGeneratorPortRange) AllocateConn 

func (r *RelayAddressGeneratorPortRange) AllocateConn(string, int) (net.Conn, net.Addr, error)

AllocateConn generates a new Conn to receive traffic on and the IP/Port to populate the allocation response with

func (*RelayAddressGeneratorPortRange) AllocatePacketConn 

func (r *RelayAddressGeneratorPortRange) AllocatePacketConn(network string, requestedPort int) (net.PacketConn, net.Addr, error)

AllocatePacketConn generates a new PacketConn to receive traffic on and the IP/Port to populate the allocation response with

func (*RelayAddressGeneratorPortRange) Validate 

func (r *RelayAddressGeneratorPortRange) Validate() error

Validate is called on server startup and confirms the RelayAddressGenerator is properly configured

type RelayAddressGeneratorStatic 

type RelayAddressGeneratorStatic struct {
	// RelayAddress is the IP returned to the user when the relay is created
	RelayAddress net.IP

	// Address is passed to Listen/ListenPacket when creating the Relay
	Address string

	Net transport.Net
}

RelayAddressGeneratorStatic can be used to return static IP address each time a relay is created. This can be used when you have a single static IP address that you want to use

func (*RelayAddressGeneratorStatic) AllocateConn 

func (r *RelayAddressGeneratorStatic) AllocateConn(string, int) (net.Conn, net.Addr, error)

AllocateConn generates a new Conn to receive traffic on and the IP/Port to populate the allocation response with

func (*RelayAddressGeneratorStatic) AllocatePacketConn 

func (r *RelayAddressGeneratorStatic) AllocatePacketConn(network string, requestedPort int) (net.PacketConn, net.Addr, error)

AllocatePacketConn generates a new PacketConn to receive traffic on and the IP/Port to populate the allocation response with

func (*RelayAddressGeneratorStatic) Validate 

func (r *RelayAddressGeneratorStatic) Validate() error

Validate is called on server startup and confirms the RelayAddressGenerator is properly configured

type STUNConn 

type STUNConn struct {
	// contains filtered or unexported fields
}

STUNConn wraps a net.Conn and implements net.PacketConn by being STUN aware and packetizing the stream

func NewSTUNConn 

func NewSTUNConn(nextConn net.Conn) *STUNConn

NewSTUNConn creates a STUNConn

func (*STUNConn) Close 

func (s *STUNConn) Close() error

Close implements Close from net.PacketConn

func (*STUNConn) LocalAddr 

func (s *STUNConn) LocalAddr() net.Addr

LocalAddr implements LocalAddr from net.PacketConn

func (*STUNConn) ReadFrom 

func (s *STUNConn) ReadFrom(p []byte) (n int, addr net.Addr, err error)

ReadFrom implements ReadFrom from net.PacketConn

func (*STUNConn) SetDeadline 

func (s *STUNConn) SetDeadline(t time.Time) error

SetDeadline implements SetDeadline from net.PacketConn

func (*STUNConn) SetReadDeadline 

func (s *STUNConn) SetReadDeadline(t time.Time) error

SetReadDeadline implements SetReadDeadline from net.PacketConn

func (*STUNConn) SetWriteDeadline 

func (s *STUNConn) SetWriteDeadline(t time.Time) error

SetWriteDeadline implements SetWriteDeadline from net.PacketConn

func (*STUNConn) WriteTo 

func (s *STUNConn) WriteTo(p []byte, _ net.Addr) (n int, err error)

WriteTo implements WriteTo from net.PacketConn

type Server 

type Server struct {
	// contains filtered or unexported fields
}

Server is an instance of the Pion TURN Server

func NewServer 

func NewServer(config ServerConfig) (*Server, error)

NewServer creates the Pion TURN server

func (*Server) AllocationCount 

func (s *Server) AllocationCount() int

AllocationCount returns the number of active allocations. It can be used to drain the server before closing

func (*Server) Close 

func (s *Server) Close() error

Close stops the TURN Server. It cleans up any associated state and closes all connections it is managing

type ServerConfig 

type ServerConfig struct {
	// PacketConnConfigs and ListenerConfigs are a list of all the turn listeners
	// Each listener can have custom behavior around the creation of Relays
	PacketConnConfigs []PacketConnConfig
	ListenerConfigs   []ListenerConfig

	// LoggerFactory must be set for logging from this server.
	LoggerFactory logging.LoggerFactory

	// Realm sets the realm for this server
	Realm string

	// AuthHandler is a callback used to handle incoming auth requests, allowing users to customize Pion TURN with custom behavior
	AuthHandler AuthHandler

	// ChannelBindTimeout sets the lifetime of channel binding. Defaults to 10 minutes.
	ChannelBindTimeout time.Duration

	// Sets the server inbound MTU(Maximum transmition unit). Defaults to 1600 bytes.
	InboundMTU int
}

ServerConfig configures the Pion TURN Server

Source Files

View all Source files

Directories

Path Synopsis
examples
lt-cred-generator
Package main implements a CLI tool for generating long-term credentials.
 Package main implements a CLI tool for generating long-term credentials.
stun-only-server
Package main implements a simple TURN server
 Package main implements a simple TURN server
turn-client/tcp
Package main implements a TURN client with support for TCP
 Package main implements a TURN client with support for TCP
turn-client/tcp-alloc
Package main implements a TURN client with support for TCP
 Package main implements a TURN client with support for TCP
turn-client/udp
Package main implements a TURN client using UDP
 Package main implements a TURN client using UDP
turn-server/add-software-attribute
Package main implements a TURN server adding a software attribute.
 Package main implements a TURN server adding a software attribute.
turn-server/log
Package main implements a TURN server with logging.
 Package main implements a TURN server with logging.
turn-server/lt-cred
Package main implements a TURN server using long-term credentials.
 Package main implements a TURN server using long-term credentials.
turn-server/lt-cred-turn-rest
Package main implements a TURN server using ephemeral credentials.
 Package main implements a TURN server using ephemeral credentials.
turn-server/perm-filter
This example demonstrates the use of a permission handler in the PION TURN server.
 This example demonstrates the use of a permission handler in the PION TURN server.
turn-server/port-range
Package main implements a TURN server with a specified port range.
 Package main implements a TURN server with a specified port range.
turn-server/simple
Package main implements a simple TURN server
 Package main implements a simple TURN server
turn-server/simple-multithreaded
Package main implements a multi-threaded TURN server
 Package main implements a multi-threaded TURN server
turn-server/tcp
Package main implements an example TURN server supporting TCP
 Package main implements an example TURN server supporting TCP
turn-server/tls
Package main implements a TURN server with TLS support
 Package main implements a TURN server with TLS support
internal
allocation
Package allocation contains all CRUD operations for allocations
 Package allocation contains all CRUD operations for allocations
client
Package client implements the API for a TURN client
 Package client implements the API for a TURN client
ipnet
Package ipnet contains helper functions around net and IP
 Package ipnet contains helper functions around net and IP
proto
Package proto implements RFC 5766 Traversal Using Relays around NAT.
 Package proto implements RFC 5766 Traversal Using Relays around NAT.
server
Package server implements the private API to implement a TURN server
 Package server implements the private API to implement a TURN server

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.