Clarify clientRootCAs guidance in core.yaml and TLS docs (#2142)

Signed-off-by: David Enyeart <enyeart@us.ibm.com>

docs/source/deploypeer/peerchecklist.md

@@ -220,8 +220,8 @@ tls:
         file: tls/ca.crt
     # If mutual TLS is enabled, clientRootCAs.files contains a list of additional root certificates
     # used for verifying certificates of client connections.
-    # It is not required to be set, but can be used to augment the set of TLS CA certificates
-    # available from the MSPs of each channel’s configuration.
+    # It augments the set of TLS CA certificates available from the MSPs of each channel’s configuration.
+    # Minimally, set your organization's TLS CA root certificate so that the peer can receive join channel requests.
     clientRootCAs:
         files:
           - tls/ca.crt
@@ -241,7 +241,7 @@ The next two parameters only need to be provided when mutual TLS is required:
 
 - **`clientAuthRequired`:** Defaults to `false`. Set to `true` for a higher level of security by using **mutual TLS**, which can be configured as an extra verification step of the client-side TLS certificate. Where server-side TLS is considered the minimally necessary level of security, mutual TLS is an additional and optional level of security.
 
-- **`clientRootCAs.files`:** Contains a list of additional root certificates used for verifying certificates of client connections. It is not required to be set, but can be used to augment the set of TLS CA certificates available from the MSPs of each channel’s configuration.
+- **`clientRootCAs.files`:** Contains a list of additional root certificates used for verifying certificates of client connections. It augments the set of TLS CA certificates available from the MSPs of each channel’s configuration. Minimally, set your organization's TLS CA root certificate so that the peer can receive join channel requests.
 
 ## peer.bccsp.*
 

docs/source/deploypeer/peerdeploy.md

@@ -70,6 +70,7 @@ In order for the peer to launch successfully, make sure that the locations of th
 - Copy the TLS certificate that contains the public key that is associated with the signing (private) key certificate, which by default is called `ca-cert.pem`, to `organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/tls-cert.pem`. The path and name of the certificate corresponds to the `peer.tls.rootcert.file` parameter in `core.yaml`.
 - After you have generated the peer TLS certificate, the certificate will have been generated in the `signcerts` directory, and the private key will have been generated in the `keystore` directory. Rename the generated private key in the `keystore` folder to `peer0-key.pem` so that it can more easily be recognized later on as being a private key.
 - Copy the peer TLS certificate and private key to `organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls`. The path and name of the certificate and private key files correspond to the `peer.tls.cert.file` and `peer.tls.key.file` parameters in the `core.yaml`.
+- If using mutual authentication (`clientAuthRequired` set to true), you need to indicate to the peer which TLS CA root certificates to use to authorize clients. Copy the organization's TLS CA root certificate `ca-cert.pem` to `organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/ca-cert.pem` so that the organization's clients will be authorized. The path and name of the certificate corresponds to `peer.tls.clientRootCAs.files` parameter in `core.yaml`. Note that multiple files can be configured, one for each client organization that will communicate with the peer (for example if other organizations will use this peer for endorsements). If `clientAuthRequired` is set to false, you can skip this step.
 
 #### Peer local MSP (enrollment certificate and private key)
 

docs/source/enable_tls.rst

@@ -23,7 +23,9 @@ By default, TLS client authentication is turned off when TLS is enabled on a pee
 This means that the peer node will not verify the certificate of a client (another peer
 node, application, or the CLI) during a TLS handshake. To enable TLS client authentication
 on a peer node, set the peer configuration property ``peer.tls.clientAuthRequired`` to
-``true``.
+``true`` and set the ``peer.tls.clientRootCAs.files`` property to the CA chain file(s) that
+contain(s) the CA certificate chain(s) that issued TLS certificates for your organization's
+clients.
 
 By default, a peer node will use the same certificate and private key pair when acting as a
 TLS server and client.  To use a different certificate and private key pair for the client
@@ -38,6 +40,7 @@ variables:
  * ``CORE_PEER_TLS_CERT_FILE`` = fully qualified path of the server certificate
  * ``CORE_PEER_TLS_KEY_FILE`` = fully qualified path of the server private key
  * ``CORE_PEER_TLS_CLIENTAUTHREQUIRED`` = ``true``
+ * ``CORE_PEER_TLS_CLIENTROOTCAS_FILES`` = fully qualified path of the CA chain file
  * ``CORE_PEER_TLS_CLIENTCERT_FILE`` = fully qualified path of the client certificate
  * ``CORE_PEER_TLS_CLIENTKEY_FILE`` = fully qualified path of the client key
 

sampleconfig/orderer.yaml

@@ -26,7 +26,7 @@ General:
         PrivateKey: tls/server.key
         # Certificate governs the file location of the server TLS certificate.
         Certificate: tls/server.crt
-        # RootCAs contains a list additional root certificates used for verifying certificates
+        # RootCAs contains a list of additional root certificates used for verifying certificates
         # of other orderer nodes during outbound connections.
         # It is not required to be set, but can be used to augment the set of TLS CA certificates
         # available from the MSPs of each channel’s configuration.