Version Detection and Bytecode Selection ​

Purpose and Scope ​

This page documents eCapture's sophisticated version detection and bytecode selection system, which enables the tool to work across multiple SSL/TLS library versions and kernel configurations without requiring manual version specification. The system automatically identifies the target library version, selects compatible eBPF bytecode, and falls back to safe defaults when exact matches are unavailable.

For information about the eBPF compilation process that produces these bytecode variants, see Build System. For details on module initialization and lifecycle, see Module System and Lifecycle.

System Overview ​

eCapture compiles over 130 different eBPF bytecode variants to support:

• OpenSSL: versions 1.0.2a through 3.5.4
• BoringSSL: Android 12-16 variants and non-Android versions
• GnuTLS: versions 3.6.12 through 3.8.7
• Go TLS: built-in crypto/tls library
• System utilities: bash, zsh, mysqld, postgres

Each SSL/TLS library version has different internal structure layouts (offsets), requiring version-specific bytecode. The system performs runtime detection to select the correct variant.

Sources: variables.mk:189-228, user/module/probe_openssl_lib.go:30-42, CHANGELOG.md:14-23

Version Detection Architecture ​

Sources: user/module/probe_openssl_lib.go:189-282, user/module/probe_openssl_lib.go:284-317, user/module/probe_openssl_lib.go:341-369

ELF Parsing and Version Extraction ​

The detectOpenssl() function implements a robust version string extraction mechanism:

Process Steps ​

1. ELF File Opening: Opens the target shared library using os.OpenFile() and elf.NewFile()
2. Architecture Validation: Ensures the binary is EM_X86_64 or EM_AARCH64
3. Section Location: Finds the .rodata section containing read-only data (version strings)
4. Chunk Reading: Reads in 1MB chunks with 30-byte overlap to handle edge cases
5. Regex Matching: Applies pattern OpenSSL\s\d\.\d\.[0-9a-z]+ to extract version

Edge Case Handling ​

Example version strings extracted:

• "OpenSSL 1.1.1j 16 Feb 2021" → "openssl 1.1.1j"
• "OpenSSL 3.2.0 23 Nov 2023" → "openssl 3.2.0"

Sources: user/module/probe_openssl_lib.go:189-282, user/module/probe_openssl_lib.go:41-42

Detection Flow Diagram ​

Sources: user/module/probe_openssl_lib.go:206-282

Version-to-Bytecode Mapping System ​

The initOpensslOffset() function initializes the sslVersionBpfMap with 100+ version mappings. This map serves as the authoritative source for version-to-bytecode associations.

Mapping Table Structure ​

Mapping Code Structure ​

Sources: user/module/probe_openssl_lib.go:73-187, user/module/probe_openssl_lib.go:44-62

Downgrade Version Selection Algorithm ​

When an exact version match is not found in sslVersionBpfMap, the downgradeOpensslVersion() function implements a progressive truncation algorithm to find the closest compatible older version.

Algorithm Steps ​

Sources: user/module/probe_openssl_lib.go:341-369

Version Comparison Logic ​

The isVersionLessOrEqual() function performs lexicographic version comparison:

1. Extract version parts: Split by dots ("3.0.12" → ["3", "0", "12"])
2. Parse numeric and suffix: "1a" → num=1, suffix="a"
3. Compare iteratively: Compare numbers first, then suffixes

Example comparisons:

• isVersionLessOrEqual("openssl 3.0.11", "openssl 3.0.12") → true
• isVersionLessOrEqual("openssl 3.0.12", "openssl 3.0.11") → false
• isVersionLessOrEqual("openssl 1.1.1j", "openssl 1.1.1k") → true

Sources: user/module/probe_openssl_lib.go:371-448

Default Fallback Behavior ​

When all detection and downgrade attempts fail, the system applies platform-specific defaults:

Linux Platform Defaults ​

Rationale:

• libssl.so.3 indicates OpenSSL 3.x series (most likely 3.0.x)
• Older library names default to 1.1.1j (most stable/common 1.1.1 variant)

Android Platform Defaults ​

Android version mapping:

• --android_ver=13 → boringssl_a_13_kern.o
• --android_ver=14 → boringssl_a_14_kern.o
• --android_ver=15 → boringssl_a_15_kern.o
• --android_ver=16 → boringssl_a_16_kern.o

Sources: user/module/probe_openssl_lib.go:284-317, user/module/probe_openssl_lib.go:361-368

CO-RE vs Non-CO-RE Bytecode Selection ​

eCapture maintains two bytecode variants for each version: CO-RE (Compile Once, Run Everywhere) and non-CO-RE (kernel-specific). The selection happens automatically based on kernel BTF support.

Selection Criteria ​

BTF Detection Flow ​

Compilation Targets ​

The build system generates both variants simultaneously:

CO-RE compilation (x86_64 example):

clang -target bpfel -D__TARGET_ARCH_x86 -I./kern/bpf/x86 \
      -O2 -g -c -o openssl_3_0_0_kern_core.o openssl_3_0_0_kern.c

Non-CO-RE compilation (x86_64 example):

clang -D__TARGET_ARCH_x86 -I/lib/modules/$(uname -r)/build/include \
      -DNOCORE -emit-llvm -S -o openssl_3_0_0_kern.ll openssl_3_0_0_kern.c
llc -march=bpf -filetype=obj -o openssl_3_0_0_kern_noncore.o openssl_3_0_0_kern.ll

Sources: variables.mk:236-268, README.md:86-101

Bytecode Loading and Validation ​

After bytecode selection, the module performs validation before attachment:

Loading Process ​

Error Handling Strategy ​

Sources: user/module/probe_openssl_lib.go:189-282, user/module/probe_openssl_lib.go:284-317

Version Support Matrix ​

This table summarizes the complete version support landscape:

Total bytecode files: 22 SSL/TLS variants × 2 modes (CO-RE + non-CO-RE) = 44 bytecode files just for OpenSSL/BoringSSL

Sources: user/module/probe_openssl_lib.go:44-62, variables.mk:189-228, CHANGELOG.md:14-23

Configuration Options ​

Users can override automatic detection using CLI flags:

Command-Line Overrides ​

Example Usage ​

Manual version specification:

sudo ecapture tls --ssl_version="openssl 3.2.3" --libssl=/usr/local/lib/libssl.so.3

Android device:

adb shell "ecapture tls --android_ver=14"

Force non-CO-RE mode (older kernels):

sudo ecapture tls --nocore

Sources: README.md:165-169, README_CN.md:144-149

Logging and Diagnostics ​

The version detection system provides detailed logging at multiple stages:

Log Message Categories ​

Troubleshooting Guide ​

Problem: "OpenSSL/BoringSSL version not found"

Solutions:

1. Check if .rodata section exists: readelf -S /path/to/libssl.so | grep rodata
2. Manually specify version: --ssl_version="openssl x.x.x"
3. For BoringSSL, use: --ssl_version="boringssl_a_13"

Problem: "BPF bytecode file is not matched"

Solutions:

1. Verify bytecode files exist: ls user/bytecode/*.o
2. Check build completed: make
3. Try forcing version: --ssl_version

Problem: Capture works but data is garbled

Cause: Incorrect version/offset mismatch

Solutions:

1. Enable debug mode: ecapture tls --debug
2. Try adjacent versions: --ssl_version="openssl 3.0.11" vs "openssl 3.0.13"
3. Check library version: openssl version or strings /lib/libssl.so.3 | grep "OpenSSL"

Sources: user/module/probe_openssl_lib.go:300-316, README.md:89-101