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 and
   6 you should already have GnuPG installed and an OpenPGP key pair before
   7 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 Keeping your keyring up-to-date
  13 -------------------------------
  14
  15 Regularly refresh your GnuPG keyring from the keyservers.  This can be
  16 done with a simple cronjob.  An example of crontab line to do this is:
  17
  18 0 12 * * * /usr/bin/gpg --refresh-keys > /dev/null 2>&1
  19
  20 This would refresh your keychain every day at noon.
  21
  22
  23 Keeping your known_hosts file in sync with your keyring
  24 -------------------------------------------------------
  25
  26 With your keyring updated, you want to make sure that OpenSSH can
  27 still see the most recent trusted information about who the various
  28 hosts are.  This can be done with the monkeysphere-ssh-proxycommand
  29 (see next section) or with the update-known_hosts command:
  30
  31 $ monkeysphere update-known_hosts
  32
  33 This command will check to see if there is an OpenPGP key for
  34 each (non-hashed) host listed in the known_hosts file, and then add
  35 the key for that host to the known_hosts file if one is found.  This
  36 command could be added to a crontab as well, if desired.
  37
  38
  39 Using monkeysphere-ssh-proxycommand(1)
  40 --------------------------------------
  41
  42 The best way to handle host keys is to use the monkeysphere ssh proxy
  43 command.  This command will make sure the known_hosts file is
  44 up-to-date for the host you are connecting to with ssh.  The best way
  45 to integrate this is to add the following line to the "Host *" section
  46 of your ~/.ssh/config file:
  47
  48 ProxyCommand monkeysphere-ssh-proxycommand %h %p
  49
  50 The "Host *" section specifies what ssh options to use for all
  51 connections. If you don't already have a "Host *" line, you can add it
  52 by entering:
  53
  54 Host *
  55
  56 On a line by itself. Add the ProxyCommand line just below it.
  57
  58 Once you've completed this step - you are half-way there. You will now
  59 be able to verify servers participating in the monkeysphere provided
  60 their keys have been signed by someone that you trust.
  61
  62 FIXME: We should setup a way for someone to download a test gpg key and
  63 then connect to a test server that is signed by this gpg key so users
  64 can establish that they are setup correctly.
  65
  66 The remaining steps will complete the second half: allow servers to
  67 verify you based on your OpenPGP key.
  68
  69 Setting up an OpenPGP authentication key
  70 ----------------------------------------
  71
  72 First things first: you'll need to create a new subkey for your
  73 current key, if you don't already have one.  If your OpenPGP key is
  74 keyid $GPGID, you can set up such a subkey relatively easily with:
  75
  76 $ monkeysphere gen-subkey $GPGID
  77
  78 Typically, you can find out what your keyid is by running:
  79
  80 gpg --list-secret-keys
  81
  82 The first line (starting with sec) will include your key length followed
  83 by the type of key (e.g. 1024D) followed by a slash and then your keyid.
  84
  85 Using your OpenPGP authentication key for SSH
  86 ---------------------------------------------
  87
  88 Once you have created a OpenPGP authentication key, you can feed it to
  89 your ssh agent by running seckey2sshagent (currently this is found in
  90 the src directory). Please run:
  91
  92 ./seckey2sshagent --help
  93
  94 And read the directions - particularly the part about being dropped into
  95 a gpg edit session. This is a work in progress!
  96
  97 NOTE: the current version of openpgp2ssh does *not* deal well with
  98 encrypted keys (as of 2008-07-26)
  99
 100 FIXME: using the key with a single session?
 101
 102 Miscellaneous
 103 -------------
 104
 105 Users can also maintain their own authorized_keys files, for users
 106 that would be logging into their accounts.  This is primarily useful
 107 for accounts on hosts that are not already systematically using the
 108 monkeysphere for user authentication.  If you're not sure whether this
 109 is the case for your host, ask your system administrator.
 110
 111 If you want to do this as a regular user, use the
 112 update-authorized_keys command:
 113
 114 $ monkeysphere update-authorized_keys
 115
 116 This command will take all the user IDs listed in the
 117 ~/.config/monkeysphere/authorized_user_ids file and check to see if
 118 there are acceptable keys for those user IDs available.  If so, they
 119 will be added to the ~/.ssh/authorized_keys file.
 120
 121 You must have indicated reasonable ownertrust in some key for this
 122 account, or no keys will be found with trusted certification paths.
 123
 124 If you find this useful, you might want to place a job like this in
 125 your crontab so that revocations and rekeyings can take place
 126 automatically.