Struct GuardSet

pub(crate) struct GuardSet {
    guards: ByRelayIds<Guard>,
    sample: Vec<GuardId>,
    confirmed: Vec<GuardId>,
    primary: Vec<GuardId>,
    active_filter: GuardFilter,
    filter_is_restrictive: bool,
    primary_guards_invalidated: bool,
    unknown_fields: HashMap<String, JsonValue>,
}

A set of sampled guards, along with various orderings on subsets of the sample.

Every guard in a GuardSet is considered to be “sampled”: that is, selected from a network directory at some point in the past. The guards in the sample are ordered (roughly) by the time at which they were added. This list is persistent.

Any guard which we’ve successfully used at least once is considered “confirmed”. Confirmed guards are ordered (roughly) by the time at which we first used them. This list is persistent.

The guards which we would prefer to use are called “primary”. Primary guards are ordered from most- to least-preferred. This list is not persistent, and is re-derived as needed.

These lists together define a “preference order”. All primary guards come first in preference order. Then come the non-primary confirmed guards, in their confirmed order. Finally come the non-primary, non-confirmed guards, in their sampled order.

Fields

guards: ByRelayIds<Guard>

Map from identities to guards, for every guard in this sample.

The key for each entry is a set of identities which we have good (trustworthy-enough) reason to link together.

When we connect to a guard we require it to demonstrate that it has all of these identities; and we do pinning, so that we note down the other identities we discover it has, with the intent that we will require them in future.

Sources of linkage:

• If we connect to a relay and it proves a set of identities, that necessarily will include at least the ones we have already. We can add any other identities we have discovered. Justification: the owners of the old ids have made a statement (via the connection protocols) that these other ids are also theirs, and should be required in future.

• If we obtain a (full) descriptor for a relay, and check the self-signatures by all the identities we have already, we can add any other identities listed in the descriptor. Justification: the owners of the old ids have made an explicit statement that these other ids are also theirs, and should be required in future.

• For a relay in the netdir, if the netdir links some ids together, we can combine the entries. Justification: the netdir is authoritative for netdir-based relays.

• For a configured bridge, if our configuration links some identities, we must insist on all those identities. So we combine them.

Handling of conflicting entries:

ByRelayIds will implicitly delete conflicting entries, simply forgetting about them. This is OK for netdir relays, since we do not expect this to occur in practice.

For bridges, conflicts may in fact occur, since bridge lines are not issued by a single authority, and should be afforded limited trust.

• If the configuration contains bridge lines that mutually conflict, affected bridge lines should be disregarded, or the configuration rejected.

• If the configuration contains information which is inconsistent with our past experience, we should discard the past experiences which aren’t reconcilable with the configuration.

• We may discover a linkage which demonstrates that the configuration is wrong: for example, two bridge lines for identities X and Y, but in fact there is only one bridge with both identities. In this situation it is OK to effectively disregard some the configuration entries which are at variance with reality, maybe with a warning, but keeping at least one of every usable id set (actually existing bridge) would be good.

sample: Vec<GuardId>

Identities of all the guards in the sample, in sample order.

This contains the same elements as the keys of guards

confirmed: Vec<GuardId>

Identities of all the confirmed guards in the sample, in confirmed order.

This contains a subset of the values in sample.

primary: Vec<GuardId>

Identities of all the primary guards, in preference order (from best to worst).

This contains a subset of the values in sample.

active_filter: GuardFilter

Currently active filter that restricts which guards we can use.

Note that all of the lists above (with the exception of primary) can hold guards that the filter doesn’t permit. This behavior is meant to give good security behavior in the presence of filters that change over time.

filter_is_restrictive: bool

If true, the active filter is “very restrictive”.

primary_guards_invalidated: bool

Set to ‘true’ whenever something changes that would force us to call ‘select_primary_guards()’, and cleared whenever we call it.

unknown_fields: HashMap<String, JsonValue>

Fields from the state file that was used to make this GuardSet that this version of Arti doesn’t understand.

Implementations

impl GuardSet

fn inner_lengths(&self) -> (usize, usize, usize, usize)

Return the lengths of the different elements of the guard set.

Used to report bugs or corruption in consistency.

fn fix_consistency(&mut self)

Remove all elements from this GuardSet that ought to be referenced by another element, but which are not.

This method only removes corrupted elements and updates IDs in the ID list (possibly adding new IDs); it doesn’t add guards or other data. It won’t do anything if the GuardSet is well-formed.

fn assert_consistency(&mut self)

Assert that this GuardSet is internally consistent.

Incidentally fixes the consistency of this GuardSet if needed.

pub(crate) fn get(&self, id: &GuardId) -> Option<&Guard>

Return the guard that has every identity in id, if any.

pub(crate) fn set_filter(&mut self, filter: GuardFilter, restrictive: bool)

Replace the filter used by this GuardSet with filter.

Removes all primary guards that the filter doesn’t permit.

If restrictive is true, this filter is treated as “extremely restrictive”.

pub(crate) fn filter(&self) -> &GuardFilter

Return the current filter for this GuardSet.

pub(crate) fn copy_ephemeral_status_into_newly_loaded_state( &mut self, other: GuardSet, )

Copy non-persistent status from every guard shared with other.

This is used as part of our reload process when we don’t own our state files, and we’re reloading in order to find out what the other Arti instance thinks the guards are. At that point, self is the set of guards that we just loaded from state, and other is our old guards, which we are using only for their status information.

fn get_state(&self) -> GuardSample<'_>

Return a serializable state object that can be stored to disk to capture the current state of this GuardSet.

fn from_state(state: GuardSample<'_>) -> Self

Reconstruct a guard state from its serialized representation.

pub(crate) fn contains(&self, id: &GuardId) -> Result<bool, &GuardId>

Return Ok(true) if id is definitely a member of this set, and Ok(false) if it is definitely not a member.

If we cannot tell, it’s because there is a guard in this sample that has a subset of the IDs in id. In that case, we return Err(guard_ident), where guard_ident is the identity of that guard.

pub(crate) fn extend_sample_as_needed<U: Universe>( &mut self, now: SystemTime, params: &GuardParams, dir: &U, ) -> ExtendedStatus

If there are not enough filter-permitted usable guards in this sample (according to the current active filter), then add more, up to the limits allowed by the parameters.

This is the only function that adds new guards to the sample.

Guards always start out un-confirmed.

Return true if any guards were added.

fn extend_sample_inner<U: Universe>( &mut self, now: SystemTime, params: &GuardParams, dir: &U, ) -> bool

Implementation helper for extend_sample_as_needed.

Complications

For spec conformance, we only consider our filter when selecting new guards if the filter is “very restrictive”. That makes it possible that this function will add fewer filter-permitted guards than we had wanted. Because of that, this is a separate function, and extend_sample_as_needed runs it in a loop until it returns false.

fn add_guard(&mut self, relay: Candidate, now: SystemTime, params: &GuardParams)

Add relay as a new guard.

Does nothing if it is already a guard.

pub(crate) fn n_primary_without_id_info_in<U: Universe>( &mut self, universe: &U, ) -> usize

Return the number of our primary guards that are missing directory information in universe.

Note that “missing directory information” is not the same as “absent”: in this case, we are counting the primary guards where we cannot tell whether they appear in the universe or not because we have not yet downloaded their descriptors.

pub(crate) fn update_status_from_dir<U: Universe>(&mut self, dir: &U)

Update the status of every guard in this sample from a given source.

pub(crate) fn select_primary_guards(&mut self, params: &GuardParams)

Re-build the list of primary guards.

Primary guards are chosen according to preference order over all the guards in the set, restricted by the current filter.

TODO: Enumerate all the times when this function needs to be called.

TODO: Make sure this is called enough.

pub(crate) fn expire_old_guards( &mut self, params: &GuardParams, now: SystemTime, )

Remove all guards which should expire now, according to the settings in params.

fn reachable_sample_ids(&self) -> impl Iterator<Item = &GuardId>

Return an iterator over the Id for every Guard in the sample that is not known to be Unreachable.

fn preference_order_ids(&self) -> impl Iterator<Item = (ListKind, &GuardId)>

Return an iterator that yields an element for every guard in this set, in preference order.

Each element contains a ListKind that describes which list the guard was in, and a &GuardId that identifies the guard.

Note that this function will return guards that are not accepted by the current active filter: the caller must apply that filter if appropriate.

fn preference_order(&self) -> impl Iterator<Item = (ListKind, &Guard)> + '_

Like preference_order_ids, but yields &Guard instead of &GuardId.

fn guard_is_primary(&self, guard_id: &GuardId) -> bool

Return true if guard_id is an identity subset for any primary guard in this set.

pub(crate) fn consider_all_retries(&mut self, now: Instant)

For every guard that has been marked as Unreachable for too long, mark it as Unknown.

pub(crate) fn next_retry(&self, usage: &GuardUsage) -> Option<Instant>

Return the earliest time at which any guard will be retriable.

pub(crate) fn mark_primary_guards_retriable(&mut self)

Mark every Unreachable primary guard as Unknown.

pub(crate) fn all_primary_guards_are_unreachable(&mut self) -> bool

Return true if all of our primary guards are currently marked unreachable.

pub(crate) fn mark_all_guards_retriable(&mut self)

Mark every Unreachable guard as Unknown.

pub(crate) fn record_attempt(&mut self, guard_id: &GuardId, now: Instant)

Record that an attempt has begun to use the guard with guard_id.

pub(crate) fn record_success( &mut self, guard_id: &GuardId, params: &GuardParams, how: Option<ExternalActivity>, now: SystemTime, )

Record that an attempt to use the guard with guard_id has just succeeded.

If how is provided, it’s an operation from outside the crate that the guard succeeded at doing.

pub(crate) fn record_failure( &mut self, guard_id: &GuardId, how: Option<ExternalActivity>, now: Instant, )

Record that an attempt to use the guard with guard_id has just failed.

pub(crate) fn record_attempt_abandoned(&mut self, guard_id: &GuardId)

Record that an attempt to use the guard with guard_id has just been abandoned, without learning whether it succeeded or failed.

pub(crate) fn record_indeterminate_result(&mut self, guard_id: &GuardId)

Record that an attempt to use the guard with guard_id has just failed in a way that we could not definitively attribute to the guard.

pub(crate) fn record_skew( &mut self, guard_id: &GuardId, observation: SkewObservation, )

Record that a given guard has told us about clock skew.

pub(crate) fn skew_observations(&self) -> impl Iterator<Item = &SkewObservation>

Return an iterator over all stored clock skew observations.

pub(crate) fn circ_usability_status( &self, guard_id: &GuardId, usage: &GuardUsage, params: &GuardParams, now: Instant, ) -> Option<bool>

Return whether the circuit manager can be allowed to use a circuit with the guard_id.

Return Some(bool) if the circuit is usable, and None if we cannot yet be sure.

pub(crate) fn pick_guard( &self, sample_id: &GuardSetSelector, usage: &GuardUsage, params: &GuardParams, now: Instant, ) -> Result<(ListKind, FirstHop), PickGuardError>

Try to select a guard for a given usage.

On success, returns the kind of guard that we got, and its filtered representation in a form suitable for use as a first hop.

Label the returned guard as having come from sample_id.

fn pick_guard_id( &self, usage: &GuardUsage, params: &GuardParams, now: Instant, ) -> Result<(ListKind, GuardId), PickGuardError>

Try to select a guard for a given usage.

On success, returns the kind of guard that we got, and its identity.

pub(crate) fn descriptors_to_request( &self, now: Instant, params: &GuardParams, ) -> Vec<&Guard>

Available on crate feature bridge-client only.

Return the guards whose bridge descriptors we should request, given our current configuration and status.

(The output of this function is not reasonable unless this is a Bridge sample.)

Trait Implementations

impl Clone for GuardSet

fn clone(&self) -> GuardSet

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for GuardSet

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for GuardSet

fn default() -> GuardSet

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for GuardSet

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<'a> From<&'a GuardSet> for GuardSample<'a>

fn from(guards: &'a GuardSet) -> Self

Converts to this type from the input type.

impl<'a> From<GuardSample<'a>> for GuardSet

fn from(sample: GuardSample<'_>) -> Self

Converts to this type from the input type.

impl Serialize for GuardSet

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.