switching ikiwiki default headers to the right-hand side of the page.

[monkeysphere.git] / website / doc.mdwn

diff --git a/website/doc.mdwn b/website/doc.mdwn
index 80eca79460699366615663cb65ee7d3e6caf889a..6a978ce49d61a0ae93057bd921ee818bb4996944 100644 (file)
--- a/website/doc.mdwn
+++ b/website/doc.mdwn
@@ -1,20 +1,27 @@
 [[!template id="nav"]]
 [[!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 #

 
 

-## References ##
+ * Getting started as a [user](/getting-started-user)
+ * Getting started as a [server admin](/getting-started-admin)
+
+# 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/)
 
 
  * [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
 
 The monkeysphere isn't the only project intending to implement a PKI
 for OpenSSH.  We provide links to these other projects because they're


@@ -24,37 +31,61 @@ 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)
 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` ###
+### openssh-gpg ###

 
 [openssh-gpg](http://www.red-bean.com/~nemo/openssh-gpg/) is a patch
 against OpenSSH to support OpenPGP certificates.  According to its
 documentation, it is intended to support [`pgp-sign-rsa` and
 
 [openssh-gpg](http://www.red-bean.com/~nemo/openssh-gpg/) is a patch
 against OpenSSH to support OpenPGP certificates.  According to its
 documentation, it is intended to support [`pgp-sign-rsa` and

-`pgp-sign-dss` public key algorithms, as specified by the
+`pgp-sign-dss` public key algorithms for hosts, as specified by the

 IETF](http://tools.ietf.org/html/rfc4253#section-6.6).
 
 Some concerns with `openssh-gpg`:
 
 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.
-
- * It requires patching OpenSSH.
+ * 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
+   mechanism for dealing with identifying users by name, or allowing
+   users to globally revoke or update keys.
+
+ * The choice of User ID (`anything goes here (and here!)
+   <ssh@foo.example.net>`) for host keys overlaps with the current use
+   of the User ID space.  While it's unlikely that someone actually
+   uses this e-mail address in the web of trust, it would be a nasty
+   collision, as the holder of that key could impersonate the server
+   in question.  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/)
+   to avoid collisions with existing use.
+
+ * It's not clear that `openssh-gpg` acknowledges or respects the
+   [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
 
 ### 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:
 
 
 Some concerns with the Perspectives OpenSSH client:
 


@@ -66,13 +97,19 @@ Some concerns with the Perspectives OpenSSH client:
    notaries during your verification.  Who are the notaries?  How
    could they be compromised?
 
    notaries during your verification.  Who are the notaries?  How
    could they be compromised?
 

- * It requires patching OpenSSH
+ * It only provides infrastructure in one direction: the user
+   authenticating the host by name.  There is no mechanism for dealing
+   with identifying users by name, or allowing users to globally
+   revoke or change keys.
+
+ * 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
 
 ### 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:
 
 
 Some concerns about OpenSSH with X.509v3:
 


@@ -88,7 +125,19 @@ Some concerns about OpenSSH with X.509v3:
 
    Depending on how you declare your trust relationships, OpenPGP is
    capable of providing the same hierarchical structure as X.509, but
 
    Depending on how you declare your trust relationships, OpenPGP is
    capable of providing the same hierarchical structure as X.509, but

-   it is not limited to it.  The Web of Trust model is more flexible
-   and more adaptable than X.509.
-
- * It requires patching OpenSSH.
+   it is not limited to such a structure.  The OpenPGP Web of Trust
+   model is more flexible and more adaptable to represent real-world
+   trust than X.509's rigid hierarchy.
+
+ * 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).