Crate tor_linkspec

tor-linkspec

Descriptions of Tor relays, as used to connect to them.

Overview

The tor-linkspec crate provides traits and data structures that describe how to connect to Tor relays.

When describing the location of a Tor relay on the network, the Tor protocol uses a set of “link specifiers”, each of which corresponds to a single aspect of the relay’s location or identity—such as its IP address and port, its Ed25519 identity key, its (legacy) RSA identity fingerprint, or so on. This crate’s LinkSpec type encodes these structures.

When a client is building a circuit through the Tor network, it needs to know certain information about the relays in that circuit. This crate’s ChanTarget and CircTarget traits represent objects that describe a relay on the network that a client can use as the first hop, or as any hop, in a circuit.

This crate is part of Arti, a project to implement Tor in Rust. Several other crates in Arti depend on it. You will probably not need this crate yourself unless you are interacting with the Tor protocol at a fairly low level.

tor-linkspec is a separate crate so that it can be used by other crates that expose link specifiers and by crates that consume them.

Future work

TODO: Possibly we should rename this crate. “Linkspec” is a pretty esoteric term in the Tor protocols.

TODO: Possibly the link specifiers and the *Target traits belong in different crates.

Compile-time features

• pt-client – Build with enhanced data types to support pluggable transports.

• full – Build with all the features above.

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 – Build with all experimental features above. (Currently, there are no experimental features in this crate, but there may be in the future.)

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. ↩

Modules

• decodedecode
  Analyze a list of link specifiers as a OwnedChanTarget.
• verbatimverbatim
  Wrappers for using a CircTarget with a verbatim list of link specifiers.

Structs

• BridgeAddr
  An address of a bridge, for use in configuration.
• ByRelayIds
  A set of objects that can be accessed by relay identity.
• EncodedLinkSpec
  An unparsed piece of information about a relay and how to connect to it.
• LinkSpecType
  A numeric identifier for the type of a LinkSpec.
• OwnedChanTarget
  OwnedChanTarget is a summary of a ChanTarget that owns all of its members.
• OwnedChanTargetBuilder
  Builder for OwnedChanTarget.
• OwnedCircTarget
  OwnedCircTarget is a summary of a CircTarget that owns all its members.
• OwnedCircTargetBuilder
  Builder for OwnedCircTarget.
• PtTarget
  The set of information passed to the pluggable transport subsystem in order to establish a connection to a bridge relay.
• PtTargetSettings
  A set of options to be passed along to a pluggable transport along with a single target bridge relay.
• PtTransportName
  The name of a Pluggable Transport protocol.
• RelayIdSet
  A set of relay identities, backed by HashSet.
• RelayIdTypeIter
  An iterator over the variants of RelayIdType
• RelayIds
  RelayIds is an owned copy of the set of known identities of a relay.
• RelayIdsBuilder
  Builder for RelayIds.
• TransportId
  Identify a type of Transport.

Enums

• BridgeAddrError
  An error from parsing a BridgeAddr or PtTargetAddr.
• ByRelayIdsError
  An error returned from an operation on an n_key_set.
• ChannelMethod
  The way to approach a single relay in order to open a channel.
• LinkSpec
  A piece of information about a relay and how to connect to it.
• PtTargetAddr
  An address that an be passed to a pluggable transport to tell it where to connect (typically, to a bridge).
• PtTargetInvalidSetting
  Invalid PT parameter setting
• RelayId
  A single relay identity.
• RelayIdError
  An error returned while trying to parse a RelayId.
• RelayIdRef
  A reference to a single relay identity.
• RelayIdType
  The type of a relay identity.
• TransportIdError
  An error related to parsing a TransportId.

Traits

• ChanTarget
  Information about a Tor relay used to connect to it.
• CircTarget
  Information about a Tor relay used to extend a circuit to it.
• DirectChanMethodsHelper
  Implement HasChanMethods for an object with HasAddr whose addresses all represent a host we can connect to by a direct Tor connection at its IP addresses.
• HasAddrs
  An object that represents a host on the network which may have known IP addresses.
• HasChanMethod
  An object that can be connected to via ChannelMethods.
• HasRelayIds
  An object containing information about a relay’s identity keys.
• HasRelayIdsLegacy
  Legacy implementation helper for HasRelayIds.
• IntoOwnedChanTarget
  A value that can be converted into an OwnedChanTarget.

Type Aliases

• LoggedChanTarget
  An OwnedChanTarget suitable for logging and including in errors