go-jose

事实及其依据的检查

以下内容均非抄自文档。检查脚本 content/libraries/verify/go-jose/run.sh 于2026年10月20日在容器镜像 golang:1.27.3-trixie 中运行了 go-jose 4.1.6；本页内容必须与它的输出一致，每条事实都列出了对应的输出行。

• JWS 算法

  HS256HS384HS512RS256RS384RS512PS256PS384PS512ES256ES384ES512EdDSA

  256/384/512 位的 HS、RS、PS 和 ES 以及 EdDSA 的签名与验证均成功；ES256K、Ed25519 和 Ed448 报错 unknown/unsupported algorithm。

  检查记录

  fact jws-algorithms = HS256, HS384, HS512, RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, EdDSA
  evidence jws-algorithms: ES256K: go-jose/go-jose: unknown/unsupported algorithm
  evidence jws-algorithms: Ed25519: go-jose/go-jose: unknown/unsupported algorithm
  evidence jws-algorithms: Ed448: go-jose/go-jose: unknown/unsupported algorithm

• ES256 签名编码

  raw

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

  检查记录

  fact jws-ecdsa-encoding = raw

• JWS 中的 DER 签名

  rejected

  DER 编码的 ES256 签名会报错 go-jose/go-jose: error in cryptographic primitive。

  检查记录

  fact jws-der-signature = rejected
  evidence jws-der-signature: go-jose/go-jose: error in cryptographic primitive

• 算法允许列表

  required

  jwt.ParseSigned 要求传入允许的算法；列表为空时报错 no signature algorithms specified。

  检查记录

  fact jwt-algorithm-allowlist = required
  evidence jwt-algorithm-allowlist: ParseSigned with an empty algorithm list: go-jose/go-jose: no signature algorithms specified

• 未签名的令牌（alg none）

  rejected

  列表中包含 none 时，未签名的令牌可以解析，但无论使用 EC 密钥还是 HMAC 密钥，Claims() 都会失败；只有 UnsafeClaimsWithoutVerification 能读取它。

  检查记录

  fact jwt-alg-none = rejected
  evidence jwt-alg-none: ParseSigned with none in the list: <nil>
  evidence jwt-alg-none: Claims(*ecdsa.PublicKey): go-jose/go-jose: error in cryptographic primitive
  evidence jwt-alg-none: Claims([]uint8): go-jose/go-jose: error in cryptographic primitive
  evidence jwt-alg-none: UnsafeClaimsWithoutVerification: <nil>, sub fact-check

• 把公钥用作 HMAC 密钥

  rejected

  以 PEM 文本为密钥的 HS256 令牌，用 *ecdsa.PublicKey 验证失败；只有把 PEM 字节本身作为密钥传入时才验证通过。

  检查记录

  fact jwt-hmac-public-key = rejected
  evidence jwt-hmac-public-key: Claims with the *ecdsa.PublicKey: go-jose/go-jose: error in cryptographic primitive
  evidence jwt-hmac-public-key: Claims with the PEM bytes as key: <nil>

• 按 alg 检查曲线

  enforced

  用 P-384 密钥签名 ES256 时报错 expected 256 bit key, got 384 bits instead。

  检查记录

  fact jwt-ecdsa-curve-check = enforced
  evidence jwt-ecdsa-curve-check: go-jose/go-jose: expected 256 bit key, got 384 bits instead

• 解码时校验声明

  no

  对于一小时前就已过期的令牌，Claims() 照样返回了声明，没有报错；时间和颁发者检查只在 Validate 中进行。

  检查记录

  fact jwt-claims-validated-on-decode = no
  evidence jwt-claims-validated-on-decode: Claims() on a token expired an hour ago: <nil>

• 默认时钟偏差

  60s

  Validate 允许 jwt.DefaultLeeway，即一分钟的容差：57 秒前过期的令牌通过了，63 秒前过期的令牌未通过。

  检查记录

  fact jwt-clock-skew = 60s
  evidence jwt-clock-skew: jwt.DefaultLeeway = 1m0s

• 是否要求过期时间声明

  no

  不含 exp 的令牌通过了 Validate；需要自行检查 Expiry 是否不为 nil。

  检查记录

  fact jwt-exp-required = no

用法

package main

import (
	"crypto/ecdsa"
	"crypto/elliptic"
	"crypto/rand"
	"fmt"
	"time"

	jose "github.com/go-jose/go-jose/v4"
	"github.com/go-jose/go-jose/v4/jwt"
)

func main() {
	key, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
	signer, _ := jose.NewSigner(jose.SigningKey{Algorithm: jose.ES256, Key: key}, (&jose.SignerOptions{}).WithType("JWT"))
	raw, _ := jwt.Signed(signer).Claims(jwt.Claims{Subject: "user-42", Issuer: "https://auth.example.com", Expiry: jwt.NewNumericDate(time.Now().Add(10 * time.Minute))}).Serialize()

	// v4 requires the allowed algorithms when parsing.
	token, _ := jwt.ParseSigned(raw, []jose.SignatureAlgorithm{jose.ES256})
	claims := jwt.Claims{}
	sigErr := token.Claims(&key.PublicKey, &claims) // checks the signature only
	// Validate checks exp, nbf and iss (with jwt.DefaultLeeway of one minute).
	valErr := claims.Validate(jwt.Expected{Issuer: "https://auth.example.com", Time: time.Now()})
	fmt.Println("valid:", sigErr == nil && valErr == nil && claims.Expiry != nil, "sub:", claims.Subject)
}