networkstatus.h File Reference

Header file for networkstatus.c. More...

#include "testsupport.h"

Include dependency graph for networkstatus.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	routerstatus_free(rs)   FREE_AND_NULL(routerstatus_t, routerstatus_free_, (rs))
#define	networkstatus_vote_free(ns)   FREE_AND_NULL(networkstatus_t, networkstatus_vote_free_, (ns))
#define	ns_detached_signatures_free(s)   FREE_AND_NULL(ns_detached_signatures_t, ns_detached_signatures_free_, (s))
#define	NSSET_FROM_CACHE   1
#define	NSSET_WAS_WAITING_FOR_CERTS   2
#define	NSSET_DONT_DOWNLOAD_CERTS   4
#define	NSSET_ACCEPT_OBSOLETE   8
#define	NSSET_REQUIRE_FLAVOR   16
#define	document_signature_free(sig)   FREE_AND_NULL(document_signature_t, document_signature_free_, (sig))
#define	vote_routerstatus_free(rs)   FREE_AND_NULL(vote_routerstatus_t, vote_routerstatus_free_, (rs))

Functions
void	networkstatus_reset_warnings (void)
void	networkstatus_reset_download_failures (void)
char *	networkstatus_read_cached_consensus (const char *flavorname)
int	router_reload_consensus_networkstatus (void)
void	routerstatus_free_ (routerstatus_t *rs)
void	networkstatus_vote_free_ (networkstatus_t *ns)
void	ns_detached_signatures_free_ (ns_detached_signatures_t *s)
networkstatus_voter_info_t *	networkstatus_get_voter_by_id (networkstatus_t *vote, const char *identity)
document_signature_t *	networkstatus_get_voter_sig_by_alg (const networkstatus_voter_info_t *voter, digest_algorithm_t alg)
int	networkstatus_check_consensus_signature (networkstatus_t *consensus, int warn)
int	networkstatus_check_document_signature (const networkstatus_t *consensus, document_signature_t *sig, const authority_cert_t *cert)
int	compare_digest_to_routerstatus_entry (const void *_key, const void **_member)
int	compare_digest_to_vote_routerstatus_entry (const void *_key, const void **_member)
const routerstatus_t *	networkstatus_vote_find_entry (networkstatus_t *ns, const char *digest)
routerstatus_t *	networkstatus_vote_find_mutable_entry (networkstatus_t *ns, const char *digest)
int	networkstatus_vote_find_entry_idx (networkstatus_t *ns, const char *digest, int *found_out)
	MOCK_DECL (download_status_t *, networkstatus_get_dl_status_by_flavor,(consensus_flavor_t flavor))
	MOCK_DECL (download_status_t *, networkstatus_get_dl_status_by_flavor_bootstrap,(consensus_flavor_t flavor))
	MOCK_DECL (download_status_t *, networkstatus_get_dl_status_by_flavor_running,(consensus_flavor_t flavor))
	MOCK_DECL (smartlist_t *, router_get_descriptor_digests,(void))
	MOCK_DECL (download_status_t *, router_get_dl_status_by_descriptor_digest,(const char *d))
const routerstatus_t *	router_get_consensus_status_by_id (const char *digest)
routerstatus_t *	router_get_mutable_consensus_status_by_id (const char *digest)
const routerstatus_t *	router_get_consensus_status_by_descriptor_digest (networkstatus_t *consensus, const char *digest)
	MOCK_DECL (routerstatus_t *, router_get_mutable_consensus_status_by_descriptor_digest,(networkstatus_t *consensus, const char *digest))
int	we_want_to_fetch_flavor (const or_options_t *options, int flavor)
int	we_want_to_fetch_unknown_auth_certs (const or_options_t *options)
void	networkstatus_consensus_download_failed (int status_code, const char *flavname)
void	update_consensus_networkstatus_fetch_time (time_t now)
int	should_delay_dir_fetches (const or_options_t *options, const char **msg_out)
void	update_networkstatus_downloads (time_t now)
void	update_certificate_downloads (time_t now)
int	consensus_is_waiting_for_certs (void)
int	client_would_use_router (const routerstatus_t *rs, time_t now)
	MOCK_DECL (networkstatus_t *, networkstatus_get_latest_consensus,(void))
	MOCK_DECL (networkstatus_t *, networkstatus_get_latest_consensus_by_flavor,(consensus_flavor_t f))
	MOCK_DECL (networkstatus_t *, networkstatus_get_live_consensus,(time_t now))
int	networkstatus_is_live (const networkstatus_t *ns, time_t now)
int	networkstatus_consensus_reasonably_live (const networkstatus_t *consensus, time_t now)
int	networkstatus_valid_until_is_reasonably_live (time_t valid_until, time_t now)
networkstatus_t *	networkstatus_get_reasonably_live_consensus (time_t now, int flavor)
	MOCK_DECL (int, networkstatus_consensus_is_bootstrapping,(time_t now))
int	networkstatus_consensus_can_use_multiple_directories (const or_options_t *options)
	MOCK_DECL (int, networkstatus_consensus_can_use_extra_fallbacks,(const or_options_t *options))
int	networkstatus_consensus_is_already_downloading (const char *resource)
int	networkstatus_consensus_has_ipv6 (const or_options_t *options)
int	networkstatus_set_current_consensus (const char *consensus, const char *flavor, unsigned flags, const char *source_dir)
void	networkstatus_note_certs_arrived (const char *source_dir)
void	routers_update_all_from_networkstatus (time_t now, int dir_version)
void	routers_update_status_from_consensus_networkstatus (smartlist_t *routers, int reset_failures)
void	signed_descs_update_status_from_consensus_networkstatus (smartlist_t *descs)
char *	networkstatus_getinfo_helper_single (const routerstatus_t *rs)
char *	networkstatus_getinfo_by_purpose (const char *purpose_string, time_t now)
void	networkstatus_dump_bridge_status_to_file (time_t now)
	MOCK_DECL (int32_t, networkstatus_get_param,(const networkstatus_t *ns, const char *param_name, int32_t default_val, int32_t min_val, int32_t max_val))
int32_t	networkstatus_get_overridable_param (const networkstatus_t *ns, int32_t torrc_value, const char *param_name, int32_t default_val, int32_t min_val, int32_t max_val)
int	getinfo_helper_networkstatus (control_connection_t *conn, const char *question, char **answer, const char **errmsg)
int32_t	networkstatus_get_bw_weight (networkstatus_t *ns, const char *weight, int32_t default_val)
const char *	networkstatus_get_flavor_name (consensus_flavor_t flav)
int	networkstatus_parse_flavor_name (const char *flavname)
void	document_signature_free_ (document_signature_t *sig)
document_signature_t *	document_signature_dup (const document_signature_t *sig)
void	networkstatus_free_all (void)
int	networkstatus_get_weight_scale_param (networkstatus_t *ns)
void	vote_routerstatus_free_ (vote_routerstatus_t *rs)

Detailed Description

Header file for networkstatus.c.

Function Documentation

client_would_use_router()

int client_would_use_router	(	const routerstatus_t *	rs,
		time_t	now
	)

Return 0 if this routerstatus is obsolete, too new, isn't running, or otherwise not a descriptor that we would make any use of even if we had it. Else return 1.

compare_digest_to_routerstatus_entry()

int compare_digest_to_routerstatus_entry	(	const void *	_key,
		const void **	_member
	)

Helper for bsearching a list of routerstatus_t pointers: compare a digest in the key to the identity digest of a routerstatus_t.

Here is the call graph for this function:

Here is the caller graph for this function:

compare_digest_to_vote_routerstatus_entry()

int compare_digest_to_vote_routerstatus_entry	(	const void *	_key,
		const void **	_member
	)

Helper for bsearching a list of routerstatus_t pointers: compare a digest in the key to the identity digest of a routerstatus_t.

Here is the call graph for this function:

Here is the caller graph for this function:

consensus_is_waiting_for_certs()

int consensus_is_waiting_for_certs

(

void

)

Return 1 if we have a consensus but we don't have enough certificates to start using it yet.

Here is the caller graph for this function:

document_signature_dup()

document_signature_t* document_signature_dup

(

const document_signature_t *

sig

)

Return a newly allocated copy of sig

document_signature_free_()

void document_signature_free_

(

document_signature_t *

sig

)

Free all storage held in sig

getinfo_helper_networkstatus()

int getinfo_helper_networkstatus	(	control_connection_t *	conn,
		const char *	question,
		char **	answer,
		const char **	errmsg
	)

If question is a string beginning with "ns/" in a format the control interface expects for a GETINFO question, set *answer to a newly-allocated string containing networkstatus lines for the appropriate ORs. Return 0 on success, -1 on unrecognized question format.

networkstatus_check_consensus_signature()

int networkstatus_check_consensus_signature	(	networkstatus_t *	consensus,
		int	warn
	)

Given a v3 networkstatus consensus in consensus, check every as-yet-unchecked signature on consensus. Return 1 if there is a signature from every recognized authority on it, 0 if there are enough good signatures from recognized authorities on it, -1 if we might get enough good signatures by fetching missing certificates, and -2 otherwise. Log messages at INFO or WARN: if warn is over 1, warn about every problem; if warn is at least 1, warn only if we can't get enough signatures; if warn is negative, log nothing at all.

Here is the call graph for this function:

Here is the caller graph for this function:

networkstatus_check_document_signature()

int networkstatus_check_document_signature	(	const networkstatus_t *	consensus,
		document_signature_t *	sig,
		const authority_cert_t *	cert
	)

Check whether the signature sig is correctly signed with the signing key in cert. Return -1 if cert doesn't match the signing key; otherwise set the good_signature or bad_signature flag on voter, and return 0.

networkstatus_consensus_can_use_multiple_directories()

int networkstatus_consensus_can_use_multiple_directories

(

const or_options_t *

options

)

Check if we can use multiple directories for a consensus download. Only clients (including bridge relays, which act like clients) benefit from multiple simultaneous consensus downloads.

networkstatus_consensus_download_failed()

void networkstatus_consensus_download_failed	(	int	status_code,
		const char *	flavname
	)

Called when an attempt to download a consensus fails: note that the failure occurred, and possibly retry.

Here is the call graph for this function:

Here is the caller graph for this function:

networkstatus_consensus_reasonably_live()

int networkstatus_consensus_reasonably_live	(	const networkstatus_t *	consensus,
		time_t	now
	)

Determine if consensus is valid or expired recently enough that we can still use it.

Return 1 if the consensus is reasonably live, or 0 if it is too old.

Here is the caller graph for this function:

networkstatus_dump_bridge_status_to_file()

void networkstatus_dump_bridge_status_to_file

(

time_t

now

)

Write out router status entries for all our bridge descriptors.

Here is the call graph for this function:

networkstatus_free_all()

void networkstatus_free_all

(

void

)

Free all storage held locally in this module.

networkstatus_get_bw_weight()

int32_t networkstatus_get_bw_weight	(	networkstatus_t *	ns,
		const char *	weight_name,
		int32_t	default_val
	)

Return the value of a integer bw weight parameter from the networkstatus ns whose name is weight_name. If ns is NULL, try loading the latest consensus ourselves. Return default_val if no latest consensus, or if it has no parameter called weight_name.

Here is the call graph for this function:

Here is the caller graph for this function:

networkstatus_get_flavor_name()

const char* networkstatus_get_flavor_name

(

consensus_flavor_t

flav

)

Return the name of the consensus flavor flav as used to identify the flavor in directory documents.

Here is the caller graph for this function:

networkstatus_get_overridable_param()

int32_t networkstatus_get_overridable_param	(	const networkstatus_t *	ns,
		int32_t	torrc_value,
		const char *	param_name,
		int32_t	default_val,
		int32_t	min_val,
		int32_t	max_val
	)

As networkstatus_get_param(), but check torrc_value before checking the consensus. If torrc_value is in-range, then return it instead of the value from the consensus.

networkstatus_get_reasonably_live_consensus()

networkstatus_t* networkstatus_get_reasonably_live_consensus	(	time_t	now,
		int	flavor
	)

As networkstatus_get_live_consensus(), but is way more tolerant of expired consensuses.

Here is the call graph for this function:

Here is the caller graph for this function:

networkstatus_get_voter_by_id()

networkstatus_voter_info_t* networkstatus_get_voter_by_id	(	networkstatus_t *	vote,
		const char *	identity
	)

Return the voter info from vote for the voter whose identity digest is identity, or NULL if no such voter is associated with vote.

networkstatus_get_voter_sig_by_alg()

document_signature_t* networkstatus_get_voter_sig_by_alg	(	const networkstatus_voter_info_t *	voter,
		digest_algorithm_t	alg
	)

Return the signature made by voter using the algorithm alg, or NULL if none is found.

networkstatus_get_weight_scale_param()

int networkstatus_get_weight_scale_param

(

networkstatus_t *

ns

)

Retrieve the consensus parameter that governs the fixed-point precision of our network balancing 'bandwidth-weights' (which are themselves integer consensus values). We divide them by this value and ensure they never exceed this value.

Here is the caller graph for this function:

networkstatus_getinfo_by_purpose()

char* networkstatus_getinfo_by_purpose	(	const char *	purpose_string,
		time_t	now
	)

Alloc and return a string describing routerstatuses for the most recent info of each router we know about that is of purpose purpose_string. Return NULL if unrecognized purpose.

Right now this function is oriented toward listing bridges (you shouldn't use this for general-purpose routers, since those should be listed from the consensus, not from the routers list).

Here is the call graph for this function:

Here is the caller graph for this function:

networkstatus_getinfo_helper_single()

char* networkstatus_getinfo_helper_single

(

const routerstatus_t *

rs

)

Generate networkstatus lines for a single routerstatus_t object, and return the result in a newly allocated string. Used only by controller interface (for now.)

Here is the call graph for this function:

networkstatus_is_live()

int networkstatus_is_live	(	const networkstatus_t *	ns,
		time_t	now
	)

Given a consensus in ns, return true iff currently live and unexpired.

Here is the caller graph for this function:

networkstatus_note_certs_arrived()

void networkstatus_note_certs_arrived

(

const char *

source_dir

)

Called when we have gotten more certificates: see whether we can now verify a pending consensus.

If source_dir is non-NULL, it's the identity digest for a directory that we've just successfully retrieved certificates from, so try it first to fetch any missing certificates.

Here is the call graph for this function:

networkstatus_parse_flavor_name()

int networkstatus_parse_flavor_name

(

const char *

flavname

)

Return the consensus_flavor_t value for the flavor called flavname, or -1 if the flavor is not recognized.

Here is the caller graph for this function:

networkstatus_read_cached_consensus()

char* networkstatus_read_cached_consensus

(

const char *

flavorname

)

Return a new string containing the current cached consensus of flavor flavorname.

Here is the call graph for this function:

Here is the caller graph for this function:

networkstatus_reset_download_failures()

void networkstatus_reset_download_failures

(

void

)

Reset the descriptor download failure count on all networkstatus docs, so that we can retry any long-failed documents immediately.

networkstatus_reset_warnings()

void networkstatus_reset_warnings

(

void

)

Forget that we've warned about anything networkstatus-related, so we will give fresh warnings if the same behavior happens again.

Here is the caller graph for this function:

networkstatus_set_current_consensus()

int networkstatus_set_current_consensus	(	const char *	consensus,
		const char *	flavor,
		unsigned	flags,
		const char *	source_dir
	)

Try to replace the current cached v3 networkstatus with the one in consensus. If we don't have enough certificates to validate it, store it in consensus_waiting_for_certs and launch a certificate fetch.

If flags & NSSET_FROM_CACHE, this networkstatus has come from the disk cache. If flags & NSSET_WAS_WAITING_FOR_CERTS, this networkstatus was already received, but we were waiting for certificates on it. If flags & NSSET_DONT_DOWNLOAD_CERTS, do not launch certificate downloads as needed. If flags & NSSET_ACCEPT_OBSOLETE, then we should be willing to take this consensus, even if it comes from many days in the past.

If source_dir is non-NULL, it's the identity digest for a directory that we've just successfully retrieved a consensus or certificates from, so try it first to fetch any missing certificates.

Return 0 on success, <0 on failure. On failure, caller should increment the failure count as appropriate.

We return -1 for mild failures that don't need to be reported to the user, and -2 for more serious problems.

Here is the call graph for this function:

Here is the caller graph for this function:

networkstatus_valid_until_is_reasonably_live()

int networkstatus_valid_until_is_reasonably_live	(	time_t	valid_until,
		time_t	now
	)

As networkstatus_consensus_reasonably_live, but takes a valid_until time rather than an entire consensus.

networkstatus_vote_find_entry()

const routerstatus_t* networkstatus_vote_find_entry	(	networkstatus_t *	ns,
		const char *	digest
	)

Return the entry in ns for the identity digest digest, or NULL if none was found.

Here is the call graph for this function:

Here is the caller graph for this function:

networkstatus_vote_find_entry_idx()

int networkstatus_vote_find_entry_idx	(	networkstatus_t *	ns,
		const char *	digest,
		int *	found_out
	)

Search the routerstatuses in ns for one whose identity digest is digest. Return value and set *found_out as for smartlist_bsearch_idx().

Here is the call graph for this function:

networkstatus_vote_find_mutable_entry()

routerstatus_t* networkstatus_vote_find_mutable_entry	(	networkstatus_t *	ns,
		const char *	digest
	)

As networkstatus_find_entry, but do not return a const pointer

Here is the call graph for this function:

Here is the caller graph for this function:

networkstatus_vote_free_()

void networkstatus_vote_free_

(

networkstatus_t *

ns

)

Free all storage held in ns.

ns_detached_signatures_free_()

void ns_detached_signatures_free_

(

ns_detached_signatures_t *

s

)

Release all storage held in s.

router_get_consensus_status_by_descriptor_digest()

const routerstatus_t* router_get_consensus_status_by_descriptor_digest	(	networkstatus_t *	consensus,
		const char *	digest
	)

Return the consensus view of the status of the router whose current descriptor digest in consensus is digest, or NULL if no such router is known.

Here is the caller graph for this function:

router_get_consensus_status_by_id()

const routerstatus_t* router_get_consensus_status_by_id

(

const char *

digest

)

Return the consensus view of the status of the router whose identity digest is digest, or NULL if we don't know about any such router.

Here is the call graph for this function:

Here is the caller graph for this function:

router_get_mutable_consensus_status_by_id()

routerstatus_t* router_get_mutable_consensus_status_by_id

(

const char *

digest

)

As router_get_consensus_status_by_id, but do not return a const pointer

Here is the call graph for this function:

Here is the caller graph for this function:

router_reload_consensus_networkstatus()

int router_reload_consensus_networkstatus

(

void

)

Read every cached v3 consensus networkstatus from the disk.

routers_update_all_from_networkstatus()

void routers_update_all_from_networkstatus	(	time_t	now,
		int	dir_version
	)

If the network-status list has changed since the last time we called this function, update the status of every routerinfo from the network-status list. If dir_version is 2, it's a v2 networkstatus that changed. If dir_version is 3, it's a v3 consensus that changed.

Here is the call graph for this function:

routers_update_status_from_consensus_networkstatus()

void routers_update_status_from_consensus_networkstatus	(	smartlist_t *	routers,
		int	reset_failures
	)

Given a list routers of routerinfo_t *, update each status field according to our current consensus networkstatus. May re-order routers.

Here is the caller graph for this function:

routerstatus_free_()

void routerstatus_free_

(

routerstatus_t *

rs

)

Free all storage held by the routerstatus object rs.

should_delay_dir_fetches()

int should_delay_dir_fetches	(	const or_options_t *	options,
		const char **	msg_out
	)

Return 1 if there's a reason we shouldn't try any directory fetches yet (e.g. we demand bridges and none are yet known). Else return 0.

If we return 1 and msg_out is provided, set msg_out to an explanation of why directory fetches are delayed. (If we return 0, we set msg_out to NULL.)

Here is the caller graph for this function:

signed_descs_update_status_from_consensus_networkstatus()

void signed_descs_update_status_from_consensus_networkstatus

(

smartlist_t *

descs

)

Given a list of signed_descriptor_t, update their fields (mainly, when they were last listed) from the most recent consensus.

Here is the call graph for this function:

update_certificate_downloads()

void update_certificate_downloads

(

time_t

now

)

Launch requests as appropriate for missing directory authority certificates.

Here is the call graph for this function:

update_consensus_networkstatus_fetch_time()

void update_consensus_networkstatus_fetch_time

(

time_t

now

)

Update the time at which we'll consider replacing the current consensus of flavor 'flavor'

Here is the call graph for this function:

update_networkstatus_downloads()

void update_networkstatus_downloads

(

time_t

now

)

Launch requests for networkstatus documents as appropriate. This is called when we retry all the connections on a SIGHUP and periodically by a Periodic event which checks whether we want to download any networkstatus documents.

Launch a consensus download request, we will wait for the consensus to download and when it completes we will launch a certificate download request.

Here is the call graph for this function:

vote_routerstatus_free_()

void vote_routerstatus_free_

(

vote_routerstatus_t *

rs

)

Free all storage held by the vote_routerstatus object rs.

we_want_to_fetch_flavor()

int we_want_to_fetch_flavor	(	const or_options_t *	options,
		int	flavor
	)

Return true iff, given the options listed in options, flavor is the flavor of a consensus networkstatus that we would like to fetch.

For certificate fetches, use we_want_to_fetch_unknown_auth_certs, and for serving fetched documents, use directory_caches_dir_info.

Here is the caller graph for this function:

we_want_to_fetch_unknown_auth_certs()

int we_want_to_fetch_unknown_auth_certs

(

const or_options_t *

options

)

Return true iff, given the options listed in options, we would like to fetch and store unknown authority certificates.

For consensus and descriptor fetches, use we_want_to_fetch_flavor, and for serving fetched certificates, use directory_caches_unknown_auth_certs.

Here is the caller graph for this function: