Module cell

Relay cell cryptography

The Tor protocol centers around “RELAY cells”, which are transmitted through the network along circuits. The client that creates a circuit shares two different sets of keys and state with each of the relays on the circuit: one for “outbound” traffic, and one for “inbound” traffic.

So for example, if a client creates a 3-hop circuit with relays R1, R2, and R3, the client has:

• An “inbound” cryptographic state shared with R1.
• An “inbound” cryptographic state shared with R2.
• An “inbound” cryptographic state shared with R3.
• An “outbound” cryptographic state shared with R1.
• An “outbound” cryptographic state shared with R2.
• An “outbound” cryptographic state shared with R3.

In this module at least, we’ll call each of these state objects a “layer” of the circuit’s encryption.

The Tor specification does not describe these layer objects very explicitly. In the current relay cryptography protocol, each layer contains:

• A keyed AES-CTR state. (AES-128 or AES-256) This cipher uses a key called Kf or Kb in the spec, where Kf is a “forward” key used in the outbound direction, and Kb is a “backward” key used in the inbound direction.
• A running digest. (SHA1 or SHA3) This digest is initialized with a value called Df or Db in the spec.

This crypto::cell module itself provides traits and implementations that should work for all current future versions of the relay cell crypto design. The current Tor protocols are instantiated in a tor1 submodule.

Modules

bench_utils 🔒 bench

Benchmark utilities for the cell module.

cgo 🔒 counter-galois-onion

Implementation for Counter Galois Onion (CGO) relay cell encryption

tor1 🔒

An implementation of Tor’s current relay cell cryptography.

Structs

HopNum

Type to store hop indices on a circuit.

HopNumDisplay

A helper for displaying HopNums.

InboundClientCrypt

A client’s view of the cryptographic state for an entire constructed circuit, as used for receiving cells.

OutboundClientCrypt

A client’s view of the cryptographic state for an entire constructed circuit, as used for sending cells.

RelayCellBody

Type for the body of a relay cell.

Traits

ClientLayer

A paired object containing the inbound and outbound cryptographic layers used by a client to communicate with a single hop on one of its circuits.

CryptInit

Represents the ability for one hop of a circuit’s cryptographic state to be initialized from a given seed.

InboundClientLayer

A client’s view of the crypto state shared with a single relay on a circuit, as used for inbound cells.

InboundRelayLayer

Represents a relay’s view of the inbound crypto state on a given circuit.

OutboundClientLayer

A client’s view of the cryptographic state shared with a single relay on a circuit, as used for outbound cells.

OutboundRelayLayer

Represent a relay’s view of the outbound crypto state on a given circuit.

RelayLayer

A paired object containing the inbound and outbound cryptographic layers used by a relay to implement a client’s circuits.

Type Aliases

Tor1Hsv3RelayCrypto 🔒 hs-common

Standard Tor relay crypto, as instantiated for the HSv3 protocol.

Tor1RelayCrypto 🔒

Standard Tor relay crypto, as instantiated for RELAY cells.