iroh-tor-transport

Tor hidden-service utilities and a custom iroh transport for routing packets over Tor streams.

Experimental: both iroh custom transports and this crate are experimental and may change.

What is iroh-tor-transport?

iroh-tor-transport provides a custom iroh custom transport that routes packets over Tor hidden services. Given only an iroh EndpointId, it derives the corresponding .onion address and connects through the Tor network.

Getting started

Tor control port

Most tests require a running Tor daemon with the control port enabled:

tor --ControlPort 9051 --CookieAuthentication 0

Custom transport

The transport connects to Tor's control port, creates an ephemeral hidden service, and handles packet framing and stream reuse:

use iroh::{Endpoint, SecretKey};
use iroh_tor_transport::TorCustomTransport;

let secret_key = SecretKey::generate(&mut rand::rng());

// Build the transport (creates hidden service)
let transport = TorCustomTransport::builder()
    .build(secret_key.clone())
    .await?;

// Build the endpoint with the Tor transport
let endpoint = Endpoint::builder()
    .secret_key(secret_key)
    .preset(transport.preset())
    .bind()
    .await?;

The preset() method configures the endpoint with:

• The Tor custom transport
• A discovery service that derives Tor addresses from endpoint IDs

Example

examples/echo.rs provides a CLI for echo server/client over Tor:

# Terminal 1: Start the echo server
cargo run --example echo -- accept

# Terminal 2: Connect to the server (use the EndpointId printed by the server)
cargo run --example echo -- connect <ENDPOINT_ID>

The onion address is derived from the EndpointId, so you only need the endpoint ID to connect.

Tests

• tests/echo.rs: hidden-service echo tests (Tor required)
• Internal tests cover packet framing, sender stream reuse, and custom transport

License

Copyright 2025 N0, INC.

This project is licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.