# DID-接入协议 ## DID颁证机构接入协议 申请成为DID颁证机构的一些前提条件，需要满足相关的DID颁证机构接入协议。以便用户能够申请到颁证机构可以颁发的凭证。 作为颁证机构，需要支持以下协议，具体协议详情：[DID办证机构接入协议接口](./DID-接入协议接口.html#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颁证机构接入协议
## DID应用接入协议 DID APP 已实现扫码登录、扫码出示VP、扫码签名和扫码授权文件几项功能，若有相关需求，可开发对应功能进行接入，基本流程为： > 一、 DID 应用需提供二维码供 APP 扫描，二维码内容应为一个 url，通过请求这个 url，返回一个 VP 结构。 > 二、 在此阶段，APP 与 DID 应用通过 VerifiablePresentation 进行数据通信和可信验证，平台方需按照需求自行生成对应VP。 生成VP 通用流程如下： 1. 构建对应功能自定义字段 extend 内容，具体参数详见对应功能流程和接口示例 2. 根据不同功能，设置VP中 presentationUsage 参数，具体见附录 [VP中presentationUsage字段含义值](#presentationUsage) 3. 设置过期时间等参数，并使用DID管理台或其他工具对 VP 进行签名 > 三、 应用还需实现接口接收来自 APP 的回调信息，此接口地址置于上面 VP extend中，DID APP 在进行完相关操作后将请求此 callbackUrl，具体回调参数详见对应功能接入协议接口 > 四、 应用接收到 APP 回调信息后继续完成相关操作 ### 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扫码登录接口](./DID-接入协议接口.html#APP扫码登录接口) #### 登录流程如下
DID接入协议-APP登录
DID APP 登录
### 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接口](./DID-接入协议接口.html#APP扫码出示VP接口) #### 扫码出示VP流程如下
DID接入协议-APP出示VP
DID APP 出示VP
### 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扫码签名接口](./DID-接入协议接口.html#APP扫码签名接口) #### 扫码签名流程如下
DID接入协议-APP签名
DID APP 签名
### 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扫码授权文件接口](./DID-接入协议接口.html#APP扫码授权文件接口) #### 扫码授权文件流程如下
DID接入协议-APP授权文件
DID APP 授权文件
## DID 注册接入协议 > 场景：境外用户注册，需要获得邀请码，同时需要平台企业根据邀请码签发相应的用户凭证信息。 在 DID APP 注册非大陆企业时，需要填写邀请码。平台方需向 DID 服务申请邀请码，并提供签发第三方企业用户证书（template为 100003）的能力。因此，平台方应实现以下两个接口功能： 1. 向 DID 服务接口（详见[申请邀请码接口](./DID-接入协议接口.html#申请邀请码接口)）发送请求，申请邀请码，通过包含以下信息的 VP： | 参数名 | 参数类型 | 是否必填 | 参数描述 | |----------------|---------|------|----------------------------------------| | description | String | 否 | 描述，提示用户查看信息。当extend.auth为1时必填 | | callbackUrl | String | 是 | 回调地址：境外企业获取VC，获取授权信息使用 | | action | String | 是 | 当前类型为注册认证 | | created | String | 是 | 创建时间 | | enterpriseName | String | 是 | 被邀请的公司名称 | | type | Integer | 是 | 企业类型，1 境外 0境内 | | auth | Integer | 是 | 1 需要单证授权，0 不需要授权，只注册用户，授权流程再次扫描二维码；默认0 | 2. 提供签发第三方企业用户证书功能详见[申请VC接口](./DID-接入协议接口.html#申请VC接口)。用户在绑定DID后，会向此接口地址发送包含以下信息的 VP，平台方验证后颁发凭证以及申请授权等操作。 | 参数名 | 参数类型 | 是否必填 | 参数描述 | |----------------|---------|------|----------------------------------------| | auth | Integer | 是 | 1 需要单证授权，0 不需要授权，只注册用户，授权流程再次扫描二维码；默认0 | | enterpriseName | String | 是 | 被邀请的公司名称 | | holder | String | 是 | 持证人，填企业DID | | invitationCode | String | 是 | 邀请码 | | type | Integer | 是 | 企业类型，1 境外 0境内 | ### 完整注册流程如下
DID接入协议-注册
DID 注册接入
## 附录 ### DID document ```json { "@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" } ] } ``` ### 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 | 响应签名授权书 |