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 ¶
- 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
- type SymmetricSigner
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)。对称形态 (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 ¶
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 构造已过期令牌 做校验测试)。
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。