← 博客
10 分钟阅读
|
发布于
|
更新于

如何使用个人密钥校验 Webhook 签名

为个人密钥设置一个值后,Chaingateway 会以 X-Signature 请求头对每个 Webhook 签名。本文说明 HMAC 的工作原理、Node.js 校验示例、如何测试处理程序、如何轮换密钥,以及签名不覆盖哪些内容。

章节
C
Chaingateway Team
区块链专家

审核: Maurice Sobiera

个人密钥是您在 Chaingateway 个人资料中设置的密钥。设置后,每个 Webhook 都会带上 X-Signature 请求头,其值为交易 ID 的 HMAC-SHA256 签名,并经 Base64 编码。服务器重新计算并比对该值,即可确认请求来自 Chaingateway。

为什么 Webhook 需要签名?

Webhook 接收端是一个公开 URL,任何知道它的人都可以向其发送请求。如果不做校验,伪造的“已收到付款”请求就可能让商品放行或让账户入账。共享密钥可以解决这个问题。只有 Chaingateway 和您的服务器知道该密钥,因此只有它们能生成匹配的签名。该构造是 HMAC,由 RFC 2104 定义:一种哈希函数与密钥的组合。

如何设置个人密钥?

在控制台中打开个人资料设置,找到 Webhook 个人密钥卡片,然后点击“Set Personal Secret”。如需替换现有密钥,请点击“Regenerate Secret”。文档中有两点细节值得注意:

  • 首次设置密钥后,所有发出的 Webhook 都会启用 X-Signature 请求头。在依赖它之前,请确保您的服务器能够接收并校验该请求头。
  • 重新生成的密钥会立即生效。请在点击之前或同时更新您的处理程序,否则有效通知将无法通过校验。

签名是如何生成的?

文档中的步骤分为三步。从 Webhook 负载中读取 txid 字段。以您的个人密钥为密钥、以 txid 字符串为消息,计算 HMAC-SHA256。将结果进行 Base64 编码,并与请求头比对。负载示例如下(来自 Webhook 指南):

{
"id": "9d18457f-c71c-4be4-ae7c-ce04e48359ed",
"webhook_id": "9ced86a9-b8d9-4bc2-bbd8-5ffe5b456bc8",
"from": "TTd9qHyjqiUkfTxe3gotbuTMpjU8LEbpkN",
"to": "DScWVXehzWdV2YS8fA2ryNsiHpKiLgAxM",
"blocknumber": "65542464",
"type": "TRC20",
"contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
"txid": "18f52f2a55b94a6e3705de4abb18e95dfce79970f27b29450705c561e12b6988",
"amount": 108935
}

如何在服务器上校验签名?

根据 txid 重新计算 HMAC,并以恒定时间与请求头比对。下面的 Express 处理程序就是这样做的。它从环境变量读取密钥,拒绝缺失或长度错误的请求头,并且只对有效请求返回 200:

const crypto = require('crypto');
const express = require('express');
const app = express();
app.use(express.json());
function isValid(txid, received, secret) {
const expected = crypto.createHmac('sha256', secret).update(txid).digest('base64');
const a = Buffer.from(expected);
const b = Buffer.from(received || '');
// timingSafeEqual throws when lengths differ, so check first
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
app.post('/hooks/deposit', (req, res) => {
const ok = isValid(req.body.txid, req.get('X-Signature'), process.env.CG_PERSONAL_SECRET);
if (!ok) return res.sendStatus(401);
// process req.body.txid, deduplicate on it, then acknowledge
res.sendStatus(200);
});
app.listen(3000);

文档还提供了 Python、Java 和 PHP 版本。在 Python 中,比对时请使用 hmac.compare_digest。在 Node.js 中,crypto.timingSafeEqual 完成同样的工作。普通的 == 比对可能泄露时间信息。

如何测试处理程序?

自行计算签名,并向本地服务器发送一条模拟通知。下面的 openssl 命令会生成处理程序所期望的同一个 Base64 HMAC。请使用测试密钥,切勿使用真实密钥:

Terminal window
TXID=18f52f2a55b94a6e3705de4abb18e95dfce79970f27b29450705c561e12b6988
SIG=$(printf '%s' "$TXID" | openssl dgst -sha256 -hmac "test-secret" -binary | base64)
curl -i -X POST http://localhost:3000/hooks/deposit \
-H "Content-Type: application/json" \
-H "X-Signature: $SIG" \
-d "{\"txid\": \"$TXID\"}"

使用 CG_PERSONAL_SECRET=test-secret 启动服务器。请求将返回 200。如果修改密钥或签名中的一个字符,则返回 401。每次部署处理程序后都应重新运行此测试,重新生成真实密钥后也应再次运行。

签名不覆盖哪些内容?

签名只覆盖交易 ID,不包含其他内容。按照文档中的构造方式,只有 txid 会被纳入 HMAC。由此产生两点后果:

  • 有效的签名只能证明 Chaingateway 发送了该交易的通知,并不能证明正文中的 amount、to 或 contractaddress 未被更改。如果这些字段决定了付款,请将它们与链上数据或订单的预期值进行核对。
  • 同一笔交易可能被多次送达,例如您要求重发失败的通知之后。每份副本都带有相同的有效签名。请以 txid 去重。

Webhook 不会自动重试。失败的通知按链列出,您需要为每条通知请求重发。Solana 没有 Webhook。在有 Webhook 的链上,签名方式完全相同。

如何在不丢失通知的情况下轮换密钥?

重新生成的密钥会立即生效,因此步骤的顺序很重要。让处理程序在短时间内同时接受两个密钥,然后再重新生成:

  1. 部署一个处理程序版本:先尝试当前密钥;如果校验失败,再尝试第二个可选的 CG_PERSONAL_SECRET_NEXT。
  2. 在个人资料中重新生成密钥,并复制新值。
  3. 将新值写入 CG_PERSONAL_SECRET_NEXT,然后重新部署。
  4. 在测试网上发起一笔测试转账,并确认处理程序能够接受它。
  5. 一天之后,将新密钥提升为 CG_PERSONAL_SECRET,并删除旧密钥。

文档没有说明轮换之后,重发的通知由哪个密钥签名。请在失败通知列表清空之前,保持双密钥的过渡期。

未设置密钥时会发生什么?

此时,Webhook 会在不带 X-Signature 请求头的情况下发送。您的处理程序不得将缺失的请求头视为有效。请按环境分别决定:在生产环境中,设置密钥后拒绝没有签名的请求;在本地测试环境中,可以允许这类请求。该请求头也是判断密钥是否生效的方式:如果通知中没有它,说明您的账户没有设置密钥。

完整参考资料在哪里?

Webhook 安全指南列出了上述步骤,并提供四种语言的代码。Webhook 指南则说明如何创建 Webhook 和接收端。

我们如何撰写这些文章

准备好自己动手构建了吗? 获取你的 API key — 7 天试用,无需信用卡 — 或查看 区块链 API 获取完整的 endpoint 参考。

C
Chaingateway Team
区块链专家

Chaingateway 团队致力于为全球开发者简化区块链集成。