本文说明 ecapture 中 text（明文） 、keylog（仅密钥） 、pcapng（网卡密文 + 密钥） 三种 CaptureMode 在代码层面如何落地，以及 上层应用 （消费 ecapture 产出或与之集成的服务）通常需要做什么。OpenSSL 探针在 ecapture 中采用 相同的三种模式 分支，仅 BPF 与挂载符号改为 libssl，下文以 gotls 为主描述。
1. 术语与总览
上层应用：不特指某仓库；凡订阅 ecapture Dispatch、读其输出文件、或与探针进程联动的业务系统，均称上层应用。
三种模式在 gotls_probe.go 中由 CaptureMode 分支：ModeText → setupManagersText；ModeKeylog / ModeKey → setupManagersKeyLog；ModePcap / ModePcapng → setupManagerPcapNG。
CaptureMode 选择
text
keylog
pcapng
setupManagersText
setupManagersKeyLog
setupManagerPcapNG
| 模式 | ecapture 挂什么 | 主要 perf / TC 输出 | 磁盘或管道主产物 |
|---|---|---|---|
| text | Read/Write uprobe | events map（明文块） | 由 Dispatcher 与 handler 决定（日志等） |
| keylog | writeKeyLog uprobe | mastersecret_go_events | NSS keylog 文件 |
| pcapng | TC ingress/egress + writeKeyLog | 包 map + mastersecret_go_events | pcapng + keylog（可嵌入 pcapng） |
2. 模式一：text（明文）
2.1 ecapture 如何实现（数据路径）
ecapture 用户态
PERF_EVENT_ARRAY
gotls_kern.c
目标 Go 进程
否
是
crypto/tls Conn Read
writeRecordLocked 等
gotls_read / gotls_write
bpf_perf_event_output CURRENT_CPU
events map
perf.NewReader
tlsDataEventDecoder
PerfReorder?
goTLSPlainPerfLoop
goTLSOrderedPerfLoop + lag
Dispatcher.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 误比 Seq （Seq 为 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_ARRAY
gotls_kern.c
目标 Go 进程
crypto/tls Config writeKeyLog
gotls_mastersecret
bpf_perf_event_output
mastersecret_go_events
StartPerfEventReader
masterSecretEventDecoder
KeylogHandler
NSS 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. 三种方式对比与选型
需求
要明文且同机可钩
只要密钥 密文别处有
要密文+密钥一体落盘
text
keylog
pcapng
| 维度 | text | keylog | pcapng |
|---|---|---|---|
| 产出是否含应用明文 | 直接含（事件里） | 否 | 否（文件内为密文） |
| 是否抓网卡 | 否 | 否 | 是 |
| perf 明文块拼序问题 | 有（需 reorder/上层排序） | 无（无此类明文块） | 无（同左，密文序在 TCP 层） |
| 依赖 TLS 套件 | 不依赖（已是明文） | 解密侧依赖工具/上层 | 解密侧依赖工具/上层 |
| 典型运维 | elf、偏移、BTF；可选 pid | elf；keylog 路径 | elf + 网卡 + 磁盘 |
| ecapture 开箱程度 | 完整 | 完整（写 keylog） | 完整（写 pcapng+密钥） |
| 上层典型工作 | 分桶、协议拼接、序与批间策略 | 准备密文源、关联 keylog；或自研解密 | 分析工具链；或流式改造与解密 |
带宽与 CPU 体感 ：text 多为 目标进程上的明文块事件 ，范围相对可控；pcapng 路径含 整包密文与协议头 ，且常覆盖 网卡上多连接 ，总比特率通常更高；单流密文相对明文仅多 TLS 封装 ，差异常小于 观测范围 带来的差异。
6. OpenSSL 探针
ecapture openssl 子命令同样具备 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：三种模式实现说明与上层应用职责