Alexandre Lision | 8af73cb | 2013-12-10 14:11:20 -0500 | [diff] [blame] | 1 | /* $Id$ */ |
| 2 | /* |
| 3 | * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com) |
| 4 | * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org> |
| 5 | * |
| 6 | * This program is free software; you can redistribute it and/or modify |
| 7 | * it under the terms of the GNU General Public License as published by |
| 8 | * the Free Software Foundation; either version 2 of the License, or |
| 9 | * (at your option) any later version. |
| 10 | * |
| 11 | * This program is distributed in the hope that it will be useful, |
| 12 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 13 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 14 | * GNU General Public License for more details. |
| 15 | * |
| 16 | * You should have received a copy of the GNU General Public License |
| 17 | * along with this program; if not, write to the Free Software |
| 18 | * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA |
| 19 | */ |
| 20 | #ifndef __PJSTUN_H__ |
| 21 | #define __PJSTUN_H__ |
| 22 | |
| 23 | /** |
| 24 | * @file stun.h |
| 25 | * @brief STUN client. |
| 26 | */ |
| 27 | |
| 28 | #include <pjlib-util/types.h> |
| 29 | #include <pj/sock.h> |
| 30 | |
| 31 | |
| 32 | PJ_BEGIN_DECL |
| 33 | |
| 34 | /* |
| 35 | * This enumeration describes STUN message types. |
| 36 | */ |
| 37 | typedef enum pjstun_msg_type |
| 38 | { |
| 39 | PJSTUN_BINDING_REQUEST = 0x0001, |
| 40 | PJSTUN_BINDING_RESPONSE = 0x0101, |
| 41 | PJSTUN_BINDING_ERROR_RESPONSE = 0x0111, |
| 42 | PJSTUN_SHARED_SECRET_REQUEST = 0x0002, |
| 43 | PJSTUN_SHARED_SECRET_RESPONSE = 0x0102, |
| 44 | PJSTUN_SHARED_SECRET_ERROR_RESPONSE = 0x0112 |
| 45 | } pjstun_msg_type; |
| 46 | |
| 47 | |
| 48 | /* |
| 49 | * This enumeration describes STUN attribute types. |
| 50 | */ |
| 51 | typedef enum pjstun_attr_type |
| 52 | { |
| 53 | PJSTUN_ATTR_MAPPED_ADDR = 1, |
| 54 | PJSTUN_ATTR_RESPONSE_ADDR, |
| 55 | PJSTUN_ATTR_CHANGE_REQUEST, |
| 56 | PJSTUN_ATTR_SOURCE_ADDR, |
| 57 | PJSTUN_ATTR_CHANGED_ADDR, |
| 58 | PJSTUN_ATTR_USERNAME, |
| 59 | PJSTUN_ATTR_PASSWORD, |
| 60 | PJSTUN_ATTR_MESSAGE_INTEGRITY, |
| 61 | PJSTUN_ATTR_ERROR_CODE, |
| 62 | PJSTUN_ATTR_UNKNOWN_ATTRIBUTES, |
| 63 | PJSTUN_ATTR_REFLECTED_FROM, |
| 64 | PJSTUN_ATTR_XOR_MAPPED_ADDR = 0x0020 |
| 65 | } pjstun_attr_type; |
| 66 | |
| 67 | |
| 68 | /* |
| 69 | * This structre describes STUN message header. |
| 70 | */ |
| 71 | typedef struct pjstun_msg_hdr |
| 72 | { |
| 73 | pj_uint16_t type; |
| 74 | pj_uint16_t length; |
| 75 | pj_uint32_t tsx[4]; |
| 76 | } pjstun_msg_hdr; |
| 77 | |
| 78 | |
| 79 | /* |
| 80 | * This structre describes STUN attribute header. |
| 81 | */ |
| 82 | typedef struct pjstun_attr_hdr |
| 83 | { |
| 84 | pj_uint16_t type; |
| 85 | pj_uint16_t length; |
| 86 | } pjstun_attr_hdr; |
| 87 | |
| 88 | |
| 89 | /* |
| 90 | * This structre describes STUN MAPPED-ADDR attribute. |
| 91 | */ |
| 92 | typedef struct pjstun_mapped_addr_attr |
| 93 | { |
| 94 | pjstun_attr_hdr hdr; |
| 95 | pj_uint8_t ignored; |
| 96 | pj_uint8_t family; |
| 97 | pj_uint16_t port; |
| 98 | pj_uint32_t addr; |
| 99 | } pjstun_mapped_addr_attr; |
| 100 | |
| 101 | typedef pjstun_mapped_addr_attr pjstun_response_addr_attr; |
| 102 | typedef pjstun_mapped_addr_attr pjstun_changed_addr_attr; |
| 103 | typedef pjstun_mapped_addr_attr pjstun_src_addr_attr; |
| 104 | typedef pjstun_mapped_addr_attr pjstun_reflected_form_attr; |
| 105 | |
| 106 | typedef struct pjstun_change_request_attr |
| 107 | { |
| 108 | pjstun_attr_hdr hdr; |
| 109 | pj_uint32_t value; |
| 110 | } pjstun_change_request_attr; |
| 111 | |
| 112 | typedef struct pjstun_username_attr |
| 113 | { |
| 114 | pjstun_attr_hdr hdr; |
| 115 | pj_uint32_t value[1]; |
| 116 | } pjstun_username_attr; |
| 117 | |
| 118 | typedef pjstun_username_attr pjstun_password_attr; |
| 119 | |
| 120 | typedef struct pjstun_error_code_attr |
| 121 | { |
| 122 | pjstun_attr_hdr hdr; |
| 123 | pj_uint16_t ignored; |
| 124 | pj_uint8_t err_class; |
| 125 | pj_uint8_t number; |
| 126 | char reason[4]; |
| 127 | } pjstun_error_code_attr; |
| 128 | |
| 129 | typedef struct pjstun_msg |
| 130 | { |
| 131 | pjstun_msg_hdr *hdr; |
| 132 | int attr_count; |
| 133 | pjstun_attr_hdr *attr[PJSTUN_MAX_ATTR]; |
| 134 | } pjstun_msg; |
| 135 | |
| 136 | /* STUN message API (stun.c). */ |
| 137 | |
| 138 | PJ_DECL(pj_status_t) pjstun_create_bind_req( pj_pool_t *pool, |
| 139 | void **msg, pj_size_t *len, |
| 140 | pj_uint32_t id_hi, |
| 141 | pj_uint32_t id_lo); |
| 142 | PJ_DECL(pj_status_t) pjstun_parse_msg( void *buf, pj_size_t len, |
| 143 | pjstun_msg *msg); |
| 144 | PJ_DECL(void*) pjstun_msg_find_attr( pjstun_msg *msg, pjstun_attr_type t); |
| 145 | |
| 146 | |
| 147 | /** |
| 148 | * @defgroup PJLIB_UTIL_STUN_CLIENT Simple STUN Helper |
| 149 | * @ingroup PJ_PROTOCOLS |
| 150 | * @brief A simple and small footprint STUN resolution helper |
| 151 | * @{ |
| 152 | * |
| 153 | * This is the older implementation of STUN client, with only one function |
| 154 | * provided (pjstun_get_mapped_addr()) to retrieve the public IP address |
| 155 | * of multiple sockets. |
| 156 | */ |
| 157 | |
| 158 | /** |
| 159 | * This is the main function to request the mapped address of local sockets |
| 160 | * to multiple STUN servers. This function is able to find the mapped |
| 161 | * addresses of multiple sockets simultaneously, and for each socket, two |
| 162 | * requests will be sent to two different STUN servers to see if both servers |
| 163 | * get the same public address for the same socket. (Note that application can |
| 164 | * specify the same address for the two servers, but still two requests will |
| 165 | * be sent for each server). |
| 166 | * |
| 167 | * This function will perform necessary retransmissions of the requests if |
| 168 | * response is not received within a predetermined period. When all responses |
| 169 | * have been received, the function will compare the mapped addresses returned |
| 170 | * by the servers, and when both are equal, the address will be returned in |
| 171 | * \a mapped_addr argument. |
| 172 | * |
| 173 | * @param pf The pool factory where memory will be allocated from. |
| 174 | * @param sock_cnt Number of sockets in the socket array. |
| 175 | * @param sock Array of local UDP sockets which public addresses are |
| 176 | * to be queried from the STUN servers. |
| 177 | * @param srv1 Host name or IP address string of the first STUN |
| 178 | * server. |
| 179 | * @param port1 The port number of the first STUN server. |
| 180 | * @param srv2 Host name or IP address string of the second STUN |
| 181 | * server. |
| 182 | * @param port2 The port number of the second STUN server. |
| 183 | * @param mapped_addr Array to receive the mapped public address of the local |
| 184 | * UDP sockets, when the function returns PJ_SUCCESS. |
| 185 | * |
| 186 | * @return This functions returns PJ_SUCCESS if responses are |
| 187 | * received from all servers AND all servers returned the |
| 188 | * same mapped public address. Otherwise this function may |
| 189 | * return one of the following error codes: |
| 190 | * - PJLIB_UTIL_ESTUNNOTRESPOND: no respons from servers. |
| 191 | * - PJLIB_UTIL_ESTUNSYMMETRIC: different mapped addresses |
| 192 | * are returned by servers. |
| 193 | * - etc. |
| 194 | * |
| 195 | */ |
| 196 | PJ_DECL(pj_status_t) pjstun_get_mapped_addr( pj_pool_factory *pf, |
| 197 | int sock_cnt, pj_sock_t sock[], |
| 198 | const pj_str_t *srv1, int port1, |
| 199 | const pj_str_t *srv2, int port2, |
| 200 | pj_sockaddr_in mapped_addr[]); |
| 201 | |
| 202 | |
| 203 | /* |
| 204 | * This structre describes configurable setting for requesting mapped address. |
| 205 | */ |
| 206 | typedef struct pjstun_setting |
| 207 | { |
| 208 | /** |
| 209 | * Specifies whether STUN request generated by old STUN library should |
| 210 | * insert magic cookie (specified in RFC 5389) in the transaction ID. |
| 211 | */ |
| 212 | pj_bool_t use_stun2; |
| 213 | |
| 214 | /** |
| 215 | * Host name or IP address string of the first STUN server. |
| 216 | */ |
| 217 | pj_str_t srv1; |
| 218 | |
| 219 | /** |
| 220 | * The port number of the first STUN server. |
| 221 | */ |
| 222 | int port1; |
| 223 | |
| 224 | /** |
| 225 | * Host name or IP address string of the second STUN server. |
| 226 | */ |
| 227 | pj_str_t srv2; |
| 228 | |
| 229 | /** |
| 230 | * The port number of the second STUN server. |
| 231 | */ |
| 232 | int port2; |
| 233 | |
| 234 | } pjstun_setting; |
| 235 | |
| 236 | |
| 237 | /** |
| 238 | * Another version of mapped address resolution of local sockets to multiple |
| 239 | * STUN servers configured in #pjstun_setting. This function is able to find |
| 240 | * the mapped addresses of multiple sockets simultaneously, and for each |
| 241 | * socket, two requests will be sent to two different STUN servers to see if |
| 242 | * both servers get the same public address for the same socket. (Note that |
| 243 | * application can specify the same address for the two servers, but still |
| 244 | * two requests will be sent for each server). |
| 245 | * |
| 246 | * This function will perform necessary retransmissions of the requests if |
| 247 | * response is not received within a predetermined period. When all responses |
| 248 | * have been received, the function will compare the mapped addresses returned |
| 249 | * by the servers, and when both are equal, the address will be returned in |
| 250 | * \a mapped_addr argument. |
| 251 | * |
| 252 | * @param pf The pool factory where memory will be allocated from. |
| 253 | * @param opt The STUN settings. |
| 254 | * @param sock_cnt Number of sockets in the socket array. |
| 255 | * @param sock Array of local UDP sockets which public addresses are |
| 256 | * to be queried from the STUN servers. |
| 257 | * @param mapped_addr Array to receive the mapped public address of the local |
| 258 | * UDP sockets, when the function returns PJ_SUCCESS. |
| 259 | * |
| 260 | * @return This functions returns PJ_SUCCESS if responses are |
| 261 | * received from all servers AND all servers returned the |
| 262 | * same mapped public address. Otherwise this function may |
| 263 | * return one of the following error codes: |
| 264 | * - PJLIB_UTIL_ESTUNNOTRESPOND: no respons from servers. |
| 265 | * - PJLIB_UTIL_ESTUNSYMMETRIC: different mapped addresses |
| 266 | * are returned by servers. |
| 267 | * - etc. |
| 268 | * |
| 269 | */ |
| 270 | PJ_DECL(pj_status_t) pjstun_get_mapped_addr2( pj_pool_factory *pf, |
| 271 | const pjstun_setting *opt, |
| 272 | int sock_cnt, |
| 273 | pj_sock_t sock[], |
| 274 | pj_sockaddr_in mapped_addr[]); |
| 275 | |
| 276 | |
| 277 | PJ_END_DECL |
| 278 | |
| 279 | /** |
| 280 | * @} |
| 281 | */ |
| 282 | |
| 283 | #endif /* __PJSTUN_H__ */ |
| 284 | |