> For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt.

# 关于证书

证书用于在开发者服务端与豆包平台之间建立可信通信。它主要解决两类问题：

- **签名与验签**：证明请求是谁发出的，并发现请求内容是否被篡改；
- **加密与解密**：让手机号等敏感数据只能被指定的开发者服务端读取。

> 先记住两条规则：**私钥用于签名或解密，必须由私钥所有者保管；证书中的公钥用于验签或加密，可以提供给通信对方。**

> 开发者证书和平台证书方向相反，不能混用。`cert_serial` 只是选择证书的索引，不是公钥或私钥。

## 一图看懂

这里先不绑定具体业务，按“数据从谁发给谁”拆成四条通用方向。判断使用哪张证书时，只需要先回答两个问题：**谁发送数据？要解决身份可信，还是内容保密？**

```mermaid
flowchart TB
  subgraph SIGN["签名认证：证明发送方身份，防篡改、防重放"]
    D1["开发者"] -->|"① 开发者私钥加签"| P1["豆包平台<br/>用开发者证书公钥验签"]
    P2["豆包平台"] -->|"② 平台私钥加签"| D2["开发者<br/>用平台证书公钥验签"]
  end

  subgraph ENCRYPT["加密传输：只有目标接收方可以读取明文"]
    P3["豆包平台"] -->|"③ 用开发者证书公钥加密"| D3["开发者<br/>用开发者私钥解密"]
    D4["开发者"] -->|"④ 用平台证书公钥加密<br/>按具体接口要求启用"| P4["豆包平台<br/>用平台私钥解密"]
  end

  classDef developer fill:#EEF4FF,stroke:#4C6FFF,color:#172B4D;
  classDef platform fill:#ECFDF3,stroke:#299764,color:#14532D;
  classDef signing fill:#FFF4E5,stroke:#D97706,color:#7C2D12;
  class D1,D2,D3,D4 developer;
  class P1,P2,P3,P4 platform;
  class SIGN,ENCRYPT signing;

```

| 数据方向            | 发送方做什么           | 接收方做什么           | 使用哪套材料               | 场景举例                                         |
| --------------- | ---------------- | ---------------- | -------------------- | -------------------------------------------- |
| ① 开发者 → 平台：签名认证 | 开发者用**开发者私钥加签**  | 平台用**开发者证书公钥验签** | 开发者私钥、开发者证书、开发者证书序列号 | 例如：`requestOrder` 的 `data + dbAuthorization` |
| ② 平台 → 开发者：签名认证 | 平台用**平台私钥加签**    | 开发者用**平台证书公钥验签** | 平台私钥、平台证书、平台证书序列号    | 例如：支付、退款、签约、代扣结果回调                           |
| ③ 平台 → 开发者：加密传输 | 平台用**开发者证书公钥加密** | 开发者用**开发者私钥解密**  | 开发者证书/CSR 公钥、开发者私钥   | 例如：`get_user_phonenumber` 返回加密手机号            |
| ④ 开发者 → 平台：加密传输 | 开发者用**平台证书公钥加密** | 平台用**平台私钥解密**    | 平台证书公钥、平台私钥          | 仅当具体接口文档明确要求加密上传时使用；普通 OpenAPI 请求不要自行加密      |

> **签名看发送方**：谁发送，谁用自己的私钥签名；接收方用发送方证书中的公钥验签。

> **加密看接收方**：要让谁能读取，就用谁的证书公钥加密；接收方再用自己的私钥解密。

是否需要签名或加密，必须以具体接口文档为准。第④种方向只在接口明确要求开发者加密上传数据时使用，不能因为持有平台证书就自行给普通 OpenAPI 请求加密。

## 证书与密钥分别是什么

| 材料                   | 持有方    | 是否保密        | 作用                                   |
| -------------------- | ------ | ----------- | ------------------------------------ |
| `dev.key` / 开发者私钥    | 开发者服务端 | **必须保密**    | 为开发者请求加签；解密平台发给开发者的敏感数据              |
| `dev.csr` / 证书签名请求   | 开发者、平台 | 不包含私钥       | 向平台提交开发者公钥和证书申请信息；本地调试时用于登记开发者公钥     |
| 开发者证书 `dev_cert`     | 开发者、平台 | 可公开         | 包含开发者公钥、证书序列号、有效期等；平台据此验开发者签名或加密敏感数据 |
| 平台证书 `platform_cert` | 平台、开发者 | 可公开         | 包含平台公钥和证书序列号；开发者据此验证平台回调签名           |
| 平台私钥                 | 平台     | **开发者不可获取** | 平台为回调加签                              |

证书不是私钥，也不会替代私钥执行签名或解密。开发者上传 CSR 后，平台签发的是开发者证书；`dev.key` 始终留在开发者自己的服务端。

## 1. 开发者证书：开发者加签，平台验签

### 适用场景

当前最典型的场景是前端支付 API `requestOrder`。业务服务端根据可信订单生成一份最终的 `data` 字符串，再使用开发者私钥生成与该 `data` 绑定的 `dbAuthorization`。前端只能原样透传这两个值。

```text
业务服务端生成最终 data 字节
  → 使用开发者私钥签名
  → 在 dbAuthorization 中携带开发者证书 cert_serial
  → 前端原样调用 requestOrder({ data, dbAuthorization })
  → 平台按 cert_serial 找到开发者证书公钥并验签

```

这里的 `dbAuthorization` 与通用 `X-DB-Authorization` 使用相同的授权串格式，但它是 `requestOrder` 的 API 参数，不是前端自行构造的 HTTP Header：

```text
algorithm="ECDSA_SHA256",version="1",signature="...",cert_serial="...",nonce="...",timestamp="..."

```

开发者签名的作用：

- 证明预下单数据来自持有开发者私钥的业务服务端；
- 保护订单号、金额、商品、商户和回调地址等字段不被篡改；
- 通过 timestamp 和 nonce 限制过期请求并防止重放。

> 前端不能持有开发者私钥，也不能对 `data` 执行 `JSON.parse` 后再次 `JSON.stringify`。即使 JSON 语义相同，只要原始字节变化，验签也会失败。

### 2. 平台证书：平台加签，开发者验签

### 适用场景

平台向开发者服务端发送以下异步通知时，会使用平台私钥加签，并在 HTTP Header 中携带 `X-DB-Authorization`：

- 支付结果回调；
- 退款结果回调；
- 签约结果回调；
- 代扣支付结果回调；
- 其它接口文档明确要求验证 `X-DB-Authorization` 的平台回调。

```text
平台使用平台私钥对回调签名
  → X-DB-Authorization 携带平台证书 cert_serial
  → 开发者按 cert_serial 选择平台证书
  → 使用平台证书公钥验证签名
  → 验签通过后才解析 Body、更新订单或执行其它业务

```

平台回调验签的作用：

- 确认请求确实来自豆包平台，而不是伪造回调；
- 确认回调路径、查询参数和原始 Body 未被篡改；
- 配合 timestamp 与 nonce 防止旧回调被重复利用。

平台证书只提供公钥。开发者不需要、也不可能获得平台私钥。**不要用开发者私钥验证平台回调，也不要用开发者证书公钥代替平台证书公钥。**

### 3. 开发者证书：平台加密，开发者解密

### 适用场景

当前典型场景是登录流程中，开发者服务端使用 `phone_code` 调用 `get_user_phonenumber` 获取加密手机号。平台不会直接返回手机号明文，而是使用开发者公钥加密后返回 `encrypt_phone_number` 或协议约定的 `cipher_data`。

该流程使用 ECIES 思路的混合加密：

1. 平台生成随机 `dataKey`，使用 AES-256-GCM 加密手机号等业务数据；
2. 平台生成临时 P-256 密钥，通过 ECDH 与开发者公钥计算共享密钥；
3. 平台对共享密钥做 SHA-256 得到 KEK，再用 KEK 加密 `dataKey`；
4. 平台将临时公钥、加密后的 `dataKey` 和业务密文编码为 `cipher_data`；
5. 开发者服务端使用配对的 `dev.key` 完成 ECDH，解出 `dataKey`，再解出业务明文。

```text
平台：开发者公钥 + 临时私钥 → ECDH → KEK → 加密 dataKey
平台：dataKey → AES-256-GCM → 加密手机号

开发者：dev.key + 临时公钥 → ECDH → 同一个 KEK → 解密 dataKey
开发者：dataKey → AES-256-GCM → 解密手机号

```

加密传输的作用是保证：即使响应或日志被意外截获，没有开发者私钥也无法还原手机号。平台证书不参与该解密链路。

本地调试时，需要把与 `dev.key` 配对的 `dev.csr` 内容粘贴到 Web 调试器的“输入证书”框，让调试环境取得开发者公钥；业务服务端仍使用同一对密钥中的 `dev.key` 解密。CSR 与私钥不匹配时，接口可能成功返回密文，但服务端无法解密。

## 哪些场景不应使用证书

| 场景                          | 正确方式                                                                   |
| --------------------------- | ---------------------------------------------------------------------- |
| 获取应用级 Token、调用普通服务端 OpenAPI | 按接口文档使用 AppID、AppSecret、`X-DB-AccessToken` 等鉴权信息；证书签名不能替代 Access Token |
| MCP Tool 普通调用               | 按 Manifest 和 MCP 鉴权配置处理；不要自行添加支付签名                                     |
| Page、Widget 或前端登录页面         | 前端不得读取私钥、执行开发者签名或解密手机号                                                 |
| 接收平台支付/退款回调                 | 使用平台证书验签，而不是仅校验 AppSecret、来源 IP 或请求字段                                  |

## 通用签名规则

开发者加签和平台回调验签使用相同的 canonical request 规则：

```text
HTTP_METHOD
REQUEST_PATH
CANONICAL_QUERY
BODY_SHA256_HEX
TIMESTAMP
NONCE

```

等价拼接方式：

```text
HTTP_METHOD + "\n" +
REQUEST_PATH + "\n" +
CANONICAL_QUERY + "\n" +
BODY_SHA256_HEX + "\n" +
TIMESTAMP + "\n" +
NONCE

```

实现时必须遵守：

- 算法为 ECC P-256 + ECDSA-SHA256；
- ECDSA 输出使用 ASN.1 DER，不能改成固定 64 字节的 `r || s`；
- DER 签名使用 URL-safe Base64，并保留编码器生成的 `=` padding；
- timestamp 使用秒级 Unix 时间戳，不是毫秒；
- nonce 每次请求重新生成，服务端需要做防重放；
- Query 为空也要保留空行；
- Body Hash 必须来自实际发送或实际收到的原始字节，计算后不能重新序列化；
- 只执行一次 SHA-256，不能把 digest 再交给会内部 SHA-256 的高层 API。

验签顺序必须是：

1. 保留原始 method、path、query 和 Body 字节；
2. 解析并校验 algorithm、version、`cert_serial`、timestamp、nonce、signature；
3. 按 `cert_serial` 精确选择证书并检查有效期；
4. 校验 timestamp 时间窗口，并使用共享的原子存储检查 nonce 是否重复；
5. 重建 canonical request；
6. 使用证书公钥执行 ECDSA DER 验签；
7. **验签通过后**才解析 Body 和处理业务。

## 加签验签代码 Demo

Go

<a data-download-card data-size="13.09 KB" href="/apps-plugin/docs/wiki-downloads/NSzEwLseGiuFe8kCDqXcZdCInme-01.bin" download="sign.go">sign.go</a>

Java

<a data-download-card data-size="20.43 KB" href="/apps-plugin/docs/wiki-downloads/NSzEwLseGiuFe8kCDqXcZdCInme-02.bin" download="DoubaoSecret.java">DoubaoSecret.java</a>

Python

<a data-download-card data-size="13.66 KB" href="/apps-plugin/docs/wiki-downloads/NSzEwLseGiuFe8kCDqXcZdCInme-03.bin" download="doubao_secret.py">doubao\_secret.py</a>

## 证书申请与配置

开发者生成 ECC P-256 私钥和 CSR：

```bash
openssl ecparam -genkey -name prime256v1 -noout -out dev.key
openssl req -new -key dev.key -out dev.csr \
  -subj "/CN=XXXXX/O=XXXXX"

```

随后：

1. 将 `dev.csr` 提交到开发者平台，申请开发者证书；
2. 下载并保存平台签发的开发者证书；
3. 从开发者平台获取平台证书，用于回调验签；
4. 在服务端安全保存 `dev.key`，并分别维护开发者证书和平台证书；
5. 启动时检查 `dev.key`、`dev.csr` 和开发者证书中的公钥一致。

查看证书序列号和有效期：

```bash
openssl x509 -in ./app.pem -noout -serial -dates -subject -issuer

```

检查私钥、CSR、证书公钥是否一致时，可以分别导出公钥后计算摘要：

```bash
openssl pkey -in dev.key -pubout -outform DER | openssl sha256
openssl req -in dev.csr -pubkey -noout | openssl pkey -pubin -outform DER | openssl sha256
openssl x509 -in app.pem -pubkey -noout | openssl pkey -pubin -outform DER | openssl sha256

```

三条命令输出的摘要应一致。

### 平台操作位置

![开发者平台证书管理界面，展示平台证书和应用证书的用途与操作入口](//lf-flow-web-cdn.doubao.com/obj/flow-doubao/goofy_deploy_edenx/flow/doubao-apps--plugin-doc/static/image/NSzEwLseGiuFe8kCDqXcZdCInme-02.1465093ff1.png)
<!-- lark-image-display-size width="1642" height="632" -->

开发者证书上传的是 CSR 公钥申请材料，不是 `dev.key` 私钥；平台证书下载后用于验证平台回调签名。两个入口和两类证书不要混淆。

## 证书轮换

- 签名时使用当前有效的开发者证书，并在授权串中填写它的序列号；
- 回调验签时根据平台传入的 `cert_serial` 精确选择平台证书；
- 轮换窗口内允许受信任的新旧证书同时存在；
- 未认识的证书序列号必须拒绝，不能回退为“拿任意一张证书都试一遍”；
- 新证书生效前，确认新私钥、CSR、证书、环境和 AppID 属于同一套配置；
- 旧证书下线前，确认不再有使用旧序列号的在途请求或回调。

## 常见错误

| 现象             | 优先检查                                                                  |
| -------------- | --------------------------------------------------------------------- |
| 平台提示开发者签名失败    | 私钥与开发者证书是否匹配；`cert_serial` 是否误填平台证书序列号；`data` 是否被前端重新序列化              |
| 开发者回调验签失败      | 是否使用平台证书；是否保留原始 Body；method、path、query 是否与实际请求一致                      |
| 部分签名成功、部分失败    | 是否删除 Base64URL 的 `=` padding；是否错误假设 DER 签名长度固定                        |
| 本地验签成功、平台验签失败  | 实际发送的 Body、Path、Query、timestamp、nonce 是否与本地签名输入完全一致                   |
| 手机号接口返回成功但解密失败 | CSR 与 `dev.key` 是否配对；是否混用了测试和正式环境；TLV、Base64URL、ECDH、AES-GCM 解码顺序是否正确 |
| 回调被重复处理        | 是否在验签后按事件/订单做幂等；nonce 防重放是否使用多实例共享存储                                  |

## 上线检查

- 开发者私钥只存在于业务服务端的 KMS、HSM、密钥管理系统或受控加密存储中；
- 前端、Manifest、运行态 Skill、代码仓库和日志中没有私钥；
- 开发者私钥、CSR、开发者证书公钥三者匹配；
- 开发者证书与平台证书分别存储、按序列号索引，没有混用；
- `requestOrder` 的 `data` 与 `dbAuthorization` 由业务服务端成对生成，前端原样透传；
- 所有平台回调都先用平台证书验签，再解析 Body 和更新业务；
- 手机号密文只在业务服务端使用开发者私钥解密，明文不进入普通日志；
- timestamp、nonce、防重放、证书有效期和轮换策略已实现；
- 单元测试覆盖 Body 篡改、错误证书、过期时间、重复 nonce、DER/Base64URL 编码错误和 CSR/私钥不匹配。

生产日志不要记录私钥、完整 canonical request、完整 Body、完整 Signature、完整 Authorization 或手机号。建议只记录脱敏业务单号、`cert_serial`、Body Hash、签名长度、是否包含 padding、验签阶段和平台 `log_id`。
