website/getting-started-user.mdwn

   1 Monkeysphere User README
   2 ========================
   3
   4         Note: This documentation is for Monkeysphere version 0.23 or later.
   5         If you are running a version prior to 0.23, we recommend that you upgrade.
   6
   7 You don't have to be an OpenSSH or OpenPGP expert to use the
   8 Monkeysphere.  However, you should be comfortable using secure shell
   9 (ssh), and you should already have an OpenPGP key before you begin.
  10
  11 As a user, the Monkeysphere lets you do two important things:
  12
  13 1. You can use the OpenPGP Web of Trust (WoT) to automatically verify
  14 the identity of hosts you connect to.
  15
  16 2. You can manage your own ssh identity on all Monkeysphere-enabled
  17 servers using the WoT.
  18
  19 These two features are independent: you can do one without the other.
  20
  21
  22 Identifying servers through the Web of Trust
  23 ============================================
  24
  25 The simplest way to identify servers through the Web of Trust is to
  26 tell `ssh` to use `monkeysphere ssh-proxycommand` to connect, instead
  27 of connecting to the remote host directly. This command will make sure
  28 the `known_hosts` file is up-to-date for the host you are connecting
  29 to with ssh.
  30
  31 You can try this out when connecting to a server which has published
  32 their host key to the monkeysphere with:
  33
  34         $ ssh -oProxyCommand='monkeysphere ssh-proxycommand %h %p' server.example.net
  35
  36 If you want to have `ssh` always do this, just add the following line
  37 to the "Host *" section of your `~/.ssh/config` file:
  38
  39         ProxyCommand monkeysphere ssh-proxycommand %h %p
  40
  41 The "Host *" section specifies what ssh options to use for all
  42 connections. If you don't already have a "Host \*" line, you can add it
  43 by entering:
  44
  45         Host *
  46
  47 On a line by itself. Add the ProxyCommand line just below it.
  48
  49 Note that the Monkeysphere will help you identify servers whose host
  50 keys are published in the WoT, and which are signed by people who you
  51 know and trust to identify such things!
  52
  53 If you aren't connected to your administrator(s) through the Web of
  54 Trust, you should talk to them and establish that relationship.  If
  55 you have already established that relationship, but a server's host
  56 key isn't published, you might suggest to your administrator that they
  57 publish it.
  58
  59
  60 Managing your SSH identity through the Web of Trust
  61 ===================================================
  62
  63 You've already got an OpenPGP identity in the Web of Trust.  But you
  64 probably don't currently use it to identify yourself to SSH servers.
  65
  66 To do that, you'll need to add an authentication-capable subkey to
  67 your OpenPGP identity.  You can do that with:
  68
  69         $ monkeysphere gen-subkey
  70
  71 If you have more than one secret key, you'll need to specify the key
  72 you want to add the subkey to on the command line.
  73
  74 Since this is a change to your key, you probably want to re-publish
  75 your key to the public keyservers.  If your key ID is $GPGID:
  76
  77         $ gpg --keyserver pool.sks-keysevers.net --send-key $GPGID
  78
  79 This way, remote services that use the monkeysphere for user
  80 authentication will know about your SSH identity.
  81
  82 You may need to wait a few minutes for your new key to propagate
  83 around the keyserver network, and another little while for any remote
  84 host running the monkeysphere to pick up the new subkey.
  85
  86
  87 Using your OpenPGP authentication key for SSH via ssh-agent(1)
  88 --------------------------------------------------------------
  89
  90 Once you have created an OpenPGP authentication subkey, you will need
  91 to feed it to your `ssh-agent`.  Your agent can then manage the key
  92 for all of your ssh sessions.
  93
  94 First make sure you have an agent running:
  95
  96         $ ssh-add -l
  97
  98 Then hand off the authentication subkey to the agent (Note: the GnuTLS
  99 library supports this operation as of version 2.6, but earlier
 100 versions do not):
 101
 102         $ monkeysphere subkey-to-ssh-agent
 103
 104 You can supply normal ssh-add(1) flags to this command if you want to
 105 give the agent different instructions.  For example, if you want the
 106 agent to always ask for confirmation before using this key, you should
 107 do this instead:
 108
 109         $ monkeysphere subkey-to-ssh-agent -c
 110
 111 You can verify that the key is in the agent just as you normally
 112 would:
 113
 114         $ ssh-add -l
 115
 116 Now you can connect to hosts that use the monkeysphere for user
 117 authentication using that key:
 118
 119         $ ssh server.example.net
 120
 121
 122 Using your OpenPGP authentication key for SSH without the agent
 123 ---------------------------------------------------------------
 124
 125 Currently, the monkeysphere does not support using your SSH subkey
 126 without the ssh-agent :( It's not impossible, we just haven't gotten
 127 around to it yet.  Patches are welcome!
 128
 129 If you are not running an agent, and you just want a single session
 130 with the key, you could cobble something together a one-shot agent
 131 like this:
 132
 133         $ ssh-agent sh -c 'monkeysphere subkey-to-ssh-agent && ssh server.example.net'
 134
 135 Maintenance
 136 ===========
 137
 138 As a regular user of the monkeysphere, you probably want to do a few
 139 things to make sure that you get automatically notified of any
 140 re-keyings or revocation of monkeysphere-enabled hosts, and that your
 141 keys are properly managed.
 142
 143
 144 Keep your keyring up-to-date
 145 ----------------------------
 146
 147 Regularly refresh your GnuPG keyring from the keyservers.  This can be
 148 done with a simple cronjob.  An example of crontab line to do this is:
 149
 150         0 12 * * * /usr/bin/gpg --refresh-keys > /dev/null 2>&1
 151
 152 This would refresh your keychain every day at noon.
 153
 154
 155 Keep your SSH identity up-to-date
 156 ---------------------------------
 157
 158 If your SSH identity or your whole OpenPGP keyring is compromised, you
 159 should be sure to revoke it and publish the revocations to the
 160 keyserver.  If only your SSH identity was compromised, you should just
 161 revoke the authentication subkey.  For keys with small sizes, or which
 162 may have been otherwise compromised, you may wish to simply revoke the
 163 old authentication subkey, add a new one, and publish those changes to
 164 the public keyservers together.
 165
 166 Many people believe that it is good security practice to only use
 167 asymmetric keys (such as the RSA keys used by SSH and the
 168 Monkeysphere) for a limited period of time, and prefer to transition
 169 from key to key every year or two.
 170
 171 Without the monkeysphere, you would have needed to update your
 172 `authorized_keys` file on every host you connect to in order to effect
 173 such a transition.  But all hosts that use the Monkeysphere to
 174 generate their authorized keys files will transition automatically to
 175 your new key, if you publish/revoke as described above.
 176
 177
 178 For those who want more
 179 =======================
 180
 181 More documentation and details are available on the web at:
 182
 183  http://web.monkeysphere.info/