diff options
Diffstat (limited to 'src/include/gnunet_nat_service.h')
-rw-r--r-- | src/include/gnunet_nat_service.h | 407 |
1 files changed, 130 insertions, 277 deletions
diff --git a/src/include/gnunet_nat_service.h b/src/include/gnunet_nat_service.h index 6b9650306..94f8a8555 100644 --- a/src/include/gnunet_nat_service.h +++ b/src/include/gnunet_nat_service.h | |||
@@ -1,6 +1,6 @@ | |||
1 | /* | 1 | /* |
2 | This file is part of GNUnet. | 2 | This file is part of GNUnet. |
3 | Copyright (C) 2007-2016 GNUnet e.V. | 3 | Copyright (C) 2007-2017 GNUnet e.V. |
4 | 4 | ||
5 | GNUnet is free software; you can redistribute it and/or modify | 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 | 6 | it under the terms of the GNU General Public License as published |
@@ -137,132 +137,6 @@ enum GNUNET_NAT_AddressClass | |||
137 | 137 | ||
138 | 138 | ||
139 | /** | 139 | /** |
140 | * Signature of the callback passed to #GNUNET_NAT_register() for | ||
141 | * a function to call whenever our set of 'valid' addresses changes. | ||
142 | * | ||
143 | * @param cls closure | ||
144 | * @param add_remove #GNUNET_YES to add a new public IP address, | ||
145 | * #GNUNET_NO to remove a previous (now invalid) one | ||
146 | * @param ac address class the address belongs to | ||
147 | * @param addr either the previous or the new public IP address | ||
148 | * @param addrlen actual length of the @a addr | ||
149 | */ | ||
150 | typedef void | ||
151 | (*GNUNET_NAT_AddressCallback) (void *cls, | ||
152 | int add_remove, | ||
153 | enum GNUNET_NAT_AddressClass ac, | ||
154 | const struct sockaddr *addr, | ||
155 | socklen_t addrlen); | ||
156 | |||
157 | |||
158 | /** | ||
159 | * Signature of the callback passed to #GNUNET_NAT_register(). | ||
160 | * for a function to call whenever someone asks us to do connection | ||
161 | * reversal. | ||
162 | * | ||
163 | * @param cls closure | ||
164 | * @param remote_addr public IP address of the other peer | ||
165 | * @param remote_addrlen actual length of the @a remote_addr | ||
166 | */ | ||
167 | typedef void | ||
168 | (*GNUNET_NAT_ReversalCallback) (void *cls, | ||
169 | const struct sockaddr *remote_addr, | ||
170 | socklen_t remote_addrlen); | ||
171 | |||
172 | |||
173 | /** | ||
174 | * Handle for active NAT registrations. | ||
175 | */ | ||
176 | struct GNUNET_NAT_Handle; | ||
177 | |||
178 | |||
179 | /** | ||
180 | * Attempt to enable port redirection and detect public IP address | ||
181 | * contacting UPnP or NAT-PMP routers on the local network. Use @a | ||
182 | * addr to specify to which of the local host's addresses should the | ||
183 | * external port be mapped. The port is taken from the corresponding | ||
184 | * sockaddr_in[6] field. The NAT module should call the given @a | ||
185 | * address_callback for any 'plausible' external address. | ||
186 | * | ||
187 | * @param cfg configuration to use | ||
188 | * @param config_section name of the configuration section for optionsx | ||
189 | * @param proto protocol this is about, IPPROTO_TCP or IPPROTO_UDP | ||
190 | * @param num_addrs number of addresses in @a addrs | ||
191 | * @param addrs list of local addresses packets should be redirected to | ||
192 | * @param addrlens actual lengths of the addresses in @a addrs | ||
193 | * @param address_callback function to call everytime the public IP address changes | ||
194 | * @param reversal_callback function to call if someone wants connection reversal from us, | ||
195 | * NULL if connection reversal is not supported | ||
196 | * @param callback_cls closure for callbacks | ||
197 | * @return NULL on error, otherwise handle that can be used to unregister | ||
198 | */ | ||
199 | struct GNUNET_NAT_Handle * | ||
200 | GNUNET_NAT_register (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
201 | const char *config_section, | ||
202 | uint8_t proto, | ||
203 | unsigned int num_addrs, | ||
204 | const struct sockaddr **addrs, | ||
205 | const socklen_t *addrlens, | ||
206 | GNUNET_NAT_AddressCallback address_callback, | ||
207 | GNUNET_NAT_ReversalCallback reversal_callback, | ||
208 | void *callback_cls); | ||
209 | |||
210 | |||
211 | /** | ||
212 | * Test if the given address is (currently) a plausible IP address for | ||
213 | * this peer. Mostly a convenience function so that clients do not | ||
214 | * have to explicitly track all IPs that the #GNUNET_NAT_AddressCallback | ||
215 | * has returned so far. | ||
216 | * | ||
217 | * @param nh the handle returned by register | ||
218 | * @param addr IP address to test (IPv4 or IPv6) | ||
219 | * @param addrlen number of bytes in @a addr | ||
220 | * @return #GNUNET_YES if the address is plausible, | ||
221 | * #GNUNET_NO if the address is not plausible, | ||
222 | * #GNUNET_SYSERR if the address is malformed | ||
223 | */ | ||
224 | int | ||
225 | GNUNET_NAT_test_address (struct GNUNET_NAT_Handle *nh, | ||
226 | const void *addr, | ||
227 | socklen_t addrlen); | ||
228 | |||
229 | |||
230 | /** | ||
231 | * We learned about a peer (possibly behind NAT) so run the | ||
232 | * gnunet-nat-client to send dummy ICMP responses to cause | ||
233 | * that peer to connect to us (connection reversal). | ||
234 | * | ||
235 | * @param nh handle (used for configuration) | ||
236 | * @param local_sa our local address of the peer (IPv4-only) | ||
237 | * @param remote_sa the remote address of the peer (IPv4-only) | ||
238 | * @return #GNUNET_SYSERR on error, | ||
239 | * #GNUNET_NO if connection reversal is unavailable, | ||
240 | * #GNUNET_OK otherwise (presumably in progress) | ||
241 | */ | ||
242 | int | ||
243 | GNUNET_NAT_request_reversal (struct GNUNET_NAT_Handle *nh, | ||
244 | const struct sockaddr_in *local_sa, | ||
245 | const struct sockaddr_in *remote_sa); | ||
246 | |||
247 | |||
248 | /** | ||
249 | * Stop port redirection and public IP address detection for the given | ||
250 | * handle. This frees the handle, after having sent the needed | ||
251 | * commands to close open ports. | ||
252 | * | ||
253 | * @param nh the handle to unregister | ||
254 | */ | ||
255 | void | ||
256 | GNUNET_NAT_unregister (struct GNUNET_NAT_Handle *nh); | ||
257 | |||
258 | |||
259 | /** | ||
260 | * Handle to a NAT test. | ||
261 | */ | ||
262 | struct GNUNET_NAT_Test; | ||
263 | |||
264 | |||
265 | /** | ||
266 | * Error Types for the NAT subsystem (which can then later be converted/resolved to a string) | 140 | * Error Types for the NAT subsystem (which can then later be converted/resolved to a string) |
267 | */ | 141 | */ |
268 | enum GNUNET_NAT_StatusCode | 142 | enum GNUNET_NAT_StatusCode |
@@ -365,129 +239,6 @@ enum GNUNET_NAT_StatusCode | |||
365 | }; | 239 | }; |
366 | 240 | ||
367 | 241 | ||
368 | /** | ||
369 | * Function called to report success or failure for | ||
370 | * NAT configuration test. | ||
371 | * | ||
372 | * @param cls closure | ||
373 | * @param result #GNUNET_NAT_ERROR_SUCCESS on success, otherwise the specific error code | ||
374 | */ | ||
375 | typedef void | ||
376 | (*GNUNET_NAT_TestCallback) (void *cls, | ||
377 | enum GNUNET_NAT_StatusCode result); | ||
378 | |||
379 | |||
380 | /** | ||
381 | * Handle an incoming STUN message. This function is useful as | ||
382 | * some GNUnet service may be listening on a UDP port and might | ||
383 | * thus receive STUN messages while trying to receive other data. | ||
384 | * In this case, this function can be used to process replies | ||
385 | * to STUN requests. | ||
386 | * | ||
387 | * The function does some basic sanity checks on packet size and | ||
388 | * content, try to extract a bit of information. | ||
389 | * | ||
390 | * At the moment this only processes BIND requests, and returns the | ||
391 | * externally visible address of the request to the rest of the | ||
392 | * NAT logic. | ||
393 | * | ||
394 | * @param nh handle to the NAT service | ||
395 | * @param sender_addr address from which we got @a data | ||
396 | * @param sender_addr_len number of bytes in @a sender_addr | ||
397 | * @param data the packet | ||
398 | * @param data_size number of bytes in @a data | ||
399 | * @return #GNUNET_OK on success | ||
400 | * #GNUNET_NO if the packet is not a STUN packet | ||
401 | * #GNUNET_SYSERR on internal error handling the packet | ||
402 | */ | ||
403 | int | ||
404 | GNUNET_NAT_stun_handle_packet (struct GNUNET_NAT_Handle *nh, | ||
405 | const struct sockaddr *sender_addr, | ||
406 | size_t sender_addr_len, | ||
407 | const void *data, | ||
408 | size_t data_size); | ||
409 | |||
410 | |||
411 | /** | ||
412 | * Handle to a request given to the resolver. Can be used to cancel | ||
413 | * the request prior to the timeout or successful execution. Also | ||
414 | * used to track our internal state for the request. | ||
415 | */ | ||
416 | struct GNUNET_NAT_STUN_Handle; | ||
417 | |||
418 | |||
419 | /** | ||
420 | * Make Generic STUN request. Sends a generic stun request to the | ||
421 | * server specified using the specified socket. If we do this, | ||
422 | * we need to watch for possible responses and call | ||
423 | * #GNUNET_NAT_stun_handle_packet() on incoming packets. | ||
424 | * | ||
425 | * @param server the address of the stun server | ||
426 | * @param port port of the stun server, in host byte order | ||
427 | * @param sock the socket used to send the request, must be a | ||
428 | * UDP socket | ||
429 | * @param cb callback in case of error | ||
430 | * @param cb_cls closure for @a cb | ||
431 | * @return NULL on error | ||
432 | */ | ||
433 | struct GNUNET_NAT_STUN_Handle * | ||
434 | GNUNET_NAT_stun_make_request (const char *server, | ||
435 | uint16_t port, | ||
436 | struct GNUNET_NETWORK_Handle *sock, | ||
437 | GNUNET_NAT_TestCallback cb, | ||
438 | void *cb_cls); | ||
439 | |||
440 | |||
441 | /** | ||
442 | * Cancel active STUN request. Frees associated resources | ||
443 | * and ensures that the callback is no longer invoked. | ||
444 | * | ||
445 | * @param rh request to cancel | ||
446 | */ | ||
447 | void | ||
448 | GNUNET_NAT_stun_make_request_cancel (struct GNUNET_NAT_STUN_Handle *rh); | ||
449 | |||
450 | |||
451 | /** | ||
452 | * Start testing if NAT traversal works using the given configuration | ||
453 | * (IPv4-only). The transport adapters should be down while using | ||
454 | * this function. | ||
455 | * | ||
456 | * @param cfg configuration for the NAT traversal | ||
457 | * @param proto protocol to test, i.e. IPPROTO_TCP or IPPROTO_UDP | ||
458 | * @param bind_ip IPv4 address to bind to | ||
459 | * @param bnd_port port to bind to, 0 to test connection reversal | ||
460 | * @param extern_ip IPv4 address to externally advertise | ||
461 | * @param extern_port externally advertised port to use | ||
462 | * @param report function to call with the result of the test | ||
463 | * @param report_cls closure for @a report | ||
464 | * @return handle to cancel NAT test | ||
465 | */ | ||
466 | struct GNUNET_NAT_Test * | ||
467 | GNUNET_NAT_test_start (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
468 | uint8_t proto, | ||
469 | struct in_addr bind_ip, | ||
470 | uint16_t bnd_port, | ||
471 | struct in_addr extern_ip, | ||
472 | uint16_t extern_port, | ||
473 | GNUNET_NAT_TestCallback report, | ||
474 | void *report_cls); | ||
475 | |||
476 | |||
477 | /** | ||
478 | * Stop an active NAT test. | ||
479 | * | ||
480 | * @param tst test to stop. | ||
481 | */ | ||
482 | void | ||
483 | GNUNET_NAT_test_stop (struct GNUNET_NAT_Test *tst); | ||
484 | |||
485 | |||
486 | /** | ||
487 | * Handle to auto-configuration in progress. | ||
488 | */ | ||
489 | struct GNUNET_NAT_AutoHandle; | ||
490 | |||
491 | 242 | ||
492 | /** | 243 | /** |
493 | * What the situation of the NAT connectivity | 244 | * What the situation of the NAT connectivity |
@@ -522,54 +273,156 @@ enum GNUNET_NAT_Type | |||
522 | }; | 273 | }; |
523 | 274 | ||
524 | 275 | ||
276 | |||
525 | /** | 277 | /** |
526 | * Converts `enum GNUNET_NAT_StatusCode` to string | 278 | * Signature of the callback passed to #GNUNET_NAT_register() for |
279 | * a function to call whenever our set of 'valid' addresses changes. | ||
527 | * | 280 | * |
528 | * @param err error code to resolve to a string | 281 | * @param cls closure |
529 | * @return point to a static string containing the error code | 282 | * @param add_remove #GNUNET_YES to add a new public IP address, |
283 | * #GNUNET_NO to remove a previous (now invalid) one | ||
284 | * @param ac address class the address belongs to | ||
285 | * @param addr either the previous or the new public IP address | ||
286 | * @param addrlen actual length of the @a addr | ||
530 | */ | 287 | */ |
531 | const char * | 288 | typedef void |
532 | GNUNET_NAT_status2string (enum GNUNET_NAT_StatusCode err); | 289 | (*GNUNET_NAT_AddressCallback) (void *cls, |
290 | int add_remove, | ||
291 | enum GNUNET_NAT_AddressClass ac, | ||
292 | const struct sockaddr *addr, | ||
293 | socklen_t addrlen); | ||
533 | 294 | ||
534 | 295 | ||
535 | /** | 296 | /** |
536 | * Function called with the result from the autoconfiguration. | 297 | * Signature of the callback passed to #GNUNET_NAT_register(). |
298 | * for a function to call whenever someone asks us to do connection | ||
299 | * reversal. | ||
537 | * | 300 | * |
538 | * @param cls closure | 301 | * @param cls closure |
539 | * @param diff minimal suggested changes to the original configuration | 302 | * @param remote_addr public IP address of the other peer |
540 | * to make it work (as best as we can) | 303 | * @param remote_addrlen actual length of the @a remote_addr |
541 | * @param result #GNUNET_NAT_ERROR_SUCCESS on success, otherwise the specific error code | ||
542 | * @param type what the situation of the NAT | ||
543 | */ | 304 | */ |
544 | typedef void | 305 | typedef void |
545 | (*GNUNET_NAT_AutoResultCallback)(void *cls, | 306 | (*GNUNET_NAT_ReversalCallback) (void *cls, |
546 | const struct GNUNET_CONFIGURATION_Handle *diff, | 307 | const struct sockaddr *remote_addr, |
547 | enum GNUNET_NAT_StatusCode result, | 308 | socklen_t remote_addrlen); |
548 | enum GNUNET_NAT_Type type); | 309 | |
310 | |||
311 | /** | ||
312 | * Handle for active NAT registrations. | ||
313 | */ | ||
314 | struct GNUNET_NAT_Handle; | ||
549 | 315 | ||
550 | 316 | ||
551 | /** | 317 | /** |
552 | * Start auto-configuration routine. The transport adapters should | 318 | * Attempt to enable port redirection and detect public IP address |
553 | * be stopped while this function is called. | 319 | * contacting UPnP or NAT-PMP routers on the local network. Use @a |
320 | * addr to specify to which of the local host's addresses should the | ||
321 | * external port be mapped. The port is taken from the corresponding | ||
322 | * sockaddr_in[6] field. The NAT module should call the given @a | ||
323 | * address_callback for any 'plausible' external address. | ||
554 | * | 324 | * |
555 | * @param cfg initial configuration | 325 | * @param cfg configuration to use |
556 | * @param cb function to call with autoconfiguration result | 326 | * @param config_section name of the configuration section for options |
557 | * @param cb_cls closure for @a cb | 327 | * @param proto protocol this is about, IPPROTO_TCP or IPPROTO_UDP |
558 | * @return handle to cancel operation | 328 | * @param num_addrs number of addresses in @a addrs |
329 | * @param addrs list of local addresses packets should be redirected to | ||
330 | * @param addrlens actual lengths of the addresses in @a addrs | ||
331 | * @param address_callback function to call everytime the public IP address changes | ||
332 | * @param reversal_callback function to call if someone wants connection reversal from us, | ||
333 | * NULL if connection reversal is not supported | ||
334 | * @param callback_cls closure for callbacks | ||
335 | * @return NULL on error, otherwise handle that can be used to unregister | ||
559 | */ | 336 | */ |
560 | struct GNUNET_NAT_AutoHandle * | 337 | struct GNUNET_NAT_Handle * |
561 | GNUNET_NAT_autoconfig_start (const struct GNUNET_CONFIGURATION_Handle *cfg, | 338 | GNUNET_NAT_register (const struct GNUNET_CONFIGURATION_Handle *cfg, |
562 | GNUNET_NAT_AutoResultCallback cb, | 339 | const char *config_section, |
563 | void *cb_cls); | 340 | uint8_t proto, |
341 | unsigned int num_addrs, | ||
342 | const struct sockaddr **addrs, | ||
343 | const socklen_t *addrlens, | ||
344 | GNUNET_NAT_AddressCallback address_callback, | ||
345 | GNUNET_NAT_ReversalCallback reversal_callback, | ||
346 | void *callback_cls); | ||
347 | |||
348 | |||
349 | /** | ||
350 | * Test if the given address is (currently) a plausible IP address for | ||
351 | * this peer. Mostly a convenience function so that clients do not | ||
352 | * have to explicitly track all IPs that the #GNUNET_NAT_AddressCallback | ||
353 | * has returned so far. | ||
354 | * | ||
355 | * @param nh the handle returned by register | ||
356 | * @param addr IP address to test (IPv4 or IPv6) | ||
357 | * @param addrlen number of bytes in @a addr | ||
358 | * @return #GNUNET_YES if the address is plausible, | ||
359 | * #GNUNET_NO if the address is not plausible, | ||
360 | * #GNUNET_SYSERR if the address is malformed | ||
361 | */ | ||
362 | int | ||
363 | GNUNET_NAT_test_address (struct GNUNET_NAT_Handle *nh, | ||
364 | const void *addr, | ||
365 | socklen_t addrlen); | ||
564 | 366 | ||
565 | 367 | ||
566 | /** | 368 | /** |
567 | * Abort autoconfiguration. | 369 | * We learned about a peer (possibly behind NAT) so run the |
370 | * gnunet-nat-client to send dummy ICMP responses to cause | ||
371 | * that peer to connect to us (connection reversal). | ||
568 | * | 372 | * |
569 | * @param ah handle for operation to abort | 373 | * @param nh handle (used for configuration) |
374 | * @param local_sa our local address of the peer (IPv4-only) | ||
375 | * @param remote_sa the remote address of the peer (IPv4-only) | ||
376 | * @return #GNUNET_SYSERR on error, | ||
377 | * #GNUNET_NO if connection reversal is unavailable, | ||
378 | * #GNUNET_OK otherwise (presumably in progress) | ||
379 | */ | ||
380 | int | ||
381 | GNUNET_NAT_request_reversal (struct GNUNET_NAT_Handle *nh, | ||
382 | const struct sockaddr_in *local_sa, | ||
383 | const struct sockaddr_in *remote_sa); | ||
384 | |||
385 | |||
386 | /** | ||
387 | * Stop port redirection and public IP address detection for the given | ||
388 | * handle. This frees the handle, after having sent the needed | ||
389 | * commands to close open ports. | ||
390 | * | ||
391 | * @param nh the handle to unregister | ||
570 | */ | 392 | */ |
571 | void | 393 | void |
572 | GNUNET_NAT_autoconfig_cancel (struct GNUNET_NAT_AutoHandle *ah); | 394 | GNUNET_NAT_unregister (struct GNUNET_NAT_Handle *nh); |
395 | |||
396 | |||
397 | /** | ||
398 | * Handle an incoming STUN message. This function is useful as | ||
399 | * some GNUnet service may be listening on a UDP port and might | ||
400 | * thus receive STUN messages while trying to receive other data. | ||
401 | * In this case, this function can be used to process replies | ||
402 | * to STUN requests. | ||
403 | * | ||
404 | * The function does some basic sanity checks on packet size and | ||
405 | * content, try to extract a bit of information. | ||
406 | * | ||
407 | * At the moment this only processes BIND requests, and returns the | ||
408 | * externally visible address of the request to the rest of the | ||
409 | * NAT logic. | ||
410 | * | ||
411 | * @param nh handle to the NAT service | ||
412 | * @param sender_addr address from which we got @a data | ||
413 | * @param sender_addr_len number of bytes in @a sender_addr | ||
414 | * @param data the packet | ||
415 | * @param data_size number of bytes in @a data | ||
416 | * @return #GNUNET_OK on success | ||
417 | * #GNUNET_NO if the packet is not a STUN packet | ||
418 | * #GNUNET_SYSERR on internal error handling the packet | ||
419 | */ | ||
420 | int | ||
421 | GNUNET_NAT_stun_handle_packet (struct GNUNET_NAT_Handle *nh, | ||
422 | const struct sockaddr *sender_addr, | ||
423 | size_t sender_addr_len, | ||
424 | const void *data, | ||
425 | size_t data_size); | ||
573 | 426 | ||
574 | 427 | ||
575 | #endif | 428 | #endif |