summaryrefslogtreecommitdiff
path: root/doc/README
blob: cf2f3968bef556806ca9566c340f88dc383e4555 (plain)
  1. Monkeysphere User README
  2. ========================
  3. You don't have to be an OpenSSH or OpenPGP expert to use the
  4. Monkeysphere. However, you should be comfortable using secure shell and
  5. you should already have GnuPG installed and an OpenPGP key pair before
  6. you begin.
  7. As a regular user on a system where the monkeysphere package is
  8. installed, you probably want to do a few things:
  9. Keeping your keyring up-to-date
  10. -------------------------------
  11. Regularly refresh your GnuPG keyring from the keyservers. This can be
  12. done with a simple cronjob. An example of crontab line to do this is:
  13. 0 12 * * * /usr/bin/gpg --refresh-keys > /dev/null 2>&1
  14. This would refresh your keychain every day at noon.
  15. Keeping your known_hosts file in sync with your keyring
  16. -------------------------------------------------------
  17. With your keyring updated, you want to make sure that OpenSSH can
  18. still see the most recent trusted information about who the various
  19. hosts are. This can be done with the monkeysphere-ssh-proxycommand
  20. (see next section) or with the update-known_hosts command:
  21. $ monkeysphere update-known_hosts
  22. This will command will check to see if there is an OpenPGP key for
  23. each (non-hashed) host listed in the known_hosts file, and then add
  24. the key for that host to the known_hosts file if one is found. This
  25. command could be added to a crontab as well, if desired.
  26. Using monkeysphere-ssh-proxycommand(1)
  27. --------------------------------------
  28. The best way to handle host keys is to use the monkeysphere ssh proxy
  29. command. This command will make sure the known_hosts file is
  30. up-to-date for the host you are connecting to with ssh. The best way
  31. to integrate this is to add the following line to the "Host *" section
  32. of your ~/.ssh/config file:
  33. ProxyCommand monkeysphere-ssh-proxycommand %h %p
  34. The "Host *" section specifies what ssh options to use for all
  35. connections. If you don't already have a "Host *" line, you can add it
  36. by entering:
  37. Host *
  38. On a line by itself. Add the ProxyCommand line just below it.
  39. Once you've completed this step - you are half-way there. You will now
  40. be able to verify servers participating in the monkeysphere provided
  41. their keys have been signed by someone that you trust.
  42. FIXME: We should setup a way for someone to download a test gpg key and
  43. then connect to a test server that is signed by this gpg key so users
  44. can establish that they are setup correctly.
  45. The remaining steps will complete the second half: allow servers to
  46. verify you based on your OpenPGP key.
  47. Setting up an OpenPGP authentication key
  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. $ monkeysphere gen-subkey $GPGID
  53. Typically, you can find out what your keyid is by running:
  54. gpg --list-secret-keys
  55. The first line (starting with sec) will include your key length followed
  56. by the type of key (e.g. 1024D) followed by a slash and then your keyid.
  57. Using your OpenPGP authentication key for SSH
  58. ---------------------------------------------
  59. Once you have created a OpenPGP authentication key, you can feed it to
  60. your ssh agent by running seckey2sshagent (currently this is found in
  61. the src directory). Please run:
  62. ./seckey2sshagent --help
  63. And read the directions - particularly the part about being dropped into
  64. a gpg edit session. This is a work in progress!
  65. NOTE: the current version of openpgp2ssh does *not* deal well with
  66. encrypted keys (as of 2008-07-26)
  67. FIXME: using the key with a single session?
  68. Miscellaneous
  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. If you want to do this as a regular user, use the
  76. update-authorized_keys command:
  77. $ monkeysphere update-authorized_keys
  78. This command will take all the user IDs listed in the
  79. ~/.config/monkeysphere/authorized_user_ids file and check to see if
  80. there are acceptable keys for those user IDs available. If so, they
  81. will be added to the ~/.ssh/authorized_keys file.
  82. You must have indicated reasonable ownertrust in some key for this
  83. account, or no keys will be found with trusted certification paths.
  84. If you find this useful, you might want to place a job like this in
  85. your crontab so that revocations and rekeyings can take place
  86. automatically.