17 releases (10 breaking)

0.10.0 May 3, 2023
0.9.1 Mar 31, 2023
0.9.0 Feb 28, 2023
0.7.0 Nov 30, 2022
0.0.0 Jun 24, 2021

#306 in Parser implementations

Download history 388/week @ 2023-02-02 203/week @ 2023-02-09 465/week @ 2023-02-16 299/week @ 2023-02-23 132/week @ 2023-03-02 172/week @ 2023-03-09 222/week @ 2023-03-16 162/week @ 2023-03-23 295/week @ 2023-03-30 148/week @ 2023-04-06 181/week @ 2023-04-13 126/week @ 2023-04-20 202/week @ 2023-04-27 263/week @ 2023-05-04 203/week @ 2023-05-11 114/week @ 2023-05-18

796 downloads per month
Used in 18 crates (3 directly)


11K SLoC


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


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 between RelayCell and RelayMsg is meant in part to future-proof arti against these proposals if they are adopted.

License: MIT OR Apache-2.0


~357K SLoC