Add better host certifier management, and updated man page.

4 files changed, 125 insertions, 34 deletions

diff --git a/debian/changelog b/debian/changelog
index c6b5de4..1f1db61 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -6,8 +6,9 @@ monkeysphere (0.4-1) UNRELEASED; urgency=low
   [ Jameson Graef Rollins ]
   * Privilege separation: use monkeysphere user to handle maintenance of
     the gnupg authentication keychain for server.
+  * Improved certifier key management.
 
- -- Jameson Graef Rollins <jrollins@phys.columbia.edu>  Tue, 24 Jun 2008 13:52:28 -0400
+ -- Jameson Graef Rollins <jrollins@phys.columbia.edu>  Sun, 29 Jun 2008 14:14:59 -0400
 
 monkeysphere (0.3-1) experimental; urgency=low
 
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
 
diff --git a/src/monkeysphere b/src/monkeysphere
index ab42665..b10adb7 100755
--- a/src/monkeysphere
+++ b/src/monkeysphere
@@ -72,7 +72,7 @@ gen_subkey(){
     # prompt if an authentication subkey already exists
     if echo "$gpgOut" | egrep "^(pub|sub):" | cut -d: -f 12 | grep -q a ; then
 	echo "An authentication subkey already exists for key '$keyID'."
-	read -p "Are you sure you would like to generate another one? [y|N]: " OK; OK=${OK:N}
+	read -p "Are you sure you would like to generate another one? (y/N) " OK; OK=${OK:N}
 	if [ "${OK/y/Y}" != 'Y' ] ; then
 	    failure "aborting."
 	fi
diff --git a/src/monkeysphere-server b/src/monkeysphere-server
index 9196c2f..a080076 100755
--- a/src/monkeysphere-server
+++ b/src/monkeysphere-server
@@ -41,7 +41,9 @@ subcommands:
   gen-key (g) [HOSTNAME]                generate gpg key for the server
   show-fingerprint (f)                  show server's host key fingerprint
   publish-key (p)                       publish server's host key to keyserver
-  trust-key (t) KEYID                   import and tsign a certification key
+  add-certifier (a) KEYID               import and tsign a certification key
+  remove-certifier (r) KEYID            remove a certification key
+  list-certifiers (l)                   list certification keys
   help (h,?)                            this help
 
 EOF
@@ -245,7 +247,7 @@ EOF
     echo "The following key parameters will be used for the host private key:"
     echo "$keyParameters"
 
-    read -p "Generate key? [Y|n]: " OK; OK=${OK:=Y}
+    read -p "Generate key? (Y/n) " OK; OK=${OK:=Y}
     if [ ${OK/y/Y} != 'Y' ] ; then
 	failure "aborting."
     fi
@@ -284,7 +286,7 @@ fingerprint_server_key() {
 
 # publish server key to keyserver
 publish_server_key() {
-    read -p "really publish key to $KEYSERVER? [y|N]: " OK; OK=${OK:=N}
+    read -p "really publish key to $KEYSERVER? (y/N) " OK; OK=${OK:=N}
     if [ ${OK/y/Y} != 'Y' ] ; then
 	failure "aborting."
     fi
@@ -297,22 +299,14 @@ publish_server_key() {
     failure "NOT PUBLISHED (to avoid permanent publication errors during monkeysphere development)."
 }
 
-# retrieve key from web of trust, and set owner trust to "full"
-# if key is found.
-trust_key() {
+# retrieve key from web of trust, import it into the host keyring, and
+# ltsign the key in the host keyring so that it may certify other keys
+add_certifier() {
     local keyID
-    local trustLevel
+    local fingerprint
+    local ltsignCommand
 
     keyID="$1"
-
-    # default values for trust depth and domain
-    DEPTH=${DEPTH:-1}
-    DOMAIN=${DOMAIN:-}
-
-    if [ -z "$keyID" ] ; then
-	failure "You must specify key to trust."
-    fi
-
     export keyID
 
     # export host ownertrust to authentication keyring
@@ -332,9 +326,18 @@ trust_key() {
     echo "key found:"
     gpg_authentication "--fingerprint $fingerprint"
 
+    read -p "Are you sure you want to add this key as a certifier of users on this system? (y/N) " OK; OK=${OK:-N}
+    if [ "${OK/y/Y}" != 'Y' ] ; then
+	failure "aborting."
+    fi
+
     # export the key to the host keyring
     gpg_authentication "--export $keyID" | gpg_host --import
 
+    # default values for trust depth and domain
+    DEPTH=${DEPTH:-1}
+    DOMAIN=${DOMAIN:-}
+
     # ltsign command
     # NOTE: *all* user IDs will be ltsigned
     ltsignCommand=$(cat <<EOF
@@ -355,6 +358,25 @@ EOF
     gpg_authentication "--check-trustdb"
 }
 
+# delete a certifiers key from the host keyring
+remove_certifier() {
+    local keyID
+    local fingerprint
+
+    keyID="$1"
+
+    # delete the requested key (with prompting)
+    gpg_host --delete-key "$keyID"
+
+    # update the trustdb for the authentication keyring
+    gpg_authentication "--check-trustdb"
+}
+
+# list the host certifiers
+list_certifiers() {
+    gpg_host --list-keys
+}
+
 ########################################################################
 # MAIN
 ########################################################################
@@ -407,8 +429,22 @@ case $COMMAND in
 	publish_server_key
 	;;
 
-    'trust-key'|'t')
-	trust_key "$@"
+    'add-certifier'|'a')
+	if [ -z "$1" ] ; then
+	    failure "You must specify a key ID."
+	fi
+	add_certifier "$1"
+	;;
+
+    'remove-certifier'|'r')
+	if [ -z "$1" ] ; then
+	    failure "You must specify a key ID."
+	fi
+	remove_certifier "$1"
+	;;
+
+    'list-certifiers'|'l')
+	list_certifiers "$@"
 	;;
 
     'help'|'h'|'?')