website/doc.mdwn

   1 [[!template id="nav"]]
   2 [[meta title="Documentation"]]
   3 # Monkeysphere Documentation #
   4 [[!toc]]
   5
   6 ## Dependencies ##
   7
   8 Monkeysphere relies on:
   9
  10  * [GnuTLS](http://gnutls.org/) version 2.4.0 or later
  11  * [OpenSSH](http://openssh.com/)
  12  * [GnuPG](http://gnupg.org/)
  13
  14 ## Getting started ##
  15
  16  * Getting started as a [user](/getting-started-user)
  17  * Getting started as a [server admin](/getting-started-admin)
  18
  19 ## References ##
  20
  21  * [Initial specifications at CMRG](http://cmrg.fifthhorseman.net/wiki/OpenPGPandSSH)
  22  * [OpenPGP (RFC 4880)](http://tools.ietf.org/html/rfc4880)
  23  * [Secure Shell Authentication Protocol (RFC 4252)](http://tools.ietf.org/html/rfc4252)
  24    * [URI scheme for SSH, RFC draft](http://tools.ietf.org/wg/secsh/draft-ietf-secsh-scp-sftp-ssh-uri/)
  25
  26 ## Similar Projects ##
  27
  28 The monkeysphere isn't the only project intending to implement a PKI
  29 for OpenSSH.  We provide links to these other projects because they're
  30 interesting, though we have concerns with their approaches.
  31
  32 All of the other projects we've found so far require a patched version
  33 of OpenSSH, which makes adoption more difficult.  Most people don't
  34 build their own software, and simply overlaying a patched binary is
  35 associated with significant maintenance (and therefore security)
  36 problems.
  37
  38 While ultimately contributing a patch to
  39 [OpenSSH](http://openssh.com/) (or any
  40 [free](http://www.chiark.greenend.org.uk/~sgtatham/putty/)
  41 [SSH](http://www.lysator.liu.se/~nisse/lsh/)
  42 [implementation](http://matt.ucc.asn.au/dropbear/dropbear.html)) is
  43 not a bad thing, we hope to be able to better establish the use of a
  44 PKI without resorting to source modification.
  45
  46 ### openssh-gpg ###
  47
  48 [openssh-gpg](http://www.red-bean.com/~nemo/openssh-gpg/) is a patch
  49 against OpenSSH to support OpenPGP certificates.  According to its
  50 documentation, it is intended to support [`pgp-sign-rsa` and
  51 `pgp-sign-dss` public key algorithms for hosts, as specified by the
  52 IETF](http://tools.ietf.org/html/rfc4253#section-6.6).
  53
  54 Some concerns with `openssh-gpg`:
  55
  56  * This patch is old; it doesn't appear to have been maintained beyond
  57    OpenSSH 3.6p1.  As of this writing, OpenSSH 5.1p1 is current.
  58
  59  * It only provides infrastructure in one direction: the user
  60    authenticating the host by name.  There doesn't seem to be a
  61    mechanism for dealing with identifying users by name, or allowing
  62    users to globally revoke or update keys.
  63
  64  * The choice of User ID (`anything goes here (and here!)
  65    <ssh@foo.example.net>`) for host keys overlaps with the current use
  66    of the User ID space.  While it's unlikely that someone actually
  67    uses this e-mail address in the web of trust, it would be a nasty
  68    collision, as the holder of that key could impersonate the server
  69    in question.  The monkeysphere uses [User IDs of the form
  70    `ssh://foo.example.net`](http://tools.ietf.org/wg/secsh/draft-ietf-secsh-scp-sftp-ssh-uri/)
  71    to avoid collisions with existing use.
  72
  73  * It's not clear that `openssh-gpg` acknowledges or respects the
  74    [usage flags](http://tools.ietf.org/html/rfc4880#section-5.2.3.21)
  75    on the host keys.  This means that it could accept a "sign-only"
  76    key as suitable for authenticating a host, despite the
  77    clearly-marked intentions of the key-holder.
  78
  79 ### Perspectives OpenSSH client ###
  80
  81 [The Perspectives project](http://www.cs.cmu.edu/~perspectives/) at
  82 CMU has released an [openssh client that uses network
  83 notaries](http://www.cs.cmu.edu/~perspectives/openssh.html) to bolster
  84 your confidence in newly-seen keys.  This offers a defense against a
  85 narrow MITM attack (e.g. by someone who controls your local gateway)
  86 by simply verifying that other machines from around the network see
  87 the same keys for the remote host that you're seeing.
  88
  89 This tactic is quite useful, but doesn't take the system as far as it
  90 could go, and doesn't tie into any existing web of trust.
  91
  92 Some concerns with the Perspectives OpenSSH client:
  93
  94  * This client won't help if you are connecting to machines behind
  95    firewalls, on NAT'ed LANs, with source IP filtering, or otherwise
  96    in a restricted network state.
  97
  98  * There is still a question of why you should trust these particular
  99    notaries during your verification.  Who are the notaries?  How
 100    could they be compromised?
 101
 102  * It only provides infrastructure in one direction: the user
 103    authenticating the host by name.  There is no mechanism for dealing
 104    with identifying users by name, or allowing users to globally
 105    revoke or change keys.
 106
 107  * It doesn't provide any mechanism for key rotation or revocation:
 108    Perspectives won't help you if you need to re-key your machine.
 109
 110 ### OpenSSH with X.509v3 certificates ###
 111
 112 Roumen Petrov [maintains a patch to OpenSSH that works with the X.509
 113 PKI model](http://www.roumenpetrov.info/openssh/).  This is the
 114 certificate hierarchy commonly used by TLS (and SSL).
 115
 116 Some concerns about OpenSSH with X.509v3:
 117
 118  * the X.509 certificate specification itself [encourages corporate
 119    consolidation and centralized global "trust" because of its
 120    single-issuer architectural
 121    limitation](http://lair.fifthhorseman.net/~dkg/tls-centralization/).
 122    This results in an expensive and cumbersome system for smaller
 123    players, and it also doesn't correspond to the true distributed
 124    nature of human-to-human trust.  Furthermore, centralized global
 125    "trusted authorities" create a tempting target for attack, and a
 126    single-point-of-failure if an attack is successful.
 127
 128    Depending on how you declare your trust relationships, OpenPGP is
 129    capable of providing the same hierarchical structure as X.509, but
 130    it is not limited to such a structure.  The OpenPGP Web of Trust
 131    model is more flexible and more adaptable to represent real-world
 132    trust than X.509's rigid hierarchy.
 133
 134  * X.509 certificates can identify hosts by name, but not by
 135    individual service.  This means that a compromised web or e-mail
 136    server with access to the X.509 key for that service could re-use
 137    its certificate as an SSH server, and it would be able to
 138    masquerade successfully.
 139
 140    The monkeysphere uses [User IDs of the form
 141    `ssh://foo.example.net`](http://tools.ietf.org/wg/secsh/draft-ietf-secsh-scp-sftp-ssh-uri/),
 142    so they are not by-default shared across services on the same host
 143    (you can still share a key across services on the same host if you
 144    like, but the service User IDs can be certified independently of
 145    one another).