4. 硬件加密使用指南

硬件加密设计链接：

4.1. 功能介绍

CA服务根私钥硬件保护
共识签名私钥硬件保护
SDK用户签名私钥硬件保护
加密数据库对称密钥硬件保护
支持国际标准算法：RSA、AES和ECDSA
支持国密标准算法：SM2、SM4

4.2. 启用硬件加密

4.2.1. 配置项

硬件加密相关配置目前有两种配置方式，一种是配置文件方式，另一种是环境变量方式，如果同时配置，则优先使用配置文件设置的配置项。注：硬件加密的开关配置,目前仅支持配置文件配置，需要将enabled设置为true，并设置type为pkcs11或者sdf

4.2.2. 配置文件方式

在chainmaker-go、sdk-go以及chainmaker-cryptogen的配置文件中，硬件加密相关的开关配置和加密机配置如下：

pkcs11:
  enabled: true                                       # set true if enable pkcs11
  type: pkcs11                                        # support pkcs11 and sdf
  library: /usr/local/lib64/libpkcs11.so              # path to the libxxx.so file of hsm
  label: HSM                                          # label for the slot to be used
  password: 12345678                                  # password to logon the HSM
  session_cache_size: 10                              # size of HSM session cache, default 10
  hash: ""                                            # hash algorithm used to compute SKI, not used now

注: 当开启硬件加密并且type为sdf时，仅需配library和session_cache_size即可，其他配置默认不生效

4.2.3. 环境变量方式

首先需要在配置文件中, 打开硬件加密开关配置，如下：

pkcs11:
  enabled: true                                       # set true if enable pkcs11
  type: pkcs11                                        # support pkcs11 and sdf

然后通过环境变量指定加密机相关的其他配置：

export HSM_LIB=/usr/local/lib64/libupkcs11.so # path to the libxxx.so file of hsm
export HSM_LABEL="HSM"                        # label for the slot to be used
export HSM_PASSWORD=12345678                  # password to logon the HSM
export HSM_SESSION_CACHE_SIZE=10              #size of HSM session cache, default 10
export HSM_HASH=""                            # hash algorithm used to compute SKI, not used now

4.2.4. 适配器插件配置

由于不同硬件密码机厂商在实现pkcs11和sdf标准上存在着细微差异，引入适配器插件的方式来进行屏蔽，目前长安链适配多家厂商密码机。

密码机适配器插件接口定义和实现参考：硬件加密设计

启用硬件加密后，同时需要设置密码机适配器插件，需要通过HSM_ADAPTER_LIB环境变量指定适配器插件链接库，如下：

export HSM_ADAPTER_LIB=/usr/local/lib64/hsm_adapter.so

如果用户进行了长安链版本升级，从v2.3.0之前版本升级到 >= v2.3.0版本，需要注意以下几点：

v2.3.0之前版本仅支持pkcs11配置方式
v2.3.0兼容之前版本，如果启用了硬件加密，需要配置选项type字段设置为pkcs11；设置HSM_ADAPTER_LIB环境变量，指定适配器插件链接库。

4.3. 测试网络

4.3.1. 测试网络部署架构

首先在密码设备创建CA根私钥、sdk用户私钥以及节点共识私钥。
通过chainmaker-cryptogen工具（以下统称cryptogen）的generate命令一键生成测试网络证书。
使用密码机节点私钥和cryptogen生成的节点证书启动chainmaker区块链网络
sdk使用密码机用户私钥进行签名，并将交易发送给chainmaker网络
chainmaker网络节点使用用户证书对交易进行验签名，并执行交易

4.3.2. cryptogen启用硬件加密

修改配置文件chainmaker-cryptogen/config/crypto_config_template.yml，增加或修改pkcs11相关配置：

crypto_config:
  - domain: chainmaker.org
    host_name: wx-org
    count: 4                # 如果为1，直接使用host_name，否则添加递增编号
    pk_algo: sm2
    ski_hash: sha256
    #pkcs11配置, 
    pkcs11:
      enabled: true                             #启用硬件加密(此处设置为true)
      library: /usr/local/lib64/libpkcs11.so    #密码机pkcs11连接库
      label: HSM                                #密码机slot对应label
      password: 12345678                        #密码机登陆密码
      session_cache_size: 10
      hash: "" 
    # 其他配置（略）

新增/修改配置文件chainmaker-cryptogen/config/pkcs11_keys.yml，配置测试网各组织CA根、用户以及节点私钥KeyID，配置如下（以4组织，每个组织1个共识节点为例）：

pkcs11_keys:
  - wx-org1.chainmaker.org: #组织1相关密钥KeyId，keyPwd
      ca:
        - 1,123456
      node:
        consensus:
          - 2,123456
        common:
          - 3,123456
      user:
        admin:
          - 4,123456
        client:
          - 5,123456
        light:
          - 6,123456
  - wx-org2.chainmaker.org:
      ca:
        - 7,123456
      node:
        consensus:
          - 8,123456
        common:
          - 9,123456
      user:
        admin:
          - 10,123456
        client:
          - 11,123456 
        light:
          - 12,123456
  - wx-org3.chainmaker.org: #组织2相关密钥keyId，keyPwd
      ca:
        - 13,123456
      node:
        consensus:
          - 14,123456
        common:
          - 15,123456
      user:
        admin:
          - 16,123456
        client:
          - 17,123456
        light:
          - 18,123456
  - wx-org4.chainmaker.org:
      ca:
        - 19,123456
      node:
        consensus:
          - 20,123456
        common:
          - 21,123456
      user:
        admin:
          - 22,123456
        client:
          - 23,123456
        light:
          - 24,123456

4.3.3. 节点启用硬件加密

修改chainmaker节点配置模版chainmaker-go/config/config_tql/chainmaker.tpl，新增/修改pkcs11相关配置：

node:
  type:              full
  org_id:            {org_id}
  priv_key_file:     ../config/{org_path}/certs/{node_cert_path}.key
  cert_file:         ../config/{org_path}/certs/{node_cert_path}.crt
  signer_cache_size: 1000
  cert_cache_size:   1000
  #pkcs11配置（配置项说明参考cryptogen）
  pkcs11: 
    enabled: true
    type: pkcs11 #支持pkcs11和sdf
    library: /usr/local/lib64/libupkcs11.so     
    label: HSM                                       
    password: 12345678                               
    session_cache_size: 10                     
    hash: ""                                 

4.3.4. 本地启动chainmaker网络

参考自拉起服务
参考多机部署

4.3.5. sdk启用硬件加密

修改sdk配置文件sdk_config.yaml, 新增/修改pkcs11相关配置如下：

  nodes:
    - # 节点地址，格式为：IP:端口:连接数
      node_addr: "127.0.0.1:12301"
      conn_cnt: 10
      enable_tls: true
      trust_root_paths:
        - "./testdata/crypto-config/wx-org1.chainmaker.org/ca"
        - "./testdata/crypto-config/wx-org2.chainmaker.org/ca"
      # TLS hostname
      tls_host_name: "chainmaker.org"
  #pkcs11配置（配置说明参考cryptogen）
  pkcs11:
    enabled: true
    type: pkcs11
    library: /usr/local/lib64/libupkcs11.so
    label: HSM
    password: 12345678 
    session_cache_size: 10
    hash: ""

sdk测试
参考命令行工具
参考 SDK

4.4. 推荐部署架构

4.4.1. 部署架构图

说明：

CA使用单独密码设备
客户端SDK使用单独密码设备
节点使用一台或多台密码设别（根据组织结构和节点部署情况而定）

4.4.2. 密码设备部署

密码设备服务商提供（详情略）