eCapture

eCapture is a tool designed to capture SSL/TLS text content without requiring a CA certificate by leveraging eBPF. The documentation is organized into several key areas to help developers build, extend, and integrate with the project:

• Getting Started: Guides for building and compiling the project.
• Architecture & Development: Deep dives into probe refactoring, migration from v1 to v2, and specific module case studies (e.g., GoTLS).
• Testing: Instructions for end-to-end (e2e) testing.
• Security & Operations: Guidance on Linux capabilities (least-privilege), performance benchmarking, and defending against unauthorized eBPF tool usage.
• API Documentation: Technical references for the Event Forwarding API and the Remote Configuration Update API.
• Integration: Information on using event forwarding with applications and GUI clients.
• Examples: Sample outputs for various eCapture modes and modules.

The following logic describes how specific traffic secrets are derived from the master or handshake secrets:

Server Application Traffic

• Input Secret: s->master_secret
• Label: server_application_traffic
• Log Label: SERVER_APPLICATION_LABEL

Client Application Traffic

• Input Secret: s->master_secret
• Label: client_application_traffic
• Log Label: CLIENT_APPLICATION_LABEL

Server Handshake Traffic

• Input Secret: s->handshake_secret
• Final Secret: s->server_finished_secret
• Label: server_handshake_traffic
• Log Label: SERVER_HANDSHAKE_LABEL
• Process: Uses derive_secret_key_and_iv with the handshake secret and the server_handshake_traffic label.

Client Handshake Traffic

• Input Secret: s->handshake_secret
• Final Secret: s->client_finished_secret
• Label: client_handshake_traffic
• Log Label: CLIENT_HANDSHAKE_LABEL

Client Early Traffic

• Input Secret: s->early_secret
• Label: client_early_traffic
• Log Label: CLIENT_EARLY_LABEL

eCapture uses eBPF uprobes to intercept function calls. The overhead is composed of uprobe entry/exit, eBPF program execution, perf buffer transfer, and userspace processing.

Expected Overhead Profile

Mitigating Perf Buffer Overflows

If you see "lost X events" in the logs, the perf buffer (default 4 MB per CPU) is overflowing. Mitigate this by:

• Using --pid to limit capture scope to specific processes.
• Using keylog mode instead of text mode (reduces data per event).
• Increasing the perf buffer size (if supported by your version).

Known Limitations

• Call Frequency Scaling: Overhead scales with the frequency of SSL_read/SSL_write calls, regardless of data size.
• No Sampling: All events are captured; there is no probabilistic sampling.
• Single-threaded Processing: The userspace event reader is single-threaded and can become a bottleneck under high load.
• No Backpressure: If the reader falls behind, events are dropped silently via perf buffer overflow.

The OpenSSL module supports three distinct capture modes via the -m flag:

Pcap Mode

Saves captured plaintext data in pcap-NG format, viewable in Wireshark. Supports HTTP 1.0/1.1/2.0 over TCP and HTTP/3 (QUIC) over UDP.

• Use -m pcap or -m pcapng.
• Use --pcapfile to specify the output file (default: ecapture_openssl.pcapng).
• Use -i to specify the interface.

Keylog Mode

Saves TLS handshake Master Secret keys to a file. You can use these keys in Wireshark to decrypt captured packets.

• Use -m keylog or -m key.
• Use --keylogfile to specify the output file (default: ecapture_masterkey.log).

Text Mode

Outputs all plaintext data packets directly to the command line or a specified file.

• Use -m text.
• Note: As of v0.7.0, this mode no longer captures SSLKEYLOG information.

### Pcap Mode Example
sudo ecapture tls -m pcap -i eth0 --pcapfile=ecapture.pcapng tcp port 443

### Keylog Mode Example
sudo ecapture tls -m keylog -keylogfile=openssl_keylog.log

### Text Mode Example
sudo ecapture tls -m text

The headers boringssl_const.h and boringssl_masterkey.h use feature flags emitted by the offset tool to adapt to changes in BoringSSL internal structures across Android versions without manual code edits.

boringssl_const.h (TLS 1.3 Secret Offsets)

Uses #ifdef SSL_SESSION_ST_SSL_VERSION to switch logic between Android ≤ 15 and Android 16+:

• Android ≤ 15: Uses private uint8_t secret_[48] and a 48-byte step size.
• Android 16+: Uses public InplaceVector<uint8_t,48> and a 49-byte step size (SSL_HANDSHAKE_FIELD_STEP).

boringssl_masterkey.h (TLS Version Detection)

Uses feature flags to identify TLS versions correctly:

• Android ≤ 15: Reads TLS version from ssl_st.version (via #ifndef SSL_SESSION_ST_SSL_VERSION).
• Android 16+: Reads TLS version from SSL3_STATE.version (via #ifdef BSSL__SSL3_STATE_VERSION) to ensure TLS 1.3 connections are identified before the version branch decision.