Hyperledger Fabric-ca配置文件解读

一、 前言

项目需要引入fabric-ca，所以派我去研究fabric-ca的可行性。写这篇文章，为了记录自己的心得方便后续研究。可能有人会问我会什么没有fabric网络，因为这是后期工作，前期只是为了使用hyperledger fabric的证书和tls通信校验功能。

二、 配置

ca

ca:
  # Name of this CA
  name:
  # Key file (is only used to import a private key into BCCSP)
  keyfile:
  # Certificate file (default: ca-cert.pem)
  certfile:
  # Chain file
  chainfile:

ca.name 通常用来区分请求的fabric-server是哪一个，fabric-client通过--caname 参数请求。

至于keyfile和certfile，chainfile都是可以配置证书、私钥和证书链证书文件存放的路径以及名称。

tls

tls:
  # Enable TLS (default: false)
  enabled: true
  # TLS for the server's listening port
  certfile:
  keyfile:
  clientauth:
    type: noclientcert
    certfiles:

tls.enabled： 通过设置true来开启tls.默认为false.此设置将配置服务器端TLS，这意味着TLS将向客户端保证服务器的身份，并在它们之间提供双向加密通道。

tls.certfile : 每一个ca都需要在tls注册并登记在它可以和其他节点进行安全交易之前。因此，在部署组织ca和中间ca之前，需要部署tls。登记的证书就存放在设置的目录下。如果是root tls ca 这个选项为空。

tls.keyfile: 跟tls.cerfile类似。这个设置用来存放私钥。

如果以上足够满足需求，就跳过下面配置。如果需要网络中相互tls。则配置一下设置。(默认情况下，相互TLS处于禁用状态。）

tls.clientauth.type : 如果服务器还需要验证客户端的身份，则需要相互TLS（MTL）。配置mTLS时，客户机需要在TLS握手期间发送其证书。要为MTL配置CA，请将clientauth.type设置为RequirementVerifyClientCert。

tls.clientauth.certfiles : 仅对于MTL，提供服务器在验证客户端证书时使用的根证书颁发机构的PEM编码列表。在虚线yaml列表中指定证书。

cafiles

如规划CA主题中所述，cafiles参数可用于配置双头CA–一个包含组织CA和TLS CA的单一CA。此使用模式可为方便起见，允许每个CA维护其自己的配置，但仍共享相同的后端用户数据库。在cafiles参数中，输入第二个ca服务器（例如TLS ca）的fabric-ca-server-config.yaml的路径。辅助ca的配置可以包含与主ca服务器配置文件中相同的所有元素，但端口和TLS部分除外。

intermediate CA

intermediate:
  parentserver:
    url:
    caname:
​
  enrollment:
    hosts:
    profile:
    label:
​
  tls:
    certfiles:
    client:
      certfile:
      keyfile:

中间ca非必须配置，但是为了减少根ca的风险，你可能想要包含一个或多个中间ca.

在设置中间ca之前，你需要检查父ca中 csr.ca.pathlength参数。只有为0时，根ca才能颁发中间ca证书，但是这些中间ca不能为别的中间ca颁发证书。如果你想要这样的操作，在根ca的csr.ca.pathlength 设置为2.

parentserver.url : 指定父server的url。eg. https://<PARENT-CA-ENROLL-ID>:<PARENT-CA-SECRET>@<PARENT-CA-URL>:<PARENT-CA-PORT>

parentserver.caname: 输入父server的ca.name

enrollment.profile : 输入父server的signing.profile值。默认为ca.

tls.certfiles: 输入本地tls ca签字证书的名称。eg. tls/ca-cert.pem 路径为相对路径，相对于fabric-ca-server-configuration.yaml文件。

为了编辑中间ca设置，你需要遵循一下注意事项：

csr- 确保csr的cn为空

port - 确保唯一端口号

signing - 检查根节点 isca参数设置为true,并且maxpathlen设置为超过0。如果当前节点为中间ca给其他中间ca颁发证书，则也需要设置。否则就是0.

port

ca端口号，保证唯一。

user registry

registry:
  # Maximum number of times a password/secret can be reused for enrollment
  # (default: -1, which means there is no limit)
  maxenrollments: -1
​
  # Contains identity information which is used when LDAP is disabled
  identities:
     - name: <<<adminUserName>>>
       pass: <<<adminPassword>>>
       type: client
       affiliation: ""
       attrs:
          hf.Registrar.Roles: "*"
          hf.Registrar.DelegateRoles: "*"
          hf.Revoker: true
          hf.IntermediateCA: true
          hf.GenCRL: true
          hf.Registrar.Attributes: "*"
          hf.AffiliationMgr: true

如果你不是使用ldap用户注册，那么就需要配置registry节点。db也需要配置。这节被用来注册用户当ca server启动后。不会登记证书，如果需要证书，则需要使用fabric-client生成相关联证书。

maxenrollments : 用来限制一个用户使用enroll ID和密码生成证书的次数。reenroll命令可用于获取证书，无任何限制。

identities: 这节定义了ca启动时要注册的用户以及相关属性。在执行fabric-ca-server init命令后，<<adminUserName>> and <<adminPassword>>会被-b后参数所替换。

identities.type : 对于fabric只能选择client,peer,admin, orderer,member类型。

alliliation： 选择要与关联名称：参数指定的用户关联的从属关系。可选择的组织，在affiliations节点定义。

attrs: 上面包含的角色列表是针对“管理员”用户的，这意味着他们可以注册和注册其他用户。如果您正在注册非管理员用户，则不会授予他们这些权限。与身份相关联的hf属性会影响该身份注册其他用户的能力。

当用户随后“注册”时，类型、从属关系和属性在用户的签名证书中可见，并由策略用于强制授权。回想一下，注册是Fabric CA颁发证书密钥对的过程，证书密钥对由签名证书和构成身份的私钥组成。私钥和公钥首先由Fabric CA客户端本地生成，然后将公钥发送到CA，CA返回一个编码证书，即签名证书。

配置mysql

fabric-ca-server init -b admin:admin -p 7054 初始化server,会生成默认的配置文件

vim fabric-ca-server-config.yaml 在db:修改配置`

db:
  type: mysql
  datasource: root:rootpw@tcp(localhost:3306)/fabric_ca?parseTime=true

csr

csr:
   cn: <<<COMMONNAME>>>
   keyrequest:
     algo: ecdsa
     size: 256
   names:
      - C: US
        ST: "North Carolina"
        L:
        O: Hyperledger
        OU: Fabric
   hosts:
     - <<<MYHOST>>>
     - localhost
   ca:
      expiry: 131400h
      pathlength: <<<PATHLENGTH>>>

本节配置控制根证书生成。因此，如果你下个你要自定义任何值，推荐在第一次启动server时配置本节。你指定的值会在生成的证书中。如果你在server启动后，修改了csr配置，你需要删除ca-cert.pem和ca.key文件，然后再fabric-ca-server start。

csr.cn：此字段必须设置为CA引导标识的ID，并且可以留空。它默认为CA服务器引导标识。

csr.keyrequest： 自定义加密算法和密钥大小.

csr.names： 指定要用于证书颁发者的值，这些值在签名证书中可见。

csr.hosts: 提供host name。

csr.expiry : 指定根证书过期时间。

csr.pathlength： 如果有1个中间ca，则设置为1在根节点。如果当前节点是中间ca,则设置为0,除非它要为其他中间ca颁发证书。

signing

signing:
    default:
      usage:
        - digital signature
      expiry: 8760h
    profiles:
      ca:
         usage:
           - cert sign
           - crl sign
         expiry: 43800h
         caconstraint:
           isca: true
           maxpathlen: 0
           maxpathlenzero: true
      tls:
         usage:
            - signing
            - key encipherment
            - server auth
            - client auth
            - key agreement
         expiry: 8760h

本节中的默认值通常足以用于生产服务器。但是，您可能希望修改生成的组织CA和TLS证书的默认过期时间。请注意，这与CA根证书的csr部分中指定的到期日期不同。

如果这是TLS CA，建议您从配置文件中删除CA部分：因为TLS CA应该只颁发TLS证书。

如果你计划有超过1级的中间节点，你必须在根节点设置maxpathlen大于0.此字段表示证书链中可在此证书之后的非自颁发中间证书的最大数量。

要强制maxpathlen为0，还需要将maxpathlenzero设置为true。如果maxpathlen大于0，则maxpathlenzero应设置为false。

bccsp

bccsp:
    default: SW
    sw:
        hash: SHA2
        security: 256
        filekeystore:
            # The directory used for the software file-based keystore
            keystore: msp/keystore

本节主要控制私钥存放路径。上述配置导致私钥存储在CA服务器的文件系统中的msp/keystore文件夹中。为CA配置HSM时，CA私钥由HSM生成并存储在HSM中，而不是msp/keystore文件夹中。

eg.

bccsp:
  default: PKCS11
  pkcs11:
    Library: /etc/hyperledger/fabric/libsofthsm2.so
    Pin: 71811222
    Label: fabric
    hash: SHA2
    security: 256
    Immutable: false

cors

cors:
    enabled: false
    origins:
      - "*"

本节主要配置跨域问题。

cfg

cfg:
  affiliations:
    allowremove: false
  identities:
    allowremove: false  

默认配置设置为false时，如果不重新启动服务器，您将无法删除从属关系或标识。如果您预计需要在不重新启动服务器的情况下从生产环境中删除从属关系或标识，则在启动服务器之前，这两个字段都应设置为true。请注意，服务器启动后，只能使用Fabric CA client CLI命令修改从属关系和身份。

operations

operations:
    # host and port for the operations server
    listenAddress: 127.0.0.1:9443
​
    # TLS configuration for the operations endpoint
    tls:
        # TLS enabled
        enabled: false
​
        # path to PEM encoded server certificate for the operations server
        cert:
            file:
​
        # path to PEM encoded server key for the operations server
        key:
            file:
​
        # require client certificate authentication to access all resources
        clientAuthRequired: false
​
        # paths to PEM encoded ca certificates to trust for client authentication
        clientRootCAs:
            files: []

操作服务可用于CA的运行状况监视，并依赖相互TLS与节点通信。因此，需要将operations.tls.clientAuthRequired设置为true。当该值设置为true时，尝试确定节点运行状况的客户端需要提供有效的身份验证证书。如果客户端未提供证书或服务无法验证客户端的证书，则请求将被拒绝。这意味着客户端需要向TLS CA注册，并在请求中提供其TLS签名证书。

如果在相同机器部署两个ca,如果不修改listenAddress，第二个ca启动时会报错:the bind address is already in use.

metrics

metrics:
    # statsd, prometheus, or disabled
    provider: disabled
​
    # statsd configuration
    statsd:
        # network type: tcp or udp
        network: udp
​
        # statsd server address
        address: 127.0.0.1:8125
​
        # the interval at which locally cached counters and gauges are pushed
        # to statsd; timings are pushed immediately
        writeInterval: 10s
​
        # prefix is prepended to all emitted statsd metrics
        prefix: server

如果要监视CA的度量，请选择度量提供程序：

provider: Statsd是一种推动模式，Prometheus是一种拉动模式。因为Prometheus是一种拉式模型，所以不需要从结构CA服务器端进行任何配置。相反，Prometheus将请求发送到操作URL以轮询度量。

注意点：

  1. 首先fabric-ca每个组织部署一套，即,enroll-ca和tls。

  2. 组织内用户申请的签名证书和tls证书最好放在设计好的msp文件结构下，通过--mspdir指定不用用户证书。

  3. fabric-ca客户端如果带 -d参数，代表开启debug 模式。

  4. 登记时，tls为开启状态需要设置tls证书， --tls.certifiles xxx

  5. tls可以为fabric-ca-client，也可以是server+client

  6. 如果想要传递中文，新增affiliation和identity可以，但是如果Identity是中文，当选择颁发证书时，go net包会解析不出来中文，所以查不到相对应的identity。

  7. 初始化Mysql时，首先要确定mysql数据库，sql_mode应该没有 NO_ZERO_IN_DATE,NO_ZERO_DATE，否则会创建失败，因为fabric-ca在初始化时时间expiry默认00:00:00。

  8. 删除identity时，首先应该确认操作删除行为的用户是否有配置，"cfg.identities.allowremove"

三、server 常见命令

    初始化CA服务器

./fabric-ca-server init -b admin:admin 

-b  指定初始化时管理员身份，这是初始化fabric-ca-server时，必须参数。

初始化命令执行之后，会生成模板fabric-ca-server-config.yaml配置文件，里面包含了关于证书，用户，组织等配置，详见，2. 配置

如果是初始化中间CA的话，

./fabric-ca-server init -b admin:admin -u http://rootUser:rootPassword@localhost:7054

-u 指定这个参数，中间CA的证书会被父节点证书签字颁发。指定的父节点颁发证书的用户必须有

"hf.intermediateCA"  属性且为true。如果你不想使用init生成的证书，那就把你的证书放在fabric-ca-server.sh的同级目录，然后init即可，原理是，如果已经存在就不会进行覆盖。

开启fabric-ca服务器

./fabric-ca-server start -b admin:admin

如果是开启中间CA

需要在后面加上 -u (没配置配置文件中intermediate，如果配置了不需要加-u)

./fabric-ca-server start -b admin:admin -u http://rootUser:rootPassword@localhost:7054

四、 client 

 Identity (身份管理)

    添加用户身份

./fabric-ca-client register --id.name userName--id.type user --id.affiliation "org1.department1" --id.attrs "hf.Revoker=true" --id.secret userPassword -u http://admin:admin@localhost:7064`

--id.name 设置用户enrollmentId即用户名

--id.type 设置用户类型，fabric默认有: client, user, member, peer, order, admin

--id.affiliation 设置用户隶属组织，affiliation表中要存有该条数据，否则新增失败。

--id.attrs 设置用户拥有的权限属性，详情见 2.配置 user register

  修改用户身份

   修改密码

./fabric-ca-client identity modify user --secret newUserPassword

   修改组织关系

./fabric-ca-client identity modify user --affiliation org2

   修改用户类型

./fabric-ca-client identity modify user --type peer

 修改用户颁发证书次数

./fabric-ca-client identity modify user --maxenrollments 5

   删除用户身份

./fabric-ca-client identity remove user

Affiliation(组织管理)

添加组织

./fabric-ca-client affiliation add org1

修改组织

./fabric-ca-client affiliation modify org1 --name org2 --force

删除组织

./fabric-ca-client affiliation remove org2

注意事项：

1. 首先操作的用户必须有"hf.AffiliationMgr" 为true;

2. 用户的组织如果为"a.b" ，可以创建"a.b.c"不可以创建"a"或者"a.b"

Certificate (证书管理)

证书是安全的关键因素之一，所以官方没有提供修改接口，只能进行查询

./fabric-ca-client certificate list

./fabric-ca-client certificate list --id user

./fabric-ca-client certificate list --serial 1234 --aki 1234

 --expiration 过期时间

 --notrevoked 未注销

五、总结

本文为我通过读官方文档的逻辑，加上自己实践操作写下。下一篇，我将使用jdk进行，register,enroll, revoke,reenroll, affiliation进行操作和讲解，还有对中文操作，敬请期待。一个在开发道路上越走越远的小白。不喜勿喷，谢谢。