Yet Another SSH Tutorial
Author: Lee Azzarello <lee@dropio.com>
Date: Mon Dec  1 18:32:21 UTC 2008

CHAPTER 1
Making it work.

SSH uses public key cryptography to authenticate your identity to another host.
This means that there are always two sides to the story. Your side, the
"private" side and the other side, the "public" one. Since you are vouching for
yourself, you must always have a private key from the host your are using to
initiate a connection. This is usually your laptop at work but it can be any
host attached to the Internet from anywhere in the world.

When you first sit down to a host, you have a clean slate. You cannot connect to
any of the other hosts in your domain's network.  The first thing you must do is
generate a "key pair". This is done via the ssh-keygen(1) utility. This utility
is a bit of a swiss army knife. For now sufice to say you only need to know
about two specific things. 1) The key algorithm to use and 2) the length of the
key in bits. You will type this at your shell:

  $ ssh-keygen -t rsa -b 2048
  Generating public/private rsa key pair.
  Enter file in which to save the key (/home/lee/.ssh/id_rsa):

Here you choose the location on your computer where your private key will be
stored. This is an important point of confusion. This is an arbitrary path on
your local disk. The path expressed by the program is merely the default
location. This location could easily be /tmp/foobar or
/home/lee/my/private/key/supersecret_ssh_private_key. So type in a custom path
or use the default. Next up you'll be prompted for a passphrase.

  Enter passphrase (empty for no passphrase):
  Enter same passphrase again:

Entering a passphrase is optional, though is a good idea. Imagine that you lost
your house keys and someone found them.  If that person knew you and knew where
your house was located, they could easily enter your house without you knowing.
But imagine an awesome futuristic scenario where your house keys could only be
inserted into your lock if you entered a passphrase only known to you.
Unauthorized access to your house is now made near impossible, since that
someone will have to know who the keys belong to, where the house is located and
enter your special passphrase left at the door.

Now that you have a key pair, you'll see two files in the path you specified
above. 1) id_rsa and 2) id_rsa.pub. These are your private and public key,
respectively. These files are unique to you, not unique to the computer you are
working on. These files can be copied, just like an mp3 or text document and
placed on another computer. These files can even be placed on drop.io and
published to the world via twitter. It's your choice. I'd not recommend the
latter and I'd probably get very angry if you chose to do that but who am I to
put artificial boundaries up. I'll trust you to use your own judgement.

Another point of confusion is the name of these files. The name of the key pair
is 100% arbitrary. If you wanted to be super secret h4x0r you could name your
key Madonna-Like_A_Virgin-Extended_Dance_Mix.mp3, just to be confusing. Try it.
It'll blow your mind. Just don't try and play your private key in iTunes. That
could be weird.

So now you have a key pair that would be very difficult to break in polynomial
time with a super secret passphrase only known to you. Big whoop. What do you do
with it? First thing you do is talk to your friendly systems team (that's me)
about opening up access to hosts. Remember that public key cryptography goes
both ways. Right now your end is the only end with keys. You need to safely
transmit your public key to a systems admin and request you be given access to a
host or group of hosts. Safe transmission is near arbitrary here, since a public
key is just that, public. Email is fine. It doesn't really mean much and just
looks like a jumble of characters. For example, here's mine:

ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAx+q6hnNsXRFltr94gMk1N5Lm4MtmzuyCkoLs0b035Np8ISykxxmMHXi+GMUdL5utGs6ZFTRIRGwOLnW8ieVBlHpTGlgt48n/vuFx7usJh2yoilL24GjsQpetgtYlBQ8lEW6P7oTHtvugkaLHG2BlvETfM7BmPSUmk1N8JafJs0y/qqQI4IBPCeUavmurM6aUAEw+XSHQ5focN4E18ezyawZrbElVm98x/pjZL1Fnz5G7m7PKv2RP5lid6ya5wYttqQtstAUCKFvPViWb30/xYpWFmehWpepQNLCFiDENx/tCfl/Xl2XQXEftFOWW+AiInNHMqPkAfkUGdumIlhPSIw== lee@dropio-dev-x61-b

Useless.

But when that key gets added to the other end, the magic happens. Now that
systems knows who you are and can vouch for your identity (at least we hope this
is true) you can open up an interactive session to a remote host! Try it.

  $ ssh -i /home/lee/.ssh/id_rsa username@remote.host
  Enter passphrase for key '.ssh/id_rsa':
  The authenticity of host 'some.host.name (some ip address)' can't be established
  RSA key fingerprint is d3:42:64:9b:b9:2c:b9:3b:ce:64:da:05:79:b4:b3:ad.
  Are you sure you want to continue connecting (yes/no)?

Oh shit, WTF does this mean? I'll bet you thought it was all clear from here.
Don't worry, this just means that your system isn't aware of the other system's
existance yet, thus it is asking you to verify that the other end is the correct
host you intend to connect to. This is an infrequently used feature of SSH but
ideally the systems admin will be able to verify the fingerprint of the host in
the rare case that you are so untrustworthy of your software you need human
verification of a host. Suffice to say you can safely type "yes" here. Remeber,
type the letters "y, e, s", not just the letter "y".

That's it. You're in!

CHAPTER 2
Making it easier.

So you have keys, you know how everything fits together and you have a trusted
account on a remote host. But there are some annoyances with working this way.
First off, pointing ssh to the private key and typing in the passphrase each
time you connect to a host is annoying and makes your fingers hurt. Enter
ssh-agent(1) and the corresponding ssh-add(1) utility. Most real operating
systems have ssh-agent running by default. This includes MacOS X and Linux with
a Gnome desktop. For non-real operating systems like Microsoft Windows, you'll
have to use a proprietary ssh client or Cygwin.  Both of these options are
beyond the scope of this tutorial. Let's make sure ssh-agent is running.

  $ ssh-add -l
  The agent has no identities.

Great. The agent is running and it has informed you that it is not aware of any
identities. In this case an identity is an ssh private key. Remember, your
private key is unique to you, and thus can be considered a unique "identity".
Also keep in mind the definition of "you" can change but that's for later. Let's
add your identity to your agent.

  $ ssh-add ~/.ssh/id_rsa
  Enter passphrase for .ssh/id_rsa:
  Identity added: .ssh/id_rsa (.ssh/id_rsa)

Now you can ask the agent about it's friends (identities) again.

  $ ssh-add -l
  2048 29:71:1f:9b:e1:e5:5a:73:0f:79:00:cc:93:43:53:58 .ssh/id_rsa (RSA)

Excellent. Our little agent robot is working nicely on our behalf. No more
typing in stupid passwords or pointing to private keys every time. The agent
remembered what you whispered in it's ear and it has a much more direct route to
the other end than you do. You can trust it to do it's job. Now let's connect to
our remote host:

  $ ssh username@remote.host
  remote_shell$

Yea! Connected safely and simply.

But what happens if you have multiple hosts and different keys to access each
one? Systems dudes commonly group different levels of access to different keys.
For example, one key can be allowed to commit to the source code repository and
another allowed to deploy that code to the staging environment. Each is mutually
exclusive. One does not allow the actions of the other. No problem. Our robot
agent has a good memory. You just have to tell it about the other keys. Let's
add the staging deployment key to the agent.

  $ ssh-add ~/deploy/stage_deploy_key
  Identity added: /home/lee/deploy/stage_deploy_key (/home/lee/deploy/stage_deploy_key)
  $ ssh-add -l
  2048 29:71:1f:9b:e1:e5:3a:73:1f:79:00:cc:93:43:53:58 .ssh/id_rsa (RSA)
  4068 7d:bf:e8:6c:d1:db:ea:a6:c3:61:4a:22:25:81:93:f4 /home/lee/deploy/stage_deploy_key (RSA)

Awesome. Now the agent knows about both identities and you can perform both
actions. Go ahead and commit some code to the repository and deploy to staging
(don't actually do this unless the other developers are aware of your actions).

Finally, how do you keep track of what keys can allow access to what actions?
Remember that the private key file names are arbitrary.  What if you change the
name of stage_deploy_key to bananas_and_wooly_mamoths? The latter is far less
descriptive of what actions the key is allowed to perform. How do you know it's
even the same key? The answer is that long number that the agent tells you about
when you ask it to show you identities. That's the "key fingerprint" and is
unique to a key pair.  We can come back to ssh-keygen(1) to get some information
out of our keys. Try this.

  $ ssh-keygen -l -f /home/lee/deploy/bananas_and_wooly_mamoths.pub
  4068 7d:bf:e8:6c:d1:db:ea:a6:c3:61:4a:22:25:81:93:f4 /home/lee/deploy/bananas_and_wooly_mamoths.pub (RSA)

Notice you're pointing to the public key file in this case. This is why it's a
good idea to keep both public and private keys in the same place, though our
final little trick is to regenerate a public key from a private one. Just in
case you lost it. Cause that happens.

  $ ssh-keygen -y -f bananas_and_wooly_mamoths
  ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAx+q6hnNsXRFltr94bMk1N7Lm4MtmzuyCkoLs0b035Np8ISykxxmMHXi+GMUdL5utGs6ZFTRIRGwOLnW8ieVBlHpTGlgt48n+vuFx7usJh2yoilL24GjsQpetgtYlBQ8lEW6P7oTHtvugkaLHG2BlvETfM7BmPSUmk1N8JafJs0y/qqQI4IBPCeUavmurM6aUAEw+XSHQ5focN4E18ezyawZrbElVm98x/pjZL1Fnz5G7m7PKv2RP5lid6ya5wYttqQtstAUCKFvPViWb30/xYpWFmehWpepQNLCFiDENx/tCfl/Xl2XQXEftFOWW+AiInNHMqPkAfkUGdumIlhPSIw==

Notice the hostname at the end of the jumble of characters is absent this time.
That's because that part of the public key is also arbitrary. It's just a
textual identifier to help you remember what host generated the key, though it
cannot be trusted to be accurate.

So in conclusion, we now know how to generate a key pair, how to request access
to a remote host, how to connect to that host, how to use the agent to hold
identities and how to get information about our keys using ssh-keygen. I hope
this clears up the client side of doing fun stuff with ssh. I'll have a third
chapter on the server side sometime soon.