WeIdentity 规范文档

1. 设计目标

2. 相关术语

详见：术语表

3. WeIdentity DID

WeIdentity DID与WeIdentity Credential的关系

从图中可见，WeIdentity DID与WeIdentity Credential的关系并非单纯的一对多：从设计目标上看，WeIdentity DID用来描述实体（人或物），WeIdentity Credential用来描述实体的身份、属性和实体间关系。因此，一个WeIdentity DID可以持有多个WeIdentity Credential；而一个WeIdentity Credential则会包含至少一个所描述的WeIdentity DID，可能会有多个。最后，每个WeIdentity DID都有一个WeIdentity Document，用来存储此DID的认证方式（如公钥、私钥套件）等信息，与WeIdentity Credential无关。

总体流程

一般来说，WeIdentity解决方案的基本流程如下：

1. 用户根据业务需求，选择是否需要进行KYC认证。
2. 用户生成WeIdentity DID。
3. 用户向相关业务方申请Credential。
4. 相关业务方扮演Issuer的角色，发行Credential交给用户。
5. 用户成为了Credential的Holder。
6. 用户出示Credential，以完成业务需求。
7. 相关业务方扮演Verifier的角色，验证Credential有效性。

如何生成WeIdentity DID

WeIdentity DID = did:weid:chain-id:bs-specific-string

备注：bsSpecificString根据区块链底层平台和业务具体情况来确定生成规则，例如可以是随机字符串，或者区块链上的地址。

示例: "did:weid:1:0x0086eb1f712ebc6f1c276e12ec21"

WeIdentity Document格式

• WeIdentity DID的Authorization机制由补充规范实现。示例：

{
  "@context": "https://weidentity.webank.com/did/v1",
  "id": "did:weid:1:123456789abcdefghi",
  "created": "2017-09-24T17:00:00Z",
  "updated": "2018-09-24T02:41:00Z",
  "publicKey": [{
    "id": "did:example:123456789abcdefghi#keys-1",
    "type": "RsaVerificationKey2018",
    "owner": "did:example:123456789abcdefghi",
    "publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n"
  }, {
    "id": "did:example:123456789abcdefghi#keys-2",
    "type": "Secp256k1VerificationKey2018",
    "owner": "did:example:123456789abcdefghi",
    "publicKeyHex": "02b97c30de767f084ce3080168ee293053ba33b235d7116a3263d29f1450936b71"
  }],
  "authentication": [{
    // this key can be used to authenticate as DID ...9938
    "type": "RsaSignatureAuthentication2018",
    "publicKey": "did:weid:1:123456789abcdefghi#keys-1"
    }
  ],
  "service": [{
    "type": "drivingCardService",
    "serviceEndpoint": "https://weidentity.webank.com/endpoint/8377464"
    }, {
    "type": "padiCertificateService",
    "serviceEndpoint": "https://weidentity.webank.com/endpoint/8377465"
  }],
  "recovery": ["did:weid:1:2323e3e3dweweewew2","did:weid:1:2323e3e3dweweewew3"],
}

WeIdentity DID支持操作

创建

创建一个WeIdentity DID（以及对应的WeIdentity Document）

读取/验证

通过WeIdentity DID读取到WeIdentity Document，并验证

更新

更新WeIdentity Document的相关属性

4. WeIdentity Credentials

角色和关系

如图所示在WeIdentity生态中，存在着以下角色：

角色	说明
User (Entity)	用户（实体）。会注册属于自己的WeIdentity DID，申请Credential，并通过出示给相关业务方来使用之。
Issuer	Credential的发行者。会首先验证实体对WeIdentity DID的所有权，其次发行Credential交给实体。
Verifier	Credential的使用者。会首先验证实体对WeIdentity DID的所有权，其次验证Credential的有效性。
User Agent / Credential Repository	用户（实体）在此生成WeIdentity DID。为了便于使用，实体也可将自己的私钥、持有的Credential托管于此。

场景

上图展示了五个WeIdentity生态下Credential在不同角色间流转的场景：

• 身份证明机构作为Issuer向用户发行「实名认证Credential」，政府机构作为Verifier在办理公共事务时对其进行验证。
• 学校作为Issuer向用户发行「学历证明Credential」，公司作为Verifier在对候选人进行背景调查时对其进行验证。
• 出入境机构作为Issuer向用户发行「签证Credential」，海关作为Verifier在出入境时对其进行验证。
• 公司作为Issuer向用户发行「收入证明Credential」，银行作为Verifier在发放贷款时对其进行验证。
• 商户作为Issuer向用户发行「优惠券Credential」，商户自己作为Verifier在对优惠券核销时对其进行验证。更多使用场景，可见： 使用场景文档。

Credential结构

区块链上的Credential结构

{
  "@context": "https://weidentity.webank.com/vc/v1",
  "id": "dsfewr23sdcsdfeqeddadfd",
  "type": ["Credential", "cpt100"],
  "issuer": "did:weid:1:2323e3e3dweweewew2",
  "issued": "2010-01-01T21:19:10Z",
  "claim": {
    "primeNumberIdx":"1234"
    //the other properties in this structure varied according to different CPT
  },
  "revocation": {
    "id": "did:weid:1:2323e3e3dweweewew2",
    "type": "SimpleRevocationList2017"
  },
  "signature": [{
    "type": "LinkedDataSignature2015",
    "created": "2016-06-18T21:19:10Z",
    "creator": "did:weid:1:2323e3e3dweweewew2",
    "domain": "www.diriving_card.com",
    "nonce": "598c63d6",
    "signatureValue": "BavEll0/I1zpYw8XNi1bgVg/sCneO4Jugez8RwDg/+MCRVpjOboDoe4SxxKjkC
  OvKiCHGDvc4krqi6Z1n0UfqzxGfmatCuFibcC1wpsPRdW+gGsutPTLzvueMWmFhwYmfIFpbBu95t501+r
    SLHIEuujM/+PXr9Cky6Ed+W3JT24="
  }]
}

Claim Protocol Type（CPT）注册机制

不同的Issuer按业务场景需要，各自定义不同类型数据结构的Claim，所有的Claim结构都需要到CPT合约注册，以保证全网唯一。所有的CPT定义文件（JSON-LD格式）可以从CPT合约下载。

• CPT格式

  属性	说明
  @context	用于描述CPT等信息
  id	CPT的编号，要保证唯一
  version	CPT的版本号
  publisher	CPT的发布者的WeIdentity DID
  signature	CPT的发布者的签名
  claim	Claim的格式定义
  created	创建时间
  updated	更新时间
  description	CPT的描述信息

• CPT例子

"CPT": {
  "@context" : "https://weidentity.webank.com/cpt100/v1",
  "version" : "v1",
  "id" : "CPT100",
  "publisher" : "did:weid:1:2323e3e3dweweewew2",
  "signature" : "BavEll0/I1zpYw8XNi1bgVg/sCneO4Jugez8RwDg/+MCRVpjOboDoe4SxxKjkC
  OvKiCHGDvc4krqi6Z1n0UfqzxGfmatCuFibcC1wpsPRdW+gGsutPTLzvueMWmFhwYmfIFpbBu95t501+r
    SLHIEuujM/+PXr9Cky6Ed+W3JT24=",
  "claim" : "",
  "address" : "重庆",
  "class" : "C1",
  "created" : "2010-06-20T21:19:10Z",
  "updated" : "2016-06-20T21:19:10Z",
  "description" : "中国内地驾照"
}

其中CPT为模板类，定义了Claim包含的数据字段及各字段属性要求。Claim为CPT的实例。Issuer将Claim进行签名，即可生成Credential。

Claim示例参考：

Claim实例

Credential操作

创建Credential

任何实体都可以issue一个Credential。

验证Credential

通过这个接口，一个Entity可以对一个Credential进行验证。

存储/提取Credential

Credential的holder可以转移这个Credential，或者提取完整的Credential私下存储。

撤销 Credential

Credential的Issuer可以撤销这个Credential。

选择性披露

如何为Credential生成签名

Issuer生成Credential签名的过程：

• Claim中的每个字段计算生成一个对应的hash值。
• 将Claim中的每个字段的hash值以某种形式拼接起来形成一个字符串Claim_Hash，然后跟Credential原有的其他字段组成一个新的用于计算hash的Credential结构。
• 对这个包含Claim_Hash的Credential结构计算hash，得到Credential Hash。
• 使用Private Key对这个Credential Hash进行签名，得到签名的值Signature。

如何验证选择性披露的Credential

用户选择需要披露的字段集合（可以是一个或者几个字段，这个例子中是Field_1），需要披露的字段提供原文，其他字段提供hash值。将包含这个Claim结构的Credential披露给Verifier。下面是Verifier验证的过程：

• Verifier从Credential提取用户披露的Claim字段。
• Verifier对用户披露的字段分别计算hash（这个例子中是Field_1,计算出Field_1_hash）,然后得到一个包含所有字段hash值的Claim结构。
• 对这个Claim结构中的每个字段的hash值以某种形式拼接起来形成一个字符串Claim_Hash，然后跟Credential原有的其他字段组成一个新的用于计算hash的Credential结构。
• 对这个包含Claim_Hash的Credential结构计算hash，得到Credential Hash。
• 使用Credential的Signature和Issuer的public key进行decrypt，得到一个签名的计算值。
• 比较Credential的Signature与签名的计算值，看是否相等，确认这个Credential的合法性。

Credential撤销

撤销如何工作

Credential撤销机制利用了下面两点：

• 任意大于1的整数 a，如果 a 不是素数，则 a 可以表示为一系列素数的乘积，且这个表示是唯一的（不考虑顺序）。参见：算数基本定理
• 目前没有一个有效率的算法，对两个足够大的素数乘积得到的半素数（semiprime）进行整数分解。参见：整数分解WeIdentity 会公开一个大素数的文件，每个素数会有一个 index，供所有 Issuer 使用。Issuer 发行一个 Credential 的时候，就随机从这个大素数文件中选择一个素数，这个素数的 index 会作为这个 Credential 的属性之一。并把以往所有发行的未撤销的 Credential 的素数相乘，得到一个大数 Accumulator（每个 Issuer 会维护自己的 Accumulator），并将这个 Accumulator 公开供所有接入方查询。

Issuer 如何撤销一个 Credential

用这个 Credential 对应的素数去除 Issuer 自己的 Accumulator，将结果更新为新的 Accumulator。

Verifier 如何验证一个 Credential 有效（未被撤销）

用这个 Credential 对应的素数去除 Credential 的 Issuer 公开的 Accumulator，如果能整除，则表明是 Credential 是有效的（未被撤销）。

5. Authority Issuer注册

链上每个WeIdentity DID持有者（包括人，机构，或者物）都可以issue一个Claim，并打上自己的签名，但只有联盟链里面的权威机构才可以在公共合约注册成为Authority Issuer。每个注册为Authority Issuer的新成员需要联盟链内其他机构投票通过。

6. Notification

通用字段如下，根据不同的type，notification的payload结构不同。

WeIdentity DID注册事件的通知

当创建WeIdentity DID时，注册了该notification的机构会收到这个通知，表明有新的WeIdentity DID被注册。

• payload结构：暂定为NULL。

WeIdentity DID属性修改的通知

当WeIdentity DID的属性有更新时，注册了该notification的机构会收到这个通知，例如public key改变或者其他meta data值改变。

• payload结构（此payload是一个数组，以支持多个属性变更的通知。）：

  字段	说明
  operation	add, update 或者 remove
  field	变动的字段的key
  original	原值
  new	新值

Notification携带业务数据

用于传输小段数据，例如机构间传递Credential的明文可以通过这类通知，payload由机构双方自行约定结构。

Notification订阅

支持对感兴趣的通知进行注册。依赖于实现。

7. 引用

• W3C DID Spec
• W3C Verifiable Credentials
• Linked Data Signatures 1.0 Draft
• RSA Signature Suite 2018