# 接入协议

## DID颁证机构接入协议

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

作为颁证机构，需要支持以下协议（DID管理台默认提供一种实现），具体协议详情：[DID颁证机构接入协议接口](./04_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)

图示如下：

<div align="center">
<img loading="lazy" src="../images/DID-Access-Protocol-Issuing-Authority.png" style="zoom:50%;" alt="DID接入协议-颁发机构"/>
<br>
DID颁证机构接入协议
</div>

## DID应用接入协议

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

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

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

> 生成VP 通用流程如下：

> 1. 构建对应功能自定义字段 extend 内容，具体参数详见对应功能流程和接口示例
> 2. 根据不同功能，设置VP中 presentationUsage 参数，具体见附录 [VP中presentationUsage字段含义值](#presentationUsage)
> 3. 设置过期时间等参数，并使用DID管理台或其他工具对 VP 进行签名

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

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

> 注：所有响应的结构体为以下通用结构，在扫码场景下，data应为一个VP结构。响应成功，code应为200000
> ```json
> {
>   "code": 200000,
>   "msg": "ok",
>   "data": {}
> }
> ```

### 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扫码登录接口](./04_DID-接入协议接口.html#APP扫码登录接口)

#### 登录流程如下

<div align="center">
<img loading="lazy" src="../images/DID接入协议-APP登录.png" style="zoom:100%;" alt="DID接入协议-APP登录"/>
<br>
DID APP 登录
</div>

### 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接口](./04_DID-接入协议接口.html#APP扫码出示VP接口)

#### 扫码出示VP流程如下

<div align="center">
<img loading="lazy" src="../images/DID接入协议-APP出示VP.png" style="zoom:100%;" alt="DID接入协议-APP出示VP"/>
<br>
DID APP 出示VP
</div>

### 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扫码签名接口](./04_DID-接入协议接口.html#APP扫码签名接口)

#### 扫码签名流程如下

<div align="center">
<img loading="lazy" src="../images/DID接入协议-APP签名.png" style="zoom:100%;" alt="DID接入协议-APP签名"/>
<br>
DID APP 签名
</div>

### 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扫码授权文件接口](./04_DID-接入协议接口.html#APP扫码授权文件接口)

#### 扫码授权文件流程如下

<div align="center">
<img loading="lazy" src="../images/DID接入协议-APP授权文件.png" style="zoom:100%;" alt="DID接入协议-APP授权文件"/>
<br>
DID APP 授权文件
</div>

## DID APP注册接入协议

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

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

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

1. 向 DID 服务接口（详见[申请邀请码接口](./04_DID-接入协议接口.html#申请邀请码接口)）发送请求，申请邀请码，通过包含以下信息（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 |

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

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

### 完整注册流程如下

<div align="center">
<img loading="lazy" src="../images/DID接入协议-注册.png" style="zoom:60%;" alt="DID接入协议-注册"/>
<br>
DID 注册接入
</div>

## 附录

<span id="DID document"></span>

### DID document 示例

```json
{
  "@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"
    }
  ]
}
```

<span id="presentationUsage"></span>

### 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 |