BFE mod_key_log 配置指南:NSS Key Log 输出模式与规则数据文件详解

原创2026-10-09 18:24:351,745 阅读
文章标签:后端网络/通信云原生

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),仅负责两件事:

  1. 指定规则数据文件(rule data file)的路径,即 Basic.DataPath;
  2. 指定 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 结构体):

  1. 直接输出模式:仅设置 Log.LogFile,日志原样写入该文件,不做轮转;
  2. 轮转输出模式:设置 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 完成:

  1. 使用 gcfg.ReadFileInto 将 INI 文件解析进 ConfModKeyLog 结构体;
  2. 调用 cfg.Check(confRoot) 进行合法性校验,核心是委托给 cfg.Log.Check(confRoot),即上一节所述的日志参数互斥与取值校验;
  3. 校验通过后返回配置结构体。

模块初始化时(见 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 加载,后者决定密钥日志写到哪里、如何轮转。

实战建议与注意事项

  1. 敏感数据管理:key log 包含 MasterSecret,任何能读取日志的人都可解密对应 TLS 会话。仅对排障目标开启,避免长期全局开启;必要时配合条件表达式(如限定源 IP 段与 SNI)缩小范围。
  2. 两种输出模式选型:调试期建议使用 LogFile = /dev/stdout 直接观察;持续采集场景使用轮转模式,并注意 RotateWhen 的五档取值(M 分钟 / H 小时 / D 天 / MIDNIGHT 自然日 / NEXTHOUR 自然小时)与 BackupCount > 0 的约束。
  3. 路径解析规则:DataPath、LogDir 均按 FilePath/DirPath 规则处理——相对路径以 BFE 配置根目录为基准,绝对路径以 / 开头,运行时文件/目录必须存在且可读(LogDir 若不存在会在初始化时被自动创建,见 logDirCreate)。
  4. 热更新:规则数据文件支持通过 Web 管理接口重载,返回信息形如 key_log.json=<Version>(见 loadConfData),便于在调整过滤条件时无需重启 BFE。
  5. 与 Wireshark 的配合:将输出的 key log 文件通过 Wireshark 的 TLS 解密设置导入,即可对匹配条件的 TLS 连接进行解密分析;解密能力取决于日志中 CLIENT_RANDOM 行与连接握手的对应关系,因此建议在排障窗口内保证日志覆盖完整握手过程。
登录后查看全文
bfe