Xirsys.XTurn.Auth.AccessToken (xturn v2.0.0)

Copy Markdown View Source

RFC 7635 third-party authorization access tokens.

What problem this solves

Some deployments let an authorization server mint temporary MAC keys instead of sharing user passwords with the TURN server. The ACCESS-TOKEN attribute carries an encrypted blob; this module mints and verifies those tokens (AES-256-GCM over a 20-byte MAC key, issue time, and lifetime) using the configured AEAD key and server name as additional authenticated data.

Opt-in via :third_party_auth application env. Long-term credentials and MESSAGE-INTEGRITY (RFC 8489) remain the default path when disabled.

RFCs

  • RFC 7635 (OAuth 2.0 third-party authorization for STUN/TURN, ACCESS-TOKEN attribute)
  • RFC 8489 (MESSAGE-INTEGRITY with token-derived MAC key)

Summary

Functions

aead_key()

Returns the 32-byte AEAD key from config, or nil when missing or invalid.

as_uri()

Returns the configured authorization-server URI, or nil.

enabled?()

Returns true when :third_party_auth is enabled and a valid AEAD key is configured.

mint(mac_key, lifetime_seconds, aead_key, server_name \\ server_name())

Mints an encrypted access token for mac_key with lifetime_seconds validity.

mint(mac_key, lifetime_seconds, aead_key, server_name, timestamp_seconds)

Mints an encrypted access token using an explicit issue timestamp (Unix seconds).

server_name()

Returns the configured server name used as GCM AAD, defaulting to :realm.

verify(token, aead_key)

Verifies token and returns {:ok, mac_key} on success.

verify(token, aead_key, server_name)

Verifies token and returns {:ok, mac_key} using an explicit GCM AAD server_name.

Functions

aead_key()

Returns the 32-byte AEAD key from config, or nil when missing or invalid.

as_uri()

Returns the configured authorization-server URI, or nil.

enabled?()

Returns true when :third_party_auth is enabled and a valid AEAD key is configured.

mint(mac_key, lifetime_seconds, aead_key, server_name \\ server_name())

@spec mint(binary(), pos_integer(), binary(), binary()) :: binary()

Mints an encrypted access token for mac_key with lifetime_seconds validity.

Uses the current system time as the issue timestamp. See mint/5 to pin time for testing.

Examples

iex> key = :crypto.hash(:sha256, "doctest-aead-key")
iex> server = "turn.example.com"
iex> mac_key = :crypto.strong_rand_bytes(20)
iex> token = Xirsys.XTurn.Auth.AccessToken.mint(mac_key, 60, key, server)
iex> {:ok, ^mac_key} = Xirsys.XTurn.Auth.AccessToken.verify(token, key, server)

mint(mac_key, lifetime_seconds, aead_key, server_name, timestamp_seconds)

@spec mint(binary(), pos_integer(), binary(), binary(), integer()) :: binary()

Mints an encrypted access token using an explicit issue timestamp (Unix seconds).

Prefer mint/4 for production; this arity supports deterministic tests.

server_name()

Returns the configured server name used as GCM AAD, defaulting to :realm.

verify(token, aead_key)

@spec verify(binary(), binary()) :: {:ok, binary()} | {:error, term()}

Verifies token and returns {:ok, mac_key} on success.

Uses the configured server name as GCM AAD. Returns {:error, :invalid} when decryption fails, the MAC key length is wrong, or the token is outside its lifetime.

verify(token, aead_key, server_name)

@spec verify(binary(), binary(), binary()) :: {:ok, binary()} | {:error, term()}

Verifies token and returns {:ok, mac_key} using an explicit GCM AAD server_name.