stun/stunmessage.h

   1 /*
   2  * This file is part of the Nice GLib ICE library.
   3  *
   4  * (C) 2008 Collabora Ltd.
   5  * (C) 2008 Nokia Corporation. All rights reserved.
   6  *  Contact: Youness Alaoui
   7  *
   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/
  12  *
  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.
  17  *
  18  * The Original Code is the Nice GLib ICE library.
  19  *
  20  * The Initial Developers of the Original Code are Collabora Ltd and Nokia
  21  * Corporation. All Rights Reserved.
  22  *
  23  *
  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.
  33  */
  34
  35 #ifndef _STUN_MESSAGE_H
  36 #define _STUN_MESSAGE_H
  37
  38
  39 /**
  40  * SECTION:stunmessage
  41  * @short_description: STUN messages parsing and formatting functions
  42  * @see_also: #StunAgent
  43  * @stability: Stable
  44  *
  45  * The STUN Messages API allows you to create STUN messages easily as well as to
  46  * parse existing messages.
  47  *
  48  */
  49
  50
  51 #ifdef _WIN32
  52 #include "win32_common.h"
  53 #else
  54 #include <stdint.h>
  55 #include <stdbool.h>
  56 #endif
  57
  58 #include <sys/types.h>
  59
  60 #ifdef _WIN32
  61 #include <winsock2.h>
  62 #include <ws2tcpip.h>
  63 #else
  64 #include <sys/socket.h>
  65 #include <arpa/inet.h>
  66 #endif
  67
  68 #include "constants.h"
  69
  70 typedef struct _StunMessage StunMessage;
  71
  72 /**
  73  * StunClass:
  74  * @STUN_REQUEST: A STUN Request message
  75  * @STUN_INDICATION: A STUN indication message
  76  * @STUN_RESPONSE: A STUN Response message
  77  * @STUN_ERROR: A STUN Error message
  78  *
  79  * This enum is used to represent the class of
  80  * a STUN message, as defined in RFC5389
  81  */
  82
  83 /* Message classes */
  84 typedef enum
  85 {
  86   STUN_REQUEST=0,
  87   STUN_INDICATION=1,
  88   STUN_RESPONSE=2,
  89   STUN_ERROR=3
  90 } StunClass;
  91
  92
  93 /**
  94  * StunMethod:
  95  * @STUN_BINDING: The Binding method as defined by the RFC5389
  96  * @STUN_SHARED_SECRET: The Shared-Secret method as defined by the RFC3489
  97  * @STUN_ALLOCATE: The Allocate method as defined by the TURN draft 12
  98  * @STUN_SET_ACTIVE_DST: The Set-Active-Destination method as defined by
  99  * the TURN draft 4
 100  * @STUN_REFRESH: The Refresh method as defined by the TURN draft 12
 101  * @STUN_SEND: The Send method as defined by the TURN draft 00
 102  * @STUN_CONNECT: The Connect method as defined by the TURN draft 4
 103  * @STUN_OLD_SET_ACTIVE_DST: The older Set-Active-Destination method as
 104  * defined by the TURN draft 0
 105  * @STUN_IND_SEND: The Send method used in indication messages as defined
 106  * by the TURN draft 12
 107  * @STUN_IND_DATA: The Data method used in indication messages as defined
 108  * by the TURN draft 12
 109  * @STUN_IND_CONNECT_STATUS:  The Connect-Status method used in indication
 110  * messages as defined by the TURN draft 4
 111  * @STUN_CREATEPERMISSION: The CreatePermission method as defined by
 112  * the TURN draft 12
 113  * @STUN_CHANNELBIND: The ChannelBind method as defined by the TURN draft 12
 114  *
 115  * This enum is used to represent the method of
 116  * a STUN message, as defined by various RFCs
 117  */
 118 /* Message methods */
 119 typedef enum
 120 {
 121   STUN_BINDING=0x001,    /* RFC5389 */
 122   STUN_SHARED_SECRET=0x002,  /* old RFC3489 */
 123   STUN_ALLOCATE=0x003,    /* TURN-12 */
 124   STUN_SET_ACTIVE_DST=0x004,  /* TURN-04 */
 125   STUN_REFRESH=0x004,  /* TURN-12 */
 126   STUN_SEND=0x004,  /* TURN-00 */
 127   STUN_CONNECT=0x005,    /* TURN-04 */
 128   STUN_OLD_SET_ACTIVE_DST=0x006,  /* TURN-00 */
 129   STUN_IND_SEND=0x006,    /* TURN-12 */
 130   STUN_IND_DATA=0x007,    /* TURN-12 */
 131   STUN_IND_CONNECT_STATUS=0x008,  /* TURN-04 */
 132   STUN_CREATEPERMISSION= 0x008, /* TURN-12 */
 133   STUN_CHANNELBIND= 0x009 /* TURN-12 */
 134 } StunMethod;
 135
 136 /**
 137  * StunAttribute:
 138  * @STUN_ATTRIBUTE_MAPPED_ADDRESS: The MAPPED-ADDRESS attribute as defined
 139  * by RFC5389
 140  * @STUN_ATTRIBUTE_RESPONSE_ADDRESS: The RESPONSE-ADDRESS attribute as defined
 141  * by RFC3489
 142  * @STUN_ATTRIBUTE_CHANGE_REQUEST: The CHANGE-REQUEST attribute as defined by
 143  * RFC3489
 144  * @STUN_ATTRIBUTE_SOURCE_ADDRESS: The SOURCE-ADDRESS attribute as defined by
 145  * RFC3489
 146  * @STUN_ATTRIBUTE_CHANGED_ADDRESS: The CHANGED-ADDRESS attribute as defined
 147  * by RFC3489
 148  * @STUN_ATTRIBUTE_USERNAME: The USERNAME attribute as defined by RFC5389
 149  * @STUN_ATTRIBUTE_PASSWORD: The PASSWORD attribute as defined by RFC3489
 150  * @STUN_ATTRIBUTE_MESSAGE_INTEGRITY: The MESSAGE-INTEGRITY attribute as defined
 151  * by RFC5389
 152  * @STUN_ATTRIBUTE_ERROR_CODE: The ERROR-CODE attribute as defined by RFC5389
 153  * @STUN_ATTRIBUTE_UNKNOWN_ATTRIBUTES: The UNKNOWN-ATTRIBUTES attribute as
 154  * defined by RFC5389
 155  * @STUN_ATTRIBUTE_REFLECTED_FROM: The REFLECTED-FROM attribute as defined
 156  * by RFC3489
 157  * @STUN_ATTRIBUTE_CHANNEL_NUMBER: The CHANNEL-NUMBER attribute as defined by
 158  * TURN draft 09 and 12
 159  * @STUN_ATTRIBUTE_LIFETIME: The LIFETIME attribute as defined by TURN
 160  * draft 04, 09 and 12
 161  * @STUN_ATTRIBUTE_MAGIC_COOKIE: The MAGIC-COOKIE attribute as defined by
 162  * the rosenberg-midcom TURN draft 08
 163  * @STUN_ATTRIBUTE_BANDWIDTH: The BANDWIDTH attribute as defined by TURN draft 04
 164  * @STUN_ATTRIBUTE_DESTINATION_ADDRESS: The DESTINATION-ADDRESS attribute as
 165  * defined by the rosenberg-midcom TURN draft 08
 166  * @STUN_ATTRIBUTE_REMOTE_ADDRESS: The REMOTE-ADDRESS attribute as defined by
 167  * TURN draft 04
 168  * @STUN_ATTRIBUTE_PEER_ADDRESS: The PEER-ADDRESS attribute as defined by
 169  * TURN draft 09
 170  * @STUN_ATTRIBUTE_XOR_PEER_ADDRESS: The XOR-PEER-ADDRESS attribute as defined
 171  * by TURN draft 12
 172  * @STUN_ATTRIBUTE_DATA: The DATA attribute as defined by TURN draft 04,
 173  * 09 and 12
 174  * @STUN_ATTRIBUTE_REALM: The REALM attribute as defined by RFC5389
 175  * @STUN_ATTRIBUTE_NONCE: The NONCE attribute as defined by RFC5389
 176  * @STUN_ATTRIBUTE_RELAY_ADDRESS: The RELAY-ADDRESS attribute as defined by
 177  * TURN draft 04
 178  * @STUN_ATTRIBUTE_RELAYED_ADDRESS: The RELAYED-ADDRESS attribute as defined by
 179  * TURN draft 09
 180  * @STUN_ATTRIBUTE_XOR_RELAYED_ADDRESS: The XOR-RELAYED-ADDRESS attribute as
 181  * defined by TURN draft 12
 182  * @STUN_ATTRIBUTE_REQUESTED_ADDRESS_TYPE: The REQUESTED-ADDRESS-TYPE attribute
 183  * as defined by TURN-IPV6 draft 05
 184  * @STUN_ATTRIBUTE_REQUESTED_PORT_PROPS: The REQUESTED-PORT-PROPS attribute
 185  * as defined by TURN draft 04
 186  * @STUN_ATTRIBUTE_REQUESTED_PROPS: The REQUESTED-PROPS attribute as defined
 187  * by TURN draft 09
 188  * @STUN_ATTRIBUTE_EVEN_PORT: The EVEN-PORT attribute as defined by TURN draft 12
 189  * @STUN_ATTRIBUTE_REQUESTED_TRANSPORT: The REQUESTED-TRANSPORT attribute as
 190  * defined by TURN draft 12
 191  * @STUN_ATTRIBUTE_DONT_FRAGMENT: The DONT-FRAGMENT attribute as defined
 192  * by TURN draft 12
 193  * @STUN_ATTRIBUTE_XOR_MAPPED_ADDRESS: The XOR-MAPPED-ADDRESS attribute as
 194  * defined by RFC5389
 195  * @STUN_ATTRIBUTE_TIMER_VAL: The TIMER-VAL attribute as defined by TURN draft 04
 196  * @STUN_ATTRIBUTE_REQUESTED_IP: The REQUESTED-IP attribute as defined by
 197  * TURN draft 04
 198  * @STUN_ATTRIBUTE_RESERVATION_TOKEN: The RESERVATION-TOKEN attribute as defined
 199  * by TURN draft 09 and 12
 200  * @STUN_ATTRIBUTE_CONNECT_STAT: The CONNECT-STAT attribute as defined by TURN
 201  * draft 04
 202  * @STUN_ATTRIBUTE_PRIORITY: The PRIORITY attribute as defined by ICE draft 19
 203  * @STUN_ATTRIBUTE_USE_CANDIDATE: The USE-CANDIDATE attribute as defined by
 204  * ICE draft 19
 205  * @STUN_ATTRIBUTE_OPTIONS: The OPTIONS optional attribute as defined by
 206  * libjingle
 207  * @STUN_ATTRIBUTE_SOFTWARE: The SOFTWARE optional attribute as defined by RFC5389
 208  * @STUN_ATTRIBUTE_ALTERNATE_SERVER: The ALTERNATE-SERVER optional attribute as
 209  * defined by RFC5389
 210  * @STUN_ATTRIBUTE_FINGERPRINT: The FINGERPRINT optional attribute as defined
 211  * by RFC5389
 212  * @STUN_ATTRIBUTE_ICE_CONTROLLED: The ICE-CONTROLLED optional attribute as
 213  * defined by ICE draft 19
 214  * @STUN_ATTRIBUTE_ICE_CONTROLLING: The ICE-CONTROLLING optional attribute as
 215  * defined by ICE draft 19
 216  *
 217  * Known STUN attribute types as defined by various RFCs and drafts
 218  */
 219 /* Should be in sync with stun_is_unknown() */
 220 typedef enum
 221 {
 222   /* Mandatory attributes */
 223   /* 0x0000 */        /* reserved */
 224   STUN_ATTRIBUTE_MAPPED_ADDRESS=0x0001,    /* RFC5389 */
 225   STUN_ATTRIBUTE_RESPONSE_ADDRESS=0x0002,  /* old RFC3489 */
 226   STUN_ATTRIBUTE_CHANGE_REQUEST=0x0003,    /* old RFC3489 */
 227   STUN_ATTRIBUTE_SOURCE_ADDRESS=0x0004,    /* old RFC3489 */
 228   STUN_ATTRIBUTE_CHANGED_ADDRESS=0x0005,  /* old RFC3489 */
 229   STUN_ATTRIBUTE_USERNAME=0x0006,      /* RFC5389 */
 230   STUN_ATTRIBUTE_PASSWORD=0x0007,    /* old RFC3489 */
 231   STUN_ATTRIBUTE_MESSAGE_INTEGRITY=0x0008,    /* RFC5389 */
 232   STUN_ATTRIBUTE_ERROR_CODE=0x0009,      /* RFC5389 */
 233   STUN_ATTRIBUTE_UNKNOWN_ATTRIBUTES=0x000A,    /* RFC5389 */
 234   STUN_ATTRIBUTE_REFLECTED_FROM=0x000B,    /* old RFC3489 */
 235   STUN_ATTRIBUTE_CHANNEL_NUMBER=0x000C,        /* TURN-12 */
 236   STUN_ATTRIBUTE_LIFETIME=0x000D,      /* TURN-12 */
 237   /* 0x000E */        /* reserved (was ALTERNATE-SERVER from midcom-TURN 08 */
 238   STUN_ATTRIBUTE_MAGIC_COOKIE=0x000F,        /* midcom-TURN 08 */
 239   STUN_ATTRIBUTE_BANDWIDTH=0x0010,      /* TURN-04 */
 240   STUN_ATTRIBUTE_DESTINATION_ADDRESS=0x0011,        /* midcom-TURN 08 */
 241   STUN_ATTRIBUTE_REMOTE_ADDRESS=0x0012,    /* TURN-04 */
 242   STUN_ATTRIBUTE_PEER_ADDRESS=0x0012,    /* TURN-09 */
 243   STUN_ATTRIBUTE_XOR_PEER_ADDRESS=0x0012,    /* TURN-12 */
 244   STUN_ATTRIBUTE_DATA=0x0013,      /* TURN-12 */
 245   STUN_ATTRIBUTE_REALM=0x0014,      /* RFC5389 */
 246   STUN_ATTRIBUTE_NONCE=0x0015,      /* RFC5389 */
 247   STUN_ATTRIBUTE_RELAY_ADDRESS=0x0016,    /* TURN-04 */
 248   STUN_ATTRIBUTE_RELAYED_ADDRESS=0x0016,    /* TURN-09 */
 249   STUN_ATTRIBUTE_XOR_RELAYED_ADDRESS=0x0016,    /* TURN-12 */
 250   STUN_ATTRIBUTE_REQUESTED_ADDRESS_TYPE=0x0017,  /* TURN-IPv6-05 */
 251   STUN_ATTRIBUTE_REQUESTED_PORT_PROPS=0x0018,  /* TURN-04 */
 252   STUN_ATTRIBUTE_REQUESTED_PROPS=0x0018,  /* TURN-09 */
 253   STUN_ATTRIBUTE_EVEN_PORT=0x0018,  /* TURN-12 */
 254   STUN_ATTRIBUTE_REQUESTED_TRANSPORT=0x0019,  /* TURN-12 */
 255   STUN_ATTRIBUTE_DONT_FRAGMENT=0x001A,  /* TURN-12 */
 256   /* 0x001B */        /* reserved */
 257   /* 0x001C */        /* reserved */
 258   /* 0x001D */        /* reserved */
 259   /* 0x001E */        /* reserved */
 260   /* 0x001F */        /* reserved */
 261   STUN_ATTRIBUTE_XOR_MAPPED_ADDRESS=0x0020,    /* RFC5389 */
 262   STUN_ATTRIBUTE_TIMER_VAL=0x0021,      /* TURN-04 */
 263   STUN_ATTRIBUTE_REQUESTED_IP=0x0022,    /* TURN-04 */
 264   STUN_ATTRIBUTE_RESERVATION_TOKEN=0x0022,    /* TURN-09 */
 265   STUN_ATTRIBUTE_CONNECT_STAT=0x0023,    /* TURN-04 */
 266   STUN_ATTRIBUTE_PRIORITY=0x0024,      /* ICE-19 */
 267   STUN_ATTRIBUTE_USE_CANDIDATE=0x0025,    /* ICE-19 */
 268   /* 0x0026 */        /* reserved */
 269   /* 0x0027 */        /* reserved */
 270   /* 0x0028 */        /* reserved */
 271   /* 0x0029 */        /* reserved */
 272   /* 0x002A-0x7fff */      /* reserved */
 273
 274   /* Optional attributes */
 275   /* 0x8000-0x8021 */      /* reserved */
 276   STUN_ATTRIBUTE_OPTIONS=0x8001, /* libjingle */
 277   STUN_ATTRIBUTE_SOFTWARE=0x8022,      /* RFC5389 */
 278   STUN_ATTRIBUTE_ALTERNATE_SERVER=0x8023,    /* RFC5389 */
 279   /* 0x8024 */        /* reserved */
 280   /* 0x8025 */        /* reserved */
 281   /* 0x8026 */        /* reserved */
 282   /* 0x8027 */        /* reserved */
 283   STUN_ATTRIBUTE_FINGERPRINT=0x8028,    /* RFC5389 */
 284   STUN_ATTRIBUTE_ICE_CONTROLLED=0x8029,    /* ICE-19 */
 285   STUN_ATTRIBUTE_ICE_CONTROLLING=0x802A,    /* ICE-19 */
 286   /* 0x802B-0xFFFF */      /* reserved */
 287 } StunAttribute;
 288
 289
 290 /**
 291  * STUN_ALL_KNOWN_ATTRIBUTES:
 292  *
 293  * An array containing all the currently known and defined mandatory attributes
 294  * from StunAttribute
 295  */
 296 /* Should be in sync with StunAttribute */
 297 static const uint16_t STUN_ALL_KNOWN_ATTRIBUTES[] =
 298   {
 299     STUN_ATTRIBUTE_MAPPED_ADDRESS,
 300     STUN_ATTRIBUTE_RESPONSE_ADDRESS,
 301     STUN_ATTRIBUTE_CHANGE_REQUEST,
 302     STUN_ATTRIBUTE_SOURCE_ADDRESS,
 303     STUN_ATTRIBUTE_CHANGED_ADDRESS,
 304     STUN_ATTRIBUTE_USERNAME,
 305     STUN_ATTRIBUTE_PASSWORD,
 306     STUN_ATTRIBUTE_MESSAGE_INTEGRITY,
 307     STUN_ATTRIBUTE_ERROR_CODE,
 308     STUN_ATTRIBUTE_UNKNOWN_ATTRIBUTES,
 309     STUN_ATTRIBUTE_REFLECTED_FROM,
 310     STUN_ATTRIBUTE_CHANNEL_NUMBER,
 311     STUN_ATTRIBUTE_LIFETIME,
 312     STUN_ATTRIBUTE_MAGIC_COOKIE,
 313     STUN_ATTRIBUTE_BANDWIDTH,
 314     STUN_ATTRIBUTE_DESTINATION_ADDRESS,
 315     STUN_ATTRIBUTE_REMOTE_ADDRESS,
 316     STUN_ATTRIBUTE_PEER_ADDRESS,
 317     STUN_ATTRIBUTE_XOR_PEER_ADDRESS,
 318     STUN_ATTRIBUTE_DATA,
 319     STUN_ATTRIBUTE_REALM,
 320     STUN_ATTRIBUTE_NONCE,
 321     STUN_ATTRIBUTE_RELAY_ADDRESS,
 322     STUN_ATTRIBUTE_RELAYED_ADDRESS,
 323     STUN_ATTRIBUTE_XOR_RELAYED_ADDRESS,
 324     STUN_ATTRIBUTE_REQUESTED_ADDRESS_TYPE,
 325     STUN_ATTRIBUTE_REQUESTED_PORT_PROPS,
 326     STUN_ATTRIBUTE_REQUESTED_PROPS,
 327     STUN_ATTRIBUTE_EVEN_PORT,
 328     STUN_ATTRIBUTE_REQUESTED_TRANSPORT,
 329     STUN_ATTRIBUTE_DONT_FRAGMENT,
 330     STUN_ATTRIBUTE_XOR_MAPPED_ADDRESS,
 331     STUN_ATTRIBUTE_TIMER_VAL,
 332     STUN_ATTRIBUTE_REQUESTED_IP,
 333     STUN_ATTRIBUTE_RESERVATION_TOKEN,
 334     STUN_ATTRIBUTE_CONNECT_STAT,
 335     STUN_ATTRIBUTE_PRIORITY,
 336     STUN_ATTRIBUTE_USE_CANDIDATE,
 337     0
 338   };
 339
 340 /**
 341  * StunTransactionId:
 342  *
 343  * A type that holds a STUN transaction id.
 344  */
 345 typedef uint8_t StunTransactionId[STUN_MESSAGE_TRANS_ID_LEN];
 346
 347
 348 /**
 349  * StunError:
 350  * @STUN_ERROR_TRY_ALTERNATE: The ERROR-CODE value for the
 351  * "Try Alternate" error as defined in RFC5389
 352  * @STUN_ERROR_BAD_REQUEST: The ERROR-CODE value for the
 353  * "Bad Request" error as defined in RFC5389
 354  * @STUN_ERROR_UNAUTHORIZED: The ERROR-CODE value for the
 355  * "Unauthorized" error as defined in RFC5389
 356  * @STUN_ERROR_UNKNOWN_ATTRIBUTE: The ERROR-CODE value for the
 357  * "Unknown Attribute" error as defined in RFC5389
 358  * @STUN_ERROR_ALLOCATION_MISMATCH:The ERROR-CODE value for the
 359  * "Allocation Mismatch" error as defined in TURN draft 12.
 360  * Equivalent to the "No Binding" error defined in TURN draft 04.
 361  * @STUN_ERROR_STALE_NONCE: The ERROR-CODE value for the
 362  * "Stale Nonce" error as defined in RFC5389
 363  * @STUN_ERROR_ACT_DST_ALREADY: The ERROR-CODE value for the
 364  * "Active Destination Already Set" error as defined in TURN draft 04.
 365  * @STUN_ERROR_UNSUPPORTED_FAMILY: The ERROR-CODE value for the
 366  * "Address Family not Supported" error as defined in TURN IPV6 Draft 05.
 367  * @STUN_ERROR_WRONG_CREDENTIALS: The ERROR-CODE value for the
 368  * "Wrong Credentials" error as defined in TURN Draft 12.
 369  * @STUN_ERROR_UNSUPPORTED_TRANSPORT:he ERROR-CODE value for the
 370  * "Unsupported Transport Protocol" error as defined in TURN Draft 12.
 371  * @STUN_ERROR_INVALID_IP: The ERROR-CODE value for the
 372  * "Invalid IP Address" error as defined in TURN draft 04.
 373  * @STUN_ERROR_INVALID_PORT: The ERROR-CODE value for the
 374  * "Invalid Port" error as defined in TURN draft 04.
 375  * @STUN_ERROR_OP_TCP_ONLY: The ERROR-CODE value for the
 376  * "Operation for TCP Only" error as defined in TURN draft 04.
 377  * @STUN_ERROR_CONN_ALREADY: The ERROR-CODE value for the
 378  * "Connection Already Exists" error as defined in TURN draft 04.
 379  * @STUN_ERROR_ALLOCATION_QUOTA_REACHED: The ERROR-CODE value for the
 380  * "Allocation Quota Reached" error as defined in TURN draft 12.
 381  * @STUN_ERROR_ROLE_CONFLICT:The ERROR-CODE value for the
 382  * "Role Conflict" error as defined in ICE draft 19.
 383  * @STUN_ERROR_SERVER_ERROR: The ERROR-CODE value for the
 384  * "Server Error" error as defined in RFC5389
 385  * @STUN_ERROR_SERVER_CAPACITY: The ERROR-CODE value for the
 386  * "Insufficient Capacity" error as defined in TURN draft 04.
 387  * @STUN_ERROR_INSUFFICIENT_CAPACITY: The ERROR-CODE value for the
 388  * "Insufficient Capacity" error as defined in TURN draft 12.
 389  * @STUN_ERROR_MAX: The maximum possible ERROR-CODE value as defined by RFC 5389.
 390  *
 391  * STUN error codes as defined by various RFCs and drafts
 392  */
 393 /* Should be in sync with stun_strerror() */
 394 typedef enum
 395 {
 396   STUN_ERROR_TRY_ALTERNATE=300,      /* RFC5389 */
 397   STUN_ERROR_BAD_REQUEST=400,      /* RFC5389 */
 398   STUN_ERROR_UNAUTHORIZED=401,      /* RFC5389 */
 399   STUN_ERROR_UNKNOWN_ATTRIBUTE=420,    /* RFC5389 */
 400   STUN_ERROR_ALLOCATION_MISMATCH=437,   /* TURN-12 */
 401   STUN_ERROR_STALE_NONCE=438,      /* RFC5389 */
 402   STUN_ERROR_ACT_DST_ALREADY=439,    /* TURN-04 */
 403   STUN_ERROR_UNSUPPORTED_FAMILY=440,      /* TURN-IPv6-05 */
 404   STUN_ERROR_WRONG_CREDENTIALS=441,    /* TURN-12 */
 405   STUN_ERROR_UNSUPPORTED_TRANSPORT=442,    /* TURN-12 */
 406   STUN_ERROR_INVALID_IP=443,      /* TURN-04 */
 407   STUN_ERROR_INVALID_PORT=444,      /* TURN-04 */
 408   STUN_ERROR_OP_TCP_ONLY=445,      /* TURN-04 */
 409   STUN_ERROR_CONN_ALREADY=446,      /* TURN-04 */
 410   STUN_ERROR_ALLOCATION_QUOTA_REACHED=486,    /* TURN-12 */
 411   STUN_ERROR_ROLE_CONFLICT=487,      /* ICE-19 */
 412   STUN_ERROR_SERVER_ERROR=500,      /* RFC5389 */
 413   STUN_ERROR_SERVER_CAPACITY=507,    /* TURN-04 */
 414   STUN_ERROR_INSUFFICIENT_CAPACITY=508,    /* TURN-12 */
 415   STUN_ERROR_MAX=699
 416 } StunError;
 417
 418
 419 /**
 420  * StunMessageReturn:
 421  * @STUN_MESSAGE_RETURN_SUCCESS: The operation was successful
 422  * @STUN_MESSAGE_RETURN_NOT_FOUND: The attribute was not found
 423  * @STUN_MESSAGE_RETURN_INVALID: The argument or data is invalid
 424  * @STUN_MESSAGE_RETURN_NOT_ENOUGH_SPACE: There is not enough space in the
 425  * message to append data to it, or not enough in an argument to fill it with
 426  * the data requested.
 427  * @STUN_MESSAGE_RETURN_UNSUPPORTED_ADDRESS: The address in the arguments or in
 428  * the STUN message is not supported.
 429  *
 430  * The return value of most stun_message_* functions.
 431  * This enum will report on whether an operation was successful or not
 432  * and what error occured if any.
 433  */
 434 typedef enum
 435 {
 436   STUN_MESSAGE_RETURN_SUCCESS,
 437   STUN_MESSAGE_RETURN_NOT_FOUND,
 438   STUN_MESSAGE_RETURN_INVALID,
 439   STUN_MESSAGE_RETURN_NOT_ENOUGH_SPACE,
 440   STUN_MESSAGE_RETURN_UNSUPPORTED_ADDRESS
 441 } StunMessageReturn;
 442
 443 #include "stunagent.h"
 444
 445 /**
 446  * STUN_MAX_MESSAGE_SIZE:
 447  * The Maximum size of a STUN message
 448  */
 449 #define STUN_MAX_MESSAGE_SIZE 65552
 450
 451 /**
 452  * StunMessage:
 453  * @agent: The agent that created or validated this message
 454  * @buffer: The buffer containing the STUN message
 455  * @buffer_len: The length of the buffer (not the size of the message)
 456  * @key: The short term credentials key to use for authentication validation
 457  * or that was used to finalize this message
 458  * @key_len: The length of the associated key
 459  * @long_term_key: The long term credential key to use for authentication
 460  * validation or that was used to finalize this message
 461  * @long_term_valid: Whether or not the #long_term_key variable contains valid
 462  * data
 463  *
 464  * This structure represents a STUN message
 465  */
 466 struct _StunMessage {
 467   StunAgent *agent;
 468   uint8_t *buffer;
 469   size_t buffer_len;
 470   uint8_t *key;
 471   size_t key_len;
 472   uint8_t long_term_key[16];
 473   bool long_term_valid;
 474 };
 475
 476 /**
 477  * stun_message_init:
 478  * @msg: The #StunMessage to initialize
 479  * @c: STUN message class (host byte order)
 480  * @m: STUN message method (host byte order)
 481  * @id: 16-bytes transaction ID
 482  *
 483  * Initializes a STUN message buffer, with no attributes.
 484  * Returns: %TRUE if the initialization was successful
 485  */
 486 bool stun_message_init (StunMessage *msg, StunClass c, StunMethod m,
 487     const StunTransactionId id);
 488
 489 /**
 490  * stun_message_length:
 491  * @msg: The #StunMessage
 492  *
 493  * Get the length of the message (including the header)
 494  *
 495  * Returns: The length of the message
 496  */
 497 uint16_t stun_message_length (const StunMessage *msg);
 498
 499 /**
 500  * stun_message_find:
 501  * @msg: The #StunMessage
 502  * @type: The #StunAttribute to find
 503  * @palen: A pointer to store the length of the attribute
 504  *
 505  * Finds an attribute in a STUN message and fetches its content
 506  *
 507  * Returns: A pointer to the start of the attribute payload if found,
 508  * otherwise NULL.
 509  */
 510 const void * stun_message_find (const StunMessage * msg, StunAttribute type,
 511     uint16_t *palen);
 512
 513
 514 /**
 515  * stun_message_find_flag:
 516  * @msg: The #StunMessage
 517  * @type: The #StunAttribute to find
 518  *
 519  * Looks for a flag attribute within a valid STUN message.
 520  *
 521  * Returns: A #StunMessageReturn value.
 522  * %STUN_MESSAGE_RETURN_INVALID is returned if the attribute's size is not zero.
 523  */
 524 StunMessageReturn stun_message_find_flag (const StunMessage *msg,
 525     StunAttribute type);
 526
 527 /**
 528  * stun_message_find32:
 529  * @msg: The #StunMessage
 530  * @type: The #StunAttribute to find
 531  * @pval: A pointer where to store the value (host byte order)
 532  *
 533  * Extracts a 32-bits attribute from a STUN message.
 534  *
 535  * Returns:  A #StunMessageReturn value.
 536  * %STUN_MESSAGE_RETURN_INVALID is returned if the attribute's size is not
 537  * 4 bytes.
 538  */
 539 StunMessageReturn stun_message_find32 (const StunMessage *msg,
 540     StunAttribute type, uint32_t *pval);
 541
 542 /**
 543  * stun_message_find64:
 544  * @msg: The #StunMessage
 545  * @type: The #StunAttribute to find
 546  * @pval: A pointer where to store the value (host byte order)
 547  *
 548  * Extracts a 64-bits attribute from a STUN message.
 549  *
 550  * Returns:  A #StunMessageReturn value.
 551  * %STUN_MESSAGE_RETURN_INVALID is returned if the attribute's size is not
 552  * 8 bytes.
 553  */
 554 StunMessageReturn stun_message_find64 (const StunMessage *msg,
 555     StunAttribute type, uint64_t *pval);
 556
 557 /**
 558  * stun_message_find_string:
 559  * @msg: The #StunMessage
 560  * @type: The #StunAttribute to find
 561  * @buf: A pointer where to store the data
 562  * @buflen: The length of the buffer
 563  *
 564  * Extracts an UTF-8 string from a valid STUN message.
 565  *
 566  * Returns: A #StunMessageReturn value.
 567  * %STUN_MESSAGE_RETURN_INVALID is returned if the attribute is improperly
 568  * encoded
 569  * %STUN_MESSAGE_RETURN_NOT_ENOUGH_SPACE is return if the buffer size is too
 570  * small to hold the string
 571  *
 572  <note>
 573    <para>
 574     The string will be NULL-terminated.
 575    </para>
 576  </note>
 577  *
 578  */
 579 StunMessageReturn stun_message_find_string (const StunMessage *msg,
 580     StunAttribute type, char *buf, size_t buflen);
 581
 582 /**
 583  * stun_message_find_addr:
 584  * @msg: The #StunMessage
 585  * @type: The #StunAttribute to find
 586  * @addr: The #sockaddr to be filled
 587  * @addrlen: The size of the @addr variable. Will be set to the size of the
 588  * extracted socket address.
 589  *
 590  * Extracts a network address attribute from a STUN message.
 591  *
 592  * Returns: A #StunMessageReturn value.
 593  * %STUN_MESSAGE_RETURN_INVALID is returned if the attribute payload size is
 594  * wrong or if the @addrlen is too small
 595  * %STUN_MESSAGE_RETURN_UNSUPPORTED_ADDRESSS if the address family is unknown.
 596  */
 597 StunMessageReturn stun_message_find_addr (const StunMessage *msg,
 598     StunAttribute type, struct sockaddr *addr, socklen_t *addrlen);
 599
 600 /**
 601  * stun_message_find_xor_addr:
 602  * @msg: The #StunMessage
 603  * @type: The #StunAttribute to find
 604  * @addr: The #sockaddr to be filled
 605  * @addrlen: The size of the @addr variable. Will be set to the size of the
 606  * extracted socket address.
 607  *
 608  * Extracts an obfuscated network address attribute from a STUN message.
 609  *
 610  * Returns: A #StunMessageReturn value.
 611  * %STUN_MESSAGE_RETURN_INVALID is returned if the attribute payload size is
 612  * wrong or if the @addrlen is too small
 613  * %STUN_MESSAGE_RETURN_UNSUPPORTED_ADDRESSS if the address family is unknown.
 614  */
 615 StunMessageReturn stun_message_find_xor_addr (const StunMessage *msg,
 616     StunAttribute type, struct sockaddr *addr, socklen_t *addrlen);
 617
 618 /**
 619  * stun_message_find_xor_addr_full:
 620  * @msg: The #StunMessage
 621  * @type: The #StunAttribute to find
 622  * @addr: The #sockaddr to be filled
 623  * @addrlen: The size of the @addr variable. Will be set to the size of the
 624  * extracted socket address.
 625  * @magic_cookie: The magic cookie to use to XOR the address.
 626  *
 627  * Extracts an obfuscated network address attribute from a STUN message.
 628  *
 629  * Returns: A #StunMessageReturn value.
 630  * %STUN_MESSAGE_RETURN_INVALID is returned if the attribute payload size is
 631  * wrong or if the @addrlen is too small
 632  * %STUN_MESSAGE_RETURN_UNSUPPORTED_ADDRESSS if the address family is unknown.
 633  */
 634 StunMessageReturn stun_message_find_xor_addr_full (const StunMessage *msg,
 635     StunAttribute type, struct sockaddr *addr,
 636     socklen_t *addrlen, uint32_t magic_cookie);
 637
 638
 639 /**
 640  * stun_message_find_error:
 641  * @msg: The #StunMessage
 642  * @code: A  pointer where to store the value
 643  *
 644  * Extract the error response code from a STUN message
 645  *
 646  * Returns: A #StunMessageReturn value.
 647  * %STUN_MESSAGE_RETURN_INVALID is returned if the value is invalid
 648  */
 649 StunMessageReturn stun_message_find_error (const StunMessage *msg, int *code);
 650
 651
 652 /**
 653  * stun_message_append:
 654  * @msg: The #StunMessage
 655  * @type: The #StunAttribute to append
 656  * @length: The length of the attribute
 657  *
 658  * Reserves room for appending an attribute to an unfinished STUN message.
 659  *
 660  * Returns: A pointer to an unitialized buffer of @length bytes to
 661  * where the attribute payload must be written, or NULL if there is not
 662  * enough room in the STUN message buffer.
 663  */
 664 void *stun_message_append (StunMessage *msg, StunAttribute type,
 665     size_t length);
 666
 667 /**
 668  * stun_message_append_bytes:
 669  * @msg: The #StunMessage
 670  * @type: The #StunAttribute to append
 671  * @data: The data to append
 672  * @len: The length of the attribute
 673  *
 674  * Appends a binary value to a STUN message
 675  *
 676  * Returns: A #StunMessageReturn value.
 677  */
 678 StunMessageReturn stun_message_append_bytes (StunMessage *msg,
 679     StunAttribute type, const void *data, size_t len);
 680
 681 /**
 682  * stun_message_append_flag:
 683  * @msg: The #StunMessage
 684  * @type: The #StunAttribute to append
 685  *
 686  * Appends an empty flag attribute to a STUN message
 687  *
 688  * Returns: A #StunMessageReturn value.
 689  */
 690 StunMessageReturn stun_message_append_flag (StunMessage *msg,
 691     StunAttribute type);
 692
 693 /**
 694  * stun_message_append32:
 695  * @msg: The #StunMessage
 696  * @type: The #StunAttribute to append
 697  * @value: The value to append (host byte order)
 698  *
 699  * Appends a 32-bits value attribute to a STUN message
 700  *
 701  * Returns: A #StunMessageReturn value.
 702  */
 703 StunMessageReturn stun_message_append32 (StunMessage *msg,
 704     StunAttribute type, uint32_t value);
 705
 706 /**
 707  * stun_message_append64:
 708  * @msg: The #StunMessage
 709  * @type: The #StunAttribute to append
 710  * @value: The value to append (host byte order)
 711  *
 712  * Appends a 64-bits value attribute to a STUN message
 713  *
 714  * Returns: A #StunMessageReturn value.
 715  */
 716 StunMessageReturn stun_message_append64 (StunMessage *msg,
 717     StunAttribute type, uint64_t value);
 718
 719 /**
 720  * stun_message_append_string:
 721  * @msg: The #StunMessage
 722  * @type: The #StunAttribute to append
 723  * @str: The string to append
 724  *
 725  * Adds an attribute from a NULL-terminated string to a STUN message
 726  *
 727  * Returns: A #StunMessageReturn value.
 728  */
 729 StunMessageReturn stun_message_append_string (StunMessage *msg,
 730     StunAttribute type, const char *str);
 731
 732 /**
 733  * stun_message_append_addr:
 734  * @msg: The #StunMessage
 735  * @type: The #StunAttribute to append
 736  * @addr: The #sockaddr to be append
 737  * @addrlen: The size of the @addr variable.
 738  *
 739  * Append a network address attribute to a STUN message
 740  *
 741  * Returns: A #StunMessageReturn value.
 742  * %STUN_MESSAGE_RETURN_INVALID is returned if the @addrlen is too small
 743  * %STUN_MESSAGE_RETURN_UNSUPPORTED_ADDRESSS if the address family is unknown.
 744  */
 745 StunMessageReturn stun_message_append_addr (StunMessage * msg,
 746     StunAttribute type, const struct sockaddr *addr, socklen_t addrlen);
 747
 748 /**
 749  * stun_message_append_xor_addr:
 750  * @msg: The #StunMessage
 751  * @type: The #StunAttribute to append
 752  * @addr: The #sockaddr to be append
 753  * @addrlen: The size of the @addr variable.
 754  *
 755  * Append an obfuscated network address attribute to a STUN message
 756  *
 757  * Returns: A #StunMessageReturn value.
 758  * %STUN_MESSAGE_RETURN_INVALID is returned if the @addrlen is too small
 759  * %STUN_MESSAGE_RETURN_UNSUPPORTED_ADDRESSS if the address family is unknown.
 760  */
 761 StunMessageReturn stun_message_append_xor_addr (StunMessage * msg,
 762     StunAttribute type, const struct sockaddr *addr, socklen_t addrlen);
 763
 764 /**
 765  * stun_message_append_xor_addr_full:
 766  * @msg: The #StunMessage
 767  * @type: The #StunAttribute to append
 768  * @addr: The #sockaddr to be append
 769  * @addrlen: The size of the @addr variable.
 770  * @magic_cookie: The magic cookie to use to XOR the address.
 771  *
 772  * Append an obfuscated network address attribute from a STUN message.
 773  *
 774  * Returns: A #StunMessageReturn value.
 775  * %STUN_MESSAGE_RETURN_INVALID is returned if the @addrlen is too small
 776  * %STUN_MESSAGE_RETURN_UNSUPPORTED_ADDRESSS if the address family is unknown.
 777  */
 778 StunMessageReturn stun_message_append_xor_addr_full (StunMessage * msg,
 779     StunAttribute type, const struct sockaddr *addr, socklen_t addrlen,
 780     uint32_t magic_cookie);
 781
 782 /**
 783  * stun_message_append_error:
 784  * @msg: The #StunMessage
 785  * @code: The error code value
 786  *
 787  * Appends the ERROR-CODE attribute to the STUN message and fills it according
 788  * to #code
 789  *
 790  * Returns: A #StunMessageReturn value.
 791  */
 792 StunMessageReturn stun_message_append_error (StunMessage * msg,
 793     StunError code);
 794
 795 /**
 796  * STUN_MESSAGE_BUFFER_INCOMPLETE:
 797  *
 798  * Convenience macro for stun_message_validate_buffer_length() meaning that the
 799  * data to validate does not hold a complete STUN message
 800  */
 801 #define STUN_MESSAGE_BUFFER_INCOMPLETE 0
 802
 803 /**
 804  * STUN_MESSAGE_BUFFER_INVALID:
 805  *
 806  * Convenience macro for stun_message_validate_buffer_length() meaning that the
 807  * data to validate is not a valid STUN message
 808  */
 809 #define STUN_MESSAGE_BUFFER_INVALID -1
 810
 811
 812 /**
 813  * stun_message_validate_buffer_length:
 814  * @msg: The buffer to validate
 815  * @length: The length of the buffer
 816  *
 817  * This function will take a data buffer and will try to validate whether it is
 818  * a STUN message or if it's not or if it's an incomplete STUN message and will
 819  * provide us with the length of the STUN message.
 820  *
 821  * Returns: The length of the valid STUN message in the buffer.
 822  * <para> See also: #STUN_MESSAGE_BUFFER_INCOMPLETE </para>
 823  * <para> See also: #STUN_MESSAGE_BUFFER_INVALID </para>
 824  */
 825 int stun_message_validate_buffer_length (const uint8_t *msg, size_t length);
 826
 827 /**
 828  * stun_message_id:
 829  * @msg: The #StunMessage
 830  * @id: The #StunTransactionId to fill
 831  *
 832  * Retreive the STUN transaction id from a STUN message
 833  */
 834 void stun_message_id (const StunMessage *msg, StunTransactionId id);
 835
 836 /**
 837  * stun_message_get_class:
 838  * @msg: The #StunMessage
 839  *
 840  * Retreive the STUN class from a STUN message
 841  *
 842  * Returns: The #StunClass
 843  */
 844 StunClass stun_message_get_class (const StunMessage *msg);
 845
 846 /**
 847  * stun_message_get_method:
 848  * @msg: The #StunMessage
 849  *
 850  * Retreive the STUN method from a STUN message
 851  *
 852  * Returns: The #StunMethod
 853  */
 854 StunMethod stun_message_get_method (const StunMessage *msg);
 855
 856 /**
 857  * stun_message_has_attribute:
 858  * @msg: The #StunMessage
 859  * @type: The #StunAttribute to look for
 860  *
 861  * Checks if an attribute is present within a STUN message.
 862  *
 863  * Returns: %TRUE if the attribute is found, %FALSE otherwise
 864  */
 865 bool stun_message_has_attribute (const StunMessage *msg, StunAttribute type);
 866
 867
 868 /* Defined in stun5389.c */
 869 /**
 870  * stun_message_has_cookie:
 871  * @msg: The #StunMessage
 872  *
 873  * Checks if the STUN message has a RFC5389 compatible cookie
 874  *
 875  * Returns: %TRUE if the cookie is present, %FALSE otherwise
 876  */
 877 bool stun_message_has_cookie (const StunMessage *msg);
 878
 879
 880 /**
 881  * stun_optional:
 882  * @t: An attribute type
 883  *
 884  * Helper function that checks whether a STUN attribute is a mandatory
 885  * or an optional attribute
 886  *
 887  * Returns: %TRUE if the attribute is an optional one
 888  */
 889 bool stun_optional (uint16_t t);
 890
 891 /**
 892  * stun_strerror:
 893  * @code: host-byte order error code
 894  *
 895  * Transforms a STUN error-code into a human readable string
 896  *
 897  * Returns: A static pointer to a NULL-terminated error message string.
 898  */
 899 const char *stun_strerror (StunError code);
 900
 901
 902 #endif /* _STUN_MESSAGE_H */