2 This file is part of GNUnet.
3 (C) 2007-2014 Christian Grothoff (and other contributing authors)
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.
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.
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.
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
29 #ifndef GNUNET_NAT_LIB_H
30 #define GNUNET_NAT_LIB_H
32 #include "gnunet_util_lib.h"
36 * Signature of the callback passed to #GNUNET_NAT_register() for
37 * a function to call whenever our set of 'valid' addresses changes.
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
46 (*GNUNET_NAT_AddressCallback) (void *cls,
48 const struct sockaddr *addr,
53 * Signature of the callback passed to #GNUNET_NAT_register().
54 * for a function to call whenever someone asks us to do connection
58 * @param addr public IP address of the other peer
59 * @param addrlen actual lenght of the @a addr
62 (*GNUNET_NAT_ReversalCallback) (void *cls,
63 const struct sockaddr *addr,
68 * Handle for active NAT registrations.
70 struct GNUNET_NAT_Handle;
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.
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
94 struct GNUNET_NAT_Handle *
95 GNUNET_NAT_register (const struct GNUNET_CONFIGURATION_Handle *cfg,
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,
107 * Test if the given address is (currently) a plausible IP address for
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
118 GNUNET_NAT_test_address (struct GNUNET_NAT_Handle *h,
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).
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
134 GNUNET_NAT_run_client (struct GNUNET_NAT_Handle *h,
135 const struct sockaddr_in *sa);
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.
143 * @param h the handle to stop
146 GNUNET_NAT_unregister (struct GNUNET_NAT_Handle *h);
150 * Handle to a NAT test.
152 struct GNUNET_NAT_Test;
156 * Function called to report success or failure for
157 * NAT configuration test.
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
165 typedef void (*GNUNET_NAT_TestCallback) (void *cls,
171 * Start testing if NAT traversal works using the
172 * given configuration (IPv4-only).
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
182 struct GNUNET_NAT_Test *
183 GNUNET_NAT_test_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
187 GNUNET_NAT_TestCallback report,
192 * Stop an active NAT test.
194 * @param tst test to stop.
197 GNUNET_NAT_test_stop (struct GNUNET_NAT_Test *tst);
201 * Signature of a callback that is given an IP address.
204 * @param addr the address, NULL on errors
205 * @param emsg NULL on success, otherwise may include an error message
207 typedef void (*GNUNET_NAT_IPCallback) (void *cls,
208 const struct in_addr *addr,
214 * Opaque handle to cancel #GNUNET_NAT_mini_get_external_ipv4() operation.
216 struct GNUNET_NAT_ExternalHandle;
220 * Try to get the external IPv4 address of this peer.
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
227 struct GNUNET_NAT_ExternalHandle *
228 GNUNET_NAT_mini_get_external_ipv4 (struct GNUNET_TIME_Relative timeout,
229 GNUNET_NAT_IPCallback cb,
236 * @param eh operation to cancel
239 GNUNET_NAT_mini_get_external_ipv4_cancel (struct GNUNET_NAT_ExternalHandle *eh);
243 * Handle to a mapping created with upnpc.
245 struct GNUNET_NAT_MiniHandle;
249 * Signature of the callback passed to #GNUNET_NAT_register() for
250 * a function to call whenever our set of 'valid' addresses changes.
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
259 (*GNUNET_NAT_MiniAddressCallback) (void *cls,
261 const struct sockaddr *addr,
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
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
279 struct GNUNET_NAT_MiniHandle *
280 GNUNET_NAT_mini_map_start (uint16_t port,
282 GNUNET_NAT_MiniAddressCallback ac,
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.
292 * @param mini the handle
295 GNUNET_NAT_mini_map_stop (struct GNUNET_NAT_MiniHandle *mini);
299 * Handle to auto-configuration in progress.
301 struct GNUNET_NAT_AutoHandle;
305 * Function called with the result from the autoconfiguration.
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
313 (*GNUNET_NAT_AutoResultCallback)(void *cls,
314 const struct GNUNET_CONFIGURATION_Handle *diff,
319 * Start auto-configuration routine. The resolver service should
320 * be available when this function is called.
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
327 struct GNUNET_NAT_AutoHandle *
328 GNUNET_NAT_autoconfig_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
329 GNUNET_NAT_AutoResultCallback cb,
334 * Abort autoconfiguration.
336 * @param ah handle for operation to abort
339 GNUNET_NAT_autoconfig_cancel (struct GNUNET_NAT_AutoHandle *ah);
343 /* end of gnunet_nat_lib.h */