Open main menu

Wikibooks β


< OpenSSH
ssh-agent(1) - An authentication agent that can store private keys.
ssh-add(1) - A tool which adds or removes keys to or from the above agent.
ssh-keygen(1) - A key generation tool.
ssh-keyscan(1) - A utility for gathering public host keys from a number of hosts.
ssh-copy-id(1) - Install a public key in a remote machine's authorized_keys register.
ssh-vulnkey(1) - Check a key against blacklist of compromised keys



ssh-agent(1) is a tool to hold private keys in memory for re-use during a session. Usually it is started at the beginning of a session and subsequent windows or programs run as clients to the agent. The environment variable SSH_AUTH_SOCK points applications to the socket used to communicate with the agent.


ssh-add(1) is a tool to load key identities into an agent for re-use. It can also be used to remove identities from the agent. The agent holds the private keys used for authentication.


ssh-keyscan(1) has been part of the OpenSSH suite since OpenSSH version 2.5.1 and is used to retrieve public keys. Keys retrieved using ssh-keyscan(1), or any other method, must be verified by checking the key fingerprint to ensure the authenticity of the key and reduce the possibility of a man-in-the-middle attack. The default is to request a ECDSA key using SSH protocol 2. David Mazieres wrote the initial version of ssh-keyscan(1) and Wayne Davison added support for SSH protocol version 2.


ssh-keygen(1) is used to generate key pairs for use in authentication, update and manage keys or to verify key fingerprints. It can generate ECDSA, Ed25519, or RSA keys and can do the following:

  • generate new key pairs, either ECDSA, Ed25519, or RSA
  • remove keys from known hosts
  • regenerate a public key from a private key
  • change the passphrase of a private key
  • change the comment text of a private key
  • show the fingerprint of a specific public key
  • show ASCII art fingerprint of a specific public key
  • load or read a key to or from a smartcard, if the reader is available

If the legacy protocol, SSH1, is used, then ssh-keygen(1) can only generate RSA keys. However, SSH1 is long since deprecated and the systems should be re-tooled if found in use. Also, DSA keys can also be generated. However, they too are deprecated and replaced if found.

One important use for key fingerprints is when connecting to a machine for the first time. A fingerprint is a hash or digest of the public key. Fingerprints can be transferred out of band and loaded into either the ~/.ssh/known_hosts or /etc/ssh/ssh_known_hosts files in advance of the first connection. The verification data for the key should be sent out of band. It can be sent ahead of time by post, fax, SMS or a phone call instead or otherwise communicated in some way such that you can be sure it is authentic and unchanged.

$ ssh -l fred
The authenticity of host ' (' can't be established.
RSA key fingerprint is SHA256:DnCHntWa4jeadiUWLUPGg9FDTAopFPR0c5TgjU/iXfw.
Are you sure you want to continue connecting (yes/no)? 

If you see that message and the key's fingerprint matches the one you were given in advance, then the connection is probably good. If you see that and the key's fingerprint is different than what you were given in advance, then stop and disconnect and get on the phone or VoIP to work out the mistake. Once the SSH client has accepted the key from the server, it is saved in known_hosts.

$ ssh -l fred
Someone could be eavesdropping on you right now (man-in-the-middle attack)!
It is also possible that a host key has just been changed.
The fingerprint for the ECDSA key sent by the remote host is
Please contact your system administrator.
Add correct host key in /home/fred/.ssh/known_hosts to get rid of this message.
Offending ECDSA key in /home/fred/.ssh/known_hosts:1
ECDSA host key for has changed and you have requested strict checking.
Host key verification failed.

If you start to connect to a known host and you get an error like the one above, then either the first connection was to an impostor or the current connection is to an impostor, or something very foolish was done to the machine. Regardless, disconnect and don't try to log in. Contact the system administrator out of band to find out what is going on.[1] It is possible that the server was reinstalled, either the whole operating system or just the OpenSSH server, without saving the old keys. That would result in new keys being generated and explain their presence. Either way, check with the system administrator before connecting to be sure.

Hashed host names and addresses can be looked up in known_hosts using -F. Or else -R can be used to delete them.

$ ssh-keygen -F -f ~/.ssh/known_hosts
# Host found: line 7 type RSA
|1|slYCk3msDPyGQ8l0lq82IbUTzBU=|KN7HPqVnJHOFX5LFmTXS6skjK4o= ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAIEA3cqqA6fZtgexZ7+4wxoLN1+YDvPfBtt4/m+N/RI8o95CXqvqZMIQjuVarVKjwRwt9pTJIVzf6bwjcNkrUx9dQqZNpNBkcvBRdmd775opWCAfkHEueKxkNx3Kb1yitz0dUaFkRwfTsXAjh+NleBq2ofAfjowu/zzCnnbAKy2R2OE=


ssh-copy-id is included in some distros to install a public key into a remote machine's authorized_keys file. It is a simple shell script and the authorized_keys file should still be checked manually after first login to verify that everything went ok and that the key was copied as it should be.


ssh-vulnkey was included in some versions of some GNU/Linux distros to check a key against a blacklist of compromised keys. The blacklist was made necessary when a broken version of OpenSSL was distributed by some distros[2], resulting in bad keys that were easily predicted and compromised. Keys made while that broken version was in use that are found to have been compromised cannot be repaired and must be replaced. The problem has since been fixed and new keys should be all right.



  1. Brian Hatch (2004). "SSH Host Key Protection". SecurityFocus. Retrieved 2013-04-14. 
  2. Jake Edge (2008). "Debian vulnerability has widespread effects". LWN. Retrieved 2013-04-14.