DID function design of BSN-DDC basic network

id:BSN_2021 Public account: BSN Study Club

On January 25, 2022, the Blockchain Service Network Development Alliance (referred to as the "BSN Alliance") launched the "BSN-DDC Basic Network" (referred to as the DDC Network). The launch of the DDC network provides infrastructure capability support for the implementation of NFT technology in my country and protects its compliance development.

DDC (Distributed Digital Certificate) is a distributed digital certificate whose properties and functions are similar to NFT. NFT is the digital proof of rights and interests of something in the real or digital world on the blockchain. Although it is currently mostly used in the field of digital artwork copyright, it is essentially a blockchain distributed database technology and does not carry It has specific business attributes, and its potential usage scenarios are very wide, and can be applied in various fields such as digital commodity certificates, tickets, account management, and intellectual property rights. The DDC network does not directly provide services to individual users, but provides extremely convenient network access services to platforms with DDC/NFT businesses, so that these platforms can provide DDC/NFT generation and management services at extremely low costs.

DDC-SDK is an API tool for developers to interact with DDC contracts. In order to allow operators or platforms to have a comprehensive and detailed understanding of the overall design of DDC-SDK, and to provide original basis and development guidance for the development, testing, verification, delivery and other aspects of the project, BSN Learning Society launched the BSN-DDC Basic Network DDC SDK detailed design series. From eight aspects: overall design, DID function design, DDC authority management, cost management, official contract BSN-DDC-721, official contract BSN-DDC-1155, transaction query, block query, signature event, data analysis, examples, etc. , a comprehensive and detailed introduction to DDC-SDK.

This issue is the second in a series of articles, DID functional design.

DID

The management of digital identity information related to physical users, including registering DID, updating keys, verifying DID, etc., can be ignored by the chain side for the time being.

1.1 Register DID

Individuals or organizations can generate a digital identity for themselves by "registering a DID". Each DID corresponds to a unique DID Document, and the DID Document is stored in the blockchain network.

1.1.1 Function introduction

Registering a DID consists of two steps: generating a DID digital identity for the user and publishing a DID Document to the blockchain network.

1.1.2 API definition

Method definition:

DidDataWrapper createDid();
Caller: platform, operator
Core logic:

Generate two sets of public and private key pairs according to the Secp256k1 algorithm;
Generate Base DID Document;
Generate DID identifiers (refer to "Identifier Generation Rules" for generation rules);
Generate DID Document (refer to "DID Document Format" for format examples);
Execute DID Document uploading process;
Sign the DID with the master public key;
Returns DID, DID signature value, primary and secondary public and private keys, and DID Document data content.

Input parameters: None
Output parameters:

Field name	Field	type	Must pass
DID	did	String	yes
DID signature value	didSign	String	yes
Master private key	authKeyInfo	KeyPair	yes
Prepare public and private keys	recyKeyInfo	KeyPair	yes
DID document	document	DocumentInfo	no
KeyPair
Private key information	privateKey	String	yes
Public key information	publicKey	String	yes
Encryption Algorithm	type	String	yes
DocumentInfo
DID	did	String	yes
version number	version	String	yes
creation time	created	String	yes
Update time	updated	String	no
master public key	authentication	PublicKey	yes
public servant	recovery	PublicKey	yes
Signature information	proof	Proof	yes
PublicKey
Public key information	publicKey	String	yes
Encryption Algorithm	type	String	yes
Proof
Signature value	signValue	String	yes
Signature algorithm	type	String	yes
DID of the signer	creator	String	yes

1.1.3 DID format

The content format of DID consists of three parts: W3C standard format prefix, project name, and DID identifier. The English colon is used as a separator between each part. Example:

did:bsn:3wxYHXwAm57grc9JUr2zrPHt9HC

1.1.3.1 Identifier generation rules

DID identifiers are generated by the following algorithm:

base58(ripemd160(sha256()))

The following is an example of the format of 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 format

The main contents in the DID Document include DID and primary and secondary public key information. The format is as follows:

{
"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 complete format

The DID Document data format content has more proof information than the digest format content. The proof is some information that uses the master private key to sign the DID Document digest format content with Secp256k1. The format is as follows:

{
"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 Update key

If the user's master private key is lost or leaked, a pair of master public and private keys can be regenerated through "Update Key".

1.2.1 Function introduction

Users use the backup public and private keys to update the main public and private keys. After the key is updated, the user's DID Document will also be updated, but the DID will not change.

1.2.2 API definition

Method definition:

KeyPair resetDidAuth(ResetDidAuth restDidAuth);
Caller: Platform, operator;
Core logic:

Verify whether the public and private keys in the request parameters match;
Generate a new master private key;
Verify whether the backup public key in the request parameter is consistent with the backup public key in the DID Document;
Update the DID Document and re-sign according to Secp256k1 using the new master private key;
Return the new key.

Input parameters

Field name	Field	type	Must pass
DID	did	String	yes
Master private key	primaryKey	KeyPair	no
Prepare public and private keys	recoveryKey	KeyPair	yes
KeyPair
private key	privateKey	String	yes
public key	publicKey	String	yes
Encryption Algorithm	type	String	yes

Output parameters:

Field name	Field	type	Must pass
New public and private keys	keyInfo	KeyPair	yes
KeyPair
private key	privateKey	String	yes
public key	publicKey	String	yes
Encryption Algorithm	type	String	yes

1.3 Verify DID

Users can check their DID identity through "Verify DID" to confirm whether the DID Document already exists on the chain; they can also confirm whether the third party's verification of their DID identity can pass.

1.3.1 Function introduction

The user performs signature verification through the master public key in the DID Document. If the signature is passed, the DID identity is recognized.

1.3.2 API definition

Method definition:

Boolean verifyDIdSign(DidSign didSign);
Caller: Platform, operator;
Core logic:

Verify whether the DID Document exists on the chain;
Parse the master public key of the DID Document;
Verify whether the DID signature is correct and return the verification result.

Input parameters:

Field name	Field	type	Must pass	Remark
DID	did	String	yes
DID signature value	didSign	String	yes

Output parameters:

Field name	Field	type	Must pass	Remark
		Boolean	yes

1.4 Registered issuing party

用户可以通过“注册发证方”使自己的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<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) ;
调用者：运营方；
核心逻辑：

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

输入参数：

字段名	字段	类型	必传	备注
私钥	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);
调用者：平台方、运营方；核心逻辑：

根据签名信息内的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<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) ;
调用者：平台方；
核心逻辑：

验证请求参数合法性；
通过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/did-sdk。欲浏览更多信息，请您点击登录查看。

DID function design of BSN-DDC basic network

1.3 Verify DID

Guess you like