BFE mod_key_log 配置指南:NSS Key Log 输出模式与规则数据文件详解
BFE mod_key_log 配置指南:NSS Key Log 输出模式与规则数据文件详解
mod_key_log.conf 是 BFE 中 mod_key_log 模块的基础配置文件,它决定了 TLS 密钥日志(NSS Key Log Format)的输出位置、轮转方式,以及 key log 规则数据文件的加载路径。本指南以该配置文件为主线,逐项讲解每个配置项的含义、合法取值与校验规则,并结合仓库源码(配置解析、日志初始化、规则表加载、运行时处理链路)与测试用例,帮助读者在 BFE 中正确启用并验证 TLS 流量解密能力。
模块定位:为 TLS 排障输出可解密密钥
mod_key_log 模块的核心能力,是将 TLS 握手过程中的密钥材料以 NSS Key Log 格式写出,供外部程序(典型如 Wireshark)解密 TLS 连接以进行问题排查。其实现位于 bfe_modules/mod_key_log/mod_key_log.go,模块注释中明确说明该格式参考 NSS Key Log Format。
模块实际输出的每一行密钥日志格式为:
CLIENT_RANDOM <ClientRandomHex> <MasterSecretHex>
其中 ClientRandom(连接标识)与 MasterSecret(连接主密钥)均以十六进制编码输出,由 logTlsKey 实现。由于该日志包含会话主密钥,属于高敏感信息,建议仅在排障窗口内对目标流量开启,并妥善控制日志文件的访问权限。
配置文件概览
mod_key_log.conf 是 mod_key_log 模块的基础配置文件(basic configuration),仅负责两件事:
- 指定规则数据文件(rule data file)的路径,即
Basic.DataPath; - 指定 NSS key log 的输出模式,即
Log小节中的各项参数。
该文件使用 INI 风格编写,由 gopkg.in/gcfg.v1 解析,对应结构体为 ConfModKeyLog:
type ConfModKeyLog struct {
Basic struct {
DataPath string // path of config data (key_log)
}
Log access_log.LogConfig
}
配置项详解
下表完整列出 mod_key_log.conf 支持的全部配置项(继承自原文档,并补充校验细节):
| 配置项 | 类型 | 含义 | 是否必填 | 补充说明 | 生效条件 |
|---|---|---|---|---|---|
| Basic.DataPath | String | 规则配置文件路径 | 是 | 无 | 类型为 FilePath,即 FilePath;文件必须存在且可读 |
| Log.LogFile | String | 无轮转的日志文件路径 | 否 | 与 LogPrefix / LogDir / RotateWhen / BackupCount 互斥 |
类型为 FilePath;文件必须可写 |
| Log.LogPrefix | String | 日志文件名前缀 | 否 | 与 LogDir / RotateWhen / BackupCount 搭配使用 |
无 |
| Log.LogDir | String | 日志文件所在目录 | 否 | 与 LogPrefix / RotateWhen / BackupCount 搭配使用 |
类型为 DirPath;目录必须存在且可读 |
| Log.RotateWhen | String | 日志文件轮转间隔 | 否 | 支持 M / H / D / MIDNIGHT / NEXTHOUR |
取值必须是合法的日志轮转间隔 |
| Log.BackupCount | Integer | 轮转日志文件的最大保留数量 | 否 | 无 | 取值必须 > 0 |
路径类型说明
DataPath 与 LogDir 引用的是 00-common.md 中定义的通用类型:
- FilePath:字符串类型。支持相对路径(相对 BFE 配置根目录解析)或绝对路径(以
/开头);运行时引用的文件必须存在且可读。 - DirPath:字符串类型。支持相对路径(相对 BFE 配置根目录解析)或绝对路径;运行时引用的目录必须存在且可读。
两种日志输出模式
Log 小节实际只存在两种互斥的用法(对应 access_log.LogConfig 结构体):
- 直接输出模式:仅设置
Log.LogFile,日志原样写入该文件,不做轮转; - 轮转输出模式:设置
LogPrefix、LogDir、RotateWhen、BackupCount四个参数,按时间轮转写日志。
这两种模式不能混用。源码中的校验逻辑位于 LogConfig.Check:
- 若
LogFile非空,则LogPrefix/LogDir/RotateWhen/BackupCount均不能再设置,否则报错; - 若不使用
LogFile,则LogPrefix与LogDir都不能为空,RotateWhen必须是合法轮转间隔,BackupCount必须大于 0。
配置示例
示例一:将日志保存到目录(带轮转)
原文档给出的完整示例,将密钥日志写入目录并开启按小时轮转:
[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
该模式下,日志实际文件名为 key.log(前缀 key 加上 .log 后缀),位于 ../log 目录下,按小时轮转,最多保留 3 个轮转文件。文件名的拼接逻辑在 prefix2Name:
func prefix2Name(prefix string) string {
return prefix + ".log"
}
轮转与保留数量由 log4go.NewTimeFileLogWriter 实现,日志条目格式为 %M(仅输出消息正文,不附加时间戳前缀),见 LoggerInit2。
示例二:输出日志到 stdout
[Basic]
DataPath = mod_key_log/key_log.data
[Log]
# filename prefix for log
LogFile = /dev/stdout
将 LogFile 设为 /dev/stdout 即可把 key log 直接打印到标准输出,适合在调试环境下配合前台运行观察,无需考虑日志轮转。该模式使用 loggerInitWithFilePath 初始化,将日志原样写入指定文件。
仓库中的默认配置
仓库自带的默认配置位于 conf/mod_key_log/mod_key_log.conf,其内容与示例一结构相同,但 RotateWhen 使用 MIDNIGHT(按自然日轮转):
[Log]
LogPrefix = key
LogDir = ../log
RotateWhen = MIDNIGHT
BackupCount = 3
[basic]
DataPath = mod_key_log/key_log.data
测试用例中使用的配置位于 bfe_modules/mod_key_log/testdata/mod_key_log/mod_key_log.conf,可对照参考。
配置文件加载与校验流程
mod_key_log.conf 的加载由 ConfLoad 完成:
- 使用
gcfg.ReadFileInto将 INI 文件解析进ConfModKeyLog结构体; - 调用
cfg.Check(confRoot)进行合法性校验,核心是委托给cfg.Log.Check(confRoot),即上一节所述的日志参数互斥与取值校验; - 校验通过后返回配置结构体。
模块初始化时(见 ModuleKeyLog.Init)按以下顺序装配:
- 通过
bfe_module.ModConfPath(cr, m.name)定位mod_key_log.conf并调用ConfLoad加载; - 读取
conf.Basic.DataPath指向的规则数据文件,加载进规则表(KeyLogTable); - 调用
access_log.LoggerInit(m.conf.Log)依据Log小节初始化日志器; - 将
logTlsKey注册为HandleHandshake阶段的过滤器,在 TLS 握手时输出密钥; - 将
loadConfData注册为 Web 重载处理器,支持运行时热更新规则。
规则数据文件(DataPath 指向的内容)
Basic.DataPath 指向的规则数据文件是 JSON 格式(尽管示例中常使用 .data 后缀)。其结构定义与加载逻辑位于 key_log_conf_load.go,顶层包含:
Version:配置版本号(必填,通常为时间戳字符串);Config:产品名(product)到规则列表的映射(必填)。
每条规则目前只有一个字段 Cond:一个条件表达式字符串(必填),运行时通过 condition.Build 编译为条件对象。仓库测试数据 key_log.json 给出了典型内容:
{
"Version": "init version",
"Config": {
"example_product": [
{
"Cond": "ses_sip_range(\"10.0.0.1\", \"10.0.0.10\") && ses_tls_sni_in(\"example.com|example.org\")"
}
],
"global": [
{
"Cond": "ses_sip_range(\"10.0.0.1\", \"10.0.0.10\") && ses_tls_sni_in(\"example.com|example.org\")"
}
]
}
}
上述条件含义为:客户端源 IP 落在 10.0.0.1 ~ 10.0.0.10 区间内,且 TLS SNI 属于 example.com 或 example.org 时,对该连接输出 key log。加载过程中的校验(KeyLogConfCheck)要求 Version 与 Config 均存在,且每个产品的规则列表非空、每条规则必须包含 Cond。
产品的匹配回退逻辑
运行时,isNeedKeyLog 先以会话的 Product 精确查找规则;若未命中,则回退到 bfe_basic.GlobalProduct(即 global 产品)查找,命中后逐条匹配 Cond,任一条件满足即输出密钥日志。规则表本身以读写锁保护的 map 形式存储(见 key_log_table.go),支持通过 Web 重载接口热更新。
配置正确性验证:测试用例解读
仓库测试为上述行为提供了可执行验证:
- TestModuleKeyLogInit:构造临时目录与配置文件(
LogFile = key.log+ 指向测试 JSON 的DataPath),验证Init能完整走通配置加载、数据加载与日志器初始化流程; - TestLogTlsKey:构造带有
TlsState(含ClientRandom与MasterSecret)的会话,验证命中规则后正常输出且返回BfeHandlerGoOn; - TestLogTlsKeyNotNeed:使用未配置的产品名,验证不输出密钥日志;
- TestLogTlsKeyNoTlsState:验证
TlsState为 nil 时安全跳过; - TestKeyLogConfLoad_ProductIsNull:加载缺少
Cond的规则文件(对应 key_log_2.conf),验证会返回错误。
这些测试同时印证了配置文件中 DataPath 与 Log 两类配置的实际消费方式:前者决定规则从哪个 JSON 加载,后者决定密钥日志写到哪里、如何轮转。
实战建议与注意事项
- 敏感数据管理:key log 包含
MasterSecret,任何能读取日志的人都可解密对应 TLS 会话。仅对排障目标开启,避免长期全局开启;必要时配合条件表达式(如限定源 IP 段与 SNI)缩小范围。 - 两种输出模式选型:调试期建议使用
LogFile = /dev/stdout直接观察;持续采集场景使用轮转模式,并注意RotateWhen的五档取值(M分钟 /H小时 /D天 /MIDNIGHT自然日 /NEXTHOUR自然小时)与BackupCount > 0的约束。 - 路径解析规则:
DataPath、LogDir均按 FilePath/DirPath 规则处理——相对路径以 BFE 配置根目录为基准,绝对路径以/开头,运行时文件/目录必须存在且可读(LogDir若不存在会在初始化时被自动创建,见 logDirCreate)。 - 热更新:规则数据文件支持通过 Web 管理接口重载,返回信息形如
key_log.json=<Version>(见 loadConfData),便于在调整过滤条件时无需重启 BFE。 - 与 Wireshark 的配合:将输出的 key log 文件通过 Wireshark 的 TLS 解密设置导入,即可对匹配条件的 TLS 连接进行解密分析;解密能力取决于日志中
CLIENT_RANDOM行与连接握手的对应关系,因此建议在排障窗口内保证日志覆盖完整握手过程。