StunMessageIntegrityValidate ()

bool
(*StunMessageIntegrityValidate) (StunAgent *agent,
                                 StunMessage *message,
                                 uint8_t *username,
                                 uint16_t username_len,
                                 uint8_t **password,
                                 size_t *password_len,
                                 void *user_data);

This is the prototype for the validater argument of the stun_agent_validate() function.

See also: stun_agent_validate()

StunDebugHandler ()

void
(*StunDebugHandler) (const char *format,
                     va_list ap);

Callback for a debug message from the STUN code.

stun_agent_init ()

void
stun_agent_init (StunAgent *agent,
                 const uint16_t *known_attributes,
                 StunCompatibility compatibility,
                 StunAgentUsageFlags usage_flags);

This function must be called to initialize an agent before it is being used.

stun_agent_validate ()

StunValidationStatus
stun_agent_validate (StunAgent *agent,
                     StunMessage *msg,
                     const uint8_t *buffer,
                     size_t buffer_len,
                     StunMessageIntegrityValidate validater,
                     void *validater_data);

This function is used to validate an inbound STUN message and transform its data buffer into a StunMessage. It will take care of various validation algorithms to make sure that the STUN message is valid and correctly authenticated.

See also: stun_agent_default_validater()

stun_agent_default_validater ()

bool
stun_agent_default_validater (StunAgent *agent,
                              StunMessage *message,
                              uint8_t *username,
                              uint16_t username_len,
                              uint8_t **password,
                              size_t *password_len,
                              void *user_data);

This is a helper function to be used with stun_agent_validate(). If no complicated processing of the username needs to be done, this function can be used with stun_agent_validate() to quickly and easily match the username of a STUN message with its password. Its user_data argument must be an array of StunDefaultValidaterData which will allow us to map a username to a password

See also: stun_agent_validate()

stun_agent_init_request ()

bool
stun_agent_init_request (StunAgent *agent,
                         StunMessage *msg,
                         uint8_t *buffer,
                         size_t buffer_len,
                         StunMethod m);

Creates a new STUN message of class STUN_REQUEST and with the method m

stun_agent_init_indication ()

bool
stun_agent_init_indication (StunAgent *agent,
                            StunMessage *msg,
                            uint8_t *buffer,
                            size_t buffer_len,
                            StunMethod m);

Creates a new STUN message of class STUN_INDICATION and with the method m

stun_agent_init_response ()

bool
stun_agent_init_response (StunAgent *agent,
                          StunMessage *msg,
                          uint8_t *buffer,
                          size_t buffer_len,
                          const StunMessage *request);

Creates a new STUN message of class STUN_RESPONSE and with the same method and transaction ID as the message request . This will also copy the pointer to the key that was used to authenticate the request, so you won't need to specify the key with stun_agent_finish_message()

stun_agent_init_error ()

bool
stun_agent_init_error (StunAgent *agent,
                       StunMessage *msg,
                       uint8_t *buffer,
                       size_t buffer_len,
                       const StunMessage *request,
                       StunError err);

Creates a new STUN message of class STUN_ERROR and with the same method and transaction ID as the message request . This will also copy the pointer to the key that was used to authenticate the request (if authenticated), so you won't need to specify the key with stun_agent_finish_message(). It will then add the ERROR-CODE attribute with code err and the associated string.

stun_agent_build_unknown_attributes_error ()

size_t
stun_agent_build_unknown_attributes_error
                               (StunAgent *agent,
                                StunMessage *msg,
                                uint8_t *buffer,
                                size_t buffer_len,
                                const StunMessage *request);

Creates a new STUN message of class STUN_ERROR and with the same method and transaction ID as the message request . It will then add the ERROR-CODE attribute with code STUN_ERROR_UNKNOWN_ATTRIBUTE and add all the unknown mandatory attributes from the request STUN message in the STUN_ATTRIBUTE_UNKNOWN_ATTRIBUTES attribute, it will then finish the message by calling stun_agent_finish_message()

stun_agent_finish_message ()

size_t
stun_agent_finish_message (StunAgent *agent,
                           StunMessage *msg,
                           const uint8_t *key,
                           size_t key_len);

This function will 'finish' a message and make it ready to be sent. It will add the MESSAGE-INTEGRITY and FINGERPRINT attributes if necessary. If the STUN message has a STUN_REQUEST class, it will save the transaction id of the message in the agent for future matching of the response.

See also: stun_agent_forget_transaction()

stun_agent_forget_transaction ()

bool
stun_agent_forget_transaction (StunAgent *agent,
                               StunTransactionId id);

This function is used to make the StunAgent forget about a previously created transaction.

This function should be called when a STUN request was previously created with stun_agent_finish_message() and for which no response was ever received (timed out). The StunAgent keeps a list of the sent transactions in order to validate the responses received. If the response is never received this will allow the StunAgent to forget about the timed out transaction and free its slot for future transactions.

Since: 0.0.6

stun_agent_set_software ()

void
stun_agent_set_software (StunAgent *agent,
                         const char *software);

This function will set the value of the SOFTWARE attribute to be added to STUN requests, responses and error responses.

Calling this function will automatically enable the addition of the SOFTWARE attribute for RFC5389 and MSICE2 compatibility modes.

Since: 0.0.10

stun_debug_enable ()

void
stun_debug_enable (void);

Enable debug messages to stderr

stun_debug_disable ()

void
stun_debug_disable (void);

Disable debug messages to stderr

stun_set_debug_handler ()

void
stun_set_debug_handler (StunDebugHandler handler);

Set a callback function to be invoked for each debug message from the STUN code. The callback will only be invoked if STUN debugging is enabled using stun_debug_enable().

The default callback prints the formatted debug message to stderr.

StunAgent

typedef struct stun_agent_t StunAgent;

An opaque structure representing the STUN agent.

enum StunCompatibility

Enum that specifies the STUN compatibility mode of the StunAgent

enum StunAgentUsageFlags

This enum defines a bitflag usages for a StunAgent and they will define how the agent should behave, independently of the compatibility mode it uses.

See also: stun_agent_init()

See also: stun_agent_validate()

enum StunValidationStatus

This enum is used as the return value of stun_agent_validate() and represents the status result of the validation of a STUN message.

StunDefaultValidaterData

typedef struct {
  uint8_t *username;
  size_t username_len;
  uint8_t *password;
  size_t password_len;
} StunDefaultValidaterData;

This structure is used as an element of the user_data to the stun_agent_default_validater() function for authenticating a STUN message during validationg.

See also: stun_agent_default_validater()