-Monkeysphere README
-===================
+Monkeysphere User README
+========================
-Default files locations (by variable):
+As a regular user on a system where the monkeysphere package is
+installed, you probably want to do a few things:
-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
+Keeping your keyring up-to-date
+-------------------------------
-$STAGING_AREA/host_keys/KEYHASH
-$STAGING_AREA/known_hosts
-$STAGING_AREA/user_keys/KEYHASH
-$STAGING_AREA/authorized_keys
+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:
-user usage
-----------
-For a user to update their ms known_hosts file:
+0 12 * * * /usr/bin/gpg --refresh-keys
-$ rhesus --known_hosts
+This would refresh your keychain every day at noon.
-For a user to update their ms authorized_keys file:
-$ rhesus --authorized_keys
+Keeping your known_hosts file in sync with your keyring
+-------------------------------------------------------
-server service publication
---------------------------
-To publish a server host key use the "howler" component:
+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:
-# howler gen-key
-# howler publish-key
+$ monkeysphere update-known_hosts
-This will generate the key for server with the service URI
-(ssh://server.hostname). The server admin should now sign the server
-key so that people in the admin's web of trust can authenticate the
-server without manual host key checking:
+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.
-$ gpg --search ='ssh://server.hostname'
-$ 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:
+Using monkeysphere-ssh-proxycommand(1)
+--------------------------------------
-MS_HOME=/etc/monkeysphere
+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:
-This directory would then have a monkeysphere.conf which defines the
-following variables:
+ProxyCommand monkeysphere-ssh-proxycommand %h %p
-AUTH_USER_FILE="$MS_HOME"/auth_user_ids/"$USER"
-STAGING_AREA=/var/lib/monkeysphere/stage/$USER
-GNUPGHOME=$MS_HOME/gnupg
-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 userid is
+Setting up an OpenPGP authentication key
+----------------------------------------
-"Alice <alice@foo.com>"
+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:
-then the server would run:
+$ monkeysphere gen-subkey $GPGID
-# howler trust-uids "Alice <alice@foo.com>"
-To update the ms authorized_keys file for user "bob", the system would
-then run the following:
+Using your OpenPGP authentication key for SSH
+---------------------------------------------
-# USER=bob MS_HOME=/etc/monkeysphere rhesus --authorized_keys
+FIXME: Sending the key to the ssh-agent?
-To update the ms authorized_keys file for all users on the the system:
+FIXME: using the key with a single session?
-MS_HOME=/etc/monkeysphere
-for USER in $(ls -1 /etc/monkeysphere/auth_user_ids) ; do
- rhesus --authorized_keys
-done
+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.
projects / monkeysphere.git / blobdiff