nihilist/tor
1
0
Fork 0
mirror of https://gitlab.torproject.org/tpo/core/tor.git synced 2024-11-10 13:13:44 +01:00
Code Issues Packages Projects Releases Wiki Activity

Finish the transition from the word 'verified' to the words

Browse Source 
'named' and 'valid'.


svn:r6188
This commit is contained in:
Roger Dingledine 2006-03-19 01:21:59 +00:00
parent 7e2aa67fcb
commit c06e6ddadd
9 changed files with 89 additions and 88 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
src/or/circuitbuild.c
View File

@ -1164,14 +1164,14 @@ choose_good_exit_server_general(routerlist_t *dir, int need_uptime,
n_supported[i] = -1;
continue; /* skip routers that are not suitable */
}
if (!router->is_verified &&
(!(options->_AllowUnverified & ALLOW_UNVERIFIED_EXIT) ||
if (!router->is_valid &&
(!(options->_AllowInvalid & ALLOW_INVALID_EXIT) ||
router_is_unreliable(router, 1, 1, 0))) {
/* if it's unverified, and either we don't want it or it's unsuitable */
/* if it's invalid, and either we don't want it or it's unsuitable */
n_supported[i] = -1;
// log_fn(LOG_DEBUG,"Skipping node %s (index %d) -- unverified router.",
// log_fn(LOG_DEBUG,"Skipping node %s (index %d) -- invalid router.",
// router->nickname, i);
continue; /* skip unverified routers */
continue; /* skip invalid routers */
}
if (router_exit_policy_rejects_all(router)) {
n_supported[i] = -1;
@ -1309,14 +1309,14 @@ choose_good_exit_server(uint8_t purpose, routerlist_t *dir,
if (is_internal) /* pick it like a middle hop */
return router_choose_random_node(NULL, get_options()->ExcludeNodes,
NULL, need_uptime, need_capacity, 0,
get_options()->_AllowUnverified & ALLOW_UNVERIFIED_MIDDLE, 0);
get_options()->_AllowInvalid & ALLOW_INVALID_MIDDLE, 0);
else
return choose_good_exit_server_general(dir,need_uptime,need_capacity);
case CIRCUIT_PURPOSE_C_ESTABLISH_REND:
return router_choose_random_node(
options->RendNodes, options->RendExcludeNodes,
NULL, need_uptime, need_capacity, 0,
options->_AllowUnverified & ALLOW_UNVERIFIED_RENDEZVOUS, 0);
options->_AllowInvalid & ALLOW_INVALID_RENDEZVOUS, 0);
}
log_warn(LD_BUG,"Bug: unhandled purpose %d", purpose);
tor_fragile_assert();
@ -1417,9 +1417,9 @@ count_acceptable_routers(smartlist_t *routers)
// log_debug(LD_CIRC,"Nope, the directory says %d is not running.",i);
goto next_i_loop;
}
if (r->is_verified == 0) {
// log_debug(LD_CIRC,"Nope, the directory says %d is not verified.",i);
/* XXXX009 But unverified routers *are* sometimes acceptable. */
if (r->is_valid == 0) {
// log_debug(LD_CIRC,"Nope, the directory says %d is not valid.",i);
/* XXXX009 But invalid routers *are* sometimes acceptable. */
goto next_i_loop;
}
num++;
@ -1486,7 +1486,7 @@ choose_good_middle_server(uint8_t purpose,
choice = router_choose_random_node(
NULL, get_options()->ExcludeNodes, excluded,
state->need_uptime, state->need_capacity, 0,
get_options()->_AllowUnverified & ALLOW_UNVERIFIED_MIDDLE, 0);
get_options()->_AllowInvalid & ALLOW_INVALID_MIDDLE, 0);
smartlist_free(excluded);
return choice;
}
@ -1538,7 +1538,7 @@ choose_good_entry_server(uint8_t purpose, cpath_build_state_t *state)
excluded, state ? state->need_uptime : 0,
state ? state->need_capacity : 0,
state ? 0 : 1,
options->_AllowUnverified & ALLOW_UNVERIFIED_ENTRY, 0);
options->_AllowInvalid & ALLOW_INVALID_ENTRY, 0);
smartlist_free(excluded);
return choice;
}

2
src/or/circuituse.c
View File

@ -1081,7 +1081,7 @@ consider_recording_trackhost(connection_t *conn, circuit_t *circ)
return;
/* write down the fingerprint of the chosen exit, not the nickname,
* because the chosen exit might not be verified. */
* because the chosen exit might not be named. */
base16_encode(fp, sizeof(fp),
circ->build_state->chosen_exit->identity_digest, DIGEST_LEN);

31
src/or/config.c
View File

@ -64,6 +64,7 @@ static config_abbrev_t _option_abbrevs[] = {
PLURAL(StrictEntryNode),
PLURAL(StrictExitNode),
{ "l", "Log", 1, 0},
{ "AllowUnverifiedNodes", "AllowInvalidNodes", 0, 0},
{ "BandwidthRateBytes", "BandwidthRate", 0, 0},
{ "BandwidthBurstBytes", "BandwidthBurst", 0, 0},
{ "DirFetchPostPeriod", "StatusFetchPeriod", 0, 0},
@ -126,7 +127,7 @@ static config_var_t _option_vars[] = {
VAR("AccountingStart", STRING, AccountingStart, NULL),
VAR("Address", STRING, Address, NULL),
VAR("__AllDirActionsPrivate",BOOL, AllDirActionsPrivate, "0"),
VAR("AllowUnverifiedNodes",CSV, AllowUnverifiedNodes,
VAR("AllowInvalidNodes", CSV, AllowInvalidNodes,
"middle,rendezvous"),
VAR("AssumeReachable", BOOL, AssumeReachable, "0"),
VAR("AuthDirInvalid", LINELIST, AuthDirInvalid, NULL),
@ -1336,12 +1337,12 @@ get_assigned_option(config_format_t *fmt, or_options_t *options,
* clearing, or make the value 0 or NULL.
*
* Here are the use cases:
* 1. A non-empty AllowUnverified line in your torrc. Appends to current
* 1. A non-empty AllowInvalid line in your torrc. Appends to current
* if linelist, replaces current if csv.
* 2. An empty AllowUnverified line in your torrc. Should clear it.
* 3. "RESETCONF AllowUnverified" sets it to default.
* 4. "SETCONF AllowUnverified" makes it NULL.
* 5. "SETCONF AllowUnverified=foo" clears it and sets it to "foo".
* 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"
@ -2311,22 +2312,22 @@ options_validate(or_options_t *old_options, or_options_t *options,
"of the Internet, so they must not set Reachable*Addresses "
"or FascistFirewall.");
options->_AllowUnverified = 0;
if (options->AllowUnverifiedNodes) {
SMARTLIST_FOREACH(options->AllowUnverifiedNodes, const char *, cp, {
options->_AllowInvalid = 0;
if (options->AllowInvalidNodes) {
SMARTLIST_FOREACH(options->AllowInvalidNodes, const char *, cp, {
if (!strcasecmp(cp, "entry"))
options->_AllowUnverified |= ALLOW_UNVERIFIED_ENTRY;
options->_AllowInvalid |= ALLOW_INVALID_ENTRY;
else if (!strcasecmp(cp, "exit"))
options->_AllowUnverified |= ALLOW_UNVERIFIED_EXIT;
options->_AllowInvalid |= ALLOW_INVALID_EXIT;
else if (!strcasecmp(cp, "middle"))
options->_AllowUnverified |= ALLOW_UNVERIFIED_MIDDLE;
options->_AllowInvalid |= ALLOW_INVALID_MIDDLE;
else if (!strcasecmp(cp, "introduction"))
options->_AllowUnverified |= ALLOW_UNVERIFIED_INTRODUCTION;
options->_AllowInvalid |= ALLOW_INVALID_INTRODUCTION;
else if (!strcasecmp(cp, "rendezvous"))
options->_AllowUnverified |= ALLOW_UNVERIFIED_RENDEZVOUS;
options->_AllowInvalid |= ALLOW_INVALID_RENDEZVOUS;
else {
log(LOG_WARN, LD_CONFIG,
"Unrecognized value '%s' in AllowUnverifiedNodes", cp);
"Unrecognized value '%s' in AllowInvalidNodes", cp);
result = -1;
}
});

42
src/or/dirserv.c
View File

@ -362,7 +362,7 @@ dirserv_get_status_impl(const char *fp, const char *nickname,
tor_free(esc_contact);
}
if (msg)
*msg = "Rejected: There is already a verified server with this nickname "
*msg = "Rejected: There is already a named server with this nickname "
"and a different fingerprint.";
return FP_REJECT; /* Wrong fingerprint. */
}
@ -485,14 +485,14 @@ authdir_wants_to_reject_router(routerinfo_t *ri, const char **msg,
/* Okay, looks like we're willing to accept this one. */
switch (status) {
case FP_NAMED:
ri->is_named = ri->is_verified = 1;
ri->is_named = ri->is_valid = 1;
break;
case FP_VALID:
ri->is_named = 0;
ri->is_verified = 1;
ri->is_valid = 1;
break;
case FP_INVALID:
ri->is_named = ri->is_verified = 0;
ri->is_named = ri->is_valid = 0;
break;
default:
tor_assert(0);
@ -556,8 +556,8 @@ dirserv_add_descriptor(const char *desc, const char **msg)
control_event_descriptors_changed(changed);
smartlist_free(changed);
if (!*msg) {
*msg = ri->is_verified ? "Verified server descriptor accepted" :
"Unverified server descriptor accepted";
*msg = ri->is_valid ? "Descriptor for valid server accepted" :
"Descriptor for invalid server accepted";
}
return r == 0 ? 2 : 1;
}
@ -586,26 +586,26 @@ directory_remove_invalid(void)
changed = 1;
break;
case FP_NAMED:
if (!ent->is_verified || !ent->is_named) {
if (!ent->is_valid || !ent->is_named) {
log_info(LD_DIRSERV,
"Router '%s' is now verified and named.", ent->nickname);
ent->is_verified = ent->is_named = 1;
"Router '%s' is now valid and named.", ent->nickname);
ent->is_valid = ent->is_named = 1;
changed = 1;
}
break;
case FP_VALID:
if (!ent->is_verified || ent->is_named) {
log_info(LD_DIRSERV, "Router '%s' is now verified.", ent->nickname);
ent->is_verified = 1;
if (!ent->is_valid || ent->is_named) {
log_info(LD_DIRSERV, "Router '%s' is now valid.", ent->nickname);
ent->is_valid = 1;
ent->is_named = 0;
changed = 1;
}
break;
case FP_INVALID:
if (ent->is_verified || ent->is_named) {
if (ent->is_valid || ent->is_named) {
log_info(LD_DIRSERV,
"Router '%s' is no longer verified.", ent->nickname);
ent->is_verified = ent->is_named = 0;
"Router '%s' is no longer valid.", ent->nickname);
ent->is_valid = ent->is_named = 0;
changed = 1;
}
break;
@ -683,7 +683,7 @@ list_single_server_status(routerinfo_t *desc, int is_live)
if (!is_live) {
*cp++ = '!';
}
if (desc->is_verified) {
if (desc->is_valid) {
strlcpy(cp, desc->nickname, sizeof(buf)-(cp-buf));
cp += strlen(cp);
*cp++ = '=';
@ -1267,7 +1267,7 @@ _compare_longs(const void **a, const void **b)
}
/** Look through the routerlist, and assign the median uptime
* of running verified servers to stable_uptime. */
* of running valid servers to stable_uptime. */
static void
dirserv_compute_stable_uptime(routerlist_t *rl)
{
@ -1275,7 +1275,7 @@ dirserv_compute_stable_uptime(routerlist_t *rl)
long *up;
SMARTLIST_FOREACH(rl->routers, routerinfo_t *, ri, {
if (ri->is_running && ri->is_verified) {
if (ri->is_running && ri->is_valid) {
up = tor_malloc(sizeof(long));
*up = ri->uptime;
smartlist_add(uptimes, up);
@ -1401,7 +1401,7 @@ generate_v2_networkstatus(void)
int f_authority = router_digest_is_trusted_dir(
ri->cache_info.identity_digest);
int f_named = naming && ri->is_named;
int f_valid = ri->is_verified;
int f_valid = ri->is_valid;
int f_guard = f_fast && f_stable;
/* 0.1.1.9-alpha is the first version to support fetch by descriptor
* hash. */
@ -1628,7 +1628,7 @@ dirserv_get_routerdescs(smartlist_t *descs_out, const char *key,
* a certificate with digest <b>digest_rcvd</b> and nickname
* <b>nickname_rcvd</b>. When this happens, it's clear that any other
* descriptors for that address/port combination must be unusable:
* delete them if they are not verified.
* delete them if they are not valid.
*
* Also, if as_advertised is 1, then inform the reachability checker
* that we could get to this guy.
@ -1653,7 +1653,7 @@ dirserv_orconn_tls_done(const char *address,
int drop = 0;
if (strcasecmp(address, ri->address) || or_port != ri->or_port)
continue;
if (!ri->is_verified) {
if (!ri->is_valid) {
/* We have a router at the same address! */
if (strcasecmp(ri->nickname, nickname_rcvd)) {
log_notice(LD_DIRSERV,

18
src/or/or.h
View File

@ -808,7 +808,7 @@ typedef struct {
/* local info */
unsigned int is_running:1; /**< As far as we know, is this OR currently
* running? */
unsigned int is_verified:1; /**< Has a trusted dirserver validated this OR?
unsigned int is_valid:1; /**< Has a trusted dirserver validated this OR?
* (For Authdir: Have we validated this OR?)
*/
unsigned int is_named:1; /**< Do we believe the nickname that this OR gives
@ -1175,11 +1175,11 @@ struct circuit_t {
typedef struct circuit_t circuit_t;
#define ALLOW_UNVERIFIED_ENTRY 1
#define ALLOW_UNVERIFIED_EXIT 2
#define ALLOW_UNVERIFIED_MIDDLE 4
#define ALLOW_UNVERIFIED_RENDEZVOUS 8
#define ALLOW_UNVERIFIED_INTRODUCTION 16
#define ALLOW_INVALID_ENTRY 1
#define ALLOW_INVALID_EXIT 2
#define ALLOW_INVALID_MIDDLE 4
#define ALLOW_INVALID_RENDEZVOUS 8
#define ALLOW_INVALID_INTRODUCTION 16
/** An entry specifying a set of addresses and ports that should be remapped
* to another address and port before exiting this exit node. */
@ -1240,8 +1240,8 @@ typedef struct {
char *RendExcludeNodes; /**< Comma-separated list of nicknames not to use
* as introduction points. */
smartlist_t *AllowUnverifiedNodes; /**< List of "entry", "middle", "exit" */
int _AllowUnverified; /**< Bitmask; derived from AllowUnverifiedNodes; */
smartlist_t *AllowInvalidNodes; /**< List of "entry", "middle", "exit" */
int _AllowInvalid; /**< Bitmask; derived from AllowInvalidNodes; */
config_line_t *ExitPolicy; /**< Lists of exit policy components. */
int ExitPolicyRejectPrivate; /**< Should we not exit to local addresses? */
config_line_t *SocksPolicy; /**< Lists of socks policy components */
@ -2303,7 +2303,7 @@ routerinfo_t *router_choose_random_node(const char *preferred,
smartlist_t *excludedsmartlist,
int need_uptime, int need_bandwidth,
int need_guard,
int allow_unverified, int strict);
int allow_invalid, int strict);
routerinfo_t *router_get_by_nickname(const char *nickname,
int warn_if_unnamed);
routerinfo_t *router_get_by_hexdigest(const char *hexdigest);

2
src/or/rendservice.c
View File

@ -999,7 +999,7 @@ rend_services_introduce(void)
char *hex_digest;
router = router_choose_random_node(service->intro_prefer_nodes,
service->intro_exclude_nodes, exclude_routers, 1, 0, 0,
get_options()->_AllowUnverified & ALLOW_UNVERIFIED_INTRODUCTION,
get_options()->_AllowInvalid & ALLOW_INVALID_INTRODUCTION,
0);
if (!router) {
log_warn(LD_REND,

4
src/or/router.c
View File

@ -833,12 +833,12 @@ router_rebuild_descriptor(int force)
options->ExitPolicyRejectPrivate);
if (desc_routerinfo) { /* inherit values */
ri->is_verified = desc_routerinfo->is_verified;
ri->is_valid = desc_routerinfo->is_valid;
ri->is_running = desc_routerinfo->is_running;
ri->is_named = desc_routerinfo->is_named;
}
if (authdir_mode(options))
ri->is_verified = ri->is_named = 1; /* believe in yourself */
ri->is_valid = ri->is_named = 1; /* believe in yourself */
if (options->MyFamily) {
smartlist_t *family;
if (!warned_nonexistent_family)

52
src/or/routerlist.c
View File

@ -79,9 +79,9 @@ static time_t last_routerdesc_download_attempted = 0;
* mirrors). Clients don't use this now. */
static time_t last_networkstatus_download_attempted = 0;
/** True iff we have logged a warning about this OR not being verified or
/** True iff we have logged a warning about this OR not being valid or
* not being named. */
static int have_warned_about_unverified_status = 0;
static int have_warned_about_invalid_status = 0;
/** True iff we have logged a warning about this OR's version being older than
* listed by the authorities */
static int have_warned_about_old_version = 0;
@ -412,7 +412,7 @@ router_pick_trusteddirserver(int need_v1_authority,
requireother, fascistfirewall);
}
/** Pick a random running verified directory server/mirror from our
/** Pick a random running valid directory server/mirror from our
* routerlist. Don't pick an authority if any non-authorities are viable.
* If <b>fascistfirewall</b>,
* make sure the router we pick is allowed by our firewall options.
@ -650,7 +650,7 @@ router_nickname_is_in_list(routerinfo_t *router, const char *list)
* <b>sl</b>, so that we can pick a node for a circuit.
*/
static void
router_add_running_routers_to_smartlist(smartlist_t *sl, int allow_unverified,
router_add_running_routers_to_smartlist(smartlist_t *sl, int allow_invalid,
int need_uptime, int need_capacity,
int need_guard)
{
@ -661,12 +661,12 @@ router_add_running_routers_to_smartlist(smartlist_t *sl, int allow_unverified,
{
if (router->is_running &&
router->purpose == ROUTER_PURPOSE_GENERAL &&
(router->is_verified ||
(allow_unverified &&
(router->is_valid ||
(allow_invalid &&
!router_is_unreliable(router, need_uptime,
need_capacity, need_guard)))) {
/* If it's running, and either it's verified or we're ok picking
* unverified routers and this one is suitable.
/* If it's running, and either it's valid or we're ok picking
* invalid routers and this one is suitable.
*/
smartlist_add(sl, router);
}
@ -819,7 +819,7 @@ router_choose_random_node(const char *preferred,
smartlist_t *excludedsmartlist,
int need_uptime, int need_capacity,
int need_guard,
int allow_unverified, int strict)
int allow_invalid, int strict)
{
smartlist_t *sl, *excludednodes;
routerinfo_t *choice = NULL;
@ -842,7 +842,7 @@ router_choose_random_node(const char *preferred,
/* Then give up on our preferred choices: any node
* will do that has the required attributes. */
sl = smartlist_create();
router_add_running_routers_to_smartlist(sl, allow_unverified,
router_add_running_routers_to_smartlist(sl, allow_invalid,
need_uptime, need_capacity,
need_guard);
smartlist_subtract(sl,excludednodes);
@ -864,7 +864,7 @@ router_choose_random_node(const char *preferred,
need_uptime?", stable":"",
need_guard?", guard":"");
choice = router_choose_random_node(
NULL, excluded, excludedsmartlist, 0, 0, 0, allow_unverified, 0);
NULL, excluded, excludedsmartlist, 0, 0, 0, allow_invalid, 0);
}
}
smartlist_free(excludednodes);
@ -1404,7 +1404,7 @@ routerlist_reset_warnings(void)
SMARTLIST_FOREACH(routerstatus_list, local_routerstatus_t *, rs,
rs->name_lookup_warned = 0);
have_warned_about_unverified_status = 0;
have_warned_about_invalid_status = 0;
have_warned_about_old_version = 0;
have_warned_about_new_version = 0;
}
@ -1471,7 +1471,7 @@ router_add_to_routerlist(routerinfo_t *router, const char **msg,
int i;
const char *id_digest;
int authdir = get_options()->AuthoritativeDir;
int authdir_verified = 0;
int authdir_believes_valid = 0;
tor_assert(msg);
@ -1501,7 +1501,7 @@ router_add_to_routerlist(routerinfo_t *router, const char **msg,
routerinfo_free(router);
return -2;
}
authdir_verified = router->is_verified;
authdir_believes_valid = router->is_valid;
} else if (from_fetch) {
/* Only check the descriptor digest against the network statuses when
* we are receiving in response to a fetch. */
@ -1567,17 +1567,17 @@ router_add_to_routerlist(routerinfo_t *router, const char **msg,
}
directory_set_dirty();
*msg = unreachable ? "Dirserver believes your ORPort is unreachable" :
authdir_verified ? "Verified server updated" :
("Unverified server updated. (Have you sent us your key "
"fingerprint?)");
authdir_believes_valid ? "Valid server updated" :
("Invalid server updated. (This dirserver is marking your "
"server as unapproved.)");
return unreachable ? 1 : 0;
}
} else if (!strcasecmp(router->nickname, old_router->nickname)) {
/* nicknames match, keys don't. */
if (router->is_named) {
/* The new verified router replaces the old one; remove the
/* The new named router replaces the old one; remove the
* old one. And carry on to the end of the list, in case
* there are more old unverified routers with this nickname
* there are more old unnamed routers with this nickname.
*/
/* mark-for-close connections using the old key, so we can
* make new ones with the new key.
@ -1592,8 +1592,8 @@ router_add_to_routerlist(routerinfo_t *router, const char **msg,
}
routerlist_remove(routerlist, old_router, i--, 0);
} else if (old_router->is_named) {
/* Can't replace a verified router with an unverified one. */
log_debug(LD_DIR, "Skipping unverified entry for verified router '%s'",
/* Can't replace a named router with an unnamed one. */
log_debug(LD_DIR, "Skipping unnamed entry for named router '%s'",
router->nickname);
routerinfo_free(router);
*msg =
@ -2786,7 +2786,7 @@ routers_update_all_from_networkstatus(void)
routers_update_status_from_networkstatus(routerlist->routers, 0);
me = router_get_my_routerinfo();
if (me && !have_warned_about_unverified_status) {
if (me && !have_warned_about_invalid_status) {
int n_recent = 0, n_listing = 0, n_valid = 0, n_named = 0, n_naming = 0;
routerstatus_t *rs;
SMARTLIST_FOREACH(networkstatus_list, networkstatus_t *, ns,
@ -2816,13 +2816,13 @@ routers_update_all_from_networkstatus(void)
"as invalid. Please "
"consider sending your identity fingerprint to the tor-ops.",
n_recent-n_valid, n_recent);
have_warned_about_unverified_status = 1;
have_warned_about_invalid_status = 1;
} else if (!n_named && have_tried_downloading_all_statuses()) {
log_warn(LD_GENERAL, "0/%d name-binding directory authorities "
"recognize this server. Please consider sending your "
"identity fingerprint to the tor-ops.",
n_naming);
have_warned_about_unverified_status = 1;
have_warned_about_invalid_status = 1;
}
}
}
@ -3217,7 +3217,7 @@ routerstatus_list_update_from_networkstatus(time_t now)
}
/** Given a list <b>routers</b> of routerinfo_t *, update each routers's
* is_named, is_verified, and is_running fields according to our current
* is_named, is_valid, and is_running fields according to our current
* networkstatus_t documents. */
void
routers_update_status_from_networkstatus(smartlist_t *routers,
@ -3248,7 +3248,7 @@ routers_update_status_from_networkstatus(smartlist_t *routers,
if (!authdir) {
/* If we're not an authdir, believe others. */
router->is_verified = rs->status.is_valid;
router->is_valid = rs->status.is_valid;
router->is_running = rs->status.is_running;
router->is_fast = rs->status.is_fast;
router->is_stable = rs->status.is_stable;

2
src/or/routerparse.c
View File

@ -640,7 +640,7 @@ check_directory_signature(const char *digest,
/** Given a string *<b>s</b> containing a concatenated sequence of router
* descriptors, parses them and stores the result in <b>dest</b>. All routers
* are marked running and verified. Advances *s to a point immediately
* are marked running and valid. Advances *s to a point immediately
* following the last router entry. Ignore any trailing router entries that
* are not complete. Returns 0 on success and -1 on failure.
*/