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