More updates on documentation (mostly Similar Projects)

diff --git a/website/doc.mdwn b/website/doc.mdwn
index 3464455f45820a8394618177888c72c048867483..c08366996ed732fff2c44354db2447bc9faaf4b1 100644 (file)
--- a/website/doc.mdwn
+++ b/website/doc.mdwn
@@ -1,25 +1,27 @@
 [[!template id="nav"]]
+[[meta title="Documentation"]]
 
-# Monkeysphere Documentation #
+# Dependencies #
 
+Monkeysphere relies on:
 
-## Dependencies ##
+ * [GnuTLS](http://gnutls.org/) version 2.4.0 or later
+ * [OpenSSH](http://openssh.com/)
+ * [GnuPG](http://gnupg.org/)
 
- * Monkeysphere relies on [GnuTLS](http://gnutls.org/) version 2.4.0 or later.
-
-## Getting started ##
+# Getting started #
 
  * Getting started as a [user](/getting-started-user)
  * Getting started as a [server admin](/getting-started-admin)
 
-## References ##
+# References #
 
  * [Initial 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/)
 
-## Similar Projects ##
+# Similar Projects #
 
 The monkeysphere isn't the only project intending to implement a PKI
 for OpenSSH.  We provide links to these other projects because they're
@@ -29,8 +31,15 @@ All of the other projects we've found so far require a patched version
 of OpenSSH, which makes adoption more difficult.  Most people don't
 build their own software, and simply overlaying a patched binary is
 associated with significant maintenance (and therefore security)
-problems.  A PKI becomes more useful the more people participate in
-it, so widespread adoption is important.
+problems.  
+
+While ultimately contributing a patch to
+[OpenSSH](http://openssh.com/) (or any
+[free](http://www.chiark.greenend.org.uk/~sgtatham/putty/)
+[SSH](http://www.lysator.liu.se/~nisse/lsh/)
+[implementation](http://matt.ucc.asn.au/dropbear/dropbear.html)) is
+not a bad thing, we hope to be able to better establish the use of a
+PKI without resorting to source modification.
 
 ### `openssh-gpg` ###
 
@@ -42,9 +51,8 @@ IETF](http://tools.ietf.org/html/rfc4253#section-6.6).
 
 Some concerns with `openssh-gpg`:
 
- * This patch is significantly old; it doesn't appear to have been
-   maintained beyond OpenSSH 3.6p1.  As of this writing, OpenSSH is on
-   version 5.1p1.
+ * This patch is old; it doesn't appear to have been maintained beyond
+   OpenSSH 3.6p1.  As of this writing, OpenSSH 5.1p1 is current.
 
  * It only provides infrastructure in one direction: the user
    authenticating the host by name.  There doesn't seem to be a
@@ -61,23 +69,23 @@ Some concerns with `openssh-gpg`:
    to avoid collisions with existing use.
 
  * It's not clear that `openssh-gpg` acknowledges or respects the
-   usage flags on the host keys.
-
- * It requires patching OpenSSH.
-
+   [usage flags](http://tools.ietf.org/html/rfc4880#section-5.2.3.21)
+   on the host keys.  This means that it could accept a "sign-only"
+   key as suitable for authenticating a host, despite the
+   clearly-marked intentions of the key-holder.
 
 ### Perspectives OpenSSH client ###
 
 [The Perspectives project](http://www.cs.cmu.edu/~perspectives/) at
 CMU has released an [openssh client that uses network
 notaries](http://www.cs.cmu.edu/~perspectives/openssh.html) to bolster
-your confidence in new keys.  This offers a defense against a narrow
-MITM attack (e.g. by someone who controls your local gateway) by
-simply verifying that other machines from around the network see the
-same keys for the remote host that you're seeing.
+your confidence in newly-seen keys.  This offers a defense against a
+narrow MITM attack (e.g. by someone who controls your local gateway)
+by simply verifying that other machines from around the network see
+the same keys for the remote host that you're seeing.
 
-This is quite useful, but doesn't take the system as far as it could
-go, and doesn't tie into the existing web of trust.
+This tactic is quite useful, but doesn't take the system as far as it
+could go, and doesn't tie into any existing web of trust.
 
 Some concerns with the Perspectives OpenSSH client:
 
@@ -94,13 +102,14 @@ Some concerns with the Perspectives OpenSSH client:
    with identifying users by name, or allowing users to globally
    revoke or change keys.
 
- * It requires patching OpenSSH
+ * It doesn't provide any mechanism for key rotation or revocation:
+   Perspectives won't help you if you need to re-key your machine.
 
 ### OpenSSH with X.509v3 certificates ###
 
 Roumen Petrov [maintains a patch to OpenSSH that works with the X.509
 PKI model](http://www.roumenpetrov.info/openssh/).  This is the
-certificate hierarchy commonly used by TLS (and SSL before that).
+certificate hierarchy commonly used by TLS (and SSL).
 
 Some concerns about OpenSSH with X.509v3:
 
@@ -120,4 +129,15 @@ Some concerns about OpenSSH with X.509v3:
    model is more flexible and more adaptable to represent real-world
    trust than X.509's rigid hierarchy.
 
- * It requires patching OpenSSH.
+ * X.509 certificates can identify hosts by name, but not by
+   individual service.  This means that a compromised web or e-mail
+   server with access to the X.509 key for that service could re-use
+   its certificate as an SSH server, and it would be able to
+   masquerade successfully.
+
+   The monkeysphere uses [User IDs of the form
+   `ssh://foo.example.net`](http://tools.ietf.org/wg/secsh/draft-ietf-secsh-scp-sftp-ssh-uri/),
+   so they are not by-default shared across services on the same host
+   (you can still share a key across services on the same host if you
+   like, but the service User IDs can be certified independently of
+   one another).