[ecapture] gotls：三种模式实现说明与上层应用职责

本文说明 ecapture 中text明文、keylog仅密钥、pcapng网卡密文 密钥三种 CaptureMode 在代码层面如何落地以及上层应用消费 ecapture 产出或与之集成的服务通常需要做什么。OpenSSL 探针在 ecapture 中采用相同的三种模式分支仅 BPF 与挂载符号改为 libssl下文以gotls为主描述。1. 术语与总览上层应用不特指某仓库凡订阅 ecapture Dispatch、读其输出文件、或与探针进程联动的业务系统均称上层应用。三种模式在gotls_probe.go中由CaptureMode分支ModeText→setupManagersTextModeKeylog/ModeKey→setupManagersKeyLogModePcap/ModePcapng→setupManagerPcapNG。CaptureMode 选择textkeylogpcapngsetupManagersTextsetupManagersKeyLogsetupManagerPcapNG模式ecapture 挂什么主要 perf / TC 输出磁盘或管道主产物textRead/Write uprobeevents map明文块由 Dispatcher 与 handler 决定日志等keylogwriteKeyLog uprobemastersecret_go_eventsNSS keylog 文件pcapngTC ingress/egress writeKeyLog包 map mastersecret_go_eventspcapng keylog可嵌入 pcapng2. 模式一text明文2.1 ecapture 如何实现数据路径ecapture 用户态PERF_EVENT_ARRAYgotls_kern.c目标 Go 进程否是crypto/tls Conn ReadwriteRecordLocked 等gotls_read / gotls_writebpf_perf_event_output CURRENT_CPUevents mapperf.NewReadertlsDataEventDecoderPerfReorder?goTLSPlainPerfLoopgoTLSOrderedPerfLoop lagDispatcher.Dispatch要点内核在每次 Read/Write 路径上填充go_tls_event含明文切片、ts_ns、emit_cpu、seq、fd、地址等写入当前 CPU对应的events槽位。用户态仅对events使用startGoTLSDataPerfReader可选perf_reorder与lag在 Dispatch 前做用户态缓冲排序。2.2 乱序原因多 CPU 多 ring 合并读时先读到的样本不一定时间最早。业务 sock 字节序仍有序乱的是多条 perf 事件的到达序。排序逻辑BpfMonoNs → EmitCPU → Seq与LessGoTLSDataEventByPerfOrder一致。EmitCPU用于同 ns 时先分组避免跨 CPU 误比 SeqSeq 为 per-CPU。reorder / lag 仅作用于 events不作用于 mastersecret 读循环。2.3 适用场景探针与目标进程同机或可挂载同一 ELF需要直接拿到 TLS 应用明文含 TLS 1.3 / ECDHE不依赖服务端私钥。可接受维护Go 版本与 netFD 等偏移以及perf 序reorder、或与上层再排序。2.4 上层应用需要做什么接入订阅或消费 ecapture 对GoTLSDataEvent的 Dispatch或等价导出。按连接分桶用 pid、fd、方向、五元组等连接键聚合 chunk通常不做全机单队列全局排序。合规与性能明文与 payload 体积敏感时需自行限流、脱敏、截断。3. 模式二keylog仅密钥文件3.1 ecapture 如何实现ecapture 用户态PERF_EVENT_ARRAYgotls_kern.c目标 Go 进程crypto/tls Config writeKeyLoggotls_mastersecretbpf_perf_event_outputmastersecret_go_eventsStartPerfEventReadermasterSecretEventDecoderKeylogHandlerNSS keylog 文件要点只挂载writeKeyLog不挂载 Read/Write 明文无events map读循环。从 uprobe 参数读取 label、client_random、secret 等到用户态不依赖应用是否配置 KeyLogWriter只要运行时进入writeKeyLog早退前参数可读以实际编译与挂载点为准。https://github.com/golang/go/blob/33241d7298e0c621cfc4cc9f878dba9eff2b1c3d/src/crypto/tls/common.go#L1591-L1603无perf_reorder密钥走StartPerfEventReader。3.2 keylog 与 text 在「乱序」上的差异不存在「多段明文perf 拼流」问题密钥事件低频与高频应用数据块不同。pcap外部解密时应用数据顺序由TCP 密文流体现。3.3 适用场景只要NSS keylog 行把密文交给Wireshark/tshark或其它已有解密工具。不在本机录网卡包流量在别处抓或不需要 ecapture 抓包。3.4 上层应用需要做什么读 keylog 文件密文来源自理ecapture keylog 模式不输出 TLS 记录明文上层需自有pcap / 镜像 / 其它抓包与 keylog按 CLIENT_RANDOM 等关联。若要在自有服务内实时解密需实现NSS解析 TCP 重组 TLS 状态机含1.3工作量在上层不在 ecapture 默认能力内。4. 模式三pcapng网卡密文 密钥4.1 ecapture 如何实现要点TC在配置的ifname上双向抓包写入pcapng。同时挂载writeKeyLog密钥可单独文件或通过PcapKeylogWriter写入pcapng 自定义块便于 Wireshark 一次打开。可选PcapFilter对 TC 程序做指令修补以过滤。4.2 pcapng 与 keylog 模式的核心差别项目keylog 模式pcapng 模式网卡 TC无有密文落盘无ecapture 不录有pcapng密钥有有且常与 pcap 配套配置elf、keylog 路径等另需网卡名、pcap 路径等pcap 文件主体是密文与链路层包头明文不在文件里自动生成需用密钥在工具或上层解密栈中解出。4.3 适用场景需要一体交付同一次运行得到可对齐的密文轨迹 密钥审计、离线分析、与 Wireshark 工作流对齐。有权限在目标环境对指定接口加载 TC。4.4 上层应用需要做什么离线直接拿 pcapng keylog 用标准工具解密分析或导入自有系统。实时ecapture 默认写文件若要不落盘、实时消费需改 ecapture 输出或另起抓包通道由上层读流式帧 流式密钥。进程内解 HTTP 明文仍属TCP TLS keylog 关联由上层或外部组件实现非ecapture pcap 模式内置。5. 三种方式对比与选型需求要明文且同机可钩只要密钥 密文别处有要密文密钥一体落盘textkeylogpcapng维度textkeylogpcapng产出是否含应用明文直接含事件里否否文件内为密文是否抓网卡否否是perf 明文块拼序问题有需 reorder/上层排序无无此类明文块无同左密文序在 TCP 层依赖 TLS 套件不依赖已是明文解密侧依赖工具/上层解密侧依赖工具/上层典型运维elf、偏移、BTF可选 pidelfkeylog 路径elf 网卡 磁盘ecapture 开箱程度完整完整写 keylog完整写 pcapng密钥上层典型工作分桶、协议拼接、序与批间策略准备密文源、关联 keylog或自研解密分析工具链或流式改造与解密带宽与 CPU 体感text 多为目标进程上的明文块事件范围相对可控pcapng 路径含整包密文与协议头且常覆盖网卡上多连接总比特率通常更高单流密文相对明文仅多TLS 封装差异常小于观测范围带来的差异。6. OpenSSL 探针ecaptureopenssl子命令同样具备text / keylog / pcap三种CaptureMode分支结构与 gotls 对称差异为挂载符号与字节码如 SSL_read、SSL_write、主密钥导出路径。上层应用对接方式可与 gotls 类比按产物类型明文事件 / keylog / pcapng选择集成策略。7. ecapture实现相关文章文章都在ecapture专栏里[eCapture] GoTLS Perf 事件有序下发[ecapture]捕获TLS明文流量[ecapture]Connect Events获取[ecapture]go1.20 tls fd抽取[ecapture] eBPF hook gotls 收包乱序根因分析[ecapture] gotls三种模式实现说明与上层应用职责