Merge #15223: Doc: add information about security to the JSON-RPC doc
5a5ea93e87
Doc: add information about security to the JSON-RPC doc (David A. Harding)
Pull request description:
This documents some information about using the RPC interface securely, as suggested in https://github.com/bitcoin-core/bitcoincore.org/pull/637 by @luke-jr and @TheBlueMatt. I think it should fit in well with #14458, but is not dependent on it (and shouldn't have any significant merge conflicts with it).
Tree-SHA512: e09d82c3029ed17a8bcf50722ea25a8c6c514731f3bce01908cbb6fe48bc96a3068a025beabebc602d18e1bc0dc3f2602848abc05dca1d3efe2a988ee50068c0
This commit is contained in:
commit
5eb32d2384
1 changed files with 79 additions and 0 deletions
|
@ -5,6 +5,85 @@ The headless daemon `bitcoind` has the JSON-RPC API enabled by default, the GUI
|
||||||
option. In the GUI it is possible to execute RPC methods in the Debug Console
|
option. In the GUI it is possible to execute RPC methods in the Debug Console
|
||||||
Dialog.
|
Dialog.
|
||||||
|
|
||||||
|
## Security
|
||||||
|
|
||||||
|
The RPC interface allows other programs to control Bitcoin Core,
|
||||||
|
including the ability to spend funds from your wallets, affect consensus
|
||||||
|
verification, read private data, and otherwise perform operations that
|
||||||
|
can cause loss of money, data, or privacy. This section suggests how
|
||||||
|
you should use and configure Bitcoin Core to reduce the risk that its
|
||||||
|
RPC interface will be abused.
|
||||||
|
|
||||||
|
- **Securing the executable:** Anyone with physical or remote access to
|
||||||
|
the computer, container, or virtual machine running Bitcoin Core can
|
||||||
|
compromise either the whole program or just the RPC interface. This
|
||||||
|
includes being able to record any passphrases you enter for unlocking
|
||||||
|
your encrypted wallets or changing settings so that your Bitcoin Core
|
||||||
|
program tells you that certain transactions have multiple
|
||||||
|
confirmations even when they aren't part of the best block chain. For
|
||||||
|
this reason, you should not use Bitcoin Core for security sensitive
|
||||||
|
operations on systems you do not exclusively control, such as shared
|
||||||
|
computers or virtual private servers.
|
||||||
|
|
||||||
|
- **Securing local network access:** By default, the RPC interface can
|
||||||
|
only be accessed by a client running on the same computer and only
|
||||||
|
after the client provides a valid authentication credential (username
|
||||||
|
and passphrase). Any program on your computer with access to the file
|
||||||
|
system and local network can obtain this level of access.
|
||||||
|
Additionally, other programs on your computer can attempt to provide
|
||||||
|
an RPC interface on the same port as used by Bitcoin Core in order to
|
||||||
|
trick you into revealing your authentication credentials. For this
|
||||||
|
reason, it is important to only use Bitcoin Core for
|
||||||
|
security-sensitive operations on a computer whose other programs you
|
||||||
|
trust.
|
||||||
|
|
||||||
|
- **Securing remote network access:** You may optionally allow other
|
||||||
|
computers to remotely control Bitcoin Core by setting the `rpcallowip`
|
||||||
|
and `rpcbind` configuration parameters. These settings are only meant
|
||||||
|
for enabling connections over secure private networks or connections
|
||||||
|
that have been otherwise secured (e.g. using a VPN or port forwarding
|
||||||
|
with SSH or stunnel). **Do not enable RPC connections over the public
|
||||||
|
Internet.** Although Bitcoin Core's RPC interface does use
|
||||||
|
authentication, it does not use encryption, so your login credentials
|
||||||
|
are sent as clear text that can be read by anyone on your network
|
||||||
|
path. Additionally, the RPC interface has not been hardened to
|
||||||
|
withstand arbitrary Internet traffic, so changing the above settings
|
||||||
|
to expose it to the Internet (even using something like a Tor hidden
|
||||||
|
service) could expose you to unconsidered vulnerabilities. See
|
||||||
|
`bitcoind -help` for more information about these settings and other
|
||||||
|
settings described in this document.
|
||||||
|
|
||||||
|
Related, if you use Bitcoin Core inside a Docker container, you may
|
||||||
|
need to expose the RPC port to the host system. The default way to
|
||||||
|
do this in Docker also exposes the port to the public Internet.
|
||||||
|
Instead, expose it only on the host system's localhost, for example:
|
||||||
|
`-p 127.0.0.1:8332:8332`
|
||||||
|
|
||||||
|
- **Secure authentication:** By default, Bitcoin Core generates unique
|
||||||
|
login credentials each time it restarts and puts them into a file
|
||||||
|
readable only by the user that started Bitcoin Core, allowing any of
|
||||||
|
that user's RPC clients with read access to the file to login
|
||||||
|
automatically. The file is `.cookie` in the Bitcoin Core
|
||||||
|
configuration directory, and using these credentials is the preferred
|
||||||
|
RPC authentication method. If you need to generate static login
|
||||||
|
credentials for your programs, you can use the script in the
|
||||||
|
`share/rpcauth` directory in the Bitcoin Core source tree. As a final
|
||||||
|
fallback, you can directly use manually-chosen `rpcuser` and
|
||||||
|
`rpcpassword` configuration parameters---but you must ensure that you
|
||||||
|
choose a strong and unique passphrase (and still don't use insecure
|
||||||
|
networks, as mentioned above).
|
||||||
|
|
||||||
|
- **Secure string handling:** The RPC interface does not guarantee any
|
||||||
|
escaping of data beyond what's necessary to encode it as JSON,
|
||||||
|
although it does usually provide serialized data using a hex
|
||||||
|
representation of the bytes. If you use RPC data in your programs or
|
||||||
|
provide its data to other programs, you must ensure any problem
|
||||||
|
strings are properly escaped. For example, multiple websites have
|
||||||
|
been manipulated because they displayed decoded hex strings that
|
||||||
|
included HTML `<script>` tags. For this reason, and other
|
||||||
|
non-security reasons, it is recommended to display all serialized data
|
||||||
|
in hex form only.
|
||||||
|
|
||||||
## RPC consistency guarantees
|
## RPC consistency guarantees
|
||||||
|
|
||||||
State that can be queried via RPCs is guaranteed to be at least up-to-date with
|
State that can be queried via RPCs is guaranteed to be at least up-to-date with
|
||||||
|
|
Loading…
Add table
Reference in a new issue