41 releases (breaking)

new 0.30.0 May 1, 2025
0.28.0 Mar 3, 2025
0.25.0 Dec 2, 2024
0.24.0 Oct 31, 2024
0.0.0 Jun 24, 2021

#369 in Parser implementations

Download history 1830/week @ 2025-01-14 1388/week @ 2025-01-21 1102/week @ 2025-01-28 3210/week @ 2025-02-04 1490/week @ 2025-02-11 1121/week @ 2025-02-18 1419/week @ 2025-02-25 1445/week @ 2025-03-04 1640/week @ 2025-03-11 1077/week @ 2025-03-18 915/week @ 2025-03-25 1441/week @ 2025-04-01 925/week @ 2025-04-08 2409/week @ 2025-04-15 2374/week @ 2025-04-22 1444/week @ 2025-04-29

7,322 downloads per month
Used in 55 crates (10 directly)

MIT/Apache and maybe LGPL-3.0-only

1MB
19K SLoC

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.

Compile-time features

  • hs -- Types relating to Tor Hidden Services (.onion services).

  • hs-pow-full -- Types relating to Tor Hidden Services Proof of Work.

  • full -- Enable all features above.

Experimental and unstable features

Note that the APIs enabled by these features are NOT covered by semantic versioning[^1] guarantees: we might break them or remove them between patch versions.

  • experimental-udp: Types for conveying UDP over Tor.

  • testing: Additional APIs for testing, used in our whole-workspace tests.

  • experimental: Enable all the above experimental features.

[^1]: Remember, semantic versioning is what makes various cargo features work reliably. To be explicit: if you want cargo update to only make safe changes, then you cannot enable these features.

License: MIT OR Apache-2.0

Dependencies

~21–32MB
~500K SLoC