stun.c File Reference


Detailed Description

STUN client module.

See RFC 3489/3489bis for further information.

Author:
Martti Mela <Martti.Mela@nokia-email.address.hidden>

Tat Chan <Tat.Chan@nokia-email.address.hidden>

Pekka Pessi <Pekka.Pessi@nokia-email.address.hidden>

Kai Vehmanen <Kai.Vehmanen@nokia-email.address.hidden>

Date:
Created: Thu Jul 24 17:21:00 2003 ppessi

#include "config.h"
#include <assert.h>
#include <string.h>
#include "sofia-sip/stun.h"
#include "stun_internal.h"
#include "sofia-sip/stun_tag.h"
#include <sofia-sip/su_alloc.h>
#include <sofia-sip/su_tagarg.h>
#include <sofia-sip/su_log.h>
#include <sofia-sip/su.h>
#include <sofia-sip/su_localinfo.h>

Include dependency graph for stun.c:


Typedefs

typedef enum stun_req_state_e stun_req_state_t
 States of STUN requests.

Enumerations

enum  stun_req_state_e { , stun_req_dispose_me }
 States of STUN requests. More...

Functions

char const * stun_nattype_str (stun_discovery_t *sd)
 Returns the NAT type attached to STUN discovery handle.
stun_nattype_t stun_nattype (stun_discovery_t *sd)
 Returns the detected NAT type.
su_root_tstun_root (stun_handle_t *self)
 Return su_root_t assigned to stun_handle_t.
int stun_is_requested (tag_type_t tag, tag_value_t value,...)
 Check if a STUN handle should be created.
stun_handle_t * stun_handle_init (su_root_t *root, tag_type_t tag, tag_value_t value,...)
 Creates a STUN handle.
int stun_obtain_shared_secret (stun_handle_t *sh, stun_discovery_f sdf, stun_discovery_magic_t *magic, tag_type_t tag, tag_value_t value,...)
 Performs shared secret request/response processing.
void stun_handle_destroy (stun_handle_t *sh)
 Destroy a STUN client.
int stun_bind (stun_handle_t *sh, stun_discovery_f sdf, stun_discovery_magic_t *magic, tag_type_t tag, tag_value_t value,...)
 Performs a STUN Binding Discovery (see RFC3489/3489bis) process.
int stun_discovery_get_address (stun_discovery_t *sd, void *addr, socklen_t *return_addrlen)
 Returns the address of the public binding allocated by the NAT.
int stun_test_nattype (stun_handle_t *sh, stun_discovery_f sdf, stun_discovery_magic_t *magic, tag_type_t tag, tag_value_t value,...)
 Initiates STUN discovery process to find out NAT characteristics.
int stun_make_sharedsecret_req (stun_msg_t *msg)
 Compose a STUN message of the format defined by stun_msg_t result encoded in enc_buf ready for sending as well.
int stun_make_binding_req (stun_handle_t *sh, stun_request_t *req, stun_msg_t *msg, tag_type_t tag, tag_value_t value,...)
 Compose a STUN message of the format defined by stun_msg_t.
int stun_process_binding_response (stun_msg_t *msg)
 process binding response
int stun_process_error_response (stun_msg_t *msg)
 process binding error response Report error and return
int stun_set_uname_pwd (stun_handle_t *sh, const char *uname, isize_t len_uname, const char *pwd, isize_t len_pwd)
 Sets values for USERNAME and PASSWORD stun fields for the handle.
int stun_atoaddr (su_home_t *home, int ai_family, su_addrinfo_t *info, char const *in)
 Converts character address format to sockaddr_in.
int stun_test_lifetime (stun_handle_t *sh, stun_discovery_f sdf, stun_discovery_magic_t *magic, tag_type_t tag, tag_value_t value,...)
 Initiates STUN discovery process to find out NAT binding life-time settings.
int stun_msg_is_keepalive (uint16_t data)
 Determines if the message is STUN message (-1 if not stun).
int stun_message_length (void *data, isize_t len, int end_of_message)
 Determines length of STUN message (0 (-1?) if not stun).
int stun_process_message (stun_handle_t *sh, su_socket_t s, su_sockaddr_t *sa, socklen_t salen, void *data, isize_t len)
 Process incoming message.
int stun_keepalive (stun_handle_t *sh, su_sockaddr_t *sa, tag_type_t tag, tag_value_t value,...)
 Creates a keepalive dispatcher for bound SIP sockets.
int stun_keepalive_destroy (stun_handle_t *sh, su_socket_t s)
 Destroys the keepalive dispatcher without touching the socket.
su_socket_t stun_discovery_get_socket (stun_discovery_t *sd)
 Returns socket attached to the discovery object.

Variables

su_log_t stun_log []
 STUN log.
char const stun_version []
 Name and version of STUN software.

Typedef Documentation

typedef enum stun_req_state_e stun_req_state_t

States of STUN requests.

See stun_state_e for states discovery processes.


Enumeration Type Documentation

enum stun_req_state_e

States of STUN requests.

See stun_state_e for states discovery processes.

Enumerator:
stun_req_dispose_me  request can be disposed


Function Documentation

int stun_bind ( stun_handle_t *  sh,
stun_discovery_f  sdf,
stun_discovery_magic_t magic,
tag_type_t  tag,
tag_value_t  value,
  ... 
)

Performs a STUN Binding Discovery (see RFC3489/3489bis) process.

To integrity protect the discovery process, first call stun_request_shared_secret() on the handle 'sh'.

If STUNTAG_REGISTER_SOCKET() is omitted, or set to false, the client is responsible for socket i/o. Other stun module will perform the whole discovery process and return the results via callback 'sdf'.

Parameters:
sh pointer to valid stun handle
sdf callback to signal process progress
magic context pointer attached to 'sdf'
tag,value,... list of tagged parameters.
Related Tags:
STUNTAG_SOCKET() Bind socket handle to STUN (socket handle).
STUNTAG_REGISTER_SOCKET() Register socket for eventloop owned by STUN (boolean)
Returns:
On success, zero is returned. Upon error, -1 is returned, and errno is set appropriately.
Errors:
EFAULT An invalid address is given as argument
EPROTONOSUPPORT Not a UDP socket.
EINVAL The socket is already bound to an address.
EACCESS The address is protected, and the user is not the super-user.
ENOTSOCK Argument is a descriptor for a file, not a socket.
EAGAIN Operation in progress. Application should call stun_bind() again when there is data available on the socket.

int stun_discovery_get_address ( stun_discovery_t *  sd,
void *  addr,
socklen_t *  return_addrlen 
)

Returns the address of the public binding allocated by the NAT.

In case of multiple on path NATs, the binding allocated by the outermost NAT is returned.

This function returns the local address seen from outside. Note that the address is not valid until the event stun_clien_done is launched.

stun_handle_t* stun_handle_init ( su_root_t root,
tag_type_t  tag,
tag_value_t  value,
  ... 
)

Creates a STUN handle.

The created handles can be used for STUN binding discovery, keepalives, and other STUN usages.

Parameters:
root eventloop to used by the stun state machine
tag,value,... tag-value list
Related Tags:
STUNTAG_DOMAIN() domain to use in DNS-SRV based STUN server
STUNTAG_SERVER() stun server hostname or dotted IPv4 address
STUNTAG_REQUIRE_INTEGRITY() true if msg integrity should be used enforced

int stun_is_requested ( tag_type_t  tag,
tag_value_t  value,
  ... 
)

Check if a STUN handle should be created.

Return true if STUNTAG_SERVER() or STUNTAG_DOMAIN() tags have been specified, or otherwise if STUN_SERVER environment variable is set.

Related Tags:
STUNTAG_DOMAIN() domain to use in DNS-SRV based STUN server
STUNTAG_SERVER() stun server hostname or dotted IPv4 address
Parameters:
tag,value,... tag-value list

stun_nattype_t stun_nattype ( stun_discovery_t *  sd  ) 

Returns the detected NAT type.

See also:
stun_nattype_str().

stun_test_nattype().

char const* stun_nattype_str ( stun_discovery_t *  sd  ) 

Returns the NAT type attached to STUN discovery handle.

See also:
stun_nattype_str().

stun_test_nattype().

int stun_obtain_shared_secret ( stun_handle_t *  sh,
stun_discovery_f  sdf,
stun_discovery_magic_t magic,
tag_type_t  tag,
tag_value_t  value,
  ... 
)

Performs shared secret request/response processing.

Result will be trigged in STUN handle callback (state one of stun_tls_*).

su_root_t* stun_root ( stun_handle_t *  self  ) 

Return su_root_t assigned to stun_handle_t.

Parameters:
self stun_handle_t object
Returns:
su_root_t object, NULL if self not given.

int stun_test_lifetime ( stun_handle_t *  sh,
stun_discovery_f  sdf,
stun_discovery_magic_t magic,
tag_type_t  tag,
tag_value_t  value,
  ... 
)

Initiates STUN discovery process to find out NAT binding life-time settings.

Related Tags:
STUNTAG_SOCKET Bind socket for STUN
STUNTAG_REGISTER_EVENTS Register socket for eventloop owned by STUN
STUNTAG_SERVER() stun server hostname or dotted IPv4 address
Returns:
0 on success, non-zero on error

int stun_test_nattype ( stun_handle_t *  sh,
stun_discovery_f  sdf,
stun_discovery_magic_t magic,
tag_type_t  tag,
tag_value_t  value,
  ... 
)

Initiates STUN discovery process to find out NAT characteristics.

Process partly follows the algorithm defined in RFC3489 section 10.1. Due the known limitations of RFC3489, some of the tests are done.

Note: does not support STUNTAG_DOMAIN() even if specified to stun_handle_init().

Related Tags:
STUNTAG_SOCKET Bind socket for STUN
STUNTAG_REGISTER_SOCKET Register socket for eventloop owned by STUN
STUNTAG_SERVER() stun server hostname or dotted IPv4 address
Returns:
0 on success, non-zero on error


Variable Documentation

su_log_t stun_log[]

STUN log.


Sofia-SIP 1.12.6 - Copyright (C) 2006 Nokia Corporation. All rights reserved. Licensed under the terms of the GNU Lesser General Public License.