History

Nick Mathewson 3885a2c05b tor-proto: add a backend to detect reported clock skew. NETINFO cells, which are sent in every handshake, may contain timestamps. This patch adds an accessor for the timestamp in the Netinfo messages, and teaches the tor-proto code how to compute the minimum clock skew in the code. The computation isn't terribly precise, but it doesn't need to be: Tor should work fine if your clock is accurate to within a few hours. This patch also notes a Y2038 problem in the protocol: see torspec#80. Part of #405.		2022-03-23 08:24:36 -04:00
..
fuzz	Update corpus and links.	2021-09-07 12:32:50 -04:00
src	tor-proto: add a backend to detect reported clock skew.	2022-03-23 08:24:36 -04:00
tests	Remove many needless borrows and slices	2022-02-02 18:34:26 +00:00
Cargo.toml	Move skip_fmt into tor-basic-utils	2022-03-04 11:45:24 +00:00
README.md	Update our disclaimers and limitations sections.	2021-10-27 11:13:46 -04:00

README.md

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