SSH keys and repositories

Some instructions for ssh, svn, and git

Generating an SSH key

To generate an SSH key, use 

ssh-keygen -t rsa
Generally, the default filename it suggests is a good choice, unless you already have one with that name in which case you should rename it. (Keep the default directory, typically ~/.ssh, otherwise ssh and other programs which look for keys won't be able to find them unless you use ssh-add below.) Choose a good passphrase, which is something distinct from all of your other passwords. After ssh-keygen is done, it will generate two files: a private key (with the name you specified) and a public key (with an extra .pub suffix). By default, the public and private keys are generated with the correct permissions (typically 644 and 600, respectively), but ssh won't work if these permissions are wrong so it's good to be aware of what they should be. You may send your public key to friends or colleagues but never send anyone your private key. Also, never send your private key to yourself over email. Similarly, never share your passphrase with anyone.

Keep in mind that this passphrase is only applicable to this particular SSH key, and has no connection to other passwords. For example, it may be completely different from your password for the operating system itself.

Note you can get slightly better security by increasing the number of bits, e.g. 

ssh-keygen -t rsa -b 4096

You can use the command ssh-keygen -y -f [private key filename] to verify the passphrase for a public/private key pair. If you give the correct passphrase, it outputs the public key (this comment never prints out a username and host field). If you give the wrong passphrase it gives an error. Note that this means that given a private key it is always possible to regenerate the corresponding public key.

There's nothing wrong with using DSA instead of RSA, but RSA tends to be a bit more widely supported and is thus sometimes recommended for that reason. DSA should be used with 1024 bit (or longer) keys

You may want to generate several SSH keys over time. Avoid storing your private key on computers that you do not trust.

On mac, you may be able to ensure that your key is loaded in the OSX keychain using ssh -K [private key] or editing your config file using something like: 

	      Host *
	      UseKeychain yes
	      AddKeysToAgent yes
	      IdentityFile ~/.ssh/id_rsa
(I haven't tried this myself.)

SSH Client/Server setup

The client is the machine which you are currently logged into (sometimes called the "local" machine), while the server is the machine you are trying to access (sometimes called the "remote" machine). Typically, you want to ensure your private key (and typically your public key as well) is on the client and your public key is stored in the file ~/.ssh/authorized_keys on the server. (I always keep a copy of all public keys in a separate file in the .ssh folder in addition to putting them in the authorized_keys file.) In your .ssh directory on both the client and the server, everything should be file access mode 600 (see, e.g., the chmod man page for details) and the top level .ssh directory should have access mode 700 (the public key files can have access mode 640 or 644 but they're typically inaccessible when they're stored in the .ssh directory anyway). If ssh gives you an error message about unprotected private key files, this is what's going on.)

A common mistake is to copy and paste the keys into a file without checking the line endings. The public key will not be read if it contains any line breaks in the middle of the public key. Public keys should be one line, and three fields: key type, public key, and username@hostname. The third field is only a label and does not need to correspond to the real username or real hostname on any machine.

Using the -v switch to ssh displays verbose output which is extremely useful for diagnosing connection issues. Make sure to include the output of ssh -v when asking for help.

Using ssh-add

After generating a key, and before connecting, you may (depending on how the authentication agent works on your machine) need to use the command ssh-add <private_key_filename> to add your key to the authentication agent so that you can connect using ssh. An alternative, using ssh config files, is described below. The command ssh-add -L lists all the public keys for all current SSH "identities". The first entry on each line is the key type, (ssh-rsa, ssh-dss, etc.), the second entry on each line is the public key itself, and the third entry on each line is typically the user and hostname on which the key was generated. Note that the third field is just a label and it's value doesn't matter, since ssh will usually try all keys in order to get a connection independent of what the third field says.

Error: Could not open a connection to you authentication agent

If this happens when you try to use ssh-add (particularly when using a machine remotely), then use eval `ssh-agent -s` (notice the "backticks" in the previous command are not "apostrophes"). You can then add your key using ssh-add as described above. A convenient way to automate this process is to add the line alias ssha="eval `ssh-agent -s` ssh-add ~/.ssh/id_rsa" to your .bashrc file.

More on SSH config files

In order to save typing your username and to prevent from having to add your ssh key every time you log in, you can use a SSH config file. This plain text file, stored in ~/.ssh/config, contains entries of the form 

	      Host unix
	      Hostname unix.phys.utk.edu
	      User andrew
	      IdentityFile /home/asteiner/.ssh/my_rsa
which allows one to type, e.g., ssh unix rather than typing ssh-add ~/.ssh/my_rsa and ssh -l andrew unix.phys.utk.edu. This config file example automatically uses the SSH keypair named my_rsa and my_rsa.pub. If ssh finds a match in your config file, it will always try that key first, and if that fails, proceed to the other keys in ~/.ssh.

Enigmail and GPG

Enigmail uses GPG for handling encryption keys. GPG keys and authentication is separate from they keys used by default by ssh You can use gpg --list-keys to see what keys are stored in gpg (typically in the ~/.gnupg directory), somewhat analogous to ssh-add -L above. In order to send encrypted email messages, gpg needs to know the public encryption key for the recipient, using 

gpg --search-keys "Name"
or 
gpg --search-keys email_address

Typically people use different keys for signing and encryption.

Using GPG to send encrypted files

Once you have the recipient's public key, you can encrypt a file to send to them using 

gpg -r email_address -e -o encrypted_file original_file
and then send the encrypted file.

Setting up a gitolite server on Ubuntu

I use synaptic as a package manager, and it's better to do some initial setup before trying to install the gitolite package in synaptic.

  • Log in as normal and create a new user named e.g. 'gituser'.
  • Create a new RSA SSH key pair for the server and copy the public key to /home/gituser/git.pub
  • Use chown to change the ownership of /home/gituser/git.pub to the git user.
  • Now install gitolite3 on synaptic, specifying /home/gituser/git.pub as the public key.
  • Switch to the git user using su and run gitolite steup -pk git.pub.
  • If you want to remotely administer the server, then .ssh/config can be updated with 
    Host host.name.univ.edu
		  User gituser
		  IdentityFile ~/.ssh/git
    and use git clone gituser@host.name.univ.edu:gitolite-admin to checkout the admin repo.

More information

See Alex Cabal's "Creating the perfect GPG keypair".

Back to Andrew W. Steiner at the University of Tennessee.