turn_credentials.h File Reference

TURN server credential generation for WebRTC. More...

Go to the source code of this file.

Data Structures
struct	turn_credentials_t
	TURN server credentials (username + password) More...

Functions
asciichat_error_t	turn_generate_credentials (const char *session_id, const char *secret, uint32_t validity_seconds, turn_credentials_t *out_credentials)
	Generate time-limited TURN credentials.
bool	turn_credentials_expired (const turn_credentials_t *credentials)
	Check if TURN credentials have expired.

Detailed Description

TURN server credential generation for WebRTC.

Implements time-limited HMAC-based TURN authentication as specified in RFC 5389 (STUN) and RFC 5766 (TURN).

Credential format:

• Username: "{timestamp}:{session_id}"
• Password: base64(HMAC-SHA1(secret, username))

The timestamp provides time-limited credentials that expire after a configurable duration (default 24 hours).

Definition in file turn_credentials.h.

Function Documentation

turn_credentials_expired()

bool turn_credentials_expired

(

const turn_credentials_t *

credentials

)

Check if TURN credentials have expired.

Parameters

credentials

Credentials to check

Returns

true if expired, false if still valid

Definition at line 192 of file turn_credentials.c.

                                                                     {
  if (!credentials) {
    return true;
  }
 
  time_t now = time(NULL);
  return now >= credentials->expires_at;
}

References turn_credentials_t::expires_at.

turn_generate_credentials()

asciichat_error_t turn_generate_credentials	(	const char *	session_id,
		const char *	secret,
		uint32_t	validity_seconds,
		turn_credentials_t *	out_credentials
	)

Generate time-limited TURN credentials.

Creates TURN authentication credentials using HMAC-SHA1 with a shared secret. The username includes a timestamp for automatic expiration.

Parameters

session_id	Session identifier (e.g., "swift-river-mountain")
secret	Shared secret configured on TURN server
validity_seconds	How long credentials remain valid (default: 86400 = 24 hours)
out_credentials	Output credentials structure

Returns

ASCIICHAT_OK on success, error code on failure

Note

The secret must match the static-auth-secret configured on the TURN server

Example:

turn_credentials_t creds;
asciichat_error_t result = turn_generate_credentials(
    "swift-river-mountain",
    "my-turn-secret",
    86400,  // 24 hours
    &creds
);
if (result == ASCIICHAT_OK) {
    printf("Username: %s\n", creds.username);
    printf("Password: %s\n", creds.password);
}

Definition at line 142 of file turn_credentials.c.

                                                                                 {
  if (!session_id || !secret || !out_credentials) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "TURN credentials: NULL parameter");
  }
 
  if (validity_seconds == 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "TURN credentials: validity_seconds must be > 0");
  }
 
  // Calculate expiration timestamp
  time_t now = time(NULL);
  time_t expires_at = now + (time_t)validity_seconds;
 
  // Format username: "{timestamp}:{session_id}"
  int username_len = safe_snprintf(out_credentials->username, sizeof(out_credentials->username), "%ld:%s",
                                   (long)expires_at, session_id);
  if (username_len < 0 || (size_t)username_len >= sizeof(out_credentials->username)) {
    return SET_ERRNO(ERROR_BUFFER_OVERFLOW, "TURN credentials: username too long");
  }
 
  // Compute HMAC-SHA1(secret, username)
  uint8_t hmac_result[SHA1_DIGEST_LENGTH];
  unsigned int hmac_len = 0;
 
  asciichat_error_t result = hmac_sha1((const uint8_t *)out_credentials->username, (size_t)username_len,
                                       (const uint8_t *)secret, strlen(secret), hmac_result, &hmac_len);
  if (result != ASCIICHAT_OK) {
    return result;
  }
 
  if (hmac_len != SHA1_DIGEST_LENGTH) {
    return SET_ERRNO(ERROR_CRYPTO, "TURN credentials: unexpected HMAC length %u (expected %u)", hmac_len,
                     SHA1_DIGEST_LENGTH);
  }
 
  // Base64-encode the HMAC to get the password
  size_t encoded_len =
      base64_encode(hmac_result, hmac_len, out_credentials->password, sizeof(out_credentials->password));
  if (encoded_len == 0) {
    return SET_ERRNO(ERROR_BUFFER_OVERFLOW, "TURN credentials: password encoding failed");
  }
 
  out_credentials->expires_at = expires_at;
 
  log_debug("Generated TURN credentials: username=%s, expires_at=%ld", out_credentials->username, (long)expires_at);
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_BUFFER_OVERFLOW, ERROR_CRYPTO, ERROR_INVALID_PARAM, turn_credentials_t::expires_at, log_debug, turn_credentials_t::password, safe_snprintf(), session_id, SET_ERRNO, SHA1_DIGEST_LENGTH, and turn_credentials_t::username.

Referenced by database_session_join().