dirserv.h File Reference

Header file for dirserv.c. More...

#include "testsupport.h"

Include dependency graph for dirserv.h:

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

Go to the source code of this file.

Data Structures
struct	spooled_resource_t

Macros
#define	REACHABILITY_MODULO_PER_TEST   128
#define	REACHABILITY_TEST_INTERVAL   10
#define	REACHABILITY_TEST_CYCLE_PERIOD   (REACHABILITY_TEST_INTERVAL*REACHABILITY_MODULO_PER_TEST)
#define	MAX_EXITPOLICY_SUMMARY_LEN   1000
#define	MAX_V_LINE_LEN   128
#define	dir_spool_source_bitfield_t   ENUM_BF(dir_spool_source_t)
#define	spooled_resource_free(sp)   FREE_AND_NULL(spooled_resource_t, spooled_resource_free_, (sp))

Typedefs
typedef enum dir_spool_source_t	dir_spool_source_t
typedef struct spooled_resource_t	spooled_resource_t

Enumerations
enum	dir_spool_source_t {   DIR_SPOOL_SERVER_BY_DIGEST =1, DIR_SPOOL_SERVER_BY_FP, DIR_SPOOL_EXTRA_BY_DIGEST, DIR_SPOOL_EXTRA_BY_FP,   DIR_SPOOL_MICRODESC, DIR_SPOOL_NETWORKSTATUS, DIR_SPOOL_CONSENSUS_CACHE_ENTRY }

Functions
int	connection_dirserv_flushed_some (dir_connection_t *conn)
int	dirserv_add_own_fingerprint (crypto_pk_t *pk)
int	dirserv_load_fingerprint_file (void)
void	dirserv_free_fingerprint_list (void)
enum was_router_added_t	dirserv_add_multiple_descriptors (const char *desc, uint8_t purpose, const char *source, const char **msg)
enum was_router_added_t	dirserv_add_descriptor (routerinfo_t *ri, const char **msg, const char *source)
void	dirserv_set_router_is_running (routerinfo_t *router, time_t now)
int	list_server_status_v1 (smartlist_t *routers, char **router_status_out, int for_controller)
char *	dirserv_get_flag_thresholds_line (void)
void	dirserv_compute_bridge_flag_thresholds (void)
int	directory_fetches_from_authorities (const or_options_t *options)
int	directory_fetches_dir_info_early (const or_options_t *options)
int	directory_fetches_dir_info_later (const or_options_t *options)
int	directory_caches_unknown_auth_certs (const or_options_t *options)
int	directory_caches_dir_info (const or_options_t *options)
int	directory_permits_begindir_requests (const or_options_t *options)
int	directory_too_idle_to_fetch_descriptors (const or_options_t *options, time_t now)
cached_dir_t *	dirserv_get_consensus (const char *flavor_name)
void	dirserv_set_cached_consensus_networkstatus (const char *consensus, const char *flavor_name, const common_digests_t *digests, const uint8_t *sha3_as_signed, time_t published)
void	dirserv_clear_old_networkstatuses (time_t cutoff)
int	dirserv_get_routerdesc_spool (smartlist_t *spools_out, const char *key, dir_spool_source_t source, int conn_is_encrypted, const char **msg_out)
int	dirserv_get_routerdescs (smartlist_t *descs_out, const char *key, const char **msg)
void	dirserv_orconn_tls_done (const tor_addr_t *addr, uint16_t or_port, const char *digest_rcvd, const ed25519_public_key_t *ed_id_rcvd)
int	dirserv_should_launch_reachability_test (const routerinfo_t *ri, const routerinfo_t *ri_old)
void	dirserv_single_reachability_test (time_t now, routerinfo_t *router)
void	dirserv_test_reachability (time_t now)
int	authdir_wants_to_reject_router (routerinfo_t *ri, const char **msg, int complain, int *valid_out)
uint32_t	dirserv_router_get_status (const routerinfo_t *router, const char **msg, int severity)
void	dirserv_set_node_flags_from_authoritative_status (node_t *node, uint32_t authstatus)
int	dirserv_would_reject_router (const routerstatus_t *rs)
char *	routerstatus_format_entry (const routerstatus_t *rs, const char *version, const char *protocols, routerstatus_format_type_t format, int consensus_method, const vote_routerstatus_t *vrs)
void	dirserv_free_all (void)
void	cached_dir_decref (cached_dir_t *d)
cached_dir_t *	new_cached_dir (char *s, time_t published)
int	validate_recommended_package_line (const char *line)
int	dirserv_query_measured_bw_cache_kb (const char *node_id, long *bw_out, time_t *as_of_out)
void	dirserv_clear_measured_bw_cache (void)
int	dirserv_has_measured_bw (const char *node_id)
int	dirserv_get_measured_bw_cache_size (void)
void	dirserv_count_measured_bws (const smartlist_t *routers)
int	running_long_enough_to_decide_unreachable (void)
void	dirserv_compute_performance_thresholds (digestmap_t *omit_as_sybil)
int	dirserv_read_measured_bandwidths (const char *from_file, smartlist_t *routerstatuses)
int	dirserv_read_guardfraction_file (const char *fname, smartlist_t *vote_routerstatuses)
spooled_resource_t *	spooled_resource_new (dir_spool_source_t source, const uint8_t *digest, size_t digestlen)
spooled_resource_t *	spooled_resource_new_from_cache_entry (struct consensus_cache_entry_t *entry)
void	spooled_resource_free_ (spooled_resource_t *spooled)
void	dirserv_spool_remove_missing_and_guess_size (dir_connection_t *conn, time_t cutoff, int compression, size_t *size_out, int *n_expired_out)
void	dirserv_spool_sort (dir_connection_t *conn)
void	dir_conn_clear_spool (dir_connection_t *conn)

Detailed Description

Header file for dirserv.c.

Macro Definition Documentation

MAX_EXITPOLICY_SUMMARY_LEN

#define MAX_EXITPOLICY_SUMMARY_LEN   1000

Maximum length of an exit policy summary.

MAX_V_LINE_LEN

#define MAX_V_LINE_LEN   128

Maximum allowable length of a version line in a networkstatus.

REACHABILITY_MODULO_PER_TEST

#define REACHABILITY_MODULO_PER_TEST   128

What fraction (1 over this number) of the relay ID space do we (as a directory authority) launch connections to at each reachability test?

REACHABILITY_TEST_CYCLE_PERIOD

#define REACHABILITY_TEST_CYCLE_PERIOD   (REACHABILITY_TEST_INTERVAL*REACHABILITY_MODULO_PER_TEST)

How many seconds apart are the reachability tests for a given relay?

REACHABILITY_TEST_INTERVAL

#define REACHABILITY_TEST_INTERVAL   10

How often (in seconds) do we launch reachability tests?

Typedef Documentation

dir_spool_source_t

typedef enum dir_spool_source_t dir_spool_source_t

Ways to convert a spoolable_resource_t to a bunch of bytes.

spooled_resource_t

typedef struct spooled_resource_t spooled_resource_t

Object to remember the identity of an object that we are spooling, or about to spool, in response to a directory request.

(Why do we spool? Because some directory responses are very large, and we don't want to just shove the complete answer into the output buffer: that would take a ridiculous amount of RAM.)

If the spooled resource is relatively small (like microdescriptors, descriptors, etc), we look them up by ID as needed, and add the whole thing onto the output buffer at once. If the spooled reseource is big (like networkstatus documents), we reference-count it, and add it a few K at a time.

Enumeration Type Documentation

dir_spool_source_t

enum dir_spool_source_t

Ways to convert a spoolable_resource_t to a bunch of bytes.

Function Documentation

authdir_wants_to_reject_router()

int authdir_wants_to_reject_router	(	routerinfo_t *	ri,
		const char **	msg,
		int	complain,
		int *	valid_out
	)

Check whether we, as a directory server, want to accept ri. If so, set its is_valid,running fields and return 0. Otherwise, return -1.

If the router is rejected, set *msg to an explanation of why.

If complain then explain at log-level 'notice' why we refused a descriptor; else explain at log-level 'info'.

Here is the call graph for this function:

cached_dir_decref()

void cached_dir_decref

(

cached_dir_t *

d

)

Decrement the reference count on d, and free it if it no longer has any references.

Here is the caller graph for this function:

connection_dirserv_flushed_some()

int connection_dirserv_flushed_some

(

dir_connection_t *

conn

)

Called whenever we have flushed some directory data in state SERVER_WRITING, or whenever we want to fill the buffer with initial directory data (so that subsequent writes will occur, and trigger this function again.)

Return 0 on success, and -1 on failure.

dir_conn_clear_spool()

void dir_conn_clear_spool

(

dir_connection_t *

conn

)

Remove every element from conn's outgoing spool, and delete the spool.

directory_caches_dir_info()

int directory_caches_dir_info

(

const or_options_t *

options

)

Return 1 if we want to fetch and serve descriptors, networkstatuses, etc Else return 0. Check options->DirPort_set and directory_permits_begindir_requests() to see if we are willing to serve these directory documents to others via the DirPort and begindir-over-ORPort, respectively.

To check if we should fetch documents, use we_want_to_fetch_flavor and we_want_to_fetch_unknown_auth_certs instead of this function.

Here is the call graph for this function:

Here is the caller graph for this function:

directory_caches_unknown_auth_certs()

int directory_caches_unknown_auth_certs

(

const or_options_t *

options

)

Return true iff we want to serve certificates for authorities that we don't acknowledge as authorities ourself. Use we_want_to_fetch_unknown_auth_certs to check if we want to fetch and keep these certificates.

Here is the call graph for this function:

directory_fetches_dir_info_early()

int directory_fetches_dir_info_early

(

const or_options_t *

options

)

Return 1 if we should fetch new networkstatuses, descriptors, etc on the "mirror" schedule rather than the "client" schedule.

Here is the call graph for this function:

Here is the caller graph for this function:

directory_fetches_dir_info_later()

int directory_fetches_dir_info_later

(

const or_options_t *

options

)

Return 1 if we should fetch new networkstatuses, descriptors, etc on a very passive schedule – waiting long enough for ordinary clients to probably have the info we want. These would include bridge users, and maybe others in the future e.g. if a Tor client uses another Tor client as a directory guard.

directory_fetches_from_authorities()

int directory_fetches_from_authorities

(

const or_options_t *

options

)

Return 1 if we fetch our directory material directly from the authorities, rather than from a mirror.

Here is the call graph for this function:

Here is the caller graph for this function:

directory_permits_begindir_requests()

int directory_permits_begindir_requests

(

const or_options_t *

options

)

Return 1 if we want to allow remote clients to ask us directory requests via the "begin_dir" interface, which doesn't require having any separate port open.

Here is the call graph for this function:

directory_too_idle_to_fetch_descriptors()

int directory_too_idle_to_fetch_descriptors	(	const or_options_t *	options,
		time_t	now
	)

Return 1 if we have no need to fetch new descriptors. This generally happens when we're not a dir cache and we haven't built any circuits lately.

Here is the call graph for this function:

Here is the caller graph for this function:

dirserv_add_descriptor()

enum was_router_added_t dirserv_add_descriptor	(	routerinfo_t *	ri,
		const char **	msg,
		const char *	source
	)

Examine the parsed server descriptor in ri and maybe insert it into the list of server descriptors. Set *msg to a message that should be passed back to the origin of this descriptor, or NULL if there is no such message. Use source to produce better log messages.

If ri is not added to the list of server descriptors, free it. That means the caller must not access ri after this function returns, since it might have been freed.

Return the status of the operation.

This function is only called when fresh descriptors are posted, not when we re-load the cache.

dirserv_add_multiple_descriptors()

enum was_router_added_t dirserv_add_multiple_descriptors	(	const char *	desc,
		uint8_t	purpose,
		const char *	source,
		const char **	msg
	)

As for dirserv_add_descriptor(), but accepts multiple documents, and returns the most severe error that occurred for any one of them.

dirserv_add_own_fingerprint()

int dirserv_add_own_fingerprint

(

crypto_pk_t *

pk

)

Add the fingerprint for this OR to the global list of recognized identity key fingerprints.

Here is the call graph for this function:

dirserv_clear_measured_bw_cache()

void dirserv_clear_measured_bw_cache

(

void

)

Clear and free the measured bandwidth cache

dirserv_compute_performance_thresholds()

void dirserv_compute_performance_thresholds

(

digestmap_t *

omit_as_sybil

)

Look through the routerlist, the Mean Time Between Failure history, and the Weighted Fractional Uptime history, and use them to set thresholds for the Stable, Fast, and Guard flags. Update the fields stable_uptime, stable_mtbf, enough_mtbf_info, guard_wfu, guard_tk, fast_bandwidth, guard_bandwidth_including_exits, and guard_bandwidth_excluding_exits.

Also, set the is_exit flag of each router appropriately.

dirserv_count_measured_bws()

void dirserv_count_measured_bws

(

const smartlist_t *

routers

)

Look through the routerlist, and using the measured bandwidth cache count how many measured bandwidths we know. This is used to decide whether we ever trust advertised bandwidths for purposes of assigning flags.

dirserv_free_all()

void dirserv_free_all

(

void

)

Release all storage used by the directory server.

Here is the call graph for this function:

dirserv_free_fingerprint_list()

void dirserv_free_fingerprint_list

(

void

)

Clear the current fingerprint list.

Here is the call graph for this function:

Here is the caller graph for this function:

dirserv_get_consensus()

cached_dir_t* dirserv_get_consensus

(

const char *

flavor_name

)

Return the latest downloaded consensus networkstatus in encoded, signed, optionally compressed format, suitable for sending to clients.

Here is the caller graph for this function:

dirserv_get_flag_thresholds_line()

char* dirserv_get_flag_thresholds_line

(

void

)

Give a statement of our current performance thresholds for inclusion in a vote document.

dirserv_get_measured_bw_cache_size()

int dirserv_get_measured_bw_cache_size

(

void

)

Get the current size of the measured bandwidth cache

dirserv_get_routerdesc_spool()

int dirserv_get_routerdesc_spool	(	smartlist_t *	spool_out,
		const char *	key,
		dir_spool_source_t	source,
		int	conn_is_encrypted,
		const char **	msg_out
	)

As dirserv_get_routerdescs(), but instead of getting signed_descriptor_t pointers, adds copies of digests to fps_out, and doesn't use the /tor/server/ prefix. For a /d/ request, adds descriptor digests; for other requests, adds identity digests.

Here is the call graph for this function:

dirserv_get_routerdescs()

int dirserv_get_routerdescs	(	smartlist_t *	descs_out,
		const char *	key,
		const char **	msg
	)

Add a signed_descriptor_t to descs_out for each router matching key. The key should be either

• "/tor/server/authority" for our own routerinfo;
• "/tor/server/all" for all the routerinfos we have, concatenated;
• "/tor/server/fp/FP" where FP is a plus-separated sequence of hex identity digests; or
• "/tor/server/d/D" where D is a plus-separated sequence of server descriptor digests, in hex.

Return 0 if we found some matching descriptors, or -1 if we do not have any descriptors, no matching descriptors, or if we did not recognize the key (URL). If -1 is returned *msg will be set to an appropriate error message.

XXXX rename this function. It's only called from the controller. XXXX in fact, refactor this function, merging as much as possible.

Here is the call graph for this function:

dirserv_has_measured_bw()

int dirserv_has_measured_bw

(

const char *

node_id

)

Predicate wrapper for dirserv_query_measured_bw_cache()

Here is the call graph for this function:

dirserv_load_fingerprint_file()

int dirserv_load_fingerprint_file

(

void

)

Load the nickname->fingerprint mappings stored in the approved-routers file. The file format is line-based, with each non-blank holding one nickname, some space, and a fingerprint for that nickname. On success, replace the current fingerprint list with the new list and return 0. On failure, leave the current fingerprint list untouched, and return -1.

dirserv_orconn_tls_done()

void dirserv_orconn_tls_done	(	const tor_addr_t *	addr,
		uint16_t	or_port,
		const char *	digest_rcvd,
		const ed25519_public_key_t *	ed_id_rcvd
	)

Called when a TLS handshake has completed successfully with a router listening at address:or_port, and has yielded a certificate with digest digest_rcvd.

Inform the reachability checker that we could get to this relay.

Here is the call graph for this function:

dirserv_query_measured_bw_cache_kb()

int dirserv_query_measured_bw_cache_kb	(	const char *	node_id,
		long *	bw_kb_out,
		time_t *	as_of_out
	)

Query the cache by identity digest, return value indicates whether we found it. The bw_out and as_of_out pointers receive the cached bandwidth value and the time it was cached if not NULL.

Here is the caller graph for this function:

dirserv_read_guardfraction_file()

int dirserv_read_guardfraction_file	(	const char *	fname,
		smartlist_t *	vote_routerstatuses
	)

Read a guardfraction file at fname and load all its information to vote_routerstatuses.

dirserv_read_measured_bandwidths()

int dirserv_read_measured_bandwidths	(	const char *	from_file,
		smartlist_t *	routerstatuses
	)

Read the measured bandwidth file and apply it to the list of vote_routerstatus_t. Returns -1 on error, 0 otherwise.

Here is the call graph for this function:

dirserv_router_get_status()

uint32_t dirserv_router_get_status	(	const routerinfo_t *	router,
		const char **	msg,
		int	severity
	)

Check whether router has a nickname/identity key combination that we recognize from the fingerprint list, or an IP we automatically act on according to our configuration. Return the appropriate router status.

If the status is 'FP_REJECT' and msg is provided, set *msg to an explanation of why.

Here is the call graph for this function:

Here is the caller graph for this function:

dirserv_set_cached_consensus_networkstatus()

void dirserv_set_cached_consensus_networkstatus	(	const char *	networkstatus,
		const char *	flavor_name,
		const common_digests_t *	digests,
		const uint8_t *	sha3_as_signed,
		time_t	published
	)

Replace the v3 consensus networkstatus of type flavor_name that we're serving with networkstatus, published at published. No validation is performed.

dirserv_set_node_flags_from_authoritative_status()

void dirserv_set_node_flags_from_authoritative_status	(	node_t *	node,
		uint32_t	authstatus
	)

Update the relevant flags of node based on our opinion as a directory authority in authstatus, as returned by dirserv_router_get_status or equivalent.

dirserv_set_router_is_running()

void dirserv_set_router_is_running	(	routerinfo_t *	router,
		time_t	now
	)

Treat a router as alive if

• It's me, and I'm not hibernating. or - We've found it reachable recently.

Here is the call graph for this function:

Here is the caller graph for this function:

dirserv_should_launch_reachability_test()

int dirserv_should_launch_reachability_test	(	const routerinfo_t *	ri,
		const routerinfo_t *	ri_old
	)

Called when we, as an authority, receive a new router descriptor either as an upload or a download. Used to decide whether to relaunch reachability testing for the server.

Here is the call graph for this function:

dirserv_single_reachability_test()

void dirserv_single_reachability_test	(	time_t	now,
		routerinfo_t *	router
	)

Helper function for dirserv_test_reachability(). Start a TLS connection to router, and annotate it with when we started the test.

Here is the call graph for this function:

Here is the caller graph for this function:

dirserv_spool_remove_missing_and_guess_size()

void dirserv_spool_remove_missing_and_guess_size	(	dir_connection_t *	conn,
		time_t	cutoff,
		int	compression,
		size_t *	size_out,
		int *	n_expired_out
	)

Try to guess the number of bytes that will be needed to send the spooled objects for conn's outgoing spool. In the process, remove every element of the spool that refers to an absent object, or which was published earlier than cutoff. Set *size_out to the number of bytes, and *n_expired_out to the number of objects removed for being too old.

dirserv_spool_sort()

void dirserv_spool_sort

(

dir_connection_t *

conn

)

Sort all the entries in conn by digest.

Here is the call graph for this function:

dirserv_test_reachability()

void dirserv_test_reachability

(

time_t

now

)

Auth dir server only: load balance such that we only try a few connections per call.

The load balancing is such that if we get called once every ten seconds, we will cycle through all the tests in REACHABILITY_TEST_CYCLE_PERIOD seconds (a bit over 20 minutes).

Here is the call graph for this function:

dirserv_would_reject_router()

int dirserv_would_reject_router

(

const routerstatus_t *

rs

)

Return true if there is no point in downloading the router described by rs because this directory would reject it.

list_server_status_v1()

int list_server_status_v1	(	smartlist_t *	routers,
		char **	router_status_out,
		int	for_controller
	)

Based on the routerinfo_ts in routers, allocate the contents of a v1-style router-status line, and store it in *router_status_out. Return 0 on success, -1 on failure.

If for_controller is true, include the routers with very old descriptors.

This is deprecated: it's only used for controllers that want outputs in the old format.

Here is the call graph for this function:

new_cached_dir()

cached_dir_t* new_cached_dir	(	char *	s,
		time_t	published
	)

Allocate and return a new cached_dir_t containing the string s, published at published.

routerstatus_format_entry()

char* routerstatus_format_entry	(	const routerstatus_t *	rs,
		const char *	version,
		const char *	protocols,
		routerstatus_format_type_t	format,
		int	consensus_method,
		const vote_routerstatus_t *	vrs
	)

Helper: write the router-status information in rs into a newly allocated character buffer. Use the same format as in network-status documents. If version is non-NULL, add a "v" line for the platform.

consensus_method is the current consensus method when format is NS_V3_CONSENSUS or NS_V3_CONSENSUS_MICRODESC. It is ignored for other formats: pass ROUTERSTATUS_FORMAT_NO_CONSENSUS_METHOD.

Return 0 on success, -1 on failure.

The format argument has one of the following values: NS_V2 - Output an entry suitable for a V2 NS opinion document NS_V3_CONSENSUS - Output the first portion of a V3 NS consensus entry for consensus_method. NS_V3_CONSENSUS_MICRODESC - Output the first portion of a V3 microdesc consensus entry for consensus_method. NS_V3_VOTE - Output a complete V3 NS vote. If vrs is present, it contains additional information for the vote. NS_CONTROL_PORT - Output a NS document for the control port.

Here is the caller graph for this function:

spooled_resource_free_()

void spooled_resource_free_

(

spooled_resource_t *

spooled

)

Release all storage held by spooled.

Here is the call graph for this function:

spooled_resource_new_from_cache_entry()

spooled_resource_t* spooled_resource_new_from_cache_entry

(

consensus_cache_entry_t *

entry

)

Create a new spooled_resource_t to spool the contents of entry to the user. Return the spooled object on success, or NULL on failure (which is probably caused by a failure to map the body of the item from disk).

Adds a reference to entry's reference counter.

validate_recommended_package_line()

int validate_recommended_package_line

(

const char *

line

)

Return true iff line is a valid RecommendedPackages line.

Here is the caller graph for this function: