1 Monkeysphere Server Administrator README
2 ========================================
4 As the administrator of an SSH server, you can take advantage of the
5 Monkeysphere in two ways:
7 1. you can publish the host key of your machine to the Web of Trust
8 (WoT) so that your users can automatically verify it, and
10 2. you can set up your machine to automatically identify connecting
11 users by their presence in the OpenPGP Web of Trust.
13 These two pieces are independent: you can do one without the other.
15 Monkeysphere for host verification (monkeysphere-host)
16 ======================================================
18 Server host key publication
19 ---------------------------
21 To begin, you must first import an ssh host key. This assumes that
22 you have the ssh server installed, and that you have generated a host
23 RSA key. Once that has been done, import the key:
25 # monkeysphere-host import-key /etc/ssh/ssh_host_rsa_key
27 This will generate an OpenPGP certificate for the server. The primary
28 user ID for this certificate will be the ssh service URI for the host,
29 which by default is based on the output of `hostname -f`
30 (eg. `ssh://server.example.net`). If the name determined from
31 `hostname -f` is not the name you want to have in the service URI,
32 then you can provide one manually:
34 # monkeysphere-host import-key /etc/ssh/ssh_host_rsa_key host.example.net
36 The hostname you provide should probably be a fully qualified domain
37 name for the host in order for your users to find it.
39 Now you can display information about the host key's certificate with
40 the 'show-key' command:
42 # monkeysphere-host show-key
44 Once the host key's certificate has been generated, you'll probably
45 want to publish it to the public keyservers which distribute the Web
48 # monkeysphere-host publish-key
50 But anyone could publish a simple self-signed certificate to the WoT
51 with any name attached. Your users should be able to tell that
52 someone they know and trust with the machine (e.g. *you*, the
53 administrator) has verified that this particular key is indeed the
54 correct key. So your next step is to sign the host's key with your
57 On your (the admin's) local machine retrieve the host key (it may take
58 several minutes for the key to propagate across the keyserver
59 network), and sign it:
61 $ gpg --search '=ssh://server.example.net'
62 $ gpg --sign-key '=ssh://server.example.net'
64 Make sure you compare the fingerprint of the retrieved certificate
65 with the output from the 'show-key' command above!
67 Finally, publish your signatures back to the keyservers, so that your
68 users can automatically verify your machine when they connect:
70 $ gpg --send-key '=ssh://server.example.net'
72 See http://web.monkeysphere.info/signing-host-keys/ for more info
75 Monkeysphere for user authentication (monkeysphere-authentication)
76 ==================================================================
78 A host can maintain ssh-style `authorized_keys` files automatically
79 for its users with the Monkeysphere. This frees you (the
80 administrator) from the task of manually checking/placing SSH keys,
81 and enables users to do relatively painless key transitions, and to
82 quickly and universally revoke access if they find that their ssh key
83 has become compromised.
85 You simply tell the system what *person* (identified by her OpenPGP
86 User ID) should have access to an account, the Monkeysphere takes care
87 of generating the proper `authorized_keys` file and keeping it
88 up-to-date, and `sshd` reads the generated `authorized_keys` files
91 Monkeysphere authorized_keys maintenance
92 ----------------------------------------
94 For each user account on the server, the userids of people authorized
95 to log into that account would be placed in:
97 ~/.monkeysphere/authorized_user_ids
99 The server will use the Monkeysphere to look up matching OpenPGP
100 certificates, validate them, and generate an `authorized_keys` file.
102 To validate the OpenPGP certificates, the server needs to know who it
103 can trust to correctly identify users. The individuals trusted to
104 identify users like this are known in the Monkeysphere as "Identity
105 Certifiers". One obvious choice is to trust *you*, the administrator,
106 to be an Identity Certifier. If your OpenPGP keyid is `$GPGID`, then
107 run the following command on the server:
109 # monkeysphere-authentication add-identity-certifier $GPGID
111 You'll probably only set up Identity Certifiers when you set up the
112 machine. After that, you'll only need to add or remove Identity
113 Certifiers when the roster of admins on the machine changes, or when
114 one of the admins switches OpenPGP keys.
116 Now that the server knows who to trust to identify users, the
117 Monkeysphere can generate ssh-style `authorized_keys` quickly and
120 To update the Monkeysphere-generated `authorized_keys` file for user
123 # monkeysphere-authentication update-users bob
125 To update the monkeysphere `authorized_keys` file for all users on the
126 the system, run the same command with no arguments:
128 # monkeysphere-authentication update-users
130 You probably want to set up a regularly scheduled job (e.g. with cron)
131 to do this automatically.
133 Update OpenSSH server AuthorizedKeysFile configuration
134 ------------------------------------------------------
136 Generating the `authorized_keys` files is not quite enough, because
137 `sshd` needs to know where to find the generated keys.
139 You can do this by adding the following line to
140 `/etc/ssh/sshd_config`, commenting out any other `AuthorizedKeysFile`
143 AuthorizedKeysFile /var/lib/monkeysphere/authorized_keys/%u
145 You'll need to restart `sshd` to have your changes take effect. As
146 with any change to `sshd_config`, if you're doing this remotely, be
147 sure to retain an existing session to the machine while you test your
148 changes so you don't get locked out if something went wrong.