From 8465e1dab33487218841fb4fb176b15215bc1862 Mon Sep 17 00:00:00 2001 From: joe-alewine Date: Thu, 25 Jan 2018 17:02:37 -0500 Subject: [PATCH] [FAB-7926] Enabling TLS doc Mutual TLS documentation. Also change to index. [ci-skip] Change-Id: I695de7bfada003f8cd22999412be10a41b9aa6fe Signed-off-by: joe-alewine Signed-off-by: Gari Singh --- docs/source/enable_tls.rst | 124 +++++++++++++++++++++++++++++++++++++ docs/source/index.rst | 1 + 2 files changed, 125 insertions(+) create mode 100644 docs/source/enable_tls.rst diff --git a/docs/source/enable_tls.rst b/docs/source/enable_tls.rst new file mode 100644 index 00000000000..c01543961cd --- /dev/null +++ b/docs/source/enable_tls.rst @@ -0,0 +1,124 @@ +Securing Communication With Transport Layer Security (TLS) +========================================================== + +Fabric supports for secure communication between nodes using TLS. TLS communication +can use both one-way (server only) and two-way (server and client) authentication. + +Configuring TLS for peers nodes +------------------------------- + +A peer node is both a TLS server and a TLS client. It is the former when another peer +node, application, or the CLI makes a connection to it and the latter when it makes +a connection to another peer node or orderer. + +To enable TLS on a peer node set the following peer configuration properties: + + * ``peer.tls.enabled`` = ``true`` + * ``peer.tls.cert.file`` = fully qualified path of the file that contains the TLS server + 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. + +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 +side, set the ``peer.tls.clientCert.file`` and ``peer.tls.clientKey.file`` configuration +properties to the fully qualified path of the client certificate and key file, +respectively. + +TLS with client authentication can also be enabled by setting the following environment +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 + +When client authentication is enabled on a peer node, a client is required to send its +certificate during a TLS handshake. If the client does not send its certificate, the +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 +root CAs data structure. So, peer to peer communication, peer to orderer communication +should work seamlessly. + +Configuring TLS for orderer nodes +--------------------------------- + +To enable TLS on an orderer node, set the following orderer configuration properties: + + * ``General.TLS.Enabled`` = ``true`` + * ``General.TLS.PrivateKey`` = fully qualified path of the file that contains the server + 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: + + * ``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: + + * ``ORDERER_GENERAL_TLS_ENABLED`` = ``true`` + * ``ORDERER_GENERAL_TLS_PRIVATEKEY`` = fully qualified path of the file that contains the + 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 + +Configuring TLS for the peer CLI +-------------------------------- + +The following environment variables must be set when running peer CLI commands against a +TLS enabled peer node or orderer: + +* ``CORE_PEER_TLS_ENABLED`` = ``true`` +* ``CORE_PEER_TLS_ROOTCERT_FILE`` = fully qualified path of the file that contains cert chain + of the CA that issued the TLS server cert + +If TLS client authentication is also enabled on the remote server, the following variables +must to be set in addition to those above: + +* ``CORE_PEER_TLS_CLIENTAUTHREQUIRED`` = ``true`` +* ``CORE_PEER_TLS_CLIENTCERT_FILE`` = fully qualified path of the client certificate +* ``CORE_PEER_TLS_CLIENTKEY_FILE`` = fully qualified path of the client private key + +Debugging TLS issues +-------------------- + +Before debugging TLS issues, it is advisable to enable ``GRPC debug`` on both the TLS client +and the server side to get additional information. To enable ``GRPC debug``, set the +environment variable ``CORE_LOGGING_GRPC`` to ``DEBUG``. + +If you see the error message ``remote error: tls: bad certificate`` on the client side, it +usually means that the TLS server has enabled client authentication and the server either did +not receive the correct client certificate or it received a client certificate that it does +not trust. Make sure the client is sending its certificate and that it has been signed by one +of the CA certificates trusted by the peer or orderer node. + +.. Licensed under Creative Commons Attribution 4.0 International License + https://creativecommons.org/licenses/by/4.0/ diff --git a/docs/source/index.rst b/docs/source/index.rst index f2b42f13b9a..545c6af6700 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -89,6 +89,7 @@ Business: peer_event_services readwrite gossip + enable_tls .. toctree:: :maxdepth: 2