X-Git-Url: https://codewiz.org/gitweb?a=blobdiff_plain;f=doc%2FREADME;h=bed03806f32e3ee092e1e9b6442e56af7cbd9811;hb=a7ccf57188892a050566025587009d153c39cfef;hp=90345193414da1fa4c6306e0fa48068cd634a347;hpb=ec55ca0c26b054a63265947b50e0392060b2a7e0;p=monkeysphere.git diff --git a/doc/README b/doc/README index 9034519..bed0380 100644 --- a/doc/README +++ b/doc/README @@ -1,82 +1,91 @@ -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 " +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 " -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.