![]() |
![]() |
![]() |
libnice Reference Manual | ![]() |
---|---|---|---|---|
#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);
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.
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
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. |
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 |
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
|
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
|
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
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. |
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 |
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
|
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
|
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
|
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
|
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
|
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 |
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
NoteThe 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 |
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
|