10. CA证书服务

10.1. 证书简介

ChainMaker区块链网络中使用的证书类型有三大类 CA证书 节点证书 用户证书。
CA证书: 可以是根CA证书、中间CA证书、自签CA证书，其余两类证书都是使用CA证书签名生成。
节点证书: 细分为共识节点、同步节点、轻节点使用的证书。同步节点和轻节点证书类型相同。
用户证书: 细分为管理员用户证书、普通用户证书。分别对应管理员权限和普通用户权限。
下面详细介绍ChainMaker网络中各类证书。

10.2. 证书

10.2.1. CA证书

一般每个组织一个CA证书。
CA证书可通过 chainmaker-cryptogen 或者自建的 CA证书服务 生成，也可通过向证书颁发机构申请获得。
本组织的所有节点证书以及用户证书都是由此CA证书签发生成。

10.2.2. 节点证书类

每个组织至少有一个共识节点，也可以部署多个。
每个组织可以有若干同步和轻节点，也可以不部署。
不管什么类型的节点，每个节点都会有一个节点TLS证书和一个节点SIGN证书，其证书字段详见节点证书、用户证书字段

  • 共识节点

    • 节点TLS证书

      用于跟客户端建立tls链接，使用CA证书签发获得，证书字段信息如下示例：

      O=wx-org1.chainmaker.org
OU=consensus // 共识节点证书必须为consensus
CN=consensus1.wx-org1.chainmaker.org
sans=localhost // 用于tls的证书sans字段必填

    • 节点SIGN证书

      用于签名验签等等，使用CA证书签发获得，证书字段信息如下示例：

      O=wx-org1.chainmaker.org
OU=consensus // 共识节点证书必须为consensus
CN=consensus1.wx-org1.chainmaker.org

  • 同步节点、轻节点

    同步节点与轻节点的证书规格完全一致，以下示例都互相适用，不再重复举例。

    • 节点TLS证书

      用于跟客户端建立tls链接，使用CA证书签发获得，证书字段信息如下示例：

      O=wx-org1.chainmaker.org
OU=common // 同步节点/轻节点证书必须为common
CN=consensus1.wx-org1.chainmaker.org
sans=localhost // 用于tls的证书sans字段必填

    • 节点SIGN证书

      用于签名验签等等，使用CA证书签发获得，证书字段信息如下示例：

      O=wx-org1.chainmaker.org
OU=common // 同步节点/轻节点证书必须为common
CN=consensus1.wx-org1.chainmaker.org

10.2.3. 用户证书类

用户证书类分为admin证书类分配给管理员用户使用和client证书类分配给普通用户使用。
每个组织至少有一个管理员用户和若干个普通用户
不管什么类型的用户，每个用户都会有一个用户TLS证书和一个用户SIGN证书，其证书字段详见节点证书、用户证书字段

  • admin证书类

    • 用户TLS证书

      用于跟节点建立tls链接，使用CA证书签发获得，证书字段信息如下示例：

      O=wx-org1.chainmaker.org
OU=admin // 管理员用户必须为admin
CN=admin1.wx-org1.chainmaker.org

    • 用户SIGN证书

      用于签名验签等等，使用CA证书签发获得，证书字段信息如下示例：

      O=wx-org1.chainmaker.org
OU=admin // 管理员用户必须为admin
CN=admin1.wx-org1.chainmaker.org

  • client证书类

    • 用户TLS证书

      用于跟节点建立tls链接，使用CA证书签发获得，证书字段信息如下示例：

      O=wx-org1.chainmaker.org
OU=client // 普通用户必须为client
CN=client1.wx-org1.chainmaker.org

    • 用户SIGN证书

      用于签名验签等等，使用CA证书签发获得，证书字段信息如下示例：

      O=wx-org1.chainmaker.org
OU=client // 普通用户必须为client
CN=client1.wx-org1.chainmaker.org

10.3. 链上变更

10.3.1. 组织CA证书类

10.4. 附录

10.4.1. 节点证书、用户证书字段

节点证书和用户证书字段通用

字段 含义 规范
C country 国家 如：CN
L locality 位置(城市) 如：Guangzhou
ST state 省份(州) 如：Guangdong
O organization 组织 对应chainmaker的组织ID（orgId）如：wx-org1.chainmaker.org
OU organizationalUnit 组织单位 对应chainmaker里的用户角色：consensus/common/admin/client
CN commonName 常用名 chainmaker里通常以用户ID+组织ID形式，如：ca.wx-testorg.chainmaker.org、admin1.wx-org1.chainmaker.org、consensus1.wx-org1.chainmaker.org、client1.wx-org1.chainmaker.org
expireYear 证书有效期 以年为单位 如：2
sans 节点证书的地址信息 可为节点地址IP，也可以是节点域名 如：consensus1.wx-org1.chainmaker.org



10.5. CA证书服务概述

长安链证书签发服务，可用于多种场景部署，提供证书签发，管理，更新，吊销等服务。

CA证书服务的使用手册链接：

CA证书服务的使用手册

10.6. 表设计

10.6.1. cert_content

证书的内容表，存储写到X509证书里的证书详情。

字段 类型 含义 备注
serial_number bigint SN码 证书字段，证书的唯一标识
content longtext 证书的内容 pem编码
signature longtext 证书的签名 hex编码
country varchar(255) 国家 X509证书字段
locality varchar(255) 地区 X509证书字段
province varchar(255) 省份 X509证书字段
organization varchar(255) 组织 X509证书字段
organizational_unit varchar(255) 单位 X509证书字段
common_name varchar(255) 常用名 X509证书字段
csr_content longtext 证书的csr pem编码
is_ca bool 证书是否具有签发能力 X509证书字段
ski varchar(255) 证书密钥的ski X509证书字段
aki varchar(255) 证书密钥的aki X509证书字段
key_usage int 证书密钥的使用方式 X509证书字段
ext_key_usage varchar(255) 证书密钥的扩展使用方式 X509证书字段
issue_date bigint 签发日期 unix时间戳
expiration_date bigint 到期时间 unix时间戳

10.6.2. cert_info

证书的相关信息表，存储与证书相关的，包括密钥，用户信息等。

字段 类型 含义 备注
serial_number bigint 证书sn 证书的唯一标识sn
private_key_id varchar(255) 私钥标识 一般为私钥的ski
issuer_sn bigint 签发者sn 该证书的颁发者的sn
p2p_node_id varchar(255) p2p网络Id 长安链P2P网络节点ID
org_id varchar(255) 组织唯一标识 长安链组织ID
user_type int 证书用户类型 长安链证书角色
cert_usage int 证书用途 长安链证书使用方式
user_id varchar(255) 用户唯一标识 长安链用户（节点）标识

  • user_type: 1.root , 2.ca , 3.admin , 4.client , 5.consensus , 6.common

  • cert_usage: 1.sign , 2.tls , 3.tls-sign , 4.tls-enc

10.6.3. keypair

公私钥对表，存储密钥的具体信息。

字段 类型 含义 备注
ski varchar(255) 密钥的ski 密钥在证书里的唯一标识
private_key longtext 私钥的内容 pem编码
public_key longtext 公钥的内容 pem编码
key_type int 公钥算法
hash_type int 哈希算法

10.6.4. revoked_cert

撤销的证书表，存储撤销信息。

字段 类型 含义
revoked_cert_sn bigint 撤销证书的SN
reason longtext 撤销原因
revoked_start_time bigint 撤销开始时间
revoked_end_time bigint 撤销结束时间
revoke_by bigint 撤销者
org_id varchar(255) 所属组织

10.6.5. app_info

访问控制应用信息表，存储配置的应用id和key还有角色。

字段 类型 含义
app_id varchar(255) 应用id
app_key varchar(255) 应用口令
app_role int 应用角色

app_role : 1.admin , 2.user

  • admin : 所有权限

  • user ：不能进行吊销、延期证书。只能申请，查询证书。

10.7. 证书详解

10.7.1. 证书使用方式

  • sign ：签名证书。

  • tls ：tls 证书

  • tls-enc ：tls加密证书（符合国密tls双证书标准）

  • tls-sign ：tls签名证书（符合国密tls双证书标准）

10.7.2. 证书分类

  • CA证书

    CA证书是指具有签发能力的证书，即使用该证书可以继续签发下级证书。通常为root或者ca两种证书角色。

  • 用户证书

    用户证书是指不具备签发能力的、给用户使用的tls或sign证书。通常为admin或client两种角色。

  • 节点证书

    节点证书是指不具备签发能力的、给节点使用的tls或sign证书。通常为consensus或common两种角色。

10.7.3. 证书角色分类

  • root

    root为根证书。即初始证书，是由自签形成的第一个证书。

  • ca

    ca为中间CA证书。该类证书是由根证书直接或间接签发，本身也具有继续向下签发的能力。在ChainMaker中，通常表现为组织证书。

  • admin

    admin为用户证书的一种。通常称为管理员证书。该证书拥有参与投票等更多的参与权限。（想要了解具体权限设计详情，请查看长安链开源文档，用户手册的权限管理模块。）

  • client

    client为用户证书的一种。通常称为普通用户证书。该证书拥有发起交易，查询信息等基本的链上操作权限。但缺乏参与投票等一些重大决策权限。（想要了解具体权限设计详情，请查看长安链开源文档，用户手册的权限管理模块。）

  • consensus

    consensus为节点证书的一种。通常称为共识节点证书。该证书通常颁发给ChainMaker的共识节点，共识节点用共识节点证书参与链上的共识投票、签名、校验、通信等操作。

  • common

    common为节点证书的一种。通常称为同步节点证书。该证书通常颁发给ChainMaker的同步节点，同步节点的校验，签名、通信的操作需要同步节点的tls和sign证书。

10.7.4. 场景模拟

CA-scenario.png

该场景下，以集团为基础，以多个分公司为参与方构建一条区块链。

分公司在链上是组织的身份。分公司下的部门，在链上是用户和节点的身份。

在这种场景下，集团以root证书的身份给所有分公司颁发中间ca证书（组织证书）。

分公司用各自的中间ca证书给自己的部门颁发用户和节点证书。

10.7.5. X.509证书字段规范

在ChainMaker证书体系里，X.509证书格式的以下字段做出了具体的规范：

10.7.5.1. 常用字段

字段 证书类型 全称 填写内容 含义
O 统一 Organization OrgId 组织ID
（组织的唯一标识）
OU 统一 OrganizationalUnit 证书角色类型* 角色
CN CA证书 CommonName root/ca
CN 用户证书 CommonName UserId 用户ID
（用户唯一标识）
CN 节点证书 CommonName xxx.xxx.xxx.com 节点真实域名（链上唯一）
DNSNames（SANS） 节点证书 DNSNames xxx.xxx.xxx.com 节点真实域名

*证书角色类型：root/ca/admin/client/consensus/common 共六种选择。

  • O字段，即X.509证书的Organization字段，我们要求所有证书必须填写组织的唯一标识，需要与ChainMaker启动时配置的OrgId统一。

  • OU字段，即X.509证书的OrganizationalUnit字段，我们要求所有证书必须填写ChainMaker证书6种角色的其中一种。

  • CN字段，即X.509证书的CommonName字段，CA证书根据实际的证书角色填写root或者ca。用户证书填写用户的唯一标识，UserId。节点证书填写节点的真实域名信息。同一节点（用户）的tls和sign证书，CN字段应该相同。

  • DNSNames字段，节点证书填写节点的真实域名信息，其余不作要求。

10.7.5.2. KeyUsage

X.509的KeyUsage字段，具体用法介绍请参照RFC 5280标准

根据证书角色和证书的使用方式，我们对字段KeyUsage进行了具体设定：

  • admin/client/consensus/common :

    • tls-sign : x509.KeyUsageDigitalSignature | x509.KeyUsageContentCommitment

    • tls-enc : x509.KeyUsageKeyEncipherment | x509.KeyUsageDataEncipherment | x509.KeyUsageKeyAgreement

    • tls: x509.KeyUsageKeyEncipherment | x509.KeyUsageDataEncipherment | x509.KeyUsageKeyAgreement |x509.KeyUsageDigitalSignature | x509.KeyUsageContentCommitment

    • sign : x509.KeyUsageDigitalSignature | x509.KeyUsageContentCommitment

  • ca/root :

    • tls : x509.KeyUsageCertSign | x509.KeyUsageCRLSign

    • sign : x509.KeyUsageCertSign | x509.KeyUsageCRLSign

10.7.5.3. ExtKeyUsage

X.509的ExtKeyUsage字段，具体用法介绍请参照RFC 5280标准

根据证书角色和证书的使用方式，我们对字段KeyUsage进行了具体设定：

  • consensus/common :

    • tls: {ExtKeyUsageServerAuth, ExtKeyUsageClientAuth}

    • tls-enc: {ExtKeyUsageServerAuth, ExtKeyUsageClientAuth}

    • tls-sign: {ExtKeyUsageServerAuth, ExtKeyUsageClientAuth}

  • admin/client：

    • tls: {ExtKeyUsageClientAuth}

    • tls-sign: {ExtKeyUsageClientAuth}

    • tls-enc: {ExtKeyUsageClientAuth}

10.8. 证书延期

通过提供的证书SN，找到旧证书，在旧证书的基础上，以旧证书的信息为基础，包括SN字段，在旧证书的有效期基础上，用该证书的签发者，重新签名签发延期证书。

流程：

CA-cert_renew.png

10.9. 证书撤销

首先判断签发者SN是否是要撤销证书的上级，如果是，将撤销信息插入数据库保存。撤销日期以撤销动作起，到证书的失效期结束（永久吊销）。然后，生成该签发者证书下所有撤销的证书列表（CRL）并返回。

流程：

CA-cert_revoke.png

10.10. 服务启动

流程：

CA-start_server.png