Enable PoW defenses for hidden services that we create via Tor Control using the ADD_ONION command.
The ability to do that has been added in tor-0.4.9.2-alpha. Previous versions return a syntax error to the ADD_ONION command with PoWDefensesEnabled=1, so the approach here is to try with PoW and if we get syntax error, then retry without PoW.
Also update doc/tor.md with a hint on enabling PoW on manually configured Tor hidden services.
<!--e57a25ab6845829454e8d69fc972939a-->
The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.
<!--006a51241073e994b41acfe9ec718e94-->
For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/33414.
<!--021abf342d371248e50ceaed478a90ca-->
See the guideline for information on the review process.
| Type | Reviewers |
|---|---|
| ACK | willcl-ark, fjahr, sedited |
If your review is incorrectly listed, please copy-paste <code><!--meta-tag:bot-skip--></code> into the comment that the bot should ignore.
<!--174a7506f384e20aa4161008e828411d-->
Reviewers, this pull request conflicts with the following ones:
If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.
<!--5faf32d7da4f0f540f40219e4f7537a3-->
Should we then also add PoW to the connections that we make to other nodes running behind hidden services?
Should we then also add PoW to the connections that we make to other nodes running behind hidden services?
Reading the linked FAQ, the feature still supports "older clients" (which don't have PoW defence capability), but they may take a lower priority when a service considers itself under DoS. So no PoW is required on the client side.
When the client-side tor is new-enough, my understanding is that the puzzle-solving is automatically handled by Tor, and doesn't need client-side changes to the connection code, as it happens during the introduction. But I am not 100% certain.
What is the status of this?
I think tor_control_reply_code = 512 could be added here, to hit this expected path more frequently than random?
Right, good catch! Done and also moved the TOR_REPLY_* constants to torcontrol.h so this fuzz test can use them instead of hardcoding numbers. Thanks!
Approach and lightly-tested ACK on PoW-enabled Tor (version 0.4.8.22).
2026-02-16T21:44:26Z [tor] Get SOCKS port command yielded 127.0.0.1:9050
2026-02-16T21:44:26Z [tor] Configuring onion proxy for 127.0.0.1:9050
2026-02-16T21:44:26Z [tor] ADD_ONION failed with PoW defenses, retrying without
2026-02-16T21:44:26Z [tor] ADD_ONION successful (PoW defenses disabled)
Seems very reasonable to me to implement this configuration in order that we fare better during DoS attacks on the Tor network. Noting for others that as far as I read, due to the dynamic difficulty the (tor) PoW is ~ free on idle, and the cost only applies during an attack, which seems nice.
I quite like the pragmatism of "detecting" the tor version via the failure mode. It appears that the 512 failure happens early on the Tor side, before any service is created. So failing and retrying is "clean".
What is the status of this?
Looks like it needs a pretty trivial rebase at the moment is all.
8a526d39d8a00edff2361ceaa012574d1337b77b...206da5e5e420ab43857e4d15ddb7d1c603d6e762: rebase due to conflicts
What is the status of this?
Needed a rebase.
`src/torcontrol.cpp` used to define some constants that are used
explicitly in `src/torcontrol.cpp` and implicitly in
`src/test/fuzz/torcontrol.cpp` by duplicating their values.
Move the constants to `src/torcontrol.h` and reuse them in
`src/test/fuzz/torcontrol.cpp` to avoid duplication and magic
numbers.
Enable PoW defenses [1] for hidden services that we create via
Tor Control using the `ADD_ONION` command [2].
The ability to do that has been added in tor-0.4.9.2-alpha [3]. Previous
versions return a syntax error to the `ADD_ONION` command with
`PoWDefensesEnabled=1`, so the approach here is to try with PoW and if
we get syntax error, then retry without PoW.
[1] https://tpo.pages.torproject.net/onion-services/ecosystem/technology/security/pow/
[2] https://spec.torproject.org/control-spec/commands.html#add_onion
[3] https://gitlab.torproject.org/tpo/core/tor/-/commit/02c18044464bfe45f168b55297a785244094cfd5
206da5e5e420ab43857e4d15ddb7d1c603d6e762...c68e3d2c57dcab5cea22ad5986fcd2b147a7daaa: address suggestion
Great, the range-diff looks good:
<details> <summary>Details</summary>
git range-diff 2d6a0c464912c325faf35d4ad28b1990e828b414..8a526d3 8ee24d764a2820259fe42f8def93fd8a2c36a4cf..c68e3d2c57d
-: ----------- > 1: fb993f76047 tor, fuzz: reuse constants instead of duplicating
1: 5aefa080178 ! 2: 4c6798a3d38 tor: enable PoW defenses for automatically created hidden services
@@ Commit message
[3] https://gitlab.torproject.org/tpo/core/tor/-/commit/02c18044464bfe45f168b55297a785244094cfd5
## src/test/fuzz/torcontrol.cpp ##
+@@ src/test/fuzz/torcontrol.cpp: FUZZ_TARGET(torcontrol, .init = initialize_torcontrol)
+ [&] {
+ tor_control_reply.code = TOR_REPLY_UNRECOGNIZED;
+ },
++ [&] {
++ tor_control_reply.code = TOR_REPLY_SYNTAX_ERROR;
++ },
+ [&] {
+ tor_control_reply.code = fuzzed_data_provider.ConsumeIntegral<int>();
+ });
@@ src/test/fuzz/torcontrol.cpp: FUZZ_TARGET(torcontrol, .init = initialize_torcontrol)
CallOneOf(
fuzzed_data_provider,
@@ src/test/fuzz/torcontrol.cpp: FUZZ_TARGET(torcontrol, .init = initialize_torcont
tor_controller.auth_cb(dummy_tor_control_connection, tor_control_reply);
## src/torcontrol.cpp ##
-@@ src/torcontrol.cpp: static const int TOR_NONCE_SIZE = 32;
- /** Tor control reply code. Ref: https://spec.torproject.org/control-spec/replies.html */
- static const int TOR_REPLY_OK = 250;
- static const int TOR_REPLY_UNRECOGNIZED = 510;
-+static const int TOR_REPLY_SYNTAX_ERROR = 512; //!< Syntax error in command argument
- /** For computing serverHash in SAFECOOKIE */
- static const std::string TOR_SAFE_SERVERKEY = "Tor safe cookie authentication server-to-controller hash";
- /** For computing clientHash in SAFECOOKIE */
@@ src/torcontrol.cpp: void TorController::get_socks_cb(TorControlConnection& _conn, const TorControlRe
}
}
@@ src/torcontrol.cpp: void TorController::get_socks_cb(TorControlConnection& _conn
@@ src/torcontrol.cpp: void TorController::add_onion_cb(TorControlConnection& _conn, const TorControlRe
// ... onion requested - keep connection open
} else if (reply.code == TOR_REPLY_UNRECOGNIZED) {
- LogPrintf("tor: Add onion failed with unrecognized command (You probably need to upgrade Tor)\n");
+ LogWarning("tor: Add onion failed with unrecognized command (You probably need to upgrade Tor)");
+ } else if (pow_was_enabled && reply.code == TOR_REPLY_SYNTAX_ERROR) {
+ LogDebug(BCLog::TOR, "ADD_ONION failed with PoW defenses, retrying without");
+ _conn.Command(MakeAddOnionCmd(private_key, m_target.ToStringAddrPort(), /*enable_pow=*/false),
-+ std::bind(&TorController::add_onion_cb,
-+ this,
-+ std::placeholders::_1,
-+ std::placeholders::_2,
-+ /*pow_was_enabled=*/false));
++ [this](TorControlConnection& conn, const TorControlReply& reply) {
++ add_onion_cb(conn, reply, /*pow_was_enabled=*/false);
++ });
} else {
- LogPrintf("tor: Add onion failed; error code %d\n", reply.code);
+ LogWarning("tor: Add onion failed; error code %d", reply.code);
}
@@ src/torcontrol.cpp: void TorController::auth_cb(TorControlConnection& _conn, const TorControlReply&
private_key = "NEW:ED25519-V3"; // Explicitly request key type - see issue [#9214](/bitcoin-bitcoin/9214/)
@@ src/torcontrol.cpp: void TorController::auth_cb(TorControlConnection& _conn, con
// Request onion service, redirect port.
- // Note that the 'virtual' port is always the default port to avoid decloaking nodes using other ports.
- _conn.Command(strprintf("ADD_ONION %s Port=%i,%s", private_key, Params().GetDefaultPort(), m_target.ToStringAddrPort()),
-- std::bind(&TorController::add_onion_cb, this, std::placeholders::_1, std::placeholders::_2));
+- std::bind_front(&TorController::add_onion_cb, this));
+ _conn.Command(MakeAddOnionCmd(private_key, m_target.ToStringAddrPort(), /*enable_pow=*/true),
-+ std::bind(&TorController::add_onion_cb,
-+ this,
-+ std::placeholders::_1,
-+ std::placeholders::_2,
-+ /*pow_was_enabled=*/true));
++ [this](TorControlConnection& conn, const TorControlReply& reply) {
++ add_onion_cb(conn, reply, /*pow_was_enabled=*/true);
++ });
} else {
- LogPrintf("tor: Authentication failed\n");
+ LogWarning("tor: Authentication failed");
}
## src/torcontrol.h ##
+@@ src/torcontrol.h: static const bool DEFAULT_LISTEN_ONION = true;
+ /** Tor control reply code. Ref: https://spec.torproject.org/control-spec/replies.html */
+ constexpr int TOR_REPLY_OK{250};
+ constexpr int TOR_REPLY_UNRECOGNIZED{510};
++constexpr int TOR_REPLY_SYNTAX_ERROR{512}; //!< Syntax error in command argument
+
+ void StartTorControl(CService onion_service_target);
+ void InterruptTorControl();
@@ src/torcontrol.h: public:
/** Callback for GETINFO net/listeners/socks result */
void get_socks_cb(TorControlConnection& conn, const TorControlReply& reply);
2: a61080aef87 = 3: 4bae84c94af doc: add a hint to enable PoW defenses to manual hidden services
3: 8a526d39d8a = 4: c68e3d2c57d doc: add release notes for Tor PoW defenses
</details>
Just realised though that my tor, although it has PoWDefenses compiled in, does not support it via ADD_ONION yet
❯ tor --list-modules
relay: yes
dirauth: yes
dircache: yes
pow: yes
❯ nc 127.0.0.1 9051
AUTHENTICATE ""
250 OK
ADD_ONION NEW:ED25519-V3 PoWDefensesEnabled=1 Port=38333,127.0.0.1:38333
512 Bad arguments to ADD_ONION: Unrecognized keyword argument "PoWDefensesEnabled"
I think it might only be for pre-configured services unti addition to the ONION keyword in 0.4.9.5. That said, it does show the fallback mechanism, even in this edge case, works as intended... (and in fact that querying the binary modules would have been a bug here?).
and in fact that querying the binary modules would have been a bug here?
I think yes, better to actually check if the ADD_ONION command supports pow (like in this PR).
ACK c68e3d2c57dcab5cea22ad5986fcd2b147a7daaa
Tested with two versions of tor. ON 0.4.8.22 automatic PoWDefense via ONION message (correctly) does not work and falls back to without.
On 0.4.9.5 I see:
2026-02-19T12:04:04Z torcontrol thread start
2026-02-19T12:04:04Z [tor] Reading cached private key from /xxxxxxxx/onion_v3_private_key
2026-02-19T12:04:04Z [tor] Successfully connected!
2026-02-19T12:04:04Z [tor] Connected to Tor version 0.4.9.5
2026-02-19T12:04:04Z [tor] Supported authentication method: NULL
2026-02-19T12:04:04Z [tor] Using NULL authentication
2026-02-19T12:04:04Z [tor] Authentication successful
2026-02-19T12:04:04Z [tor] Get SOCKS port command yielded 127.0.0.1:9050
2026-02-19T12:04:04Z [tor] Configuring onion proxy for 127.0.0.1:9050
2026-02-19T12:04:04Z [tor] ADD_ONION successful (PoW defenses enabled)
The changes look clean and correct to me.
Concept ACK
180 | @@ -181,6 +181,10 @@ Add these lines to your `/etc/tor/torrc` (or equivalent config file): 181 | 182 | HiddenServiceDir /var/lib/tor/bitcoin-service/ 183 | HiddenServicePort 8333 127.0.0.1:8334 184 | + # If `tor --list-modules` shows "pow: yes", then enable PoW protection. 185 | + # It is available in tor-0.4.8.1-alpha and newer when configured with
In the PR description you say that it has been available since 0.4.9.2-alpha. Does this mean something different or is this an inconsistency?
It means something different.
First in 0.4.8.1-alpha PoW defenses were added. This makes it possible to put HiddenServicePoWDefensesEnabled in torrc which our doc/tor.md advises here. Still with that change it was not possible to enable PoW for services that are created dynamically via the Tor server (instead of configured in torrc).
Then in 0.4.9.2-alpha it was made possible to enable PoW also for the programatically created services: ADD_ONION ... PoWDefensesEnabled.
422 | @@ -423,10 +423,20 @@ void TorController::get_socks_cb(TorControlConnection& _conn, const TorControlRe 423 | } 424 | } 425 | 426 | -void TorController::add_onion_cb(TorControlConnection& _conn, const TorControlReply& reply) 427 | +static std::string MakeAddOnionCmd(const std::string& private_key, const std::string& target, bool enable_pow)
nit: Could have made this a member function of TorController to avoid having to pass private_key and target.
Right! Here is a diff for that:
<details> <summary>make member function</summary>
diff --git i/src/torcontrol.cpp w/src/torcontrol.cpp
index b948de3e5b..77227112b2 100644
--- i/src/torcontrol.cpp
+++ w/src/torcontrol.cpp
@@ -420,20 +420,20 @@ void TorController::get_socks_cb(TorControlConnection& _conn, const TorControlRe
// If NET_ONION is not reachable, then none of -proxy or -onion was given.
// Since we are here, then -torcontrol and -torpassword were given.
g_reachable_nets.Add(NET_ONION);
}
}
-static std::string MakeAddOnionCmd(const std::string& private_key, const std::string& target, bool enable_pow)
+std::string TorController::make_add_onion_cmd(bool enable_pow) const
{
// Note that the 'virtual' port is always the default port to avoid decloaking nodes using other ports.
return strprintf("ADD_ONION %s%s Port=%i,%s",
private_key,
enable_pow ? " PoWDefensesEnabled=1" : "",
Params().GetDefaultPort(),
- target);
+ m_target.ToStringAddrPort());
}
void TorController::add_onion_cb(TorControlConnection& _conn, const TorControlReply& reply, bool pow_was_enabled)
{
if (reply.code == TOR_REPLY_OK) {
LogDebug(BCLog::TOR, "ADD_ONION successful (PoW defenses %s)", pow_was_enabled ? "enabled" : "disabled");
@@ -462,13 +462,13 @@ void TorController::add_onion_cb(TorControlConnection& _conn, const TorControlRe
AddLocal(service, LOCAL_MANUAL);
// ... onion requested - keep connection open
} else if (reply.code == TOR_REPLY_UNRECOGNIZED) {
LogWarning("tor: Add onion failed with unrecognized command (You probably need to upgrade Tor)");
} else if (pow_was_enabled && reply.code == TOR_REPLY_SYNTAX_ERROR) {
LogDebug(BCLog::TOR, "ADD_ONION failed with PoW defenses, retrying without");
- _conn.Command(MakeAddOnionCmd(private_key, m_target.ToStringAddrPort(), /*enable_pow=*/false),
+ _conn.Command(make_add_onion_cmd(/*enable_pow=*/false),
[this](TorControlConnection& conn, const TorControlReply& reply) {
add_onion_cb(conn, reply, /*pow_was_enabled=*/false);
});
} else {
LogWarning("tor: Add onion failed; error code %d", reply.code);
}
@@ -487,13 +487,13 @@ void TorController::auth_cb(TorControlConnection& _conn, const TorControlReply&
// Finally - now create the service
if (private_key.empty()) { // No private key, generate one
private_key = "NEW:ED25519-V3"; // Explicitly request key type - see issue [#9214](/bitcoin-bitcoin/9214/)
}
// Request onion service, redirect port.
- _conn.Command(MakeAddOnionCmd(private_key, m_target.ToStringAddrPort(), /*enable_pow=*/true),
+ _conn.Command(make_add_onion_cmd(/*enable_pow=*/true),
[this](TorControlConnection& conn, const TorControlReply& reply) {
add_onion_cb(conn, reply, /*pow_was_enabled=*/true);
});
} else {
LogWarning("tor: Authentication failed");
}
diff --git i/src/torcontrol.h w/src/torcontrol.h
index b8a1d6540b..1d4f1581fd 100644
--- i/src/torcontrol.h
+++ w/src/torcontrol.h
@@ -139,12 +139,14 @@ private:
/** ClientNonce for SAFECOOKIE auth */
std::vector<uint8_t> clientNonce;
public:
/** Callback for GETINFO net/listeners/socks result */
void get_socks_cb(TorControlConnection& conn, const TorControlReply& reply);
+ /** Create the "ADD_ONION ..." command with enabled PoW defenses if `enable_pow` is `true`. */
+ std::string make_add_onion_cmd(bool enable_pow) const;
/** Callback for ADD_ONION result */
void add_onion_cb(TorControlConnection& conn, const TorControlReply& reply, bool pow_was_enabled);
/** Callback for AUTHENTICATE result */
void auth_cb(TorControlConnection& conn, const TorControlReply& reply);
/** Callback for AUTHCHALLENGE result */
void authchallenge_cb(TorControlConnection& conn, const TorControlReply& reply);
</details>
I think this is worth including, but this PR has a few ACKs already. Include it?
As you like, I can re-ack quickly but you can also leave it as is. It was just a minor style-nit.
Merged now, leaving it as it is.
tACK c68e3d2c57dcab5cea22ad5986fcd2b147a7daaa
Only tested that PoW enable worked with the latest tor version (0.4.9.5), not the fallback with an older tor version. Code looks good, note to self: I will extend the test coverage in #34158 with additional coverage for this.
ACK c68e3d2c57dcab5cea22ad5986fcd2b147a7daaa