tor

confmgt.c (44489B)

---

/* 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 confmgt.c
*
* \brief Back-end for parsing and generating key-value files, used to
*   implement the torrc file format and the state file.
*
* This module is used by config.c to parse and encode torrc
* configuration files, and by statefile.c to parse and encode the
* $DATADIR/state file.
*
* To use this module, its callers provide an instance of
* config_format_t to describe the mappings from a set of configuration
* options to a number of fields in a C structure.  With this mapping,
* the functions here can convert back and forth between the C structure
* specified, and a linked list of key-value pairs.
*/

#define CONFMGT_PRIVATE
#include "orconfig.h"
#include "lib/confmgt/confmgt.h"

#include "lib/confmgt/structvar.h"
#include "lib/confmgt/unitparse.h"
#include "lib/container/bitarray.h"
#include "lib/container/smartlist.h"
#include "lib/encoding/confline.h"
#include "lib/log/escape.h"
#include "lib/log/log.h"
#include "lib/log/util_bug.h"
#include "lib/string/compat_ctype.h"
#include "lib/string/printf.h"
#include "lib/string/util_string.h"

#include "ext/siphash.h"

/**
* A managed_var_t is an internal wrapper around a config_var_t in
* a config_format_t structure.  It is used by config_mgr_t to
* keep track of which option goes with which structure. */
typedef struct managed_var_t {
 /**
  * A pointer to the config_var_t for this option.
  */
 const config_var_t *cvar;
 /**
  * The index of the object in which this option is stored.  It is
  * IDX_TOPLEVEL to indicate that the object is the top-level object.
  **/
 int object_idx;
} managed_var_t;

static void config_reset(const config_mgr_t *fmt, void *options,
                        const managed_var_t *var, int use_defaults);
static void config_mgr_register_fmt(config_mgr_t *mgr,
                                   const config_format_t *fmt,
                                   int object_idx);

/** Release all storage held in a managed_var_t. */
static void
managed_var_free_(managed_var_t *mv)
{
 if (!mv)
   return;
 tor_free(mv);
}
#define managed_var_free(mv) \
 FREE_AND_NULL(managed_var_t, managed_var_free_, (mv))

struct config_suite_t {
 /** A list of configuration objects managed by a given configuration
  * manager. They are stored in the same order as the config_format_t
  * objects in the manager's list of subformats. */
 smartlist_t *configs;
};

/**
* Allocate a new empty config_suite_t.
**/
static config_suite_t *
config_suite_new(void)
{
 config_suite_t *suite = tor_malloc_zero(sizeof(config_suite_t));
 suite->configs = smartlist_new();
 return suite;
}

/** Release all storage held by a config_suite_t.  (Does not free
* any configuration objects it holds; the caller must do that first.) */
static void
config_suite_free_(config_suite_t *suite)
{
 if (!suite)
   return;
 smartlist_free(suite->configs);
 tor_free(suite);
}

#define config_suite_free(suite) \
 FREE_AND_NULL(config_suite_t, config_suite_free_, (suite))

struct config_mgr_t {
 /** The 'top-level' configuration format.  This one is used for legacy
  * options that have not yet been assigned to different sub-modules.
  *
  * (NOTE: for now, this is the only config_format_t that a config_mgr_t
  * contains.  A subsequent commit will add more. XXXX)
  */
 const config_format_t *toplevel;
 /**
  * List of second-level configuration format objects that this manager
  * also knows about.
  */
 smartlist_t *subconfigs;
 /** A smartlist of managed_var_t objects for all configuration formats. */
 smartlist_t *all_vars;
 /** A smartlist of config_abbrev_t objects for all configuration
  * formats. These objects are used to track synonyms and abbreviations for
  * different configuration options. */
 smartlist_t *all_abbrevs;
 /** A smartlist of config_deprecation_t for all configuration formats. */
 smartlist_t *all_deprecations;
 /** True if this manager has been frozen and cannot have any more formats
  * added to it. A manager must be frozen before it can be used to construct
  * or manipulate objects. */
 bool frozen;
 /** A replacement for the magic number of the toplevel object. We override
  * that number to make it unique for this particular config_mgr_t, so that
  * an object constructed with one mgr can't be used with another, even if
  * those managers' contents are equal.
  */
 struct_magic_decl_t toplevel_magic;
};

#define IDX_TOPLEVEL (-1)

/** Create a new config_mgr_t to manage a set of configuration objects to be
* wrapped under <b>toplevel_fmt</b>. */
config_mgr_t *
config_mgr_new(const config_format_t *toplevel_fmt)
{
 config_mgr_t *mgr = tor_malloc_zero(sizeof(config_mgr_t));
 mgr->subconfigs = smartlist_new();
 mgr->all_vars = smartlist_new();
 mgr->all_abbrevs = smartlist_new();
 mgr->all_deprecations = smartlist_new();

 config_mgr_register_fmt(mgr, toplevel_fmt, IDX_TOPLEVEL);
 mgr->toplevel = toplevel_fmt;

 return mgr;
}

/** Add a config_format_t to a manager, with a specified (unique) index. */
static void
config_mgr_register_fmt(config_mgr_t *mgr,
                       const config_format_t *fmt,
                       int object_idx)
{
 int i;

 tor_assertf(!mgr->frozen,
             "Tried to add a format to a configuration manager after "
             "it had been frozen.");

 if (object_idx != IDX_TOPLEVEL) {
   tor_assertf(! fmt->has_config_suite,
         "Tried to register a toplevel format in a non-toplevel position");
 }
 if (fmt->config_suite_offset) {
   tor_assertf(fmt->has_config_suite,
               "config_suite_offset was set, but has_config_suite was not.");
 }

 tor_assertf(fmt != mgr->toplevel &&
             ! smartlist_contains(mgr->subconfigs, fmt),
             "Tried to register an already-registered format.");

 /* register variables */
 for (i = 0; fmt->vars[i].member.name; ++i) {
   managed_var_t *mv = tor_malloc_zero(sizeof(managed_var_t));
   mv->cvar = &fmt->vars[i];
   mv->object_idx = object_idx;
   smartlist_add(mgr->all_vars, mv);
 }

 /* register abbrevs */
 if (fmt->abbrevs) {
   for (i = 0; fmt->abbrevs[i].abbreviated; ++i) {
     smartlist_add(mgr->all_abbrevs, (void*)&fmt->abbrevs[i]);
   }
 }

 /* register deprecations. */
 if (fmt->deprecations) {
   const config_deprecation_t *d;
   for (d = fmt->deprecations; d->name; ++d) {
     smartlist_add(mgr->all_deprecations, (void*)d);
   }
 }
}

/**
* Add a new format to this configuration object.  Asserts on failure.
*
* Returns an internal "index" value used to identify this format within
* all of those formats contained in <b>mgr</b>.  This index value
* should not generally be used outside of this module.
**/
int
config_mgr_add_format(config_mgr_t *mgr,
                     const config_format_t *fmt)
{
 tor_assert(mgr);
 int idx = smartlist_len(mgr->subconfigs);
 config_mgr_register_fmt(mgr, fmt, idx);
 smartlist_add(mgr->subconfigs, (void *)fmt);
 return idx;
}

/** Return a pointer to the config_suite_t * pointer inside a
* configuration object; returns NULL if there is no such member. */
static inline config_suite_t **
config_mgr_get_suite_ptr(const config_mgr_t *mgr, void *toplevel)
{
 if (! mgr->toplevel->has_config_suite)
   return NULL;
 return STRUCT_VAR_P(toplevel, mgr->toplevel->config_suite_offset);
}

/**
* Return a pointer to the configuration object within <b>toplevel</b> whose
* index is <b>idx</b>.
*
* NOTE: XXXX Eventually, there will be multiple objects supported within the
* toplevel object.  For example, the or_options_t will contain pointers
* to configuration objects for other modules.  This function gets
* the sub-object for a particular module.
*/
void *
config_mgr_get_obj_mutable(const config_mgr_t *mgr, void *toplevel, int idx)
{
 tor_assert(mgr);
 tor_assert(toplevel);
 if (idx == IDX_TOPLEVEL)
   return toplevel;

 tor_assertf(idx >= 0 && idx < smartlist_len(mgr->subconfigs),
             "Index %d is out of range.", idx);
 config_suite_t **suite = config_mgr_get_suite_ptr(mgr, toplevel);
 tor_assert(suite);
 tor_assert(smartlist_len(mgr->subconfigs) ==
            smartlist_len((*suite)->configs));

 return smartlist_get((*suite)->configs, idx);
}

/** As config_mgr_get_obj_mutable(), but return a const pointer. */
const void *
config_mgr_get_obj(const config_mgr_t *mgr, const void *toplevel, int idx)
{
 return config_mgr_get_obj_mutable(mgr, (void*)toplevel, idx);
}

/** Sorting helper for smartlist of managed_var_t */
static int
managed_var_cmp(const void **a, const void **b)
{
 const managed_var_t *mv1 = *(const managed_var_t**)a;
 const managed_var_t *mv2 = *(const managed_var_t**)b;

 return strcasecmp(mv1->cvar->member.name, mv2->cvar->member.name);
}

/**
* Mark a configuration manager as "frozen", so that no more formats can be
* added, and so that it can be used for manipulating configuration objects.
**/
void
config_mgr_freeze(config_mgr_t *mgr)
{
 static uint64_t mgr_count = 0;

 smartlist_sort(mgr->all_vars, managed_var_cmp);
 memcpy(&mgr->toplevel_magic, &mgr->toplevel->magic,
        sizeof(struct_magic_decl_t));
 uint64_t magic_input[3] = { mgr->toplevel_magic.magic_val,
                             (uint64_t) (uintptr_t) mgr,
                             ++mgr_count };
 mgr->toplevel_magic.magic_val =
   (uint32_t)siphash24g(magic_input, sizeof(magic_input));
 mgr->frozen = true;
}

/** Release all storage held in <b>mgr</b> */
void
config_mgr_free_(config_mgr_t *mgr)
{
 if (!mgr)
   return;
 SMARTLIST_FOREACH(mgr->all_vars, managed_var_t *, mv, managed_var_free(mv));
 smartlist_free(mgr->all_vars);
 smartlist_free(mgr->all_abbrevs);
 smartlist_free(mgr->all_deprecations);
 smartlist_free(mgr->subconfigs);
 memset(mgr, 0, sizeof(*mgr));
 tor_free(mgr);
}

/** Return a new smartlist_t containing a config_var_t for every variable that
* <b>mgr</b> knows about.  The elements of this smartlist do not need
* to be freed; they have the same lifespan as <b>mgr</b>. */
smartlist_t *
config_mgr_list_vars(const config_mgr_t *mgr)
{
 smartlist_t *result = smartlist_new();
 tor_assert(mgr);
 SMARTLIST_FOREACH(mgr->all_vars, managed_var_t *, mv,
                   smartlist_add(result, (void*) mv->cvar));
 return result;
}

/** Return a new smartlist_t containing the names of all deprecated variables.
* The elements of this smartlist do not need to be freed; they have the same
* lifespan as <b>mgr</b>.
*/
smartlist_t *
config_mgr_list_deprecated_vars(const config_mgr_t *mgr)
{
 smartlist_t *result = smartlist_new();
 tor_assert(mgr);
 SMARTLIST_FOREACH(mgr->all_deprecations, config_deprecation_t *, d,
                   smartlist_add(result, (char*)d->name));
 return result;
}

/**
* Check the magic number on <b>object</b> to make sure it's a valid toplevel
* object, created with <b>mgr</b>.  Exit with an assertion if it isn't.
**/
void
config_check_toplevel_magic(const config_mgr_t *mgr,
                           const void *object)
{
 struct_check_magic(object, &mgr->toplevel_magic);
}

/** Assert that the magic fields in <b>options</b> and its subsidiary
* objects are all okay. */
static void
config_mgr_assert_magic_ok(const config_mgr_t *mgr,
                          const void *options)
{
 tor_assert(mgr);
 tor_assert(options);
 tor_assert(mgr->frozen);
 struct_check_magic(options, &mgr->toplevel_magic);

 config_suite_t **suitep = config_mgr_get_suite_ptr(mgr, (void*)options);
 if (suitep == NULL) {
   tor_assert(smartlist_len(mgr->subconfigs) == 0);
   return;
 }

 tor_assert(smartlist_len((*suitep)->configs) ==
            smartlist_len(mgr->subconfigs));
 SMARTLIST_FOREACH_BEGIN(mgr->subconfigs, const config_format_t *, fmt) {
   void *obj = smartlist_get((*suitep)->configs, fmt_sl_idx);
   tor_assert(obj);
   struct_check_magic(obj, &fmt->magic);
 } SMARTLIST_FOREACH_END(fmt);
}

/** Macro: assert that <b>cfg</b> has the right magic field for
* <b>mgr</b>. */
#define CONFIG_CHECK(mgr, cfg) STMT_BEGIN                               \
   config_mgr_assert_magic_ok((mgr), (cfg));                           \
 STMT_END

/** Allocate an empty configuration object of a given format type. */
void *
config_new(const config_mgr_t *mgr)
{
 tor_assert(mgr->frozen);
 void *opts = tor_malloc_zero(mgr->toplevel->size);
 struct_set_magic(opts, &mgr->toplevel_magic);
 config_suite_t **suitep = config_mgr_get_suite_ptr(mgr, opts);
 if (suitep) {
   *suitep = config_suite_new();
   SMARTLIST_FOREACH_BEGIN(mgr->subconfigs, const config_format_t *, fmt) {
     void *obj = tor_malloc_zero(fmt->size);
     struct_set_magic(obj, &fmt->magic);
     smartlist_add((*suitep)->configs, obj);
   } SMARTLIST_FOREACH_END(fmt);
 }
 CONFIG_CHECK(mgr, opts);
 return opts;
}

/*
* Functions to parse config options
*/

/** If <b>option</b> is an official abbreviation for a longer option,
* return the longer option.  Otherwise return <b>option</b>.
* If <b>command_line</b> is set, apply all abbreviations.  Otherwise, only
* apply abbreviations that work for the config file and the command line.
* If <b>warn_obsolete</b> is set, warn about deprecated names. */
const char *
config_expand_abbrev(const config_mgr_t *mgr, const char *option,
                    int command_line, int warn_obsolete)
{
 SMARTLIST_FOREACH_BEGIN(mgr->all_abbrevs, const config_abbrev_t *, abbrev) {
   /* Abbreviations are case insensitive. */
   if (!strcasecmp(option, abbrev->abbreviated) &&
       (command_line || !abbrev->commandline_only)) {
     if (warn_obsolete && abbrev->warn) {
       log_warn(LD_CONFIG,
                "The configuration option '%s' is deprecated; "
                "use '%s' instead.",
                abbrev->abbreviated,
                abbrev->full);
     }
     /* Keep going through the list in case we want to rewrite it more.
      * (We could imagine recursing here, but I don't want to get the
      * user into an infinite loop if we craft our list wrong.) */
     option = abbrev->full;
   }
 } SMARTLIST_FOREACH_END(abbrev);
 return option;
}

/** If <b>key</b> is a deprecated configuration option, return the message
* explaining why it is deprecated (which may be an empty string). Return NULL
* if it is not deprecated. The <b>key</b> field must be fully expanded. */
const char *
config_find_deprecation(const config_mgr_t *mgr, const char *key)
{
 if (BUG(mgr == NULL) || BUG(key == NULL))
   return NULL; // LCOV_EXCL_LINE

 SMARTLIST_FOREACH_BEGIN(mgr->all_deprecations, const config_deprecation_t *,
                         d) {
   if (!strcasecmp(d->name, key)) {
     return d->why_deprecated ? d->why_deprecated : "";
   }
 } SMARTLIST_FOREACH_END(d);
 return NULL;
}

/**
* Find the managed_var_t object for a variable whose name is <b>name</b>
* according to <b>mgr</b>.   Return that object, or NULL if none exists.
*
* If <b>allow_truncated</b> is true, then accept any variable whose
* name begins with <b>name</b>.
*
* If <b>idx_out</b> is not NULL, set *<b>idx_out</b> to the position of
* that variable within mgr-&gt;all_vars, or to -1 if the variable is
* not found.
*/
static const managed_var_t *
config_mgr_find_var(const config_mgr_t *mgr,
                   const char *key,
                   bool allow_truncated, int *idx_out)
{
 const size_t keylen = strlen(key);
 if (idx_out)
   *idx_out = -1;

 if (!keylen)
   return NULL; /* if they say "--" on the command line, it's not an option */

 /* First, check for an exact (case-insensitive) match */
 SMARTLIST_FOREACH_BEGIN(mgr->all_vars, const managed_var_t *, mv) {
   if (!strcasecmp(mv->cvar->member.name, key)) {
     if (idx_out)
       *idx_out = mv_sl_idx;
     return mv;
   }
 } SMARTLIST_FOREACH_END(mv);

 if (!allow_truncated)
   return NULL;

 /* If none, check for an abbreviated match */
 SMARTLIST_FOREACH_BEGIN(mgr->all_vars, const managed_var_t *, mv) {
   if (!strncasecmp(key, mv->cvar->member.name, keylen)) {
     log_warn(LD_CONFIG, "The abbreviation '%s' is deprecated. "
              "Please use '%s' instead",
              key, mv->cvar->member.name);
     if (idx_out)
       *idx_out = mv_sl_idx;
     return mv;
   }
 } SMARTLIST_FOREACH_END(mv);

 /* Okay, unrecognized option */
 return NULL;
}

/**
* If <b>key</b> is a name or an abbreviation configuration option, return
* the corresponding canonical name for it.  Warn if the abbreviation is
* non-standard.  Return NULL if the option does not exist.
*/
const char *
config_find_option_name(const config_mgr_t *mgr, const char *key)
{
 key = config_expand_abbrev(mgr, key, 0, 0);
 const managed_var_t *mv = config_mgr_find_var(mgr, key, true, NULL);
 if (mv)
   return mv->cvar->member.name;
 else
   return NULL;
}

/** Return the number of option entries in <b>fmt</b>. */
static int
config_count_options(const config_mgr_t *mgr)
{
 return smartlist_len(mgr->all_vars);
}

/**
* Return true iff at least one bit from <b>flag</b> is set on <b>var</b>,
* either in <b>var</b>'s flags, or on the flags of its type.
**/
static bool
config_var_has_flag(const config_var_t *var, uint32_t flag)
{
 uint32_t have_flags = var->flags | struct_var_get_flags(&var->member);

 return (have_flags & flag) != 0;
}

/**
* Return true if assigning a value to <b>var</b> replaces the previous
* value.  Return false if assigning a value to <b>var</b> appends
* to the previous value.
**/
static bool
config_var_is_replaced_on_set(const config_var_t *var)
{
 return ! config_var_has_flag(var, CFLG_NOREPLACE);
}

/**
* Return true iff <b>var</b> may be assigned by name (e.g., via the
* CLI, the configuration files, or the controller API).
**/
bool
config_var_is_settable(const config_var_t *var)
{
 return ! config_var_has_flag(var, CFLG_NOSET);
}

/**
* Return true iff the controller is allowed to fetch the value of
* <b>var</b>.
**/
static bool
config_var_is_gettable(const config_var_t *var)
{
 /* Arguably, invisible or obsolete options should not be gettable.  However,
  * they have been gettable for a long time, and making them ungettable could
  * have compatibility effects.  For now, let's leave them alone.
  */

 // return ! config_var_has_flag(var, CVFLAG_OBSOLETE|CFGLAGS_INVISIBLE);
 (void)var;
 return true;
}

/**
* Return true iff we need to check <b>var</b> for changes when we are
* comparing config options for changes.
*
* A false result might mean that the variable is a derived variable, and that
* comparing the variable it derives from compares this one too-- or it might
* mean that there is no data to compare.
**/
static bool
config_var_should_list_changes(const config_var_t *var)
{
 return ! config_var_has_flag(var, CFLG_NOCMP);
}

/**
* Return true iff we need to copy the data for <b>var</b> when we are
* copying a config option.
*
* A false option might mean that the variable is a derived variable, and that
* copying the variable it derives from copies it-- or it might mean that
* there is no data to copy.
**/
static bool
config_var_needs_copy(const config_var_t *var)
{
 return ! config_var_has_flag(var, CFLG_NOCOPY);
}

/**
* Return true iff variable <b>var</b> should appear on list of variable
* names given to the controller or the CLI.
*
* (Note that this option is imperfectly obeyed. The
* --list-torrc-options command looks at the "settable" flag, whereas
* "GETINFO config/defaults" and "list_deprecated_*()" do not filter
* their results. It would be good for consistency to try to converge
* these behaviors in the future.)
**/
bool
config_var_is_listable(const config_var_t *var)
{
 return ! config_var_has_flag(var, CFLG_NOLIST);
}

/**
* Return true iff variable <b>var</b> should be written out when we
* are writing our configuration to disk, to a controller, or via the
* --dump-config command.
*
* This option may be set because a variable is hidden, or because it is
* derived from another variable which will already be written out.
**/
static bool
config_var_is_dumpable(const config_var_t *var)
{
 return ! config_var_has_flag(var, CFLG_NODUMP);
}

/*
* Functions to assign config options.
*/

/** <b>c</b>-\>key is known to be a real key. Update <b>options</b>
* with <b>c</b>-\>value and return 0, or return -1 if bad value.
*
* Called from config_assign_line() and option_reset().
*/
static int
config_assign_value(const config_mgr_t *mgr, void *options,
                   config_line_t *c, char **msg)
{
 const managed_var_t *var;

 CONFIG_CHECK(mgr, options);

 var = config_mgr_find_var(mgr, c->key, true, NULL);
 tor_assert(var);
 tor_assert(!strcmp(c->key, var->cvar->member.name));
 void *object = config_mgr_get_obj_mutable(mgr, options, var->object_idx);

 if (config_var_has_flag(var->cvar, CFLG_WARN_OBSOLETE)) {
   log_warn(LD_GENERAL, "Skipping obsolete configuration option \"%s\".",
            var->cvar->member.name);
 } else if (config_var_has_flag(var->cvar, CFLG_WARN_DISABLED)) {
   log_warn(LD_GENERAL, "This copy of Tor was built without support for "
            "the option \"%s\". Skipping.", var->cvar->member.name);
 }

 return struct_var_kvassign(object, c, msg, &var->cvar->member);
}

/** Mark every linelist in <b>options</b> "fragile", so that fresh assignments
* to it will replace old ones. */
static void
config_mark_lists_fragile(const config_mgr_t *mgr, void *options)
{
 tor_assert(mgr);
 tor_assert(options);

 SMARTLIST_FOREACH_BEGIN(mgr->all_vars, const managed_var_t *, mv) {
   void *object = config_mgr_get_obj_mutable(mgr, options, mv->object_idx);
   struct_var_mark_fragile(object, &mv->cvar->member);
 } SMARTLIST_FOREACH_END(mv);
}

/**
* Log a warning that declaring that the option called <b>what</b>
* is deprecated because of the reason in <b>why</b>.
*
* (Both arguments must be non-NULL.)
**/
void
warn_deprecated_option(const char *what, const char *why)
{
 const char *space = (why && strlen(why)) ? " " : "";
 log_warn(LD_CONFIG, "The %s option is deprecated, and will most likely "
          "be removed in a future version of Tor.%s%s (If you think this is "
          "a mistake, please let us know!)",
          what, space, why);
}

/** If <b>c</b> is a syntactically valid configuration line, update
* <b>options</b> with its value and return 0.  Otherwise return -1 for bad
* key, -2 for bad value.
*
* If <b>clear_first</b> is set, clear the value first. Then if
* <b>use_defaults</b> is set, set the value to the default.
*
* Called from config_assign().
*/
static int
config_assign_line(const config_mgr_t *mgr, void *options,
                  config_line_t *c, unsigned flags,
                  bitarray_t *options_seen, char **msg)
{
 const unsigned use_defaults = flags & CAL_USE_DEFAULTS;
 const unsigned clear_first = flags & CAL_CLEAR_FIRST;
 const unsigned warn_deprecations = flags & CAL_WARN_DEPRECATIONS;
 const managed_var_t *mvar;

 CONFIG_CHECK(mgr, options);

 int var_index = -1;
 mvar = config_mgr_find_var(mgr, c->key, true, &var_index);
 if (!mvar) {
   const config_format_t *fmt = mgr->toplevel;
   if (fmt->extra) {
     void *lvalue = STRUCT_VAR_P(options, fmt->extra->offset);
     log_info(LD_CONFIG,
              "Found unrecognized option '%s'; saving it.", c->key);
     config_line_append((config_line_t**)lvalue, c->key, c->value);
     return 0;
   } else {
     tor_asprintf(msg,
               "Unknown option '%s'.  Failing.", c->key);
     return -1;
   }
 }

 const config_var_t *cvar = mvar->cvar;
 tor_assert(cvar);

 /* Put keyword into canonical case. */
 if (strcmp(cvar->member.name, c->key)) {
   tor_free(c->key);
   c->key = tor_strdup(cvar->member.name);
 }

 const char *deprecation_msg;
 if (warn_deprecations &&
     (deprecation_msg = config_find_deprecation(mgr, cvar->member.name))) {
   warn_deprecated_option(cvar->member.name, deprecation_msg);
 }

 if (!strlen(c->value)) {
   /* reset or clear it, then return */
   if (!clear_first) {
     if (! config_var_is_replaced_on_set(cvar) &&
         c->command != CONFIG_LINE_CLEAR) {
       /* We got an empty linelist from the torrc or command line.
          As a special case, call this an error. Warn and ignore. */
       log_warn(LD_CONFIG,
                "Linelist option '%s' has no value. Skipping.", c->key);
     } else { /* not already cleared */
       config_reset(mgr, options, mvar, use_defaults);
     }
   }
   return 0;
 } else if (c->command == CONFIG_LINE_CLEAR && !clear_first) {
   // This block is unreachable, since a CLEAR line always has an
   // empty value, and so will trigger be handled by the previous
   // "if (!strlen(c->value))" block.

   // LCOV_EXCL_START
   tor_assert_nonfatal_unreached();
   config_reset(mgr, options, mvar, use_defaults);
   // LCOV_EXCL_STOP
 }

 if (options_seen && config_var_is_replaced_on_set(cvar)) {
   /* We're tracking which options we've seen, and this option is not
    * supposed to occur more than once. */
   tor_assert(var_index >= 0);
   if (bitarray_is_set(options_seen, var_index)) {
     log_warn(LD_CONFIG, "Option '%s' used more than once; all but the last "
              "value will be ignored.", cvar->member.name);
   }
   bitarray_set(options_seen, var_index);
 }

 if (config_assign_value(mgr, options, c, msg) < 0)
   return -2;
 return 0;
}

/** Restore the option named <b>key</b> in options to its default value.
* Called from config_assign(). */
STATIC void
config_reset_line(const config_mgr_t *mgr, void *options,
                 const char *key, int use_defaults)
{
 const managed_var_t *var;

 CONFIG_CHECK(mgr, options);

 var = config_mgr_find_var(mgr, key, true, NULL);
 if (!var)
   return; /* give error on next pass. */

 config_reset(mgr, options, var, use_defaults);
}

/** Return true iff value needs to be quoted and escaped to be used in
* a configuration file. */
static int
config_value_needs_escape(const char *value)
{
 if (*value == '\"')
   return 1;
 while (*value) {
   switch (*value)
   {
   case '\r':
   case '\n':
   case '#':
     /* Note: quotes and backspaces need special handling when we are using
      * quotes, not otherwise, so they don't trigger escaping on their
      * own. */
     return 1;
   default:
     if (!TOR_ISPRINT(*value))
       return 1;
   }
   ++value;
 }
 return 0;
}

/** Return newly allocated line or lines corresponding to <b>key</b> in the
* configuration <b>options</b>.  If <b>escape_val</b> is true and a
* value needs to be quoted before it's put in a config file, quote and
* escape that value. Return NULL if no such key exists. */
config_line_t *
config_get_assigned_option(const config_mgr_t *mgr, const void *options,
                          const char *key, int escape_val)
{
 const managed_var_t *var;
 config_line_t *result;

 tor_assert(options && key);

 CONFIG_CHECK(mgr, options);

 var = config_mgr_find_var(mgr, key, true, NULL);
 if (!var) {
   log_warn(LD_CONFIG, "Unknown option '%s'.  Failing.", key);
   return NULL;
 }
 if (! config_var_is_gettable(var->cvar)) {
   log_warn(LD_CONFIG, "Option '%s' is obsolete or unfetchable. Failing.",
            key);
   return NULL;
 }
 const void *object = config_mgr_get_obj(mgr, options, var->object_idx);

 result = struct_var_kvencode(object, &var->cvar->member);

 if (escape_val) {
   config_line_t *line;
   for (line = result; line; line = line->next) {
     if (line->value && config_value_needs_escape(line->value)) {
       char *newval = esc_for_log(line->value);
       tor_free(line->value);
       line->value = newval;
     }
   }
 }

 return result;
}
/** Iterate through the linked list of requested options <b>list</b>.
* For each item, convert as appropriate and assign to <b>options</b>.
* If an item is unrecognized, set *msg and return -1 immediately,
* else return 0 for success.
*
* If <b>clear_first</b>, interpret config options as replacing (not
* extending) their previous values. If <b>clear_first</b> is set,
* then <b>use_defaults</b> to decide if you set to defaults after
* clearing, or make the value 0 or NULL.
*
* Here are the use cases:
* 1. A non-empty AllowInvalid line in your torrc. Appends to current
*    if linelist, replaces current if csv.
* 2. An empty AllowInvalid line in your torrc. Should clear it.
* 3. "RESETCONF AllowInvalid" sets it to default.
* 4. "SETCONF AllowInvalid" makes it NULL.
* 5. "SETCONF AllowInvalid=foo" clears it and sets it to "foo".
*
* Use_defaults   Clear_first
*    0                0       "append"
*    1                0       undefined, don't use
*    0                1       "set to null first"
*    1                1       "set to defaults first"
* Return 0 on success, -1 on bad key, -2 on bad value.
*
* As an additional special case, if a LINELIST config option has
* no value and clear_first is 0, then warn and ignore it.
*/

/*
There are three call cases for config_assign() currently.

Case one: Torrc entry
options_init_from_torrc() calls config_assign(0, 0)
 calls config_assign_line(0, 0).
   if value is empty, calls config_reset(0) and returns.
   calls config_assign_value(), appends.

Case two: setconf
options_trial_assign() calls config_assign(0, 1)
 calls config_reset_line(0)
   calls config_reset(0)
     calls option_clear().
 calls config_assign_line(0, 1).
   if value is empty, returns.
   calls config_assign_value(), appends.

Case three: resetconf
options_trial_assign() calls config_assign(1, 1)
 calls config_reset_line(1)
   calls config_reset(1)
     calls option_clear().
     calls config_assign_value(default)
 calls config_assign_line(1, 1).
   returns.
*/
int
config_assign(const config_mgr_t *mgr, void *options, config_line_t *list,
             unsigned config_assign_flags, char **msg)
{
 config_line_t *p;
 bitarray_t *options_seen;
 const int n_options = config_count_options(mgr);
 const unsigned clear_first = config_assign_flags & CAL_CLEAR_FIRST;
 const unsigned use_defaults = config_assign_flags & CAL_USE_DEFAULTS;

 CONFIG_CHECK(mgr, options);

 /* pass 1: normalize keys */
 for (p = list; p; p = p->next) {
   const char *full = config_expand_abbrev(mgr, p->key, 0, 1);
   if (strcmp(full,p->key)) {
     tor_free(p->key);
     p->key = tor_strdup(full);
   }
 }

 /* pass 2: if we're reading from a resetting source, clear all
  * mentioned config options, and maybe set to their defaults. */
 if (clear_first) {
   for (p = list; p; p = p->next)
     config_reset_line(mgr, options, p->key, use_defaults);
 }

 options_seen = bitarray_init_zero(n_options);
 /* pass 3: assign. */
 while (list) {
   int r;
   if ((r=config_assign_line(mgr, options, list, config_assign_flags,
                             options_seen, msg))) {
     bitarray_free(options_seen);
     return r;
   }
   list = list->next;
 }
 bitarray_free(options_seen);

 /** Now we're done assigning a group of options to the configuration.
  * Subsequent group assignments should _replace_ linelists, not extend
  * them. */
 config_mark_lists_fragile(mgr, options);

 return 0;
}

/** Reset config option <b>var</b> to 0, 0.0, NULL, or the equivalent.
* Called from config_reset() and config_free(). */
static void
config_clear(const config_mgr_t *mgr, void *options, const managed_var_t *var)
{
 void *object = config_mgr_get_obj_mutable(mgr, options, var->object_idx);
 struct_var_free(object, &var->cvar->member);
}

/** Clear the option indexed by <b>var</b> in <b>options</b>. Then if
* <b>use_defaults</b>, set it to its default value.
* Called by config_init() and option_reset_line() and option_assign_line(). */
static void
config_reset(const config_mgr_t *mgr, void *options,
            const managed_var_t *var, int use_defaults)
{
 config_line_t *c;
 char *msg = NULL;
 CONFIG_CHECK(mgr, options);
 config_clear(mgr, options, var); /* clear it first */

 if (!use_defaults)
   return; /* all done */

 if (var->cvar->initvalue) {
   c = tor_malloc_zero(sizeof(config_line_t));
   c->key = tor_strdup(var->cvar->member.name);
   c->value = tor_strdup(var->cvar->initvalue);
   if (config_assign_value(mgr, options, c, &msg) < 0) {
     // LCOV_EXCL_START
     log_warn(LD_BUG, "Failed to assign default: %s", msg);
     tor_free(msg); /* if this happens it's a bug */
     // LCOV_EXCL_STOP
   }
   config_free_lines(c);
 }
}

/** Release storage held by <b>options</b>. */
void
config_free_(const config_mgr_t *mgr, void *options)
{
 if (!options)
   return;

 tor_assert(mgr);

 if (mgr->toplevel->clear_fn) {
   mgr->toplevel->clear_fn(mgr, options);
 }
 config_suite_t **suitep = config_mgr_get_suite_ptr(mgr, options);
 if (suitep) {
   tor_assert(smartlist_len((*suitep)->configs) ==
              smartlist_len(mgr->subconfigs));
   SMARTLIST_FOREACH_BEGIN(mgr->subconfigs, const config_format_t *, fmt) {
     void *obj = smartlist_get((*suitep)->configs, fmt_sl_idx);
     if (fmt->clear_fn) {
       fmt->clear_fn(mgr, obj);
     }
   } SMARTLIST_FOREACH_END(fmt);
 }

 SMARTLIST_FOREACH_BEGIN(mgr->all_vars, const managed_var_t *, mv) {
   config_clear(mgr, options, mv);
 } SMARTLIST_FOREACH_END(mv);

 if (mgr->toplevel->extra) {
   config_line_t **linep = STRUCT_VAR_P(options,
                                        mgr->toplevel->extra->offset);
   config_free_lines(*linep);
   *linep = NULL;
 }

 if (suitep) {
   SMARTLIST_FOREACH((*suitep)->configs, void *, obj, tor_free(obj));
   config_suite_free(*suitep);
 }

 tor_free(options);
}

/** Return true iff the option <b>name</b> has the same value in <b>o1</b>
* and <b>o2</b>.  Must not be called for LINELIST_S or OBSOLETE options.
*/
int
config_is_same(const config_mgr_t *mgr,
              const void *o1, const void *o2,
              const char *name)
{
 CONFIG_CHECK(mgr, o1);
 CONFIG_CHECK(mgr, o2);

 const managed_var_t *var = config_mgr_find_var(mgr, name, true, NULL);
 if (!var) {
   return true;
 }
 const void *obj1 = config_mgr_get_obj(mgr, o1, var->object_idx);
 const void *obj2 = config_mgr_get_obj(mgr, o2, var->object_idx);

 return struct_var_eq(obj1, obj2, &var->cvar->member);
}

/**
* Return a list of the options which have changed between <b>options1</b> and
* <b>options2</b>. If an option has reverted to its default value, it has a
* value entry of NULL.
*
* <b>options1</b> and <b>options2</b> must be top-level configuration objects
* of the type managed by <b>mgr</b>.
**/
config_line_t *
config_get_changes(const config_mgr_t *mgr,
                  const void *options1, const void *options2)
{
 config_line_t *result = NULL;
 config_line_t **next = &result;
 SMARTLIST_FOREACH_BEGIN(mgr->all_vars, managed_var_t *, mv) {
   if (! config_var_should_list_changes(mv->cvar)) {
     /* something else will check this var, or it doesn't need checking */
     continue;
   }
   const void *obj1 = config_mgr_get_obj(mgr, options1, mv->object_idx);
   const void *obj2 = config_mgr_get_obj(mgr, options2, mv->object_idx);

   if (struct_var_eq(obj1, obj2, &mv->cvar->member)) {
     continue;
   }

   const char *varname = mv->cvar->member.name;
   config_line_t *line =
     config_get_assigned_option(mgr, options2, varname, 1);

   if (line) {
     *next = line;
   } else {
     *next = tor_malloc_zero(sizeof(config_line_t));
     (*next)->key = tor_strdup(varname);
   }
   while (*next)
     next = &(*next)->next;
 } SMARTLIST_FOREACH_END(mv);

 return result;
}

/** Copy storage held by <b>old</b> into a new or_options_t and return it. */
void *
config_dup(const config_mgr_t *mgr, const void *old)
{
 void *newopts;

 newopts = config_new(mgr);
 SMARTLIST_FOREACH_BEGIN(mgr->all_vars, managed_var_t *, mv) {
   if (! config_var_needs_copy(mv->cvar)) {
     // Something else will copy this option, or it doesn't need copying.
     continue;
   }
   const void *oldobj = config_mgr_get_obj(mgr, old, mv->object_idx);
   void *newobj = config_mgr_get_obj_mutable(mgr, newopts, mv->object_idx);
   if (struct_var_copy(newobj, oldobj, &mv->cvar->member) < 0) {
     // LCOV_EXCL_START
     log_err(LD_BUG, "Unable to copy value for %s.",
             mv->cvar->member.name);
     tor_assert_unreached();
     // LCOV_EXCL_STOP
   }
 } SMARTLIST_FOREACH_END(mv);

 return newopts;
}
/** Set all vars in the configuration object <b>options</b> to their default
* values. */
void
config_init(const config_mgr_t *mgr, void *options)
{
 CONFIG_CHECK(mgr, options);

 SMARTLIST_FOREACH_BEGIN(mgr->all_vars, const managed_var_t *, mv) {
   if (!mv->cvar->initvalue)
     continue; /* defaults to NULL or 0 */
   config_reset(mgr, options, mv, 1);
 } SMARTLIST_FOREACH_END(mv);
}

/**
* Helper for config_validate_single: see whether any immutable option
* has changed between old_options and new_options.
*
* On success return 0; on failure set *msg_out to a newly allocated
* string explaining what is wrong, and return -1.
*/
static int
config_check_immutable_flags(const config_format_t *fmt,
                            const void *old_options,
                            const void *new_options,
                            char **msg_out)
{
 tor_assert(fmt);
 tor_assert(new_options);
 if (BUG(! old_options))
   return 0;

 unsigned i;
 for (i = 0; fmt->vars[i].member.name; ++i) {
   const config_var_t *v = &fmt->vars[i];
   if (! config_var_has_flag(v, CFLG_IMMUTABLE))
     continue;

   if (! struct_var_eq(old_options, new_options, &v->member)) {
     tor_asprintf(msg_out,
                  "While Tor is running, changing %s is not allowed",
                  v->member.name);
     return -1;
   }
 }

 return 0;
}

/**
* Normalize and validate a single object `options` within a configuration
* suite, according to its format.  `options` may be modified as appropriate
* in order to set ancillary data.  If `old_options` is provided, make sure
* that the transition from `old_options` to `options` is permitted.
*
* On success return VSTAT_OK; on failure set *msg_out to a newly allocated
* string explaining what is wrong, and return a different validation_status_t
* to describe which step failed.
**/
static validation_status_t
config_validate_single(const config_format_t *fmt,
                      const void *old_options, void *options,
                      char **msg_out)
{
 tor_assert(fmt);
 tor_assert(options);

 if (fmt->pre_normalize_fn) {
   if (fmt->pre_normalize_fn(options, msg_out) < 0) {
     return VSTAT_PRE_NORMALIZE_ERR;
   }
 }

 if (fmt->legacy_validate_fn) {
   if (fmt->legacy_validate_fn(old_options, options, msg_out) < 0) {
     return VSTAT_LEGACY_ERR;
   }
 }

 if (fmt->validate_fn) {
   if (fmt->validate_fn(options, msg_out) < 0) {
     return VSTAT_VALIDATE_ERR;
   }
 }

 if (old_options) {
   if (config_check_immutable_flags(fmt, old_options, options, msg_out) < 0) {
     return VSTAT_TRANSITION_ERR;
   }

   if (fmt->check_transition_fn) {
     if (fmt->check_transition_fn(old_options, options, msg_out) < 0) {
       return VSTAT_TRANSITION_ERR;
     }
   }
 }

 if (fmt->post_normalize_fn) {
   if (fmt->post_normalize_fn(options, msg_out) < 0) {
     return VSTAT_POST_NORMALIZE_ERR;
   }
 }

 return VSTAT_OK;
}

/**
* Normalize and validate all the options in configuration object `options`
* and its sub-objects. `options` may be modified as appropriate in order to
* set ancillary data.  If `old_options` is provided, make sure that the
* transition from `old_options` to `options` is permitted.
*
* On success return VSTAT_OK; on failure set *msg_out to a newly allocated
* string explaining what is wrong, and return a different validation_status_t
* to describe which step failed.
**/
validation_status_t
config_validate(const config_mgr_t *mgr,
               const void *old_options, void *options,
               char **msg_out)
{
 validation_status_t rv;
 CONFIG_CHECK(mgr, options);
 if (old_options) {
   CONFIG_CHECK(mgr, old_options);
 }

 config_suite_t **suitep_new = config_mgr_get_suite_ptr(mgr, options);
 config_suite_t **suitep_old = NULL;
 if (old_options)
   suitep_old = config_mgr_get_suite_ptr(mgr, (void*) old_options);

 /* Validate the sub-objects */
 if (suitep_new) {
   SMARTLIST_FOREACH_BEGIN(mgr->subconfigs, const config_format_t *, fmt) {
     void *obj = smartlist_get((*suitep_new)->configs, fmt_sl_idx);
     const void *obj_old=NULL;
     if (suitep_old)
       obj_old = smartlist_get((*suitep_old)->configs, fmt_sl_idx);

     rv = config_validate_single(fmt, obj_old, obj, msg_out);
     if (rv < 0)
       return rv;
   } SMARTLIST_FOREACH_END(fmt);
 }

 /* Validate the top-level object. */
 rv = config_validate_single(mgr->toplevel, old_options, options, msg_out);
 if (rv < 0)
   return rv;

 return VSTAT_OK;
}

/** Allocate and return a new string holding the written-out values of the vars
* in 'options'.  If 'minimal', do not write out any default-valued vars.
* Else, if comment_defaults, write default values as comments.
*/
char *
config_dump(const config_mgr_t *mgr, const void *default_options,
           const void *options, int minimal,
           int comment_defaults)
{
 const config_format_t *fmt = mgr->toplevel;
 smartlist_t *elements;
 const void *defaults = default_options;
 void *defaults_tmp = NULL;
 config_line_t *line, *assigned;
 char *result;
 char *msg = NULL;

 if (defaults == NULL) {
   defaults = defaults_tmp = config_new(mgr);
   config_init(mgr, defaults_tmp);
 }

 /* XXX use a 1 here so we don't add a new log line while dumping */
 if (default_options == NULL) {
   if (config_validate(mgr, NULL, defaults_tmp, &msg) < 0) {
     // LCOV_EXCL_START
     log_err(LD_BUG, "Failed to validate default config: %s", msg);
     tor_free(msg);
     tor_assert(0);
     // LCOV_EXCL_STOP
   }
 }

 elements = smartlist_new();
 SMARTLIST_FOREACH_BEGIN(mgr->all_vars, managed_var_t *, mv) {
   int comment_option = 0;
   /* Don't save 'hidden' control variables. */
   if (! config_var_is_dumpable(mv->cvar))
     continue;
   const char *name = mv->cvar->member.name;
   if (minimal && config_is_same(mgr, options, defaults, name))
     continue;
   else if (comment_defaults &&
            config_is_same(mgr, options, defaults, name))
     comment_option = 1;

   line = assigned =
     config_get_assigned_option(mgr, options, name, 1);

   for (; line; line = line->next) {
     if (!strcmpstart(line->key, "__")) {
       /* This check detects "hidden" variables inside LINELIST_V structures.
        */
       continue;
     }
     int value_exists = line->value && *(line->value);
     smartlist_add_asprintf(elements, "%s%s%s%s\n",
                  comment_option ? "# " : "",
                  line->key, value_exists ? " " : "", line->value);
   }
   config_free_lines(assigned);
 } SMARTLIST_FOREACH_END(mv);

 if (fmt->extra) {
   line = *(config_line_t**)STRUCT_VAR_P(options, fmt->extra->offset);
   for (; line; line = line->next) {
     int value_exists = line->value && *(line->value);
     smartlist_add_asprintf(elements, "%s%s%s\n",
                            line->key, value_exists ? " " : "", line->value);
   }
 }

 result = smartlist_join_strings(elements, "", 0, NULL);
 SMARTLIST_FOREACH(elements, char *, cp, tor_free(cp));
 smartlist_free(elements);
 config_free(mgr, defaults_tmp);
 return result;
}

/**
* Return true if every member of <b>options</b> is in-range and well-formed.
* Return false otherwise.  Log errors at level <b>severity</b>.
*/
bool
config_check_ok(const config_mgr_t *mgr, const void *options, int severity)
{
 bool all_ok = true;

 SMARTLIST_FOREACH_BEGIN(mgr->all_vars, const managed_var_t *, mv) {
   if (!struct_var_ok(options, &mv->cvar->member)) {
     log_fn(severity, LD_BUG, "Invalid value for %s",
            mv->cvar->member.name);
     all_ok = false;
   }
 } SMARTLIST_FOREACH_END(mv);

 return all_ok;
}