BFE mod_key_log 模块:基于 NSS Key Log 格式的 TLS 会话密钥导出与解密排障指南
BFE mod_key_log 模块:基于 NSS Key Log 格式的 TLS 会话密钥导出与解密排障指南
mod_key_log 是 BFE(百度开源的企业级七层负载均衡)中用于 TLS 排障的辅助模块:它按照 NSS Key Log 标准格式,把 TLS 握手中的 ClientRandom 与 MasterSecret 写入日志文件,从而让 Wireshark 等外部抓包工具能够解密 TLS 流量。本文基于 BFE 官方文档与仓库源码,讲解 mod_key_log 的模块配置、规则数据文件格式、条件匹配原理、日志轮转方式,并给出完整的启用与验证步骤,帮助读者快速搭建"抓包 + 解密"的 HTTPS 排障链路。
模块简介:为什么要导出 TLS 密钥
HTTPS 流量经过 TLS 加密后,抓包工具只能看到密文,无法直接定位 HTTP 层的问题。破解的常见手段是让服务端(BFE)在 TLS 握手时额外导出一份密钥日志(key log),抓包工具借助它还原会话密钥后即可解密整条连接。
mod_key_log 做的事正是这个:在 BFE 与客户端完成 TLS 握手后,以 NSS Key Log 格式把当前会话的随机数与主密钥写入日志,供外部程序(如 Wireshark)解密 TLS 连接,用于故障排查。NSS Key Log 格式由 Mozilla 定义,其核心是形如下面的一行记录:
CLIENT_RANDOM <ClientRandom-hex> <MasterSecret-hex>
在 BFE 源码中,这一行的生成逻辑位于 mod_key_log.go 的 logTlsKey 函数:将从 session.TlsState 中取出的 ClientRandom 与 MasterSecret 分别做十六进制编码,再拼接为上述格式写入日志。
安全提示:密钥日志等同于把会话密钥明文落盘,任何能读取该日志的人都能解密对应 TLS 流量。因此该模块应仅在排障期间按需开启,生产环境默认关闭(仓库默认配置
conf/bfe.conf中Modules = mod_key_log处于注释状态),并配合日志权限控制。
模块工作流程与源码解析
mod_key_log 的整体流程可以分为"规则匹配"与"密钥落盘"两步,全部实现集中在 bfe_modules/mod_key_log 目录:
- 注册回调阶段:
Init()通过cbs.AddFilter(bfe_module.HandleHandshake, m.logTlsKey)将logTlsKey注册到握手阶段处理器(HandleHandshake回调类型定义于 bfe_callback.go)。也就是说,BFE 每完成一次 TLS 握手都会进入该处理器,这保证了所有被 BFE 代理的 HTTPS 连接都有机会被记录。 - 规则匹配阶段:
isNeedKeyLog()先以session.Product(产品线)为键在规则表中查找规则列表;若未命中,则回退到bfe_basic.GlobalProduct(即global)继续查找;只有命中的产品才会进入下一步。规则列表按顺序逐条执行rule.Cond.Match(req)做条件匹配,任一条件满足即返回true。对应实现见 mod_key_log.go。 - 密钥落盘阶段:
logTlsKey在tlsState == nil(非 TLS 连接或状态缺失)时直接放行;否则拼装CLIENT_RANDOM ...记录并通过m.logger.Info(keyLog)写出,见 mod_key_log.go。 - 热加载阶段:
loadConfData被注册为 Web 监控的 reload 处理器(web_monitor.WebHandleReload),支持通过管理接口在不重启 BFE 的情况下重新加载规则数据文件,见 mod_key_log.go。
规则表本身由 KeyLogTable 承载,内部用 sync.RWMutex 保护 productRules,Update 整表替换、Search 按产品查询,实现在 key_log_table.go。
上述规则匹配与密钥落盘逻辑均有对应的单元测试覆盖,见 mod_key_log_test.go:TestLogTlsKey 验证命中规则的会话会正常写日志且返回 BfeHandlerGoOn;TestLogTlsKeyNotNeed 验证未命中产品的会话不写日志;TestLogTlsKeyNoTlsState 验证 TlsState 为空的会话直接放行。
模块配置文件 mod_key_log.conf
mod_key_log 的基础配置文件为 mod_key_log.conf(格式为 INI),它决定了两件事:规则数据文件路径(Basic.DataPath)与密钥日志的输出方式(Log 段)。配置项一览如下(来自 mod_key_log.conf.md):
| 配置项 | 类型 | 含义 | 必填 | 补充说明 | 生效条件 |
|---|---|---|---|---|---|
Basic.DataPath |
String | 规则配置文件路径 | Y | - | 类型为 FilePath;文件必须存在且可读 |
Log.LogFile |
String | 无轮转的日志文件路径 | N | 与 LogPrefix/LogDir/RotateWhen/BackupCount 互斥 |
类型为 FilePath;文件必须可写 |
Log.LogPrefix |
String | 日志文件名前缀 | N | 需与 LogDir/RotateWhen/BackupCount 搭配使用 |
- |
Log.LogDir |
String | 日志文件目录 | N | 需与 LogPrefix/RotateWhen/BackupCount 搭配使用 |
类型为 DirPath;目录必须存在且可读 |
Log.RotateWhen |
String | 日志轮转间隔 | N | 支持 M/H/D/MIDNIGHT/NEXTHOUR |
必须是合法的轮转间隔值 |
Log.BackupCount |
Integer | 保留的轮转日志最大份数 | N | - | 取值必须大于 0 |
关于类型 FilePath 与 DirPath:二者均支持相对路径(相对 BFE 配置根目录解析)或绝对路径(以 / 开头)。
配置校验逻辑
上述互斥与必填约束在源码中有严格校验:access_log.LogConfig.Check() 在 access_log.go 中实现——若设置了 LogFile,则 LogPrefix/LogDir/RotateWhen/BackupCount 四项均不允许再设置;反之若使用轮转模式,则 LogPrefix 与 LogDir 不能为空、RotateWhen 必须是合法值(log4go.WhenIsValid)、BackupCount 必须大于 0。ConfModKeyLog.Check 直接调用该逻辑,见 conf_mod_key_log.go。日志实际初始化走 access_log.LoggerInit:LogFile 非空时直接写入指定文件,否则生成 <LogPrefix>.log 并按 RotateWhen/BackupCount 轮转,见 access_log.go。
示例一:按目录轮转输出
以下配置把密钥日志写入 ../log 目录,文件名前缀为 key(实际文件为 key.log),每小时轮转一次并最多保留 3 份历史文件:
[Basic]
DataPath = mod_key_log/key_log.data
[Log]
# filename prefix for log
LogPrefix = key
# log directory
LogDir = ../log
# interval to rotate logs: M/H/D/MIDNIGHT/NEXTHOUR
# - M: minute
# - H: hour
# - D: day
RotateWhen = H
# max number of rotated log files
BackupCount = 3
仓库中 conf/mod_key_log/mod_key_log.conf 即采用轮转模式(RotateWhen = MIDNIGHT,每天零点轮转),可作为线上参考,见 conf/mod_key_log/mod_key_log.conf。
示例二:直接输出到标准输出
调试时若希望将密钥日志直接打到终端或由进程管理器统一采集,可以省略轮转参数、指定 LogFile:
[Basic]
DataPath = mod_key_log/key_log.data
[Log]
# filename prefix for log
LogFile = /dev/stdout
规则数据文件 key_log.data
Basic.DataPath 指向的规则数据文件采用 JSON 格式,定义"哪些产品的哪些连接需要记录密钥"。整体结构为 Version + Config,Config 以产品名为键,值为该产品的规则列表;每条规则的核心是 Cond(条件表达式)。文件结构定义与解析逻辑见 key_log_conf_load.go(KeyLogConfFile/KeyLogRuleFile 等结构体及 keyLogConfLoad 函数)。
仓库自带的规则示例(conf/mod_key_log/key_log.data):
{
"Version": "init version",
"Config": {
"global": [
{
"Cond": "ses_sip_range(\"10.0.0.1\", \"10.0.0.10\") && ses_tls_sni_in(\"example.com|example.org\")"
}
]
}
}
Version:配置版本号(通常用时间戳),reload 后管理接口会返回文件名=版本号以确认加载结果。Config:产品名 -> 规则列表的映射。产品名global具有特殊含义——当某个产品在表中没有专属规则时,isNeedKeyLog会回退到global的规则做匹配(对应源码 mod_key_log.go)。Cond:由 BFE 条件表达式构建,支持&&组合多个原语条件。
校验方面,KeyLogConfCheck 要求 Version 与 Config 均非空、每个产品的规则列表非 nil、每条规则必须包含 Cond;ruleConvert 通过 condition.Build 将条件字符串编译为可执行的条件对象。对应实现与测试见 key_log_conf_load.go 与 key_log_conf_load_test.go(其中 key_log_2.conf 因规则缺少 Cond 而加载失败,用于验证校验逻辑)。
常用条件函数:ses_sip_range / ses_tls_sni_in / ses_vip_range
规则文件中最常出现的条件函数,其匹配语义可从条件构建代码中确认(build.go):
| 条件函数 | 参数 | 语义 | 数据来源 |
|---|---|---|---|
ses_sip_range("ip1", "ip2") |
两个 IP 字符串 | 客户端源 IP 落在 ip1, ip2] 区间内 | session.RemoteAddr.IP,见 [primitive.go 的 SIPFetcher |
ses_tls_sni_in("sni1|sni2") |
竖线分隔的 SNI 列表 | TLS ClientHello 中的 SNI 命中列表 | session.TlsState.ServerName,见 primitive.go 的 SniFetcher |
ses_vip_range("ip1", "ip2") |
两个 IP 字符串 | 连接命中的 VIP 落在 ip1, ip2] 区间内 | session.Vip,见 [primitive.go 的 VIPFetcher |
测试数据 key_log.json 中的规则组合即是一个典型场景:只对"源 IP 在 10.0.0.1~10.0.0.10 之间,且 SNI 为 example.com 或 example.org 的 TLS 连接"记录密钥,从而把解密范围精确收敛到正在排障的客户端与域名。
在 Wireshark 中解密 TLS 流量
拿到密钥日志后,使用 Wireshark 解密的具体步骤:
- 在 Wireshark 中打开抓包文件(或边抓包边配置)。
- 进入 Edit → Preferences → Protocols → TLS(旧版本为 SSL)。
- 在
(Pre)-Master-Secret log filename一栏填入 BFE 产出的密钥日志文件路径(如key.log)。 - 重新加载抓包文件(或重新抓包),Wireshark 会依据日志中的
CLIENT_RANDOM <ClientRandom> <MasterSecret>行还原会话密钥,HTTPS 流量即可在 "Decrypted" 视图中以明文呈现,便于直接定位请求行、响应状态码与业务报文内容。
由于 NSS Key Log 格式是跨工具标准,同样的日志文件也可被其他支持该格式的抓包/解密工具使用,并不局限于 Wireshark。
完整启用步骤
在 BFE 中启用 mod_key_log 的完整操作流程如下:
- 准备规则数据文件:参照上文格式编写
key_log.data(JSON),确定需要记录密钥的产品、源 IP 范围与 SNI 条件。仓库中的真实示例见 conf/mod_key_log/key_log.data,测试示例见 key_log.json。 - 编写模块配置:在 BFE 配置目录下创建
mod_key_log/mod_key_log.conf,配置Basic.DataPath指向规则文件,并按需选择轮转写目录或直写LogFile;参考 conf/mod_key_log/mod_key_log.conf。 - 启用模块:编辑 BFE 主配置 conf/bfe.conf,在
Modules列表中取消#Modules = mod_key_log一行的注释(该行默认被注释,即模块默认不加载)。 - 启动并验证:启动 BFE 后发起一次满足规则的 HTTPS 请求,检查日志目录下
key.log(轮转模式)或指定LogFile中是否出现CLIENT_RANDOM ...记录;管理接口 reload 后返回的文件名=版本号可用于确认规则是否加载成功。 - 排障结束及时关闭:从
Modules中移除 mod_key_log 并 reload/重启,避免长期记录会话密钥带来泄露风险。
小结
mod_key_log 是 BFE 面向 TLS 排障场景的轻量模块:它以 NSS Key Log 标准格式导出握手主密钥,通过产品维度的规则表与条件表达式精确控制记录范围,支持目录轮转、标准输出两种落盘方式,并支持管理接口热加载规则。整个链路(握手回调注册、规则匹配、密钥落盘、配置校验)在 bfe_modules/mod_key_log 中实现完整且有测试覆盖,配合 Wireshark 即可实现 HTTPS 流量的按需解密,是定位证书、握手与业务报文问题的实用手段。