Fabric-CA-1.0-Alpha 小结

#1. 整体概览#

在Fabric 1.0版本中，原0.6版本中的“Membership Service”已经被“Fabric CA”所替代。

Fabric CA是Hyperledger Fabric的证书颁发机构，它提供的功能如下：
1）身份的注册，或连接到LDAP作为用户注册表;
2）发放登记证书（ECerts）;
3）发布交易证书（TCerts），在Hyperledger Fabric blockchain上进行交易时提供匿名性和不可链接性;
4）证书更新和撤销。

Fabric CA包含一个client端和一个server端。在Fabric 1.0版本中，CA可以脱离Docker镜像，作为一个独立的服务来运行。若使用docker启动，所有的CA服务都是在一个专门的镜像（名称类似于“ca”）中进行执行。

Fabric CA提供了两种访问方式调用Server服务，一种是通过Client调用，另一种是通过SDK调用。两种调用都是REST风格的。SDK的API接口位于fabric-ca工程的`fabric-ca/swagger/swagger-fabric-ca.json`。本文使用的是通过Client调用。

##1.1 Fabric CA整体架构图##
[1]
Server端由一个集群组成，包括前端的一个高可用的代理服务器，连接着若干个CA Server集群，这些集群将数据共同存放在同一个数据服务器上。数据库可能是MySQL、LDAP、PostgresSQL或者SQLite。

##1.2 Fabric CA运行流程的时序图##

###具体步骤包括：
*1) Server端初始化*
*2) CA根证书生成*
*3) Server端启动服务*
*4) Client端向Server端请求登记*
*5) Server端向Client端返回登记证书ECert*
*6) Client端向Server端请求注册节点*
*7) Server端向Client端返回节点注册信息结果*
*8) Client端向Server端请求登记节点*
*9) Server端生成TCert，存入数据库*
*10) Server端向Client端返回登记结果*
#2. 安装#

##2.1 Dokcer启动##

###2.1.1 拉取镜像###
```
docker pull hyperledger/fabric-ca:x86_64-1.0.0-alpha
```

###2.1.2 使用Docker-Compose启动###
将下部分代码添加到`docker-compose.yaml`中的service中，使用`docker-compose up`启动ca服务节点
```
  ca:
    image: hyperledger/fabric-ca:x86_64-1.0.0-alpha
    container_name: fabric-ca
    ports:
      - "8888:8888"
    environment:
      - FABRIC_CA_HOME=/etc/hyperledger/fabric-ca
    volumes:
      - "./fabric-ca:/etc/hyperledger/fabric-ca"
    command: sh -c 'fabric-ca-server start -b admin:adminpw'
```

##2.2 Native启动##
###2.2.1前提条件###
 - Go 1.7版本或以上
 - GOPATH环境配置正确
 - 安装libtool和libtdhl-dev

### 2.2.2 安装方法 ###
可直接使用“go get”命令进行安装。“go get”相当于“git clone”+“go install”
```shell
#go get -u github.com/hyperledger/fabric-ca/cmd/...
```

后续的操作和在Docker中类似，这里我们主要讲Docker启动的情况。

#3. Fabric-CA-Server#
官方说明如下：
```shell
Hyperledger Fabric Certificate Authority Server

Usage:
  fabric-ca-server [command]

Available Commands:
  init        Initialize the fabric-ca server
  start       Start the fabric-ca server

Flags:
      --address string                  Listening address of fabric-ca-server (default "0.0.0.0")
  -b, --boot string                     The user:pass for bootstrap admin which is required to build default config file
      --ca.certfile string              PEM-encoded CA certificate file (default "ca-cert.pem")
      --ca.chainfile string             PEM-encoded CA chain file (default "ca-chain.pem")
      --ca.keyfile string               PEM-encoded CA key file (default "ca-key.pem")
  -n, --ca.name string                  Certificate Authority name
  -c, --config string                   Configuration file (default "fabric-ca-server-config.yaml")
      --csr.cn string                   The common name field of the certificate signing request to a parent fabric-ca-server
      --csr.serialnumber string         The serial number in a certificate signing request to a parent fabric-ca-server
      --db.datasource string            Data source which is database specific (default "fabric-ca-server.db")
      --db.tls.certfiles string         PEM-encoded comma separated list of trusted certificate files (e.g. root1.pem, root2.pem)
      --db.tls.client.certfile string   PEM-encoded certificate file when mutual authenticate is enabled
      --db.tls.client.keyfile string    PEM-encoded key file when mutual authentication is enabled
      --db.tls.enabled                  Enable TLS for client connection
      --db.type string                  Type of database; one of: sqlite3, postgres, mysql (default "sqlite3")
  -d, --debug                           Enable debug level logging
      --ldap.enabled                    Enable the LDAP client for authentication and attributes
      --ldap.groupfilter string         The LDAP group filter for a single affiliation group (default "(memberUid=%s)")
      --ldap.url string                 LDAP client URL of form ldap://adminDN:adminPassword@host[:port]/base
      --ldap.userfilter string          The LDAP user filter to use when searching for users (default "(uid=%s)")
  -p, --port int                        Listening port of fabric-ca-server (default 7054)
      --registry.maxenrollments int     Maximum number of enrollments; valid if LDAP not enabled
      --tls.certfile string             PEM-encoded TLS certificate file for server's listening port (default "ca-cert.pem")
      --tls.enabled                     Enable TLS on the listening port
      --tls.keyfile string              PEM-encoded TLS key for server's listening port (default "ca-key.pem")
  -u, --url string                      URL of the parent fabric-ca-server

Use "fabric-ca-server [command] --help" for more information about a command.
```

##3.1 初始化Server服务##

###3.1.1 指令介绍###
```
# fabric-ca-server init -b admin:adminpw
```
-b在这里指的是bootstrap，也就是启动加载状态。

有一个名为`fabric-ca-server-config.yaml`的配置文件会在节点启动时自动生成。我们也可以根据里面的内容自定义配置CSR信息，使用 `--config 文件名`来进行启动配置。

CSR为“Certificate Signing Request”的缩写，即证书签名请求。

目前在keys中支持的算法和相关长度如下：

Fabric-CA 1.0支持MySQL、LDAP、PostgresSQL和SQLite，这里配置用的是默认的SQLite。其他配置方法暂且不表。

###3.1.2 示例###
```
root@0f86c3e1cf15:/etc/hyperledger/fabric-ca# fabric-ca-server init -b admin:adminpw
2017/03/21 08:54:23 [INFO] Configuration file location: /etc/hyperledger/fabric-ca/fabric-ca-server-config.yaml
2017/03/21 08:54:23 Initialize BCCSP [SW]
2017/03/21 08:54:23 [INFO] The CA key and certificate files already exist
2017/03/21 08:54:23 [INFO] Key file location: /etc/hyperledger/fabric-ca/ca-key.pem
2017/03/21 08:54:23 [INFO] Certificate file location: /etc/hyperledger/fabric-ca/ca-cert.pem
2017/03/21 08:54:23 [INFO] Initialized sqlite3 data base at /etc/hyperledger/fabric-ca/fabric-ca-server.db
2017/03/21 08:54:23 [INFO] Initialization was successful
```

##3.2 启动Server服务##

###3.2.1 指令介绍###
```
fabric-ca-server start -b <admin>:<adminpw>
```
这里，默认调用的启动配置文件为`fabric-ca-server-config.yaml`，如果需要自定义配置，还是使用 `--config 文件名`来进行启动配置。
成功后，server端会在预先配置的环境路径下生成相应的ca证书文件，并在配置的端口号上进行服务监听。这里我们在端口8888上进行监听。

###3.2.2 示例###
```
root@0f86c3e1cf15:/etc/hyperledger/fabric-ca# fabric-ca-server start -b admin:adminpw
2017/03/21 08:54:50 [INFO] Configuration file location: /etc/hyperledger/fabric-ca/fabric-ca-server-config.yaml
2017/03/21 08:54:50 Initialize BCCSP [SW]
2017/03/21 08:54:50 [INFO] The CA key and certificate files already exist
2017/03/21 08:54:50 [INFO] Key file location: /etc/hyperledger/fabric-ca/ca-key.pem
2017/03/21 08:54:50 [INFO] Certificate file location: /etc/hyperledger/fabric-ca/ca-cert.pem
2017/03/21 08:54:50 [INFO] Initialized sqlite3 data base at /etc/hyperledger/fabric-ca/fabric-ca-server.db
2017/03/21 08:54:50 [INFO] Listening at http://0.0.0.0:8888
```

#4. Fabric-CA-Client#

官方说明如下：
```shell
Hyperledger Fabric Certificate Authority Client

Usage:
  fabric-ca-client [command]

Available Commands:
  enroll      Enroll user
  getcacert   Get CA certificate chain
  reenroll    Reenroll user
  register    Register user
  revoke      Revoke user

Flags:
  -c, --config string                Configuration file (default "/etc/hyperledger/fabric-ca/clients/admin/fabric-ca-client-config.yaml")
      --csr.cn string                The common name field of the certificate signing request to a parent fabric-ca-server
      --csr.serialnumber string      The serial number in a certificate signing request to a parent fabric-ca-server
  -d, --debug                        Enable debug level logging
      --enrollment.hosts string      Comma-separated host list
      --enrollment.label string      Label to use in HSM operations
      --enrollment.profile string    Name of the signing profile to use in issuing the certificate
      --id.affiliation string        The identity's affiliation
      --id.attr string               Attributes associated with this identity (e.g. hf.Revoker=true)
      --id.maxenrollments int        The maximum number of times the secret can be reused to enroll.
      --id.name string               Unique name of the identity
      --id.secret string             The enrollment secret for the identity being registered
      --id.type string               Type of identity being registered (e.g. 'peer, app, user')
  -M, --mspdir string                Membership Service Provider directory (default "msp")
  -m, --myhost string                Hostname to include in the certificate signing request during enrollment (default "0f86c3e1cf15")
      --tls.certfiles string         PEM-encoded comma separated list of trusted certificate files (e.g. root1.pem, root2.pem)
      --tls.client.certfile string   PEM-encoded certificate file when mutual authenticate is enabled
      --tls.client.keyfile string    PEM-encoded key file when mutual authentication is enabled
      --tls.enabled                  Enable TLS for client connection
  -u, --url string                   URL of fabric-ca-server (default "http://localhost:7054")

Use "fabric-ca-client [command] --help" for more information about a command.

```
##4.1启动用户登记##

###4.1.1 指令介绍###
```
#fabric-ca-client enroll -u http://admin:adminpw@localhost:8888
```
登记启动用户会在用户的home路径下生成登记证书文件ECert。
###4.1.2 示例###
```
root@0f86c3e1cf15:/etc/hyperledger/fabric-ca# fabric-ca-client enroll -u http://admin:adminpw@localhost:8888
2017/03/21 08:59:09 [INFO] User provided config file: /etc/hyperledger/fabric-ca/fabric-ca-client-config.yaml
2017/03/21 08:59:09 [INFO] Configuration file location: /etc/hyperledger/fabric-ca/fabric-ca-client-config.yaml
2017/03/21 08:59:09 Initialize BCCSP [SW]
2017/03/21 08:59:09 [INFO] received CSR
2017/03/21 08:59:09 [INFO] generating key: ecdsa-256
2017/03/21 08:59:09 [INFO] encoded CSR
2017/03/21 08:59:09 [INFO] Stored client key at /etc/hyperledger/fabric-ca/msp/keystore/key.pem
2017/03/21 08:59:09 [INFO] Stored client certificate at /etc/hyperledger/fabric-ca/msp/signcerts/cert.pem
2017/03/21 08:59:09 [INFO] Stored CA certificate chain at /etc/hyperledger/fabric-ca/msp/cacerts/.pem
```
##4.2 新身份注册##
##4.2.1  指令介绍##
```
# fabric-ca-client register
```

在注册阶段，server端需要检查被注册对象的两方面内容：
 - 1 被注册的对象的角色一定要在预先配置的“hf.Registrar.Roles”属性中约定的范围内。比如，如果“hf.Registrar.Roles”约定的角色包括“peer”和“client”，那么被注册对象就只能是这两个角色中的一个，如果被注册对象的角色为“user”，那么注册就不能被通过。
 - 2 被注册对象的从属关系参数一定要归属于预先配置的组织属性。换句话说，被注册对象的affiliation参数一定要是预先配置的affiliation参数的一个前缀。例如，假设预先配置的组织关系为：“a.b.c”，那么新注册的对象的affiliation属性可以是“a.b.c”，也可以是“a.b”，但“a.c”就不能通过注册。

下面是id配置的一个示例：
```
id:
  name: MyPeer1
  type: peer
  affiliation: org1.department1
  attributes:
    - name: SomeAttrName
      value: SomeAttrValue
    - name: foo
      value: bar
```

如果想要在后面允许对这个ID进行注销，在这里配置的attributes中要包含“hf.Revoker”，即：
```
  attributes:
    - name: hf.Revoker
      value: true
```

###4.2.2 示例###
```
root@0f86c3e1cf15:/etc/hyperledger/fabric-ca# fabric-ca-client register --id.name cliTest00
2017/03/21 09:05:16 [INFO] User provided config file: /etc/hyperledger/fabric-ca/clients/admin/fabric-ca-client-config.yaml
2017/03/21 09:05:16 Initialize BCCSP [SW]
2017/03/21 09:05:16 [INFO] Configuration file location: /etc/hyperledger/fabric-ca/clients/admin/fabric-ca-client-config.yaml
Password: oLtPkJRCzdTH
```
这里随机生成了一个Password，将在后面的节点登记中用到。
在指令中使用flag来临时自定义用户名和密码：`--id.name <用户名> --id.secret <密码>`

##4.3 节点身份登记##
###4.3.1 指令介绍###

官方文档上说，在节点身份登记之前，要先指定FABRIC_CA_CERT_FILE和FABRIC_CA_KEY_FILE两个环境变量，生成的peer.pem和key.pem两个证书文件作为TCert。但是我的试验中，生成的证书文件路径仍然是在FABRIC_CA_CLIENT_HOME相应的路径下，不知是否是仍然存在的bug。
```
# export FABRIC_CA_CERT_FILE=$MSP_DIR/signcerts/peer.pem
# export FABRIC_CA_KEY_FILE=$MSP_DIR/keystore/key.pem
fabric-ca client enroll -u http://<peer ID>:<password>@localhost:port
```
这里Peer ID为注册时的id name，password为上文提到的注册时生成的密码。

###4.3.2 示例###
```
root@0f86c3e1cf15:/etc/hyperledger/fabric-ca# fabric-ca-client enroll -u http://cliTest00:oLtPkJRCzdTH@localhost:8888
2017/03/21 09:07:48 [INFO] User provided config file: /etc/hyperledger/fabric-ca/clients/admin/fabric-ca-client-config.yaml
2017/03/21 09:07:48 [INFO] Configuration file location: /etc/hyperledger/fabric-ca/clients/admin/fabric-ca-client-config.yaml
2017/03/21 09:07:48 Initialize BCCSP [SW]
2017/03/21 09:07:48 [INFO] received CSR
2017/03/21 09:07:48 [INFO] generating key: ecdsa-256
2017/03/21 09:07:48 [INFO] encoded CSR
2017/03/21 09:07:48 [INFO] Stored client key at /etc/hyperledger/fabric-ca/clients/admin/msp/keystore/key.pem
2017/03/21 09:07:48 [INFO] Stored client certificate at /etc/hyperledger/fabric-ca/clients/admin/msp/signcerts/cert.pem
2017/03/21 09:07:48 [INFO] Stored CA certificate chain at /etc/hyperledger/fabric-ca/clients/admin/msp/cacerts/.pem
```
##4.4 身份重登记##
###4.4.1 指令介绍###
```
# fabric-ca-client reenroll
```
当登记的身份过期时，可以利用reenroll命令对身份进行重新登记。注意，这个指令后面不能添加登记的名称和密码，只是按照之前配置好的内容进行重新登记。
###4.4.2 示例###
```
root@0f86c3e1cf15:/etc/hyperledger/fabric-ca# fabric-ca-client reenroll                                                                                                        
2017/03/21 10:11:36 [INFO] User provided config file: /etc/hyperledger/fabric-ca/clients/admin/fabric-ca-client-config.yaml
2017/03/21 10:11:36 Initialize BCCSP [SW]
2017/03/21 10:11:36 [INFO] Configuration file location: /etc/hyperledger/fabric-ca/clients/admin/fabric-ca-client-config.yaml
2017/03/21 10:11:36 [INFO] received CSR
2017/03/21 10:11:36 [INFO] generating key: ecdsa-256
2017/03/21 10:11:37 [INFO] encoded CSR
2017/03/21 10:11:37 [INFO] Stored client key at /etc/hyperledger/fabric-ca/clients/admin/msp/keystore/key.pem
2017/03/21 10:11:37 [INFO] Stored client certificate at /etc/hyperledger/fabric-ca/clients/admin/msp/signcerts/cert.pem
2017/03/21 10:11:37 [INFO] Stored CA certificate chain at /etc/hyperledger/fabric-ca/clients/admin/msp/cacerts/.pem

```
##4.5 证书或身份撤销##
###4.5.1 指令介绍###
```
Usage:
  fabric-ca-client revoke [flags]

Flags:
  -a, --aki string      AKI
  -e, --eid string      Enrollment ID (Optional)
  -r, --reason string   Reason for revoking
  -s, --serial string   Serial Number
```
官方给出的说明有些错误，被标（Optional）的应该是“Reason for revoking”部分。实际上，要求指令后面的flag内容为下面两种格式中的一种：
```
fabric-ca-client revoke -a xxx -s yyy -r <reason>
```
或
```
fabric-ca-client revoke -e <enrollment_id> -r <reason>
```

支持的<reason>包括：
```
Reasons:
- unspecified
- keycompromise
- cacompromise
- affiliationchange
- superseded
- cessationofoperation
- certificatehold
- removefromcrl
- privilegewithdrawn
- aacompromise
```

AKI（Authority Key Identifier）和Serial Number都是在身份登记后生成的cert.pem文件中。我们需要对这个文件进行解析。可以使用OpenSSL进行解析：
```
root@xiao-virtual-machine:/home/xiao/test/fabric-ca/clients/admin/msp/signcerts# openssl x509 -in cert.pem -text -noout -serial
Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number:
            4a:ad:ce:89:16:9d:36:23:99:c5:37:7a:e9:2b:06:d7:8a:f3:f3:da
    Signature Algorithm: ecdsa-with-SHA256
        Issuer: C=US, ST=North Carolina, O=Hyperledger, OU=Fabric, CN=fabric-ca-server
        Validity
            Not Before: Mar 21 09:21:00 2017 GMT
            Not After : Feb 17 17:21:00 2018 GMT
        Subject: C=US, ST=North Carolina, O=Hyperledger, OU=Fabric, CN=test001
        Subject Public Key Info:
            Public Key Algorithm: id-ecPublicKey
                Public-Key: (256 bit)
                pub: 
                    04:8a:ff:a4:44:2c:10:e5:4c:4e:7d:7d:0f:bb:28:
                    aa:c0:30:b8:53:2c:0d:1d:26:92:c9:85:7c:0d:24:
                    7a:c0:25:5c:18:c9:f7:fa:d2:53:e9:00:00:99:d1:
                    04:30:a1:d5:dd:a1:3c:30:37:5a:f9:70:e5:aa:6e:
                    89:6c:54:ad:18
                ASN1 OID: prime256v1
        X509v3 extensions:
            X509v3 Key Usage: critical
                Certificate Sign
            X509v3 Basic Constraints: critical
                CA:FALSE
            X509v3 Subject Key Identifier: 
                6F:76:CA:12:7D:20:5F:27:6F:93:55:15:48:F1:32:6C:83:2A:F6:03
            X509v3 Authority Key Identifier: 
                keyid:A5:1F:27:F8:09:78:46:4D:63:A8:23:48:B3:B4:01:1D:FB:FF:C9:43

            X509v3 Subject Alternative Name: 
                DNS:38cdca9067ac
    Signature Algorithm: ecdsa-with-SHA256
         30:46:02:21:00:a6:3e:33:78:e2:59:8c:e2:ba:6f:0f:7b:01:
         66:5d:67:08:af:81:de:1b:47:20:c1:00:e5:11:ba:1e:7a:f1:
         f2:02:21:00:95:1a:31:06:6e:ab:cd:91:85:02:38:8c:72:87:
         70:8e:e5:bc:7d:a8:0f:05:a1:55:60:c9:49:a0:72:1d:a1:11
serial=4AADCE89169D362399C5377AE92B06D78AF3F3DA
```
这里，AKI为
```
A5:1F:27:F8:09:78:46:4D:63:A8:23:48:B3:B4:01:1D:FB:FF:C9:43```
(需要去除冒号），Serial Number为
```
4AADCE89169D362399C5377AE92B06D78AF3F3DA
```

###4.5.2 示例###
```
root@0f86c3e1cf15:/etc/hyperledger/fabric-ca# fabric-ca-client revoke -e test01   
2017/03/21 11:11:05 [INFO] User provided config file: /etc/hyperledger/fabric-ca/clients/admin/fabric-ca-client-config.yaml
2017/03/21 11:11:05 Initialize BCCSP [SW]
2017/03/21 11:11:05 [INFO] Configuration file location: /etc/hyperledger/fabric-ca/clients/admin/fabric-ca-client-config.yaml
2017/03/21 11:11:05 [INFO] Revocation was successful
```
这里只是表述了通过eid进行撤销的方式，另一种方法总是不能成功，与Hyperledger项目组的成员沟通后，说是存在bug，目前仍在修复中。所以这里暂且不表。

#5. 其他#

##5.1 优先级##
命令执行的优先级从高到低依次是：
 - 1 命令行flag
 - 2 环境变量
 - 3 配置文件

#References#
[1] https://github.com/hyperledger/fabric/blob/master/docs/source/Setup/ca-setup.rst