Merge commit 'dkg/master'
[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 The GnuTLS library supports this operation as of version 2.6, but
91 earlier versions do not.  With a recent version of GnuTLS installed,
92 you can feed your authentication subkey to your ssh agent by running:
93
94         $ monkeysphere subkey-to-ssh-agent
95
96 If you can't (or don't want to) upgrade to GnuTLS 2.6 or later, there
97 are patches for GnuTLS 2.4 available in [the Monkeysphere git
98 repo](/community).
99
100 FIXME: using the key with a single ssh connection?
101
102 Establish trust
103 ---------------
104
105 Now that you have the above setup, you will need to establish an
106 acceptable trust path to the admin(s) of a monkeysphere-enabled server
107 that you will be connecting to. You need to do this because the admin
108 is certifying the host, and you need a mechanism to validate that
109 certification. The only way to do that is by indicating who you trust
110 to certify hosts. This is a two step process: first you must sign the
111 key, and then you have to indicate a trust level.
112
113 The process of signing another key is outside the scope of this
114 document, however the [gnupg
115 README](http://cvs.gnupg.org/cgi-bin/viewcvs.cgi/branches/STABLE-BRANCH-1-4/README?root=GnuPG&view=markup)
116 details the signing process and you can find good [documentation
117 ](http://www.debian.org/events/keysigning) online detailing this
118 process.
119
120 If you have signed your admins' key, you need to denote some kind of
121 trust to that key. To do this you should edit the key and use the
122 'trust' command. For the Monkeysphere to trust the assertions that are
123 made about a host, you need full calculated validity to the host
124 certifiers. This can be done either by giving full trust to one
125 host-certifying key, or by giving marginal trust to three different
126 host-certifiers. In the following we demonstrate how to add full trust
127 validity to a host-certifying key:
128         
129         
130         $ gpg --edit-key 'Jane Admin'
131         gpg (GnuPG) 1.4.9; Copyright (C) 2008 Free Software Foundation, Inc.
132         This is free software: you are free to change and redistribute it.
133         There is NO WARRANTY, to the extent permitted by law.
134         
135         
136         pub  4096R/ABCD123A  created: 2007-06-02  expires: 2012-05-31  usage: SC  
137                              trust: unknown       validity: full
138         sub  2048R/01DECAF7  created: 2007-06-02  expires: 2012-05-31  usage: E   
139         [  full  ] (1). Jane Admin <jane_admin@example.net>
140         
141         Command> trust
142         pub  4096R/ABCD123A  created: 2007-06-02  expires: 2012-05-31  usage: SC  
143                              trust: unknown       validity: full
144         sub  2048R/01DECAF7  created: 2007-06-02  expires: 2012-05-31  usage: E   
145         [  full  ] (1). Jane Admin <jane_admin@example.net>
146         
147         Please decide how far you trust this user to correctly verify other users' keys
148         (by looking at passports, checking fingerprints from different sources, etc.)
149         
150           1 = I don't know or won't say
151           2 = I do NOT trust
152           3 = I trust marginally
153           4 = I trust fully
154           5 = I trust ultimately
155           m = back to the main menu
156         
157         Your decision? 4
158         
159         pub  4096R/ABCD123A  created: 2007-06-02  expires: 2012-05-31  usage: SC  
160                              trust: full          validity: full
161         sub  2048R/01DECAF7  created: 2007-06-02  expires: 2012-05-31  usage: E   
162         [  full  ] (1). Jane Admin <jane_admin@example.net>
163         Please note that the shown key validity is not necessarily correct
164         unless you restart the program.
165         
166         Command> save
167         Key not changed so no update needed.
168         $ 
169
170 Note: Due to a limitation with gnupg, it is not currently possible to
171 limit the domain scope properly, which means that if you fully trust
172 an admin, you'll trust all their certifications.
173
174 Because the Monkeysphre relies on GPG's definition of the OpenPGP web
175 of trust, it is important to understand [how GPG calculates User ID
176 validity for a key](/trust-models).
177
178
179 Miscellaneous
180 -------------
181
182 Users can also maintain their own `~/.ssh/authorized_keys` files with
183 the Monkeysphere.  This is primarily useful for accounts on hosts that
184 are not already systematically using the Monkeysphere for user
185 authentication.  If you're not sure whether this is the case for your
186 host, ask your system administrator.
187
188 If you want to do this as a regular user, use the
189 `update-authorized_keys` command:
190
191         $ monkeysphere update-authorized_keys
192
193 This command will take all the user IDs listed in the
194 `~/.monkeysphere/authorized_user_ids` file and check to see if
195 there are acceptable keys for those user IDs available.  If so, they
196 will be added to the `~/.ssh/authorized_keys` file.
197
198 You must have indicated reasonable ownertrust in some key for this
199 account, or no keys will be found with trusted certification paths.
200
201 If you find this useful, you might want to place this command in your
202 crontab so that revocations and rekeyings can take place
203 automatically.