src/include/gnunet_nat_service.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2007-2016 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 handling UPnP and NAT-PMP port forwarding
  27  * and external IP address retrieval
  28  *
  29  * @defgroup nat  NAT library
  30  * Service for handling UPnP and NAT-PMP port forwarding
  31  * and external IP address retrieval
  32  *
  33  * @{
  34  */
  35
  36 #ifndef GNUNET_NAT_SERVICE_H
  37 #define GNUNET_NAT_SERVICE_H
  38
  39 #include "gnunet_util_lib.h"
  40
  41
  42 /**
  43  * Some addresses contain sensitive information or are
  44  * not suitable for global distribution.  We use address
  45  * classes to filter addresses by which domain they make
  46  * sense to be used in.  These are used in a bitmask.
  47  *
  48  * FIXME: might want to define this elsewhere; we have
  49  * an equivalent enum in gnunet_transport_hello_service.h;
  50  * might ultimately belong with the new HELLO definition.
  51  */
  52 enum GNUNET_NAT_AddressClass
  53 {
  54
  55   /**
  56    * No address.
  57    */
  58   GNUNET_NAT_AC_NONE = 0,
  59
  60   /**
  61    * Addresses that fall into no other category
  62    * (i.e. incoming which we cannot use elsewhere).
  63    */
  64   GNUNET_NAT_AC_OTHER = 1,
  65
  66   /**
  67    * Flag for addresses that are highly sensitive
  68    * (i.e. IPv6 with our MAC).
  69    */
  70   GNUNET_NAT_AC_PRIVATE = 2,
  71
  72   /**
  73    * Addresses that are global (i.e. IPv4).
  74    */
  75   GNUNET_NAT_AC_GLOBAL = 4,
  76
  77   /**
  78    * Addresses that are global and are sensitive
  79    * (i.e. IPv6 with our MAC).
  80    */
  81   GNUNET_NAT_AC_GLOBAL_PRIVATE = 6,
  82
  83   /**
  84    * Addresses useful in the local wired network,
  85    * i.e. a MAC.  Sensitive, but obvious to people nearby.
  86
  87    * Useful for broadcasts.
  88    */
  89   GNUNET_NAT_AC_LAN = 8,
  90
  91   /**
  92    * Addresses useful in the local wired network,
  93    * i.e. a MAC.  Sensitive, but obvious to people nearby.
  94    * Useful for broadcasts.
  95    */
  96   GNUNET_NAT_AC_LAN_PRIVATE = 10,
  97
  98   /**
  99    * Addresses useful in the local wireless network,
 100    * i.e. a MAC.  Sensitive, but obvious to people nearby.
 101    * Useful for broadcasts.
 102    */
 103   GNUNET_NAT_AC_WLAN = 16,
 104
 105   /**
 106    * Addresses useful in the local bluetooth network.  Sensitive, but
 107    * obvious to people nearby.  Useful for broadcasts.
 108    */
 109   GNUNET_NAT_AC_BT = 32,
 110
 111   /**
 112    * Loopback addresses, only useful under special cirumstances.
 113    */
 114   GNUNET_NAT_AC_LOOPBACK = 64,
 115
 116   /**
 117    * Addresses that should be our global external IP address
 118    * on the outside of a NAT.  Might be incorrectly determined.
 119    * Used as a bit in combination with #GNUNET_NAT_AC_GLOBAL.
 120    */
 121   GNUNET_NAT_AC_GLOBAL_EXTERN = 128,
 122
 123   /**
 124    * Bitmask for "any" address.
 125    */
 126   GNUNET_NAT_AC_ANY = 65535
 127
 128 };
 129
 130
 131 /**
 132  * Signature of the callback passed to #GNUNET_NAT_register() for
 133  * a function to call whenever our set of 'valid' addresses changes.
 134  *
 135  * @param cls closure
 136  * @param add_remove #GNUNET_YES to add a new public IP address,
 137  *                   #GNUNET_NO to remove a previous (now invalid) one
 138  * @param ac address class the address belongs to
 139  * @param addr either the previous or the new public IP address
 140  * @param addrlen actual length of the @a addr
 141  */
 142 typedef void
 143 (*GNUNET_NAT_AddressCallback) (void *cls,
 144                                int add_remove,
 145                                enum GNUNET_NAT_AddressClass ac,
 146                                const struct sockaddr *addr,
 147                                socklen_t addrlen);
 148
 149
 150 /**
 151  * Signature of the callback passed to #GNUNET_NAT_register().
 152  * for a function to call whenever someone asks us to do connection
 153  * reversal.
 154  *
 155  * @param cls closure
 156  * @param local_addr address where we received the request
 157  * @param local_addrlen actual length of the @a local_addr
 158  * @param remote_addr public IP address of the other peer
 159  * @param remote_addrlen actual length of the @a remote_addr
 160  */
 161 typedef void
 162 (*GNUNET_NAT_ReversalCallback) (void *cls,
 163                                 const struct sockaddr *local_addr,
 164                                 socklen_t local_addrlen,
 165                                 const struct sockaddr *remote_addr,
 166                                 socklen_t remote_addrlen);
 167
 168
 169 /**
 170  * Handle for active NAT registrations.
 171  */
 172 struct GNUNET_NAT_Handle;
 173
 174
 175 /**
 176  * Attempt to enable port redirection and detect public IP address
 177  * contacting UPnP or NAT-PMP routers on the local network. Use @a
 178  * addr to specify to which of the local host's addresses should the
 179  * external port be mapped. The port is taken from the corresponding
 180  * sockaddr_in[6] field.  The NAT module should call the given @a
 181  * address_callback for any 'plausible' external address.
 182  *
 183  * @param cfg configuration to use
 184  * @param proto protocol this is about, IPPROTO_TCP or IPPROTO_UDP
 185  * @param adv_port advertised port (port we are either bound to or that our OS
 186  *                 locally performs redirection from to our bound port).
 187  * @param num_addrs number of addresses in @a addrs
 188  * @param addrs list of local addresses packets should be redirected to
 189  * @param addrlens actual lengths of the addresses in @a addrs
 190  * @param address_callback function to call everytime the public IP address changes
 191  * @param reversal_callback function to call if someone wants connection reversal from us,
 192  *        NULL if connection reversal is not supported
 193  * @param callback_cls closure for callbacks
 194  * @return NULL on error, otherwise handle that can be used to unregister
 195  */
 196 struct GNUNET_NAT_Handle *
 197 GNUNET_NAT_register (const struct GNUNET_CONFIGURATION_Handle *cfg,
 198                      uint8_t proto,
 199                      uint16_t adv_port,
 200                      unsigned int num_addrs,
 201                      const struct sockaddr **addrs,
 202                      const socklen_t *addrlens,
 203                      GNUNET_NAT_AddressCallback address_callback,
 204                      GNUNET_NAT_ReversalCallback reversal_callback,
 205                      void *callback_cls);
 206
 207
 208 /**
 209  * Test if the given address is (currently) a plausible IP address for
 210  * this peer.  Mostly a convenience function so that clients do not
 211  * have to explicitly track all IPs that the #GNUNET_NAT_AddressCallback
 212  * has returned so far.
 213  *
 214  * @param nh the handle returned by register
 215  * @param addr IP address to test (IPv4 or IPv6)
 216  * @param addrlen number of bytes in @a addr
 217  * @return #GNUNET_YES if the address is plausible,
 218  *         #GNUNET_NO if the address is not plausible,
 219  *         #GNUNET_SYSERR if the address is malformed
 220  */
 221 int
 222 GNUNET_NAT_test_address (struct GNUNET_NAT_Handle *nh,
 223                          const void *addr,
 224                          socklen_t addrlen);
 225
 226
 227 /**
 228  * We learned about a peer (possibly behind NAT) so run the
 229  * gnunet-nat-client to send dummy ICMP responses to cause
 230  * that peer to connect to us (connection reversal).
 231  *
 232  * @param nh handle (used for configuration)
 233  * @param local_sa our local address of the peer (IPv4-only)
 234  * @param remote_sa the remote address of the peer (IPv4-only)
 235  * @return #GNUNET_SYSERR on error,
 236  *         #GNUNET_NO if connection reversal is unavailable,
 237  *         #GNUNET_OK otherwise (presumably in progress)
 238  */
 239 int
 240 GNUNET_NAT_request_reversal (struct GNUNET_NAT_Handle *nh,
 241                              const struct sockaddr_in *local_sa,
 242                              const struct sockaddr_in *remote_sa);
 243
 244
 245 /**
 246  * Stop port redirection and public IP address detection for the given
 247  * handle.  This frees the handle, after having sent the needed
 248  * commands to close open ports.
 249  *
 250  * @param nh the handle to unregister
 251  */
 252 void
 253 GNUNET_NAT_unregister (struct GNUNET_NAT_Handle *nh);
 254
 255
 256 /**
 257  * Handle to a NAT test.
 258  */
 259 struct GNUNET_NAT_Test;
 260
 261
 262 /**
 263  * Error Types for the NAT subsystem (which can then later be converted/resolved to a string)
 264  */
 265 enum GNUNET_NAT_StatusCode
 266 {
 267   /**
 268    * Just the default
 269    */
 270   GNUNET_NAT_ERROR_SUCCESS = GNUNET_OK,
 271
 272   /**
 273    * IPC Failure
 274    */
 275   GNUNET_NAT_ERROR_IPC_FAILURE,
 276
 277   /**
 278    * Failure in network subsystem, check permissions
 279    */
 280   GNUNET_NAT_ERROR_INTERNAL_NETWORK_ERROR,
 281
 282   /**
 283    * test timed out
 284    */
 285   GNUNET_NAT_ERROR_TIMEOUT,
 286
 287   /**
 288    * detected that we are offline
 289    */
 290   GNUNET_NAT_ERROR_NOT_ONLINE,
 291
 292   /**
 293    * `upnpc` command not found
 294    */
 295   GNUNET_NAT_ERROR_UPNPC_NOT_FOUND,
 296
 297   /**
 298    * Failed to run `upnpc` command
 299    */
 300   GNUNET_NAT_ERROR_UPNPC_FAILED,
 301
 302   /**
 303    * `upnpc' command took too long, process killed
 304    */
 305   GNUNET_NAT_ERROR_UPNPC_TIMEOUT,
 306
 307   /**
 308    * `upnpc' command failed to establish port mapping
 309    */
 310   GNUNET_NAT_ERROR_UPNPC_PORTMAP_FAILED,
 311
 312   /**
 313    * `external-ip' command not found
 314    */
 315   GNUNET_NAT_ERROR_EXTERNAL_IP_UTILITY_NOT_FOUND,
 316
 317   /**
 318    * Failed to run `external-ip` command
 319    */
 320   GNUNET_NAT_ERROR_EXTERNAL_IP_UTILITY_FAILED,
 321
 322   /**
 323    * `external-ip' command output invalid
 324    */
 325   GNUNET_NAT_ERROR_EXTERNAL_IP_UTILITY_OUTPUT_INVALID,
 326
 327   /**
 328    * "no valid address was returned by `external-ip'"
 329    */
 330   GNUNET_NAT_ERROR_EXTERNAL_IP_ADDRESS_INVALID,
 331
 332   /**
 333    * Could not determine interface with internal/local network address
 334    */
 335   GNUNET_NAT_ERROR_NO_VALID_IF_IP_COMBO,
 336
 337   /**
 338    * No working gnunet-helper-nat-server found
 339    */
 340   GNUNET_NAT_ERROR_HELPER_NAT_SERVER_NOT_FOUND,
 341
 342   /**
 343    * NAT test could not be initialized
 344    */
 345   GNUNET_NAT_ERROR_NAT_TEST_START_FAILED,
 346
 347   /**
 348    * NAT test timeout
 349    */
 350   GNUNET_NAT_ERROR_NAT_TEST_TIMEOUT,
 351
 352   /**
 353    * NAT test failed to initiate
 354    */
 355   GNUNET_NAT_ERROR_NAT_REGISTER_FAILED,
 356
 357   /**
 358    *
 359    */
 360   GNUNET_NAT_ERROR_HELPER_NAT_CLIENT_NOT_FOUND
 361
 362 };
 363
 364
 365 /**
 366  * Function called to report success or failure for
 367  * NAT configuration test.
 368  *
 369  * @param cls closure
 370  * @param result #GNUNET_NAT_ERROR_SUCCESS on success, otherwise the specific error code
 371  */
 372 typedef void
 373 (*GNUNET_NAT_TestCallback) (void *cls,
 374                             enum GNUNET_NAT_StatusCode result);
 375
 376
 377 /**
 378  * Handle an incoming STUN message.  This function is useful as
 379  * some GNUnet service may be listening on a UDP port and might
 380  * thus receive STUN messages while trying to receive other data.
 381  * In this case, this function can be used to process replies
 382  * to STUN requests.
 383  *
 384  * The function does some basic sanity checks on packet size and
 385  * content, try to extract a bit of information.
 386  *
 387  * At the moment this only processes BIND requests, and returns the
 388  * externally visible address of the request to the rest of the
 389  * NAT logic.
 390  *
 391  * @param nh handle to the NAT service
 392  * @param sender_addr address from which we got @a data
 393  * @param sender_addr_len number of bytes in @a sender_addr
 394  * @param data the packet
 395  * @param data_size number of bytes in @a data
 396  * @return #GNUNET_OK on success
 397  *         #GNUNET_NO if the packet is not a STUN packet
 398  *         #GNUNET_SYSERR on internal error handling the packet
 399  */
 400 int
 401 GNUNET_NAT_stun_handle_packet (struct GNUNET_NAT_Handle *nh,
 402                                const struct sockaddr *sender_addr,
 403                                size_t sender_addr_len,
 404                                const void *data,
 405                                size_t data_size);
 406
 407
 408 /**
 409  * Handle to a request given to the resolver.  Can be used to cancel
 410  * the request prior to the timeout or successful execution.  Also
 411  * used to track our internal state for the request.
 412  */
 413 struct GNUNET_NAT_STUN_Handle;
 414
 415
 416 /**
 417  * Make Generic STUN request. Sends a generic stun request to the
 418  * server specified using the specified socket.  If we do this,
 419  * we need to watch for possible responses and call
 420  * #GNUNET_NAT_stun_handle_packet() on incoming packets.
 421  *
 422  * @param server the address of the stun server
 423  * @param port port of the stun server, in host byte order
 424  * @param sock the socket used to send the request, must be a
 425  *             UDP socket
 426  * @param cb callback in case of error
 427  * @param cb_cls closure for @a cb
 428  * @return NULL on error
 429  */
 430 struct GNUNET_NAT_STUN_Handle *
 431 GNUNET_NAT_stun_make_request (const char *server,
 432                               uint16_t port,
 433                               struct GNUNET_NETWORK_Handle *sock,
 434                               GNUNET_NAT_TestCallback cb,
 435                               void *cb_cls);
 436
 437
 438 /**
 439  * Cancel active STUN request. Frees associated resources
 440  * and ensures that the callback is no longer invoked.
 441  *
 442  * @param rh request to cancel
 443  */
 444 void
 445 GNUNET_NAT_stun_make_request_cancel (struct GNUNET_NAT_STUN_Handle *rh);
 446
 447
 448 /**
 449  * Start testing if NAT traversal works using the given configuration
 450  * (IPv4-only).  The transport adapters should be down while using
 451  * this function.
 452  *
 453  * @param cfg configuration for the NAT traversal
 454  * @param proto protocol to test, i.e. IPPROTO_TCP or IPPROTO_UDP
 455  * @param bind_ip IPv4 address to bind to
 456  * @param bnd_port port to bind to, 0 to test connection reversal
 457  * @param extern_ip IPv4 address to externally advertise
 458  * @param extern_port externally advertised port to use
 459  * @param report function to call with the result of the test
 460  * @param report_cls closure for @a report
 461  * @return handle to cancel NAT test
 462  */
 463 struct GNUNET_NAT_Test *
 464 GNUNET_NAT_test_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
 465                        uint8_t proto,
 466                        struct in_addr bind_ip,
 467                        uint16_t bnd_port,
 468                        struct in_addr extern_ip,
 469                        uint16_t extern_port,
 470                        GNUNET_NAT_TestCallback report,
 471                        void *report_cls);
 472
 473
 474 /**
 475  * Stop an active NAT test.
 476  *
 477  * @param tst test to stop.
 478  */
 479 void
 480 GNUNET_NAT_test_stop (struct GNUNET_NAT_Test *tst);
 481
 482
 483 /**
 484  * Handle to auto-configuration in progress.
 485  */
 486 struct GNUNET_NAT_AutoHandle;
 487
 488
 489 /**
 490  * What the situation of the NAT connectivity
 491  */
 492 enum GNUNET_NAT_Type
 493 {
 494   /**
 495    * We have a direct connection
 496    */
 497   GNUNET_NAT_TYPE_NO_NAT = GNUNET_OK,
 498
 499   /**
 500    * We are under a NAT but cannot traverse it
 501    */
 502   GNUNET_NAT_TYPE_UNREACHABLE_NAT,
 503
 504   /**
 505    * We can traverse using STUN
 506    */
 507   GNUNET_NAT_TYPE_STUN_PUNCHED_NAT,
 508
 509   /**
 510    * We can traverse using UPNP
 511    */
 512   GNUNET_NAT_TYPE_UPNP_NAT,
 513
 514   /**
 515    * We know nothing about the NAT.
 516    */
 517   GNUNET_NAT_TYPE_UNKNOWN
 518
 519 };
 520
 521
 522 /**
 523  * Converts `enum GNUNET_NAT_StatusCode` to string
 524  *
 525  * @param err error code to resolve to a string
 526  * @return point to a static string containing the error code
 527  */
 528 const char *
 529 GNUNET_NAT_status2string (enum GNUNET_NAT_StatusCode err);
 530
 531
 532 /**
 533  * Function called with the result from the autoconfiguration.
 534  *
 535  * @param cls closure
 536  * @param diff minimal suggested changes to the original configuration
 537  *             to make it work (as best as we can)
 538  * @param result #GNUNET_NAT_ERROR_SUCCESS on success, otherwise the specific error code
 539  * @param type what the situation of the NAT
 540  */
 541 typedef void
 542 (*GNUNET_NAT_AutoResultCallback)(void *cls,
 543                                  const struct GNUNET_CONFIGURATION_Handle *diff,
 544                                  enum GNUNET_NAT_StatusCode result,
 545                                  enum GNUNET_NAT_Type type);
 546
 547
 548 /**
 549  * Start auto-configuration routine.  The transport adapters should
 550  * be stopped while this function is called.
 551  *
 552  * @param cfg initial configuration
 553  * @param cb function to call with autoconfiguration result
 554  * @param cb_cls closure for @a cb
 555  * @return handle to cancel operation
 556  */
 557 struct GNUNET_NAT_AutoHandle *
 558 GNUNET_NAT_autoconfig_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
 559                              GNUNET_NAT_AutoResultCallback cb,
 560                              void *cb_cls);
 561
 562
 563 /**
 564  * Abort autoconfiguration.
 565  *
 566  * @param ah handle for operation to abort
 567  */
 568 void
 569 GNUNET_NAT_autoconfig_cancel (struct GNUNET_NAT_AutoHandle *ah);
 570
 571
 572 #endif
 573
 574 /** @} */  /* end of group */
 575
 576 /* end of gnunet_nat_service.h */