libnice Reference Manual: StunAgent

## StunAgent StunAgent — STUN agent for building and validating STUN messages |

## Stability Level

Stable, unless otherwise indicated

## Functions

bool | (*StunMessageIntegrityValidate) ()
void | (*StunDebugHandler) ()
void | stun_agent_init ()
StunValidationStatus | stun_agent_validate ()
bool | stun_agent_default_validater ()
bool | stun_agent_init_request ()
bool | stun_agent_init_indication ()
bool | stun_agent_init_response ()
bool | stun_agent_init_error ()
size_t | stun_agent_build_unknown_attributes_error ()
size_t | stun_agent_finish_message ()
bool | stun_agent_forget_transaction ()
void | stun_agent_set_software ()
void | stun_debug_enable ()
void | stun_debug_disable ()
void | stun_set_debug_handler ()

## Types and Values

typedef | StunAgent
enum | StunCompatibility
enum | StunAgentUsageFlags
enum | StunValidationStatus
| StunDefaultValidaterData

## 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_WLM2009 `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 WLM2009 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

#### 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_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_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_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 WLM2009 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. |

### 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 |

### 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