doc/README

   1 Monkeysphere User README
   2 ========================
   3
   4 You don't have to be an OpenSSH or OpenPGP expert to use the
   5 Monkeysphere.  However, you should be comfortable using secure shell
   6 (ssh), and you should already have GnuPG installed and an OpenPGP key
   7 pair before you begin.
   8
   9 As a regular user on a system where the monkeysphere package is
  10 installed, you probably want to do a few things:
  11
  12
  13 Keep your keyring up-to-date
  14 ----------------------------
  15
  16 Regularly refresh your GnuPG keyring from the keyservers.  This can be
  17 done with a simple cronjob.  An example of crontab line to do this is:
  18
  19 0 12 * * * /usr/bin/gpg --refresh-keys > /dev/null 2>&1
  20
  21 This would refresh your keychain every day at noon.
  22
  23
  24 Keeping your known_hosts file in sync with your keyring
  25 -------------------------------------------------------
  26
  27 With your keyring updated, you want to make sure that OpenSSH can
  28 still see the most recent trusted information about who the various
  29 hosts are.  This can be done with the monkeysphere-ssh-proxycommand
  30 (see next section) or with the update-known_hosts command:
  31
  32 $ monkeysphere update-known_hosts
  33
  34 This command will check to see if there is an OpenPGP key for
  35 each (non-hashed) host listed in the known_hosts file, and then add
  36 the key for that host to the known_hosts file if one is found.  This
  37 command could be added to a crontab as well, if desired.
  38
  39
  40 Using monkeysphere-ssh-proxycommand(1)
  41 --------------------------------------
  42
  43 The best way to handle host keys is to use the monkeysphere ssh proxy
  44 command.  This command will make sure the known_hosts file is
  45 up-to-date for the host you are connecting to with ssh.  The best way
  46 to integrate this is to add the following line to the "Host *" section
  47 of your ~/.ssh/config file:
  48
  49 ProxyCommand monkeysphere-ssh-proxycommand %h %p
  50
  51 The "Host *" section specifies what ssh options to use for all
  52 connections. If you don't already have a "Host *" line, you can add it
  53 by entering:
  54
  55 Host *
  56
  57 On a line by itself. Add the ProxyCommand line just below it.
  58
  59 Once you've completed this step - you are half-way there. You will now
  60 be able to verify servers participating in the monkeysphere provided
  61 their keys have been signed by someone that you trust.
  62
  63 FIXME: We should setup a way for someone to download a test gpg key and
  64 then connect to a test server that is signed by this gpg key so users
  65 can establish that they are setup correctly.
  66
  67 The remaining steps will complete the second half: allow servers to
  68 verify you based on your OpenPGP key.
  69
  70
  71 Setting up an OpenPGP authentication key
  72 ----------------------------------------
  73
  74 First things first: you'll need to create a new subkey for your
  75 current key, if you don't already have one.  If your OpenPGP key is
  76 keyid $GPGID, you can set up such a subkey relatively easily with:
  77
  78 $ monkeysphere gen-subkey $GPGID
  79
  80 Typically, you can find out what your keyid is by running:
  81
  82 gpg --list-secret-keys
  83
  84 The first line (starting with sec) will include your key length followed
  85 by the type of key (e.g. 1024D) followed by a slash and then your keyid.
  86
  87
  88 Using your OpenPGP authentication key for SSH
  89 ---------------------------------------------
  90
  91 Once you have created an OpenPGP authentication key, you will need to
  92 feed it to your ssh agent.
  93
  94 Currently (2008-08-23), gnutls does not support this operation. In order
  95 to take this step, you will need to upgrade to a patched version of
  96 gnutls. You can easily upgrade a Debian system by adding the following
  97 to /etc/apt/sources.list.d/monkeysphere.list:
  98
  99                 deb http://monkeysphere.info/debian experimental gnutls
 100                 deb-src http://monkeysphere.info/debian experimental gnutls
 101
 102 And then adding the following to /etc/apt/preferences:
 103
 104                 Package: libgnutls26
 105                 Pin: release o=The MonkeySphere Project
 106                 Pin-Priority: 990
 107
 108                 Package: libgnutls26-dbg
 109                 Pin: release o=The MonkeySphere Project
 110                 Pin-Priority: 990
 111
 112                 Package: gnutls-bin
 113                 Pin: release o=The MonkeySphere Project
 114                 Pin-Priority: 990
 115
 116                 Package: gnutls-doc
 117                 Pin: release o=The MonkeySphere Project
 118                 Pin-Priority: 990
 119
 120                 Package: guile-gnutls
 121                 Pin: release o=The MonkeySphere Project
 122                 Pin-Priority: 990
 123
 124                 Package: gnutls-dev
 125                 Pin: release o=The MonkeySphere Project
 126                 Pin-Priority: 990
 127
 128 Next, run `aptitude update; aptitude install libgnuttls26`.
 129
 130 With the patched gnutls installed, you can feed your authentication sub
 131 key to your ssh agent by running:
 132
 133                 monkeysphere subkey-to-ssh-agent
 134
 135 You may want to add this command to your ~/.xsession file so it is run
 136 automatically everytime you login.
 137
 138 FIXME: using the key with a single session?
 139
 140
 141 Miscellaneous
 142 -------------
 143
 144 Users can also maintain their own authorized_keys files, for users
 145 that would be logging into their accounts.  This is primarily useful
 146 for accounts on hosts that are not already systematically using the
 147 monkeysphere for user authentication.  If you're not sure whether this
 148 is the case for your host, ask your system administrator.
 149
 150 If you want to do this as a regular user, use the
 151 update-authorized_keys command:
 152
 153 $ monkeysphere update-authorized_keys
 154
 155 This command will take all the user IDs listed in the
 156 ~/.config/monkeysphere/authorized_user_ids file and check to see if
 157 there are acceptable keys for those user IDs available.  If so, they
 158 will be added to the ~/.ssh/authorized_keys file.
 159
 160 You must have indicated reasonable ownertrust in some key for this
 161 account, or no keys will be found with trusted certification paths.
 162
 163 If you find this useful, you might want to place a job like this in
 164 your crontab so that revocations and rekeyings can take place
 165 automatically.