server-side components
----------------------
-* "howler": service gpg key generator/publisher
+* "howler": server gpg maintainer
+ - generate gpg keys for the server
+ - publish server gpg keys
+ - give owner trust to keys for user authentication
-* "tamarin": script to trigger rhesus during attempt to initiate
- connection from client
+* "tamarin": concept - how to trigger or schedule rhesus at admin defined
+ points (e.g. via cron or during ssh connections).
client-side components
----------------------
-* "marmoset": script to trigger rhesus during attempt to initiate
+* "marmoset": concept - how to trigger rhesus during attempt to initiate
connection to server
- runs on connection to a certain host
- triggers update to known_hosts file then makes connection
Dramatis Personae: http://en.wikipedia.org/wiki/Alice_and_Bob
Backstory: http://www.conceptlabs.co.uk/alicebob.html
-Bob wants to sign on to the computer "mangabey" 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
-contientious 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
-"ssh://magabey" URI userid. Alice signs magabey's gpg key and
-publishes her signature. Alice then creates a user "bob" on magabey,
-and puts Bob's userid in the auth_user_ids file for user bob on
-magabey. tamarin triggers on magabey, which triggers rhesus, which
-takes all userids in bob's auth_user_ids file, look 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 insert
-those keys into an authorized_keys file for bob.
-
-Bob now adds the "ssh://magabey" userid to the auth_host_ids file in
-his account on his localhost. Bob now goes to connect to bob@magabey.
-Bob's ssh client, which is monkeysphere enabled, triggers marmoset,
-which triggers rhesus on Bob's computer, which 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 magabey
+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 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 magabey's side, since Bob's key has "full" validity (since it had
-also been signed by Alice whom magabey fully trusts (since Alice told
-him to)), Bob is authenticated to log into bob@magabey.
+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
=====
additionally allows the sysadmin also to authenticate the server to
the end-user.
-git clone http://git.mlcastle.net/monkeysphere.git/ monkeysphere
+see doc/git-init for more detail on how to pull from the distributed
+repositories.