Turn

Functions
struct	__attribute__ ((packed))
	TURN server configuration with credentials.

Variables
	turn_server_t

TURN Protocol Constants
#define	TURN_DEFAULT_PORT   3478
	Standard TURN port (RFC 5766)
#define	TURN_TLS_DEFAULT_PORT   5349
	TURN over TLS port (RFC 5766)
#define	TURN_MAX_URL_LEN   64
	Maximum TURN URL length.
#define	TURN_MAX_USERNAME_LEN   32
	Maximum TURN username length.
#define	TURN_MAX_CREDENTIAL_LEN   64
	Maximum TURN credential length.
#define	TURN_CREDENTIAL_EXPIRY_SECS   (24 * 60 * 60)
	Recommended credential expiration time (seconds)

Detailed Description

This module defines TURN server configuration structures for WebRTC connectivity. TURN servers act as relay servers when direct peer-to-peer connections are not possible due to restrictive NAT or firewalls.

RFC 5766: Traversal Using Relays around NAT (TURN) RFC 8656: TURN Extensions for IPv6

TURN SERVER ROLE:

• Relays media traffic when direct P2P connection fails
• Fallback mechanism when STUN-based connectivity doesn't work
• Requires authentication (username/credential)
• Uses server bandwidth (unlike STUN which is free)

USAGE IN ACDS:

• Discovery server provides TURN server list in SESSION_CREATED response
• Credentials are time-limited for security
• Clients use TURN as last resort for ICE connectivity

SECURITY CONSIDERATIONS:

• Credentials should be time-limited (ephemeral)
• TURN servers should enforce rate limiting
• Use TURN over TLS (TURNS) when possible for privacy

Note

All structures are packed with attribute((packed)) for wire format

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

January 2026

Version

1.0

Macro Definition Documentation

TURN_CREDENTIAL_EXPIRY_SECS

#define TURN_CREDENTIAL_EXPIRY_SECS   (24 * 60 * 60)

#include <turn.h>

Recommended credential expiration time (seconds)

Definition at line 125 of file turn.h.

TURN_DEFAULT_PORT

#define TURN_DEFAULT_PORT   3478

#include <turn.h>

Standard TURN port (RFC 5766)

Definition at line 110 of file turn.h.

TURN_MAX_CREDENTIAL_LEN

#define TURN_MAX_CREDENTIAL_LEN   64

#include <turn.h>

Maximum TURN credential length.

Definition at line 122 of file turn.h.

TURN_MAX_URL_LEN

#define TURN_MAX_URL_LEN   64

#include <turn.h>

Maximum TURN URL length.

Definition at line 116 of file turn.h.

TURN_MAX_USERNAME_LEN

#define TURN_MAX_USERNAME_LEN   32

#include <turn.h>

Maximum TURN username length.

Definition at line 119 of file turn.h.

TURN_TLS_DEFAULT_PORT

#define TURN_TLS_DEFAULT_PORT   5349

#include <turn.h>

TURN over TLS port (RFC 5766)

Definition at line 113 of file turn.h.

Function Documentation

__attribute__()

struct __attribute__

(

(packed)

)

#include <turn.h>

TURN server configuration with credentials.

Used in ACDS SESSION_CREATED response to provide WebRTC relay information. Includes time-limited credentials for secure TURN access.

Protocol Format:

• url_len: 1 byte (length of URL string)
• url: 64 bytes (null-terminated TURN URL)
• username_len: 1 byte (length of username)
• username: 32 bytes (null-terminated username)
• credential_len: 1 byte (length of credential)
• credential: 64 bytes (null-terminated time-limited credential)

URL Format Examples:

• turn:discovery.ascii.chat:3478 (standard TURN)
• turns:discovery.ascii.chat:5349 (TURN over TLS)
• turn:relay.example.com:3478?transport=udp (UDP transport)
• turn:relay.example.com:3478?transport=tcp (TCP transport)

Credential Types:

• Short-term: Simple username/password (less secure)
• Long-term: HMAC-based with timestamp (recommended)
• OAuth: Token-based authentication

Wire Format (163 bytes total):

+---------+----------------+---------------+----------------+--------------+
| url_len |    url[64]     | username_len  |  username[32]  |credential_len|
+---------+----------------+---------------+----------------+--------------+
| 1 byte  |   64 bytes     |    1 byte     |   32 bytes     |   1 byte     |
+---------+----------------+---------------+----------------+--------------+
|                  credential[64]                                          |
+--------------------------------------------------------------------------+
|                      64 bytes                                            |
+--------------------------------------------------------------------------+

< Length of URL string (actual length)

< TURN server URL (e.g., "turn:discovery.ascii.chat:3478")

< Length of username string

< TURN authentication username

< Length of credential string

< Time-limited TURN credential/password

Definition at line 1 of file turn.h.

                                       {
  uint8_t url_len;        
  char url[64];           
  uint8_t username_len;   
  char username[32];      
  uint8_t credential_len; 
  char credential[64];    
} turn_server_t;

Variable Documentation

turn_server_t

turn_server_t

#include <turn.h>

Definition at line 101 of file turn.h.