JWCrypto

事实及其依据的检查

以下内容均非抄自文档。检查脚本 content/libraries/verify/jwcrypto/run.sh 于2026年10月20日在容器镜像 python:3.14.8-slim-trixie 中运行了 JWCrypto 1.6.1（运行时为 cryptography 50.0.2）；本页内容必须与它的输出一致，每条事实都列出了对应的输出行。

• JWS 算法

  HS256HS384HS512RS256RS384RS512PS256PS384PS512ES256ES384ES512ES256KEdDSAEd25519Ed448ML-DSA-44ML-DSA-65ML-DSA-87

  256/384/512 位的 HS、RS、PS 和 ES，以及 ES256K、EdDSA、Ed25519、Ed448 和 ML-DSA-44/65/87（使用 AKP 密钥）的签名与验证均成功；它们全部在默认允许列表中。

  检查记录

  fact jws-algorithms = HS256, HS384, HS512, RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, ES256K, EdDSA, Ed25519, Ed448, ML-DSA-44, ML-DSA-65, ML-DSA-87
  evidence jws-algorithms: ML-DSA-44: JWK kty AKP
  evidence jws-algorithms: ML-DSA-65: JWK kty AKP
  evidence jws-algorithms: ML-DSA-87: JWK kty AKP
  evidence jws-algorithms: default allowed list: HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512, EdDSA, ES256K, Ed25519, Ed448, ML-DSA-44, ML-DSA-65, ML-DSA-87

• ES256 签名编码

  raw

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

  检查记录

  fact jws-ecdsa-encoding = raw

• JWS 中的 DER 签名

  rejected

  DER 编码的 ES256 签名会报错 InvalidJWSSignature: Verification failed for all signatures。

  检查记录

  fact jws-der-signature = rejected
  evidence jws-der-signature: InvalidJWSSignature: Verification failed for all signatures["Failed: [InvalidJWSSignature('Verification failed')]"]

• 算法允许列表

  from-key

  不传 algs 时，使用默认列表，由密钥类型决定：ES256 令牌用 EC 密钥验证通过，而用同一密钥验证 RS256 令牌则失败。

  检查记录

  fact jwt-algorithm-allowlist = from-key
  evidence jwt-algorithm-allowlist: no algs argument: verified; RS256 token with the EC key: InvalidJWSSignature: Verification failed for all signatures["Failed: [InvalidJWSSignature('Verification failed')]"]

• 未签名的令牌（alg none）

  opt-in

  默认情况下，未签名的令牌会报错 Algorithm not allowed，只有设置 algs=["none"] 时才能验证通过。

  检查记录

  fact jwt-alg-none = opt-in
  evidence jwt-alg-none: with the EC key: InvalidJWSSignature: Verification failed for all signatures["Failed: [InvalidJWSOperation('Algorithm not allowed')]"]
  evidence jwt-alg-none: algs ['none'] with an empty oct key: verified

• 把公钥用作 HMAC 密钥

  rejected

  用 EC 公钥 JWK 检查 HS256 令牌失败；只有特意构造、包含 PEM 文本的 oct JWK 才让它验证通过。

  检查记录

  fact jwt-hmac-public-key = rejected
  evidence jwt-hmac-public-key: HS256 token checked with the EC public JWK: InvalidJWSSignature: Verification failed for all signatures["Failed: [InvalidJWSSignature('Verification failed')]"]
  evidence jwt-hmac-public-key: only an explicit oct JWK made from the PEM text verifies it: True

• 按 alg 检查曲线

  enforced

  用 P-384 密钥签名 ES256 时抛出 Curve requested is "P-256", but key curve is "P-384"。

  检查记录

  fact jwt-ecdsa-curve-check = enforced
  evidence jwt-ecdsa-curve-check: InvalidJWKValue: Curve requested is "P-256", but key curve is "P-384"

• 默认时钟偏差

  60s

  过期检查默认容许 60 秒的时钟偏差：57 秒前过期的令牌验证通过，63 秒前过期的则未通过。

  检查记录

  fact jwt-clock-skew = 60s

• 是否要求过期时间声明

  no

  不含 exp 的令牌验证通过；在 check_claims 中列出 exp 即可将其设为必需。

  检查记录

  fact jwt-exp-required = no
  evidence jwt-exp-required: verified

用法

import json
import time

from jwcrypto import jwk, jwt

key = jwk.JWK.generate(kty="EC", crv="P-256", kid="2026-10")
public = jwk.JWK.from_json(key.export_public())

token = jwt.JWT(header={"alg": "ES256", "kid": "2026-10"}, claims={"sub": "user-42", "iss": "https://auth.example.com", "exp": int(time.time()) + 600})
token.make_signed_token(key)

# algs narrows the default list; check_claims makes iss and exp mandatory.
checked = jwt.JWT(
    jwt=token.serialize(),
    key=public,
    algs=["ES256"],
    check_claims={"iss": "https://auth.example.com", "exp": None},
)
print("sub:", json.loads(checked.claims)["sub"])