Commit 259d6efa authored by Youness Alaoui's avatar Youness Alaoui
Browse files

Add documentation for libstun and fix some docs elsewhere

parent b5d0c1fd
......@@ -13,7 +13,7 @@ DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml
# gtk-doc will search all .c & .h files beneath here for inline comments
# documenting the functions and macros.
# e.g. DOC_SOURCE_DIR=../../../gtk
DOC_SOURCE_DIR=$(top_srcdir)/agent
DOC_SOURCE_DIR=$(top_srcdir)
# Extra options to pass to gtkdoc-scangobj. Not normally needed.
SCANGOBJ_OPTIONS=
......@@ -37,12 +37,20 @@ FIXXREF_OPTIONS=
# Used for dependencies. The docs will be rebuilt if any of these change.
# e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h
# e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c
HFILE_GLOB=$(DOC_SOURCE_DIR)/agent.h $(DOC_SOURCE_DIR)/address.h $(DOC_SOURCE_DIR)/debug.h $(DOC_SOURCE_DIR)/candidate.h $(DOC_SOURCE_DIR)/interfaces.h
CFILE_GLOB=$(DOC_SOURCE_DIR)/agent.c
HFILE_GLOB=$(DOC_SOURCE_DIR)/agent/agent.h $(DOC_SOURCE_DIR)/agent/address.h \
$(DOC_SOURCE_DIR)/agent/debug.h $(DOC_SOURCE_DIR)/agent/candidate.h \
$(DOC_SOURCE_DIR)/agent/interfaces.h \
$(DOC_SOURCE_DIR)/stun/stunmessage.h $(DOC_SOURCE_DIR)/stun/stun5389.h \
$(DOC_SOURCE_DIR)/stun/utils.h $(DOC_SOURCE_DIR)/stun/stunagent.h \
$(DOC_SOURCE_DIR)/stun/usages/bind.h \
$(DOC_SOURCE_DIR)/stun/usages/ice.h \
$(DOC_SOURCE_DIR)/stun/usages/timer.h \
$(DOC_SOURCE_DIR)/stun/usages/turn.h
CFILE_GLOB=$(DOC_SOURCE_DIR)/agent/agent.c
# Header files to ignore when scanning.
# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
IGNORE_HFILES= conncheck.h discovery.h stream.h
IGNORE_HFILES= conncheck.h discovery.h stream.h gstnice.h gstnicesrc.h gstnicesink.h
# Images to copy into HTML directory.
# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
......@@ -69,7 +77,7 @@ AM_CFLAGS = $(ERROR_CFLAGS) \
-I $(top_srcdir)/socket \
-I $(top_srcdir)/stun
GTKDOC_LIBS= $(top_builddir)/agent/libagent.la $(GLIB_LIBS)
GTKDOC_LIBS= $(top_builddir)/agent/libagent.la $(GLIB_LIBS) $(top_builddir)/stun/libstun.la
# This includes the standard gtk-doc make rules, copied by gtkdocize.
......
......@@ -17,5 +17,11 @@
<xi:include href="xml/debug.xml"/>
<xi:include href="xml/candidate.xml"/>
<xi:include href="xml/interfaces.xml"/>
<xi:include href="xml/stunagent.xml"/>
<xi:include href="xml/stunmessage.xml"/>
<xi:include href="xml/turn.xml"/>
<xi:include href="xml/bind.xml"/>
<xi:include href="xml/ice.xml"/>
<xi:include href="xml/timer.xml"/>
</chapter>
</book>
<SECTION>
<FILE>agent</FILE>
NICE_AGENT_MAX_REMOTE_CANDIDATES
<TITLE>NiceAgent</TITLE>
NiceAgent
NiceComponentState
NiceComponentType
NiceProxyType
NiceCompatibility
NiceAgentRecvFunc
<TITLE>NiceAgent</TITLE>
NiceAgent
NICE_AGENT_MAX_REMOTE_CANDIDATES
nice_agent_new
nice_agent_add_local_address
nice_agent_add_stream
......@@ -15,15 +16,14 @@ nice_agent_set_relay_info
nice_agent_gather_candidates
nice_agent_set_remote_credentials
nice_agent_get_local_credentials
nice_agent_add_remote_candidate
nice_agent_set_remote_candidates
nice_agent_send
nice_agent_get_local_candidates
nice_agent_get_remote_candidates
nice_agent_restart
nice_agent_get_local_candidates
nice_agent_send
nice_agent_attach_recv
nice_agent_set_selected_pair
nice_agent_set_selected_remote_candidate
nice_agent_restart
<SUBSECTION Standard>
NICE_AGENT
NICE_IS_AGENT
......@@ -36,25 +36,15 @@ NICE_AGENT_GET_CLASS
NiceAgentClass
</SECTION>
<SECTION>
<FILE>debug</FILE>
<TITLE>Debug messages</TITLE>
nice_debug_enable
nice_debug_disable
<SUBSECTION Private>
nice_debug_init
nice_debug
</SECTION>
<SECTION>
<FILE>candidate</FILE>
<TITLE>NiceCandidate</TITLE>
NICE_CANDIDATE_MAX_FOUNDATION
NiceCandidate
NiceCandidateType
NiceCandidateTransport
NiceRelayType
NiceCandidate
TurnServer
NiceRelayType
NICE_CANDIDATE_MAX_FOUNDATION
nice_candidate_new
nice_candidate_free
nice_candidate_copy
......@@ -70,22 +60,11 @@ nice_candidate_ice_priority
nice_candidate_pair_priority
</SECTION>
<SECTION>
<FILE>interfaces</FILE>
<TITLE>Network interfaces discovery</TITLE>
<INCLUDE>gst/farsight/fs-interfaces.h</INCLUDE>
nice_interfaces_get_ip_for_interface
nice_interfaces_get_local_interfaces
nice_interfaces_get_local_ips
</SECTION>
<SECTION>
<FILE>address</FILE>
<TITLE>NiceAddress</TITLE>
NICE_ADDRESS_STRING_LEN
NiceAddress
NICE_ADDRESS_STRING_LEN
nice_address_init
nice_address_new
nice_address_free
......@@ -104,51 +83,131 @@ nice_address_is_valid
</SECTION>
<SECTION>
<FILE>component</FILE>
<FILE>debug</FILE>
<TITLE>Debug messages</TITLE>
nice_debug_enable
nice_debug_disable
<SUBSECTION Private>
Component
CandidatePair
IncomingCheck
component_new
component_free
component_find_socket_by_fd
component_find_pair
component_restart
component_update_selected_pair
component_find_remote_candidate
component_set_selected_remote_candidate
nice_debug_init
nice_debug
</SECTION>
<SECTION>
<FILE>agent-priv</FILE>
<SUBSECTION Private>
NICE_AGENT_TIMER_TA_DEFAULT
NICE_AGENT_TIMER_TR_DEFAULT
NICE_AGENT_TIMER_TR_MIN
NICE_AGENT_MAX_CONNECTIVITY_CHECKS_DEFAULT
MAX_STUN_DATAGRAM_PAYLOAD
NiceAgent
agent_find_component
agent_find_stream
agent_gathering_done
agent_signal_gathering_done
agent_signal_new_selected_pair
agent_signal_component_state_change
agent_signal_new_candidate
agent_signal_new_remote_candidate
agent_signal_initial_binding_request_received
agent_candidate_pair_priority
agent_timeout_add_with_context
priv_attach_stream_component_socket
<FILE>interfaces</FILE>
<TITLE>Network interfaces discovery</TITLE>
nice_interfaces_get_ip_for_interface
nice_interfaces_get_local_interfaces
nice_interfaces_get_local_ips
</SECTION>
<SECTION>
<FILE>agent-signals-marshal</FILE>
<FILE>stunagent</FILE>
<TITLE>StunAgent</TITLE>
StunAgent
StunCompatibility
StunAgentUsageFlags
StunValidationStatus
StunMessageIntegrityValidate
StunDefaultValidaterData
stun_agent_init
stun_agent_validate
stun_agent_default_validater
stun_agent_init_request
stun_agent_init_indication
stun_agent_init_response
stun_agent_init_error
stun_agent_build_unknown_attributes_error
stun_agent_finish_message
stun_debug_enable
stun_debug_disable
<SUBSECTION Private>
agent_marshal_VOID__UINT_UINT_UINT
agent_marshal_VOID__UINT_UINT_STRING_STRING
agent_marshal_VOID__UINT_UINT_STRING
agent_marshal_VOID__UINT
StunAgentSavedIds
</SECTION>
<SECTION>
<FILE>stunmessage</FILE>
<TITLE>StunMessage</TITLE>
StunMessage
StunClass
StunMethod
StunAttribute
StunTransactionId
StunError
StunMessageReturn
STUN_MESSAGE_BUFFER_INCOMPLETE
STUN_MESSAGE_BUFFER_INVALID
stun_message_init
stun_message_length
stun_message_find
stun_message_find_flag
stun_message_find32
stun_message_find64
stun_message_find_string
stun_message_find_addr
stun_message_find_xor_addr
stun_message_find_xor_addr_full
stun_message_find_error
stun_message_append
stun_message_append_bytes
stun_message_append_flag
stun_message_append32
stun_message_append64
stun_message_append_string
stun_message_append_addr
stun_message_append_xor_addr
stun_message_append_xor_addr_full
stun_message_append_error
stun_message_validate_buffer_length
stun_message_id
stun_message_get_class
stun_message_get_method
stun_message_has_attribute
stun_message_has_cookie
stun_optional
stun_strerror
</SECTION>
<SECTION>
<FILE>turn</FILE>
StunUsageTurnCompatibility
StunUsageTurnRequestPorts
StunUsageTurnReturn
stun_usage_turn_create
stun_usage_turn_create_refresh
stun_usage_turn_process
stun_usage_turn_refresh_process
</SECTION>
<SECTION>
<FILE>ice</FILE>
StunUsageIceCompatibility
StunUsageIceReturn
stun_usage_ice_conncheck_create
stun_usage_ice_conncheck_process
stun_usage_ice_conncheck_create_reply
stun_usage_ice_conncheck_priority
stun_usage_ice_conncheck_use_candidate
</SECTION>
<SECTION>
<FILE>timer</FILE>
StunTimer
StunUsageTimerReturn
stun_timer_start
stun_timer_start_reliable
stun_timer_refresh
stun_timer_remainder
</SECTION>
<SECTION>
<FILE>bind</FILE>
StunUsageBindReturn
stun_usage_bind_create
stun_usage_bind_process
stun_usage_bind_keepalive
stun_usage_bind_run
</SECTION>
......@@ -60,10 +60,28 @@
#include <sys/types.h>
/**
* StunAgent:
*
* An opaque structure representing the STUN agent.
*/
typedef struct stun_agent_t StunAgent;
#include "stunmessage.h"
/**
* StunCompatibility:
* @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 that specifies the STUN compatibility mode of the #StunAgent
*/
typedef enum {
STUN_COMPATIBILITY_RFC3489,
STUN_COMPATIBILITY_RFC5389,
......@@ -72,31 +90,40 @@ typedef enum {
} StunCompatibility;
/**
* StunValidationStatus:
* @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
*
* This enum is used as the return value of stun_agent_validate() and represents
* the status result of the validation of a STUN message.
*/
typedef enum {
/* The message is validated */
STUN_VALIDATION_SUCCESS,
/* This is not a valid STUN message */
STUN_VALIDATION_NOT_STUN,
/* The message seems to be valid but incomplete */
STUN_VALIDATION_INCOMPLETE_STUN,
/* The message does not have the cookie or the fingerprint
* while the agent needs it with its usage */
STUN_VALIDATION_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_BAD_REQUEST,
/* The message is valid but unauthorized as the username/password do not match.
An UNAUTHORIZED error must be generated */
STUN_VALIDATION_UNAUTHORIZED,
/* The message is valid but this is a response/error that doesn't match
* a previously sent request */
STUN_VALIDATION_UNMATCHED_RESPONSE,
/* The message is valid but contains one or more unknown comprehension
* attributes. stun_agent_build_unknown_attributes_error should be called */
STUN_VALIDATION_UNKNOWN_REQUEST_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_UNKNOWN_ATTRIBUTE,
} StunValidationStatus;
......@@ -157,39 +184,251 @@ struct stun_agent_t {
StunAgentUsageFlags usage_flags;
};
/**
* StunDefaultValidaterData:
* @username: The username
* @username_len: The length of the @username
* @password: The password
* @password_len: The length of the @password
*
* 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.
* <para> See also: stun_agent_default_validater() </para>
*/
typedef struct {
uint8_t *username;
size_t username_len;
uint8_t *password;
size_t password_len;
} stun_validater_data;
} StunDefaultValidaterData;
/**
* StunMessageIntegrityValidate:
* @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
*
* This is the prototype for the @validater argument of the stun_agent_validate()
* function.
* <para> See also: stun_agent_validate() </para>
* Returns: %TRUE if the authentication was successful,
* %FALSE if the authentication failed
*/
typedef bool (*StunMessageIntegrityValidate) (StunAgent *agent,
StunMessage *message, uint8_t *username, uint16_t username_len,
uint8_t **password, size_t *password_len, void *user_data);
/**
* stun_agent_default_validater:
* @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
*
* 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
* <para> See also: stun_agent_validate() </para>
* Returns: %TRUE if the authentication was successful,
* %FALSE if the authentication failed
*/
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);
/**
* stun_agent_init:
* @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.
*
* This function must be called to initialize an agent before it is being used.
*
<note>
<para>
The @known_attributes data must exist in memory as long as the @agent is used
</para>
<para>
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
</para>
<para>
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
</para>
</note>
*/
void stun_agent_init (StunAgent *agent, const uint16_t *known_attributes,
StunCompatibility compatibility, uint32_t usage_flags);
StunCompatibility compatibility, StunAgentUsageFlags usage_flags);
/**
* stun_agent_validate:
* @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.
*
* 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.
* <para> See also: stun_agent_default_validater() </para>
* Returns: A #StunValidationStatus
<note>
<para>
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.
</para>
</note>
*/
StunValidationStatus stun_agent_validate (StunAgent *agent, StunMessage *msg,
const uint8_t *buffer, size_t buffer_len,
StunMessageIntegrityValidate validater, void * validater_data);
/**
* stun_agent_init_request:
* @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
*
* Creates a new STUN message of class #STUN_REQUEST and with the method @m
* Returns: %TRUE if the message was initialized correctly, %FALSE otherwise
*/
bool stun_agent_init_request (StunAgent *agent, StunMessage *msg,
uint8_t *buffer, size_t buffer_len, StunMethod m);
/**
* stun_agent_init_indication:
* @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
*
* Creates a new STUN message of class #STUN_INDICATION and with the method @m
* 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);
/**
* stun_agent_init_response:
* @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
*
* 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()
* 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);
/**
* stun_agent_init_error:
* @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
*
* 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.
* 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);
/**
* stun_agent_build_unknown_attributes_error:
* @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
*
* 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()
* Returns: The size of the message built
*/
size_t stun_agent_build_unknown_attributes_error (StunAgent *agent,
StunMessage *msg, uint8_t *buffer, size_t buffer_len,
const StunMessage *request);
/**
* stun_agent_finish_message:
* @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
*
* 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.
* Returns: The final size of the message built