jwt

package
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 8, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

HS256 对称形态(#86):与 RS256(jwt.go)并列的第二种主流 JWT 形态——共享密钥 HMAC。内网 SSO / 网关注入 / 服务间对等约定场景没有证书分发问题,IdP 与资源服务 约定一个 secret 即可;此前该场景下游各自手搓三段式解析 + HMAC 校验 + claims 校验(alg 混淆、hmac.Equal 常量时间比较、aud 双形态解析等坑每份实现各踩一遍), 库侧一份正确实现收编整个面。

Package jwt 提供 JWT 签发与校验,覆盖两种主流形态:RS256(非对称密钥对, Sign/Parse)与 HS256(对称共享密钥,SymmetricSigner/ParseSymmetric,#86)。

两形态共享同一套 SignOption/ParseOption/Claims 与校验语义;每个入口固定自己 的算法(RS256 入口只认 RS256、HS256 入口只认 HS256),密钥形态绑定算法关死 alg 混淆。

硬契约(与既有消费方互通,不可改):

  • RS256 形态 alg 恰为 RS256;HS256 形态 alg 恰为 HS256
  • JWT header 只含 {"alg":"<alg>"},不带 typ
  • 业务自定义声明平铺进 payload,解析时收集进 Claims.Extra

Index

Constants

This section is empty.

Variables

View Source
var ErrInvalidToken = errors.New("jwt: invalid token")

ErrInvalidToken 表示令牌无法解析或校验失败。

Functions

func MarshalKeyPairPEM

func MarshalKeyPairPEM(kp *KeyPair) (privPEM, pubPEM string, err error)

MarshalKeyPairPEM 把密钥对编为 PEM(私钥 PKCS#1,公钥 PKIX)。

func ParsePrivateKey

func ParsePrivateKey(pemBytes []byte) (*rsa.PrivateKey, error)

ParsePrivateKey 解析 PEM 私钥(PKCS#1 / PKCS#8)。

func ParsePublicKey

func ParsePublicKey(pemBytes []byte) (*rsa.PublicKey, error)

ParsePublicKey 解析 PEM 公钥(PKIX / PKCS#1),也接受 X.509 证书。

func Sign

func Sign(kp *KeyPair, opts ...SignOption) (string, error)

Sign 用 RS256 签发令牌。缺省 iat = time.Now()、ttl = 24h;可用 WithNow/ WithIssuedAt 注入签发时刻(iat 与 exp 同钟源),WithNoExpiry 显式去掉 exp。 对称形态(HS256 共享密钥)见 SymmetricSigner(#86)。

Types

type Claims

type Claims struct {
	gojwt.RegisteredClaims
	// Extra 承载业务自定义声明(签发时经 WithClaim 平铺进 payload,解析时收集回来)。
	Extra map[string]any
}

Claims 是签发与解析的载荷容器。

func Parse

func Parse(token string, pub *rsa.PublicKey, opts ...ParseOption) (*Claims, error)

Parse 校验并解析令牌(RS256-only,缺省零 leeway、不校验 aud)。对称形态 (HS256 共享密钥)见 ParseSymmetric(#86)——两入口共享校验语义。

错误链保留(#70):失败时外层哨兵 ErrInvalidToken 与 gojwt 底层 sentinel (ErrTokenExpired/ErrTokenSignatureInvalid/ErrTokenNotValidYet 等)同时可 errors.Is——业务侧可据此分流「过期→走刷新、签名坏→踢下线」。

已注册声明(iss/sub/aud/jti/exp/iat/nbf)收进 RegisteredClaims;其余进 Extra。 iss/sub/jti 存在但非字符串时拒绝(#67):RFC 7519 §4.1.1/§4.1.2 要求 iss/sub MUST be a String,类型异常即规格违规令牌,fail-closed 而非静默归零放行 (golang-jwt 上游 MapClaims.GetSubject 对类型异常同样返回错误);声明缺失 维持零值不报错——缺失声明的令牌按消费方自身的校验责任走。

func ParseSymmetric added in v0.5.0

func ParseSymmetric(token string, secret []byte, opts ...ParseOption) (*Claims, error)

ParseSymmetric 校验并解析 HS256 令牌——与 Parse(RS256)同构(#86):同 Claims (注册声明收进 RegisteredClaims、其余进 Extra)、同 ParseOption(WithLeeway/ WithAudience)、同错误链(外层哨兵 ErrInvalidToken 与 gojwt 底层 sentinel ErrTokenExpired/ErrTokenSignatureInvalid 等双可 errors.Is,#70)。

alg 混淆防护(#86):入口绑定算法——gojwt.WithValidMethods(["HS256"]) 单算法 白名单,RS256 令牌(无论密钥对真假)在本入口一律拒绝;RS256 的 Parse 同理只认 RS256。密钥形态绑定算法,杜绝「用 HMAC 密钥校验非对称签名」的经典 CVE 形态。

type KeyPair

type KeyPair struct {
	Private *rsa.PrivateKey
	Public  *rsa.PublicKey
}

KeyPair 持有 RS256 的密钥对。

func GenerateKeyPair

func GenerateKeyPair(bits int) (*KeyPair, error)

GenerateKeyPair 生成 RSA 密钥对(bits < 2048 时按 2048 处理)。

type ParseOption

type ParseOption func(*parseOptions)

ParseOption 是 Parse 的函数选项。

func WithAudience added in v0.4.2

func WithAudience(expected ...string) ParseOption

WithAudience 设置期望受众(#66):令牌 aud 命中任一即通过;令牌无 aud 时 拒绝(fail-closed)。不设置时不校验 aud(向后兼容)——签名校验只证明 「是我的 key 签的」,不证明「是签给我的」;同密钥多受众场景必须显式配置。

func WithLeeway

func WithLeeway(d time.Duration) ParseOption

WithLeeway 设置时钟偏移容忍。

type SignOption

type SignOption func(*signOptions)

SignOption 是 Sign 的函数选项。

func WithClaim

func WithClaim(key string, val any) SignOption

WithClaim 追加一个业务自定义声明。

注册声明(iss/sub/aud/exp/nbf/iat/jti)不可经 WithClaim 注入,注入时 Sign 直接报错(#71):Sign 先写注册声明、最后平铺 claims,无条件覆盖会让 WithClaim("exp", ...) 顶掉过期时间、WithClaim("iss", externalInput) 篡改 签发者——claim key 若来自配置/请求拼接,就是令牌声明注入面。注册声明请用 WithIssuer/WithSubject/WithJTI/WithNotBefore 设置,exp/iat 由 WithTTL 与 签发时钟派生。

func WithIssuedAt added in v0.4.2

func WithIssuedAt(t time.Time) SignOption

WithIssuedAt 显式设置签发时刻:iat = t、exp = t + ttl,等价于 WithNow( 固定返回 t)。带显式签发时刻的签发面(如消费方 Issue(..., now time.Time) 参数形态)委托本包时用它透传 now,缺省行为不变(#64)。

func WithIssuer

func WithIssuer(iss string) SignOption

WithIssuer 设置 iss。

func WithJTI

func WithJTI(jti string) SignOption

WithJTI 设置 jti(令牌 ID)。

func WithNoExpiry added in v0.4.2

func WithNoExpiry() SignOption

WithNoExpiry 显式签发无 exp 的令牌(#65):名字本身即审计信号,grep 得到。 无 exp 令牌一旦泄漏没有自然失效路径,仅供确有轮换/吊销机制的场景;与 WithTTL 并用时后应用的生效。

func WithNotBefore

func WithNotBefore(t time.Time) SignOption

WithNotBefore 设置 nbf。

func WithNow added in v0.4.2

func WithNow(f func() time.Time) SignOption

WithNow 注入签发时钟:iat = now()、exp = iat + ttl 同钟源(nbf 仍取 WithNotBefore 的绝对时刻)。缺省 time.Now(#64:缺省行为不变);f 为 nil 直接 panic——静默回落真实时钟会让 iat 无声漂移。测试可注入假时钟获得 确定性令牌,不再只能断言 iat≈now 的区间。

func WithSubject

func WithSubject(sub string) SignOption

WithSubject 设置 sub。

func WithTTL

func WithTTL(d time.Duration) SignOption

WithTTL 设置 exp = iat + ttl。d 为 0 直接 panic(#65):显式 0 与「未设置」 不可区分,而最可能的成因是「配置缺失的零值透传」——静默接受等于放行一批 永不过期的凭据,与 uidgen.RandomHex 拒绝空串密钥(#50)同款纪律。确需无 过期令牌请显式 WithNoExpiry。负值不拦(既有消费方用负 ttl 构造已过期令牌 做校验测试)。

type SymmetricSigner added in v0.5.0

type SymmetricSigner struct {
	// contains filtered or unexported fields
}

SymmetricSigner 持有 HS256 共享密钥的签发器(对称形态,与 KeyPair/RS256 并列)。 签发选项与 RS256 形态同一套 SignOption,签发语义完全一致(#86)。

func NewSymmetric added in v0.5.0

func NewSymmetric(secret []byte) (*SymmetricSigner, error)

NewSymmetric 用共享密钥构造 HS256 签发器。

secret 缺失或长度 < 32 字节(RFC 7518 §3.2 下限)直接报错 fail-fast(#86): 与全仓「配置错误宁可启动即暴露」哲学一致,不能等到首个令牌校验时才见分晓, 也不设「静默接受短密钥」的兼容路径。

func (*SymmetricSigner) Sign added in v0.5.0

func (s *SymmetricSigner) Sign(opts ...SignOption) (string, error)

Sign 用 HS256 签发令牌:选项与签发语义(缺省 ttl=24h、iat/exp 同钟源、注册 声明注入面防护 #71)与 RS256 的 Sign 完全同一套(#86)。header 硬契约同形态: 只含 {"alg":"HS256"},不带 typ。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL