From b3f34c8df3d7c29dea30b89583749d597106d7e2 Mon Sep 17 00:00:00 2001 From: Daniel Kahn Gillmor Date: Sat, 26 Jul 2008 00:11:01 -0400 Subject: [PATCH] breaking out README.admin from README, adding a few TODOs --- debian/monkeysphere.docs | 1 + doc/README | 63 ++++++++++++-------------------- doc/README.admin | 77 ++++++++++++++++++++++++++++++++++++++++ doc/TODO | 11 ++++++ 4 files changed, 112 insertions(+), 40 deletions(-) create mode 100644 doc/README.admin diff --git a/debian/monkeysphere.docs b/debian/monkeysphere.docs index 4b8144e..595e6c8 100644 --- a/debian/monkeysphere.docs +++ b/debian/monkeysphere.docs @@ -1,2 +1,3 @@ doc/README +doc/README.admin doc/MonkeySpec diff --git a/doc/README b/doc/README index cda1194..7aa2850 100644 --- a/doc/README +++ b/doc/README @@ -1,56 +1,39 @@ -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? diff --git a/doc/README.admin b/doc/README.admin new file mode 100644 index 0000000..25a7a80 --- /dev/null +++ b/doc/README.admin @@ -0,0 +1,77 @@ +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 diff --git a/doc/TODO b/doc/TODO index e50da4d..c4e2544 100644 --- a/doc/TODO +++ b/doc/TODO @@ -107,3 +107,14 @@ Test and document what happens when any filesystem that the 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. -- 2.26.2