X-Git-Url: https://codewiz.org/gitweb?a=blobdiff_plain;f=doc%2FREADME;h=9d70e9822f9bad3bba7f0d46a6e46c4f7a9d2374;hb=335ccb07202eb718ae85ca2a1fa7e04042ad4542;hp=86d0150bee6a4b4292af1d496612b8dfd8851da2;hpb=7d38c9dc47c2f47010435ad1dd305c5fe9d2f429;p=monkeysphere.git diff --git a/doc/README b/doc/README index 86d0150..9d70e98 100644 --- a/doc/README +++ b/doc/README @@ -1,21 +1,22 @@ -Monkeysphere User README +#Monkeysphere User README ======================== 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. +Monkeysphere. However, you should be comfortable using secure shell +(ssh), 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 -------------------------------- + +Keep 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 + 0 12 * * * /usr/bin/gpg --refresh-keys > /dev/null 2>&1 This would refresh your keychain every day at noon. @@ -28,9 +29,9 @@ 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 + $ monkeysphere update-known_hosts -This will command will check to see if there is an OpenPGP key for +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. @@ -45,13 +46,13 @@ 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 + 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 * + Host * On a line by itself. Add the ProxyCommand line just below it. @@ -66,6 +67,7 @@ can establish that they are setup correctly. The remaining steps will complete the second half: allow servers to verify you based on your OpenPGP key. + Setting up an OpenPGP authentication key ---------------------------------------- @@ -73,29 +75,36 @@ 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 + $ monkeysphere gen-subkey $GPGID Typically, you can find out what your keyid is by running: -gpg --list-key your@email.address + $ gpg --list-secret-keys -The first line (starting with pub) will include your key length followed +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: +Once you have created an OpenPGP authentication key, you will need to +feed it to your ssh agent. + +Currently (2008-08-23), gnutls does not support this operation. In order +to take this step, you will need to upgrade to a patched version of +gnutls. You can easily upgrade a Debian system by adding the following +to /etc/apt/sources.list.d/monkeysphere.list: + + deb http://monkeysphere.info/debian experimental gnutls + deb-src http://monkeysphere.info/debian experimental gnutls -./seckey2sshagent --help +Next, run `aptitude update; aptitude install libgnuttls26`. -And read the directions - particularly the part about being dropped into -a gpg edit session. This is a work in progress! +With the patched gnutls installed, you can feed your authentication sub +key to your ssh agent by running: -NOTE: the current version of openpgp2ssh does *not* deal well with -encrypted keys (as of 2008-07-26) + $ monkeysphere subkey-to-ssh-agent FIXME: using the key with a single session? @@ -111,7 +120,7 @@ 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 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