StunAgent

StunAgent — STUN agent for building and validating STUN messages

Stability Level

Stable, unless otherwise indicated

Functions

Types and Values

Includes

#include <stun/stunagent.h>

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.

Functions

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

Parameters

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


StunDebugHandler ()

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

Callback for a debug message from the STUN code.

Parameters

format

printf()-style debug message format string

 

ap

Parameters to substitute into message placeholders

 

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.

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_MSICE2 compatibility is used

Parameters

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

Parameters

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

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

Parameters

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

Parameters

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

Parameters

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

Parameters

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.

Parameters

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

Parameters

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

Parameters

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

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.

Parameters

agent

The StunAgent

 

id

The StunTransactionId of the transaction to forget

 

Returns

TRUE if the transaction was found, FALSE otherwise

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.

The software argument must be in UTF-8 encoding and only the first 128 characters will be sent.

The value of the software argument must stay valid throughout the life of the StunAgent's life. Do not free its content.

Parameters

agent

The StunAgent

 

software

The value of the SOFTWARE attribute to add.

 

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.

Parameters

handler

Handler for STUN debug messages, or NULL to use the default.

[nullable]

Types and Values

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

STUN_COMPATIBILITY_WLM2009 is deprecated and should not be used in newly-written code. It is kept for compatibility reasons and represents the same compatibility as STUN_COMPATIBILITY_MSICE2.

Members

STUN_COMPATIBILITY_RFC3489

Use the STUN specifications compatible with RFC 3489

 

STUN_COMPATIBILITY_RFC5389

Use the STUN specifications compatible with RFC 5389

 

STUN_COMPATIBILITY_MSICE2

Use the STUN specifications compatible with [MS-ICE2] (a mix between RFC3489 and RFC5389)

 

STUN_COMPATIBILITY_OC2007

Use the STUN specifications compatible with Microsoft Office Communicator 2007 (basically RFC3489 with swapped REALM and NONCE attribute hex IDs, attributes are not aligned)

 

STUN_COMPATIBILITY_WLM2009

An alias for STUN_COMPATIBILITY_MSICE2

 

STUN_COMPATIBILITY_LAST

Dummy last compatibility mode

 

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

Members

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. Calling nice_agent_set_software() will have the same effect as enabling this Usage. STUN Indications do not have the SOFTWARE attributes added to them though. The SOFTWARE attribute is only added for the RFC5389 and MSICE2 compatibility modes.

 

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.

 

STUN_AGENT_USAGE_NO_ALIGNED_ATTRIBUTES

The agent should not assume STUN attributes are aligned on 32-bit boundaries when parsing messages and also do not add padding when creating messages.

 

STUN_AGENT_USAGE_CONSENT_FRESHNESS

The agent should expect and use the STUN_VALIDATION_FORBIDDEN return value from ERROR-CODE responses and abort all transactions accordingly.

 

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.

Members

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

 

STUN_VALIDATION_FORBIDDEN

The message response is valid and indicates the peer responded with the error code 403 'Forbidden'. No response should be sent.

 

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

Members

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

 

See Also

StunMessage