stun.h 9.07 KB
Newer Older
Pekka Pessi's avatar
Pekka Pessi committed
1 2 3
/*
 * This file is part of the Sofia-SIP package
 *
4
 * Copyright (C) 2005-2006 Nokia Corporation.
Pekka Pessi's avatar
Pekka Pessi committed
5 6 7
 *
 * Contact: Pekka Pessi <pekka.pessi@nokia.com>
 *
8
 * This library is free software; you can redistribute it and/or
Pekka Pessi's avatar
Pekka Pessi committed
9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
 * modify it under the terms of the GNU Lesser General Public License
 * as published by the Free Software Foundation; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA
 *
 */

#ifndef STUN_H /** Defined when stun.h has been included. */
Pekka Pessi's avatar
Pekka Pessi committed
26
#define STUN_H
27 28

/**@file stun.h STUN module public interface
Pekka Pessi's avatar
Pekka Pessi committed
29 30
 *
 * @author Tat Chan <Tat.Chan@nokia.com>
31
 * @author Martti Mela <Martti.Mela@nokia.com>
Pekka Pessi's avatar
Pekka Pessi committed
32
 * @author Pekka Pessi <Pekka.Pessi@nokia.com>
33
 * @author Kai Vehmanen <kai.vehmanen@nokia.com>
Pekka Pessi's avatar
Pekka Pessi committed
34 35
 */

36
#ifndef SU_WAIT_H
37
#include <sofia-sip/su_wait.h>
38 39
#endif
#ifndef SU_TAG_H
40
#include <sofia-sip/su_tag.h>
41
#endif
42
#include "sofia-sip/stun_common.h"
Pekka Pessi's avatar
Pekka Pessi committed
43

44
#include <sofia-sip/su_localinfo.h>
Martti Mela's avatar
Martti Mela committed
45

46 47
SOFIA_BEGIN_DECLS

48 49 50 51
typedef struct stun_handle_s     stun_handle_t;
typedef struct stun_request_s    stun_request_t;
typedef struct stun_discovery_s  stun_discovery_t;
typedef struct stun_dns_lookup_s stun_dns_lookup_t;
Pekka Pessi's avatar
Pekka Pessi committed
52

Pekka Pessi's avatar
Pekka Pessi committed
53 54
typedef struct stun_mini_s     stun_mini_t;

55 56 57 58 59 60
#ifndef STUN_MAGIC_T 
#define STUN_MAGIC_T            struct stun_magic_t
#endif
/** STUN server context */
typedef STUN_MAGIC_T stun_magic_t;

61 62 63 64 65 66
#ifndef STUN_DISCOVERY_MAGIC_T 
#define STUN_DISCOVERY_MAGIC_T            struct stun_discovery_magic_t
#endif
/** STUN discovery_ context */
typedef STUN_DISCOVERY_MAGIC_T stun_discovery_magic_t;

Pekka Pessi's avatar
Pekka Pessi committed
67 68
extern char const stun_version[]; /**< Name and version of STUN software */

69 70
/**
 * STUN Action types. These define the current discovery process.
71
 * Defined as a bitmap.
72 73
 */
typedef enum stun_action_s {
74 75 76 77
  stun_action_no_action = 1,
  stun_action_tls_query = 2,
  stun_action_binding_request = 4,
  stun_action_keepalive = 8,
78 79
  stun_action_test_nattype = 16,
  stun_action_test_lifetime = 32,
80 81
} stun_action_t;

82 83 84
/**
 * States of the STUN client->server query process.
 */ 
85
typedef enum stun_state_e {
86 87
  
  stun_no_assigned_event,
88
  stun_dispose_me,
89

90 91 92
  /* DNS-SRV lookups */
  stun_dns_lookup_pending,

Martti Mela's avatar
Martti Mela committed
93 94 95 96 97 98 99 100
  /* TLS events */
  stun_tls_connecting,
  stun_tls_ssl_connecting,
  stun_tls_writing,
  stun_tls_closing,
  stun_tls_reading,
  stun_tls_done,

101 102 103 104 105
  /* STUN discovery events */
  stun_discovery_init,
  stun_discovery_processing,
  stun_discovery_done,

Martti Mela's avatar
Martti Mela committed
106 107 108 109 110
  /* STUN bind events */
  stun_bind_init,             /**< Initial state */
  stun_bind_processing,       /**< Processing server reply */
  stun_bind_done,             /**< Initial state */

111 112
  stun_request_not_found,     /**< Response without matching request */

Martti Mela's avatar
Martti Mela committed
113
  /* STUN errors */
114
  /* Do not change the order! Errors need to be after stun_error */
Martti Mela's avatar
Martti Mela committed
115 116 117 118 119

  stun_error,
  stun_tls_connection_timeout,
  stun_tls_connection_failed,
  stun_tls_ssl_connect_failed,
120 121

  /* stun client errors */
Martti Mela's avatar
Martti Mela committed
122 123
  stun_bind_error,
  stun_bind_timeout,
124

125
  stun_request_timeout,
126 127 128
  stun_discovery_timeout,

} stun_state_t;
129

130 131 132
/* -------------------------------------------------------------------
 * Calback function prototypes (signals emitted by the stack) */

133 134 135 136 137 138 139 140
/* Per discovery */
typedef void (*stun_discovery_f)(stun_discovery_magic_t *magic,
				 stun_handle_t *sh,
				 stun_request_t *req,
				 stun_discovery_t *sd,
				 stun_action_t action,
				 stun_state_t event);

141 142
/** Callback invoked by stun handle when it has a message to send. */
typedef int (*stun_send_callback)(stun_magic_t *magic,
143
				  stun_handle_t *sh,
144 145 146 147 148
				  int socket,
				  void *data,
				  unsigned len,
				  int only_a_keepalive);

149 150 151 152
/** Callback for delivering DNS lookup results */
typedef void (*stun_dns_lookup_f)(stun_dns_lookup_t *self,
				  stun_magic_t *magic);

153 154
/* -------------------------------------------------------------------
 * Functions for managing STUN handles. */
Pekka Pessi's avatar
Pekka Pessi committed
155

156 157 158
stun_handle_t *stun_handle_init(su_root_t *root,
				tag_type_t tag, tag_value_t value, ...);

159
void stun_handle_destroy(stun_handle_t *sh);
160 161

su_root_t *stun_root(stun_handle_t *sh);
162
int stun_is_requested(tag_type_t tag, tag_value_t value, ...);
Kai Vehmanen's avatar
Kai Vehmanen committed
163
char const *stun_str_state(stun_state_t state);
164
su_addrinfo_t const *stun_server_address(stun_handle_t *sh);
Pekka Pessi's avatar
Pekka Pessi committed
165

166 167 168 169 170 171 172
int stun_process_message(stun_handle_t *sh, su_socket_t s,
			 su_sockaddr_t *sa, socklen_t salen,
			 void *data, int len);
int stun_process_request(su_socket_t s, stun_msg_t *req,
			 int sid, su_sockaddr_t *from_addr,
			 int from_len);

173
/* ------------------------------------------------------------------- 
174 175
 * Functions for 'Binding Discovery' usage (RFC3489/3489bis) */

176 177 178 179
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, ...);

180
int stun_bind(stun_handle_t *sh, 
181 182
	      stun_discovery_f, stun_discovery_magic_t *magic,
	      tag_type_t tag, tag_value_t value, ...);
Kai Vehmanen's avatar
Kai Vehmanen committed
183

Martti Mela's avatar
Martti Mela committed
184 185 186
int stun_discovery_get_address(stun_discovery_t *sd,
			       void *addr,
			       socklen_t *return_addrlen);
187
su_socket_t stun_discovery_get_socket(stun_discovery_t *sd);
188
int stun_discovery_release_socket(stun_discovery_t *sd);
189

190 191 192
int stun_test_nattype(stun_handle_t *sh,
		       stun_discovery_f, stun_discovery_magic_t *magic,
		       tag_type_t tag, tag_value_t value, ...);
193 194
char const *stun_nattype(stun_discovery_t *sd);

195 196 197
int stun_test_lifetime(stun_handle_t *sh,
			stun_discovery_f, stun_discovery_magic_t *magic,
			tag_type_t tag, tag_value_t value, ...);
Pekka Pessi's avatar
Pekka Pessi committed
198 199
int stun_lifetime(stun_discovery_t *sd);

200 201
/* ------------------------------------------------------------------- 
 * Functions for 'Connectivity Check' and 'NAT Keepalives' usages (RFC3489bis) */
202

203 204 205 206 207
int stun_set_uname_pwd(stun_handle_t *sh,
		       const char *uname,
		       int len_uname, 
		       const char *pwd,
		       int len_pwd);
Pekka Pessi's avatar
Pekka Pessi committed
208

Martti Mela's avatar
Martti Mela committed
209
int stun_msg_is_keepalive(uint16_t data);
210
int stun_message_length(void *data, int len, int end_of_message);
211 212 213

/* Create a keepalive dispatcher for bound SIP sockets */

214
int stun_keepalive(stun_handle_t *sh,
Martti Mela's avatar
Martti Mela committed
215
		   su_sockaddr_t *sa,
216 217 218 219
		   tag_type_t tag, tag_value_t value,
		   ...);
int stun_keepalive_destroy(stun_handle_t *sh, su_socket_t s);

220 221 222
/* -------------------------------------------------------------------
 * Functions for 'Short-Term password' usage (RFC3489bis) */

Kai Vehmanen's avatar
Kai Vehmanen committed
223
/* (not implemented, see stun_request_shared_secret()) */
224

225 226 227 228 229 230 231 232 233
/* -------------------------------------------------------------------
 * Functions for STUN server discovery using DNS (RFC3489/3489bis) */

stun_dns_lookup_t *stun_dns_lookup(stun_magic_t *magic, 
				   su_root_t *root,
				   stun_dns_lookup_f func, 
				   const char *domain);
void stun_dns_lookup_destroy(stun_dns_lookup_t *self);

234 235 236 237
int stun_dns_lookup_udp_addr(stun_dns_lookup_t *self, const char **target, uint16_t *port);
int stun_dns_lookup_tcp_addr(stun_dns_lookup_t *self, const char **target, uint16_t *port);
int stun_dns_lookup_stp_addr(stun_dns_lookup_t *self, const char **target, uint16_t *port);

Pekka Pessi's avatar
Pekka Pessi committed
238 239 240 241 242 243 244 245 246 247 248 249 250
/* -------------------------------------------------------------------
 * Functions for minimal STUN server */

stun_mini_t *stun_mini_create(void);
void stun_mini_destroy(stun_mini_t *);

int stun_mini_add_socket(stun_mini_t *server, int socket);
int stun_mini_remove_socket(stun_mini_t *server, int socket);

void stun_mini_request(stun_mini_t *server, int socket,
			 void *msg, ssize_t msglen,
			 void *addr, socklen_t addrlen);

251
/* --------------------------------------------------------------------
252
 * Deprecated functions and definitions. These are supported with limited
253
 * compatibility. */
254

255 256 257 258 259 260 261 262
/* Used if no stun_discovery_f specified for a discovery  */
typedef void (*stun_event_f)(stun_magic_t *magic,
			     stun_handle_t *sh,
			     stun_request_t *req,
			     stun_discovery_t *sd,
			     stun_action_t action,
			     stun_state_t event);

263 264 265 266 267
stun_handle_t *stun_handle_create(stun_magic_t *context,
				  su_root_t *root,
				  stun_event_f cb,
				  tag_type_t tag, tag_value_t value, ...);

268 269
int stun_handle_release(stun_handle_t *sh, su_socket_t s);

270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289
su_root_t *stun_handle_root(stun_handle_t *sh);
int stun_handle_request_shared_secret(stun_handle_t *sh);

/** Bind a socket using STUN.  */
int stun_handle_bind(stun_handle_t *sh, 
		     /* su_localinfo_t *my_addr, */
		     tag_type_t tag, tag_value_t value,
		     ...);
int stun_handle_set_uname_pwd(stun_handle_t *sh,
			      const char *uname,
			      int len_uname, 
			      const char *pwd,
			      int len_pwd);

int stun_handle_process_message(stun_handle_t *sh,
				su_socket_t s,
				su_sockaddr_t *sa,
				socklen_t salen,
				void *data,
				int len);
290 291 292 293 294 295
int stun_handle_request_shared_secret(stun_handle_t *sh);
int stun_handle_set_uname_pwd(stun_handle_t *sh,
			      const char *uname,
			      int len_uname, 
			      const char *pwd,
			      int len_pwd);
296

297 298
SOFIA_END_DECLS

Pekka Pessi's avatar
Pekka Pessi committed
299
#endif /* !defined(STUN_H) */