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 rhesus during attempt to initiate
  47   connection from client
  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 magabey.  Alice and Bob, being
  67 the conscientious netizens that they are, have already published their
  68 personal gpg keys to the web of trust, and being good friends, have
  69 both signed each other's keys and marked each others keys with "full"
  70 trust.
  71
  72 Alice uses howler to publish a gpg key for magabey with the special
  73 userid of "ssh://mangabey.example.org".  Alice signs mangabey's gpg
  74 key and publishes this signature as a certification.  Alice then
  75 creates a user "bob" on mangabey, and puts Bob's userid in the
  76 auth_user_ids file for user bob on magabey.  tamarin triggers on
  77 mangabey, which invokes rhesus.  rhesus takes all userids in bob's
  78 auth_user_ids file, looks on a keyserver to find the public keys for
  79 each user, converts the gpg public keys into ssh public keys if the
  80 key validity is acceptable, and finally inserts those keys into an
  81 authorized_keys file for bob.
  82
  83 Bob now adds the "ssh://mangabey.example.org" userid to the
  84 auth_host_ids file in his account on his localhost.  Bob now goes to
  85 connect to bob@mangabey.example.org.  Bob's monkeysphere-enabled ssh
  86 client triggers marmoset, which invokes rhesus on Bob's computer.
  87 rhesus takes all server userids in his auth_host_ids file, looks on a
  88 keyserver to find the public key for each server (based on the
  89 server's URI), converts the gpg public keys into ssh public keys if
  90 the key validity is acceptable, and finally insert those keys into
  91 Bob's known_hosts file.
  92
  93 On Bob's side, since mangabey's key had "full" validity (since it was
  94 signed by Alice whom he fully trusts), Bob's ssh client deems mangabey
  95 "known" and no further host key checking is required.
  96
  97 On mangabey's side, since Bob's key has "full" validity (since it had
  98 also been signed by Alice, mangabey's trusted administrator), Bob is
  99 authenticated and authorized to log into bob@mangabey.
 100
 101 NOTES
 102 =====
 103
 104 * Daniel and Elliot lie. <check>
 105 * We will use a distributed VCS, each developer will create their own
 106   git repository and publish it publicly for others to pull from, mail
 107   out
 108 * public project page doesn't perhaps make sense yet
 109 * approximate goal - using the web of trust to authenticate ppl for
 110   SSH
 111 * outline of various components of monkeysphere
 112 * M: what does it mean to be in the monkeysphere?  not necessarily a
 113   great coder.
 114 * J: interested in seeing project happen, not in actually doing it.
 115   anybody can contribute as much as they want.
 116 * J: if we put the structure in place to work on monkeysphere then we
 117   don't have to do anything
 118 * D: we are not creating
 119 * understand gpg's keyring better, understanding tools better,
 120   building scripts
 121 * Some debian packages allow automated configuration of config files.
 122
 123 * GENERAL GOAL - use openpgp web-of-trust to authenticate ppl for SSH
 124 * SPECIFIC GOAL - allow openssh to tie into pgp web-of-trust without
 125   modifying either openpgp and openssh
 126 * DESIGN GOALS - authentication, use the existing generic OpenSSH
 127   client, the admin can make it default, although end-user should be
 128   decide to use monkeysphere or not
 129 * DESIGN GOAL - use of monkeysphere should not radically change
 130   connecting-to-server experience
 131 * GOAL - pick a monkey-related name for each component
 132
 133 Host identity piece of monkeysphere could be used without buying into
 134 the authorization component.
 135
 136 Monkeysphere is authentication layer that allows the sysadmin to
 137 perform authorization on user identities instead of on keys, it
 138 additionally allows the sysadmin also to authenticate the server to
 139 the end-user.
 140
 141 see doc/git-init for more detail on how to pull from the distributed
 142 repositories.