StunAgent

StunAgent — STUN agent for building and validating STUN messages

Stability Level

Stable, unless otherwise indicated

Synopsis


#include <stun/stunagent.h>

typedef             StunAgent;
enum                StunCompatibility;
enum                StunAgentUsageFlags;
enum                StunValidationStatus;
bool                (*StunMessageIntegrityValidate)     (StunAgent *agent,
                                                         StunMessage *message,
                                                         uint8_t *username,
                                                         uint16_t username_len,
                                                         uint8_t **password,
                                                         size_t *password_len,
                                                         void *user_data);
                    StunDefaultValidaterData;
void                stun_agent_init                     (StunAgent *agent,
                                                         const uint16_t *known_attributes,
                                                         StunCompatibility compatibility,
                                                         StunAgentUsageFlags usage_flags);
StunValidationStatus stun_agent_validate                (StunAgent *agent,
                                                         StunMessage *msg,
                                                         const uint8_t *buffer,
                                                         size_t buffer_len,
                                                         StunMessageIntegrityValidate validater,
                                                         void *validater_data);
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);
bool                stun_agent_init_request             (StunAgent *agent,
                                                         StunMessage *msg,
                                                         uint8_t *buffer,
                                                         size_t buffer_len,
                                                         StunMethod m);
bool                stun_agent_init_indication          (StunAgent *agent,
                                                         StunMessage *msg,
                                                         uint8_t *buffer,
                                                         size_t buffer_len,
                                                         StunMethod m);
bool                stun_agent_init_response            (StunAgent *agent,
                                                         StunMessage *msg,
                                                         uint8_t *buffer,
                                                         size_t buffer_len,
                                                         const StunMessage *request);
bool                stun_agent_init_error               (StunAgent *agent,
                                                         StunMessage *msg,
                                                         uint8_t *buffer,
                                                         size_t buffer_len,
                                                         const StunMessage *request,
                                                         StunError err);
size_t              stun_agent_build_unknown_attributes_error
                                                        (StunAgent *agent,
                                                         StunMessage *msg,
                                                         uint8_t *buffer,
                                                         size_t buffer_len,
                                                         const StunMessage *request);
size_t              stun_agent_finish_message           (StunAgent *agent,
                                                         StunMessage *msg,
                                                         const uint8_t *key,
                                                         size_t key_len);
bool                stun_agent_forget_transaction       (StunAgent *agent,
                                                         StunTransactionId id);
void                stun_debug_enable                   (void);
void                stun_debug_disable                  (void);

Description

The STUN Agent allows you to create and validate STUN messages easily. It's main purpose is to make sure the building and validation methods used are compatible with the RFC you create it with. It also tracks the transaction ids of the requests you send, so you can validate if a STUN response you received should be processed by that agent or not.

Details

StunAgent

typedef struct stun_agent_t StunAgent;

An opaque structure representing the STUN agent.

enum StunCompatibility

typedef enum {
  STUN_COMPATIBILITY_RFC3489,
  STUN_COMPATIBILITY_RFC5389,
  STUN_COMPATIBILITY_WLM2009,
  STUN_COMPATIBILITY_LAST = STUN_COMPATIBILITY_WLM2009
} StunCompatibility;

Enum that specifies the STUN compatibility mode of the StunAgent

STUN_COMPATIBILITY_RFC3489 Use the STUN specifications compatible with RFC 3489
STUN_COMPATIBILITY_RFC5389 Use the STUN specifications compatible with RFC 5389
STUN_COMPATIBILITY_WLM2009 Use the STUN specifications compatible with Windows Live Messenger 2009 (a mix between RFC3489 and RFC5389, as well as a special usecase against a typo in their code)
STUN_COMPATIBILITY_LAST Dummy last compatibility mode

enum StunAgentUsageFlags

typedef enum {
  STUN_AGENT_USAGE_SHORT_TERM_CREDENTIALS    = (1 << 0),
  STUN_AGENT_USAGE_LONG_TERM_CREDENTIALS     = (1 << 1),
  STUN_AGENT_USAGE_USE_FINGERPRINT           = (1 << 2),
  STUN_AGENT_USAGE_ADD_SOFTWARE              = (1 << 3),
  STUN_AGENT_USAGE_IGNORE_CREDENTIALS        = (1 << 4),
  STUN_AGENT_USAGE_NO_INDICATION_AUTH        = (1 << 5),
  STUN_AGENT_USAGE_FORCE_VALIDATER           = (1 << 6),
} 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()

STUN_AGENT_USAGE_SHORT_TERM_CREDENTIALS The agent should be using the short term credentials mechanism for authenticating STUN messages
STUN_AGENT_USAGE_LONG_TERM_CREDENTIALS The agent should be using the long term credentials mechanism for authenticating STUN messages
STUN_AGENT_USAGE_USE_FINGERPRINT The agent should add the FINGERPRINT attribute to the STUN messages it creates.
STUN_AGENT_USAGE_ADD_SOFTWARE The agent should add the SOFTWARE attribute to the STUN messages it creates
STUN_AGENT_USAGE_IGNORE_CREDENTIALS The agent should ignore any credentials in the STUN messages it receives (the MESSAGE-INTEGRITY attribute will never be validated by stun_agent_validate())
STUN_AGENT_USAGE_NO_INDICATION_AUTH The agent should ignore credentials in the STUN messages it receives if the StunClass of the message is STUN_INDICATION (some implementation require STUN_INDICATION messages to be authenticated, while others never add a MESSAGE-INTEGRITY attribute to a STUN_INDICATION message)
STUN_AGENT_USAGE_FORCE_VALIDATER The agent should always try to validate the password of a STUN message, even if it already knows what the password should be (a response to a previously created request). This means that the StunMessageIntegrityValidate callback will always be called when there is a MESSAGE-INTEGRITY attribute.

enum StunValidationStatus

typedef enum {
  STUN_VALIDATION_SUCCESS,
  STUN_VALIDATION_NOT_STUN,
  STUN_VALIDATION_INCOMPLETE_STUN,
  STUN_VALIDATION_BAD_REQUEST,
  STUN_VALIDATION_UNAUTHORIZED_BAD_REQUEST,
  STUN_VALIDATION_UNAUTHORIZED,
  STUN_VALIDATION_UNMATCHED_RESPONSE,
  STUN_VALIDATION_UNKNOWN_REQUEST_ATTRIBUTE,
  STUN_VALIDATION_UNKNOWN_ATTRIBUTE,
} 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.

STUN_VALIDATION_SUCCESS The message is validated
STUN_VALIDATION_NOT_STUN This is not a valid STUN message
STUN_VALIDATION_INCOMPLETE_STUN The message seems to be valid but incomplete
STUN_VALIDATION_BAD_REQUEST The message does not have the cookie or the fingerprint while the agent needs it with its usage
STUN_VALIDATION_UNAUTHORIZED_BAD_REQUEST The message is valid but unauthorized with no username and message-integrity attributes. A BAD_REQUEST error must be generated
STUN_VALIDATION_UNAUTHORIZED The message is valid but unauthorized as the username/password do not match. An UNAUTHORIZED error must be generated
STUN_VALIDATION_UNMATCHED_RESPONSE The message is valid but this is a response/error that doesn't match a previously sent request
STUN_VALIDATION_UNKNOWN_REQUEST_ATTRIBUTE The message is valid but contains one or more unknown comprehension attributes. stun_agent_build_unknown_attributes_error() should be called
STUN_VALIDATION_UNKNOWN_ATTRIBUTE The message is valid but contains one or more unknown comprehension attributes. This is a response, or error, or indication message and no error response should be sent

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()

agent : The StunAgent
message : The StunMessage being validated
username : The username found in the message
username_len : The length of username
password : The password associated with that username. This argument is a pointer to a byte array that must be set by the validater function.
password_len : The length of password which must also be set by the validater function.
user_data : Data to give the function
Returns : TRUE if the authentication was successful, FALSE if the authentication failed

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()

uint8_t *username; The username
size_t username_len; The length of the username
uint8_t *password; The password
size_t password_len; The length of the password

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.

Note

The known_attributes data must exist in memory as long as the agent is used

If the STUN_AGENT_USAGE_SHORT_TERM_CREDENTIALS and STUN_AGENT_USAGE_LONG_TERM_CREDENTIALS usage flags are not set, then the agent will default in using the short term credentials mechanism

The STUN_AGENT_USAGE_USE_FINGERPRINT and STUN_AGENT_USAGE_ADD_SOFTWARE usage flags are only valid if the STUN_COMPATIBILITY_RFC5389 or STUN_COMPATIBILITY_WLM2009 compatibility is used

agent : The StunAgent to initialize
known_attributes : An array of uint16_t specifying which attributes should be known by the agent. Any STUN message received that contains a mandatory attribute that is not in this array will yield a STUN_VALIDATION_UNKNOWN_REQUEST_ATTRIBUTE or a STUN_VALIDATION_UNKNOWN_ATTRIBUTE error when calling stun_agent_validate()
compatibility : The StunCompatibility to use for this agent. This will affect how the agent builds and validates the STUN messages
usage_flags : A bitflag using StunAgentUsageFlags values to define which STUN usages the agent should use.

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()

agent : The StunAgent
msg : The StunMessage to build
buffer : The data buffer of the STUN message
buffer_len : The length of buffer
validater : A StunMessageIntegrityValidate function callback that will be called if the agent needs to validate a MESSAGE-INTEGRITY attribute. It will only be called if the agent finds a message that needs authentication and a USERNAME is present in the STUN message, but no password is known. The validater will not be called if the STUN_AGENT_USAGE_IGNORE_CREDENTIALS usage flag is set on the agent, and it will always be called if the STUN_AGENT_USAGE_FORCE_VALIDATER usage flag is set on the agent.
validater_data : A user data to give to the validater callback when it gets called.
Returns : A StunValidationStatus

Note

if the return value is different from STUN_VALIDATION_NOT_STUN or STUN_VALIDATION_INCOMPLETE_STUN, then the msg argument will contain a valid STUN message that can be used. This means that you can use the msg variable as the request argument to functions like stun_agent_init_error() or stun_agent_build_unknown_attributes_error(). If the return value is STUN_VALIDATION_BAD_REQUEST, STUN_VALIDATION_UNAUTHORIZED or STUN_VALIDATION_UNAUTHORIZED_BAD_REQUEST then the key in the StunMessage will not be set, so that error responses will not have a MESSAGE-INTEGRITY attribute.

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()

agent : The StunAgent
message : The StunMessage being validated
username : The username found in the message
username_len : The length of username
password : The password associated with that username. This argument is a pointer to a byte array that must be set by the validater function.
password_len : The length of password which must also be set by the validater function.
user_data : This must be an array of StunDefaultValidaterData structures. The last element in the array must have a username set to NULL
Returns : TRUE if the authentication was successful, FALSE if the authentication failed

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

agent : The StunAgent
msg : The StunMessage to build
buffer : The buffer to use in the StunMessage
buffer_len : The length of the buffer
m : The StunMethod of the request
Returns : TRUE if the message was initialized correctly, FALSE otherwise

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

agent : The StunAgent
msg : The StunMessage to build
buffer : The buffer to use in the StunMessage
buffer_len : The length of the buffer
m : The StunMethod of the indication
Returns : TRUE if the message was initialized correctly, FALSE otherwise

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()

agent : The StunAgent
msg : The StunMessage to build
buffer : The buffer to use in the StunMessage
buffer_len : The length of the buffer
request : The StunMessage of class STUN_REQUEST that this response is for
Returns : TRUE if the message was initialized correctly, FALSE otherwise

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.

agent : The StunAgent
msg : The StunMessage to build
buffer : The buffer to use in the StunMessage
buffer_len : The length of the buffer
request : The StunMessage of class STUN_REQUEST that this error response is for
err : The StunError to put in the ERROR-CODE attribute of the error response
Returns : TRUE if the message was initialized correctly, FALSE otherwise

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()

agent : The StunAgent
msg : The StunMessage to build
buffer : The buffer to use in the StunMessage
buffer_len : The length of the buffer
request : The StunMessage of class STUN_REQUEST that this response is for
Returns : The size of the message built

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()

agent : The StunAgent
msg : The StunMessage to finish
key : The key to use for the MESSAGE-INTEGRITY attribute
key_len : The length of the key
Returns : The final size of the message built or 0 if an error occured

Note

The return value must always be checked. a value of 0 means the either the buffer's size is too small to contain the finishing attributes (MESSAGE-INTEGRITY, FINGERPRINT), or that there is no more free slots for saving the sent id in the agent's state.

Everytime stun_agent_finish_message() is called for a STUN_REQUEST message, you must make sure to call stun_agent_forget_transaction() in case the response times out and is never received. This is to avoid filling up the StunAgent's sent ids state preventing any further use of the stun_agent_finish_message()

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.

agent : The StunAgent
id : The StunTransactionId of the transaction to forget
Returns : TRUE if the transaction was found, FALSE otherwise

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

See Also

StunMessage
Generated by GTK-Doc V1.10