clarify the need for the shared secret

docs/src/main/sphinx/security/internal-communication.rst

@@ -3,16 +3,22 @@ Secure internal communication
 =============================
 
 The Trino cluster can be configured to use secured communication with internal
-authentication of the nodes in the cluster, and optionally added security with
-:ref:`TLS <glossTLS>`.
+authentication of the nodes in the cluster, and to optionally use added security
+with :ref:`TLS <glossTLS>`.
 
-Shared secret for internal authentication
------------------------------------------
+Configure shared secret
+-----------------------
 
-Requests between Trino nodes are authenticated using a shared secret. For secure
-internal communication, and for any :ref:`external authentication
-<security-authentication>`, the shared secret must be set to the same value in
-:ref:`config.properties <config_properties>` on all nodes in the cluster:
+Configure a shared secret to authenticate all communication between nodes of the
+cluster. Use this configuration under the following conditions:
+
+* When opting to configure `internal TLS encryption <#configure-internal-tls>`_
+  between nodes of the cluster
+* When using any :doc:`external authentication <authentication-types>` method
+  between clients and the coordinator
+
+Set the shared secret to the same value in :ref:`config.properties
+<config_properties>` on all nodes of the cluster:
 
 .. code-block:: text
 
@@ -25,8 +31,11 @@ command:
 
     openssl rand 512 | base64
 
-Internal TLS configuration
---------------------------
+Configure internal TLS
+----------------------
+
+You can optionally add an extra layer of security by configuring the cluster to
+encrypt communication between nodes with :ref:`TLS <glossTLS>`.
 
 You can configure the coordinator and all workers to encrypt all communication
 with each other using TLS. Every node in the cluster must be configured. Nodes
@@ -37,7 +46,7 @@ In typical deployments, you should enable :ref:`TLS directly on the coordinator
 <https-secure-directly>` for fully encrypted access to the cluster by client
 tools.
 
-Now you can enable TLS for internal communication with the following
+Enable TLS for internal communication with the following
 configuration identical on all cluster nodes.
 
 1. Configure a shared secret for internal communication as described in
@@ -84,7 +93,7 @@ inside the cluster is secured with TLS.
     * ``node.internal-address-source``
 
 Performance with SSL/TLS enabled
---------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Enabling encryption impacts performance. The performance degradation can vary
 based on the environment, queries, and concurrency.
@@ -99,7 +108,7 @@ considerable. The slowdown may vary from 10% to even 100%+, depending on the net
 traffic and the CPU utilization.
 
 Advanced performance tuning
----------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 In some cases, changing the source of random numbers improves performance
 significantly.