SSH agent

Android · Linux · macOS · Windows
View Markdown

Keyguard can act as an SSH agent for OpenSSH clients such as ssh and git. The private key never leaves your vault: a client sends Keyguard the data to sign and gets back only the signature. No key file sits on disk for other programs to read or copy.

Keyguard asks you to approve requests and logs every request. Agent approvals covers when Keyguard remembers an approval.

Before you begin

  • An SSH Key item in your vault, holding an Ed25519 or RSA key. The Generator creates one, and Keyguard imports OpenSSH and PEM keys, with or without a passphrase.
  • SSH agent turned on in Settings > Developer > SSH agent.

Set up the agent on desktop

Open Settings > Developer > SSH agent > SSH client setup. Under Automatic configuration, select Configure automatically. Choose all SSH hosts or one host or alias, and optionally select your shells. Continue to review the file changes, then select Apply changes. The wizard checks the agent connection after applying. Open a new terminal and test remote authentication with your chosen key.

The Flatpak build can’t edit host files, so the wizard shows a command instead. Run it in a host terminal. It shows the file changes and asks before applying them.

Setup supports Bash, Zsh, Fish, PowerShell 7 and Windows PowerShell 5.1. It adds Keyguard’s settings to the end of each file and leaves your lines unchanged. For Pin hosts to keys, it also adds an Include line to the top of ~/.ssh/config.

Check these lines lists lines that can take precedence over Keyguard’s settings. These are SSH_AUTH_SOCK lines that run later, and IdentityAgent lines earlier in ~/.ssh/config. Make sure they don’t select another agent.

If no files need changes, select Check agent connection. This tests Keyguard’s endpoint; it does not prove which settings your shell loads.

Setup stops for symlinked files, or for a compiled Zsh startup file (.zwc) dated in the future. Resolve these manually, then review again.

The undo icon in Automatic configuration opens a review of recorded settings to remove. Undo preserves other edits and does not stop agents or change the Windows OpenSSH service.

For manual setup:

  1. Add this line to your shell profile, with your platform’s path from Endpoints:

    export SSH_AUTH_SOCK="<ENDPOINT>"

    On Windows, add this line to your PowerShell profile:

    $env:SSH_AUTH_SOCK="\\.\pipe\keyguard-ssh-agent"

  2. Open a new shell.

  3. Run ssh-add -L. It lists the public keys that Keyguard serves.

Instead of SSH_AUTH_SOCK, you can set IdentityAgent in ~/.ssh/config. In this file, write environment variables in braces, such as ${HOME}. On macOS:

Host *
  IdentityAgent "${HOME}/.keyguard/ssh-agent.sock"

On Windows, use forward slashes in the SSH configuration:

Host *
  IdentityAgent "//./pipe/keyguard-ssh-agent"

ssh-add reads SSH_AUTH_SOCK, not IdentityAgent. Select a terminal environment or set the variable explicitly before using ssh-add -L.

Set up the agent in Termux

Termux reaches Keyguard through a helper package.

  1. Install Termux.

  2. In Keyguard, open Settings > Developer > SSH agent > SSH client setup.

  3. In Termux, run the commands under Install package. They add Keyguard’s APT repository and install openssh and keyguard-android-ssh-agent.

  4. Review and apply startup configuration for your shell:

    keyguard-android-ssh-agent --setup-shells bash

    Choose bash, zsh, fish, or a comma-separated list. The helper asks before editing files. To review removal, run keyguard-android-ssh-agent --undo-setup.

  5. Open a new Termux session.

  6. Run ssh-add -L. It lists the public keys that Keyguard serves.

When ssh uses a key, Keyguard asks for your approval.

Use the agent from other Android apps

Apps that support the OpenKeychain SSH Authentication API use Keyguard directly, without Termux. They see Keyguard only while SSH agent is on.

  1. In the other app, select Keyguard as the SSH key provider. The setting’s name depends on the app.
  2. In Keyguard, approve the registration request.

Later requests can ask you to choose a key, unlock the vault or authenticate. To revoke an app, select it in Settings > Developer > Connected apps, then select Revoke.

Sign in with a certificate

An OpenSSH certificate is your public key signed by a certificate authority. A server that trusts the authority accepts it without your key in authorized_keys.

  1. Edit the SSH Key item.
  2. Paste the contents of the key’s -cert.pub file into Certificate, or drop the file on the key.
  3. Save the item.

The agent offers the certificate before the key while the certificate is valid. The item shows why a certificate isn’t offered: it expired, isn’t valid yet, is a host certificate or is for another key. Apps that use the OpenKeychain API get the key only.

Keyguard doesn’t renew certificates. To use one that your certificate authority renews often, keep it on disk and point CertificateFile at it:

Host <HOST>
  CertificateFile ~/.ssh/<KEY_NAME>-cert.pub

Pin hosts to keys

The agent offers every key to every host. A server that allows few attempts can stop with “Too many authentication failures” before it gets the right key. A pinned host gets only its own keys.

  1. Edit the SSH Key item and add a host, such as git@github.com, under SSH bookmarks. Custom field conventions lists the format.
  2. In Settings > Developer > SSH agent, turn on Generate SSH config for bookmarked hosts. If ~/.ssh/config doesn’t include the generated config, the setting stays off. Select Run SSH client setup, or add the line below yourself. Then turn the setting on again.

The Flatpak build can’t read ~/.ssh/config, so the setting turns on without this check. Then follow Set up the agent on desktop again.

For manual setup, add this line to the top of ~/.ssh/config, with your platform’s directory:

Include "<DIRECTORY>/config"
PlatformDirectory
Linux, macOS, Windows~/.ssh/keyguard
Linux, Flatpak~/.var/app/com.artemchep.keyguard/data/ssh-bookmarks

Keyguard keeps a Match host block for each bookmarked host in that file, plus the public keys and certificates it names. It updates them while the vault is unlocked, and deletes them when you turn the setting off. The host names and public keys are not encrypted.

ssh matches only the user and host on its command line. A bookmark for git@github.com doesn’t apply to ssh github.com with User git set later in ~/.ssh/config. A pinned host doesn’t get the default keys from ~/.ssh, so its key login fails while Keyguard isn’t running.

Review request history

In Settings > Developer > SSH agent, select Request log. Each entry shows the caller, the key, the request and its result, such as Success, Denied or Key not found.

To see the requests for one key, open its SSH Key item and select View SSH agent history.

Endpoints

PlatformEndpoint
Android, Termux$PREFIX/tmp/keyguard-ssh-agent.sock
Linux$XDG_RUNTIME_DIR/keyguard-ssh-agent.sock
Linux, Flatpak$XDG_RUNTIME_DIR/app/com.artemchep.keyguard/ssh-agent.sock
macOS$HOME/.keyguard/ssh-agent.sock
Windows\\.\pipe\keyguard-ssh-agent