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 Install the monkeysphere software on your system
  25 ------------------------------------------------
  26
  27 If you haven't installed monkeysphere yet, you will need to [download
  28 and install](/download) before continuing.
  29
  30 Make sure that you have the GnuTLS library version 2.6 or later
  31 installed on your system. If you can't (or don't want to) upgrade to
  32 GnuTLS 2.6 or later, there are patches for GnuTLS 2.4 available in
  33 [the Monkeysphere git repo](/community).
  34
  35
  36 Keeping your `known_hosts` file in sync with your keyring
  37 ---------------------------------------------------------
  38
  39 With your keyring updated, you want to make sure that OpenSSH can
  40 still see the most recent trusted information about who the various
  41 hosts are.  This can be done with the monkeysphere-ssh-proxycommand
  42 (see next section) or with the `update-known_hosts` command:
  43
  44         $ monkeysphere update-known_hosts
  45
  46 This command will check to see if there is an OpenPGP key for each
  47 (non-hashed) host listed in the `known_hosts` file, and then add the
  48 key for that host to the `known_hosts` file if one is found.  This
  49 command could be added to a crontab as well, if desired.
  50
  51
  52 Using `monkeysphere-ssh-proxycommand`(1)
  53 ----------------------------------------
  54
  55 The best way to handle host keys is to use the monkeysphere ssh proxy
  56 command.  This command will make sure the `known_hosts` file is
  57 up-to-date for the host you are connecting to with ssh.  The best way
  58 to integrate this is to add the following line to the "Host *" section
  59 of your `~/.ssh/config` file:
  60
  61         ProxyCommand monkeysphere ssh-proxycommand %h %p
  62
  63 The "Host *" section specifies what ssh options to use for all
  64 connections. If you don't already have a "Host *" line, you can add it
  65 by entering:
  66
  67         Host *
  68
  69 On a line by itself. Add the ProxyCommand line just below it.
  70
  71 Once you've completed this step - you are half-way there. You will now
  72 be able to verify servers participating in the monkeysphere provided
  73 their keys have been signed by someone that you trust.
  74
  75 FIXME: We should setup a way for someone to download a test gpg key and
  76 then connect to a test server that is signed by this gpg key so users
  77 can establish that they are setup correctly.
  78
  79 The remaining steps will complete the second half: allowing servers to
  80 verify you based on your OpenPGP key.
  81
  82
  83 Setting up an OpenPGP authentication key
  84 ----------------------------------------
  85
  86 First things first: you'll need to have a OpenPGP "authentication"
  87 subkey for your current key, if you don't already have one.  If you
  88 already have a GPG key, you can generate an authentication subkey with
  89 the `gen-subkey` command:
  90
  91         $ monkeysphere gen-subkey
  92
  93 If you have more than one secret key, you'll need to specify the key
  94 you want to add the subkey to on the command line.
  95
  96
  97 Using your OpenPGP authentication key for SSH
  98 ---------------------------------------------
  99
 100 Once you have created an OpenPGP authentication subkey, you will need
 101 to feed it to your ssh agent.
 102
 103 The GnuTLS library supports this operation as of version 2.6, but
 104 earlier versions do not.  With a recent version of GnuTLS installed,
 105 you can feed your authentication subkey to your ssh agent by running:
 106
 107         $ monkeysphere subkey-to-ssh-agent
 108
 109 FIXME: using the key with a single ssh connection?
 110
 111
 112 Establish trust
 113 ---------------
 114
 115 Now that you have the above setup, you will need to establish an
 116 acceptable trust path to the admin(s) of a monkeysphere-enabled server
 117 that you will be connecting to. You need to do this because the admin
 118 is certifying the host, and you need a mechanism to validate that
 119 certification. The only way to do that is by indicating who you trust
 120 to certify hosts. This is a two step process: first you must sign the
 121 key, and then you have to indicate a trust level.
 122
 123 The process of signing another key is outside the scope of this
 124 document, however the [gnupg
 125 README](http://cvs.gnupg.org/cgi-bin/viewcvs.cgi/branches/STABLE-BRANCH-1-4/README?root=GnuPG&view=markup)
 126 details the signing process and you can find good [documentation
 127 ](http://www.debian.org/events/keysigning) online detailing this
 128 process.
 129
 130 If you have signed your admins' key, you need to denote some kind of
 131 trust to that key. To do this you should edit the key and use the
 132 'trust' command. For the Monkeysphere to trust the assertions that are
 133 made about a host, you need full calculated validity to the host
 134 certifiers. This can be done either by giving full trust to one
 135 host-certifying key, or by giving marginal trust to three different
 136 host-certifiers. In the following we demonstrate how to add full trust
 137 validity to a host-certifying key:
 138
 139
 140         $ gpg --edit-key 'Jane Admin'
 141         gpg (GnuPG) 1.4.9; Copyright (C) 2008 Free Software Foundation, Inc.
 142         This is free software: you are free to change and redistribute it.
 143         There is NO WARRANTY, to the extent permitted by law.
 144
 145
 146         pub  4096R/ABCD123A  created: 2007-06-02  expires: 2012-05-31  usage: SC
 147                              trust: unknown       validity: full
 148         sub  2048R/01DECAF7  created: 2007-06-02  expires: 2012-05-31  usage: E
 149         [  full  ] (1). Jane Admin <jane_admin@example.net>
 150
 151         Command> trust
 152         pub  4096R/ABCD123A  created: 2007-06-02  expires: 2012-05-31  usage: SC
 153                              trust: unknown       validity: full
 154         sub  2048R/01DECAF7  created: 2007-06-02  expires: 2012-05-31  usage: E
 155         [  full  ] (1). Jane Admin <jane_admin@example.net>
 156
 157         Please decide how far you trust this user to correctly verify other users' keys
 158         (by looking at passports, checking fingerprints from different sources, etc.)
 159
 160           1 = I don't know or won't say
 161           2 = I do NOT trust
 162           3 = I trust marginally
 163           4 = I trust fully
 164           5 = I trust ultimately
 165           m = back to the main menu
 166
 167         Your decision? 4
 168
 169         pub  4096R/ABCD123A  created: 2007-06-02  expires: 2012-05-31  usage: SC
 170                              trust: full          validity: full
 171         sub  2048R/01DECAF7  created: 2007-06-02  expires: 2012-05-31  usage: E
 172         [  full  ] (1). Jane Admin <jane_admin@example.net>
 173         Please note that the shown key validity is not necessarily correct
 174         unless you restart the program.
 175
 176         Command> save
 177         Key not changed so no update needed.
 178         $
 179
 180 Note: Due to a limitation with gnupg, it is not currently possible to
 181 limit the domain scope properly, which means that if you fully trust
 182 an admin, you'll trust all their certifications.
 183
 184 Because the Monkeysphre relies on GPG's definition of the OpenPGP web
 185 of trust, it is important to understand [how GPG calculates User ID
 186 validity for a key](/trust-models).
 187
 188
 189 Miscellaneous
 190 -------------
 191
 192 Users can also maintain their own `~/.ssh/authorized_keys` files with
 193 the Monkeysphere.  This is primarily useful for accounts on hosts that
 194 are not already systematically using the Monkeysphere for user
 195 authentication.  If you're not sure whether this is the case for your
 196 host, ask your system administrator.
 197
 198 If you want to do this as a regular user, use the
 199 `update-authorized_keys` command:
 200
 201         $ monkeysphere update-authorized_keys
 202
 203 This command will take all the user IDs listed in the
 204 `~/.monkeysphere/authorized_user_ids` file and check to see if
 205 there are acceptable keys for those user IDs available.  If so, they
 206 will be added to the `~/.ssh/authorized_keys` file.
 207
 208 You must have indicated reasonable ownertrust in some key for this
 209 account, or no keys will be found with trusted certification paths.
 210
 211 If you find this useful, you might want to place this command in your
 212 crontab so that revocations and rekeyings can take place
 213 automatically.