Skip to main content

Crate tor_guardmgr

Crate tor_guardmgr 

Source
Expand description

§tor-guardmgr

Guard node selection for Tor network clients.

§Overview

This crate is part of Arti, a project to implement Tor in Rust.

“Guard nodes” are mechanism that Tor clients uses to limit the impact of hostile relays. Approximately: each client chooses a small set of relays to use as its “guards”. Later, when the client picks its paths through network, rather than choosing a different first hop randomly for every path, it chooses the best “guard” as the first hop.

This crate provides GuardMgr, an object that manages a set of guard nodes, and helps the tor-circmgr crate know when to use them.

Guard nodes are persistent across multiple process invocations.

More Arti users won’t need to use this crate directly.

§Motivation

What’s the point? By restricting their first hops to a small set, clients increase their odds against traffic-correlation attacks. Since we assume that an adversary who controls both ends of a circuit can correlate its traffic, choosing many circuits with random entry points will eventually cause a client to eventually pick an attacker-controlled circuit, with probability approaching 1 over time. If entry nodes are restricted to a small set, however, then the client has a chance of never picking an attacker-controlled circuit.

(The actual argument is a little more complicated here, and it relies on the assumption that, since the attacker knows statistics, exposing any of your traffic is nearly as bad as exposing all of your traffic.)

§Complications

The real algorithm for selecting and using guards can get more complicated because of a variety of factors.

  • In reality, we can’t just “pick a few guards at random” and use them forever: relays can appear and disappear, relays can go offline and come back online, and so on. What’s more, keeping guards for too long can make targeted attacks against those guards more attractive.

  • Further, we may have particular restrictions on where we can connect. (For example, we might be restricted to ports 80 and 443, but only when we’re on a commuter train’s wifi network.)

  • We need to resist attacks from local networks that block all but a small set of guard relays, to force us to choose those.

  • We need to give good, reliable performance while using the guards that we prefer.

These needs complicate our API somewhat. Instead of simply asking the GuardMgr for a guard, the circuit-management code needs to be able to tell the GuardMgr that a given guard has failed (or succeeded), and that it needs a different guard in the future (or not).

Further, the GuardMgr code needs to be able to hand out provisional guards, in effect saying “You can try building a circuit with this guard, but please don’t actually use that circuit unless I tell you it’s safe.”

For details on the exact algorithm, see guard-spec.txt (link below) and comments and internal documentation in this crate.

§Limitations

  • Our circuit blocking algorithm is simplified from the one that Tor uses. See comments in GuardSet::circ_usability_status for more information. See also proposal 337.

§References

Guard nodes were first proposed (as “helper nodes”) in “Defending Anonymous Communications Against Passive Logging Attacks” by Matthew Wright, Micah Adler, Brian N. Levine, and Clay Shields in the Proceedings of the 2003 IEEE Symposium on Security and Privacy. (See https://www.freehaven.net/anonbib/#wright03)

Tor’s current guard selection algorithm is described in Tor’s Guard Specification document.

§Compile-time features

  • bridge-client: Build with support for bridges. (Bridges are relays that are not listed in the Tor network directory, which can be used for anti-censorship purposes.)

  • pt-client: Build with support for guards that can be contacted using pluggable transports. (A pluggable transport is an alternative mechanism for contacting a Tor relay, for censorship avoidance.)

  • full: Enable all features above.

License: MIT OR Apache-2.0

Re-exports§

pub use config::testing::TestConfig;
pub use config::GuardMgrConfig;
pub use err::GuardMgrConfigError;
pub use err::GuardMgrError;
pub use err::PickGuardError;
pub use events::ClockSkewEvents;
pub use filter::GuardFilter;
pub use ids::FirstHopId;
pub use pending::GuardMonitor;
pub use pending::GuardStatus;
pub use pending::GuardUsable;
pub use skew::SkewEstimate;
pub use vanguards::VanguardMgrError;
pub(crate) use pending::PendingRequest; 🔒
pub(crate) use pending::RequestId; 🔒
pub(crate) use sample::GuardSet; 🔒
pub(crate) use sample::Universe; 🔒
pub(crate) use sample::UniverseRef; 🔒
pub(crate) use crate::ids::FirstHopIdInner; 🔒
pub(crate) use crate::ids::GuardId; 🔒
pub(crate) use derive_deftly::Deftly; 🔒
pub(crate) use futures::channel::mpsc; 🔒
pub(crate) use itertools::Either; 🔒
pub(crate) use Deserialize; 🔒
pub(crate) use Deserialize; 🔒
pub(crate) use Serialize; 🔒
pub(crate) use Serialize; 🔒
pub(crate) use std::collections::HashMap; 🔒
pub(crate) use std::net::SocketAddr; 🔒
pub(crate) use Arc; 🔒
pub(crate) use Mutex; 🔒
pub(crate) use Weak; 🔒
pub(crate) use tor_error::internal; 🔒
pub(crate) use OwnedChanTarget; 🔒
pub(crate) use OwnedCircTarget; 🔒
pub(crate) use RelayId; 🔒
pub(crate) use RelayIdSet; 🔒
pub(crate) use tor_netdir::NetDirProvider; 🔒
pub(crate) use tor_proto::ClockSkew; 🔒
pub(crate) use tor_rtcompat::SpawnExt; 🔒
pub(crate) use tor_units::BoundedInt32; 🔒
pub(crate) use debug; 🔒
pub(crate) use info; 🔒
pub(crate) use instrument; 🔒
pub(crate) use instrument; 🔒
pub(crate) use trace; 🔒
pub(crate) use warn; 🔒
pub(crate) use Duration; 🔒
pub(crate) use Instant; 🔒
pub(crate) use SystemTime; 🔒
pub(crate) use ExplicitOrAuto; 🔒
pub(crate) use impl_standard_builder; 🔒
pub(crate) use ReconfigureError; 🔒
pub(crate) use impl_not_auto_value; 🔒
pub(crate) use define_list_builder_accessors; 🔒
pub(crate) use define_list_builder_helper; 🔒
pub(crate) use NetDir; 🔒
pub(crate) use Relay; 🔒
pub(crate) use params::NetParameters; 🔒
pub(crate) use DynStorageHandle; 🔒
pub(crate) use StateMgr; 🔒
pub(crate) use tor_rtcompat::Runtime; 🔒
pub(crate) use tor_config::derive::prelude::*; 🔒

Modules§

bridge
Code to configure and manage a set of bridge relays.
config 🔒
Configuration elements for the guard manager
daemon 🔒
Implement background tasks used by guard managers.
dirstatus 🔒
Types and code to track the readiness status of a directory cache.
err 🔒
Declare error types for the tor-guardmgr crate.
events 🔒
Code to remotely notify other crates about changes in the status of the GuardMgr.
fallback
Data structures that wrap FallbackDir and related primitives into data structures required for bootstrapping Tor properly.
filter 🔒
Implement GuardFilter and related types.
guard 🔒
Code to represent its single guard node and track its status.
ids 🔒
Identifier objects used to specify guards and/or fallbacks.
pending 🔒
Help the guard manager (and other crates) deal with “pending information”.
sample 🔒
Logic for manipulating a sampled set of guards, along with various orderings on that sample.
skew 🔒
Code for creating and manipulating observations about clock skew.
util 🔒
Helper functionality used by the rest of tor-guardmgr.
vanguards
Experimental support for vanguards.

Structs§

FirstHop
Representation of a guard or fallback, as returned by GuardMgr::select_guard().
GuardMgr
A “guard manager” that selects and remembers a persistent set of guard nodes.
GuardMgrInner 🔒
Helper type that holds the data used by a GuardMgr.
GuardParams 🔒
A set of parameters, derived from the consensus document, controlling the behavior of a guard manager.
GuardRestrictionListBuilder
Wrapper struct to help derive_builder find the right types and methods
GuardSetSelectorIter 🔒
An iterator over the variants of GuardSetSelector
GuardSets 🔒
Persistent state for a guard manager, as serialized to disk.
GuardUsage
A set of parameters describing how a single guard should be selected.
GuardUsageBuilder
Builder for GuardUsage.
VanguardConfig
Vanguards configuration.
VanguardConfigBuilder
A builder to create an instance of VanguardConfig.

Enums§

ExtendedStatus 🔒
A possible outcome of trying to extend a guard sample.
ExternalActivity
An activity that can succeed or fail, and whose success or failure can be attributed to a guard.
FirstHopInner 🔒
The enumeration inside a FirstHop that holds information about how to connect to (and possibly through) a guard or fallback.
GuardRestriction
A restriction that applies to a single request for a guard.
GuardSetSelector 🔒
A selector that tells us which GuardSet of several is currently in use.
GuardUsageKind
The purpose for which we plan to use a guard.
RetireCircuits
A description of which circuits to retire because of a configuration change.
UniverseType 🔒
Describes the Universe that a guard sample should take its guards from.
VanguardMode
The kind of vanguards to use.

Constants§

STORAGE_KEY 🔒
The key (filename) we use for storing our persistent guard state in the StateMgr.

Type Aliases§

GuardRestrictionList
List of socket restrictions, as configured