[[!template id="nav"]]
-
+[[meta title="Documentation"]]
# Monkeysphere Documentation #
-
+[[!toc]]
## Dependencies ##
- * Monkeysphere relies on [GnuTLS](http://gnutls.org/) version 2.4.0 or later.
+Monkeysphere relies on:
+
+ * [GnuTLS](http://gnutls.org/) version 2.4.0 or later
+ * [OpenSSH](http://openssh.com/)
+ * [GnuPG](http://gnupg.org/)
+
+## Getting started ##
+
+ * Getting started as a [user](/getting-started-user)
+ * Getting started as a [server admin](/getting-started-admin)
## References ##
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.
-### `openssh-gpg` ###
+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](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`:
- * 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
-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:
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
-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:
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).
projects / monkeysphere.git / blobdiff