Choosing a TLS Probe ​

Purpose and Scope ​

This page provides a technical comparison and decision framework for selecting the appropriate eCapture TLS probe (tls, gotls, or gnutls). Choosing the correct probe depends on the target application's underlying cryptographic library or language runtime, the operating system platform (Linux vs. Android), and the desired output representation (text, keylog, or pcap/pcapng).

Sources: cli/cmd/tls.go:29-48, cli/cmd/gotls.go:28-43, cli/cmd/gnutls.go:33-49

Core TLS Probes Decision Matrix ​

The following decision table maps application runtimes and binary characteristics to the correct eCapture CLI subcommand, internal probe factory type, and bytecode targets.

Sources: cli/cmd/tls.go:29-61, cli/cmd/gotls.go:28-55, cli/cmd/gnutls.go:33-60, docs/agent/architecture.md:37-49

Probe Selection Architecture ​

The diagram below bridges natural language selection criteria to concrete code entities across the CLI parser, factory registry, and probe initialization packages.

Sources: cli/cmd/tls.go:26-48, cli/cmd/gotls.go:26-43, cli/cmd/gnutls.go:29-49, internal/probe/openssl/openssl_probe.go:44-69, internal/probe/gotls/gotls_probe.go:52-78, internal/probe/gnutls/gnutls_probe.go:39-55

Initialization and Data Flow ​

Once a probe command is invoked, eCapture validates the configuration, selects matching bytecode assets via BaseProbe, and binds eBPF maps to event decoders.

Sources: internal/probe/openssl/openssl_probe.go:102-163, internal/probe/gotls/gotls_probe.go:107-157, internal/probe/gnutls/gnutls_probe.go:80-117, docs/agent/architecture.md:7-26

Detailed Probe Profiles ​

1. OpenSSL and BoringSSL Probe (tls) ​

• Use Case: Applications dynamically or statically linked against OpenSSL (such as Nginx, cURL, Python, Node.js, PHP) or Google BoringSSL (Android system apps, Chrome).
• Key Flags: --libssl to specify custom library paths cli/cmd/tls.go:51; --ssl_version to target specific ABI offsets cli/cmd/tls.go:57; -m text|keylog|pcap for output modes cli/cmd/tls.go:53.
• Implementation Details: Attaches uprobes to SSL write/read entry/exit functions (e.g., SSL_write, SSL_read) or BoringSSL internal master secret logging functions.

Sources: cli/cmd/tls.go:29-61, internal/probe/openssl/openssl_probe.go:44-69

2. Go Native TLS Probe (gotls) ​

• Use Case: Compiled Go binaries using Go's standard library crypto/tls package. Does not depend on OpenSSL.
• Key Flags: --elfpath (-e) to point to the target Go binary for symbol and register ABI discovery cli/cmd/gotls.go:46; --perf-reorder for high-throughput ordering cli/cmd/gotls.go:47.
• Implementation Details: Resolves Go internal function symbols such as crypto/tls.(*Conn).Read, crypto/tls.(*Conn).writeRecordLocked, and crypto/tls.(*Config).writeKeyLog internal/probe/gotls/gotls_probe.go:47-50.

Sources: cli/cmd/gotls.go:28-55, internal/probe/gotls/gotls_probe.go:46-68

3. GnuTLS Probe (gnutls) ​

• Use Case: Applications compiled against the GnuTLS library (common in enterprise Linux distributions and Termux on Android).
• Key Flags: --gnutls to specify libgnutls.so path cli/cmd/gnutls.go:52; --ssl_version for GnuTLS version mapping cli/cmd/gnutls.go:57.
• Implementation Details: Attaches uprobes to gnutls_record_send and gnutls_record_recv functions within libgnutls.so internal/probe/gnutls/gnutls_probe.go:211-212.

Sources: cli/cmd/gnutls.go:33-60, internal/probe/gnutls/gnutls_probe.go:39-55