From Wikibooks, open books for an open world
Jump to: navigation, search
ssh-agent(1) - An authentication agent that can store private keys.
ssh-add(1) - Tool which adds or removes keys in the above agent.
ssh-keygen(1) - Key generation tool.
ssh-keyscan(1) - Utility for gathering public host keys from a number of hosts.
ssh-vulnkey(1) - Check key against blacklist of compromised keys
ssh-copy-id(1) - Install a public key in a remote machine's authorized_keys


ssh-agent 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.


ssh-add 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 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, 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 and Wayne Davison added support for SSH protocol version 2.


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

  • generate new key pairs, either ECDSA, Ed25519, RSA or DSA
  • 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 can only generate RSA keys.

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 sent ahead of time out of band via post, fax, SMS or other means not related to the Internet.

The verification data for the key should be sent out of band, not done via the Internet. It can be sent ahead of time by post, fax, SMS or a phone call instead or some other way you can be sure it is an authentic and unchanged key.

$ 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 and the key matches what your were given in advance, the connection is probably good. If you see that and the key 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 OS or just the OpenSSH server, without saving the old keys resulting in new keys being generated. Either way, check with the system administrator before connecting to be sure.

It is possible to use more than one key per account or the same key on more than one machine. Single-use keys allow some remote data transfer tasks to be automated fairly securely.

The public keys of the hosts you have verified the connections to are stored in known_hosts whereas the public keys of the users you accept logins from are kept in authorized_keys. There are also global files kept on each machine though each account has its own local ones.

When generating keys use good, solid passphrases. Good passphrases are 10 to 30 characters in length and are not simple sentences or otherwise easily guessable words or phrases from any language. It should contain a mixture of upper and lowercase letters, numbers, and non-alphanumeric characters. Passphrases can be changed later, but there is no way to recover a lost passphrase. If the passphrase is lost or forgotten, the key is useless and must be replaced with a new key pair. Hashed host names and addresses can be looked up in known_hosts using -F or -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-vulnkey is included in some 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.


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.



  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.