SSH Key Authentication Howto

A more secure method of authentication is through the use of RSA keys. The basic principle is as follows. Each user generates a 1024bit public/private key pair for himself. Generally, each user has a different key for every system he is on, but frequently, if he has multiple trusted hosts, it can be more convenient to use the same key on all the systems to simplify things.
Any host to which the user wants to connect must be aware of his public RSA key, as the server uses it during the authentication process. The user must place his public key living on the originating client machine, into his own authorized_keys file on the server.
When he wants to connect to that server, ssh will first negotiate an encrypted session, then send the server the client's public key. The server checks that the public key is in the user's authorized_keys. If so, the server sends the client a challenge (a random number encrypted with the user's public key). If the client can then send back the random number unencrypted, it has just proven that it has the private key (there is no other way to unencrypt the challenge number), and is therefore authentic.
The user's private key is a very sensitive piece of data - with it, anyone can connect to any host on which the corresponding public key is in the authorized_keys. Therefore, the user's private key is never written to disk unencrypted.
The private key is encrypted using a passphrase made up by the user. The passphrase should generally be around 20 characters in length to prevent brute force cracking attempts against it. With a safe passphrase, there is little risk in exposing the private key.
The advantage of RSA based authentication is that a password is never sent across the line, even in encrypted form. Additionally, you have to remember only one passphrase rather than a password for each system you log into. However, because of the neccessity for a long passphrase on a private key, it is becomes very inconvenient to type it every time you connect to another host.

If you hate having to type passwords, then learn how to more securely login via SSH. A method which also happens to ease the need to type your password over and over.
Secure Shell (SSH) public key authentication can be used by a client to access servers, if properly configured. These notes describe how to configure OpenSSH for public key authentication, how to enable a ssh-agent to allow for passphrase-free logins, and tips on debugging problems with SSH connections. Password free logins benefit remote access and automation, for example if administering many servers or accessing version control software over SSH.

Definition of terms used in this documentation:

  • client system: the system one types directly on, such as a laptop or desktop system.
  • server: anything connected to from the client. This includes other servers accessed through the first server connected to.

For more information, see also SSH, The Secure Shell: The Definitive Guide.


We use OpenSSH. OpenSSH is maintained by the OpenBSD project. While it is compatible with both SSH protocols 1 and 2, only SSH protocol 2 is made available. Further, only RSA keys are allowed.

Public-Key Authentication

Public-key authentication uses a pair of keys, one private and one public.

The private key resides on your local computer. This should be closely guarded because someone getting it is equivalent to stealing your password. Always use a passphrase to safeguard your private key. This encrypts your private key so that even if someone obtains it they will not be able to use it (don't worry with a little effort you won't have to type this in as frequently as a password -- stay tuned for ssh-agent).

The public key sits in your home folder on the server.

During authentication your private key and public key exchange some information and if they match against a cryptographic test, you are authenticated.

Detailed information can be found about this and all following topics in SSH, The Secure Shell: The Definitive Guide

Users of PuTTY will want to follow the instructions given here. Be sure you use an RSA key for use with the SSH 2 protocol.

First, confirm that OpenSSH is the SSH software installed on the client system. Key generation may vary under different implementations of SSH. The ssh -V command should print a line beginning with OpenSSH, followed by other details.

$ ssh -V
OpenSSH_3.6.1p2, SSH protocols 1.5/2.0, OpenSSL 0x0090701f

Example of configuring pauli as ssh client and gibbs as ssh server

First thing is to generate your key pair. You will be prompted for a passphrase when you do and I cannot say it enough, use a passphase. Good passphrases are 10-30 characters long, are not simple sentences or otherwise easily guessable. Also, please note that there is no way to recover a lost passphrase. If you lose or forget your passphrase, a new key must be generated and copied to the corresponding public key on the server.

The command to create your key pair is
 yuan_pauli> mkdir ~/.ssh
 yuan_pauli> chmod 700 ~/.ssh
 yuan_pauli>  ssh-keygen -q -f ~/.ssh/id_rsa -t rsa

Then you may see something like:
Enter passphrase (empty for no passphrase): …
Enter same passphrase again: …
on the screen.

Here: the -t rsa option tells ssh-keygen to create an RSA (Rivest-Shamir-Adleman) key, which is what you need on our servers (and is widely considered more secure than DSA)
     -f filename Specifies the filename of the key file, which by default: id_rsa.
     -q    Silence ssh-keygen.  Used by /etc/rc when creating a new key

Do not use your account password, nor an empty passphrase. The password should be at least 16 characters long, and not a simple sentence. 
The ssh-agent setup notes below will reduce the number of times this passphrase will need to be used, so using a long passphrase is encouraged

Make sure your private key is only readable by you (e.g., chmod 400 ~/.ssh/id_rsa)

Key Distribution
The public portion of the RSA key pair must be copied to any servers that will be accessed by the client. The public key information to be copied should be located in the ~/.ssh/ file on the client. Assuming that all of the servers use OpenSSH instead of a different SSH implementation, the public key data must be appended into the ~/.ssh/authorized_keys file on the servers.
To distribute your newly generated ~/.ssh/ to ssh server gibbs
1) sftp gibbs
2) lcd  ~/.ssh
3) put
4) ssh gibbs
5) gibbs_yuan@MASTER> cat ~/ >> ~/.ssh/authorized_keys
6) rm ~/
7) yuan_pauli> ssh -o PreferredAuthentications=publickey

If step 7 returns no error info, then you are done and needs no passowrd to login to gibbs when issuing:
pauli_yuan> ssh gibbs

Key Access Limits

As an optional step to limit usage of the public key for access to any servers, a from statement can be used before public key entries in the ~/.ssh/authorized_keys file on the servers to limit where the client system is permitted to access the server from. Without a from limit, any client system with the appropriate private key data will be able to connect to the server from anywhere. If the key pair should only work when the client system is connecting from a host under, set from="*" before the public key data.

server$ cat ~/.ssh/authorized_keys
from="*" ssh-rsa AAAAB3NzaC1…

If a text editor is used to add the from option, ensure the data is saved as a single line; some editors may wrap the public key and thus corrupt the data. Each public key in the ~/.ssh/authorized_keys file must not span multiple lines.

Multiple hosts or addresses can be specified as comma separated values. For more information on the syntax of the from option, see the sshd(8) documentation.

from="*,10.*," …

Configure ssh-agent Process

To reduce the frequency with which the key passphrase must be typed in, setup a ssh-agent(1) daemon to hold the private portion of the RSA key pair for the duration of a session. There are several ways to run and manage ssh-agent, for example from a X11 login script or with a utility like Keychain. These notes rely on the setup of ssh-agent via an @reboot crontab(5) entry, along with appropriate shell configuration.

The ssh-agent must only be run on the client system. The private key of the RSA key pair must remain on the client system. Agent forwarding should be used to make the key available to subsequent logins to other servers from the first server connected to.

  1. Startup cron job
  2. The following crontab(5) entry should run the agent at system startup time. The cron daemons on BSD and Linux systems should support the special @reboot syntax required for this to work.

    @reboot ssh-agent -s | grep -v echo > $HOME/.ssh-agent

    To setup the agent for the first time without having to reboot the system, run the following.

    $ nohup ssh-agent -s > ~/.ssh-agent

    Once the ssh-agent is running, any shells already running will need to source in the environment settings from the ~/.ssh-agent file. The SSH_AUTH_SOCK and SSH_AGENT_PID environment variables set in this file are required for the OpenSSH commands such as ssh and ssh-add to communicate with the ssh-agent on the client system.

    $ . ~/.ssh-agent

    Notes on configuring all shells to be able to run arbitrary commands are available. This reduces the initial setup to the following commands.

    $ nohup ssh-agent -s | grep -v echo > ~/.ssh-agent
    $ allsh - < ~/.ssh-agent

    If csh or tcsh is being used instead of a Bourne-based shell, replace the -s argument with -c, and the source command used instead of . in any running shells.

  3. Shell startup script changes
  4. The shell’s startup script on the client system will need to be modified to pull in the required environment settings from ~/.ssh-agent and setup useful aliases. The agent settings in ~/.ssh-agent should not be read in if the client system is being connected to as a server. Remote connections set the SSH_CLIENT environment variable, so ~/.ssh-agent must not be read in when this variable contains data.

    [ -z "$SSH_CLIENT" ] && . $HOME/.ssh-agent

    alias keyon="ssh-add -t 10800"
    alias keyoff='ssh-add -D'
    alias keylist='ssh-add -l'

    The -t option to ssh-add will remove keys from memory after the specified number of seconds. This option prevents the keys from being left unlocked for long periods of time. Older versions of OpenSSH will not have the timeout -t option.

    For the csh and tcsh shells, slightly different configuration of the agent and aliases is required. Consult the relevant ssh-agent(1) and shell documentation.

Once the ssh-agent is running and shell configured to read in the appropriate settings and set easy aliases, enable the key then test a login to a remote server. The keyon will only need to be run when initially adding the private key data to ssh-agent, and only rerun if ssh-agent is restarted or the key is removed with keyoff.

client$ keyon

client$ ssh
server$ exit
client$ keyoff

Use the keylist command to see what keys are in the agent process.

$ keylist
1024 01:a1:aa:34:21:bc:7d:a4:ea:56:a4:a1:1a:c5:fa:9f /home/…/.ssh/id_rsa (RSA)

If password free logins do not work, see tips on debugging problems with SSH connections to work out where the problem may be.

To make other applications not run from a shell aware of the agent, the environment definitions in the ~/.ssh-agent file will need to be read into the software in question. Consult the documentation for the software to see whether this is possible.