iTop 内置 firebase/php-jwt 版本演进全解读:从 2.0 到 7.0 的 JWT 安全加固与功能变迁

原创2026-10-15 11:22:421,738 阅读
文章标签:后端企业应用

iTop 内置 firebase/php-jwt 版本演进全解读:从 2.0 到 7.0 的 JWT 安全加固与功能变迁

导读

本篇文章以 iTop 仓库内 lib/firebase/php-jwt/CHANGELOG.md 为核心骨架,系统梳理 PHP-JWT(firebase/php-jwt)从 2.0.0 到 7.0.5 的完整版本演进史,并结合 lib/firebase/php-jwt/src 下的真实源码,逐条解析各版本特性、破坏性变更与安全修复背后的底层实现。读完本文,你将掌握该库的算法支持矩阵、Key/JWK/CachedKeySet 三大核心抽象、密钥长度校验规则、异常体系设计,以及在 iTop 这类 PHP 8 项目中使用 JWT 时应当注意的升级与安全实践。

一、该库在 iTop 中的定位与安装方式

在深入版本历史之前,先明确这份 CHANGELOG 描述的对象在仓库中的位置。firebase/php-jwt 是一个符合 RFC 7519 的轻量级 PHP JWT 编解码库("A simple library to encode and decode JSON Web Tokens (JWT) in PHP"),其源码目录位于:

该库并非 iTop 自研,而是通过 Composer 引入的第三方依赖,这可以从根目录的 lib/composer/installed.json(composer 安装清单)得到确认。其下游消费者之一是 Azure OAuth2 客户端 lib/thenetworg/oauth2-azure/composer.json,即 iTop 在接入 Azure AD 登录等场景时会经由该库来签发/校验 JWT 令牌。因此,理解 php-jwt 的版本行为,本质上就是理解 iTop 认证链路中令牌安全边界的行为。

官方推荐通过 Composer 安装:

composer require firebase/php-jwt

如果 PHP 环境缺少 libsodium 扩展,为支持 EdDSA(Ed25519)签名还可可选安装:

composer require paragonie/sodium_compat

二、版本演进总览

CHANGELOG 记录的时间跨度从 2015 年 4 月的 2.0.0 一直延伸到 2026 年 3 月的 7.0.5,跨度超过十年。整体来看,演进可划分为三个时代:

时代 版本区间 主题
2.x 时代 2.0.0 – 2.2.0 引入算法白名单、leeway、自定义 header,奠定安全基础
3.x – 5.x 时代 3.0.0 – 5.0.0 引入命名空间、增加 RSA/ECDSA 算法与错误处理
6.x 时代 6.0.0 – 6.11.1 引入 Key 对象、JWK、CachedKeySet、ES/EdDSA 全曲线
7.x 时代 7.0.0 – 7.0.5 安全加固密集期:密钥长度校验、敏感参数标记、时间校验
PHP 版本要求 3.0.0 起 >= 5.3 6.1.0 淘汰 5.x/7.0,7.x 要求 ^8.0

三、7.x 时代:以安全加固为核心的密集迭代

7.0.0 是 CHANGELOG 中标注了 ⚠️ Security Fixes 的重大版本,后续 7.0.2、7.0.4、7.0.5 均围绕安全与正确性持续打补丁。

3.1 7.0.0:密钥长度校验(可能破坏现有配置)

7.0.0 引入的关键安全修复是"add key size validation"(对应 JWT.php 中的校验逻辑),CHANGELOG 明确给出兼容性警告:

NOTE: This fix will cause keys with a size below the minimally allowed size to break.

也就是说,凡密钥长度低于最低允许值的现有系统,在升级后签名/验签会直接失败。具体校验规则在源码中清晰可见:

  • RSA 密钥:RSA_KEY_MIN_LENGTH = 2048,validateRsaKeyLength() 通过 openssl_pkey_get_details($key) 读取 bits,若小于 2048 抛 DomainException('Provided key is too short')(JWT.php 中的 validateRsaKeyLength 方法)。
  • EC 密钥:7.0.2 补充了 EC 密钥长度校验,validateEcKeyLength() 从算法名中提取最小位数(如 ES256 → 256、ES384 → 384),低于阈值同样抛 DomainException。
  • HMAC 密钥:validateHmacKeyLength() 要求密钥长度(字节 × 8)不小于哈希算法位数,例如 HS256 要求 ≥ 256 位,否则抛 DomainException('Provided key is too short')。

这意味着 7.x 之后,"短密钥 + 高强度算法"这类不安全的组合会被库直接拒绝,从源头杜绝了弱密钥风险。升级到 7.0.x 前,请务必检查现有 RSA 密钥是否 ≥ 2048 位、HMAC 密钥是否满足对应哈希长度。

3.2 7.0.0:SensitiveParameter 属性与 ExpiredException 时间戳

7.0.0 还包含两项重要特性:

  1. 为安全关键参数添加 #[\SensitiveParameter] 属性:在 JWT.php 中,decode() 的 $keyOrKeyArray、encode() 的 $key、sign() 的 $key、verify() 的 $keyMaterial 以及 Key.php 构造函数的 $keyMaterial 均被标记为 #[\SensitiveParameter]。该属性会在异常回溯中屏蔽敏感值,防止密钥材料在栈追踪中泄露到日志。

  2. 在 ExpiredException 中存储时间戳:源码 ExpiredException.php 新增 setTimestamp(int) / getTimestamp(): ?int。当 JWT::decode 检测到 exp 已过期时,会执行 $ex->setTimestamp($timestamp) 后再抛出,调用方据此可精确得知令牌失效的判定时间点。

3.3 7.0.0:校验 iat 与 nbf

7.0.0 的 Bug Fixes 中还包含 "validate iat and nbf on payload"。在 JWT.php 的 decode() 流程里可以看到:iat、nbf、exp 若存在且非数值,会直接抛 UnexpectedValueException('Payload xxx must be a number');随后依次执行:

  • nbf 校验:floor($payload->nbf) > ($timestamp + static::$leeway) 时抛 BeforeValidException("Cannot handle token with nbf prior to ...");
  • iat 校验:仅在 未设置 nbf 时才检查(!isset($payload->nbf) && isset($payload->iat)),这是 6.6.0 引入的"only check iat if nbf is not used"语义的延续;
  • exp 校验:($timestamp - static::$leeway) >= $payload->exp 时抛 ExpiredException。

三者共同构成完整的时间有效性防线,且 iat/nbf 均向下取整(floor),这与 6.8.1 的"accept float claims but round down"行为一脉相承。

3.4 7.0.4 与 7.0.5:正确性收尾

  • 7.0.4 做了两件事:一是为 README 中的所有示例补齐测试(保证文档示例可运行);二是 "use urlsafeB64Decode everywhere"——统一所有 Base64URL 解码路径为 JWT.php 中 urlsafeB64Decode() 这一个入口,消除了内部解码方式不一致带来的边界问题。
  • 7.0.5 修复了 "RSA from JWK sometimes returns empty Instance":当 JWK 中 RSA 公钥的 n/e 参数被解析成空实例时(可参考 JWK.php 中 createPemFromModulusAndExponent() 的 PEM 构造逻辑)给出正确结果。

四、6.x 时代:JWK、CachedKeySet 与算法矩阵大扩充

6.x 是功能增长最快的时期,许多今天仍在使用的核心抽象都诞生于此时。

4.1 6.0.0:破坏性变更与 Key 对象

6.0.0 是一次向后不兼容的大版本(CHANGELOG 提示参见 Release Notes),核心变化包括:

  • 引入 Key 对象,用于消除"密钥/算法类型混淆"(key/algorithm type confusion)攻击面。从 Key.php 可见,Key 同时持有 $keyMaterial 与 $algorithm,JWT::decode 在验签前会通过 constantTimeEquals($key->getAlgorithm(), $header->alg) 强制比对 JWT header 中的 alg 与 Key 声明的算法,不匹配即抛 UnexpectedValueException('Incorrect key for this algorithm')(JWT.php 的 decode() 流程)。这就是杜绝"算法混淆攻击"(如把 RS256 令牌换成 HS256 用公钥当 HMAC 密钥)的关键机制。
  • 同一版本新增 JWK 支持(JWT::parseKey 由 6.2.0 补充 $defaultAlg 参数)、ES256/ES384/Ed25519 支持。

4.2 6.2.0:CachedKeySet 与默认算法参数

6.2.0 引入 CachedKeySet(CachedKeySet.php),用于从公开 URI 拉取并缓存 JWKS,其设计目标可归纳为:

  1. 结果缓存,提升性能;
  2. 遇到未知 kid 时自动刷新缓存,兼容密钥轮换;
  3. 开启限流时,JWKS URI 每秒不超过 10 次请求。

源码实现上,CachedKeySet 实现 ArrayAccess,JWT::decode 的 getKey() 会直接通过 $keyOrKeyArray[$kid] 取值,触发 keyIdExists() 的"查缓存 → 未命中则 GET JWKS → 写回缓存"流程;rateLimitExceeded() 通过缓存项中的 callsPerMinute 计数,超过 maxCallsPerMinute = 10 即拒绝拉取,避免对提供方造成压力。6.3.0 进一步把 JWKS 以字符串形式缓存以规避序列化错误,6.10.1 则修复了限流过期时间"每次都要重新设置"的缺陷,确保限流计数窗口始终正确。

JWT::parseKeySet(array $jwks, ?string $defaultAlg = null) 则允许在 JWKS 中缺少 alg 字段时(RFC 7517 中该字段对 kty 可选)用默认算法兜底。

4.3 算法与曲线矩阵的持续扩充

CHANGELOG 中 6.x 的算法相关条目可汇总为下表:

版本 新增能力 源码佐证
6.3.0 JWK 解析支持 ES256 JWK.php EC_CURVES 常量
6.4.0 支持 W3C ES256K(secp256k1 曲线);JWKS 仅在必要时解码以优化缓存 EC_CURVES['secp256k1'] = '1.3.132.0.10'
6.7.0 Ed25519 公钥的 JWK 支持(OKP 类型) OKP_SUBTYPES['Ed25519']
6.8.0 P-384 曲线支持 EC_CURVES['P-384'] = '1.3.132.0.34'
6.11.0 oct 类型(对称密钥)JWK 支持 JWK.php 的 case 'oct' 分支

对照 JWT.php 中的 $supported_algs,7.x 最终支持的算法集合为:HS256/HS384/HS512(hash_hmac)、RS256/RS384/RS512(openssl)、ES256/ES256K/ES384(openssl)、EdDSA(libsodium)。ES 系列的签名在验签时需由原始 r||s 格式转换为 ASN.1 DER 序列(signatureToDER()),签发时反向转换(signatureFromDER()),这是 OpenSSL 与 JOSE 规范之间的格式差异所致。

4.4 解码体验与兼容性修补

6.x 还持续打磨解码接口与 PHP 版本兼容:

  • 6.6.0:"allow get headers when decoding token"——JWT::decode($jwt, $key, $headers) 的第三个 stdClass 引用参数会回填 header(对应 JWT.php 的 ?stdClass &$headers = null)。注意 README 强调:不应在未验证签名前解码 header,未验证的 header 内容应视作攻击者可注入的任意字符串。
  • 6.9.0:把导致异常的 payload 附加到异常对象中(JWTExceptionWithPayloadInterface,见 JWTExceptionWithPayloadInterface.php),便于排查"哪个 claim 导致失败"。
  • 6.10.0:允许覆盖 typ header(encode() 的 $head 参数会与默认 ['typ' => 'JWT'] 合并)。
  • 6.5.0:允许 kid 为字符串 '0'(此前会被误判为空),并淘汰 PHP 7.3。
  • 6.10.2 / 6.3.1:分别支持 PHP 8.4(消除弃用警告)与 PHP 8.2 字符串插值语法。

五、6.0.0 之前的演进:安全基石的奠定

5.1 2.x:算法白名单与 leeway

  • 2.0.0 是安全转折点:CHANGELOG 明确指出,"当对称与非对称密钥混用时,旧版本存在已知安全漏洞,强烈建议升级到 2.0.0+"。2.0.0 将 JWT::decode() 的签名改为要求传入受支持算法数组,即强制调用方声明允许的算法集合,这正是今天 Key 对象强制 alg 匹配的前身。
  • 2.1.0 引入 JWT::$leeway(默认 0),用于抵消签发方与验证方之间的时钟偏差,README 建议 leeway 不宜超过几分钟;同时 $keys 参数支持 ArrayAccess 对象。
  • 2.2.0 允许向 JWT::encode() 追加自定义可选 header。

5.2 3.x – 4.x:命名空间与可测试性

  • 3.0.0:最低 PHP 版本提升到 5.3,引入 \Firebase\JWT 命名空间,并要求非空密钥才能解码验签(防止"空密钥"绕过)。
  • 4.0.0:改用静态 $timestamp 替代直接调用 time(),便于单元测试固定时间点(该设计在 JWT.php 中保留至今:$timestamp = is_null(static::$timestamp) ? time() : static::$timestamp);同时支持后期静态绑定(late static binding)。

5.3 5.x:RSA 算法扩充与错误处理

5.0.0 是一次功能里程碑:

  • 支持 RS384 / RS512;
  • 增加 RS256 的 openssl 示例;
  • 检测签名中的非法 Base64 编码;
  • JWT::verify 现在能处理 OpenSSL 错误(对应源码中 openssl_verify 返回 -1 时抛 DomainException('OpenSSL error: ...'));
  • decode 方法增加 array 类型提示,并覆盖所有 JSON 错误类型(handleJsonError() 中的 JSON_ERROR_DEPTH/STATE_MISMATCH/CTRL_CHAR/SYNTAX/UTF8 映射)。

六、源码级对照:decode 校验链与异常体系

把版本史落到当前代码上,JWT::decode() 的完整校验顺序(JWT.php 的 decode 方法)可以概括为一条清晰的"校验链":

  1. 空 Key / 空 Key 数组 → InvalidArgumentException('Key may not be empty');
  2. 非三段式(explode('.', $jwt) 不等于 3)→ UnexpectedValueException('Wrong number of segments');
  3. header / payload 的 Base64URL 解码与 JSON 解析失败 → UnexpectedValueException;
  4. payload 必须为 JSON 对象;iat/nbf/exp 非数值 → UnexpectedValueException;
  5. 空 alg 或不在 $supported_algs → UnexpectedValueException;
  6. 按 kid 查找 Key(getKey(),支持 Key、数组、ArrayAccess/CachedKeySet)→ 找不到抛 UnexpectedValueException;
  7. Key 算法与 header alg 不一致 → UnexpectedValueException('Incorrect key for this algorithm');
  8. ES 系列签名转 DER 后验签,失败 → SignatureInvalidException;
  9. nbf/iat/exp 时间校验 → BeforeValidException / ExpiredException。

对应的异常体系如下(全部位于 Firebase\JWT 命名空间,均继承 \UnexpectedValueException):

use Firebase\JWT\JWT;
use Firebase\JWT\SignatureInvalidException;
use Firebase\JWT\BeforeValidException;
use Firebase\JWT\ExpiredException;
use DomainException;
use InvalidArgumentException;
use UnexpectedValueException;

try {
    $decoded = JWT::decode($jwt, $keys);
} catch (InvalidArgumentException $e) {
    // 传入的 key/key 数组为空或格式错误
} catch (DomainException $e) {
    // 算法不受支持、key 无效、OpenSSL/libsodium 出错、缺少 libsodium
} catch (SignatureInvalidException $e) {
    // 签名验证失败
} catch (BeforeValidException $e) {
    // 令牌在 nbf / iat 之前被使用
} catch (ExpiredException $e) {
    // 令牌已过期(exp)
} catch (UnexpectedValueException $e) {
    // 令牌格式错误、缺少/不支持 alg、alg 与 key 不匹配、kid 无效
}

其中 ExpiredException(ExpiredException.php)额外实现了 JWTExceptionWithPayloadInterface,可调用 getPayload() / getTimestamp() 获取引发异常的令牌载荷与判定时间戳,这是 7.0.0 与 6.9.0 两版特性叠加的成果。

七、对使用者的升级与实践建议

基于 CHANGELOG 与源码,给 iTop 及其扩展的 JWT 使用场景总结几点可落地的建议:

  1. 关注 7.0.0 的破坏性:升级后短于 2048 位的 RSA 密钥、短于哈希位数的 HMAC 密钥会被直接拒绝(Provided key is too short)。升级前务必盘点现有密钥长度。
  2. 始终坚持算法白名单:无论用 Key 对象还是 $supported_algs 数组,都要显式声明允许的算法,不要接受 header 中的任意 alg,这是 2.0.0 至今反复加固的安全底线。
  3. 善用 leeway 但不滥用:JWT::$leeway 用于抵消时钟偏差,README 建议不超过几分钟;时间校验规则为 exp 用 >=(含 leeway 收缩),nbf/iat 用 >(含 leeway 放宽),且 iat 仅在无 nbf 时才校验。
  4. 远程 JWKS 使用 CachedKeySet:它同时解决性能、密钥轮换(未知 kid 自动刷新)与限流(默认 10 次/分钟)三个问题;构造参数 $expiresAfter 与 $rateLimit 可分别控制缓存时长与限流开关。
  5. 不要把未验证的 header 当可信数据:如需 header 内容,先完成 decode 验签,或明确意识到手工 json_decode(base64_decode(...)) 解析出的 header 可能已被篡改。
  6. decode 返回值为 stdClass:如需关联数组,用 (array) $decoded 或 json_decode(json_encode($decoded), true) 转换,这是 6.0.0 之后的固定返回类型。

结语

透过 lib/firebase/php-jwt/CHANGELOG.md 这份清单,可以看到一个被广泛使用的 JWT 库十年间的进化轨迹:2.x 确立算法白名单与 leeway,3.x/5.x 建立命名空间、算法矩阵与错误处理,6.x 打造 Key 对象、JWK 与 CachedKeySet 三大现代抽象,7.x 则以密钥长度校验、SensitiveParameter、时间 claim 校验等安全修复完成最后的闭环。这些演进既体现在 lib/firebase/php-jwt/src 的每一行源码中,也直接决定了 iTop 认证与 OAuth2 集成场景下令牌校验的安全边界。升级或使用该库时,以 CHANGELOG 为线索、以源码为印证,是最稳妥的实践路径。

登录后查看全文
iTop