besu-eth · bgravenorst · Feb 21, 2020 · Jan 21, 2020 · Feb 4, 2020 · Feb 10, 2020
diff --git a/docs/Concepts/TLS.md b/docs/Concepts/TLS.md
@@ -0,0 +1,15 @@
+description: TLS overview
+<!--- END of page meta data -->
+
+# TLS Communication
+
+Hyperledger Besu supports TLS to secure client and server communication. The
+client (EthSigner) or server (Orion) must also be configured for TLS  
+
+![Besu TLS](../images/Besu_TLS.png)
+
+
+Private keys and certificates must be stored in a password-protected PKCS #12
+keystore files.
+
+Use the command line options to [enable and configure](../HowTo/Configure/Configure-TLS.md) TLS.
diff --git a/docs/HowTo/Configure/Configure-TLS.md b/docs/HowTo/Configure/Configure-TLS.md
@@ -0,0 +1,113 @@
+description: Configure TLS
+<!--- END of page meta data -->
+
+# Configure TLS
+
+Hyperledger Besu supports TLS for client and server communication. For example, you can
+[configure TLS](../../Concepts/TLS.md) for communication between EthSigner and Besu, and Besu and Orion.
+
+Configure TLS communication from the command line.
+
+**Prerequisites**:
+
+* Besu's password-protected PKSC #12 keystore.
+* File containing the keystore password
+
+## Configure Client TLS
+
+Allow clients (for example a dApp, curl, or EthSigner) to send and receive
+secure HTTP JSON-RPCs.
+
+**Prerequisites**:
+
+* The client must be configured for TLS.
+* Client's PKSC #12 keystore information.
+
+### Create the Known Clients File
+
+The known clients file allows clients with self-signed certificates or
+non-public certificates to connect to Besu.
+
+Create a file (in this example, `knownClients`) that lists one or more trusted
+clients. Use the format`<common_name> <hex-string>` where:
+
+* `<common_name>` is the Common Name specified in the client certificate.
+* `<hex-string>` is the SHA-256 fingerprint of the client certificate.
+
+!!! example
+    ```
+    ethsigner 8E:E0:85:9F:FC:2E:2F:21:31:46:0B:82:4C:A6:88:AB:30:34:9A:C6:EA:4F:04:31:ED:0F:69:A7:B5:C2:2F:A7
+    curl FC:18:BF:39:45:45:9A:15:46:76:A6:E7:C3:94:64:B8:34:84:A3:8E:B8:EA:67:DC:61:C0:29:E6:38:B8:B7:99
+    ```
+
+You can use `openssl` or `keytool` to display the SHA256 fingerprint.
+
+!!! example
+    ```
+    keytool -list -v -keystore <keystore> -storetype PKCS12 -storepass <MY_PASSWORD>`.
+    ```
+
+### Start Besu
+
+```bash
+besu --rpc-http-enabled --rpc-http-tls-enabled --rpc-http-tls-client-auth-enabled --rpc-http-tls-keystore-file=/Users/me/my_node/keystore.pfx --rpc-http-tls-keystore-password-file=/Users/me/my_node/keystorePassword --rpc-http-tls-known-clients-file=/Users/me/my_node/knownClients
+```
+
+The command line:
+
+* Enables the HTTP JSON-RPC service using the [`--rpc-http-enabled`](../../Reference/CLI/CLI-Syntax.md#rpc-http-enabled) option.
+* Enables TLS for the HTTP JSON-RPC service using the [`--rpc-http-tls-enabled`](../../Reference/CLI/CLI-Syntax.md#rpc-http-tls-enabled)
+option.
+* Enables TLS client authentication using the [`--rpc-http-tls-client-auth-enabled`](../../Reference/CLI/CLI-Syntax.md#rpc-http-tls-client-auth-enabled) option.
+* Specifies the keystore using the [`--rpc-http-tls-keystore-file`](../../Reference/CLI/CLI-Syntax.md#rpc-http-tls-keystore-file) option.
+* Specifies the file that contains the password to decrypt the keystore using
+the [`--rpc-http-tls-keystore-password-file`](../../Reference/CLI/CLI-Syntax.md#rpc-http-tls-keystore-password-file) option.
+* [Specify the clients](#create-the-known-clients-file) that are allowed to connect to Besu using the
+[`--rpc-http-tls-known-clients-file`](../../Reference/CLI/CLI-Syntax.md#rpc-http-tls-known-clients-file) option.
+
+!!! note
+    Set [`--rpc-http-tls-ca-clients-enabled`](../../Reference/CLI/CLI-Syntax.md#rpc-http-tls-ca-clients-enabled)
+    to `true` to allow access to clients with signed and trusted root CAs.
+
+## Configure Server TLS
+
+Allow Besu to securely communicate with the server (Orion)
+
+**Prerequisites**:
+
+* The server must be configured to allow TLS communication
+* Server's certificate information.
+
+### Create the Known Servers file
+
+Create a file (in this example, `knownServers`) that lists one or more trusted
+servers. The file contents use the format `<hostame>:<port> <hex-string>`
+where:
+
+* `<hostname>` is the server hostname
+* `<port>` is the port used for communication
+* `<hex-string>` is the SHA-256 fingerprint of the server's certificate.
+
+!!! example
+    ```
+    localhost:8888 3C:B4:5A:F9:88:43:5E:62:69:9F:A9:9D:41:14:03:BA:83:24:AC:04:CE:BD:92:49:1B:8D:B2:A4:86:39:4C:AC
+    127.0.0.1:8888 3C:B4:5A:F9:88:43:5E:62:69:9F:A9:9D:41:14:03:BA:83:24:AC:04:CE:BD:92:49:1B:8D:B2:A4:86:39:4C:AC
+    ```
+
+!!! note
+    Specify both hostname and IP address in the file if unsure which is used in
+    requests.
+
+### Start Besu
+
+```bash
+besu --privacy-tls-enabled --privacy-tls-keystore-file=/Users/me/my_node/keystore.pfx --privacy-tls-keystore-password-file=/Users/me/my_node/keystorePassword --privacy-tls-known-enclave-file=/Users/me/my_node/knownServers
+```
+
+The command line:
+
+* Enables TLS with the server using the [`--privacy-tls-enabled`](../../Reference/CLI/CLI-Syntax.md#privacy-tls-enabled) option.
+* Specifies the keystore using the [`--privacy-tls-keystore-file`](../../Reference/CLI/CLI-Syntax.md#privacy-tls-keystore-file) option.
+* Specifies the file that contains the password to decrypt the keystore using
+the [`--privacy-tls-keystore-password-file`](../../Reference/CLI/CLI-Syntax.md#privacy-tls-keystore-password-file) option.
+* Specifies the trusted servers using the [`--privacy-tls-known-enclave-file`](../../Reference/CLI/CLI-Syntax.md#privacy-tls-known-enclave-file) option.
diff --git a/docs/Reference/CLI/CLI-Syntax.md b/docs/Reference/CLI/CLI-Syntax.md
@@ -1180,6 +1180,92 @@ privacy-public-key-file="Orion/nodeKey.pub"
 
 Path to the [public key of the Orion node](../../Concepts/Privacy/Privacy-Overview.md#besu-and-orion-keys).     
 
+### privacy-tls-enabled
+
+```bash tab="Syntax"
+--privacy-tls-enabled[=<true|false>]
+```
+
+```bash tab="Command Line"
+--privacy-tls-enabled=false
+```
+
+```bash tab="Environment Variable"
+BESU_PRIVACY_TLS_ENABLED=false
+```
+
+```bash tab="Configuration File"
+privacy-tls-enabled=false
+```
+
+Enables [TLS with the Private Transaction Manager](../../Concepts/Privacy/Privacy-Overview.md#private-transaction-manager).
+
+The default is false.
+
+### privacy-tls-keystore-file
+
+```bash tab="Syntax"
+--privacy-tls-keystore-password-file=<FILE>
+```
+
+```bash tab="Command Line"
+--privacy--keystore-password-file=/home/me/me_node/password
+```
+
+```bash tab="Environment Variable"
+BESU_PRIVACY_TLS_KEYSTORE_PASSWORD_FILE=/home/me/me_node/password
+```
+
+```bash tab="Configuration File"
+privacy-tls-keystore-password-file="/home/me/me_node/password"
+```
+
+Keystore file (in PKCS #12 format) that contains private key and the certificate
+presented during authentication.  
+
+Must be specified if [`--privacy-tls-enabled`](#privacy-tls-enabled) is `true`.
+
+### privacy-tls-keystore-password-file
+
+```bash tab="Syntax"
+--privacy-tls-keystore-password-file=<FILE>
+```
+
+```bash tab="Command Line"
+--privacy-tls-keystore-password-file=/home/me/me_node/password
+```
+
+```bash tab="Environment Variable"
+BESU_PRIVACY_TLS_KEYSTORE_PASSWORD_FILE=/home/me/me_node/password
+```
+
+```bash tab="Configuration File"
+privacy-tls-keystore-password-file="/home/me/me_node/password"
+```
+
+Path to a file that contains the password to decrypt the keystore.
+
+### privacy-tls-known-enclave-file
+
+```bash tab="Syntax"
+--privacy-tls-known-enclave-file=<FILE>
+```
+
+```bash tab="Command Line"
+--privacy-tls-known-enclave-file=/home/me/me_node/knownEnclave
+```
+
+```bash tab="Environment Variable"
+BESU_PRIVACY_TLS_KNOWN_ENCLAVE_FILE=/home/me/me_node/knownEnclave
+```
+
+```bash tab="Configuration File"
+privacy-tls-known-enclave-file="/home/me/me_node/knownEnclave"
+```
+
+Path to a file containing the hostnames, ports, and SHA256 certificate fingerprints
+of the [authorized privacy enclave](../../HowTo/Configure/Configure-TLS.md##create-the-known-servers-file).
+
 ### privacy-url
 
 ```bash tab="Syntax"
@@ -1517,6 +1603,133 @@ rpc-http-port="3435"
 Specifies HTTP JSON-RPC listening port (TCP).
 The default is 8545. Ports must be [exposed appropriately](../../HowTo/Find-and-Connect/Configuring-Ports.md). 
 
+### rpc-http-tls-ca-clients-enabled
+
+```bash tab="Syntax"
+--rpc-http-tls-ca-clients-enabled
+```
+
+```bash tab="Environment Variable"
+BESU_RPC_HTTP_TLS_CA_CLIENTS_ENABLED[=<true|false>]
+```
+
+```bash tab="Configuration File"
+rpc-http-tls-ca-clients-enabled=true
+```
+
+Allows clients with trusted CA certificates to connect. Defaults to `false`.
+
+!!! note
+    Client authentication must be enabled using [`---rpc-http-tls-client-auth-enabled`](#rpc-http-tls-client-auth-enabled).
+
+### rpc-http-tls-client-auth-enabled
+
+```bash tab="Syntax"
+--rpc-http-tls-client-auth-enabled
+```
+
+```bash tab="Environment Variable"
+BESU_RPC_HTTP_TLS_CLIENT_AUTH_ENABLED=true
+```
+
+```bash tab="Configuration File"
+rpc-http-tls-client-auth-enabled=true
+```
+
+Enables TLS client authentication for the JSON-RPC HTTP service. Defaults to
+`false`.
+
+!!! note
+    [`--rpc-http-tls-ca-clients-enabled`](#rpc-http-tls-ca-clients-enabled) and/or [`rpc-http-tls-known-clients-file`](#rpc-http-tls-known-clients-file) must be specified.
+
+### rpc-http-tls-enabled
+
+```bash tab="Syntax"
+--rpc-http-tls-enabled
+```
+
+```bash tab="Environment Variable"
+BESU_RPC_HTTP_TLS_ENABLED=true
+```
+
+```bash tab="Configuration File"
+rpc-http-tls-enabled=true
+```
+
+Enable TLS for the JSON-RPC HTTP service. Defaults to `false`.
+
+!!! note
+    [`--rpc-http-enabled`](#rpc-http-enabled) must be enabled.
+
+
+### rpc-http-tls-keystore-file
+
+```bash tab="Syntax"
+--rpc-http-tls-keystore-file=<FILE>
+```
+
+```bash tab="Command Line"
+--rpc-http-tls-keystore-file=/home/me/me_node/keystore.pfx
+```
+
+```bash tab="Environment Variable"
+BESU_RPC_HTTP_TLS_KEYSTORE_FILE=/home/me/me_node/keystore.pfx
+```
+
+```bash tab="Configuration File"
+rpc-http-tls-keystore-file="/home/me/me_node/keystore.pfx"
+```
+
+Keystore file (in PKCS #12 format) that contains private key and the certificate
+presented to the client during authentication. 
+
+### rpc-http-tls-keystore-password-file
+
+```bash tab="Syntax"
+--rpc-http-tls-keystore-password-file=<FILE>
+```
+
+```bash tab="Command Line"
+--rpc-http-tls-keystore-password-file=/home/me/me_node/password
+```
+
+```bash tab="Environment Variable"
+BESU_RPC_HTTP_TLS_KEYSTORE_PASSWORD_FILE=/home/me/me_node/password
+```
+
+```bash tab="Configuration File"
+rpc-http-tls-keystore-password-file="/home/me/me_node/password"
+```
+
+Path to a file that contains the password to decrypt the keystore.
+
+### rpc-http-tls-known-clients-file
+
+```bash tab="Syntax"
+--rpc-http-tls-known-clients-file=<FILE>
+```
+
+```bash tab="Command Line"
+--rpc-http-tls-known-clients-file=/home/me/me_node/knownClients
+```
+
+```bash tab="Environment Variable"
+BESU_RPC_HTTP_TLS_KNOWN_CLIENTS_FILE=/home/me/me_node/knownClients
+```
+
+```bash tab="Configuration File"
+rpc-http-tls-known-clients-file="/home/me/me_node/knownClients"
+```
+
+Used to [authenticate clients](../../HowTo/Configure/Configure-TLS.md##create-the-known-clients-file) that use self-signed certificates or non-public
+certificates.
+
+Must contain the certificates's Common Name, and SHA-256 fingerprint in the
+format `<CommonName> <hex-string>`.
+
+!!! note
+    Client authentication must be enabled using [`---rpc-http-tls-client-auth-enabled`](#rpc-http-tls-client-auth-enabled).
+
 ### rpc-ws-api
 
 ```bash tab="Syntax"

diff --git a/docs/images/Besu_TLS.png b/docs/images/Besu_TLS.png
diff --git a/docs/index.md b/docs/index.md
@@ -20,7 +20,7 @@ Besu supports enterprise features including privacy and permissioning.
 
 Besu includes a [command line interface](Reference/CLI/CLI-Syntax.md) and [JSON-RPC API](HowTo/Interact/APIs/API.md)
 for running, maintaining, debugging, and monitoring nodes in an Ethereum network. You can use the API via RPC
-over HTTP or via WebSockets, and Pub/Sub is supported. The API supports typical Ethereum functionalities such as:
+over HTTP/HTTPS or via WebSockets, and Pub/Sub is supported. The API supports typical Ethereum functionalities such as:
 
 * Ether mining
 * Smart contract development

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -67,6 +67,7 @@ nav:
           - Create Besu Genesis File: HowTo/Configure/Genesis-File.md
           - Specify Options in a Configuration File: HowTo/Configure/Using-Configuration-File.md
           - Configure a Free Gas Network: HowTo/Configure/FreeGas.md
+          - Configure TLS: HowTo/Configure/Configure-TLS.md
           - High Availability:
             - Configure High Availability of APIs: HowTo/Configure/Configure-HA/High-Availability.md
             - Sample Load Balancer Configurations: HowTo/Configure/Configure-HA/Sample-Configuration.md
@@ -160,6 +161,7 @@ nav:
           - Vadidating Transactions: Concepts/Transactions/Transaction-Validation.md
         - Monitoring: Concepts/Monitoring.md
         - Events and Logs: Concepts/Events-and-Logs.md
+        - TLS Communication: Concepts/TLS.md
         - Node Keys: Concepts/Node-Keys.md
         - Network vs Node Configuration: Concepts/Network-vs-Node.md
         - Network ID and Chain ID: Concepts/NetworkID-And-ChainID.md