1MONKEYSPHERE-HOST(8) System Commands MONKEYSPHERE-HOST(8)
2
6 monkeysphere-host - Monkeysphere host key administration tool.
7
10 monkeysphere-host subcommand [args]
11
14 Monkeysphere is a framework to leverage the OpenPGP web of trust for
15 SSH and TLS key-based authentication.
16 monkeysphere-host stores and manages OpenPGP certificates for various
18 services offered by the host.
19 Most subcommands take a KEYID argument, which identifies (by OpenPGP
21 key ID (e.g. 0xDEADBEEF) or full OpenPGP fingerprint) which certificate
22 is to be operated upon. If only one certificate is currently managed
23 by monkeysphere-host, the KEYID argument may be omitted, and monkey‐
24 sphere-host will operate on it.
25
28 monkeysphere-host takes various subcommands:
29 import-key FILE SCHEME://HOSTNAME[:PORT]
31 Import a PEM-encoded host secret key from file FILE. If FILE is
32 `-', then the key will be imported from stdin. Only RSA keys
33 are supported at the moment. SCHEME://HOSTNAME[:PORT] is used
34 to specify the scheme (e.g. ssh or https), fully-qualified host‐
35 name (and port) used in the user ID of the new OpenPGP key (e.g.
36 ssh://example.net or https://www.example.net). If PORT is not
37 specified, then no port is added to the user ID, which means the
38 default port for that service (e.g. 22 for ssh) is assumed. `i'
39 may be used in place of `import-key'.
40 show-keys [KEYID ...]
42 Output information about the OpenPGP certificate(s) for services
43 offered by the host, including their KEYIDs. If no KEYID is
44 specified (or if the special string `--all' is used), output
45 information about all certificates managed by monkeysphere-host.
46 `s' may be used in place of `show-keys'.
47 set-expire EXPIRE [KEYID]
49 Extend the validity of the OpenPGP certificate specified until
50 EXPIRE from the present. Expiration is specified as with GnuPG
51 (measured from today's date):
52 0 = key does not expire
53 <n> = key expires in n days
54 <n>w = key expires in n weeks
55 <n>m = key expires in n months
56 <n>y = key expires in n years
57 `e' may be used in place of `set-expire'.
58 add-servicename SCHEME://HOSTNAME[:PORT] [KEYID]
60 Add a service-specific user ID to the specified certificate.
61 For example, the operator of `https://example.net' may wish to
62 add an additional servicename of `https://www.example.net' to
63 the certificate corresponding to the secret key used by the
64 TLS-enabled web server. `add-name' or `n+' may be used in place
65 of `add-servicename'.
66 revoke-servicename SCHEME://HOSTNAME[:PORT] [KEYID]
68 Revoke a service-specific user ID from the specified certifi‐
69 cate. `revoke-name' or `n-' may be used in place of
70 `revoke-servicename'.
71 add-revoker REVOKER_KEYID|FILE [KEYID]
73 Add a revoker to the specified OpenPGP certificate. The revoker
74 can be specified by their own REVOKER_KEYID (in which case it
75 will be loaded from an OpenPGP keyserver), or by specifying a
76 path to a file containing the revoker's OpenPGP certificate, or
77 by specifying `-' to load from stdin. `r+' may be be used in
78 place of `add-revoker'.
79 revoke-key [KEYID]
81 Generate (with the option to publish) a revocation certificate
82 for given OpenPGP certificate. If such a certificate is pub‐
83 lished, the given key will be permanently revoked, and will no
84 longer be accepted by monkeysphere-enabled clients. This sub‐
85 command will ask you a series of questions, and then generate a
86 key revocation certificate, sending it to stdout. You might
87 want to store these certificates safely offline, to publish in
88 case of compromise). If you explicitly tell it to publish the
89 revocation certificate immediately, it will send it to the pub‐
90 lic keyservers. PUBLISH THESE CERTIFICATES ONLY IF YOU ARE SURE
91 THE CORRESPONDING KEY WILL NEVER BE RE-USED!
92 publish-keys [KEYID ...]
94 Publish the specified OpenPGP certificates to the public key‐
95 servers. If the special string `--all' is specified, all of the
96 host's OpenPGP certificates will be published. `p' may be used
97 in place of `publish-keys'. NOTE: that there is no way to
98 remove a key from the public keyservers once it is published!
99 version
101 Show the monkeysphere version number. `v' may be used in place
102 of `version'.
103 help Output a brief usage summary. `h' or `?' may be used in place
105 of `help'.
106 diagnostics
108 Review the state of the monkeysphere server host key and report
109 on suggested changes. Among other checks, this includes making
110 sure there is a valid host key, that the key is not expired,
111 that the sshd configuration points to the right place, etc. `d'
112 may be used in place of `diagnostics'.
113
116 To enable users to verify your SSH host's key via the monkeysphere, an
117 OpenPGP certificate must be made out of the host's RSA ssh key, and the
118 certificate must be published to the Web of Trust. Certificate publi‐
119 cation is not done by default. The first step is to import the host's
120 ssh key into a monkeysphere-style OpenPGP certificate. This is done
121 with the import-key command. For example:
122 # monkeysphere-host import-key /etc/ssh/ssh_host_rsa_key
124 ssh://host.example.org
125 On most systems, sshd's RSA secret key is stored at
127 /etc/ssh/ssh_host_rsa_key.
128 See PUBLISHING AND CERTIFYING MONKEYSPHERE SERVICE CERTIFICATES for how
130 to make sure your users can verify the ssh service offered by your host
131 once the key is imported into monkeysphere-host.
132
135 You can set up your HTTPS-capable web server so that your users can
136 verify it via the monkeysphere, without changing your server's software
137 at all. You just need access to a (PEM-encoded) version of the
138 server's RSA secret key (most secret keys are already stored
139 PEM-encoded). The first step is to import the web server's key into a
140 monkeysphere-style OpenPGP certificate. This is done with the
141 import-key command. For example:
142 # monkeysphere-host import-key /etc/ssl/private/host.exam‐
144 ple.net-key.pem https://host.example.net
145 If you don't know where the web server's key is stored on your machine,
147 consult the configuration files for your web server. Debian-based sys‐
148 tems using the `ssl-cert' packages often have a default self-signed
149 certificate stored in `/etc/ssl/private/ssl-cert-snakeoil.key' ; if
150 you're using that key, your users are getting browser warnings about
151 it. You can keep using the same key, but help them use the OpenPGP WoT
152 to verify that it does belong to your web server by using something
153 like:
154 # monkeysphere-host import-key /etc/ssl/private/ssl-cert-snakeoil.key
156 https://$(hostname --fqdn)
157 If you offer multiple HTTPS websites using the same secret key, you
159 should add the additional website names with the `add-servicename' sub‐
160 command.
161 See PUBLISHING AND CERTIFYING MONKEYSPHERE SERVICE CERTIFICATES (the
163 next section) for how to make sure your users can verify the https ser‐
164 vice offered by your host once the key is imported and any extra site
165 names have been added. Note that you can add or remove additional ser‐
166 vicenames at any time, but you'll need to certify any new ones sepa‐
167 rately.
168
171 Once the host key has been imported, the corresponding certificate must
172 be published to the Web of Trust so that users can retrieve the cert
173 when connecting to the host. The host certificates are published to
174 the keyserver with the publish-key command:
175 $ monkeysphere-host publish-key --all
177 In order for users accessing the system to be able to identify the
179 host's service via the monkeysphere, at least one person (e.g. a server
180 admin) will need to sign the host's certificate. This is done using
181 standard OpenPGP keysigning techniques. Usually: pull the host's
182 OpenPGP certificate from the keyserver, verify and sign it, and then
183 re-publish your signature. More than one person can certify any cer‐
184 tificate. Please see http://web.monkeysphere.info/signing-host-keys/
185 for more information and details. Once an admin's signature is pub‐
186 lished, users accessing the host can use the certificate to validate
187 the host's key without having to manually check the host key's finger‐
188 print (in the case of ssh) or without seeing a nasty "security warning"
189 in their browsers (in the case of https).
190
193 Note that monkeysphere-host currently caches a copy of all imported
194 secret keys (stored in OpenPGP form for future manipulation) in
195 /var/lib/monkeysphere/host/secring.gpg. Cleartext backups of this file
196 could expose secret key material if not handled sensitively.
197
200 The following environment variables will override those specified in
201 the config file (defaults in parentheses):
202 MONKEYSPHERE_LOG_LEVEL
204 Set the log level. Can be SILENT, ERROR, INFO, VERBOSE, DEBUG,
205 in increasing order of verbosity. (INFO)
206 MONKEYSPHERE_KEYSERVER
208 OpenPGP keyserver to use. (pool.sks-keyservers.net)
209 MONKEYSPHERE_PROMPT
211 If set to `false', never prompt the user for confirmation.
212 (true)
213
216 /etc/monkeysphere/monkeysphere-host.conf
217 System monkeysphere-host config file.
218 /var/lib/monkeysphere/host_keys.pub.pgp
220 A world-readable copy of the host's OpenPGP certificates in
221 ASCII armored format. This includes the certificates (including
222 the public keys, servicename-based User IDs, and most recent
223 relevant self-signatures) corresponding to every key used by
224 Monkeysphere-enabled services on the host.
225 /var/lib/monkeysphere/host/
227 A locked directory (readable only by the superuser) containing
228 copies of all imported secret keys (this is the host's GNUPGHOME
229 directory).
230 /etc/monkeysphere/monkeysphere-host-x509-anchors.crt or
232 /etc/monkeysphere/monkeysphere-x509-anchors.crt
233 If monkeysphere-host is configured to query an hkps keyserver
234 for publish-keys, it will use X.509 Certificate Authority cer‐
235 tificates in this file to validate any X.509 certificates used
236 by the keyserver. If the monkeysphere-host-x509 file is
237 present, the monkeysphere-x509 file will be ignored.
238
241 This man page was written by: Jameson Rollins <jrollins@finestruc‐
242 ture.net>, Daniel Kahn Gillmor <dkg@fifthhorseman.net>, Matthew Goins
243 <mjgoins@openflows.com>
244
247 monkeysphere(1), monkeysphere(7), gpg(1), monkeysphere-authentica‐
248 tion(8), ssh(1), sshd(8)
249monkeysphere January 2010 MONKEYSPHERE-HOST(8)