Add support for conncheck keepalives with retransmissions and timeout
[sipe-libnice.git] / stun / stunmessage.h
blobd768eb3738b78b7ebe984a3683b547d64f03520a
1 /*
2 * This file is part of the Nice GLib ICE library.
4 * (C) 2008 Collabora Ltd.
5 * (C) 2008 Nokia Corporation. All rights reserved.
6 * Contact: Youness Alaoui
8 * The contents of this file are subject to the Mozilla Public License Version
9 * 1.1 (the "License"); you may not use this file except in compliance with
10 * the License. You may obtain a copy of the License at
11 * http://www.mozilla.org/MPL/
13 * Software distributed under the License is distributed on an "AS IS" basis,
14 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
15 * for the specific language governing rights and limitations under the
16 * License.
18 * The Original Code is the Nice GLib ICE library.
20 * The Initial Developers of the Original Code are Collabora Ltd and Nokia
21 * Corporation. All Rights Reserved.
24 * Alternatively, the contents of this file may be used under the terms of the
25 * the GNU Lesser General Public License Version 2.1 (the "LGPL"), in which
26 * case the provisions of LGPL are applicable instead of those above. If you
27 * wish to allow use of your version of this file only under the terms of the
28 * LGPL and not to allow others to use your version of this file under the
29 * MPL, indicate your decision by deleting the provisions above and replace
30 * them with the notice and other provisions required by the LGPL. If you do
31 * not delete the provisions above, a recipient may use your version of this
32 * file under either the MPL or the LGPL.
35 #ifndef _STUN_MESSAGE_H
36 #define _STUN_MESSAGE_H
39 /**
40 * SECTION:stunmessage
41 * @short_description: STUN messages parsing and formatting functions
42 * @see_also: #StunAgent
43 * @stability: Stable
45 * The STUN Messages API allows you to create STUN messages easily as well as to
46 * parse existing messages.
51 #ifdef _WIN32
52 #include "win32_common.h"
53 #else
54 #include <stdint.h>
55 #include <stdbool.h>
56 #endif
58 #include <sys/types.h>
59 #include "constants.h"
61 #ifdef _WIN32
62 #include <winsock2.h>
63 #include <ws2tcpip.h>
64 #else
65 #include <sys/socket.h>
66 #include <arpa/inet.h>
67 #endif
69 typedef struct _StunMessage StunMessage;
71 /**
72 * StunClass:
73 * @STUN_REQUEST: A STUN Request message
74 * @STUN_INDICATION: A STUN indication message
75 * @STUN_RESPONSE: A STUN Response message
76 * @STUN_ERROR: A STUN Error message
78 * This enum is used to represent the class of
79 * a STUN message, as defined in RFC5389
82 /* Message classes */
83 typedef enum
85 STUN_REQUEST=0,
86 STUN_INDICATION=1,
87 STUN_RESPONSE=2,
88 STUN_ERROR=3
89 } StunClass;
92 /**
93 * StunMethod:
94 * @STUN_BINDING: The Binding method as defined by the RFC5389
95 * @STUN_SHARED_SECRET: The Shared-Secret method as defined by the RFC3489
96 * @STUN_ALLOCATE: The Allocate method as defined by the TURN draft 12
97 * @STUN_SET_ACTIVE_DST: The Set-Active-Destination method as defined by
98 * the TURN draft 4
99 * @STUN_REFRESH: The Refresh method as defined by the TURN draft 12
100 * @STUN_SEND: The Send method as defined by the TURN draft 00
101 * @STUN_CONNECT: The Connect method as defined by the TURN draft 4
102 * @STUN_OLD_SET_ACTIVE_DST: The older Set-Active-Destination method as
103 * defined by the TURN draft 0
104 * @STUN_IND_SEND: The Send method used in indication messages as defined
105 * by the TURN draft 12
106 * @STUN_IND_DATA: The Data method used in indication messages as defined
107 * by the TURN draft 12
108 * @STUN_IND_CONNECT_STATUS: The Connect-Status method used in indication
109 * messages as defined by the TURN draft 4
110 * @STUN_CREATEPERMISSION: The CreatePermission method as defined by
111 * the TURN draft 12
112 * @STUN_CHANNELBIND: The ChannelBind method as defined by the TURN draft 12
114 * This enum is used to represent the method of
115 * a STUN message, as defined by various RFCs
117 /* Message methods */
118 typedef enum
120 STUN_BINDING=0x001, /* RFC5389 */
121 STUN_SHARED_SECRET=0x002, /* old RFC3489 */
122 STUN_ALLOCATE=0x003, /* TURN-12 */
123 STUN_SET_ACTIVE_DST=0x004, /* TURN-04 */
124 STUN_REFRESH=0x004, /* TURN-12 */
125 STUN_SEND=0x004, /* TURN-00 */
126 STUN_CONNECT=0x005, /* TURN-04 */
127 STUN_OLD_SET_ACTIVE_DST=0x006, /* TURN-00 */
128 STUN_IND_SEND=0x006, /* TURN-12 */
129 STUN_IND_DATA=0x007, /* TURN-12 */
130 STUN_IND_CONNECT_STATUS=0x008, /* TURN-04 */
131 STUN_CREATEPERMISSION= 0x008, /* TURN-12 */
132 STUN_CHANNELBIND= 0x009 /* TURN-12 */
133 } StunMethod;
136 * StunAttribute:
137 * @STUN_ATTRIBUTE_MAPPED_ADDRESS: The MAPPED-ADDRESS attribute as defined
138 * by RFC5389
139 * @STUN_ATTRIBUTE_RESPONSE_ADDRESS: The RESPONSE-ADDRESS attribute as defined
140 * by RFC3489
141 * @STUN_ATTRIBUTE_CHANGE_REQUEST: The CHANGE-REQUEST attribute as defined by
142 * RFC3489
143 * @STUN_ATTRIBUTE_SOURCE_ADDRESS: The SOURCE-ADDRESS attribute as defined by
144 * RFC3489
145 * @STUN_ATTRIBUTE_CHANGED_ADDRESS: The CHANGED-ADDRESS attribute as defined
146 * by RFC3489
147 * @STUN_ATTRIBUTE_USERNAME: The USERNAME attribute as defined by RFC5389
148 * @STUN_ATTRIBUTE_PASSWORD: The PASSWORD attribute as defined by RFC3489
149 * @STUN_ATTRIBUTE_MESSAGE_INTEGRITY: The MESSAGE-INTEGRITY attribute as defined
150 * by RFC5389
151 * @STUN_ATTRIBUTE_ERROR_CODE: The ERROR-CODE attribute as defined by RFC5389
152 * @STUN_ATTRIBUTE_UNKNOWN_ATTRIBUTES: The UNKNOWN-ATTRIBUTES attribute as
153 * defined by RFC5389
154 * @STUN_ATTRIBUTE_REFLECTED_FROM: The REFLECTED-FROM attribute as defined
155 * by RFC3489
156 * @STUN_ATTRIBUTE_CHANNEL_NUMBER: The CHANNEL-NUMBER attribute as defined by
157 * TURN draft 09 and 12
158 * @STUN_ATTRIBUTE_LIFETIME: The LIFETIME attribute as defined by TURN
159 * draft 04, 09 and 12
160 * @STUN_ATTRIBUTE_MAGIC_COOKIE: The MAGIC-COOKIE attribute as defined by
161 * the rosenberg-midcom TURN draft 08
162 * @STUN_ATTRIBUTE_BANDWIDTH: The BANDWIDTH attribute as defined by TURN draft 04
163 * @STUN_ATTRIBUTE_DESTINATION_ADDRESS: The DESTINATION-ADDRESS attribute as
164 * defined by the rosenberg-midcom TURN draft 08
165 * @STUN_ATTRIBUTE_REMOTE_ADDRESS: The REMOTE-ADDRESS attribute as defined by
166 * TURN draft 04
167 * @STUN_ATTRIBUTE_PEER_ADDRESS: The PEER-ADDRESS attribute as defined by
168 * TURN draft 09
169 * @STUN_ATTRIBUTE_XOR_PEER_ADDRESS: The XOR-PEER-ADDRESS attribute as defined
170 * by TURN draft 12
171 * @STUN_ATTRIBUTE_DATA: The DATA attribute as defined by TURN draft 04,
172 * 09 and 12
173 * @STUN_ATTRIBUTE_REALM: The REALM attribute as defined by RFC5389
174 * @STUN_ATTRIBUTE_NONCE: The NONCE attribute as defined by RFC5389
175 * @STUN_ATTRIBUTE_RELAY_ADDRESS: The RELAY-ADDRESS attribute as defined by
176 * TURN draft 04
177 * @STUN_ATTRIBUTE_RELAYED_ADDRESS: The RELAYED-ADDRESS attribute as defined by
178 * TURN draft 09
179 * @STUN_ATTRIBUTE_XOR_RELAYED_ADDRESS: The XOR-RELAYED-ADDRESS attribute as
180 * defined by TURN draft 12
181 * @STUN_ATTRIBUTE_REQUESTED_ADDRESS_TYPE: The REQUESTED-ADDRESS-TYPE attribute
182 * as defined by TURN-IPV6 draft 05
183 * @STUN_ATTRIBUTE_REQUESTED_PORT_PROPS: The REQUESTED-PORT-PROPS attribute
184 * as defined by TURN draft 04
185 * @STUN_ATTRIBUTE_REQUESTED_PROPS: The REQUESTED-PROPS attribute as defined
186 * by TURN draft 09
187 * @STUN_ATTRIBUTE_EVEN_PORT: The EVEN-PORT attribute as defined by TURN draft 12
188 * @STUN_ATTRIBUTE_REQUESTED_TRANSPORT: The REQUESTED-TRANSPORT attribute as
189 * defined by TURN draft 12
190 * @STUN_ATTRIBUTE_DONT_FRAGMENT: The DONT-FRAGMENT attribute as defined
191 * by TURN draft 12
192 * @STUN_ATTRIBUTE_XOR_MAPPED_ADDRESS: The XOR-MAPPED-ADDRESS attribute as
193 * defined by RFC5389
194 * @STUN_ATTRIBUTE_TIMER_VAL: The TIMER-VAL attribute as defined by TURN draft 04
195 * @STUN_ATTRIBUTE_REQUESTED_IP: The REQUESTED-IP attribute as defined by
196 * TURN draft 04
197 * @STUN_ATTRIBUTE_RESERVATION_TOKEN: The RESERVATION-TOKEN attribute as defined
198 * by TURN draft 09 and 12
199 * @STUN_ATTRIBUTE_CONNECT_STAT: The CONNECT-STAT attribute as defined by TURN
200 * draft 04
201 * @STUN_ATTRIBUTE_PRIORITY: The PRIORITY attribute as defined by ICE draft 19
202 * @STUN_ATTRIBUTE_USE_CANDIDATE: The USE-CANDIDATE attribute as defined by
203 * ICE draft 19
204 * @STUN_ATTRIBUTE_OPTIONS: The OPTIONS optional attribute as defined by
205 * libjingle
206 * @STUN_ATTRIBUTE_SOFTWARE: The SOFTWARE optional attribute as defined by RFC5389
207 * @STUN_ATTRIBUTE_ALTERNATE_SERVER: The ALTERNATE-SERVER optional attribute as
208 * defined by RFC5389
209 * @STUN_ATTRIBUTE_FINGERPRINT: The FINGERPRINT optional attribute as defined
210 * by RFC5389
211 * @STUN_ATTRIBUTE_ICE_CONTROLLED: The ICE-CONTROLLED optional attribute as
212 * defined by ICE draft 19
213 * @STUN_ATTRIBUTE_ICE_CONTROLLING: The ICE-CONTROLLING optional attribute as
214 * defined by ICE draft 19
216 * Known STUN attribute types as defined by various RFCs and drafts
218 /* Should be in sync with stun_is_unknown() */
219 typedef enum
221 /* Mandatory attributes */
222 /* 0x0000 */ /* reserved */
223 STUN_ATTRIBUTE_MAPPED_ADDRESS=0x0001, /* RFC5389 */
224 STUN_ATTRIBUTE_RESPONSE_ADDRESS=0x0002, /* old RFC3489 */
225 STUN_ATTRIBUTE_CHANGE_REQUEST=0x0003, /* old RFC3489 */
226 STUN_ATTRIBUTE_SOURCE_ADDRESS=0x0004, /* old RFC3489 */
227 STUN_ATTRIBUTE_CHANGED_ADDRESS=0x0005, /* old RFC3489 */
228 STUN_ATTRIBUTE_USERNAME=0x0006, /* RFC5389 */
229 STUN_ATTRIBUTE_PASSWORD=0x0007, /* old RFC3489 */
230 STUN_ATTRIBUTE_MESSAGE_INTEGRITY=0x0008, /* RFC5389 */
231 STUN_ATTRIBUTE_ERROR_CODE=0x0009, /* RFC5389 */
232 STUN_ATTRIBUTE_UNKNOWN_ATTRIBUTES=0x000A, /* RFC5389 */
233 STUN_ATTRIBUTE_REFLECTED_FROM=0x000B, /* old RFC3489 */
234 STUN_ATTRIBUTE_CHANNEL_NUMBER=0x000C, /* TURN-12 */
235 STUN_ATTRIBUTE_LIFETIME=0x000D, /* TURN-12 */
236 /* 0x000E */ /* reserved (was ALTERNATE-SERVER from midcom-TURN 08 */
237 STUN_ATTRIBUTE_MAGIC_COOKIE=0x000F, /* midcom-TURN 08 */
238 STUN_ATTRIBUTE_BANDWIDTH=0x0010, /* TURN-04 */
239 STUN_ATTRIBUTE_DESTINATION_ADDRESS=0x0011, /* midcom-TURN 08 */
240 STUN_ATTRIBUTE_REMOTE_ADDRESS=0x0012, /* TURN-04 */
241 STUN_ATTRIBUTE_PEER_ADDRESS=0x0012, /* TURN-09 */
242 STUN_ATTRIBUTE_XOR_PEER_ADDRESS=0x0012, /* TURN-12 */
243 STUN_ATTRIBUTE_DATA=0x0013, /* TURN-12 */
244 STUN_ATTRIBUTE_REALM=0x0014, /* RFC5389 */
245 STUN_ATTRIBUTE_NONCE=0x0015, /* RFC5389 */
246 STUN_ATTRIBUTE_RELAY_ADDRESS=0x0016, /* TURN-04 */
247 STUN_ATTRIBUTE_RELAYED_ADDRESS=0x0016, /* TURN-09 */
248 STUN_ATTRIBUTE_XOR_RELAYED_ADDRESS=0x0016, /* TURN-12 */
249 STUN_ATTRIBUTE_REQUESTED_ADDRESS_TYPE=0x0017, /* TURN-IPv6-05 */
250 STUN_ATTRIBUTE_REQUESTED_PORT_PROPS=0x0018, /* TURN-04 */
251 STUN_ATTRIBUTE_REQUESTED_PROPS=0x0018, /* TURN-09 */
252 STUN_ATTRIBUTE_EVEN_PORT=0x0018, /* TURN-12 */
253 STUN_ATTRIBUTE_REQUESTED_TRANSPORT=0x0019, /* TURN-12 */
254 STUN_ATTRIBUTE_DONT_FRAGMENT=0x001A, /* TURN-12 */
255 /* 0x001B */ /* reserved */
256 /* 0x001C */ /* reserved */
257 /* 0x001D */ /* reserved */
258 /* 0x001E */ /* reserved */
259 /* 0x001F */ /* reserved */
260 STUN_ATTRIBUTE_XOR_MAPPED_ADDRESS=0x0020, /* RFC5389 */
261 STUN_ATTRIBUTE_TIMER_VAL=0x0021, /* TURN-04 */
262 STUN_ATTRIBUTE_REQUESTED_IP=0x0022, /* TURN-04 */
263 STUN_ATTRIBUTE_RESERVATION_TOKEN=0x0022, /* TURN-09 */
264 STUN_ATTRIBUTE_CONNECT_STAT=0x0023, /* TURN-04 */
265 STUN_ATTRIBUTE_PRIORITY=0x0024, /* ICE-19 */
266 STUN_ATTRIBUTE_USE_CANDIDATE=0x0025, /* ICE-19 */
267 /* 0x0026 */ /* reserved */
268 /* 0x0027 */ /* reserved */
269 /* 0x0028 */ /* reserved */
270 /* 0x0029 */ /* reserved */
271 /* 0x002A-0x7fff */ /* reserved */
273 /* Optional attributes */
274 /* 0x8000-0x8021 */ /* reserved */
275 STUN_ATTRIBUTE_OPTIONS=0x8001, /* libjingle */
276 STUN_ATTRIBUTE_SOFTWARE=0x8022, /* RFC5389 */
277 STUN_ATTRIBUTE_ALTERNATE_SERVER=0x8023, /* RFC5389 */
278 /* 0x8024 */ /* reserved */
279 /* 0x8025 */ /* reserved */
280 /* 0x8026 */ /* reserved */
281 /* 0x8027 */ /* reserved */
282 STUN_ATTRIBUTE_FINGERPRINT=0x8028, /* RFC5389 */
283 STUN_ATTRIBUTE_ICE_CONTROLLED=0x8029, /* ICE-19 */
284 STUN_ATTRIBUTE_ICE_CONTROLLING=0x802A, /* ICE-19 */
285 /* 0x802B-0xFFFF */ /* reserved */
286 } StunAttribute;
290 * STUN_ALL_KNOWN_ATTRIBUTES:
292 * An array containing all the currently known and defined mandatory attributes
293 * from StunAttribute
295 /* Should be in sync with StunAttribute */
296 static const uint16_t STUN_ALL_KNOWN_ATTRIBUTES[] =
298 STUN_ATTRIBUTE_MAPPED_ADDRESS,
299 STUN_ATTRIBUTE_RESPONSE_ADDRESS,
300 STUN_ATTRIBUTE_CHANGE_REQUEST,
301 STUN_ATTRIBUTE_SOURCE_ADDRESS,
302 STUN_ATTRIBUTE_CHANGED_ADDRESS,
303 STUN_ATTRIBUTE_USERNAME,
304 STUN_ATTRIBUTE_PASSWORD,
305 STUN_ATTRIBUTE_MESSAGE_INTEGRITY,
306 STUN_ATTRIBUTE_ERROR_CODE,
307 STUN_ATTRIBUTE_UNKNOWN_ATTRIBUTES,
308 STUN_ATTRIBUTE_REFLECTED_FROM,
309 STUN_ATTRIBUTE_CHANNEL_NUMBER,
310 STUN_ATTRIBUTE_LIFETIME,
311 STUN_ATTRIBUTE_MAGIC_COOKIE,
312 STUN_ATTRIBUTE_BANDWIDTH,
313 STUN_ATTRIBUTE_DESTINATION_ADDRESS,
314 STUN_ATTRIBUTE_REMOTE_ADDRESS,
315 STUN_ATTRIBUTE_PEER_ADDRESS,
316 STUN_ATTRIBUTE_XOR_PEER_ADDRESS,
317 STUN_ATTRIBUTE_DATA,
318 STUN_ATTRIBUTE_REALM,
319 STUN_ATTRIBUTE_NONCE,
320 STUN_ATTRIBUTE_RELAY_ADDRESS,
321 STUN_ATTRIBUTE_RELAYED_ADDRESS,
322 STUN_ATTRIBUTE_XOR_RELAYED_ADDRESS,
323 STUN_ATTRIBUTE_REQUESTED_ADDRESS_TYPE,
324 STUN_ATTRIBUTE_REQUESTED_PORT_PROPS,
325 STUN_ATTRIBUTE_REQUESTED_PROPS,
326 STUN_ATTRIBUTE_EVEN_PORT,
327 STUN_ATTRIBUTE_REQUESTED_TRANSPORT,
328 STUN_ATTRIBUTE_DONT_FRAGMENT,
329 STUN_ATTRIBUTE_XOR_MAPPED_ADDRESS,
330 STUN_ATTRIBUTE_TIMER_VAL,
331 STUN_ATTRIBUTE_REQUESTED_IP,
332 STUN_ATTRIBUTE_RESERVATION_TOKEN,
333 STUN_ATTRIBUTE_CONNECT_STAT,
334 STUN_ATTRIBUTE_PRIORITY,
335 STUN_ATTRIBUTE_USE_CANDIDATE,
340 * StunTransactionId:
342 * A type that holds a STUN transaction id.
344 typedef uint8_t StunTransactionId[STUN_MESSAGE_TRANS_ID_LEN];
348 * StunError:
349 * @STUN_ERROR_TRY_ALTERNATE: The ERROR-CODE value for the
350 * "Try Alternate" error as defined in RFC5389
351 * @STUN_ERROR_BAD_REQUEST: The ERROR-CODE value for the
352 * "Bad Request" error as defined in RFC5389
353 * @STUN_ERROR_UNAUTHORIZED: The ERROR-CODE value for the
354 * "Unauthorized" error as defined in RFC5389
355 * @STUN_ERROR_UNKNOWN_ATTRIBUTE: The ERROR-CODE value for the
356 * "Unknown Attribute" error as defined in RFC5389
357 * @STUN_ERROR_ALLOCATION_MISMATCH:The ERROR-CODE value for the
358 * "Allocation Mismatch" error as defined in TURN draft 12.
359 * Equivalent to the "No Binding" error defined in TURN draft 04.
360 * @STUN_ERROR_STALE_NONCE: The ERROR-CODE value for the
361 * "Stale Nonce" error as defined in RFC5389
362 * @STUN_ERROR_ACT_DST_ALREADY: The ERROR-CODE value for the
363 * "Active Destination Already Set" error as defined in TURN draft 04.
364 * @STUN_ERROR_UNSUPPORTED_FAMILY: The ERROR-CODE value for the
365 * "Address Family not Supported" error as defined in TURN IPV6 Draft 05.
366 * @STUN_ERROR_WRONG_CREDENTIALS: The ERROR-CODE value for the
367 * "Wrong Credentials" error as defined in TURN Draft 12.
368 * @STUN_ERROR_UNSUPPORTED_TRANSPORT:he ERROR-CODE value for the
369 * "Unsupported Transport Protocol" error as defined in TURN Draft 12.
370 * @STUN_ERROR_INVALID_IP: The ERROR-CODE value for the
371 * "Invalid IP Address" error as defined in TURN draft 04.
372 * @STUN_ERROR_INVALID_PORT: The ERROR-CODE value for the
373 * "Invalid Port" error as defined in TURN draft 04.
374 * @STUN_ERROR_OP_TCP_ONLY: The ERROR-CODE value for the
375 * "Operation for TCP Only" error as defined in TURN draft 04.
376 * @STUN_ERROR_CONN_ALREADY: The ERROR-CODE value for the
377 * "Connection Already Exists" error as defined in TURN draft 04.
378 * @STUN_ERROR_ALLOCATION_QUOTA_REACHED: The ERROR-CODE value for the
379 * "Allocation Quota Reached" error as defined in TURN draft 12.
380 * @STUN_ERROR_ROLE_CONFLICT:The ERROR-CODE value for the
381 * "Role Conflict" error as defined in ICE draft 19.
382 * @STUN_ERROR_SERVER_ERROR: The ERROR-CODE value for the
383 * "Server Error" error as defined in RFC5389
384 * @STUN_ERROR_SERVER_CAPACITY: The ERROR-CODE value for the
385 * "Insufficient Capacity" error as defined in TURN draft 04.
386 * @STUN_ERROR_INSUFFICIENT_CAPACITY: The ERROR-CODE value for the
387 * "Insufficient Capacity" error as defined in TURN draft 12.
388 * @STUN_ERROR_MAX: The maximum possible ERROR-CODE value as defined by RFC 5389.
390 * STUN error codes as defined by various RFCs and drafts
392 /* Should be in sync with stun_strerror() */
393 typedef enum
395 STUN_ERROR_TRY_ALTERNATE=300, /* RFC5389 */
396 STUN_ERROR_BAD_REQUEST=400, /* RFC5389 */
397 STUN_ERROR_UNAUTHORIZED=401, /* RFC5389 */
398 STUN_ERROR_UNKNOWN_ATTRIBUTE=420, /* RFC5389 */
399 STUN_ERROR_ALLOCATION_MISMATCH=437, /* TURN-12 */
400 STUN_ERROR_STALE_NONCE=438, /* RFC5389 */
401 STUN_ERROR_ACT_DST_ALREADY=439, /* TURN-04 */
402 STUN_ERROR_UNSUPPORTED_FAMILY=440, /* TURN-IPv6-05 */
403 STUN_ERROR_WRONG_CREDENTIALS=441, /* TURN-12 */
404 STUN_ERROR_UNSUPPORTED_TRANSPORT=442, /* TURN-12 */
405 STUN_ERROR_INVALID_IP=443, /* TURN-04 */
406 STUN_ERROR_INVALID_PORT=444, /* TURN-04 */
407 STUN_ERROR_OP_TCP_ONLY=445, /* TURN-04 */
408 STUN_ERROR_CONN_ALREADY=446, /* TURN-04 */
409 STUN_ERROR_ALLOCATION_QUOTA_REACHED=486, /* TURN-12 */
410 STUN_ERROR_ROLE_CONFLICT=487, /* ICE-19 */
411 STUN_ERROR_SERVER_ERROR=500, /* RFC5389 */
412 STUN_ERROR_SERVER_CAPACITY=507, /* TURN-04 */
413 STUN_ERROR_INSUFFICIENT_CAPACITY=508, /* TURN-12 */
414 STUN_ERROR_MAX=699
415 } StunError;
419 * StunMessageReturn:
420 * @STUN_MESSAGE_RETURN_SUCCESS: The operation was successful
421 * @STUN_MESSAGE_RETURN_NOT_FOUND: The attribute was not found
422 * @STUN_MESSAGE_RETURN_INVALID: The argument or data is invalid
423 * @STUN_MESSAGE_RETURN_NOT_ENOUGH_SPACE: There is not enough space in the
424 * message to append data to it, or not enough in an argument to fill it with
425 * the data requested.
426 * @STUN_MESSAGE_RETURN_UNSUPPORTED_ADDRESS: The address in the arguments or in
427 * the STUN message is not supported.
429 * The return value of most stun_message_* functions.
430 * This enum will report on whether an operation was successful or not
431 * and what error occured if any.
433 typedef enum
435 STUN_MESSAGE_RETURN_SUCCESS,
436 STUN_MESSAGE_RETURN_NOT_FOUND,
437 STUN_MESSAGE_RETURN_INVALID,
438 STUN_MESSAGE_RETURN_NOT_ENOUGH_SPACE,
439 STUN_MESSAGE_RETURN_UNSUPPORTED_ADDRESS
440 } StunMessageReturn;
442 #include "stunagent.h"
443 #include "stunhmac.h"
444 #include "stuncrc32.h"
445 #include "utils.h"
446 #include "stun5389.h"
449 * StunMessage:
450 * @agent: The agent that created or validated this message
451 * @buffer: The buffer containing the STUN message
452 * @buffer_len: The length of the buffer (not the size of the message)
453 * @key: The short term credentials key to use for authentication validation
454 * or that was used to finalize this message
455 * @key_len: The length of the associated key
456 * @long_term_key: The long term credential key to use for authentication
457 * validation or that was used to finalize this message
458 * @long_term_valid: Whether or not the #long_term_key variable contains valid
459 * data
461 * This structure represents a STUN message
463 struct _StunMessage {
464 StunAgent *agent;
465 uint8_t *buffer;
466 size_t buffer_len;
467 uint8_t *key;
468 size_t key_len;
469 uint8_t long_term_key[16];
470 bool long_term_valid;
474 * stun_message_init:
475 * @msg: The #StunMessage to initialize
476 * @c: STUN message class (host byte order)
477 * @m: STUN message method (host byte order)
478 * @id: 16-bytes transaction ID
480 * Initializes a STUN message buffer, with no attributes.
481 * Returns: %TRUE if the initialization was successful
483 bool stun_message_init (StunMessage *msg, StunClass c, StunMethod m,
484 const StunTransactionId id);
487 * stun_message_length:
488 * @msg: The #StunMessage
490 * Get the length of the message (including the header)
492 * Returns: The length of the message
494 uint16_t stun_message_length (const StunMessage *msg);
497 * stun_message_find:
498 * @msg: The #StunMessage
499 * @type: The #StunAttribute to find
500 * @palen: A pointer to store the length of the attribute
502 * Finds an attribute in a STUN message and fetches its content
504 * Returns: A pointer to the start of the attribute payload if found,
505 * otherwise NULL.
507 const void * stun_message_find (const StunMessage * msg, StunAttribute type,
508 uint16_t *palen);
512 * stun_message_find_flag:
513 * @msg: The #StunMessage
514 * @type: The #StunAttribute to find
516 * Looks for a flag attribute within a valid STUN message.
518 * Returns: A #StunMessageReturn value.
519 * %STUN_MESSAGE_RETURN_INVALID is returned if the attribute's size is not zero.
521 StunMessageReturn stun_message_find_flag (const StunMessage *msg,
522 StunAttribute type);
525 * stun_message_find32:
526 * @msg: The #StunMessage
527 * @type: The #StunAttribute to find
528 * @pval: A pointer where to store the value (host byte order)
530 * Extracts a 32-bits attribute from a STUN message.
532 * Returns: A #StunMessageReturn value.
533 * %STUN_MESSAGE_RETURN_INVALID is returned if the attribute's size is not
534 * 4 bytes.
536 StunMessageReturn stun_message_find32 (const StunMessage *msg,
537 StunAttribute type, uint32_t *pval);
540 * stun_message_find64:
541 * @msg: The #StunMessage
542 * @type: The #StunAttribute to find
543 * @pval: A pointer where to store the value (host byte order)
545 * Extracts a 64-bits attribute from a STUN message.
547 * Returns: A #StunMessageReturn value.
548 * %STUN_MESSAGE_RETURN_INVALID is returned if the attribute's size is not
549 * 8 bytes.
551 StunMessageReturn stun_message_find64 (const StunMessage *msg,
552 StunAttribute type, uint64_t *pval);
555 * stun_message_find_string:
556 * @msg: The #StunMessage
557 * @type: The #StunAttribute to find
558 * @buf: A pointer where to store the data
559 * @buflen: The length of the buffer
561 * Extracts an UTF-8 string from a valid STUN message.
563 * Returns: A #StunMessageReturn value.
564 * %STUN_MESSAGE_RETURN_INVALID is returned if the attribute is improperly
565 * encoded
566 * %STUN_MESSAGE_RETURN_NOT_ENOUGH_SPACE is return if the buffer size is too
567 * small to hold the string
569 <note>
570 <para>
571 The string will be NULL-terminated.
572 </para>
573 </note>
576 StunMessageReturn stun_message_find_string (const StunMessage *msg,
577 StunAttribute type, char *buf, size_t buflen);
580 * stun_message_find_addr:
581 * @msg: The #StunMessage
582 * @type: The #StunAttribute to find
583 * @addr: The #sockaddr to be filled
584 * @addrlen: The size of the @addr variable. Will be set to the size of the
585 * extracted socket address.
587 * Extracts a network address attribute from a STUN message.
589 * Returns: A #StunMessageReturn value.
590 * %STUN_MESSAGE_RETURN_INVALID is returned if the attribute payload size is
591 * wrong or if the @addrlen is too small
592 * %STUN_MESSAGE_RETURN_UNSUPPORTED_ADDRESSS if the address family is unknown.
594 StunMessageReturn stun_message_find_addr (const StunMessage *msg,
595 StunAttribute type, struct sockaddr *addr, socklen_t *addrlen);
598 * stun_message_find_xor_addr:
599 * @msg: The #StunMessage
600 * @type: The #StunAttribute to find
601 * @addr: The #sockaddr to be filled
602 * @addrlen: The size of the @addr variable. Will be set to the size of the
603 * extracted socket address.
605 * Extracts an obfuscated network address attribute from a STUN message.
607 * Returns: A #StunMessageReturn value.
608 * %STUN_MESSAGE_RETURN_INVALID is returned if the attribute payload size is
609 * wrong or if the @addrlen is too small
610 * %STUN_MESSAGE_RETURN_UNSUPPORTED_ADDRESSS if the address family is unknown.
612 StunMessageReturn stun_message_find_xor_addr (const StunMessage *msg,
613 StunAttribute type, struct sockaddr *addr, socklen_t *addrlen);
616 * stun_message_find_xor_addr_full:
617 * @msg: The #StunMessage
618 * @type: The #StunAttribute to find
619 * @addr: The #sockaddr to be filled
620 * @addrlen: The size of the @addr variable. Will be set to the size of the
621 * extracted socket address.
622 * @magic_cookie: The magic cookie to use to XOR the address.
624 * Extracts an obfuscated network address attribute from a STUN message.
626 * Returns: A #StunMessageReturn value.
627 * %STUN_MESSAGE_RETURN_INVALID is returned if the attribute payload size is
628 * wrong or if the @addrlen is too small
629 * %STUN_MESSAGE_RETURN_UNSUPPORTED_ADDRESSS if the address family is unknown.
631 StunMessageReturn stun_message_find_xor_addr_full (const StunMessage *msg,
632 StunAttribute type, struct sockaddr *addr,
633 socklen_t *addrlen, uint32_t magic_cookie);
637 * stun_message_find_error:
638 * @msg: The #StunMessage
639 * @code: A pointer where to store the value
641 * Extract the error response code from a STUN message
643 * Returns: A #StunMessageReturn value.
644 * %STUN_MESSAGE_RETURN_INVALID is returned if the value is invalid
646 StunMessageReturn stun_message_find_error (const StunMessage *msg, int *code);
650 * stun_message_append:
651 * @msg: The #StunMessage
652 * @type: The #StunAttribute to append
653 * @length: The length of the attribute
655 * Reserves room for appending an attribute to an unfinished STUN message.
657 * Returns: A pointer to an unitialized buffer of @length bytes to
658 * where the attribute payload must be written, or NULL if there is not
659 * enough room in the STUN message buffer.
661 void *stun_message_append (StunMessage *msg, StunAttribute type,
662 size_t length);
665 * stun_message_append_bytes:
666 * @msg: The #StunMessage
667 * @type: The #StunAttribute to append
668 * @data: The data to append
669 * @len: The length of the attribute
671 * Appends a binary value to a STUN message
673 * Returns: A #StunMessageReturn value.
675 StunMessageReturn stun_message_append_bytes (StunMessage *msg,
676 StunAttribute type, const void *data, size_t len);
679 * stun_message_append_flag:
680 * @msg: The #StunMessage
681 * @type: The #StunAttribute to append
683 * Appends an empty flag attribute to a STUN message
685 * Returns: A #StunMessageReturn value.
687 StunMessageReturn stun_message_append_flag (StunMessage *msg,
688 StunAttribute type);
691 * stun_message_append32:
692 * @msg: The #StunMessage
693 * @type: The #StunAttribute to append
694 * @value: The value to append (host byte order)
696 * Appends a 32-bits value attribute to a STUN message
698 * Returns: A #StunMessageReturn value.
700 StunMessageReturn stun_message_append32 (StunMessage *msg,
701 StunAttribute type, uint32_t value);
704 * stun_message_append64:
705 * @msg: The #StunMessage
706 * @type: The #StunAttribute to append
707 * @value: The value to append (host byte order)
709 * Appends a 64-bits value attribute to a STUN message
711 * Returns: A #StunMessageReturn value.
713 StunMessageReturn stun_message_append64 (StunMessage *msg,
714 StunAttribute type, uint64_t value);
717 * stun_message_append_string:
718 * @msg: The #StunMessage
719 * @type: The #StunAttribute to append
720 * @str: The string to append
722 * Adds an attribute from a NULL-terminated string to a STUN message
724 * Returns: A #StunMessageReturn value.
726 StunMessageReturn stun_message_append_string (StunMessage *msg,
727 StunAttribute type, const char *str);
730 * stun_message_append_addr:
731 * @msg: The #StunMessage
732 * @type: The #StunAttribute to append
733 * @addr: The #sockaddr to be append
734 * @addrlen: The size of the @addr variable.
736 * Append a network address attribute to a STUN message
738 * Returns: A #StunMessageReturn value.
739 * %STUN_MESSAGE_RETURN_INVALID is returned if the @addrlen is too small
740 * %STUN_MESSAGE_RETURN_UNSUPPORTED_ADDRESSS if the address family is unknown.
742 StunMessageReturn stun_message_append_addr (StunMessage * msg,
743 StunAttribute type, const struct sockaddr *addr, socklen_t addrlen);
746 * stun_message_append_xor_addr:
747 * @msg: The #StunMessage
748 * @type: The #StunAttribute to append
749 * @addr: The #sockaddr to be append
750 * @addrlen: The size of the @addr variable.
752 * Append an obfuscated network address attribute to a STUN message
754 * Returns: A #StunMessageReturn value.
755 * %STUN_MESSAGE_RETURN_INVALID is returned if the @addrlen is too small
756 * %STUN_MESSAGE_RETURN_UNSUPPORTED_ADDRESSS if the address family is unknown.
758 StunMessageReturn stun_message_append_xor_addr (StunMessage * msg,
759 StunAttribute type, const struct sockaddr *addr, socklen_t addrlen);
762 * stun_message_append_xor_addr_full:
763 * @msg: The #StunMessage
764 * @type: The #StunAttribute to append
765 * @addr: The #sockaddr to be append
766 * @addrlen: The size of the @addr variable.
767 * @magic_cookie: The magic cookie to use to XOR the address.
769 * Append an obfuscated network address attribute from a STUN message.
771 * Returns: A #StunMessageReturn value.
772 * %STUN_MESSAGE_RETURN_INVALID is returned if the @addrlen is too small
773 * %STUN_MESSAGE_RETURN_UNSUPPORTED_ADDRESSS if the address family is unknown.
775 StunMessageReturn stun_message_append_xor_addr_full (StunMessage * msg,
776 StunAttribute type, const struct sockaddr *addr, socklen_t addrlen,
777 uint32_t magic_cookie);
780 * stun_message_append_error:
781 * @msg: The #StunMessage
782 * @code: The error code value
784 * Appends the ERROR-CODE attribute to the STUN message and fills it according
785 * to #code
787 * Returns: A #StunMessageReturn value.
789 StunMessageReturn stun_message_append_error (StunMessage * msg,
790 StunError code);
793 * STUN_MESSAGE_BUFFER_INCOMPLETE:
795 * Convenience macro for stun_message_validate_buffer_length() meaning that the
796 * data to validate does not hold a complete STUN message
798 #define STUN_MESSAGE_BUFFER_INCOMPLETE 0
801 * STUN_MESSAGE_BUFFER_INVALID:
803 * Convenience macro for stun_message_validate_buffer_length() meaning that the
804 * data to validate is not a valid STUN message
806 #define STUN_MESSAGE_BUFFER_INVALID -1
810 * stun_message_validate_buffer_length:
811 * @msg: The buffer to validate
812 * @length: The length of the buffer
814 * This function will take a data buffer and will try to validate whether it is
815 * a STUN message or if it's not or if it's an incomplete STUN message and will
816 * provide us with the length of the STUN message.
818 * Returns: The length of the valid STUN message in the buffer.
819 * <para> See also: #STUN_MESSAGE_BUFFER_INCOMPLETE </para>
820 * <para> See also: #STUN_MESSAGE_BUFFER_INVALID </para>
822 int stun_message_validate_buffer_length (const uint8_t *msg, size_t length);
825 * stun_message_id:
826 * @msg: The #StunMessage
827 * @id: The #StunTransactionId to fill
829 * Retreive the STUN transaction id from a STUN message
831 void stun_message_id (const StunMessage *msg, StunTransactionId id);
834 * stun_message_get_class:
835 * @msg: The #StunMessage
837 * Retreive the STUN class from a STUN message
839 * Returns: The #StunClass
841 StunClass stun_message_get_class (const StunMessage *msg);
844 * stun_message_get_method:
845 * @msg: The #StunMessage
847 * Retreive the STUN method from a STUN message
849 * Returns: The #StunMethod
851 StunMethod stun_message_get_method (const StunMessage *msg);
854 * stun_message_has_attribute:
855 * @msg: The #StunMessage
856 * @type: The #StunAttribute to look for
858 * Checks if an attribute is present within a STUN message.
860 * Returns: %TRUE if the attribute is found, %FALSE otherwise
862 bool stun_message_has_attribute (const StunMessage *msg, StunAttribute type);
864 #endif /* _STUN_MESSAGE_H */