Differences between revisions 5 and 6
Revision 5 as of 2009-05-28 19:23:51
Size: 6274
Editor: GreyCat
Comment: more emphasis on private/public, and add a summary at the end
Revision 6 as of 2011-03-09 20:25:02
Size: 7942
Editor: GreyCat
Comment: Add overview
Deletions are marked like this. Additions are marked like this.
Line 2: Line 2:

== Overview ==

This overview describes the basic concepts of public key authentication for those who don't know much about it yet.

Public key authentication involves the use of cryptography to ''prove'' that you possess certain credentials, without actually revealing those credentials to the other party. Specifically, the client holds a ''private key'', which may or may not be encrypted with a ''pass phrase''. The server holds the ''public key''. The client and server use a [[WikiPedia:Zero-knowledge proof]] method, in which the client ''proves'' that it holds the private key, but does not actually transmit the private key.

Setting it up requires a few steps. First, a ''key pair'' (private and public keys) is generated on the client system. Then, the public key is copied to the server, (appended) to the file `~username/.ssh/authorized_keys` (a simple text file). This file tells the `sshd` program on the server that the holder of the private key which ''matches'' the public key is allowed to login as "username".

The public key is not secret information, and does not need to be protected. If someone copies your public key to their own `authorized_keys` file, this only hurts ''them'', not you -- it allows you to login to their system.

The private key ''is'' secret information, and should be protected as such. The private key is normally encrypted using a ''pass phrase'', which must be entered in the client system before the private key can be used. The private key's pass phrase has nothing to do with the server's ''password'' (if the server has such a thing). The two should not be confused.

== Troubleshooting ==

This page describes some of the ways in which SSH key-based authentication may fail, and some of the steps you can take to solve your problems. Key authentication failure is probably the single most common problem new users of SSH experience, and answering these questions repeatedly is exhausting....

Overview

This overview describes the basic concepts of public key authentication for those who don't know much about it yet.

Public key authentication involves the use of cryptography to prove that you possess certain credentials, without actually revealing those credentials to the other party. Specifically, the client holds a private key, which may or may not be encrypted with a pass phrase. The server holds the public key. The client and server use a Zero-knowledge proof method, in which the client proves that it holds the private key, but does not actually transmit the private key.

Setting it up requires a few steps. First, a key pair (private and public keys) is generated on the client system. Then, the public key is copied to the server, (appended) to the file ~username/.ssh/authorized_keys (a simple text file). This file tells the sshd program on the server that the holder of the private key which matches the public key is allowed to login as "username".

The public key is not secret information, and does not need to be protected. If someone copies your public key to their own authorized_keys file, this only hurts them, not you -- it allows you to login to their system.

The private key is secret information, and should be protected as such. The private key is normally encrypted using a pass phrase, which must be entered in the client system before the private key can be used. The private key's pass phrase has nothing to do with the server's password (if the server has such a thing). The two should not be confused.

Troubleshooting

Most of the commands shown on this page assume that you are using OpenSSH. There are equivalents in other implementations; they may sometimes have different names (for example, ssh-keygen2 or puttygen). When in doubt, consult your documentation.

For starters, please read man ssh-keygen (or its equivalent) on your system. This describes the basic process of generating a key pair, and then putting the public key onto the server.

SSH has two protocols for communications, which are cleverly called "protocol 1" and "protocol 2". Protocol 1 is considered obsolete, and should not be used. Nevertheless, until quite recently, the default setting for ssh-keygen in OpenSSH was to generate a protocol-1 keypair. So, you should always explicitly specify which type of keypair you want to generate.

Protocol 2 offers two different algorithms for public key authentication: RSA and DSA. RSA is an older algorithm, and was deprecated a few years ago due to patent issues. Those patents have now expired. DSA was developed more recently, and has not seen quite as much real-world use yet. Both are considered "secure", and you may use either one:

   ssh-keygen -t rsa    # or
   ssh-keygen -t dsa

Note that keypair generation is usually done on the client so that the private key never needs to be transmitted anywhere.

You'll be prompted for the location of your keypair (just hit Enter to accept the defaults), and the passphrase. If you use a passphrase, the private key will be encrypted. Every time the SSH client needs to read the private key, it will need to use your passphrase to open it -- either by prompting you for it, or by getting it from ssh-agent. This provides you with some security against theft of the private key. If you don't use a passphrase, then anyone who obtains your private key (for example, from a backup of your home directory) will be able to use it. (Setting up ssh-agent is not covered here.)

When ssh-keygen is done, you will have two files:

   $HOME/.ssh/id_rsa       # Private key
   $HOME/.ssh/id_rsa.pub   # Public key

If you generated a DSA keypair, or if you're using a different implementation, the names will differ. Your private key should be kept secret. If you used a passphrase, it is also encrypted. The public key should be copied to the server where sshd can read it.

Now, before you do that, you need to realize that there are two different formats in which the public key may be stored: OpenSSH format, or SECSH format. You may need to convert the public key to whichever format the sshd implementation on your server knows how to read. If you generated the keypair using OpenSSH, then (obviously) your public key will be in OpenSSH format. If the sshd on your server is OpenSSH (which you can determine by using telnet server.hostname 22 and reading the banner), then your key does not need conversion.

If your server is running an implementation that uses the SECSH format, then you'll need to convert your public key to that format. ssh-keygen has flags for doing that; read the man page to see how. Likewise, if you generated your keypair using PuTTY (or something else that uses the SECSH format), and your server runs OpenSSH, then you'll need to convert your public key to OpenSSH format.

Once the key is in the correct format, it should be placed into the file (not directory) named $HOME/.ssh/authorized_keys on the server. If you have connected to this server before, or if you've used the ssh client on this server before, then the $HOME/.ssh directory should already exist; and then all you'll need to do is concatenate your public key to the end of the authorized_keys file.

Please note that the authorized_keys file uses the American spelling, not the British spelling.

Once that's done, you need to check the Permissions on everything. OpenSSH will refuse to honor your public key if it's in a place where other users might be able to write their own public keys. (If another user can write to your authorized_keys file, then she can put her own key there, and then login as you.)

This is the part that many people mess up. Not only do you have to ensure that the authorized_keys file itself has no group- or world-write permission; but you also must make sure that every directory in the full path to that file is similarly free of group- or world-write permissions. For example:

   wooledg@hostname:~$ echo $HOME
   /home/wooledg
   wooledg@hostname:~$ ls -ld / /home /home/wooledg /home/wooledg/.ssh
   drwxr-xr-x 21 root    root    4096 2007-07-03 08:57 /
   drwxrwsr-x  3 root    staff   4096 2006-07-20 14:32 /home
   drwxr-sr-x 25 wooledg wooledg 4096 2007-07-17 17:00 /home/wooledg
   drwx--S---  2 wooledg wooledg 4096 2006-07-20 14:40 /home/wooledg/.ssh
        ^
        |
        +-- Group write permission.

In many implementations, the presence of the group-write permission bit on the /home directory would cause sshd to reject an authorized_keys file in this user's .ssh directory. (There are some configuration settings that can change that, but it's typically easier and better to fix permissions on too-loose directories rather than removing SSH's safety precautions.)

For the impatient who just skimmed this to the bottom, let's recap:

  1. The private key lives on the client. The public key is created on the client and gets copied to the server. Make sure you don't mix this up.

  2. The authorized_keys file on the server must be spelled correctly.

  3. The Permissions on every directory in the path to authorized_keys starting from root must not be group- or world-writable.


CategorySsh CategoryUnix

SshKeys (last edited 2018-05-23 19:30:15 by GreyCat)