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-keyservers.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:
  99
 100         $ monkeysphere subkey-to-ssh-agent
 101
 102 You can supply normal ssh-add(1) flags to this command if you want to
 103 give the agent different instructions.  For example, if you want the
 104 agent to always ask for confirmation before using this key, you should
 105 do this instead:
 106
 107         $ monkeysphere subkey-to-ssh-agent -c
 108
 109 You can verify that the key is in the agent just as you normally
 110 would:
 111
 112         $ ssh-add -l
 113
 114 Now you can connect to hosts that use the monkeysphere for user
 115 authentication using that key:
 116
 117         $ ssh server.example.net
 118
 119
 120 Using your OpenPGP authentication key for SSH without the agent
 121 ---------------------------------------------------------------
 122
 123 Currently, the monkeysphere does not support using your SSH subkey
 124 without the ssh-agent :( It's not impossible, we just haven't gotten
 125 around to it yet.  Patches are welcome!
 126
 127 If you are not running an agent, and you just want a single session
 128 with the key, you could cobble something together a one-shot agent
 129 like this:
 130
 131         $ ssh-agent sh -c 'monkeysphere subkey-to-ssh-agent && ssh server.example.net'
 132
 133 Maintenance
 134 ===========
 135
 136 As a regular user of the monkeysphere, you probably want to do a few
 137 things to make sure that you get automatically notified of any
 138 re-keyings or revocation of monkeysphere-enabled hosts, and that your
 139 keys are properly managed.
 140
 141
 142 Keep your keyring up-to-date
 143 ----------------------------
 144
 145 Regularly refresh your GnuPG keyring from the keyservers.  This can be
 146 done with a simple cronjob.  An example of crontab line to do this is:
 147
 148         0 12 * * * /usr/bin/gpg --refresh-keys > /dev/null 2>&1
 149
 150 This would refresh your keychain every day at noon.
 151
 152
 153 Keep your SSH identity up-to-date
 154 ---------------------------------
 155
 156 If your SSH identity or your whole OpenPGP keyring is compromised, you
 157 should be sure to revoke it and publish the revocations to the
 158 keyserver.  If only your SSH identity was compromised, you should just
 159 revoke the authentication subkey.  For keys with small sizes, or which
 160 may have been otherwise compromised, you may wish to simply revoke the
 161 old authentication subkey, add a new one, and publish those changes to
 162 the public keyservers together.
 163
 164 Many people believe that it is good security practice to only use
 165 asymmetric keys (such as the RSA keys used by SSH and the
 166 Monkeysphere) for a limited period of time, and prefer to transition
 167 from key to key every year or two.
 168
 169 Without the monkeysphere, you would have needed to update your
 170 `authorized_keys` file on every host you connect to in order to effect
 171 such a transition.  But all hosts that use the Monkeysphere to
 172 generate their authorized keys files will transition automatically to
 173 your new key, if you publish/revoke as described above.
 174
 175
 176 For those who want more
 177 =======================
 178
 179 More documentation and details are available on the web at:
 180
 181  http://web.monkeysphere.info/