Fabric CA 官方使用者指南
一、Fabric CA概述
圖1.1 fabric-ca架構圖
Fabric Server端由一個伺服器叢集組成,以樹形架構組織CA Server節點,包含一個Root 節點和多箇中間節點。每個CA要麼是根CA,要麼是中間CA。每個中間CA都有一個父CA,它要麼是根CA,要麼是另一箇中間CA。
可以通過Client或SDK與伺服器叢集中的CA伺服器進行互動。客戶端首先路由到HA代理,由代理進行負載均衡,將客戶端連線至某一伺服器的叢集成員。
包括前端的一個高可用的代理伺服器,連線著若干個CA Server叢集,這些叢集將資料共同存放在同一個資料伺服器上。資料庫可能是MySQL、LDAP、PostgresSQL或者SQLite(叢集環境中不推薦使用SQLite)。
叢集中的所有CA伺服器都共享相同的資料庫,以跟蹤身份和證書。如果配置了LDAP,則將標識資訊儲存在LDAP中而不是資料庫中。
二、開始使用
(一)先決條件
1. 安裝Go 1.9+
2. 設定正確的GOPATH路徑,虛擬主機GOPATH:/home/greedystar/goapps
按照官方推薦的路徑結構,原始碼會在GOPATH/src/ github.com/hyperledger/目錄下
3. 安裝libtool和libtdhl-dev
Ubuntu安裝命令:sudo apt install libtool libltdl-dev
注意:在MacOSX上沒有必要使用libtdhl-dev
(二)安裝Fabric-ca
官方建議:
go get -ugithub.com/hyperledger/fabric-ca/cmd/...
注意:上面的命令將在$GOPATH/bin中安裝fabric-ca-server 和fabric-ca-client二進位制檔案,並克隆fabric-ca原始碼到$GOPATH/src/github.com/hyperledger/fabric-ca/目錄下,但在啟動server服務時會提示錯誤:panic: Version is not setfor fabric-ca library,原因是fabric-ca 1.1.0版本在執行時會呼叫lib/metadta/version.go,其中的version變數在初始化啟動時預設沒有賦值,因此可以通過編譯二進位制檔案時指定版本,命令如下:
go get -v-ldflags "-X github.com/hyperledger/fabric-ca/lib/metadata.Version=1.1.0"github.com/hyperledger/fabric-ca/cmd/...
注意:如果已經克隆了fabric-ca倉庫,請確保在執行“go get”命令之前已經在主分支上了。
配置fabric-ca-server和client的命令列路徑
- export GOPATH=/home/greedystar/apps
- export GOROOT=/usr/local/go
- export PATH=$PATH:$GOROOT/bin:$GOPATH/bin
安裝成功後可通過fabric-ca-server version檢視版本如下圖所示:
(三)啟動服務方式
1. Docker啟動
進入$GOPATH/src/github.com/hyperledger/fabric-ca/docker/server編輯docker-compose.yml,更改映象版本為本地fabric-ca映象版本,下圖紅框部分。
在docker-compose.yml檔案所在目錄中開啟終端,執行命令:docker-compose up –d
此命令首先會拉取docker-compse.yml中配置的fabric-ca映象,然後啟動fabric-ca-server例項,由於我使用的是本地映象,因此此命令不會去拉取映象,只會啟動ca伺服器例項。
2. 原生命令啟動
使用預設設定啟動fabric-ca-server,命令如下:
fabric-ca-server start -b admin:adminpw
三、Fabric CA Server
(一)初始化Server
命令:fabric-ca-server init -badmin:adminpw
-b選項提供了引導管理員的註冊ID和金鑰;如果配置檔案中LDAP沒有啟用“ldap.enabled”設定,那麼這是必需的(LDAP是輕量目錄訪問協議,英文全稱是Lightweight Directory Access Protocol,是一種以樹狀的層次結構來儲存資料的協議)
執行命令後在當前目錄生成如下圖所示的結構的檔案。
ca-cert.pem為生成的證書檔案,通過openssl命令檢視證書內容,命令如下:
openssl x509 –inca-cert.pen –inform pem –noout -text
fabric-ca-config.yaml為生成的預設配置檔案,如果需要自定義配置,可以使用–config xx-config.yaml來進行啟動配置。也可設定FABRIC_CA_SERVER_HOME環境變數,在該環境變數所指向的目錄下配置fabric-ca-server-config.yaml(預設尋找的配置檔案,如無則建立預設配置檔案),並在該目錄下啟動Server,則Server便會使用當前目錄下的配置檔案。
fabric-ca-server.db為儲存發放證書資訊的sqlite3資料庫。
msp/keystore儲存的即為keyfile(官方文件中所描述的ca-key.pem)
Server配置檔案中可以配置一個證書籤名請求(CSR),如下所示(欄位的具體含義會在配置檔案部分說明):
如果需要自定義CSR的屬性,那麼就需要自定義server配置檔案,並刪除掉配置檔案中ca.certfile和ca.keyfile節點指向的檔案,然後重新執行初始化命令。
fabric-ca-server init命令會生成一個自簽名的CA證書,除非提供-u <parent-fabric-ca-server-URL> 選項。如果提供了-u選項,此伺服器的CA證書將由其父Server節點進行簽名。為了保證得到父節點的認證許可權,<parent-fabric-ca-server-URL>的格式必須遵從<scheme>://<enrollmentID>:<secret>@<host>:<port>
如:fabric-ca-server init-u http://admin:[email protected]:7054
如果想要CA Server使用個人提供的簽名證書和私鑰簽名,則必須修改配置檔案中的ca.certfile和ca.keyfile,且證書和私鑰簽名必須是pem格式編碼的檔案。
可以通過自定義CSR來生成支援ECDSA和RSA的X.509證書和金鑰。以下是一個橢圓曲線數字簽名演算法(ECDSA)的設定,採用的曲線是prime256v1,簽名演算法是ecdsa-with-SHA256。
對演算法和金鑰長度的選擇出於對安全的考量。
ECDSA提供以下選項:
size
ASN1 OID
Signature Algorithm
256
prime256v1
ecdsa-with-SHA256
384
secp384r1
ecdsa-with-SHA384
521
secp384r1
ecdsa-with-SHA521
RSA提供以下選項:
size
Modulus (bits)
Signature Algorithm
2048
2048
sha256WithRSAEncryption
4096
2096
sha512WithRSAEncryption
(二)啟動Server
命令:fabric-ca-server start -b<admin>:<adminpw>
如果Fabric CA server沒有被初始化,則會首先初始化Server,初始化詳情請參考上一小節。
如果Fabric CA server沒有啟用LDAP,那麼必須在命令中攜帶-b選項並指定至少一個引導使用者。
如果想要Fabric CA server在https協議監聽,那麼就需要將tls.enabled設定為true。
啟動成功後,Fabric CA server預設在7054埠監聽(可在配置檔案中配置)。
(三)配置資料庫
Fabric CA預設使用SQLite資料庫,這是一種嵌入式的檔案資料庫,如果需要將在叢集中部署Fabric CA,那麼就需要使用PostgreSQL或者MySQL資料庫,支援的最低版本如下:
PostgreSQL: 9.5.5
MySQL: 5.7
1. PostgreSQL
- db:
- type: postgres
- datasource: host=localhost port=5432 user=Username password=Password dbname=fabric_ca sslmode=verify-full
sslmode欄位設定了SSL認證的具體配置,如下表所示
sslmode 描述 disable 禁用SSL require Always SSL (跳過驗證) verify-ca Always SSL (驗證Server提供的證書是否由可信CA簽名) verify-full 與verify-ca相同,驗證Server提供的證書是否由可信CA簽名且Server的主機名與證書中的主機名匹配 如果要使用TLS,那麼必須設定CA server配置檔案中的db.tls屬性,如果在PostgreSQL伺服器中啟用了SSL客戶端認證,那麼必須在Server配置檔案中的db.tls.client欄位指定客戶端的證書和金鑰檔案,如下:
- db:
- ...
- tls:
- enabled: true
- certfiles:
- - db-server-cert.pem
- client:
- certfile: db-client-cert.pem
- keyfile: db-client-key.pem
certfiles:PEM編碼的可信根證書檔案列表
certfile 和 keyfile:PEM編碼的證書和金鑰檔案,用來保證CA server和PostgreSQL server的安全通訊。
在PostgreSQL伺服器上配置SSL的基本步驟:
1. 在postgresql.conf中,取消SSLd的註釋並設定為“ON”(SSL= ON)
2. 在PostgreSQL資料目錄中放置證書和金鑰檔案。
注意:自簽名證書用於測試,不應用於生產環境中。
PostgreSQL伺服器 - 需要客戶端證書
1. 將您信任的證書頒發機構(CAS)的證書放置在PostgreSQL資料目錄中的檔案root.crt中
2. 在postgresql.conf中,設定“ssl_ca_file”以指向客戶端的根證書(CA證書)
3. 在pg_hba.conf中的appropriate hostssl line,設定clientcert引數為1
2. MySQL
- db:
- type: mysql
- datasource: root:rootpw3306)/fabric_ca?parseTime=true&tls=custom
(localhost:使用MySQL需要MySQL Server允許接受’0000-00-00’為有效的日期,需要在my.cnf中找到配置選項sql_mode,並且刪除NO_ZERO_DATE,並重啟伺服器。
如果要使用TLS,請參考上一節的配置。
在MySQL伺服器上配置SSL的基本步驟
開啟或建立伺服器的my.cnf檔案,在[mysqld] 部分增加如下程式碼或取消如下程式碼的註釋。應該指向MySql伺服器的金鑰和證書,以及根CA證書。
[mysqld] ssl-ca=ca-cert.pem ssl-cert=server-cert.pem ssl-key=server-key.pem
可以通過以下命令查詢配置是否生效:
mysql> SHOW GLOBAL VARIABLES LIKE ‘have_%ssl’;
應當可以看到下表結果
variable_name Value have_openssl YES have_ssl YES 在MySQL伺服器端SSL配置完成之後,下一步是建立一個有特權通過SSL接入MySQL伺服器的使用者。
mysql> GRANT ALL PRIVILEGES ON . TO ‘ssluser’@’%’ IDENTIFIED BY ‘password’ REQUIRE SSL; mysql> FLUSH PRIVILEGES
如果想要使使用者從一個特定的IP地址訪問MySQL Server,可以把“%”變為特定的IP地址。
MySQL伺服器 - 需要客戶端證書
安全連線的選項和用於伺服器端的選項是相似的
- ssl-ca識別CA證書,如果用到,必須和伺服器端用相同的證書。
- ssl-cert識別MySQL伺服器的證書。
- ssl-key識別MySQL伺服器的私鑰。
假設你想要用一個賬戶來連線,這個賬戶沒有特殊的加密要求或是被一個包括REQUIRE SSL的GRANT statement建立的,啟動MySQL服務至少需要-ssl-cert和-ssl-key選項。然後在服務設定檔案中設定db.tls.certfiles屬性並啟動CA服務。
為了要求一個客戶端證書也是被指定的,建立一個用REQUIRE X509選項的賬戶。然後客戶端也必須明確客戶端金鑰和證書檔案;否則,MySQL server將會拒絕連線。為了給CA server指定客戶端金鑰和證書檔案,設定db.tls.client.certfile和db.tls.client.keyfile
(四)配置LDAP
CA Server可以從LDAP Server中讀取進行配置
特別地,CA Server可以連線到LDAP Server做如下事情:
- 在登記前認證身份
- 檢索用於認證的身份屬性
修改CA Server配置檔案的LDAP部分來配置CA Server連線LDAP Server
- ldap:
- enabled: false
- url: <scheme>://<adminDN>:<pass>@<host>:<port>/<base>
- userfilter: <filter>
- attribute:
- names: <LDAPAttrs>
- converters:
- - name: <fcaAttrName>
- value: <fcaExpr>
- maps:
- <mapName>:
- - name: <from>
- value: <to>
- - scheme: LDAP或LDAPS中的一個。
- - adminDN:admin使用者的名字。
- - pass:admin使用者的密碼。
- - host:LDAP伺服器的hostname或IP地址。
- - port:可選的埠號,ldap預設的埠號是389,ldaps預設的埠號是636。
- - base:LDAP樹的根,用來搜尋。
- - filter:登入名的過濾器,例如:(uid=%s)用來搜尋用使用者名稱登陸的使用者,(email=%s)用來搜尋用郵箱登陸的使用者。
當LDAP被配置好之後,登記過程如下:
- CA client或client SDK傳送一個enrollment請求,這個請求帶一個basic authorization header
- CA server接收了這個enrollment請求,對authorization header中的identity name和password進行解碼,用配置檔案中的“userfilter”來從identity name中查詢DN(Distinquished Name),然後用identity的密碼請求一個LDAP bind,如果LDAP bind成功了,enrollment過程就被授權了,可以執行了。
(五)配置多個CAs
Fabric-ca-server預設包含一個CA,可以通過cafiles 或 cacount配置選項來增加其他的CA,每一個CA都有他自己的home 目錄。
1. cacount
cacount可以方便的建立多個附加CAs,他們的home directory和server directory相關,如下所示:
- -- <Server Home>
- |--ca
- |--ca1
- |--ca2
如下命令來啟動2個附加CAs:
fabric-ca-server start -b admin:admin --cacount 2
2. cafiles
為每個要啟動的CA配置CA配置檔案。每個配置檔案必須有唯一的CA名稱和通用名稱(CN),否則伺服器將無法啟動,因為這些名稱必須是唯一的。CA配置檔案將重寫任何預設CA配置,CA配置檔案中的任何缺失選項將由預設CA的值替換。
配置的優先順序如下:
- CA Configuration file(自定義配置檔案)
- Default CA CLI flags (預設命令選項)
- Default CA Environment variables(預設CA環境變數)
- Default CA Configuration file(預設配置檔案)
一個CA的配置檔案至少包括下述內容:
- ca:
- # Name of this CA
- name: <CANAME>
- csr:
- cn: <COMMONNAME>
可以設定文件結構如下:
- --<Server Home>
- |--ca
- |--ca1
- |-- fabric-ca-config.yaml
- |--ca2
- |-- fabric-ca-config.yaml
如下命令可以啟動兩個自定義配置的CA例項:
fabric-ca-server start -b admin:admin --cafiles ca/ca1/fabric-ca-config.yaml --cafiles ca/ca2/fabric-ca-config.yaml
四、Fabric CA Client
(一)登記引導身份
fabric-ca-client enroll命令用於登記身份,如下命令在本地7054埠監聽的Server登記了Id為admin,密碼為adminpw的引導身份(未指定-u選項即為登記引導身份)
- export FABRIC_CA_CLIENT_HOME=$HOME/fabric-ca/clients/admin
- fabric-ca-client enroll -u http://admin:[email protected]:7054
(二)註冊新身份
進行註冊身份請求的身份首先需要進行登入,並且擁有註冊此類別身份的許可權。
Fabric CA server制定瞭如下3種許可權檢驗規則:
1. 註冊者必須擁有hf.Registrar.Roles屬性,其中的一個值與被註冊身份的型別相同。例如註冊User身份,則註冊者的hf.Registrar.Roles屬性中必須包含User值。
2. 註冊者的組織關係必須與被註冊身份相同或者是被註冊身份組織關係的字首。例如註冊者組織關係為a.b,則被註冊身份可以為a.b或a.b.*。
3. 註冊者可以註冊帶有屬性的使用者,當且僅當滿足如下情況:
- 註冊者可以註冊以“hf”為字首的Fabric CA保留屬性,註冊者擁有保留屬性且取值必須是hf.Registrar.Attributes屬性中的值。如果屬性是型別列表,則被註冊的屬性的值必須等於或是註冊者具有的值的子集。如果屬性為布林型別,則註冊者只有在該屬性值為“true”時才能註冊該屬性。
- 註冊非“hf”字首的自定義屬性,要求註冊者擁有hf.Registrar.Attributes屬性和值或屬性和模式表示式。如果註冊者有hf.Registrar.Attributes=ad*,那麼註冊者可以從身份新增或刪除的屬性就是以“ad”為字首的屬性。
- 如果請求的屬性名是以hf為字首的保留屬性,則會進行額外的檢查,以檢視該屬性值是否為註冊者相同屬性值的子集。例如註冊者的屬性值為“A.B.*,X.Y.Z”,那麼請求A.B.C是有效的,請求A.C.B是無效的。
下表列出了可以為身份註冊的所有預置屬性。注:屬性的名稱是區分大小寫的
屬性名
型別
描述
hf.Registrar.Roles
List
註冊者可以管理的角色列表
hf.Registrar.DelegateRoles
List
註冊者可以授予被註冊身份hf.Registrar.Roles屬性的角色列表
hf.Registrar.Attributes
List
註冊者允許註冊的屬性列表
hf.GenCRL
Boolean
如果true則身份可以生成CRL
hf.Revoker
Boolean
如果true則身份可以撤銷使用者或證書
hf.AffiliationMgr
Boolean
如果true則身份可以管理組織關係
hf.IntermediateCA
Boolean
如果true則身份可以登記中間CA Server
注意:在註冊身份時若提供屬性為列表,且列表中存在重複的屬性名,則以最後一個為準。
下述命令以admin身份證書註冊了一個id為admin2,組織關係為org1.department1的使用者,並提供了hf.Revoker的保留屬性和admin的自定義屬性(:exert表示該屬性名和值會插入到登記證書中)
- export FABRIC_CA_CLIENT_HOME=$HOME/fabric-ca/clients/admin
- fabric-ca-client register --id.name admin2 --id.affiliation org1.department1 --id.attrs 'hf.Revoker=true,admin=true:ecert'
可以將多個屬性指定為-id.attrs選項的一部分,每個屬性必須逗號分隔。對於包含逗號的屬性值,屬性必須封裝在雙引號中。見下面的例子。
- fabric-ca-client register -d --id.name admin2 --id.affiliation org1.department1 --id.attrs '"hf.Registrar.Roles=peer,user",hf.Revoker=true'
- fabric-ca-client register -d --id.name admin2 --id.affiliation org1.department1 --id.attrs '"hf.Registrar.Roles=peer,user"' --id.attrs hf.Revoker=true
可以通過修改配置檔案為欄位提供預設值,如下命令從命令列提供了name欄位,其餘欄位在配置檔案中讀取。
- export FABRIC_CA_CLIENT_HOME=$HOME/fabric-ca/clients/admin
- fabric-ca-client register --id.name admin3
可以通過--id.secret peerpw提供密碼。
(三)登記身份
命令如下,-M選項表示填充MSP(成員服務提供商)目錄結構。
- export FABRIC_CA_CLIENT_HOME=$HOME/fabric-ca/clients/peer1
- fabric-ca-client enroll -u http://peer1:[email protected]:7054 -M $FABRIC_CA_CLIENT_HOME/msp
Fabric CA Server發出的所有註冊證書都有組織關係,規則如下:
1. OU層次結構的根等於身份型別。
2. 為身份標識的每個元件添加了OU。
例如,一個身份的型別為節點,它屬於dept1.team1,那麼它的OU層次結構為(從葉到根)OU=team1 OU=dept1 OU=peer
(四)從其他CA伺服器獲取CA證書鏈
通常,msp目錄的cacerts目錄必須包含CA頒發的證書鏈,代表節點的所有可信根證書。