doc/README

   1 Monkeysphere User README
   2 ========================
   3
   4 As a regular user on a system where the monkeysphere package is
   5 installed, you probably want to do a few things:
   6
   7 Keeping your keyring up-to-date
   8 -------------------------------
   9
  10 Regularly refresh your GnuPG keyring from the keyservers.  This can be
  11 done with a simple cronjob.  An example of crontab line to do this is:
  12
  13 0 12 * * * /usr/bin/gpg --refresh-keys
  14
  15 This would refresh your keychain every day at noon.
  16
  17
  18 Keeping your known_hosts file in sync with your keyring
  19 -------------------------------------------------------
  20
  21 With your keyring updated, you want to make sure that openssh can
  22 still see the most recent trusted information about who the various
  23 hosts are.  This can be done with the monkeysphere-ssh-proxycommand
  24 (see next section) or with the update-known_hosts command:
  25
  26 $ monkeysphere update-known_hosts
  27
  28 This will command will check to see if there is an openpgp key for
  29 each (non-hashed) host listed in the known_hosts file, and then add
  30 the key for that host to the known_hosts file if one is found.  This
  31 command could be added to a crontab as well, if desired.
  32
  33
  34 Using monkeysphere-ssh-proxycommand(1)
  35 --------------------------------------
  36
  37 The best way to handle host keys is to use the monkeysphere ssh proxy
  38 command.  This command will make sure the known_hosts file is
  39 up-to-date for the host you are connecting to with ssh.  The best way
  40 to integrate this is to add the following line to the "Host *" section
  41 of your ~/.ssh/config file:
  42
  43 ProxyCommand monkeysphere-ssh-proxycommand %h %p
  44
  45
  46 Setting up an OpenPGP authentication key
  47 ----------------------------------------
  48
  49 First things first: you'll need to create a new subkey for your
  50 current key, if you don't already have one.  If your OpenPGP key is
  51 keyid $GPGID, you can set up such a subkey relatively easily with:
  52
  53 $ monkeysphere gen-subkey $GPGID
  54
  55
  56 Using your OpenPGP authentication key for SSH
  57 ---------------------------------------------
  58
  59 FIXME: Sending the key to the ssh-agent?
  60
  61 FIXME: using the key with a single session?
  62
  63 NOTE: the current version of openpgp2ssh does *not* deal well with
  64 encrypted keys (as of 2008-07-26)
  65
  66
  67 Miscellaneous
  68 -------------
  69
  70 Users can also maintain their own authorized_keys files, for users
  71 that would be logging into their accounts.  This is primarily useful
  72 for accounts on hosts that are not already systematically using the
  73 monkeysphere for user authentication.  If you're not sure whether this
  74 is the case for your host, ask your system administrator.
  75
  76 If you want to do this as a regular user, use the
  77 update-authorized_keys command:
  78
  79 $ monkeysphere update-authorized_keys
  80
  81 This command will take all the user IDs listed in the
  82 ~/.config/monkeysphere/authorized_user_ids file and check to see if
  83 there are acceptable keys for those user IDs available.  If so, they
  84 will be added to the ~/.ssh/authorized_keys file.
  85
  86 You must have indicated reasonable ownertrust in some key for this
  87 account, or no keys will be found with trusted certification paths.
  88
  89 If you find this useful, you might want to place a job like this in
  90 your crontab so that revocations and rekeyings can take place
  91 automatically.