可公开密钥和私钥：保护客户端免受验证数据的影响。
Charles Archibong, 联合创始人
将可发布密钥放在您的应用程序中，并将私钥保存在您的服务器上。可发布密钥可以启动验证并读取最少的状态信息，但绝不会读取身份数据，因此请做好密钥泄露的准备，并尽可能降低泄露造成的损失。
要点
- 可发布的密钥随客户端一起发布，可以启动验证并读取最少的状态，但绝不会读取身份数据。
- 密钥可以读取完整结果、捕获的媒体和每个风险情报端点，因此它们会保留在您的服务器上。
- 假设所有客户端密钥都将被提取，并将其限制在您的 Web 源中，即在浏览器中运行的源。
- 撤销密钥会在下次请求时生效，因此轮换密钥时应先创建替代密钥。
Toden 给你两种 API 密钥，使用规则很简单：可发布的密钥（pk_）放在你的网页或移动应用程序中，以及密钥（sk_密钥永远不会离开您的服务器。可发布密钥可以启动验证并读取最基本的状态信息，但无法读取姓名、出生日期、身份证号码或自拍照等信息。而私钥则可以读取所有这些信息。
为了限制密钥泄露，您可以使用三种方法：密钥白名单（对于可发布密钥，白名单包含 Web 源；对于私钥，白名单包含 IP 地址或 IP 地址范围）、针对每个服务的密钥（这样一次撤销不会导致所有服务瘫痪）以及立即撤销。本文的其余部分将解释密钥拆分的工作原理，以及如何在需要之前使用这些方法。
为什么需要验证 API 需要两种钥匙吗？
因为任何你输入到客户端的密钥最终都会被你意想不到的人读取。移动应用可以被反编译，网页包可以在开发者工具中打开。把客户端密钥当作秘密只是一种侥幸，而非真正的控制。
因此，该设计假定客户端密钥会泄露，并限制了其功能。下表摘自身份验证文档 （在新标签页中打开）。
钥匙 | 前缀 | 它居住的地方 | 它可以叫什么 |
|---|---|---|---|
可发布 |
| 你的前端或移动应用，在 SDK | 开始验证（ |
秘密 |
| 仅限您的后端 | 完整的验证结果和媒体资料，以及所有风险情报端点 |
密钥由其前缀加上 32 个随机字母数字字符组成，例如pk_test_aB3dE5fG7hJ9kL1mN3pQ5rS7tU9vW1xY前缀可以让人工审阅者一眼看出他们正在查看的范围和环境，这在日志或拉取请求中出现键时非常有用。
泄露的可公开密钥能做什么？
他们可以对您的帐户发起验证并轮询其最低状态。他们无法读取任何验证结果，无论是您的还是他们的，因为完整结果端点拒绝使用可发布的密钥。403 secret_key_required。
这是一个有意义的限制，但并非为零。在生产环境中，每次完成的验证都会从您的信用余额中扣除，具体情况请参阅环境文档 （在新标签页中打开）。如果将可发布的密钥复制到其他网站，则可能被用于运行您付费的验证。以下源地址允许列表旨在降低这种风险。
如果密钥泄露了，别人能做什么？
读取身份数据。密钥可以调用GET /api/kyc/verifications/:id完整结果（生物数据、明文ID号码、面部匹配）GET /api/kyc/verifications/:id/media/:kind它可用于拍摄自拍照、文档图像和活体视频。它还可以调用所有风险智能端点。
对待密钥应如同对待数据库密码一样。密钥泄露对贵组织而言属于数据泄露事件，贵组织应遵循自身的事件处理流程并承担相应的法律义务。不同司法管辖区的相关规定有所不同，本文仅提供一般信息，不构成法律建议。
在典型的集成中，每个键应该位于什么位置？
以下是一个常见的引导用户入门的应用程序界面：
该应用程序挂载了 Toden SDK 使用可发布的密钥。申请人完成同意、采集和活体检测，以及 SDK 提交验证信息。
该应用会显示“我们正在核实您的信息”屏幕。如果需要显示进度，它会使用可发布密钥轮询最小状态。
您的后端会收到已签名的 webhook 以进行验证。
您的后端使用密钥调用完整结果，更新客户记录，并决定应用程序接下来显示什么内容。
申请人的身份数据从设备传输到 Toden 以及来自 Toden 发送到您的服务器。它永远不需要返回到设备，而且在这种布局下也无法返回，因为设备上唯一的密钥不允许获取它。
一个常见的错误是，为了简化步骤 4，直接在应用程序中调用结果端点，仅仅为了显示成功页面。这样做需要在设备上设置密钥，完全违背了设计初衷。正确的做法是从后端向应用程序发送它所需的少量信息。
环境如何与密钥交互？
每个键都属于一个特定的环境，数据永远不会在不同环境之间交叉。pk_test_针对 Sandbox 和 a 的关键工作pk_live_密钥与生产环境冲突。密钥、验证、Webhook 端点和配置都仅限于一个环境。
在错误的位置使用密钥会返回403 environment_mismatch文档中给出的实用规则是，在整个流程中保持只有一个环境： SDK 's Sandbox 坐骑使用pk_test_密钥，读取这些结果的后端使用一个sk_test_钥匙。
生产密钥也取决于您的企业概况。直到您的组织完成业务验证（ KYB 如果获得批准，则生产验证和上传请求将被拒绝。business_not_approved沙盒模式贯穿始终。
如何防止密钥泄露？
在控制面板中，位于“开发者”下方 → API 每个键都可以携带一个允许列表。允许列表的类型取决于键的作用域，因为每个控件都在其作用域内工作。
钥匙 | 限制 | 它阻止了什么 | 它无法阻止的 |
|---|---|---|---|
可发布 | 允许的网站来源，例如 | 被盗的密钥在另一个网站上再次使用 | 发送的请求 |
秘密 | 允许的 IP 地址或 CIDR 范围，例如 | 被盗密钥在除您的服务器之外的任何地方被使用 | 您列出的范围内没有任何东西。 |
从这张表格中可以得出两点。
首先，源允许列表是浏览器的一个控件。对于 Web 集成来说，设置源允许列表是有意义的，但对于移动应用来说则没有任何作用，因为原生应用不会发送任何源地址。Origin对于移动端而言，泄露的可发布密钥的限制是其作用范围，而不是允许列表。
其次，IP地址白名单是控制密钥最有效的手段，而且如果你的后端服务器使用固定的出站地址，成本也很低。列出你服务器的公网出站IP地址。如果你的后端服务器运行在没有固定出站地址的基础设施上，那么在选择密钥存放位置之前，了解这一点非常重要。
空的允许列表意味着密钥可以从任何地方使用。将其留空是一种选择，因此请特意这样做。
钥匙漏水该怎么办？
请按顺序完成以下步骤：
在开发者选项中撤销密钥→ API 密钥。撤销是立即生效的：下次使用该密钥的请求将立即返回。
401。创建具有相同范围和环境的替代版本，并进行部署。对于移动应用中的可发布密钥，这意味着需要发布应用，因此步骤 1 和步骤 2 之间存在实际的差距。请提前做好规划。
检查您的审计跟踪。密钥的创建和撤销会发出……
api_key.created和api_key.revokedwebhook，这样您的安全工具就可以记录谁在何时更改了什么。对于私钥，请评估其暴露风险。确定密钥可能影响的范围和持续时间，并遵循您自身的事件处理流程。
如果密钥实际上并未泄露，并且您按计划轮换密钥，请反向执行步骤 1 和 2：先创建并部署新密钥，确认流量已转移，然后再撤销旧密钥。如果先撤销旧密钥，则会导致中间的所有请求中断。
哪些习惯能使爆炸半径变小？
每个服务或环境只能使用一个密钥。如果您的入职服务和报告作业共用一个密钥，撤销该密钥会导致两者都停止运行。使用不同的密钥则可以单独撤销其中一个。
创建密钥时，请将其存储在密钥管理器中。每个密钥仅显示一次。之后，控制面板只会显示密钥的前缀，因此无需后续复制任何内容。
密钥不应存放在代码仓库中。即使提交记录已被删除，提交到公共代码仓库的密钥也应被视为已泄露。
使用
_test_开发和持续集成中的关键点。储备_live_生产流量密钥。限制密钥管理权限。创建或撤销密钥需要……
api_keys:create权限。没有权限的成员只能看到密钥。
要适用的规则
在审核集成方案时，请针对密钥出现的每一个地方问自己一个问题：持有此设备或读取此软件包的人是否可能使用此密钥读取身份数据？如果答案是肯定的，并且这种情况发生在服务器之外的任何地方，那么无论其他方面多么正确，该设计都是错误的。
然后检查三件事：Web 发布密钥是否具有源地址允许列表；每个密钥是否具有 IP 地址允许列表（如果您的基础架构允许）；以及您的团队是否已演练过撤销和替换步骤。开发者文档涵盖了每个密钥可访问的端点，安全页面则涵盖了如何…… Toden 它自行处理数据。
参考来源
