updated MonkeySpec to be more user-friendly.

1 files changed, 51 insertions, 32 deletions

diff --git a/doc/MonkeySpec b/doc/MonkeySpec
index b0a0d6a..6ac5f11 100644
--- a/doc/MonkeySpec
+++ b/doc/MonkeySpec
@@ -63,40 +63,59 @@ Backstory: http://www.conceptlabs.co.uk/alicebob.html
 
 Bob wants to sign on to the computer "mangabey.example.org" via
 monkeysphere framework.  He doesn't yet have access to the machine,
-but he knows Alice, who is the admin of magabey.  Alice and Bob, being
-the conscientious netizens that they are, have already published their
-personal gpg keys to the web of trust, and being good friends, have
-both signed each other's keys and marked each others keys with "full"
-trust.
-
-Alice uses howler to publish a gpg key for magabey with the special
-userid of "ssh://mangabey.example.org".  Alice signs mangabey's gpg
-key and publishes this signature as a certification.  Alice then
-creates a user "bob" on mangabey, and puts Bob's userid in the
-auth_user_ids file for user bob on magabey.  tamarin triggers on
-mangabey, which invokes rhesus.  rhesus takes all userids in bob's
-auth_user_ids file, looks on a keyserver to find the public keys for
-each user, converts the gpg public keys into ssh public keys if the
-key validity is acceptable, and finally inserts those keys into an
-authorized_keys file for bob.
-
-Bob now adds the "ssh://mangabey.example.org" userid to the
-auth_host_ids file in his account on his localhost.  Bob now goes to
-connect to bob@mangabey.example.org.  Bob's monkeysphere-enabled ssh
-client triggers marmoset, which invokes rhesus on Bob's computer.
-rhesus takes all server userids in his auth_host_ids file, looks on a
-keyserver to find the public key for each server (based on the
-server's URI), converts the gpg public keys into ssh public keys if
-the key validity is acceptable, and finally insert those keys into
-Bob's known_hosts file.
-
-On Bob's side, since mangabey's key had "full" validity (since it was
-signed by Alice whom he fully trusts), Bob's ssh client deems mangabey
+but he knows Alice, who is the admin of mangabey.  Alice and Bob,
+being the conscientious netizens that they are, have already published
+their personal gpg keys to the web of trust, and being good friends,
+have both signed each other's keys and marked each others keys with
+"full" ownertrust.
+
+When Alice set up mangabey initially, she used howler to publish a gpg
+key for the machine with the special userid of
+"ssh://mangabey.example.org".  She also signed mangabey's gpg key and
+published this certification to commonly-used keyservers.  Alice also
+configured mangabey to treat her own key with full ownertrust (could
+this be done as part of the howler invocation?)
+
+Now, Alice creates a user account "bob" on mangabey, and puts Bob's
+userid ("Bob <bob@example.org>") in the authorized_user_ids file for
+user bob on mangabey.  tamarin triggers on mangabey either by a
+cronjob or an inotify hook, and invokes rhesus for the "bob" account.
+rhesus automatically takes each userid in bob's authorized_user_ids
+file, and looks on a keyserver to find all public keys associated with
+that user ID, with the goal of populating the authorized_keys file for
+bob@mangabey.  
+
+In particular: for each key found, the server evaluates the calculated
+validity of the specified user ID based on the ownertrust rules it has
+configured ("trust alice's certifications fully", in this example).
+For each key for which the user ID in question is fully-valid, it
+extracts all DSA- or RSA-based primary or secondary keys marked with
+usage flags for encrypted communications and authentication, and
+converts these gpg public keys into ssh public keys.  Finally, rhesus
+inserts these calculated public keys into the authorized_keys file for
+bob.
+
+Bob now attempts to connect, by firing up a terminal and invoking:
+"ssh bob@mangabey.example.org".  Bob's monkeysphere-enabled ssh client
+notices that mangabey.example.org isn't already available in bob's
+known_hosts file, and triggers rhesus (on Bob's computer) to fetch the
+key for mangabey, with the goal of populating Bob's local known_hosts
+file.
+
+In particular: rhesus queries its configured keyservers to find all
+public keys with User ID ssh://mangabey.example.org.  For each public
+key found, rhesus checks the relevant User ID's validity, converts any
+"encrypted comms, authentication" gpg public keys into ssh public keys
+if the User ID validity is acceptable, and finally insert those keys
+into Bob's known_hosts file.
+
+On Bob's side, since mangabey's key had "full" validity (it was signed
+by Alice whom he fully trusts), Bob's ssh client deems mangabey
 "known" and no further host key checking is required.
 
-On mangabey's side, since Bob's key has "full" validity (since it had
-also been signed by Alice, mangabey's trusted administrator), Bob is
-authenticated and authorized to log into bob@mangabey.
+On mangabey's side, since Bob's key has "full" validity (it had been
+signed by Alice, mangabey's trusted administrator), Bob is
+authenticated and therefore authorized to log into his account.
 
 NOTES
 =====