From 9db117dd0fc001e64981c6366594c3f8823aa796 Mon Sep 17 00:00:00 2001 From: Byron Gravenorst <50852695+bgravenorst@users.noreply.github.com> Date: Fri, 22 Nov 2024 09:15:22 +1000 Subject: [PATCH] Add WebSocket authentication options. (#1729) * Add WebSocket authentication options. Signed-off-by: bgravenorst * Add additional content. Signed-off-by: bgravenorst * Apply suggestions from code review Peer review feedback. Co-authored-by: Alexandra Carrillo <12214231+alexandratran@users.noreply.github.com> Signed-off-by: Byron Gravenorst <50852695+bgravenorst@users.noreply.github.com> --------- Signed-off-by: bgravenorst Signed-off-by: Byron Gravenorst <50852695+bgravenorst@users.noreply.github.com> Co-authored-by: Alexandra Carrillo <12214231+alexandratran@users.noreply.github.com> --- .../how-to/configure/tls/client-and-server.md | 12 + docs/public-networks/reference/cli/options.md | 494 +++++++++++++++++- 2 files changed, 501 insertions(+), 5 deletions(-) diff --git a/docs/private-networks/how-to/configure/tls/client-and-server.md b/docs/private-networks/how-to/configure/tls/client-and-server.md index 5e57133b79b..a6cee37b354 100644 --- a/docs/private-networks/how-to/configure/tls/client-and-server.md +++ b/docs/private-networks/how-to/configure/tls/client-and-server.md @@ -9,6 +9,18 @@ tags: Besu supports TLS for client and server communication. For example, you can configure TLS for communication between [Web3Signer](https://docs.web3signer.consensys.net/concepts/tls) and Besu, and Besu and [Tessera](https://docs.tessera.consensys.net/HowTo/Configure/TLS/). +The following instructions allow you to configure client and server authentication to secure HTTP JSON-RPC +calls. + +:::info Secure Websocket JSON-RPC calls + +You can configure SSL/TLS authentication for WebSocket calls by enabling +[`--rpc-ws-ssl-enabled`](../../../../public-networks/reference/cli/options.md#rpc-ws-ssl-enabled) for +server authentication, and +[`--rpc-ws-ssl-client-auth-enabled`](../../../../public-networks/reference/cli/options.md#rpc-ws-ssl-client-auth-enabled) for client authentication. + +::: + The following diagram displays an example client and server TLS configuration. ![Besu client and server TLS](../../../../assets/images/Besu_TLS.png) diff --git a/docs/public-networks/reference/cli/options.md b/docs/public-networks/reference/cli/options.md index 17d1d4b72c9..037bf5384e0 100644 --- a/docs/public-networks/reference/cli/options.md +++ b/docs/public-networks/reference/cli/options.md @@ -220,7 +220,8 @@ auto-log-bloom-caching-enabled=false Enables or disables automatic log bloom caching. APIs such as [`eth_getLogs`](../api/index.md#eth_getlogs) and [`eth_getFilterLogs`](../api/index.md#eth_getfilterlogs) use the cache for improved performance. The default is `true`. -If automatic log bloom caching is enabled and a log bloom query reaches the end of the cache, Besu performs an uncached query for logs not yet written to the cache. +If automatic log bloom caching is enabled and a log bloom query reaches the end of the cache, Besu +performs an uncached query for logs not yet written to the cache. Automatic log bloom caching has a small impact on performance. If you are not querying logs blooms for a large number of blocks, you might want to disable automatic log bloom caching. @@ -4331,7 +4332,9 @@ When using [`eth_getLogs`](../api/index.md#eth_getlogs), the maximum number of b :::caution -Using `eth_getLogs` to get logs from a large range of blocks, especially an entire chain from its genesis block, might cause Besu to hang for an indeterminable amount of time while generating the response. +Using `eth_getLogs` to get logs from a large range of blocks, especially an entire chain from its +genesis block, might cause Besu to stop responding for an indeterminable amount of time while +generating the response. We recommend setting a range limit or leaving this option at its default value. @@ -4416,7 +4419,7 @@ rpc-tx-feecap=1200000000000000000 -The maximum transaction fee (in Wei) accepted for transactions submitted through the [`eth_sendRawTransaction`](../api/index.md#eth_sendrawtransaction) RPC. The default is 1000000000000000000 (1 ether). +The maximum transaction fee (in wei) accepted for transactions submitted through the [`eth_sendRawTransaction`](../api/index.md#eth_sendrawtransaction) RPC. The default is 1000000000000000000 (1 ether). If set to 0, then this option is ignored and no cap is applied. @@ -4884,6 +4887,487 @@ rpc-ws-port="6174" The port (TCP) on which WebSocket JSON-RPC listens. The default is `8546`. You must [expose ports appropriately](../../how-to/connect/configure-ports.md). + +### `rpc-ws-ssl-cert-file` + + + + + +```bash +--rpc-ws-ssl-cert-file= +``` + + + + + +```bash +--rpc-ws-ssl-cert-file=/home/me/me_node/websocket-cert.pem +``` + + + + + +```bash +BESU_RPC_WS_SSL_CERT_FILE="/home/me/me_node/websocket-cert.pem" +``` + + + + + +```bash +rpc-ws-ssl-cert-file="/home/me/me_node/websocket-cert.pem" +``` + + + + + +Path to the PEM certificate file enabling SSL/TLS for the WebSocket JSON-RPC service. +This file contains the public certificate that is used to establish the identity of the server to clients. + +Specify the private key file using [`--rpc-ws-ssl-key-file`](#rpc-ws-ssl-key-file). + +Required if [`--rpc-ws-ssl-keystore-type`](#rpc-ws-ssl-keystore-type) is `PEM`. + +### `rpc-ws-ssl-client-auth-enabled` + + + + + +```bash +--rpc-ws-ssl-client-auth-enabled[=] +``` + + + + + +```bash +--rpc-ws-ssl-client-auth-enabled=true +``` + + + + + +```bash +BESU_RPC_WS_SSL_CLIENT_AUTH_ENABLED=true +``` + + + + + +```bash +rpc-ws-ssl-client-auth-enabled=true +``` + + + + + +Enables or disables client authentication for the WebSocket JSON-RPC service. The default is `false`. + +:::note + +When enabling client authentication, specify the truststore type using [`--rpc-ws-ssl-truststore-type`](#rpc-ws-ssl-truststore-type) +and provide the appropriate file path for the truststore or trust certificate using either +[`--rpc-ws-ssl-truststore-file`](#rpc-ws-ssl-truststore-file) (for JKS or PKCS12) or +[`--rpc-ws-ssl-trustcert-file`](#rpc-ws-ssl-trustcert-file) (for PEM). + +If using JKS or PKCS12, specify the truststore password using [`--rpc-ws-ssl-truststore-password`](#rpc-ws-ssl-truststore-password). +::: + +### `rpc-ws-ssl-enabled` + + + + + +```bash +--rpc-ws-ssl-enabled[=] +``` + + + + + +```bash +--rpc-ws-ssl-enabled=true +``` + + + + + +```bash +BESU_RPC_WS_SSL_ENABLED=true +``` + + + + + +```bash +rpc-ws-ssl-enabled=true +``` + + + + + +Enables or disables server SSL/TLS authentication for the WebSocket JSON-RPC service. The default is `false`. + +Set the appropriate keystore type using [`--rpc-ws-ssl-keystore-type`](#rpc-ws-ssl-keystore-type). + +### `rpc-ws-ssl-key-file` + + + + + +```bash +--rpc-ws-ssl-key-file= +``` + + + + + +```bash +--rpc-ws-ssl-key-file=/home/me/me_node/websocket-cert.pem +``` + + + + + +```bash +BESU_RPC_WS_SSL_KEY_FILE="/home/me/me_node/websocket-cert.pem" +``` + + + + + +```bash +rpc-ws-ssl-key-file="/home/me/me_node/websocket-cert.pem" +``` + + + + + +Path to the PEM certificate file when enabling SSL/TLS for the WebSocket JSON-RPC service. +This file contains the private key that corresponds to the public certificate specified using +[`--rpc-ws-ssl-cert-file`](#rpc-ws-ssl-cert-file). + +Required if [`--rpc-ws-ssl-keystore-type`](#rpc-ws-ssl-keystore-type) is `PEM`. + +### `rpc-ws-ssl-keystore-file` + + + + + +```bash +--rpc-ws-ssl-keystore-file= +``` + + + + + +```bash +--rpc-ws-ssl-keystore-file=/home/me/me_node/keystore.jks +``` + + + + + +```bash +BESU_RPC_WS_SSL_KEYSTORE_FILE="/home/me/me_node/keystore.jks" +``` + + + + + +```bash +rpc-ws-ssl-keystore-file="/home/me/me_node/keystore.jks" +``` + + + + + +Path to the keystore file when enabling SSL/TLS for the WebSocket JSON-RPC service. +The keystore file is used to store the server's private key and public certificate in a single +file, typically in JKS or PKCS12 format. Use this option if you prefer to +manage your SSL/TLS certificates and keys in a keystore rather than separate PEM files. + +Required if [`--rpc-ws-ssl-keystore-type`](#rpc-ws-ssl-keystore-type) is set to `JKS` or `PKCS12`. + +### `rpc-ws-ssl-keystore-password` + + + + + +```bash +--rpc-ws-ssl-keystore-password= +``` + + + + + +```bash +--rpc-ws-ssl-keystore-password=keystore_password +``` + + + + + +```bash +BESU_RPC_WS_SSL_KEYSTORE_PASSWORD="keystore_password" +``` + + + + + +```bash +rpc-ws-ssl-keystore-password="keystore_password" +``` + + + + + +Password for the keystore file specified in [`--rpc-ws-ssl-keystore-file`](#rpc-ws-ssl-keystore-file). + +### `rpc-ws-ssl-keystore-type` + + + + + +```bash +--rpc-ws-ssl-keystore-type= +``` + + + + + +```bash +--rpc-ws-ssl-keystore-type=JKS +``` + + + + + +```bash +BESU_RPC_WS_SSL_KEYSTORE_TYPE="JKS" +``` + + + + + +```bash +rpc-ws-ssl-keystore-type="JKS" +``` + + + + + +Type of the keystore when enabling SSL/TLS for the WebSocket JSON-RPC service. Valid options are +`JKS`, `PKCS12`, and `PEM`. + +Provide the appropriate file path for the keystore using either +[`--rpc-ws-ssl-keystore-file`](#rpc-ws-ssl-keystore-file) (for `JKS` or `PKCS12`), or +[`--rpc-ws-ssl-key-file`](#rpc-ws-ssl-key-file) and [`--rpc-ws-ssl-cert-file`](#rpc-ws-ssl-cert-file) (for `PEM`). + +### `rpc-ws-ssl-trustcert-file` + + + + + +```bash +--rpc-ws-ssl-trustcert-file= +``` + + + + + +```bash +--rpc-ws-ssl-trustcert-file=/home/me/me_node/trust-cert.pem +``` + + + + + +```bash +BESU_RPC_WS_SSL_TRUSTCERT_FILE="/home/me/me_node/trust-cert.pem" +``` + + + + + +```bash +rpc-ws-ssl-trustcert-file="/home/me/me_node/trust-cert.pem" +``` + + + + + +Path to the PEM trust certificate file for enabling client SSL/TLS authentication for the WebSocket JSON-RPC +service. + +### `rpc-ws-ssl-truststore-file` + + + + + +```bash +--rpc-ws-ssl-truststore-file= +``` + + + + + +```bash +--rpc-ws-ssl-truststore-file=/home/me/me_node/websocket-truststore.jks +``` + + + + + +```bash +BESU_RPC_WS_SSL_TRUSTSTORE_FILE="/home/me/me_node/websocket-truststore.jks" +``` + + + + + +```bash +rpc-ws-ssl-truststore-file="/home/me/me_node/websocket-truststore.jks" +``` + + + + + +Path to the truststore file for enabling SSL/TLS client authentication for the WebSocket JSON-RPC +service. + +Specify the truststore file password using [`--rpc-ws-ssl-truststore-password`](#rpc-ws-ssl-truststore-password). + +### `rpc-ws-ssl-truststore-password` + + + + + +```bash +--rpc-ws-ssl-truststore-password= +``` + + + + + +```bash +--rpc-ws-ssl-truststore-password=/home/me/me_node/websocket-truststore.jks +``` + + + + + +```bash +BESU_RPC_WS_SSL_TRUSTSTORE_PASSWORD="/home/me/me_node/websocket-truststore.jks" +``` + + + + + +```bash +rpc-ws-ssl-truststore-password="/home/me/me_node/websocket-truststore.jks" +``` + + + + + +Password for the truststore file specified using [`--rpc-ws-ssl-truststore-file`](#rpc-ws-ssl-truststore-file) +when enabling WebSocket SSL/TLS client authentication. + +### `rpc-ws-ssl-truststore-type` + + + + + +```bash +--rpc-ws-ssl-truststore-type= +``` + + + + + +```bash +--rpc-ws-ssl-truststore-type=JKS +``` + + + + + +```bash +BESU_RPC_WS_SSL_TRUSTSTORE_TYPE="JKS" +``` + + + + + +```bash +rpc-ws-ssl-truststore-type="JKS" +``` + + + + + +Type of the truststore when enabling client SSL/TLS authentication for the WebSocket JSON-RPC service. Valid options are +`JKS`, `PKCS12`, and `PEM`. + +Specify the required [`--rpc-ws-ssl-truststore-file`](#rpc-ws-ssl-truststore-file) for `JKS` and `PKCS12`, or +[`--rpc-ws-ssl-trustcert-file`](#rpc-ws-ssl-trustcert-file) for `PEM`. + ### `security-module` @@ -5330,8 +5814,8 @@ tx-pool-layer-max-capacity="20000000" Maximum amount of memory (in bytes) that any layer within the [layered transaction pool](../../concepts/transactions/pool.md#layered-transaction-pool) can occupy. The default is `12500000`, or 12.5 MB. -There are two memory-limited layers in the transaction pool, so the expected memory consumption is -twice the value specified by this option, or 25 MB by default. +The transaction pool includes two memory-limited layers, resulting in an expected memory consumption +that is twice the value specified by this option, or 25 MB by default. Increase this value if you have spare RAM and the eviction rate is high for your network. ### `tx-pool-limit-by-account-percentage`