Add better host certifier management, and updated man page.

1 files changed, 68 insertions, 14 deletions

diff --git a/man/man8/monkeysphere-server.8 b/man/man8/monkeysphere-server.8
index dbcc083..3411c64 100644
--- a/man/man8/monkeysphere-server.8
+++ b/man/man8/monkeysphere-server.8
@@ -32,7 +32,7 @@ user-controlled authorized_keys file (usually
 may be used in place of `update-users.
 .TP
 .B gen-key
-Generate a gpg key for the host.  `g' may be used in place of
+Generate a gpg key pair for the host.  `g' may be used in place of
 `gen-key'.
 .TP
 .B show-fingerprint
@@ -43,11 +43,24 @@ Show the fingerprint for the host's OpenPGP key.  `f' may be used in place of
 Publish the host's gpg key to the keyserver.  `p' may be used in place
 of `publish-key'.
 .TP
-.B trust-key KEYID [LEVEL]
-Set owner trust for key.  If LEVEL is not specified, then the program
+.B add-certifier KEYID
+Add a certifier key to host keyring.  The key with specified key ID
+will be retrieved from the keyserver and imported to the host keyring.
+It will then be given a non-exportable trust signature, with default
+depth of 1, so that the key may certifier users to log into the
+system.  `a' may be used in place of `add-certifier'.
+.TP
+.B remove-certifier KEYID
+Remove a certifier key from the host keyring.  The key with specified
+key ID will be removed entirely from the host keyring so that the key
+will not longer be able to certify users on the system.  `r' may be
+used in place of `remove-certifier'.
+.TP
+.B list-certifiers KEYID
+Add key to certify system users.  If LEVEL is not specified, then the program
 will prompt for an owner trust level to set for KEYID.  This function
-lsigns the key as well so that it will have a known validity.  `t' may
-be used in place of `trust-key'.
+lsigns the key as well so that it will have a known validity.  `l' may
+be used in place of `list-certifiers'.
 .TP
 .B help
 Output a brief usage summary.  `h' or `?' may be used in place of
@@ -55,22 +68,63 @@ Output a brief usage summary.  `h' or `?' may be used in place of
 
 .SH SETUP
 
-In order to start using the monkeysphere, there are a couple of things
-you need to do first.  The first is to generate an OpenPGP key for the
-server and convert that key to an ssh key that can be used by ssh for
-host authentication.  To do this, run the "gen-key" subcommand.  Once
-that is done, publish the key to a keyserver with "publish-key"
-subcommand.  Finally, you need to modify the sshd_config to tell sshd
-where the new server host key:
+In order to start using the monkeysphere, you must first generate an
+OpenPGP key for the server and convert that key to an ssh key that can
+be used by ssh for host authentication.  To do this, run the "gen-key"
+subcommand to generate the host key pair:
+
+$ monkeysphere-server gen-key
+
+To enable host verification via the monkeysphere, you must then
+publish the host's key to the Web of Trust using the "publish-key"
+command to push the key to a keyserver.  Then modify the sshd_config
+to tell sshd where the new server host key is located:
 
 HostKey /var/lib/monkeysphere/ssh_host_rsa_key
 
+For users logging into the system to be able to verify the host via
+the monkeysphere, at least one person (ie. a server admin) will need
+to sign the host's key.  This is done in the same way that key signing
+is usually done, by pulling the host's key from the keyserver, signing
+the key, and re-publishing the signature.  Once that is done, users
+logging into the host will be able to certify the host's key via the
+signature of the host admin.
+
 If the server will also handle user authentication through
-monkeysphere-generated authorized_keys files, set the following:
+monkeysphere-generated authorized_keys files, the server must be told
+which keys will act as user certifiers.  This is done with the
+"add-certifier" command:
+
+$ monkeysphere-server add-certifier KEYID
+
+where KEYID is the key ID of the server admin, or whoever's signature
+will be certifying users to the system.  Certifiers can be later
+remove with the "remove-certifier" command, and listed with the
+"list-certifiers" command.
+
+Remote user's will then be granted access to a local user account
+based on the appropriately signed and valid keys associated with user
+IDs listed in the authorized_user_ids file of the local user.  By
+default, the authorized_user_ids file for local users is found in
+~/.config/monkeysphere/authorized_user_ids.  This can be changed in
+the monkeysphere-server.conf file.
+
+The "update-users" command can then be used to generate
+authorized_keys file for local users that sshd can use to grant access
+to user accounts for remote users:
+
+$ monkeysphere-server update-users [USER]
+
+If no user is specified, authorized_keys files will be generated for
+all users on the system.  You must also tell sshd to look at the
+monkeysphere-generated authorized_keys file for user authentication by
+setting the following in the sshd_config:
 
 AuthorizedKeysFile /var/lib/monkeysphere/authorized_keys/%u
 
-Once those changes are made, restart the ssh server.
+It is recommended to add "monkeysphere-server update-users" to a
+system crontab, so that user keys are kept up-to-date, and key
+revokations and expirations can be processed in a timely manor.
 
 .SH FILES