diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/JSON-RPC-interface.md | 79 | ||||
-rw-r--r-- | doc/REST-interface.md | 7 | ||||
-rw-r--r-- | doc/dependencies.md | 2 | ||||
-rw-r--r-- | doc/developer-notes.md | 16 | ||||
-rw-r--r-- | doc/fuzzing.md | 2 | ||||
-rw-r--r-- | doc/release-notes-14941.md | 5 | ||||
-rw-r--r-- | doc/release-notes-14982.md | 5 | ||||
-rw-r--r-- | doc/release-notes.md | 14 | ||||
-rw-r--r-- | doc/release-process.md | 2 |
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. |