doc/README
+doc/README.admin
doc/MonkeySpec
-Monkeysphere README
-===================
+Monkeysphere User README
+========================
-user usage
-----------
-For a user to update their known_hosts file:
+As a regular user on a system where the monkeysphere package is
+installed, you probably want to do a few things:
-$ monkeysphere update-known_hosts
-
-For a user to update their monkeysphere authorized_keys file:
+Keeping your keyring up-to-date
+-------------------------------
-$ monkeysphere update-authorized_keys
+Regularly refresh your GnuPG keyring from the keyservers. This can be
+done with a simple cronjob.
-server service publication
---------------------------
-To publish a server host key:
+FIXME: give an example of a useful cronjob
-# monkeysphere-server gen-key
-# monkeysphere-server publish-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:
+Keeping your known_hosts file in sync with your keyring
+-------------------------------------------------------
-$ gpg --search ='ssh://server.hostname'
-$ gpg --sign-key 'ssh://server.hostname'
+With your keyring updated, you want to make sure that openssh can
+still see the most recent trusted information about who the various
+hosts are:
-server authorized_keys maintenance
-----------------------------------
-A system can maintain monkeysphere authorized_keys files for it's
-users.
+$ monkeysphere update-known_hosts
-For each user account on the server, the userids of people authorized
-to log into that account would be placed in:
-/etc/monkeysphere/authorized_user_ids/USER
+Using monkeysphere-ssh-proxycommand(1)
+--------------------------------------
-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 users 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:
+FIXME: make a suggestion about how to integrate this in daily use.
-# monkeysphere-server trust-keys XXXXXXXX
-To update the monkeysphere authorized_keys file for user "bob", the
-system would then run the following:
+Miscellaneous
+-------------
-# monkeysphere-server update-users bob
+For a user to update their monkeysphere authorized_keys file:
-To update the monkeysphere authorized_keys file for all users on the
-the system, run the same command with no arguments:
+$ monkeysphere update-authorized_keys
-# monkeysphere-server update-users
+FIXME: where is this file located? What does this command do?
--- /dev/null
+Monkeysphere Server Administrator README
+========================================
+
+FIXME: distinguish between publishing a new monkeysphere-enabled host
+key and accepting user identification via the web-of-trust.
+
+server service publication
+--------------------------
+To publish a server host key:
+
+# monkeysphere-server gen-key
+# monkeysphere-server publish-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:
+
+$ gpg --search ='ssh://server.hostname'
+$ gpg --sign-key ='ssh://server.hostname'
+
+
+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 remove references
+to any other key):
+
+HostKey /var/lib/monkeysphere/ssh_host_rsa_key
+
+FIXME: should we just suggest symlinks in the filesystem here instead?
+
+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.
+
+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):
+
+AuthorizedKeysFile /var/lib/monkeysphere/authorized_keys/%u
+
+
+
+MonkeySphere authorized_keys maintenance
+----------------------------------------
+
+A system can maintain monkeysphere authorized_keys files for it's
+users.
+
+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
+
+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:
+
+# monkeysphere-server add-identity-certifier XXXXXXXX
+
+To update the monkeysphere authorized_keys file for user "bob", the
+system would then run the following:
+
+# 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 regularly.
+
+FIXME: document other likely problems and troubleshooting techniques
Optimize keyserver access, particularly on monkeysphere-server
update-users -- is there a way to query the keyserver all in a
chunk?
+
+Create DSA authentication subkey for server during gen-key
+
+Fix behavior when add-identity-certifier fails to fetch a key from the
+ keyserver.
+
+Allow server administrators to add-identity-certifier from a key in
+ the filesystem (or on stdin, etc)
+
+Add "monkeysphere-server diagnostics" subcommand to identify missing
+ pieces of monkeysphere server administration setup.
projects / monkeysphere.git / commitdiff