src/include/gnunet_nat_auto_service.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2007-2017 GNUnet e.V.
   4
   5      GNUnet is free software; you can redistribute it and/or modify
   6      it under the terms of the GNU General Public License as published
   7      by the Free Software Foundation; either version 3, or (at your
   8      option) any later version.
   9
  10      GNUnet is distributed in the hope that it will be useful, but
  11      WITHOUT ANY WARRANTY; without even the implied warranty of
  12      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13      General Public License for more details.
  14
  15      You should have received a copy of the GNU General Public License
  16      along with GNUnet; see the file COPYING.  If not, write to the
  17      Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18      Boston, MA 02110-1301, USA.
  19 */
  20
  21 /**
  22  * @author Christian Grothoff
  23  * @author Milan Bouchet-Valat
  24  *
  25  * @file
  26  * Service for testing and autoconfiguration of
  27  * NAT traversal functionality
  28  *
  29  * @defgroup nat  NAT testing library
  30  *
  31  * @{
  32  */
  33
  34 #ifndef GNUNET_NAT_AUTO_SERVICE_H
  35 #define GNUNET_NAT_AUTO_SERVICE_H
  36
  37 #include "gnunet_util_lib.h"
  38
  39
  40 /**
  41  * Handle to a NAT test.
  42  */
  43 struct GNUNET_NAT_Test;
  44
  45
  46 /**
  47  * Function called to report success or failure for
  48  * NAT configuration test.
  49  *
  50  * @param cls closure
  51  * @param result #GNUNET_NAT_ERROR_SUCCESS on success, otherwise the specific error code
  52  */
  53 typedef void
  54 (*GNUNET_NAT_TestCallback) (void *cls,
  55                             enum GNUNET_NAT_StatusCode result);
  56
  57
  58 /**
  59  * Handle an incoming STUN message.  This function is useful as
  60  * some GNUnet service may be listening on a UDP port and might
  61  * thus receive STUN messages while trying to receive other data.
  62  * In this case, this function can be used to process replies
  63  * to STUN requests.
  64  *
  65  * The function does some basic sanity checks on packet size and
  66  * content, try to extract a bit of information.
  67  *
  68  * At the moment this only processes BIND requests, and returns the
  69  * externally visible address of the request to the rest of the
  70  * NAT logic.
  71  *
  72  * @param nh handle to the NAT service
  73  * @param sender_addr address from which we got @a data
  74  * @param sender_addr_len number of bytes in @a sender_addr
  75  * @param data the packet
  76  * @param data_size number of bytes in @a data
  77  * @return #GNUNET_OK on success
  78  *         #GNUNET_NO if the packet is not a STUN packet
  79  *         #GNUNET_SYSERR on internal error handling the packet
  80  */
  81 int
  82 GNUNET_NAT_stun_handle_packet (struct GNUNET_NAT_Handle *nh,
  83                                const struct sockaddr *sender_addr,
  84                                size_t sender_addr_len,
  85                                const void *data,
  86                                size_t data_size);
  87
  88
  89 /**
  90  * Handle to a request given to the resolver.  Can be used to cancel
  91  * the request prior to the timeout or successful execution.  Also
  92  * used to track our internal state for the request.
  93  */
  94 struct GNUNET_NAT_STUN_Handle;
  95
  96
  97 /**
  98  * Make Generic STUN request. Sends a generic stun request to the
  99  * server specified using the specified socket.  If we do this,
 100  * we need to watch for possible responses and call
 101  * #GNUNET_NAT_stun_handle_packet() on incoming packets.
 102  *
 103  * @param server the address of the stun server
 104  * @param port port of the stun server, in host byte order
 105  * @param sock the socket used to send the request, must be a
 106  *             UDP socket
 107  * @param cb callback in case of error
 108  * @param cb_cls closure for @a cb
 109  * @return NULL on error
 110  */
 111 struct GNUNET_NAT_STUN_Handle *
 112 GNUNET_NAT_stun_make_request (const char *server,
 113                               uint16_t port,
 114                               struct GNUNET_NETWORK_Handle *sock,
 115                               GNUNET_NAT_TestCallback cb,
 116                               void *cb_cls);
 117
 118
 119 /**
 120  * Cancel active STUN request. Frees associated resources
 121  * and ensures that the callback is no longer invoked.
 122  *
 123  * @param rh request to cancel
 124  */
 125 void
 126 GNUNET_NAT_stun_make_request_cancel (struct GNUNET_NAT_STUN_Handle *rh);
 127
 128
 129 /**
 130  * Start testing if NAT traversal works using the given configuration
 131  * (IPv4-only).  The transport adapters should be down while using
 132  * this function.
 133  *
 134  * @param cfg configuration for the NAT traversal
 135  * @param proto protocol to test, i.e. IPPROTO_TCP or IPPROTO_UDP
 136  * @param bind_ip IPv4 address to bind to
 137  * @param bnd_port port to bind to, 0 to test connection reversal
 138  * @param extern_ip IPv4 address to externally advertise
 139  * @param extern_port externally advertised port to use
 140  * @param report function to call with the result of the test
 141  * @param report_cls closure for @a report
 142  * @return handle to cancel NAT test
 143  */
 144 struct GNUNET_NAT_Test *
 145 GNUNET_NAT_test_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
 146                        uint8_t proto,
 147                        struct in_addr bind_ip,
 148                        uint16_t bnd_port,
 149                        struct in_addr extern_ip,
 150                        uint16_t extern_port,
 151                        GNUNET_NAT_TestCallback report,
 152                        void *report_cls);
 153
 154
 155 /**
 156  * Stop an active NAT test.
 157  *
 158  * @param tst test to stop.
 159  */
 160 void
 161 GNUNET_NAT_test_stop (struct GNUNET_NAT_Test *tst);
 162
 163
 164 /**
 165  * Handle to auto-configuration in progress.
 166  */
 167 struct GNUNET_NAT_AutoHandle;
 168
 169
 170 /**
 171  * Converts `enum GNUNET_NAT_StatusCode` to string
 172  *
 173  * @param err error code to resolve to a string
 174  * @return point to a static string containing the error code
 175  */
 176 const char *
 177 GNUNET_NAT_status2string (enum GNUNET_NAT_StatusCode err);
 178
 179
 180 /**
 181  * Function called with the result from the autoconfiguration.
 182  *
 183  * @param cls closure
 184  * @param diff minimal suggested changes to the original configuration
 185  *             to make it work (as best as we can)
 186  * @param result #GNUNET_NAT_ERROR_SUCCESS on success, otherwise the specific error code
 187  * @param type what the situation of the NAT
 188  */
 189 typedef void
 190 (*GNUNET_NAT_AutoResultCallback)(void *cls,
 191                                  const struct GNUNET_CONFIGURATION_Handle *diff,
 192                                  enum GNUNET_NAT_StatusCode result,
 193                                  enum GNUNET_NAT_Type type);
 194
 195
 196 /**
 197  * Start auto-configuration routine.  The transport adapters should
 198  * be stopped while this function is called.
 199  *
 200  * @param cfg initial configuration
 201  * @param cb function to call with autoconfiguration result
 202  * @param cb_cls closure for @a cb
 203  * @return handle to cancel operation
 204  */
 205 struct GNUNET_NAT_AutoHandle *
 206 GNUNET_NAT_autoconfig_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
 207                              GNUNET_NAT_AutoResultCallback cb,
 208                              void *cb_cls);
 209
 210
 211 /**
 212  * Abort autoconfiguration.
 213  *
 214  * @param ah handle for operation to abort
 215  */
 216 void
 217 GNUNET_NAT_autoconfig_cancel (struct GNUNET_NAT_AutoHandle *ah);
 218
 219
 220 #endif
 221
 222 /** @} */  /* end of group */
 223
 224 /* end of gnunet_nat_auto_service.h */