Module client

stem_rs

Module client 

Source
Expand description

ORPort client module for direct relay communication.

This module provides direct communication with Tor relays via their ORPort using the Tor relay protocol. This is distinct from the control protocol used by Controller and enables direct circuit creation and data transfer through the Tor network.

§Overview

The client module implements the Tor relay protocol (tor-spec.txt) for establishing connections to Tor relays and creating circuits. This enables:

  • Direct TLS connections to relay ORPorts
  • Link protocol negotiation (versions 3, 4, 5)
  • Circuit creation using CREATE_FAST cells
  • Directory requests through established circuits
  • Encrypted relay cell communication

§Architecture

The module is organized into three submodules:

  • cell: Cell types for the Tor relay protocol (VERSIONS, NETINFO, RELAY, etc.)
  • datatype: Data types used in cell construction (Address, Size, KDF, etc.)
  • This module: High-level Relay and RelayCircuit abstractions

§Connection Lifecycle

  1. Connect: Establish TLS connection to relay’s ORPort
  2. Negotiate: Exchange VERSIONS cells to agree on link protocol
  3. Initialize: Send NETINFO cell to complete handshake
  4. Create Circuit: Use CREATE_FAST/CREATED_FAST for circuit establishment
  5. Communicate: Send/receive encrypted RELAY cells
  6. Close: Destroy circuits and close connection

§Example

use stem_rs::client::{Relay, DEFAULT_LINK_PROTOCOLS};

// Connect to a relay's ORPort
let mut relay = Relay::connect("127.0.0.1", 9001, DEFAULT_LINK_PROTOCOLS).await?;

// Create a circuit through the relay
let mut circuit = relay.create_circuit().await?;

// Make a directory request
let request = "GET /tor/server/authority HTTP/1.0\r\n\r\n";
let response = circuit.directory(request, 1).await?;

// Clean up
circuit.close().await?;
relay.close().await?;

§Thread Safety

Relay uses internal Arc<Mutex<_>> for the TLS stream, making it safe to share across tasks. However, operations are serialized through the mutex. For high-throughput scenarios, consider using separate connections.

§Security Considerations

  • TLS certificate verification is disabled (relays use self-signed certs)
  • Circuit keys are derived using KDF-TOR from shared key material
  • CREATE_FAST provides weaker security than CREATE2 (no forward secrecy)
  • Key material is stored in memory for the circuit’s lifetime

§Differences from Python Stem

  • Uses async/await instead of threading
  • TLS handled by tokio-rustls instead of Python’s ssl module
  • Circuit encryption not yet fully implemented (placeholder)

§See Also

Re-exports§

pub use cell::cell_by_name;
pub use cell::cell_by_value;
pub use cell::AuthChallengeCell;
pub use cell::Cell;
pub use cell::CellType;
pub use cell::CertsCell;
pub use cell::CreateFastCell;
pub use cell::CreatedFastCell;
pub use cell::DestroyCell;
pub use cell::NetinfoCell;
pub use cell::PaddingCell;
pub use cell::RelayCell;
pub use cell::VPaddingCell;
pub use cell::VersionsCell;
pub use cell::AUTH_CHALLENGE_SIZE;
pub use cell::CELL_TYPE_SIZE;
pub use cell::FIXED_PAYLOAD_LEN;
pub use cell::PAYLOAD_LEN_SIZE;
pub use cell::RELAY_DIGEST_SIZE;
pub use cell::STREAM_ID_DISALLOWED;
pub use cell::STREAM_ID_REQUIRED;
pub use datatype::split;
pub use datatype::AddrType;
pub use datatype::Address;
pub use datatype::CertType;
pub use datatype::Certificate;
pub use datatype::CloseReason;
pub use datatype::LinkProtocol;
pub use datatype::LinkSpecifier;
pub use datatype::RelayCommand;
pub use datatype::Size;
pub use datatype::HASH_LEN;
pub use datatype::KDF;
pub use datatype::KEY_LEN;
pub use datatype::ZERO;

Modules§

cell
Cell types for the Tor relay protocol.
datatype
Data types for the Tor relay protocol.

Structs§

Relay
A connection to a Tor relay’s ORPort.
RelayCircuit
A circuit established through a Tor relay.

Constants§

DEFAULT_LINK_PROTOCOLS
Default link protocol versions supported for relay connections.