JJWT (io.jsonwebtoken)

事实及其依据的检查

以下内容均非抄自文档。检查脚本 content/libraries/verify/jjwt/run.sh 于2026年10月20日在容器镜像 maven:3.9.16-eclipse-temurin-25 中运行了 JJWT (io.jsonwebtoken) 0.13.0；本页内容必须与它的输出一致，每条事实都列出了对应的输出行。

• JWS 算法

  HS256HS384HS512RS256RS384RS512PS256PS384PS512ES256ES384ES512EdDSA

  256/384/512 的 HS、RS、PS 和 ES 以及 EdDSA 的签名与验证均成功；ES256K、Ed25519 和 Ed448 不在 Jwts.SIG 中。

  检查记录

  fact jws-algorithms = HS256, HS384, HS512, RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, EdDSA
  evidence jws-algorithms: ES256K: not in Jwts.SIG
  evidence jws-algorithms: Ed25519: not in Jwts.SIG
  evidence jws-algorithms: Ed448: not in Jwts.SIG

• ES256 签名编码

  raw

  ES256 签名是 64 字节的原始 r‖s。

  检查记录

  fact jws-ecdsa-encoding = raw

• JWS 中的 DER 签名

  rejected

  DER 编码的 ES256 签名会报错 Provided signature is 576 bits (72 bytes) but ES256 signatures must be exactly 512 bits (64 bytes)。

  检查记录

  fact jws-der-signature = rejected
  evidence jws-der-signature: SignatureException: Unable to verify Elliptic Curve signature using provided ECPublicKey: Provided signature is 576 bits (72 bytes) but ES256 signatures must be exactly 512 bits (64 bytes) per [RFC 7518, Section 3.4 (validation)](https://www.rfc-editor.org/rfc/rfc7518.html#section-3.4).

• 算法允许列表

  from-key

  由验证密钥决定算法：用 EC 公钥验证 RS256 令牌，报错 UnsupportedJwtException。

  检查记录

  fact jwt-algorithm-allowlist = from-key
  evidence jwt-algorithm-allowlist: RS256 token, verifyWith(EC public key): UnsupportedJwtException: The parsed JWT indicates it was signed with the 'RS256' signature algorithm, but the provided sun.security.ec.ECPublicKeyImpl key may not be used to verify RS256 signatures.  Because the specified key reflects a specific and expected algorithm, and the JWT does not reflect this algorithm, it is likely that the JWT was not expected and therefore should not be trusted.  Another possibility is that the parser was provided the incorrect signature verification key, but this cannot be assumed for security reasons.

• 未签名的令牌（alg none）

  opt-in

  parseSignedClaims 会拒绝未签名的令牌；Jwts.parser().unsecured() 配合 parseUnsecuredClaims 可以读取它们。

  检查记录

  fact jwt-alg-none = opt-in
  evidence jwt-alg-none: parseSignedClaims with the EC key: UnsupportedJwtException: Unsecured JWSs (those with an 'alg' (Algorithm) header value of 'none') are disallowed by default as mandated by https://www.rfc-editor.org/rfc/rfc7518.html#section-3.6. If you wish to allow them to be parsed, call the JwtParserBuilder.unsecured() method, but please read the security considerations covered in that method's JavaDoc before doing so. Header: {alg=none, typ=JWT}
  evidence jwt-alg-none: parser().unsecured().parseUnsecuredClaims: verified

• 把公钥用作 HMAC 密钥

  rejected

  以 PEM 文本为密钥的 HS256 令牌，用 EC 公钥验证时被拒绝，但用 Keys.hmacShaKeyFor(pemBytes) 验证通过了。

  检查记录

  fact jwt-hmac-public-key = rejected
  evidence jwt-hmac-public-key: verifyWith(EC public key): UnsupportedJwtException: The parsed JWT indicates it was signed with the 'HS256' signature algorithm, but the provided sun.security.ec.ECPublicKeyImpl key may not be used to verify HS256 signatures.  Because the specified key reflects a specific and expected algorithm, and the JWT does not reflect this algorithm, it is likely that the JWT was not expected and therefore should not be trusted.  Another possibility is that the parser was provided the incorrect signature verification key, but this cannot be assumed for security reasons.
  evidence jwt-hmac-public-key: verifyWith(Keys.hmacShaKeyFor(PEM bytes)): verified

• 按 alg 检查曲线

  enforced

  用 P-384 密钥签名 ES256 会失败：the 'ES256' algorithm requires EC Keys with 256 bits。

  检查记录

  fact jwt-ecdsa-curve-check = enforced
  evidence jwt-ecdsa-curve-check: SignatureException: Unable to compute ES256 signature. Cause: The provided Elliptic Curve signing key size (aka order bit length) is 384 bits (48 bytes), but the 'ES256' algorithm requires EC Keys with 256 bits (32 bytes) per [RFC 7518, Section 3.4](https://www.rfc-editor.org/rfc/rfc7518.html#section-3.4).

• 默认时钟偏差

  0s

  默认不允许时钟偏差：三秒前过期的令牌被拒绝。

  检查记录

  fact jwt-clock-skew = 0s

• 是否要求过期时间声明

  no

  不含 exp 的令牌能成功解析。

  检查记录

  fact jwt-exp-required = no

• 过短的 HMAC 密钥

  rejected

  Keys.hmacShaKeyFor 以 WeakKeyException 拒绝了 16 字节的密钥。

  检查记录

  fact jwt-hmac-short-secret = rejected
  evidence jwt-hmac-short-secret: Keys.hmacShaKeyFor(16 bytes): WeakKeyException: The specified key byte array is 128 bits which is not secure enough for any JWT HMAC-SHA algorithm.  The JWT JWA Specification (RFC 7518, Section 3.2) states that keys used with HMAC-SHA algorithms MUST have a size >= 256 bits (the key size must be greater than or equal to the hash output size).  Consider using the Jwts.SIG.HS256.key() builder (or HS384.key() or HS512.key()) to create a key guaranteed to be secure enough for your preferred HMAC-SHA algorithm.  See https://tools.ietf.org/html/rfc7518#section-3.2 for more information.

用法

import io.jsonwebtoken.Claims;
import io.jsonwebtoken.Jwts;
import java.security.KeyPair;
import java.util.Date;

public class Usage {
    public static void main(String[] args) {
        KeyPair pair = Jwts.SIG.ES256.keyPair().build();
        String token = Jwts.builder()
            .subject("user-42")
            .issuer("https://auth.example.com")
            .expiration(new Date(System.currentTimeMillis() + 600_000))
            .signWith(pair.getPrivate(), Jwts.SIG.ES256)
            .compact();

        // The key decides which algorithms are acceptable; require iss and exp explicitly
        // and allow some clock skew (the default is none).
        Claims claims = Jwts.parser()
            .verifyWith(pair.getPublic())
            .requireIssuer("https://auth.example.com")
            .clockSkewSeconds(30)
            .build()
            .parseSignedClaims(token)
            .getPayload();
        System.out.println("sub: " + claims.getSubject() + ", has exp: " + (claims.getExpiration() != null));
    }
}