2 * This file is part of the Nice GLib ICE library.
4 * (C) 2008-2009 Collabora Ltd.
5 * Contact: Youness Alaoui
6 * (C) 2008-2009 Nokia Corporation. All rights reserved.
7 * Contact: Rémi Denis-Courmont
9 * The contents of this file are subject to the Mozilla Public License Version
10 * 1.1 (the "License"); you may not use this file except in compliance with
11 * the License. You may obtain a copy of the License at
12 * http://www.mozilla.org/MPL/
14 * Software distributed under the License is distributed on an "AS IS" basis,
15 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
16 * for the specific language governing rights and limitations under the
19 * The Original Code is the Nice GLib ICE library.
21 * The Initial Developers of the Original Code are Collabora Ltd and Nokia
22 * Corporation. All Rights Reserved.
25 * Youness Alaoui, Collabora Ltd.
26 * Rémi Denis-Courmont, Nokia
28 * Alternatively, the contents of this file may be used under the terms of the
29 * the GNU Lesser General Public License Version 2.1 (the "LGPL"), in which
30 * case the provisions of LGPL are applicable instead of those above. If you
31 * wish to allow use of your version of this file only under the terms of the
32 * LGPL and not to allow others to use your version of this file under the
33 * MPL, indicate your decision by deleting the provisions above and replace
34 * them with the notice and other provisions required by the LGPL. If you do
35 * not delete the provisions above, a recipient may use your version of this
36 * file under either the MPL or the LGPL.
39 #ifndef _STUN_MESSAGE_H
40 #define _STUN_MESSAGE_H
45 * @short_description: STUN messages parsing and formatting functions
46 * @include: stun/stunmessage.h
47 * @see_also: #StunAgent
50 * The STUN Messages API allows you to create STUN messages easily as well as to
51 * parse existing messages.
57 #include "win32_common.h"
63 #include <sys/types.h>
69 #include <sys/socket.h>
70 #include <arpa/inet.h>
73 #include "constants.h"
75 typedef struct _StunMessage StunMessage;
79 * @STUN_REQUEST: A STUN Request message
80 * @STUN_INDICATION: A STUN indication message
81 * @STUN_RESPONSE: A STUN Response message
82 * @STUN_ERROR: A STUN Error message
84 * This enum is used to represent the class of
85 * a STUN message, as defined in RFC5389
100 * @STUN_BINDING: The Binding method as defined by the RFC5389
101 * @STUN_SHARED_SECRET: The Shared-Secret method as defined by the RFC3489
102 * @STUN_ALLOCATE: The Allocate method as defined by the TURN draft 12
103 * @STUN_SET_ACTIVE_DST: The Set-Active-Destination method as defined by
105 * @STUN_REFRESH: The Refresh method as defined by the TURN draft 12
106 * @STUN_SEND: The Send method as defined by the TURN draft 00
107 * @STUN_CONNECT: The Connect method as defined by the TURN draft 4
108 * @STUN_OLD_SET_ACTIVE_DST: The older Set-Active-Destination method as
109 * defined by the TURN draft 0
110 * @STUN_IND_SEND: The Send method used in indication messages as defined
111 * by the TURN draft 12
112 * @STUN_IND_DATA: The Data method used in indication messages as defined
113 * by the TURN draft 12
114 * @STUN_IND_CONNECT_STATUS: The Connect-Status method used in indication
115 * messages as defined by the TURN draft 4
116 * @STUN_CREATEPERMISSION: The CreatePermission method as defined by
118 * @STUN_CHANNELBIND: The ChannelBind method as defined by the TURN draft 12
120 * This enum is used to represent the method of
121 * a STUN message, as defined by various RFCs
123 /* Message methods */
126 STUN_BINDING=0x001, /* RFC5389 */
127 STUN_SHARED_SECRET=0x002, /* old RFC3489 */
128 STUN_ALLOCATE=0x003, /* TURN-12 */
129 STUN_SET_ACTIVE_DST=0x004, /* TURN-04 */
130 STUN_REFRESH=0x004, /* TURN-12 */
131 STUN_SEND=0x004, /* TURN-00 */
132 STUN_CONNECT=0x005, /* TURN-04 */
133 STUN_OLD_SET_ACTIVE_DST=0x006, /* TURN-00 */
134 STUN_IND_SEND=0x006, /* TURN-12 */
135 STUN_IND_DATA=0x007, /* TURN-12 */
136 STUN_IND_CONNECT_STATUS=0x008, /* TURN-04 */
137 STUN_CREATEPERMISSION= 0x008, /* TURN-12 */
138 STUN_CHANNELBIND= 0x009 /* TURN-12 */
143 * @STUN_ATTRIBUTE_MAPPED_ADDRESS: The MAPPED-ADDRESS attribute as defined
145 * @STUN_ATTRIBUTE_RESPONSE_ADDRESS: The RESPONSE-ADDRESS attribute as defined
147 * @STUN_ATTRIBUTE_CHANGE_REQUEST: The CHANGE-REQUEST attribute as defined by
149 * @STUN_ATTRIBUTE_SOURCE_ADDRESS: The SOURCE-ADDRESS attribute as defined by
151 * @STUN_ATTRIBUTE_CHANGED_ADDRESS: The CHANGED-ADDRESS attribute as defined
153 * @STUN_ATTRIBUTE_USERNAME: The USERNAME attribute as defined by RFC5389
154 * @STUN_ATTRIBUTE_PASSWORD: The PASSWORD attribute as defined by RFC3489
155 * @STUN_ATTRIBUTE_MESSAGE_INTEGRITY: The MESSAGE-INTEGRITY attribute as defined
157 * @STUN_ATTRIBUTE_ERROR_CODE: The ERROR-CODE attribute as defined by RFC5389
158 * @STUN_ATTRIBUTE_UNKNOWN_ATTRIBUTES: The UNKNOWN-ATTRIBUTES attribute as
160 * @STUN_ATTRIBUTE_REFLECTED_FROM: The REFLECTED-FROM attribute as defined
162 * @STUN_ATTRIBUTE_CHANNEL_NUMBER: The CHANNEL-NUMBER attribute as defined by
163 * TURN draft 09 and 12
164 * @STUN_ATTRIBUTE_LIFETIME: The LIFETIME attribute as defined by TURN
165 * draft 04, 09 and 12
166 * @STUN_ATTRIBUTE_MS_ALTERNATE_SERVER: The ALTERNATE-SERVER attribute as
167 * defined by [MS-TURN]
168 * @STUN_ATTRIBUTE_MAGIC_COOKIE: The MAGIC-COOKIE attribute as defined by
169 * the rosenberg-midcom TURN draft 08
170 * @STUN_ATTRIBUTE_BANDWIDTH: The BANDWIDTH attribute as defined by TURN draft 04
171 * @STUN_ATTRIBUTE_DESTINATION_ADDRESS: The DESTINATION-ADDRESS attribute as
172 * defined by the rosenberg-midcom TURN draft 08
173 * @STUN_ATTRIBUTE_REMOTE_ADDRESS: The REMOTE-ADDRESS attribute as defined by
175 * @STUN_ATTRIBUTE_PEER_ADDRESS: The PEER-ADDRESS attribute as defined by
177 * @STUN_ATTRIBUTE_XOR_PEER_ADDRESS: The XOR-PEER-ADDRESS attribute as defined
179 * @STUN_ATTRIBUTE_DATA: The DATA attribute as defined by TURN draft 04,
181 * @STUN_ATTRIBUTE_REALM: The REALM attribute as defined by RFC5389
182 * @STUN_ATTRIBUTE_NONCE: The NONCE attribute as defined by RFC5389
183 * @STUN_ATTRIBUTE_RELAY_ADDRESS: The RELAY-ADDRESS attribute as defined by
185 * @STUN_ATTRIBUTE_RELAYED_ADDRESS: The RELAYED-ADDRESS attribute as defined by
187 * @STUN_ATTRIBUTE_XOR_RELAYED_ADDRESS: The XOR-RELAYED-ADDRESS attribute as
188 * defined by TURN draft 12
189 * @STUN_ATTRIBUTE_REQUESTED_ADDRESS_TYPE: The REQUESTED-ADDRESS-TYPE attribute
190 * as defined by TURN-IPV6 draft 05
191 * @STUN_ATTRIBUTE_REQUESTED_PORT_PROPS: The REQUESTED-PORT-PROPS attribute
192 * as defined by TURN draft 04
193 * @STUN_ATTRIBUTE_REQUESTED_PROPS: The REQUESTED-PROPS attribute as defined
195 * @STUN_ATTRIBUTE_EVEN_PORT: The EVEN-PORT attribute as defined by TURN draft 12
196 * @STUN_ATTRIBUTE_REQUESTED_TRANSPORT: The REQUESTED-TRANSPORT attribute as
197 * defined by TURN draft 12
198 * @STUN_ATTRIBUTE_DONT_FRAGMENT: The DONT-FRAGMENT attribute as defined
200 * @STUN_ATTRIBUTE_XOR_MAPPED_ADDRESS: The XOR-MAPPED-ADDRESS attribute as
202 * @STUN_ATTRIBUTE_TIMER_VAL: The TIMER-VAL attribute as defined by TURN draft 04
203 * @STUN_ATTRIBUTE_REQUESTED_IP: The REQUESTED-IP attribute as defined by
205 * @STUN_ATTRIBUTE_RESERVATION_TOKEN: The RESERVATION-TOKEN attribute as defined
206 * by TURN draft 09 and 12
207 * @STUN_ATTRIBUTE_CONNECT_STAT: The CONNECT-STAT attribute as defined by TURN
209 * @STUN_ATTRIBUTE_PRIORITY: The PRIORITY attribute as defined by ICE draft 19
210 * @STUN_ATTRIBUTE_USE_CANDIDATE: The USE-CANDIDATE attribute as defined by
212 * @STUN_ATTRIBUTE_OPTIONS: The OPTIONS optional attribute as defined by
214 * @STUN_ATTRIBUTE_MS_VERSION: The MS-VERSION optional attribute as defined
216 * @STUN_ATTRIBUTE_MS_XOR_MAPPED_ADDRESS: The XOR-MAPPED-ADDRESS optional
217 * attribute as defined by [MS-TURN]
218 * @STUN_ATTRIBUTE_SOFTWARE: The SOFTWARE optional attribute as defined by RFC5389
219 * @STUN_ATTRIBUTE_ALTERNATE_SERVER: The ALTERNATE-SERVER optional attribute as
221 * @STUN_ATTRIBUTE_FINGERPRINT: The FINGERPRINT optional attribute as defined
223 * @STUN_ATTRIBUTE_ICE_CONTROLLED: The ICE-CONTROLLED optional attribute as
224 * defined by ICE draft 19
225 * @STUN_ATTRIBUTE_ICE_CONTROLLING: The ICE-CONTROLLING optional attribute as
226 * defined by ICE draft 19
227 * @STUN_ATTRIBUTE_MS_SEQUENCE_NUMBER: The MS-SEQUENCE NUMBER optional attribute
228 * as defined by [MS-TURN]
229 * @STUN_ATTRIBUTE_CANDIDATE_IDENTIFIER: The CANDIDATE-IDENTIFIER optional
230 * attribute as defined by [MS-ICE2]
231 * @STUN_ATTRIBUTE_MS_IMPLEMENTATION_VERSION: The IMPLEMENTATION-VERSION
232 * optional attribute as defined by [MS-ICE2]
233 * @STUN_ATTRIBUTE_NOMINATION: The NOMINATION attribute as defined by
234 * draft-thatcher-ice-renomination-00 and deployed in Google Chrome
236 * Known STUN attribute types as defined by various RFCs and drafts
238 /* Should be in sync with stun_is_unknown() */
241 /* Mandatory attributes */
242 /* 0x0000 */ /* reserved */
243 STUN_ATTRIBUTE_MAPPED_ADDRESS=0x0001, /* RFC5389 */
244 STUN_ATTRIBUTE_RESPONSE_ADDRESS=0x0002, /* old RFC3489 */
245 STUN_ATTRIBUTE_CHANGE_REQUEST=0x0003, /* old RFC3489 */
246 STUN_ATTRIBUTE_SOURCE_ADDRESS=0x0004, /* old RFC3489 */
247 STUN_ATTRIBUTE_CHANGED_ADDRESS=0x0005, /* old RFC3489 */
248 STUN_ATTRIBUTE_USERNAME=0x0006, /* RFC5389 */
249 STUN_ATTRIBUTE_PASSWORD=0x0007, /* old RFC3489 */
250 STUN_ATTRIBUTE_MESSAGE_INTEGRITY=0x0008, /* RFC5389 */
251 STUN_ATTRIBUTE_ERROR_CODE=0x0009, /* RFC5389 */
252 STUN_ATTRIBUTE_UNKNOWN_ATTRIBUTES=0x000A, /* RFC5389 */
253 STUN_ATTRIBUTE_REFLECTED_FROM=0x000B, /* old RFC3489 */
254 STUN_ATTRIBUTE_CHANNEL_NUMBER=0x000C, /* TURN-12 */
255 STUN_ATTRIBUTE_LIFETIME=0x000D, /* TURN-12 */
256 /* MS_ALTERNATE_SERVER is only used by Microsoft's dialect, probably should
257 * not to be placed in STUN_ALL_KNOWN_ATTRIBUTES */
258 STUN_ATTRIBUTE_MS_ALTERNATE_SERVER=0x000E, /* MS-TURN */
259 STUN_ATTRIBUTE_MAGIC_COOKIE=0x000F, /* midcom-TURN 08 */
260 STUN_ATTRIBUTE_BANDWIDTH=0x0010, /* TURN-04 */
261 STUN_ATTRIBUTE_DESTINATION_ADDRESS=0x0011, /* midcom-TURN 08 */
262 STUN_ATTRIBUTE_REMOTE_ADDRESS=0x0012, /* TURN-04 */
263 STUN_ATTRIBUTE_PEER_ADDRESS=0x0012, /* TURN-09 */
264 STUN_ATTRIBUTE_XOR_PEER_ADDRESS=0x0012, /* TURN-12 */
265 STUN_ATTRIBUTE_DATA=0x0013, /* TURN-12 */
266 STUN_ATTRIBUTE_REALM=0x0014, /* RFC5389 */
267 STUN_ATTRIBUTE_NONCE=0x0015, /* RFC5389 */
268 STUN_ATTRIBUTE_RELAY_ADDRESS=0x0016, /* TURN-04 */
269 STUN_ATTRIBUTE_RELAYED_ADDRESS=0x0016, /* TURN-09 */
270 STUN_ATTRIBUTE_XOR_RELAYED_ADDRESS=0x0016, /* TURN-12 */
271 STUN_ATTRIBUTE_REQUESTED_ADDRESS_TYPE=0x0017, /* TURN-IPv6-05 */
272 STUN_ATTRIBUTE_REQUESTED_PORT_PROPS=0x0018, /* TURN-04 */
273 STUN_ATTRIBUTE_REQUESTED_PROPS=0x0018, /* TURN-09 */
274 STUN_ATTRIBUTE_EVEN_PORT=0x0018, /* TURN-12 */
275 STUN_ATTRIBUTE_REQUESTED_TRANSPORT=0x0019, /* TURN-12 */
276 STUN_ATTRIBUTE_DONT_FRAGMENT=0x001A, /* TURN-12 */
277 /* 0x001B */ /* reserved */
278 /* 0x001C */ /* reserved */
279 /* 0x001D */ /* reserved */
280 /* 0x001E */ /* reserved */
281 /* 0x001F */ /* reserved */
282 STUN_ATTRIBUTE_XOR_MAPPED_ADDRESS=0x0020, /* RFC5389 */
283 STUN_ATTRIBUTE_TIMER_VAL=0x0021, /* TURN-04 */
284 STUN_ATTRIBUTE_REQUESTED_IP=0x0022, /* TURN-04 */
285 STUN_ATTRIBUTE_RESERVATION_TOKEN=0x0022, /* TURN-09 */
286 STUN_ATTRIBUTE_CONNECT_STAT=0x0023, /* TURN-04 */
287 STUN_ATTRIBUTE_PRIORITY=0x0024, /* ICE-19 */
288 STUN_ATTRIBUTE_USE_CANDIDATE=0x0025, /* ICE-19 */
289 /* 0x0026 */ /* reserved */
290 /* 0x0027 */ /* reserved */
291 /* 0x0028 */ /* reserved */
292 /* 0x0029 */ /* reserved */
293 /* 0x002A-0x7fff */ /* reserved */
295 /* Optional attributes */
296 /* 0x8000-0x8021 */ /* reserved */
297 STUN_ATTRIBUTE_OPTIONS=0x8001, /* libjingle */
298 STUN_ATTRIBUTE_MS_VERSION=0x8008, /* MS-TURN */
299 STUN_ATTRIBUTE_MS_XOR_MAPPED_ADDRESS=0x8020, /* MS-TURN */
300 STUN_ATTRIBUTE_SOFTWARE=0x8022, /* RFC5389 */
301 STUN_ATTRIBUTE_ALTERNATE_SERVER=0x8023, /* RFC5389 */
302 /* 0x8024 */ /* reserved */
303 /* 0x8025 */ /* reserved */
304 /* 0x8026 */ /* reserved */
305 /* 0x8027 */ /* reserved */
306 STUN_ATTRIBUTE_FINGERPRINT=0x8028, /* RFC5389 */
307 STUN_ATTRIBUTE_ICE_CONTROLLED=0x8029, /* ICE-19 */
308 STUN_ATTRIBUTE_ICE_CONTROLLING=0x802A, /* ICE-19 */
309 /* 0x802B-0x804F */ /* reserved */
310 STUN_ATTRIBUTE_MS_SEQUENCE_NUMBER=0x8050, /* MS-TURN */
311 /* 0x8051-0x8053 */ /* reserved */
312 STUN_ATTRIBUTE_CANDIDATE_IDENTIFIER=0x8054, /* MS-ICE2 */
313 /* 0x8055-0x806F */ /* reserved */
314 STUN_ATTRIBUTE_MS_IMPLEMENTATION_VERSION=0x8070, /* MS-ICE2 */
315 /* 0x8071-0xC000 */ /* reserved */
316 STUN_ATTRIBUTE_NOMINATION=0xC001 /* https://tools.ietf.org/html/draft-thatcher-ice-renomination-00 */
317 /* 0xC002-0xFFFF */ /* reserved */
322 * STUN_ALL_KNOWN_ATTRIBUTES:
324 * An array containing all the currently known and defined mandatory attributes
327 /* Should be in sync with StunAttribute */
328 static const uint16_t STUN_ALL_KNOWN_ATTRIBUTES[] =
330 STUN_ATTRIBUTE_MAPPED_ADDRESS,
331 STUN_ATTRIBUTE_RESPONSE_ADDRESS,
332 STUN_ATTRIBUTE_CHANGE_REQUEST,
333 STUN_ATTRIBUTE_SOURCE_ADDRESS,
334 STUN_ATTRIBUTE_CHANGED_ADDRESS,
335 STUN_ATTRIBUTE_USERNAME,
336 STUN_ATTRIBUTE_PASSWORD,
337 STUN_ATTRIBUTE_MESSAGE_INTEGRITY,
338 STUN_ATTRIBUTE_ERROR_CODE,
339 STUN_ATTRIBUTE_UNKNOWN_ATTRIBUTES,
340 STUN_ATTRIBUTE_REFLECTED_FROM,
341 STUN_ATTRIBUTE_CHANNEL_NUMBER,
342 STUN_ATTRIBUTE_LIFETIME,
343 STUN_ATTRIBUTE_MAGIC_COOKIE,
344 STUN_ATTRIBUTE_BANDWIDTH,
345 STUN_ATTRIBUTE_DESTINATION_ADDRESS,
346 STUN_ATTRIBUTE_REMOTE_ADDRESS,
347 STUN_ATTRIBUTE_PEER_ADDRESS,
348 STUN_ATTRIBUTE_XOR_PEER_ADDRESS,
350 STUN_ATTRIBUTE_REALM,
351 STUN_ATTRIBUTE_NONCE,
352 STUN_ATTRIBUTE_RELAY_ADDRESS,
353 STUN_ATTRIBUTE_RELAYED_ADDRESS,
354 STUN_ATTRIBUTE_XOR_RELAYED_ADDRESS,
355 STUN_ATTRIBUTE_REQUESTED_ADDRESS_TYPE,
356 STUN_ATTRIBUTE_REQUESTED_PORT_PROPS,
357 STUN_ATTRIBUTE_REQUESTED_PROPS,
358 STUN_ATTRIBUTE_EVEN_PORT,
359 STUN_ATTRIBUTE_REQUESTED_TRANSPORT,
360 STUN_ATTRIBUTE_DONT_FRAGMENT,
361 STUN_ATTRIBUTE_XOR_MAPPED_ADDRESS,
362 STUN_ATTRIBUTE_TIMER_VAL,
363 STUN_ATTRIBUTE_REQUESTED_IP,
364 STUN_ATTRIBUTE_RESERVATION_TOKEN,
365 STUN_ATTRIBUTE_CONNECT_STAT,
366 STUN_ATTRIBUTE_PRIORITY,
367 STUN_ATTRIBUTE_USE_CANDIDATE,
372 * STUN_MSOC_KNOWN_ATTRIBUTES:
374 * An array containing all the currently known mandatory attributes used by
375 * Microsoft Office Communicator as defined in [MS-TURN]
377 static const uint16_t STUN_MSOC_KNOWN_ATTRIBUTES[] =
379 STUN_ATTRIBUTE_MAPPED_ADDRESS,
380 STUN_ATTRIBUTE_USERNAME,
381 STUN_ATTRIBUTE_MESSAGE_INTEGRITY,
382 STUN_ATTRIBUTE_ERROR_CODE,
383 STUN_ATTRIBUTE_UNKNOWN_ATTRIBUTES,
384 STUN_ATTRIBUTE_LIFETIME,
385 STUN_ATTRIBUTE_MS_ALTERNATE_SERVER,
386 STUN_ATTRIBUTE_MAGIC_COOKIE,
387 STUN_ATTRIBUTE_BANDWIDTH,
388 STUN_ATTRIBUTE_DESTINATION_ADDRESS,
389 STUN_ATTRIBUTE_REMOTE_ADDRESS,
391 /* REALM and NONCE have swapped hexadecimal IDs in [MS-TURN]. Libnice users
392 * or developers can still use these enumeration values in their original
393 * meanings from StunAttribute anywhere in the code, as stun_message_find()
394 * and stun_message_append() will choose correct ID in MSOC compatibility
396 STUN_ATTRIBUTE_NONCE,
397 STUN_ATTRIBUTE_REALM,
404 * A type that holds a STUN transaction id.
406 typedef uint8_t StunTransactionId[STUN_MESSAGE_TRANS_ID_LEN];
411 * @STUN_ERROR_TRY_ALTERNATE: The ERROR-CODE value for the
412 * "Try Alternate" error as defined in RFC5389
413 * @STUN_ERROR_BAD_REQUEST: The ERROR-CODE value for the
414 * "Bad Request" error as defined in RFC5389
415 * @STUN_ERROR_UNAUTHORIZED: The ERROR-CODE value for the
416 * "Unauthorized" error as defined in RFC5389
417 * @STUN_ERROR_UNKNOWN_ATTRIBUTE: The ERROR-CODE value for the
418 * "Unknown Attribute" error as defined in RFC5389
419 * @STUN_ERROR_ALLOCATION_MISMATCH:The ERROR-CODE value for the
420 * "Allocation Mismatch" error as defined in TURN draft 12.
421 * Equivalent to the "No Binding" error defined in TURN draft 04.
422 * @STUN_ERROR_STALE_NONCE: The ERROR-CODE value for the
423 * "Stale Nonce" error as defined in RFC5389
424 * @STUN_ERROR_ACT_DST_ALREADY: The ERROR-CODE value for the
425 * "Active Destination Already Set" error as defined in TURN draft 04.
426 * @STUN_ERROR_UNSUPPORTED_FAMILY: The ERROR-CODE value for the
427 * "Address Family not Supported" error as defined in TURN IPV6 Draft 05.
428 * @STUN_ERROR_WRONG_CREDENTIALS: The ERROR-CODE value for the
429 * "Wrong Credentials" error as defined in TURN Draft 12.
430 * @STUN_ERROR_UNSUPPORTED_TRANSPORT:he ERROR-CODE value for the
431 * "Unsupported Transport Protocol" error as defined in TURN Draft 12.
432 * @STUN_ERROR_INVALID_IP: The ERROR-CODE value for the
433 * "Invalid IP Address" error as defined in TURN draft 04.
434 * @STUN_ERROR_INVALID_PORT: The ERROR-CODE value for the
435 * "Invalid Port" error as defined in TURN draft 04.
436 * @STUN_ERROR_OP_TCP_ONLY: The ERROR-CODE value for the
437 * "Operation for TCP Only" error as defined in TURN draft 04.
438 * @STUN_ERROR_CONN_ALREADY: The ERROR-CODE value for the
439 * "Connection Already Exists" error as defined in TURN draft 04.
440 * @STUN_ERROR_ALLOCATION_QUOTA_REACHED: The ERROR-CODE value for the
441 * "Allocation Quota Reached" error as defined in TURN draft 12.
442 * @STUN_ERROR_ROLE_CONFLICT:The ERROR-CODE value for the
443 * "Role Conflict" error as defined in ICE draft 19.
444 * @STUN_ERROR_SERVER_ERROR: The ERROR-CODE value for the
445 * "Server Error" error as defined in RFC5389
446 * @STUN_ERROR_SERVER_CAPACITY: The ERROR-CODE value for the
447 * "Insufficient Capacity" error as defined in TURN draft 04.
448 * @STUN_ERROR_INSUFFICIENT_CAPACITY: The ERROR-CODE value for the
449 * "Insufficient Capacity" error as defined in TURN draft 12.
450 * @STUN_ERROR_MAX: The maximum possible ERROR-CODE value as defined by RFC 5389.
452 * STUN error codes as defined by various RFCs and drafts
454 /* Should be in sync with stun_strerror() */
457 STUN_ERROR_TRY_ALTERNATE=300, /* RFC5389 */
458 STUN_ERROR_BAD_REQUEST=400, /* RFC5389 */
459 STUN_ERROR_UNAUTHORIZED=401, /* RFC5389 */
460 STUN_ERROR_UNKNOWN_ATTRIBUTE=420, /* RFC5389 */
461 STUN_ERROR_ALLOCATION_MISMATCH=437, /* TURN-12 */
462 STUN_ERROR_STALE_NONCE=438, /* RFC5389 */
463 STUN_ERROR_ACT_DST_ALREADY=439, /* TURN-04 */
464 STUN_ERROR_UNSUPPORTED_FAMILY=440, /* TURN-IPv6-05 */
465 STUN_ERROR_WRONG_CREDENTIALS=441, /* TURN-12 */
466 STUN_ERROR_UNSUPPORTED_TRANSPORT=442, /* TURN-12 */
467 STUN_ERROR_INVALID_IP=443, /* TURN-04 */
468 STUN_ERROR_INVALID_PORT=444, /* TURN-04 */
469 STUN_ERROR_OP_TCP_ONLY=445, /* TURN-04 */
470 STUN_ERROR_CONN_ALREADY=446, /* TURN-04 */
471 STUN_ERROR_ALLOCATION_QUOTA_REACHED=486, /* TURN-12 */
472 STUN_ERROR_ROLE_CONFLICT=487, /* ICE-19 */
473 STUN_ERROR_SERVER_ERROR=500, /* RFC5389 */
474 STUN_ERROR_SERVER_CAPACITY=507, /* TURN-04 */
475 STUN_ERROR_INSUFFICIENT_CAPACITY=508, /* TURN-12 */
482 * @STUN_MESSAGE_RETURN_SUCCESS: The operation was successful
483 * @STUN_MESSAGE_RETURN_NOT_FOUND: The attribute was not found
484 * @STUN_MESSAGE_RETURN_INVALID: The argument or data is invalid
485 * @STUN_MESSAGE_RETURN_NOT_ENOUGH_SPACE: There is not enough space in the
486 * message to append data to it, or not enough in an argument to fill it with
487 * the data requested.
488 * @STUN_MESSAGE_RETURN_UNSUPPORTED_ADDRESS: The address in the arguments or in
489 * the STUN message is not supported.
491 * The return value of most stun_message_* functions.
492 * This enum will report on whether an operation was successful or not
493 * and what error occured if any.
497 STUN_MESSAGE_RETURN_SUCCESS,
498 STUN_MESSAGE_RETURN_NOT_FOUND,
499 STUN_MESSAGE_RETURN_INVALID,
500 STUN_MESSAGE_RETURN_NOT_ENOUGH_SPACE,
501 STUN_MESSAGE_RETURN_UNSUPPORTED_ADDRESS
504 #include "stunagent.h"
507 * STUN_MAX_MESSAGE_SIZE:
509 * The Maximum size of a STUN message
511 #define STUN_MAX_MESSAGE_SIZE 65552
515 * @agent: The agent that created or validated this message
516 * @buffer: The buffer containing the STUN message
517 * @buffer_len: The length of the buffer (not the size of the message)
518 * @key: The short term credentials key to use for authentication validation
519 * or that was used to finalize this message
520 * @key_len: The length of the associated key
521 * @long_term_key: The long term credential key to use for authentication
522 * validation or that was used to finalize this message
523 * @long_term_valid: Whether or not the #long_term_key variable contains valid
526 * This structure represents a STUN message
528 struct _StunMessage {
534 uint8_t long_term_key[16];
535 bool long_term_valid;
540 * @msg: The #StunMessage to initialize
541 * @c: STUN message class (host byte order)
542 * @m: STUN message method (host byte order)
543 * @id: 16-bytes transaction ID
545 * Initializes a STUN message buffer, with no attributes.
546 * Returns: %TRUE if the initialization was successful
548 bool stun_message_init (StunMessage *msg, StunClass c, StunMethod m,
549 const StunTransactionId id);
552 * stun_message_length:
553 * @msg: The #StunMessage
555 * Get the length of the message (including the header)
557 * Returns: The length of the message
559 uint16_t stun_message_length (const StunMessage *msg);
563 * @msg: The #StunMessage
564 * @type: The #StunAttribute to find
565 * @palen: A pointer to store the length of the attribute
567 * Finds an attribute in a STUN message and fetches its content
569 * Returns: A pointer to the start of the attribute payload if found,
572 const void * stun_message_find (const StunMessage * msg, StunAttribute type,
577 * stun_message_find_flag:
578 * @msg: The #StunMessage
579 * @type: The #StunAttribute to find
581 * Looks for a flag attribute within a valid STUN message.
583 * Returns: A #StunMessageReturn value.
584 * %STUN_MESSAGE_RETURN_INVALID is returned if the attribute's size is not zero.
586 StunMessageReturn stun_message_find_flag (const StunMessage *msg,
590 * stun_message_find32:
591 * @msg: The #StunMessage
592 * @type: The #StunAttribute to find
593 * @pval: A pointer where to store the value (host byte order)
595 * Extracts a 32-bits attribute from a STUN message.
597 * Returns: A #StunMessageReturn value.
598 * %STUN_MESSAGE_RETURN_INVALID is returned if the attribute's size is not
601 StunMessageReturn stun_message_find32 (const StunMessage *msg,
602 StunAttribute type, uint32_t *pval);
605 * stun_message_find64:
606 * @msg: The #StunMessage
607 * @type: The #StunAttribute to find
608 * @pval: A pointer where to store the value (host byte order)
610 * Extracts a 64-bits attribute from a STUN message.
612 * Returns: A #StunMessageReturn value.
613 * %STUN_MESSAGE_RETURN_INVALID is returned if the attribute's size is not
616 StunMessageReturn stun_message_find64 (const StunMessage *msg,
617 StunAttribute type, uint64_t *pval);
620 * stun_message_find_string:
621 * @msg: The #StunMessage
622 * @type: The #StunAttribute to find
623 * @buf: A pointer where to store the data
624 * @buflen: The length of the buffer
626 * Extracts an UTF-8 string from a valid STUN message.
628 * Returns: A #StunMessageReturn value.
629 * %STUN_MESSAGE_RETURN_INVALID is returned if the attribute is improperly
631 * %STUN_MESSAGE_RETURN_NOT_ENOUGH_SPACE is return if the buffer size is too
632 * small to hold the string
636 The string will be nul-terminated.
641 StunMessageReturn stun_message_find_string (const StunMessage *msg,
642 StunAttribute type, char *buf, size_t buflen);
645 * stun_message_find_addr:
646 * @msg: The #StunMessage
647 * @type: The #StunAttribute to find
648 * @addr: The #sockaddr to be filled
649 * @addrlen: The size of the @addr variable. Must be set to the size of the
650 * @addr socket address and will be set to the size of the extracted socket
653 * Extracts a network address attribute from a STUN message.
655 * Returns: A #StunMessageReturn value.
656 * %STUN_MESSAGE_RETURN_INVALID is returned if the attribute payload size is
657 * wrong or if the @addrlen is too small
658 * %STUN_MESSAGE_RETURN_UNSUPPORTED_ADDRESS if the address family is unknown.
660 StunMessageReturn stun_message_find_addr (const StunMessage *msg,
661 StunAttribute type, struct sockaddr_storage *addr, socklen_t *addrlen);
664 * stun_message_find_xor_addr:
665 * @msg: The #StunMessage
666 * @type: The #StunAttribute to find
667 * @addr: The #sockaddr to be filled
668 * @addrlen: The size of the @addr variable. Must be set to the size of the
669 * @addr socket address and will be set to the size of the
670 * extracted socket address.
672 * Extracts an obfuscated network address attribute from a STUN message.
674 * Returns: A #StunMessageReturn value.
675 * %STUN_MESSAGE_RETURN_INVALID is returned if the attribute payload size is
676 * wrong or if the @addrlen is too small
677 * %STUN_MESSAGE_RETURN_UNSUPPORTED_ADDRESS if the address family is unknown.
679 StunMessageReturn stun_message_find_xor_addr (const StunMessage *msg,
680 StunAttribute type, struct sockaddr_storage *addr, socklen_t *addrlen);
683 * stun_message_find_xor_addr_full:
684 * @msg: The #StunMessage
685 * @type: The #StunAttribute to find
686 * @addr: The #sockaddr to be filled
687 * @addrlen: The size of the @addr variable. Must be set to the size of the
688 * @addr socket address and will be set to the size of the
689 * extracted socket address.
690 * @magic_cookie: The magic cookie to use to XOR the address.
692 * Extracts an obfuscated network address attribute from a STUN message.
694 * Returns: A #StunMessageReturn value.
695 * %STUN_MESSAGE_RETURN_INVALID is returned if the attribute payload size is
696 * wrong or if the @addrlen is too small
697 * %STUN_MESSAGE_RETURN_UNSUPPORTED_ADDRESS if the address family is unknown.
699 StunMessageReturn stun_message_find_xor_addr_full (const StunMessage *msg,
700 StunAttribute type, struct sockaddr_storage *addr,
701 socklen_t *addrlen, uint32_t magic_cookie);
705 * stun_message_find_error:
706 * @msg: The #StunMessage
707 * @code: A pointer where to store the value
709 * Extract the error response code from a STUN message
711 * Returns: A #StunMessageReturn value.
712 * %STUN_MESSAGE_RETURN_INVALID is returned if the value is invalid
714 StunMessageReturn stun_message_find_error (const StunMessage *msg, int *code);
718 * stun_message_append:
719 * @msg: The #StunMessage
720 * @type: The #StunAttribute to append
721 * @length: The length of the attribute
723 * Reserves room for appending an attribute to an unfinished STUN message.
725 * Returns: A pointer to an unitialized buffer of @length bytes to
726 * where the attribute payload must be written, or NULL if there is not
727 * enough room in the STUN message buffer.
729 void *stun_message_append (StunMessage *msg, StunAttribute type,
733 * stun_message_append_bytes:
734 * @msg: The #StunMessage
735 * @type: The #StunAttribute to append
736 * @data: The data to append
737 * @len: The length of the attribute
739 * Appends a binary value to a STUN message
741 * Returns: A #StunMessageReturn value.
743 StunMessageReturn stun_message_append_bytes (StunMessage *msg,
744 StunAttribute type, const void *data, size_t len);
747 * stun_message_append_flag:
748 * @msg: The #StunMessage
749 * @type: The #StunAttribute to append
751 * Appends an empty flag attribute to a STUN message
753 * Returns: A #StunMessageReturn value.
755 StunMessageReturn stun_message_append_flag (StunMessage *msg,
759 * stun_message_append32:
760 * @msg: The #StunMessage
761 * @type: The #StunAttribute to append
762 * @value: The value to append (host byte order)
764 * Appends a 32-bits value attribute to a STUN message
766 * Returns: A #StunMessageReturn value.
768 StunMessageReturn stun_message_append32 (StunMessage *msg,
769 StunAttribute type, uint32_t value);
772 * stun_message_append64:
773 * @msg: The #StunMessage
774 * @type: The #StunAttribute to append
775 * @value: The value to append (host byte order)
777 * Appends a 64-bits value attribute to a STUN message
779 * Returns: A #StunMessageReturn value.
781 StunMessageReturn stun_message_append64 (StunMessage *msg,
782 StunAttribute type, uint64_t value);
785 * stun_message_append_string:
786 * @msg: The #StunMessage
787 * @type: The #StunAttribute to append
788 * @str: The string to append
790 * Adds an attribute from a nul-terminated string to a STUN message
792 * Returns: A #StunMessageReturn value.
794 StunMessageReturn stun_message_append_string (StunMessage *msg,
795 StunAttribute type, const char *str);
798 * stun_message_append_addr:
799 * @msg: The #StunMessage
800 * @type: The #StunAttribute to append
801 * @addr: The #sockaddr to be append
802 * @addrlen: The size of the @addr variable.
804 * Append a network address attribute to a STUN message
806 * Returns: A #StunMessageReturn value.
807 * %STUN_MESSAGE_RETURN_INVALID is returned if the @addrlen is too small
808 * %STUN_MESSAGE_RETURN_UNSUPPORTED_ADDRESS if the address family is unknown.
810 StunMessageReturn stun_message_append_addr (StunMessage * msg,
811 StunAttribute type, const struct sockaddr *addr, socklen_t addrlen);
814 * stun_message_append_xor_addr:
815 * @msg: The #StunMessage
816 * @type: The #StunAttribute to append
817 * @addr: The #sockaddr to be append
818 * @addrlen: The size of the @addr variable.
820 * Append an obfuscated network address attribute to a STUN message
822 * Returns: A #StunMessageReturn value.
823 * %STUN_MESSAGE_RETURN_INVALID is returned if the @addrlen is too small
824 * %STUN_MESSAGE_RETURN_UNSUPPORTED_ADDRESS if the address family is unknown.
826 StunMessageReturn stun_message_append_xor_addr (StunMessage * msg,
827 StunAttribute type, const struct sockaddr_storage *addr, socklen_t addrlen);
830 * stun_message_append_xor_addr_full:
831 * @msg: The #StunMessage
832 * @type: The #StunAttribute to append
833 * @addr: The #sockaddr to be append
834 * @addrlen: The size of the @addr variable.
835 * @magic_cookie: The magic cookie to use to XOR the address.
837 * Append an obfuscated network address attribute from a STUN message.
839 * Returns: A #StunMessageReturn value.
840 * %STUN_MESSAGE_RETURN_INVALID is returned if the @addrlen is too small
841 * %STUN_MESSAGE_RETURN_UNSUPPORTED_ADDRESS if the address family is unknown.
843 StunMessageReturn stun_message_append_xor_addr_full (StunMessage * msg,
844 StunAttribute type, const struct sockaddr_storage *addr, socklen_t addrlen,
845 uint32_t magic_cookie);
848 * stun_message_append_error:
849 * @msg: The #StunMessage
850 * @code: The error code value
852 * Appends the ERROR-CODE attribute to the STUN message and fills it according
855 * Returns: A #StunMessageReturn value.
857 StunMessageReturn stun_message_append_error (StunMessage * msg,
861 * STUN_MESSAGE_BUFFER_INCOMPLETE:
863 * Convenience macro for stun_message_validate_buffer_length() meaning that the
864 * data to validate does not hold a complete STUN message
866 #define STUN_MESSAGE_BUFFER_INCOMPLETE 0
869 * STUN_MESSAGE_BUFFER_INVALID:
871 * Convenience macro for stun_message_validate_buffer_length() meaning that the
872 * data to validate is not a valid STUN message
874 #define STUN_MESSAGE_BUFFER_INVALID -1
878 * stun_message_validate_buffer_length:
879 * @msg: The buffer to validate
880 * @length: The length of the buffer
881 * @has_padding: Set TRUE if attributes should be padded to multiple of 4 bytes
883 * This function will take a data buffer and will try to validate whether it is
884 * a STUN message or if it's not or if it's an incomplete STUN message and will
885 * provide us with the length of the STUN message.
887 * Returns: The length of the valid STUN message in the buffer.
888 * <para> See also: #STUN_MESSAGE_BUFFER_INCOMPLETE </para>
889 * <para> See also: #STUN_MESSAGE_BUFFER_INVALID </para>
891 int stun_message_validate_buffer_length (const uint8_t *msg, size_t length,
896 * @buffer: a buffer containing already-received binary data
897 * @size: length of @buffer, in bytes
899 * Container for a single buffer which also stores its length. This is designed
900 * for vectored I/O: typically an array of #StunInputVectors is passed to
901 * functions, providing multiple buffers which store logically contiguous
904 * This is guaranteed to be layed out identically in memory to #GInputVector.
909 const uint8_t *buffer;
914 * stun_message_validate_buffer_length_fast:
915 * @buffers: (array length=n_buffers) (in caller-allocated): array of contiguous
916 * #StunInputVectors containing already-received message data
917 * @n_buffers: number of entries in @buffers or if -1 , then buffers is
918 * terminated by a #StunInputVector with the buffer pointer being %NULL.
919 * @total_length: total number of valid bytes stored consecutively in @buffers
920 * @has_padding: %TRUE if attributes should be padded to 4-byte boundaries
922 * Quickly validate whether the message in the given @buffers is potentially a
923 * valid STUN message, an incomplete STUN message, or if it’s definitely not one
926 * This is designed as a first-pass validation only, and does not check the
927 * message’s attributes for validity. If this function returns success, the
928 * buffers can be compacted and a more thorough validation can be performed
929 * using stun_message_validate_buffer_length(). If it fails, the buffers
930 * definitely do not contain a complete, valid STUN message.
932 * Returns: The length of the valid STUN message in the buffer, or zero or -1 on
934 * <para> See also: #STUN_MESSAGE_BUFFER_INCOMPLETE </para>
935 * <para> See also: #STUN_MESSAGE_BUFFER_INVALID </para>
939 ssize_t stun_message_validate_buffer_length_fast (StunInputVector *buffers,
940 int n_buffers, size_t total_length, bool has_padding);
944 * @msg: The #StunMessage
945 * @id: The #StunTransactionId to fill
947 * Retreive the STUN transaction id from a STUN message
949 void stun_message_id (const StunMessage *msg, StunTransactionId id);
952 * stun_message_get_class:
953 * @msg: The #StunMessage
955 * Retreive the STUN class from a STUN message
957 * Returns: The #StunClass
959 StunClass stun_message_get_class (const StunMessage *msg);
962 * stun_message_get_method:
963 * @msg: The #StunMessage
965 * Retreive the STUN method from a STUN message
967 * Returns: The #StunMethod
969 StunMethod stun_message_get_method (const StunMessage *msg);
972 * stun_message_has_attribute:
973 * @msg: The #StunMessage
974 * @type: The #StunAttribute to look for
976 * Checks if an attribute is present within a STUN message.
978 * Returns: %TRUE if the attribute is found, %FALSE otherwise
980 bool stun_message_has_attribute (const StunMessage *msg, StunAttribute type);
983 /* Defined in stun5389.c */
985 * stun_message_has_cookie:
986 * @msg: The #StunMessage
988 * Checks if the STUN message has a RFC5389 compatible cookie
990 * Returns: %TRUE if the cookie is present, %FALSE otherwise
992 bool stun_message_has_cookie (const StunMessage *msg);
997 * @t: An attribute type
999 * Helper function that checks whether a STUN attribute is a mandatory
1000 * or an optional attribute
1002 * Returns: %TRUE if the attribute is an optional one
1004 bool stun_optional (uint16_t t);
1008 * @code: host-byte order error code
1010 * Transforms a STUN error-code into a human readable string
1012 * Returns: A static pointer to a nul-terminated error message string.
1014 const char *stun_strerror (StunError code);
1017 #endif /* _STUN_MESSAGE_H */