X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_nat_lib.h;h=93b441849b886abbcd513d2b305bbb86969795a7;hb=6973ade884b8e22e7fcaa51a90d00a8caa2d2fa4;hp=6d158930a2a3aea8b243e5cf32d5efb9ffc38389;hpb=219094661b70a0e635ba8f9d9944c05c995fb055;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_nat_lib.h b/src/include/gnunet_nat_lib.h index 6d158930a..93b441849 100644 --- a/src/include/gnunet_nat_lib.h +++ b/src/include/gnunet_nat_lib.h @@ -1,6 +1,6 @@ /* This file is part of GNUnet. - (C) 2007, 2008, 2009, 2010 Christian Grothoff (and other contributing authors) + (C) 2007, 2008, 2009, 2010, 2011, 2012 Christian Grothoff (and other contributing authors) GNUnet is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published @@ -32,7 +32,8 @@ #include "gnunet_util_lib.h" /** - * Signature of the callback passed to GNUNET_NAT_register. + * Signature of the callback passed to GNUNET_NAT_register for + * a function to call whenever our set of 'valid' addresses changes. * * @param cls closure * @param add_remove GNUNET_YES to mean the new public IP address, GNUNET_NO to mean @@ -40,34 +41,90 @@ * @param addr either the previous or the new public IP address * @param addrlen actual lenght of the address */ -typedef void (*GNUNET_NAT_AddressCallback) (void *cls, - int add_remove, - const struct sockaddr *addr, +typedef void (*GNUNET_NAT_AddressCallback) (void *cls, int add_remove, + const struct sockaddr * addr, socklen_t addrlen); +/** + * Signature of the callback passed to GNUNET_NAT_register + * for a function to call whenever someone asks us to do connection + * reversal. + * + * @param cls closure + * @param addr public IP address of the other peer + * @param addrlen actual lenght of the address + */ +typedef void (*GNUNET_NAT_ReversalCallback) (void *cls, + const struct sockaddr * addr, + socklen_t addrlen); + + /** * Handle for active NAT registrations. */ struct GNUNET_NAT_Handle; + /** * Attempt to enable port redirection and detect public IP address contacting * UPnP or NAT-PMP routers on the local network. Use addr to specify to which * of the local host's addresses should the external port be mapped. The port - * is taken from the corresponding sockaddr_in[6] field. + * is taken from the corresponding sockaddr_in[6] field. The NAT module + * should call the given callback for any 'plausible' external address. * - * @param addr the local address packets should be redirected to - * @param addrlen actual lenght of the address - * @param callback function to call everytime the public IP address changes + * @param cfg configuration to use + * @param is_tcp GNUNET_YES for TCP, GNUNET_NO for UDP + * @param adv_port advertised port (port we are either bound to or that our OS + * locally performs redirection from to our bound port). + * @param num_addrs number of addresses in 'addrs' + * @param addrs list of local addresses packets should be redirected to + * @param addrlens actual lengths of the addresses + * @param address_callback function to call everytime the public IP address changes + * @param reversal_callback function to call if someone wants connection reversal from us, + * NULL if connection reversal is not supported * @param callback_cls closure for callback - * @return NULL on error, otherwise handle that can be used to unregister + * @return NULL on error, otherwise handle that can be used to unregister */ struct GNUNET_NAT_Handle * -GNUNET_NAT_register (const struct sockaddr *addr, - socklen_t addrlen, - GNUNET_NAT_AddressCallback callback, - void *callback_cls); +GNUNET_NAT_register (const struct GNUNET_CONFIGURATION_Handle *cfg, int is_tcp, + uint16_t adv_port, unsigned int num_addrs, + const struct sockaddr **addrs, const socklen_t * addrlens, + GNUNET_NAT_AddressCallback address_callback, + GNUNET_NAT_ReversalCallback reversal_callback, + void *callback_cls); + + +/** + * Test if the given address is (currently) a plausible IP address for this peer. + * + * @param h the handle returned by register + * @param addr IP address to test (IPv4 or IPv6) + * @param addrlen number of bytes in addr + * @return GNUNET_YES if the address is plausible, + * GNUNET_NO if the address is not plausible, + * GNUNET_SYSERR if the address is malformed + */ +int +GNUNET_NAT_test_address (struct GNUNET_NAT_Handle *h, const void *addr, + socklen_t addrlen); + + +/** + * We learned about a peer (possibly behind NAT) so run the + * gnunet-nat-client to send dummy ICMP responses to cause + * that peer to connect to us (connection reversal). + * + * @param h handle (used for configuration) + * @param sa the address of the peer (IPv4-only) + * + * @return GNUNET_SYSERR on error, GNUNET_NO if nat client is disabled, + * GNUNET_OK otherwise + */ +int +GNUNET_NAT_run_client (struct GNUNET_NAT_Handle *h, + const struct sockaddr_in *sa); + /** @@ -76,8 +133,167 @@ GNUNET_NAT_register (const struct sockaddr *addr, * * @param h the handle to stop */ -void GNUNET_NAT_unregister (struct GNUNET_NAT_Handle *h); +void +GNUNET_NAT_unregister (struct GNUNET_NAT_Handle *h); + + +/** + * Handle to a NAT test. + */ +struct GNUNET_NAT_Test; + +/** + * Function called to report success or failure for + * NAT configuration test. + * + * @param cls closure + * @param success GNUNET_OK on success, GNUNET_NO on failure, + * GNUNET_SYSERR if the test could not be + * properly started (internal failure) + */ +typedef void (*GNUNET_NAT_TestCallback) (void *cls, int success); + +/** + * Start testing if NAT traversal works using the + * given configuration (IPv4-only). + * + * @param cfg configuration for the NAT traversal + * @param is_tcp GNUNET_YES to test TCP, GNUNET_NO to test UDP + * @param bnd_port port to bind to, 0 for connection reversal + * @param adv_port externally advertised port to use + * @param report function to call with the result of the test + * @param report_cls closure for report + * @return handle to cancel NAT test + */ +struct GNUNET_NAT_Test * +GNUNET_NAT_test_start (const struct GNUNET_CONFIGURATION_Handle *cfg, + int is_tcp, uint16_t bnd_port, uint16_t adv_port, + GNUNET_NAT_TestCallback report, void *report_cls); + + +/** + * Stop an active NAT test. + * + * @param tst test to stop. + */ +void +GNUNET_NAT_test_stop (struct GNUNET_NAT_Test *tst); + + +/** + * Signature of a callback that is given an IP address. + * + * @param cls closure + * @param addr the address, NULL on errors + */ +typedef void (*GNUNET_NAT_IPCallback) (void *cls, const struct in_addr * addr); + + + +/** + * Opaque handle to cancel "GNUNET_NAT_mini_get_external_ipv4" operation. + */ +struct GNUNET_NAT_ExternalHandle; + + +/** + * Try to get the external IPv4 address of this peer. + * + * @param timeout when to fail + * @param cb function to call with result + * @param cb_cls closure for 'cb' + * @return handle for cancellation (can only be used until 'cb' is called), NULL on error + */ +struct GNUNET_NAT_ExternalHandle * +GNUNET_NAT_mini_get_external_ipv4 (struct GNUNET_TIME_Relative timeout, + GNUNET_NAT_IPCallback cb, void *cb_cls); + + +/** + * Cancel operation. + * + * @param eh operation to cancel + */ +void +GNUNET_NAT_mini_get_external_ipv4_cancel (struct GNUNET_NAT_ExternalHandle *eh); + + +/** + * Handle to a mapping created with upnpc. + */ +struct GNUNET_NAT_MiniHandle; + + +/** + * Start mapping the given port using (mini)upnpc. This function + * should typically not be used directly (it is used within the + * general-purpose 'GNUNET_NAT_register' code). However, it can be + * used if specifically UPnP-based NAT traversal is to be used or + * tested. + * + * @param port port to map + * @param is_tcp GNUNET_YES to map TCP, GNUNET_NO for UDP + * @param ac function to call with mapping result + * @param ac_cls closure for 'ac' + * @return NULL on error + */ +struct GNUNET_NAT_MiniHandle * +GNUNET_NAT_mini_map_start (uint16_t port, int is_tcp, + GNUNET_NAT_AddressCallback ac, void *ac_cls); + + +/** + * Remove a mapping created with (mini)upnpc. Calling + * this function will give 'upnpc' 1s to remove tha mapping, + * so while this function is non-blocking, a task will be + * left with the scheduler for up to 1s past this call. + * + * @param mini the handle + */ +void +GNUNET_NAT_mini_map_stop (struct GNUNET_NAT_MiniHandle *mini); + + +/** + * Handle to auto-configuration in progress. + */ +struct GNUNET_NAT_AutoHandle; + + +/** + * Function called with the result from the autoconfiguration. + * + * @param cls closure + * @param diff minimal suggested changes to the original configuration + * to make it work (as best as we can) + */ +typedef void (*GNUNET_NAT_AutoResultCallback)(void *cls, + const struct GNUNET_CONFIGURATION_Handle *diff); + + +/** + * Start auto-configuration routine. The resolver service should + * be available when this function is called. + * + * @param cfg initial configuration + * @param cb function to call with autoconfiguration result + * @param cb_cls closure for cb + * @return handle to cancel operation + */ +struct GNUNET_NAT_AutoHandle * +GNUNET_NAT_autoconfig_start (const struct GNUNET_CONFIGURATION_Handle *cfg, + GNUNET_NAT_AutoResultCallback cb, + void *cb_cls); + + +/** + * Abort autoconfiguration. + * + * @param ah handle for operation to abort + */ +void +GNUNET_NAT_autoconfig_cancel (struct GNUNET_NAT_AutoHandle *ah); -#endif +#endif /* end of gnunet_nat_lib.h */