Crate tor_dirmgr

tor-dirmgr

Code to fetch, store, and update Tor directory information.

Overview

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

In its current design, Tor requires a set of up-to-date authenticated directory documents in order to build multi-hop anonymized circuits through the network.

This directory manager crate is responsible for figuring out which directory information we lack, downloading what we’re missing, and keeping a cache of it on disk.

Compile-time features

• mmap (default) – Use memory mapping to reduce the memory load for reading large directory objects from disk.

• routerdesc – (Incomplete) support for downloading and storing router descriptors.

• compression (default) – Build support for downloading compressed documents. Requires a C compiler.

• bridge-client: Provide APIs used to fetch and use bridge information.

• full – Enable all features above.

Non-additive features

• static – Try to link with a static copy of sqlite3.

Experimental and unstable features

Note that the APIs enabled by these features are NOT covered by semantic versioning¹ guarantees: we might break them or remove them between patch versions.

• experimental-api: Add additional non-stable APIs to our public interfaces.

• dirfilter: enable an experimental mechanism to modify incoming directory information before it is used.

• experimental: Enable all the above experimental features.

License: MIT OR Apache-2.0

---

1. Remember, semantic versioning is what makes various cargo features work reliably. To be explicit: if you want cargo update to only make safe changes, then you cannot enable these features. ↩

Re-exports

• pub use authority::Authority;
• pub use authority::AuthorityBuilder;
• pub use config::DirMgrConfig;
• pub use config::DirTolerance;
• pub use config::DirToleranceBuilder;
• pub use config::DownloadScheduleConfig;
• pub use config::DownloadScheduleConfigBuilder;
• pub use config::NetworkConfig;
• pub use config::NetworkConfigBuilder;

Modules

• authority
  Information about directory authorities
• bootstrap 🔒
  Functions to download or load directory objects, using the state machines in the states module.
• bridgedescbridge-client
  BridgeDescMgr - downloads and caches bridges’ router descriptors
• config
  Types for managing directory configuration.
• docid 🔒
  Declare a general purpose “document ID type” for tracking which documents we want and which we have.
• docmeta 🔒
  Types to describe information about other downloaded directory documents, without necessarily having the full document.
• err 🔒
  Declare an error type for the tor-dirmgr crate.
• event 🔒
  Code for notifying other modules about changes in the directory.
• filterdirfilter
  A filtering mechanism for directory objects.
• retry 🔒
  Configure timers for a timer for retrying a single failed fetch or object.
• shared_ref 🔒
  Utility module to safely refer to a mutable Arc.
• state 🔒
  Implementation for the primary directory state machine.
• storage 🔒
  Methods for storing and loading directory information from disk.

Structs

• DirBootstrapEvents
  A stream of DirBootstrapStatus events.
• DirBootstrapStatus
  Description of the directory manager’s current bootstrapping status.
• DirMgr
  A directory manager to download, fetch, and cache a Tor directory.
• DirMgrStore
  Storage manager used by DirMgr and BridgeDescMgr
• DocumentText
  A document returned by a directory manager.
• DownloadSchedule
  Configuration for how many times to retry a download, with what frequency.
• DownloadScheduleBuilder
  Builder for DownloadSchedule.
• FallbackDir
  A directory whose location ships with Tor (or arti), and which we can use for bootstrapping when we don’t know anything else about the network.
• FallbackDirBuilder
  Builder for FallbackDir.
• SharedMutArcexperimental-api
  A shareable mutable-ish optional reference to a an Arc.

Enums

• DirBlockage
  A reported diagnostic for what kind of trouble we’ve seen while trying to bootstrap a directory.
• DocId
  The identity of a single document, in enough detail to load it from storage.
• DocSource
  The possible origins of a document.
• Error
  An error originated by the directory manager code
• Readiness 🔒
  A degree of readiness for a given directory state object.
• Timeliness
  How “timely” must a network directory be?

Traits

• DirProvider
  Trait for DirMgr implementations

Functions

• default_consensus_cutoff 🔒
  Given a time now, and an amount of tolerated clock skew tolerance, return the age of the oldest consensus that we should request at that time.
• upgrade_weak_ref 🔒
  Try to upgrade a weak reference to a DirMgr, and give an error on failure.

Type Aliases

• Result
  A Result as returned by this crate.