Monkeysphere Server Administrator README
========================================

As the administrator of an SSH server, you can take advantage of the
monkeysphere in two ways:

1. you can publish the host key of your machine so that your users can
have it automatically verified, and

2. you can set up your machine to automatically identify connecting
users by their presence in the OpenPGP web of trust.

These things are not mutually required, and it is in fact possible to
do one without the other.  However, it is highly recommend that you at
least do the first.  Even if you decide that you do not want to use
the monkeysphere to authenticate users to your system, you should at
least the host key into the Web of Trust so that your users can be
sure they're connecting to the correct machine.


Monkeysphere for host verification
==================================

Server host key publication
---------------------------

To begin, you must first generate a server host key:

	# monkeysphere-server gen-key

This will generate the key for server with the service URI
(`ssh://server.example.net`).  Output the new key information with the
'show-key' command:

	# monkeysphere-server show-key

Once the key has been generated, it needs to be publish to the Web of
Trust:

	# monkeysphere-server publish-key

The server admin should now sign the server key so that people in the
admin's web of trust can identify the server without manual host key
checking.  On your (the admin's) local machine retrieve the host key:

	$ gpg --search '=ssh://server.example.net'

Now sign the server key:

	$ gpg --sign-key '=ssh://server.example.net'

Make sure you compare the fingerprint of the retrieved with the one
output with the 'show-key' command above, to verify you are signing
the correct key.  Finally, publish your signatures back to the
keyservers:

	$ gpg --send-key '=ssh://server.example.net'

Update OpenSSH configuration files
----------------------------------

To use the newly-generated host key for ssh connections, put the
following line in `/etc/ssh/sshd_config` (be sure to comment out or
remove any other HostKey references):

	HostKey /var/lib/monkeysphere/ssh_host_rsa_key

FIXME: What about DSA host keys?  The SSH RFC seems to require
implementations support DSA, though OpenSSH will work without a DSA
host key.


Monkeysphere for user authentication
====================================

A host can maintain ssh `authorized_keys` files automatically for its
users with the Monkeysphere.  These `authorized_keys` files can then
be used to enable users to use the monkeysphere to authenticate to
your machine using the OpenPGP web of trust.

Before this can happen, the host must first have a host key to use for
user key verification.  If you have not already generated a host key
(as in the host verification instructions above), generate one now:

	# monkeysphere-server gen-key

Update OpenSSH configuration files
----------------------------------

SSH must be configured to point to the monkeysphere generated
`authorized_keys` file.  Add this line to `/etc/ssh/sshd_config`
(again, making sure that no other AuthorizedKeysFile directive is left
uncommented):

	AuthorizedKeysFile /var/lib/monkeysphere/authorized_keys/%u

You'll need to restart `sshd` to have your changes take effect.  As
with any change to `sshd_config`, be sure to retain an existing
session to the machine while you test your changes so you don't get
locked out.

Monkeysphere authorized_keys maintenance
----------------------------------------

For each user account on the server, the userids of people authorized
to log into that account would be placed in:

	~/.monkeysphere/authorized_user_ids

However, in order for users to become authenticated, the server must
determine that the user IDs on their keys have "full" validity.  This
means that the server must fully trust at least one person whose
signature on the connecting user's key would validate the relevant
user ID.  The individuals trusted to identify users like this are
known in the Monkeysphere as "Identity Certifiers".  In a simple
scenario, the host's administrator would be trusted identity certifer.
If the admin's OpenPGP keyid is `$GPGID`, then on the server run:

	# monkeysphere-server add-identity-certifier $GPGID

To update the monkeysphere `authorized_keys` file for user "bob" using
the current set of identity certifiers, run:

	# monkeysphere-server update-users bob

To update the monkeysphere `authorized_keys` file for all users on the
the system, run the same command with no arguments:

	# monkeysphere-server update-users

You probably want to set up a regularly scheduled job (e.g. with cron)
to take care of this automatically.

FIXME: document other likely problems and troubleshooting techniques