Turn

Macros
#define	TURN_URL_BUFFER_SIZE   64
	TURN server configuration with credentials.
#define	TURN_USERNAME_BUFFER_SIZE   32
#define	TURN_CREDENTIAL_BUFFER_SIZE   64

Functions
struct	__attribute__ ((packed))

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_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_BUFFER_SIZE

#define TURN_CREDENTIAL_BUFFER_SIZE   64

#include <include/ascii-chat/network/webrtc/turn.h>

Definition at line 97 of file turn.h.

TURN_CREDENTIAL_EXPIRY_SECS

#define TURN_CREDENTIAL_EXPIRY_SECS   (24 * 60 * 60)

#include <include/ascii-chat/network/webrtc/turn.h>

Recommended credential expiration time (seconds).

Definition at line 121 of file turn.h.

TURN_DEFAULT_PORT

#define TURN_DEFAULT_PORT   3478

#include <include/ascii-chat/network/webrtc/turn.h>

Standard TURN port (RFC 5766).

Definition at line 115 of file turn.h.

TURN_TLS_DEFAULT_PORT

#define TURN_TLS_DEFAULT_PORT   5349

#include <include/ascii-chat/network/webrtc/turn.h>

TURN over TLS port (RFC 5766).

Definition at line 118 of file turn.h.

TURN_URL_BUFFER_SIZE

#define TURN_URL_BUFFER_SIZE   64

#include <include/ascii-chat/network/webrtc/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                                            |
+--------------------------------------------------------------------------+

TURN wire string capacities in bytes, including NUL.

Definition at line 95 of file turn.h.

TURN_USERNAME_BUFFER_SIZE

#define TURN_USERNAME_BUFFER_SIZE   32

#include <include/ascii-chat/network/webrtc/turn.h>

Definition at line 96 of file turn.h.

Function Documentation

__attribute__()

struct __attribute__

(

(packed)

)

#include <include/ascii-chat/network/webrtc/turn.h>

< 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[TURN_URL_BUFFER_SIZE];               
  uint8_t username_len;                         
  char username[TURN_USERNAME_BUFFER_SIZE];     
  uint8_t credential_len;                       
  char credential[TURN_CREDENTIAL_BUFFER_SIZE]; 
} turn_server_t;

Variable Documentation

turn_server_t

turn_server_t

#include <include/ascii-chat/network/webrtc/turn.h>

Definition at line 106 of file turn.h.

Referenced by webrtc_create_peer_connection(), and webrtc_turn_servers_parse().