Using Agent Keys

Introduction

Once you have loaded your private keys into the Desktop SSH Agent, it is ready to authenticate your SSH connections.

The agent works by loading private keys into memory and signing authentication requests on-behalf of SSH clients that connect to it. It also allows the clients to list the keys available so the client can check with the server if a public-key is suitable for authentication.

Environment Variables

The Desktop SSH Agent cannot be used at the same time as the default OpenSSH agent process and its only possible to run one agent process at anyone time.

As part of the installation of the Desktop SSH Agent, a number of entries are added to your .bash_profile. Here we can see the entries on OSX

#Added by Desktop SSH Agent
export SSH_AUTH_SOCK_PREV=$SSH_AUTH_SOCK
export SSH_AUTH_SOCK=/Users/lee/.desktop-ssh-agent/agent.sock
export PATH=$PATH:"/Applications/Desktop SSH Agent"
# End Desktop SSH Agent 

The SSH_AUTH_SOCK_PREV variable stores the default OpenSSH agent socket. The SSH_AUTH_SOCK is then replaced by the Desktop SSH Agent’s own socket. This allows the OpenSSH command line, and any other applications that honour this variable to connect to the client.

IMPORTANT

The current version of the Desktop SSH Agent only writes to .bash_profile. Modern versions of OSX now default to using the Zsh shell, so the content of .bash_profile should be moved over to the users .zprofile on OSX. The next release will contain a fix for this.

Similary, Linux users that use a different shell should also move the script to their shells profile.

Windows uses named pipes, but still uses the SSH_AUTH_SOCK variable to point to the named piped of the agent. This is automatically setup as part of the Desktop SSH Agent isntallation.

Troubleshooting

If your SSH client does not connect with and use the agent keys you should check the following things:

  1. Check the value of SSH_AUTH_SOCK in the processes environment is pointing to ~/.desktop-ssh-agent/agent.sock
  2. Test the connection using the Desktop Agent’s buit-in terminal to see if the keys are valid for the host; this action bypasses the socket so will tell you if the problem is related to configuration of the keys, or configuration of the agent and connectivity.
  3. If you think the environment variable is correct then connect to your server using the ssh command line with -vvv arguments. This will create verbose output and will indicate if the agent keys are being used. 

You should see the keys listed like below:

debug1: Will attempt key: LogonBox Key ED25519 SHA256:CZmGwVc59DrR0BdDNVesw4qOjyA0rGM0dl7OkY agent
debug1: Will attempt key: Legacy RSA RSA SHA256:oh3mYiYZAeDGTFbt2hQkwNgKa6Xox7doY+kU agent