Monkeysphere Server Administrator README
========================================
-FIXME: distinguish between publishing a new monkeysphere-enabled host
-key and accepting user identification via the web-of-trust.
+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 have it automatically verified, and
-server service publication
---------------------------
-To publish a server host key:
+2. you can set up your machine to automatically identify connecting
+users by their presence in the OpenPGP Web of Trust.
- # monkeysphere-server gen-key
- # monkeysphere-server publish-key
+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 (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 /etc/ssh/ssh\_host\_rsa\_key
This will generate the key for server with the service URI
-(ssh://server.hostname). The server admin should now sign the server
-key so that people in the admin's web of trust can authenticate the
-server without manual host key checking:
+(`ssh://server.example.net`). You can output the new key information
+with the 'show-key' command:
- $ gpg --search ='ssh://server.hostname'
- $ gpg --sign-key ='ssh://server.hostname'
+ # monkeysphere-host show-key
+Once the key has been imported, it needs to be publish to the Web of
+Trust:
-Update OpenSSH configuration files
-----------------------------------
+ # monkeysphere-host publish-key
-To use the newly-generated host key for ssh connections, put the
-following line in /etc/ssh/sshd_config (be sure to remove references
-to any other 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:
- HostKey /var/lib/monkeysphere/ssh_host_rsa_key
+ $ gpg --search '=ssh://server.example.net'
-FIXME: should we just suggest symlinks in the filesystem here instead?
+Now sign the server key:
-FIXME: What about DSA host keys? The SSH RFC seems to require that DSA be available, though OpenSSH will work without a DSA host key.
+ $ gpg --sign-key '=ssh://server.example.net'
-To enable users to use the monkeysphere to authenticate against the
-web-of-trust, add this line to /etc/ssh/sshd_config (again, making
-sure that no other AuthorizedKeysFile directive exists):
+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:
- AuthorizedKeysFile /var/lib/monkeysphere/authorized_keys/%u
+ $ gpg --send-key '=ssh://server.example.net'
+See http://web.monkeysphere.info/signing-host-keys/ for more info
+signing host keys.
-MonkeySphere authorized_keys maintenance
-----------------------------------------
+Monkeysphere for user authentication (monkeysphere-authentication)
+==================================================================
-A system can maintain monkeysphere authorized_keys files for it's
-users.
+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.
+
+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:
- ~/.config/monkeysphere/authorized_user_ids
+ ~/.monkeysphere/authorized_user_ids
However, in order for users to become authenticated, the server must
-determine that the user 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 user. This would generally be
-the server admin. If the server admin's keyid is XXXXXXXX, then on
-the server run:
+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 a trusted identity
+certifer. If the admin's OpenPGP keyid is `$GPGID`, then on the
+server run:
- # monkeysphere-server add-identity-certifier XXXXXXXX
+ # monkeysphere-authentication add-identity-certifier $GPGID
-To update the monkeysphere authorized_keys file for user "bob", the
-system would then run the following:
+To update the monkeysphere `authorized_keys` file for user "bob" using
+the current set of identity certifiers, run:
- # monkeysphere-server update-users bob
+ # monkeysphere-authentication update-users bob
-To update the monkeysphere authorized_keys file for all users on the
+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
+ # monkeysphere-authentication update-users
You probably want to set up a regularly scheduled job (e.g. with cron)
-to take care of this regularly.
+to take care of this automatically.
+
+Update OpenSSH server AuthorizedKeysFile configuration
+------------------------------------------------------
+
+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
-FIXME: document other likely problems and troubleshooting techniques
+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.