Expand description
Code for talking directly (over a TLS connection) to a Tor client or relay.
Channels form the basis of the rest of the Tor protocol: they are the only way for two Tor instances to talk.
Channels are not useful directly for application requests: after making a channel, it needs to get used to build circuits, and the circuits are used to anonymize streams. The streams are the objects corresponding to directory requests.
In general, you shouldn’t try to manage channels on your own;
use the tor-chanmgr crate instead.
To launch a channel:
- Create a TLS connection as an object that implements AsyncRead + AsyncWrite + StreamOps, and pass it to a channel builder. This will yield an crate::client::channel::handshake::ClientInitiatorHandshake that represents the state of the handshake.
- Call crate::client::channel::handshake::ClientInitiatorHandshake::connect on the result to negotiate the rest of the handshake. This will verify syntactic correctness of the handshake, but not its cryptographic integrity.
- Call handshake::UnverifiedChannel::check on the result. This finishes the cryptographic checks.
- Call handshake::VerifiedChannel::finish on the result. This completes the handshake and produces an open channel and Reactor.
- Launch an asynchronous task to call the reactor’s run() method.
One you have a running channel, you can create circuits on it with its Channel::new_tunnel method. See crate::client::circuit::PendingClientTunnel for information on how to proceed from there.
§Design
For now, this code splits the channel into two pieces: a “Channel” object that can be used by circuits to write cells onto the channel, and a “Reactor” object that runs as a task in the background, to read channel cells and pass them to circuits as appropriate.
I’m not at all sure that’s the best way to do that, but it’s what I could think of.
§Limitations
TODO: There is no rate limiting or fairness.
Re-exports§
pub(crate) use crate::channel::reactor::Reactor;🔒use crate::channel::reactor::BoxedChannelSink;🔒use crate::channel::reactor::BoxedChannelStream;🔒pub use crate::channel::unique_id::UniqId;use crate::client::circuit::PendingClientTunnel;🔒use crate::client::circuit::padding::PaddingController;🔒use crate::client::circuit::padding::QueuedCellPaddingInfo;🔒use crate::memquota::ChannelAccount;🔒use crate::memquota::CircuitAccount;🔒use crate::memquota::SpecificAccount as _;🔒use crate::peer::PeerInfo;🔒use crate::util::err::ChannelClosed;🔒use crate::util::timeout::TimeoutEstimator;🔒use crate::util::ts::AtomicOptTimestamp;🔒use crate::ClockSkew;🔒use crate::client;🔒use crate::Error;🔒use crate::Result;🔒use cfg_if::cfg_if;🔒use reactor::BoxedChannelStreamOps;🔒use safelog::MaybeSensitive;🔒use safelog::sensitive as sv;🔒use std::future::Future;🔒use std::future::IntoFuture;🔒use std::net::IpAddr;🔒use std::pin::Pin;🔒use std::sync::Mutex;🔒use std::sync::MutexGuard;🔒use std::time::Duration;🔒use tor_async_utils::oneshot_broadcast;🔒use tor_cell::chancell::ChanMsg;🔒use tor_cell::chancell::AnyChanCell;🔒use tor_cell::chancell::CircId;🔒use tor_cell::chancell::msg::Netinfo;🔒use tor_cell::chancell::msg::PaddingNegotiate;🔒use tor_error::internal;🔒use tor_linkspec::HasRelayIds;🔒use tor_linkspec::OwnedChanTarget;🔒use tor_memquota::mq_queue;🔒use tor_memquota::mq_queue::ChannelSpec as _;🔒use tor_memquota::mq_queue::MpscSpec;🔒use tor_rtcompat::CoarseTimeProvider;🔒use tor_rtcompat::DynTimeProvider;🔒use tor_rtcompat::Runtime;🔒use tor_rtcompat::SleepProvider;🔒use tor_async_utils::counting_streams;🔒use tor_async_utils::counting_streams::CountingSink;🔒use tor_async_utils::counting_streams::CountingStream;🔒use crate::channel::reactor::CreateRequestHandlerAndData;🔒use crate::circuit::CircuitRxReceiver;🔒use crate::relay::channel::create_handler::CreateRequestHandler;🔒use tor_llcrypto::pk::ed25519::Ed25519Identity;🔒use tor_llcrypto::pk::rsa::RsaIdentity;🔒use asynchronous_codec;🔒use futures::channel::mpsc;🔒use futures::io::AsyncRead;🔒use futures::io::AsyncWrite;🔒use oneshot_fused_workaround as oneshot;🔒use educe::Educe;🔒use futures::FutureExt as _;🔒use futures::Sink;🔒use std::result::Result as StdResult;🔒use std::sync::Arc;🔒use std::task::Context;🔒use std::task::Poll;🔒use tracing::instrument;🔒use tracing::instrument;🔒use tracing::trace;🔒pub use super::client::channel::handshake::ClientInitiatorHandshake;pub use super::relay::channel::handshake::RelayInitiatorHandshake;pub(crate) use crate::channel::handler::ClogDigest;🔒pub(crate) use crate::channel::handler::SlogDigest;🔒use crate::channel::unique_id::CircUniqIdContext;🔒use kist::KistParams;🔒use PaddingControlState as PCS;🔒pub use super::reactor::CtrlMsg;pub use crate::circuit::celltypes::CreateResponse;pub use crate::channel::params::*;
Modules§
- circmap 🔒
- Types and code to map circuit IDs to circuits.
- handler 🔒
- Wrap tor_cell::chancell::codec::ChannelCodec for use with the asynchronous_codec crate.
- handshake 🔒
- Implementations for the channel handshake
- kist
- KIST-related parameters.
- msg 🔒
- This contains restricted message sets namespaced by link protocol version.
- padding
- Channel padding
- params
- Parameters influencing all channels in a Tor client
- reactor 🔒
- Code to handle incoming cells on a channel.
- testing_
exports 🔒 - Imports that are re-exported pub if feature
testingis enabled - unique_
id 🔒 - Helper for unique identifiers for channels.
Structs§
- Canonicity 🔒
- Canonical state between this channel and its peer. This is inferred from the
Netinforeceived during the channel handshake. - Channel
- An open client channel, ready to send and receive Tor cells.
- Channel
Details 🔒 - This is information shared between the reactor and the frontend (
Channelobject). - Channel
Sender 🔒 - A handle to a
Channel` that can be used, by circuits, to send channel cells. - Close
Info - The status of a channel which was closed successfully.
- Mutable
Details 🔒 - Mutable details (state) used by the
Channel(frontend)
Enums§
- Channel
Mode 🔒 - Whether the channel is operating in “client” or “relay” mode, and some mode-specific parameters.
- Channel
Type - This indicate what type of channel it is. It allows us to decide for the correct channel cell state machines and authentication process (if any).
- Closed
Unexpectedly - The status of a channel which closed unexpectedly.
- Padding
Control 🔒State - State used to control padding
Constants§
- CHANNEL_
BUFFER_ SIZE - The size of the channel buffer for communication between
Channeland its reactor.
Functions§
- check_
id_ 🔒match_ helper - If there is any identity in
wanted_identthat is not present inmy_ident, return a ChanMismatch error. - fake_
channel_ 🔒details - Make some fake channel details (for testing only!)
- fake_
mpsc 🔒 - Make an MPSC queue, of the type we use in Channels, but a fake one for testing
- new_
frame 🔒 - Helper: Return a new channel frame ChannelFrame from an object implementing AsyncRead + AsyncWrite. In the tor context, it is always a TLS stream.
Type Aliases§
- CellRx 🔒
- Implementation type for a cell queue held by a reactor.
- CellTx 🔒
- Implementation type for a ChannelSender.
- Chan
Cell 🔒Queue Entry - An entry in a channel’s queue of cells to be flushed.
- Channel
Frame 🔒 - A channel cell frame used for sending and receiving cells on a channel. The handler takes care of the cell codec transition depending in which state the channel is.