tor

addressmap.c (37938B)

---

/* Copyright (c) 2001 Matej Pfajfar.
* Copyright (c) 2001-2004, Roger Dingledine.
* Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
* Copyright (c) 2007-2021, The Tor Project, Inc. */
/* See LICENSE for licensing information */

/**
* \file addressmap.c
*
* \brief The addressmap module manages the processes by which we rewrite
* addresses in client requess.  It handles the MapAddress controller and
* torrc commands, and the TrackHostExits feature, and the client-side DNS
* cache (deprecated).
*/

#define ADDRESSMAP_PRIVATE

#include "lib/crypt_ops/crypto_rand.h"

#include "core/or/or.h"
#include "feature/client/addressmap.h"
#include "core/or/circuituse.h"
#include "app/config/config.h"
#include "core/or/connection_edge.h"
#include "feature/control/control_events.h"
#include "feature/nodelist/nodelist.h"
#include "feature/nodelist/routerset.h"

#include "core/or/entry_connection_st.h"

/** A client-side struct to remember requests to rewrite addresses
* to new addresses. These structs are stored in the hash table
* "addressmap" below.
*
* There are 5 ways to set an address mapping:
* - A MapAddress command from the controller [permanent]
* - An AddressMap directive in the torrc [permanent]
* - When a TrackHostExits torrc directive is triggered [temporary]
* - When a DNS resolve succeeds [temporary]
* - When a DNS resolve fails [temporary]
*
* When an addressmap request is made but one is already registered,
* the new one is replaced only if the currently registered one has
* no "new_address" (that is, it's in the process of DNS resolve),
* or if the new one is permanent (expires==0 or 1).
*
* (We overload the 'expires' field, using "0" for mappings set via
* the configuration file, "1" for mappings set from the control
* interface, and other values for DNS and TrackHostExit mappings that can
* expire.)
*
* A mapping may be 'wildcarded'.  If "src_wildcard" is true, then
* any address that ends with a . followed by the key for this entry will
* get remapped by it.  If "dst_wildcard" is also true, then only the
* matching suffix of such addresses will get replaced by new_address.
*/
typedef struct {
 char *new_address;
 time_t expires;
 addressmap_entry_source_bitfield_t source:3;
 unsigned src_wildcard:1;
 unsigned dst_wildcard:1;
 short num_resolve_failures;
} addressmap_entry_t;

/** Entry for mapping addresses to which virtual address we mapped them to. */
typedef struct {
 char *ipv4_address;
 char *ipv6_address;
 char *hostname_address;
} virtaddress_entry_t;

/** A hash table to store client-side address rewrite instructions. */
static strmap_t *addressmap=NULL;

/**
* Table mapping addresses to which virtual address, if any, we
* assigned them to.
*
* We maintain the following invariant: if [A,B] is in
* virtaddress_reversemap, then B must be a virtual address, and [A,B]
* must be in addressmap.  We do not require that the converse hold:
* if it fails, then we could end up mapping two virtual addresses to
* the same address, which is no disaster.
**/
static strmap_t *virtaddress_reversemap=NULL;

/** Initialize addressmap. */
void
addressmap_init(void)
{
 addressmap = strmap_new();
 virtaddress_reversemap = strmap_new();
}

#define addressmap_ent_free(ent)                                        \
 FREE_AND_NULL(addressmap_entry_t, addressmap_ent_free_, (ent))

/** Free the memory associated with the addressmap entry <b>_ent</b>. */
static void
addressmap_ent_free_(addressmap_entry_t *ent)
{
 if (!ent)
   return;

 tor_free(ent->new_address);
 tor_free(ent);
}

static void
addressmap_ent_free_void(void *ent)
{
 addressmap_ent_free_(ent);
}

#define addressmap_virtaddress_ent_free(ent)                            \
 FREE_AND_NULL(virtaddress_entry_t, addressmap_virtaddress_ent_free_, (ent))

/** Free storage held by a virtaddress_entry_t* entry in <b>_ent</b>. */
static void
addressmap_virtaddress_ent_free_(virtaddress_entry_t *ent)
{
 if (!ent)
   return;
 tor_free(ent->ipv4_address);
 tor_free(ent->ipv6_address);
 tor_free(ent->hostname_address);
 tor_free(ent);
}

static void
addressmap_virtaddress_ent_free_void(void *ent)
{
 addressmap_virtaddress_ent_free_(ent);
}

/** Remove <b>address</b> (which must map to <b>ent</b>) from the
* virtual address map. */
static void
addressmap_virtaddress_remove(const char *address, addressmap_entry_t *ent)
{
 if (ent && ent->new_address &&
     address_is_in_virtual_range(ent->new_address)) {
   virtaddress_entry_t *ve =
     strmap_get(virtaddress_reversemap, ent->new_address);
   /*log_fn(LOG_NOTICE,"remove reverse mapping for %s",ent->new_address);*/
   if (ve) {
     if (!strcmp(address, ve->ipv4_address))
       tor_free(ve->ipv4_address);
     if (!strcmp(address, ve->ipv6_address))
       tor_free(ve->ipv6_address);
     if (!strcmp(address, ve->hostname_address))
       tor_free(ve->hostname_address);
     if (!ve->ipv4_address && !ve->ipv6_address && !ve->hostname_address) {
       tor_free(ve);
       strmap_remove(virtaddress_reversemap, ent->new_address);
     }
   }
 }
}

/** Remove <b>ent</b> (which must be mapped to by <b>address</b>) from the
* client address maps, and then free it. */
static void
addressmap_ent_remove(const char *address, addressmap_entry_t *ent)
{
 addressmap_virtaddress_remove(address, ent);
 addressmap_ent_free(ent);
}

/** Unregister all TrackHostExits mappings from any address to
* *.exitname.exit. */
void
clear_trackexithost_mappings(const char *exitname)
{
 char *suffix = NULL;
 if (!addressmap || !exitname)
   return;
 tor_asprintf(&suffix, ".%s.exit", exitname);
 tor_strlower(suffix);

 STRMAP_FOREACH_MODIFY(addressmap, address, addressmap_entry_t *, ent) {
   if (ent->source == ADDRMAPSRC_TRACKEXIT &&
       !strcmpend(ent->new_address, suffix)) {
     addressmap_ent_remove(address, ent);
     MAP_DEL_CURRENT(address);
   }
 } STRMAP_FOREACH_END;

 tor_free(suffix);
}

/** Remove all TRACKEXIT mappings from the addressmap for which the target
* host is unknown or no longer allowed, or for which the source address
* is no longer in trackexithosts. */
void
addressmap_clear_excluded_trackexithosts(const or_options_t *options)
{
 const routerset_t *allow_nodes = options->ExitNodes;
 const routerset_t *exclude_nodes = options->ExcludeExitNodesUnion_;

 if (!addressmap)
   return;
 if (routerset_is_empty(allow_nodes))
   allow_nodes = NULL;
 if (allow_nodes == NULL && routerset_is_empty(exclude_nodes))
   return;

 STRMAP_FOREACH_MODIFY(addressmap, address, addressmap_entry_t *, ent) {
   size_t len;
   const char *target = ent->new_address, *dot;
   char *nodename;
   const node_t *node;

   if (!target) {
     /* DNS resolving in progress */
     continue;
   } else if (strcmpend(target, ".exit")) {
     /* Not a .exit mapping */
     continue;
   } else if (ent->source != ADDRMAPSRC_TRACKEXIT) {
     /* Not a trackexit mapping. */
     continue;
   }
   len = strlen(target);
   if (len < 6)
     continue; /* malformed. */
   dot = target + len - 6; /* dot now points to just before .exit */
   while (dot > target && *dot != '.')
     dot--;
   if (*dot == '.') dot++;
   nodename = tor_strndup(dot, len-5-(dot-target));
   node = node_get_by_nickname(nodename, NNF_NO_WARN_UNNAMED);
   tor_free(nodename);
   if (!node ||
       (allow_nodes && !routerset_contains_node(allow_nodes, node)) ||
       routerset_contains_node(exclude_nodes, node) ||
       !hostname_in_track_host_exits(options, address)) {
     /* We don't know this one, or we want to be rid of it. */
     addressmap_ent_remove(address, ent);
     MAP_DEL_CURRENT(address);
   }
 } STRMAP_FOREACH_END;
}

/** Return true iff <b>address</b> is one that we are configured to
* automap on resolve according to <b>options</b>. */
int
addressmap_address_should_automap(const char *address,
                                 const or_options_t *options)
{
 const smartlist_t *suffix_list = options->AutomapHostsSuffixes;

 if (!suffix_list)
   return 0;

 SMARTLIST_FOREACH_BEGIN(suffix_list, const char *, suffix) {
   if (!strcmp(suffix, "."))
     return 1;
   if (!strcasecmpend(address, suffix))
     return 1;
 } SMARTLIST_FOREACH_END(suffix);
 return 0;
}

/** Remove all AUTOMAP mappings from the addressmap for which the
* source address no longer matches AutomapHostsSuffixes, which is
* no longer allowed by AutomapHostsOnResolve, or for which the
* target address is no longer in the virtual network. */
void
addressmap_clear_invalid_automaps(const or_options_t *options)
{
 int clear_all = !options->AutomapHostsOnResolve;
 const smartlist_t *suffixes = options->AutomapHostsSuffixes;

 if (!addressmap)
   return;

 if (!suffixes)
   clear_all = 1; /* This should be impossible, but let's be sure. */

 STRMAP_FOREACH_MODIFY(addressmap, src_address, addressmap_entry_t *, ent) {
   int remove_this = clear_all;
   if (ent->source != ADDRMAPSRC_AUTOMAP)
     continue; /* not an automap mapping. */

   if (!remove_this) {
     remove_this = ! addressmap_address_should_automap(src_address, options);
   }

   if (!remove_this && ! address_is_in_virtual_range(ent->new_address))
     remove_this = 1;

   if (remove_this) {
     addressmap_ent_remove(src_address, ent);
     MAP_DEL_CURRENT(src_address);
   }
 } STRMAP_FOREACH_END;
}

/** Remove all entries from the addressmap that were set via the
* configuration file or the command line. */
void
addressmap_clear_configured(void)
{
 addressmap_get_mappings(NULL, 0, 0, 0);
}

/** Remove all entries from the addressmap that are set to expire, ever. */
void
addressmap_clear_transient(void)
{
 addressmap_get_mappings(NULL, 2, TIME_MAX, 0);
}

/** Clean out entries from the addressmap cache that were
* added long enough ago that they are no longer valid.
*/
void
addressmap_clean(time_t now)
{
 addressmap_get_mappings(NULL, 2, now, 0);
}

/** Free all the elements in the addressmap, and free the addressmap
* itself. */
void
addressmap_free_all(void)
{
 strmap_free(addressmap, addressmap_ent_free_void);
 addressmap = NULL;

 strmap_free(virtaddress_reversemap, addressmap_virtaddress_ent_free_void);
 virtaddress_reversemap = NULL;
}

/** Try to find a match for AddressMap expressions that use
*  wildcard notation such as '*.c.d *.e.f' (so 'a.c.d' will map to 'a.e.f') or
*  '*.c.d a.b.c' (so 'a.c.d' will map to a.b.c).
*  Return the matching entry in AddressMap or NULL if no match is found.
*  For expressions such as '*.c.d *.e.f', truncate <b>address</b> 'a.c.d'
*  to 'a' before we return the matching AddressMap entry.
*
* This function does not handle the case where a pattern of the form "*.c.d"
* matches the address c.d -- that's done by the main addressmap_rewrite
* function.
*/
static addressmap_entry_t *
addressmap_match_superdomains(char *address)
{
 addressmap_entry_t *val;
 char *cp;

 cp = address;
 while ((cp = strchr(cp, '.'))) {
   /* cp now points to a suffix of address that begins with a . */
   val = strmap_get_lc(addressmap, cp+1);
   if (val && val->src_wildcard) {
     if (val->dst_wildcard)
       *cp = '\0';
     return val;
   }
   ++cp;
 }
 return NULL;
}

/** Look at address, and rewrite it until it doesn't want any
* more rewrites; but don't get into an infinite loop.
* Don't write more than maxlen chars into address.  Return true if the
* address changed; false otherwise.  Set *<b>expires_out</b> to the
* expiry time of the result, or to <b>time_max</b> if the result does
* not expire.
*
* If <b>exit_source_out</b> is non-null, we set it as follows.  If we the
* address starts out as a non-exit address, and we remap it to an .exit
* address at any point, then set *<b>exit_source_out</b> to the
* address_entry_source_t of the first such rule.  Set *<b>exit_source_out</b>
* to ADDRMAPSRC_NONE if there is no such rewrite, or if the original address
* was a .exit.
*/
int
addressmap_rewrite(char *address, size_t maxlen,
                  unsigned flags,
                  time_t *expires_out,
                  addressmap_entry_source_t *exit_source_out)
{
 addressmap_entry_t *ent;
 int rewrites;
 time_t expires = TIME_MAX;
 addressmap_entry_source_t exit_source = ADDRMAPSRC_NONE;
 char *addr_orig = tor_strdup(address);
 char *log_addr_orig = NULL;

 /* We use a loop here to limit the total number of rewrites we do,
  * so that we can't hit an infinite loop. */
 for (rewrites = 0; rewrites < 16; rewrites++) {
   int exact_match = 0;
   log_addr_orig = tor_strdup(escaped_safe_str_client(address));

   /* First check to see if there's an exact match for this address */
   ent = strmap_get(addressmap, address);

   if (!ent || !ent->new_address) {
     /* And if we don't have an exact match, try to check whether
      * we have a pattern-based match.
      */
     ent = addressmap_match_superdomains(address);
   } else {
     if (ent->src_wildcard && !ent->dst_wildcard &&
         !strcasecmp(address, ent->new_address)) {
       /* This is a rule like "rewrite *.example.com to example.com", and we
        * just got "example.com". Instead of calling it an infinite loop,
        * call it complete. */
       goto done;
     }
     exact_match = 1;
   }

   if (!ent || !ent->new_address) {
     /* We still have no match at all.  We're done! */
     goto done;
   }

   /* Check whether the flags we were passed tell us not to use this
    * mapping. */
   switch (ent->source) {
     case ADDRMAPSRC_DNS:
       {
         sa_family_t f;
         tor_addr_t tmp;
         f = tor_addr_parse(&tmp, ent->new_address);
         if (f == AF_INET && !(flags & AMR_FLAG_USE_IPV4_DNS))
           goto done;
         else if (f == AF_INET6 && !(flags & AMR_FLAG_USE_IPV6_DNS))
           goto done;
       }
       break;
     case ADDRMAPSRC_CONTROLLER:
     case ADDRMAPSRC_TORRC:
       if (!(flags & AMR_FLAG_USE_MAPADDRESS))
         goto done;
       break;
     case ADDRMAPSRC_AUTOMAP:
       if (!(flags & AMR_FLAG_USE_AUTOMAP))
         goto done;
       break;
     case ADDRMAPSRC_TRACKEXIT:
       if (!(flags & AMR_FLAG_USE_TRACKEXIT))
         goto done;
       break;
     case ADDRMAPSRC_NONE:
     default:
       log_warn(LD_BUG, "Unknown addrmap source value %d. Ignoring it.",
                (int) ent->source);
       goto done;
   }

   /* Now fill in the address with the new address. That might be via
    * appending some new stuff to the end, or via just replacing it. */
   if (ent->dst_wildcard && !exact_match) {
     strlcat(address, ".", maxlen);
     strlcat(address, ent->new_address, maxlen);
   } else {
     strlcpy(address, ent->new_address, maxlen);
   }

   /* Is this now a .exit address?  If so, remember where we got it.*/
   if (!strcmpend(address, ".exit") &&
       strcmpend(addr_orig, ".exit") &&
       exit_source == ADDRMAPSRC_NONE) {
     exit_source = ent->source;
   }

   log_info(LD_APP, "Addressmap: rewriting %s to %s",
            log_addr_orig, escaped_safe_str_client(address));
   if (ent->expires > 1 && ent->expires < expires)
     expires = ent->expires;

   tor_free(log_addr_orig);
 }
 log_warn(LD_CONFIG,
          "Loop detected: we've rewritten %s 16 times! Using it as-is.",
          escaped_safe_str_client(address));
 /* it's fine to rewrite a rewrite, but don't loop forever */

done:
 tor_free(addr_orig);
 tor_free(log_addr_orig);
 if (exit_source_out)
   *exit_source_out = exit_source;
 if (expires_out)
   *expires_out = expires;
 return (rewrites > 0);
}

/** If we have a cached reverse DNS entry for the address stored in the
* <b>maxlen</b>-byte buffer <b>address</b> (typically, a dotted quad) then
* rewrite to the cached value and return 1.  Otherwise return 0.  Set
* *<b>expires_out</b> to the expiry time of the result, or to <b>time_max</b>
* if the result does not expire. */
int
addressmap_rewrite_reverse(char *address, size_t maxlen, unsigned flags,
                          time_t *expires_out)
{
 char *s, *cp;
 addressmap_entry_t *ent;
 int r = 0;
 {
   sa_family_t f;
   tor_addr_t tmp;
   f = tor_addr_parse(&tmp, address);
   if (f == AF_INET && !(flags & AMR_FLAG_USE_IPV4_DNS))
     return 0;
   else if (f == AF_INET6 && !(flags & AMR_FLAG_USE_IPV6_DNS))
     return 0;
   /* FFFF we should reverse-map virtual addresses even if we haven't
    * enabled DNS caching. */
 }

 tor_asprintf(&s, "REVERSE[%s]", address);
 ent = strmap_get(addressmap, s);
 if (ent) {
   cp = tor_strdup(escaped_safe_str_client(ent->new_address));
   log_info(LD_APP, "Rewrote reverse lookup %s -> %s",
            escaped_safe_str_client(s), cp);
   tor_free(cp);
   strlcpy(address, ent->new_address, maxlen);
   r = 1;
 }

 if (expires_out)
   *expires_out = (ent && ent->expires > 1) ? ent->expires : TIME_MAX;

 tor_free(s);
 return r;
}

/** Return 1 if <b>address</b> is already registered, else return 0. If address
* is already registered, and <b>update_expires</b> is non-zero, then update
* the expiry time on the mapping with update_expires if it is a
* mapping created by TrackHostExits. */
int
addressmap_have_mapping(const char *address, int update_expiry)
{
 addressmap_entry_t *ent;
 if (!(ent=strmap_get_lc(addressmap, address)))
   return 0;
 if (update_expiry && ent->source==ADDRMAPSRC_TRACKEXIT)
   ent->expires=time(NULL) + update_expiry;
 return 1;
}

/** Register a request to map <b>address</b> to <b>new_address</b>,
* which will expire on <b>expires</b> (or 0 if never expires from
* config file, 1 if never expires from controller, 2 if never expires
* (virtual address mapping) from the controller.)
*
* <b>new_address</b> should be a newly dup'ed string, which we'll use or
* free as appropriate. We will leave <b>address</b> alone.
*
* If <b>wildcard_addr</b> is true, then the mapping will match any address
* equal to <b>address</b>, or any address ending with a period followed by
* <b>address</b>.  If <b>wildcard_addr</b> and <b>wildcard_new_addr</b> are
* both true, the mapping will rewrite addresses that end with
* ".<b>address</b>" into ones that end with ".<b>new_address</b>".
*
* If <b>new_address</b> is NULL, or <b>new_address</b> is equal to
* <b>address</b> and <b>wildcard_addr</b> is equal to
* <b>wildcard_new_addr</b>, remove any mappings that exist from
* <b>address</b>.
*
* It is an error to set <b>wildcard_new_addr</b> if <b>wildcard_addr</b> is
* not set. */
void
addressmap_register(const char *address, char *new_address, time_t expires,
                   addressmap_entry_source_t source,
                   const int wildcard_addr,
                   const int wildcard_new_addr, uint64_t stream_id)
{
 addressmap_entry_t *ent;

 if (wildcard_new_addr)
   tor_assert(wildcard_addr);

 ent = strmap_get(addressmap, address);
 if (!new_address || (!strcasecmp(address,new_address) &&
                      wildcard_addr == wildcard_new_addr)) {
   /* Remove the mapping, if any. */
   tor_free(new_address);
   if (ent) {
     addressmap_ent_remove(address,ent);
     strmap_remove(addressmap, address);
   }
   return;
 }
 if (!ent) { /* make a new one and register it */
   ent = tor_malloc_zero(sizeof(addressmap_entry_t));
   strmap_set(addressmap, address, ent);
 } else if (ent->new_address) { /* we need to clean up the old mapping. */
   if (expires > 1) {
     log_info(LD_APP,"Temporary addressmap ('%s' to '%s') not performed, "
              "since it's already mapped to '%s'",
              safe_str_client(address),
              safe_str_client(new_address),
              safe_str_client(ent->new_address));
     tor_free(new_address);
     return;
   }
   if (address_is_in_virtual_range(ent->new_address) &&
       expires != 2) {
     /* XXX This isn't the perfect test; we want to avoid removing
      * mappings set from the control interface _as virtual mapping */
     addressmap_virtaddress_remove(address, ent);
   }
   tor_free(ent->new_address);
 } /* else { we have an in-progress resolve with no mapping. } */

 ent->new_address = new_address;
 ent->expires = expires==2 ? 1 : expires;
 ent->num_resolve_failures = 0;
 ent->source = source;
 ent->src_wildcard = wildcard_addr ? 1 : 0;
 ent->dst_wildcard = wildcard_new_addr ? 1 : 0;

 log_info(LD_CONFIG, "Addressmap: (re)mapped '%s' to '%s'",
          safe_str_client(address),
          safe_str_client(ent->new_address));
 control_event_address_mapped(address, ent->new_address,
                              expires, NULL, 1, stream_id);
}

/** An attempt to resolve <b>address</b> failed at some OR.
* Increment the number of resolve failures we have on record
* for it, and then return that number.
*/
int
client_dns_incr_failures(const char *address)
{
 addressmap_entry_t *ent = strmap_get(addressmap, address);
 if (!ent) {
   ent = tor_malloc_zero(sizeof(addressmap_entry_t));
   ent->expires = time(NULL) + MAX_DNS_ENTRY_AGE;
   strmap_set(addressmap,address,ent);
 }
 if (ent->num_resolve_failures < SHRT_MAX)
   ++ent->num_resolve_failures; /* don't overflow */
 log_info(LD_APP, "Address %s now has %d resolve failures.",
          safe_str_client(address),
          ent->num_resolve_failures);
 return ent->num_resolve_failures;
}

/** If <b>address</b> is in the client DNS addressmap, reset
* the number of resolve failures we have on record for it.
* This is used when we fail a stream because it won't resolve:
* otherwise future attempts on that address will only try once.
*/
void
client_dns_clear_failures(const char *address)
{
 addressmap_entry_t *ent = strmap_get(addressmap, address);
 if (ent)
   ent->num_resolve_failures = 0;
}

/** Record the fact that <b>address</b> resolved to <b>name</b>.
* We can now use this in subsequent streams via addressmap_rewrite()
* so we can more correctly choose an exit that will allow <b>address</b>.
*
* If <b>exitname</b> is defined, then append the addresses with
* ".exitname.exit" before registering the mapping.
*
* If <b>ttl</b> is nonnegative, the mapping will be valid for
* <b>ttl</b>seconds; otherwise, we use the default.
*/
static void
client_dns_set_addressmap_impl(entry_connection_t *for_conn,
                              const char *address, const char *name,
                              const char *exitname,
                              int ttl)
{
 char *extendedaddress=NULL, *extendedval=NULL;
 uint64_t stream_id = 0;

 tor_assert(address);
 tor_assert(name);

 if (for_conn) {
   stream_id = ENTRY_TO_CONN(for_conn)->global_identifier;
 }

 if (ttl<0)
   ttl = DEFAULT_DNS_TTL;
 else
   ttl = clip_dns_ttl(ttl);

 if (exitname) {
   /* XXXX fails to ever get attempts to get an exit address of
    * google.com.digest[=~]nickname.exit; we need a syntax for this that
    * won't make strict RFC952-compliant applications (like us) barf. */
   tor_asprintf(&extendedaddress,
                "%s.%s.exit", address, exitname);
   tor_asprintf(&extendedval,
                "%s.%s.exit", name, exitname);
 } else {
   tor_asprintf(&extendedaddress,
                "%s", address);
   tor_asprintf(&extendedval,
                "%s", name);
 }
 addressmap_register(extendedaddress, extendedval,
                     time(NULL) + ttl, ADDRMAPSRC_DNS, 0, 0, stream_id);
 tor_free(extendedaddress);
}

/** Record the fact that <b>address</b> resolved to <b>val</b>.
* We can now use this in subsequent streams via addressmap_rewrite()
* so we can more correctly choose an exit that will allow <b>address</b>.
*
* If <b>exitname</b> is defined, then append the addresses with
* ".exitname.exit" before registering the mapping.
*
* If <b>ttl</b> is nonnegative, the mapping will be valid for
* <b>ttl</b>seconds; otherwise, we use the default.
*/
void
client_dns_set_addressmap(entry_connection_t *for_conn,
                         const char *address,
                         const tor_addr_t *val,
                         const char *exitname,
                         int ttl)
{
 tor_addr_t addr_tmp;
 char valbuf[TOR_ADDR_BUF_LEN];

 tor_assert(address);
 tor_assert(val);

 if (tor_addr_parse(&addr_tmp, address) >= 0)
   return; /* If address was an IP address already, don't add a mapping. */

 if (tor_addr_family(val) == AF_INET) {
   if (! for_conn->entry_cfg.cache_ipv4_answers)
     return;
 } else if (tor_addr_family(val) == AF_INET6) {
   if (! for_conn->entry_cfg.cache_ipv6_answers)
     return;
 }

 if (! tor_addr_to_str(valbuf, val, sizeof(valbuf), 1))
   return;

 client_dns_set_addressmap_impl(for_conn, address, valbuf, exitname, ttl);
}

/** Add a cache entry noting that <b>address</b> (ordinarily a dotted quad)
* resolved via a RESOLVE_PTR request to the hostname <b>v</b>.
*
* If <b>exitname</b> is defined, then append the addresses with
* ".exitname.exit" before registering the mapping.
*
* If <b>ttl</b> is nonnegative, the mapping will be valid for
* <b>ttl</b>seconds; otherwise, we use the default.
*/
void
client_dns_set_reverse_addressmap(entry_connection_t *for_conn,
                                 const char *address, const char *v,
                                 const char *exitname,
                                 int ttl)
{
 char *s = NULL;
 {
   tor_addr_t tmp_addr;
   sa_family_t f = tor_addr_parse(&tmp_addr, address);
   if ((f == AF_INET && ! for_conn->entry_cfg.cache_ipv4_answers) ||
       (f == AF_INET6 && ! for_conn->entry_cfg.cache_ipv6_answers))
     return;
 }
 tor_asprintf(&s, "REVERSE[%s]", address);
 client_dns_set_addressmap_impl(for_conn, s, v, exitname, ttl);
 tor_free(s);
}

/* By default, we hand out 127.192.0.1 through 127.254.254.254.
* These addresses should map to localhost, so even if the
* application accidentally tried to connect to them directly (not
* via Tor), it wouldn't get too far astray.
*
* These options are configured by parse_virtual_addr_network().
*/

static virtual_addr_conf_t virtaddr_conf_ipv4;
static virtual_addr_conf_t virtaddr_conf_ipv6;

/** Read a netmask of the form 127.192.0.0/10 from "val", and check whether
* it's a valid set of virtual addresses to hand out in response to MAPADDRESS
* requests.  Return 0 on success; set *msg (if provided) to a newly allocated
* string and return -1 on failure.  If validate_only is false, sets the
* actual virtual address range to the parsed value. */
int
parse_virtual_addr_network(const char *val, sa_family_t family,
                          int validate_only,
                          char **msg)
{
 const int ipv6 = (family == AF_INET6);
 tor_addr_t addr;
 maskbits_t bits;
 const int max_prefix_bits = ipv6 ? 104 : 16;
 virtual_addr_conf_t *conf = ipv6 ? &virtaddr_conf_ipv6 : &virtaddr_conf_ipv4;

 if (!val || val[0] == '\0') {
   if (msg)
     tor_asprintf(msg, "Value not present (%s) after VirtualAddressNetwork%s",
                  val?"Empty":"NULL", ipv6?"IPv6":"");
   return -1;
 }
 if (tor_addr_parse_mask_ports(val, 0, &addr, &bits, NULL, NULL) < 0) {
   if (msg)
     tor_asprintf(msg, "Error parsing VirtualAddressNetwork%s %s",
                  ipv6?"IPv6":"", val);
   return -1;
 }
 if (tor_addr_family(&addr) != family) {
   if (msg)
     tor_asprintf(msg, "Incorrect address type for VirtualAddressNetwork%s",
                  ipv6?"IPv6":"");
   return -1;
 }
#if 0
 if (port_min != 1 || port_max != 65535) {
   if (msg)
     tor_asprintf(msg, "Can't specify ports on VirtualAddressNetwork%s",
                  ipv6?"IPv6":"");
   return -1;
 }
#endif /* 0 */

 if (bits > max_prefix_bits) {
   if (msg)
     tor_asprintf(msg, "VirtualAddressNetwork%s expects a /%d "
                  "network or larger",ipv6?"IPv6":"", max_prefix_bits);
   return -1;
 }

 if (validate_only)
   return 0;

 tor_addr_copy(&conf->addr, &addr);
 conf->bits = bits;

 return 0;
}

/**
* Return true iff <b>addr</b> is likely to have been returned by
* client_dns_get_unused_address.
**/
int
address_is_in_virtual_range(const char *address)
{
 tor_addr_t addr;
 tor_assert(address);
 if (!strcasecmpend(address, ".virtual")) {
   return 1;
 } else if (tor_addr_parse(&addr, address) >= 0) {
   const virtual_addr_conf_t *conf = (tor_addr_family(&addr) == AF_INET6) ?
     &virtaddr_conf_ipv6 : &virtaddr_conf_ipv4;
   if (tor_addr_compare_masked(&addr, &conf->addr, conf->bits, CMP_EXACT)==0)
     return 1;
 }
 return 0;
}

/** Return a random address conforming to the virtual address configuration
* in <b>conf</b>.
*/
STATIC void
get_random_virtual_addr(const virtual_addr_conf_t *conf, tor_addr_t *addr_out)
{
 uint8_t tmp[4];
 const uint8_t *addr_bytes;
 uint8_t bytes[16];
 const int ipv6 = tor_addr_family(&conf->addr) == AF_INET6;
 const int total_bytes = ipv6 ? 16 : 4;

 tor_assert(conf->bits <= total_bytes * 8);

 /* Set addr_bytes to the bytes of the virtual network, in host order */
 if (ipv6) {
   addr_bytes = tor_addr_to_in6_addr8(&conf->addr);
 } else {
   set_uint32(tmp, tor_addr_to_ipv4n(&conf->addr));
   addr_bytes = tmp;
 }

 /* Get an appropriate number of random bytes. */
 crypto_rand((char*)bytes, total_bytes);

 /* Now replace the first "conf->bits" bits of 'bytes' with addr_bytes*/
 if (conf->bits >= 8)
   memcpy(bytes, addr_bytes, conf->bits / 8);
 if (conf->bits & 7) {
   uint8_t mask = 0xff >> (conf->bits & 7);
   bytes[conf->bits/8] &= mask;
   bytes[conf->bits/8] |= addr_bytes[conf->bits/8] & ~mask;
 }

 if (ipv6)
   tor_addr_from_ipv6_bytes(addr_out, bytes);
 else
   tor_addr_from_ipv4n(addr_out, get_uint32(bytes));

 tor_assert(tor_addr_compare_masked(addr_out, &conf->addr,
                                    conf->bits, CMP_EXACT)==0);
}

/** Return a newly allocated string holding an address of <b>type</b>
* (one of RESOLVED_TYPE_{IPV4|IPV6|HOSTNAME}) that has not yet been
* mapped, and that is very unlikely to be the address of any real host.
*
* May return NULL if we have run out of virtual addresses.
*/
static char *
addressmap_get_virtual_address(int type)
{
 char buf[64];
 tor_assert(addressmap);

 if (type == RESOLVED_TYPE_HOSTNAME) {
   char rand_bytes[10];
   do {
     crypto_rand(rand_bytes, sizeof(rand_bytes));
     base32_encode(buf,sizeof(buf),rand_bytes,sizeof(rand_bytes));
     strlcat(buf, ".virtual", sizeof(buf));
   } while (strmap_get(addressmap, buf));
   return tor_strdup(buf);
 } else if (type == RESOLVED_TYPE_IPV4 || type == RESOLVED_TYPE_IPV6) {
   const int ipv6 = (type == RESOLVED_TYPE_IPV6);
   const virtual_addr_conf_t *conf = ipv6 ?
     &virtaddr_conf_ipv6 : &virtaddr_conf_ipv4;

   /* Don't try more than 1000 times.  This gives us P < 1e-9 for
    * failing to get a good address so long as the address space is
    * less than ~97.95% full.  That's always going to be true under
    * sensible circumstances for an IPv6 /10, and it's going to be
    * true for an IPv4 /10 as long as we've handed out less than
    * 4.08 million addresses. */
   uint32_t attempts = 1000;

   tor_addr_t addr;

   while (attempts--) {
     get_random_virtual_addr(conf, &addr);

     if (!ipv6) {
       /* Don't hand out any .0 or .255 address. */
       const uint32_t a = tor_addr_to_ipv4h(&addr);
       if ((a & 0xff) == 0 || (a & 0xff) == 0xff)
         continue;
     }

     tor_addr_to_str(buf, &addr, sizeof(buf), 1);
     if (!strmap_get(addressmap, buf)) {
       /* XXXX This code is to make sure I didn't add an undecorated version
        * by mistake. I hope it's needless. */
       char tmp[TOR_ADDR_BUF_LEN];
       tor_addr_to_str(tmp, &addr, sizeof(tmp), 0);
       if (strmap_get(addressmap, tmp)) {
         // LCOV_EXCL_START
         log_warn(LD_BUG, "%s wasn't in the addressmap, but %s was.",
                  buf, tmp);
         continue;
         // LCOV_EXCL_STOP
       }

       return tor_strdup(buf);
     }
   }
   log_warn(LD_CONFIG, "Ran out of virtual addresses!");
   return NULL;
 } else {
   // LCOV_EXCL_START
   log_warn(LD_BUG, "Called with unsupported address type (%d)", type);
   return NULL;
   // LCOV_EXCL_STOP
 }
}

/** A controller has requested that we map some address of type
* <b>type</b> to the address <b>new_address</b>.  Choose an address
* that is unlikely to be used, and map it, and return it in a newly
* allocated string.  If another address of the same type is already
* mapped to <b>new_address</b>, try to return a copy of that address.
*
* The string in <b>new_address</b> may be freed or inserted into a map
* as appropriate.  May return NULL if are out of virtual addresses.
**/
const char *
addressmap_register_virtual_address(int type, char *new_address)
{
 char **addrp;
 virtaddress_entry_t *vent;
 int vent_needs_to_be_added = 0;

 tor_assert(new_address);
 tor_assert(addressmap);
 tor_assert(virtaddress_reversemap);

 vent = strmap_get(virtaddress_reversemap, new_address);
 if (!vent) {
   vent = tor_malloc_zero(sizeof(virtaddress_entry_t));
   vent_needs_to_be_added = 1;
 }

 if (type == RESOLVED_TYPE_IPV4)
   addrp = &vent->ipv4_address;
 else if (type == RESOLVED_TYPE_IPV6)
   addrp = &vent->ipv6_address;
 else
   addrp = &vent->hostname_address;

 if (*addrp) {
   addressmap_entry_t *ent = strmap_get(addressmap, *addrp);
   if (ent && ent->new_address &&
       !strcasecmp(new_address, ent->new_address)) {
     tor_free(new_address);
     tor_assert(!vent_needs_to_be_added);
     return *addrp;
   } else {
     log_warn(LD_BUG,
              "Internal confusion: I thought that '%s' was mapped to by "
              "'%s', but '%s' really maps to '%s'. This is a harmless bug.",
              safe_str_client(new_address),
              safe_str_client(*addrp),
              safe_str_client(*addrp),
              ent?safe_str_client(ent->new_address):"(nothing)");
   }
 }

 tor_free(*addrp);
 *addrp = addressmap_get_virtual_address(type);
 if (!*addrp) {
   tor_free(vent);
   tor_free(new_address);
   return NULL;
 }
 log_info(LD_APP, "Registering map from %s to %s", *addrp, new_address);
 if (vent_needs_to_be_added)
   strmap_set(virtaddress_reversemap, new_address, vent);
 addressmap_register(*addrp, new_address, 2, ADDRMAPSRC_AUTOMAP, 0, 0, 0);

 /* FFFF register corresponding reverse mapping. */

#if 0
 {
   /* Try to catch possible bugs */
   addressmap_entry_t *ent;
   ent = strmap_get(addressmap, *addrp);
   tor_assert(ent);
   tor_assert(!strcasecmp(ent->new_address,new_address));
   vent = strmap_get(virtaddress_reversemap, new_address);
   tor_assert(vent);
   tor_assert(!strcasecmp(*addrp,
                          (type == RESOLVED_TYPE_IPV4) ?
                          vent->ipv4_address : vent->hostname_address));
   log_info(LD_APP, "Map from %s to %s okay.",
            safe_str_client(*addrp),
            safe_str_client(new_address));
 }
#endif /* 0 */

 return *addrp;
}

/** Return 1 if <b>address</b> has funny characters in it like colons. Return
* 0 if it's fine, or if we're configured to allow it anyway.  <b>client</b>
* should be true if we're using this address as a client; false if we're
* using it as a server.
*/
int
address_is_invalid_destination(const char *address, int client)
{
 if (client) {
   if (get_options()->AllowNonRFC953Hostnames)
     return 0;
 } else {
   if (get_options()->ServerDNSAllowNonRFC953Hostnames)
     return 0;
 }

 /* It might be an IPv6 address! */
 {
   tor_addr_t a;
   if (tor_addr_parse(&a, address) >= 0)
     return 0;
 }

 while (*address) {
   if (TOR_ISALNUM(*address) ||
       *address == '-' ||
       *address == '.' ||
       *address == '_') /* Underscore is not allowed, but Windows does it
                         * sometimes, just to thumb its nose at the IETF. */
     ++address;
   else
     return 1;
 }
 return 0;
}

/** Iterate over all address mappings which have expiry times between
* min_expires and max_expires, inclusive.  If sl is provided, add an
* "old-addr new-addr expiry" string to sl for each mapping, omitting
* the expiry time if want_expiry is false. If sl is NULL, remove the
* mappings.
*/
void
addressmap_get_mappings(smartlist_t *sl, time_t min_expires,
                       time_t max_expires, int want_expiry)
{
  strmap_iter_t *iter;
  const char *key;
  void *val_;
  addressmap_entry_t *val;

  if (!addressmap)
    addressmap_init();

  for (iter = strmap_iter_init(addressmap); !strmap_iter_done(iter); ) {
    strmap_iter_get(iter, &key, &val_);
    val = val_;
    if (val->expires >= min_expires && val->expires <= max_expires) {
      if (!sl) {
        iter = strmap_iter_next_rmv(addressmap,iter);
        addressmap_ent_remove(key, val);
        continue;
      } else if (val->new_address) {
        const char *src_wc = val->src_wildcard ? "*." : "";
        const char *dst_wc = val->dst_wildcard ? "*." : "";
        if (want_expiry) {
          if (val->expires < 3 || val->expires == TIME_MAX)
            smartlist_add_asprintf(sl, "%s%s %s%s NEVER",
                                   src_wc, key, dst_wc, val->new_address);
          else {
            char isotime[ISO_TIME_LEN+1];
            format_iso_time(isotime, val->expires);
            smartlist_add_asprintf(sl, "%s%s %s%s \"%s\"",
                                   src_wc, key, dst_wc, val->new_address,
                                   isotime);
          }
        } else {
          smartlist_add_asprintf(sl, "%s%s %s%s",
                                 src_wc, key, dst_wc, val->new_address);
        }
      }
    }
    iter = strmap_iter_next(addressmap,iter);
  }
}