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 ChannelBuilder. This will yield an handshake::OutboundClientHandshake that represents the state of the handshake.
- Call handshake::OutboundClientHandshake::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_circ method. See crate::circuit::PendingClientCirc 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
This is client-only, and only supports link protocol version 4.
TODO: There is no channel padding.
TODO: There is no flow control, rate limiting, queueing, or fairness.
Re-exports§
pub use crate::channel::params::*;
Modules§
- kist
- KIST-related parameters.
- padding
- Channel padding
- params
- Parameters influencing all channels in a Tor client
Structs§
- Channel
- An open client channel, ready to send and receive Tor cells.
- Channel
Builder - Structure for building and launching a Tor channel.
- Close
Info - The status of a channel which was closed successfully.
- Outbound
Client Handshake - A raw client channel on which nothing has been done.
- UniqId
- Unique identifier for a channel.
- Unverified
Channel - A client channel on which versions have been negotiated and the relay’s handshake has been read, but where the certs have not been checked.
- Verified
Channel - A client channel on which versions have been negotiated, relay’s handshake has been read, but the client has not yet finished the handshake.
Enums§
- Closed
Unexpectedly - The status of a channel which closed unexpectedly.
- Create
Response - A subclass of ChanMsg that can arrive in response to a CREATE* cell that we send.
- CtrlMsg
- A message telling the channel reactor to do something.
Constants§
- CHANNEL_
BUFFER_ SIZE - The size of the channel buffer for communication between
Channel
and its reactor.