Module channel 

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::ClientInitiatorHandshake that represents the state of the handshake.
• Call 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 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 futures_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 testing is enabled

unique_id 🔒

Helper for unique identifiers for channels.

Structs

Channel

An open client channel, ready to send and receive Tor cells.

ChannelBuilder

Structure for building and launching a Tor channel.

ChannelDetails 🔒

This is information shared between the reactor and the frontend (Channel object).

ChannelSender 🔒

A handle to a Channel` that can be used, by circuits, to send channel cells.

ClientInitiatorHandshake

A raw client channel on which nothing has been done.

CloseInfo

The status of a channel which was closed successfully.

MutableDetails 🔒

Mutable details (state) used by the Channel (frontend)

UniqId

Unique identifier for a channel.

UnverifiedChannel

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.

VerifiedChannel

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

ChannelType

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

ClosedUnexpectedly

The status of a channel which closed unexpectedly.

CreateResponse

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.

OpenChanMsgS2C 🔒

A channel message that we allow to be sent from a server to a client on an open channel.

PaddingControlState 🔒

State used to control padding

Constants

CHANNEL_BUFFER_SIZE

The size of the channel buffer for communication between Channel and its reactor.

Functions

check_id_match_helper 🔒

If there is any identity in wanted_ident that is not present in my_ident, return a ChanMismatch error.

fake_channel_details 🔒 testing

Make some fake channel details (for testing only!)

fake_mpsc 🔒 testing

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.

ChanCellQueueEntry 🔒

An entry in a channel’s queue of cells to be flushed.

ChannelFrame 🔒

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.