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

     1  # Using a Hardware Security Module (HSM)
     2  
     3  You can use a Hardware Security Module (HSM) to generate and store the private
     4  keys used by your Fabric nodes. An HSM protects your private keys and handles
     5  cryptographic operations, which allows your peers and ordering nodes to sign and
     6  endorse transactions without exposing their private keys. Currently, Fabric only
     7  supports the PKCS11 standard to communicate with an HSM.
     8  
     9  ## Configuring an HSM
    10  
    11  To use an HSM with your Fabric node, you need to update the BCCSP (Crypto Service
    12  Provider) section of the node configuration file such as core.yaml or
    13  orderer.yaml. In BCCSP section, you need to select PKCS11 as the provider and
    14  provide the path to the PKCS11 library that you would like to use. You also need
    15  to provide the label and pin of the token that you created for your cryptographic
    16  operations. You can use one token to generate and store multiple keys.
    17  
    18  The prebuilt Hyperledger Fabric Docker images are not enabled to use PKCS11. If
    19  you are deploying Fabric using docker, you need to build your own images and
    20  enable PKCS11 using the following command:
    21  ```
    22  make docker GO_TAGS=pkcs11
    23  ```
    24  You also need to ensure that the PKCS11 library is available to be used by the
    25  node by installing it or mounting it inside the container.
    26  
    27  ### Example
    28  
    29  The following example demonstrates how to configure a Fabric node to use an HSM.
    30  
    31  First, you will need to install an implementation of the PKCS11 interface. This
    32  example uses the [softhsm](https://github.com/opendnssec/SoftHSMv2) open source
    33  implementation. After downloading and configuring softhsm, you will need to set
    34  the SOFTHSM2_CONF environment variable to point to the softhsm2 configuration
    35  file.
    36  
    37  You can then use softhsm to create the token that will handle the cryptographic
    38  operations of your Fabric node inside an HSM slot. In this example, we create a
    39  token labelled "fabric" and set the pin to "71811222". After you have created
    40  the token, update the configuration file to use PKCS11 and your token as the
    41  crypto service provider. You can find an example BCCSP section below:
    42  
    43  ```
    44  #############################################################################
    45  # BCCSP (BlockChain Crypto Service Provider) section is used to select which
    46  # crypto library implementation to use
    47  #############################################################################
    48  bccsp:
    49    default: PKCS11
    50    pkcs11:
    51      Library: /etc/hyperledger/fabric/libsofthsm2.so
    52      Pin: 71811222
    53      Label: fabric
    54      hash: SHA2
    55      security: 256
    56  ```
    57  
    58  You can also use environment variables to override the relevant fields of the
    59  configuration file. If you are connecting to an HSM using the Fabric CA server,
    60  you need to set the following environment variables:
    61  
    62  ```
    63  FABRIC_CA_SERVER_BCCSP_DEFAULT=PKCS11
    64  FABRIC_CA_SERVER_BCCSP_PKCS11_LIBRARY=/etc/hyperledger/fabric/libsofthsm2.so
    65  FABRIC_CA_SERVER_BCCSP_PKCS11_PIN=71811222
    66  FABRIC_CA_SERVER_BCCSP_PKCS11_LABEL=fabric
    67  ```
    68  
    69  If you are deploying your nodes using docker compose, after building your own
    70  images, you can update your docker compose files to mount the softhsm library
    71  and configuration file inside the container using volumes. As an example, you
    72  would add the following environment and volumes variables to your docker compose
    73  file:
    74  ```
    75    environment:
    76       - SOFTHSM2_CONF=/etc/hyperledger/fabric/config.file
    77    volumes:
    78       - /home/softhsm/config.file:/etc/hyperledger/fabric/config.file
    79       - /usr/local/Cellar/softhsm/2.1.0/lib/softhsm/libsofthsm2.so:/etc/hyperledger/fabric/libsofthsm2.so
    80  ```
    81  
    82  ## Setting up a network using HSM
    83  
    84  If you are deploying Fabric nodes using an HSM, your private keys need to be
    85  generated inside the HSM rather than inside the `keystore` folder of the node's
    86  local MSP folder. The `keystore` folder of the MSP will remain empty. Instead,
    87  the Fabric node will use the subject key identifier of the signing certificate
    88  in the `signcerts` folder to retrieve the private key from inside the HSM.
    89  The process for creating the MSP folders will be different depending on if you
    90  are using a Fabric Certificate Authority (CA) your own CA.
    91  
    92  ### Using a Fabric CA
    93  
    94  You can set up a Fabric CA to use an HSM by making the same edits to the
    95  configuration file as you would make to a peer or ordering node. Because you can
    96  use Fabric CA to generate keys inside an HSM, the process of creating the local
    97  MSP folders is straightforward. Use the following steps:
    98  
    99  1. Create an HSM token and point to it in the Fabric CA server configuration
   100  file. When the Fabric CA server starts, it will generate the CA signing
   101  certificate inside your HSM. If you are not concerned about exposing your CA
   102  signing certificate, you can skip this step.
   103  
   104  2. Use the Fabric CA client to register the peer or ordering node identities
   105  with your CA.
   106  
   107  3. Edit the Fabric CA client config file or environment variables to use your
   108  HSM as the crypto service provider. Then for each node, use the Fabric CA client
   109  to generate the component MSP folder by enrolling against the node identity. The
   110  enroll command will generate the private key inside your HSM.
   111  
   112  3. Update the BCCSP section of the peer or orderer configuration file to use
   113  PKCS11 and your token as the crypto service provider. Point to the MSP that was
   114  generated using the Fabric CA client. Once it is deployed, the peer or orderer
   115  node will be able sign and endorse transactions with the private key protected by
   116  the HSM.
   117  
   118  ### Using an HSM with your own CA
   119  
   120  If you are using your own Certificate Authority to deploy Fabric components, you
   121  can use an HSM using the following steps:
   122  
   123  1. Configure your CA to communicate with an HSM using PKCS11 and create a token.
   124  Then use your CA to generate the private key and signing certificate for each
   125  node, with the private key generated inside the HSM.
   126  
   127  2. Use your CA to build the node MSP folder. Place the signing certificate that
   128  you generated in step 1 inside the `signcerts` folder. You can leave the
   129  `keystore` folder empty.
   130  
   131  3. Update the peer or orderer configuration file to use PKCS11 and your token as
   132  the crypto service provider. Point to the MSP folder that you created with the
   133  signing certificate inside. Once it has deployed, the peer or ordering node will
   134  be able to sign and endorse transactions using the HSM.
   135  
   136  <!--- Licensed under Creative Commons Attribution 4.0 International License
   137  https://creativecommons.org/licenses/by/4.0/ -->