First OpenSSL and BoringSSL Capture ​

Purpose and Scope ​

This page provides a verified end-to-end walkthrough for capturing TLS plaintext events from OpenSSL and BoringSSL shared libraries using ecapture in text mode. It covers command execution, traffic generation, expected output structure, and references to advanced keylog and pcapng workflows.

Sources: internal/probe/openssl/openssl_probe.go:44-69, internal/probe/openssl/config.go:43-74

Prerequisites and Environment Setup ​

Before running your first OpenSSL capture, verify that your environment meets the core requirements:

• Operating System & Kernel: Linux kernel version 4.18 or higher with BTF (BPF Type Format) support enabled.
• Privileges: Root access (or CAP_SYS_ADMIN / CAP_BPF capabilities) is required to load eBPF programs and attach uprobes.
• Target Application: A dynamic binary or service linked against OpenSSL (libssl.so.1.1, libssl.so.3) or BoringSSL (libssl.so on Android or embedded environments).

Sources: test/e2e/common.sh:32-59

Verified End-to-End Text-Mode Command ​

By default, ecapture tls operates in text mode (-m text), intercepting SSL_read and SSL_write function calls to decode and print plaintext HTTP or application payloads to standard output.

1. Launching eCapture ​

Run the following command with root privileges, specifying the target OpenSSL/BoringSSL library path if necessary, or letting ecapture auto-detect it:

sudo ./bin/ecapture tls -m text

If targeting a specific library path or interface (particularly on Android / BoringSSL environments), supply the explicit path flag:

sudo ./bin/ecapture tls -m text --libssl /usr/lib/x86_64-linux-gnu/libssl.so.3

Probe Configuration and Initialization Architecture ​

The following diagram illustrates how configuration options are validated and how the OpenSSL probe initializes its eBPF manager and execution context:

Sources: internal/probe/openssl/config.go:69-129, internal/probe/openssl/openssl_probe.go:61-163

Traffic Generator and Execution ​

While ecapture is listening, generate HTTPS traffic against an external or local endpoint using curl or a test client:

curl -Iv https://www.cloudflare.com/

Event Capture and Decoding Pipeline ​

As the target process executes TLS handshakes and data exchange, the eBPF uprobes capture encrypted buffers and forward them through perf event maps to the user-space decoder:

Sources: internal/probe/openssl/openssl_probe.go:50-60, internal/probe/openssl/openssl_probe.go:151-160

Expected Event Output ​

When a matching TLS connection transmits data, ecapture outputs structured event logs containing timestamp, process ID, connection tuples, and decoded plaintext payloads:

2026-03-30T12:00:00.123Z [INFO] [openssl] PID: 12345, TID: 12345, IP: 192.168.1.10:54321 -> 104.16.123.96:443
GET / HTTP/1.1
Host: www.cloudflare.com
User-Agent: curl/7.88.1
Accept: */*

2026-03-30T12:00:00.456Z [INFO] [openssl] PID: 12345, TID: 12345, IP: 192.168.1.10:54321 -> 104.16.123.96:443
HTTP/1.1 200 OK
Date: Mon, 30 Mar 2026 12:00:00 GMT
Content-Type: text/html; charset=UTF-8

Sources: internal/probe/openssl/openssl_probe.go:102-163

Links to Advanced Workflows ​

Once you have verified text-mode capture, you can transition to other operational modes depending on your analysis requirements:

• Keylog Mode: Export NSS key log lines to disk for external packet analyzers using -m keylog (see Section 3.3).
• pcapng Mode: Capture network packets with embedded TLS Decryption Secrets Blocks using -m pcap or -m pcapng (see Section 3.4).

Sources: internal/probe/openssl/config.go:139-178