1 Monkeysphere User README
2 ========================
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
9 As a regular user on a system where the monkeysphere package is
10 installed, you probably want to do a few things:
13 Keep your keyring up-to-date
14 ----------------------------
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:
19 0 12 * * * /usr/bin/gpg --refresh-keys > /dev/null 2>&1
21 This would refresh your keychain every day at noon.
24 Install the monkeysphere software on your system
25 ------------------------------------------------
27 If you haven't installed monkeysphere yet, you will need to [download
28 and install](/download) before continuing.
30 Make sure that you have the GnuTLS library version 2.6 or later
31 installed on your system. If you can't (or don't want to) upgrade to
32 GnuTLS 2.6 or later, there are patches for GnuTLS 2.4 available in
33 [the Monkeysphere git repo](/community).
36 Keeping your `known_hosts` file in sync with your keyring
37 ---------------------------------------------------------
39 With your keyring updated, you want to make sure that OpenSSH can
40 still see the most recent trusted information about who the various
41 hosts are. This can be done with the monkeysphere-ssh-proxycommand
42 (see next section) or with the `update-known_hosts` command:
44 $ monkeysphere update-known_hosts
46 This command will check to see if there is an OpenPGP key for each
47 (non-hashed) host listed in the `known_hosts` file, and then add the
48 key for that host to the `known_hosts` file if one is found. This
49 command could be added to a crontab as well, if desired.
52 Using `monkeysphere-ssh-proxycommand`(1)
53 ----------------------------------------
55 The best way to handle host keys is to use the monkeysphere ssh proxy
56 command. This command will make sure the `known_hosts` file is
57 up-to-date for the host you are connecting to with ssh. The best way
58 to integrate this is to add the following line to the "Host *" section
59 of your `~/.ssh/config` file:
61 ProxyCommand monkeysphere ssh-proxycommand %h %p
63 The "Host *" section specifies what ssh options to use for all
64 connections. If you don't already have a "Host *" line, you can add it
69 On a line by itself. Add the ProxyCommand line just below it.
71 Once you've completed this step - you are half-way there. You will now
72 be able to verify servers participating in the monkeysphere provided
73 their keys have been signed by someone that you trust.
75 FIXME: We should setup a way for someone to download a test gpg key and
76 then connect to a test server that is signed by this gpg key so users
77 can establish that they are setup correctly.
79 The remaining steps will complete the second half: allowing servers to
80 verify you based on your OpenPGP key.
83 Setting up an OpenPGP authentication key
84 ----------------------------------------
86 First things first: you'll need to have a OpenPGP "authentication"
87 subkey for your current key, if you don't already have one. If you
88 already have a GPG key, you can generate an authentication subkey with
89 the `gen-subkey` command:
91 $ monkeysphere gen-subkey
93 If you have more than one secret key, you'll need to specify the key
94 you want to add the subkey to on the command line. It have already
95 have an ssh pub key that you use regularly, you can import this key
96 into GPG with the `import-subkey` command:
98 $ monkeysphere import-subkey ~/.ssh/id_rsa
101 Using your OpenPGP authentication key for SSH
102 ---------------------------------------------
104 Once you have created an OpenPGP authentication subkey, you will need
105 to feed it to your ssh agent.
107 The GnuTLS library supports this operation as of version 2.6, but
108 earlier versions do not. With a recent version of GnuTLS installed,
109 you can feed your authentication subkey to your ssh agent by running:
111 $ monkeysphere subkey-to-ssh-agent
113 FIXME: using the key with a single ssh connection?
119 Now that you have the above setup, you will need to establish an
120 acceptable trust path to the admin(s) of a monkeysphere-enabled server
121 that you will be connecting to. You need to do this because the admin
122 is certifying the host, and you need a mechanism to validate that
123 certification. The only way to do that is by indicating who you trust
124 to certify hosts. This is a two step process: first you must sign the
125 key, and then you have to indicate a trust level.
127 The process of signing another key is outside the scope of this
128 document, however the [gnupg
129 README](http://cvs.gnupg.org/cgi-bin/viewcvs.cgi/branches/STABLE-BRANCH-1-4/README?root=GnuPG&view=markup)
130 details the signing process and you can find good [documentation
131 ](http://www.debian.org/events/keysigning) online detailing this
134 If you have signed your admins' key, you need to denote some kind of
135 trust to that key. To do this you should edit the key and use the
136 'trust' command. For the Monkeysphere to trust the assertions that are
137 made about a host, you need full calculated validity to the host
138 certifiers. This can be done either by giving full trust to one
139 host-certifying key, or by giving marginal trust to three different
140 host-certifiers. In the following we demonstrate how to add full trust
141 validity to a host-certifying key:
144 $ gpg --edit-key 'Jane Admin'
145 gpg (GnuPG) 1.4.9; Copyright (C) 2008 Free Software Foundation, Inc.
146 This is free software: you are free to change and redistribute it.
147 There is NO WARRANTY, to the extent permitted by law.
150 pub 4096R/ABCD123A created: 2007-06-02 expires: 2012-05-31 usage: SC
151 trust: unknown validity: full
152 sub 2048R/01DECAF7 created: 2007-06-02 expires: 2012-05-31 usage: E
153 [ full ] (1). Jane Admin <jane_admin@example.net>
156 pub 4096R/ABCD123A created: 2007-06-02 expires: 2012-05-31 usage: SC
157 trust: unknown validity: full
158 sub 2048R/01DECAF7 created: 2007-06-02 expires: 2012-05-31 usage: E
159 [ full ] (1). Jane Admin <jane_admin@example.net>
161 Please decide how far you trust this user to correctly verify other users' keys
162 (by looking at passports, checking fingerprints from different sources, etc.)
164 1 = I don't know or won't say
166 3 = I trust marginally
168 5 = I trust ultimately
169 m = back to the main menu
173 pub 4096R/ABCD123A created: 2007-06-02 expires: 2012-05-31 usage: SC
174 trust: full validity: full
175 sub 2048R/01DECAF7 created: 2007-06-02 expires: 2012-05-31 usage: E
176 [ full ] (1). Jane Admin <jane_admin@example.net>
177 Please note that the shown key validity is not necessarily correct
178 unless you restart the program.
181 Key not changed so no update needed.
184 Note: Due to a limitation with gnupg, it is not currently possible to
185 limit the domain scope properly, which means that if you fully trust
186 an admin, you'll trust all their certifications.
188 Because the Monkeysphre relies on GPG's definition of the OpenPGP web
189 of trust, it is important to understand [how GPG calculates User ID
190 validity for a key](/trust-models).
196 Users can also maintain their own `~/.ssh/authorized_keys` files with
197 the Monkeysphere. This is primarily useful for accounts on hosts that
198 are not already systematically using the Monkeysphere for user
199 authentication. If you're not sure whether this is the case for your
200 host, ask your system administrator.
202 If you want to do this as a regular user, use the
203 `update-authorized_keys` command:
205 $ monkeysphere update-authorized_keys
207 This command will take all the user IDs listed in the
208 `~/.monkeysphere/authorized_user_ids` file and check to see if
209 there are acceptable keys for those user IDs available. If so, they
210 will be added to the `~/.ssh/authorized_keys` file.
212 You must have indicated reasonable ownertrust in some key for this
213 account, or no keys will be found with trusted certification paths.
215 If you find this useful, you might want to place this command in your
216 crontab so that revocations and rekeyings can take place