X-Git-Url: https://codewiz.org/gitweb?a=blobdiff_plain;f=doc%2FREADME;h=bed03806f32e3ee092e1e9b6442e56af7cbd9811;hb=a7ccf57188892a050566025587009d153c39cfef;hp=4c70d1d8d31efa84c630bd9e6be3b67af77cec3a;hpb=d19ed9fb6cc0bd7de9eb14b6d192c9eaccedc427;p=monkeysphere.git

diff --git a/doc/README b/doc/README
index 4c70d1d..bed0380 100644
--- a/doc/README
+++ b/doc/README
@@ -1,5 +1,91 @@
-				Monkeysphere
-				------------
+Monkeysphere User README
+========================
 
+As a regular user on a system where the monkeysphere package is
+installed, you probably want to do a few things:
 
-This is the README!
+Keeping your keyring up-to-date
+-------------------------------
+
+Regularly refresh your GnuPG keyring from the keyservers.  This can be
+done with a simple cronjob.  An example of crontab line to do this is:
+
+0 12 * * * /usr/bin/gpg --refresh-keys
+
+This would refresh your keychain every day at noon.
+
+
+Keeping your known_hosts file in sync with your keyring
+-------------------------------------------------------
+
+With your keyring updated, you want to make sure that openssh can
+still see the most recent trusted information about who the various
+hosts are.  This can be done with the monkeysphere-ssh-proxycommand
+(see next section) or with the update-known_hosts command:
+
+$ monkeysphere update-known_hosts
+
+This will command will check to see if there is an openpgp key for
+each (non-hashed) host listed in the known_hosts file, and then add
+the key for that host to the known_hosts file if one is found.  This
+command could be added to a crontab as well, if desired.
+
+
+Using monkeysphere-ssh-proxycommand(1)
+--------------------------------------
+
+The best way to handle host keys is to use the monkeysphere ssh proxy
+command.  This command will make sure the known_hosts file is
+up-to-date for the host you are connecting to with ssh.  The best way
+to integrate this is to add the following line to the "Host *" section
+of your ~/.ssh/config file:
+
+ProxyCommand monkeysphere-ssh-proxycommand %h %p
+
+
+Setting up an OpenPGP authentication key
+----------------------------------------
+
+First things first: you'll need to create a new subkey for your
+current key, if you don't already have one.  If your OpenPGP key is
+keyid $GPGID, you can set up such a subkey relatively easily with:
+
+$ monkeysphere gen-subkey $GPGID
+
+
+Using your OpenPGP authentication key for SSH
+---------------------------------------------
+
+FIXME: Sending the key to the ssh-agent?
+
+FIXME: using the key with a single session?
+
+NOTE: the current version of openpgp2ssh does *not* deal well with
+encrypted keys (as of 2008-07-26)
+
+
+Miscellaneous
+-------------
+
+Users can also maintain their own authorized_keys files, for users
+that would be logging into their accounts.  This is primarily useful
+for accounts on hosts that are not already systematically using the
+monkeysphere for user authentication.  If you're not sure whether this
+is the case for your host, ask your system administrator.
+
+If you want to do this as a regular user, use the
+update-authorized_keys command:
+
+$ monkeysphere update-authorized_keys
+
+This command will take all the user IDs listed in the
+~/.config/monkeysphere/authorized_user_ids file and check to see if
+there are acceptable keys for those user IDs available.  If so, they
+will be added to the ~/.ssh/authorized_keys file.
+
+You must have indicated reasonable ownertrust in some key for this
+account, or no keys will be found with trusted certification paths.
+
+If you find this useful, you might want to place a job like this in
+your crontab so that revocations and rekeyings can take place
+automatically.