X-Git-Url: https://codewiz.org/gitweb?a=blobdiff_plain;f=doc%2FREADME;h=684f524100698642664d79a652b75f52fbb79b8e;hb=5001c4b2f12540425be9e74c84beba3096981b21;hp=cda1194336bfb028e8fabd71f46c3d0104fdc088;hpb=3a6f611a52d56b919b8c50a6e1700af43ff49578;p=monkeysphere.git diff --git a/doc/README b/doc/README index cda1194..684f524 100644 --- a/doc/README +++ b/doc/README @@ -1,56 +1,126 @@ -Monkeysphere README -=================== +Monkeysphere User README +======================== -user usage ----------- -For a user to update their known_hosts file: +You don't have to be an OpenSSH or OpenPGP expert to use the +Monkeysphere. However, you should be comfortable using secure shell and +you should already have GnuPG installed and an OpenPGP key pair before +you begin. + +As a regular user on a system where the monkeysphere package is +installed, you probably want to do a few things: + +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 > /dev/null 2>&1 + +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 -For a user to update their monkeysphere authorized_keys file: +This 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. -$ monkeysphere update-authorized_keys -server service publication --------------------------- -To publish a server host key: +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 + +The "Host *" section specifies what ssh options to use for all +connections. If you don't already have a "Host *" line, you can add it +by entering: + +Host * -# monkeysphere-server gen-key -# monkeysphere-server publish-key +On a line by itself. Add the ProxyCommand line just below it. -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: +Once you've completed this step - you are half-way there. You will now +be able to verify servers participating in the monkeysphere provided +their keys have been signed by someone that you trust. -$ gpg --search ='ssh://server.hostname' -$ gpg --sign-key 'ssh://server.hostname' +FIXME: We should setup a way for someone to download a test gpg key and +then connect to a test server that is signed by this gpg key so users +can establish that they are setup correctly. -server authorized_keys maintenance ----------------------------------- -A system can maintain monkeysphere authorized_keys files for it's -users. +The remaining steps will complete the second half: allow servers to +verify you based on your OpenPGP key. -For each user account on the server, the userids of people authorized -to log into that account would be placed in: +Setting up an OpenPGP authentication key +---------------------------------------- -/etc/monkeysphere/authorized_user_ids/USER +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: -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: +$ monkeysphere gen-subkey $GPGID -# monkeysphere-server trust-keys XXXXXXXX +Typically, you can find out what your keyid is by running: -To update the monkeysphere authorized_keys file for user "bob", the -system would then run the following: +gpg --list-secret-keys + +The first line (starting with sec) will include your key length followed +by the type of key (e.g. 1024D) followed by a slash and then your keyid. + +Using your OpenPGP authentication key for SSH +--------------------------------------------- + +Once you have created a OpenPGP authentication key, you can feed it to +your ssh agent by running seckey2sshagent (currently this is found in +the src directory). Please run: + +./seckey2sshagent --help + +And read the directions - particularly the part about being dropped into +a gpg edit session. This is a work in progress! + +NOTE: the current version of openpgp2ssh does *not* deal well with +encrypted keys (as of 2008-07-26) + +FIXME: using the key with a single session? + +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 -# monkeysphere-server update-users bob +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. -To update the monkeysphere authorized_keys file for all users on the -the system, run the same command with no arguments: +You must have indicated reasonable ownertrust in some key for this +account, or no keys will be found with trusted certification paths. -# monkeysphere-server update-users +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.