src/include/gnunet_nat_lib.h

   1 /*
   2      This file is part of GNUnet.
   3      (C) 2007-2014 Christian Grothoff (and other contributing authors)
   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., 59 Temple Place - Suite 330,
  18      Boston, MA 02111-1307, USA.
  19 */
  20
  21 /**
  22  * @file include/gnunet_nat_lib.h
  23  * @brief Library handling UPnP and NAT-PMP port forwarding and
  24  *     external IP address retrieval
  25  * @author Christian Grothoff
  26  * @author Milan Bouchet-Valat
  27  */
  28
  29 #ifndef GNUNET_NAT_LIB_H
  30 #define GNUNET_NAT_LIB_H
  31
  32 #include "gnunet_util_lib.h"
  33
  34
  35 /**
  36  * Signature of the callback passed to #GNUNET_NAT_register() for
  37  * a function to call whenever our set of 'valid' addresses changes.
  38  *
  39  * @param cls closure
  40  * @param add_remove #GNUNET_YES to mean the new public IP address, #GNUNET_NO to mean
  41  *     the previous (now invalid) one
  42  * @param addr either the previous or the new public IP address
  43  * @param addrlen actual length of the @a addr
  44  */
  45 typedef void
  46 (*GNUNET_NAT_AddressCallback) (void *cls,
  47                                int add_remove,
  48                                const struct sockaddr *addr,
  49                                socklen_t addrlen);
  50
  51
  52 /**
  53  * Signature of the callback passed to #GNUNET_NAT_register().
  54  * for a function to call whenever someone asks us to do connection
  55  * reversal.
  56  *
  57  * @param cls closure
  58  * @param addr public IP address of the other peer
  59  * @param addrlen actual lenght of the @a addr
  60  */
  61 typedef void
  62 (*GNUNET_NAT_ReversalCallback) (void *cls,
  63                                 const struct sockaddr *addr,
  64                                 socklen_t addrlen);
  65
  66
  67 /**
  68  * Handle for active NAT registrations.
  69  */
  70 struct GNUNET_NAT_Handle;
  71
  72
  73 /**
  74  * Attempt to enable port redirection and detect public IP address
  75  * contacting UPnP or NAT-PMP routers on the local network. Use addr
  76  * to specify to which of the local host's addresses should the
  77  * external port be mapped. The port is taken from the corresponding
  78  * sockaddr_in[6] field.  The NAT module should call the given
  79  * callback for any 'plausible' external address.
  80  *
  81  * @param cfg configuration to use
  82  * @param is_tcp #GNUNET_YES for TCP, #GNUNET_NO for UDP
  83  * @param adv_port advertised port (port we are either bound to or that our OS
  84  *                 locally performs redirection from to our bound port).
  85  * @param num_addrs number of addresses in @a addrs
  86  * @param addrs list of local addresses packets should be redirected to
  87  * @param addrlens actual lengths of the addresses in @a addrs
  88  * @param address_callback function to call everytime the public IP address changes
  89  * @param reversal_callback function to call if someone wants connection reversal from us,
  90  *        NULL if connection reversal is not supported
  91  * @param callback_cls closure for callbacks
  92  * @return NULL on error, otherwise handle that can be used to unregister
  93  */
  94 struct GNUNET_NAT_Handle *
  95 GNUNET_NAT_register (const struct GNUNET_CONFIGURATION_Handle *cfg,
  96                      int is_tcp,
  97                      uint16_t adv_port,
  98                      unsigned int num_addrs,
  99                      const struct sockaddr **addrs,
 100                      const socklen_t *addrlens,
 101                      GNUNET_NAT_AddressCallback address_callback,
 102                      GNUNET_NAT_ReversalCallback reversal_callback,
 103                      void *callback_cls);
 104
 105
 106 /**
 107  * Test if the given address is (currently) a plausible IP address for
 108  * this peer.
 109  *
 110  * @param h the handle returned by register
 111  * @param addr IP address to test (IPv4 or IPv6)
 112  * @param addrlen number of bytes in @a addr
 113  * @return #GNUNET_YES if the address is plausible,
 114  *         #GNUNET_NO if the address is not plausible,
 115  *         #GNUNET_SYSERR if the address is malformed
 116  */
 117 int
 118 GNUNET_NAT_test_address (struct GNUNET_NAT_Handle *h,
 119                          const void *addr,
 120                          socklen_t addrlen);
 121
 122
 123 /**
 124  * We learned about a peer (possibly behind NAT) so run the
 125  * gnunet-nat-client to send dummy ICMP responses to cause
 126  * that peer to connect to us (connection reversal).
 127  *
 128  * @param h handle (used for configuration)
 129  * @param sa the address of the peer (IPv4-only)
 130  * @return #GNUNET_SYSERR on error, #GNUNET_NO if nat client is disabled,
 131  *         #GNUNET_OK otherwise
 132  */
 133 int
 134 GNUNET_NAT_run_client (struct GNUNET_NAT_Handle *h,
 135                        const struct sockaddr_in *sa);
 136
 137
 138 /**
 139  * Stop port redirection and public IP address detection for the given
 140  * handle.  This frees the handle, after having sent the needed
 141  * commands to close open ports.
 142  *
 143  * @param h the handle to stop
 144  */
 145 void
 146 GNUNET_NAT_unregister (struct GNUNET_NAT_Handle *h);
 147
 148
 149 /**
 150  * Handle to a NAT test.
 151  */
 152 struct GNUNET_NAT_Test;
 153
 154
 155 /**
 156  * Function called to report success or failure for
 157  * NAT configuration test.
 158  *
 159  * @param cls closure
 160  * @param success #GNUNET_OK on success, #GNUNET_NO on failure,
 161  *                #GNUNET_SYSERR if the test could not be
 162  *                properly started (internal failure)
 163  * @param emsg NULL on success, otherwise may include an error message
 164  */
 165 typedef void (*GNUNET_NAT_TestCallback) (void *cls,
 166                                          int success,
 167                                          const char *emsg);
 168
 169
 170 /**
 171  * Start testing if NAT traversal works using the
 172  * given configuration (IPv4-only).
 173  *
 174  * @param cfg configuration for the NAT traversal
 175  * @param is_tcp #GNUNET_YES to test TCP, #GNUNET_NO to test UDP
 176  * @param bnd_port port to bind to, 0 for connection reversal
 177  * @param adv_port externally advertised port to use
 178  * @param report function to call with the result of the test
 179  * @param report_cls closure for @a report
 180  * @return handle to cancel NAT test
 181  */
 182 struct GNUNET_NAT_Test *
 183 GNUNET_NAT_test_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
 184                        int is_tcp,
 185                        uint16_t bnd_port,
 186                        uint16_t adv_port,
 187                        GNUNET_NAT_TestCallback report,
 188                        void *report_cls);
 189
 190
 191 /**
 192  * Stop an active NAT test.
 193  *
 194  * @param tst test to stop.
 195  */
 196 void
 197 GNUNET_NAT_test_stop (struct GNUNET_NAT_Test *tst);
 198
 199
 200 /**
 201  * Signature of a callback that is given an IP address.
 202  *
 203  * @param cls closure
 204  * @param addr the address, NULL on errors
 205  * @param emsg NULL on success, otherwise may include an error message
 206  */
 207 typedef void (*GNUNET_NAT_IPCallback) (void *cls,
 208                                        const struct in_addr *addr,
 209                                        const char *emsg);
 210
 211
 212
 213 /**
 214  * Opaque handle to cancel #GNUNET_NAT_mini_get_external_ipv4() operation.
 215  */
 216 struct GNUNET_NAT_ExternalHandle;
 217
 218
 219 /**
 220  * Try to get the external IPv4 address of this peer.
 221  *
 222  * @param timeout when to fail
 223  * @param cb function to call with result
 224  * @param cb_cls closure for @a cb
 225  * @return handle for cancellation (can only be used until @a cb is called), NULL on error
 226  */
 227 struct GNUNET_NAT_ExternalHandle *
 228 GNUNET_NAT_mini_get_external_ipv4 (struct GNUNET_TIME_Relative timeout,
 229                                    GNUNET_NAT_IPCallback cb,
 230                                    void *cb_cls);
 231
 232
 233 /**
 234  * Cancel operation.
 235  *
 236  * @param eh operation to cancel
 237  */
 238 void
 239 GNUNET_NAT_mini_get_external_ipv4_cancel (struct GNUNET_NAT_ExternalHandle *eh);
 240
 241
 242 /**
 243  * Handle to a mapping created with upnpc.
 244  */
 245 struct GNUNET_NAT_MiniHandle;
 246
 247
 248 /**
 249  * Signature of the callback passed to #GNUNET_NAT_register() for
 250  * a function to call whenever our set of 'valid' addresses changes.
 251  *
 252  * @param cls closure
 253  * @param add_remove #GNUNET_YES to mean the new public IP address, #GNUNET_NO to mean
 254  *     the previous (now invalid) one
 255  * @param addr either the previous or the new public IP address
 256  * @param addrlen actual length of the @a addr
 257  */
 258 typedef void
 259 (*GNUNET_NAT_MiniAddressCallback) (void *cls,
 260                                    int add_remove,
 261                                    const struct sockaddr *addr,
 262                                    socklen_t addrlen,
 263                                    const char *emsg);
 264
 265
 266 /**
 267  * Start mapping the given port using (mini)upnpc.  This function
 268  * should typically not be used directly (it is used within the
 269  * general-purpose #GNUNET_NAT_register() code).  However, it can be
 270  * used if specifically UPnP-based NAT traversal is to be used or
 271  * tested.
 272  *
 273  * @param port port to map
 274  * @param is_tcp #GNUNET_YES to map TCP, #GNUNET_NO for UDP
 275  * @param ac function to call with mapping result
 276  * @param ac_cls closure for @a ac
 277  * @return NULL on error
 278  */
 279 struct GNUNET_NAT_MiniHandle *
 280 GNUNET_NAT_mini_map_start (uint16_t port,
 281                            int is_tcp,
 282                            GNUNET_NAT_MiniAddressCallback ac,
 283                            void *ac_cls);
 284
 285
 286 /**
 287  * Remove a mapping created with (mini)upnpc.  Calling
 288  * this function will give 'upnpc' 1s to remove the mapping,
 289  * so while this function is non-blocking, a task will be
 290  * left with the scheduler for up to 1s past this call.
 291  *
 292  * @param mini the handle
 293  */
 294 void
 295 GNUNET_NAT_mini_map_stop (struct GNUNET_NAT_MiniHandle *mini);
 296
 297
 298 /**
 299  * Handle to auto-configuration in progress.
 300  */
 301 struct GNUNET_NAT_AutoHandle;
 302
 303
 304 /**
 305  * Function called with the result from the autoconfiguration.
 306  *
 307  * @param cls closure
 308  * @param diff minimal suggested changes to the original configuration
 309  *             to make it work (as best as we can)
 310  * @param emsg NULL on success, otherwise may include an error message
 311  */
 312 typedef void
 313 (*GNUNET_NAT_AutoResultCallback)(void *cls,
 314                                  const struct GNUNET_CONFIGURATION_Handle *diff,
 315                                  const char *emsg);
 316
 317
 318 /**
 319  * Start auto-configuration routine.  The resolver service should
 320  * be available when this function is called.
 321  *
 322  * @param cfg initial configuration
 323  * @param cb function to call with autoconfiguration result
 324  * @param cb_cls closure for @a cb
 325  * @return handle to cancel operation
 326  */
 327 struct GNUNET_NAT_AutoHandle *
 328 GNUNET_NAT_autoconfig_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
 329                              GNUNET_NAT_AutoResultCallback cb,
 330                              void *cb_cls);
 331
 332
 333 /**
 334  * Abort autoconfiguration.
 335  *
 336  * @param ah handle for operation to abort
 337  */
 338 void
 339 GNUNET_NAT_autoconfig_cancel (struct GNUNET_NAT_AutoHandle *ah);
 340
 341 #endif
 342
 343 /* end of gnunet_nat_lib.h */