stun/usages/turn.h

   1 /*
   2  * This file is part of the Nice GLib ICE library.
   3  *
   4  * (C) 2008-2009 Collabora Ltd.
   5  *  Contact: Youness Alaoui
   6  * (C) 2007-2009 Nokia Corporation. All rights reserved.
   7  *  Contact: Rémi Denis-Courmont
   8  *
   9  * The contents of this file are subject to the Mozilla Public License Version
  10  * 1.1 (the "License"); you may not use this file except in compliance with
  11  * the License. You may obtain a copy of the License at
  12  * http://www.mozilla.org/MPL/
  13  *
  14  * Software distributed under the License is distributed on an "AS IS" basis,
  15  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  16  * for the specific language governing rights and limitations under the
  17  * License.
  18  *
  19  * The Original Code is the Nice GLib ICE library.
  20  *
  21  * The Initial Developers of the Original Code are Collabora Ltd and Nokia
  22  * Corporation. All Rights Reserved.
  23  *
  24  * Contributors:
  25  *   Youness Alaoui, Collabora Ltd.
  26  *   Rémi Denis-Courmont, Nokia
  27  *
  28  * Alternatively, the contents of this file may be used under the terms of the
  29  * the GNU Lesser General Public License Version 2.1 (the "LGPL"), in which
  30  * case the provisions of LGPL are applicable instead of those above. If you
  31  * wish to allow use of your version of this file only under the terms of the
  32  * LGPL and not to allow others to use your version of this file under the
  33  * MPL, indicate your decision by deleting the provisions above and replace
  34  * them with the notice and other provisions required by the LGPL. If you do
  35  * not delete the provisions above, a recipient may use your version of this
  36  * file under either the MPL or the LGPL.
  37  */
  38
  39 #ifndef STUN_TURN_H
  40 # define STUN_TURN_H 1
  41
  42 /**
  43  * SECTION:turn
  44  * @short_description: TURN Allocation Usage
  45  * @include: stun/usages/turn.h
  46  * @stability: Stable
  47  *
  48  * The STUN TURN usage allows for easily creating and parsing STUN Allocate
  49  * requests and responses used for TURN. The API allows you to create a new
  50  * allocation or refresh an existing one as well as to parse a response to
  51  * an allocate or refresh request.
  52  */
  53
  54
  55 #ifdef _WIN32
  56 #  include "../win32_common.h"
  57 #else
  58 # include <stdbool.h>
  59 # include <stdint.h>
  60 #endif
  61
  62 #ifdef _WIN32
  63 #include <winsock2.h>
  64 #else
  65 #include <sys/types.h>
  66 #include <sys/socket.h>
  67 #endif
  68
  69 # include "stun/stunagent.h"
  70
  71 # ifdef __cplusplus
  72 extern "C" {
  73 # endif
  74
  75 /**
  76  * StunUsageTurnRequestPorts:
  77  * @STUN_USAGE_TURN_REQUEST_PORT_NORMAL: Request a normal port
  78  * @STUN_USAGE_TURN_REQUEST_PORT_EVEN: Request an even port
  79  * @STUN_USAGE_TURN_REQUEST_PORT_EVEN_AND_RESERVE: Request an even port and
  80  * reserve the next higher port
  81  *
  82  * This enum is used to specify which port configuration you want when creating
  83  * a new Allocation
  84  */
  85 typedef enum {
  86   STUN_USAGE_TURN_REQUEST_PORT_NORMAL = 0,
  87   STUN_USAGE_TURN_REQUEST_PORT_EVEN = 1,
  88   STUN_USAGE_TURN_REQUEST_PORT_EVEN_AND_RESERVE = 2
  89 } StunUsageTurnRequestPorts;
  90
  91 /**
  92  * StunUsageTurnCompatibility:
  93  * @STUN_USAGE_TURN_COMPATIBILITY_DRAFT9: Use the specification compatible with
  94  * TURN Draft 09
  95  * @STUN_USAGE_TURN_COMPATIBILITY_GOOGLE: Use the specification compatible with
  96  * Google Talk's relay server
  97  * @STUN_USAGE_TURN_COMPATIBILITY_MSN: Use the specification compatible with
  98  * MSN TURN servers
  99  * @STUN_USAGE_TURN_COMPATIBILITY_OC2007: Use the specification compatible with
 100  * Microsoft Office Communicator 2007
 101  * @STUN_USAGE_TURN_COMPATIBILITY_RFC5766: Use the specification compatible with
 102  * RFC 5766 (the final, canonical TURN standard)
 103  *
 104  * Specifies which TURN specification compatibility to use
 105  */
 106 typedef enum {
 107   STUN_USAGE_TURN_COMPATIBILITY_DRAFT9,
 108   STUN_USAGE_TURN_COMPATIBILITY_GOOGLE,
 109   STUN_USAGE_TURN_COMPATIBILITY_MSN,
 110   STUN_USAGE_TURN_COMPATIBILITY_OC2007,
 111   STUN_USAGE_TURN_COMPATIBILITY_RFC5766,
 112 } StunUsageTurnCompatibility;
 113
 114 /**
 115  * StunUsageTurnReturn:
 116  * @STUN_USAGE_TURN_RETURN_RELAY_SUCCESS: The response was successful and a relay
 117  * address is provided
 118  * @STUN_USAGE_TURN_RETURN_MAPPED_SUCCESS: The response was successful and a
 119  * relay address as well as a mapped address are provided
 120  * @STUN_USAGE_TURN_RETURN_ERROR: The response resulted in an error
 121  * @STUN_USAGE_TURN_RETURN_INVALID: The response is not a valid response
 122  * @STUN_USAGE_TURN_RETURN_ALTERNATE_SERVER: The server requests the message
 123  * to be sent to an alternate server
 124  *
 125  * Return value of stun_usage_turn_process() and
 126  * stun_usage_turn_refresh_process() which allows you to see what status the
 127  * function call returned.
 128  */
 129 typedef enum {
 130   STUN_USAGE_TURN_RETURN_RELAY_SUCCESS,
 131   STUN_USAGE_TURN_RETURN_MAPPED_SUCCESS,
 132   STUN_USAGE_TURN_RETURN_ERROR,
 133   STUN_USAGE_TURN_RETURN_INVALID,
 134   STUN_USAGE_TURN_RETURN_ALTERNATE_SERVER,
 135 } StunUsageTurnReturn;
 136
 137
 138 /**
 139  * stun_usage_turn_create:
 140  * @agent: The #StunAgent to use to build the request
 141  * @msg: The #StunMessage to build
 142  * @buffer: The buffer to use for creating the #StunMessage
 143  * @buffer_len: The size of the @buffer
 144  * @previous_response: If this is the first request you are sending, set this
 145  * argument to NULL, if it's a subsequent request you are building, then set this
 146  * argument to the response you have received. This argument is used for building
 147  * long term credentials (using the REALM and NONCE attributes) as well as for
 148  * getting the RESERVATION-TOKEN attribute when you previously requested an
 149  * allocation which reserved two ports
 150  * @request_ports: Specify how you want to request the allocated port(s).
 151  * This is only used if the compatibility is set to
 152  * #STUN_USAGE_TURN_COMPATIBILITY_DRAFT9
 153  * <para>See #StunUsageTurnRequestPorts </para>
 154  * @bandwidth: The bandwidth to request from the server for the allocation. If
 155  * this value is negative, then no BANDWIDTH attribute is added to the request.
 156  * This is only used if the compatibility is set to
 157  * #STUN_USAGE_TURN_COMPATIBILITY_DRAFT9
 158  * @lifetime: The lifetime of the allocation to request from the server. If
 159  * this value is negative, then no LIFETIME attribute is added to the request.
 160  * This is only used if the compatibility is set to
 161  * #STUN_USAGE_TURN_COMPATIBILITY_DRAFT9
 162  * @username: The username to use in the request
 163  * @username_len: The length of @username
 164  * @password: The key to use for building the MESSAGE-INTEGRITY
 165  * @password_len: The length of @password
 166  * @compatibility: The compatibility mode to use for building the Allocation
 167  * request
 168  *
 169  * Create a new TURN Allocation request
 170  * Returns: The length of the message to send
 171  */
 172 size_t stun_usage_turn_create (StunAgent *agent, StunMessage *msg,
 173     uint8_t *buffer, size_t buffer_len,
 174     StunMessage *previous_response,
 175     StunUsageTurnRequestPorts request_ports,
 176     int32_t bandwidth, int32_t lifetime,
 177     uint8_t *username, size_t username_len,
 178     uint8_t *password, size_t password_len,
 179     StunUsageTurnCompatibility compatibility);
 180
 181 /**
 182  * stun_usage_turn_create_refresh:
 183  * @agent: The #StunAgent to use to build the request
 184  * @msg: The #StunMessage to build
 185  * @buffer: The buffer to use for creating the #StunMessage
 186  * @buffer_len: The size of the @buffer
 187  * @previous_response: If this is the first request you are sending, set this
 188  * argument to NULL, if it's a subsequent request you are building, then set this
 189  * argument to the response you have received. This argument is used for building
 190  * long term credentials (using the REALM and NONCE attributes)
 191  * @lifetime: The lifetime of the allocation to request from the server. If
 192  * this value is negative, then no LIFETIME attribute is added to the request.
 193  * This is only used if the compatibility is set to
 194  * #STUN_USAGE_TURN_COMPATIBILITY_DRAFT9
 195  * @username: The username to use in the request
 196  * @username_len: The length of @username
 197  * @password: The key to use for building the MESSAGE-INTEGRITY
 198  * @password_len: The length of @password
 199  * @compatibility: The compatibility mode to use for building the Allocation
 200  * request
 201  *
 202  * Create a new TURN Refresh request
 203  * Returns: The length of the message to send
 204  */
 205 size_t stun_usage_turn_create_refresh (StunAgent *agent, StunMessage *msg,
 206     uint8_t *buffer, size_t buffer_len,
 207     StunMessage *previous_response, int32_t lifetime,
 208     uint8_t *username, size_t username_len,
 209     uint8_t *password, size_t password_len,
 210     StunUsageTurnCompatibility compatibility);
 211
 212 /**
 213  * stun_usage_turn_create_permission:
 214  * @agent: The #StunAgent to use to build the request
 215  * @msg: The #StunMessage to build
 216  * @buffer: The buffer to use for creating the #StunMessage
 217  * @buffer_len: The size of the @buffer
 218  * @username: The username to use in the request
 219  * @username_len: The length of @username
 220  * @password: The key to use for building the MESSAGE-INTEGRITY
 221  * @password_len: The length of @password
 222  * @realm: The realm identifier to use in the request
 223  * @realm_len: The length of @realm
 224  * @nonce: Unique and securely random nonce to use in the request
 225  * @nonce_len: The length of @nonce
 226  * @peer: Server-reflexive host address to request permission for
 227  * @compatibility: The compatibility mode to use for building the
 228  * CreatePermission request
 229  *
 230  * Create a new TURN CreatePermission request
 231  *
 232  * Returns: The length of the message to send
 233  */
 234 size_t stun_usage_turn_create_permission (StunAgent *agent, StunMessage *msg,
 235     uint8_t *buffer, size_t buffer_len,
 236     uint8_t *username, size_t username_len,
 237     uint8_t *password, size_t password_len,
 238     uint8_t *realm, size_t realm_len,
 239     uint8_t *nonce, size_t nonce_len,
 240     struct sockaddr_storage *peer,
 241     StunUsageTurnCompatibility compatibility);
 242
 243 /**
 244  * stun_usage_turn_process:
 245  * @msg: The message containing the response
 246  * @relay_addr: A pointer to a #sockaddr structure to fill with the relay address
 247  * that the TURN server allocated for us
 248  * @relay_addrlen: The length of @relay_addr
 249  * @addr: A pointer to a #sockaddr structure to fill with the mapped address
 250  * that the STUN response contains.
 251  * This argument will only be filled if the return value
 252  * of the function is #STUN_USAGE_TURN_RETURN_MAPPED_SUCCESS
 253  * @addrlen: The length of @addr
 254  * @alternate_server: A pointer to a #sockaddr structure to fill with the
 255  * address of an alternate server to which we should send our new STUN
 256  * Allocate request, in case the currently used TURN server is requesting the use
 257  * of an alternate server. This argument will only be filled if the return value
 258  * of the function is #STUN_USAGE_TURN_RETURN_ALTERNATE_SERVER
 259  * In the case of @STUN_USAGE_TURN_COMPATIBILITY_OC2007 compatibility, the
 260  * @alternate_server could be filled at any time, and should only be considered
 261  * if the request was sent to a different server than the address returned
 262  * in the @alternate_server field
 263  * @alternate_server_len: The length of @alternate_server
 264  * @bandwidth: A pointer to fill with the bandwidth the TURN server allocated us
 265  * @lifetime: A pointer to fill with the lifetime of the allocation
 266  * @compatibility: The compatibility mode to use for processing the Allocation
 267  * response
 268  *
 269  * Process a TURN Allocate response and extract the necessary information from
 270  * the message
 271  * Returns: A #StunUsageTurnReturn value
 272  */
 273 StunUsageTurnReturn stun_usage_turn_process (StunMessage *msg,
 274     struct sockaddr_storage *relay_addr, socklen_t *relay_addrlen,
 275     struct sockaddr_storage *addr, socklen_t *addrlen,
 276     struct sockaddr_storage *alternate_server, socklen_t *alternate_server_len,
 277     uint32_t *bandwidth, uint32_t *lifetime,
 278     StunUsageTurnCompatibility compatibility);
 279
 280 /**
 281  * stun_usage_turn_refresh_process:
 282  * @msg: The message containing the response
 283  * @lifetime: A pointer to fill with the lifetime of the allocation
 284  * @compatibility: The compatibility mode to use for processing the Refresh
 285  * response
 286  *
 287  * Process a TURN Refresh response and extract the necessary information from
 288  * the message
 289  * Returns: A #StunUsageTurnReturn value. A #STUN_USAGE_TURN_RETURN_RELAY_SUCCESS
 290  * means the Refresh was successful, but no relay address is given (kept the same
 291  * as for the original allocation)
 292  */
 293 StunUsageTurnReturn stun_usage_turn_refresh_process (StunMessage *msg,
 294     uint32_t *lifetime, StunUsageTurnCompatibility compatibility);
 295
 296
 297 # ifdef __cplusplus
 298 }
 299 # endif
 300
 301 #endif