-.SH SETUP HOST AUTHENTICATION
-
-To enable host verification via the monkeysphere, the host's key must
-be published to the Web of Trust. This is not done by default. To
-publish the host key to the keyservers, run the following command:
-
-$ monkeysphere-host publish-key
-
-In order for users logging into the system to be able to identify the
-host via the monkeysphere, at least one person (e.g. a server admin)
-will need to sign the host's key. This is done using standard OpenPGP
-keysigning techniques, usually: pull the key from the keyserver,
-verify and sign the key, and then re-publish the signature. Once an
-admin's signature is published, users logging into the host can use it
-to validate the host's key.
+.SH SETUP SSH SERVER CERTIFICATES
+
+To enable users to verify your SSH host's key via the monkeysphere, an
+OpenPGP certificate must be made out of the host's RSA ssh key, and
+the certificate must be published to the Web of Trust. Certificate
+publication is not done by default. The first step is to import the
+host's ssh key into a monkeysphere\-style OpenPGP certificate. This
+is done with the import\-key command. For example:
+
+# monkeysphere\-host import\-key /etc/ssh/ssh_host_rsa_key ssh://host.example.org
+
+On most systems, sshd's RSA secret key is stored at
+/etc/ssh/ssh_host_rsa_key.
+
+See PUBLISHING AND CERTIFYING MONKEYSPHERE SERVICE CERTIFICATES for
+how to make sure your users can verify the ssh service offered by your
+host once the key is imported into \fBmonkeysphere\-host\fP.
+
+.SH SETUP WEB SERVER CERTIFICATES
+
+You can set up your HTTPS\-capable web server so that your users can
+verify it via the monkeysphere, without changing your server's
+software at all. You just need access to a (PEM\-encoded) version of
+the server's RSA secret key (most secret keys are already stored
+PEM\-encoded). The first step is to import the web server's key into
+a monkeysphere\-style OpenPGP certificate. This is done with the
+import\-key command. For example:
+
+# monkeysphere\-host import\-key /etc/ssl/private/host.example.net\-key.pem https://host.example.net
+
+If you don't know where the web server's key is stored on your
+machine, consult the configuration files for your web server.
+Debian\-based systems using the `ssl\-cert' packages often have a
+default self\-signed certificate stored in
+`/etc/ssl/private/ssl\-cert\-snakeoil.key' ; if you're using that key,
+your users are getting browser warnings about it. You can keep using
+the same key, but help them use the OpenPGP WoT to verify that it does
+belong to your web server by using something like:
+
+# monkeysphere\-host import\-key /etc/ssl/private/ssl\-cert\-snakeoil.key https://$(hostname \-\-fqdn)
+
+If you offer multiple HTTPS websites using the same secret key, you
+should add the additional website names with the `add\-servicename'
+subcommand.
+
+See PUBLISHING AND CERTIFYING MONKEYSPHERE SERVICE CERTIFICATES (the
+next section) for how to make sure your users can verify the https
+service offered by your host once the key is imported and any extra
+site names have been added. Note that you can add or remove
+additional servicenames at any time, but you'll need to certify any
+new ones separately.
+
+.SH PUBLISHING AND CERTIFYING MONKEYSPHERE SERVICE CERTIFICATES
+
+Once the host key has been imported, the corresponding certificate
+must be published to the Web of Trust so that users can retrieve the
+cert when connecting to the host. The host certificates are published
+to the keyserver with the publish\-key command:
+
+$ monkeysphere\-host publish\-key \-\-all
+
+In order for users accessing the system to be able to identify the
+host's service via the monkeysphere, at least one person (e.g. a
+server admin) will need to sign the host's certificate. This is done
+using standard OpenPGP keysigning techniques. Usually: pull the
+host's OpenPGP certificate from the keyserver, verify and sign it, and
+then re\-publish your signature. More than one person can certify any
+certificate. Please see
+http://web.monkeysphere.info/signing\-host\-keys/ for more information
+and details. Once an admin's signature is published, users accessing
+the host can use the certificate to validate the host's key without
+having to manually check the host key's fingerprint (in the case of
+ssh) or without seeing a nasty "security warning" in their browsers
+(in the case of https).
+
+.SH SECURITY CONSIDERATIONS
+
+Note that \fBmonkeysphere\-host\fP currently caches a copy of all
+imported secret keys (stored in OpenPGP form for future manipulation)
+in /var/lib/monkeysphere/host/secring.gpg. Cleartext backups of this
+file could expose secret key material if not handled sensitively.
projects / monkeysphere.git / blobdiff