github.com/hechain20/hechain@v0.0.0-20220316014945-b544036ba106/docs/source/hsm.md (about)

     1  # Using a Hardware Security Module (HSM)
     2  
     3  The cryptographic operations performed by Fabric nodes can be delegated to
     4  a Hardware Security Module (HSM).  An HSM protects your private keys and
     5  handles cryptographic operations, allowing your peers and orderer nodes to
     6  sign and endorse transactions without exposing their private keys.  If you
     7  require compliance with government standards such as FIPS 140-2, there are
     8  multiple certified HSMs from which to choose.
     9  
    10  Fabric currently leverages the PKCS11 standard to communicate with an HSM.
    11  
    12  
    13  ## Configuring an HSM
    14  
    15  To use an HSM with your Fabric node, you need to update the `bccsp` (Crypto Service
    16  Provider) section of the node configuration file such as core.yaml or
    17  orderer.yaml. In the `bccsp` section, you need to select PKCS11 as the provider and
    18  enter the path to the PKCS11 library that you would like to use. You also need
    19  to provide the `Label` and `PIN` of the token that you created for your cryptographic
    20  operations. You can use one token to generate and store multiple keys.
    21  
    22  The prebuilt Hechain Docker images are not enabled to use PKCS11. If
    23  you are deploying Fabric using docker, you need to build your own images and
    24  enable PKCS11 using the following command:
    25  ```
    26  make docker GO_TAGS=pkcs11
    27  ```
    28  You also need to ensure that the PKCS11 library is available to be used by the
    29  node by installing it or mounting it inside the container.
    30  
    31  ### Example
    32  
    33  The following example demonstrates how to configure a Fabric node to use an HSM.
    34  
    35  First, you will need to install an implementation of the PKCS11 interface. This
    36  example uses the [softhsm](https://github.com/opendnssec/SoftHSMv2) open source
    37  implementation. After downloading and configuring softhsm, you will need to set
    38  the SOFTHSM2_CONF environment variable to point to the softhsm2 configuration
    39  file.
    40  
    41  You can then use softhsm to create the token that will handle the cryptographic
    42  operations of your Fabric node inside an HSM slot. In this example, we create a
    43  token labelled "fabric" and set the pin to "71811222". After you have created
    44  the token, update the configuration file to use PKCS11 and your token as the
    45  crypto service provider. You can find an example `bccsp` section below:
    46  
    47  ```
    48  #############################################################################
    49  # BCCSP (BlockChain Crypto Service Provider) section is used to select which
    50  # crypto library implementation to use
    51  #############################################################################
    52  bccsp:
    53    default: PKCS11
    54    pkcs11:
    55      Library: /etc/hyperledger/fabric/libsofthsm2.so
    56      Pin: "71811222"
    57      Label: fabric
    58      hash: SHA2
    59      security: 256
    60      Immutable: false
    61  ```
    62  
    63  By default, when private keys are generated using the HSM, the private key is mutable, meaning PKCS11 private key  attributes can be changed after the key is generated. Setting `Immutable` to `true` means that the private key attributes cannot be altered after key generation. Before you configure immutability by setting `Immutable: true`, ensure that PKCS11 object copy is supported by the HSM.
    64  
    65  If you are using AWS HSM there is an additional step required:
    66  
    67  - Add the parameter, `AltID` to the `pkcs11` section of the `bccsp` block. When AWS HSM is being used, this parameter is used to assign a unique value for the Subject Key Identifier (SKI). Create a long secure string outside of Fabric and assign it to the `AltID` parameter. For example:
    68  
    69    ```
    70    #############################################################################
    71    # BCCSP (BlockChain Crypto Service Provider) section is used to select which
    72    # crypto library implementation to use
    73    #############################################################################
    74    bccsp:
    75      default: PKCS11
    76      pkcs11:
    77        Library: /etc/hyperledger/fabric/libsofthsm2.so
    78        Pin: 71811222
    79        Label: fabric
    80        hash: SHA2
    81        security: 256
    82        Immutable: false
    83        AltID: 4AMfmFMtLY6B6vN3q4SQtCkCQ6UY5f6gUF3rDRE4wqD4YDUrunuZbmZpVk8zszkt86yenPBUGE2aCQCZmQFcmnj3UaxyLzfTMjCnapAe3
    84    ```
    85  
    86  You can also use environment variables to override the relevant fields of the configuration file. If you are connecting to softhsm2 using the Fabric CA server, you could set the following environment variables or directly set the corresponding values in the CA server config file:
    87  
    88  ```
    89  FABRIC_CA_SERVER_BCCSP_DEFAULT=PKCS11
    90  FABRIC_CA_SERVER_BCCSP_PKCS11_LIBRARY=/etc/hyperledger/fabric/libsofthsm2.so
    91  FABRIC_CA_SERVER_BCCSP_PKCS11_PIN=71811222
    92  FABRIC_CA_SERVER_BCCSP_PKCS11_LABEL=fabric
    93  ```
    94  
    95  If you are connecting to softhsm2 using the Fabric peer, you could set the following environment variables or directly set the corresponding values in the peer config file:
    96  
    97  ```
    98  CORE_PEER_BCCSP_DEFAULT=PKCS11
    99  CORE_PEER_BCCSP_PKCS11_LIBRARY=/etc/hyperledger/fabric/libsofthsm2.so
   100  CORE_PEER_BCCSP_PKCS11_PIN=71811222
   101  CORE_PEER_BCCSP_PKCS11_LABEL=fabric
   102  ```
   103  
   104  If you are connecting to softhsm2 using the Fabric orderer, you could set the following environment variables or directly set the corresponding values in the orderer config file:
   105  
   106  ```
   107  ORDERER_GENERAL_BCCSP_DEFAULT=PKCS11
   108  ORDERER_GENERAL_BCCSP_PKCS11_LIBRARY=/etc/hyperledger/fabric/libsofthsm2.so
   109  ORDERER_GENERAL_BCCSP_PKCS11_PIN=71811222
   110  ORDERER_GENERAL_BCCSP_PKCS11_LABEL=fabric
   111  ```
   112  
   113  If you are deploying your nodes using docker compose, after building your own
   114  images, you can update your docker compose files to mount the softhsm library
   115  and configuration file inside the container using volumes. As an example, you
   116  would add the following environment and volumes variables to your docker compose
   117  file:
   118  ```
   119    environment:
   120       - SOFTHSM2_CONF=/etc/hyperledger/fabric/config.file
   121    volumes:
   122       - /home/softhsm/config.file:/etc/hyperledger/fabric/config.file
   123       - /usr/local/Cellar/softhsm/2.1.0/lib/softhsm/libsofthsm2.so:/etc/hyperledger/fabric/libsofthsm2.so
   124  ```
   125  
   126  ## Setting up a network using HSM
   127  
   128  If you are deploying Fabric nodes using an HSM, your private keys need to be
   129  generated and stored inside the HSM rather than inside the `keystore` folder of the node's
   130  local MSP folder. The `keystore` folder of the MSP will remain empty. Instead,
   131  the Fabric node will use the subject key identifier of the signing certificate
   132  in the `signcerts` folder to retrieve the private key from inside the HSM.
   133  The process for creating the node MSP folder differs depending on whether you
   134  are using a Fabric Certificate Authority (CA) your own CA.
   135  
   136  ### Before you begin
   137  
   138  Before configuring a Fabric node to use an HSM, you should have completed the following steps:
   139  
   140  1. Created a partition on your HSM Server and recorded the `Label` and `PIN` of the partition.
   141  2. Followed instructions in the documentation from your HSM provider to configure an HSM Client that communicates with your HSM server.
   142  
   143  ### Using an HSM with a Fabric CA
   144  
   145  You can set up a Fabric CA to use an HSM by making the same edits to the CA server configuration file as you would make to a peer or ordering node. Because you can use the Fabric CA to generate keys inside an HSM, the process of creating the local MSP folders is straightforward. Use the following steps:
   146  
   147  1. Modify the `bccsp` section of the Fabric CA server configuration file and point to the `Label` and `PIN` that you created for your HSM. When the Fabric CA server starts, the private key is generated and stored in the HSM. If you are not concerned about exposing your CA signing certificate, you can skip this step and only configure an HSM for your peer or ordering nodes, described in the next steps.
   148  
   149  2. Use the Fabric CA client to register the peer or ordering node identities with your CA.
   150  
   151  3. Before you deploy a peer or ordering node with HSM support, you need to enroll the node identity by storing its private key in the HSM. Edit the `bccsp` section of the Fabric CA client config file or use the associated environment variables to point to the HSM configuration for your peer or ordering node. In the Fabric CA Client configuration file, replace the default `SW` configuration with the `PKCS11` configuration and provide the values for your own HSM:
   152  
   153    ```
   154    bccsp:
   155      default: PKCS11
   156      pkcs11:
   157        Library: /etc/hyperledger/fabric/libsofthsm2.so
   158        Pin: "71811222"
   159        Label: fabric
   160        hash: SHA2
   161        security: 256
   162        Immutable: false
   163    ```
   164  
   165    Then for each node, use the Fabric CA client to generate the peer or ordering node's MSP folder by enrolling against the node identity that you registered in step 2. Instead of storing the private key in the `keystore` folder of the associated MSP, the enroll command uses the node's HSM to generate and store the private key for the peer or ordering node. The `keystore` folder remains empty.
   166  
   167  4. To configure a peer or ordering node to use the HSM, similarly update the `bccsp` section of the peer or orderer configuration file to use PKCS11 and provide the `Label` and `PIN`. Also, edit the value of the `mspConfigPath` (for a peer node) or the `LocalMSPDir` (for an ordering node) to point to the MSP folder that was generated in the previous step using the Fabric CA client. Now that the peer or ordering node is configured to use HSM, when you start the node it will be able sign and endorse transactions with the private key protected by the HSM.
   168  
   169  ### Using an HSM with your own CA
   170  
   171  If you are using your own Certificate Authority to deploy Fabric components, you
   172  can use an HSM using the following steps:
   173  
   174  1. Configure your CA to communicate with an HSM using PKCS11 and create a `Label` and `PIN`.
   175  Then use your CA to generate the private key and signing certificate for each
   176  node, with the private key generated inside the HSM.
   177  
   178  2. Use your CA to build the peer or ordering node MSP folder. Place the signing certificate that you generated in step 1 inside the `signcerts` folder. You can leave the `keystore` folder empty.
   179  
   180  3. To configure a peer or ordering node to use the HSM, similarly update the `bccsp` section of the peer or orderer configuration file to use PKCS11 andand provide the `Label` and `PIN`. Edit the value of the `mspConfigPath` (for a peer node) or the `LocalMSPDir` (for an ordering node) to point to the MSP folder that was generated in the previous step using the Fabric CA client. Now that the peer or ordering node is configured to use HSM, when you start the node it will be able sign and endorse transactions with the private key protected by the HSM.
   181  
   182  <!--- Licensed under Creative Commons Attribution 4.0 International License
   183  https://creativecommons.org/licenses/by/4.0/ -->