[Proposal] Let TShark Do All the Dirty Work

[blaisewang]

I'm proposing several enhancements to improve the usability of eCapture and I welcome discussions and suggestions from all contributors.

1. Utilize TShark Protocol Parsing Capabilities

Currently, eCapture relies on http.ReadRequest and http.ReadResponse in Golang for assembling http.Request and http.Response, which limits support to HTTP/1.1 and older protocols. By leveraging the advanced protocol parsing capabilities of TShark, eCapture can extend its protocol support to nearly match that of Wireshark, starting from the TCP/UDP layer.

2. Reduce the burden on ecapture

With the reduced need for data transfer between user land and kernel land, eCapture can evolve into a more efficient TLS Key Log recording tool. This optimization would allow eCapture to function as a lightweight TLS key log collection agent, potentially operable as a DaemonSet privileged container for monitoring encrypted traffic across an entire Kubernetes cluster.

3. Agent-Server Architecture

In agent mode, eCapture offers flexibility, allowing users to choose between mirroring network packets with the TLS Key Log or capturing only the TLS Key Log, based on the startup command.

In server mode, acting essentially as a TShark Wrapper, eCapture can listen on a specified address to receive network packets and TLS Key logs from the agent for analysis. This server mode opens up limitless possibilities for data analysis.

With this design, ecapture becomes more flexible and practical from an architectural perspective. Certainly, ecapture is also capable of recording TLS Key logs concurrently with the streaming decryption process.

4. ecapctl (Optional)

Similar to Docker/Containerd, the ecapctl command-line tool could be introduced to control eCapture, enabling modifications to its behavior dynamically, without the need to stop the process.

POC

Demonstrating TShark's capability to stream and decrypt TLS traffic is straightforward. The following commands can be executed in two separate terminals:

tshark -o tls.keylog_file:key.log -Y http -T fields -e http.file_data -f "port 32888" -i <interface>
SSLKEYLOGFILE=key.log curl --local-port 32888 --http1.1 --tlsv1.3 https://www.google.com

Under this setup, TShark monitors the tls.keylog_file for changes, temporarily storing network packets in the /tmp/ directory, showcasing its efficient packet handling and decryption capabilities.

[cfc4n]

Great idea. However, I need to verify the range of HTTP protocols and TLS versions supported by tshark.

• http 1.0 and tls 1.0
• http 1.0 and tls 1.1
• http 1.0 and tls 1.2
• http 1.0 and tls 1.3
• http 1.1 and tls 1.0
• http 1.1 and tls 1.1
• http 1.1 and tls 1.2
• htto 1.1 and tls 1.3
• http 2.0 and tls 1.0
• http 2.0 and tls 1.1
• http 2.0 and tls 1.2
• http 2.0 and tls 1.3

It seems that tshark supports TLS versions 1.0-1.3 well under the HTTP 1.1/2 protocol, but it appears to not support decryption for HTTP 1.0.

eCapture shell

root@VM-0-13-ubuntu:/home/ubuntu/ecapture# bin/ecapture tls
tls_2023/11/28 22:41:14 ECAPTURE :: ecapture Version : linux_x86_64:0.6.6-20231126-db7e37a:[CORE]
tls_2023/11/28 22:41:14 ECAPTURE :: Pid Info : 24947
tls_2023/11/28 22:41:14 ECAPTURE :: Kernel Info : 5.15.126
tls_2023/11/28 22:41:14 EBPFProbeOPENSSL	module initialization
tls_2023/11/28 22:41:14 EBPFProbeOPENSSL	master key keylogger: ecapture_masterkey.log
tls_2023/11/28 22:41:14 ECAPTURE ::	Module.Run()
tls_2023/11/28 22:41:14 EBPFProbeOPENSSL	UPROBE MODEL
tls_2023/11/28 22:41:14 EBPFProbeOPENSSL	OpenSSL/BoringSSL version not found from shared library file, used default version:linux_default_3_0
tls_2023/11/28 22:41:14 EBPFProbeOPENSSL	HOOK type:2, binrayPath:/lib/x86_64-linux-gnu/libssl.so.3
tls_2023/11/28 22:41:14 EBPFProbeOPENSSL	Hook masterKey function:SSL_write
tls_2023/11/28 22:41:14 EBPFProbeOPENSSL	libPthread:/lib/x86_64-linux-gnu/libc.so.6
tls_2023/11/28 22:41:14 EBPFProbeOPENSSL	target all process.
tls_2023/11/28 22:41:14 EBPFProbeOPENSSL	target all users.
tls_2023/11/28 22:41:14 ECAPTURE :: 	start 2 modules

for http1.x

tshark -o tls.keylog_file:ecapture_masterkey.log -Y http -T fields -e http.file_data -f "port 443" -i eth0

for http2

tshark -o tls.keylog_file:ecapture_masterkey.log -Y http2 -T fields -e http2.data.data -f "port 443" -i eth0

ref:https://www.wireshark.org/docs/dfref/h/http2.html

[blaisewang]

Let’s not limit our imagination to just the HTTPS protocol; in fact, TShark (essentially WireShark) can support a wide range of protocols, including but not limited to MySQL （PostgreSQL) connections over TLS, SMTPS, POP3S, and more. Additionally, we should also pay attention to how OpenSSL retrieves the TLS Key Log in HTTP/3.0 (UDP), with the possibility of hooking into new functions to support HTTP/3.0.

[blaisewang]

Theoretically, any protocol listed here (https://www.wireshark.org/docs/dfref/) and encapsulated within the TLS layer can be parsed and displayed.

[blaisewang]

It seems that tshark supports TLS versions 1.0-1.3 well under the HTTP 1.1/2 protocol, but it appears to not support decryption for HTTP 1.0.

Works well for me.

tshark -o tls.keylog_file:key.log -Y http -T fields -e http.file_data -f "port 32888" -i eth0
SSLKEYLOGFILE=key.log curl --local-port 32888 --http1.0 https://www.baidu.com -v

HTTP/1.0 over TLS v1.2 (max supported TLS version for Baidu)

It's really hard find a modern website with both HTTP/1.0 and TLS v1.3 support.

I suppose you'll need to properly set up an Nginx service on your own to kickstart a Ferrari with an antiquated tractor engine (to verify that HTTP/1.0 or even HTTP/0.9 works with TLS v1.3). I believe that the HTTP versions (at least before HTTP/3) and TLS versions are decoupled, and there's fundamentally no need to verify such a multitude of combinations.