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();
- 调用者:平台方、运营方
- 核心逻辑:
- 根据Secp256k1算法生成两组公私钥对;
- 生成Base DID Document;
- 生成DID标识符(生成规则参照“标识符生成规则”);
- 生成DID Document(格式示例参照“DID Document格式”);
- 执行DID Document上链处理;
- 用主公钥对DID进行签名;
- 返回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的格式示例:
{
"@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);
- 调用者:平台方、运营方;
- 核心逻辑:
- 验证请求参数内的备公私钥是否匹配;
- 生成新的主公私钥;
- 验证请求参数内的备公钥与DID Document内的备公钥是否一致;
- 更新DID Document并使用新的主私钥按Secp256k1重新签名;
- 返回新的密钥。
- 输入参数
字段名 | 字段 | 类型 | 必传 | 备注 |
---|---|---|---|---|
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);
- 调用者:平台方、运营方;
- 核心逻辑:
- 验证DID Document是否在链上存在;
- 解析DID Document的主公钥;
- 验证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);
- 调用者:运营方;
- 核心逻辑:
- 验证DID Document是否在链上存在;
- 解析DID Document的主公钥与当前公钥进行比对;
- 验证DID是否为发证方;
- 注册发证方并对基本信息上链。
- 输入参数:
字段名 | 字段 | 类型 | 必传 | 备注 |
---|---|---|---|---|
私钥 | privateKey | String | 是 | 主私钥 |
DID | did | String | 是 | |
名称 | name | String | 是 | 发证方名称 |
- 输出参数:
字段名 | 字段 | 类型 | 必传 | 备注 |
---|---|---|---|---|
Boolean | 是 |
1.5 注册凭证模板
发证方依据自己所要签发的凭证信息,自定义凭证属性形成一份凭证模板。
1.5.1 功能介绍
一个发证方可以定义多个凭证模板逐个进行注册,基于凭证模板可以签发多个凭证,每个凭证都由发证方的私钥进行签名。
1.5.2 API定义
方法定义:
CptBaseInfo registerCpt(RegisterCpt registerCpt);
- 调用者:运营方;
- 核心逻辑:
- 验证DID Document是否在链上存在;
- 解析DID Document的主公钥与当前公钥进行比对;
- 验证DID是否为发证方;
- 注册凭证模板并对模板信息上链。
- 输入参数:
字段名 | 字段 | 类型 | 必传 | 备注 |
---|---|---|---|---|
私钥 | privateKey | String | 是 | 主私钥 |
DID | did | String | 是 | |
属性信息 | cptJsonSchema | Map |
是 | |
标题 | 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) ;
- 调用者:运营方;
- 核心逻辑:
- 验证DID Document是否在链上存在;
- 解析DID Document的主公钥与当前公钥进行比对;
- 验证DID是否为发证方;
- 验证凭证模板是否在链上存在;
- 验证属性格式;
- 凭证签发并返回凭证信息。
- 输入参数:
字段名 | 字段 | 类型 | 必传 | 备注 |
---|---|---|---|---|
私钥 | privateKey | String | 是 | 主私钥 |
DID | issuerDid | String | 是 | 发证方的DID |
DID | userDid | String | 是 | 用户的DID |
到期日 | expirationDate | String | 是 | |
属性 | claim | Map |
是 | 和凭证模板的格式一致 |
类型 | 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 |
是 | |
签名信息 | proof | Map |
是 |
1.7 验证凭证
用户可以通过“验证凭证”对凭证的真伪性、有效性进行查验。。1.7.1 功能介绍验证凭证包含两个方面:验证凭证内容和验证凭证是否到期,两个方面都验证通过,则认为凭证有效。1.7.2 API定义
- 方法定义:Boolean verifyCredential(Credential credential,PublicKey publickKey);
- 调用者:平台方、运营方;核心逻辑:
- 根据签名信息内的DID,在链上查询对应的Document;
- 解析Document内的公钥对凭证验签;
- 验证凭证内的到期日期。
- 输入参数:
- 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 |
是 | |
签名信息 | proof | Map |
是 |
- PublicKey
字段名 | 字段 | 类型 | 必传 | 备注 |
---|---|---|---|---|
算法类型 | type | String | 是 | Secp256k1 |
公钥 | publicKey | String | 是 | 主公钥 |
- 输出参数:
字段名 | 字段 | 类型 | 必传 | 备注 |
---|---|---|---|---|
Boolean | 是 |
1.8吊销凭证
发证方可通过“吊销凭证”吊销已经签发给用户的凭证。
1.8.1 功能介绍
发证方对已签发的凭证进行作废标记。凭证已签发给用户,发证方是无法直接修改。所以凭证吊销后将吊销的凭证编号存储与区块链网络中。
1.8.2 API定义
方法定义:
Boolean revokeCredential(RevokeCredential cred) ;
- 调用者:平台方;
- 核心逻辑:
- 验证请求参数合法性;
- 通过DID标识符查询DID Document内的主公钥,验证其是否与请求参数内的私钥是否匹配;
- 通过凭证模板编号查询验证发证方与凭证模板的关联关系;
- 将凭证编号上链标记为已吊销;
- 返回吊销结果。
- 输入参数:
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
getRevokedCredList(QueryCredentialList queryCredentialList) ; - 调用者:运营方;
- 核心逻辑:
- 验证请求参数合法性;
- 按请求参数查询相应结果;
- 返回吊销结果。
- 输入参数:
字段名 | 字段 | 类型 | 必传 | 备注 |
---|---|---|---|---|
页码 | 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/di...。欲浏览更多信息,请您点击登录查看。