Update core.yaml, orderer.yaml and docs for TLS

docs/source/deployorderer/ordererchecklist.md

@@ -41,14 +41,24 @@ ListenPort: 7050
 ## General.TLS
 
 ```
+# Require server-side TLS
 Enabled: false
 # PrivateKey governs the file location of the private key of the TLS certificate.
 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
+# 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.
 RootCAs:
   - tls/ca.crt
+# Require client certificates / mutual TLS for inbound connections.
 ClientAuthRequired: false
+# If mutual TLS is enabled, ClientRootCAs 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:
 ```
 

docs/source/deploypeer/peerchecklist.md

@@ -200,26 +200,31 @@ Peers leverage the Gossip data dissemination protocol to broadcast ledger and ch
 
 ```
 tls:
-# Require server-side TLS
-enabled:  false
-# Require client certificates / mutual TLS.
-# Note that clients that are not configured to use a certificate will
-# fail to connect to the peer.
-clientAuthRequired: false
-# X.509 certificate used for TLS server
-cert:
-    file: tls/server.crt
-# Private key used for TLS server (and client if clientAuthEnabled
-# is set to true
-key:
-    file: tls/server.key
-# Trusted root certificate chain for tls.cert
-rootcert:
-    file: tls/ca.crt
-# Set of root certificate authorities used to verify client certificates
-clientRootCAs:
-    files:
-      - tls/ca.crt
+    # Require server-side TLS
+    enabled:  false
+    # Require client certificates / mutual TLS for inbound connections.
+    # Note that clients that are not configured to use a certificate will
+    # fail to connect to the peer.
+    clientAuthRequired: false
+    # X.509 certificate used for TLS server
+    cert:
+        file: tls/server.crt
+    # Private key used for TLS server
+    key:
+        file: tls/server.key
+    # rootcert.file represents the trusted root certificate chain used for verifying certificates
+    # of other 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.
+    rootcert:
+        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.
+    clientRootCAs:
+        files:
+          - tls/ca.crt
 ```
 
 Configure this section to enable TLS communications for the peer. After TLS is enabled, all nodes that transact with the peer will also need to enable TLS. Review the topic on [Registering and enrolling identities with a CA](https://hyperledger-fabric-ca.readthedocs.io/en/release-1.4/deployguide/use_CA.html) for instructions on how to generate the peer TLS certificates.
@@ -230,13 +235,13 @@ Configure this section to enable TLS communications for the peer. After TLS is e
 
 - **`key.file`:** (Default value should be overridden.) Similar to the `cert.file`, provide the name and location of the generated TLS private key for this peer, for example, `/msp/keystore/87bf5eff47d33b13d7aee81032b0e8e1e0ffc7a6571400493a7c_sk`. If you are using the recommended folder structure from the [Registering and enrolling identities with a CA](https://hyperledger-fabric-ca.readthedocs.io/en/release-1.4/deployguide/use_CA.html) topic, this file needs to be copied into `config/organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls`.  If you are using an [HSM](#bccsp) to store the private key for the peer, this field will be blank.
 
-- **`rootcert.file`:**  (Default value should be overridden.) This value contains the name and location of the peer organization CA root certificate. If you are using the recommended folder structure from the [Registering and enrolling identities with a CA](https://hyperledger-fabric-ca.readthedocs.io/en/release-1.4/deployguide/use_CA.html) topic, this file needs to be copied into `config/organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls`.
+- **`rootcert.file`:**  (Default value can be unset.) This value contains the name and location of the root certificate chain used for verifying certificates of other 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. If you are using the recommended folder structure from the [Registering and enrolling identities with a CA](https://hyperledger-fabric-ca.readthedocs.io/en/release-1.4/deployguide/use_CA.html) topic, this file can be copied into `config/organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls`.
 
 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`:** Specify the list of client root CA certificate files that can be used to verify client certificates.
+- **`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.
 
 ## peer.bccsp.*
 

docs/source/deploypeer/peerdeploy.md

@@ -70,7 +70,6 @@ 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

@@ -18,16 +18,12 @@ To enable TLS on a peer node set the following peer configuration properties:
    certificate
  * ``peer.tls.key.file`` = fully qualified path of the file that contains the TLS server
    private key
- * ``peer.tls.rootcert.file`` = fully qualified path of the file that contains the
-   certificate chain of the certificate authority(CA) that issued TLS server certificate
 
 By default, TLS client authentication is turned off when TLS is enabled on a peer node.
 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`` 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.
+``true``.
 
 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
@@ -41,9 +37,7 @@ variables:
  * ``CORE_PEER_TLS_ENABLED`` = ``true``
  * ``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_ROOTCERT_FILE`` = fully qualified path of the CA chain file
  * ``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
 
@@ -52,9 +46,10 @@ certificate during a TLS handshake. If the client does not send its certificate,
 handshake will fail and the peer will close the connection.
 
 When a peer joins a channel, root CA certificate chains of the channel members are
-read from the config block of the channel and are added to the TLS client and server
+read from the config block of the channel and are added to the TLS server and client
 root CAs data structure. So, peer to peer communication, peer to orderer communication
-should work seamlessly.
+should work seamlessly. However, if needed, you can add additional root CA certificates
+by setting ``peer.tls.rootcert.file`` and ``peer.tls.clientRootCAs.files``.
 
 Configuring TLS for orderer nodes
 ---------------------------------
@@ -66,15 +61,11 @@ To enable TLS on an orderer node, set the following orderer configuration proper
    private key
  * ``General.TLS.Certificate`` = fully qualified path of the file that contains the server
    certificate
- * ``General.TLS.RootCAs`` = fully qualified path of the file that contains the certificate
-   chain of the CA that issued TLS server certificate
 
 By default, TLS client authentication is turned off on orderer, as is the case with peer.
-To enable TLS client authentication, set the following config properties:
+To enable TLS client authentication, set the following config property:
 
  * ``General.TLS.ClientAuthRequired`` = ``true``
- * ``General.TLS.ClientRootCAs`` = fully qualified path of the file that contains the
-   certificate chain of the CA that issued the TLS server certificate
 
 TLS with client authentication can also be enabled by setting the following environment
 variables:
@@ -84,11 +75,13 @@ variables:
    server private key
  * ``ORDERER_GENERAL_TLS_CERTIFICATE`` = fully qualified path of the file that contains the
    server certificate
- * ``ORDERER_GENERAL_TLS_ROOTCAS`` = fully qualified path of the file that contains the
-   certificate chain of the CA that issued TLS server certificate
  * ``ORDERER_GENERAL_TLS_CLIENTAUTHREQUIRED`` = ``true``
- * ``ORDERER_GENERAL_TLS_CLIENTROOTCAS`` = fully qualified path of the file that contains
-   the certificate chain of the CA that issued TLS server certificate
+
+   When an orderer participates in a channel, root CA certificate chains of the channel members are
+   read from the config block of the channel and are added to the TLS server and client
+   root CAs data structure. So, orderer to orderer communication
+   should work seamlessly. However, if needed, you can add additional root CA certificates
+   by setting ``General.TLS.RootCAs`` and ``General.TLS.ClientRootCAs``.
 
 Configuring TLS for the peer CLI
 --------------------------------

sampleconfig/core.yaml

@@ -253,26 +253,31 @@ peer:
     tls:
         # Require server-side TLS
         enabled:  false
-        # Require client certificates / mutual TLS.
+        # Require client certificates / mutual TLS for inbound connections.
         # Note that clients that are not configured to use a certificate will
         # fail to connect to the peer.
         clientAuthRequired: false
         # X.509 certificate used for TLS server
         cert:
             file: tls/server.crt
-        # Private key used for TLS server (and client if clientAuthEnabled
-        # is set to true
+        # Private key used for TLS server
         key:
             file: tls/server.key
-        # Trusted root certificate chain for tls.cert
+        # rootcert.file represents the trusted root certificate chain used for verifying certificates
+        # of other 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.
         rootcert:
             file: tls/ca.crt
-        # Set of root certificate authorities used to verify client certificates
+        # 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.
         clientRootCAs:
             files:
               - tls/ca.crt
-        # Private key used for TLS when making client connections.  If
-        # not set, peer.tls.key.file will be used instead
+        # Private key used for TLS when making client connections.
+        # If not set, peer.tls.key.file will be used instead
         clientKey:
             file:
         # X.509 certificate used for TLS when making client connections.

sampleconfig/orderer.yaml

@@ -20,14 +20,24 @@ General:
 
     # TLS: TLS settings for the GRPC server.
     TLS:
+        # Require server-side TLS
         Enabled: false
         # PrivateKey governs the file location of the private key of the TLS certificate.
         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
+        # 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.
         RootCAs:
           - tls/ca.crt
+        # Require client certificates / mutual TLS for inbound connections.
         ClientAuthRequired: false
+        # If mutual TLS is enabled, ClientRootCAs 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:
     # Keepalive settings for the GRPC server.
     Keepalive: