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

API 密钥轮换:创建、设置、测试、完成

如何在不停机的情况下轮换 API 密钥:创建、设置、测试、完成的模式,NIST 给出的轮换周期,密钥管理服务,以及 Chaingateway 的具体做法。并说明 Webhook 密钥与钱包密码的轮换方法,以及怀疑泄露时应立即轮换。

章节
C
Chaingateway Team
区块链专家

审核: Maurice Sobiera

旋转的 API 凭证等轴插图

API 密钥轮换是指按计划或在密钥暴露之后,用一个新密钥替换正在使用的密钥,然后停用旧密钥。可靠的模式包括四个步骤:创建、设置、测试、完成。一段短暂的重叠期让两个密钥同时有效,因此正在进行中的请求不会失败。NIST 和 OWASP 都建议将其自动化。

为什么应该轮换 API 密钥?

轮换可以缩短泄露的密钥对攻击者有用的时间。每一个 API 密钥都是一项持续存在的风险。密钥可能通过被提交的 .env 文件、被攻陷的 CI 运行器或前员工的笔记本电脑泄露。密钥的有效期越长,泄露的风险就持续得越久。

OWASP 在其 非人类身份十大风险中将这一风险列为 NHI7,即长期有效的密钥。它描述的是有效期极长甚至没有有效期的 API 密钥和令牌。它称这类密钥极为常见,因为轮换很困难,而且并非总有短期有效的替代方案。

对以下凭证,轮换最为重要:

  • 权限范围很广的密钥,例如管理员、计费或生产数据写入权限。
  • 在多个服务或团队之间共享的凭证。
  • 嵌入客户端代码、移动应用或第三方集成中的任何内容。
  • 曾经出现在公开仓库中的令牌,即使只是短暂出现。

如果可以,请用来自 OAuth 或工作负载身份系统的短期令牌替换静态密钥。能够自行过期的凭证不需要轮换任务。

应多久轮换一次 API 密钥?

NIST 给出了一个具体的数字,并且它适用于签名密钥。NIST IR 8587 指出,对于高影响系统,签名密钥的最长活跃使用期限不应超过 90 天。对于中等和低影响系统,可以采用更长的期限,但应少于一年。该报告还建议记录加密周期,并采用自动化轮换。

NIST 没有为普通 API 密钥给出间隔。下表中的数值是我们的建议,依据是该报告中基于风险的方法。它们并非 NIST 的要求。

凭证建议的最长使用期限理由
高影响系统的签名密钥90 天(NIST)影响范围最大
服务之间的 API 密钥30 至 90 天取决于权限范围
CI/CD 令牌30 天通常具有部署权限
面向用户的 API 密钥90 天,并在怀疑泄露后立即轮换副本很多

建议加密周期的柱状图:签名密钥最长 90 天,服务间密钥 30 至 90 天,CI/CD 令牌最长 30 天,面向用户的 API 密钥 90 天

表格背后的规则很简单:泄露的凭证可能造成的损害越大,其可用期限就应越短。对于少数几个密钥,每 30 天手动轮换一次是现实的。若服务多达几十个,则需要自动化。NIST 也强调了同样的观点。更短的加密周期会促使组织实现轮换自动化,并定期演练密钥切换。

应在哪里存储 API 密钥?

将密钥存放在能够为密钥做版本管理、运行轮换钩子、限定访问范围并记录每一次读取的密钥管理服务中。电子表格和共享的 .env 文件无法做到这些。在选择之前,请检查以下四项能力:

  • 版本管理,使当前密钥和上一个密钥可以同时存在。
  • 轮换钩子,能按计划或事件触发轮换函数。
  • 访问范围限定,使轮换代理无法读取每一个密钥。
  • 审计日志,记录谁访问或轮换了哪个密钥。

AWS Secrets Manager 通过轮换函数支持定时轮换。HashiCorp Vault 可以签发会自行过期的动态密钥。与 IAM 角色绑定的云原生密钥管理服务也承担相同的角色。

在架构允许的情况下,尽量不要使用静态密钥。OWASP 建议尽可能使用动态密钥,因为它们减少了凭证被重复使用的机会。来自 AWS STS 的临时凭证,或 Azure 和 Google Cloud 上的托管身份,会在几分钟或几小时后过期,因此不会留下需要轮换的长期凭证。

创建、设置、测试、完成四步分别是什么?

这四个步骤是 OWASP 速查表为无服务器轮换函数所描述的模式。它们适用于任何密钥管理服务或自定义脚本。

  1. 创建:在不改动正在使用的版本的前提下,生成一个新的密钥版本。
  2. 设置:将新凭证推送到依赖它的服务或配置存储中。
  3. 测试:运行集成检查,证明新密钥能够通过身份验证。
  4. 完成:将新密钥提升为活跃密钥,并撤销旧密钥或安排其删除。

团队常常忽略的步骤,是“设置”与“完成”之间的重叠期。NIST 将其描述为对旧密钥和新密钥的重叠接受。轮换应在到期之前提前安排密钥切换,使接收方在一段时间内同时接受两个版本。重叠期的长短取决于您的系统。它必须长于最长的进行中请求,也必须长于您的客户端获取新值所需的时间,包括缓存的有效期。请先确定一个数值,然后在预发布环境中加以测试。

触发方式最适合权限模型
定时节奏可预测,例如 30 或 90 天轮换角色仅限于一个密钥路径
事件驱动发现泄露、员工离职权限提升但有时间限制,运行后即撤销
手动一次性审计、新服务接入人工审批加多因素认证

轮换代理应持有尽可能窄的权限:只对一个密钥具有写入权限,而不是更广的权限。

轮换检查清单应包含什么?

在将任何内容自动化之前,请逐一检查以下四点。

  1. 备份当前密钥,并测试回滚,使其不只是纸面上的理论。
  2. 构建集成测试,用真实端点验证新凭证。
  3. 创建一个只针对一个密钥的轮换角色。
  4. 把每一次轮换事件记录到审计日志中。

请留意三个反复出现的故障点。应用会把凭证缓存在内存中,在重启之前看不到新密钥。如果您在一批操作中轮换大量密钥,服务商可能会对创建密钥的端点进行速率限制。过时的客户端在重叠期结束后仍会继续使用已撤销的密钥。

应记录每次轮换由谁或什么触发、旧密钥和新密钥的脱敏版本、模式(定时、手动或紧急)以及结果。留意以下情况:某个密钥的请求量突然激增,来自该密钥从未使用过的 IP 地址或地区的调用,以及使用本应已过期密钥的请求。定期扫描代码仓库中的硬编码密钥,并维护一份清单,因为不在清单中的密钥永远不会被轮换。

如何轮换 Chaingateway 的凭证?

一个 Chaingateway 集成有三类密钥,每类的轮换方式各不相同。

API 令牌以 Bearer 令牌的形式为您的请求进行身份验证。您在账户面板的 API Tokens 下创建令牌,并为每个令牌命名。每个环境使用一个名称,例如开发、预发布和生产。轮换时,先创建新令牌,通过密钥管理服务部署,确认请求成功,然后停用旧令牌。为了限制泄露令牌的影响范围,可启用 IP 白名单(见下文),使只有您的服务器地址能够使用它。

Webhook 密钥(即个人密钥)通过 X-Signature 请求头为每个 Webhook 签名。Webhook 安全文档指出,新密钥会立即对 Webhook 通知生效。发送方无法同时运行两个密钥,因此重叠期必须设在您的接收端。请在一段短时间内同时用新密钥和旧密钥进行验证,然后再移除旧密钥。

import { createHmac, timingSafeEqual } from "node:crypto";
// Accept the new secret and, during rotation only, the previous one
const secrets = [process.env.WEBHOOK_SECRET, process.env.WEBHOOK_SECRET_PREVIOUS].filter(Boolean);
function signatureValid(txid, received) {
return secrets.some((secret) => {
const expected = createHmac("sha256", secret).update(txid).digest("base64");
return (
expected.length === received.length &&
timingSafeEqual(Buffer.from(expected), Buffer.from(received))
);
});
}

在切换期间被您的服务器拒绝的通知,会出现在失败通知列表中。Chaingateway 不会自动重试它们。请使用 GET /api/v2/{chain}/webhooks/notifications/failed 读取该列表,并通过 POST /api/v2/{chain}/webhooks/notifications/{id}/retry 重新发送每一条记录。Webhook 投递指南对此有更详细的说明。

钱包密码保护的是您使用密码创建的地址。您可以通过 POST /api/v2/ethereum/addresses/{address} 更改密码,该接口接收 old_password 和 new_password。其他链也有相同的路由。Chaingateway 不保存密码,因此在更改之前,请先把新密码保存到您的密钥管理服务中。丢失的密码无法恢复。

Chaingateway 的 IP 白名单有什么作用?

IP 白名单是一项账户设置,它把您的 API 密钥限制在您列出的服务器地址上。该功能于 2021 年 6 月 21 日发布。您在账户面板的设置中启用它,然后填入允许的地址。来自其他任何地址的请求都会被拒绝,即使密钥正确。因此,泄露的密钥在您没有列出的机器上毫无用处。

启用时请加入您自己服务器的地址,否则您自己的请求也会被拒绝。请列出服务器在互联网上使用的公网地址。10.0.0.0/8 和 192.168.0.0/16 等私有地址段由 RFC 1918 定义,永远不会作为请求的来源到达 API。如果服务器位于 NAT 网关之后,请列出网关的地址。这样,网关后面的所有机器都会被允许,而不只是一台。

白名单只针对您发送给 API 的请求。它不适用于 Webhook,因为 Webhook 是从 Chaingateway 发往您的端点的。请按上文所述,通过签名验证 Webhook。

白名单和轮换限制的是不同的东西。白名单限制被盗的密钥在哪里可用,轮换限制它在多长时间内可用。请两者并用。当服务器迁移到新地址时,请在迁移之前更新列表,以免您自己的流量被拒绝。

静态 API 密钥在什么时候不再合适?

对于低风险的内部工具,静态密钥是可以接受的。一旦您把 API 开放给外部合作伙伴,或处理财务数据,就应转向使用有效期较短的 OIDC 或基于 JWT 的身份验证。先从一个低流量的服务开始。确认您的轮换自动化在真实流量下运行正常,然后再扩大范围。一项被强制执行、而不仅仅是被建议的轮换策略,是安全团队能够做出的最有效的运营改进之一。

Chaingateway 首页截图,标题介绍用于加密支付和 Webhook 的统一区块链 API,并有一个开始 7 天免费试用的按钮

Chaingateway 通过一个 REST API 和一个身份验证层覆盖 Ethereum、Bitcoin、Tron、Solana、Polygon、BNB Smart Chain 和 Arbitrum,因此您无需为每条链分别管理凭证的生命周期。Webhook 功能涵盖充值通知。价格页面上的套餐每月 49 欧元起,7 天免费试用无需银行卡。

来源

常见问题

轮换 API 密钥是什么意思?

轮换 API 密钥是指生成一个新凭证来替换正在使用的凭证,并在所有依赖它的系统都切换之后,停用旧凭证。如果做得正确,它会作为一个自动化的创建、设置、测试、完成周期运行,并包含一段两个密钥都有效的短暂重叠期。

API 密钥应多久轮换一次?

这取决于风险。NIST IR 8587 指出,高影响系统的签名密钥不应持续活跃使用超过 90 天。对于普通的 API 密钥,它没有给出具体数字,因此应根据密钥的权限范围来选择间隔。对于 CI/CD 令牌和任何具有广泛访问权限的凭证,间隔越短越好。

为什么 API 密钥需要轮换?

轮换可以限制泄露或被盗凭证造成的损害,因为它缩短了密钥有效的时间。OWASP 在其非人类身份十大风险中将长期有效的密钥列为 NHI7。

轮换 API 密钥的最佳实践是什么?

使用密钥管理服务将流程自动化,遵循创建、设置、测试、完成的模式,并保留一段新旧密钥都有效的过渡期。这样就能避免同时切换所有依赖服务所带来的停机。

Chaingateway 是否支持 Webhook 的安全密钥处理?

支持。Chaingateway 通过 X-Signature 请求头以 HMAC-SHA256 为 Webhook 签名,因此您可以验证其真实性。如果更改个人密钥,新密钥会立即生效,因此您的接收端应在短时间内同时接受两个密钥。

推荐阅读

由 BabyLoveGrowth 创建以构建反向链接

我们如何撰写这些文章

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

C
Chaingateway Team
区块链专家

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