Kernel Module

Riptides uses a Linux kernel module to enforce security policies transparently at the socket level. The kernel module handles TLS/mTLS termination, credential injection, and policy enforcement — all without requiring any changes to application code.

Why a Kernel Module?

Riptides chose a kernel module over eBPF for several technical reasons. eBPF programs are sandboxed and limited in what they can do — they cannot generate cryptographic keys, perform full TLS handshakes, inject credentials into HTTP streams, or create sysfs filesystem entries. These are all core capabilities that Riptides requires:

Capability	eBPF	Kernel Module
Generate private keys	No	Yes
Full TLS handshakes	No	Yes
Credential injection (header rewriting)	No	Yes
Sysfs filesystem for credential delivery	No	Yes
Policy enforcement at socket level	Limited	Yes
Private keys isolated from userspace	No	Yes

The kernel module approach means private keys are generated and stored exclusively in kernel memory — they are never accessible from userspace, even by the application they belong to.

TLS in Kernel Space

Riptides runs a compact TLS library in kernel space that provides:

• TLS 1.3 with quantum-ready cipher suites
• Modern cipher suites including ChaCha20-Poly1305 AEAD
• X.509 certificate handling
• Small memory footprint suitable for kernel context

The in-kernel TLS implementation handles the initial handshake (key exchange, certificate verification) and can process the ongoing encrypted stream when kTLS offload is not available.

For transparent mTLS between Riptides-managed workloads, the internal connection is always established with TLS 1.3, and Riptides offers PQC mTLS for this internal traffic.

kTLS Integration

When the kernel’s built-in TLS support (kTLS) is available, Riptides offloads symmetric encryption to it for better performance. The flow is:

1. The in-kernel TLS implementation performs the handshake (asymmetric crypto, certificate exchange)
2. Once the session is established, symmetric keys are handed to kTLS
3. kTLS handles bulk data encryption/decryption in the kernel’s networking stack

If kTLS is not available or not applicable for a particular connection, the in-kernel TLS implementation handles the entire TLS session as a fallback.

Transparent Operation

Applications connect to network services using standard TCP sockets — no TLS libraries, no certificate management code, no authentication logic. The kernel module intercepts connections at the socket level and:

1. Outbound connections: Initiates a TLS/mTLS handshake with the destination and optionally injects credentials into the HTTP stream based on the evaluation context set by the daemon
2. Inbound connections: Terminates TLS, verifies the client certificate against allowedSPIFFEIDs, and forwards plaintext to the application

From the application’s perspective, it sends and receives plaintext. From the network’s perspective, all traffic is encrypted and authenticated.

TLS Termination Modes

The module supports several TLS handling strategies depending on the connection and policy:

• Transparent mTLS: Plaintext connections are automatically upgraded to mTLS. Both endpoints present SPIFFE certificates.
• TLS intercept: The module terminates an existing TLS connection and re-establishes it, allowing credential injection into the HTTP stream between the two TLS sessions. Because the module presents a Riptides-issued certificate to the application, any userspace library or SDK that performs its own TLS verification must be configured to trust the Riptides CA. See Trusting the Riptides CA below.
• TLS pass-through: For connections that are already encrypted, the module can wrap them in an additional Riptides mTLS layer for identity verification without modifying the original payload. The original TLS is not double-encrypted — the Riptides layer provides identity and policy enforcement only.

Trusting the Riptides CA for TLS Intercept

When tls.intercept: true is configured on an egress rule, the kernel module terminates the application’s outbound TLS connection and re-originates a new one to the destination. The application sees a Riptides-issued certificate instead of the destination’s original certificate.

Any userspace library or SDK that performs its own certificate verification will reject this certificate unless configured to trust the Riptides CA. The CA bundle is available at:

/sys/module/riptides/certs/ca-certificates.crt

Configure your application’s TLS trust store to include this file. Common environment variables:

SDK / Library	Environment Variable
AWS SDK	AWS_CA_BUNDLE=/sys/module/riptides/certs/ca-certificates.crt
Python requests	REQUESTS_CA_BUNDLE=/sys/module/riptides/certs/ca-certificates.crt
Node.js	NODE_EXTRA_CA_CERTS=/sys/module/riptides/certs/ca-certificates.crt
Go (net/http)	SSL_CERT_FILE=/sys/module/riptides/certs/ca-certificates.crt
Generic OpenSSL	SSL_CERT_FILE=/sys/module/riptides/certs/ca-certificates.crt
cURL	CURL_CA_BUNDLE=/sys/module/riptides/certs/ca-certificates.crt

Alternatively, you can append the Riptides CA to your system’s existing CA bundle if you prefer a single trust store.

Credential Injection

One of the kernel module’s unique capabilities is on-the-wire credential injection. When a CredentialBinding is configured with injection propagation, the module:

1. Intercepts outbound HTTP requests at the socket level
2. Adds or rewrites HTTP headers (e.g., Authorization: Bearer <token>, AWS SigV4 signature headers)
3. Forwards the modified request to the destination

The application makes a plain HTTP request without any authentication headers. The daemon evaluates the connection context and determines which credentials to inject; the kernel checks the evaluation context and adds them transparently. This means credentials are never exposed in application memory.

Sysfs Based Secure Credential Delivery

For applications that need to read credentials from the filesystem (e.g., GCP Application Default Credentials), the kernel module provides credentials via sysfs:

/sys/module/riptides/credentials/<binding-id>/<binding-name>/token.jwt

Applications can read credential files from this path. The kernel module owns these files, controls access and it also manages credential rotation automatically. Reading the file always returns a current, valid credential.

Daemon Communication

The kernel module communicates with the userspace daemon via the /dev/riptides character device. The daemon uses Protocol Buffers over this interface to:

• Push identity configurations (certificates, private keys, SPIFFE IDs)
• Push service definitions (addresses, ports, labels)
• Push credential bindings and policies
• Receive health and status information

The daemon acts as the bridge between the control plane (which manages policy centrally) and the kernel module (which enforces policy locally).

Diagnostics

The module exposes diagnostic information through procfs and sysfs:

Endpoint	Description
/proc/riptides/health	Module health status
/proc/riptides/certificates	Loaded certificates (JSON)
/proc/riptides/connections	Active connections (JSON)
/proc/riptides/trust-anchors	Trust anchor certificates (JSON)
/sys/module/riptides/credentials/	Credential files

You can also enable/disable the module at runtime without unloading it, and toggle debug logging via the kernel’s dynamic debug facility.

Platform Support

The kernel module runs on Linux and supports:

• Architectures: x86_64, ARM64
• Environments: Bare metal, VMs, Kubernetes nodes
• Installation: Pre-built .deb/.rpm packages via the Riptides package repository
• IPv4 and IPv6 TCP sockets