消息
品牌在前,验证码在后,此外没有其他要紧内容:ACME: your code is 493 201. It expires in 10 minutes.(意为“ACME:您的验证码是 493 201,10 分钟后过期。”)把验证码放在靠前位置,使其显示在通知预览中,并将文本控制在一个 160 个字符的 GSM-7 分段内。从设计文档中粘贴进来的一个弯撇号,就会把整条消息切换为 Unicode,而 Unicode 一个分段只能容纳 70 个字符。API 从不改写文本,因此模板必须在上线前清理干净;编码指南列出了常见的罪魁祸首。不要包含链接:运营商对带链接验证码的过滤力度高于任何其他模式。
品牌之所以要写进正文,是因为不能指望发件人字段显示品牌。在美洲和中国,本地号码会取代任何名称;在要求注册的地方,获批前会使用共享数字发件人;如果运营商拒绝某个名称,该条消息会回退到数字发件人。发件人 ID 规则解释了这三种情况。字母数字发件人是单向的,因此绝不要让用户回复验证码。
有两项补充值得占用字符。说明验证码的用途,例如用于登录或用于确认新设备,并加上切勿向任何人透露此验证码:两者都能帮助用户察觉有人正试图在通话中骗取验证码。如果你的网页登录使用自动填充,请在消息末尾加上一行,例如 @example.com #493201;Safari 和 Android 版 Chrome 能识别这种绑定域名的格式,并且只会在该域名上提供验证码。通过 SMS Retriever API 读取验证码的 Android 应用,则需要在消息中改为加入 11 个字符的应用哈希。
验证码长度与格式
六位数字是常见选择,算一算就知道原因。六位数字共有 1,000,000 种组合;如果验证码在输错五次后作废,攻击者对每个验证码的猜中概率为 5/1,000,000,即 1/200,000。四位数字只有 10,000 种组合,同样猜五次,猜中概率为 1/2,000。八位数字增加了输入负担,收益却很小。
- 只用数字。这样会弹出数字键盘,也不会把 O 和 0 混淆。
- 使用安全的随机源,绝不要使用通用随机源。
- 存为文本,而非数字。如果存为整数,042817 会变成 42817,正确的输入反而会验证失败。
- 存储带密钥的哈希,而不是验证码本身;以恒定时间比较,并绑定到一个号码和一种用途。
- 加一个空格便于阅读,例如 493 201,能帮助手动输入验证码的用户;如果依赖自动填充,请在真机上测试确切格式。
# Python;Node 中可用:crypto.randomInt(0, 1000000).toString().padStart(6, "0")
import secrets
code = f"{secrets.randbelow(1_000_000):06d}" # "042817" 会保留开头的零有效期
验证码的寿命以分钟计,通常为五到十分钟。请把消息的 validity(以分钟为单位)设为相同的寿命,而不要保留默认值 2,880(即 48 小时)。手机关机或不在服务区时,网络会持续重试,直到有效期结束:设为 10 分钟,消息最终显示为已过期;设为 48 小时,消息可能在第二天早上才到达,带着一个已经失效的验证码。过期后才送达的验证码,就是一张客服工单。
所有地方使用同一个数字:服务器端的过期时间、validity 字段和正文中的说法。如果正文写十分钟,而服务器只在五分钟内接受验证码,那么用了七分钟的用户就会无辜失败。
API 设置
向 POST /v1/messages 发送的验证码请求,除号码和文本外,还需要几项设置:
POST /v1/messages
Authorization: Bearer sk_live_...
Idempotency-Key: verify-8812-attempt-2
Content-Type: application/json
{
"to": "+447700900123",
"from": "ACME",
"text": "ACME: your code is 493201. It expires in 10 minutes. Never share this code.",
"validity": 10,
"window": { "quiet_hours": "bypass" },
"campaign": "otp-login",
"reference": "verify-8812"
}quiet_hours: bypass将流量标记为事务性,使其在任何时间都能发出。只对验证码使用:标记为事务性的推广内容会被视为滥用。详见绕过免打扰时段。Idempotency-Key由验证记录和尝试次数构成,这样你这边因网络问题重试时,会返回原始结果,而不会再发送一个验证码。有意的重发属于新的尝试,应使用新的幂等密钥。campaign在报告中将验证码流量归组;reference会在响应和 Webhook 中原样返回,送达事件正是借此找到对应的验证记录。
检查响应中的 encoding 和 segments:如果验证码模板返回 ucs2 或两个分段,说明其中混入了异常字符。为验证码服务单独配置一个只有发送权限的密钥;每秒 50 个请求的限制按密钥计算,因此另一个密钥上的群发任务不会耗尽验证码所需的额度。集成测试应使用测试密钥:它会像正式密钥一样验证、计价和响应,并触发签名 Webhook,但不会发送任何消息,也不会产生任何费用。
重发时机
允许用户在 30 秒后请求新验证码,之后依次为 60 秒、120 秒,并显示倒计时。签发新验证码时令上一个失效,只接受最新的验证码;同时限制总数:对真实用户来说,每个号码每小时三到四个验证码已经足够。显示验证码发往的号码(部分遮盖),并在重发按钮旁提供修改号码的入口。号码输错导致收不到验证码,重发多少次都无法解决。
在提供下一次尝试之前,先读取状态。已拒绝的消息在发送前就被拒绝,从未计费;如果错误与号码有关,请让用户重新输入号码。原因为未知号码的 message.failed 事件也是同样的含义:请提示用户检查号码,而不是再提供重发。对于只返回运营商确认的目的地,有已发送而无已送达并不代表失败;国家或地区页面会说明哪些目的地属于这种情况。接收这些事件的处理程序,在生产环境中的 Webhook 中有详细介绍。
SMS 未送达时
每个目的地只有一条路由,按实测送达效果选定,因此第二条 SMS 会走与第一条相同的路径。如果第一条因临时问题丢失,这会有帮助;如果手机关机、正在拒收该消息的网络上漫游,或者号码有误,就无济于事。从第二个验证码起,请在重发按钮旁提供另一种渠道;如果出现重发无法解决的失败,则直接切换到该渠道:
- 电子邮件,发送到账户中已验证的地址。
- 身份验证器应用或通行密钥,在开通时提供,以便在 SMS 失败之前就已设置好。
- 语音电话播报验证码,通过你所用的语音服务商拨打。
- 备用码,在注册时发放,用于找回账户。
对后备渠道施加与 SMS 相同的限制:未加保护的语音后备渠道,同样可能以完全相同的方式被滥用。
速率限制与 SMS 泵送
没有限制的验证码端点,就是一个花掉你余额的途径。这种攻击有多个名称(SMS 泵送、话费欺诈、人为虚增流量):脚本为成千上万个号码请求验证码,这些号码所在的号段中,链条上的某一方能从终接费用中分成。每个号码都有效,因此每条消息都会发送并计费;只有发送前被拒绝的消息,即已拒绝的消息,不产生费用。按电话号码限制无法阻止这种攻击,因为每个请求使用的号码都不同。预付余额能为损失设定上限,但这个上限就是全部余额,包括明天的群发任务所需的部分。
| 限制维度 | 参考起点 | 能阻止什么 |
|---|---|---|
| 每个电话号码 | 每小时 4 个验证码,每天 10 个 | 循环请求,以及对同一个人的骚扰 |
| 每个 IP 地址 | 每小时 10 个验证码,因为移动网络会共享地址 | 简单脚本 |
| 每个账户或会话 | 每小时 5 个验证码 | 来自已登录会话的滥用 |
| 每个国家和号段 | 略高于你正常峰值的每小时上限 | 分散到大量号码上的泵送 |
| 全局 | 一旦触及就呼叫值班人员的每小时支出上限 | 其他限制遗漏的一切 |
根据自己的流量调整这些数值;结构比具体数字更重要。然后加上低成本的防御:在调用 API 之前拒绝你不提供服务的目的地;第二次请求后要求通过人机验证;在你这边校验号码格式;无论号码是否已有账户,都以相同方式响应,使端点无法被用来探测哪些号码已注册。预警信号包括:发往你很少服务的国家的突发流量、号码连续或共享很长的前缀,以及验证码发出后几乎从未被输入。
衡量什么
按目的地衡量从验证码发出到验证码输入的转化。它是比任何回执都更好的送达指标,因为它同时涵盖手机、通知和用户;在只返回运营商确认的目的地,它是你唯一的端到端信号。通过 reference 将验证记录与消息事件关联起来,然后跟踪:
- 转化:按目的地和尝试次数统计,即收到第一个验证码后输入、收到第二个后输入,还是从未输入。
- 验证耗时:从请求到正确输入,要关注最慢的十分之一,而不只是中位数。
- 重发率:某个目的地的重发率上升,值得单独设置告警。
- 每位已验证用户的成本:支出除以完成的验证次数。
假设某个目的地一周发送 2,000 个验证码,支出 60,有 1,500 人完成验证:转化率为 75%,每位已验证用户的成本为 0.04。转化率比其他目的地低十个百分点的目的地,应检查其发件人规则和失败原因;如果在流量攀升的同时转化率骤降,在得到相反证据之前,都应视为泵送攻击。CSV 或 JSON 导出文件包含每条消息的消息 ID、状态、运营商代码、时间戳和价格,保留 90 天。另请参阅 OTP 验证使用场景。
有内容不清楚或已经过时?请在支持页面告诉我们;修正内容会更新到指南中,同时更新修订日期。
