From 12cc5704dbf8384b7821b576aadf90b9875aee5b Mon Sep 17 00:00:00 2001 From: Jon Atack Date: Mon, 15 Mar 2021 16:24:10 +0100 Subject: [PATCH 1/3] net: update incorrect Doxygen documentation in netbase.cpp --- src/netbase.cpp | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/src/netbase.cpp b/src/netbase.cpp index b95bb05e71..17b030eb70 100644 --- a/src/netbase.cpp +++ b/src/netbase.cpp @@ -178,7 +178,7 @@ static bool LookupIntern(const std::string& name, std::vector& vIP, un * @returns Whether or not the specified host string successfully resolved to * any resulting network addresses. * - * @see Lookup(const char *, std::vector&, int, bool, unsigned int) + * @see Lookup(const std::string&, std::vector&, int, bool, unsigned int, DNSLookupFn) * for additional parameter descriptions. */ bool LookupHost(const std::string& name, std::vector& vIP, unsigned int nMaxSolutions, bool fAllowLookup, DNSLookupFn dns_lookup_function) @@ -199,8 +199,8 @@ bool LookupHost(const std::string& name, std::vector& vIP, unsigned in /** * Resolve a host string to its first corresponding network address. * - * @see LookupHost(const std::string&, std::vector&, unsigned int, bool) for - * additional parameter descriptions. + * @see LookupHost(const std::string&, std::vector&, unsigned int, bool, DNSLookupFn) + * for additional parameter descriptions. */ bool LookupHost(const std::string& name, CNetAddr& addr, bool fAllowLookup, DNSLookupFn dns_lookup_function) { @@ -257,7 +257,7 @@ bool Lookup(const std::string& name, std::vector& vAddr, int portDefau /** * Resolve a service string to its first corresponding service. * - * @see Lookup(const char *, std::vector&, int, bool, unsigned int) + * @see Lookup(const std::string&, std::vector&, int, bool, unsigned int, DNSLookupFn) * for additional parameter descriptions. */ bool Lookup(const std::string& name, CService& addr, int portDefault, bool fAllowLookup, DNSLookupFn dns_lookup_function) @@ -277,11 +277,10 @@ bool Lookup(const std::string& name, CService& addr, int portDefault, bool fAllo * Resolve a service string with a numeric IP to its first corresponding * service. * - * @returns The resulting CService if the resolution was successful, [::]:0 - * otherwise. + * @returns The resulting CService if the resolution was successful, [::]:0 otherwise. * - * @see Lookup(const char *, CService&, int, bool) for additional parameter - * descriptions. + * @see Lookup(const std::string&, std::vector&, int, bool, unsigned int, DNSLookupFn) + * for additional parameter descriptions. */ CService LookupNumeric(const std::string& name, int portDefault, DNSLookupFn dns_lookup_function) { From e6bd74b2e5f7f68614ca77a6667520b39feb9247 Mon Sep 17 00:00:00 2001 From: Jon Atack Date: Mon, 15 Mar 2021 16:53:25 +0100 Subject: [PATCH 2/3] net: move Doxygen docs from netbase.cpp to netbase.h --- src/netbase.cpp | 128 -------------------------------------------- src/netbase.h | 137 +++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 136 insertions(+), 129 deletions(-) diff --git a/src/netbase.cpp b/src/netbase.cpp index 17b030eb70..ac2392ebed 100644 --- a/src/netbase.cpp +++ b/src/netbase.cpp @@ -166,21 +166,6 @@ static bool LookupIntern(const std::string& name, std::vector& vIP, un return (vIP.size() > 0); } -/** - * Resolve a host string to its corresponding network addresses. - * - * @param name The string representing a host. Could be a name or a numerical - * IP address (IPv6 addresses in their bracketed form are - * allowed). - * @param[out] vIP The resulting network addresses to which the specified host - * string resolved. - * - * @returns Whether or not the specified host string successfully resolved to - * any resulting network addresses. - * - * @see Lookup(const std::string&, std::vector&, int, bool, unsigned int, DNSLookupFn) - * for additional parameter descriptions. - */ bool LookupHost(const std::string& name, std::vector& vIP, unsigned int nMaxSolutions, bool fAllowLookup, DNSLookupFn dns_lookup_function) { if (!ValidAsCString(name)) { @@ -196,12 +181,6 @@ bool LookupHost(const std::string& name, std::vector& vIP, unsigned in return LookupIntern(strHost, vIP, nMaxSolutions, fAllowLookup, dns_lookup_function); } - /** - * Resolve a host string to its first corresponding network address. - * - * @see LookupHost(const std::string&, std::vector&, unsigned int, bool, DNSLookupFn) - * for additional parameter descriptions. - */ bool LookupHost(const std::string& name, CNetAddr& addr, bool fAllowLookup, DNSLookupFn dns_lookup_function) { if (!ValidAsCString(name)) { @@ -215,26 +194,6 @@ bool LookupHost(const std::string& name, CNetAddr& addr, bool fAllowLookup, DNSL return true; } -/** - * Resolve a service string to its corresponding service. - * - * @param name The string representing a service. Could be a name or a - * numerical IP address (IPv6 addresses should be in their - * disambiguated bracketed form), optionally followed by a port - * number. (e.g. example.com:8333 or - * [2001:db8:85a3:8d3:1319:8a2e:370:7348]:420) - * @param[out] vAddr The resulting services to which the specified service string - * resolved. - * @param portDefault The default port for resulting services if not specified - * by the service string. - * @param fAllowLookup Whether or not hostname lookups are permitted. If yes, - * external queries may be performed. - * @param nMaxSolutions The maximum number of results we want, specifying 0 - * means "as many solutions as we get." - * - * @returns Whether or not the service string successfully resolved to any - * resulting services. - */ bool Lookup(const std::string& name, std::vector& vAddr, int portDefault, bool fAllowLookup, unsigned int nMaxSolutions, DNSLookupFn dns_lookup_function) { if (name.empty() || !ValidAsCString(name)) { @@ -254,12 +213,6 @@ bool Lookup(const std::string& name, std::vector& vAddr, int portDefau return true; } -/** - * Resolve a service string to its first corresponding service. - * - * @see Lookup(const std::string&, std::vector&, int, bool, unsigned int, DNSLookupFn) - * for additional parameter descriptions. - */ bool Lookup(const std::string& name, CService& addr, int portDefault, bool fAllowLookup, DNSLookupFn dns_lookup_function) { if (!ValidAsCString(name)) { @@ -273,15 +226,6 @@ bool Lookup(const std::string& name, CService& addr, int portDefault, bool fAllo return true; } -/** - * Resolve a service string with a numeric IP to its first corresponding - * service. - * - * @returns The resulting CService if the resolution was successful, [::]:0 otherwise. - * - * @see Lookup(const std::string&, std::vector&, int, bool, unsigned int, DNSLookupFn) - * for additional parameter descriptions. - */ CService LookupNumeric(const std::string& name, int portDefault, DNSLookupFn dns_lookup_function) { if (!ValidAsCString(name)) { @@ -419,24 +363,6 @@ static std::string Socks5ErrorString(uint8_t err) } } -/** - * Connect to a specified destination service through an already connected - * SOCKS5 proxy. - * - * @param strDest The destination fully-qualified domain name. - * @param port The destination port. - * @param auth The credentials with which to authenticate with the specified - * SOCKS5 proxy. - * @param sock The SOCKS5 proxy socket. - * - * @returns Whether or not the operation succeeded. - * - * @note The specified SOCKS5 proxy socket must already be connected to the - * SOCKS5 proxy. - * - * @see RFC1928: SOCKS Protocol - * Version 5 - */ bool Socks5(const std::string& strDest, int port, const ProxyCredentials* auth, const Sock& sock) { IntrRecvError recvr; @@ -611,18 +537,6 @@ static void LogConnectFailure(bool manual_connection, const char* fmt, const Arg } } -/** - * Try to connect to the specified service on the specified socket. - * - * @param addrConnect The service to which to connect. - * @param hSocket The socket on which to connect. - * @param nTimeout Wait this many milliseconds for the connection to be - * established. - * @param manual_connection Whether or not the connection was manually requested - * (e.g. through the addnode RPC) - * - * @returns Whether or not a connection was successfully made. - */ bool ConnectSocketDirectly(const CService &addrConnect, const SOCKET& hSocket, int nTimeout, bool manual_connection) { // Create a sockaddr from the specified service. @@ -721,22 +635,6 @@ bool GetProxy(enum Network net, proxyType &proxyInfoOut) { return true; } -/** - * Set the name proxy to use for all connections to nodes specified by a - * hostname. After setting this proxy, connecting to a node specified by a - * hostname won't result in a local lookup of said hostname, rather, connect to - * the node by asking the name proxy for a proxy connection to the hostname, - * effectively delegating the hostname lookup to the specified proxy. - * - * This delegation increases privacy for those who set the name proxy as they no - * longer leak their external hostname queries to their DNS servers. - * - * @returns Whether or not the operation succeeded. - * - * @note SOCKS5's support for UDP-over-SOCKS5 has been considered, but no SOCK5 - * server in common use (most notably Tor) actually implements UDP - * support, and a DNS resolver is beyond the scope of this project. - */ bool SetNameProxy(const proxyType &addrProxy) { if (!addrProxy.IsValid()) return false; @@ -767,21 +665,6 @@ bool IsProxy(const CNetAddr &addr) { return false; } -/** - * Connect to a specified destination service through a SOCKS5 proxy by first - * connecting to the SOCKS5 proxy. - * - * @param proxy The SOCKS5 proxy. - * @param strDest The destination service to which to connect. - * @param port The destination port. - * @param sock The socket on which to connect to the SOCKS5 proxy. - * @param nTimeout Wait this many milliseconds for the connection to the SOCKS5 - * proxy to be established. - * @param[out] outProxyConnectionFailed Whether or not the connection to the - * SOCKS5 proxy failed. - * - * @returns Whether or not the operation succeeded. - */ bool ConnectThroughProxy(const proxyType& proxy, const std::string& strDest, int port, const Sock& sock, int nTimeout, bool& outProxyConnectionFailed) { // first connect to proxy server @@ -805,17 +688,6 @@ bool ConnectThroughProxy(const proxyType& proxy, const std::string& strDest, int return true; } -/** - * Parse and resolve a specified subnet string into the appropriate internal - * representation. - * - * @param strSubnet A string representation of a subnet of the form `network - * address [ "/", ( CIDR-style suffix | netmask ) ]`(e.g. - * `2001:db8::/32`, `192.0.2.0/255.255.255.0`, or `8.8.8.8`). - * @param ret The resulting internal representation of a subnet. - * - * @returns Whether the operation succeeded or not. - */ bool LookupSubNet(const std::string& strSubnet, CSubNet& ret, DNSLookupFn dns_lookup_function) { if (!ValidAsCString(strSubnet)) { diff --git a/src/netbase.h b/src/netbase.h index 227da1a63b..e13ca4dbc5 100644 --- a/src/netbase.h +++ b/src/netbase.h @@ -76,6 +76,22 @@ std::vector GetNetworkNames(bool append_unroutable = false); bool SetProxy(enum Network net, const proxyType &addrProxy); bool GetProxy(enum Network net, proxyType &proxyInfoOut); bool IsProxy(const CNetAddr &addr); +/** + * Set the name proxy to use for all connections to nodes specified by a + * hostname. After setting this proxy, connecting to a node specified by a + * hostname won't result in a local lookup of said hostname, rather, connect to + * the node by asking the name proxy for a proxy connection to the hostname, + * effectively delegating the hostname lookup to the specified proxy. + * + * This delegation increases privacy for those who set the name proxy as they no + * longer leak their external hostname queries to their DNS servers. + * + * @returns Whether or not the operation succeeded. + * + * @note SOCKS5's support for UDP-over-SOCKS5 has been considered, but no SOCK5 + * server in common use (most notably Tor) actually implements UDP + * support, and a DNS resolver is beyond the scope of this project. + */ bool SetNameProxy(const proxyType &addrProxy); bool HaveNameProxy(); bool GetNameProxy(proxyType &nameProxyOut); @@ -83,11 +99,83 @@ bool GetNameProxy(proxyType &nameProxyOut); using DNSLookupFn = std::function(const std::string&, bool)>; extern DNSLookupFn g_dns_lookup; +/** + * Resolve a host string to its corresponding network addresses. + * + * @param name The string representing a host. Could be a name or a numerical + * IP address (IPv6 addresses in their bracketed form are + * allowed). + * @param[out] vIP The resulting network addresses to which the specified host + * string resolved. + * + * @returns Whether or not the specified host string successfully resolved to + * any resulting network addresses. + * + * @see Lookup(const std::string&, std::vector&, int, bool, unsigned int, DNSLookupFn) + * for additional parameter descriptions. + */ bool LookupHost(const std::string& name, std::vector& vIP, unsigned int nMaxSolutions, bool fAllowLookup, DNSLookupFn dns_lookup_function = g_dns_lookup); + +/** + * Resolve a host string to its first corresponding network address. + * + * @see LookupHost(const std::string&, std::vector&, unsigned int, bool, DNSLookupFn) + * for additional parameter descriptions. + */ bool LookupHost(const std::string& name, CNetAddr& addr, bool fAllowLookup, DNSLookupFn dns_lookup_function = g_dns_lookup); -bool Lookup(const std::string& name, CService& addr, int portDefault, bool fAllowLookup, DNSLookupFn dns_lookup_function = g_dns_lookup); + +/** + * Resolve a service string to its corresponding service. + * + * @param name The string representing a service. Could be a name or a + * numerical IP address (IPv6 addresses should be in their + * disambiguated bracketed form), optionally followed by a port + * number. (e.g. example.com:8333 or + * [2001:db8:85a3:8d3:1319:8a2e:370:7348]:420) + * @param[out] vAddr The resulting services to which the specified service string + * resolved. + * @param portDefault The default port for resulting services if not specified + * by the service string. + * @param fAllowLookup Whether or not hostname lookups are permitted. If yes, + * external queries may be performed. + * @param nMaxSolutions The maximum number of results we want, specifying 0 + * means "as many solutions as we get." + * + * @returns Whether or not the service string successfully resolved to any + * resulting services. + */ bool Lookup(const std::string& name, std::vector& vAddr, int portDefault, bool fAllowLookup, unsigned int nMaxSolutions, DNSLookupFn dns_lookup_function = g_dns_lookup); + +/** + * Resolve a service string to its first corresponding service. + * + * @see Lookup(const std::string&, std::vector&, int, bool, unsigned int, DNSLookupFn) + * for additional parameter descriptions. + */ +bool Lookup(const std::string& name, CService& addr, int portDefault, bool fAllowLookup, DNSLookupFn dns_lookup_function = g_dns_lookup); + +/** + * Resolve a service string with a numeric IP to its first corresponding + * service. + * + * @returns The resulting CService if the resolution was successful, [::]:0 otherwise. + * + * @see Lookup(const std::string&, std::vector&, int, bool, unsigned int, DNSLookupFn) + * for additional parameter descriptions. + */ CService LookupNumeric(const std::string& name, int portDefault = 0, DNSLookupFn dns_lookup_function = g_dns_lookup); + +/** + * Parse and resolve a specified subnet string into the appropriate internal + * representation. + * + * @param strSubnet A string representation of a subnet of the form `network + * address [ "/", ( CIDR-style suffix | netmask ) ]`(e.g. + * `2001:db8::/32`, `192.0.2.0/255.255.255.0`, or `8.8.8.8`). + * @param ret The resulting internal representation of a subnet. + * + * @returns Whether the operation succeeded or not. + */ bool LookupSubNet(const std::string& strSubnet, CSubNet& subnet, DNSLookupFn dns_lookup_function = g_dns_lookup); /** @@ -102,14 +190,61 @@ std::unique_ptr CreateSockTCP(const CService& address_family); */ extern std::function(const CService&)> CreateSock; +/** + * Try to connect to the specified service on the specified socket. + * + * @param addrConnect The service to which to connect. + * @param hSocket The socket on which to connect. + * @param nTimeout Wait this many milliseconds for the connection to be + * established. + * @param manual_connection Whether or not the connection was manually requested + * (e.g. through the addnode RPC) + * + * @returns Whether or not a connection was successfully made. + */ bool ConnectSocketDirectly(const CService &addrConnect, const SOCKET& hSocketRet, int nTimeout, bool manual_connection); + +/** + * Connect to a specified destination service through a SOCKS5 proxy by first + * connecting to the SOCKS5 proxy. + * + * @param proxy The SOCKS5 proxy. + * @param strDest The destination service to which to connect. + * @param port The destination port. + * @param sock The socket on which to connect to the SOCKS5 proxy. + * @param nTimeout Wait this many milliseconds for the connection to the SOCKS5 + * proxy to be established. + * @param[out] outProxyConnectionFailed Whether or not the connection to the + * SOCKS5 proxy failed. + * + * @returns Whether or not the operation succeeded. + */ bool ConnectThroughProxy(const proxyType& proxy, const std::string& strDest, int port, const Sock& sock, int nTimeout, bool& outProxyConnectionFailed); + /** Disable or enable blocking-mode for a socket */ bool SetSocketNonBlocking(const SOCKET& hSocket, bool fNonBlocking); /** Set the TCP_NODELAY flag on a socket */ bool SetSocketNoDelay(const SOCKET& hSocket); void InterruptSocks5(bool interrupt); +/** + * Connect to a specified destination service through an already connected + * SOCKS5 proxy. + * + * @param strDest The destination fully-qualified domain name. + * @param port The destination port. + * @param auth The credentials with which to authenticate with the specified + * SOCKS5 proxy. + * @param sock The SOCKS5 proxy socket. + * + * @returns Whether or not the operation succeeded. + * + * @note The specified SOCKS5 proxy socket must already be connected to the + * SOCKS5 proxy. + * + * @see RFC1928: SOCKS Protocol + * Version 5 + */ bool Socks5(const std::string& strDest, int port, const ProxyCredentials* auth, const Sock& socket); #endif // BITCOIN_NETBASE_H From 8348a3742b938a1f3a24ee73ef8261931f93c7ff Mon Sep 17 00:00:00 2001 From: Jon Atack Date: Mon, 15 Mar 2021 16:54:42 +0100 Subject: [PATCH 3/3] net: fix hSocket param in netbase.h::ConnectSocketDirectly() --- src/netbase.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/netbase.h b/src/netbase.h index e13ca4dbc5..e98a21ce1f 100644 --- a/src/netbase.h +++ b/src/netbase.h @@ -202,7 +202,7 @@ extern std::function(const CService&)> CreateSock; * * @returns Whether or not a connection was successfully made. */ -bool ConnectSocketDirectly(const CService &addrConnect, const SOCKET& hSocketRet, int nTimeout, bool manual_connection); +bool ConnectSocketDirectly(const CService &addrConnect, const SOCKET& hSocket, int nTimeout, bool manual_connection); /** * Connect to a specified destination service through a SOCKS5 proxy by first