KepassXC SSH Agent on WSL2

Managing SSH keys securely while using Windows Subsystem for Linux 2 (WSL2) can be a challenge, especially when you want to leverage KeePassXC for SSH key storage and agent functionality. This post outlines a practical workaround to enable SSH access within WSL2 while utilizing SSH keys managed by KeePassXC on the Windows side.

Background

KeePassXC is a popular open-source password manager that also supports storing SSH keys securely within its database. While KeePassXC itself does not provide a native SSH agent, it serves SSH keys to the Windows OpenSSH agent. This integration allows the Windows OpenSSH agent to handle key authentication requests, including keys managed by KeePassXC.

In a WSL2 environment, however, the Linux subsystem is isolated from the Windows environment, causing SSH clients inside WSL2 to not automatically communicate with the Windows SSH agent where the KeePassXC-managed keys reside. To resolve this, a mechanism to bridge communication between WSL2 and the Windows SSH agent is required.

Workaround with Bash Aliases

The approach presented here simplifies usage by transparently redirecting SSH client commands in WSL2 to their Windows counterparts, which can communicate directly with the Windows OpenSSH agent, gaining access to the KeePassXC-stored SSH keys.

Add the following aliases to your ~/.bashrc file in WSL2:

# Redirect SSH commands to Windows executables
alias ssh='ssh.exe -F ~/.ssh/config'

alias ssh-add='ssh-add.exe'
alias scp='scp.exe'
alias sftp='sftp.exe'

# Configure Git to use Windows SSH client
git config --global core.sshCommand "ssh.exe -F ~/.ssh/config"

This setup instructs the shell to use the Windows versions of SSH, SCP, and SFTP, which inherently communicate with the Windows SSH agent (and by extension, with KeePassXC’s SSH key management). The option -F ~/.ssh/config ensures that SSH configuration inside WSL2 is respected when invoking Windows SSH.

Additionally, ensure your ~/.profile sources the .bashrc to load these aliases:

# Load bashrc if present
if [ -f ~/.bashrc ]; then
   . ~/.bashrc

fi

How This Works Technically

• KeePassXC enables SSH agent functionality on Windows by forwarding SSH keys to the Windows OpenSSH agent.
• Windows OpenSSH client (ssh.exe) communicates with the Windows SSH agent to handle authentication requests.
• By aliasing SSH-related commands in WSL2 to the Windows binaries, all SSH operations in WSL2 leverage the Windows SSH agent.
• This circumvents the lack of a native seamless SSH agent forwarding mechanism between WSL2 Linux tools and Windows.
• Git is also configured to use the Windows SSH binary to ensure SSH-based Git operations use the KeePassXC-managed keys without issues.

Benefits

• No need to transfer or duplicate SSH keys between Windows and WSL2.
• KeePassXC remains the single source of truth for SSH key storage and passphrase management.
• Supports common tools like SSH, SCP, SFTP, and Git seamlessly.

Limitations & Notes

• This approach relies on invoking Windows binaries from WSL2, which might have differences in behavior or environment compared to native Linux binaries.
• Users relying on more complex Linux-native SSH configurations or tools may need additional setup.
• More advanced setups to allow native Linux SSH clients communicate with Windows SSH agent involve tools like npiperelay and socat, which require more complex configuration.