Editing SSH:Authorized Keys

This article originally appeared on the [http://web.archive.org/web/20131003235025/http://www.eng.cam.ac.uk/help/jpmg/ssh/authorized_keys_howto.html University of Cambridge Engineering site].

<h2>Key generation</h2>

<h3>Decisions to make</h3>

<h4>Passphrase or not?</h4> If you use a passphrase, the key will not
   be useable unless you type the passphrase to make it available.  
<p> So this is not helpful if you want ssh to run unattended for some
   reason.
<p> On the other hand, it means that someone with temporary access to your
   account can't just make a copy of the private key file and then use
   it subsequently
<h4>key type?</h4> Unless you have good reason to do otherwise, allow
   the key generator to use its default (rsa for ssh-v2 connections).

<h3>Creating the key</h3>

   You can create a private/public key pair (in the files
   <code>~/.ssh/filename</code> and <code>~/.ssh/filename.pub</code>)
   that has no passphrase protecting the private key, by doing the
   following:

<pre>
   cd ~/.ssh
   ssh-keygen -f filename -C 'Some comment' -N '' -t rsa -q
</pre>

   The two files created (<code>filename</code> and <code>filename.pub</code>)
   can then be used as described below.
<p>   
   If on the other hand, you'd like to protect the private key file with
   a passphrase (which will be needed to be typed at any client that wants
   to use the key pair):

<pre>
   cd ~/.ssh
   ssh-keygen -f filename -C 'Some comment' -t rsa -q
</pre>

   and you'll be prompted for a passphrase.  This has no limitation on
   length.  All the normal advice about non-guessable passwords may 
   reasonably be applied to it, although it's possible that a suitably
   long passphrase consisting of dictionary-attackable words can be just
   as secure as a short passphrase of random characters.

<h3>What the private/public key files are for</h3>

   The private key is the secret one, not surprisingly.  It needs to
   be kept secure (not world-readable).  Only a client with knowledge
   of the private key can correctly respond to a challenge issued
   by a server that is using the public key.
   <p>
   If the private key is not passphrase protected, then the file
   containing it is particularly sensitive; even temporary exposure of
   your account to a third party could allow it to be copied and then
   used inappropriately.
   <p>
   If the private key is passphrase protected, then its vulnerability is
   lower;  an attacker would need a copy of the private key file, and
   <em>also</em> to observe your keystrokes typing the passphrase to
   your client program (or to have inserted a trojan version of the
   client program, or ...).

   The public key does not need to be kept secret; there is no
   practical way of guessing the private key that will match it.  It
   is put in your <code>~/.ssh/authorized_keys</code> file on the
   machine that you want to connect to.  
<p>
   There may be good reasons to keep the <code>authorized_keys</code>
   file protected from world-readability (it may contain directives as
   to what machines may use a given key or what commands will be run
   in response to the use of a given key, which may be sensitive
   information) but protecting the public key is not one of them!
   

<h3>Setting up an authorized_keys file</h3>

   Once you've created your key pair, you can insert the public half
   of it into your authorized_keys file on computer "X".  A client on
   computer "Y" that knows the private key can then authenticate to
   your account on computer "X".
<p>
   So, on the machine you want to log into, you should add a line to
   your <code>~/.ssh/authorized_keys</code> file that contains exactly
   the single line that was created in the <code>filename.pub</code>
   file (for whatever choice of "filename" you made).
<p> 
   For example, we might wind up with a <code>.ssh/authorized_keys</code>
   file that looks like:
<pre>
ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAybmcqaU/Xos/GhYCzkV+kDsK8+A5OjaK
5WgLMqmu38aPo56Od10RQ3EiB42DjRVY8trXS1NH4jbURQPERr2LHCCYq6tHJYfJNhUX
/COwHs+ozNPE83CYDhK4AhabahnltFE5ZbefwXW4FoKOO+n8AdDfSXOazpPas8jXi5bE
wNf7heZT++a/Qxbu9JHF1huThuDuxOtIWl07G+tKqzggFVknM5CoJCFxaik91lNGgu2O
TKfY94c/ieETOXE5L+fVrbtOh7DTFMjIYAWNxy4tlMR/59UVw5dapAxH9J2lZglkj0w0
LwFI+7hZu9XvNfMKMKg+ERAz9XHYH3608RL1RQ== This comment describes the 
key
</pre>
   except that I have deliberately split the single long line to make 
it more readable.

<h3>Making an ssh connection using a private key</h3>
<p>   
   On the machine you want to log in <em>from</em> you would run
<pre>
   slogin -i ~/.ssh/filename remotehost
</pre><p>
   (for appropriate values of "filename" and "remotehost") thus
   telling slogin to look in the private key file.
<p> 
   The connection would then be made without any further authentication
   being necessary (although <code>slogin</code> would prompt for a 
   passphrase if the private key were protected by one.
</p>
<h3>authorized_keys : restricting access</h3>
<p>
   What we have described above allows any remote host where the private
   key is known to make any kind of ssh connection (login, remote command
   execution, port forwarding, etc.) to the computer on which the
   <code>authorized_keys</code.>
   There are a number of things that can be done in an authorized_keys to
   further restrict access.  These are all arranged by prefixing the
   line containing the public key by a single "phrase" of comma-separated 
   options (see below for an example of what this winds up looking like)
</p>
<h4>Host access list</h4>
<p>
   If the options phrase at the beginning of a line contains the
   keyword <code>from="string"</code> this restricts the use of the
   key on that line to sessions that originate from hosts that match
   <code>"string"</code>.  Examples might be
</p><pre>
   from="trusted.eng.cam.ac.uk"
   from="*.eng.cam.ac.uk,!untrusted.eng.cam.ac.uk"
   from="tw?00.eng.cam.ac.uk"
</pre><p>
   The hostname used will need to be the hostname reported when the IP
   (network) address of the connecting machine is looked up in the DNS.
   The <code>*</code> wildcard matches one or more characters, while the
   <code>?</code> wildcard matches a single character.  If the connecting
   hostname matches an entry prefixed by '!', then it will be rejected.
</p>
<h4>Forced command</h4>
<p>
   If the options phrase at the beginning of a line contains the keyword
   <code>command="string"</code>, then any ssh connection that authenticates
   using that particular key will <em>only</em> run the command specified,
   even if the command line it was given specified another command.
</p>
<h4>Other options</h4>
<p>
   Various ssh facilities may be suppressed by adding the following options
   to the options phrase at the beginning of a line:
</p>
<pre>
   no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty
</pre><p>   
   When heavily restricting an ssh key in circumstances where entirely
   automated remote connections are desired, it is generally a good idea
   to apply all of these options unless the command being run actually
   needs one of these facilities.
</p>
<h4>Example authorized_keys file</h4>
<p>
This example file has two entries.  Note that there is no whitespace
in the list of options; they are separated by commas, and strings are
double-quoted (eg in the argument to <code>from=</code>).
</p>
<pre>
#
# comments are ignored in authorized_keys files
#
from="trusted.eng.cam.ac.uk",no-port-forwarding,no-pty ssh-rsa AAAAB
3NzaC1yc2EAAAABIwAAAQEAybmcqaU/Xos/GhYCzkV+kDsK8+A5OjaK5WgLMqmu38aPo
56Od10RQ3EiB42DjRVY8trXS1NH4jbURQPERr2LHCCYq6tHJYfJNhUX/COwHs+ozNPE8
3CYDhK4AhabahnltFE5ZbefwXW4FoKOO+n8AdDfSXOazpPas8jXi5bEwNf7heZT++a/Q
xbu9JHF1huThuDuxOtIWl07G+tKqzggFVknM5CoJCFxaik91lNGgu2OTKfY94c/ieETO
XE5L+fVrbtOh7DTFMjIYAWNxy4tlMR/59UVw5dapAxH9J2lZglkj0w0LwFI+7hZu9XvN
fMKMKg+ERAz9XHYH3608RL1RQ== This comment describes key #1
# 
# this one should be restricted so that only machines with hostnames
# matching *.eng.cam.ac.uk can use it.
# 
from="*.eng.cam.ac.uk",no-X11-forwarding,noagent-forwarding ssh-rsa 
AAAAC4MybC1yc2EAAAABIwAAAQEAybmcqaU/Xos/GhYCzkV+kDsK8+A5OjaK5WgLMqm
u38aPo56Od10RQ3EiB42DjRVY8trXS1NH4jbURQPERr2LHCCYq6tHJYfJNhUX/COwHs
+ozNPE83CYDhK4AhabahnltFE5ZbefwXW4FoKOO+n8AdDfSXOazpPas8jXi5bENf7he
ZT++a/Qxbu9JHF1huThuDuxOtIWl07G+tKqzggFVknM5CoJCFxaik91lNGgu2OTKfY9
4c/ieETOXE5L+fVrbtOh7DTFMjIYAWNxy4tlMR/59UVw5dapAxH9J2lZglkj0w0LwFI
+7hZu9XvNfMKMKg+ERAz9XHYH3608RL1RQ== This comment describes key #2
</pre><p>
Note that in reality, such a file would only have two uncommented
lines, both of them very long.
</p>
<h3>If it doesn't work</h3>
<p>
There are a number of reasons why key authentication might not work.
</p>
<h4>Wrong keys</h4>
<p>First, check that you really have put the matching public key in
the <code>~/.ssh/authorized_keys</code> file on the machine you're
trying to connect <em>to</em>, and that you're telling your ssh
client about the correct private key using the <code>-i</code>
argument.
</p>
<h4>Keys the wrong way round</h4>
<p>
The public key goes in the destination host's
<code>~/.ssh/authorized_keys</code> file.
<p>
The private key is needed on the machine you're running ssh or slogin from.
</p>
<h4>File permissions</h4>
<p>Some clients and servers are very picky about file permissions on their
configuration files.  Among possible objections they may have are:
<ul>
<li>a key file being writable by anyone other than the user (eg 
 group-writable)
<li>a private key file being readable by anyone other than the user.
</ul></p>
<h4>Wrong ssh protocol version</h4>
<p>
Most ssh clients and servers support both v1.5 and v2 of the ssh protocol.
<p>
Sometimes, however, they'll both decide to prefer v1.5 even though they 
both support v2.  In such cases, your ssh-rsa key (which is v2 compliant)
won't work.
<p>
<em>Solution</em>:  Force v2 by using the <code>-2</code> flag to ssh or
slogin
</p>
<pre>
     ssh -2 -i ~/.ssh/my_private_key remotemachine
</pre>
<h4>failure to use the right authentication mechanisms</h4>
<p>
The client can be configured to request particular authentication mechanisms
in a particular order.  A non-standard local configuration file can 
therefore potentially lead the client to prompt for a password before
in a particular ordera successful keybased authentication
can occur.
<p>
The following options passed to ssh or slogin should compel the client to
only offer/try the key-based authentication mechanism only:
</p>
<pre>
   ssh -2 -i ~/.ssh/my_private_key \
       -o 'PasswordAuthentication no' \
       -o 'ChallengeResponseAuthentication no' \
       -o 'PreferredAuthentications publickey' \
       remotemachine
</pre>
<p>
This may be a useful way of minimising the chances of an entirely autonomous
ssh-based command execution failing due to attempting a user interaction.
</p>