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 TLS 1.2 supported for interoperability with legacy peers
• Modern AEAD cipher suites: AES-256-GCM, AES-128-GCM, and ChaCha20-Poly1305
• X.509 certificate handling and SPIFFE identity verification
• 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.

Quantum Safety

Riptides protects the confidentiality of mesh traffic against quantum attack today, including the harvest-now, decrypt-later threat where an adversary records encrypted traffic now to decrypt once a quantum computer exists. Both layers that establish and protect the data stream - the key exchange and the symmetric cipher - are quantum-resistant. Authentication (certificate signatures) remains classical for now.

Key exchange - post-quantum hybrid

Session keys are established with a post-quantum hybrid key exchange. The X25519MLKEM768 group combines ML-KEM-768 (FIPS 203, the standardized successor to Kyber) with classical X25519: the shared secret is derived from both an ML-KEM encapsulation and an X25519 Diffie-Hellman exchange. The result is at least as strong as X25519 and adds post-quantum protection, so recorded handshakes cannot be broken by a future quantum computer.

ML-KEM runs entirely in kernel space as part of the in-kernel TLS 1.3 handshake, using a kernel-native FIPS 203 implementation (the SHA-3/SHAKE primitives it depends on are built into the module). Because the handshake always runs in the module - kTLS only offloads the symmetric layer afterward - the post-quantum key exchange applies whether or not kTLS is in use.

The exchange degrades gracefully. For transparent mTLS between Riptides workloads, both ends support the hybrid group and negotiate it directly. For other destinations - including TLS intercept toward external servers - the classical groups remain on offer, so a peer that does not support the hybrid falls back to X25519 automatically: post-quantum wherever the peer allows it, with no loss of connectivity where it does not.

Symmetric layer - quantum-resistant

Bulk traffic is protected by 256-bit AEAD cipher suites - AES-256-GCM and ChaCha20-Poly1305. Symmetric ciphers of this strength are considered quantum-resistant: the best known quantum attack (Grover’s algorithm) only halves the effective key length, leaving AES-256 and ChaCha20 at roughly 128 bits of post-quantum security.

Authentication - classical today

Workload identities are still authenticated with classical signatures - ECDSA (P-256/P-384) or RSA - over SPIFFE X.509 certificates. ML-KEM protects the key exchange (confidentiality), not authentication, so this remains a classical primitive. It is a lower-urgency gap than key exchange: forging a signature requires an active attack at connection time rather than passive recording, so it is not exposed to harvest-now-decrypt-later. Post-quantum signatures (such as ML-DSA / FIPS 204) are a future step.

Note

The negotiated key-exchange group is visible per connection in /proc/riptides/connections as kex_group - X25519MLKEM768 indicates the post-quantum hybrid handshake, X25519 indicates a classical fallback.

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 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