doc/MonkeySpec

   1 THE MONKEYSPHERE
   2 ================
   3
   4 Monkeysphere is authentication layer that allows the sysadmin to
   5 perform authorization on OpenPGP user identities instead of on keys.
   6 It also allows end users to authenticate/identify the ssh server they
   7 are connecting to by checking the sysadmin's certification.
   8
   9 * GENERAL GOAL - use openpgp web-of-trust to authenticate ppl for SSH
  10 * SPECIFIC GOAL - allow openssh to tie into pgp web-of-trust without
  11   modifying the openpgp spec, gpg or openssh
  12 * DESIGN GOALS - authentication, use the existing generic OpenSSH
  13   client, the admin can make it default, although end-user should be
  14   decide to use monkeysphere or not
  15 * DESIGN GOAL - use of monkeysphere should not radically change
  16   connecting-to-server experience
  17
  18 Host identity piece of monkeysphere could be used without buying into
  19 the user authentication component.
  20
  21
  22 USE CASE
  23 ========
  24
  25 Dramatis Personae: http://en.wikipedia.org/wiki/Alice_and_Bob
  26 Backstory: http://www.conceptlabs.co.uk/alicebob.html
  27
  28 Bob wants to sign on to the computer "mangabey.example.org" via
  29 monkeysphere framework.  He doesn't yet have access to the machine,
  30 but he knows Alice, who is the admin of mangabey.  Alice and Bob,
  31 being the conscientious netizens that they are, have already published
  32 their personal gpg keys to the web of trust, and being good friends,
  33 have both signed each other's keys and marked each others keys with
  34 "full" ownertrust.
  35
  36 When Alice set up mangabey initially, she published an OpenPGP key for
  37 the machine with the special userid of "ssh://mangabey.example.org".
  38 She also signed mangabey's OpenPGP key and published this
  39 certification to commonly-used keyservers.  Alice also configured
  40 mangabey to treat her own key with full ownertrust, so that it knows
  41 how to identify connecting users.
  42
  43 Now, Alice creates a user account "bob" on mangabey, and puts Bob's
  44 userid ("Bob <bob@example.org>") in the authorized_user_ids file for
  45 user bob on mangabey.  The monkeysphere automatically (via cron or
  46 inotify hook) takes each userid in bob's authorized_user_ids file, and
  47 looks on a keyserver to find all public keys associated with that user
  48 ID, with the goal of populating the authorized_keys file for
  49 bob@mangabey.
  50
  51 In particular: for each key found, the server evaluates the calculated
  52 validity of the specified user ID based on the ownertrust rules it has
  53 configured ("trust alice's certifications fully", in this example).
  54 For each key for which the user ID in question is fully-valid, it
  55 extracts all DSA- or RSA-based primary or secondary keys marked with
  56 the authentication usage flag, and converts these OpenPGP public keys
  57 into ssh public keys.  These keys are automatically placed into the
  58 authorized_keys file for bob.
  59
  60 Bob now attempts to connect, by firing up a terminal and invoking:
  61 "ssh bob@mangabey.example.org".  Bob's monkeysphere-enabled ssh client
  62 notices that mangabey.example.org isn't already available in bob's
  63 known_hosts file, and fetches the host key for mangabey from the
  64 public keyservers, with the goal of populating Bob's local known_hosts
  65 file.
  66
  67 In particular: the monkeysphere queries its configured keyservers to
  68 find all public keys with User ID ssh://mangabey.example.org.  For
  69 each public key found, it checks the relevant User ID's validity,
  70 converts any authentication-capable OpenPGP public keys into ssh
  71 public keys if the User ID validity is acceptable, and finally insert
  72 those keys into Bob's known_hosts file.
  73
  74 On Bob's side, since mangabey's key had "full" validity (it was signed
  75 by Alice, whom he fully trusts), Bob's ssh client deems mangabey
  76 "known" and no further host key checking is required.
  77
  78 On mangabey's side, since Bob's key has "full" validity (it had been
  79 signed by Alice, mangabey's trusted administrator), Bob is
  80 authenticated and therefore authorized to log into his account.
  81