Monkeysphere User README

Note: This documentation is for Monkeysphere version 0.23 or later.
If you are running a version prior to 0.23, we recommend that you upgrade.

You don't have to be an OpenSSH or OpenPGP expert to use the Monkeysphere. However, you should be comfortable using secure shell (ssh), and you should already have an OpenPGP key before you begin.

As a user, the Monkeysphere lets you do two important things:

  1. You can use the OpenPGP Web of Trust (WoT) to automatically verify the identity of hosts you connect to.

  2. You can manage your own ssh identity on all Monkeysphere-enabled servers using the WoT.

These two features are independent: you can do one without the other.

Identifying servers through the Web of Trust

The simplest way to identify servers through the Web of Trust is to tell ssh to use monkeysphere ssh-proxycommand to connect, instead of connecting to the remote host directly. This command will make sure the known_hosts file is up-to-date for the host you are connecting to with ssh.

You can try this out when connecting to a server which has published their host key to the monkeysphere with:

$ ssh -oProxyCommand='monkeysphere ssh-proxycommand %h %p'

If you want to have ssh always do this, just add the following line to the "Host *" section of your ~/.ssh/config file:

ProxyCommand monkeysphere ssh-proxycommand %h %p

The "Host *" section specifies what ssh options to use for all connections. So that would look like:

Host *
ProxyCommand monkeysphere ssh-proxycommand %h %p

If you want to use the ProxyCommand only on a smaller subset of hosts, adjust the Host line to match only the hosts you want instead of *.

Note that the Monkeysphere will help you identify servers whose host keys are published in the WoT, and which are signed by people who you know and trust to identify such things!

If you aren't connected to your administrator(s) through the Web of Trust, you should talk to them and establish that relationship. If you have already established that relationship, but a server's host key isn't published, you might suggest to your administrator that they publish it.

Managing your SSH identity through the Web of Trust

You've already got an OpenPGP identity in the Web of Trust. But you probably don't currently use it to identify yourself to SSH servers.

To do that, you'll need to add an authentication-capable subkey to your OpenPGP identity. You can do that with:

$ monkeysphere gen-subkey

If you have more than one secret key, you'll need to specify the key you want to add the subkey to on the command line.

Since this is a change to your key, you probably want to re-publish your key to the public keyservers. If your key ID is $GPGID:

$ gpg --keyserver --send-key $GPGID

This way, remote services that use the monkeysphere for user authentication will know about your SSH identity.

You may need to wait a few minutes for your new key to propagate around the keyserver network, and another little while for any remote host running the monkeysphere to pick up the new subkey.

Using your OpenPGP authentication key for SSH via ssh-agent(1)

Once you have created an OpenPGP authentication subkey, you will need to feed it to your ssh-agent. Your agent can then manage the key for all of your ssh sessions.

First make sure you have an agent running:

$ ssh-add -l

Then hand off the authentication subkey to the agent:

$ monkeysphere subkey-to-ssh-agent

You can supply normal ssh-add(1) flags to this command if you want to give the agent different instructions. For example, if you want the agent to always ask for confirmation before using this key, you should do this instead:

$ monkeysphere subkey-to-ssh-agent -c

You can verify that the key is in the agent just as you normally would:

$ ssh-add -l

Now you can connect to hosts that use the monkeysphere for user authentication using that key:

$ ssh

Using your OpenPGP authentication key for SSH without the agent

Currently, the monkeysphere does not support using your SSH subkey without the ssh-agent :( It's not impossible, we just haven't gotten around to it yet. Patches are welcome!

If you are not running an agent, and you just want a single session with the key, you could cobble something together a one-shot agent like this:

$ ssh-agent sh -c 'monkeysphere subkey-to-ssh-agent && ssh'


As a regular user of the monkeysphere, you probably want to do a few things to make sure that you get automatically notified of any re-keyings or revocation of monkeysphere-enabled hosts, and that your keys are properly managed.

Keep your keyring up-to-date

Regularly refresh your GnuPG keyring from the keyservers. This can be done with a simple cronjob. An example of crontab line to do this is:

0 12 * * * /usr/bin/gpg --refresh-keys > /dev/null 2>&1

This would refresh your keychain every day at noon.

Tools like parcimonie can be used to reduce the information leaked during a keyring refresh.

Keep your SSH identity up-to-date

If your SSH identity or your whole OpenPGP keyring is compromised, you should be sure to revoke it and publish the revocations to the keyserver. If only your SSH identity was compromised, you should just revoke the authentication subkey. For keys with small sizes, or which may have been otherwise compromised, you may wish to simply revoke the old authentication subkey, add a new one, and publish those changes to the public keyservers together.

Many people believe that it is good security practice to only use asymmetric keys (such as the RSA keys used by SSH and the Monkeysphere) for a limited period of time, and prefer to transition from key to key every year or two.

Without the monkeysphere, you would have needed to update your authorized_keys file on every host you connect to in order to effect such a transition. But all hosts that use the Monkeysphere to generate their authorized keys files will transition automatically to your new key, if you publish/revoke as described above.