stun  1.12.11devel
stun.h
Go to the documentation of this file.
1 /*
2  * This file is part of the Sofia-SIP package
3  *
4  * Copyright (C) 2005-2006 Nokia Corporation.
5  *
6  * Contact: Pekka Pessi <pekka.pessi@nokia-email.address.hidden>
7  *
8  * This library is free software; you can redistribute it and/or
9  * modify it under the terms of the GNU Lesser General Public License
10  * as published by the Free Software Foundation; either version 2.1 of
11  * the License, or (at your option) any later version.
12  *
13  * This library is distributed in the hope that it will be useful, but
14  * WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16  * Lesser General Public License for more details.
17  *
18  * You should have received a copy of the GNU Lesser General Public
19  * License along with this library; if not, write to the Free Software
20  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
21  * 02110-1301 USA
22  *
23  */
24 
25 #ifndef STUN_H
26 
27 #define STUN_H
28 
37 #include <sofia-sip/stun_common.h>
38 
39 #ifndef SU_WAIT_H
40 #include <sofia-sip/su_wait.h>
41 #endif
42 
43 #ifndef SU_TAG_H
44 #include <sofia-sip/su_tag.h>
45 #endif
46 
47 #include <sofia-sip/su_localinfo.h>
48 
49 
50 SOFIA_BEGIN_DECLS
51 
52 typedef struct stun_handle_s stun_handle_t;
53 typedef struct stun_request_s stun_request_t;
54 typedef struct stun_discovery_s stun_discovery_t;
55 typedef struct stun_dns_lookup_s stun_dns_lookup_t;
56 
57 typedef struct stun_mini_s stun_mini_t;
58 
59 #ifndef STUN_MAGIC_T
60 #define STUN_MAGIC_T struct stun_magic_t
61 #endif
62 
63 typedef STUN_MAGIC_T stun_magic_t;
64 
65 #ifndef STUN_DISCOVERY_MAGIC_T
66 #define STUN_DISCOVERY_MAGIC_T struct stun_discovery_magic_t
67 #endif
68 
69 typedef STUN_DISCOVERY_MAGIC_T stun_discovery_magic_t;
70 
72 SOFIAPUBVAR char const stun_version[];
73 
78 typedef enum stun_action_s {
79  stun_action_no_action = 1,
80  stun_action_tls_query = 2,
81  stun_action_binding_request = 4,
82  stun_action_keepalive = 8,
83  stun_action_test_nattype = 16,
84  stun_action_test_lifetime = 32,
86 
97 typedef enum stun_nattype_e {
98  stun_nat_unknown = 0,
99 
100  /* no NAT between client and STUN server */
101  stun_open_internet,
102 
103  /* UDP communication blocked by FW */
104  stun_udp_blocked,
105 
106  /* No NAT, but a FW element is performing address and port
107  * restricted filtering. */
108  stun_sym_udp_fw,
109 
110  /* Endpoint independent filtering (endpoint independent mapping)
111  * RFC3489 full cone NAT. */
112  stun_nat_full_cone,
113 
114  /* Address restricted filtering (endpoint independent mapping),
115  * RFC3489 restricted cone NAT. */
116  stun_nat_res_cone,
117 
118  /* Address and port restricted filtering (endpoint
119  * independent mapping), RFC3489 port restricted cone */
120  stun_nat_port_res_cone,
121 
122  /* Endpoint independent filtering, endpoint dependent mapping. */
123  stun_nat_ei_filt_ad_map,
124 
125  /* Address dependent filtering, endpoint dependent mapping. */
126  stun_nat_ad_filt_ad_map,
127 
128  /* Address and port dependent filtering, endpoint dependent mapping
129  * RFC3489 symmetric NAT). */
130  stun_nat_adp_filt_ad_map,
131 
133 
142 typedef enum stun_state_e {
143 
144  stun_no_assigned_event,
145 
146  /* TLS events; see stun_obtain_shared_request() */
154  /* STUN discovery events */
157  /* STUN errors */
158  /* Do not change the order! Errors need to be after stun_error */
159 
169 
170 /* -------------------------------------------------------------------
171  * Calback function prototypes (signals emitted by the stack) */
172 
173 /* Per discovery */
174 typedef void (*stun_discovery_f)(stun_discovery_magic_t *magic,
175  stun_handle_t *sh,
176  stun_discovery_t *sd,
177  stun_action_t action,
178  stun_state_t event);
179 
181 typedef int (*stun_send_callback)(stun_magic_t *magic,
182  stun_handle_t *sh,
183  int socket,
184  void *data,
185  unsigned len,
186  int only_a_keepalive);
187 
189 typedef void (*stun_dns_lookup_f)(stun_dns_lookup_t *self,
190  stun_magic_t *magic);
191 
192 /* -------------------------------------------------------------------
193  * Functions for managing STUN handles. */
194 
195 SOFIAPUBFUN stun_handle_t *stun_handle_init(su_root_t *root,
196  tag_type_t, tag_value_t, ...);
197 
198 SOFIAPUBFUN void stun_handle_destroy(stun_handle_t *sh);
199 
200 SOFIAPUBFUN su_root_t *stun_root(stun_handle_t *sh);
202 SOFIAPUBFUN char const *stun_str_state(stun_state_t state);
203 SOFIAPUBFUN su_addrinfo_t const *stun_server_address(stun_handle_t *sh);
204 
206 int stun_process_message(stun_handle_t *sh, su_socket_t s,
207  su_sockaddr_t *sa, socklen_t salen,
208  void *data, isize_t len);
210 int stun_process_request(su_socket_t s, stun_msg_t *req,
211  int sid, su_sockaddr_t *from_addr,
212  socklen_t from_len);
213 
214 /* -------------------------------------------------------------------
215  * Functions for 'Binding Discovery' usage (RFC3489/3489bis) */
216 
218 int stun_obtain_shared_secret(stun_handle_t *sh, stun_discovery_f,
219  stun_discovery_magic_t *magic,
220  tag_type_t tag, tag_value_t value, ...);
221 
223 int stun_bind(stun_handle_t *sh,
224  stun_discovery_f, stun_discovery_magic_t *magic,
225  tag_type_t tag, tag_value_t value, ...);
226 
228 int stun_discovery_get_address(stun_discovery_t *sd,
229  void *addr,
230  socklen_t *return_addrlen);
232 SOFIAPUBFUN int stun_discovery_release_socket(stun_discovery_t *sd);
233 
235 int stun_test_nattype(stun_handle_t *sh,
236  stun_discovery_f, stun_discovery_magic_t *magic,
237  tag_type_t tag, tag_value_t value, ...);
238 SOFIAPUBFUN char const *stun_nattype_str(stun_discovery_t *sd);
239 SOFIAPUBFUN stun_nattype_t stun_nattype(stun_discovery_t *sd);
240 
242 int stun_test_lifetime(stun_handle_t *sh,
243  stun_discovery_f, stun_discovery_magic_t *magic,
244  tag_type_t tag, tag_value_t value, ...);
245 SOFIAPUBFUN int stun_lifetime(stun_discovery_t *sd);
246 
247 /* -------------------------------------------------------------------
248  * Functions for 'Connectivity Check' and 'NAT Keepalives' usages (RFC3489bis) */
249 
251 int stun_set_uname_pwd(stun_handle_t *sh,
252  const char *uname,
253  isize_t len_uname,
254  const char *pwd,
255  isize_t len_pwd);
256 
258 SOFIAPUBFUN int stun_message_length(void *data, isize_t len, int end_of_message);
259 
260 /* Create a keepalive dispatcher for bound SIP sockets */
261 
263 int stun_keepalive(stun_handle_t *sh,
264  su_sockaddr_t *sa,
265  tag_type_t tag, tag_value_t value,
266  ...);
267 SOFIAPUBFUN int stun_keepalive_destroy(stun_handle_t *sh, su_socket_t s);
268 
269 /* -------------------------------------------------------------------
270  * Functions for 'Short-Term password' usage (RFC3489bis) */
271 
272 /* (not implemented, see stun_request_shared_secret()) */
273 
274 /* -------------------------------------------------------------------
275  * Functions for STUN server discovery using DNS (RFC3489/3489bis) */
276 
278 stun_dns_lookup_t *stun_dns_lookup(stun_magic_t *magic,
279  su_root_t *root,
280  stun_dns_lookup_f func,
281  const char *domain);
282 SOFIAPUBFUN void stun_dns_lookup_destroy(stun_dns_lookup_t *self);
283 
284 SOFIAPUBFUN int stun_dns_lookup_udp_addr(stun_dns_lookup_t *,
285  const char **target, uint16_t *port);
286 SOFIAPUBFUN int stun_dns_lookup_tcp_addr(stun_dns_lookup_t *self,
287  const char **target, uint16_t *port);
288 SOFIAPUBFUN int stun_dns_lookup_stp_addr(stun_dns_lookup_t *self,
289  const char **target, uint16_t *port);
290 
291 /* -------------------------------------------------------------------
292  * Functions for minimal STUN server */
293 
294 SOFIAPUBFUN stun_mini_t *stun_mini_create(void);
295 SOFIAPUBFUN void stun_mini_destroy(stun_mini_t *);
296 
297 SOFIAPUBFUN int stun_mini_add_socket(stun_mini_t *server,
298  su_socket_t socket);
299 SOFIAPUBFUN int stun_mini_remove_socket(stun_mini_t *server,
300  su_socket_t socket);
301 
302 SOFIAPUBFUN void stun_mini_request(stun_mini_t *server, su_socket_t socket,
303  void *msg, ssize_t msglen,
304  void *addr, socklen_t addrlen);
305 
306 SOFIA_END_DECLS
307 
308 #endif /* !defined(STUN_H) */
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,...
Definition: stun_dns.c:242
stun_obtain_shared_secret
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.
Definition: stun.c:529
stun_tls_writing
@ stun_tls_writing
Next step: send request.
Definition: stun.h:149
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'.
Definition: stun_dns.c:133
stun_handle_init
stun_handle_t * stun_handle_init(su_root_t *root, tag_type_t, tag_value_t,...)
Creates a STUN handle.
Definition: stun.c:439
stun_tls_ssl_connect_failed
@ stun_tls_ssl_connect_failed
TLS/SSL handshake failed.
Definition: stun.h:163
stun_state_t
enum stun_state_e stun_state_t
States of the STUN client->server query process.
stun_send_callback
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.
Definition: stun.h:181
stun_discovery_magic_t
STUN_DISCOVERY_MAGIC_T stun_discovery_magic_t
STUN discovery_ context.
Definition: stun.h:69
stun_discovery_error
@ stun_discovery_error
Error in discovery process.
Definition: stun.h:165
su_addrinfo_t
struct addrinfo su_addrinfo_t
stun_nattype_t
enum stun_nattype_e stun_nattype_t
NAT types.
stun_tls_connection_timeout
@ stun_tls_connection_timeout
No response to connect attempt.
Definition: stun.h:161
stun_nattype_e
stun_nattype_e
NAT types.
Definition: stun.h:97
tag_type_t
struct tag_type_s const * tag_type_t
stun_action_t
enum stun_action_s stun_action_t
STUN Action types.
stun_keepalive
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.
Definition: stun.c:2910
stun_dns_lookup_udp_addr
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).
Definition: stun_dns.c:196
su_tag.h
stun_common.h
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).
Definition: stun_dns.c:219
stun_test_nattype
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.
Definition: stun.c:1183
su_socket_t
int su_socket_t
stun_mini_destroy
void stun_mini_destroy(stun_mini_t *)
Destroy a stun miniserver.
Definition: stun_mini.c:87
stun_tls_closing
@ stun_tls_closing
Closing TLS connection.
Definition: stun.h:150
stun_tls_connection_failed
@ stun_tls_connection_failed
No response from TLS/SSL server
Definition: stun.h:162
stun_message_length
int stun_message_length(void *data, isize_t len, int end_of_message)
Determines length of STUN message (0 (-1?) if not stun).
Definition: stun.c:2831
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.
Definition: stun.c:1089
stun_dns_lookup_f
void(* stun_dns_lookup_f)(stun_dns_lookup_t *self, stun_magic_t *magic)
Callback for delivering DNS lookup results.
Definition: stun.h:189
tag_value_t
intptr_t tag_value_t
stun_mini_remove_socket
int stun_mini_remove_socket(stun_mini_t *server, su_socket_t socket)
Remove socket from stun miniserver.
Definition: stun_mini.c:133
stun_msg_is_keepalive
int stun_msg_is_keepalive(uint16_t data)
Determines if the message is STUN message (-1 if not stun).
Definition: stun.c:2813
stun_nattype
stun_nattype_t stun_nattype(stun_discovery_t *sd)
Returns the detected NAT type.
Definition: stun.c:301
stun_tls_done
@ stun_tls_done
Shared-secret acquired.
Definition: stun.h:152
stun_set_uname_pwd
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.
Definition: stun.c:2560
stun_version
char const stun_version[]
Name and version of STUN software.
Definition: stun.c:324
stun_bind
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.
Definition: stun.c:1026
stun_dns_lookup_destroy
void stun_dns_lookup_destroy(stun_dns_lookup_t *self)
Destroys the 'self' object created by stun_dns_lookup_destroy().
Definition: stun_dns.c:177
stun_nattype_str
char const * stun_nattype_str(stun_discovery_t *sd)
Returns the NAT type attached to STUN discovery handle.
Definition: stun.c:274
stun_discovery_done
@ stun_discovery_done
Discovery process done.
Definition: stun.h:155
stun_tls_connecting
@ stun_tls_connecting
Connecting to TLS port.
Definition: stun.h:147
stun_handle_destroy
void stun_handle_destroy(stun_handle_t *sh)
Destroy a STUN client.
Definition: stun.c:710
stun_keepalive_destroy
int stun_keepalive_destroy(stun_handle_t *sh, su_socket_t s)
Destroys the keepalive dispatcher without touching the socket.
Definition: stun.c:3004
stun_test_lifetime
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.
Definition: stun.c:2672
stun_error
@ stun_error
Generic error in discovery process.
Definition: stun.h:160
su_root_t
struct su_root_t su_root_t
SOFIAPUBVAR
#define SOFIAPUBVAR
su_wait.h
stun_mini_create
stun_mini_t * stun_mini_create(void)
Create a stun miniserver.
Definition: stun_mini.c:81
stun_root
su_root_t * stun_root(stun_handle_t *sh)
Return su_root_t assigned to stun_handle_t.
Definition: stun.c:381
stun_action_s
stun_action_s
STUN Action types.
Definition: stun.h:78
SOFIAPUBFUN
#define SOFIAPUBFUN
su_localinfo.h
stun_tls_ssl_connecting
@ stun_tls_ssl_connecting
Started the TLS/SSL handshake.
Definition: stun.h:148
stun_tls_reading
@ stun_tls_reading
Request send, waiting for response.
Definition: stun.h:151
stun_discovery_get_socket
su_socket_t stun_discovery_get_socket(stun_discovery_t *sd)
Returns socket attached to the discovery object.
Definition: stun.c:3123
stun_discovery_timeout
@ stun_discovery_timeout
No response to discovery request.
Definition: stun.h:166
stun_state_e
stun_state_e
States of the STUN client->server query process.
Definition: stun.h:142
uint16_t
SU_U16_T uint16_t
stun_is_requested
int stun_is_requested(tag_type_t tag, tag_value_t value,...)
Check if a STUN handle should be created.
Definition: stun.c:400
stun_magic_t
STUN_MAGIC_T stun_magic_t
STUN server context.
Definition: stun.h:63
stun_mini_add_socket
int stun_mini_add_socket(stun_mini_t *server, su_socket_t socket)
Add a socket to stun miniserver.
Definition: stun_mini.c:101
stun_process_message
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.
Definition: stun.c:2854

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