How do I use KeePassXC as an SSH agent?

Question

There's an SSH Agent tab in KeePassXC's options. How do I use it to manage my SSH keys across multiple Windows and Linux machines?

Answer 1

The SSH Agent has a whole dedicated section in KeePassXC docs. It's probably best to read it whole to get a general idea of how it works. If you don't want to, here's a summary.

KeePassXC doesn't act as a full-blown SSH agent replacement. Instead, it communicates with an already running SSH agent and adds or removes SSH keys as needed.

Private keys can be stored entirely in a KeePassXC database. Alternatively, you can keep password-protected key files in the filesystem and use KeePassXC to unlock them automatically using a password stored in the DB and insert them into agent.

Keys can be added and removed on demand or automatically when the database is opened/closed. You can also set timeouts for key removal and enable confirmations on per-key basis.

Pretty neat!

One major drawback of this setup is that on Windows git won't work with the SSH agent. Other OSes aren't affected. See the dedicated section about this problem, its consequences and possible workarounds at the end.

Adding keys to KeePassXC

Add a new entry. Name it as you wish.

The username will be used as a key name in the agent (ssh-add -l). The password will be used to unlock the key if it's password protected.

Advanced tab: Add the private key as an attachment if you wish to store it in the database (useful for sharing between systems if your database is already shared somehow).

Auto-Type tab: Uncheck Enable Auto-Type for this entry.

SSH Agent tab: Configure when the key is added and removed to your liking. Choose your private key from attachments or the filesystem.

Browser Integration tab: Check Hide this entry from the browser extension.

Linux

I've tested this on Pop!_OS 18.04, which is a closely related fork of Ubuntu.

This feature should mostly work out of the box, just enable it in KeePassXC settings.

Use ssh-add -l to check if your keys are loaded (if you've chosen to add them manually, you can do this by right-clicking them and selecting Add key to SSH Agent).

SSH Agent does not work if KeePassXC is installed as a snap package. If snap info keepassxc returns something, you must remove the snap version and install a regular one using apt. If you're on Pop!_OS and apt installs an older version than snap, see this question: KeePassXC is not upgrading to latest version on Pop!_OS.

Windows

Answer tested on Windows 10 version 2004.

First of all, you have to be using the OpenSSH Client that comes with Windows 10. It's a bit different than "bare" OpenSSH when it comes to communication with the agent. Make sure you have OpenSSH Client component installed (it's optional - may be missing if you've removed it explicitly or upgraded from an older version of Windows).

If you have another SSH client installed (for example the one that comes with git), make sure that the Windows one is used on the command line. Typing where ssh-add in the cmd window should return C:\Windows\System32\OpenSSH\ssh-add.exe as the first entry. If that's not the case, you have to reorder your PATH entries.

You also have to enable the agent's service. Open services.msc and find OpenSSH Authentication Agent. Set its Startup type to Automatic, apply and start it.

Unfortunately the version of SSH client that comes with Windows 10 before version 21H1 is buggy and doesn't work with RSA keys (this has been patched in 21H1). If you are running a version of Windows earlier than 21H1, then you must apply this workaround:

1. Stop the agent service.
2. Download the latest release of OpenSSH-Win64.zip from GitHub. Extract it to C:\Program Files\OpenSSH-Win64.
3. Open regedit and go to HKLM\SYSTEM\CurrentControlSet\Services\ssh-agent. Change ImagePath to C:\Program Files\OpenSSH-Win64\ssh-agent.exe
4. Start the service.

Now enable the SSH Agent in KeePassXC settings and check Use OpenSSH for Windows instead of Pageant.

Use ssh-add -l to check if your keys are loaded (if you've chosen to add them manually, you can do this by right-clicking them and selecting Add key to SSH Agent).

How do I use my keys in ~/.ssh/config?

Save a corresponding public key in the filesystem and use it in the config. ssh will use the correct key from KeePassXC if it's added to agent.

Git issues on Windows

The msys git (ie. the default Windows build of git) doesn't seem to work with the Windows SSH agent. The git's agent, on the other hand, doesn't work (well) with KeePassXC on Windows.

If you use git over SSH with keyfile authentication, you'll have to apply a workaround, namely configure git to use a fixed keyfile rather than the agent. For this to work you'll have to store the private key in the filesystem, which may defeat the purpose of storing it in KeePassXC in the first place. If you're going to use this workaround, make sure the keyfile is password protected. KeePassXC will use entry's password value to unlock the key. For git you'll have to unlock it manually every time you use it.

It should be possible to run git's SSH agent in parallel with Windows's, but they won't share identities. You can ssh-add identities from keyfiles stored in the filesystem to that 2nd agent to avoid re-entering the password on each use. I haven't tried this setup myself yet, so I can't provide exact instructions.