Merge commit 'dkg/master'

Conflicts:

	doc/MonkeySpec

3 files changed, 133 insertions, 86 deletions

diff --git a/doc/MonkeySpec b/doc/MonkeySpec
index b0a0d6a..54aaa72 100644
--- a/doc/MonkeySpec
+++ b/doc/MonkeySpec
@@ -39,16 +39,16 @@ common components
 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
+  - 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
@@ -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
 =====
diff --git a/doc/README b/doc/README
index d8f1897..427f214 100644
--- a/doc/README
+++ b/doc/README
@@ -1,36 +1,22 @@
 Monkeysphere README
 ===================
 
-Default files locations (by variable):
-
-MS_HOME=~/.config/monkeysphere
-MS_CONF=$MS_HOME/monkeysphere.conf
-AUTH_HOST_FILE=$MS_HOME/auth_host_ids
-AUTH_USER_FILE=$MS_HOME/auth_user_ids
-GNUPGHOME=~/.gnupg
-STAGING_AREA=$MS_HOME
-
-$STAGING_AREA/host_keys/KEYHASH
-$STAGING_AREA/known_hosts
-$STAGING_AREA/user_keys/KEYHASH
-$STAGING_AREA/authorized_keys
-
 user usage
 ----------
-For a user to update their ms known_hosts file:
+For a user to update their known_hosts file:
 
-$ rhesus --known_hosts
+$ monkeysphere update-known_hosts
 
-For a user to update their ms authorized_keys file:
+For a user to update their monkeysphere authorized_keys file:
 
-$ rhesus --authorized_keys
+$ monkeysphere update-authorized_keys
 
 server service publication
 --------------------------
-To publish a server host key use the "howler" component:
+To publish a server host key:
 
-# howler gen-key
-# howler publish-key
+# monkeysphere-server gen-key
+# monkeysphere-server publish-key
 
 This will generate the key for server with the service URI
 (ssh://server.hostname).  The server admin should now sign the server
@@ -42,38 +28,29 @@ $ gpg --sign-key 'ssh://server.hostname'
 
 server authorized_keys maintenance
 ----------------------------------
-A system can maintain ms authorized_keys files for it's users.  Some
-different variables need to be defined to help manage this.  The way
-this is done is by first defining a new MS_HOME:
+A system can maintain monkeysphere authorized_keys files for it's
+users.
 
-MS_HOME=/etc/monkeysphere
-
-This directory would then have a monkeysphere.conf which defines the
-following variables:
+For each user account on the server, the userids of people authorized
+to log into that account would be placed in:
 
-AUTH_USER_FILE="$MS_HOME"/auth_user_ids/"$USER"
-STAGING_AREA=/var/lib/monkeysphere/stage/$USER
-GNUPGHOME=$MS_HOME/gnupg
+/etc/monkeysphere/authorized_user_file/USER
 
-For each user account on the server, the userids of people authorized
-to log into that account would be placed in the AUTH_USER_FILE for
-that user.  However, in order for users to become authenticated, the
-server must determine that the user keys have "full" validity.  This
-means that the server must fully trust at least one person whose
-signature on the connecting users key would validate the user.  This
-would generally be the server admin.  If the server admin's keyid is
-XXXXXXXX, then on the server run:
+However, in order for users to become authenticated, the server must
+determine that the user keys have "full" validity.  This means that
+the server must fully trust at least one person whose signature on the
+connecting users key would validate the user.  This would generally be
+the server admin.  If the server admin's keyid is XXXXXXXX, then on
+the server run:
 
-# howler trust-key XXXXXXXX
+# monkeysphere-server trust-keys XXXXXXXX
 
-To update the ms authorized_keys file for user "bob", the system would
-then run the following:
+To update the monkeysphere authorized_keys file for user "bob", the
+system would then run the following:
 
-# USER=bob MS_HOME=/etc/monkeysphere rhesus --authorized_keys
+# monkeysphere-server update-users bob
 
-To update the ms authorized_keys file for all users on the the system:
+To update the monkeysphere authorized_keys file for all users on the
+the system, run the same command with no arguments:
 
-MS_HOME=/etc/monkeysphere
-for USER in $(ls -1 /etc/monkeysphere/auth_user_ids) ; do
-    rhesus --authorized_keys
-done
+# monkeysphere-server update-users bob
diff --git a/doc/TODO b/doc/TODO
new file mode 100644
index 0000000..905d198
--- /dev/null
+++ b/doc/TODO
@@ -0,0 +1,51 @@
+Next-Steps Monkeysphere Projects:
+---------------------------------
+
+Handle unknown hosts in such a way that they're not always removed
+   from known_hosts file.  Ask user to lsign the host key?
+
+Handle multiple multiple hostnames (multiple user IDs?) when
+   generating host keys with gen-key.
+
+Make sure alternate ports are handled for known_hosts.
+
+Add environment variables sections to man pages.
+
+Script to import private key into ssh agent.
+
+Provide a friendly interactive UI for marginal or failing client-side
+   hostkey verifications.  Handle the common cases smoothly, and
+   provide good debugging info for the unusual cases.
+
+Make sure onak properly escapes user IDs with colons in them.
+
+Build a decent, presentable web site for documentation, evangelism,
+   etc.  Include a mention of how to report trouble or concerns.
+
+Create ssh2openpgp or convert to full-fledged keytrans.
+
+Resolve the bugs listed in openpgp2ssh(1):BUGS.
+
+Understand and document alternate trustdb models.
+
+Understand and document the output of gpg --check-trustdb:
+ gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
+ gpg: depth: 0  valid:   2  signed:  20  trust: 0-, 0q, 0n, 0m, 0f, 2u
+ gpg: depth: 1  valid:  20  signed:  67  trust: 15-, 0q, 1n, 3m, 1f, 0u
+ gpg: next trustdb check due at 2008-10-09
+
+Understand and document the numeric values between sig! and the keyid
+   in "gpg --check-sigs $KEYID" .  Compare with the details found from
+   "gpg --with-colons --check-sigs $KEYID".  This has to do with trust
+   signatures.
+
+Fix gpg's documentation to clarify the difference between validity and
+   ownertrust.  Include better documentation for trust signatures.
+
+Make it easier to do domain-relative ssh host trust signatures with
+   gnupg. (e.g. "i trust Jamie McClelland (keyID 76CC057D) to properly
+   identify ssh servers in the mayfirst.org domain") See:
+   http://tools.ietf.org/html/rfc4880#section-5.2.3.21 and grep for
+   "tsign" in gpg(1).
+
+Fix the order of questions when user does a tsign in gpg or gpg2.