updated MonkeySpec to be more user-friendly.

diff --git a/doc/MonkeySpec b/doc/MonkeySpec
index b0a0d6a10d203f81141d5ed5a059234d97928db7..6ac5f1195bf755d7ef65f29660ae423741cc3ab8 100644 (file)
--- 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,
 
 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.
 
 "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
 =====
 
 NOTES
 =====