星火链网可信数字证书颁发规范

1. 序言

编号：类型：标准标题：星火链网可信数字证书颁发规范作者：金键，jin.jian@caict.ac.cn；谢家贵，xiejiagui@caict.ac.cn；李志平，lizhiping@caict.ac.cn；张波，zhangbo3@caict.ac.cn 发布时间：状态：更新时间：2023-03-22 讨论地址：依赖RFC：

2. 摘要

介绍星火链网可信数字证书发证方颁发证书的规范标准和系统设计指导。

3. 原理

具备颁发证书的机构可以向公开[星火链网数字证书可信数据集]()（简称:数字证书可信数据集)进行申请成为发证方，成为发证方后就能颁发可信数字证书并将自己的提供的证书模板数据在数字证书可信数据集中进行公示。普通用户可以在数字证书可信数据集中查询到发证方的相关信息包括发证服务 URL 等，结合本协议即可向发证服务进行申请数字证书。

3.1 发证方交互流程

机构需要先向公开数字证书可信数据集提交发证方注册申请，成为发证方并信息公开后，数字钱包就能进行证书的申请。使用流程如下：

企业机构向数字证书可信数据集进行发证方注册申请，并提供自己的发证服务endpoint。
数字证书可信数据集审核通过发证方申请后，企业机构就可以在数字证书可信数据集中申请创建自己的证书模板信息，数字证书可信数据集审批此申请。
数字钱包在数字证书可信数据集中查询到发证方的资质、url、证书模板信息。
数字钱包根据证书模板构建证书申请数据，向发证方 URL 提交颁发数字证书申请，返回申请流程 ID。参考数字证书颁发流程
数字钱包根据申请反馈的 ID 信息查询证书颁发状态。
若发证方同意颁发证书申请后，数字钱包可以向发证方请求获取数字证书。
3.2 数字证书颁发流程

数字证书可以由发证方直接颁发，也可以由数字钱包进行申请过程。若发证方直接颁发数字证书，只需要进入步骤5，而用户申请数字证书流程如下：

数字钱包向发证方申请颁发数字证书
发证方返回此次申请的流程 id
数字钱包根据流程 id，查询数字证书颁发状态
发证方审核成功后会反馈可信数字证书的 ID。
数字钱包请求获取数字证书
发证方校验数字钱包身份后，返回数字证书。
4. 规范

协议设计的签名消息需要经过JWS签名生成的 jws token，消息发送者以 did 文档中的公钥配对的私钥进行签名。有关 JWS 签名，请参见 JWS RFC文档。签名算法支持 SM2

4.1 数字证书生成

4.1.1 可信数字证书原文

可信数字证书规范请参见星火链网RFC-008：星火链网BID可信证书协议标准中的可信数字证书章节。证书原文示例如下：
```
{
   "@context":[
       "https://www.w3.org/2018/credentials/v1",
       "https://www.w3.org/2018/credentials/examples/v1"
   ],
   "id":"http://example.edu/credentials/1872",
   "bid":"did:bid:CredentialID",
   "type":[
       "VerifiableCredential",
       "AlumniCredential"
   ],
   "issuer":"did:bid:CredentialIssuerID",
   "issuanceDate":"2023-01-01T19:23:24Z",
   "templateId":"20230101T23Nedex",
   "validBefore":"2029-10-01T19:23:24Z ",
   "credentialSubject":{
       "id":"did:bid:CredentialSubjectID",
       "alumniOf":{
           "id":"did:bid:AlumniID",
           "name":[
               {
                   "value":"Example University",
                   "lang":"en"
               }
           ]
       }
   },
   "revocationId": "20230101NN30d398",
   "parseType": "sel-disclose-SM2"
}
```
4.1.2 签发后的数字证书

发证方生成支持可选择性披露的可信数字证书后，组成 JWS 消息的 payload 部分，再由发证方使用 did document 中公钥对应的私钥进行签名最后生成证书的 jws token 数据发送给数字钱包。签发后的数字证书如下：

eyJhbGciOiJTTTIifQ.eyJAY29udGV4dCI6WyJodHRwczovL3d3dy53My5vcmcvMjAxOC9jcmVkZW50aWFscy92MSIsImh0dHBzOi8vd3d3LnczLm9yZy8yMDE4L2NyZWRlbnRpYWxzL2V4YW1wbGVzL3YxIl0sImJpZCI6ImRpZDpiaWQ6Q3JlZGVudGlhbElEIiwiY3JlZGVudGlhbFN1YmplY3QiOnsiYWx1bW5pT2YiOnsiaWQiOiJkaWQ6YmlkOkFsdW1uaUlEIiwibmFtZSI6W3sibGFuZyI6ImVuIiwidmFsdWUiOiJFeGFtcGxlIFVuaXZlcnNpdHkifV19LCJpZCI6ImRpZDpiaWQ6Q3JlZGVudGlhbFN1YmplY3RJRCJ9LCJpZCI6Imh0dHA6Ly9leGFtcGxlLmVkdS9jcmVkZW50aWFscy8xODcyIiwiaXNzdWFuY2VEYXRlIjoiMjAxMC0wMS0wMVQxOToyMzoyNFoiLCJpc3N1ZXIiOiJkaWQ6YmlkOkNyZWRlbnRpYWxJc3N1ZXJJRCIsInBhcnNlVHlwZSI6InNlbC1kaXNjbG9zZS1TTTIiLCJyZXZvY2F0aW9uSWQiOiIyMDEwMDEwMU5OMzBkMzk4IiwidGVtcGxhdGVJZCI6IjIwMTAwMTAxVDIzTmVkZXgiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIiwiQWx1bW5pQ3JlZGVudGlhbCJdLCJ2YWxpZEJlZm9yZSI6IjIwMTAtMTAtMDFUMTk6MjM6MjRaICJ9.xxxxxxxxxx

4.2 数字证书申请

发证方可以直接颁发证书也可以支持数字钱包进行数字证书申请，需要数字钱包向发证方申请颁发数字证书可以使用此规范。 申请数据结构

{
        "bid ":"",
        "publicKey ":"",
        "templateId ":"",
        "content ":""
}

bid: 申请者bid。
publicKey: 申请者公钥。
templateId: 凭证模板id。
content：申请内容(根据数字证书可信数据集中凭证申请模版生成 jsonld context 字符串数据)。模板数据结构可以依据不同业务定义，本文档定义示例：
format：关键字的类型。包括String、int、boolean
- label：关键字标签。
- value：值。
- desc：其它描述。
```
{
"attributes": [{
"format": "",
"label": "",
"key": "",
"value": "",
"desc": ""
}]
}
```
  attributes: 一组属性，属性为如下结构：
- key：属性的关键字。

响应数据结构

{
        "applyNo":""
}

applyNo: 申请发证反馈 ID。

4.3 证书申请状态查询

向发证方查询自己的证书申请状态。 申请数据结构
```
{
       "bid ":"",
    "applyNo":""
}
```
applyNo: 证书申请反馈ID。

响应数据结构

{
    "status":"",
    "credentialId":""
}

status: 1待审核 2已通过 3未通过 4已吊销。
credentialId:证书发行方内唯一 id。status 状态为2/4才产生 id，状态1/3为空
4.4 获取数字证书

数字钱包向发证方获取数字证书，发证方需校验请求发送者是证书拥有方 申请数据结构

{
    "bid ":"",
    "credentialId ":""
}

id: 证书发行方内唯一 id。

响应数据结构

{
        "jws":""
}

jws: 数字证书的 jws token 数据。
5 实现示例

5.1 安全令牌

数字钱包和服务端进行交互，需要先获取令牌（accessToken）。令牌是调用服务接口的凭据，请自行做好令牌的管理。令牌中包含（请求者 bid，请求者 publickey ）相关数据的JWT编码处理，数字钱包和发证服务的每次交互都要携带令牌。

5.1.1 获取流程

调用接口获取随机数
数字钱包对随机数进行签名得到签名数据
调用接口将签名数据和 bid 公钥传给发证服务
数字身份验证成功，获取令牌
5.1.2 令牌使用方法

在请求接口之前，请将令牌信息以 accessToken:{{accessToken}} 的键值对的形式放在请求头 (header) 中

5.1.3 接口

1.获取随机数
```
http请求方式：POST
//{url}-发证方服务地址
http://{url}/bid/auth/random
{
 "bid":""
}
```
请求参数说明：

字段名	类型	是否必填	描述
bid	String	是	用户bid

成功的返回JSON数据：

{
    "errorCode": 0,
    "message": "操作成功",
    "data": {
      "randomStr":""
    }
}

响应参数说明：

字段名	类型	描述
randomStr	String	随机数

2.授权

http请求方式：POST
//{url}-发证方服务地址
http://{url}/bid/auth
{
  "randomStr":"",
  "signData":"",
  "publicKey":""
}

请求参数说明：

字段名	类型	是否必填	描述
randomStr	String	是	随机数
signData	String	是	签名串（bid私钥对随机数进行签名）
publicKey	String	是	公钥（bid公钥）

成功的返回 JSON 数据：

{
    "errorCode": 0,
    "message": "操作成功",
    "data": {
      "accessToken":""
    }
}

响应参数说明：

字段名	类型	描述
accessToken	String	请求令牌

5.2 数字证书申请

请求数据

http请求方式：POST
//{url}-发证方服务地址
https://{url}/credential/apply
accessToken：{accessToken}
{
    "templateId ":"20100101T23Nedex",
    "content ":"{\"attributes\":[{\"format\":\"String\",\"label\":\"姓名\",\"type\":\"2\",\"key\":\"name\",\"value\":\"zhangsan\",\"desc\":\"\"},{\"format\":\"String\",\"label\":\"性别\",\"type\":\"2\",\"key\":\"sex\",\"value\":\"man\",\"desc\":\"\"}]}"
}

返回数据

{
    "applyNo":"10100101NN30d398"
}

5.3 证书申请状态查询

请求数据

http请求方式：POST
//{url}-发证方服务地址
https://{url}/credential/status
accessToken：{accessToken}
{
    "applyNo":"10100101NN30d398"
}

返回数据

{
    "status":"1",
    "credentialId":"did:bid:ef29WUbsJVixTASPfe9VKWHpf2dw4Rxt1"
}

5.4 获取数字证书

请求数据

http请求方式：POST
//{url}-发证方服务地址
https://{url}/credential/download
accessToken：{accessToken}
{
    "credentialId":"did:bid:ef29WUbsJVixTASPfe9VKWHpf2dw4Rxt1"
}

返回数据

{
"jws":"eyJhbGciOiJTTTIifQ.eyJAY29udGV4dCI6WyJodHRwczovL3d3dy53My5vcmcvMjAxOC9jcmVkZW50aWFscy92MSJdLCJjcmVkZW50aWFsU3ViamVjdCI6eyJpZCI6ImRpZDpiaWQ6ZWZvMTJWTGFoZThYN0NYeVNtclJEYVMxdzRvYWF0cnAiLCJuYW1lIjp7Imhhc2giOiJmODQzOWNkN2U0NjAwODhiMWVhNzZkYjk0MDA1OGJkZWFjNjJmMTVmYTRhODI4M2UwYzk1YjY2NDE3OWVmOTgyIiwic2FsdCI6IjcyMzI4MDMxNjI0MDI5MTUiLCJ2YWx1ZSI6InpoYW5nc2FuIn0sInNleCI6eyJoYXNoIjoiMzdjNDg3MmY4N2RkMmU5ZGExOTc3ZjNkNjg0ZjdiYzk0MmQxNDYyYjc5ZGQ0YTcwMmRlZjFiMmQ4OTJmYjBhYiIsInNhbHQiOiIyMDI0NzM3MzIxMjIwODgwIiwidmFsdWUiOiJtYW4ifX0sImlkIjoiZGlkOmJpZDplZm8xMlZMYWhlOFg3Q1h5U21yUkRhUzF3NG9hYXRycCIsImlzc3VhbmNlRGF0ZSI6IjIwMjMtMDEtMzFUMDI6MzQ6MDlaIiwiaXNzdWVyIjoiZGlkOmJpZDplZjE0dVBzWDdYWUx6c1U0dDJyblJyc0syemZVYkZFaiIsInBhcnNlVHlwZSI6InNlbC1kaXNjbG9zZS1TTTIiLCJyZXZvY2F0aW9uSWQiOiJkaWQ6YmlkOmVmS0s1Y2MyaUFyWDNjbXhEVm14Y1V4OFFnZWNNNG9EIiwidGVtcGxhdGVJZCI6ImRpZDpiaWQ6ZWZ2QlBpWldDdUI4OUxweW5MVXBtWENvempHRW91aFUiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIiwiaWRlbnRpdHlDZXJ0aWZpY2F0aW9uIl0sInZhbGlkQmVmb3JlIjoiMjA5OS0wMS0wMVQwMDowMDowMFoifQ.xxxxxxxxxx"
}

caict-4iot-dev / bif-rfcs