Loading...
Searching...
No Matches
stun.h File Reference

STUN module public interface. More...

`#include <sofia-sip/stun_common.h>`
`#include <sofia-sip/su_wait.h>`
`#include <sofia-sip/su_tag.h>`
`#include <sofia-sip/su_localinfo.h>`
Include dependency graph for stun.h:

Go to the source code of this file.

## Macros

#define | STUN_H
| Defined when <sofia-sip/stun.h> has been included.

## Typedefs

typedef STUN_MAGIC_T | stun_magic_t
| STUN server context.
typedef STUN_DISCOVERY_MAGIC_T | stun_discovery_magic_t
| STUN discovery_ context.
typedef enum stun_action_s | stun_action_t
| STUN Action types.
typedef enum stun_nattype_e | stun_nattype_t
| NAT types.
typedef enum stun_state_e | stun_state_t
| States of the STUN client->server query process.
typedef int(* | stun_send_callback) (stun_magic_t *magic, stun_handle_t *sh, int socket, void *data, unsigned len, int only_a_keepalive)
| Callback invoked by stun handle when it has a message to send.
typedef void(* | stun_dns_lookup_f) (stun_dns_lookup_t *self, stun_magic_t *magic)
| Callback for delivering DNS lookup results.

## Enumerations

enum | stun_action_s
| STUN Action types. More...
enum | stun_nattype_e
| NAT types. More...
enum | stun_state_e { }
| States of the STUN client->server query process. More...

## Functions

stun_handle_t * | stun_handle_init (su_root_t *root, tag_type_t, tag_value_t,...)
| Creates a STUN handle.
void | stun_handle_destroy (stun_handle_t *sh)
| Destroy a STUN client.
su_root_t * | stun_root (stun_handle_t *sh)
| 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.
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_obtain_shared_secret (stun_handle_t *sh, stun_discovery_f, stun_discovery_magic_t *magic, tag_type_t tag, tag_value_t value,...)
| Performs shared secret request/response processing.
int | stun_bind (stun_handle_t *sh, stun_discovery_f, 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.
su_socket_t | stun_discovery_get_socket (stun_discovery_t *sd)
| Returns socket attached to the discovery object.
int | stun_test_nattype (stun_handle_t *sh, stun_discovery_f, stun_discovery_magic_t *magic, tag_type_t tag, tag_value_t value,...)
| Initiates STUN discovery process to find out NAT characteristics.
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.
int | stun_test_lifetime (stun_handle_t *sh, stun_discovery_f, 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_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_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_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.
stun_dns_lookup_t * | stun_dns_lookup (stun_magic_t *magic, su_root_t *root, stun_dns_lookup_f func, const char *domain)
| Performs a DNS-SRV check for STUN 'stun' (tcp) and 'stun' (udp) services for 'domain'.
void | stun_dns_lookup_destroy (stun_dns_lookup_t *self)
| Destroys the 'self' object created by stun_dns_lookup_destroy().
int | stun_dns_lookup_udp_addr (stun_dns_lookup_t *, const char **target, uint16_t *port)
| Fetches the results of a completed STUN DNS-SRV lookup for "_stun._udp" service (RFC3489/3489bis).
int | stun_dns_lookup_tcp_addr (stun_dns_lookup_t *self, const char **target, uint16_t *port)
| Fetches the results of a completed STUN DNS-SRV lookup for "_stun._tcp" service (RFC3489).
int | stun_dns_lookup_stp_addr (stun_dns_lookup_t *self, const char **target, uint16_t *port)
| Fetches the results of a completed STUN DNS-SRV lookup for "_stun._udp" service (3489bis, "Short-Term Password").
stun_mini_t * | stun_mini_create (void)
| Create a stun miniserver.
void | stun_mini_destroy (stun_mini_t *)
| Destroy a stun miniserver.
int | stun_mini_add_socket (stun_mini_t *server, su_socket_t socket)
| Add a socket to stun miniserver.
int | stun_mini_remove_socket (stun_mini_t *server, su_socket_t socket)
| Remove socket from stun miniserver.

## Variables

char const | stun_version []
| Name and version of STUN software.

## Detailed Description

STUN module public interface.

Author
  Martti Mela Martt.nosp@m.i.Me.nosp@m.la@no.nosp@m.kia..nosp@m.com
  Tat Chan Tat.C.nosp@m.han@.nosp@m.nokia.nosp@m..com
  Pekka Pessi Pekka.nosp@m..Pes.nosp@m.si@no.nosp@m.kia..nosp@m.com
  Kai Vehmanen kai.v.nosp@m.ehma.nosp@m.nen@n.nosp@m.okia.nosp@m..com

## Typedef Documentation

## stun_action_t

typedef enum stun_action_s stun_action_t

STUN Action types.

These define the current discovery process. Defined as a bitmap.

## stun_nattype_t

typedef enum stun_nattype_e stun_nattype_t

NAT types.

XXX: should be extended to distinguish between filtering and mapping allocation behaviour (see IETF BEHAVE documents)

Note: the NAT type detection algorithm can fail in case where the NAT behaves in a nondeterministic fashion.

## stun_state_t

typedef enum stun_state_e stun_state_t

States of the STUN client->server query process.

See also
  stun_bind()
  stun_obtain_shared_secret()
  stun_test_nattype()
  stun_test_lifetime()

## Enumeration Type Documentation

## stun_action_s

enum stun_action_s

STUN Action types.

These define the current discovery process. Defined as a bitmap.

## stun_nattype_e

enum stun_nattype_e

NAT types.

XXX: should be extended to distinguish between filtering and mapping allocation behaviour (see IETF BEHAVE documents)

Note: the NAT type detection algorithm can fail in case where the NAT behaves in a nondeterministic fashion.

## stun_state_e

enum stun_state_e

States of the STUN client->server query process.

See also
  stun_bind()
  stun_obtain_shared_secret()
  stun_test_nattype()
  stun_test_lifetime()

Enumerator
stun_tls_connecting | Connecting to TLS port.
stun_tls_ssl_connecting | Started the TLS/SSL handshake.
stun_tls_writing | Next step: send request.
stun_tls_closing | Closing TLS connection.
stun_tls_reading | Request send, waiting for response.
stun_tls_done | Shared-secret acquired.
stun_discovery_done | Discovery process done.
stun_error | Generic error in discovery process.
stun_tls_connection_timeout | No response to connect attempt.
stun_tls_connection_failed | No response from TLS/SSL server.
stun_tls_ssl_connect_failed | TLS/SSL handshake failed.
stun_discovery_error | Error in discovery process.
stun_discovery_timeout | No response to discovery request.

## Function Documentation

## stun_bind()

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:

\n STUNTAG_SOCKET() Bind socket handle to STUN (socket handle).

\n 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:

\n EFAULT An invalid address is given as argument

\n EPROTONOSUPPORT Not a UDP socket.

\n EINVAL The socket is already bound to an address.

\n EACCESS The address is protected, and the user is not
  the super-user.

\n ENOTSOCK Argument is a descriptor for a file, not a socket.

\n EAGAIN Operation in progress. Application should call
  stun_bind() again when there is data available on the socket.

## stun_discovery_get_address()

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_dns_lookup()

stun_dns_lookup_t * stun_dns_lookup | ( | stun_magic_t * | magic,
|  | su_root_t * | root,
|  | stun_dns_lookup_f | func,
|  | const char * | domain )

Performs a DNS-SRV check for STUN 'stun' (tcp) and 'stun' (udp) services for 'domain'.

The result will be delivered asynchronously in the 'func' callback. 'root' will be used as the event loop.

## stun_dns_lookup_stp_addr()

int stun_dns_lookup_stp_addr | ( | stun_dns_lookup_t * | self,
|  | const char ** | target,
|  | uint16_t * | port )

Fetches the results of a completed STUN DNS-SRV lookup for "_stun._udp" service (3489bis, "Short-Term Password").

Parameters

  self | context pointer
  target | location where to stored the 'target' SRV field for stun service
  port | location where to store port number

Returns
  0 on success, non-zero otherwise

## stun_dns_lookup_tcp_addr()

int stun_dns_lookup_tcp_addr | ( | stun_dns_lookup_t * | self,
|  | const char ** | target,
|  | uint16_t * | port )

Fetches the results of a completed STUN DNS-SRV lookup for "_stun._tcp" service (RFC3489).

Parameters

  self | context pointer
  target | location where to stored the 'target' SRV field for stun service
  port | location where to store port number

Returns
  0 on success, non-zero otherwise

## stun_dns_lookup_udp_addr()

int stun_dns_lookup_udp_addr | ( | stun_dns_lookup_t * | self,
|  | const char ** | target,
|  | uint16_t * | port )

Fetches the results of a completed STUN DNS-SRV lookup for "_stun._udp" service (RFC3489/3489bis).

Parameters

  self | context pointer
  target | location where to stored the 'target' SRV field for stun service
  port | location where to store port number

Returns
  0 on success, non-zero otherwise

## stun_handle_init()

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:

\n STUNTAG_DOMAIN() domain to use in DNS-SRV based STUN server

\n STUNTAG_SERVER() stun server hostname or dotted IPv4 address

\n STUNTAG_REQUIRE_INTEGRITY() true if msg integrity should be
  used enforced

## stun_is_requested()

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:

\n STUNTAG_DOMAIN() domain to use in DNS-SRV based STUN server

\n STUNTAG_SERVER() stun server hostname or dotted IPv4 address

Parameters

  tag,value,... | tag-value list

## stun_nattype()

stun_nattype_t stun_nattype | ( | stun_discovery_t * | sd | ) |

Returns the detected NAT type.

See also
  stun_nattype_str().
  stun_test_nattype().

## stun_nattype_str()

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().

## stun_obtain_shared_secret()

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_*).

## stun_root()

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.

## stun_test_lifetime()

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:

\n STUNTAG_SOCKET Bind socket for STUN

\n STUNTAG_REGISTER_EVENTS Register socket for eventloop owned by STUN

\n STUNTAG_SERVER() stun server hostname or dotted IPv4 address

Returns
  0 on success, non-zero on error

## stun_test_nattype()

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:

\n STUNTAG_SOCKET Bind socket for STUN

\n STUNTAG_REGISTER_SOCKET Register socket for eventloop owned by STUN

\n STUNTAG_SERVER() stun server hostname or dotted IPv4 address

Returns
  0 on success, non-zero on error

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