SSH with Keys HOWTO <author>Dave Aaldering, <tt/ <date>v0.08, Thursday September 1 00:52:42 CET 2005 <abstract>This document shows how you can use SSH with keys, passphrase and ssh-agent under console or the X Window System. </abstract> <!-- Table of contents --> <toc> <!-- Begin the document --> <!-- Chapter 1 Introduction --> <sect>Introduction <p> For those of you who have been using SSH for a while, you will probably understand it's advantages over the previous telnet style applications such as telnet and remote shell. Although SSH with keys has always been there, not many people know what it is about, and how you can utilize it's strenghts to make your life as a system administrator a bit more easy. <sect1>Why I am writing this <p> Before we get to the technical part of this howto I would like to share with you my motivations on writing this document. By explaining this to you all I hope to encourage more people to help one and another. Either by programming, documenting, reviewing or just giving those little thanks and compliments we all need so badly. After I started a new job as unix sysadmin I ran into a colleague that used SSH with keys. Using keys has some major advantages over using SSH without keys, such as no more having to type in long and strong passwords all the time. Using SSH with keys by utilizing ssh-agent (which manages your keys for you during your session of for example xterm or even your entire X session) can be a great relief when you need to administer a large number of unix machines. After I started to use keys I needed an easy and convenient way to get my keys added to the ssh-agent for my entire Window Maker X session. Luckily my college already had this setup, so I could easily peek at his configurations when I couldn't get things to work. After I got it working, going through large amounts of intense pain, I thought : "There must be people that have gone through this trouble before. If they had documented their findings it would have been a lot more easier for me to get things going." So here I am, documenting my findings, and trying to help those people who are in need of those small hints and hacks to get things to work. So if you find this document useful and want to do me a favor, try and help someone else out by documenting your findings and solutions to the problems you run into yourself. Open-Source is what you make of it! <sect1>Read this first! (Disclaimer) <p>I am by no means an expert in the field of SSH, X, encryption, writing documentation or what so ever. I just found a way to make my life more easy by letting the right tools do the right job for me. I would like to share this with you to make your life a bit easier too! So if this document does not solve your problem, trashes your setup, or even makes your machine compose to nothing but the remains of a computer meltdown ... don't blame me for it. <!-- Chapter 2 About this document --> <sect>About this document <sect1>Copyright <p> Copyright (c) 2001-2005 Dave Aaldering, All rights reserved. This is free document ware; you can redistribute it and/or modify it under the terms of version 2 or later of the GNU General Public License. <sect1>Versions and Locations <p> The official and latest releases for this HOWTO can be found at : <url name="the SSH with Keys HOWTO homepage" url="">. Which is located at : Until the document reaches version 1.0 I do *NOT* encourage mirroring, since new versions will be released as often as possible. For now, please post a link to the project home-page. <sect1>Who this document is for <p> This document is for SSH users, that want to get the maximum comfort out of using SSH on a large scale. <sect1>What this document is about <p> This document gives a very hands on approach to using SSH with keys. It will learn you how to use ssh with keys and how to use ssh-agent and add keys to the agent. After that we will try creating and adding keys with a passphrase. Then we'll get to the most important part, setting up a mechanism that asks you for your passphrase *once* when starting up X and your favorite window manager, and staying present during your entire session. Also I would like to show you the strenghts of issuing remote commands. <sect1>What you need to play <p> I presume you are already using SSH and X. If not you will need those two. The third ingredient in our SSH-Soup is a nice little utility called x11-ssh-askpass. It is a little X application that pops up and ask us for a password in a very discreet manner. After that it spits that out for us in clear text :) so we can use it to add our key. You will find out how that works later on in this document. <p> <itemize> <item>OpenSSH can be found <url name="here" url=""> at the Open SSH project website. <item>x11-ssh-askpass can be found <url name="here" url=""> at the x11-ssh-askpass website. </itemize> <sect1>Platforms, versions, differences <p>While I try to keep the HOWTO as generic and inter-operable as possible, it could happen that I write an example that is not working on your *NIX, please let me know. This document will contain examples for both Protocol version 1 and 2. I use mostly Red Hat Linux systems, while testing, discovering, playing with SSH and writing this document. For SSH I use OpenSSH, but most things wil work with commercial versions of SSH as well. Differences between SSH versions do occur. And some commercial SSH versions have their flaws such as odd PGP-like key formats and entries in the 'identity' and 'authorization' files instead of in 'authorized_keys'. So sticking to Open SSH is a good idea! For more information on the differences between SSH versions and OpenSSH you can have a look at the snailbook (which will be named again later) homepage <url name="FAQ" url="">. Differences between versions, discussion about which version is the best, and matters like those are not within the scope of this document! <sect1>Feedback <p>You are very welcome, and encouraged to send your feedback to <url name="" url="">. <!-- Chapter 3 SSH-essentials --> <sect>SSH essentials <p>This part of the document will contain the basics to ssh. [todo] <sect1>Keys and Crypto <p>This part is to be containing a short basic intro on how the crypto mechanism works. [todo] <sect1>Thank god for O'Reilly (read this!) <p>In the snail book, also know as <url name="SSH, The Secure Shell: The Definitive Guide" url=""> written by Daniel J. Barret & Richard Silverman, published by O'Reilly, there was a line containing the following : repeat the following scentence three times : "ssh -v is your friend" This will give you verbose logging, so you can see what is happening. From now on, we will consider using ssh -v as standard procedure when using ssh. By the way, the authors of the snailbook also maintain a website on the book, which has some sample chapters, and a nice FAQ. It can be found at (how appropriate) <url name="" url="">. If you want to become a ssh-shaolin-master, I reccomend you buy the book :). <!-- Chapter 4 SSH with keus in a console window --> <sect>SSH with Keys in a console window <p> This first short wil learn us how to generate a key without a passphrase, and use it in a console. </p> <sect1>Creating A Key <p> When you want to use ssh with keys, the first thing that you will need is a key. If you want to know more about how this mechanism works you can have a look in chapter 3, SSH essentials. Hence there are 2 versions, we will show examples for the both of them. <sect1>Protocol version 1 key generation <p>To create the most simple key, with the default encryption, open up a console, and enter the following command : <p><code> [dave@caprice dave]$ ssh-keygen </code> Wil output the following : <p><code> Generating public/private rsa1 key pair. Enter file in which to save the key (/home/dave/.ssh/identity): /home/dave/.ssh/identity Enter passphrase (empty for no passphrase): Enter same passphrase again: Your identification has been saved in /home/dave/.ssh/identity. Your public key has been saved in /home/dave/.ssh/ The key fingerprint is: 22:bc:0b:fe:f5:06:1d:c0:05:ea:59:09:e3:07:8a:8c dave@caprice </code> When asked for a "passphrase", we won't enter one. Just press enter twice. The ssh-keygen program will now generate both your public and your private key. For the sake of this first simple tutorial I will call these files by their default names "identity" and the public key "". Your keys are stored in the .ssh/ directory in your home directory, but you can store them where ever you'd like. Good practice is to backup your keys on a floppy. If you do so, guard this floppy with your life! * Note: specifying a key type may be mandatory on your system. In that case, skip to the version 2 key geneation process. Lets have a look at your keys. <code> cd ~.ssh; ls -l -rw------- 1 dave dave 526 Nov 2 01:33 identity -rw-r--r-- 1 dave dave 330 Nov 2 01:33 </code> The file <tt>identity</tt> contains your private key. YOU SHOULD GUARD THIS KEY WITH YOUR LIFE! This key is used to gain access on systems which have your private key listed in their authorized keys file. I cannot stress this enough, dont have your keys drifting around. Also, make sure your private key always is chmod 600, so other users on the system won't have access to it. The file <tt></tt> contains your public key, which can be added to other system's authorized keys files. We will get to adding keys later. </p> <sect1>Protocol version 2 key generation <p> Creating a version 2 keypair is much like creating a version 1 keypair. Except for the fact that the SSH protocol version 2 uses different encryption algorithms for its encryption. In this case we can even choos it ourselves! Huray! To find out which versions are available on your system I'd advise you to have a look in the ssh-keygen manpage. In our example we wil create a keypair using dsa encryption. This can be done by passing the key encryption method type to ssh-keygen. This is done in the following way : <code> [dave@caprice dave]$ ssh-keygen -t dsa </code> Which will output the following : <code> [dave@caprice dave]$ ssh-keygen -t dsa Generating public/private dsa key pair. Enter file in which to save the key (/home/dave/.ssh/id_dsa): Enter passphrase (empty for no passphrase): Enter same passphrase again: Your identification has been saved in /home/dave/.ssh/id_dsa. Your public key has been saved in /home/dave/.ssh/ The key fingerprint is: 7b:ab:75:32:9e:b6:6c:4b:29:dc:2a:2b:8c:2f:4e:37 dave@caprice </code> Again, we will retain the default locations, and we will not use a passphrase either. Your keys are stored in the .ssh/ directory in your home directory. Lets have a look at your keys. <code> cd ~.ssh; ls -l -rw------- 1 dave dave 526 Nov 3 01:21 id_dsa -rw-r--r-- 1 dave dave 330 Nov 3 01:21 </code> The file <tt>id_dsa</tt> contains your version 2 private key. The file <tt></tt> contains your version 2 public key, which can be added to other system's authorized keys file. Again, I have listed a full ls -l with permissions, make sure you have the permissions set up correctly, otherwise other users may be able to snatch it from you. It is also a good idea to give your keys a non-standard name, since it makes guessing the name of your keypair files more easy. </p> <sect1>Placing the public key on the remote server <p>To be able to log in to remote systems using your pair of keys, you will first have to add your <bf>public</bf> key on the remote server to the authorized_keys (for version 1) file, and the authorized_keys2 (for version2) file in the .ssh/ directory in your home directory on the remote machine. In our example we will assume you don't have any keys in the authorized_keys files on the remote server. (Hint: If you do not have a remote shell, you can always use your own useraccount on your local machine as a remote shell (ssh localhost)) First we will upload the public keys to the remote server : <code>[dave@capricedave]$ cd .ssh/ [dave@caprice .ssh]$ scp dave@ 100% |*****************************************************| 526 00:00 [dave@caprice .ssh]$ scp dave@ 100% |*****************************************************| 614 00:00 </code> This will place your keys in your home directory on the remote server. After that we will login on the remote server using ssh or telnet the conventional way... with a password. When you are logged in you should create a .ssh directory, and inside the .ssh/ directory create an authorized_keys and an authorized_keys2 file and add the keys to the files. Make sure the files are not readable for other users/groups. chmod 600 authorized_keys* does the trick. Adding the public key for version 1 works like this: <code> [dave@caprice dave]$ ssh -v [I edited out the verbose output, and entered the password] [Remember kids, always use -v so dont try this at home :) ] [dave@julia dave]$ mkdir .ssh [dave@julia dave]$ chmod 700 .ssh [dave@julia dave]$ cd .ssh [dave@julia .ssh]$ touch authorized_keys [dave@julia .ssh]$ chmod 600 authorized_keys [dave@julia .ssh]$ cat ../ >> authorized_keys [dave@julia .ssh]$ rm ../ </code> Placing the key for version 2 works about the same : <code> [dave@julia dave]$ cd .ssh [dave@julia .ssh]$ touch authorized_keys2 [dave@julia .ssh]$ chmod 600 authorized_keys2 [dave@julia .ssh]$ cat ../ >> authorized_keys2 [dave@julia .ssh]$ rm ../ </code> If you take a little peek inside your public key files, you will find it to be a bunch of crypto, separated over a couple of rules. The public key is *1 line*. It is worth to note that the entire public key file should be one line in the authorized_keys files. So using >> is preferred over copying and pasting it from one document to another. This could put line breaks in your key which makes it useless. Either way, your keys are in place, you are ready to go to the final step and log in using your keys. </p> <sect1>Log in using your key <p> To log in using your key use the ssh command. We will add -1 to make sure we are using SSH Protocol version 1. <code> ssh -1 -v dave@ </code> <p> This logs you into a system using your version 1 key. Try it again, now for version 2 <code> ssh -2 -v dave@ </code> Have a look in the output of both ssh logins and you will be able to see some differences between version 1 and 2. </p> <!-- chapter 4 ssh with keys and a passphrase --> <sect>SSH Keys with a passphrase <p> Well that that was not too bad was it? But isn't this a bit insecure, anyone who where to gain access to my console would be able to log in to remote systems using your keys. Or what if I lost my key, the finder would be able to access every system on which I installed my public key. <p> To sort out this problem we can use a passphrase on our key. This does nothing more than configuring your key so that you have to enter a passphrase to use it. So every time you want to use your key with ssh, you'll have to enter this passphrase. Lets give that a shot.</p> <p>First we generate the key with ssh-keygen". When asked for a passphrase you can enter your passphrase to add it to the key. Remember, the longer and stronger you make your password, the harder it will be for any malicious h4x0r (or government agency) to decrypt it. Save the key to /home/username/.ssh/indentity as recommended by the ssh-keygen program. In the case you want to create an SSH protocol 2 key, you wil need to specify which encryption method you want to use.</p> <p>A brief example of creating the keys can be found below. First we will try and create an SSH 1 key</p> <sect1>Generating the keys <p><code> Generating public/private rsa1 key pair. Enter file in which to save the key (/home/dave/.ssh/identity): /home/dave/.ssh/identity Enter passphrase (empty for no passphrase): *enter your passphrase here* Enter same passphrase again: *repeat your passphrase* Your identification has been saved in /home/dave/.ssh/identity. Your public key has been saved in /home/dave/.ssh/ The key fingerprint is: 24:bc:0b:fs:f5:06:1d:c0:05:3a:59:09:e3:07:8a:8d dave@caprice </code> <p> It works the same way for SSH 2, only in this case you will have to specify which method to use. This could be like this: <tt>ssh-keygen -t dsa</tt> or <tt>ssh-keygen -t rsa</tt></p> <sect1>Testing the setup <p>To test this setup, we will have to put the public key on the remote server again since we created a new one. After that use the command "<tt>ssh -v -i .ssh/identity</tt>" to test it. The ssh program will ask you for the passphrase for the user@system key file. After you enter your passphrase, it will load the key and use it to authenticate you using ssh. </p> <p>Remember that you can use a passphrase instead of a password to use for your keys, so use these features and let your crypto protect you!</p> <!-- chapter 5 using ssh-agent --> <sect>Using ssh-agent to manage your keys <sect1>ssh-agent <p>But what if i use two keys, or three or a hundred. But what if I use the keys several times after each other, it sucks to have to enter my "l33t and strong" passphrase.</p> <p>Okay, thats what ssh-agent is for. The little program ssh-agent does you a favor by managing your keys for you. You enter the passphrase once, and after that, ssh-agent keeps your key in its memory and pulls it up whenever it is asked for it.</p> <p>To use the agent first start it. Just enter "<tt>ssh-agent bash</tt>" and thats all. This will put you in a bash shell which is spawned by ssh-agent. After that you'll need to add your key. To do this enter the command "ssh-add". This will try and add the standard key "identity" to the key manager. To add a key with a different name, enter "ssh-add /location/of/key". After this, the ssh-add program will ask you for your passphrase. After you entered your password the key is loaded in the key manager ssh-agent.</p> <p>You can test this by logging into the server you put your public key on. If the key is correctly loaded in the ssh agent it wont ask you for your passphrase and log you in. ("ssh -v host.with.pubkey").</p> <p>Also you can have a look at your currently loaded keys by using "<tt>ssh-add -l</tt>".</p> <p>After you logged in, log out by typing "logout". After this, try and login again, using "ssh -v host.with.pubkey" again. Again it wont ask you for your passphrase, because the ssh-agent does this for you.</p> <!-- chapter 6 ssh-agent under x --> <sect>SSH with keys and the agent under X <p>This part is next in line :)</p> <!-- chapter 7 ssh remote commands --> <sect>Issuing remote commands <sect1>ssh host.domain.tld command <p>This is the most fundamental way of using ssh to remotely issue commands.</p> <p>SSH provides a mechanism of issuing remote commands, and redirecting the output to you. For instance, if you want to have a quick look at your uptime on a remote machine :</p> <p><code> [dave@caprice dave]$ ssh uptime 11:09pm up 42 days, 22:55, 2 users, load average: 0.00, 0.03, 0.00 </code> <p>Ofcourse we used keys and the agent to manage those for us, so we dont need to enter password all the time. <sect1>Smart use of remote commands <p>This part wil show us some examples of nicely issuing remote commands to more than 1 machine at a time [todo]</p> <!-- chapter 8 more information --> <sect>More information <p>Where you can find links to discussion, and other related HOWTO's and items. <sect1>Related HOWTO's <p> <itemize> <item><url name="MindTerm-SSH-HOWTO" url="">. Encrypted tunnels using SSH and Mind Term.</item> <item><url name="SSL-RedHat-HOWTO" url="">. Using SSL applications under for instance Apache.</item> <item><url name="Compressed-TCP" url="">. Compressed TCP-IP-sessions using SSH-like tools.</item> <item><url name="Keychain, a key management application" url="">.</item> </itemize> <sect>Acknowledgments & Thanks <p> <itemize> <item>Frido Ferdinand, being the guru colleague at work that got the whole keys thing started. <item>Bert Hubert, Linux guru, powerdns king, and great company when drinking beer on various occasions. <item>Jim Knoble, for writing x11-ssh-askpass. <item>The OpenSSH Team. <item>Thom Carlin, for providing me with the feedback I was so eagerly waiting for. (And the feedback that quietly motivated me to start working on this document again.) <item>My employer Hubris Nederland, for allowing me to work on this HOWTO at work too :) </itemize> </article>