http: Restore requirement of IPv4 bind success #36187

hodlinator commented at 7:51 PM on September 7, 2026: contributor

Problem

When bitcoind starts and the HTTP IPv4 listen address is occupied by another process, but the IPv6 address is available, the server fails open and generates a cookie file. When bitcoin-cli runs it picks up the cookie file and sends the credentials in plain text to the non-bitcoind process running on the default IPv4 port. An attacker can then use the credentials to commandeer bitcoind over IPv6.

Solution

Safe defaults:

When running with default settings, require that the IPv4 bind succeeds.
When -rpcbind is specified, require that all HTTP listen socket binds succeed (fail closed-behavior).

Node runners who only have IPv6 are now required to override -rpcbind to only specify the working interface if they were not doing so already.

The problem of bitcoin-cli sending the credentials to what could possibly be the wrong process remains only in non-default setups.

History

40b556d3742a1f65d67e2d4c760d0b13fe8be5b7 from 2015 switched the HTTP server from Boost Asio to LibEvent, and binding switched from an attempt at dual-binding IPv4+v6 and falling back to IPv4-only (rpcserver.cpp / StartRPCThreads()), to binding IPv4 or IPv6 (httpserver.cpp / HTTPBindAddresses()). The current PR restores the prior behavior of IPv4 being mandatory.

#14968 from 2018 was an attempt to change the behavior to require all binds to succeed. But it ran into issues with poor IPv6 support on CI.

Severity

This credential exfiltration attack requires capability to launch processes on the bitcoind host. If we are on the same account we can already read the cookie credentials off disk. So it's only really interesting when an attacker is on a different user account on the same host.

Disclaimer

The 2 commits with multiple authors were probably initially generated with the help of silicon LLMs.

DrahtBot added the label RPC/REST/ZMQ on Sep 7, 2026

DrahtBot commented at 7:51 PM on September 7, 2026: contributor

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

Code Coverage & Benchmarks

For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/36187.

Reviews

See the guideline and AI policy for information on the review process.

Type	Reviewers
Concept ACK	l0rinc, janb84, sedited, winterrdog

If your review is incorrectly listed, please copy-paste <code></code> into the comment that the bot should ignore.

Conflicts

No conflicts as of last run.

l0rinc commented at 7:55 PM on September 7, 2026: contributor

Concept ACK, thanks for pushing the fix

hodlinator marked this as a draft on Sep 7, 2026

hodlinator renamed this:
~~http: Require all binds to succeed~~
http: Require default IPv4 bind to succeed (again)
on Sep 7, 2026

hodlinator commented at 8:07 PM on September 7, 2026: contributor

For some reason thought that we weren't enabling the HTTP subsystem by default. Going to re-work the code slightly. Put in draft.

hodlinator force-pushed on Sep 7, 2026

DrahtBot added the label CI failed on Sep 7, 2026

DrahtBot removed the label CI failed on Sep 7, 2026

hodlinator marked this as ready for review on Sep 8, 2026

hodlinator force-pushed on Sep 8, 2026

in test/functional/rpc_bind.py:123 in 64fd5cef0c

 118 | +                self.cleanup_partially_started_nodes()
 119 | +        self.nodes[0].rpchost = None
 120 | +
 121 | +        assert_equal(started, False)
 122 | +        assert_equal(credential_captured, False)
 123 | +        assert started or 'Unable to start HTTP server' in error

janb84 commented at 9:18 AM on September 8, 2026:

NIT: Leftover assert on started, Line 121 asserts that started is false so started cannot be true at this point.

        assert 'Unable to start HTTP server' in error

in src/httpserver.cpp:230 in 64fd5cef0c outdated

 228 | -        endpoints.emplace_back("::1", http_port);
 229 | +        // We allow the default IPv6 bind to fail, but IPv4 is required even
 230 | +        // with the default port as bitcoin-cli will default to handing RPC
 231 | +        // credentials in plaintext to whatever process is running on that port.
 232 | +        endpoints.push_back({.address = "::1", .port = http_port, .required = false});
 233 |          endpoints.emplace_back("127.0.0.1", http_port);

janb84 commented at 9:48 AM on September 8, 2026:

NIT: I would keep the style of the 2 lines the same (helps the OCD people)

        endpoints.push_back({.address = "127.0.0.1", .port = http_port});

hodlinator commented at 7:19 PM on September 8, 2026:

Will do if others agree, holding off for now.

winterrdog commented at 10:39 PM on September 10, 2026:

one of the "others" has arrived 😁

anyway, i agree with @janb84

when i first looked at the code, i thought there might be a subtle reason for using one over the other, but later on i realised they do the same thing. so i think sticking to the same pattern makes sense. whether you use emplace_back() or push_back() is up to you, as long as there is some symmetry

in src/httpserver.cpp:1366 in 64fd5cef0c

1366 |              if (!result) {
1367 | -                LogWarning("Binding RPC on address %s failed: %s", addr->ToStringAddrPort(), result.error());
1368 | +                LogWarning("Binding %s RPC on address %s failed: %s",
1369 | +                           required ? "required" : "optional",
1370 | +                           addr->ToStringAddrPort(), result.error());
1371 | +                if (required) required_failure = true;

janb84 commented at 10:25 AM on September 8, 2026:

non blocking, micro nit: Currently even the required entry/bindings failure only logs as a LogWarning. Is that the correct level for something that aborts startup ?

if (required) {
    LogError("Binding required RPC endpoint %s failed: %s", addr->ToStringAddrPort(), result.error());
    required_failure = true;
} else {
    LogWarning("Binding optional RPC endpoint %s failed: %s", addr->ToStringAddrPort(), result.error());
}

janb84 commented at 10:27 AM on September 8, 2026: contributor

Concept ACK 64fd5cef0c938d3d1e7f69d6be2f255b6eafc1e2

Looks good, some suggestion NITS.

NITl Commit message of c309e5fb73 has a typo / grammar issue "and without this change that one would Mac CI would fail with:"

test: characterize partial HTTP binds

When the IPv4 RPC address is already owned, the server starts on its remaining IPv6 listener for both default and explicit bind configurations. bitcoin-cli then sends the generated cookie to the other process on its default IPv4 destination.

Record the partial startup and exact captured Authorization credential for the following fail-closed fix.

75e77e7073

hodlinator force-pushed on Sep 8, 2026

test: Remove attempt to bind RPC to 127.1.1.1

The next commit requires all binds to succeed, and without this change that one would fail on Mac CI with:
[InitHTTPServer] [warning] Binding RPC on address 127.1.1.1:19036 failed: Unable to bind to 127.1.1.1:19036 on this computer (bind returned error Can't assign requested address (49))

The options in this test are there to verify log censorship of sensitive data and bind-addresses were made non-sensitive in #26829 / b9d567454159f062ce84353f5821d6e6daf433bd. That commit added the missing -rpcallowip option to actually make -rpcbind not be ignored any longer. That commit added 127.0.0.1 in addition to the already existing 127.1.1.1, probably because the latter would fail by itself.

32a3c89b99

hodlinator force-pushed on Sep 8, 2026

DrahtBot added the label CI failed on Sep 8, 2026

hodlinator commented at 8:08 PM on September 8, 2026: contributor

Latest push addresses all but 1 comment from #36187#pullrequestreview-5139772278

DrahtBot removed the label CI failed on Sep 8, 2026

sedited commented at 3:28 PM on September 9, 2026: contributor

Concept ACK

in src/httpserver.cpp:1392 in 690a4b1a6c

1393 |      if (!bind_success) {
1394 |          LogError("Unable to bind any endpoint for RPC server");
1395 |          return false;
1396 | +    } else if (required_failure) {
1397 | +        g_http_server->StopListening();
1398 | +        LogError("Unable to bind all required endpoints for RPC server");

winterrdog commented at 10:23 PM on September 10, 2026:

from the PR description:

Node runners who only have IPv6 are now required to override -rpcbind to only specify the working interface if they were not doing so already.

can we make the IPv6-only case a bit more actionable in the error message ?

with the new defaults, an IPv6-only host will fail because the required 127.0.0.1 bind will never succeed, but the user may not know that they need to override -rpcbind to use only their IPv6 address. mayhaps the error could point them towards -rpcbind rather than just reporting that a required endpoint failed

i was thinking of sth like (feel free to put a spin to it):

        LogError("Unable to bind all required endpoints for RPC server. If this host does not support IPv4, specify the IPv6 RPC address with -rpcbind.");

hodlinator commented at 11:10 AM on September 11, 2026:

Good point. Default behavior for IPv6-only hosts should at least be to get an informative error message.

winterrdog commented at 10:40 PM on September 10, 2026: contributor

concept ACK

this makes sense since bitcoin-cli defaults to IPv4, so bitcoind should have a corresponding IPv4 listener, already working by default as well

http: fail closed on partial binds

When any RPC bind succeeds, initialization ignores every other endpoint failure. A process that already owns the default IPv4 port can therefore receive bitcoin-cli credentials while the node continues on IPv6.

Switch to safe defaults through only making the default IPv6 address optional, requiring all others. Hosts intentionally providing only an IPv6 interface must use -rpcbind to set that endpoint explicitly.

This carries the fail-closed policy from bitcoin/bitcoin#14968 now that the in-tree socket implementation reports each bind result.

Co-authored-by: laanwj <126646+laanwj@users.noreply.github.com>
Co-authored-by: Lőrinc <pap.lorinc@gmail.com>

4a92148470

http: Only log *unique* attempts to bind to *resolved addresses*

Also:
* Document why it's not worth logging endpoints_seen collisions
* Make lookup error more explanatory (helps explain why this fails: bitcoind -rpcbind=localhost -rpcallowip=127.0.0.1)

05de7be9d7

hodlinator force-pushed on Sep 11, 2026

hodlinator commented at 11:13 AM on September 11, 2026: contributor

Latest push avoids stringly typing endpoints_seen and addresses points from #36187#pullrequestreview-5172841125.

hodlinator commented at 9:40 AM on September 21, 2026: contributor

Updated PR description, primarily the History-section.

hodlinator renamed this:
~~http: Require default IPv4 bind to succeed (again)~~
http: Restore requirement of IPv4 bind success
on Sep 21, 2026