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