diff options
author | Christian Grothoff <christian@grothoff.org> | 2016-10-23 17:11:37 +0000 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2016-10-23 17:11:37 +0000 |
commit | 0639111c675f7caddb777e8690eefc1cc383bff4 (patch) | |
tree | ea642ec1894b20632a1118768bf709ee40e0bd51 /src/include/gnunet_nat_service.h | |
parent | 48f8bbc215fc84a295993fb5bc529a9fe9b11b7e (diff) | |
download | gnunet-0639111c675f7caddb777e8690eefc1cc383bff4.tar.gz gnunet-0639111c675f7caddb777e8690eefc1cc383bff4.zip |
design for new NAT service API
Diffstat (limited to 'src/include/gnunet_nat_service.h')
-rw-r--r-- | src/include/gnunet_nat_service.h | 514 |
1 files changed, 514 insertions, 0 deletions
diff --git a/src/include/gnunet_nat_service.h b/src/include/gnunet_nat_service.h new file mode 100644 index 000000000..5ac936065 --- /dev/null +++ b/src/include/gnunet_nat_service.h | |||
@@ -0,0 +1,514 @@ | |||
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 | * Addresses that are global and are insensitive | ||
68 | * (i.e. IPv4). | ||
69 | */ | ||
70 | GNUNET_NAT_AC_GLOBAL = 2, | ||
71 | |||
72 | /** | ||
73 | * Addresses that are global and are sensitive | ||
74 | * (i.e. IPv6 with our MAC). | ||
75 | */ | ||
76 | GNUNET_NAT_AC_GLOBAL_PRIVATE = 4, | ||
77 | |||
78 | /** | ||
79 | * Addresses useful in the local wired network, | ||
80 | * i.e. a MAC. Sensitive, but obvious to people nearby. | ||
81 | * Useful for broadcasts. | ||
82 | */ | ||
83 | GNUNET_NAT_AC_LAN = 8, | ||
84 | |||
85 | /** | ||
86 | * Addresses useful in the local wireless network, | ||
87 | * i.e. a MAC. Sensitive, but obvious to people nearby. | ||
88 | * Useful for broadcasts. | ||
89 | */ | ||
90 | GNUNET_NAT_AC_WLAN = 16, | ||
91 | |||
92 | /** | ||
93 | * Addresses useful in the local bluetooth network. Sensitive, but | ||
94 | * obvious to people nearby. Useful for broadcasts. | ||
95 | */ | ||
96 | GNUNET_NAT_AC_BT = 32, | ||
97 | |||
98 | /** | ||
99 | * Bitmask for "any" address. | ||
100 | */ | ||
101 | GNUNET_NAT_AC_ANY = 65535 | ||
102 | |||
103 | }; | ||
104 | |||
105 | |||
106 | /** | ||
107 | * Signature of the callback passed to #GNUNET_NAT_register() for | ||
108 | * a function to call whenever our set of 'valid' addresses changes. | ||
109 | * | ||
110 | * @param cls closure | ||
111 | * @param add_remove #GNUNET_YES to add a new public IP address, #GNUNET_NO to remove a previous (now invalid) one | ||
112 | * @param ac address class the address belongs to | ||
113 | * @param addr either the previous or the new public IP address | ||
114 | * @param addrlen actual length of the @a addr | ||
115 | */ | ||
116 | typedef void | ||
117 | (*GNUNET_NAT_AddressCallback) (void *cls, | ||
118 | int add_remove, | ||
119 | enum GNUNET_NAT_AddressClass ac, | ||
120 | const struct sockaddr *addr, | ||
121 | socklen_t addrlen); | ||
122 | |||
123 | |||
124 | /** | ||
125 | * Signature of the callback passed to #GNUNET_NAT_register(). | ||
126 | * for a function to call whenever someone asks us to do connection | ||
127 | * reversal. | ||
128 | * | ||
129 | * @param cls closure | ||
130 | * @param addr public IP address of the other peer | ||
131 | * @param addrlen actual lenght of the @a addr | ||
132 | */ | ||
133 | typedef void | ||
134 | (*GNUNET_NAT_ReversalCallback) (void *cls, | ||
135 | const struct sockaddr *addr, | ||
136 | socklen_t addrlen); | ||
137 | |||
138 | |||
139 | /** | ||
140 | * Signature of a callback that is given an IPv4 address | ||
141 | * which is now presumably a global IPv4 address under which | ||
142 | * this peer is visible (external IP address of our NAT). | ||
143 | * Note that the NAT may not have punched holes, so it is | ||
144 | * possible that while this is "our" IPv4 address, it still | ||
145 | * does not work for receiving traffic. | ||
146 | * | ||
147 | * @param cls closure | ||
148 | * @param add_remove #GNUNET_YES to add a new public IP address, #GNUNET_NO to remove a previous (now invalid) one | ||
149 | * @param addr the address to add or remove | ||
150 | */ | ||
151 | typedef void | ||
152 | (*GNUNET_NAT_IPv4Callback) (void *cls, | ||
153 | int add_remove, | ||
154 | const struct in_addr *addr); | ||
155 | |||
156 | |||
157 | /** | ||
158 | * Handle for active NAT registrations. | ||
159 | */ | ||
160 | struct GNUNET_NAT_Handle; | ||
161 | |||
162 | |||
163 | /** | ||
164 | * Attempt to enable port redirection and detect public IP address | ||
165 | * contacting UPnP or NAT-PMP routers on the local network. Use @a | ||
166 | * addr to specify to which of the local host's addresses should the | ||
167 | * external port be mapped. The port is taken from the corresponding | ||
168 | * sockaddr_in[6] field. The NAT module should call the given @a | ||
169 | * address_callback for any 'plausible' external address. | ||
170 | * | ||
171 | * @param cfg configuration to use | ||
172 | * @param proto protocol this is about, IPPROTO_TCP or IPPROTO_UDP | ||
173 | * @param adv_port advertised port (port we are either bound to or that our OS | ||
174 | * locally performs redirection from to our bound port). | ||
175 | * @param num_addrs number of addresses in @a addrs | ||
176 | * @param addrs list of local addresses packets should be redirected to | ||
177 | * @param addrlens actual lengths of the addresses in @a addrs | ||
178 | * @param ip_callback function to call whenever our (external) IPv4 address changes (or becomes known) | ||
179 | * @param address_callback function to call everytime the public IP address changes | ||
180 | * @param reversal_callback function to call if someone wants connection reversal from us, | ||
181 | * NULL if connection reversal is not supported | ||
182 | * @param callback_cls closure for callbacks | ||
183 | * @return NULL on error, otherwise handle that can be used to unregister | ||
184 | */ | ||
185 | struct GNUNET_NAT_Handle * | ||
186 | GNUNET_NAT_register (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
187 | int proto, | ||
188 | uint16_t adv_port, | ||
189 | unsigned int num_addrs, | ||
190 | const struct sockaddr **addrs, | ||
191 | const socklen_t *addrlens, | ||
192 | GNUNET_NAT_IPv4Callback ip_callback, | ||
193 | GNUNET_NAT_AddressCallback address_callback, | ||
194 | GNUNET_NAT_ReversalCallback reversal_callback, | ||
195 | void *callback_cls); | ||
196 | |||
197 | |||
198 | /** | ||
199 | * Handle an incoming STUN message. This function is useful as | ||
200 | * some GNUnet service may be listening on a UDP port and might | ||
201 | * thus receive STUN messages while trying to receive other data. | ||
202 | * In this case, this function can be used to act as a proper | ||
203 | * STUN server (if desired). | ||
204 | * | ||
205 | * The function does some basic sanity checks on packet size and | ||
206 | * content, try to extract a bit of information, and possibly replies | ||
207 | * if this is an actual STUN message. | ||
208 | * | ||
209 | * At the moment this only processes BIND requests, and returns the | ||
210 | * externally visible address of the request. | ||
211 | * | ||
212 | * @param nat handle to the NAT service | ||
213 | * @param sender_addr address from which we got @a data | ||
214 | * @param data the packet | ||
215 | * @param data_size number of bytes in @a data | ||
216 | * @return #GNUNET_OK on success | ||
217 | * #GNUNET_NO if the packet is not a STUN packet | ||
218 | * #GNUNET_SYSERR on internal error handling the packet | ||
219 | */ | ||
220 | int | ||
221 | GNUNET_NAT_stun_handle_packet (struct GNUNET_NAT_Handle *nat, | ||
222 | const struct sockaddr *sender_addr, | ||
223 | const void *data, | ||
224 | size_t data_size); | ||
225 | |||
226 | |||
227 | /** | ||
228 | * Test if the given address is (currently) a plausible IP address for | ||
229 | * this peer. Mostly a convenience function so that clients do not | ||
230 | * have to explicitly track all IPs that the #GNUNET_NAT_AddressCallback | ||
231 | * has returned so far. | ||
232 | * | ||
233 | * @param h the handle returned by register | ||
234 | * @param addr IP address to test (IPv4 or IPv6) | ||
235 | * @param addrlen number of bytes in @a addr | ||
236 | * @return #GNUNET_YES if the address is plausible, | ||
237 | * #GNUNET_NO if the address is not plausible, | ||
238 | * #GNUNET_SYSERR if the address is malformed | ||
239 | */ | ||
240 | int | ||
241 | GNUNET_NAT_test_address (struct GNUNET_NAT_Handle *h, | ||
242 | const void *addr, | ||
243 | socklen_t addrlen); | ||
244 | |||
245 | |||
246 | /** | ||
247 | * We learned about a peer (possibly behind NAT) so run the | ||
248 | * gnunet-nat-client to send dummy ICMP responses to cause | ||
249 | * that peer to connect to us (connection reversal). | ||
250 | * | ||
251 | * @param h handle (used for configuration) | ||
252 | * @param local_sa our local address of the peer (IPv4-only) | ||
253 | * @param remote_sa the remote address of the peer (IPv4-only) | ||
254 | * @return #GNUNET_SYSERR on error, | ||
255 | * #GNUNET_NO if connection reversal is unavailable, | ||
256 | * #GNUNET_OK otherwise (presumably in progress) | ||
257 | */ | ||
258 | int | ||
259 | GNUNET_NAT_request_reversal (struct GNUNET_NAT_Handle *h, | ||
260 | const struct sockaddr_in *local_sa, | ||
261 | const struct sockaddr_in *remote_sa); | ||
262 | |||
263 | |||
264 | /** | ||
265 | * Stop port redirection and public IP address detection for the given | ||
266 | * handle. This frees the handle, after having sent the needed | ||
267 | * commands to close open ports. | ||
268 | * | ||
269 | * @param h the handle to stop | ||
270 | */ | ||
271 | void | ||
272 | GNUNET_NAT_unregister (struct GNUNET_NAT_Handle *h); | ||
273 | |||
274 | |||
275 | /** | ||
276 | * Handle to a NAT test. | ||
277 | */ | ||
278 | struct GNUNET_NAT_Test; | ||
279 | |||
280 | |||
281 | /** | ||
282 | * Function called to report success or failure for | ||
283 | * NAT configuration test. | ||
284 | * | ||
285 | * @param cls closure | ||
286 | * @param result #GNUNET_NAT_ERROR_SUCCESS on success, otherwise the specific error code | ||
287 | */ | ||
288 | typedef void | ||
289 | (*GNUNET_NAT_TestCallback) (void *cls, | ||
290 | enum GNUNET_NAT_StatusCode result); | ||
291 | |||
292 | |||
293 | /** | ||
294 | * Start testing if NAT traversal works using the given configuration | ||
295 | * (IPv4-only). The transport adapters should be down while using | ||
296 | * this function. | ||
297 | * | ||
298 | * @param cfg configuration for the NAT traversal | ||
299 | * @param proto protocol to test, i.e. IPPROTO_TCP or IPPROTO_UDP | ||
300 | * @param bnd_port port to bind to, 0 to test connection reversal | ||
301 | * @param adv_port externally advertised port to use | ||
302 | * @param report function to call with the result of the test | ||
303 | * @param report_cls closure for @a report | ||
304 | * @return handle to cancel NAT test | ||
305 | */ | ||
306 | struct GNUNET_NAT_Test * | ||
307 | GNUNET_NAT_test_start (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
308 | int proto, | ||
309 | uint16_t bnd_port, | ||
310 | uint16_t adv_port, | ||
311 | GNUNET_NAT_TestCallback report, | ||
312 | void *report_cls); | ||
313 | |||
314 | |||
315 | /** | ||
316 | * Stop an active NAT test. | ||
317 | * | ||
318 | * @param tst test to stop. | ||
319 | */ | ||
320 | void | ||
321 | GNUNET_NAT_test_stop (struct GNUNET_NAT_Test *tst); | ||
322 | |||
323 | |||
324 | /** | ||
325 | * Handle to auto-configuration in progress. | ||
326 | */ | ||
327 | struct GNUNET_NAT_AutoHandle; | ||
328 | |||
329 | |||
330 | /** | ||
331 | * What the situation of the NAT connectivity | ||
332 | */ | ||
333 | enum GNUNET_NAT_Type | ||
334 | { | ||
335 | /** | ||
336 | * We have a direct connection | ||
337 | */ | ||
338 | GNUNET_NAT_TYPE_NO_NAT = GNUNET_OK, | ||
339 | |||
340 | /** | ||
341 | * We are under a NAT but cannot traverse it | ||
342 | */ | ||
343 | GNUNET_NAT_TYPE_UNREACHABLE_NAT, | ||
344 | |||
345 | /** | ||
346 | * We can traverse using STUN | ||
347 | */ | ||
348 | GNUNET_NAT_TYPE_STUN_PUNCHED_NAT, | ||
349 | |||
350 | /** | ||
351 | * WE can traverse using UPNP | ||
352 | */ | ||
353 | GNUNET_NAT_TYPE_UPNP_NAT | ||
354 | |||
355 | }; | ||
356 | |||
357 | /** | ||
358 | * Error Types for the NAT subsystem (which can then later be converted/resolved to a string) | ||
359 | */ | ||
360 | enum GNUNET_NAT_StatusCode | ||
361 | { | ||
362 | /** | ||
363 | * Just the default | ||
364 | */ | ||
365 | GNUNET_NAT_ERROR_SUCCESS = GNUNET_OK, | ||
366 | |||
367 | /** | ||
368 | * IPC Failure | ||
369 | */ | ||
370 | GNUNET_NAT_ERROR_IPC_FAILURE, | ||
371 | |||
372 | /** | ||
373 | * Failure in network subsystem, check permissions | ||
374 | */ | ||
375 | GNUNET_NAT_ERROR_INTERNAL_NETWORK_ERROR, | ||
376 | |||
377 | /** | ||
378 | * test timed out | ||
379 | */ | ||
380 | GNUNET_NAT_ERROR_TIMEOUT, | ||
381 | |||
382 | /** | ||
383 | * detected that we are offline | ||
384 | */ | ||
385 | GNUNET_NAT_ERROR_NOT_ONLINE, | ||
386 | |||
387 | /** | ||
388 | * `upnpc` command not found | ||
389 | */ | ||
390 | GNUNET_NAT_ERROR_UPNPC_NOT_FOUND, | ||
391 | |||
392 | /** | ||
393 | * Failed to run `upnpc` command | ||
394 | */ | ||
395 | GNUNET_NAT_ERROR_UPNPC_FAILED, | ||
396 | |||
397 | /** | ||
398 | * `upnpc' command took too long, process killed | ||
399 | */ | ||
400 | GNUNET_NAT_ERROR_UPNPC_TIMEOUT, | ||
401 | |||
402 | /** | ||
403 | * `upnpc' command failed to establish port mapping | ||
404 | */ | ||
405 | GNUNET_NAT_ERROR_UPNPC_PORTMAP_FAILED, | ||
406 | |||
407 | /** | ||
408 | * `external-ip' command not found | ||
409 | */ | ||
410 | GNUNET_NAT_ERROR_EXTERNAL_IP_UTILITY_NOT_FOUND, | ||
411 | |||
412 | /** | ||
413 | * Failed to run `external-ip` command | ||
414 | */ | ||
415 | GNUNET_NAT_ERROR_EXTERNAL_IP_UTILITY_FAILED, | ||
416 | |||
417 | /** | ||
418 | * `external-ip' command output invalid | ||
419 | */ | ||
420 | GNUNET_NAT_ERROR_EXTERNAL_IP_UTILITY_OUTPUT_INVALID, | ||
421 | |||
422 | /** | ||
423 | * "no valid address was returned by `external-ip'" | ||
424 | */ | ||
425 | GNUNET_NAT_ERROR_EXTERNAL_IP_ADDRESS_INVALID, | ||
426 | |||
427 | /** | ||
428 | * Could not determine interface with internal/local network address | ||
429 | */ | ||
430 | GNUNET_NAT_ERROR_NO_VALID_IF_IP_COMBO, | ||
431 | |||
432 | /** | ||
433 | * No working gnunet-helper-nat-server found | ||
434 | */ | ||
435 | GNUNET_NAT_ERROR_HELPER_NAT_SERVER_NOT_FOUND, | ||
436 | |||
437 | /** | ||
438 | * NAT test could not be initialized | ||
439 | */ | ||
440 | GNUNET_NAT_ERROR_NAT_TEST_START_FAILED, | ||
441 | |||
442 | /** | ||
443 | * NAT test timeout | ||
444 | */ | ||
445 | GNUNET_NAT_ERROR_NAT_TEST_TIMEOUT, | ||
446 | |||
447 | /** | ||
448 | * NAT test failed to initiate | ||
449 | */ | ||
450 | GNUNET_NAT_ERROR_NAT_REGISTER_FAILED, | ||
451 | |||
452 | /** | ||
453 | * | ||
454 | */ | ||
455 | GNUNET_NAT_ERROR_HELPER_NAT_CLIENT_NOT_FOUND | ||
456 | |||
457 | }; | ||
458 | |||
459 | |||
460 | /** | ||
461 | * Converts `enum GNUNET_NAT_StatusCode` to string | ||
462 | * | ||
463 | * @param err error code to resolve to a string | ||
464 | * @return point to a static string containing the error code | ||
465 | */ | ||
466 | const char * | ||
467 | GNUNET_NAT_status2string (enum GNUNET_NAT_StatusCode err); | ||
468 | |||
469 | |||
470 | /** | ||
471 | * Function called with the result from the autoconfiguration. | ||
472 | * | ||
473 | * @param cls closure | ||
474 | * @param diff minimal suggested changes to the original configuration | ||
475 | * to make it work (as best as we can) | ||
476 | * @param result #GNUNET_NAT_ERROR_SUCCESS on success, otherwise the specific error code | ||
477 | * @param type what the situation of the NAT | ||
478 | */ | ||
479 | typedef void | ||
480 | (*GNUNET_NAT_AutoResultCallback)(void *cls, | ||
481 | const struct GNUNET_CONFIGURATION_Handle *diff, | ||
482 | enum GNUNET_NAT_StatusCode result, | ||
483 | enum GNUNET_NAT_Type type); | ||
484 | |||
485 | |||
486 | /** | ||
487 | * Start auto-configuration routine. The transport adapters should | ||
488 | * be stopped while this function is called. | ||
489 | * | ||
490 | * @param cfg initial configuration | ||
491 | * @param cb function to call with autoconfiguration result | ||
492 | * @param cb_cls closure for @a cb | ||
493 | * @return handle to cancel operation | ||
494 | */ | ||
495 | struct GNUNET_NAT_AutoHandle * | ||
496 | GNUNET_NAT_autoconfig_start (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
497 | GNUNET_NAT_AutoResultCallback cb, | ||
498 | void *cb_cls); | ||
499 | |||
500 | |||
501 | /** | ||
502 | * Abort autoconfiguration. | ||
503 | * | ||
504 | * @param ah handle for operation to abort | ||
505 | */ | ||
506 | void | ||
507 | GNUNET_NAT_autoconfig_cancel (struct GNUNET_NAT_AutoHandle *ah); | ||
508 | |||
509 | |||
510 | #endif | ||
511 | |||
512 | /** @} */ /* end of group */ | ||
513 | |||
514 | /* end of gnunet_nat_service.h */ | ||