add some documentation to the user section about establishing trust
[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 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 Keeping your `known_hosts` file in sync with your keyring
25 -----------------------------------------------------------
26
27 With your keyring updated, you want to make sure that OpenSSH can
28 still see the most recent trusted information about who the various
29 hosts are.  This can be done with the monkeysphere-ssh-proxycommand
30 (see next section) or with the `update-known_hosts` command:
31
32         $ monkeysphere update-known_hosts
33
34 This command will check to see if there is an OpenPGP key for each
35 (non-hashed) host listed in the `known_hosts` file, and then add the
36 key for that host to the `known_hosts` file if one is found.  This
37 command could be added to a crontab as well, if desired.
38
39
40 Using `monkeysphere-ssh-proxycommand`(1)
41 ----------------------------------------
42
43 The best way to handle host keys is to use the monkeysphere ssh proxy
44 command.  This command will make sure the `known_hosts` file is
45 up-to-date for the host you are connecting to with ssh.  The best way
46 to integrate this is to add the following line to the "Host *" section
47 of your `~/.ssh/config` file:
48
49         ProxyCommand monkeysphere-ssh-proxycommand %h %p
50
51 The "Host *" section specifies what ssh options to use for all
52 connections. If you don't already have a "Host *" line, you can add it
53 by entering:
54
55         Host *
56
57 On a line by itself. Add the ProxyCommand line just below it.
58
59 Once you've completed this step - you are half-way there. You will now
60 be able to verify servers participating in the monkeysphere provided
61 their keys have been signed by someone that you trust.
62
63 FIXME: We should setup a way for someone to download a test gpg key and
64 then connect to a test server that is signed by this gpg key so users
65 can establish that they are setup correctly.
66
67 The remaining steps will complete the second half: allowing servers to
68 verify you based on your OpenPGP key.
69
70
71 Setting up an OpenPGP authentication key
72 ----------------------------------------
73
74 First things first: you'll need to create an "authentication" subkey
75 for your current key, if you don't already have one.  If you already
76 have a GPG key, you can add an authentication subkey with:
77
78         $ monkeysphere gen-subkey
79
80 If you have more than one secret key, you'll need to specify the key
81 you want to add the subkey to on the command line.
82
83
84 Using your OpenPGP authentication key for SSH
85 ---------------------------------------------
86
87 Once you have created an OpenPGP authentication subkey, you will need
88 to feed it to your ssh agent.
89
90 Currently (2008-08-23), gnutls does not support this operation. In order
91 to take this step, you will need to upgrade to a patched version of
92 gnutls. You can easily upgrade a Debian system by adding the following
93 to `/etc/apt/sources.list.d/monkeysphere.list`:
94
95         deb http://archive.monkeysphere.info/debian experimental gnutls
96         deb-src http://archive.monkeysphere.info/debian experimental gnutls
97
98 Next, run `aptitude update; aptitude install libgnutls26`.
99
100 With the patched gnutls installed, you can feed your authentication
101 subkey to your ssh agent by running:
102
103         $ monkeysphere subkey-to-ssh-agent
104
105 FIXME: using the key with a single ssh connection?
106
107 Establish trust
108 ---------------
109
110 Now that you have the above setup, you will need to establish an
111 acceptable trust path to the admin(s) of a monkeysphere-enabled server
112 that you will be connecting to. You need to do this because the admin
113 is certifying the host, and you need a mechanism to validate that
114 certification. The only way to do that is by indicating who you trust
115 to certify hosts. This is a two step process: first you must sign the
116 key, and then you have to indicate a trust level.
117
118 The process of signing another key is outside the scope of this
119 document, however the gnupg README details the signing process and you
120 can find good [documentation
121 ](http://www.debian.org/events/keysigning) online detailing this
122 process.
123
124 If you have signed your admins' key, you need to denote some kind of
125 trust to that key. To do this you should edit the key and use the
126 'trust' command. For the Monkeysphere to trust the assertions that are
127 made about a host, you need full calculated validity to the host
128 certifiers. This can be done either by giving full trust to one
129 host-certifying key, or by giving marginal trust to three different
130 host-certifiers. In the following we demonstrate how to add full trust
131 validity to a host-certifying key:
132
133      $ gpg --edit-key <admin_keyid>
134      Command> trust
135      pub  2048R/3B757F8C  created: 2008-06-19  expires: 2008-11-16  usage: CA  
136                      trust: unknown       validity: full
137      [  unknown  ] (1). ssh://monkeysphere.info
138      [  unknown  ] (2)  ssh://george.riseup.net
139
140      Please decide how far you trust this user to correctly verify other users' keys
141      (by looking at passports, checking fingerprints from different sources, etc.)
142
143        1 = I don't know or won't say
144        2 = I do NOT trust
145        3 = I trust marginally
146        4 = I trust fully
147        5 = I trust ultimately
148        m = back to the main menu
149
150        Your decision? 4 
151
152 Note: Due to a limitation with gnupg, it is not currently possible to
153 limit the domain scope properly, which means that if you fully trust
154 an admin, this admin can currently assert host verification for any
155 hosts.
156
157 Because the Monkeysphre relies on GPG's definition of the OpenPGP web
158 of trust, it is important to understand [how GPG calculates User ID
159 validity for a key](/trust-models).
160
161
162 Miscellaneous
163 -------------
164
165 Users can also maintain their own `~/.ssh/authorized_keys` files with
166 the Monkeysphere.  This is primarily useful for accounts on hosts that
167 are not already systematically using the Monkeysphere for user
168 authentication.  If you're not sure whether this is the case for your
169 host, ask your system administrator.
170
171 If you want to do this as a regular user, use the
172 `update-authorized_keys` command:
173
174         $ monkeysphere update-authorized_keys
175
176 This command will take all the user IDs listed in the
177 `~/.monkeysphere/authorized_user_ids` file and check to see if
178 there are acceptable keys for those user IDs available.  If so, they
179 will be added to the `~/.ssh/authorized_keys` file.
180
181 You must have indicated reasonable ownertrust in some key for this
182 account, or no keys will be found with trusted certification paths.
183
184 If you find this useful, you might want to place this command in your
185 crontab so that revocations and rekeyings can take place
186 automatically.