Documentation
¶
Overview ¶
Package jwt 提供 RS256 的 JWT 签发与校验。
硬契约(与既有消费方互通,不可改):
- alg 恰为 RS256
- JWT header 只含 {"alg":"RS256"},不带 typ
- 业务自定义声明平铺进 payload,解析时收集进 Claims.Extra
Index ¶
- Variables
- func MarshalKeyPairPEM(kp *KeyPair) (privPEM, pubPEM string, err error)
- func ParsePrivateKey(pemBytes []byte) (*rsa.PrivateKey, error)
- func ParsePublicKey(pemBytes []byte) (*rsa.PublicKey, error)
- func Sign(kp *KeyPair, opts ...SignOption) (string, error)
- type Claims
- type KeyPair
- type ParseOption
- type SignOption
- func WithClaim(key string, val any) SignOption
- func WithIssuedAt(t time.Time) SignOption
- func WithIssuer(iss string) SignOption
- func WithJTI(jti string) SignOption
- func WithNoExpiry() SignOption
- func WithNotBefore(t time.Time) SignOption
- func WithNow(f func() time.Time) SignOption
- func WithSubject(sub string) SignOption
- func WithTTL(d time.Duration) SignOption
Constants ¶
This section is empty.
Variables ¶
var ErrInvalidToken = errors.New("jwt: invalid token")
ErrInvalidToken 表示令牌无法解析或校验失败。
Functions ¶
func MarshalKeyPairPEM ¶
MarshalKeyPairPEM 把密钥对编为 PEM(私钥 PKCS#1,公钥 PKIX)。
func ParsePrivateKey ¶
func ParsePrivateKey(pemBytes []byte) (*rsa.PrivateKey, error)
ParsePrivateKey 解析 PEM 私钥(PKCS#1 / PKCS#8)。
func ParsePublicKey ¶
ParsePublicKey 解析 PEM 公钥(PKIX / PKCS#1),也接受 X.509 证书。
Types ¶
type Claims ¶
type Claims struct {
gojwt.RegisteredClaims
// Extra 承载业务自定义声明(签发时经 WithClaim 平铺进 payload,解析时收集回来)。
Extra map[string]any
}
Claims 是签发与解析的载荷容器。
func Parse ¶
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 ¶
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 签的」,不证明「是签给我的」;同密钥多受众场景必须显式配置。
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 WithNoExpiry ¶ added in v0.4.2
func WithNoExpiry() SignOption
WithNoExpiry 显式签发无 exp 的令牌(#65):名字本身即审计信号,grep 得到。 无 exp 令牌一旦泄漏没有自然失效路径,仅供确有轮换/吊销机制的场景;与 WithTTL 并用时后应用的生效。
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 WithTTL ¶
func WithTTL(d time.Duration) SignOption
WithTTL 设置 exp = iat + ttl。d 为 0 直接 panic(#65):显式 0 与「未设置」 不可区分,而最可能的成因是「配置缺失的零值透传」——静默接受等于放行一批 永不过期的凭据,与 uidgen.RandomHex 拒绝空串密钥(#50)同款纪律。确需无 过期令牌请显式 WithNoExpiry。负值不拦(既有消费方用负 ttl 构造已过期令牌 做校验测试)。