aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/JSON-RPC-interface.md79
-rw-r--r--doc/REST-interface.md7
-rw-r--r--doc/dependencies.md2
-rw-r--r--doc/developer-notes.md16
-rw-r--r--doc/fuzzing.md2
-rw-r--r--doc/release-notes-14941.md5
-rw-r--r--doc/release-notes-14982.md5
-rw-r--r--doc/release-notes.md14
-rw-r--r--doc/release-process.md2
9 files changed, 130 insertions, 2 deletions
diff --git a/doc/JSON-RPC-interface.md b/doc/JSON-RPC-interface.md
index 59df541567..982afd5d56 100644
--- a/doc/JSON-RPC-interface.md
+++ b/doc/JSON-RPC-interface.md
@@ -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
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
State that can be queried via RPCs is guaranteed to be at least up-to-date with
diff --git a/doc/REST-interface.md b/doc/REST-interface.md
index 44df698382..d21df36130 100644
--- a/doc/REST-interface.md
+++ b/doc/REST-interface.md
@@ -27,6 +27,7 @@ For full TX query capability, one must enable the transaction index via "txindex
`GET /rest/block/notxdetails/<BLOCK-HASH>.<bin|hex|json>`
Given a block hash: returns a block, in binary, hex-encoded binary or JSON formats.
+Responds with 404 if the block doesn't exist.
The HTTP request and response are both handled entirely in-memory, thus making maximum memory usage at least 2.66MB (1 MB max block, plus hex encoding) per request.
@@ -36,6 +37,12 @@ With the /notxdetails/ option JSON response will only contain the transaction ha
`GET /rest/headers/<COUNT>/<BLOCK-HASH>.<bin|hex|json>`
Given a block hash: returns <COUNT> amount of blockheaders in upward direction.
+Returns empty if the block doesn't exist or it isn't in the active chain.
+
+#### Blockhash by height
+`GET /rest/blockhashbyheight/<HEIGHT>.<bin|hex|json>`
+
+Given a height: returns hash of block in best-block-chain at height provided.
#### Chaininfos
`GET /rest/chaininfo.json`
diff --git a/doc/dependencies.md b/doc/dependencies.md
index 50dde02fad..b833e9151f 100644
--- a/doc/dependencies.md
+++ b/doc/dependencies.md
@@ -26,5 +26,5 @@ These are the dependencies currently used by Bitcoin Core. You can find instruct
| Qt | [5.9.7](https://download.qt.io/official_releases/qt/) | [5.2](https://github.com/bitcoin/bitcoin/pull/14725) | No | | |
| XCB | | | | | [Yes](https://github.com/bitcoin/bitcoin/blob/master/depends/packages/qt.mk#L87) (Linux only) |
| xkbcommon | | | | | [Yes](https://github.com/bitcoin/bitcoin/blob/master/depends/packages/qt.mk#L86) (Linux only) |
-| ZeroMQ | [4.2.5](https://github.com/zeromq/libzmq/releases) | 4.0.0 | No | | |
+| ZeroMQ | [4.3.1](https://github.com/zeromq/libzmq/releases) | 4.0.0 | No | | |
| zlib | [1.2.11](https://zlib.net/) | | | | No |
diff --git a/doc/developer-notes.md b/doc/developer-notes.md
index e0def4ea27..ec29310ffe 100644
--- a/doc/developer-notes.md
+++ b/doc/developer-notes.md
@@ -35,6 +35,7 @@ Developer Notes
- [Subtrees](#subtrees)
- [Git and GitHub tips](#git-and-github-tips)
- [Scripted diffs](#scripted-diffs)
+ - [Release notes](#release-notes)
- [RPC interface guidelines](#rpc-interface-guidelines)
<!-- markdown-toc end -->
@@ -874,6 +875,21 @@ test/lint/commit-script-check.sh origin/master..HEAD
Commit [`bb81e173`](https://github.com/bitcoin/bitcoin/commit/bb81e173) is an example of a scripted-diff.
+Release notes
+-------------
+
+Release notes should be written for any PR that:
+
+- introduces a notable new feature
+- fixes a significant bug
+- changes an API or configuration model
+- makes any other visible change to the end-user experience.
+
+Release notes should be added to a PR-specific release note file at
+`/doc/release-notes-<PR number>.md` to avoid conflicts between multiple PRs.
+All `release-notes*` files are merged into a single
+[/doc/release-notes.md](/doc/release-notes.md) file prior to the release.
+
RPC interface guidelines
--------------------------
diff --git a/doc/fuzzing.md b/doc/fuzzing.md
index dff9e71bba..23317e938e 100644
--- a/doc/fuzzing.md
+++ b/doc/fuzzing.md
@@ -82,7 +82,7 @@ make
```
The fuzzer needs some inputs to work on, but the inputs or seeds can be used
-interchangably between libFuzzer and AFL.
+interchangeably between libFuzzer and AFL.
See https://llvm.org/docs/LibFuzzer.html#running on how to run the libFuzzer
instrumented executable.
diff --git a/doc/release-notes-14941.md b/doc/release-notes-14941.md
new file mode 100644
index 0000000000..c3820d0368
--- /dev/null
+++ b/doc/release-notes-14941.md
@@ -0,0 +1,5 @@
+Miscellaneous RPC changes
+------------
+
+- The `unloadwallet` RPC is now synchronous, meaning that it blocks until the
+ wallet is fully unloaded.
diff --git a/doc/release-notes-14982.md b/doc/release-notes-14982.md
new file mode 100644
index 0000000000..3f0bf8aacd
--- /dev/null
+++ b/doc/release-notes-14982.md
@@ -0,0 +1,5 @@
+New RPCs
+--------
+
+- The RPC `getrpcinfo` returns runtime details of the RPC server. At the moment
+ it returns the active commands and the corresponding execution time.
diff --git a/doc/release-notes.md b/doc/release-notes.md
index 5a5a566715..a54b08848f 100644
--- a/doc/release-notes.md
+++ b/doc/release-notes.md
@@ -111,6 +111,14 @@ Configuration option changes
ambiguous whether the hash character is meant for the password or as a
comment.
+- The `whitelistforcerelay` option is used to relay transactions from
+ whitelisted peers even when not accepted to the mempool. This option now
+ defaults to being off, so that changes in policy and disconnect/ban behavior
+ will not cause a node that is whitelisting another to be dropped by peers.
+ Users can still explicitly enable this behavior with the command line option
+ (and may want to consider letting the Bitcoin Core project know about their
+ use-case, as this feature could be deprecated in the future).
+
Documentation
-------------
@@ -268,6 +276,12 @@ Graphical User Interface (GUI)
balance shown if the wallet was created using the `createwallet` RPC
and the `disable_private_keys` parameter was set to true.
+- The launch-on-startup option is no longer available on macOS if
+ compiled with macosx min version greater than 10.11 (use
+ CXXFLAGS="-mmacosx-version-min=10.11"
+ CFLAGS="-mmacosx-version-min=10.11" for setting the deployment
+ sdk version)
+
Low-level changes
=================
diff --git a/doc/release-process.md b/doc/release-process.md
index 3bdbabcf04..9fcd5e2298 100644
--- a/doc/release-process.md
+++ b/doc/release-process.md
@@ -87,7 +87,9 @@ Ensure gitian-builder is up-to-date:
pushd ./gitian-builder
mkdir -p inputs
wget -P inputs https://bitcoincore.org/cfields/osslsigncode-Backports-to-1.7.1.patch
+ echo 'a8c4e9cafba922f89de0df1f2152e7be286aba73f78505169bc351a7938dd911 inputs/osslsigncode-Backports-to-1.7.1.patch' | sha256sum -c
wget -P inputs https://downloads.sourceforge.net/project/osslsigncode/osslsigncode/osslsigncode-1.7.1.tar.gz
+ echo 'f9a8cdb38b9c309326764ebc937cba1523a3a751a7ab05df3ecc99d18ae466c9 inputs/osslsigncode-1.7.1.tar.gz' | sha256sum -c
popd
Create the macOS SDK tarball, see the [macOS readme](README_osx.md) for details, and copy it into the inputs directory.