Skip to content

doc: clarify why Tor connections use plain TCP on port 50001#1290

Open
PeterXMR wants to merge 1 commit into
romanz:masterfrom
PeterXMR:fix-tor-docs-1144
Open

doc: clarify why Tor connections use plain TCP on port 50001#1290
PeterXMR wants to merge 1 commit into
romanz:masterfrom
PeterXMR:fix-tor-docs-1144

Conversation

@PeterXMR
Copy link
Copy Markdown

Closes #1144.

#1144 reports a confusion: this repository's doc/config.md Tor section instructs users to connect with <onion>.onion:50001:t over SOCKS 9050, while external guides such as raspiblitz's terminal UI document the connection as <onion>.onion:50002:s over SOCKS 9150. The user asked which is correct.

The answer

doc/config.md is correct as written:

  • electrs has no native TLS support (verified: no rustls/openssl/TLS-related dependency in Cargo.toml, and src/server.rs only emits a warning when a client tries to connect with SSL). Port 50002 with the :s suffix only works if an external TLS terminator like nginx/stunnel sits in front, which the SSL-connection section already covers.
  • TLS is not required when reaching electrs through an .onion address: the v3 onion address encodes the hidden service's Ed25519 public key, and the Tor rendezvous handshake provides end-to-end authentication and encryption between client and server.
  • Port 9050 is the standalone tor daemon's SOCKS port. Port 9150 is the Tor Browser bundle's SOCKS — that's the one the raspiblitz example uses, because raspiblitz users may be proxying through Tor Browser.

So the contradiction is not in the technical advice — it is in the doc not explaining its choice, and in one earlier sentence flatly stating that plain TCP is "recommended only for local connections", which contradicts the Tor section that follows.

What this PR changes

doc/config.md only — a +4/-2 prose adjustment:

  1. "Connecting an Electrum client" section. Softens the existing "recommended only for local connections" to also acknowledge Tor hidden services as a safe context for plain TCP, with a forward link to the Tor section.
  2. "Tor hidden service" section. Adds one paragraph explaining why port 50001 + :t is correct (no native TLS in electrs), why TLS is generally unnecessary over an .onion endpoint (with a brief, correct one-liner on the v3 onion ↔ Ed25519 public-key relationship), and how to layer TLS on top anyway if a client requires it — by referring to the SSL terminator setup already documented above.
  3. SOCKS port note. Mentions 9150 for users proxying through the Tor Browser bundle, in addition to the existing 9050 for the standalone tor daemon.

Why this is the right scope

I deliberately kept this to docs-only and minimal. Two alternatives I considered and rejected:

  • Add native TLS support to electrs so the :s form Just Works. Out of scope for Docs: tor onion address confusion about port #1144, and adds significant new dependency surface (rustls/openssl).
  • Add a new doc/tor.md standalone guide. Heavier than the issue calls for and would duplicate parts of doc/config.md. The existing structure already has a Tor section; the right fix is to make it self-explanatory.

Verification

  • cargo build — clean (defensive; no code changed).
  • Anchor targets #tor-hidden-service and #ssl-connection both resolve to existing ### … headers in the file.
  • The diff is +4 / -2 lines, all prose.

Issue romanz#1144 reported confusion between this repository's Tor
configuration example (`<onion>.onion:50001:t` over SOCKS port 9050)
and external guides such as raspiblitz's UI which document the
connection as `<onion>.onion:50002:s` (SSL) over SOCKS port 9150.

The current example in `doc/config.md` is correct — `electrs` does
not provide TLS natively, and TLS is not needed when reaching the
server through an `.onion` address — but the document does not
explain that, and the "Connecting an Electrum client" section above
flatly states that plain TCP is "recommended only for local
connections", contradicting the Tor section that follows.

This change:

- Softens the local-connections wording so it also acknowledges Tor
  hidden services as a safe context for plain TCP, with a forward
  link to the Tor section.
- Adds a short paragraph to the Tor section explaining: why port
  `50001` with the `:t` suffix is correct (no native TLS in
  `electrs`), why TLS is generally unnecessary over an `.onion`
  endpoint (v3 onion addresses encode the hidden service's Ed25519
  public key, and the Tor rendezvous handshake provides end-to-end
  authentication and encryption), and how to layer TLS on top
  anyway if a client requires it (via the existing SSL terminator
  setup and `<onion>:50002:s`).
- Notes the SOCKS port distinction between a standalone `tor`
  daemon (`9050`) and the Tor Browser bundle (`9150`), since the
  raspiblitz example referenced in the issue uses the latter.

No code change.

Closes romanz#1144

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Docs: tor onion address confusion about port

1 participant