Ditching Tokens: Why Iddio Uses Kernel Peer Credentials for Local IPC

When designing the Inter-Process Communication (IPC) architecture for the Iddio daemon and its companion CLI and desktop applications, we face a classic local security problem: how does the daemon reliably authenticate the client connecting to it?

The industry standard answers for local IPC authentication typically involve Mutual TLS (mTLS), local bearer tokens, or loopback TCP connections bound to localhost. We reject all of these.

Instead, Iddio uses Unix domain sockets located at ~/.iddio/iddio.sock (for user-mode) or /var/lib/iddio/iddio.sock (for system-mode) and relies entirely on kernel-level peer credentials—SO_PEERCRED on Linux and LOCAL_PEERCRED on macOS—to authenticate incoming connections.

Here is why we discard the traditional approaches in favor of a kernel-enforced model.

The Flaws in Standard Local Authentication

Most modern applications default to building a miniature network stack on loopback interfaces for local communication. This introduces unnecessary complexity and security vulnerabilities.

The Loopback Problem Binding to 127.0.0.1 or ::1 means you are speaking TCP/IP. You immediately expose the daemon to port scanning and local network interference. If a user runs malicious code or a compromised dependency on the same machine, that code can reach your open loopback port.

The Bearer Token Problem To secure that TCP port, applications often write a secret bearer token to a file on disk (e.g., ~/.config/app/auth.token). The CLI reads this token and sends it in an HTTP Authorization header. This turns authentication into a file-permissions problem. If another process reads that file, it impersonates the CLI. Furthermore, tokens leak in memory dumps, command-line arguments, and swap space.

The mTLS Problem Using mTLS for local IPC is massive overkill. It requires managing local Certificate Authorities (CAs), issuing short-lived client certificates, and handling local rotation. It burns CPU cycles on cryptographic handshakes for data that never leaves the machine.

Enter Kernel Peer Credentials

We completely eliminate the network stack for local communication. The Iddio CLI and desktop app connect to the Iddio daemon exclusively via a Unix domain socket at ~/.iddio/iddio.sock (or /var/lib/iddio/iddio.sock).

Because Unix domain sockets are file system objects, we rely on standard Unix file permissions to restrict initial access. But we do not stop there. The true security guarantee comes from querying the operating system kernel directly for the user identity of the process at the other end of the socket.

When the CLI initiates a connection, the daemon asks the kernel who opened the connection.

On Linux, we call getsockopt with SO_PEERCRED. The kernel returns a ucred struct containing the Process ID (PID), User ID (UID), and Group ID (GID) of the connecting process.

On macOS, we call getsockopt with LOCAL_PEERCRED to retrieve the xucred struct, which provides the UID and a group list (macOS does not supply the PID in xucred). Ultimately, on both platforms, the daemon authorizes the connection by validating the connecting peer’s UID against the expected UID for the socket.

Why the Kernel Model Wins

1. Unforgeable, but Same-UID, Not Same-Process: A userspace process cannot lie about its UID to the kernel, so there are no tokens to steal or forge. Be precise about what this buys you, though: the daemon’s check is same-UID authorization, not full client authentication. It admits any connection whose UID matches the daemon’s own (or root, on the system-mode socket) — not specifically the genuine CLI or desktop binary. That’s an explicit, accepted trade-off for a local daemon, not process- or binary-level attestation.
2. No Secrets on Disk: We eliminate the need to generate, store, and protect local bearer tokens or private keys for mTLS. The UID check is intrinsic to the connecting process’s OS credentials — there is nothing on disk to leak, steal, or rotate.
3. Zero Cryptographic Overhead: We bypass the TCP/IP stack and all TLS handshakes. Data moves directly through kernel memory buffers, drastically reducing latency and CPU usage.

The Reality of Local Governance

In Iddio’s architecture, the daemon operates as a privileged component enforcing policies governed by the Control Server. The CLI and desktop apps are merely unprivileged interfaces to query status and request transient actions.

By anchoring our local IPC authentication to SO_PEERCRED and LOCAL_PEERCRED, we shift the burden of proof from userspace secrets to kernel-level invariants. We eliminate an entire class of local privilege escalation attacks related to token theft and mTLS misconfiguration.

When building for hostile or heavily scrutinized enterprise environments, removing secrets is always superior to protecting them. By letting the kernel handle local identity, we build a faster, simpler, and fundamentally more secure local communication channel.