
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。
Pingback: PKCE Code Verifier & Challenge Generator Field Guide: When Three Modes and Four Entropy Tiers Decide Whether the OAuth Handshake Survives a Network Sniffer - COSESAI