diff options
| -rw-r--r-- | debian/monkeysphere.docs | 1 | ||||
| -rw-r--r-- | doc/README | 63 | ||||
| -rw-r--r-- | doc/README.admin | 77 | ||||
| -rw-r--r-- | doc/TODO | 11 | ||||
| -rw-r--r-- | man/man1/monkeysphere.1 | 14 | ||||
| -rw-r--r-- | src/common | 2 |
6 files changed, 120 insertions, 48 deletions
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 @@ -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 @@ -94,3 +94,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. diff --git a/man/man1/monkeysphere.1 b/man/man1/monkeysphere.1 index cd3f45e..43102d3 100644 --- a/man/man1/monkeysphere.1 +++ b/man/man1/monkeysphere.1 @@ -41,13 +41,13 @@ Update the monkeysphere authorized_keys file. For each user ID in the user's authorized_user_ids file, gpg will be queried for keys associated with that user ID, optionally querying a keyserver. If an acceptable key is found (see KEY ACCEPTABILITY in monkeysphere(5)), -the key is add to the user's authorized_keys file. If a key is found -but is unacceptable for the user ID, any matching keys are removed -from the user's authorized_keys file. If no gpg key is found for the -user ID, nothing is done. This subcommand will exit with a status of -0 if at least one acceptable key was found for a user ID, 1 if no -matching keys were found at all, and 2 if matching keys were found but -none were acceptable. `a' may be used in place of +the key is added to the user's authorized_keys file. If a key is +found but is unacceptable for the user ID, any matching keys are +removed from the user's authorized_keys file. If no gpg key is found +for the user ID, nothing is done. This subcommand will exit with a +status of 0 if at least one acceptable key was found for a user ID, 1 +if no matching keys were found at all, and 2 if matching keys were +found but none were acceptable. `a' may be used in place of `update-authorized_keys'. .TP .B gen-subkey KEYID @@ -115,7 +115,7 @@ translate_ssh_variables() { # test that a string to conforms to GPG's expiration format test_gpg_expire() { - echo "$1" | egrep -q "^[0-9][mwy]?$" + echo "$1" | egrep -q "^[0-9]+[mwy]?$" } # check that a file is properly owned, and that all it's parent |