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.

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

Typically, you want to ensure your private key (and typically your public key as well) is on the client (i.e. on the local machine) and your public key is stored in the file ~/.ssh/authorized_keys on the server (i.e. on the remote machine) you want to connect to. (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 chmod 600 except for public key files which can be chmod 644.

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.

Using the -v switch to ssh displays verbose output which is extremely useful for diagnosing connection issues.

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&rt; 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 the user and hostname on which the key was generated. Note that the third field doesn't matter so much, as ssh will try 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 "back ticks" in the previous command are not "apostrophes"). You can then add your key using ssh-add as described above. A convenient .bashrc alias to automate this is something like: alias ssha="eval `ssh-agent -s` ssh-add ~/.ssh/id_rsa"

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.