id:BSN_2021 公众号：BSN 研习社

2022年1月25日，区块链服务网络发展联盟（简称“BSN联盟”）推出了“BSN-DDC基础网络”（简称DDC网络）。DDC网络的推出，为NFT技术在我国的落地提供基础设施能力支撑，并为其合规发展保驾护航。

DDC（Distributed Digital Certificate）即分布式数字凭证，其属性和功能类似于NFT。NFT是现实或数字世界中某个事物在区块链上的数字化权益证明，尽管目前大多被用于数字艺术品版权领域，然而其本质上是一种区块链分布式数据库技术，并不带有特定的业务属性，它的潜在使用场景是非常广泛的，可应用在数字商品凭证、票证、账户管理、知识产权等各种领域。DDC网络不直接向个人用户提供服务，而是向拥有DDC/NFT业务的平台方提供极其便捷的网络接入服务，以方便这些平台以极低的成本提供DDC/NFT的生成和管理服务。

DDC-SDK 是用于开发者与DDC 合约交互的 API 工具。为了让运营方或各平台方对DDC-SDK整体设计有一个全面详细的了解，同时为项目的开发、测试、验证、交付等环节提供原始依据以及开发指导，BSN研习社推出BSN-DDC基础网络DDC SDK详细设计系列。分别从整体设计，DID功能设计，DDC权限管理、费用管理，官方合约BSN-DDC-721，官方合约 BSN-DDC-1155，交易查询、区块查询、签名事件，数据解析，示例等八个方面，全面详细的介绍DDC-SDK。

本期是系列文章第二期，DID功能设计。

**DID**

与实体用户相关的数字化身份信息的管理，包含注册DID、更新密钥、验证DID等链方暂时可以不用关注。

**1.1注册DID**

个人或机构都可通过“注册DID”给自己生成一个数字化身份。每个DID都对应唯一的一份DID Document，且DID Document存储于区块链网络中。

1.1.1功能介绍

注册DID包含两个环节：为用户生成DID数字身份和向区块链网络发布DID Document 。

1.1.2 API定义

-   方法定义：

DidDataWrapper createDid();

-   调用者：平台方、运营方

-   核心逻辑：

1.  根据Secp256k1算法生成两组公私钥对；
1.  生成Base DID Document；
1.  生成DID标识符（生成规则参照“标识符生成规则”）；
1.  生成DID Document（格式示例参照“DID Document格式”）；
1.  执行DID Document上链处理；
1.  用主公钥对DID进行签名；
1.  返回DID，DID签名值，主备公私钥，和 DID Document数据内容。

-   输入参数：无
-   输出参数：

| **字段名**          | **字段**         | **类型**       | **必传** | **备注** |
| ---------------- | -------------- | ------------ | ------ | ------ |
| DID              | did            | String       | 是      |        |
| DID签名值           | didSign        | String       | 是      |        |
| 主公私钥             | authKeyInfo    | KeyPair      | 是      |        |
| 备公私钥             | recyKeyInfo    | KeyPair      | 是      |        |
| DID文档            | document       | DocumentInfo | 否      |        |
| **KeyPair**      |                |              |        |        |
| 私钥信息             | privateKey     | String       | 是      |        |
| 公钥信息             | publicKey      | String       | 是      |        |
| 加密算法             | type           | String       | 是      |        |
| **DocumentInfo** |                |              |        |        |
| DID              | did            | String       | 是      |        |
| 版本号              | version        | String       | 是      |        |
| 创建时间             | created        | String       | 是      |        |
| 更新时间             | updated        | String       | 否      |        |
| 主公钥              | authentication | PublicKey    | 是      |        |
| 备公钥              | recovery       | PublicKey    | 是      |        |
| 签名信息             | proof          | Proof        | 是      |        |
| **PublicKey**    |                |              |        |        |
| 公钥信息             | publicKey      | String       | 是      |        |
| 加密算法             | type           | String       | 是      |        |
| **Proof**        |                |              |        |        |
| 签名值              | signValue      | String       | 是      |        |
| 签名算法             | type           | String       | 是      |        |
| 签名者的DID          | creator        | String       | 是      |        |

1.1.3 DID格式

DID的内容格式由W3C标准格式前缀、项目名、DID标识符三部分组成，各部分之间以英文符冒号为分隔符。如下示例：

did:bsn:3wxYHXwAm57grc9JUr2zrPHt9HC

1.1.3.1 标识符生成规则

DID标识符通过以下算法生成：

base58(ripemd160(sha256(<Base DID Document>)))

以下为Base DID Document的格式示例：

```
{
"@context": "https://w3id.org/did/v1",
"authentication":
{
"type": "Secp256k1",
"publicKey":"28986472722394106073871327423452879123214061743224210681401278929598807211140001274507530324221923795865447680836742348963337343510229880669968499735858"
}
"recovery":
{
"type": "Secp256k1",
"publicKey":"9251971168042915941551574641987721503984542761641852064853964541181378832746959340151297908312616596971625573967556676367696067937171601766581709843378481"
}
}
```

1.1.3.2 DID Document格式

DID Document里面的主要内容有DID和主备公钥信息，格式如下所示：

```
{
"did": "did:bsn:3wxYHXwAm57grc9JUr2zrPHt9HC",
"version": 1,
"created": "2021-05-20T16:02:20Z",
"updated": "2021-05-20T16:02:20Z",
"authentication":
{
"type": "Secp256k1",
"publicKey":"28986472722394106073871327423452879123214061743224210681401278929598807211140001274507530324221923795865447680836742348963337343510229880669968499735858"
}
"recovery":
{
"type": "Secp256k1",
"publicKey":"9251971168042915941551574641987721503984542761641852064853964541181378832746959340151297908312616596971625573967556676367696067937171601766581709843378481"
}
}
```

1.1.3.3 DID Document完整格式

DID Document数据格式内容比摘要格式内容多了proof信息，proof是使用主私钥对DID Document摘要格式内容进行Secp256k1签名的一些信息，格式如下所示：

```
{
"did": "did:bsn:3wxYHXwAm57grc9JUr2zrPHt9HC",
"version": 1,
"created": "2021-05-20T16:02:20Z",
"updated": "2021-05-20T16:02:20Z",
"authentication":
{
"type": "Secp256k1",
"publicKey":"28986472722394106073871327423452879123214061743224210681401278929598807211140001274507530324221923795865447680836742348963337343510229880669968499735858"
}
"recovery":
{
"type": "Secp256k1",
"publicKey":"9251971168042915941551574641987721503984542761641852064853964541181378832746959340151297908312616596971625573967556676367696067937171601766581709843378481"
}
"proof": {
"type": "Secp256k1",
"creator": "did:bsn:3wxYHXwAm57grc9JUr2zrPHt9HC",
  "signatureValue":          "zD5nt+P/Ga/CRG2hJU/SMRXy210CLdvATsxQdPxTEy9Mc9Y0OSFpE3Yu5k2+OjQKVOtu5of9VFbgO3Zljw/vQxs="
}
}
```

**1.2更新密钥**

用户的主私钥丢失或者泄漏，可以通过“更新密钥”重新生成一对主公私钥。

1.2.1 功能介绍

用户通过备份的公私钥来完成主公私密钥更新。密钥更新后用户的DID Document也将更新，但是DID不会改变。

1.2.2 API定义

-   方法定义：

KeyPair resetDidAuth(ResetDidAuth restDidAuth);

-   调用者：平台方、运营方；

-   核心逻辑：

1.  验证请求参数内的备公私钥是否匹配；
1.  生成新的主公私钥；
1.  验证请求参数内的备公钥与DID Document内的备公钥是否一致；
1.  更新DID Document并使用新的主私钥按Secp256k1重新签名；
1.  返回新的密钥。

-   输入参数

| **字段名**     | **字段**      | **类型**  | **必传** | **备注** |
| ----------- | ----------- | ------- | ------ | ------ |
| DID         | did         | String  | 是      |        |
| 主公私钥        | primaryKey  | KeyPair | 否      |        |
| 备公私钥        | recoveryKey | KeyPair | 是      |        |
| **KeyPair** |             |         |        |        |
| 私钥          | privateKey  | String  | 是      |        |
| 公钥          | publicKey   | String  | 是      |        |
| 加密算法        | type        | String  | 是      |        |

-   输出参数：

| **字段名**     | **字段**     | **类型**  | **必传** | **备注** |
| ----------- | ---------- | ------- | ------ | ------ |
| 新公私钥        | keyInfo    | KeyPair | 是      |        |
| **KeyPair** |            |         |        |        |
| 私钥          | privateKey | String  | 是      |        |
| 公钥          | publicKey  | String  | 是      |        |
| 加密算法        | type       | String  | 是      |        |

### **1.3   验证DID**

用户可以通过“验证DID”对自己的DID身份进行查验，以此来确认DID Document是否已存在于链上；也可以确认第三方对自己DID身份的查验结果能否通过。

1.3.1 功能介绍

用户通过DID Document中的主公钥进行签名验证，验签通过则认可DID身份。

1.3.2 API定义

-   方法定义：

Boolean verifyDIdSign(DidSign didSign);

-   调用者：平台方、运营方；

-   核心逻辑：

1.  验证DID Document是否在链上存在；
1.  解析DID Document的主公钥；
1.  验证DID签名是否正确，并返回验证结果。

-   输入参数：

| **字段名** | **字段**  | **类型** | **必传** | **备注** |
| ------- | ------- | ------ | ------ | ------ |
| DID     | did     | String | 是      |        |
| DID签名值  | didSign | String | 是      |        |

-   输出参数：

| **字段名** | **字段** | **类型**  | **必传** | **备注** |
| ------- | ------ | ------- | ------ | ------ |
|         |        | Boolean | 是      |        |

**1.4 注册发证方**

用户可以通过“注册发证方”使自己的DID身份拥有可注册凭证模板的权限。1.4.1 功能介绍注册发证方仅是对DID身份进行了标记，不会改变DID和DID Document。发证方的信息在链上存储，是公开透明的。1.4.2 API定义

-   方法定义：Boolean registerAuthIssuer(RegisterAuthorityIssuer register);
-   调用者：运营方；
-   核心逻辑：

1.  验证DID Document是否在链上存在；
1.  解析DID Document的主公钥与当前公钥进行比对；
1.  验证DID是否为发证方；
1.  注册发证方并对基本信息上链。

-   输入参数：

| **字段名** | **字段**     | **类型** | **必传** | **备注** |
| ------- | ---------- | ------ | ------ | ------ |
| 私钥      | privateKey | String | 是      | 主私钥    |
| DID     | did        | String | 是      |        |
| 名称      | name       | String | 是      | 发证方名称  |

-   输出参数：

| **字段名** | **字段** | **类型**  | **必传** | **备注** |
| ------- | ------ | ------- | ------ | ------ |
|         |        | Boolean | 是      |        |

**1.5 注册凭证模板**

发证方依据自己所要签发的凭证信息，自定义凭证属性形成一份凭证模板。

1.5.1 功能介绍

一个发证方可以定义多个凭证模板逐个进行注册，基于凭证模板可以签发多个凭证，每个凭证都由发证方的私钥进行签名。

1.5.2 API定义

-   方法定义：

CptBaseInfo registerCpt(RegisterCpt registerCpt);

-   调用者：运营方；

-   核心逻辑：

1.  验证DID Document是否在链上存在；
1.  解析DID Document的主公钥与当前公钥进行比对；
1.  验证DID是否为发证方；
1.  注册凭证模板并对模板信息上链。

-   输入参数：

| **字段名**        | **字段**        | **类型**                 | **必传** | **备注**             |
| -------------- | ------------- | ---------------------- | ------ | ------------------ |
| 私钥             | privateKey    | String                 | 是      | 主私钥                |
| DID            | did           | String                 | 是      |                    |
| 属性信息           | cptJsonSchema | Map<String,JsonSchema> | 是      |                    |
| 标题             | title         | String                 | 是      |                    |
| 描述             | description   | String                 | 是      |                    |
| 类型             | type          | String                 | 是      | Proof              |
| **JsonSchema** |               |                        |        |                    |
| 字段类型           | type          | String                 | 是      |                    |
| 字段描述           | description   | String                 | 是      |                    |
| 是否必填           | required      | Boolean                | 是      | true表示必填；false表示选填 |

-   输出参数：

| **字段名** | **字段**     | **类型**  | **必传** | **备注** |
| ------- | ---------- | ------- | ------ | ------ |
| ID      | cptId      | Long    | 是      |        |
| 版本      | cptVersion | Integer | 是      |        |

**1.6 签发凭证**

发证方根据用户信息，可通过“签发凭证”为用户生成凭证。1.6.1 功能介绍用户根据凭证模板的属性要求，向发证方提供了对应的属性值后，发证方可基于凭证模板为其生成一份凭证。1.6.2 API定义

-   方法定义：CredentialWrapper createCredential(CreateCredential createCredential) ;
-   调用者：运营方；
-   核心逻辑：

1.  验证DID Document是否在链上存在；
1.  解析DID Document的主公钥与当前公钥进行比对；
1.  验证DID是否为发证方；
1.  验证凭证模板是否在链上存在；
1.  验证属性格式；
1.  凭证签发并返回凭证信息。

-   输入参数：

| **字段名** | **字段**         | **类型**             | **必传** | **备注**     |
| ------- | -------------- | ------------------ | ------ | ---------- |
| 私钥      | privateKey     | String             | 是      | 主私钥        |
| DID     | issuerDid      | String             | 是      | 发证方的DID    |
| DID     | userDid        | String             | 是      | 用户的DID     |
| 到期日     | expirationDate | String             | 是      |            |
| 属性      | claim          | Map<String,Object> | 是      | 和凭证模板的格式一致 |
| 类型      | type           | String             | 是      | Proof      |

-   输出参数：

| **字段名** | **字段**         | **类型**             | **必传** | **备注** |
| ------- | -------------- | ------------------ | ------ | ------ |
| 标准      | context        | String             | 是      |        |
| ID      | id             | String             | 是      | 凭证ID   |
| 类型      | type           | String             | 是      | Proof  |
| ID      | cptId          | Long               | 是      | 凭证模板ID |
| DID     | issuerDid      | String             | 是      | 发证方DID |
| DID     | userDid        | String             | 是      | 用户DID  |
| 到期日     | expirationDate | String             | 是      | 凭证到期日  |
| 生成日期    | created        | String             | 是      | 凭证签发日  |
| 简要说明    | shortDesc      | String             | 是      | 凭证简述   |
| 详细说明    | longDesc       | String             | 是      | 凭证详述   |
| 内容      | claim          | Map<String,Object> | 是      |        |
| 签名信息    | proof          | Map<String,Object> | 是      |        |

**1.7 验证凭证**

用户可以通过“验证凭证”对凭证的真伪性、有效性进行查验。。1.7.1 功能介绍验证凭证包含两个方面：验证凭证内容和验证凭证是否到期，两个方面都验证通过，则认为凭证有效。1.7.2 API定义

-   方法定义：Boolean verifyCredential(Credential credential,PublicKey publickKey);
-   调用者：平台方、运营方；核心逻辑：

1.  根据签名信息内的DID，在链上查询对应的Document；
1.  解析Document内的公钥对凭证验签；
1.  验证凭证内的到期日期。

-   输入参数：

-   Credential

| **字段名** | **字段**         | **类型**             | **必传** | **备注** |
| ------- | -------------- | ------------------ | ------ | ------ |
| 标准      | context        | String             | 是      |        |
| ID      | id             | String             | 是      | 凭证ID   |
| 类型      | type           | String             | 是      | Proof  |
| ID      | cptId          | Long               | 是      | 凭证模板ID |
| DID     | issuerDid      | String             | 是      | 发证方DID |
| DID     | userDid        | String             | 是      | 用户DID  |
| 到期日     | expirationDate | String             | 是      | 凭证到期日  |
| 生成日期    | created        | String             | 是      | 凭证签发日  |
| 简要说明    | shortDesc      | String             | 是      | 凭证简述   |
| 详细说明    | longDesc       | String             | 是      | 凭证详述   |
| 内容      | claim          | Map<String,Object> | 是      |        |
| 签名信息    | proof          | Map<String,Object> | 是      |        |

-   PublicKey

| **字段名** | **字段**    | **类型** | **必传** | **备注**    |
| ------- | --------- | ------ | ------ | --------- |
| 算法类型    | type      | String | 是      | Secp256k1 |
| 公钥      | publicKey | String | 是      | 主公钥       |

-   输出参数：

| **字段名** | **字段** | **类型**  | **必传** | **备注** |
| ------- | ------ | ------- | ------ | ------ |
|         |        | Boolean | 是      |        |

**1.8吊销凭证**

发证方可通过“吊销凭证”吊销已经签发给用户的凭证。

1.8.1 功能介绍

发证方对已签发的凭证进行作废标记。凭证已签发给用户，发证方是无法直接修改。所以凭证吊销后将吊销的凭证编号存储与区块链网络中。

1.8.2 API定义

-   方法定义：

Boolean revokeCredential(RevokeCredential cred) ;

-   调用者：平台方；

-   核心逻辑：

1.  验证请求参数合法性；
1.  通过DID标识符查询DID Document内的主公钥，验证其是否与请求参数内的私钥是否匹配；
1.  通过凭证模板编号查询验证发证方与凭证模板的关联关系；
1.  将凭证编号上链标记为已吊销；
1.  返回吊销结果。

-   输入参数：

RevokeCredential

| **字段名** | **字段**     | **类型** | **必传** | **备注** |
| ------- | ---------- | ------ | ------ | ------ |
| ID      | credId     | String | 是      | 凭证ID   |
| 模板ID    | cptId      | Long   | 是      | 凭证模板ID |
| DID     | did        | String | 是      | 发证方DID |
| 私钥      | privateKey | String | 是      | 发证方私钥  |

-   输出参数：

| **字段名** | **字段** | **类型**  | **必传** | **备注** |
| ------- | ------ | ------- | ------ | ------ |
|         |        | Boolean | 是      |        |

**1.9 查询吊销凭证**

用户可通过“查询吊销凭证”查询发证方已吊销的凭证和吊销时间。1.9.1 功能介绍用户查询某个发证方已经吊销凭证的吊销列表。1.9.2 API定义

-   方法定义：public Pages<BaseCredential> getRevokedCredList(QueryCredentialList queryCredentialList) ;
-   调用者：运营方；
-   核心逻辑：

1.  验证请求参数合法性；
1.  按请求参数查询相应结果；
1.  返回吊销结果。

-   输入参数：

| **字段名** | **字段** | **类型**  | **必传** | **备注**           |
| ------- | ------ | ------- | ------ | ---------------- |
| 页码      | page   | Integer | 是      | 当前页码             |
| 分页大小    | size   | Integer | 是      | 分页大小，单次最多可以检索50条 |
| DID     | did    | String  | 是      | 发证方的DID          |

-   输出参数：

| **字段名** | **字段**    | **类型**                 | **必传** | **备注** |
| ------- | --------- | ---------------------- | ------ | ------ |
| 页码      | page      | Integer                | 是      | 当前页码   |
| 分页大小    | size      | Integer                | 是      |        |
| 总数      | totalNum  | Integer                | 是      | 总记录数   |
| 总页数     | totalPage | Integer                | 是      |        |
| 记录      | result    | List<  BaseCredential> | 是      | 记录列表   |

-   BaseCredential

| **字段名** | **字段**  | **类型** | **必传** | **备注** |
| ------- | ------- | ------ | ------ | ------ |
| ID      | id      | String |        | 凭证编号   |
| 时间      | created | String |        | 凭证吊销时间 |

本文资料内容来源于BSN-DDC SDK详细设计-V1.0，GitHub地址为：https://github.com/BSN-DDC/did-sdk。欲浏览更多信息，请您点击登录查看。

ITPub博客

BSN-DDC基础网络DDC SDK详细设计（二）DID功能设计

最新文章