Skip to content
Riptides Docs

Platform Architecture

Riptides is an identity-first workload security platform that enforces authentication, authorization, and credential management at the kernel level. The platform consists of three components: a centralized control plane, a per-node daemon, and a Linux kernel module. Together, they provide transparent mutual TLS, workload identity, and credential injection without application changes.

Components

Section titled “Components”

Control Plane

Section titled “Control Plane”

The control plane is the central management layer. It defines and distributes identity policies, issues certificates, and acts as the trust anchor for the entire platform.

The control plane includes:

  • API server — A Kubernetes-style API server that exposes Custom Resource Definitions (CRDs) for all Riptides resources: workload identities, services, credential sources, credential bindings, verifiers, and federation configuration. Operators interact with it using standard kubectl commands.
  • Controllers — Reconcile declared policy into concrete artifacts (certificates, access rules, credential bindings) that the enforcement layer consumes.
  • OIDC provider — Handles user authentication for the control plane UI and API. External identity providers (GitHub, Google, etc.) authenticate human users via OIDC, and Riptides manages sessions and access control.
  • gRPC server — Serves policy, certificate, and credential updates to daemons. Daemons maintain a persistent gRPC connection and receive updates in real time.
  • Tunnel server — Provides a secure communication channel for daemons that cannot reach the control plane directly (for example, daemons behind NAT or in private networks).
  • Front proxy — TLS-terminates inbound API and gRPC connections and routes them to the appropriate backend.

The control plane can be deployed as a managed service, a dedicated instance, or on-premises.

Daemon

Section titled “Daemon”

The daemon runs on every node that hosts workloads. In Kubernetes environments it runs as a DaemonSet; on bare-metal or VM hosts it runs as a standalone binary.

The daemon is responsible for:

  • Node attestation — On startup, the daemon authenticates to the control plane using a configured Verifier (JoinToken, AWS Instance Identity Document, GCP Instance Identity Token, and others). This establishes the node’s identity.
  • Metadata collection — Gathers host and workload metadata from the environment: Kubernetes pod labels, namespaces, and container names; AWS instance identity; OS information; network interfaces. This metadata drives workload attestation.
  • Policy synchronization — Receives identity, service, and credential policies from the control plane and loads them into the kernel module.
  • Certificate operations — Acts as a local certificate authority or forwards certificate signing requests to the control plane. Signs CSRs generated by the kernel module for workload SVIDs.
  • Kernel communication — Communicates with the kernel module through the /dev/riptides character device using Protocol Buffer messages.

Kernel Module

Section titled “Kernel Module”

The kernel module is a Linux kernel module (not eBPF) that enforces security policy at the socket level. It intercepts TCP connections transparently and applies identity-based authentication and authorization without any application changes.

Key capabilities:

  • TLS/mTLS termination — Performs full TLS 1.3, quantum-ready handshakes in kernel space. When kernel TLS (kTLS) is available, symmetric cryptographic operations are offloaded to kTLS for performance, with an in-kernel TLS implementation as a fallback.
  • Private key protection — Workload private keys are generated and stored in kernel memory. They are never accessible from user space, eliminating an entire class of key-theft attacks.
  • Policy enforcement — Evaluates access control rules at connection time. Connections that violate policy are dropped before any application code executes.
  • Credential injection — Intercepts outbound HTTP requests and rewrites headers on the wire (for example, adding Authorization headers or AWS SigV4 signatures) before packets leave the machine. The application never handles the credential directly.
  • Transparent operation — Applications connect using ordinary plaintext TCP sockets. The kernel module intercepts at the socket level and upgrades connections to TLS or mTLS as policy dictates.

Trust Domains and SPIFFE

Section titled “Trust Domains and SPIFFE”

Riptides uses the SPIFFE (Secure Production Identity Framework for Everyone) standard for workload identity.

Every deployment operates within a trust domain (for example, example.com). Within a trust domain, each workload receives a SPIFFE ID of the form:

spiffe://<trust-domain>/<workload-id>

Workloads prove their identity using SVIDs (SPIFFE Verifiable Identity Documents), which are X.509 certificates or JWT tokens containing the workload’s SPIFFE ID.

Data Flow

Section titled “Data Flow”

The following describes how policy moves from declaration to enforcement:

  1. Declare — An operator creates or updates identity, service, and credential policies on the control plane using CRDs.
  2. Distribute — The control plane reconciles the policies and pushes the resulting configuration (certificates, access rules, credential bindings) to daemons over gRPC.
  3. Load — Each daemon writes the configuration to the kernel module through the /dev/riptides character device.
  4. Enforce — The kernel module applies the configuration immediately. New and existing connections are evaluated against the loaded policies. TLS handshakes use the provisioned certificates, and credential injection rules take effect on matching outbound requests.

This push-based architecture means policy changes propagate to all nodes without requiring workload restarts or redeployments.