Group PJNATH_STUN_SESSION

group PJNATH_STUN_SESSION

STUN client and server session.

This is is a transport-independent object to manage a client or server STUN session. It has the following features:

transport independent
:

the object does not have it’s own socket, but rather it provides functions and callbacks to send and receive packets. This way the object can be used by different transport types (e.g. UDP, TCP, TLS, etc.) as well as better integration to application which already has its own means to send and receive packets.
authentication management
:

the object manages STUN authentication throughout the lifetime of the session. For client sessions, once it’s given a credential to authenticate itself with the server, the object will automatically add authentication info (the MESSAGE-INTEGRITY) to the request as well as authenticate the response. It will also handle long-term authentication challenges, including handling of nonce expiration, and retry the request automatically. For server sessions, it can be configured to authenticate incoming requests automatically.
static or dynamic credential
:

application may specify static or dynamic credential to be used by the STUN session. Static credential means a static combination of username and password (and these cannot change during the session duration), while dynamic credential provides callback to ask the application about which username/password to use everytime authentication is about to be performed.
client transaction management
:

outgoing requests may be sent with a STUN transaction for reliability, and the object will manage the transaction internally (including performing retransmissions). Application will be notified about the result of the request when the response arrives (or the transaction times out). When the request is challenged with authentication, the object will retry the request with new authentication info, and application will be notified about the final result of this request.
server transaction management
:

application may ask response to incoming requests to be cached by the object, and in this case the object will check for cached response everytime request is received. The cached response will be deleted once a timer expires.

Using the STUN session

The following steps describes how to use the STUN session:

create the object configuration
:

The
pj_stun_config contains the configuration to create the STUN session, such as the timer heap to register internal timers and various STUN timeout values. You can initialize this structure by calling pj_stun_config_init()
create the STUN session
:

by calling
pj_stun_session_create(). Among other things, this function requires the instance of pj_stun_config and also pj_stun_session_cb structure which stores callbacks to send outgoing packets as well as to notify application about incoming STUN requests, responses, and indicates and other events.
configure credential: if authentication is required for the session, configure the credential with pj_stun_session_set_credential()
configuring other settings: several APIs are provided to configure the behavior of the STUN session (for example, to set the SOFTWARE attribute value, controls the logging behavior, fine tune the mutex locking, etc.). Please see the API reference for more info.
creating outgoing STUN requests or indications: create the STUN message by using pj_stun_session_create_req() or pj_stun_session_create_ind(). This will create a transmit data buffer containing a blank STUN request or indication. You will then typically need to add STUN attributes that are relevant to the request or indication, but note that some default attributes will be added by the session later when the message is sent (such as SOFTWARE attribute and attributes related to authentication). The message is now ready to be sent.
sending outgoing message: use pj_stun_session_send_msg() to send outgoing STUN messages (this includes STUN requests, indications, and responses). The function has options whether to retransmit the request (for non reliable transports) or to cache the response if we’re sending response. This function in turn will call the on_send_msg() callback of pj_stun_session_cb to request the application to send the packet.
handling incoming packet: call pj_stun_session_on_rx_pkt() everytime the application receives a STUN packet. This function will decode the packet and process the packet according to the message, and normally this will cause one of the callback in the pj_stun_session_cb to be called to notify the application about the event.
handling incoming requests: incoming requests are notified to application in the on_rx_request callback of the pj_stun_session_cb. If authentication is enabled in the session, the application will only receive this callback after the incoming request has been authenticated (if the authentication fails, the session would respond automatically with 401 error and the callback will not be called). Application now must create and send response for this request.
creating and sending response: create the STUN response with pj_stun_session_create_res(). This will create a transmit data buffer containing a blank STUN response. You will then typically need to add STUN attributes that are relevant to the response, but note that some default attributes will be added by the session later when the message is sent (such as SOFTWARE attribute and attributes related to authentication). The message is now ready to be sent. Use pj_stun_session_send_msg() (as explained above) to send the response.
convenient way to send response: the pj_stun_session_respond() is provided as a convenient way to create and send simple STUN responses, such as error responses.
destroying the session: once the session is done, use pj_stun_session_destroy() to destroy the session.

Typedefs

typedef struct pj_stun_session pj_stun_session: Forward declaration for pj_stun_session

Enums

enum pj_stun_sess_msg_log_flag

These are the flags to control the message logging in the STUN session.

Values:

enumerator PJ_STUN_SESS_LOG_TX_REQ: Log outgoing STUN requests.

enumerator PJ_STUN_SESS_LOG_TX_RES: Log outgoing STUN responses.

enumerator PJ_STUN_SESS_LOG_TX_IND: Log outgoing STUN indications.

enumerator PJ_STUN_SESS_LOG_RX_REQ: Log incoming STUN requests.

enumerator PJ_STUN_SESS_LOG_RX_RES: Log incoming STUN responses

enumerator PJ_STUN_SESS_LOG_RX_IND: Log incoming STUN indications

Functions

pj_status_t pj_stun_session_create(pj_stun_config *cfg, const char *name, const pj_stun_session_cb *cb, pj_bool_t fingerprint, pj_grp_lock_t *grp_lock, pj_stun_session **p_sess)

Create a STUN session.

Parameters:

cfg – The STUN endpoint, to be used to register timers etc.
name – Optional name to be associated with this instance. The name will be used for example for logging purpose.
cb – Session callback.
fingerprint – Enable message fingerprint for outgoing messages.
grp_lock – Optional group lock to be used by this session. If NULL, the session will create one itself.
p_sess – Pointer to receive STUN session instance.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pj_stun_session_destroy(pj_stun_session *sess)

Destroy the STUN session and all objects created in the context of this session.

Parameters:: sess – The STUN session instance.
Returns:: PJ_SUCCESS on success, or the appropriate error code. This function will return PJ_EPENDING if the operation cannot be performed immediately because callbacks are being called; in this case the session will be destroyed as soon as the last callback returns.

pj_status_t pj_stun_session_set_user_data(pj_stun_session *sess, void *user_data)

Associated an arbitrary data with this STUN session. The user data may be retrieved later with pj_stun_session_get_user_data() function.

Parameters:

sess – The STUN session instance.
user_data – The user data.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

void *pj_stun_session_get_user_data(pj_stun_session *sess)

Retrieve the user data previously associated to this STUN session with pj_stun_session_set_user_data().

Parameters:: sess – The STUN session instance.
Returns:: The user data associated with this STUN session.

pj_grp_lock_t *pj_stun_session_get_grp_lock(pj_stun_session *sess)

Get the group lock for this STUN session.

Parameters:: sess – The STUN session instance.
Returns:: The group lock.

pj_status_t pj_stun_session_set_software_name(pj_stun_session *sess, const pj_str_t *sw)

Set SOFTWARE name to be included in all requests and responses.

Parameters:

sess – The STUN session instance.
sw – Software name string. If this argument is NULL or empty, the session will not include SOFTWARE attribute in STUN requests and responses.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pj_stun_session_set_credential(pj_stun_session *sess, pj_stun_auth_type auth_type, const pj_stun_auth_cred *cred)

Set credential to be used by this session. Once credential is set, all outgoing messages will include MESSAGE-INTEGRITY, and all incoming message will be authenticated against this credential.

To disable authentication after it has been set, call this function again with NULL as the argument.

Parameters:

sess – The STUN session instance.
auth_type – Type of authentication.
cred – The credential to be used by this session. If NULL is specified, authentication will be disabled.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

void pj_stun_session_set_log(pj_stun_session *sess, unsigned flags)

Configure message logging. By default all flags are enabled.

Parameters:

sess – The STUN session instance.
flags – Bitmask combination of pj_stun_sess_msg_log_flag

pj_bool_t pj_stun_session_use_fingerprint(pj_stun_session *sess, pj_bool_t use)

Configure whether the STUN session should utilize FINGERPRINT in outgoing messages.

Parameters:

sess – The STUN session instance.
use – Boolean for the setting.

Returns:

The previous configured value of FINGERPRINT utilization of the sessoin.

pj_status_t pj_stun_session_create_req(pj_stun_session *sess, int msg_type, pj_uint32_t magic, const pj_uint8_t tsx_id[12], pj_stun_tx_data **p_tdata)

Create a STUN request message. After the message has been successfully created, application can send the message by calling pj_stun_session_send_msg().

Parameters:

sess – The STUN session instance.
msg_type – The STUN request message type, from pj_stun_method_e or from pj_stun_msg_type.
magic – STUN magic, use PJ_STUN_MAGIC.
tsx_id – Optional transaction ID.
p_tdata – Pointer to receive STUN transmit data instance containing the request.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pj_stun_session_create_ind(pj_stun_session *sess, int msg_type, pj_stun_tx_data **p_tdata)

Create a STUN Indication message. After the message has been successfully created, application can send the message by calling pj_stun_session_send_msg().

Parameters:

sess – The STUN session instance.
msg_type – The STUN request message type, from pj_stun_method_e or from pj_stun_msg_type. This function will add the indication bit as necessary.
p_tdata – Pointer to receive STUN transmit data instance containing the message.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pj_stun_session_create_res(pj_stun_session *sess, const pj_stun_rx_data *rdata, unsigned err_code, const pj_str_t *err_msg, pj_stun_tx_data **p_tdata)

Create a STUN response message. After the message has been successfully created, application can send the message by calling pj_stun_session_send_msg(). Alternatively application may use pj_stun_session_respond() to create and send response in one function call.

Parameters:

sess – The STUN session instance.
rdata – The STUN request where the response is to be created.
err_code – Error code to be set in the response, if error response is to be created, according to pj_stun_status enumeration. This argument MUST be zero if successful response is to be created.
err_msg – Optional pointer for the error message string, when creating error response. If the value is NULL and the err_code is non-zero, then default error message will be used.
p_tdata – Pointer to receive the response message created.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pj_stun_session_send_msg(pj_stun_session *sess, void *token, pj_bool_t cache_res, pj_bool_t retransmit, const pj_sockaddr_t *dst_addr, unsigned addr_len, pj_stun_tx_data *tdata)

Send STUN message to the specified destination. This function will encode the pj_stun_msg instance to a packet buffer, and add credential or fingerprint if necessary. If the message is a request, the session will also create and manage a STUN client transaction to be used to manage the retransmission of the request. After the message has been encoded and transaction is setup, the on_send_msg() callback of pj_stun_session_cb (which is registered when the STUN session is created) will be called to actually send the message to the wire.

Parameters:

sess – The STUN session instance.
token – Optional token which will be given back to application in on_send_msg() callback and on_request_complete() callback, if the message is a STUN request message. Internally this function will put the token in the token field of pj_stun_tx_data, hence it will overwrite any value that the application puts there.
cache_res – If the message is a response message for an incoming request, specify PJ_TRUE to instruct the STUN session to cache this response for subsequent incoming request retransmission. Otherwise this parameter will be ignored for non-response message.
retransmit – If the message is a request message, specify whether the request should be retransmitted. Normally application will specify TRUE if the underlying transport is UDP and FALSE if the underlying transport is TCP or TLS.
dst_addr – The destination socket address.
addr_len – Length of destination address.
tdata – The STUN transmit data containing the STUN message to be sent.

Returns:

PJ_SUCCESS on success, or the appropriate error code. This function will return PJNATH_ESTUNDESTROYED if application has destroyed the session in on_send_msg() callback.

pj_status_t pj_stun_session_respond(pj_stun_session *sess, const pj_stun_rx_data *rdata, unsigned code, const char *err_msg, void *token, pj_bool_t cache, const pj_sockaddr_t *dst_addr, unsigned addr_len)

This is a utility function to create and send response for an incoming STUN request. Internally this function calls pj_stun_session_create_res() and pj_stun_session_send_msg(). It is provided here as a matter of convenience.

Parameters:

sess – The STUN session instance.
rdata – The STUN request message to be responded.
code – Error code to be set in the response, if error response is to be created, according to pj_stun_status enumeration. This argument MUST be zero if successful response is to be created.
err_msg – Optional pointer for the error message string, when creating error response. If the value is NULL and the err_code is non-zero, then default error message will be used.
token – Optional token which will be given back to application in on_send_msg() callback and on_request_complete() callback, if the message is a STUN request message. Internally this function will put the token in the token field of pj_stun_tx_data, hence it will overwrite any value that the application puts there.
cache – Specify whether session should cache this response for future request retransmission. If TRUE, subsequent request retransmission will be handled by the session and it will not call request callback.
dst_addr – Destination address of the response (or equal to the source address of the original request).
addr_len – Address length.

Returns:

PJ_SUCCESS on success, or the appropriate error code. This function will return PJNATH_ESTUNDESTROYED if application has destroyed the session in on_send_msg() callback.

pj_status_t pj_stun_session_cancel_req(pj_stun_session *sess, pj_stun_tx_data *tdata, pj_bool_t notify, pj_status_t status)

Cancel outgoing STUN transaction. This operation is only valid for outgoing STUN request, to cease retransmission of the request and destroy the STUN client transaction that is used to send the request.

Parameters:

sess – The STUN session instance.
tdata – The request message previously sent.
notify – Specify whether on_request_complete() callback should be called.
status – If on_request_complete() callback is to be called, specify the error status to be given when calling the callback. This error status MUST NOT be PJ_SUCCESS.

Returns:

PJ_SUCCESS if transaction is successfully cancelled. This function will return PJNATH_ESTUNDESTROYED if application has destroyed the session in on_request_complete() callback.

pj_status_t pj_stun_session_retransmit_req(pj_stun_session *sess, pj_stun_tx_data *tdata, pj_bool_t mod_count)

Explicitly request retransmission of the request. Normally application doesn’t need to do this, but this functionality is needed by ICE to speed up connectivity check completion.

Parameters:

sess – The STUN session instance.
tdata – The request message previously sent.
mod_count – Boolean flag to indicate whether transmission count needs to be incremented.

Returns:

PJ_SUCCESS on success, or the appropriate error. This function will return PJNATH_ESTUNDESTROYED if application has destroyed the session in on_send_msg() callback.

pj_status_t pj_stun_session_on_rx_pkt(pj_stun_session *sess, const void *packet, pj_size_t pkt_size, unsigned options, void *token, pj_size_t *parsed_len, const pj_sockaddr_t *src_addr, unsigned src_addr_len)

Application must call this function to notify the STUN session about the arrival of STUN packet. The STUN packet MUST have been checked first with pj_stun_msg_check() to verify that this is indeed a valid STUN packet.

The STUN session will decode the packet into pj_stun_msg, and process the message accordingly. If the message is a response, it will search through the outstanding STUN client transactions for a matching transaction ID and hand over the response to the transaction.

On successful message processing, application will be notified about the message via one of the pj_stun_session_cb callback.

Parameters:

sess – The STUN session instance.
packet – The packet containing STUN message.
pkt_size – Size of the packet.
options – Options, from pj_stun_decode_options.
parsed_len – Optional pointer to receive the size of the parsed STUN message (useful if packet is received via a stream oriented protocol).
token – Optional token which will be given back to application in the on_rx_request(), on_rx_indication() and on_send_msg() callbacks. The token can be used to associate processing or incoming request or indication with some context.
src_addr – The source address of the packet, which will also be given back to application callbacks, along with source address length.
src_addr_len – Length of the source address.

Returns:

PJ_SUCCESS on success, or the appropriate error code. This function will return PJNATH_ESTUNDESTROYED if application has destroyed the session in one of the callback.

void pj_stun_msg_destroy_tdata(pj_stun_session *sess, pj_stun_tx_data *tdata)

Destroy the transmit data. Call this function only when tdata has been created but application doesn’t want to send the message (perhaps because of other error).

Parameters:

sess – The STUN session.
tdata – The transmit data.

struct pj_stun_session_cb

#include <stun_session.h>

This is the callback to be registered to pj_stun_session, to send outgoing message and to receive various notifications from the STUN session.

Public Members

pj_status_t (*on_send_msg)(pj_stun_session *sess, void *token, const void *pkt, pj_size_t pkt_size, const pj_sockaddr_t *dst_addr, unsigned addr_len)

Callback to be called by the STUN session to send outgoing message.

Param sess:: The STUN session.
Param token:: The token associated with this outgoing message and was set by the application. This token was set by application in pj_stun_session_send_msg() for outgoing messages that are initiated by the application, or in pj_stun_session_on_rx_pkt() if this message is a response that was internally generated by the STUN session (for example, an 401/Unauthorized response). Application may use this facility for any purposes.
Param pkt:: Packet to be sent.
Param pkt_size:: Size of the packet to be sent.
Param dst_addr:: The destination address.
Param addr_len:: Length of destination address.
Return:: The callback should return the status of the packet sending.

pj_status_t (*on_rx_request)(pj_stun_session *sess, const pj_uint8_t *pkt, unsigned pkt_len, const pj_stun_rx_data *rdata, void *token, const pj_sockaddr_t *src_addr, unsigned src_addr_len)

Callback to be called on incoming STUN request message. This function is called when application calls pj_stun_session_on_rx_pkt() and when the STUN session has detected that the incoming STUN message is a STUN request message. In the callback processing, application MUST create a response by calling pj_stun_session_create_response() function and send the response with pj_stun_session_send_msg() function, before returning from the callback.

Param sess:: The STUN session.
Param pkt:: Pointer to the original STUN packet.
Param pkt_len:: Length of the STUN packet.
Param rdata:: Data containing incoming request message.
Param token:: The token that was set by the application when calling pj_stun_session_on_rx_pkt() function.
Param src_addr:: Source address of the packet.
Param src_addr_len:: Length of the source address.
Return:: The return value of this callback will be returned back to pj_stun_session_on_rx_pkt() function.

void (*on_request_complete)(pj_stun_session *sess, pj_status_t status, void *token, pj_stun_tx_data *tdata, const pj_stun_msg *response, const pj_sockaddr_t *src_addr, unsigned src_addr_len)

Callback to be called when response is received or the transaction has timed out. This callback is called either when application calls pj_stun_session_on_rx_pkt() with the packet containing a STUN response for the client transaction, or when the internal timer of the STUN client transaction has timed-out before a STUN response is received.

Param sess:: The STUN session.
Param status:: Status of the request. If the value if not PJ_SUCCESS, the transaction has timed-out or other error has occurred, and the response argument may be NULL. Note that when the status is not success, the response may contain non-NULL value if the response contains STUN ERROR-CODE attribute.
Param token:: The token that was set by the application when calling pj_stun_session_send_msg() function. Please not that this token IS NOT the token that was given in pj_stun_session_on_rx_pkt().
Param tdata:: The original STUN request.
Param response:: The response message, on successful transaction, or otherwise MAY BE NULL if status is not success. Note that when the status is not success, this argument may contain non-NULL value if the response contains STUN ERROR-CODE attribute.
Param src_addr:: The source address where the response was received, or NULL if the response is NULL.
Param src_addr_len:: The length of the source address.

pj_status_t (*on_rx_indication)(pj_stun_session *sess, const pj_uint8_t *pkt, unsigned pkt_len, const pj_stun_msg *msg, void *token, const pj_sockaddr_t *src_addr, unsigned src_addr_len)

Callback to be called on incoming STUN request message. This function is called when application calls pj_stun_session_on_rx_pkt() and when the STUN session has detected that the incoming STUN message is a STUN indication message.

Param sess:: The STUN session.
Param pkt:: Pointer to the original STUN packet.
Param pkt_len:: Length of the STUN packet.
Param msg:: The parsed STUN indication.
Param token:: The token that was set by the application when calling pj_stun_session_on_rx_pkt() function.
Param src_addr:: Source address of the packet.
Param src_addr_len:: Length of the source address.
Return:: The return value of this callback will be returned back to pj_stun_session_on_rx_pkt() function.

struct pj_stun_rx_data

#include <stun_session.h>

This structure describes incoming request message.

Forward declaration for pj_stun_rx_data

Public Members

pj_stun_msg *msg: The parsed request message.

pj_stun_req_cred_info info: Credential information that is found and used to authenticate incoming request. Application may use this information when generating authentication for the outgoing response.

struct pj_stun_tx_data

#include <stun_session.h>

This structure describe the outgoing STUN transmit data to carry the message to be sent.

Forward declaration for pj_stun_tx_data

Public Functions

PJ_DECL_LIST_MEMBER(struct pj_stun_tx_data): PJLIB list interface

Public Members

pj_pool_t *pool: Pool.

pj_stun_session *sess: The STUN session.

pj_stun_msg *msg: The STUN message.

pj_bool_t is_destroying: Is destroying?

void *token: The token.

pj_stun_client_tsx *client_tsx: Client STUN transaction.

pj_bool_t retransmit: Retransmit request?

pj_uint32_t msg_magic: Message magic.

pj_uint8_t msg_key[12]: Message/transaction key.

pj_grp_lock_t *grp_lock: Group lock (for resp cache).

pj_stun_req_cred_info auth_info: Credential info

void *pkt: The STUN packet.

unsigned max_len: Length of packet buffer.

pj_size_t pkt_size: The actual length of STUN pkt.

unsigned addr_len: Length of destination address.

const pj_sockaddr_t *dst_addr: Destination address.

pj_timer_entry res_timer: Response cache timer.