Documentation
¶
Overview ¶
Package signverify 提供基于 HMAC-SHA256 的 HTTP 请求签名校验中间件。
签名公式（默认）：hex(HMAC-SHA256(secret, timestamp + userID + body))
请求需携带以下 header（名称均可自定义）：
- X-App-Id: 调用方标识，用于查找对应的 secret
- X-Timestamp: Unix 秒级时间戳，超过 MaxAge 则拒绝
- X-Sign: 请求签名
- X-User-Id: 用户标识（参与签名计算，防止篡改）
可选功能：WithExtractUser() 在签名校验通过后自动将 X-User-Id 写入 auth.User context，下游通过 auth.GetUserFromContext 读取。
典型用法：
getSecret := func(appID string) ([]byte, bool) { return secrets[appID] }
mux.Use(signverify.HTTPMiddleware(getSecret,
signverify.WithExtractUser(),
signverify.WithSkipPrefixes("/healthz", "/callback/"),
))
Index ¶
- Constants
- func DeriveKey(masterKey []byte, unixTimestamp int64, windowSec int64) []byte
- func HTTPMiddleware(getSecret SecretFunc, opts ...Option) func(http.Handler) http.Handler
- func Sign(secret []byte, timestamp, userID string, body []byte) string
- type Option
- func WithAppIDHeader(name string) Option
- func WithDerivedKey(windowSec int64) Option
- func WithExtractUser() Option
- func WithMaxAge(d time.Duration) Option
- func WithRejectHandler(fn func(w http.ResponseWriter, reason string)) Option
- func WithSecretDeriver(fn SecretDeriver) Option
- func WithSignHeader(name string) Option
- func WithSkipPrefixes(prefixes ...string) Option
- func WithTimestampHeader(name string) Option
- func WithUserIDHeader(name string) Option
- type SecretDeriver
- type SecretFunc
Constants ¶
const DefaultWindowSec int64 = 300
DefaultWindowSec 派生 key 的默认时间窗口（秒）。
Variables ¶
This section is empty.
Functions ¶
func DeriveKey ¶ added in v0.3.2
DeriveKey 从 masterKey + 时间窗口编号派生短时效签名 key。 window = floor(unixTimestamp / windowSec)，masterKey 始终不出现在网络上。
客户端用法：
ts := time.Now().Unix() dk := signverify.DeriveKey(masterSecret, ts, 300) sig := signverify.Sign(dk, strconv.FormatInt(ts, 10), userID, body)
func HTTPMiddleware ¶
HTTPMiddleware 返回 HMAC 签名校验 HTTP 中间件。 若配置了 WithSecretDeriver，则 getSecret 可传 nil。
Types ¶
type Option ¶
type Option func(*options)
Option 配置 SignVerify 中间件。
func WithAppIDHeader ¶
WithAppIDHeader 自定义 appID header 名称，默认 "X-App-Id"。
func WithDerivedKey ¶ added in v0.3.2
WithDerivedKey 启用基于时间窗口的 key 派生模式。
masterKey 始终不出现在网络上；客户端和服务端各自用 DeriveKey 从 masterKey 派生出短时效的 derivedKey 来签名。验签时自动尝试当前窗口和上一个窗口， 容忍窗口边界漂移。
windowSec 为时间窗口秒数，传 0 使用默认值 300（5 分钟）。
用法：
signverify.HTTPMiddleware(getSecret, signverify.WithDerivedKey(300))
func WithExtractUser ¶
func WithExtractUser() Option
WithExtractUser 启用后，签名校验通过时自动将用户标识 header 的值写入 auth.User context（通过 auth.WithUser），下游用 auth.GetUserFromContext 读取。
func WithRejectHandler ¶
func WithRejectHandler(fn func(w http.ResponseWriter, reason string)) Option
WithRejectHandler 自定义拒绝响应。reason 可能为： "missing_headers"、"invalid_timestamp"、"timestamp_expired"、"unknown_app"、"signature_mismatch"。
func WithSecretDeriver ¶ added in v0.3.2
func WithSecretDeriver(fn SecretDeriver) Option
WithSecretDeriver 使用完全自定义的动态 key 派生替代静态 SecretFunc。 设置后 HTTPMiddleware 的 getSecret 参数将被忽略。
func WithSignHeader ¶
WithSignHeader 自定义签名 header 名称，默认 "X-Sign"。
func WithSkipPrefixes ¶
WithSkipPrefixes 指定跳过校验的 URL 路径前缀。
func WithTimestampHeader ¶
WithTimestampHeader 自定义时间戳 header 名称，默认 "X-Timestamp"。
func WithUserIDHeader ¶
WithUserIDHeader 自定义用户标识 header 名称，默认 "X-User-Id"。
type SecretDeriver ¶ added in v0.3.2
SecretDeriver 根据 appID 和请求上下文动态派生 secret。 适用于基于请求内容（时间戳、region 等）派生密钥的场景，如 AWS SigV4 风格。
type SecretFunc ¶
SecretFunc 根据 appID 查找静态 secret。返回 false 表示未知 appID。
Source Files