Crate stem_rs

Crate stem_rs 

Source
Expand description

§stem-rs

A Rust implementation of the Stem library for Tor control protocol interaction.

§Overview

stem-rs provides idiomatic Rust APIs for interacting with Tor’s control protocol, maintaining functional parity with Python Stem. The library enables:

  • Control socket communication (TCP and Unix domain sockets)
  • All authentication methods (NONE, PASSWORD, COOKIE, SAFECOOKIE)
  • High-level Controller API for Tor interaction
  • Complete descriptor parsing (server, micro, consensus, extra-info, hidden service)
  • Event subscription and handling
  • Exit policy parsing and evaluation
  • ORPort relay communication
  • Version parsing and comparison

§Architecture

The library is organized into these primary modules:

  • socket: Low-level control socket communication
  • auth: Authentication methods and protocol info
  • controller: High-level Controller API
  • descriptor: Tor descriptor parsing
  • events: Event types and handling
  • exit_policy: Exit policy evaluation
  • client: Direct ORPort relay communication
  • response: Control protocol response parsing
  • interpreter: Interactive Tor control interpreter
  • version: Tor version parsing and comparison
  • util: Validation utilities for fingerprints, nicknames, etc.

§Quick Start

use stem_rs::{controller::Controller, Error};

#[tokio::main]
async fn main() -> Result<(), Error> {
    // Connect to Tor's control port
    let mut controller = Controller::from_port("127.0.0.1:9051".parse().unwrap()).await?;
     
    // Authenticate (auto-detects method)
    controller.authenticate(None).await?;
     
    // Query Tor version
    let version = controller.get_version().await?;
    println!("Connected to Tor {}", version);
     
    Ok(())
}

§Thread Safety

The controller::Controller type is Send but not Sync. For concurrent access, wrap it in Arc<Mutex<Controller>> or use separate connections.

§Security Considerations

  • Authentication tokens are cleared from memory after use
  • Constant-time comparison is used for sensitive data (see util::secure_compare)
  • Input validation prevents protocol injection attacks

§Error Handling

All fallible operations return Result<T, Error>. The [Error] enum provides specific error variants for different failure modes:

See the [Error] documentation for recovery guidance.

Re-exports§

pub use controller::Controller;
pub use socket::ControlSocket;
pub use version::Version;

Modules§

auth
Authentication methods for Tor control protocol.
client
ORPort client module for direct relay communication.
controller
High-level controller API for Tor control protocol interaction.
descriptor
Descriptor parsing for Tor network documents.
events
Event types and handling for Tor control protocol async notifications.
exit_policy
Exit policy parsing and evaluation for Tor relays.
interpreter
Interactive interpreter for Tor control protocol.
protocol
Control protocol message parsing for Tor control protocol.
response
Response parsing for Tor control protocol messages.
socket
Control socket communication with Tor’s control interface.
util
Validation and helper functions for Tor-related data.
version
Tor version parsing and comparison.

Enums§

AuthDescriptorAction
Actions that directory authorities take with relay descriptors.
AuthError
Authentication-specific errors.
BridgeDistribution
Bridge distribution methods.
CircBuildFlag
Attributes about how a circuit is built.
CircClosureReason
Reason that a circuit is being closed or failed to be established.
CircEvent
Type of change reflected in a circuit by a CIRC_MINOR event.
CircPurpose
Purpose of a circuit.
CircStatus
Status of a circuit in the Tor network.
ConnectionType
Purpose for a Tor connection.
Error
Errors that can occur during stem-rs operations.
EventType
Types of events that can be subscribed to via the control protocol.
Flag
Flags assigned to Tor relays by directory authorities.
GuardStatus
Status of a guard relay.
GuardType
Type of guard relay usage.
HiddenServiceState
State of a hidden service circuit.
HsAuth
Type of authentication for a HS_DESC event.
HsDescAction
Action being taken in a HS_DESC event.
HsDescReason
Reason for a hidden service descriptor fetch to fail.
OrClosureReason
Reason that an OR connection is being closed or failed.
OrStatus
Status of an OR (Onion Router) connection.
Runlevel
Logging severity levels for Tor events.
Signal
Signals that can be sent to the Tor process.
StatusType
Source of a status event.
StreamClosureReason
Reason that a stream is being closed or failed to be established.
StreamPurpose
Purpose of a stream.
StreamSource
Cause of a stream being remapped to another address.
StreamStatus
Status of a stream going through Tor.
TimeoutSetType
Way in which the timeout value of a circuit is changing.
TokenBucket
Bucket categories for TB_EMPTY events.