
Passkey 断言失败时往往悄无声息,而且几乎从来不是签名算错了。实际情况是断言的密码学部分完好无损,依赖方(relying party)却仍然拒收,因为前面有一道绑定校验先挂了:clientDataJSON 里的 challenge 不是你服务器签发的那个,origin 是你忘了加进白名单的预发布域名,或者 rpIdHash 属于另一个依赖方域名,与请求到达时用的域名对不上。这三个字段都是两层嵌套容器里的明文,正因如此,它们特别容易写错,从外面又特别难看出来。
容器结构本身就是专用解码器存在的理由。一条 WebAuthn 断言由三段各自 base64url 编码的数据组成,中间那段 authenticatorData 是裸二进制:定宽头部、一个塞了八种标志位的 flag 字节,外加 4 字节计数器。不拆开,什么都读不出来。本文逐字节走一遍结构,说明哪些 flag 位决定一条断言值不值得验,再复盘一次真实的调试过程:四个不同的缺陷,从服务器那侧看长得一模一样。
想直接拆一段真实数据,可以用 WebAuthn Passkey Assertion 解码与 Challenge 调试器:喂进一条完整断言,它会打印解码后的 authenticatorData、每个具名标志、各项绑定校验的结论,粘贴 COSE 公钥后还能给出签名验证结果。
断言到达时带着三段数据
WebAuthn 断言响应不是一个对象。它是个容器,里面三段载荷各自独立编码,解码方式各不相同:
- clientDataJSON:UTF-8 JSON,经 base64url 编码。承载
type、challenge、origin、crossOrigin与crossOriginIsolated。 - authenticatorData:裸二进制,经 base64url 编码。承载
rpIdHash、flag 字节、signCount,可选附带认证凭据数据与扩展。 - signature:ES256 与 RS256 是 DER 包装的 ASN.1,Ed25519 则是 64 字节原始数据。由认证器对你服务器必须精确重建的消息签名。
结果就是服务器没法“只验签名”。验证要求服务器先拼出认证器签的那串精确字节,而这串字节由注册时协商的 COSE 算法标识决定。ES256 是 authenticatorData || SHA-256(clientDataJSON)。RS256 同样是 authenticatorData || SHA-256(clientDataJSON) 的哈希摘要,外面套 PKCS#1 v1.5 填充。Ed25519 就不一样了,这也是几乎所有首次实现都会踩的坑:签名消息是 authenticatorData || clientDataJSON,JSON 在 Ed25519 算法内部完成哈希,不是服务器先算好摘要。多算一次 SHA-256,密钥完全正确也会验证失败。
因为 JSON 一种情况先哈希、另一种不哈希,“同一条断言、同一把密钥、换一个验证器”就可能给出不同结论。如果你只在 Ed25519 凭据上遇到过 100% 的签名失败,原因就在这里。
解析 JSON 这层不难,但载荷一长,手工做就很琐碎。Base64URL 编解码处理传输编码,JWT 解码器能干净地拆开 base64url 加 JSON 这一层,凡是长得像签名令牌的东西都适用。
逐字节拆开 authenticatorData
authenticatorData 在可选数据之前有一个固定 37 字节的头部。这 37 字节长度不变,是整条断言里唯一可以拿尺子量的部分:

- rpIdHash,32 字节。依赖方 ID 的
SHA-256,通常就是可注册域名。凭据靠它绑定到域名。 - flags,1 字节。八个具名标志位,下一节展开。
- signCount,4 字节,大端无符号。由认证器维护的单调递增计数器。
- attestedCredentialData,变长,只在 AT 标志置位时出现。注册时紧跟在后面,断言时通常没有。
- extensions,变长 CBOR map。只在扩展数据标志置位时出现。
先查 rpIdHash 是值得的,因为这是服务器自己能算的字段。把预期的 RP ID 自己哈希一遍,再比对。两者不一致,后面每一步都没有意义;而原因通常根本不是密码学缺陷,是 RP ID 被配成了带协议和端口的完整 origin,它却必须是裸域名。
signCount 值得单独说一句:它是 32 位值,会回绕。大约 42.9 亿次操作之后计数器往回跳一个小负值,那是算术,不是攻击。硬件令牌这类认证器在固件升级后归零是另一回事;WebAuthn 自己的建议是,已注册凭据出现计数器回退,属于应当标红、而不是默默接受的强信号。
解码 flags 字节
偏移 32 处的那一个字节,决定后面整段数据里你还能信多少。把它当普通整数读,是最常见的解码错误:

- Bit 0(0x01)UP:用户在场。用户碰过认证器。任何值得验证的断言都会置这一位。
- Bit 1(0x02)UV:用户已验证。本地生物识别或 PIN 校验通过。所有主流消费级部署都强烈建议要求它。
- Bit 2(0x04)BE:可备份。凭据能同步到备份。
- Bit 3(0x08)BS:备份状态。凭据当前处于已备份状态。
- Bit 4(0x10)RFU1:保留位。服务器要从里面读出含义,读到的只是噪声。
- Bit 5(0x20)AT:附带认证凭据数据。注册时置位,断言时通常清零。
- Bit 6(0x40)ED:附带扩展数据。这一位清零,就没有扩展,数据块到此结束。
- Bit 7(0x80)MF:多因素,由扩展推导的提示位。在较早的修订版里不是核心位。
实际判断很简单:UP 没置位就拒收,没有用户在场的断言不构成认证。纯 passkey 流程里,UV 清零按策略失败处理。ED 清零时,别把尾部字节当 CBOR 扩展 map 去解析,你只会读到空,或者凭空造出一层结构。
注册阶段的断言正好相反。那里 AT 置位,signCount 之后的字节就是认证凭据数据:16 字节凭据 ID、2 字节凭据公钥长度、COSE 公钥本体,以及可选的扩展块。解析器如果在注册数据上按 37 字节头部处理到这就停,凭据 ID 会无声无息地丢掉。
绑定校验:challenge、origin、rpIdHash
这四项校验决定了 passkey 流程是能跑通,还是给支持团队添工单。生产环境里失败的也是这四项。

- 1. challenge:
clientDataJSON里的值必须等于服务器签发的那个,逐字节比对。这是防重放的一环,被偷走的断言一旦 challenge 已被消费就毫无价值。 - 2. origin:必须与服务器白名单里的条目完全一致。协议、主机、端口都算。
https对http是不匹配,末尾多个斜杠是不匹配,预览部署的临时主机名也是不匹配。 - 3. rpIdHash:必须等于服务器端算出的、预期 RP ID 的
SHA-256。 - 4. type:登录断言必须是
webauthn.get,注册必须是webauthn.create。两个端点之间若出现 type 交叉,说明存在混淆代理的路径。
这四项里任何一项失败,客户端看到的都是同一个结果:登录按钮转圈,然后报一个笼统的失败。所以它们必须按顺序检查,并在日志里分开报告。实际最常见的是 origin,白名单照着生产域名写,从没扩到预发布主机;当负载均衡复制了会话状态、却没复制一次性 challenge 存储时,最常见的就变成 challenge:第二个节点找不到本该拿来比对的值。
紧挨着这一整套流程之前的那一步,PKCE Code Verifier 与 Challenge 生成器覆盖 passkey 相邻登录里的授权请求部分,OAuth 2.0 / OIDC 授权码 + PKCE 流程可视化则展示 WebAuthn 认证仪式在整个流程里被调用的位置。
签名验证与 COSE 公钥
要验证,服务器需要凭据公钥的 COSE 形式,也就是注册时认证器返回的那个 CBOR 结构。相关标签是 1 表示密钥类型,3 表示算法,-1 表示曲线:
- 标签 1(kty):
2是椭圆曲线密钥,1是 RSA 密钥。 - 标签 3(alg):协商出的算法,通常是
-7(ES256)、-257(RS256)、-8(Ed25519)。 - 标签 -1(crv):具名曲线,
1是 P-256。 - 标签 -2(x)与标签 -3(y):EC2 密钥的未压缩公钥坐标。
- 标签 -1 / 标签 -2(n, e):RSA 密钥的模数与指数。
公钥是 CBOR,所以务实的做法是先按 CBOR 解码,确认算法标签与客户端协商的一致,再把坐标交给加密库。注册算法与验证算法不一致是真正常见的 bug,而它产生的拒绝和其他所有原因一模一样。CBOR转换器负责拆这一步;如果你用的库不收 COSE,需要同一份密钥材料的 JWK 形式,JWK 生成与解析器正合适。
两个验证细节值得记住。第一,DER 签名是严格编码的,宽松解析之后才通过的签名,说明你技术栈的某处过于宽松。第二,Ed25519 的消息是 authenticatorData || clientDataJSON,没有外部哈希,那 64 字节原始签名也根本不是 ASN.1。把它塞给 DER 解析器,得到的错误只会让人更糊涂,而不是更明白。
一次实操调试
这是一个很典型的故障形态。客户端发来一条断言,服务器日志写下 verification failed,响应体里没有有用信息:
- clientDataJSON:JSON 的 base64url,含
type、challenge、origin、crossOrigin。 - authenticatorData:至少 37 字节,
rpIdHash、一个 flag 字节、四个计数器字节。 - flag 字节:解码后 UP 置位、UV 置位、AT 清零。
- rpIdHash 不匹配:哈希不等于预期 RP ID 的
SHA-256。 - origin:白名单里只有生产域名,缺预发布环境。
- challenge:在节点 A 签发,在节点 B 消费,两边没有共享存储。
- COSE 标签 3:算法是
-8,服务器走 Ed25519 分支。 - 结果:一条有效断言因为三个互不相干的配置原因被同时拒收。
注意这次调试真正说明了什么:断言从来没有被伪造,签名很可能验得过。三个独立的部署配置缺陷,造出一个无法区分的错误。这是按顺序跑完三层(解码、绑定、验证)最有力的理由;换个顺序修,就只能一张支持工单修一个。
解码器给了日志给不了的东西
要解码而不是只打日志,原因是解码后的断言把状态和结论分开了。flag 字节是状态,它告诉你认证器声称发生了什么。绑定校验是结论,它告诉你服务器判定了什么。一行日志把两者揉进一个字符串,所以同一段报错文本会对应八种不同的底层情况。
具体说,解码后的断言让四件事立刻可见。rpIdHash 是不是你预期的域名,还是多租户部署里隔壁租户的域名。signCount 在递增、停滞还是归零:一个在多次登录中始终为零的计数器,说明背后是模拟器或软件令牌,不是硬件认证器。UP 与 UV 是否都置位,这决定了认证仪式到底有没有让用户参与。COSE 算法标签是否与验证器即将走的分支一致,这一项能在 Ed25519 双哈希 bug 变成签名失败之前拦住它。
同一次解码还回答了每个 passkey 支持帖开头的那个问题:“这到底是不是一条真断言?”结构上无效的数据块会立刻失败:authenticatorData 不足 37 字节,clientDataJSON 解析不成 JSON,type 既不是 webauthn.get 也不是 webauthn.create。这三项结构检查能筛掉相当大一部分畸形载荷,而且在动任何密码学之前做,成本为零。
调试一次本该失败却成功了的登录时(比如计数器回退,或凭据注册到了错误的依赖方域名),把这三层反过来跑。解码这一步会立刻告诉你,你正在评估的凭据是不是你本来想评估的那个。
Passkey 上线前的健全性清单
上线之前,或者接手一套跑不通的 passkey 流程时,按顺序检查:
- 先解码。没亲眼拆开过的载荷,不要拿去验证。确认是三段数据,确认 flag 字节是按位读出来的。
- 自己算
rpIdHash。服务器端把 RP ID 哈希一遍,与偏移 0 处比对。不一致就停下,下游没有一个环节可信。 - origin 白名单要精确。每个能完成认证仪式的环境都要有自己的条目,含协议和端口。
- challenge 存在所有节点都够得着的地方。一次性使用、短 TTL、全集群共享。
- 按注册算法分支。ES256 与 RS256 在签名前先哈希
clientDataJSON,Ed25519 不哈希。消息从 COSE 标签推导,别用硬编码的默认值。 - UP 清零一律拒收。没有用户在场的断言不是认证。
- 让 signCount 回退可观测。写日志;如果这本该是硬件凭据,就该报警。
- 错误码要分开。客户端只看到一个笼统失败,你的日志里该看到四种。
这些全是配置和管线检查,没有一项是密码学检查。这正是 passkey 调试反复出现的教训:密码学几乎总是对的,绑定几乎总是错的。等 authenticatorData 拆开了,四项绑定一项项对完,一张“WebAuthn 坏了”的工单就变成两分钟的 diff。
需要相邻的原语时,可以去 elysiatools.com浏览其余工具:密钥生成、编码层,以及 passkey 部署管线接下来常要用到的证书检查。
Pingback: WebAuthn Passkey Assertion Debugging: Signatures Pass, Binding Checks Fail - COSESAI