View source

[[SSH]] provides secure logins and file transfer capabilities.  Traditionally, users log in using passwords; however, SSH supports a host of other authentication mechanisms.  In particular, SSH's key-based login mechanism provides users the ability to log in without sending passwords over the network, and (with some configuration) the ability to avoid entering a password or passphrase more than once per session.

This document describes how to create, use, and manage SSH keys for authentication.

== Conventions ==
Unfortunately, OCF machines have up to three separate implementations of SSH installed; they have (mostly) compatible syntax, but (mostly) incompatible key formats.  Therefore, it is important to specify which implementation of SSH is being talked about.  Throughout this document:
* <tt>ssh</tt>, <tt>ssh-keygen</tt>, <tt>ssh-agent</tt> and the like refer to the [http://www.openssh.org OpenSSH] implementation.  OpenSSH (or a derivative) is the default implementation of SSH on all OCF machines as of March 15, 2007.  Developed by the OpenBSD project as free and open-source software, OpenSSH and its derivatives are by far the most popular SSH implementations for Unix machines; chances are good that the <tt>ssh</tt> binaries installed on any Unix system you have access to come from OpenSSH.  OpenSSH comes standard with almost all Linux distributions, BSD Unix systems, and Mac OS X, and derivatives have been shipped in products as diverse as Sun's Solaris 9 and 10 (a light modification called SunSSH) and Cisco routers.
* <tt>ssh1</tt>, <tt>ssh-keygen1</tt>, and the like refer to the commercial SSH implementation version 1.2.33 formerly distributed by [http://www.ssh.com SSH Communications Security] ("commercial SSH1" for short).  Extremely out-of-date and supporting only the weaker SSH1 protocol, it is (or should be) rare on modern machines.  It should be irrelevant to this document, except that it was installed as the default SSH implementation on OCF's Solaris 8 machines until March 15, 2007, and will continue to be available on the OCF as <tt>ssh1</tt> after that.
* <tt>ssh2</tt>, <tt>ssh-keygen2</tt>, and the like refer to the commercial SSH implementation version 3.2 distributed by SSH Communications Security ("commercial SSH2" or "SSH.com SSH" for short).  This is a more up-to-date implementation supporting the SSH2 protocol (though SSH Communications Security has moved on to versions 4 and 5 of its product, which are not available for free download), but is nowhere near as common as the OpenSSH implementation.

The symbol
 $
indicates your shell prompt; when prefixed by a leading tilde (<tt>~</tt>)
 ~$
this indicates that you should be in your home directory when running this command.

== Creating a new OpenSSH key ==
On a machine with OpenSSH installed:
<pre>
~$ ssh-keygen -b 2048 -f .ssh/id_rsa
Generating public/private rsa key pair.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in .ssh/id_rsa.
Your public key has been saved in .ssh/id_rsa.pub.
The key fingerprint is:
1d:70:92:fa:e2:b2:57:47:b5:02:e5:42:cb:9f:0d:77 steven@sandcity
</pre>
This will create a new SSH2 private key in <tt>~/.ssh/id_rsa</tt> (one of the places OpenSSH looks for a key by default), with corresponding public key available in <tt>~/.ssh/id_rsa.pub</tt>.  The option <tt>-b 2048</tt> selects 2048-bit encryption for use with the default RSA cipher, which is generally considered sufficiently strong.  (While newer versions of OpenSSH default to generating 2048-bit keys, older versions generate 1024-bit keys, which could potentially be vulnerable to attack in the longer term.  The paranoid may wish to consider larger values than 2048.)  You will be prompted for the passphrase you entered every time you use the private key; to ensure the security of your key, it is strongly recommended that you choose a passphrase which is longer than a regular password, contains different types of characters (upper- and lowercase letters, numbers, symbols, spaces), and is not too easily related to you.  While it is tempting to choose to have no passphrase, this allows anyone who can read those files on disk, whether by accident, abuse, or active attack, to log in as you anywhere you install this key with no further effort.  For a better way to avoid entering your passphrase multiple times, see the section on [[#Running an SSH agent to store your keys|using an SSH agent]].

== Allowing key-based logins to a host (installing a key) ==
To allow logins using this key to machines running the OpenSSH server (chances are very good that any machine you log in to is running OpenSSH) or recent versions of the commercial SSH2 server, do the following:
<pre>
~$ ssh hostname 'cat >> .ssh/authorized_keys' < .ssh/id_rsa.pub
</pre>
You will be prompted for your password.

Now, when you try to log in to this host, you can authenticate using your key instead:
<pre>
$ ssh hostname
Enter passphrase for key '/home/u/us/username/.ssh/id_rsa':
</pre>

== Running an SSH agent to store your keys ==
Entering your passphrase every time you want to log in to a machine may seem like no improvement over entering passwords (especially if you followed the suggestions for choosing a passphrase above).  However, OpenSSH supports retrieving its keys from an agent, to which you only need to give your passphrase once.

=== Starting an SSH agent ===
First of all, check to see whether you actually need to do this; many modern desktop environments start an SSH agent automatically for you:
<pre>
$ [ -z $SSH_AGENT_PID ] || echo "SSH agent running"
SSH agent running
</pre>
If you see the words <tt>SSH agent running</tt> printed out when you run this, an SSH agent is already running.

Otherwise, start the SSH agent:
<pre>
$ eval `ssh-agent`
Agent pid 18368
</pre>
If you get lots of errors from your shell when running this, try <tt>eval `ssh-agent -c`</tt> (if running a C shell) or <tt>eval `ssh-agent -s`</tt> (if running ksh, bash, or another Bourne-style shell).

Note that you will only be able to access this agent from within this particular shell; if you need to access it from others, you can propagate the values of the environment variables <tt>SSH_AGENT_PID</tt> and <tt>SSH_AUTH_SOCK</tt> to your other shells.
<!-- (sluo) I have a nice Tcl script for doing this, though I don't ever use it myself (GNOME starts agents automatically); should I mention them or install them somewhere? -->

=== Adding a key to a running SSH agent ===
<pre>
$ ssh-add
Enter passphrase for /home/u/us/username/.ssh/id_rsa:
</pre>
Enter your passphrase, and the key will be entered into the agent.

=== Listing the keys available in a running SSH agent ===
<pre>
$ ssh-add -l
2048 1d:70:92:fa:e2:b2:57:47:b5:02:e5:42:cb:9f:0d:77 /home/u/us/username/.ssh/id_rsa (RSA)
</pre>

=== Shutting down an SSH agent ===
<pre>
$ eval `ssh-agent -k`
Agent pid 18368 killed
</pre>
You may wish to drop this in the logout scripts for your shell, as this turns out to be quite easy to forget to do, which leads to you leaving SSH agents lying around all over the place.
<!-- (sluo) My scripts take care of this too. -->

== Converting an SSH1 key for use with SSH2 ==
This section explains how to convert one's SSH protocol version 1 key to be supported by SSH protocol version 2 clients, as SSH1 keys cannot be used directly in SSH2-only environments.

Note that you can continue to use your old SSH1 key with <tt>ssh1</tt> (on the Solaris machines only), or with the <tt>-1</tt> option to OpenSSH (<tt>ssh -1</tt>).  However, SSH1 has some security weaknesses, so you are encouraged to migrate to SSH2 as soon as possible, whether by generating new SSH2 keys (see above) or by converting your existing SSH1 keys.

The information below is based on [http://www.ocf.berkeley.edu/~dwc/ssh-key-conversion.shtml instructions] written by an OCF staffer.

=== Converting SSH1 keys to commercial SSH2 format ===
From one of the OCF's Solaris 8 machines, or from any machine with the commercial SSH2 client installed, assuming that your existing SSH1 key is <tt>~/.ssh/identity</tt> (the default): 
<pre>
~$ ssh-keygen2 -1 .ssh/identity
Passphrase :
Successfully saved private key to .ssh/identity_ssh2
Successfully converted public key to .ssh/identity_ssh2.pub
</pre>

This will allow you to use your existing key with the SSH2 client, once you've installed the SSH2 version of your key on the hosts that you log in to.

If you use the commercial SSH2 client, you can make it easier for it to find your key:
<pre>
~$ mkdir .ssh2/
~$ mv .ssh/identity_ssh2 .ssh/identity_ssh2.pub .ssh2
</pre>

=== Converting commercial SSH2 keys for use with OpenSSH ===
As the OpenSSH implementation is so dominant these days, you will most likely need to convert your key to OpenSSH format to be able to use it to log in to most servers.  (This also allows you to use the much more common OpenSSH client.)  While OpenSSH will not convert SSH1 keys directly to OpenSSH SSH2 keys, it will convert unencrypted (empty passphrase) keys from the commercial SSH2 client.

Start by removing the passphrase from your commercial SSH2 key:
<pre>
~$ ssh-keygen2 -e .ssh/identity_ssh2
Passphrase needed for key "-".
Passphrase :
Do you want to edit key "-" (yes or no)? yes
Your key comment is "-". Do you want to edit it (yes or no)? no
Do you want to edit passphrase (yes or no)? yes
New passphrase :
Again          :
Do you want to continue editing key "-" (yes or no)? no
Do you want to save key "-" to file .ssh/identity_ssh2 (yes or no)? yes
</pre>

Now convert the keys to OpenSSH format:
<pre>
~$ umask 077    # prevent others from reading the new unencrypted key
~$ ssh-keygen -i -f .ssh/identity_ssh2 > .ssh/id_rsa
~$ ssh-keygen -i -f .ssh/identity_ssh2.pub > .ssh/id_rsa.pub
</pre>
The <tt>~/.ssh/id_rsa.pub</tt> file is the key you want to install on other machines to allow you to log in with this keypair.

You should set a passphrase on your OpenSSH private key to protect it:
<pre>
~$ ssh-keygen -p -f .ssh/id_rsa
Key has comment 'id_rsa'
Enter new passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved with the new passphrase.
</pre>

You can now reencrypt (with <tt>ssh-keygen2 -e</tt>, as above) or delete your commercial SSH2 key.