doc: clarify why Tor connections use plain TCP on port 50001#1290
Open
PeterXMR wants to merge 1 commit into
Open
doc: clarify why Tor connections use plain TCP on port 50001#1290PeterXMR wants to merge 1 commit into
PeterXMR wants to merge 1 commit into
Conversation
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #1144.
#1144 reports a confusion: this repository's
doc/config.mdTor section instructs users to connect with<onion>.onion:50001:tover SOCKS9050, while external guides such as raspiblitz's terminal UI document the connection as<onion>.onion:50002:sover SOCKS9150. The user asked which is correct.The answer
doc/config.mdis correct as written:electrshas no native TLS support (verified: norustls/openssl/TLS-related dependency inCargo.toml, andsrc/server.rsonly emits a warning when a client tries to connect with SSL). Port50002with the:ssuffix only works if an external TLS terminator like nginx/stunnel sits in front, which the SSL-connection section already covers.electrsthrough an.onionaddress: 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.9050is the standalonetordaemon's SOCKS port. Port9150is 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.mdonly — a +4/-2 prose adjustment:50001+:tis correct (no native TLS inelectrs), why TLS is generally unnecessary over an.onionendpoint (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.9150for users proxying through the Tor Browser bundle, in addition to the existing9050for the standalonetordaemon.Why this is the right scope
I deliberately kept this to docs-only and minimal. Two alternatives I considered and rejected:
electrsso the:sform Just Works. Out of scope for Docs: tor onion address confusion about port #1144, and adds significant new dependency surface (rustls/openssl).doc/tor.mdstandalone guide. Heavier than the issue calls for and would duplicate parts ofdoc/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).#tor-hidden-serviceand#ssl-connectionboth resolve to existing### …headers in the file.