TURN module (rfc5766)

IAllocation

Base class for TURN relay allocations shared by client and server flows.

IAllocation

#include <icy/turn/iallocation.h>

Subclassed by: Client, ServerAllocation

Base class for TURN relay allocations shared by client and server flows.

All TURN operations revolve around allocations, and all TURN messages are associated with an allocation. An allocation conceptually consists of:

the relayed transport address;
the 5-tuple: client's IP address, client's port, server IP address, server port, and transport protocol;
the authentication information;
the time-to-expiry;
a list of permissions;
a list of channel-to-peer bindings.

The relayed transport address is the transport address allocated by the server for communicating with peers, while the 5-tuple describes the communication path between the client and the server. On the client, the 5-tuple uses the client's host transport address; on the server, the 5-tuple uses the client's server-reflexive transport address.

Both the relayed transport address and the 5-tuple must be unique across all allocations, so either one can be used to uniquely identify the allocation.

The authentication information, such as username, password, realm, and nonce, is used to verify subsequent requests and compute the message integrity of responses. The username, realm, and nonce values are initially those used in the authenticated Allocate request that creates the allocation, though the server can change the nonce during the allocation lifetime using a 438 (Stale Nonce) reply. Rather than storing the password explicitly, a server may prefer to store the key value, which is an MD5 hash over the username, realm, and password as described by RFC 5389.

The time-to-expiry is the time left until the allocation expires. Each Allocate or Refresh transaction resets this timer, which then ticks down toward zero. By default, each Allocate or Refresh resets the lifetime to 600 seconds (10 minutes), but the client can request a different value in the Allocate and Refresh requests. Allocations can only be refreshed using Refresh; sending data to a peer does not refresh an allocation. When an allocation expires, the state data associated with it can be freed.

Public Methods

Return	Name	Description
	`IAllocation`	#### Parameters
	`IAllocation`	Deleted constructor.
	`IAllocation`	Deleted constructor.
`void`	`updateUsage` `virtual`	Updates the last-activity timestamp and accumulates bandwidth usage. Call this whenever data is relayed through the allocation.
`void`	`setLifetime` `virtual`	Sets the allocation lifetime in seconds and resets the activity timestamp, effectively extending the expiry from the current moment.
`void`	`setBandwidthLimit` `virtual`	Sets the maximum number of bytes this allocation may relay in its lifetime. Pass 0 to disable bandwidth limiting.
`bool`	`expired` `virtual` `const`	#### Returns
`bool`	`deleted` `virtual` `const`	Returns true if the allocation's deleted flag is set and or if the allocation has expired.
`std::int64_t`	`bandwidthLimit` `virtual` `const`	#### Returns
`std::int64_t`	`bandwidthUsed` `virtual` `const`	#### Returns
`std::int64_t`	`bandwidthRemaining` `virtual` `const`	#### Returns
`std::int64_t`	`timeRemaining` `virtual` `const`	#### Returns
`FiveTuple &`	`tuple` `virtual`	#### Returns
`std::string`	`username` `virtual` `const`	#### Returns
`std::int64_t`	`lifetime` `virtual` `const`	#### Returns
`PermissionList`	`permissions` `virtual` `const`	#### Returns
`net::Address`	`relayedAddress` `const`	#### Returns
`void`	`addPermission` `virtual`	Adds a permission for `ip`, or refreshes the existing one.
`void`	`addPermission` `virtual`	Adds a permission for `address`, or refreshes the existing one. The port is ignored; TURN permissions are IP-only.
`void`	`addPermissions` `virtual`	Adds (or refreshes) permissions for multiple IPs.
`void`	`removePermission` `virtual`	Removes the permission for `ip` if present.
`void`	`removePermission` `virtual`	Removes the permission for `address` if present. The port is ignored; TURN permissions are IP-only.
`void`	`removeAllPermissions` `virtual`	Removes all permissions from the list.
`void`	`removeExpiredPermissions` `virtual`	Removes any permissions whose 5-minute lifetime has elapsed.
`bool`	`hasPermission` `virtual`	Checks whether a permission exists for `peerIP`. Local addresses (192.168.x.x and 127.x.x.x) are always permitted.
`bool`	`hasPermission` `virtual`	Checks whether a permission exists for `peerAddress`. The port is ignored; TURN permissions are IP-only.
`void`	`print` `virtual` `const` `inline`

IAllocation

IAllocation(const FiveTuple & tuple, const std::string & username, std::int64_t lifetime)

Parameters

tuple The 5-tuple identifying this allocation.
username Authenticated username associated with this allocation.
lifetime Initial lifetime in seconds.

IAllocation

IAllocation(const IAllocation &) = delete

Deleted constructor.

IAllocation

IAllocation(IAllocation &&) = delete

Deleted constructor.

updateUsage

virtual

virtual void updateUsage(std::int64_t numBytes)

Updates the last-activity timestamp and accumulates bandwidth usage. Call this whenever data is relayed through the allocation.

Parameters

numBytes Number of bytes relayed (0 just refreshes the timestamp).

setLifetime

virtual

virtual void setLifetime(std::int64_t lifetime)

Sets the allocation lifetime in seconds and resets the activity timestamp, effectively extending the expiry from the current moment.

Parameters

lifetime New lifetime in seconds.

setBandwidthLimit

virtual

virtual void setBandwidthLimit(std::int64_t numBytes)

Sets the maximum number of bytes this allocation may relay in its lifetime. Pass 0 to disable bandwidth limiting.

Parameters

numBytes Bandwidth cap in bytes (0 = unlimited).

expired

virtual const

virtual bool expired() const

Returns

true if the allocation's lifetime has elapsed or the bandwidth quota has been exhausted.

deleted

virtual const

virtual bool deleted() const

Returns true if the allocation's deleted flag is set and or if the allocation has expired.

This signifies that the allocation is ready to be destroyed via async garbage collection. See Server::onTimer() and Client::onTimer()

bandwidthLimit

virtual const

virtual std::int64_t bandwidthLimit() const

Returns

The configured bandwidth limit in bytes (0 means unlimited).

bandwidthUsed

virtual const

virtual std::int64_t bandwidthUsed() const

Returns

Total bytes transferred through this allocation since creation.

bandwidthRemaining

virtual const

virtual std::int64_t bandwidthRemaining() const

Returns

Bytes remaining before the bandwidth quota is exhausted. Returns a large sentinel value when no limit is configured.

timeRemaining

virtual const

virtual std::int64_t timeRemaining() const

Returns

Seconds until the allocation expires (0 if already expired).

tuple

virtual

virtual FiveTuple & tuple()

Returns

Reference to the 5-tuple identifying this allocation.

username

virtual const

virtual std::string username() const

Returns

The username associated with this allocation.

lifetime

virtual const

virtual std::int64_t lifetime() const

Returns

The configured lifetime in seconds.

permissions

virtual const

virtual PermissionList permissions() const

Returns

A copy of the current permission list.

relayedAddress

const

net::Address relayedAddress() const

Returns

The relay transport address assigned to this allocation.

addPermission

virtual

virtual void addPermission(const std::string & ip)

Adds a permission for ip, or refreshes the existing one.

Parameters

ip IPv4 address string to permit.

addPermission

virtual

virtual void addPermission(const net::Address & address)

Adds a permission for address, or refreshes the existing one. The port is ignored; TURN permissions are IP-only.

addPermissions

virtual

virtual void addPermissions(const IPList & ips)

Adds (or refreshes) permissions for multiple IPs.

Parameters

ips List of IPv4 address strings.

removePermission

virtual

virtual void removePermission(const std::string & ip)

Removes the permission for ip if present.

Parameters

ip IPv4 address string to remove.

removePermission

virtual

virtual void removePermission(const net::Address & address)

Removes the permission for address if present. The port is ignored; TURN permissions are IP-only.

removeAllPermissions

virtual

virtual void removeAllPermissions()

Removes all permissions from the list.

removeExpiredPermissions

virtual

virtual void removeExpiredPermissions()

Removes any permissions whose 5-minute lifetime has elapsed.

hasPermission

virtual

virtual bool hasPermission(const std::string & peerIP)

Checks whether a permission exists for peerIP. Local addresses (192.168.x.x and 127.x.x.x) are always permitted.

Parameters

peerIP IPv4 address string to check.

Returns

true if a valid (non-expired) permission exists.

hasPermission

virtual

virtual bool hasPermission(const net::Address & peerAddress)

Checks whether a permission exists for peerAddress. The port is ignored; TURN permissions are IP-only.

print

virtual const inline

virtual inline void print(std::ostream & os) const

Protected Attributes

Return	Name	Description
`FiveTuple`	`_tuple`
`std::string`	`_username`
`PermissionList`	`_permissions`
`std::int64_t`	`_lifetime`
`std::int64_t`	`_bandwidthLimit`
`std::int64_t`	`_bandwidthUsed`
`time_t`	`_createdAt`
`time_t`	`_updatedAt`
`bool`	`_deleted`

_tuple

FiveTuple _tuple

_username

std::string _username

_permissions

PermissionList _permissions

_lifetime

std::int64_t _lifetime

_bandwidthLimit

std::int64_t _bandwidthLimit

_bandwidthUsed

std::int64_t _bandwidthUsed

_createdAt

time_t _createdAt

_updatedAt

time_t _updatedAt

_deleted

bool _deleted

Built with Sourcey

Edit this page