GnuTLS and NSS Modules ​

Purpose and Scope ​

This document describes the GnuTLS and NSS/NSPR capture modules in ecapture. These modules provide TLS/SSL traffic interception for applications that use alternative TLS libraries instead of OpenSSL. For OpenSSL and BoringSSL interception, see OpenSSL/BoringSSL Module. For Go's native TLS implementation, see Go TLS Module.

The GnuTLS module targets applications using the GNU TLS library (libgnutls.so), commonly found in GTK-based applications and Linux command-line tools like wget. The NSS/NSPR module targets applications using Mozilla's Network Security Services library (libnspr44.so), primarily Firefox, Thunderbird, and Chrome on some Linux distributions.

Module Architecture ​

Both modules follow the standard ecapture module pattern but hook different library functions than the OpenSSL module. They capture plaintext data at the TLS library boundary before encryption (send) and after decryption (receive).

Sources: cli/cmd/gnutls.go:1-65, cli/cmd/nspr.go:1-52, user/event/event_gnutls.go:1-157, user/event/event_nspr.go:1-174

GnuTLS Module ​

CLI Command and Configuration ​

The GnuTLS module is invoked using the gnutls command (alias: gnu). It provides options similar to the OpenSSL module but targets GnuTLS libraries.

Sources: cli/cmd/gnutls.go:29-56

Usage Examples ​

# Basic text capture
ecapture gnutls

# Capture with hex output for specific PID
ecapture gnutls --hex --pid=3423

# Save to log file
ecapture gnutls -l save.log --pid=3423

# Specify custom library path
ecapture gnutls --gnutls=/lib/x86_64-linux-gnu/libgnutls.so

# Keylog mode for Wireshark decryption
ecapture gnutls -m keylog -k ecapture_gnutls_key.log --ssl_version=3.7.9

# Pcap capture with network interface
ecapture gnutls -m pcap --pcapfile save.pcapng -i eth0 --gnutls=/lib/x86_64-linux-gnu/libgnutls.so tcp port 443

Sources: cli/cmd/gnutls.go:36-43

GnuTLS Event Structure ​

The GnutlsDataEvent structure captures plaintext data intercepted at the GnuTLS library boundary.

Event Fields:

• DataType: 0 (ProbeEntry) for received data, 1 (ProbeRet) for sent data
• Timestamp: Kernel time converted to Unix nanoseconds using DecodeKtime()
• Pid/Tid: Process ID and thread ID of the GnuTLS-using process
• Comm: Process command name (16 bytes)
• Data: Raw plaintext payload (up to MaxDataSize = 16KB)
• DataLen: Actual length of captured data

UUID Format: Pid_Tid_Comm_DataType - e.g., 12345_12346_wget_0

Sources: user/event/event_gnutls.go:25-157

Event Decoding and Display ​

The module decodes events from binary eBPF perf buffer data:

The String() method formats output with color coding:

• Green (ProbeEntry): Received N bytes
• Purple (ProbeRet): Send N bytes

Example output format:

PID:1234, Comm:wget, TID:1234, TYPE:Received, DataLen:512 bytes, Payload:
GET / HTTP/1.1
Host: example.com

Sources: user/event/event_gnutls.go:37-102

NSS/NSPR Module ​

CLI Command and Configuration ​

The NSS/NSPR module is invoked using the nspr command (alias: nss). It is simpler than the GnuTLS module, providing only text-mode capture.

Module Aliases: The command can be invoked as either ecapture nspr or ecapture nss.

Sources: cli/cmd/nspr.go:27-46

Usage Examples ​

# Basic capture
ecapture nspr

# Hex output for specific PID
ecapture nspr --hex --pid=3423

# Save to log file
ecapture nspr -l save.log --pid=3423

# Specify custom library path
ecapture nspr --nspr=/lib/x86_64-linux-gnu/libnspr44.so

Sources: cli/cmd/nspr.go:35-39

NSS/NSPR Event Structure ​

The NsprDataEvent structure is nearly identical to GnutlsDataEvent but includes special handling for Mozilla applications.

Key Differences from GnuTLS:

• Target library: libnspr44.so (Mozilla's NSPR)
• Primary use case: Firefox, Thunderbird, Chrome (some distributions)
• Thread-name aware: Firefox's network operations occur in threads named "Socket Thread"

Sources: user/event/event_nspr.go:26-174

Firefox/Thunderbird Support ​

The NSS/NSPR module is specifically designed for Mozilla applications. The event decoder contains logic to detect Firefox's communication thread:

var fireThread = strings.TrimSpace(fmt.Sprintf("%s", ne.Comm[:13]))
// Firefox network thread is named "Socket Thread"

While the filtering is currently disabled (if false && ...), this demonstrates awareness of Mozilla's threading model. The first 13 bytes of the Comm field are checked against the string "Socket Thread".

UUID Format: Pid_Tid_Comm_DataType - e.g., 5678_5679_Socket Thread_1

Sources: user/event/event_nspr.go:84-93

Event Processing Flow ​

Both modules follow identical event processing paths after capturing data:

Event Type: Both modules use TypeEventProcessor as their event type, which routes events to the event processing pipeline for potential HTTP parsing and protocol detection.

Sources: user/event/event_gnutls.go:104-108, user/event/event_nspr.go:123-127

Comparison with OpenSSL Module ​

The following table highlights key differences between the OpenSSL, GnuTLS, and NSS modules:

Sources: user/event/event_openssl.go:77-198, user/event/event_gnutls.go:25-157, user/event/event_nspr.go:26-174

Module Registration and Initialization ​

Both modules register with the ecapture module system through the standard pattern:

Module Names:

• GnuTLS: module.ModuleNameGnutls
• NSS/NSPR: module.ModuleNameNspr

Sources: cli/cmd/gnutls.go:59-64, cli/cmd/nspr.go:49-51

Library Detection Strategy ​

Both modules support automatic library detection when no path is specified:

1. Search System Paths: Check standard library locations (/lib, /usr/lib, /lib64, /usr/lib64)
2. LD Library Path: Parse /etc/ld.so.conf and /etc/ld.so.conf.d/*
3. Linked Libraries: Examine target process memory maps
4. Fallback: Use default system paths

Specified Path Priority: If --gnutls or --nspr flags are provided, those paths are used directly without auto-detection.

Sources: cli/cmd/gnutls.go:49, cli/cmd/nspr.go:44

Limitations and Considerations ​

GnuTLS Module Limitations ​

• No connection correlation: Unlike OpenSSL module, does not capture socket metadata or connection tuples
• Version compatibility: May require --ssl_version flag for accurate keylog generation
• Pcap mode complexity: Requires TC classifier for network-level capture

NSS/NSPR Module Limitations ​

• Text mode only: No pcap or keylog modes currently implemented
• Thread filtering: Firefox-specific optimizations are disabled in current implementation
• Limited metadata: No TLS version, cipher, or connection information captured

Common Limitations ​

• Binary data handling: Both modules capture up to 16KB (MaxDataSize) per event, which may truncate large payloads
• Performance impact: Uprobe overhead increases with high-frequency calls
• Root privileges: Both modules require root/CAP_BPF capabilities

Sources: user/event/event_gnutls.go:32, user/event/event_nspr.go:32

Integration with Output Formats ​

Both modules support the standard ecapture output pipeline:

Protobuf Support: Both event types implement ToProtobufEvent() for serialization to external systems, though they populate limited fields (no IP addresses or ports).

Sources: user/event/event_gnutls.go:125-139, user/event/event_nspr.go:143-157