5. DID-接入协议
5.1. 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颁证机构接入协议
5.2. DID应用接入协议
DID APP 已实现扫码登录、扫码出示VP、扫码签名和扫码授权文件几项功能，若有相关需求，可开发对应功能进行接入，基本流程为：
一、 DID 应用需提供二维码供 APP 扫描，二维码内容应为一个 url，通过请求这个 url，返回一个 VP 结构。
二、 在此阶段，APP 与 DID 应用通过 VerifiablePresentation 进行数据通信和可信验证，平台方需按照需求自行生成对应VP。
生成VP 通用流程如下：
构建对应功能自定义字段 extend 内容，具体参数详见对应功能流程和接口示例
根据不同功能，设置VP中 presentationUsage 参数，具体见附录 VP中presentationUsage字段含义值
设置过期时间等参数，并使用DID管理台或其他工具对 VP 进行签名
三、 应用还需实现接口接收来自 APP 的回调信息，此接口地址置于上面 VP extend中，DID APP 在进行完相关操作后将请求此 callbackUrl，具体回调参数详见对应功能接入协议接口
四、 应用接收到 APP 回调信息后继续完成相关操作
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 登录
5.2.2. DID APP扫码出示VP
场景：网站出示二维码，使用DID APP扫码授权出示VP。网站可获得签名后的VC数据
在此场景下，向 APP 提供的 VP 中应包含以下信息：
| 参数名 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| 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
5.2.3. DID APP扫码签名
场景：网站出示二维码，使用DID APP扫码签名。网站可获得签名后的数据
在此场景下，向 APP 提供的 VP 中应包含以下信息：
| 参数名 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| 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 | String | 是 | 授权方主体类型(个人/企业) |
| authoriserCompanyName | String | 否 | 授权方企业名称 |
| authoriserUSCC | String | 否 | 授权方统一社会信用代码 |
| authoriserPersonalName | String | 否 | 授权方个人姓名 |
| authoriserIdCard | String | 否 | 授权方身份证号 |
| authoriedCompanyName | String | 是 | 被授权方企业名称 |
| authoriedUSCC | String | 是 | 被授权方统一社会信用代码 |
| validityPeriod | String | 是 | 有效期(含) |
| extendField | String | 是 | 扩展字段，例如报关单号等 |
| requiredVC | Boolean | 是 | 是否需要实名VC，true-需要 false-不需要 |
APP 将发送携带签名信息的 VP 请求到回调地址，应用进行验证，并返回验证是否通过
具体接口详见：APP扫码签名接口
5.2.3.1. 扫码签名流程如下
DID APP 签名
5.2.4. DID APP扫码授权文件
场景：网站出示二维码，使用DID APP扫码授权授权存证文件。
在此场景下，向 APP 提供的 VP 中应包含以下信息：
| 参数名 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| 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 授权文件
5.3. DID 注册接入协议
场景：境外用户注册，需要获得邀请码，同时需要平台企业根据邀请码签发相应的用户凭证信息。
在 DID APP 注册非大陆企业时，需要填写邀请码。平台方需向 DID 服务申请邀请码，并提供签发第三方企业用户证书（template为 100003）的能力。因此，平台方应实现以下两个接口功能：
向 DID 服务接口（详见申请邀请码接口）发送请求，申请邀请码，通过包含以下信息的 VP：
| 参数名 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| description | String | 否 | 描述，提示用户查看信息。当extend.auth为1时必填 |
| callbackUrl | String | 是 | 回调地址：境外企业获取VC，获取授权信息使用 |
| action | String | 是 | 当前类型为注册认证 |
| created | String | 是 | 创建时间 |
| enterpriseName | String | 是 | 被邀请的公司名称 |
| type | Integer | 是 | 企业类型，1 境外 0境内 |
| auth | Integer | 是 | 1 需要单证授权，0 不需要授权，只注册用户，授权流程再次扫描二维码；默认0 |
提供签发第三方企业用户证书功能详见申请VC接口。用户在绑定DID后，会向此接口地址发送包含以下信息的 VP，平台方验证后颁发凭证以及申请授权等操作。
| 参数名 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| auth | Integer | 是 | 1 需要单证授权，0 不需要授权，只注册用户，授权流程再次扫描二维码；默认0 |
| enterpriseName | String | 是 | 被邀请的公司名称 |
| holder | String | 是 | 持证人，填企业DID |
| invitationCode | String | 是 | 邀请码 |
| type | Integer | 是 | 企业类型，1 境外 0境内 |
5.3.1. 完整注册流程如下
DID 注册接入
5.4. 附录
5.4.1. DID document
{
"@context": [
"https://www.w3.org/ns/did/v1"
],
"id": "did:cert:123456789abcdefghi",
"created": "2022-01-01T00:00:00Z",
"updated": "2022-01-10T10:00:00Z",
"version": "1",
"unionId": {
"abcid": "did:abcid:1CFC4FE0C938F28A77A50E0D5C89FA8FBE95AF005307BEADA0F3EF007DD1EC89"
},
"verificationMethod": [
{
"id": "did:cert:123456789abcdefghi#keys-1",
"type": "SM2VerificationKey2022",
"controller": "did:cert:123456789abcdefghi",
"publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoEcz1UBgi0DQgAEYbBKJ5xqkUaxYOoJlKkZIb2rhoVw\nZbjmyF9BRmOiBdp5Jde3QswKjicjMccB299I2n5UgQKdU8nPAY69Qiv5/w==\n-----END PUBLIC KEY-----",
"address": "0x2B5AD5c4795c026514f8317c7a215E218DcCD6cF"
}
],
"authentication": [
"did:cert:123456789abcdefghi#keys-1"
],
"controller": [
"did:cert:123456789abcdefghi",
"did:cert:admin"
],
"service": [
{
"id": "did:cert:issuer1#issuerService",
"type": "IssuerService",
"serviceEndpoint": "https://issuer.example.com/service"
}
],
"proof": [
{
"type": "SM2Signature",
"created": "2022-01-01T00:00:00Z",
"proofPurpose": "assertionMethod",
"verificationMethod": "did:cert:123456789abcdefghi#keys-1",
"proofValue": "eyJhbGciOiJFUzI1NksiLCJraWQiOiJkaWQ6ZXhhbXBsZToxMjM0NTY3ODlhYmNkZWZnaGlfa2V5LTEiLCJ0eXAiOiJKV1MifQ..Q9JYDNOU0oyJkXW5NcC1hR3U4SHN6U1RiY3pvYkUzam5vY3VtY2tjZERxY3dLd1Z0a1d0Z2pUa0dWY3A0bFZJZw"
}
]
}
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 | 响应签名授权书 |