PKCE Code Verifier 与 Challenge 生成器实战指南:三种模式、四档熵,决定 OAuth 握手能否扛住网络嗅探

PKCE 实战指南:三种模式、四档熵、一条 URL

PKCE Code Verifier 与 Challenge 生成器实战指南:三种模式、四档熵,决定 OAuth 握手能否扛住网络嗅探

PKCE 划出一条分界线:一边是安全的公共客户端 OAuth 握手,另一边是把授权码送给同一个 Wi-Fi 下下一位用户的握手。手机应用、SPA 和命令行工具没有 client secret,只能用一次性的 verifier 加 challenge 配对来证明自己的意图。算错一步,攻击者拿到授权码就够了;算对了,最坏的情况也只是授权码被偷,却兑换不出令牌。PKCE Code Verifier 与 Challenge 生成器把 RFC 7636 的三件事收进一个框里:从 256/384/512/768 位熵生成全新配对;按长度、字符集和熵规则审计手上已有的 verifier;通过重算 BASE64URL(SHA256(verifier)) 校验 verifier 与 challenge 是否配对。

PKCE 到底在防什么

PKCE 在 RFC 7636 中定稿,解决的是 2015 年暴露的一个问题:授权码拦截攻击。跑在 Android 或 iOS 上的原生应用会注册一个自定义 URL scheme 来接收授权码,可要是别的应用先注册了同一个 scheme,授权码就落进了攻击者的进程。没有 PKCE,攻击者立刻能把码兑走。有了 PKCE,他还得拿到 verifier,而 verifier 只在合法客户端内部生成,从未离开它的内存。

这套防线成立的前提有两个:verifier 猜不出来,challenge 反推不回去。RFC 7636 把两者钉在一起:从 [A-Za-z0-9-._~] 里生成 43 到 128 个字符,用 SHA-256 哈希,再把 BASE64URL 编码后的摘要作为 challenge 发出去。授权服务器存的是哈希,不是明文。客户端兑码时把原始 verifier 发过去,服务器重新哈希并比对。攻击者只握着被拦截的授权码,没法从 challenge 反推出 verifier,因为 SHA-256 是单向函数。

实际会用到的三种模式

生成器把整个流程压成三种模式,都在同一个输入框里切换。

三种模式与四档熵
  • 生成模式输出一个新的 code_verifier,以及匹配的 code_challenge_method = 'S256' 和 code_challenge。verifier 放进客户端配置,challenge 放进授权请求的 code_challenge 查询参数。
  • 审计模式校验手上已有的 verifier。它检查长度区间(43 到 128 字符)、字符集([A-Za-z0-9-._~])和熵预算(≥ 256 位)。它常抓到的毛病是「拿 UUID 补零当 verifier」:带连字符的 UUID 只有 122 位熵,远低于 RFC 的下限。
  • 验证模式接收 verifier 和 challenge,重算 BASE64URL(SHA256(verifier)) 确认两者匹配。这是服务器在令牌交换时做的事的离线版本;上线前跑一遍,能发现存下的 verifier 和前端发出的 challenge 之间的漂移。

熵为什么比长度更要紧

RFC 只写了 43 到 128 字符,这个下限是有误导性的。从 64 个符号里抽出的 43 字符 verifier 有 43 × 6 = 258 位;从 10 个符号的字母表里抽出的 43 字符 verifier 只有 43 × ~3.3 = 142 位,掉到下限以下。生成器的熵选择器替你把这笔账算好,并给每一档标出位数。

  • 256 位熵是 RFC 下限,任何合规审计都能过。由 32 个随机字节生成。
  • 384 位熵是价值较高的 SPA 令牌常用的档位。由 48 个随机字节生成。
  • 512 位熵对齐 SHA-512 的块大小,不给未来的暴力破解留余地。由 64 个随机字节生成。
  • 768 位熵是 PKCE 的实际上限。由 96 个随机字节生成,输出正好 128 字符的字符串,卡在 RFC 的长度上限上。

真正的坑是把熵当成面子指标。生成器只发 [A-Z0-9] 而不是 [A-Za-z0-9-._~],512 位的 verifier 照样过不了 RFC 7636。审计模式一轮就能把两类失败都查出来。

不合格的 verifier 审计长什么样

拿一个手写的 verifier 跑审计模式,眼睛看不见的窟窿就露出来了。审计按规则逐条给结果:长度通过与否、字符集通过与否、熵通过与否,外加重算出的位数。一个 64 字符的十六进制([0-9a-f])verifier 会报 256 位熵,因为字母表是 16 个符号;肉眼觉得「够长了」,审计却指出它在长度和字符集上都合规,唯独字母表多样性偏窄。

上线前的五项检查

另一种失败是补零的 verifier。Java 的 UUID.randomUUID().toString() 是 36 字符,用 16 个十六进制符号加 4 个连字符。补上 = 凑到 43 字符,长度和字符集都过了,熵却只有 122 位,离 256 位的下限差得很远。审计会打出「entropy FAIL (122 < 256 bits)」。标准修法是改用 SecureRandom,从 32 个字节输出 BASE64URL[5]。

verifier 变成 challenge 的那一步

数学很短。取一个 43 字符、取自 [A-Za-z0-9-._~] 的字符串,按字节解码,做 SHA-256,再把摘要做 BASE64URL 编码。输出是 43 字符的 challenge(无填充,URL 安全字母表)。用伪 shell 写出来,流程是这样:

四档熵并排比较
  • 输入:43 字符的 verifier,例如 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
  • SHA-256 十六进制:293e6cc24fcf2a96ea9d2e3a8c40f5d2a4f5a3a8e6f9b1c4d6e7f8a9b0c1d2e3f(显示时截断)
  • BASE64URL:LS6mY9P1x9B_KoSq5LM3vx_r_q8FSxhOJf4_GCNFRBg
  • 授权请求:https://auth.example.com/authorize?response_type=code&client_id=...&code_challenge=LS6mY9P1x9B_KoSq5LM3vx_r_q8FSxhOJf4_GCNFRBg&code_challenge_method=S256&state=...&redirect_uri=...

服务器在授权请求上存下 code_challenge,到令牌交换时重新哈希 verifier。对上了就发令牌,对不上就返回 invalid_grant,攻击就此落空。

拼出授权请求 URL

生成器也能拼出完整的授权 URL,你唯一要手敲的只剩 redirect URI。把 client ID、scope、state 和新生成的 challenge 交给它,它返回一条能直接塞进 WebView 或 openURL() 调用的地址。典型的结果长这样:

  • 端点:https://auth.example.com/authorize
  • 参数:response_type=code、client_id=<your-client>、redirect_uri=<your-scheme>、scope=openid profile、state=<csrf-token>、code_challenge=<43-char-base64url>、code_challenge_method=S256

参数全靠手拼,state 令牌就是这么泄的,code_challenge_method 的拼写错误就是这么混进生产的。让生成器负责拼装,参数名只有一处来源,输出还带百分号编码,复制粘贴也不会坏。

verify 模式为什么能抓住集成漂移

审计和验证两种模式不只是开发者的多疑,它们抓的是前端与后端通过数据库或缓存共享状态时发生的漂移。典型的样子:第一天生成 verifier,存进会话表;一年后一个移动客户端取到这一行,想去兑码;服务器拒绝,因为存下的 verifier 被截断过,或者被重新哈希过。重新部署前拿存下的配对跑一遍验证模式,几秒钟就能看到不匹配,不必等到凌晨 3 点集成测试全线飘红。

验证模式的第二个用处,是调试你管不了的授权服务器。手上有闭源客户端写出的 verifier,想知道服务器期待什么 challenge,生成模式加验证模式就够了:把 verifier 粘进验证模式,让它算出 challenge,再跟闭源客户端实际发出的 URL 比对。两者对不上,集成里就有状态不同步的 bug。

上线前核对这几项

PKCE 属于少数几种安全原语:verifier 可以在三个彼此独立的方向上出错,握手看上去仍然「像模像样」。上线前用 PKCE Code Verifier 与 Challenge 生成器 的审计模式做预检:43 到 128 字符,字符集只用 [A-Za-z0-9-._~],熵不少于 256 位。再拿会话表里存的 verifier 和 challenge 跑验证模式,抓漂移。然后在一个非生产租户里跟真实的授权服务器走一遍完整流程,看 code_challenge 参数是否原样落到服务器上。

这三项检查漏掉任何一项,防线就失效。41 字符的 verifier 肉眼看着没问题,到令牌交换时会被授权服务器打回。[A-Z0-9] 的 verifier 能过你本地的长度测试,却会撞上服务器的字符集检查。200 位的 verifier 能过 CI 的 lint,却会在加固过的渗透测试里翻车。审计模式一次抓住这三种,验证模式证明集成接对了,生成模式让字节在各平台上保持一致。

更多工具见 elysiatools.com。

1 Comment

Leave a Reply

Your email address will not be published. Required fields are marked *