keychain-auth platform support: macOS, Linux, Windows

keychain-auth runs on macOS, Linux, and Windows, using platform-native IPC and kernel-verified process identity on each OS to guard your keychain.

keychain-auth is a cross-platform security daemon. Whether you run macOS, Linux, or Windows, it uses your OS’s native inter-process communication (IPC) channel and kernel-level process verification to ensure only approved, hash-verified binaries can access your credentials. The underlying keychain backend is always the one native to your platform.

Platform comparison

Platform	IPC Mechanism	Verification Backend	Keychain Storage
macOS	Unix Domain Socket	LOCAL_PEERPID & Code Signatures	Apple Keychain Services
Linux	Unix Domain Socket	SO_PEERCRED & /proc/<pid>/exe	GNOME Keyring / KWallet (dbus)
Windows	Named Pipe	GetNamedPipeClientProcessId	Windows Credential Manager

On every platform, the daemon retrieves the caller’s process ID directly from the kernel — self-reported PIDs are never trusted. It then resolves the binary path on disk and computes a SHA-256 hash, checking it against your approved binary database before executing any keychain operation.

How the IPC channel works

On macOS and Linux, the daemon listens on a Unix domain socket owned by your user with 0600 permissions, so no other user account on the system can reach it. On macOS this is ~/Library/Application Support/keychain-auth/agent.sock; on Linux it is $XDG_RUNTIME_DIR/keychain-auth/agent.sock. On Windows, the daemon creates a Named Pipe (\\.\pipe\keychain-auth) with equivalent access restrictions.

The connection itself is the authenticated session. There are no API keys or session tokens: the moment a client connects, the daemon performs kernel-level identity verification and binds a fine-grained access policy to that live connection.

Headless Linux and WSL

If you are running a headless Linux server (no $DISPLAY set) or running inside Windows Subsystem for Linux (WSL), no D-Bus session is available. The daemon detects this automatically and falls back to a secure file-based keyring at ~/.keychain-auth/keyring.json. The file is created with 0600 permissions and secrets are stored base64-encoded. No configuration change is required on your part.

The file-based fallback is not encrypted at rest with a hardware key the way GNOME Keyring or Windows Credential Manager is. For production servers, consider using a secrets manager rather than storing long-lived credentials on disk.

Platform-specific pages

Each platform has its own setup page covering socket paths, verification details, the keychain backend, and the security problem keychain-auth solves on that OS:

• macOS — Apple Keychain Services
• Linux — GNOME Keyring / KWallet
• Windows — Credential Manager