## Configure an SSH server to use a key pair for authentication ##

[Author](authors.html): [[KevinDKinsey]]

[Reviewer](technical_reviewers.html): Cezary Morga cm@therek.net FreeBSD

[Reviewer](technical_reviewers.html): Sean Swayze swayze@pcsage.biz FreeBSD/OpenBSD

----

### Concept ###

Understand private/public key theory including:
which protocols are available for generating key pairs, choosing an
appropriate bit size, providing a seed, providing a passphrase, and
verifying a fingerprint. In addition, able to
generate their own keys and use them for authentication.


### Introduction ###

(**Note:** Some basics on configuring the SSH server are covered in section [[Configure_an_SSH_server_according_to_a_set_of_requirements]].)

Passwords and passphrases help keep your system secure.  However, passwords can be guessed, leaked, or inadvertently disclosed in several ways.  SSH authentication using "key-based" authentication eliminates these potential vulnerabilities.  In addition, strongly encrypted keys can help protect against various other types of attacks by assuring  that the host you intend to connect to really **is** the correct host.

### "Public-Key" Encryption and SSH ###

"Public-key" encryption uses a strongly-encrypted "public key" and "private key" pair; the private key is kept secret, while the public key may be widely disseminated (as in PGP signatures for e-mail).  A user or machine can encrypt a "message" using the public key which cannot be decrypted without knowledge of the "private key".  While the keys are mathematically related, it is currently impossible, or at least extremely infeasible, to calculate the private key from the contents of the public key.

In SSH key-based authentication, the public key is known to the SSH server(s) that you wish to connect to, and the private key is known only by the SSH client program you are using.  During "setup" of the SSH connection, the SSH client first checks that the server's public key matches an entry in ~/.ssh/known hosts.  If this check is successful, the client and server exchange an encrypted message that can only be decoded with the use of the client's private key.  If your client successfully decodes the message, you will be "logged in".  

If the security of using password authentication is a concern, it can be disabled on the SSH server, and only SSH clients which provide the correct key are allowed access.  This will disallow any attempt to enter your system using SSH and a passphrase, either by "crackers" (which is good), or by you (which has a few ramifications!).

To configure an SSH server to use key-based authentication, edit the server's configuration file `/etc/ssh/sshd_config` and restart sshd(8) (see the previous section [[Configure_an_SSH_server_according_to_a_set_of_requirements]]).  You must also copy your public key to the ~/.ssh/authorized\_keys file on the remote machine.  To learn more about key creation, keep reading.

### Key Generation Algorithms ###

Two "standard" algorithms exist for the encryption of public-private key pairs - RSA and DSA.  RSA was developed in the late 1970's by MIT researchers.  The DSA algorithm was developed by the US Government in the early 1990's.  In US government work (and probably in many other circumstances/organizations) DSA keys are a required standard.  **ssh-keygen(1)** can generate both RSA and DSA keys for use in key-based SSH authentication.

The SSH server daemon sshd(8) utilizes RSA keys when SSH protocol version 1 is used, and can use both RSA and DSA keys for protocol version 2. ssh-keygen(1) can produce keys of either type for both protocols; by default (when called without arguments), ssh-keygen produces an RSA key for use with SSH protocol 2.

### Using ssh-keygen ###

ssh-keygen(1) is used to generate keys for the SSH server (to assist in identification), and also to generate keys for use in SSH client authentication.  Generally, server keys are generated when a machine is first booted after installation of the OS; they can be changed if necessary, but this might have an impact on other systems.  You should also read the next section [[Preserve_existing_SSH_host_keys_during_a_system_upgrade]] in order to understand more about the server's host keys.

####Providing a Seed####

Each time your system is booted with sshd enabled, rc(8) checks that your machine has generated RSA and DSA key pairs for use with SSH authentication.  If it has not (for example, at first boot), keys will be generated by the system using ssh-keygen.  sshd does this automatically, but if the system's random number generator has not been seeded, you will need to help out from the console.  It may seem strange to be asked to "type a screenfull of random junk", but this is important --- make it as random as possible.  TODO: How do Net/Open/Drag handle this?  Same way?  Is this even what we're talking about here?  See discussion.

####Choosing an Appropriate Bit Size####

The minimum bit size for an RSA-key is 768 bits; the default is 2048 bits.  The default should be good enough for most applications.  You should probably avoid using the "minimum" bit size for an RSA key.  Some researchers believe that new computer systems may be able to break fairly small RSA keys within 20-30 years (or perhaps even more quickly), but most believe that keys as large as 1024 for RSA encryption will be safe for a very long time ("the suns [sic] going to burn out before current desktop technologies can factor it", writes one armchair analyst).  

DSA keys **must** be 1024 bits according to the  FIPS 186-2 specification.

You can specify the bit size for RSA key generation by using the "-b" option to **ssh-keygen**.

####Providing a Passphrase####

Normally, both your public key and private key are stored locally in the directory ~/.ssh/.  To keep the private key secure from others, it is owned by the user and chmodded 600.  However, the file is plaintext, so it is possible that others might see your private key (for example, if they have root privileges).  For this reason, it may be a good idea to encrypt the private key.  Note that this refers to your SSH client's key (in ~/.ssh/), not the machine's key (in /etc/ssh).  Setting a passphrase on the machine's key could cause some issues that we won't go into detail about here.  TODO: check, please?  At the very least, sshd(8) couldn't start without it, right?

ssh-keygen can, either at the time of key creation or a later time, encrypt a private key (RSA or DSA) using the 3DES algorithm and a passphrase.  It can also change a encrypted key's passphrase (assuming you can provide the current passphrase).  Passphrases should be 10-30 characters in length and may include any characters you want, including whitespace.  Plain words or sentences should be avoided --- use something somewhat unusual!

Once your private key is encrypted, you must provide the passphrase each time you authenticate.  A lost key passphrase is a problem --- a new key pair must be generated and the public key copied to the SSH server.  This could be fairly simple (for example, if you have console access or another account with access to the SSH server), or very challenging (for example, if your very remote, unattended SSH server will only allow key-based authentication for a single account).

### Examples ###


### Practice Exercises ###


### More information ###

ssh-keygen(1) including these keywords: authorized\_keys, id\_rsa,
and id\_rsa.pub