关于证书
证书用于在开发者服务端与豆包平台之间建立可信通信。它主要解决两类问题:
- 签名与验签:证明请求是谁发出的,并发现请求内容是否被篡改;
- 加密与解密:让手机号等敏感数据只能被指定的开发者服务端读取。
先记住两条规则:私钥用于签名或解密,必须由私钥所有者保管;证书中的公钥用于验签或加密,可以提供给通信对方。
开发者证书和平台证书方向相反,不能混用。
cert_serial只是选择证书的索引,不是公钥或私钥。
一图看懂
这里先不绑定具体业务,按“数据从谁发给谁”拆成四条通用方向。判断使用哪张证书时,只需要先回答两个问题:谁发送数据?要解决身份可信,还是内容保密?
签名看发送方:谁发送,谁用自己的私钥签名;接收方用发送方证书中的公钥验签。
加密看接收方:要让谁能读取,就用谁的证书公钥加密;接收方再用自己的私钥解密。
是否需要签名或加密,必须以具体接口文档为准。第④种方向只在接口明确要求开发者加密上传数据时使用,不能因为持有平台证书就自行给普通 OpenAPI 请求加密。
证书与密钥分别是什么
证书不是私钥,也不会替代私钥执行签名或解密。开发者上传 CSR 后,平台签发的是开发者证书;dev.key 始终留在开发者自己的服务端。
1. 开发者证书:开发者加签,平台验签
适用场景
当前最典型的场景是前端支付 API requestOrder。业务服务端根据可信订单生成一份最终的 data 字符串,再使用开发者私钥生成与该 data 绑定的 dbAuthorization。前端只能原样透传这两个值。
这里的 dbAuthorization 与通用 X-DB-Authorization 使用相同的授权串格式,但它是 requestOrder 的 API 参数,不是前端自行构造的 HTTP Header:
开发者签名的作用:
- 证明预下单数据来自持有开发者私钥的业务服务端;
- 保护订单号、金额、商品、商户和回调地址等字段不被篡改;
- 通过 timestamp 和 nonce 限制过期请求并防止重放。
前端不能持有开发者私钥,也不能对
data执行JSON.parse后再次JSON.stringify。即使 JSON 语义相同,只要原始字节变化,验签也会失败。
2. 平台证书:平台加签,开发者验签
适用场景
平台向开发者服务端发送以下异步通知时,会使用平台私钥加签,并在 HTTP Header 中携带 X-DB-Authorization:
- 支付结果回调;
- 退款结果回调;
- 签约结果回调;
- 代扣支付结果回调;
- 其它接口文档明确要求验证
X-DB-Authorization的平台回调。
平台回调验签的作用:
- 确认请求确实来自豆包平台,而不是伪造回调;
- 确认回调路径、查询参数和原始 Body 未被篡改;
- 配合 timestamp 与 nonce 防止旧回调被重复利用。
平台证书只提供公钥。开发者不需要、也不可能获得平台私钥。不要用开发者私钥验证平台回调,也不要用开发者证书公钥代替平台证书公钥。
3. 开发者证书:平台加密,开发者解密
适用场景
当前典型场景是登录流程中,开发者服务端使用 phone_code 调用 get_user_phonenumber 获取加密手机号。平台不会直接返回手机号明文,而是使用开发者公钥加密后返回 encrypt_phone_number 或协议约定的 cipher_data。
该流程使用 ECIES 思路的混合加密:
- 平台生成随机
dataKey,使用 AES-256-GCM 加密手机号等业务数据; - 平台生成临时 P-256 密钥,通过 ECDH 与开发者公钥计算共享密钥;
- 平台对共享密钥做 SHA-256 得到 KEK,再用 KEK 加密
dataKey; - 平台将临时公钥、加密后的
dataKey和业务密文编码为cipher_data; - 开发者服务端使用配对的
dev.key完成 ECDH,解出dataKey,再解出业务明文。
加密传输的作用是保证:即使响应或日志被意外截获,没有开发者私钥也无法还原手机号。平台证书不参与该解密链路。
本地调试时,需要把与 dev.key 配对的 dev.csr 内容粘贴到 Web 调试器的“输入证书”框,让调试环境取得开发者公钥;业务服务端仍使用同一对密钥中的 dev.key 解密。CSR 与私钥不匹配时,接口可能成功返回密文,但服务端无法解密。
哪些场景不应使用证书
通用签名规则
开发者加签和平台回调验签使用相同的 canonical request 规则:
等价拼接方式:
实现时必须遵守:
- 算法为 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。
验签顺序必须是:
- 保留原始 method、path、query 和 Body 字节;
- 解析并校验 algorithm、version、
cert_serial、timestamp、nonce、signature; - 按
cert_serial精确选择证书并检查有效期; - 校验 timestamp 时间窗口,并使用共享的原子存储检查 nonce 是否重复;
- 重建 canonical request;
- 使用证书公钥执行 ECDSA DER 验签;
- 验签通过后才解析 Body 和处理业务。
加签验签代码 Demo
Go
Java
Python
证书申请与配置
开发者生成 ECC P-256 私钥和 CSR:
随后:
- 将
dev.csr提交到开发者平台,申请开发者证书; - 下载并保存平台签发的开发者证书;
- 从开发者平台获取平台证书,用于回调验签;
- 在服务端安全保存
dev.key,并分别维护开发者证书和平台证书; - 启动时检查
dev.key、dev.csr和开发者证书中的公钥一致。
查看证书序列号和有效期:
检查私钥、CSR、证书公钥是否一致时,可以分别导出公钥后计算摘要:
三条命令输出的摘要应一致。
平台操作位置

开发者证书上传的是 CSR 公钥申请材料,不是 dev.key 私钥;平台证书下载后用于验证平台回调签名。两个入口和两类证书不要混淆。
证书轮换
- 签名时使用当前有效的开发者证书,并在授权串中填写它的序列号;
- 回调验签时根据平台传入的
cert_serial精确选择平台证书; - 轮换窗口内允许受信任的新旧证书同时存在;
- 未认识的证书序列号必须拒绝,不能回退为“拿任意一张证书都试一遍”;
- 新证书生效前,确认新私钥、CSR、证书、环境和 AppID 属于同一套配置;
- 旧证书下线前,确认不再有使用旧序列号的在途请求或回调。
常见错误
上线检查
- 开发者私钥只存在于业务服务端的 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。