Merge commit 'dkg/master'

26 files changed, 651 insertions, 104 deletions

diff --git a/doc/zimmerman/changelog b/doc/zimmerman/changelog
deleted file mode 100644
index e833b1e..0000000
--- a/doc/zimmerman/changelog
+++ /dev/null
@@ -1,19 +0,0 @@
-******************************************************************************
-*                                                                            *
-*                       zimmerman system log                                 *
-*                                                                            *
-******************************************************************************
-*  Please add new entries in reverse chronological order whenever you make   *
-*  changes to this system (first command at top, last at bottom)             *
-******************************************************************************
-
-2008-11-15 - micah
-	* aptitude update && aptitude full-upgrade
-	* aptitude install sks
-	* cd /var/lib/sks/dump ; wget -q -r -np -nd -A bz2,SHA256,asc \
-	  http://nynex.net/keydump/ -e robots=off
-	* install monkeysphere 0.21-2 package
-
-2008-11-15 - jamie
-  * aptitude install esmtp-run mailx
-	* edited /etc/esmtp-run, configured to relay to bulk.mayfirst.org
diff --git a/doc/zimmermann/changelog b/doc/zimmermann/changelog
new file mode 100644
index 0000000..8dedf58
--- /dev/null
+++ b/doc/zimmermann/changelog
@@ -0,0 +1,49 @@
+******************************************************************************
+*                                                                            *
+*                       zimmermann system log                                *
+*                                                                            *
+******************************************************************************
+*  Please add new entries in reverse chronological order whenever you make   *
+*  changes to this system (first command at top, last at bottom)             *
+******************************************************************************
+
+2008-11-29 - dkg
+	* zimmermann now uses an X.509 certificate signed by the MF/PL CA
+	for its HTTPS connection.
+	
+2008-11-19 - dkg
+	* added 10 SKS peers as a result of feedback from sks-devel.
+	* set localtime to America/New_York via dpkg-reconfigure tzdata
+	* aptitude update && aptitude full-upgrade
+	* set up /var/lib/sks/www/index.html based on
+	doc/zimmermann/index.html from this repo.
+	* made nginx proxy plain ol' HTTP on port 80 also so that SKS does
+	not need to try to listen on a privileged port.
+	* turned on initial_stat and stat_hour: 3 in /etc/sks/sksconf
+	
+2008-11-19 - mlc
+	* aptitude install nginx
+	* get rid of /etc/nginx/sites-enabled/default
+	* create /etc/nginx/sites-available/https-proxy and make a symlink
+	  to it in the sites-enabled directory
+	* invoke-rc.d nginx start
+
+2008-11-17 - micah
+	* verified the SHA256 values for the key material
+	* /usr/lib/sks/sks_build.sh (chose option #2: normalbuild)
+	* chown -R debian-sks:debian-sks /var/lib/sks
+	* edit /etc/default/sks to enable the initscript
+	* /etc/init.d/sks start
+	* rm -rf /var/lib/sks/dump
+	
+2008-11-15 - micah
+	* aptitude update && aptitude full-upgrade
+	* aptitude install sks
+	* cd /var/lib/sks/dump ; wget -q -r -np -nd -A bz2,SHA256,asc \
+	  http://nynex.net/keydump/ -e robots=off
+	* install monkeysphere 0.21-2 package
+	* apt-get install bzip2 ; bunzip2 /var/lib/sks/dump/*.bz2
+
+2008-11-15 - jamie
+  * aptitude install esmtp-run mailx
+	* edited /etc/esmtp-run, configured to relay to bulk.mayfirst.org
diff --git a/doc/zimmermann/https-proxy b/doc/zimmermann/https-proxy
new file mode 100644
index 0000000..c4521a7
--- /dev/null
+++ b/doc/zimmermann/https-proxy
@@ -0,0 +1,14 @@
+server {
+	listen  443;
+	server_name zimmermann.mayfirst.org;
+	ssl on;
+	ssl_certificate /etc/ssl/certs/ssl-cert-snakeoil.pem;
+	ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key;
+	ssl_ciphers HIGH:MEDIUM:!ADH;
+
+	access_log  off;
+
+	location / {
+		proxy_pass http://localhost:11371/;
+	}
+}
diff --git a/doc/zimmermann/index.html b/doc/zimmermann/index.html
new file mode 100644
index 0000000..e8e36e0
--- /dev/null
+++ b/doc/zimmermann/index.html
@@ -0,0 +1,73 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+	<head>
+		<title>SKS Search Page</title>
+		<meta http-equiv="content-type" content="text/html; charset="utf-8">
+		<meta name="author" content="Yaron M. Minsky/Jack Cummings/Daniel Kahn Gillmor">
+	</head>
+	<body text="#000000" bgcolor="#ffffff" link="#000099" vlink="#990099" alink="#000099">
+	<h1><a href="http://www.nongnu.org/sks/">SKS OpenPGP Keyserver</a> <br> @zimmermann.mayfirst.org</h1>
+	<p> SKS is a OpenPGP keyserver whose goal is to provide easy to deploy, decentralized, and highly reliable synchronization.  That means that a key submitted to one SKS server will quickly be distributed to all key servers, and even wildly out-of-date servers, or servers that experience spotty connectivity, can fully synchronize with rest of the system. </p>
+	<p>You can find out more about SKS, along with links to graphs of the network status <a href="http://www.nongnu.org/sks/">here</a>.</p>
+	<table cellpadding="2" cellspacing="2" border="1" width="600" bgcolor="#ddddff">
+ 	<tr>
+		<td valign="top"> 	    
+		<h3>Extract a key</h3>
+		<p>You can extract a key by typing in some words that appear in the userid
+ 	    of the key you're looking for, or by typing in the keyid in hex format ("0x...")</p>
+	    <p>
+	    <form action="/pks/lookup" method="get"> 
+	      Search String: <input name="search" size="40"> <br>
+	      Show PGP "fingerprints" for keys  
+	      <input type="checkbox" name="fingerprint"> <br>
+	      Show SKS full-key hashes
+	      <input type="checkbox" name="hash"> <br>
+	      Search for keys: <br>
+	      <input type="radio" name="op" value="index" CHECKED> get index of matching keys  <br>
+	      <input type="radio" name="op" value="vindex"> get verbose index of matching keys  <br>
+	      <input type="radio" name="op" value="get"> retrieve ascii-armored keys <br>
+	      <input type="radio" name="op" value="hget"> retrieve keys by full-key hash
+	      <br>
+	      <input type="reset" value="Reset">                 
+ 	      <input type="submit">              
+ 	    </form>
+ 	    <br>
+ 	  </td>
+ 	</tr>
+ 	<tr>
+ 	  <td valign="top"> 	    
+	    <h3>Submit a key</h3>
+ 	    You can submit a key by simply pasting in the ASCII-armored version 
+	    of your key and clicking on submit.           	    
+	    <form action="/pks/add" method="post">
+	      <textarea name="keytext" rows="20" cols="66"></textarea> <br>
+ 	      <input type="reset" value="Reset">         	      
+	      <input type="submit" value="Submit this key to the keyserver!">       	    
+	    </form>
+ 	  </td>
+ 	</tr>
+            <tr>
+              <td>
+                <h3>
+                  Access
+                </h3>
+                To use this server directly via HKP add this to your .PGP keyserver list:<br>
+                 
+<pre>x-hkp://zimmermann.mayfirst.org
+http://zimmermann.mayfirst.org:11371</pre>
+
+                You can also select a random server by adding this to your keyserver list:<br>
+                 
+<pre>x-hkp://pool.sks-keyservers.net
+http://pool.sks-keyservers.net:11371</pre>
+                 
+              </td>
+            </tr>
+      </tbody>     
+    </table>
+  
+<hr>
+  [<a href="/pks/lookup?op=stats">Server Status</a>] If you have any questions
+  about or problems with this server, please <a href="https://support.mayfirst.org/newticket?summary=zimmermann.mayfirst.org%20trouble">open a ticket</a>.
+  </body>
+</html>
diff --git a/packaging/debian/changelog b/packaging/debian/changelog
index 3b7432b..2aaa9ca 100644
--- a/packaging/debian/changelog
+++ b/packaging/debian/changelog
@@ -1,19 +1,30 @@
-monkeysphere (0.22~pre-1) UNRELEASED; urgency=low
+monkeysphere (0.23~pre-1) UNRELEASED; urgency=low
 
   * New upstream release:
-  [ Jameson Rollins ]
+    - added better checks for the existence of a host private key for
+      functions that require it to be there.
+
+ -- Jameson Graef Rollins <jrollins@finestructure.net>  Sun, 30 Nov 2008 17:14:50 -0500
+
+monkeysphere (0.22-1) unstable; urgency=low
+
+  * New upstream release:
+  [ Jameson Graef Rollins ]
 
     - added info log output when a new key is added to known_hosts file.
     - added some useful output to the ssh-proxycommand for "marginal"
       cases where keys are found for host but do not have full validity.
+    - force ssh-keygen to read from stdin to get ssh key fingerprint.
 
   [ Daniel Kahn Gillmor ]
 
     - automatically output two copies of the host's public key: one
     standard ssh public key file, and the other a minimal OpenPGP key with
     just the latest valid self-sig.
+    - debian/control: corrected alternate dependency from procfile to
+    procmail (which provides /usr/bin/lockfile)
 
- -- Jameson Graef Rollins <jrollins@finestructure.net>  Sun, 16 Nov 2008 03:22:08 -0500
+ -- Jameson Graef Rollins <jrollins@finestructure.net>  Fri, 28 Nov 2008 14:23:31 -0500
 
 monkeysphere (0.21-2) unstable; urgency=low
 
diff --git a/packaging/debian/control b/packaging/debian/control
index 4c836b4..52eccf3 100644
--- a/packaging/debian/control
+++ b/packaging/debian/control
@@ -11,7 +11,7 @@ Dm-Upload-Allowed: yes
 
 Package: monkeysphere
 Architecture: any
-Depends: openssh-client, gnupg, coreutils (>= 6) | base64, lockfile-progs | procfile, adduser, ${shlibs:Depends}
+Depends: openssh-client, gnupg, coreutils (>= 6) | base64, lockfile-progs | procmail, adduser, ${shlibs:Depends}
 Recommends: netcat | socat, ssh-askpass
 Enhances: openssh-client, openssh-server
 Description: use the OpenPGP web of trust to verify ssh connections
diff --git a/packaging/freebsd/security/monkeysphere/Makefile b/packaging/freebsd/security/monkeysphere/Makefile
index 984bc87..976f543 100644
--- a/packaging/freebsd/security/monkeysphere/Makefile
+++ b/packaging/freebsd/security/monkeysphere/Makefile
@@ -6,7 +6,7 @@
 #
 
 PORTNAME=      monkeysphere
-PORTVERSION=   0.19
+PORTVERSION=   0.22~pre
 CATEGORIES=    security
 MASTER_SITES=  http://archive.monkeysphere.info/debian/pool/monkeysphere/m/monkeysphere/
 # hack for debian orig tarballs
diff --git a/packaging/freebsd/security/monkeysphere/distinfo b/packaging/freebsd/security/monkeysphere/distinfo
index 86aecd1..51edfbe 100644
--- a/packaging/freebsd/security/monkeysphere/distinfo
+++ b/packaging/freebsd/security/monkeysphere/distinfo
@@ -1,3 +1,3 @@
-MD5 (monkeysphere_0.19.orig.tar.gz) = 64c643dd0ab642bbc8814aec1718000e
-SHA256 (monkeysphere_0.19.orig.tar.gz) = 321b77c1e10fe48ffbef8491893f5dd22842c35c11464efa7893150ce756a522
-SIZE (monkeysphere_0.19.orig.tar.gz) = 68335
+MD5 (monkeysphere_0.22~pre.orig.tar.gz) = fd19f09ed9a720f673d74c9cb58e9d6d
+SHA256 (monkeysphere_0.22~pre.orig.tar.gz) = 337c7fdb93b697fba5a9e35cdff2b5faf0e4914fd8beab7994b456d58d19abb6
+SIZE (monkeysphere_0.22~pre.orig.tar.gz) = 69345
diff --git a/packaging/rpm/howto b/packaging/rpm/howto
new file mode 100644
index 0000000..add951e
--- /dev/null
+++ b/packaging/rpm/howto
@@ -0,0 +1 @@
+http://www.rpm-based.org/how-to-create-rpm-package
diff --git a/packaging/rpm/monkeysphere.spec b/packaging/rpm/monkeysphere.spec
new file mode 100644
index 0000000..9e32837
--- /dev/null
+++ b/packaging/rpm/monkeysphere.spec
@@ -0,0 +1,40 @@
+Name: monkeysphere
+Summary: use the OpenPGP web of trust to verify ssh connections
+Version: 0.22~pre
+Release: 1
+License: GPLv3
+Group: net
+URL: http://web.monkeysphere.info/
+
+Source: http://archive.monkeysphere.info/debian/pool/monkeysphere/m/monkeysphere/monkeysphere_%{version}.orig.tar.gz
+
+%description
+SSH key-based authentication is tried-and-true, but it lacks a true
+Public Key Infrastructure for key certification, revocation and
+expiration.  Monkeysphere is a framework that uses the OpenPGP web of
+trust for these PKI functions.  It can be used in both directions: for
+users to get validated host keys, and for hosts to authenticate users.
+
+Monkeysphere is free software released under the GNU General Public
+License (GPL).
+
+%prep
+%setup -q
+
+%build
+%{__make}
+
+%install
+%{__rm} -rf %{buildroot}
+Prefix=%{buildroot}/usr
+%makeinstall
+
+%clean
+%{__rm} -rf %{buildroot}
+
+%files
+%defattr(-, root, root, 0755)
+
+%changelog
+* Sat Nov 22 2008 - 
+- Initial release.
diff --git a/src/common b/src/common
index efee9bd..f6000d3 100644
--- a/src/common
+++ b/src/common
@@ -147,7 +147,7 @@ advance_date() {
     local shortunits
 
     # try things the GNU way first 
-    if date -d "$number $longunits" "$format" >&/dev/null ; then
+    if date -d "$number $longunits" "$format" >/dev/null 2>&1; then
 	date -d "$number $longunits" "$format"
     else
 	# otherwise, convert to (a limited version of) BSD date syntax:
@@ -639,7 +639,7 @@ process_user_id() {
 		;;
 	    'uid') # user ids
 		if [ "$lastKey" != pub ] ; then
-		    log verbose " - got a user ID after a sub key?!  user IDs should only follow primary keys!"
+		    log verbose " ! got a user ID after a sub key?!  user IDs should only follow primary keys!"
 		    continue
 		fi
 		# if an acceptable user ID was already found, skip
@@ -652,6 +652,8 @@ process_user_id() {
 		    if [ "$validity" = 'u' -o "$validity" = 'f' ] ; then
 			# mark user ID acceptable
 			uidOK=true
+		    else
+			log debug "  - unacceptable user ID validity ($validity)."
 		    fi
 		else
 		    continue
@@ -693,10 +695,12 @@ process_user_id() {
 		
 		# if sub key validity is not ok, skip
 		if [ "$validity" != 'u' -a "$validity" != 'f' ] ; then
+		    log debug "  - unacceptable sub key validity ($validity)."
 		    continue
 		fi
 		# if sub key capability is not ok, skip
 		if ! check_capability "$usage" $requiredCapability ; then
+		    log debug "  - unacceptable sub key capability ($usage)."
 		    continue
 		fi
 
diff --git a/src/monkeysphere b/src/monkeysphere
index 7e800cc..523ddfe 100755
--- a/src/monkeysphere
+++ b/src/monkeysphere
@@ -158,7 +158,7 @@ EOF
     log verbose "done."
 }
 
-function subkey_to_ssh_agent() {
+subkey_to_ssh_agent() {
     # try to add all authentication subkeys to the agent:
 
     local sshaddresponse
diff --git a/src/monkeysphere-server b/src/monkeysphere-server
index bb26c04..c4f6985 100755
--- a/src/monkeysphere-server
+++ b/src/monkeysphere-server
@@ -117,6 +117,16 @@ gpg_authentication() {
     su_monkeysphere_user "gpg $@"
 }
 
+# function to check for host secret keys
+# fails if host sec key exists, exits true otherwise
+check_host_keyring() {
+    if ! gpg_host --list-secret-keys --fingerprint \
+	--with-colons --fixed-list-mode 2>/dev/null | grep -q '^sec:' ; then
+
+	failure "You don't appear to have a Monkeysphere host key on this server.  Please run 'monkeysphere-server gen-key' first."
+    fi
+}
+
 # output just key fingerprint
 fingerprint_server_key() {
     gpg_host --list-secret-keys --fingerprint \
@@ -132,13 +142,13 @@ show_server_key() {
     fingerprint=$(fingerprint_server_key)
     gpg_authentication "--fingerprint --list-key --list-options show-unusable-uids $fingerprint"
 
-    # dumping to a file named ' ' so that the ssh-keygen output
-    # doesn't claim any potentially bogus hostname(s):
-    tmpkey=$(mktemp ${TMPDIR:-/tmp}/tmp.XXXXXXXXXX) || failure "Could not create temporary directory!"
-    gpg_authentication "--export $fingerprint" | openpgp2ssh "$fingerprint" 2>/dev/null > "$tmpkey"
+    # do some crazy "Here Strings" redirection to get the key to
+    # ssh-keygen, since it doesn't read from stdin cleanly
     echo -n "ssh fingerprint: "
-    ssh-keygen -l -f "$tmpkey" | awk '{ print $1, $2, $4 }'
-    rm -rf "$tmpkey"
+    ssh-keygen -l -f /dev/stdin \
+	<<<$(gpg_authentication "--export $fingerprint" | \
+	openpgp2ssh "$fingerprint" 2>/dev/null) | \
+	awk '{ print $1, $2, $4 }'
     echo -n "OpenPGP fingerprint: "
     echo "$fingerprint"
 }
@@ -337,6 +347,7 @@ gen_key() {
     userID="ssh://${hostName}"
 
     # check for presense of key with user ID
+    # FIXME: is this the proper test to be doing here?
     if gpg_host --list-key ="$userID" > /dev/null 2>&1 ; then
 	failure "Key for '$userID' already exists"
     fi
@@ -402,7 +413,7 @@ EOF
     log info "SSH host private key output to file: ${SYSDATADIR}/ssh_host_rsa_key"
     ssh-keygen -y -f "${SYSDATADIR}/ssh_host_rsa_key" > "${SYSDATADIR}/ssh_host_rsa_key.pub"
     log info "SSH host public key output to file: ${SYSDATADIR}/ssh_host_rsa_key.pub"
-    gpg_authentication --export-options export-minimal --export "0x${fingerprint}!" > "${SYSDATADIR}/ssh_host_rsa_key.pub.gpg"
+    gpg_authentication "--export-options export-minimal --armor --export 0x${fingerprint}\!" > "${SYSDATADIR}/ssh_host_rsa_key.pub.gpg"
     log info "SSH host public key in OpenPGP form: ${SYSDATADIR}/ssh_host_rsa_key.pub.gpg"
 }
 
@@ -411,10 +422,6 @@ extend_key() {
     local fpr=$(fingerprint_server_key)
     local extendTo="$1"
 
-    if [ -z "$fpr" ] ; then
-	failure "You don't appear to have a MonkeySphere host key on this server.  Try 'monkeysphere-server gen-key' first."
-    fi
-
     # get the new expiration date
     extendTo=$(get_gpg_expiration "$extendTo")
 
@@ -709,6 +716,10 @@ diagnostics() {
 		echo " - Recommendation: remove the above HostKey lines from $sshd_config"
 		problemsfound=$(($problemsfound+1))
 	    fi
+
+        # FIXME: test (with ssh-keyscan?) that the running ssh
+        # daemon is actually offering the monkeysphere host key.
+
 	fi
     fi
 
@@ -855,9 +866,9 @@ add_certifier() {
     # export the key to the host keyring
     gpg_authentication "--export 0x${fingerprint}!" | gpg_host --import
 
-    if [ "$trust" == marginal ]; then
+    if [ "$trust" = marginal ]; then
 	trustval=1
-    elif [ "$trust" == full ]; then
+    elif [ "$trust" = full ]; then
 	trustval=2
     else
 	failure "Trust value requested ('$trust') was unclear (only 'marginal' or 'full' are supported)."
@@ -990,6 +1001,7 @@ shift
 
 case $COMMAND in
     'update-users'|'update-user'|'u')
+	check_host_keyring
 	update_users "$@"
 	;;
 
@@ -998,22 +1010,27 @@ case $COMMAND in
 	;;
 
     'extend-key'|'e')
+	check_host_keyring
 	extend_key "$@"
 	;;
 
     'add-hostname'|'add-name'|'n+')
+	check_host_keyring
 	add_hostname "$@"
 	;;
 
     'revoke-hostname'|'revoke-name'|'n-')
+	check_host_keyring
 	revoke_hostname "$@"
 	;;
 
     'show-key'|'show'|'s')
+	check_host_keyring
 	show_server_key
 	;;
 
     'publish-key'|'publish'|'p')
+	check_host_keyring
 	publish_server_key
 	;;
 
@@ -1022,14 +1039,17 @@ case $COMMAND in
 	;;
 
     'add-identity-certifier'|'add-id-certifier'|'add-certifier'|'c+')
+	check_host_keyring
 	add_certifier "$@"
 	;;
 
     'remove-identity-certifier'|'remove-id-certifier'|'remove-certifier'|'c-')
+	check_host_keyring
 	remove_certifier "$@"
 	;;
 
     'list-identity-certifiers'|'list-id-certifiers'|'list-certifiers'|'list-certifier'|'c')
+	check_host_keyring
 	list_certifiers "$@"
 	;;
 
diff --git a/src/monkeysphere-ssh-proxycommand b/src/monkeysphere-ssh-proxycommand
index b039844..a609199 100755
--- a/src/monkeysphere-ssh-proxycommand
+++ b/src/monkeysphere-ssh-proxycommand
@@ -43,22 +43,27 @@ output_no_valid_key() {
     local uidfpr
     local usage
     local sshKeyGPG
+    local tmpkey
     local sshFingerprint
+    local gpgSigOut
 
-    log "OpenPGP keys with*out* full validity found for this host:"
-    log
+    userID="ssh://${HOSTP}"
+
+    log "-------------------- Monkeysphere warning -------------------"
+    log "Monkeysphere found OpenPGP keys for this hostname, but none had full validity."
 
     # retrieve the actual ssh key
     sshKeyOffered=$(ssh-keyscan -t rsa -p "$PORT" "$HOST" 2>/dev/null | awk '{ print $2, $3 }')
+    # FIXME: should we do any checks for failed keyscans, eg. host not
+    # found?
 
-    userID="ssh://${HOSTP}"
-
-    # output gpg info for (exact) userid and store
+    # get the gpg info for userid
     gpgOut=$(gpg --list-key --fixed-list-mode --with-colon \
 	--with-fingerprint --with-fingerprint \
 	="$userID" 2>/dev/null)
 
-    # loop over all lines in the gpg output and process.
+    # find all 'pub' and 'sub' lines in the gpg output, which each
+    # represent a retrieved key for the user ID
     echo "$gpgOut" | cut -d: -f1,2,5,10,12 | \
     while IFS=: read -r type validity keyid uidfpr usage ; do
 	case $type in
@@ -69,26 +74,67 @@ output_no_valid_key() {
 		# if one of keys found matches the one offered by the
 		# host, then output info
 		if [ "$sshKeyGPG" = "$sshKeyOffered" ] ; then
+		    log "An OpenPGP key matching the ssh key offered by the host was found:"
+		    log
 
-		    # get the fingerprint of the ssh key
-		    tmpkey=$(mktemp ${TMPDIR:-/tmp}/tmp.XXXXXXXXXX)
-		    echo "$sshKeyGPG" > "$tmpkey"
-		    sshFingerprint=$(ssh-keygen -l -f "$tmpkey" | awk '{ print $2 }')
-		    rm -rf "$tmpkey"
+		    # do some crazy "Here Strings" redirection to get the key to
+		    # ssh-keygen, since it doesn't read from stdin cleanly
+		    sshFingerprint=$(ssh-keygen -l -f /dev/stdin \
+			<<<$(echo "$sshKeyGPG") | \
+			awk '{ print $2 }')
 
-		    # output gpg info
-		    gpg --check-sigs \
+		    # get the sigs for the matching key
+		    gpgSigOut=$(gpg --check-sigs \
 			--list-options show-uid-validity \
-			"$keyid" >&2
+			"$keyid")
+
+		    # output the sigs, but only those on the user ID
+		    # we are looking for
+		    echo "$gpgSigOut" | awk '
+{
+if (match($0,"^pub")) {	print; }
+if (match($0,"^uid")) { ok=0; }
+if (match($0,"^uid.*'$userID'$")) { ok=1; print; }
+if (ok) { if (match($0,"^sig")) { print; } }
+}
+' >&2
+		    log
+
+		    # output the other user IDs for reference
+		    if (echo "$gpgSigOut" | grep "^uid" | grep -v -q "$userID") ; then
+			log "Other user IDs on this key:"
+			echo "$gpgSigOut" | grep "^uid" | grep -v "$userID" >&2
+			log
+		    fi
 
 		    # output ssh fingerprint
 		    log "RSA key fingerprint is ${sshFingerprint}."
-		    log "Falling through to standard ssh host checking."
-		    log
+
+		    # this whole process is in a "while read"
+		    # subshell.  the only way to get information out
+		    # of the subshell is to change the return code.
+		    # therefore we return 1 here to indicate that a
+		    # matching gpg key was found for the ssh key
+		    # offered by the host
+		    return 1
 		fi
 		;;
 	esac
     done
+
+    # if no key match was made (and the "while read" subshell returned
+    # 1) output how many keys were found
+    if (($? != 1)) ; then
+	log "None of the found keys matched the key offered by the host."
+	log "Run the following command for more info about the found keys:"
+	log "gpg --check-sigs --list-options show-uid-validity =${userID}"
+	# FIXME: should we do anything extra here if the retrieved
+	# host key is actually in the known_hosts file and the ssh
+	# connection will succeed?  Should the user be warned?
+	# prompted?
+    fi
+
+    log "-------------------- ssh continues below --------------------"
 }
 
 ########################################################################
@@ -182,6 +228,15 @@ case $? in
 	;;
 esac
 
+# FIXME: what about the case where monkeysphere successfully finds a
+# valid key for the host and adds it to the known_hosts file, but a
+# different non-monkeysphere key for the host already exists in the
+# known_hosts, and it is this non-ms key that is offered by the host?
+# monkeysphere will succeed, and the ssh connection will succeed, and
+# the user will be left with the impression that they are dealing with
+# a OpenPGP/PKI host key when in fact they are not.  should we use
+# ssh-keyscan to compare the keys first?
+
 # exec a netcat passthrough to host for the ssh connection
 if [ -z "$NO_CONNECT" ] ; then
     if (which nc 2>/dev/null >/dev/null); then
diff --git a/utils/build-releasenote b/utils/build-releasenote
index 522917c..b25a87c 100755
--- a/utils/build-releasenote
+++ b/utils/build-releasenote
@@ -4,7 +4,7 @@ VERSION=`head -n1 packaging/debian/changelog | sed 's/.*(\([^)]*\)).*/\1/'`
 
 { 
     sed "s/__VERSION__/$VERSION/g" < utils/releasenote.header
-    head -n$(( $(grep -n '^ --' debian/changelog  | head -n1 | cut -f1 -d:) - 2 )) debian/changelog | tail -n+3
+    head -n$(( $(grep -n '^ --' packaging/debian/changelog  | head -n1 | cut -f1 -d:) - 2 )) packaging/debian/changelog | tail -n+3
     sed "s/__VERSION__/$VERSION/g" < utils/releasenote.footer
 } > "website/news/release-$VERSION.mdwn"
 
diff --git a/website/bugs/posix_compliance.mdwn b/website/bugs/posix_compliance.mdwn
new file mode 100644
index 0000000..c2908ad
--- /dev/null
+++ b/website/bugs/posix_compliance.mdwn
@@ -0,0 +1,9 @@
+It would be nice to make all of the Monkeysphere scripts POSIX
+compliant, for portability and light-weightedness.  Better POSIX
+compliance would probably at least be better for compatibility with
+o{ther,lder} versions of bash.  Unfortunately there are quite a few
+bashism at the moment, so this may not be trivial.  For instance:
+
+      servo:~/cmrg/monkeysphere/git 0$ checkbashisms -f src/monkeysphere-server 2>&1 | wc -l
+      50
+      servo:~/cmrg/monkeysphere/git 0$ 
diff --git a/website/bugs/problems-with-root-owned-gpg-keyrings.mdwn b/website/bugs/problems-with-root-owned-gpg-keyrings.mdwn
index 65268c5..67bc9d2 100644
--- a/website/bugs/problems-with-root-owned-gpg-keyrings.mdwn
+++ b/website/bugs/problems-with-root-owned-gpg-keyrings.mdwn
@@ -22,3 +22,100 @@ be hiding a bug, rather than getting it fixed correctly.
 Are there other ways we can deal with this problem?
 
 --dkg
+
+Here is an example when using monkeysphere-server
+add-identity-certifier on a host with a newly-installed monkeysphere
+installaton.  Note that running the same command a second time works
+as expected:
+
+     0 pip:~# monkeysphere-server c+ 0EE5BE979282D80B9F7540F1CCD2ED94D21739E9
+     gpg: requesting key D21739E9 from hkp server pool.sks-keyservers.net
+     gpg: key D21739E9: public key "Daniel Kahn Gillmor <dkg@fifthhorseman.net>" imported
+     gpg: can't create `/var/lib/monkeysphere/gnupg-host/pubring.gpg.tmp': Permission denied
+     gpg: failed to rebuild keyring cache: file open error
+     gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
+     gpg: depth: 0  valid:   1  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 1u
+     gpg: next trustdb check due at 2009-03-30
+     gpg: Total number processed: 1
+     gpg:               imported: 1  (RSA: 1)
+     Could not receive a key with this ID from the 'pool.sks-keyservers.net' keyserver.
+     255 pip:~# monkeysphere-server c+ 0EE5BE979282D80B9F7540F1CCD2ED94D21739E9
+     gpg: requesting key D21739E9 from hkp server pool.sks-keyservers.net
+     gpg: key D21739E9: "Daniel Kahn Gillmor <dkg@fifthhorseman.net>" not changed
+     gpg: Total number processed: 1
+     gpg:              unchanged: 1
+
+     key found:
+     pub   4096R/D21739E9 2007-06-02 [expires: 2012-05-31]
+           Key fingerprint = 0EE5 BE97 9282 D80B 9F75  40F1 CCD2 ED94 D217 39E9
+     uid       [ unknown] Daniel Kahn Gillmor <dkg@fifthhorseman.net>
+     uid       [ unknown] Daniel Kahn Gillmor <dkg@openflows.com>
+     uid       [ unknown] Daniel Kahn Gillmor <dkg@astro.columbia.edu>
+     uid       [ unknown] Daniel Kahn Gillmor <dkg-debian.org@fifthhorseman.net>
+     uid       [ unknown] [jpeg image of size 3515]
+     sub   2048R/4BFA08E4 2008-06-19 [expires: 2009-06-19]
+     sub   4096R/21484CFF 2007-06-02 [expires: 2012-05-31]
+
+     Are you sure you want to add the above key as a
+     certifier of users on this system? (y/N) y
+     gpg: key D21739E9: public key "Daniel Kahn Gillmor <dkg@fifthhorseman.net>" imported
+     gpg: Total number processed: 1
+     gpg:               imported: 1  (RSA: 1)
+     gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
+     gpg: depth: 0  valid:   1  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 1u
+     gpg: next trustdb check due at 2009-03-30
+     gpg (GnuPG) 1.4.9; Copyright (C) 2008 Free Software Foundation, Inc.
+     This is free software: you are free to change and redistribute it.
+     There is NO WARRANTY, to the extent permitted by law.
+
+
+     pub  4096R/D21739E9  created: 2007-06-02  expires: 2012-05-31  usage: SC  
+                          trust: unknown       validity: unknown
+     [ unknown] (1). Daniel Kahn Gillmor <dkg@fifthhorseman.net>
+     [ unknown] (2)  Daniel Kahn Gillmor <dkg@openflows.com>
+     [ unknown] (3)  Daniel Kahn Gillmor <dkg@astro.columbia.edu>
+     [ unknown] (4)  Daniel Kahn Gillmor <dkg-debian.org@fifthhorseman.net>
+     [ unknown] (5)  [jpeg image of size 3515]
+
+
+     pub  4096R/D21739E9  created: 2007-06-02  expires: 2012-05-31  usage: SC  
+                          trust: unknown       validity: unknown
+      Primary key fingerprint: 0EE5 BE97 9282 D80B 9F75  40F1 CCD2 ED94 D217 39E9
+
+          Daniel Kahn Gillmor <dkg@fifthhorseman.net>
+          Daniel Kahn Gillmor <dkg@openflows.com>
+          Daniel Kahn Gillmor <dkg@astro.columbia.edu>
+          Daniel Kahn Gillmor <dkg-debian.org@fifthhorseman.net>
+          [jpeg image of size 3515]
+
+     This key is due to expire on 2012-05-31.
+     Please decide how far you trust this user to correctly verify other users' keys
+     (by looking at passports, checking fingerprints from different sources, etc.)
+
+       1 = I trust marginally
+       2 = I trust fully
+
+
+     Please enter the depth of this trust signature.
+     A depth greater than 1 allows the key you are signing to make
+     trust signatures on your behalf.
+
+
+     Please enter a domain to restrict this signature, or enter for none.
+
+
+     Are you sure that you want to sign this key with your
+     key "ssh://pip.fifthhorseman.net" (9B83C17D)
+
+     The signature will be marked as non-exportable.
+
+
+     gpg: can't create `/var/lib/monkeysphere/gnupg-host/pubring.gpg.tmp': Permission denied
+     gpg: failed to rebuild keyring cache: file open error
+     gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
+     gpg: depth: 0  valid:   1  signed:   1  trust: 0-, 0q, 0n, 0m, 0f, 1u
+     gpg: depth: 1  valid:   1  signed:   0  trust: 0-, 0q, 0n, 0m, 1f, 0u
+     gpg: next trustdb check due at 2009-03-30
+
+     Identity certifier added.
+     0 pip:~# 
diff --git a/website/bugs/use_getopts_instead_of_getopt.mdwn b/website/bugs/use_getopts_instead_of_getopt.mdwn
new file mode 100644
index 0000000..db087b4
--- /dev/null
+++ b/website/bugs/use_getopts_instead_of_getopt.mdwn
@@ -0,0 +1,4 @@
+Since Monkeysphere is using bash, it would be nice to use the shell
+build in getopts function, instead of the external getopt program.
+This would reduce an external dependency, which would definitely be
+better for portability.
diff --git a/website/bugs/useful-information.mdwn b/website/bugs/useful-information.mdwn
deleted file mode 100644
index 62094bb..0000000
--- a/website/bugs/useful-information.mdwn
+++ /dev/null
@@ -1,24 +0,0 @@
-I would like to know, at INFO (default) log level, when the 
-monkeyspehere makes a "real" modification to my known_hosts file; that 
-is, when it adds or deletes a key.
-
-Apparently this is hard because monkeysphere is currently configured to 
-delete all keys and then add good keys, so a key added for the first 
-time seems to the monkeysphere very similar to a key re-added ten 
-seconds after last login.
-
-Still, from a UI perspective, I want to know what monkeysphere is doing.
-
-------
-
-It looks like jrollins committed a change for reporting at INFO level
-when a host key gets added by the monkeysphere:
-2459fa3ea277d7b9289945748619eab1e3441e5c
-
-When i connect to a host whose key is not already present in my
-known_hosts file, i get the following to stderr:
-
-    ms: * new key for squeak.fifthhorseman.net added to known_hosts file.
-
-This doesn't fully close this bug, because we aren't notifying on key
-deletion, afaict.
diff --git a/website/bugs/useful_information.mdwn b/website/bugs/useful_information.mdwn
new file mode 100644
index 0000000..025d678
--- /dev/null
+++ b/website/bugs/useful_information.mdwn
@@ -0,0 +1,50 @@
+I would like to know, at INFO (default) log level, when the 
+monkeyspehere makes a "real" modification to my known\_hosts file; that 
+is, when it adds or deletes a key.
+
+Apparently this is hard because monkeysphere is currently configured to 
+delete all keys and then add good keys, so a key added for the first 
+time seems to the monkeysphere very similar to a key re-added ten 
+seconds after last login.
+
+Still, from a UI perspective, I want to know what monkeysphere is doing.
+
+------
+
+It looks like jrollins committed a change for reporting at INFO level
+when a host key gets added by the monkeysphere:
+2459fa3ea277d7b9289945748619eab1e3441e5c
+
+When i connect to a host whose key is not already present in my
+known_hosts file, i get the following to stderr:
+
+    ms: * new key for squeak.fifthhorseman.net added to known_hosts file.
+
+This doesn't fully close this bug, because we aren't notifying on key
+deletion, afaict.
+
+------
+
+So current log level DEBUG will output a message if the known host
+file has been modified.  If the issue is that you want to know at the
+default log level everytime the known\_hots file is modified, then we
+should just move this message to INFO instead of debug, and then maybe
+remove the message that I added above.  I was under the impression
+that the issue was more about notification that a *new* key was added
+to the known\_hosts file, and therefore the new INFO message above
+fixed that problem.  Should we do this instead?
+
+In general, more verbose log levels *do* tell the user what the
+monkeysphere is doing.  Moving to DEBUG log level will tell you pretty
+much everything that happens.  I do *not* think that this should be
+the default log level, though.
+
+------
+
+I wouldn't want to see an extremely verbose default log level.  But i
+do think that saying something like "key blah blah blah was stripped
+from your known\_hosts file because it was expired" (for example)
+would be useful.  I think this case would occur infrequently enough
+that it is worth reporting in the UI at the regular log level.
+
+  --dkg
diff --git a/website/doc.mdwn b/website/doc.mdwn
index b60cf28..cd7bc76 100644
--- a/website/doc.mdwn
+++ b/website/doc.mdwn
@@ -8,6 +8,10 @@
  * Getting started as a [user](/getting-started-user)
  * Getting started as a [server admin](/getting-started-admin)
 
+## Going further ##
+
+ * [Signing host keys](/signing-host-keys)
+
 ## Under the hood ##
 
  * [Developing the monkeysphere](/community)
@@ -15,7 +19,7 @@
 
 ## References ##
 
- * [Initial specifications at CMRG](http://cmrg.fifthhorseman.net/wiki/OpenPGPandSSH)
+ * [Initial Monkeysphere specifications at CMRG](http://cmrg.fifthhorseman.net/wiki/OpenPGPandSSH)
  * [OpenPGP (RFC 4880)](http://tools.ietf.org/html/rfc4880)
  * [Secure Shell Authentication Protocol (RFC 4252)](http://tools.ietf.org/html/rfc4252)
    * [URI scheme for SSH, RFC draft](http://tools.ietf.org/wg/secsh/draft-ietf-secsh-scp-sftp-ssh-uri/)
diff --git a/website/download.mdwn b/website/download.mdwn
index 6d5a73f..a5c7479 100644
--- a/website/download.mdwn
+++ b/website/download.mdwn
@@ -75,38 +75,38 @@ For those that would like to download the source directly, [the source
 is available](/community) via [git](http://git.or.cz/).
 
 The [latest
-tarball](http://archive.monkeysphere.info/debian/pool/monkeysphere/m/monkeysphere/monkeysphere_0.21.orig.tar.gz)
+tarball](http://archive.monkeysphere.info/debian/pool/monkeysphere/m/monkeysphere/monkeysphere_0.22.orig.tar.gz)
 is also available, and has these checksums:
 
 <pre>
 -----BEGIN PGP SIGNED MESSAGE-----
 Hash: SHA1
 
-checksums for the monkeysphere 0.21 release:
+checksums for the monkeysphere 0.22 release:
 
 MD5:
-15fe181983565aca0fbe4c41f9f6752e  monkeysphere_0.21.orig.tar.gz
+2bb00c86323409b98aff53f94d9ce0a6  monkeysphere_0.22.orig.tar.gz
 
 SHA1:
-27e915a45cdbe50a139ed4f4b13746b17c165b0f  monkeysphere_0.21.orig.tar.gz
+312882ad192b8e7303e3e0ac9db20ac8ddc529b3  monkeysphere_0.22.orig.tar.gz
 
 SHA256:
-1535c3f722f5f5c1646a4981efef4a262ac7b23bf4b980c9aee11af2600eedc2  monkeysphere_0.21.orig.tar.gz
+2566facda807a67a4d2d6de3833cccfa0b78b454909e8d25f47a235a9e621b24  monkeysphere_0.22.orig.tar.gz
 -----BEGIN PGP SIGNATURE-----
 Version: GnuPG v1.4.9 (GNU/Linux)
 
-iQIVAwUBSR8+7BjmZ/HrivMUAQLeKg/+JT4LCXBR/06p/w2KBd1MKqch5Qf2ryIo
-mxCTWtZRgVQSeOFUJ5SXX+Tfs7VZfkV5HuahUH3NmGC6EMhYyB2olwBOOoIAqEKw
-1zVyn49bowCee+gTc3QHyT0Eqgt2ARtzl3/VrHkiw2MaJN3IZXseovyL8ksnEu+u
-s8fq26imtBrrucIxp4ZtHUw/h/YrJohHcJ8QQN5/UWFLug4C4aRFmnzL+oCySxAa
-0au/zFxxRZE5pMhLUvRwwCwPFx2CGBz6y9lAOiDPhhUqh+Bf7JKWJzk35Dj5Tm+2
-lCIzYtfpBkuF9ehCrm8WYF5aFg+gto8Bc6IJci9J6h2npBYIG0IbWOknMZz3+Ti2
-c3EltlJjK0LKEHujDYjf9tkNAxbBdtlYuw8x925ILeK7n8xX0Jr1TDzPyAIYaogv
-IVqsgnvQ489K8k06173kyrPaetyvOlU3bN1zcPdqTyCD6+eBbeCeKXO4324C8iMF
-rQPW4HScOdIidqFuzHyIT7PoY4DwWMgeAVymRSEufifvRcdCvQdlC4MaxxVf5I8A
-ATkD3CrY+5NZeERAGbmlu7Uz+sUk5tLUH0Q2qvjZUIQRctfr4BMheuBubsLR9yP3
-FZ4Q4kl34eU/WU7NtTmIFy7gDhLSIoeQINfYZlNEXQ7Y/RZUOEwoPI/spAXgw6De
-Xpsw0wPZtcM=
-=JDaA
+iQIVAwUBSTCiPRjmZ/HrivMUAQLg/BAAsdLsCQYSmvYLrYy1HiARtZOckqSOFv5e
+lnoOYEXKCXVjKqYUn4gjOkP2kQlnEOazfXrT/pO4u0AKUbf3C8bPDpIeao8uuPXI
+GG6HOWtsY93a2g8DM9fOzadIwhhBc9U7VwizBwFsxMw6xFTIKfoqqQonfEYFFLb6
+zyJVcfhmmGjgoJ9qA3AlYAf/i3Y/fcXh+YMI5J3Gez3BTVcep41UlcQUyd33pHF6
+aHdSWCzrotFual3fbf0meQewbBCW3JRBsbmCHQltbO/kNrtyfXb3Rp4oLiffcmpI
+DhfpFeonVHnUI9CVHmL7qbnBsgu5Q8l8Fxzu5pyzrGJxlvqBCpG8JM2FI0jJxw6o
+LQkmXCHteYKyopqKz5X0ATCot2Eoc9+kNEHwNWI37XbY7AV1XOOzGiaMjl+w8aUR
+QM8+Gi0h7SU2KuEogIsq1TghsDp3BJpTyBnc72ttLt2BvMzANOJnM8cmQqW8bOpz
+9Jdob+ISKkKG9q0wp61gb+8/f7mZKNtpr2rpRVYyjHgwR5XfbnS+gaD2B1NyG7NY
+yxW7fHpTsuwqcm2ONjZCDpEj0bXM0cL7r8c3J0L5kRCiN05c/KKYTNC70kTwCeQa
+ninihvIJal0Wu3LZxtYmtxuApq3wmc8NPo66C+TC24YGtxxJuZMS1qOlPFIPADIa
+EeBVdDmRbBw=
+=FmCP
 -----END PGP SIGNATURE-----
 </pre>
diff --git a/website/getting-started-admin.mdwn b/website/getting-started-admin.mdwn
index 6c8ad53..1c373ac 100644
--- a/website/getting-started-admin.mdwn
+++ b/website/getting-started-admin.mdwn
@@ -7,6 +7,7 @@ so that your users can have it automatically verified, and you can set
 up your machine to automatically identify connecting users by their
 presence in the OpenPGP web of trust.
 
+
 Server host key publication
 ---------------------------
 To generate and publish a server host key:
@@ -48,6 +49,7 @@ effect.  As with any change to `sshd_config`, be sure to retain an
 existing session to the machine while you test your changes so you
 don't get locked out.
 
+
 Monkeysphere authorized_keys maintenance
 ----------------------------------------
 
diff --git a/website/getting-started-user.mdwn b/website/getting-started-user.mdwn
index 5dcb0d6..9b04edc 100644
--- a/website/getting-started-user.mdwn
+++ b/website/getting-started-user.mdwn
@@ -20,6 +20,7 @@ done with a simple cronjob.  An example of crontab line to do this is:
 
 This would refresh your keychain every day at noon.
 
+
 Install the monkeysphere software on your system
 ------------------------------------------------
 
@@ -31,8 +32,9 @@ installed on your system. If you can't (or don't want to) upgrade to
 GnuTLS 2.6 or later, there are patches for GnuTLS 2.4 available in
 [the Monkeysphere git repo](/community).
 
+
 Keeping your `known_hosts` file in sync with your keyring
------------------------------------------------------------
+---------------------------------------------------------
 
 With your keyring updated, you want to make sure that OpenSSH can
 still see the most recent trusted information about who the various
@@ -47,6 +49,7 @@ key for that host to the `known_hosts` file if one is found.  This
 command could be added to a crontab as well, if desired.
 
 
+
 Using `monkeysphere-ssh-proxycommand`(1)
 ----------------------------------------
 
@@ -91,6 +94,7 @@ If you have more than one secret key, you'll need to specify the key
 you want to add the subkey to on the command line.
 
 
+
 Using your OpenPGP authentication key for SSH
 ---------------------------------------------
 
@@ -105,6 +109,7 @@ you can feed your authentication subkey to your ssh agent by running:
 
 FIXME: using the key with a single ssh connection?
 
+
 Establish trust
 ---------------
 
diff --git a/website/news/release-0.22-1.mdwn b/website/news/release-0.22-1.mdwn
new file mode 100644
index 0000000..078b605
--- /dev/null
+++ b/website/news/release-0.22-1.mdwn
@@ -0,0 +1,25 @@
+[[meta title="Monkeysphere 0.22-1 released!"]]
+
+Monkeysphere 0.22-1 has been released.  
+
+Notes from the changelog:
+
+<pre>
+  * New upstream release:
+  [ Jameson Graef Rollins ]
+
+    - added info log output when a new key is added to known_hosts file.
+    - added some useful output to the ssh-proxycommand for "marginal"
+      cases where keys are found for host but do not have full validity.
+    - force ssh-keygen to read from stdin to get ssh key fingerprint.
+
+  [ Daniel Kahn Gillmor ]
+
+    - automatically output two copies of the host's public key: one
+    standard ssh public key file, and the other a minimal OpenPGP key with
+    just the latest valid self-sig.
+    - debian/control: corrected alternate dependency from procfile to
+    procmail (which provides /usr/bin/lockfile)
+</pre>
+
+[[Download]] it now!
diff --git a/website/signing-host-keys.mdwn b/website/signing-host-keys.mdwn
new file mode 100644
index 0000000..1eb61a0
--- /dev/null
+++ b/website/signing-host-keys.mdwn
@@ -0,0 +1,127 @@
+# Signing a host's SSH key using OpenPGP #
+
+This page is meant to address the issue of signing OpenPGP-based SSH
+host keys.  Machines are not people, so the circumstances under which
+one should sign a host key are different from those under which one
+should sign another person's key.
+
+# Why are signatures on an SSH host key important? #
+
+In order for users to validate a host (an SSH server) in a
+monkeysphere-enabled network, the host key must have *full* calculated
+validity from the perspective of the connecting user.  If the user has
+not themselves signed the server's key, then the server's key can only
+be valid if other people that the user trusts have signed the key.
+
+If only one person has signed the server's key, then the user must
+fully trust the single person who has signed the host key.  Full trust
+should be granted sparingly and with consideration, though, so unless
+the user knows the server admin very well, they will in general not
+have full trust of this person.
+
+However, full trust of the host key can also be achieved if the
+server key has been signed by three or more people that the user has
+ *marginal* trust of.  In other words, three or more *marginally*
+trusted signatures equals one *fully* trusted signature.  It is much
+more common for users to have marginal trust of other users in the Web
+of Trust.  For this reason, it is advisable to have as many people
+sign the server key as possible.
+
+## What information should you have before signing a host key? ##
+
+Before signing the key of a person, you want to do two things:
+
+1. verify the identity of the person.
+2. verify that the person is actually in control of the key that you
+are signing.
+
+For a server, you want to do basically the same thing:
+
+1. verify the identity of the server.
+2. verify that the server is actually in control of the key that you
+are signing.
+
+However, verifying these things for a server is less intuitive than it
+is for a human.
+
+Verifying that the host is in control of the key is, in principle,
+straightforward.  If you are logged on to the machine in question,
+then you can check directly that the key exists on the system.
+
+What is not so straightforward is what exactly it means to "verify the
+identity" of a remote server on the internet?  The identity in this
+case is the fully qualified domain name (FQDN) of the host.  Verifying
+this identity amounts to being sure that the host in question really
+is located at that FQDN.
+
+## Signing the host key ##
+
+If you are the person (or persons) that actually setup the server and
+configured Monkeysphere and ssh on the server, then you should sign
+the host key as part of that process.  When the server is first set
+up, the administrators who set it up are the only ones who can
+actually vouch for the server key, so their signatures are necessary
+to get things going.  Their signatures are also necessary so that they
+can validate the host key themselves and log into the server via
+monkeysphere-enabled ssh in the future.
+
+If you did not set up the server initially, you do not have an
+accumulated full trust of the person(s) who did, and you do not
+necessarily have console access to the server directly, it's hard to
+confidently verify the server identity and key ownership.  You would
+like to be able to walk up to the server, log in at the console, and
+get the fingerprint of the ssh host key directly.  But this is usually
+impossible.
+
+However, it is still possible to verify the server identity *and*
+server ownership of the key, even in this case.
+
+## Remotely verifying host identity and key possession ##
+
+It is in fact possible to verify the identity and key ownership of a
+server in one fell swoop with monkeysphere-enabled ssh.  Here is the
+procedure:
+
+> **Attempt to make a monkeysphere-enabled ssh connection to the host in
+question.  Monkeysphere will check that the ssh host key offered by the
+host matches the OpenPGP key with the correct host FQDN user ID.  If
+the ssh host key and the OpenPGP key with the correct user ID match,
+then you will have effectively:**
+
+>**1. verified the host identity, because you actually connected to the
+host in question, which you know because you:**
+
+>**2. verified the host is in control of the key, because the ssh host
+key offered by the host matches the OpenPGP key with correct host FQDN
+user ID.**
+
+Here is an example:
+
+	servo:~ 0$ ssh zimmermann.mayfirst.org
+	-------------------- Monkeysphere warning -------------------
+	Monkeysphere found OpenPGP keys for this hostname, but none had full validity.
+	An OpenPGP key matching the ssh key offered by the host was found:
+	
+	pub   2048R/860E8F9C 2008-10-29 [expires: 2009-02-26]
+	uid       [marginal] ssh://zimmermann.mayfirst.org
+	sig!         76CC057D 2008-11-15  Jamie McClelland <jamie@mayfirst.org>
+	sig!3        860E8F9C 2008-10-29  ssh://zimmermann.mayfirst.org
+	sig!         D21739E9 2008-10-29  Daniel Kahn Gillmor <dkg@fifthhorseman.net>
+	sig!         1CF2D62A 2008-11-16  Micah Anderson <micah@riseup.net>
+	
+	RSA key fingerprint is 81:96:13:3e:24:c9:3c:5b:3c:6d:55:ba:58:85:e9:9e.
+	-------------------- ssh continues below --------------------
+	The authenticity of host 'zimmermann.mayfirst.org (<no hostip for proxy command>)' can't be established.
+	RSA key fingerprint is 81:96:13:3e:24:c9:3c:5b:3c:6d:55:ba:58:85:e9:9e.
+	No matching host key fingerprint found in DNS.
+	Are you sure you want to continue connecting (yes/no)? no
+	Host key verification failed.
+	servo:~ 255$ 
+
+I have attempted to connect to the host zimmermann.mayfirst.org.
+zimmermann's host key has only *marginal* validity for the FQDN user
+ID in question, so I am not able to connect.  However, the
+Monkeysphere has checked that the ssh host key actually does match the
+OpenPGP key with the correct user ID `ssh://zimmermann.mayfirst.org`.
+I have therefore verified the identity of zimmermann, and verified
+that zimmermann is in possession of the key in question.