1 /* $Id$ */ 2 /* 3 * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com) 4 * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org> 5 * 6 * This program is free software; you can redistribute it and/or modify 7 * it under the terms of the GNU General Public License as published by 8 * the Free Software Foundation; either version 2 of the License, or 9 * (at your option) any later version. 10 * 11 * This program is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14 * GNU General Public License for more details. 15 * 16 * You should have received a copy of the GNU General Public License 17 * along with this program; if not, write to the Free Software 18 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 19 */ 20 #ifndef __PJNATH_STUN_MSG_H__ 21 #define __PJNATH_STUN_MSG_H__ 22 23 /** 24 * @file stun_msg.h 25 * @brief STUN message components. 26 */ 27 28 #include <pjnath/types.h> 29 #include <pj/sock.h> 30 31 32 PJ_BEGIN_DECL 33 34 35 /* **************************************************************************/ 36 /** 37 * @defgroup PJNATH_STUN_MSG STUN Message Representation and Parsing 38 * @ingroup PJNATH_STUN_BASE 39 * @brief Low-level representation and parsing of STUN messages. 40 * @{ 41 */ 42 43 44 /** 45 * STUN magic cookie. 46 */ 47 #define PJ_STUN_MAGIC 0x2112A442 48 49 50 /** 51 * STUN method constants. 52 */ 53 enum pj_stun_method_e 54 { 55 /** 56 * STUN Binding method as defined by RFC 3489-bis. 57 */ 58 PJ_STUN_BINDING_METHOD = 1, 59 60 /** 61 * STUN Shared Secret method as defined by RFC 3489-bis. 62 */ 63 PJ_STUN_SHARED_SECRET_METHOD = 2, 64 65 /** 66 * STUN/TURN Allocate method as defined by draft-ietf-behave-turn 67 */ 68 PJ_STUN_ALLOCATE_METHOD = 3, 69 70 /** 71 * STUN/TURN Refresh method as defined by draft-ietf-behave-turn 72 */ 73 PJ_STUN_REFRESH_METHOD = 4, 74 75 /** 76 * STUN/TURN Send indication as defined by draft-ietf-behave-turn 77 */ 78 PJ_STUN_SEND_METHOD = 6, 79 80 /** 81 * STUN/TURN Data indication as defined by draft-ietf-behave-turn 82 */ 83 PJ_STUN_DATA_METHOD = 7, 84 85 /** 86 * STUN/TURN CreatePermission method as defined by draft-ietf-behave-turn 87 */ 88 PJ_STUN_CREATE_PERM_METHOD = 8, 89 90 /** 91 * STUN/TURN ChannelBind as defined by draft-ietf-behave-turn 92 */ 93 PJ_STUN_CHANNEL_BIND_METHOD = 9, 94 95 /** 96 * STUN/TURN Connect as defined by RFC 6062 97 */ 98 PJ_STUN_CONNECT_METHOD = 10, 99 100 /** 101 * STUN/TURN ConnectionBind as defined by RFC 6062 102 */ 103 PJ_STUN_CONNECTION_BIND_METHOD = 11, 104 105 /** 106 * STUN/TURN ConnectionAttempt as defined by RFC 6062 107 */ 108 PJ_STUN_CONNECTION_ATTEMPT_METHOD = 12, 109 110 /** 111 * All known methods. 112 */ 113 PJ_STUN_METHOD_MAX 114 }; 115 116 117 /** 118 * Retrieve the STUN method from the message-type field of the STUN 119 * message. 120 */ 121 #define PJ_STUN_GET_METHOD(msg_type) ((msg_type) & 0xFEEF) 122 123 124 /** 125 * STUN message classes constants. 126 */ 127 enum pj_stun_msg_class_e 128 { 129 /** 130 * This specifies that the message type is a STUN request message. 131 */ 132 PJ_STUN_REQUEST_CLASS = 0, 133 134 /** 135 * This specifies that the message type is a STUN indication message. 136 */ 137 PJ_STUN_INDICATION_CLASS = 1, 138 139 /** 140 * This specifies that the message type is a STUN successful response. 141 */ 142 PJ_STUN_SUCCESS_CLASS = 2, 143 144 /** 145 * This specifies that the message type is a STUN error response. 146 */ 147 PJ_STUN_ERROR_CLASS = 3 148 }; 149 150 151 /** 152 * Determine if the message type is a request. 153 */ 154 #define PJ_STUN_IS_REQUEST(msg_type) (((msg_type) & 0x0110) == 0x0000) 155 156 157 /** 158 * Determine if the message type is a successful response. 159 */ 160 #define PJ_STUN_IS_SUCCESS_RESPONSE(msg_type) (((msg_type) & 0x0110) == 0x0100) 161 162 /** 163 * The response bit in the message type. 164 */ 165 #define PJ_STUN_SUCCESS_RESPONSE_BIT (0x0100) 166 167 168 /** 169 * Determine if the message type is an error response. 170 */ 171 #define PJ_STUN_IS_ERROR_RESPONSE(msg_type) (((msg_type) & 0x0110) == 0x0110) 172 173 /** 174 * The error response bit in the message type. 175 */ 176 #define PJ_STUN_ERROR_RESPONSE_BIT (0x0110) 177 178 /** 179 * Determine if the message type is a response. 180 */ 181 #define PJ_STUN_IS_RESPONSE(msg_type) (((msg_type) & 0x0100) == 0x0100) 182 183 184 /** 185 * Determine if the message type is an indication message. 186 */ 187 #define PJ_STUN_IS_INDICATION(msg_type) (((msg_type) & 0x0110) == 0x0010) 188 189 /** 190 * The error response bit in the message type. 191 */ 192 #define PJ_STUN_INDICATION_BIT (0x0010) 193 194 195 /** 196 * This enumeration describes STUN message types. 197 */ 198 typedef enum pj_stun_msg_type 199 { 200 /** 201 * STUN BINDING request. 202 */ 203 PJ_STUN_BINDING_REQUEST = 0x0001, 204 205 /** 206 * Successful response to STUN BINDING-REQUEST. 207 */ 208 PJ_STUN_BINDING_RESPONSE = 0x0101, 209 210 /** 211 * Error response to STUN BINDING-REQUEST. 212 */ 213 PJ_STUN_BINDING_ERROR_RESPONSE = 0x0111, 214 215 /** 216 * Binding Indication (ICE) 217 */ 218 PJ_STUN_BINDING_INDICATION = 0x0011, 219 220 /** 221 * STUN SHARED-SECRET reqeust. 222 */ 223 PJ_STUN_SHARED_SECRET_REQUEST = 0x0002, 224 225 /** 226 * Successful response to STUN SHARED-SECRET reqeust. 227 */ 228 PJ_STUN_SHARED_SECRET_RESPONSE = 0x0102, 229 230 /** 231 * Error response to STUN SHARED-SECRET reqeust. 232 */ 233 PJ_STUN_SHARED_SECRET_ERROR_RESPONSE = 0x0112, 234 235 236 /** 237 * STUN/TURN Allocate Request 238 */ 239 PJ_STUN_ALLOCATE_REQUEST = 0x0003, 240 241 /** 242 * Successful response to STUN/TURN Allocate Request 243 */ 244 PJ_STUN_ALLOCATE_RESPONSE = 0x0103, 245 246 /** 247 * Failure response to STUN/TURN Allocate Request 248 */ 249 PJ_STUN_ALLOCATE_ERROR_RESPONSE = 0x0113, 250 251 252 /** 253 * STUN/TURN REFRESH Request 254 */ 255 PJ_STUN_REFRESH_REQUEST = 0x0004, 256 257 /** 258 * Successful response to STUN REFRESH request 259 */ 260 PJ_STUN_REFRESH_RESPONSE = 0x0104, 261 262 /** 263 * Error response to STUN REFRESH request. 264 */ 265 PJ_STUN_REFRESH_ERROR_RESPONSE = 0x0114, 266 267 268 /** 269 * TURN Send indication 270 */ 271 PJ_STUN_SEND_INDICATION = 0x0016, 272 273 274 /** 275 * TURN Data indication 276 */ 277 PJ_STUN_DATA_INDICATION = 0x0017, 278 279 280 /** 281 * TURN CreatePermission request 282 */ 283 PJ_STUN_CREATE_PERM_REQUEST = 0x0008, 284 285 /** 286 * TURN CreatePermission successful response. 287 */ 288 PJ_STUN_CREATE_PERM_RESPONSE = 0x0108, 289 290 /** 291 * TURN CreatePermission failure response 292 */ 293 PJ_STUN_CREATE_PERM_ERROR_RESPONSE = 0x0118, 294 295 296 /** 297 * STUN/TURN ChannelBind Request 298 */ 299 PJ_STUN_CHANNEL_BIND_REQUEST = 0x0009, 300 301 /** 302 * Successful response to STUN ChannelBind request 303 */ 304 PJ_STUN_CHANNEL_BIND_RESPONSE = 0x0109, 305 306 /** 307 * Error response to STUN ChannelBind request. 308 */ 309 PJ_STUN_CHANNEL_BIND_ERROR_RESPONSE = 0x0119, 310 311 312 /** 313 * STUN/TURN ConnectBind Request 314 */ 315 PJ_STUN_CONNECTION_BIND_REQUEST = 0x000b, 316 317 /** 318 * TURN ConnectionAttempt indication 319 */ 320 PJ_STUN_CONNECTION_ATTEMPT_INDICATION = 0x001c, 321 322 } pj_stun_msg_type; 323 324 325 326 /** 327 * This enumeration describes STUN attribute types. 328 */ 329 typedef enum pj_stun_attr_type 330 { 331 PJ_STUN_ATTR_MAPPED_ADDR = 0x0001,/**< MAPPED-ADDRESS. */ 332 PJ_STUN_ATTR_RESPONSE_ADDR = 0x0002,/**< RESPONSE-ADDRESS (deprcatd)*/ 333 PJ_STUN_ATTR_CHANGE_REQUEST = 0x0003,/**< CHANGE-REQUEST (deprecated)*/ 334 PJ_STUN_ATTR_SOURCE_ADDR = 0x0004,/**< SOURCE-ADDRESS (deprecated)*/ 335 PJ_STUN_ATTR_CHANGED_ADDR = 0x0005,/**< CHANGED-ADDRESS (deprecatd)*/ 336 PJ_STUN_ATTR_USERNAME = 0x0006,/**< USERNAME attribute. */ 337 PJ_STUN_ATTR_PASSWORD = 0x0007,/**< was PASSWORD attribute. */ 338 PJ_STUN_ATTR_MESSAGE_INTEGRITY = 0x0008,/**< MESSAGE-INTEGRITY. */ 339 PJ_STUN_ATTR_ERROR_CODE = 0x0009,/**< ERROR-CODE. */ 340 PJ_STUN_ATTR_UNKNOWN_ATTRIBUTES = 0x000A,/**< UNKNOWN-ATTRIBUTES. */ 341 PJ_STUN_ATTR_REFLECTED_FROM = 0x000B,/**< REFLECTED-FROM (deprecatd)*/ 342 PJ_STUN_ATTR_CHANNEL_NUMBER = 0x000C,/**< TURN CHANNEL-NUMBER */ 343 PJ_STUN_ATTR_LIFETIME = 0x000D,/**< TURN LIFETIME attr. */ 344 PJ_STUN_ATTR_MAGIC_COOKIE = 0x000F,/**< MAGIC-COOKIE attr (deprec)*/ 345 PJ_STUN_ATTR_BANDWIDTH = 0x0010,/**< TURN BANDWIDTH (deprec) */ 346 PJ_STUN_ATTR_XOR_PEER_ADDR = 0x0012,/**< TURN XOR-PEER-ADDRESS */ 347 PJ_STUN_ATTR_DATA = 0x0013,/**< DATA attribute. */ 348 PJ_STUN_ATTR_REALM = 0x0014,/**< REALM attribute. */ 349 PJ_STUN_ATTR_NONCE = 0x0015,/**< NONCE attribute. */ 350 PJ_STUN_ATTR_XOR_RELAYED_ADDR = 0x0016,/**< TURN XOR-RELAYED-ADDRESS */ 351 PJ_STUN_ATTR_REQ_ADDR_TYPE = 0x0017,/**< REQUESTED-ADDRESS-TYPE */ 352 PJ_STUN_ATTR_REQ_ADDR_FAMILY = 0x0017,/**< REQUESTED-ADDRESS-FAMILY */ 353 PJ_STUN_ATTR_EVEN_PORT = 0x0018,/**< TURN EVEN-PORT */ 354 PJ_STUN_ATTR_REQ_TRANSPORT = 0x0019,/**< TURN REQUESTED-TRANSPORT */ 355 PJ_STUN_ATTR_DONT_FRAGMENT = 0x001A,/**< TURN DONT-FRAGMENT */ 356 PJ_STUN_ATTR_XOR_MAPPED_ADDR = 0x0020,/**< XOR-MAPPED-ADDRESS */ 357 PJ_STUN_ATTR_TIMER_VAL = 0x0021,/**< TIMER-VAL attribute. */ 358 PJ_STUN_ATTR_RESERVATION_TOKEN = 0x0022,/**< TURN RESERVATION-TOKEN */ 359 PJ_STUN_ATTR_XOR_REFLECTED_FROM = 0x0023,/**< XOR-REFLECTED-FROM */ 360 PJ_STUN_ATTR_PRIORITY = 0x0024,/**< PRIORITY */ 361 PJ_STUN_ATTR_USE_CANDIDATE = 0x0025,/**< USE-CANDIDATE */ 362 PJ_STUN_ATTR_CONNECTION_ID = 0x002a,/**< CONNECTION-ID */ 363 PJ_STUN_ATTR_ICMP = 0x0030,/**< ICMP (TURN) */ 364 365 PJ_STUN_ATTR_END_MANDATORY_ATTR, 366 367 PJ_STUN_ATTR_START_EXTENDED_ATTR= 0x8021, 368 369 PJ_STUN_ATTR_SOFTWARE = 0x8022,/**< SOFTWARE attribute. */ 370 PJ_STUN_ATTR_ALTERNATE_SERVER = 0x8023,/**< ALTERNATE-SERVER. */ 371 PJ_STUN_ATTR_REFRESH_INTERVAL = 0x8024,/**< REFRESH-INTERVAL. */ 372 PJ_STUN_ATTR_FINGERPRINT = 0x8028,/**< FINGERPRINT attribute. */ 373 PJ_STUN_ATTR_ICE_CONTROLLED = 0x8029,/**< ICE-CCONTROLLED attribute.*/ 374 PJ_STUN_ATTR_ICE_CONTROLLING = 0x802a,/**< ICE-CCONTROLLING attribute*/ 375 376 PJ_STUN_ATTR_END_EXTENDED_ATTR 377 378 } pj_stun_attr_type; 379 380 381 /** 382 * STUN error codes, which goes into STUN ERROR-CODE attribute. 383 */ 384 typedef enum pj_stun_status 385 { 386 PJ_STUN_SC_TRY_ALTERNATE = 300, /**< Try Alternate */ 387 PJ_STUN_SC_BAD_REQUEST = 400, /**< Bad Request */ 388 PJ_STUN_SC_UNAUTHORIZED = 401, /**< Unauthorized */ 389 PJ_STUN_SC_FORBIDDEN = 403, /**< Forbidden (TURN) */ 390 PJ_STUN_SC_UNKNOWN_ATTRIBUTE = 420, /**< Unknown Attribute */ 391 #if 0 392 /* These were obsolete in recent rfc3489bis */ 393 //PJ_STUN_SC_STALE_CREDENTIALS = 430, /**< Stale Credentials */ 394 //PJ_STUN_SC_INTEGRITY_CHECK_FAILURE= 431, /**< Integrity Chk Fail */ 395 //PJ_STUN_SC_MISSING_USERNAME = 432, /**< Missing Username */ 396 //PJ_STUN_SC_USE_TLS = 433, /**< Use TLS */ 397 //PJ_STUN_SC_MISSING_REALM = 434, /**< Missing Realm */ 398 //PJ_STUN_SC_MISSING_NONCE = 435, /**< Missing Nonce */ 399 //PJ_STUN_SC_UNKNOWN_USERNAME = 436, /**< Unknown Username */ 400 #endif 401 PJ_STUN_SC_ALLOCATION_MISMATCH = 437, /**< TURN Alloc Mismatch */ 402 PJ_STUN_SC_STALE_NONCE = 438, /**< Stale Nonce */ 403 PJ_STUN_SC_TRANSITIONING = 439, /**< Transitioning. */ 404 PJ_STUN_SC_WRONG_CREDENTIALS = 441, /**< TURN Wrong Credentials */ 405 PJ_STUN_SC_UNSUPP_TRANSPORT_PROTO = 442, /**< Unsupported Transport or 406 Protocol (TURN) */ 407 PJ_STUN_SC_OPER_TCP_ONLY = 445, /**< Operation for TCP Only */ 408 PJ_STUN_SC_CONNECTION_FAILURE = 446, /**< Connection Failure */ 409 PJ_STUN_SC_CONNECTION_TIMEOUT = 447, /**< Connection Timeout */ 410 PJ_STUN_SC_ALLOCATION_QUOTA_REACHED = 486, /**< Allocation Quota Reached 411 (TURN) */ 412 PJ_STUN_SC_ROLE_CONFLICT = 487, /**< Role Conflict */ 413 PJ_STUN_SC_SERVER_ERROR = 500, /**< Server Error */ 414 PJ_STUN_SC_INSUFFICIENT_CAPACITY = 508, /**< Insufficient Capacity 415 (TURN) */ 416 PJ_STUN_SC_GLOBAL_FAILURE = 600 /**< Global Failure */ 417 } pj_stun_status; 418 419 420 /** 421 * This structure describes STUN message header. A STUN message has the 422 * following format: 423 * 424 * \verbatim 425 426 0 1 2 3 427 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 428 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 429 |0 0| STUN Message Type | Message Length | 430 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 431 | Magic Cookie | 432 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 433 | 434 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 435 Transaction ID 436 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 437 | 438 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 439 440 \endverbatim 441 */ 442 typedef struct pj_stun_msg_hdr 443 { 444 /** 445 * STUN message type, which the first two bits must be zeroes. 446 */ 447 pj_uint16_t type; 448 449 /** 450 * The message length is the size, in bytes, of the message not 451 * including the 20 byte STUN header. 452 */ 453 pj_uint16_t length; 454 455 /** 456 * The magic cookie is a fixed value, 0x2112A442 (PJ_STUN_MAGIC constant). 457 * In the previous version of this specification [15] this field was part 458 * of the transaction ID. 459 */ 460 pj_uint32_t magic; 461 462 /** 463 * The transaction ID is a 96 bit identifier. STUN transactions are 464 * identified by their unique 96-bit transaction ID. For request/ 465 * response transactions, the transaction ID is chosen by the STUN 466 * client and MUST be unique for each new STUN transaction generated by 467 * that STUN client. The transaction ID MUST be uniformly and randomly 468 * distributed between 0 and 2**96 - 1. 469 */ 470 pj_uint8_t tsx_id[12]; 471 472 } pj_stun_msg_hdr; 473 474 475 /** 476 * This structre describes STUN attribute header. Each attribute is 477 * TLV encoded, with a 16 bit type, 16 bit length, and variable value. 478 * Each STUN attribute ends on a 32 bit boundary: 479 * 480 * \verbatim 481 482 0 1 2 3 483 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 484 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 485 | Type | Length | 486 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 487 488 \endverbatim 489 */ 490 typedef struct pj_stun_attr_hdr 491 { 492 /** 493 * STUN attribute type. 494 */ 495 pj_uint16_t type; 496 497 /** 498 * The Length refers to the length of the actual useful content of the 499 * Value portion of the attribute, measured in bytes. The value 500 * in the Length field refers to the length of the Value part of the 501 * attribute prior to padding - i.e., the useful content. 502 */ 503 pj_uint16_t length; 504 505 } pj_stun_attr_hdr; 506 507 508 /** 509 * This structure describes STUN generic IP address attribute, used for 510 * example to represent STUN MAPPED-ADDRESS attribute. 511 * 512 * The generic IP address attribute indicates the transport address. 513 * It consists of an eight bit address family, and a sixteen bit port, 514 * followed by a fixed length value representing the IP address. If the 515 * address family is IPv4, the address is 32 bits, in network byte 516 * order. If the address family is IPv6, the address is 128 bits in 517 * network byte order. 518 * 519 * The format of the generic IP address attribute is: 520 * 521 * \verbatim 522 523 0 1 2 3 524 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 525 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 526 |x x x x x x x x| Family | Port | 527 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 528 | Address (variable) 529 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 530 531 \endverbatim 532 */ 533 typedef struct pj_stun_sockaddr_attr 534 { 535 /** 536 * Standard STUN attribute header. 537 */ 538 pj_stun_attr_hdr hdr; 539 540 /** 541 * Flag to indicate whether this attribute should be sent in XOR-ed 542 * format, or has been received in XOR-ed format. 543 */ 544 pj_bool_t xor_ed; 545 546 /** 547 * The socket address 548 */ 549 pj_sockaddr sockaddr; 550 551 } pj_stun_sockaddr_attr; 552 553 554 /** 555 * This structure represents a generic STUN attributes with no payload, 556 * and it is used for example by ICE USE-CANDIDATE attribute. 557 */ 558 typedef struct pj_stun_empty_attr 559 { 560 /** 561 * Standard STUN attribute header. 562 */ 563 pj_stun_attr_hdr hdr; 564 565 } pj_stun_empty_attr; 566 567 568 /** 569 * This structure represents generic STUN string attributes, such as STUN 570 * USERNAME, PASSWORD, SOFTWARE, REALM, and NONCE attributes. 571 */ 572 typedef struct pj_stun_string_attr 573 { 574 /** 575 * Standard STUN attribute header. 576 */ 577 pj_stun_attr_hdr hdr; 578 579 /** 580 * The string value. 581 */ 582 pj_str_t value; 583 584 } pj_stun_string_attr; 585 586 587 /** 588 * This structure represents a generic STUN attributes with 32bit (unsigned) 589 * integer value, such as STUN FINGERPRINT and REFRESH-INTERVAL attributes. 590 */ 591 typedef struct pj_stun_uint_attr 592 { 593 /** 594 * Standard STUN attribute header. 595 */ 596 pj_stun_attr_hdr hdr; 597 598 /** 599 * The 32bit value, in host byte order. 600 */ 601 pj_uint32_t value; 602 603 } pj_stun_uint_attr; 604 605 606 /** 607 * This structure represents a generic STUN attributes with 64bit (unsigned) 608 * integer value, such as ICE-CONTROLLED and ICE-CONTROLLING attributes. 609 */ 610 typedef struct pj_stun_uint64_attr 611 { 612 /** 613 * Standard STUN attribute header. 614 */ 615 pj_stun_attr_hdr hdr; 616 617 /** 618 * The 64bit value, in host byte order, represented with pj_timestamp. 619 */ 620 pj_timestamp value; 621 622 } pj_stun_uint64_attr; 623 624 625 /** 626 * This structure represents generic STUN attributes to hold a raw binary 627 * data. 628 */ 629 typedef struct pj_stun_binary_attr 630 { 631 /** 632 * Standard STUN attribute header. 633 */ 634 pj_stun_attr_hdr hdr; 635 636 /** 637 * Special signature to indicate that this is a valid attribute even 638 * though we don't have meta-data to describe this attribute. 639 */ 640 pj_uint32_t magic; 641 642 /** 643 * Length of the data. 644 */ 645 unsigned length; 646 647 /** 648 * The raw data. 649 */ 650 pj_uint8_t *data; 651 652 } pj_stun_binary_attr; 653 654 655 /** 656 * This structure describes STUN MESSAGE-INTEGRITY attribute. 657 * The MESSAGE-INTEGRITY attribute contains an HMAC-SHA1 [10] of the 658 * STUN message. The MESSAGE-INTEGRITY attribute can be present in any 659 * STUN message type. Since it uses the SHA1 hash, the HMAC will be 20 660 * bytes. 661 */ 662 typedef struct pj_stun_msgint_attr 663 { 664 /** 665 * Standard STUN attribute header. 666 */ 667 pj_stun_attr_hdr hdr; 668 669 /** 670 * The 20 bytes hmac value. 671 */ 672 pj_uint8_t hmac[20]; 673 674 } pj_stun_msgint_attr; 675 676 677 /** 678 * This structure describes STUN FINGERPRINT attribute. The FINGERPRINT 679 * attribute can be present in all STUN messages. It is computed as 680 * the CRC-32 of the STUN message up to (but excluding) the FINGERPRINT 681 * attribute itself, xor-d with the 32 bit value 0x5354554e 682 */ 683 typedef struct pj_stun_uint_attr pj_stun_fingerprint_attr; 684 685 686 /** 687 * This structure represents STUN ERROR-CODE attribute. The ERROR-CODE 688 * attribute is present in the Binding Error Response and Shared Secret 689 * Error Response. It is a numeric value in the range of 100 to 699 690 * plus a textual reason phrase encoded in UTF-8 691 * 692 * \verbatim 693 694 0 1 2 3 695 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 696 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 697 | 0 |Class| Number | 698 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 699 | Reason Phrase (variable) .. 700 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 701 702 \endverbatim 703 */ 704 typedef struct pj_stun_errcode_attr 705 { 706 /** 707 * Standard STUN attribute header. 708 */ 709 pj_stun_attr_hdr hdr; 710 711 /** 712 * STUN error code. 713 */ 714 int err_code; 715 716 /** 717 * The reason phrase. 718 */ 719 pj_str_t reason; 720 721 } pj_stun_errcode_attr; 722 723 724 /** 725 * This describes STUN REALM attribute. 726 * The REALM attribute is present in requests and responses. It 727 * contains text which meets the grammar for "realm" as described in RFC 728 * 3261 [11], and will thus contain a quoted string (including the 729 * quotes). 730 */ 731 typedef struct pj_stun_string_attr pj_stun_realm_attr; 732 733 734 /** 735 * This describes STUN NONCE attribute. 736 * The NONCE attribute is present in requests and in error responses. 737 * It contains a sequence of qdtext or quoted-pair, which are defined in 738 * RFC 3261 [11]. See RFC 2617 [7] for guidance on selection of nonce 739 * values in a server. 740 */ 741 typedef struct pj_stun_string_attr pj_stun_nonce_attr; 742 743 744 /** 745 * This describes STUN UNKNOWN-ATTRIBUTES attribute. 746 * The UNKNOWN-ATTRIBUTES attribute is present only in an error response 747 * when the response code in the ERROR-CODE attribute is 420. 748 * The attribute contains a list of 16 bit values, each of which 749 * represents an attribute type that was not understood by the server. 750 * If the number of unknown attributes is an odd number, one of the 751 * attributes MUST be repeated in the list, so that the total length of 752 * the list is a multiple of 4 bytes. 753 */ 754 typedef struct pj_stun_unknown_attr 755 { 756 /** 757 * Standard STUN attribute header. 758 */ 759 pj_stun_attr_hdr hdr; 760 761 /** 762 * Number of unknown attributes in the array. 763 */ 764 unsigned attr_count; 765 766 /** 767 * Array of unknown attribute IDs. 768 */ 769 pj_uint16_t attrs[PJ_STUN_MAX_ATTR]; 770 771 } pj_stun_unknown_attr; 772 773 774 /** 775 * This structure describes STUN MAPPED-ADDRESS attribute. 776 * The MAPPED-ADDRESS attribute indicates the mapped transport address. 777 */ 778 typedef struct pj_stun_sockaddr_attr pj_stun_mapped_addr_attr; 779 780 781 /** 782 * This describes STUN XOR-MAPPED-ADDRESS attribute (which has the same 783 * format as STUN MAPPED-ADDRESS attribute). 784 * The XOR-MAPPED-ADDRESS attribute is present in responses. It 785 * provides the same information that would present in the MAPPED- 786 * ADDRESS attribute but because the NAT's public IP address is 787 * obfuscated through the XOR function, STUN messages are able to pass 788 * through NATs which would otherwise interfere with STUN. 789 */ 790 typedef struct pj_stun_sockaddr_attr pj_stun_xor_mapped_addr_attr; 791 792 793 /** 794 * This describes STUN SOFTWARE attribute. 795 * The SOFTWARE attribute contains a textual description of the software 796 * being used by the agent sending the message. It is used by clients 797 * and servers. Its value SHOULD include manufacturer and version 798 * number. */ 799 typedef struct pj_stun_string_attr pj_stun_software_attr; 800 801 802 /** 803 * This describes STUN ALTERNATE-SERVER attribute. 804 * The alternate server represents an alternate transport address for a 805 * different STUN server to try. It is encoded in the same way as 806 * MAPPED-ADDRESS. 807 */ 808 typedef struct pj_stun_sockaddr_attr pj_stun_alt_server_attr; 809 810 811 /** 812 * This describes STUN REFRESH-INTERVAL attribute. 813 * The REFRESH-INTERVAL indicates the number of milliseconds that the 814 * server suggests the client should use between refreshes of the NAT 815 * bindings between the client and server. 816 */ 817 typedef struct pj_stun_uint_attr pj_stun_refresh_interval_attr; 818 819 820 /** 821 * This structure describes STUN RESPONSE-ADDRESS attribute. 822 * The RESPONSE-ADDRESS attribute indicates where the response to a 823 * Binding Request should be sent. Its syntax is identical to MAPPED- 824 * ADDRESS. 825 * 826 * Note that the usage of this attribute has been deprecated by the 827 * RFC 3489-bis standard. 828 */ 829 typedef struct pj_stun_sockaddr_attr pj_stun_response_addr_attr; 830 831 832 /** 833 * This structure describes STUN CHANGED-ADDRESS attribute. 834 * The CHANGED-ADDRESS attribute indicates the IP address and port where 835 * responses would have been sent from if the "change IP" and "change 836 * port" flags had been set in the CHANGE-REQUEST attribute of the 837 * Binding Request. The attribute is always present in a Binding 838 * Response, independent of the value of the flags. Its syntax is 839 * identical to MAPPED-ADDRESS. 840 * 841 * Note that the usage of this attribute has been deprecated by the 842 * RFC 3489-bis standard. 843 */ 844 typedef struct pj_stun_sockaddr_attr pj_stun_changed_addr_attr; 845 846 847 /** 848 * This structure describes STUN CHANGE-REQUEST attribute. 849 * The CHANGE-REQUEST attribute is used by the client to request that 850 * the server use a different address and/or port when sending the 851 * response. 852 * 853 * Bit 29 of the value is the "change IP" flag. If true, it requests 854 * the server to send the Binding Response with a different IP address 855 * than the one the Binding Request was received on. 856 * 857 * Bit 30 of the value is the "change port" flag. If true, it requests 858 * the server to send the Binding Response with a different port than 859 * the one the Binding Request was received on. 860 * 861 * Note that the usage of this attribute has been deprecated by the 862 * RFC 3489-bis standard. 863 */ 864 typedef struct pj_stun_uint_attr pj_stun_change_request_attr; 865 866 /** 867 * This structure describes STUN SOURCE-ADDRESS attribute. 868 * The SOURCE-ADDRESS attribute is present in Binding Responses. It 869 * indicates the source IP address and port that the server is sending 870 * the response from. Its syntax is identical to that of MAPPED- 871 * ADDRESS. 872 * 873 * Note that the usage of this attribute has been deprecated by the 874 * RFC 3489-bis standard. 875 */ 876 typedef struct pj_stun_sockaddr_attr pj_stun_src_addr_attr; 877 878 879 /** 880 * This describes the STUN REFLECTED-FROM attribute. 881 * The REFLECTED-FROM attribute is present only in Binding Responses, 882 * when the Binding Request contained a RESPONSE-ADDRESS attribute. The 883 * attribute contains the identity (in terms of IP address) of the 884 * source where the request came from. Its purpose is to provide 885 * traceability, so that a STUN server cannot be used as a reflector for 886 * denial-of-service attacks. 887 */ 888 typedef struct pj_stun_sockaddr_attr pj_stun_reflected_from_attr; 889 890 891 /** 892 * This describes STUN USERNAME attribute. 893 * The USERNAME attribute is used for message integrity. It identifies 894 * the shared secret used in the message integrity check. Consequently, 895 * the USERNAME MUST be included in any request that contains the 896 * MESSAGE-INTEGRITY attribute. 897 */ 898 typedef struct pj_stun_string_attr pj_stun_username_attr; 899 900 901 /** 902 * This describes STUN PASSWORD attribute. 903 * If the message type is Shared Secret Response it MUST include the 904 * PASSWORD attribute. 905 */ 906 typedef struct pj_stun_string_attr pj_stun_password_attr; 907 908 909 /** 910 * This describes TURN CHANNEL-NUMBER attribute. In this library, 911 * this attribute is represented with 32bit integer. Application may 912 * use #PJ_STUN_GET_CH_NB() and #PJ_STUN_SET_CH_NB() to extract/set 913 * channel number value from the 32bit integral value. 914 * 915 * The CHANNEL-NUMBER attribute contains the number of the channel. 916 * It is a 16-bit unsigned integer, followed by a two-octet RFFU field 917 * which MUST be set to 0 on transmission and ignored on reception. 918 919 \verbatim 920 0 1 2 3 921 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 922 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 923 | Channel Number | RFFU | 924 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 925 \endverbatim 926 */ 927 typedef struct pj_stun_uint_attr pj_stun_channel_number_attr; 928 929 /** 930 * Get 16bit channel number from 32bit integral value. 931 * Note that uint32 attributes are always stored in host byte order 932 * after they have been parsed from the PDU, so no need to do ntohs() 933 * here. 934 */ 935 #define PJ_STUN_GET_CH_NB(u32) ((pj_uint16_t)(u32>>16)) 936 937 /** 938 * Convert 16bit channel number into 32bit integral value. 939 * Note that uint32 attributes will be converted to network byte order 940 * when the attribute is written to packet, so no need to do htons() 941 * here. 942 */ 943 #define PJ_STUN_SET_CH_NB(chnum) (((pj_uint32_t)chnum) << 16) 944 945 946 /** 947 * This describes STUN LIFETIME attribute. 948 * The lifetime attribute represents the duration for which the server 949 * will maintain an allocation in the absence of data traffic either 950 * from or to the client. It is a 32 bit value representing the number 951 * of seconds remaining until expiration. 952 */ 953 typedef struct pj_stun_uint_attr pj_stun_lifetime_attr; 954 955 956 /** 957 * This describes STUN BANDWIDTH attribute. 958 * The bandwidth attribute represents the peak bandwidth, measured in 959 * kbits per second, that the client expects to use on the binding. The 960 * value represents the sum in the receive and send directions. 961 */ 962 typedef struct pj_stun_uint_attr pj_stun_bandwidth_attr; 963 964 965 /** 966 * This describes the STUN XOR-PEER-ADDRESS attribute. 967 * The XOR-PEER-ADDRESS specifies the address and port of the peer as seen 968 * from the TURN server. It is encoded in the same way as XOR-MAPPED- 969 * ADDRESS. 970 */ 971 typedef struct pj_stun_sockaddr_attr pj_stun_xor_peer_addr_attr; 972 973 974 /** 975 * This describes the STUN DATA attribute. 976 * The DATA attribute is present in Send Indications and Data 977 * Indications. It contains raw payload data that is to be sent (in the 978 * case of a Send Request) or was received (in the case of a Data 979 * Indication).. 980 */ 981 typedef struct pj_stun_binary_attr pj_stun_data_attr; 982 983 984 /** 985 * This describes the STUN XOR-RELAYED-ADDRESS attribute. The 986 * XOR-RELAYED-ADDRESS is present in Allocate responses. It specifies the 987 * address and port that the server allocated to the client. It is 988 * encoded in the same way as XOR-MAPPED-ADDRESS. 989 */ 990 typedef struct pj_stun_sockaddr_attr pj_stun_xor_relayed_addr_attr; 991 992 993 /** 994 * According to RFC 6156, this describes the REQUESTED-ADDRESS-FAMILY 995 * attribute (formerly known as REQUESTED-ADDRESS-TYPE in the draft). 996 * The REQUESTED-ADDRESS-FAMILY attribute is used by clients to request 997 * the allocation of a specific address type from a server. The 998 * following is the format of the REQUESTED-ADDRESS-FAMILY attribute. 999 1000 \verbatim 1001 1002 0 1 2 3 1003 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1004 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1005 | Family | Reserved | 1006 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1007 1008 \endverbatim 1009 */ 1010 typedef struct pj_stun_uint_attr pj_stun_req_addr_type_attr; 1011 1012 1013 /** 1014 * This describes the TURN REQUESTED-TRANSPORT attribute, encoded in 1015 * STUN generic integer attribute. 1016 * 1017 * This attribute allows the client to request that the port in the 1018 * relayed-transport-address be even, and (optionally) that the server 1019 * reserve the next-higher port number. The attribute is 8 bits long. 1020 * Its format is: 1021 1022 \verbatim 1023 0 1024 0 1 2 3 4 5 6 7 1025 +-+-+-+-+-+-+-+-+ 1026 |R| RFFU | 1027 +-+-+-+-+-+-+-+-+ 1028 1029 \endverbatim 1030 1031 * The attribute contains a single 1-bit flag: 1032 * 1033 * R: If 1, the server is requested to reserve the next higher port 1034 * number (on the same IP address) for a subsequent allocation. If 1035 * 0, no such reservation is requested. 1036 * 1037 * The other 7 bits of the attribute must be set to zero on transmission 1038 * and ignored on reception. 1039 */ 1040 typedef struct pj_stun_uint_attr pj_stun_even_port_attr; 1041 1042 1043 /** 1044 * This describes the TURN REQUESTED-TRANSPORT attribute, encoded in 1045 * STUN generic integer attribute. 1046 * 1047 * This attribute is used by the client to request a specific transport 1048 * protocol for the allocated transport address. It has the following 1049 * format: 1050 1051 \verbatim 1052 1053 0 1 2 3 1054 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1055 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1056 | Protocol | RFFU | 1057 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1058 1059 1060 \endverbatim 1061 1062 * The Protocol field specifies the desired protocol. The codepoints 1063 * used in this field are taken from those allowed in the Protocol field 1064 * in the IPv4 header and the NextHeader field in the IPv6 header 1065 * [Protocol-Numbers]. This specification only allows the use of 1066 * codepoint 17 (User Datagram Protocol). 1067 * 1068 * The RFFU field is set to zero on transmission and ignored on 1069 * receiption. It is reserved for future uses. 1070 */ 1071 typedef struct pj_stun_uint_attr pj_stun_req_transport_attr; 1072 1073 /** 1074 * Get protocol value from 32bit TURN REQUESTED-TRANSPORT attribute. 1075 */ 1076 #define PJ_STUN_GET_RT_PROTO(u32) (u32 >> 24) 1077 1078 /** 1079 * Convert protocol value to be placed in 32bit TURN REQUESTED-TRANSPORT 1080 * attribute. 1081 */ 1082 #define PJ_STUN_SET_RT_PROTO(proto) (((pj_uint32_t)(proto)) << 24) 1083 1084 1085 /** 1086 * This describes the TURN DONT-FRAGMENT attribute. 1087 * 1088 * This attribute is used by the client to request that the server set 1089 * the DF (Don't Fragment) bit in the IP header when relaying the 1090 * application data onward to the peer. This attribute has no value 1091 * part and thus the attribute length field is 0. 1092 */ 1093 typedef struct pj_stun_empty_attr pj_stun_dont_fragment_attr; 1094 1095 1096 /** 1097 * This describes the TURN RESERVATION-TOKEN attribute. 1098 * The RESERVATION-TOKEN attribute contains a token that uniquely 1099 * identifies a relayed transport address being held in reserve by the 1100 * server. The server includes this attribute in a success response to 1101 * tell the client about the token, and the client includes this 1102 * attribute in a subsequent Allocate request to request the server use 1103 * that relayed transport address for the allocation. 1104 * 1105 * The attribute value is a 64-bit-long field containing the token 1106 * value. 1107 */ 1108 typedef struct pj_stun_uint64_attr pj_stun_res_token_attr; 1109 1110 /** 1111 * This describes the XOR-REFLECTED-FROM attribute, as described by 1112 * draft-macdonald-behave-nat-behavior-discovery-00. 1113 * The XOR-REFLECTED-FROM attribute is used in place of the REFLECTED- 1114 * FROM attribute. It provides the same information, but because the 1115 * NAT's public address is obfuscated through the XOR function, It can 1116 * pass through a NAT that would otherwise attempt to translate it to 1117 * the private network address. XOR-REFLECTED-FROM has identical syntax 1118 * to XOR-MAPPED-ADDRESS. 1119 */ 1120 typedef struct pj_stun_sockaddr_attr pj_stun_xor_reflected_from_attr; 1121 1122 /** 1123 * This describes the PRIORITY attribute from draft-ietf-mmusic-ice-13. 1124 * The PRIORITY attribute indicates the priority that is to be 1125 * associated with a peer reflexive candidate, should one be discovered 1126 * by this check. It is a 32 bit unsigned integer, and has an attribute 1127 * type of 0x0024. 1128 */ 1129 typedef struct pj_stun_uint_attr pj_stun_priority_attr; 1130 1131 /** 1132 * This describes the USE-CANDIDATE attribute from draft-ietf-mmusic-ice-13. 1133 * The USE-CANDIDATE attribute indicates that the candidate pair 1134 * resulting from this check should be used for transmission of media. 1135 * The attribute has no content (the Length field of the attribute is 1136 * zero); it serves as a flag. 1137 */ 1138 typedef struct pj_stun_empty_attr pj_stun_use_candidate_attr; 1139 1140 /** 1141 * This describes the STUN TIMER-VAL attribute. 1142 * The TIMER-VAL attribute is used only in conjunction with the Set 1143 * Active Destination response. It conveys from the server, to the 1144 * client, the value of the timer used in the server state machine. 1145 */ 1146 typedef struct pj_stun_uint_attr pj_stun_timer_val_attr; 1147 1148 /** 1149 * This describes ICE-CONTROLLING attribute. 1150 */ 1151 typedef struct pj_stun_uint64_attr pj_stun_ice_controlling_attr; 1152 1153 /** 1154 * This describes ICE-CONTROLLED attribute. 1155 */ 1156 typedef struct pj_stun_uint64_attr pj_stun_ice_controlled_attr; 1157 1158 /** 1159 * This describes TURN ICMP attribute 1160 */ 1161 typedef struct pj_stun_uint_attr pj_stun_icmp_attr; 1162 1163 /** 1164 * This structure describes a parsed STUN message. All integral fields 1165 * in this structure (including IP addresses) will be in the host 1166 * byte order. 1167 */ 1168 typedef struct pj_stun_msg 1169 { 1170 /** 1171 * STUN message header. 1172 */ 1173 pj_stun_msg_hdr hdr; 1174 1175 /** 1176 * Number of attributes in the STUN message. 1177 */ 1178 unsigned attr_count; 1179 1180 /** 1181 * Array of STUN attributes. 1182 */ 1183 pj_stun_attr_hdr *attr[PJ_STUN_MAX_ATTR]; 1184 1185 } pj_stun_msg; 1186 1187 1188 /** STUN decoding options */ 1189 enum pj_stun_decode_options 1190 { 1191 /** 1192 * Tell the decoder that the message was received from datagram 1193 * oriented transport (such as UDP). 1194 */ 1195 PJ_STUN_IS_DATAGRAM = 1, 1196 1197 /** 1198 * Tell pj_stun_msg_decode() to check the validity of the STUN 1199 * message by calling pj_stun_msg_check() before starting to 1200 * decode the packet. 1201 */ 1202 PJ_STUN_CHECK_PACKET = 2, 1203 1204 /** 1205 * This option current is only valid for #pj_stun_session_on_rx_pkt(). 1206 * When specified, it tells the session NOT to authenticate the 1207 * message. 1208 */ 1209 PJ_STUN_NO_AUTHENTICATE = 4, 1210 1211 /** 1212 * Disable FINGERPRINT verification. This option can be used when calling 1213 * #pj_stun_msg_check() and #pj_stun_msg_decode() to disable the 1214 * verification of FINGERPRINT, for example when the STUN usage says when 1215 * FINGERPRINT mechanism shall not be used. 1216 */ 1217 PJ_STUN_NO_FINGERPRINT_CHECK = 8 1218 }; 1219 1220 1221 /** 1222 * Get STUN message method name. 1223 * 1224 * @param msg_type The STUN message type (in host byte order) 1225 * 1226 * @return The STUN message method name string. 1227 */ 1228 PJ_DECL(const char*) pj_stun_get_method_name(unsigned msg_type); 1229 1230 1231 /** 1232 * Get STUN message class name. 1233 * 1234 * @param msg_type The STUN message type (in host byte order) 1235 * 1236 * @return The STUN message class name string. 1237 */ 1238 PJ_DECL(const char*) pj_stun_get_class_name(unsigned msg_type); 1239 1240 1241 /** 1242 * Get STUN attribute name. 1243 * 1244 * @return attr_type The STUN attribute type (in host byte order). 1245 * 1246 * @return The STUN attribute type name string. 1247 */ 1248 PJ_DECL(const char*) pj_stun_get_attr_name(unsigned attr_type); 1249 1250 1251 /** 1252 * Get STUN standard reason phrase for the specified error code. 1253 * 1254 * @param err_code The STUN error code. 1255 * 1256 * @return The STUN error reason phrase. 1257 */ 1258 PJ_DECL(pj_str_t) pj_stun_get_err_reason(int err_code); 1259 1260 1261 /** 1262 * Internal: set the padding character for string attribute. 1263 * The default padding character is PJ_STUN_STRING_ATTR_PAD_CHR. 1264 * 1265 * @return The previous padding character. 1266 */ 1267 PJ_DECL(int) pj_stun_set_padding_char(int chr); 1268 1269 1270 /** 1271 * Initialize a generic STUN message. 1272 * 1273 * @param msg The message structure to be initialized. 1274 * @param msg_type The 14bit message type (see pj_stun_msg_type 1275 * constants). 1276 * @param magic Magic value to be put to the mesage; for requests, 1277 * the value normally should be PJ_STUN_MAGIC. 1278 * @param tsx_id Optional transaction ID, or NULL to let the 1279 * function generates a random transaction ID. 1280 * 1281 * @return PJ_SUCCESS on success. 1282 */ 1283 PJ_DECL(pj_status_t) pj_stun_msg_init(pj_stun_msg *msg, 1284 unsigned msg_type, 1285 pj_uint32_t magic, 1286 const pj_uint8_t tsx_id[12]); 1287 1288 /** 1289 * Create a generic STUN message. 1290 * 1291 * @param pool Pool to create the STUN message. 1292 * @param msg_type The 14bit message type. 1293 * @param magic Magic value to be put to the mesage; for requests, 1294 * the value should be PJ_STUN_MAGIC. 1295 * @param tsx_id Optional transaction ID, or NULL to let the 1296 * function generates a random transaction ID. 1297 * @param p_msg Pointer to receive the message. 1298 * 1299 * @return PJ_SUCCESS on success. 1300 */ 1301 PJ_DECL(pj_status_t) pj_stun_msg_create(pj_pool_t *pool, 1302 unsigned msg_type, 1303 pj_uint32_t magic, 1304 const pj_uint8_t tsx_id[12], 1305 pj_stun_msg **p_msg); 1306 1307 /** 1308 * Clone a STUN message with all of its attributes. 1309 * 1310 * @param pool Pool to allocate memory for the new message. 1311 * @param msg The message to be cloned. 1312 * 1313 * @return The duplicate message. 1314 */ 1315 PJ_DECL(pj_stun_msg*) pj_stun_msg_clone(pj_pool_t *pool, 1316 const pj_stun_msg *msg); 1317 1318 /** 1319 * Create STUN response message. 1320 * 1321 * @param pool Pool to create the mesage. 1322 * @param req_msg The request message. 1323 * @param err_code STUN error code. If this value is not zero, 1324 * then error response will be created, otherwise 1325 * successful response will be created. 1326 * @param err_msg Optional error message to explain err_code. 1327 * If this value is NULL and err_code is not zero, 1328 * the error string will be taken from the default 1329 * STUN error message. 1330 * @param p_response Pointer to receive the response. 1331 * 1332 * @return PJ_SUCCESS on success, or the appropriate error. 1333 */ 1334 PJ_DECL(pj_status_t) pj_stun_msg_create_response(pj_pool_t *pool, 1335 const pj_stun_msg *req_msg, 1336 unsigned err_code, 1337 const pj_str_t *err_msg, 1338 pj_stun_msg **p_response); 1339 1340 1341 /** 1342 * Add STUN attribute to STUN message. 1343 * 1344 * @param msg The STUN message. 1345 * @param attr The STUN attribute to be added to the message. 1346 * 1347 * @return PJ_SUCCESS on success, or PJ_ETOOMANY if there are 1348 * already too many attributes in the message. 1349 */ 1350 PJ_DECL(pj_status_t) pj_stun_msg_add_attr(pj_stun_msg *msg, 1351 pj_stun_attr_hdr *attr); 1352 1353 1354 /** 1355 * Print the STUN message structure to a packet buffer, ready to be 1356 * sent to remote destination. This function will take care about 1357 * calculating the MESSAGE-INTEGRITY digest as well as FINGERPRINT 1358 * value, if these attributes are present in the message. 1359 * 1360 * If application wants to apply credential to the message, it MUST 1361 * include a blank MESSAGE-INTEGRITY attribute in the message as the 1362 * last attribute or the attribute before FINGERPRINT. This function will 1363 * calculate the HMAC digest from the message using the supplied key in 1364 * the parameter. The key should be set to the password if short term 1365 * credential is used, or calculated from the MD5 hash of the realm, 1366 * username, and password using #pj_stun_create_key() if long term 1367 * credential is used. 1368 * 1369 * If FINGERPRINT attribute is present, this function will calculate 1370 * the FINGERPRINT CRC attribute for the message. The FINGERPRINT MUST 1371 * be added as the last attribute of the message. 1372 * 1373 * @param msg The STUN message to be printed. Upon return, 1374 * some fields in the header (such as message 1375 * length) will be updated. 1376 * @param pkt_buf The buffer to be filled with the packet. 1377 * @param buf_size Size of the buffer. 1378 * @param options Options, which currently must be zero. 1379 * @param key Authentication key to calculate MESSAGE-INTEGRITY 1380 * value. Application can create this key by using 1381 * #pj_stun_create_key() function. 1382 * @param p_msg_len Upon return, it will be filed with the size of 1383 * the packet in bytes, or negative value on error. 1384 * 1385 * @return PJ_SUCCESS on success or the appropriate error code. 1386 */ 1387 PJ_DECL(pj_status_t) pj_stun_msg_encode(pj_stun_msg *msg, 1388 pj_uint8_t *pkt_buf, 1389 pj_size_t buf_size, 1390 unsigned options, 1391 const pj_str_t *key, 1392 pj_size_t *p_msg_len); 1393 1394 /** 1395 * Check that the PDU is potentially a valid STUN message. This function 1396 * is useful when application needs to multiplex STUN packets with other 1397 * application traffic. When this function returns PJ_SUCCESS, there is a 1398 * big chance that the packet is a STUN packet. 1399 * 1400 * Note that we cannot be sure that the PDU is a really valid STUN message 1401 * until we actually parse the PDU. 1402 * 1403 * @param pdu The packet buffer. 1404 * @param pdu_len The length of the packet buffer. 1405 * @param options Additional options to be applied in the checking, 1406 * which can be taken from pj_stun_decode_options. One 1407 * of the useful option is PJ_STUN_IS_DATAGRAM which 1408 * means that the pdu represents a whole STUN packet. 1409 * 1410 * @return PJ_SUCCESS if the PDU is a potentially valid STUN 1411 * message. 1412 */ 1413 PJ_DECL(pj_status_t) pj_stun_msg_check(const pj_uint8_t *pdu, 1414 pj_size_t pdu_len, unsigned options); 1415 1416 1417 /** 1418 * Decode incoming packet into STUN message. 1419 * 1420 * @param pool Pool to allocate the message. 1421 * @param pdu The incoming packet to be parsed. 1422 * @param pdu_len The length of the incoming packet. 1423 * @param options Parsing flags, according to pj_stun_decode_options. 1424 * @param p_msg Pointer to receive the parsed message. 1425 * @param p_parsed_len Optional pointer to receive how many bytes have 1426 * been parsed for the STUN message. This is useful 1427 * when the packet is received over stream oriented 1428 * transport. 1429 * @param p_response Optional pointer to receive an instance of response 1430 * message, if one can be created. If the packet being 1431 * decoded is a request message, and it contains error, 1432 * and a response can be created, then the STUN 1433 * response message will be returned on this argument. 1434 * 1435 * @return PJ_SUCCESS if a STUN message has been successfully 1436 * decoded. 1437 */ 1438 PJ_DECL(pj_status_t) pj_stun_msg_decode(pj_pool_t *pool, 1439 const pj_uint8_t *pdu, 1440 pj_size_t pdu_len, 1441 unsigned options, 1442 pj_stun_msg **p_msg, 1443 pj_size_t *p_parsed_len, 1444 pj_stun_msg **p_response); 1445 1446 /** 1447 * Dump STUN message to a printable string output. 1448 * 1449 * @param msg The STUN message 1450 * @param buffer Buffer where the printable string output will 1451 * be printed on. 1452 * @param length Specify the maximum length of the buffer. 1453 * @param printed_len Optional pointer, which on output will be filled 1454 * up with the actual length of the output string. 1455 * 1456 * @return The message string output. 1457 */ 1458 #if PJ_LOG_MAX_LEVEL > 0 1459 PJ_DECL(char*) pj_stun_msg_dump(const pj_stun_msg *msg, 1460 char *buffer, 1461 unsigned length, 1462 unsigned *printed_len); 1463 #else 1464 # define pj_stun_msg_dump(msg, buf, length, printed_len) "" 1465 #endif 1466 1467 1468 /** 1469 * Find STUN attribute in the STUN message, starting from the specified 1470 * index. 1471 * 1472 * @param msg The STUN message. 1473 * @param attr_type The attribute type to be found, from pj_stun_attr_type. 1474 * @param start_index The start index of the attribute in the message. 1475 * Specify zero to start searching from the first 1476 * attribute. 1477 * 1478 * @return The attribute instance, or NULL if it cannot be 1479 * found. 1480 */ 1481 PJ_DECL(pj_stun_attr_hdr*) pj_stun_msg_find_attr(const pj_stun_msg *msg, 1482 int attr_type, 1483 unsigned start_index); 1484 1485 1486 /** 1487 * Clone a STUN attribute. 1488 * 1489 * @param pool Pool to allocate memory. 1490 * @param attr Attribute to clone. 1491 * 1492 * @return Duplicate attribute. 1493 */ 1494 PJ_DECL(pj_stun_attr_hdr*) pj_stun_attr_clone(pj_pool_t *pool, 1495 const pj_stun_attr_hdr *attr); 1496 1497 1498 /** 1499 * Initialize generic STUN IP address attribute. The \a addr_len and 1500 * \a addr parameters specify whether the address is IPv4 or IPv4 1501 * address. 1502 * 1503 * @param attr The socket address attribute to initialize. 1504 * @param attr_type Attribute type, from #pj_stun_attr_type. 1505 * @param xor_ed If non-zero, the port and address will be XOR-ed 1506 * with magic, to make the XOR-MAPPED-ADDRESS attribute. 1507 * @param addr A pj_sockaddr_in or pj_sockaddr_in6 structure. 1508 * @param addr_len Length of \a addr parameter. 1509 * 1510 * @return PJ_SUCCESS on success or the appropriate error code. 1511 */ 1512 PJ_DECL(pj_status_t) pj_stun_sockaddr_attr_init(pj_stun_sockaddr_attr *attr, 1513 int attr_type, 1514 pj_bool_t xor_ed, 1515 const pj_sockaddr_t *addr, 1516 unsigned addr_len); 1517 1518 /** 1519 * Create a generic STUN IP address attribute. The \a addr_len and 1520 * \a addr parameters specify whether the address is IPv4 or IPv4 1521 * address. 1522 * 1523 * @param pool The pool to allocate memory from. 1524 * @param attr_type Attribute type, from #pj_stun_attr_type. 1525 * @param xor_ed If non-zero, the port and address will be XOR-ed 1526 * with magic, to make the XOR-MAPPED-ADDRESS attribute. 1527 * @param addr A pj_sockaddr_in or pj_sockaddr_in6 structure. 1528 * @param addr_len Length of \a addr parameter. 1529 * @param p_attr Pointer to receive the attribute. 1530 * 1531 * @return PJ_SUCCESS on success or the appropriate error code. 1532 */ 1533 PJ_DECL(pj_status_t) pj_stun_sockaddr_attr_create(pj_pool_t *pool, 1534 int attr_type, 1535 pj_bool_t xor_ed, 1536 const pj_sockaddr_t *addr, 1537 unsigned addr_len, 1538 pj_stun_sockaddr_attr **p_attr); 1539 1540 1541 /** 1542 * Create and add generic STUN IP address attribute to a STUN message. 1543 * The \a addr_len and \a addr parameters specify whether the address is 1544 * IPv4 or IPv4 address. 1545 * 1546 * @param pool The pool to allocate memory from. 1547 * @param msg The STUN message. 1548 * @param attr_type Attribute type, from #pj_stun_attr_type. 1549 * @param xor_ed If non-zero, the port and address will be XOR-ed 1550 * with magic, to make the XOR-MAPPED-ADDRESS attribute. 1551 * @param addr A pj_sockaddr_in or pj_sockaddr_in6 structure. 1552 * @param addr_len Length of \a addr parameter. 1553 * 1554 * @return PJ_SUCCESS on success or the appropriate error code. 1555 */ 1556 PJ_DECL(pj_status_t) pj_stun_msg_add_sockaddr_attr(pj_pool_t *pool, 1557 pj_stun_msg *msg, 1558 int attr_type, 1559 pj_bool_t xor_ed, 1560 const pj_sockaddr_t *addr, 1561 unsigned addr_len); 1562 1563 /** 1564 * Initialize a STUN generic string attribute. 1565 * 1566 * @param attr The string attribute to be initialized. 1567 * @param pool Pool to duplicate the value into the attribute, 1568 * if value is not NULL or empty. 1569 * @param attr_type Attribute type, from #pj_stun_attr_type. 1570 * @param value The string value to be assigned to the attribute. 1571 * 1572 * @return PJ_SUCCESS on success or the appropriate error code. 1573 */ 1574 PJ_DECL(pj_status_t) pj_stun_string_attr_init(pj_stun_string_attr *attr, 1575 pj_pool_t *pool, 1576 int attr_type, 1577 const pj_str_t *value); 1578 1579 /** 1580 * Create a STUN generic string attribute. 1581 * 1582 * @param pool The pool to allocate memory from. 1583 * @param attr_type Attribute type, from #pj_stun_attr_type. 1584 * @param value The string value to be assigned to the attribute. 1585 * @param p_attr Pointer to receive the attribute. 1586 * 1587 * @return PJ_SUCCESS on success or the appropriate error code. 1588 */ 1589 PJ_DECL(pj_status_t) pj_stun_string_attr_create(pj_pool_t *pool, 1590 int attr_type, 1591 const pj_str_t *value, 1592 pj_stun_string_attr **p_attr); 1593 1594 /** 1595 * Create and add STUN generic string attribute to the message. 1596 * 1597 * @param pool The pool to allocate memory from. 1598 * @param msg The STUN message. 1599 * @param attr_type Attribute type, from #pj_stun_attr_type. 1600 * @param value The string value to be assigned to the attribute. 1601 * 1602 * @return PJ_SUCCESS on success or the appropriate error code. 1603 */ 1604 PJ_DECL(pj_status_t) pj_stun_msg_add_string_attr(pj_pool_t *pool, 1605 pj_stun_msg *msg, 1606 int attr_type, 1607 const pj_str_t *value); 1608 1609 /** 1610 * Create a STUN generic 32bit value attribute. 1611 * 1612 * @param pool The pool to allocate memory from. 1613 * @param attr_type Attribute type, from #pj_stun_attr_type. 1614 * @param value The 32bit value to be assigned to the attribute. 1615 * @param p_attr Pointer to receive the attribute. 1616 * 1617 * @return PJ_SUCCESS on success or the appropriate error code. 1618 */ 1619 PJ_DECL(pj_status_t) pj_stun_uint_attr_create(pj_pool_t *pool, 1620 int attr_type, 1621 pj_uint32_t value, 1622 pj_stun_uint_attr **p_attr); 1623 1624 /** 1625 * Create and add STUN generic 32bit value attribute to the message. 1626 * 1627 * @param pool The pool to allocate memory from. 1628 * @param msg The STUN message 1629 * @param attr_type Attribute type, from #pj_stun_attr_type. 1630 * @param value The 32bit value to be assigned to the attribute. 1631 * 1632 * @return PJ_SUCCESS on success or the appropriate error code. 1633 */ 1634 PJ_DECL(pj_status_t) pj_stun_msg_add_uint_attr(pj_pool_t *pool, 1635 pj_stun_msg *msg, 1636 int attr_type, 1637 pj_uint32_t value); 1638 1639 1640 /** 1641 * Create a STUN generic 64bit value attribute. 1642 * 1643 * @param pool Pool to allocate memory from. 1644 * @param attr_type Attribute type, from #pj_stun_attr_type. 1645 * @param value Optional value to be assigned. 1646 * @param p_attr Pointer to receive the attribute. 1647 * 1648 * @return PJ_SUCCESS on success or the appropriate error code. 1649 */ 1650 PJ_DECL(pj_status_t) pj_stun_uint64_attr_create(pj_pool_t *pool, 1651 int attr_type, 1652 const pj_timestamp *value, 1653 pj_stun_uint64_attr **p_attr); 1654 1655 1656 /** 1657 * Create and add STUN generic 64bit value attribute to the message. 1658 * 1659 * @param pool The pool to allocate memory from. 1660 * @param msg The STUN message 1661 * @param attr_type Attribute type, from #pj_stun_attr_type. 1662 * @param value The 64bit value to be assigned to the attribute. 1663 * 1664 * @return PJ_SUCCESS on success or the appropriate error code. 1665 */ 1666 PJ_DECL(pj_status_t) pj_stun_msg_add_uint64_attr(pj_pool_t *pool, 1667 pj_stun_msg *msg, 1668 int attr_type, 1669 const pj_timestamp *value); 1670 1671 /** 1672 * Create a STUN MESSAGE-INTEGRITY attribute. 1673 * 1674 * @param pool The pool to allocate memory from. 1675 * @param p_attr Pointer to receive the attribute. 1676 * 1677 * @return PJ_SUCCESS on success or the appropriate error code. 1678 */ 1679 PJ_DECL(pj_status_t) pj_stun_msgint_attr_create(pj_pool_t *pool, 1680 pj_stun_msgint_attr **p_attr); 1681 1682 /** 1683 * Create and add STUN MESSAGE-INTEGRITY attribute. 1684 * 1685 * @param pool The pool to allocate memory from. 1686 * @param msg The STUN message 1687 * 1688 * @return PJ_SUCCESS on success or the appropriate error code. 1689 */ 1690 PJ_DECL(pj_status_t) pj_stun_msg_add_msgint_attr(pj_pool_t *pool, 1691 pj_stun_msg *msg); 1692 1693 /** 1694 * Create a STUN ERROR-CODE attribute. 1695 * 1696 * @param pool The pool to allocate memory from. 1697 * @param err_code STUN error code. 1698 * @param err_reason Optional STUN error reason. If NULL is given, the 1699 * standard error reason will be given. 1700 * @param p_attr Pointer to receive the attribute. 1701 * 1702 * @return PJ_SUCCESS on success or the appropriate error code. 1703 */ 1704 PJ_DECL(pj_status_t) pj_stun_errcode_attr_create(pj_pool_t *pool, 1705 int err_code, 1706 const pj_str_t *err_reason, 1707 pj_stun_errcode_attr **p_attr); 1708 1709 1710 /** 1711 * Create and add STUN ERROR-CODE attribute to the message. 1712 * 1713 * @param pool The pool to allocate memory from. 1714 * @param msg The STUN mesage. 1715 * @param err_code STUN error code. 1716 * @param err_reason Optional STUN error reason. If NULL is given, the 1717 * standard error reason will be given. 1718 * 1719 * @return PJ_SUCCESS on success or the appropriate error code. 1720 */ 1721 PJ_DECL(pj_status_t) pj_stun_msg_add_errcode_attr(pj_pool_t *pool, 1722 pj_stun_msg *msg, 1723 int err_code, 1724 const pj_str_t *err_reason); 1725 1726 /** 1727 * Create instance of STUN UNKNOWN-ATTRIBUTES attribute and copy the 1728 * unknown attribute array to the attribute. 1729 * 1730 * @param pool The pool to allocate memory from. 1731 * @param attr_cnt Number of attributes in the array (can be zero). 1732 * @param attr Optional array of attributes. 1733 * @param p_attr Pointer to receive the attribute. 1734 * 1735 * @return PJ_SUCCESS on success or the appropriate error code. 1736 */ 1737 PJ_DECL(pj_status_t) pj_stun_unknown_attr_create(pj_pool_t *pool, 1738 unsigned attr_cnt, 1739 const pj_uint16_t attr[], 1740 pj_stun_unknown_attr **p_attr); 1741 1742 /** 1743 * Create and add STUN UNKNOWN-ATTRIBUTES attribute to the message. 1744 * 1745 * @param pool The pool to allocate memory from. 1746 * @param msg The STUN message. 1747 * @param attr_cnt Number of attributes in the array (can be zero). 1748 * @param attr Optional array of attribute types. 1749 * 1750 * @return PJ_SUCCESS on success or the appropriate error code. 1751 */ 1752 PJ_DECL(pj_status_t) pj_stun_msg_add_unknown_attr(pj_pool_t *pool, 1753 pj_stun_msg *msg, 1754 unsigned attr_cnt, 1755 const pj_uint16_t attr[]); 1756 1757 /** 1758 * Initialize STUN binary attribute. 1759 * 1760 * @param attr The attribute to be initialized. 1761 * @param pool Pool to copy data, if the data and length are set. 1762 * @param attr_type The attribute type, from #pj_stun_attr_type. 1763 * @param data Data to be coped to the attribute, or NULL 1764 * if no data to be copied now. 1765 * @param length Length of data, or zero if no data is to be 1766 * copied now. 1767 * 1768 * @return PJ_SUCCESS on success or the appropriate error code. 1769 */ 1770 PJ_DECL(pj_status_t) pj_stun_binary_attr_init(pj_stun_binary_attr *attr, 1771 pj_pool_t *pool, 1772 int attr_type, 1773 const pj_uint8_t *data, 1774 unsigned length); 1775 1776 /** 1777 * Create STUN binary attribute. 1778 * 1779 * @param pool The pool to allocate memory from. 1780 * @param attr_type The attribute type, from #pj_stun_attr_type. 1781 * @param data Data to be coped to the attribute, or NULL 1782 * if no data to be copied now. 1783 * @param length Length of data, or zero if no data is to be 1784 * copied now. 1785 * @param p_attr Pointer to receive the attribute. 1786 * 1787 * @return PJ_SUCCESS on success or the appropriate error code. 1788 */ 1789 PJ_DECL(pj_status_t) pj_stun_binary_attr_create(pj_pool_t *pool, 1790 int attr_type, 1791 const pj_uint8_t *data, 1792 unsigned length, 1793 pj_stun_binary_attr **p_attr); 1794 1795 /** 1796 * Create STUN binary attribute and add the attribute to the message. 1797 * 1798 * @param pool The pool to allocate memory from. 1799 * @param msg The STUN message. 1800 * @param attr_type The attribute type, from #pj_stun_attr_type. 1801 * @param data Data to be coped to the attribute, or NULL 1802 * if no data to be copied now. 1803 * @param length Length of data, or zero if no data is to be 1804 * copied now. 1805 * 1806 * @return PJ_SUCCESS on success or the appropriate error code. 1807 */ 1808 PJ_DECL(pj_status_t) pj_stun_msg_add_binary_attr(pj_pool_t *pool, 1809 pj_stun_msg *msg, 1810 int attr_type, 1811 const pj_uint8_t *data, 1812 unsigned length); 1813 1814 /** 1815 * Create STUN empty attribute. 1816 * 1817 * @param pool The pool to allocate memory from. 1818 * @param attr_type The attribute type, from #pj_stun_attr_type. 1819 * @param p_attr Pointer to receive the attribute. 1820 * 1821 * @return PJ_SUCCESS on success or the appropriate error code. 1822 */ 1823 PJ_DECL(pj_status_t) pj_stun_empty_attr_create(pj_pool_t *pool, 1824 int attr_type, 1825 pj_stun_empty_attr **p_attr); 1826 1827 /** 1828 * Create STUN empty attribute and add the attribute to the message. 1829 * 1830 * @param pool The pool to allocate memory from. 1831 * @param msg The STUN message. 1832 * @param attr_type The attribute type, from #pj_stun_attr_type. 1833 * 1834 * @return PJ_SUCCESS on success or the appropriate error code. 1835 */ 1836 PJ_DECL(pj_status_t) pj_stun_msg_add_empty_attr(pj_pool_t *pool, 1837 pj_stun_msg *msg, 1838 int attr_type); 1839 1840 /** 1841 * @} 1842 */ 1843 1844 1845 PJ_END_DECL 1846 1847 1848 #endif /* __PJNATH_STUN_MSG_H__ */ 1849 1850