+(names in "" are code names until we think of better ones.)
+
+common components
+-----------------
+* "rhesus": update known_hosts/authorized_keys files:
+ - be responsible for removing keys from the file as key revocation
+ happens
+ - be responsible for updating a key in the file where there is a key
+ replacement
+ - must result in a file that is parsable by the existing ssh client
+ without errors
+ - manual management must be allowed without stomping on it
+ - provide a simple, intelligible, clear policy for key acceptance
+
+* "langur": policy-editor for viewing/editing policies
+
+* gpg2ssh: utility to convert gpg keys to ssh
+ known_hosts/authorized_keys lines
+
+* ssh2gpg: create openpgp keypair from ssh keypair
+
+server-side components
+----------------------
+* "howler": server gpg maintainer
+ - generates gpg keys for the server
+ - publishes server gpg keys
+ - used to specify userids to trust for user authentication
+
+* "tamarin": script to trigger rhesus during attempt to initiate
+ connection from client
+
+client-side components
+----------------------
+* "marmoset": script 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
+ - proxy-command | pre-hook script | wrapper script
+ - (ssh_config "LocalCommand" is only run *after* connection)
+
+USE CASE
+========
+
+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.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
+"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.