5. 接入协议

5.1. DID颁证机构接入协议

申请成为DID颁证机构的一些前提条件，需要满足相关的DID颁证机构接入协议。以便用户能够申请到颁证机构可以颁发的凭证。

作为颁证机构，需要支持以下协议（DID管理台默认提供一种实现），具体协议详情：DID颁证机构接入协议接口

接口名称 地址 必须 描述
查询VC列表 {service_url}/did/vc/list 是 用户可以使用自身DID签名获得颁证机构给用户颁发过的VC
查询签发凭证类型 {service_url}/did/vc/type/list 否 用户可以查询颁发机构支持签发凭证类型
查询公开的凭证模板列表 {service_url}/did/vct/list 否 用户可以查询颁证机构签发凭证模板
查询凭证模板详情 {service_url}/did/vct/get 否 用户可以使用模板ID查询颁证机构本地凭证模板详情
申请VC {service_url}/did/vc/apply 否 用户可以申请公开的凭证
注销VC（用户自主） {service_url}/did/vc/cancel 否 用户可以申请注销自己的凭证
获取申请签发状态 {service_url}/did/vc/apply/list 否 用户可以查询凭证签发状态

{service_url}是签发机构Document中的Service模块， document.service[?].serviceEndpoint 见附录 [DID document](#DID document)

图示如下：

DID接入协议-颁发机构
DID颁证机构接入协议

5.2. DID应用接入协议

DID APP 已实现扫码登录、扫码出示VP、扫码签名和扫码授权文件几项功能，若有相关需求，可开发对应功能进行接入，基本流程为：

一、 DID 应用需提供二维码供 APP 扫描，二维码内容应为一个 url，通过请求这个 url，返回的响应体中 data 为一个 VP 结构。

二、 在此阶段，APP 与 DID 应用通过 VerifiablePresentation 进行数据通信和可信验证，平台方需按照需求自行生成对应VP。

生成VP 通用流程如下：

  1. 构建对应功能自定义字段 extend 内容，具体参数详见对应功能流程和接口示例

  2. 根据不同功能，设置VP中 presentationUsage 参数，具体见附录 VP中presentationUsage字段含义值

  3. 设置过期时间等参数，并使用DID管理台或其他工具对 VP 进行签名

三、 应用还需实现接口接收来自 APP 的回调信息，此接口地址置于上面 VP extend中，DID APP 在进行完相关操作后将请求此 callbackUrl，具体回调参数详见对应功能接入协议接口

四、 应用接收到 APP 回调信息后继续完成相关操作

注：所有响应的结构体为以下通用结构，在扫码场景下，data应为一个VP结构。响应成功，code应为200000

{
  "code": 200000,
  "msg": "ok",
  "data": {}
}

5.2.1. DID APP扫码登录

场景：网站出示二维码，使用DID APP扫码授权登录。

在此场景下，向 APP 提供的 VP 中 extend 应包含以下信息：

参数名 参数类型 是否必填 参数描述
authorizedName String 是 请求授权的平台的名称
authorizedNameEn String 是 请求授权的平台的英文名称
callbackUrl String 是 平台实现的回调接口地址，APP将向此地址发送回调信息
logo String 否 请求登录网站的logo图标
method String 是 回调地址的http请求方式
requestId String 是 当次请求的唯一ID，64位UUID，用于APP回调返回
siteName String 否 请求登录网站的名称

APP 将发送携带 requestId 的 VP 请求到回调地址，应用进行验证，并返回验证是否通过

具体接口详见：APP扫码登录接口

5.2.1.1. 登录流程如下

DID接入协议-APP登录
DID APP 登录

5.2.2. DID APP扫码出示VP

场景：网站出示二维码，使用DID APP扫码授权出示VP。网站可获得签名后的VC数据

在此场景下，向 APP 提供的 VP 中 extend 应包含以下信息：

参数名 参数类型 是否必填 参数描述
authorizedName String 是 请求授权的平台的名称
authorizedNameEn String 是 请求授权的平台的英文名称
callbackUrl String 是 平台实现的回调接口地址，APP将向此地址发送回调信息
issuer String 是 颁证机构DID
method String 是 回调地址的http请求方式
requestId String 是 当次请求的唯一ID，64位UUID，用于APP回调返回
vctId String 是 凭证模板ID

APP 将发送携带 requestId 以及 VC 的 VP 请求到回调地址，应用进行验证，并返回验证是否通过。之后应用可展示实名信息。

具体接口详见：APP扫码出示VP接口

5.2.2.1. 扫码出示VP流程如下

DID接入协议-APP出示VP
DID APP 出示VP

5.2.3. DID APP扫码签名

场景：网站出示二维码，使用DID APP扫码签名。网站可获得签名后的数据

在此场景下，向 APP 提供的 VP 中 extend 应包含以下信息：

参数名 参数类型 是否必填 参数描述
authorizedName String 是 请求授权的平台的名称
authorizedNameEn String 是 请求授权的平台的英文名称
callbackUrl String 是 平台实现的回调接口地址，APP将向此地址发送回调信息
method String 是 回调地址的http请求方式
requestId String 是 当次请求的唯一ID，64位UUID，用于APP回调返回
authorisationId String 是 授权书Id
applyNumber String 是 申请单编号
authorisationTitle String 是 授权书标题
authorisationContent String 是 授权书正文
authoriserSubjectType Int 是 授权方主体类型(个人/企业)
authoriserCompanyName String 否 授权方企业名称
authoriserUSCC String 否 授权方统一社会信用代码
authoriserPersonalName String 否 授权方个人姓名
authoriserIdCard String 否 授权方身份证号
authorisedCompanyName String 是 被授权方企业名称
authorisedUSCC String 是 被授权方统一社会信用代码
validityPeriod String 是 有效期(含)
extendField String 是 扩展字段，例如报关单号等
requiredVC Boolean 是 是否需要实名VC，true-需要 false-不需要

APP 将发送携带签名信息的 VP 请求到回调地址，应用进行验证，并返回验证是否通过

具体接口详见：APP扫码签名接口

5.2.3.1. 扫码签名流程如下

DID接入协议-APP签名
DID APP 签名

5.2.4. DID APP扫码授权文件

场景：网站出示二维码，使用DID APP扫码授权授权存证文件。

此场景可分为单证授权（确定某一文件ID，请求该文件授权）和多证授权（不确定文件ID，请求多个文件授权）两种情况。在单证授权的情景下 businessID、 businessType、createdTime、fileID 字段为必填，多证授权则无需填写。APP 在扫码二维码后，会通过是否存在 fileID 字段区分两种情况。

在此场景下，向 APP 提供的 VP 中 extend 应包含以下信息：

参数名 参数类型 是否必填 参数描述
authorizedDID String 是 被授权企业的did
authorizedName String 否 被授权企业的昵称
authorizedVerificationMethod String 是 被授权企业的用于加密的公钥ID
businessID String 否 文件业务ID
businessType String 否 文件业务类型
createdTime String 否 创建时间
fileID String 否 请求授权的文件ID
fileName String 否 请求授权的文件名称
operatorDID String 否 文件提供方的DID
operatorName String 否 文件提供方的昵称
updateType String 否 updateType为add表示新增授权，为del表示取消授权，默认添加
requestId String 是 当次请求的唯一ID，64位UUID，用于APP回调返回

此场景下，APP 不会发送回调信息，而是由存证中心给请求授权企业发送事件通知

具体接口详见：APP扫码授权文件接口

5.2.4.1. 扫码授权文件流程如下

DID接入协议-APP授权文件
DID APP 授权文件

5.3. DID APP注册接入协议

DID APP注册需要实名，若不需要实名则可以在部署时跳过实名验证。直接使用境内注册即可。

场景：境外用户注册，需要获得邀请码，同时需要平台企业根据邀请码签发相应的用户凭证信息。

在 DID APP 注册非大陆企业时，需要填写邀请码。平台方需向 DID 服务申请邀请码，并提供签发第三方企业用户证书（template为 100003）的能力。因此，平台方应实现以下两个接口功能：

  1. 向 DID 服务接口（详见申请邀请码接口）发送请求，申请邀请码，通过包含以下信息（extend 内容）的 VP：

参数名 参数类型 是否必填 参数描述
description String 否 描述，提示用户查看信息。当extend.auth为1时必填
callbackUrl String 是 回调地址：境外企业获取VC，获取授权信息使用
action String 是 当前类型为注册认证
created String 是 创建时间
enterpriseName String 是 被邀请的公司名称
type Integer 是 企业类型，1 境外 0境内
auth Integer 是 1 需要单证授权，0 不需要授权，只注册用户，授权流程再次扫描二维码；默认0

  1. 提供签发第三方企业用户证书功能详见申请VC接口。用户在绑定DID后，会向此接口地址发送包含以下信息 （extend 内容）的VP，平台方验证后颁发凭证以及申请授权等操作。

参数名 参数类型 是否必填 参数描述
auth Integer 是 1 需要单证授权，0 不需要授权，只注册用户，授权流程再次扫描二维码；默认0
enterpriseName String 是 被邀请的公司名称
holder String 是 持证人，填企业DID
invitationCode String 是 邀请码
type Integer 是 企业类型，1 境外 0境内

5.3.1. 完整注册流程如下

DID接入协议-注册
DID 注册接入

5.4. 附录

5.4.1. DID document 示例

{
  "@context": [
    "https://www.w3.org/ns/did/v1"
  ],
  "authentication": [
    "did:cndid:22a985689f0c08733ac55bffd3e430d1c2896a0b#key-1"
  ],
  "controller": [
    "did:cndid:cndid",
    "did:cndid:22a985689f0c08733ac55bffd3e430d1c2896a0b"
  ],
  "id": "did:cndid:22a985689f0c08733ac55bffd3e430d1c2896a0b",
  "proof": [
    {
      "created": "2024-08-27T07:59:45Z",
      "proofPurpose": "verificationMethod",
      "proofValue": "MEUCIEknK5LATLspycW95n676t1JH3M4bVxZag6VQl+6lzTwAiEApkGPy9o1eROQCoUO3WhfH0GX54dL5w8lSPDutMItmB4=",
      "type": "SM2Signature",
      "verificationMethod": "did:cndid:22a985689f0c08733ac55bffd3e430d1c2896a0b#key-1"
    }
  ],
  "service": [
    {
      "id": "did:cndid:issuer#issuerService-1",
      "serviceEndpoint": "https://cnbn.org.cn/api/v1",
      "type": "IssuerService"
    }
  ],
  "verificationMethod": [
    {
      "address": "22a985689f0c08733ac55bffd3e430d1c2896a0b",
      "controller": "did:cndid:22a985689f0c08733ac55bffd3e430d1c2896a0b",
      "id": "did:cndid:22a985689f0c08733ac55bffd3e430d1c2896a0b#key-1",
      "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoEcz1UBgi0DQgAElbWAttQNuw7kkdJMy5sB2m9ZSJTP\nkmX4Ju6Ycyzs28Qn3B0syYfXzvHGPD0HGGwH7RCQx4ptOplIGBCIuLkINg==\n-----END PUBLIC KEY-----\n",
      "type": "SM2VerificationKey"
    }
  ]
}

5.4.2. VP中presentationUsage字段含义值

presentationUsage 含义
DID_LOGIN_REQUEST 请求授权登录
DID_LOGIN_RESPONSE 响应授权登录
DID_GET_VC_REQUEST 请求获取证书
DID_GET_VC_RESPONSE 响应获取证书
DID_GET_IDENTITY_VC_REQUEST 请求实名认证证书
DID_GET_IDENTITY_VC_RESPONSE 响应实名认证证书
TDH_APPLY_AUTH_REQUEST 请求选择文件授权给本平台
TDH_GET_AUTH_TO_REQUEST 请求文件授权给其他平台
DID_APPLY_ISSUE_VC 申请签发VC
IDA_AUTHORISATION_REQUEST 请求签名授权书
IDA_AUTHORISATION_RESPONSE 响应签名授权书
DID_APPLY_INVITATION_CODE_CALLBACK 境外企业通过邀请码申请VC