github.com/kaituanwang/hyperledger@v2.0.1+incompatible/docs/source/enable_tls.rst (about)

     1  Securing Communication With Transport Layer Security (TLS)
     2  ==========================================================
     3  
     4  Fabric supports for secure communication between nodes using TLS.  TLS communication
     5  can use both one-way (server only) and two-way (server and client) authentication.
     6  
     7  Configuring TLS for peers nodes
     8  -------------------------------
     9  
    10  A peer node is both a TLS server and a TLS client. It is the former when another peer
    11  node, application, or the CLI makes a connection to it and the latter when it makes
    12  a connection to another peer node or orderer.
    13  
    14  To enable TLS on a peer node set the following peer configuration properties:
    15  
    16   * ``peer.tls.enabled`` = ``true``
    17   * ``peer.tls.cert.file`` = fully qualified path of the file that contains the TLS server
    18     certificate
    19   * ``peer.tls.key.file`` = fully qualified path of the file that contains the TLS server
    20     private key
    21   * ``peer.tls.rootcert.file`` = fully qualified path of the file that contains the
    22     certificate chain of the certificate authority(CA) that issued TLS server certificate
    23  
    24  By default, TLS client authentication is turned off when TLS is enabled on a peer node.
    25  This means that the peer node will not verify the certificate of a client (another peer
    26  node, application, or the CLI) during a TLS handshake. To enable TLS client authentication
    27  on a peer node, set the peer configuration property ``peer.tls.clientAuthRequired`` to
    28  ``true`` and set the ``peer.tls.clientRootCAs.files`` property to the CA chain file(s) that
    29  contain(s) the CA certificate chain(s) that issued TLS certificates for your organization's
    30  clients.
    31  
    32  By default, a peer node will use the same certificate and private key pair when acting as a
    33  TLS server and client.  To use a different certificate and private key pair for the client
    34  side, set the ``peer.tls.clientCert.file`` and ``peer.tls.clientKey.file`` configuration
    35  properties to the fully qualified path of the client certificate and key file,
    36  respectively.
    37  
    38  TLS with client authentication can also be enabled by setting the following environment
    39  variables:
    40  
    41   * ``CORE_PEER_TLS_ENABLED`` = ``true``
    42   * ``CORE_PEER_TLS_CERT_FILE`` = fully qualified path of the server certificate
    43   * ``CORE_PEER_TLS_KEY_FILE`` = fully qualified path of the server private key
    44   * ``CORE_PEER_TLS_ROOTCERT_FILE`` = fully qualified path of the CA chain file
    45   * ``CORE_PEER_TLS_CLIENTAUTHREQUIRED`` = ``true``
    46   * ``CORE_PEER_TLS_CLIENTROOTCAS_FILES`` = fully qualified path of the CA chain file
    47   * ``CORE_PEER_TLS_CLIENTCERT_FILE`` = fully qualified path of the client certificate
    48   * ``CORE_PEER_TLS_CLIENTKEY_FILE`` = fully qualified path of the client key
    49  
    50  When client authentication is enabled on a peer node, a client is required to send its
    51  certificate during a TLS handshake. If the client does not send its certificate, the
    52  handshake will fail and the peer will close the connection.
    53  
    54  When a peer joins a channel, root CA certificate chains of the channel members are
    55  read from the config block of the channel and are added to the TLS client and server
    56  root CAs data structure. So, peer to peer communication, peer to orderer communication
    57  should work seamlessly.
    58  
    59  Configuring TLS for orderer nodes
    60  ---------------------------------
    61  
    62  To enable TLS on an orderer node, set the following orderer configuration properties:
    63  
    64   * ``General.TLS.Enabled`` = ``true``
    65   * ``General.TLS.PrivateKey`` = fully qualified path of the file that contains the server
    66     private key
    67   * ``General.TLS.Certificate`` = fully qualified path of the file that contains the server
    68     certificate
    69   * ``General.TLS.RootCAs`` = fully qualified path of the file that contains the certificate
    70     chain of the CA that issued TLS server certificate
    71  
    72  By default, TLS client authentication is turned off on orderer, as is the case with peer.
    73  To enable TLS client authentication, set the following config properties:
    74  
    75   * ``General.TLS.ClientAuthRequired`` = ``true``
    76   * ``General.TLS.ClientRootCAs`` = fully qualified path of the file that contains the
    77     certificate chain of the CA that issued the TLS server certificate
    78  
    79  TLS with client authentication can also be enabled by setting the following environment
    80  variables:
    81  
    82   * ``ORDERER_GENERAL_TLS_ENABLED`` = ``true``
    83   * ``ORDERER_GENERAL_TLS_PRIVATEKEY`` = fully qualified path of the file that contains the
    84     server private key
    85   * ``ORDERER_GENERAL_TLS_CERTIFICATE`` = fully qualified path of the file that contains the
    86     server certificate
    87   * ``ORDERER_GENERAL_TLS_ROOTCAS`` = fully qualified path of the file that contains the
    88     certificate chain of the CA that issued TLS server certificate
    89   * ``ORDERER_GENERAL_TLS_CLIENTAUTHREQUIRED`` = ``true``
    90   * ``ORDERER_GENERAL_TLS_CLIENTROOTCAS`` = fully qualified path of the file that contains
    91     the certificate chain of the CA that issued TLS server certificate
    92  
    93  Configuring TLS for the peer CLI
    94  --------------------------------
    95  
    96  The following environment variables must be set when running peer CLI commands against a
    97  TLS enabled peer node:
    98  
    99  * ``CORE_PEER_TLS_ENABLED`` = ``true``
   100  * ``CORE_PEER_TLS_ROOTCERT_FILE`` = fully qualified path of the file that contains cert chain
   101    of the CA that issued the TLS server cert
   102  
   103  If TLS client authentication is also enabled on the remote server, the following variables
   104  must to be set in addition to those above:
   105  
   106  * ``CORE_PEER_TLS_CLIENTAUTHREQUIRED`` = ``true``
   107  * ``CORE_PEER_TLS_CLIENTCERT_FILE`` = fully qualified path of the client certificate
   108  * ``CORE_PEER_TLS_CLIENTKEY_FILE`` = fully qualified path of the client private key
   109  
   110  When running a command that connects to orderer service, like `peer channel <create|update|fetch>`
   111  or `peer chaincode <invoke>`, following command line arguments must also be specified
   112  if TLS is enabled on the orderer:
   113  
   114  * --tls
   115  * --cafile <fully qualified path of the file that contains cert chain of the orderer CA>
   116  
   117  If TLS client authentication is enabled on the orderer, the following arguments must be specified
   118  as well:
   119  
   120  * --clientauth
   121  * --keyfile <fully qualified path of the file that contains the client private key>
   122  * --certfile <fully qualified path of the file that contains the client certificate>
   123  
   124  
   125  Debugging TLS issues
   126  --------------------
   127  
   128  Before debugging TLS issues, it is advisable to enable ``GRPC debug`` on both the TLS client
   129  and the server side to get additional information. To enable ``GRPC debug``, set the
   130  environment variable ``FABRIC_LOGGING_SPEC`` to include ``grpc=debug``. For example, to
   131  set the default logging level to ``INFO`` and the GRPC logging level to ``DEBUG``, set
   132  the logging specification to ``grpc=debug:info``.
   133  
   134  If you see the error message ``remote error: tls: bad certificate`` on the client side, it
   135  usually means that the TLS server has enabled client authentication and the server either did
   136  not receive the correct client certificate or it received a client certificate that it does
   137  not trust. Make sure the client is sending its certificate and that it has been signed by one
   138  of the CA certificates trusted by the peer or orderer node.
   139  
   140  If you see the error message ``remote error: tls: bad certificate`` in your chaincode logs,
   141  ensure that your chaincode has been built using the chaincode shim provided with Fabric v1.1
   142  or newer.
   143  
   144  .. Licensed under Creative Commons Attribution 4.0 International License
   145     https://creativecommons.org/licenses/by/4.0/