Monkeysphere Server Administrator 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.

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 to the Web of Trust
(WoT) so that your users can automatically verify it, and

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

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

Monkeysphere for host verification (monkeysphere-host)
======================================================

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

To begin, you must first import an ssh host key.  This assumes that
you have the ssh server installed, and that you have generated a host
RSA key.  Once that has been done, import the key:

	# monkeysphere-host import-key /etc/ssh/ssh_host_rsa_key server.example.net

This will generate an OpenPGP certificate for the server.  The primary
user ID for this certificate will be the ssh service URI for the host,
(eg. `ssh://server.example.net`).  Remember that the name you provide
here should probably be a fully qualified domain name for the host in
order for your users to find it.

Now you can display information about the host key's certificate with
the 'show-key' command:

	# monkeysphere-host show-key

Once the host key's certificate has been generated, you'll probably
want to publish it to the public keyservers which distribute the Web
of Trust:

	# monkeysphere-host publish-key

But anyone could publish a simple self-signed certificate to the WoT
with any name attached.  Your users should be able to tell that
someone they know and trust with the machine (e.g. *you*, the
administrator) has verified that this particular key is indeed the
correct key.  So your next step is to sign the host's key with your
own OpenPGP key.

On your (the admin's) local machine retrieve the host key (it may take
several minutes for the key to propagate across the keyserver
network), and sign it:

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

Make sure you compare the fingerprint of the retrieved certificate
with the output from the 'show-key' command above!

Next, find out your key's Key ID, which is a hexadecimal string like "ABCDEF19"

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

which will output something like:

	pub   2048R/ABCDEF19 2009-05-07
	uid       [  full  ] ssh://server.example.net

Finally, publish your signatures back to the keyservers, so that your
users can automatically verify your machine when they connect:

	$ gpg --send-key ABCDEF19

See http://web.monkeysphere.info/signing-host-keys/ for more info
signing host keys.

Monkeysphere for user authentication (monkeysphere-authentication)
==================================================================

A host can maintain ssh-style `authorized_keys` files automatically
for its users with the Monkeysphere.  This frees you (the
administrator) from the task of manually checking/placing SSH keys,
and enables users to do relatively painless key transitions, and to
quickly and universally revoke access if they find that their ssh key
has become compromised.

You simply tell the system what *person* (identified by her OpenPGP
User ID) should have access to an account, the Monkeysphere takes care
of generating the proper `authorized_keys` file and keeping it
up-to-date, and `sshd` reads the generated `authorized_keys` files
directly.

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

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

	~/.monkeysphere/authorized_user_ids

For example, this file could contain:

	Joe User <joe@example.net>
	Joe User at Work <joe@example.org>

Provided that those exact strings are among the uids for which the user's gpg
key is valid.

The server will use the Monkeysphere to look up matching OpenPGP
certificates, validate them, and generate an `authorized_keys` file.

To validate the OpenPGP certificates, the server needs to know who it
can trust to correctly identify users.  The individuals trusted to
identify users like this are known in the Monkeysphere as "Identity
Certifiers".  One obvious choice is to trust *you*, the administrator,
to be an Identity Certifier. 

You will need to know your full 40 hex character gpg fingerprint. This can be learned by doing:

	gpg --with-colons --fingerprint user@example.org

Replacing "user@example.org" with either your gpg key id, or your gpg uid.
The output of this command is very long and difficult to read. Look for a line like:

	fpr:::::::::D8E6414012D371BFC5AB8E2540D6B49E0E708ADF:

The portion between the ":::::::::" and ":" is your 40 digit fingerprint.

With your OpenPGP 40-digit hex fingerprint replacing `$GPGFPR`, then
run the following command on the server:

	# monkeysphere-authentication add-identity-certifier $GPGFPR

You'll probably only set up Identity Certifiers when you set up the
machine.  After that, you'll only need to add or remove Identity
Certifiers when the roster of admins on the machine changes, or when
one of the admins switches OpenPGP keys.

Now that the server knows who to trust to identify users, the
Monkeysphere can generate ssh-style `authorized_keys` quickly and
easily:

To update the Monkeysphere-generated `authorized_keys` file for user
"bob", run:

	# monkeysphere-authentication 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-authentication update-users

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

Update OpenSSH server AuthorizedKeysFile configuration
------------------------------------------------------

Generating the `authorized_keys` files is not quite enough, because
`sshd` needs to know where to find the generated keys.


You can do this by adding the following line to
`/etc/ssh/sshd_config`, commenting out any other `AuthorizedKeysFile`
directives. 

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

Warning: Be aware that with this change in configuration, only those users whose
authorized keys files appear under the above path will be able to log in via
ssh. This includes the root user if root has ssh access. Remember to run
'monkeysphere-authentication update-users' if you are unsure whether any users'
authorized_keys files have been updated.

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