BFE mod_secure_link 模块实战:链接签名校验、防盗链与时效控制
BFE mod_secure_link 模块实战:链接签名校验、防盗链与时效控制
导读
本文聚焦 BFE(七层负载均衡器)内置的 mod_secure_link 模块,讲解如何通过模块配置与规则配置对请求链接进行签名校验,从而保护资源不被未授权访问,并限制链接的有效期。读完本文,你将掌握 mod_secure_link.conf 与 secure_link_rule.data 的完整配置语法、六种表达式节点(ExpressionNode)的计算逻辑、签名生成与校验的底层算法,以及模块暴露的 7 个监控指标的含义。
mod_secure_link 是 BFE 中典型的"请求校验型"模块:它不修改请求内容,只在路由定位之后对请求做合法性检查,非法请求直接返回 403。其核心思路是:请求方在生成链接时,把"过期时间 + 若干请求特征 + 密钥"拼接成原文,经 MD5 + Base64 变形后作为校验和放入 URL 参数;BFE 收到请求后按相同规则重新计算校验和并比对,同时检查过期时间,从而同时实现防盗链与链接时效控制。
模块简介与校验流程
mod_secure_link 用于检查请求链接的真实性(authenticity),防止资源被未授权访问,并限制链接的生命周期。从源码看,该模块在 Init() 中注册了两个钩子(见 mod_secure_link.go):
bfe_module.HandleAfterLocation过滤器:在请求完成路由定位后执行validateHandler,对请求做校验;web_monitor.WebHandleReload处理器:支持通过监控接口热加载规则数据。
validateHandler 的处理逻辑(mod_secure_link.go)可概括为:
- 按请求所属产品(
request.Route.Product)在规则表中查找规则;若该产品没有规则,直接放行; - 逐条匹配规则的
Cond条件表达式,命中的规则才参与校验; - 校验通过 → 计数
ReqAccept并放行(BfeHandlerGoOn); - 校验失败 → 根据具体错误类型累加对应指标,并返回
403响应(BfeHandlerResponse)。
校验过程中可能出现的 5 类错误与源码中定义的错误对象一一对应(checker.go):
| 错误 | 含义 | 触发场景 |
|---|---|---|
ErrReqWithoutExpiresKey |
缺少过期时间参数 | 请求 URL 中没有 ExpiresKey 指定的参数 |
ErrReqInvalidExpiresValue |
过期时间非法 | ExpiresKey 参数无法解析为整数 |
ErrReqExpired |
链接已过期 | time.Now().Unix() > expiredUnix |
ErrReqWithoutChecksumKey |
缺少校验和参数 | 请求 URL 中没有 ChecksumKey 指定的参数 |
ErrReqInvalidChecksum |
校验和不匹配 | 重算出的签名与请求携带的签名不一致 |
模块基础配置:mod_secure_link.conf
模块的基础配置文件为 conf/mod_secure_link/mod_secure_link.conf,完整参数说明见 mod_secure_link 基础配置文档。它只负责两件事:规则数据文件路径与调试开关。
| 配置项 | 类型 | 含义 | 必填 | 补充说明 |
|---|---|---|---|---|
Basic.DataPath |
String | 规则配置文件路径 | 是 | 默认值为 mod_secure_link/secure_link_rule.data;类型为 FilePath,文件必须存在且可读 |
Log.OpenDebug |
Boolean | 模块调试开关 | 否 | - |
标准配置示例:
[Basic]
DataPath = ./mod_secure_link/secure_link_rule.data
[Log]
OpenDebug = true
从源码 conf_load.go 可以看到两个关键行为:若 DataPath 未设置,模块会打印告警并使用默认值 mod_secure_link/secure_link.data;随后该路径会经过 bfe_util.ConfPathProc 结合配置根目录(confRoot)处理成绝对路径。仓库自带的示例配置 conf/mod_secure_link/mod_secure_link.conf 内容与上述格式一致,可直接作为部署参考。
规则配置:secure_link_rule.data
规则文件 secure_link_rule.data 是 JSON 格式,完整参数说明见 mod_secure_link 规则配置文档。其顶层结构按产品(product)维度组织规则列表。
| 配置项 | 类型 | 含义 | 必填 | 补充说明 |
|---|---|---|---|---|
Version |
String | 配置文件版本号 | 是 | 通常为时间戳,如 2019-12-10184356;类型为 Version |
Config |
Object | 各产品的规则集合 | 是 | Key 为产品名 |
Config{k} |
String | 产品名称 | 是 | - |
Config{v} |
Array | 规则列表 | 是 | - |
Config{v}<a href="https://link.gitcode.com/i/4b32aa89f246a850d3635276b746047f" target="_blank">].Cond |
String | 条件表达式 | 是 | 语法参见 [条件表达式语法 |
Config{v}[].ChecksumKey |
String | 存放校验和的 Query 参数名 | 是 | - |
Config{v}[].ExpiresKey |
String | 存放过期时间的 Query 参数名 | 是 | - |
Config{v}[].ExpressionNodes |
Array | 参与校验和计算的节点 | 是 | - |
Config{v}[].ExpressionNodes[].Type |
String | 节点类型 | 是 | 合法值见下文"节点类型" |
Config{v}[].ExpressionNodes[].Param |
String | 节点取值参数 | 条件必填 | 当 Type 为 label、query、header 时必须提供 |
一个完整规则示例:
{
"Version": "2019-12-10184356",
"Config": {
"p1": [{
"Cond": "default_t()",
"ChecksumKey": "sign",
"ExpiresKey": "time",
"ExpressionNodes": [{
"Type": "query",
"Param": "time"
},
{
"Type": "uri"
},
{
"Type": "remote_addr"
},
{
"Type": "label",
"Param": " secret"
}
]
}]
}
}
几点值得注意的实现细节(依据 data_load.go):
Cond会被condition.Build()编译成条件对象,规则在请求校验前先做条件匹配;ChecksumKey未显式配置时默认取"md5";若显式配置为空字符串则报错;ExpressionNodes为 nil 时直接判定为非法规则;Version与Config缺失时加载失败(bad Version node/bad Config node)。
仓库测试数据 testdata/mod_secure_link/secure_link_rule.data 展示了同一产品 p1 配置 ChecksumKey/ExpiresKey、产品 p2 不配置这两个 key(使用默认值 md5)两种写法,可作为理解"默认值生效"行为的参考。
节点类型与校验和计算逻辑
ExpressionNodes 中的每个节点按顺序拼接出一个字符串(原始原文 origin),其取值逻辑由 checker.go 中对应节点实现确定:
| Type | 计算逻辑 | 对应源码实现 |
|---|---|---|
label |
直接取 $Param 字符串(常用于注入密钥) |
labelNode.Value 返回固定值 |
query |
取 req.URL.Query($Param) 的查询参数值 |
queryNode.Value 调用 CachedQuery().Get(key) |
header |
取 req.Header.Get($Param) 的请求头值 |
headerNode.Value |
host |
取 req.Host |
hostNode.Value |
uri |
取 req.RequestURI(原始请求 URI,含路径与查询串) |
uriNode.Value |
remote_addr |
取 req.RemoteAddr(客户端地址) |
remoteAddrNode.Value |
Expression.Value() 将各节点结果按顺序写入同一个缓冲区拼接为原始字符串(checker.go)。因此,示例配置生成的原文为:
{expires}{req.RequestURI}{req.RemoteAddr}{labelParam}
即 "2147483647/s/link127.0.0.1 secret" 这类形态(过期时间 + URI + 客户端地址 + 密钥)。将密钥放在 label 节点中、与请求特征拼接后再做签名,是典型的 HMAC 式防篡改设计。
签名生成与校验算法
校验和(sign)的编码算法由 Checker.encode() 实现(checker.go),规则文档中以伪代码完整给出了生成链接的步骤:
func WrapSecureLinkParam (req *http.Request) {
now := time.Now().Unix()
expires := now + int64(time.Hour*24/time.Second)
// step1: get origin data
origin := fmt.Sprintf("%d%s%s%s", expires, req.RequestURI, req.RemoteAddr, " secret")
// step2: generator sign
sign := func(origin string) string {
tmpB := md5.Sum([]byte(origin))
tmp := base64.StdEncoding.EncodeToString(tmpB[:])
tmp = strings.ReplaceAll(tmp, "+", "-")
tmp = strings.ReplaceAll(tmp, "/", "_")
tmp = strings.ReplaceAll(tmp, "=", "")
return tmp
}
// step3: generate link
req.URL.Query().Set("sign", sign(origin))
req.URL.Query().Set("time", fmt.Sprintf("%d", expires))
}
编码过程与 Go 源码中的 encode() 完全一致:MD5 摘要 → 标准 Base64 编码 → 将 + 替换为 -、/ 替换为 _、去掉末尾的 =。这样得到的字符串可直接安全地放进 URL 而无需转义。该算法同样可以在 shell 中复现,便于在脚本、CDN 或客户端侧生成签名链接:
echo -n $origin | openssl md5 -binary | openssl base64 | tr +/ -_ | tr -d =
# 示例:
echo -n '2147483647/s/link127.0.0.1 secret' | openssl md5 -binary | openssl base64 | tr +/ -_ | tr -d =
# 输出:_e4Nc3iduzkWRm01TBBNYw
服务端校验流程对应 checker.go 的 Check(),顺序为:先取 ExpiresKey 参数(缺失 → ErrReqWithoutExpiresKey,非数字 → ErrReqInvalidExpiresValue,当前时间晚于过期时间 → ErrReqExpired),再取 ChecksumKey 参数(缺失 → ErrReqWithoutChecksumKey),最后用 ExpressionNodes 重算原文并 encode(),与请求携带的签名比对,不一致 → ErrReqInvalidChecksum。
规则加载与热更新
规则数据支持运行时热加载。模块初始化时把规则文件一次性载入内存中的 SecureLinkTable(prodcut_table.go),表内使用 sync.RWMutex 保护读写:
Update(conf):整表替换productRules与version;Search(product):按产品名取规则列表。
热加载通过 Web 监控接口触发:loadConfData(query) 支持通过 URL 参数 path 指定新规则文件路径;未指定时使用配置中的默认路径(mod_secure_link.go)。加载完成后调用 DataLoad 解析 JSON 并经 NewData 逐产品、逐规则构建 Rule,任一节点非法都会导致整次加载失败并返回错误,避免半更新状态。
监控指标
模块通过 web-monitor/metrics 暴露 7 个计数器指标(定义见 mod_secure_link.go),完整列表如下:
| Metric | Description |
|---|---|
REQ_TOTAL |
Total count of requests(进入校验的请求总数) |
REQ_ACCEPT |
Count of accepted requests(校验通过的请求数) |
REQ_WITHOUT_EXPIRES_KEY |
Count of requests missing expires key(缺少过期时间参数的请求数) |
REQ_INVALID_EXPIRES_VALUE |
Count of requests with invalid expires value(过期时间非法的请求数) |
REQ_WITHOUT_CHECKSUM_KEY |
Count of requests missing checksum key(缺少校验和参数的请求数) |
REQ_INVALID_CHECKSUM |
Count of requests with invalid checksum(校验和不匹配的请求数) |
REQ_EXPIRED |
Count of expired requests(链接已过期的请求数) |
指标名以 mod_secure_link 为前缀注册。运维上可重点关注 REQ_EXPIRED 与 REQ_INVALID_CHECKSUM 的占比:前者异常升高通常说明链接时效设置过短或客户端时钟偏差;后者异常升高则往往意味着密钥泄露、签名算法实现不一致,或存在恶意构造的请求。
实践要点小结
- 密钥管理:
label节点中的密钥(如示例中的" secret")应视为机密,仅部署在可信的签名生成方(如应用服务器或 CDN 边缘)与 BFE 之间,避免出现在前端代码中; - 节点顺序即签名顺序:
ExpressionNodes中节点顺序决定原文拼接顺序,生成与校验两侧必须完全一致,否则签名必然不匹配; - 时效粒度:过期时间以 Unix 秒为单位,生成链接时按需设置有效期(示例中为 24 小时);BFE 只校验"当前时间 ≤ 过期时间",不校验链接是否已被使用;
- 按产品隔离:规则按产品名(
Config的 key)组织,未配置规则的产品默认全部放行,不影响既有业务; - 调试与热加载:开启
Log.OpenDebug可辅助排查校验差异;规则文件变更可通过监控接口即时生效,无需重启 BFE。