[tor-commits] [tor/master] addr: Document better is_local_addr_to_resolve_addr()

[nickm at torproject.org]

commit ec57cbf179257bc56b6649e30855a550eb110cd4
Author: David Goulet <dgoulet at torproject.org>
Date:   Tue Jun 30 09:32:21 2020 -0400

    addr: Document better is_local_addr_to_resolve_addr()
    
    This function is about learning if a given address is local to us as in the
    resolved address as a relay.
    
    Closes #40009
    
    Signed-off-by: David Goulet <dgoulet at torproject.org>
---
 src/app/config/resolve_addr.c | 26 ++++++++++++++++++++------
 1 file changed, 20 insertions(+), 6 deletions(-)

diff --git a/src/app/config/resolve_addr.c b/src/app/config/resolve_addr.c
index c8b44de84..8224e8868 100644
--- a/src/app/config/resolve_addr.c
+++ b/src/app/config/resolve_addr.c
@@ -568,8 +568,26 @@ find_my_address(const or_options_t *options, int family, int warn_severity,
   return true;
 }
 
-/** Return true iff <b>addr</b> is judged to be on the same network as us, or
- * on a private network.
+/** @brief: Return true iff the given addr is judged to be local to our
+ * resolved address.
+ *
+ * This function is used to tell whether another address is 'remote' enough
+ * that we can trust it when it tells us that we are reachable, or that we
+ * have a certain address."
+ *
+ * The criterion to learn if the address is local are the following:
+ *
+ *    1. Internal address.
+ *    2. If EnforceDistinctSubnets is set then it is never local.
+ *    3. Network mask is compared. IPv4: /24 and IPv6 /48. This is different
+ *       from the path selection that looks at /16 and /32 because we only
+ *       want to learn here if the address is considered to come from the
+ *       Internet basically.
+ *
+ * @param addr The address to test if local and also test against our resovled
+ *             address.
+ *
+ * @return True iff address is considered local or else False.
  */
 MOCK_IMPL(bool,
 is_local_to_resolve_addr, (const tor_addr_t *addr))
@@ -589,10 +607,6 @@ is_local_to_resolve_addr, (const tor_addr_t *addr))
 
   switch (family) {
   case AF_INET:
-    /* XXX: Why is this /24 and not /16 which the rest of tor does? Unknown
-     * reasons at the moment highlighted in ticket #40009. Because of that, we
-     * can't use addrs_in_same_network_family(). */
-
     /* It's possible that this next check will hit before the first time
      * find_my_address actually succeeds. For clients, it is likely that
      * find_my_address will never be called at all. In those cases,