Add "true" to prerm script so that lintian will stop complaining that
[monkeysphere.git] / 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/