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' server.example.net 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. If you don't already have a "Host \*" line, you can add it by entering: Host * On a line by itself. Add the ProxyCommand line just below it. 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 pool.sks-keyservers.net --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 server.example.net 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 server.example.net' Maintenance =========== 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. 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. For those who want more ======================= More documentation and details are available on the web at: http://web.monkeysphere.info/