jwt

package
v0.4.2 Latest Latest
Warning

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

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

Documentation

Overview

Package jwt 提供 RS256 的 JWT 签发与校验。

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

  • alg 恰为 RS256
  • JWT header 只含 {"alg":"RS256"},不带 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。

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)。

错误链保留(#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 对类型异常同样返回错误);声明缺失 维持零值不报错——缺失声明的令牌按消费方自身的校验责任走。

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 构造已过期令牌 做校验测试)。

Jump to

Keyboard shortcuts

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