tor-building-on-tor-software-patterns
Use when writing code that talks to Tor — SOCKS with socks5h and stream isolation, the control port, ephemeral onion services via ADD_ONION or stem, long-lived onion services in torrc, client authorization v3, Onion-Location and Alt-Svc headers, torsocks and its limits, embedding Arti, testing against a private chutney network, and building your own private or custom onion-routing network. Covers §13.1–§13.4, §13.6 and handbook §1. Companion to the other Tor and onion-network skills.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 5
- Forks
- 3
01 前言 Front Matter
- name
- tor-building-on-tor-software-patterns
- description
- Use when writing code that talks to Tor — SOCKS with socks5h and stream isolation, the control port, ephemeral onion services via ADD_ONION or stem, long-lived onion services in torrc, client authorization v3, Onion-Location and Alt-Svc headers, torsocks and its limits, embedding Arti, testing against a private chutney network, and building your own private or custom onion-routing network. Covers §13.1–§13.4, §13.6 and handbook §1. Companion to the other Tor and onion-network skills.
03 SKILL.md 正文
Building on Tor: Software Patterns
Part 7 of 8 of the Tor and Onion Networks reference (plugin
tor-and-onion-networks), covering §13.1–§13.4, §13.6 and handbook §1. Sibling skills:tor-protocol-circuits-and-cell-cryptography(§1–§5),tor-network-consensus-guards-and-paths(§6–§7),tor-onion-services-and-hardening(§8–§9),tor-censorship-circumvention-and-bridges(§10),tor-attack-literature-and-threat-model(§11),tor-ecosystem-alternatives-and-governance(§12, §14–§16),tor-running-relays-bridges-and-hardware(§13.5 and handbook §2–§6). Section numbers are shared across the set; a reference written as §N →skillpoints into that sibling skill.Currency: compiled 16 September 2026. Config options checked against C tor 0.4.9.x (stable since Feb 2026) and Arti 2.6.x (Sept 2026). When in doubt:
man tor, https://community.torproject.org/, https://onionservices.torproject.org/.
⚠️ Five patterns cover essentially all software built on Tor. Pick the one that matches your assurance requirement, not the one that is least work.
⚠️ GOTCHA boxes mark where the obvious approach silently leaks.
The three ideas that organize this document:
- ⚠️
socks5h, NOTsocks5(§13.1). Thehmakes the exit resolve the hostname. Without it you do a local DNS lookup for the destination you are trying to hide — the single most common Tor-integration leak, and it fails silently.- ⚠️ STREAM ISOLATION IS A PRODUCT DECISION, NOT A TUNING KNOB (§13.1). SOCKS username/password pairs become isolation tokens, so distinct credentials get distinct circuits. That is how you stop two tenants, or two identities, sharing an exit.
- ⚠️ EPHEMERAL SERVICES BEAT FILESYSTEM KEYS FOR MOST APPS (§13.2).
ADD_ONION NEW:ED25519-V3 Flags=DiscardPKkeeps the key in memory only and dies with the process. OnionShare, Ricochet Refresh and Briar all work this way — no key management, no torrc edits, nothing on disk to seize.
§13. The five patterns
Conceptually, building on Tor falls into five patterns:
- SOCKS-integrated apps — the minimal, safest pattern: point your app at tor's SocksPort
(127.0.0.1:9050; 9150 for Tor Browser) using
socks5hso DNS resolves at the exit. Add stream-isolation credentials per tenant/connection class. - Ephemeral onion services — your app speaks
ADD_ONION NEW:ED25519-V3to the control port, publishes a one-shot service, and tears it down on exit. - Long-lived onion services — torrc
HiddenServiceDir/HiddenServicePort, optionally client auth, offline master keys, PoW, Onionbalance backends, and Onion-Location/Alt-Svc on the clearnet twin. - Embedding Tor — ship tor/Arti as a library (arti-client crate, Tor.framework, IPtProxy/tor-android, onionmasq for VPN-style capture) inside your product.
- Network-layer building — relays, bridges, exits, transparent-proxy gateways, two-box
isolation. See §13.5 →
tor-running-relays-bridges-and-hardware.
Building your own network — rather than building on Tor — is a different decision tree with its own three options: §13.6.
§13.1 The SOCKS interface (the boring, correct way)
- C tor default:
127.0.0.1:9050. Tor Browser:9150. - Always use
socks5h/--socks5-hostnameso name resolution happens at the exit — otherwise you resolve DNS locally and leak the destination.
# Verify egress + get your exit IP (official oracle):
curl --socks5-hostname 127.0.0.1:9050 https://check.torproject.org/api/ip
# → {"IsTor":true,"IP":"<exit-address>"}
# Per-connection stream isolation: SOCKS username/password become isolation tokens
# (IsolateSOCKSAuth is default). Two different credentials → two different circuits.
curl --socks5 127.0.0.1:9050 --proxy-user tenant-a:pw https://example.org
curl --socks5 127.0.0.1:9050 --proxy-user tenant-b:pw https://example.org
# Python; needs requests[socks]
import requests
s = requests.Session()
s.proxies = {"http": "socks5h://127.0.0.1:9050", "https": "socks5h://127.0.0.1:9050"}
print(s.get("https://check.torproject.org/api/ip").json())
Stream isolation flags you should know (apply per SocksPort line):
SocksPort 9050 IsolateDestAddr IsolateDestPort # one circuit per destination host+port
SocksPort 9062 # dedicated port for one app = hard isolation
Per-site circuits in your own tooling
Tor Browser isolates streams per first-party domain. Replicate the idea in services: distinct
SOCKS credentials per logical tenant, or NEWNYM-driven circuit freshening via the control
port for long batch jobs.
⚠️ GOTCHA:
SIGNAL NEWNYMis rate-limited to roughly once per 10 seconds, and it does not reset your guards (by design — see §7.1 →tor-network-consensus-guards-and-paths). Use isolation credentials when you can; NEWNYM is the blunt instrument.
§13.2 The control port and ephemeral onion services
Enable the controller (Debian/Ubuntu pattern):
ControlPort 9051
CookieAuthentication 1
CookieAuthFileGroupReadable 1 # then: sudo usermod -aG debian-tor youruser
Ephemeral onion service — no torrc edits, keys live only in memory (this is the
OnionShare / Ricochet Refresh pattern). With stem (pip install stem; unmaintained since
~2020 but still the canonical library — see §12.3 →
tor-ecosystem-alternatives-and-governance):
from stem.control import Controller
with Controller.from_port(port=9051) as ctl:
ctl.authenticate() # reads the cookie automatically
svc = ctl.create_ephemeral_hidden_service(
{80: ("127.0.0.1", 8000)}, # onion :80 -> local 8000
await_publication=True,
)
print(f"http://{svc.service_id}.onion")
# keep the controller connection open; the service dies when it closes
input("Serving. Press enter to tear down.\n")
Raw protocol equivalent (useful when porting to other languages — spec: control-spec.txt):
AUTHENTICATE <cookie-hex>
ADD_ONION NEW:ED25519-V3 Flags=DiscardPK Port=80,127.0.0.1:8000
Flags=DiscardPK tells tor not to return the private key (service unrecoverable by design).
Async alternatives: txtorcon (Twisted, most battle-tested for services), aiostem
(asyncio).
§13.3 Long-lived onion services (torrc)
HiddenServiceDir /var/lib/tor/mysvc/
HiddenServiceNumIntroductionPoints 3
HiddenServicePort 80 127.0.0.1:8080 # onion :80 -> local web app
#HiddenServicePort 443 unix:/run/mysvc.sock # unix sockets supported
- Address and keys appear under
HiddenServiceDir(hostnamefile holds the 56-char address). Permissions must be0700, owned by the tor user. - Offline master keys: generate the
hs_ed25519_secret_keyon an offline machine (tor --keygenin a scratch datadir), archive the encrypted master, and deploy only the signing material — a box compromise then doesn't compromise the address permanently. - DoS hardening (PoW, requires tor built with
--enable-gplfor Equi-X/HashX):
HiddenServicePoWDefensesEnabled 1
HiddenServicePoWQueueRate 250
HiddenServicePoWQueueBurst 2500
MetricsPort 127.0.0.1:9035
MetricsPortPolicy accept 127.0.0.1 # scrape tor_hs_pow_* with Prometheus
- Client authorization v3 (private services): the server keeps an
authorized_clients/directory insideHiddenServiceDir, one<name>.authfile per client containingdescriptor:x25519:<base32-pubkey-no-padding>; each client adds a<56chars>.auth_privatefile (<addr>.onion:descriptor:x25519:<base32-priv>) to itsClientOnionAuthDir. Generate x25519 pairs with any standard crypto library and base32-encode the raw 32-byte keys perrend-spec-v3. - Load balancing: run
HiddenServiceOnionbalanceInstance 1on each backend pointing at the Onionbalance master.
⚠️ GOTCHA (as of 2026): PoW and Onionbalance don't mix. Choose per threat model — DoS resistance on a single instance, or horizontal scale across backends. See §9.2–§9.3 →
tor-onion-services-and-hardening.
§13.4 Advertising the onion from your clearnet site
# nginx — Tor users get the ".onion available" pill (Tor Browser ≥ 9.5)
add_header Onion-Location http://<your56>.onion$request_uri;
# transparent variant: Tor-capable clients switch to onion silently
add_header Alt-Svc 'h2="<your56>.onion:443"; ma=86400';
Serve these over HTTPS from the clearnet origin only (never from the onion itself).
§13.4a Non-SOCKS apps: torsocks and its honest limits
torsocks curl https://check.torproject.org/api/ip
torsocks is LD_PRELOAD shimming: TCP only, breaks on apps using raw syscalls, no UDP, and it
silently does nothing for apps that bypass libc (statically linked Go/Rust binaries).
⚠️ GOTCHA — this is the dangerous one. A statically linked binary under
torsocksconnects directly, with no error and no warning. Rule of thumb: torsocks for convenience, never for high-stakes assurance. For assurance, use app-native SOCKS or a fail-closed network sandbox (§13.5 →tor-running-relays-bridges-and-hardware, §4.3–4.4).proxychainsshares the architecture and the caveats, with worse defaults.
§13.4b Arti as a library and daemon
Arti (Rust) is the future embedding path: no fork of an external process, memory safety, and — since 1.8.0 (Dec 2025) — production-grade onion services with native vanguards.
# ~/.config/arti/arti.toml (minimal client)
[proxy]
socks_listen = "127.0.0.1:9150"
dns_listen = "127.0.0.1:15354"
// embedding: arti-client = "0..." (API churned through 2.x — pin + read changelog)
use arti_client::{TorClient, TorClientConfig};
let tor = TorClient::create_bootstrapped(TorClientConfig::default()).await?;
let stream = tor.connect(("check.torproject.org", 443)).await?;
C-tor → Arti service migration: arti hsc ctor-migrate (2.x) ports hidden-service keys. Watch
the arti hss tooling and Arti RPC — both are the fast-moving surface in 2026. onionmasq
(from the Tor VPN project) gives you a userspace TUN interface over Arti: route whole
applications without them knowing.
§13.4c Developing against a test network: chutney
Never integration-test against the production network. Chutney runs a private mini-Tor on localhost:
git clone https://gitlab.torproject.org/tpo/core/chutney.git
cd chutney
./chutney configure networks/basic
./chutney start networks/basic
./chutney verify networks/basic
./chutney status networks/basic # shows per-node SOCKS/Control ports to point tests at
§13.6 Building your own private network
"I want a private network" almost always resolves to one of three architectures, separated by two orders of magnitude of effort. Pick before you build.
| Option | What it is | When it is right |
|---|---|---|
| A — public Tor + v3 onion services with client authorization | Your services are onion services on the public network; only holders of a client key can see them | Almost every real case: organizational privacy, private infrastructure, SecureDrop- and OnionShare-style deployments |
| B — your own Tor network | Your own directory authorities, relays and clients, isolated from public Tor | Testing, research, or a closed organizational network that must not touch public Tor at all |
| C — a custom onion routing network | Tor-like software of your own, with different trade-offs | Research, or a genuinely different threat model (§13.6.3) |
§13.6.1 Option A — use the public Tor network (the right answer for most cases)
Run a tor client on your server, configure a HiddenServiceDir with client authorization
(§13.3), distribute .auth_private files to your authorized users, and let them connect via
Tor Browser or a Tor-integrated application. The service is invisible to anyone without a
client key. You get location-anonymous hosting, encryption by construction, authentication of
both directions, and the whole public relay set — without operating any of it. Add PoW for
DoS resistance and vanguards for guard-discovery resistance (§9 →
tor-onion-services-and-hardening). This is what SecureDrop and OnionShare do.
⚠️ GOTCHA: running your own network reduces your anonymity set. On public Tor your traffic hides among several million daily users; on a twenty-relay private network, "someone used the network" is a much smaller set, and its operator knows who the participants are. Isolation from public Tor is an availability and control property, not an anonymity upgrade — choose B or C because you need control, never because you want more anonymity than A gives you.
§13.6.2 Option B — run your own Tor network (chutney, and past it)
Chutney is not only a test harness (§13.4c). networks/basic is a complete miniature Tor —
3 directory authorities plus relays and clients — and a custom network definition is how
you grow one:
./chutney configure networks/basic # 3 authorities + relays + clients
# For a larger private network, write a custom network definition with your own
# authorities, relays and exits. Each node gets its own torrc and data directory.
For a production private network you need: at least 3 directory authorities, run on
different infrastructure in different locations; a sufficient number of relays for bandwidth
and redundancy; your own consensus process (your authorities vote hourly exactly as public
Tor's nine do — §6.2 → tor-network-consensus-guards-and-paths); and client software
configured to use your authorities instead of the public ones. It is a substantial
undertaking, and what it buys is complete control over who participates. Operator mechanics
and the verification checklist: handbook §2 and §5 →
tor-running-relays-bridges-and-hardware.
§13.6.3 Option C — build a custom onion routing network
If you want something Tor-like with different trade-offs — different circuit lengths, guard strategies, crypto — four core components have to exist; onion services are optional:
- Relay software. Authenticates to neighbours (ed25519 identities), accepts
circuit-building commands, performs onion encryption/decryption on relay cells (§3 →
tor-protocol-circuits-and-cell-cryptography). - Directory system. Some mechanism for clients to discover relays — Tor's nine hourly-voting authorities, a single trusted directory server, a threshold-signature scheme, a DHT, a blockchain. The two properties that matter whatever you pick: clients must get a consistent view of the relay set, and an attacker must not be able to inject relays cheaply.
- Path selection. Three relays subject to constraints (no shared operator, no shared
subnet, exit policy permits the destination), guards pinned for months (§7 →
tor-network-consensus-guards-and-paths). The algorithm is the anonymity property. - Client software. Telescoping circuit construction, guard state, a SOCKS interface, stream isolation (§13.1).
- Onion services (optional). Introduction points, descriptor publication to HSDirs,
rendezvous points, client authorization, and a key-derived self-authenticating address
(§8 →
tor-onion-services-and-hardening).
⚠️ KEY DESIGN PARAMETERS. Circuit length (3 is standard; more hops raise latency and the attacker's cost together). Guard rotation period (months is standard; shorter raises exposure probability). Directory trust model (authorities vs. DHT vs. blockchain). Crypto primitives (ntor for the handshake; CGO or an AEAD for cells). Whether to support onion services. Whether to support pluggable transports. Whether the network is open (anyone joins) or closed (known participants only). These seven choices determine what your network is; everything else is implementation.
Implementation checklist:
- Use vetted cryptographic libraries (libsodium, libsecp256k1) — never implement primitives yourself.
- ntor or X25519 for the handshake (§4.1 →
tor-protocol-circuits-and-cell-cryptography). - An AEAD for cell crypto (ChaCha20-Poly1305 or AES-GCM). Do not use CTR mode without
authentication — malleability is exactly what enables tagging attacks (§4.2 →
tor-protocol-circuits-and-cell-cryptography). Note that Tor's own CGO is not a stock AEAD: it needs a rugged PRP because relays must transform cells through a deliberately malleable decrypt path. Reach for CGO only if you have that same constraint; otherwise a standard AEAD per hop is the safer build. - Guard pinning from day one and path restrictions (family, subnet) from day one — both are far harder to retrofit than to build in.
- Test against chutney-style adversarial scenarios (§13.4c).
- Have a plan for relay discovery and Sybil resistance before you have relays.
- Consider using Arti as a foundation rather than starting from zero (§12.1 →
tor-ecosystem-alternatives-and-governance).
Where to go next
- Relays, bridges, exits, transparent proxies, hardware builds, verification and abuse
handling: §13.5 →
tor-running-relays-bridges-and-hardware. - What a v3 onion service is actually doing underneath this configuration: §8 →
tor-onion-services-and-hardening. - Why
socks5hmatters — where the anonymity boundary actually sits: §3.3 →tor-protocol-circuits-and-cell-cryptography. - Library and implementation choices: §12 →
tor-ecosystem-alternatives-and-governance.
04 同仓库更多 Skills
white-paper-writing
Use when writing white papers, technical reports, policy documents, thought leadership pieces, or any long-form authoritative document. Triggers on requests to write, structure, outline, or review white papers, technical reports, position papers, policy briefs, or evidence-driven arguments. Also use for B2B content marketing strategy, technical documentation requiring authority, academic-style reports, or any document that must educate while persuading. Use when someone asks "how should I structure this" for a long-form document.
prose-technical-mechanics
Use when editing or writing prose at a technical/mechanical level: choosing between Anglo-Saxon and Latinate diction, placing information in topic vs stress positions, writing periodic vs cumulative sentences, handling sentence rhythm, punctuation as logic, transitions, paragraph structure, or phonesthetics. Use when someone wants to understand WHY prose works or doesn't, not just surface-level style advice. Triggers on word choice, sentence structure, emphasis, rhythm, diction, or any deep writing mechanics question.
prose-mechanics
Use when writing, editing, or analyzing prose style; when trying to avoid generic AI-sounding writing; when applying specific prose styles such as journalistic, academic, narrative, KJV biblical, Hemingway plain, Latinate/Jamesian, Orwellian, Augustan, Victorian, Early Modern (Bacon, Browne, Milton), or free indirect discourse; or when coaching someone on writing voice and mechanics. Triggers on any request to improve, analyze, or write in a specific prose style, to fix "AI-sounding" writing, to make prose more vivid or concrete, to vary sentence rhythm, or to understand how a particular writer achieves their effects.
narrative-structure
Use when structuring stories, pitches, presentations, white papers, or any persuasive narrative; analyzing the hero's journey in fiction or non-fiction; applying StoryBrand for business communication; designing narrative arcs for thought leadership; or understanding Vogler, Snyder, Propp, or Campbell frameworks. Triggers on any narrative structure, storytelling, pitch structure, StoryBrand, hero's journey, three-act structure, Freytag, Save the Cat, narrative arc, or "how should I structure this story/pitch/presentation" request.
legal-brief-writing
Use when writing legal briefs, motions, or any court filing; when analyzing judicial cognition and persuasion; when applying elite brief-writing techniques from Roberts, Clement, Kagan, Garner; or when structuring legal arguments for maximum persuasion. Also use for autistic/neurodivergent advocates who need to understand how their natural communication style maps to elite legal advocacy. Triggers on any legal writing, brief drafting, motion preparation, or legal argument structuring request.
journal-publishability-criteria
Use whenever a research paper, article or preprint is being written, revised, reviewed or published, and specifically before every publication of docs/paper.md. Covers what legitimate journals actually gate on, in order of gating — the editor's desk screen (scope, novelty, package problems), what reviewers judge (methodological soundness, claims the evidence can carry, statistical and qualitative reporting), EQUATOR reporting guidelines, the ICMJE authorship criteria, COPE's view of text recycling, the near-universal generative-AI policy (no AI author, disclosure, author responsibility), TOP 2025 transparency standards, how to verify a journal is legitimate, submitting without an institution, and a pre-submission checklist. Triggers on requests to evaluate, review, prepare or submit a paper, to judge publishability, to write a declarations or data-availability section, to disclose AI use, or to check a journal.