website/getting-started-user.mdwn

   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 each
  35 (non-hashed) host listed in the `known_hosts` file, and then add the
  36 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: allowing 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 an "authentication" subkey
  75 for your current key, if you don't already have one.  If you already
  76 have a GPG key, you can add an authentication subkey with:
  77
  78         $ monkeysphere gen-subkey
  79
  80 If you have more than one secret key, you'll need to specify the key
  81 you want to add the subkey to on the command line.
  82
  83
  84 Using your OpenPGP authentication key for SSH
  85 ---------------------------------------------
  86
  87 Once you have created an OpenPGP authentication subkey, you will need
  88 to feed it to your ssh agent.
  89
  90 Currently (2008-08-23), gnutls does not support this operation. In order
  91 to take this step, you will need to upgrade to a patched version of
  92 gnutls. You can easily upgrade a Debian system by adding the following
  93 to `/etc/apt/sources.list.d/monkeysphere.list`:
  94
  95         deb http://archive.monkeysphere.info/debian experimental gnutls
  96         deb-src http://archive.monkeysphere.info/debian experimental gnutls
  97
  98 Next, run `aptitude update; aptitude install libgnutls26`.
  99
 100 With the patched gnutls installed, you can feed your authentication
 101 subkey to your ssh agent by running:
 102
 103         $ monkeysphere subkey-to-ssh-agent
 104
 105 FIXME: using the key with a single ssh connection?
 106
 107 Establish trust
 108 ---------------
 109
 110 Now that you have the above setup, you will need to establish an
 111 acceptable trust path to the admin(s) of a monkeysphere-enabled server
 112 that you will be connecting to. You need to do this because the admin
 113 is certifying the host, and you need a mechanism to validate that
 114 certification. The only way to do that is by indicating who you trust
 115 to certify hosts. This is a two step process: first you must sign the
 116 key, and then you have to indicate a trust level.
 117
 118 The process of signing another key is outside the scope of this
 119 document, however the [gnupg
 120 README](http://cvs.gnupg.org/cgi-bin/viewcvs.cgi/branches/STABLE-BRANCH-1-4/README?root=GnuPG&view=markup)
 121 details the signing process and you can find good [documentation
 122 ](http://www.debian.org/events/keysigning) online detailing this
 123 process.
 124
 125 If you have signed your admins' key, you need to denote some kind of
 126 trust to that key. To do this you should edit the key and use the
 127 'trust' command. For the Monkeysphere to trust the assertions that are
 128 made about a host, you need full calculated validity to the host
 129 certifiers. This can be done either by giving full trust to one
 130 host-certifying key, or by giving marginal trust to three different
 131 host-certifiers. In the following we demonstrate how to add full trust
 132 validity to a host-certifying key:
 133
 134
 135         $ gpg --edit-key 'Jane Admin'
 136         gpg (GnuPG) 1.4.9; Copyright (C) 2008 Free Software Foundation, Inc.
 137         This is free software: you are free to change and redistribute it.
 138         There is NO WARRANTY, to the extent permitted by law.
 139
 140
 141         pub  4096R/ABCD123A  created: 2007-06-02  expires: 2012-05-31  usage: SC
 142                              trust: unknown       validity: full
 143         sub  2048R/01DECAF7  created: 2007-06-02  expires: 2012-05-31  usage: E
 144         [  full  ] (1). Jane Admin <jane_admin@example.net>
 145
 146         Command> trust
 147         pub  4096R/ABCD123A  created: 2007-06-02  expires: 2012-05-31  usage: SC
 148                              trust: unknown       validity: full
 149         sub  2048R/01DECAF7  created: 2007-06-02  expires: 2012-05-31  usage: E
 150         [  full  ] (1). Jane Admin <jane_admin@example.net>
 151
 152         Please decide how far you trust this user to correctly verify other users' keys
 153         (by looking at passports, checking fingerprints from different sources, etc.)
 154
 155           1 = I don't know or won't say
 156           2 = I do NOT trust
 157           3 = I trust marginally
 158           4 = I trust fully
 159           5 = I trust ultimately
 160           m = back to the main menu
 161
 162         Your decision? 4
 163
 164         pub  4096R/ABCD123A  created: 2007-06-02  expires: 2012-05-31  usage: SC
 165                              trust: full          validity: full
 166         sub  2048R/01DECAF7  created: 2007-06-02  expires: 2012-05-31  usage: E
 167         [  full  ] (1). Jane Admin <jane_admin@example.net>
 168         Please note that the shown key validity is not necessarily correct
 169         unless you restart the program.
 170
 171         Command> save
 172         Key not changed so no update needed.
 173         $
 174
 175 Note: Due to a limitation with gnupg, it is not currently possible to
 176 limit the domain scope properly, which means that if you fully trust
 177 an admin, you'll trust all their certifications.
 178
 179 Because the Monkeysphre relies on GPG's definition of the OpenPGP web
 180 of trust, it is important to understand [how GPG calculates User ID
 181 validity for a key](/trust-models).
 182
 183
 184 Miscellaneous
 185 -------------
 186
 187 Users can also maintain their own `~/.ssh/authorized_keys` files with
 188 the Monkeysphere.  This is primarily useful for accounts on hosts that
 189 are not already systematically using the Monkeysphere for user
 190 authentication.  If you're not sure whether this is the case for your
 191 host, ask your system administrator.
 192
 193 If you want to do this as a regular user, use the
 194 `update-authorized_keys` command:
 195
 196         $ monkeysphere update-authorized_keys
 197
 198 This command will take all the user IDs listed in the
 199 `~/.monkeysphere/authorized_user_ids` file and check to see if
 200 there are acceptable keys for those user IDs available.  If so, they
 201 will be added to the `~/.ssh/authorized_keys` file.
 202
 203 You must have indicated reasonable ownertrust in some key for this
 204 account, or no keys will be found with trusted certification paths.
 205
 206 If you find this useful, you might want to place this command in your
 207 crontab so that revocations and rekeyings can take place
 208 automatically.