本文说明 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。
| 模式 | 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 如何实现（数据路径）
要点：
- 内核在每次 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 如何实现
要点：
只挂载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 |
|---|---|---|---|
| 产出是否含应用明文 | 直接含（事件里） | 否 | 否（文件内为密文） |
| 是否抓网卡 | 否 | 否 | 是 |
| perf 明文块拼序问题 | 有（需 reorder/上层排序） | 无（无此类明文块） | 无（同左，密文序在 TCP 层） |
| 依赖 TLS 套件 | 不依赖（已是明文） | 解密侧依赖工具/上层 | 解密侧依赖工具/上层 |
| 典型运维 | elf、偏移、BTF；可选 pid | elf；keylog 路径 | 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：三种模式实现说明与上层应用职责
