doc/MonkeySpec

   1 THE MONKEYSPHERE
   2 ================
   3
   4 AGENDA
   5 ======
   6 [x] clowning
   7 [ ] work
   8 [x] jrollins will talk and gesture - in progress
   9
  10 MONKEYNAMES
  11 ===========
  12
  13 rhesus, marmoset, howler, langur, tamarin, barbary
  14
  15 COMPONENTS
  16 ==========
  17
  18 (names in "" are code names until we think of better ones.)
  19
  20 common components
  21 -----------------
  22 * "rhesus": update known_hosts/authorized_keys files:
  23   - be responsible for removing keys from the file as key revocation
  24     happens
  25   - be responsible for updating a key in the file where there is a key
  26     replacement
  27   - must result in a file that is parsable by the existing ssh client
  28     without errors
  29   - manual management must be allowed without stomping on it
  30   - provide a simple, intelligible, clear policy for key acceptance
  31
  32 * "langur": policy-editor for viewing/editing policies
  33
  34 * gpg2ssh: utility to convert gpg keys to ssh
  35   known_hosts/authorized_keys lines
  36
  37 * ssh2gpg: create openpgp keypair from ssh keypair
  38
  39 server-side components
  40 ----------------------
  41 * "howler": server gpg maintainer
  42   - generates gpg keys for the server
  43   - publishes server gpg keys
  44   - used to specify userids to trust for user authentication
  45
  46 * "tamarin": script to trigger or schedule rhesus at admin defined
  47         points (e.g. via cron or during ssh connections).
  48
  49 client-side components
  50 ----------------------
  51 * "marmoset": script to trigger rhesus during attempt to initiate
  52   connection to server
  53   - runs on connection to a certain host
  54   - triggers update to known_hosts file then makes connection
  55   - proxy-command | pre-hook script | wrapper script
  56   - (ssh_config "LocalCommand" is only run *after* connection)
  57
  58 USE CASE
  59 ========
  60
  61 Dramatis Personae: http://en.wikipedia.org/wiki/Alice_and_Bob
  62 Backstory: http://www.conceptlabs.co.uk/alicebob.html
  63
  64 Bob wants to sign on to the computer "mangabey.example.org" via
  65 monkeysphere framework.  He doesn't yet have access to the machine,
  66 but he knows Alice, who is the admin of mangabey.  Alice and Bob,
  67 being the conscientious netizens that they are, have already published
  68 their personal gpg keys to the web of trust, and being good friends,
  69 have both signed each other's keys and marked each others keys with
  70 "full" ownertrust.
  71
  72 When Alice set up mangabey initially, she used howler to publish a gpg
  73 key for the machine with the special userid of
  74 "ssh://mangabey.example.org".  She also signed mangabey's gpg key and
  75 published this certification to commonly-used keyservers.  Alice also
  76 configured mangabey to treat her own key with full ownertrust (could
  77 this be done as part of the howler invocation?)
  78
  79 Now, Alice creates a user account "bob" on mangabey, and puts Bob's
  80 userid ("Bob <bob@example.org>") in the authorized_user_ids file for
  81 user bob on mangabey.  tamarin triggers on mangabey either by a
  82 cronjob or an inotify hook, and invokes rhesus for the "bob" account.
  83 rhesus automatically takes each userid in bob's authorized_user_ids
  84 file, and looks on a keyserver to find all public keys associated with
  85 that user ID, with the goal of populating the authorized_keys file for
  86 bob@mangabey.
  87
  88 In particular: for each key found, the server evaluates the calculated
  89 validity of the specified user ID based on the ownertrust rules it has
  90 configured ("trust alice's certifications fully", in this example).
  91 For each key for which the user ID in question is fully-valid, it
  92 extracts all DSA- or RSA-based primary or secondary keys marked with
  93 usage flags for encrypted communications and authentication, and
  94 converts these gpg public keys into ssh public keys.  Finally, rhesus
  95 inserts these calculated public keys into the authorized_keys file for
  96 bob.
  97
  98 Bob now attempts to connect, by firing up a terminal and invoking:
  99 "ssh bob@mangabey.example.org".  Bob's monkeysphere-enabled ssh client
 100 notices that mangabey.example.org isn't already available in bob's
 101 known_hosts file, and triggers rhesus (on Bob's computer) to fetch the
 102 key for mangabey, with the goal of populating Bob's local known_hosts
 103 file.
 104
 105 In particular: rhesus queries its configured keyservers to find all
 106 public keys with User ID ssh://mangabey.example.org.  For each public
 107 key found, rhesus checks the relevant User ID's validity, converts any
 108 "encrypted comms, authentication" gpg public keys into ssh public keys
 109 if the User ID validity is acceptable, and finally insert those keys
 110 into Bob's known_hosts file.
 111
 112 On Bob's side, since mangabey's key had "full" validity (it was signed
 113 by Alice whom he fully trusts), Bob's ssh client deems mangabey
 114 "known" and no further host key checking is required.
 115
 116 On mangabey's side, since Bob's key has "full" validity (it had been
 117 signed by Alice, mangabey's trusted administrator), Bob is
 118 authenticated and therefore authorized to log into his account.
 119
 120 NOTES
 121 =====
 122
 123 * Daniel and Elliot lie. <check>
 124 * We will use a distributed VCS, each developer will create their own
 125   git repository and publish it publicly for others to pull from, mail
 126   out
 127 * public project page doesn't perhaps make sense yet
 128 * approximate goal - using the web of trust to authenticate ppl for
 129   SSH
 130 * outline of various components of monkeysphere
 131 * M: what does it mean to be in the monkeysphere?  not necessarily a
 132   great coder.
 133 * J: interested in seeing project happen, not in actually doing it.
 134   anybody can contribute as much as they want.
 135 * J: if we put the structure in place to work on monkeysphere then we
 136   don't have to do anything
 137 * D: we are not creating
 138 * understand gpg's keyring better, understanding tools better,
 139   building scripts
 140 * Some debian packages allow automated configuration of config files.
 141
 142 * GENERAL GOAL - use openpgp web-of-trust to authenticate ppl for SSH
 143 * SPECIFIC GOAL - allow openssh to tie into pgp web-of-trust without
 144   modifying either openpgp and openssh
 145 * DESIGN GOALS - authentication, use the existing generic OpenSSH
 146   client, the admin can make it default, although end-user should be
 147   decide to use monkeysphere or not
 148 * DESIGN GOAL - use of monkeysphere should not radically change
 149   connecting-to-server experience
 150 * GOAL - pick a monkey-related name for each component
 151
 152 Host identity piece of monkeysphere could be used without buying into
 153 the authorization component.
 154
 155 Monkeysphere is authentication layer that allows the sysadmin to
 156 perform authorization on user identities instead of on keys, it
 157 additionally allows the sysadmin also to authenticate the server to
 158 the end-user.
 159
 160 see doc/git-init for more detail on how to pull from the distributed
 161 repositories.