Crate tor_cell

Coding and decoding for the cell types that make up Tor’s protocol

Overview

Tor’s primary network protocol is oriented around a set of messages called “Cells”. They exist at two primary layers of the protocol: the channel-cell layer, and the relay-cell layer.

Channel cells are sent between relays, or between a client and a relay, over a TLS connection. Each of them encodes a single Channel Message. Channel messages can affect the channel itself (such as those used to negotiate and authenticate the channel), but more frequently are used with respect to a given multi-hop circuit.

Channel message that refer to a circuit do so with a channel-local identifier called a Circuit ID. These messages include CREATE2 (used to extend a circuit to a first hop) and DESTROY (used to tear down a circuit). But the most frequently used channel message is RELAY, which is used to send a message to a given hop along a circuit.

Each RELAY cell is encrypted and decrypted (according to protocols not implemented in this crate) until it reaches its target. When it does, it is decoded into a single Relay Message. Some of these relay messages are used to manipulate circuits (e.g., by extending the circuit to a new hop); others are used to manipulate anonymous data-streams (by creating them, ending them, or sending data); and still others are used for protocol-specific purposes (like negotiating with an onion service.)

For a list of most of the cell types used in Tor, see tor-spec.txt. Other cell types are defined in rend-spec-v3.txt (for onion services) and padding-spec.txt (for padding negotiation).

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

Futureproofing note:

There are two pending proposals to remove the one-to-one correspondence between relay cells and relay messages.

Proposal 319 would add a “RELAY_FRAGMENT” command that would allow larger relay messages to span multiple RELAY cells.

Proposal 325, on the other hand, would allow multiple relay messages to be packed into a single RELAY cell.

The distinction betweeen RelayCell and RelayMsg is meant in part to future-proof arti against these proposals if they are adopted.

Limitations

There aren’t any tests.

There isn’t enough documentation.

This is the first part of the project I started working on, and probably reflects the most naive understranding of Rust.

Modules

chancell	Messages sent over Tor channels
relaycell	Implementation for parsing and encoding relay cells

Enums

Error

An error type for the tor-proto crate.

Type Definitions

Result

An error type for this crate.