NSS / NSPR Capture ​

The nspr probe in eCapture is designed to intercept plaintext communication from applications utilizing the Netscape Portable Runtime (NSPR) and Network Security Services (NSS) libraries. This is the primary cryptographic stack for applications like Mozilla Firefox, Thunderbird, and versions of curl compiled with NSS support cli/cmd/nss.go:30-33.

Principle of Operation ​

Unlike the OpenSSL probe which hooks SSL_read and SSL_write, the NSS probe targets the underlying NSPR (Netscape Portable Runtime) I/O layer. Specifically, it hooks the PR_Read and PR_Write functions within libnspr4.so kern/nspr_kern.c:113-152.

Hook Strategy ​

The probe utilizes eBPF uprobe and uretprobe to capture data:

1. uprobe: Attached to the entry of PR_Read and PR_Write to capture the buffer pointer (buf) passed by the application kern/nspr_kern.c:113-126, kern/nspr_kern.c:152-165.
2. uretprobe: Attached to the return of these functions. At this point, the return value (PT_REGS_RC) indicates the number of bytes actually read or written. eCapture then reads that amount of data from the previously captured buffer pointer kern/nspr_kern.c:128-145, kern/nspr_kern.c:167-184.

Data Flow Diagram: NSPR Hooking ​

This diagram illustrates how the eBPF programs interact with the NSPR library functions to extract plaintext.

"NSPR Capture Flow"

Sources: kern/nspr_kern.c:113-184, internal/probe/nspr/nspr_probe.go:114-118 (inferred from typical manager setup)

Code Entity Mapping ​

The following diagram maps the logical capture components to the specific code entities in the kernel and userspace.

"NSS/NSPR Code Entity Map"

Sources: kern/nspr_kern.c:19-53, cli/cmd/nss.go:24-27.

Configuration and Usage ​

The nspr command allows users to specify the path to the NSPR library if it is not in a standard location.

CLI Examples ​

• Basic Capture: ecapture nspr
• Filter by PID: ecapture nspr --pid=3423 cli/cmd/nss.go:36
• Custom Library Path: ecapture nspr --nspr=/usr/lib/libnspr4.so cli/cmd/nss.go:38

Key Parameters ​

Sources: cli/cmd/nss.go:44-47

Implementation Details ​

Kernel Data Structures ​

The kernel program defines a ssl_data_event_t structure to pass data to userspace:

• type: Indicates if it's a Read or Write event kern/nspr_kern.c:20.
• timestamp_ns: Kernel monotonic time kern/nspr_kern.c:21.
• pid/tid: Process and Thread IDs kern/nspr_kern.c:22-23.
• data: The actual plaintext payload (up to MAX_DATA_SIZE_OPENSSL) kern/nspr_kern.c:24.

Userspace Probe Initialization ​

The nssCommandFunc initializes the probe using the factory pattern:

1. Sets the global configuration (PID, Debug, etc.) into nsprConfig cli/cmd/nss.go:50-53.
2. Invokes runProbe with factory.ProbeTypeNSPR cli/cmd/nss.go:55.

Choosing Between Probes ​

When targeting an application, use the following logic to decide if the nspr probe is appropriate:

Sources: cli/cmd/nss.go:30-33, cli/cmd/gnutls.go:33-36, cli/cmd/tls.go:32.