From f0be9ccff594242f17622b48f9279a9ec601b1bb Mon Sep 17 00:00:00 2001 From: bgravenorst Date: Thu, 21 Nov 2024 10:42:32 +1000 Subject: [PATCH 1/3] Add WebSocket authentication options. Signed-off-by: bgravenorst --- docs/public-networks/reference/cli/options.md | 493 +++++++++++++++++- 1 file changed, 488 insertions(+), 5 deletions(-) diff --git a/docs/public-networks/reference/cli/options.md b/docs/public-networks/reference/cli/options.md index 17d1d4b72c..30f3777104 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,486 @@ 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, you also need to specify the truststore password with [`--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 SSL/TLS for the WebSocket JSON-RPC service. The default is `false`. + +### `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. This option is used when 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 with the [`rpc-ws-ssl-truststore-password`](#rpc-ws-ssl-truststore-password) +command. + +### `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 +5813,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` From 1eb92ae725644c152f47dcaa1e98c31ddd06159e Mon Sep 17 00:00:00 2001 From: bgravenorst Date: Fri, 22 Nov 2024 07:39:46 +1000 Subject: [PATCH 2/3] Add additional content. Signed-off-by: bgravenorst --- .../how-to/configure/tls/client-and-server.md | 12 ++++++++++++ docs/public-networks/reference/cli/options.md | 5 ++++- 2 files changed, 16 insertions(+), 1 deletion(-) 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 5e57133b79..a6cee37b35 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 30f3777104..8ea835e109 100644 --- a/docs/public-networks/reference/cli/options.md +++ b/docs/public-networks/reference/cli/options.md @@ -5021,7 +5021,10 @@ rpc-ws-ssl-enabled=true -Enables or disables SSL/TLS for the WebSocket JSON-RPC service. The default is `false`. +Enables or disables server SSL/TLS authentication for the WebSocket JSON-RPC service. The default is `false`. + +Set the appropriate keystore type with the [`--rpc-ws-ssl-keystore-type`](#rpc-ws-ssl-keystore-type) +command line option. ### `rpc-ws-ssl-key-file` From d85b7c23c647816cd59c71344063a7bb914c0ebc Mon Sep 17 00:00:00 2001 From: Byron Gravenorst <50852695+bgravenorst@users.noreply.github.com> Date: Fri, 22 Nov 2024 09:13:16 +1000 Subject: [PATCH 3/3] 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> --- docs/public-networks/reference/cli/options.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/docs/public-networks/reference/cli/options.md b/docs/public-networks/reference/cli/options.md index 8ea835e109..037bf5384e 100644 --- a/docs/public-networks/reference/cli/options.md +++ b/docs/public-networks/reference/cli/options.md @@ -4980,7 +4980,7 @@ and provide the appropriate file path for the truststore or trust certificate us [`--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, you also need to specify the truststore password with [`--rpc-ws-ssl-truststore-password`](#rpc-ws-ssl-truststore-password). +If using JKS or PKCS12, specify the truststore password using [`--rpc-ws-ssl-truststore-password`](#rpc-ws-ssl-truststore-password). ::: ### `rpc-ws-ssl-enabled` @@ -5023,8 +5023,7 @@ 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 with the [`--rpc-ws-ssl-keystore-type`](#rpc-ws-ssl-keystore-type) -command line option. +Set the appropriate keystore type using [`--rpc-ws-ssl-keystore-type`](#rpc-ws-ssl-keystore-type). ### `rpc-ws-ssl-key-file` @@ -5066,7 +5065,7 @@ 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). +[`--rpc-ws-ssl-cert-file`](#rpc-ws-ssl-cert-file). Required if [`--rpc-ws-ssl-keystore-type`](#rpc-ws-ssl-keystore-type) is `PEM`. @@ -5110,7 +5109,7 @@ 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. This option is used when you prefer to +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`. @@ -5282,8 +5281,7 @@ 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 with the [`rpc-ws-ssl-truststore-password`](#rpc-ws-ssl-truststore-password) -command. +Specify the truststore file password using [`--rpc-ws-ssl-truststore-password`](#rpc-ws-ssl-truststore-password). ### `rpc-ws-ssl-truststore-password`