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, and this page is available as Markdown at /apps-plugin/docs/backend-development/certificate.md.

关于证书

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

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

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

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

一图看懂

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

数据方向发送方做什么接收方做什么使用哪套材料场景举例
① 开发者 → 平台:签名认证开发者用开发者私钥加签平台用开发者证书公钥验签开发者私钥、开发者证书、开发者证书序列号例如: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。前端只能原样透传这两个值。

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

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

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 的平台回调。
平台使用平台私钥对回调签名
  → 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,再解出业务明文。
平台:开发者公钥 + 临时私钥 → 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 规则:

HTTP_METHOD
REQUEST_PATH
CANONICAL_QUERY
BODY_SHA256_HEX
TIMESTAMP
NONCE

等价拼接方式:

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

sign.go13.09 KB

Java

DoubaoSecret.java20.43 KB

Python

doubao_secret.py13.66 KB

证书申请与配置

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

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 和开发者证书中的公钥一致。

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

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

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

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

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

平台操作位置

开发者平台证书管理界面,展示平台证书和应用证书的用途与操作入口

开发者证书上传的是 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。