Struct Guard

pub(crate) struct Guard {

    id: GuardId,
    orports: Vec<SocketAddr>,
    pt_targets: Vec<PtTarget>,
    added_at: SystemTime,
    added_by: Option<CrateId>,
    disabled: Option<Futureproof<GuardDisabled>>,
    confirmed_at: Option<SystemTime>,
    unlisted_since: Option<SystemTime>,
    dir_info_missing: bool,
    last_tried_to_connect_at: Option<Instant>,
    retry_at: Option<Instant>,
    retry_schedule: Option<RetryDelay>,
    reachable: Reachable,
    is_dir_cache: bool,
    dir_status: DirStatus,
    exploratory_circ_pending: bool,
    circ_history: CircHistory,
    suspicious_behavior_warned: bool,
    clock_skew: Option<SkewObservation>,
    sensitivity: DisplayRule,
    unknown_fields: HashMap<String, JsonValue>,
}

A single guard node, as held by the guard manager.

A Guard is a Tor relay that clients use for the first hop of their circuits. It doesn’t need to be a relay that’s currently on the network (that is, one that we could represent as a Relay): guards might be temporarily unlisted.

Some fields in guards are persistent; others are reset with every process.

Identity

Every guard has at least one RelayId. A guard may gain identities over time, as we learn more about it, but it should never lose or change its identities of a given type.

TODO

This structure uses Instant to represent non-persistent points in time, and SystemTime to represent points in time that need to be persistent. That’s possibly undesirable; maybe we should come up with a better solution.

Fields

id: GuardId

The identity keys for this guard.

orports: Vec<SocketAddr>

The most recently seen addresses for this guard. If pt_targets is empty, these are the addresses we use for making OR connections to this guard directly. If pt_targets is nonempty, these are addresses at which the server is “located” (q.v. HasAddrs), but not ways to connect to it.

pt_targets: Vec<PtTarget>

Any PtTarget instances that we know about for connecting to this guard over a pluggable transport.

If this is empty, then this guard only supports direct connections, at the locations in orports.

(Currently, this is always empty, or a singleton. If we find more than one, we only look at the first. It is a vector only for forward compatibility.)

added_at: SystemTime

When, approximately, did we first add this guard to our sample?

added_by: Option<CrateId>

What version of this crate added this guard to our sample?

disabled: Option<Futureproof<GuardDisabled>>

If present, this guard is permanently disabled, and this object tells us why.

confirmed_at: Option<SystemTime>

When, approximately, did we first successfully use this guard?

(We call a guard “confirmed” if we have successfully used it at least once.)

unlisted_since: Option<SystemTime>

If this guard is not listed in the current-consensus, this is the valid_after date of the oldest consensus in which it was not listed.

A guard counts as “unlisted” if it is absent, unusable, or doesn’t have the Guard flag.

dir_info_missing: bool

True if this guard is listed in the latest consensus, but we don’t have a microdescriptor for it.

last_tried_to_connect_at: Option<Instant>

When did we last give out this guard in response to a request?

retry_at: Option<Instant>

If this guard is currently Unreachable, when should we next retry it?

(Retrying a guard involves clearing this field, and setting reachable)

retry_schedule: Option<RetryDelay>

Schedule use to determine when we can next attempt to connect to this guard.

reachable: Reachable

Current reachability status for this guard.

is_dir_cache: bool

If true, then the last time we saw a relay entry for this guard, it seemed like a valid directory cache.

dir_status: DirStatus

Status for this guard, when used as a directory cache.

(This is separate from Reachable and retry_schedule, since being usable for circuit construction does not necessarily mean that the guard will have good, timely cache information. If it were not separate, then circuit success would clear directory failures.)

exploratory_circ_pending: bool

If true, we have given this guard out for an exploratory circuit, and that exploratory circuit is still pending.

A circuit is “exploratory” if we launched it on a non-primary guard.

circ_history: CircHistory

A count of all the circuit statuses we’ve seen on this guard.

Used to implement a lightweight version of path-bias detection.

suspicious_behavior_warned: bool

True if we have warned about this guard behaving suspiciously.

clock_skew: Option<SkewObservation>

Latest clock skew (if any) we have observed from this guard.

sensitivity: DisplayRule

How should we display information about this guard?

unknown_fields: HashMap<String, JsonValue>

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

Implementations

impl Guard

pub(crate) fn from_candidate( candidate: Candidate, now: SystemTime, params: &GuardParams, ) -> Self

Create a new unused Guard from a Candidate.

fn from_chan_target<T>(relay: &T, now: SystemTime, params: &GuardParams) -> Self

where T: ChanTarget,

Create a new unused Guard from a ChanTarget.

This function doesn’t check whether the provided relay is a suitable guard node or not: that’s up to the caller to decide.

fn new( id: GuardId, orports: Vec<SocketAddr>, pt_target: Option<PtTarget>, added_at: SystemTime, ) -> Self

Return a new, manually constructed Guard.

pub(crate) fn guard_id(&self) -> &GuardId

Return the identity of this Guard.

pub(crate) fn reachable(&self) -> Reachable

Return the reachability status for this guard.

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

Return the next time at which this guard will be retriable for a given usage.

(Return None if we think this guard might be reachable right now.)

pub(crate) fn usable(&self) -> bool

Return true if this guard is usable and working according to our latest configuration and directory information, and hasn’t been turned off for some other reason.

pub(crate) fn ready_for_usage(&self, usage: &GuardUsage, now: Instant) -> bool

Return true if this guard is ready (with respect to any timeouts) for the given usage at now.

pub(crate) fn copy_ephemeral_status_into_newly_loaded_state( self, other: Guard, ) -> Guard

Copy all non-persistent status from other to self.

We do this when we were not the owner of our persistent state, and we have just reloaded it (as self), but we have some ephemeral knowledge about this guard (as other).

You should not invent new uses for this function; instead we should come up with alternatives.

Panics

Panics if the identities in self are not exactly the same as the identities in other.

fn set_reachable(&mut self, r: Reachable)

Change the reachability status for this guard.

pub(crate) fn exploratory_circ_pending(&self) -> bool

Return true if at least one exploratory circuit is pending to this guard.

A circuit is “exploratory” if launched on a non-primary guard.

TODO

The “exploratory” definition doesn’t quite match up with the behavior in the spec, but it is what Tor does.

pub(crate) fn note_exploratory_circ(&mut self, pending: bool)

Note that an exploratory circuit is pending (if pending is true), or not pending (if pending is false.

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

Possibly mark this guard as retriable, if it has been down for long enough.

Specifically, if the guard is to be Unreachable, and our last attempt to connect to it is far enough in the past from now, we change its status to Unknown.

pub(crate) fn mark_retriable(&mut self)

If this guard is marked Unreachable, clear its unreachability status and mark it as Retriable.

fn obeys_restrictions(&self, restrictions: &[GuardRestriction]) -> bool

Return true if this guard obeys all of the given restrictions.

fn obeys_restriction(&self, r: &GuardRestriction) -> bool

Return true if this guard obeys a single restriction.

pub(crate) fn conforms_to_usage(&self, usage: &GuardUsage) -> bool

Return true if this guard is suitable to use for the provided usage.

pub(crate) fn listed_in<U: Universe>(&self, universe: &U) -> Option<bool>

Check whether this guard is listed in the provided sample::Universe.

Returns Some(true) if it is definitely listed, and Some(false) if it is definitely not listed. A None return indicates that we need to download more directory information about this guard before we can be certain whether this guard is listed or not.

pub(crate) fn update_from_universe<U: Universe>(&mut self, universe: &U)

Change this guard’s status based on a newly received or newly updated sample::Universe.

A guard may become “listed” or “unlisted”: a listed guard is one that appears in the consensus with the Guard flag.

A guard may acquire additional identities if we learned them from the guard, either directly or via an authenticated directory document.

Additionally, a guard’s orports or pt_targets may change, if the universe lists a new address for the relay.

fn mark_listed(&mut self)

Mark this guard as currently listed in the directory.

fn mark_unlisted(&mut self, now: SystemTime)

Mark this guard as having been unlisted since now, if it is not already so marked.

pub(crate) fn is_expired(&self, params: &GuardParams, now: SystemTime) -> bool

Return true if we should remove this guard from the current guard sample.

Guards may be ready for removal because they have been confirmed too long ago, if they have been sampled too long ago (if they are not confirmed), or if they have been unlisted for too long.

pub(crate) fn record_failure(&mut self, now: Instant, is_primary: bool)

Record that a failure has happened for this guard.

If is_primary is true, this is a primary guard (q.v.).

pub(crate) fn record_attempt(&mut self, connect_attempt: Instant)

Note that we have launch an attempted use of this guard.

We use this time to decide when to retry failing guards, and to see if the guard has been “pending” for a long time.

pub(crate) fn exploratory_attempt_after(&self, when: Instant) -> bool

Return true if this guard has an exploratory circuit pending and if the most recent attempt to connect to it is after when.

See Self::exploratory_circ_pending.

pub(crate) fn record_success( &mut self, now: SystemTime, params: &GuardParams, ) -> NewlyConfirmed

Note that a guard has been used successfully.

Updates that guard’s status to reachable, clears any failing status information for it, and decides whether the guard is newly confirmed.

If the guard is newly confirmed, the caller must add it to the list of confirmed guards.

pub(crate) fn record_external_success(&mut self, how: ExternalActivity)

Record that an external operation has succeeded on this guard.

pub(crate) fn record_external_failure( &mut self, how: ExternalActivity, now: Instant, )

Record that an external operation has failed on this guard.

pub(crate) fn record_indeterminate_result(&mut self)

Note that a circuit through this guard died in a way that we couldn’t necessarily attribute to the guard.

pub(crate) fn get_external_rep(&self, selection: GuardSetSelector) -> FirstHop

Return a FirstHop object to represent this guard.

pub(crate) fn note_skew(&mut self, observation: SkewObservation)

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

pub(crate) fn skew(&self) -> Option<&SkewObservation>

Return the most recent clock skew observation for this guard, if we have made one.

Trait Implementations

impl ChanTarget for Guard

fn display_chan_target(&self) -> DisplayChanTarget<'_, Self>

where Self: Sized,

Return a reference to this object suitable for formatting its ChanTarget-specific members.

impl Clone for Guard

fn clone(&self) -> Guard

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Guard

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Guard

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Guard

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

Formats the value using the given formatter.

impl HasAddrs for Guard

fn addrs(&self) -> &[SocketAddr]

Return the addresses listed for this server.

impl HasChanMethod for Guard

fn chan_method(&self) -> ChannelMethod

Return the known ways to contact this

impl HasRelayIds for Guard

fn identity(&self, key_type: RelayIdType) -> Option<RelayIdRef<'_>>

Return the identity of this relay whose type is key_type, or None if the relay has no such identity.

fn identities(&self) -> RelayIdIter<'_, Self>

Return an iterator over all of the identities held by this object.

fn ed_identity(&self) -> Option<&Ed25519Identity>

Return the ed25519 identity for this relay if it has one.

fn rsa_identity(&self) -> Option<&RsaIdentity>

Return the RSA identity for this relay if it has one.

fn has_identity(&self, id: RelayIdRef<'_>) -> bool

Check whether the provided Id is a known identity of this relay.

fn has_any_identity(&self) -> bool

Return true if this object has any known identity.

fn same_relay_ids<T>(&self, other: &T) -> bool

where T: HasRelayIds + ?Sized,

Return true if this object has exactly the same relay IDs as other.

fn has_all_relay_ids_from<T>(&self, other: &T) -> bool

where T: HasRelayIds + ?Sized,

Return true if this object has every relay ID that other does.

fn has_any_relay_id_from<T>(&self, other: &T) -> bool

where T: HasRelayIds + ?Sized,

Return true if this object has any relay ID that other has.

fn cmp_by_relay_ids<T>(&self, other: &T) -> Ordering

where T: HasRelayIds + ?Sized,

Compare this object to another HasRelayIds.

fn display_relay_ids(&self) -> DisplayRelayIds<'_, Self>

Return a reference to this object suitable for formatting its HasRelayIds members.

impl Serialize for Guard

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.