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