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/