BLOG | DOCUMENTATION | TRAC

Home --> Documentations --> PJNATH Reference

STUN client and server session. More...

Data Structures

struct  pj_stun_session_cb
 
struct  pj_stun_rx_data
 
struct  pj_stun_tx_data
 

Typedefs

typedef struct pj_stun_session pj_stun_session
 

Enumerations

enum  pj_stun_sess_msg_log_flag {
  PJ_STUN_SESS_LOG_TX_REQ =1,
  PJ_STUN_SESS_LOG_TX_RES =2,
  PJ_STUN_SESS_LOG_TX_IND =4,
  PJ_STUN_SESS_LOG_RX_REQ =8,
  PJ_STUN_SESS_LOG_RX_RES =16,
  PJ_STUN_SESS_LOG_RX_IND =32
}
 

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)
 
pj_status_t pj_stun_session_destroy (pj_stun_session *sess)
 
pj_status_t pj_stun_session_set_user_data (pj_stun_session *sess, void *user_data)
 
void * pj_stun_session_get_user_data (pj_stun_session *sess)
 
pj_grp_lock_tpj_stun_session_get_grp_lock (pj_stun_session *sess)
 
pj_status_t pj_stun_session_set_software_name (pj_stun_session *sess, const pj_str_t *sw)
 
pj_status_t pj_stun_session_set_credential (pj_stun_session *sess, pj_stun_auth_type auth_type, const pj_stun_auth_cred *cred)
 
void pj_stun_session_set_log (pj_stun_session *sess, unsigned flags)
 
pj_bool_t pj_stun_session_use_fingerprint (pj_stun_session *sess, pj_bool_t use)
 
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)
 
pj_status_t pj_stun_session_create_ind (pj_stun_session *sess, int msg_type, pj_stun_tx_data **p_tdata)
 
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)
 
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)
 
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)
 
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)
 
pj_status_t pj_stun_session_retransmit_req (pj_stun_session *sess, pj_stun_tx_data *tdata, pj_bool_t mod_count)
 
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)
 
void pj_stun_msg_destroy_tdata (pj_stun_session *sess, pj_stun_tx_data *tdata)
 

Detailed Description

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.

Typedef Documentation

Forward declaration for pj_stun_session

Enumeration Type Documentation

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

Enumerator
PJ_STUN_SESS_LOG_TX_REQ 

Log outgoing STUN requests.

PJ_STUN_SESS_LOG_TX_RES 

Log outgoing STUN responses.

PJ_STUN_SESS_LOG_TX_IND 

Log outgoing STUN indications.

PJ_STUN_SESS_LOG_RX_REQ 

Log incoming STUN requests.

PJ_STUN_SESS_LOG_RX_RES 

Log incoming STUN responses

PJ_STUN_SESS_LOG_RX_IND 

Log incoming STUN indications

Function Documentation

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
sessThe STUN session.
tdataThe transmit data.
Returns
PJ_SUCCESS on success, or the appropriate error code.
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
sessThe STUN session instance.
tdataThe request message previously sent.
notifySpecify whether on_request_complete() callback should be called.
statusIf 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_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
cfgThe STUN endpoint, to be used to register timers etc.
nameOptional name to be associated with this instance. The name will be used for example for logging purpose.
cbSession callback.
fingerprintEnable message fingerprint for outgoing messages.
grp_lockOptional group lock to be used by this session. If NULL, the session will create one itself.
p_sessPointer to receive STUN session instance.
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
sessThe STUN session instance.
msg_typeThe 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_tdataPointer 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_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
sessThe STUN session instance.
msg_typeThe STUN request message type, from pj_stun_method_e or from pj_stun_msg_type.
magicSTUN magic, use PJ_STUN_MAGIC.
tsx_idOptional transaction ID.
p_tdataPointer 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_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
sessThe STUN session instance.
rdataThe STUN request where the response is to be created.
err_codeError 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_msgOptional 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_tdataPointer to receive the response message created.
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
sessThe 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_grp_lock_t* pj_stun_session_get_grp_lock ( pj_stun_session sess)

Get the group lock for this STUN session.

Parameters
sessThe STUN session instance.
Returns
The group lock.
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
sessThe STUN session instance.
Returns
The user data associated with this STUN session.
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
sessThe STUN session instance.
packetThe packet containing STUN message.
pkt_sizeSize of the packet.
optionsOptions, from pj_stun_decode_options.
parsed_lenOptional pointer to receive the size of the parsed STUN message (useful if packet is received via a stream oriented protocol).
tokenOptional 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_addrThe source address of the packet, which will also be given back to application callbacks, along with source address length.
src_addr_lenLength 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.
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
sessThe STUN session instance.
rdataThe STUN request message to be responded.
codeError 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_msgOptional 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.
tokenOptional 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.
cacheSpecify 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_addrDestination address of the response (or equal to the source address of the original request).
addr_lenAddress 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_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
sessThe STUN session instance.
tdataThe request message previously sent.
mod_countBoolean 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_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
sessThe STUN session instance.
tokenOptional 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_resIf 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.
retransmitIf 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_addrThe destination socket address.
addr_lenLength of destination address.
tdataThe 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_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
sessThe STUN session instance.
auth_typeType of authentication.
credThe 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
sessThe STUN session instance.
flagsBitmask combination of pj_stun_sess_msg_log_flag
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
sessThe STUN session instance.
swSoftware 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_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
sessThe STUN session instance.
user_dataThe user data.
Returns
PJ_SUCCESS on success, or the appropriate error code.
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
sessThe STUN session instance.
useBoolean for the setting.
Returns
The previous configured value of FINGERPRINT utilization of the sessoin.

 


PJNATH - Open Source NAT traversal helper library supporting STUN, TURN, and ICE
Copyright (C) 2006-2009 Teluu Inc.