overhaul monkeysphere-host(8) to match new multi-key capable interface

1 files changed, 148 insertions, 78 deletions

diff --git a/man/man8/monkeysphere-host.8 b/man/man8/monkeysphere-host.8
index 131b8c7..2a670a1 100644
--- a/man/man8/monkeysphere-host.8
+++ b/man/man8/monkeysphere-host.8
@@ -1,8 +1,8 @@
-.TH MONKEYSPHERE-SERVER "8" "March 2009" "monkeysphere" "User Commands"
+.TH MONKEYSPHERE-HOST "8" "January 2010" "monkeysphere" "System Commands"
 
 .SH NAME
 
-monkeysphere\-host - Monkeysphere host admin tool.
+monkeysphere\-host - Monkeysphere host key administration tool.
 
 .SH SYNOPSIS
 
@@ -11,35 +11,43 @@ monkeysphere\-host - Monkeysphere host admin tool.
 .SH DESCRIPTION
 
 \fBMonkeysphere\fP is a framework to leverage the OpenPGP web of trust
-for OpenSSH authentication.  OpenPGP keys are tracked via GnuPG, and
-added to the authorized_keys and known_hosts files used by OpenSSH for
-connection authentication.
+for SSH and TLS key-based authentication.
 
-\fBmonkeysphere\-host\fP is a Monkeysphere server admin utility for
-managing the host's OpenPGP host key.
+\fBmonkeysphere\-host\fP stores and manages OpenPGP certificates for
+various services offered by the host.
+
+Most subcommands take a KEYID argument, which identifies (by OpenPGP
+key ID (e.g. 0xDEADBEEF) or full OpenPGP fingerprint) which
+certificate is to be operated upon.  If only one certificate is
+currently managed by \fBmonkeysphere\-host\fP, the KEYID argument may
+be omitted, \fBmonkeysphere\-host\fP will operate on it.
 
 .SH SUBCOMMANDS
 
 \fBmonkeysphere\-host\fP takes various subcommands:
 .TP
-.B import\-key FILE NAME[:PORT]
-Import a pem-encoded ssh secret host key from file FILE.  If FILE is
-`\-', then the key will be imported from stdin.  Only RSA keys are
-supported at the moment.  NAME[:PORT] is used to specify the
-fully-qualified hostname (and port) used in the user ID of the new
-OpenPGP key.  If PORT is not specified, then no port is added to the
-user ID, which means port 22 is assumed.  `i' may be used in place of
+.B import\-key FILE SCHEME://HOSTNAME[:PORT]
+Import a PEM-encoded host secret key from file FILE.  If FILE is `\-',
+then the key will be imported from stdin.  Only RSA keys are supported
+at the moment.  SCHEME://HOSTNAME[:PORT] is used to specify the scheme
+(e.g. ssh or https), fully-qualified hostname (and port) used in the
+user ID of the new OpenPGP key (e.g. ssh://example.net or
+https://www.example.net).  If PORT is not specified, then no port is
+added to the user ID, which means the default port for that service
+(e.g. 22 for ssh) is assumed.  `i' may be used in place of
 `import\-key'.
 .TP
-.B show\-key
-Output information about host's OpenPGP and SSH keys.  `s' may be used
+.B show\-key [KEYID ...]
+Output information about the OpenPGP certificate(s) for services
+offered by the host, including their KEYIDs.  If no KEYID is specified
+(or if the special string `--all' is used), output information about
+all certificates managed by \fBmonkeysphere\-host\fP.  `s' may be used
 in place of `show\-key'.
 .TP
-.B set\-expire [EXPIRE]
-Extend the validity of the OpenPGP key for the host until EXPIRE from
-the present.  If EXPIRE is not specified, then the user will be
-prompted for the extension term.  Expiration is specified as with
-GnuPG (measured from today's date):
+.B set\-expire EXPIRE [KEYID]
+Extend the validity of the OpenPGP certificate specified until EXPIRE
+from the present.  Expiration is specified as with GnuPG (measured
+from today's date):
 .nf
          0 = key does not expire
       <n>  = key expires in n days
@@ -49,34 +57,42 @@ GnuPG (measured from today's date):
 .fi
 `e' may be used in place of `set\-expire'.
 .TP
-.B add\-hostname HOSTNAME
-Add a hostname user ID to the server host key.  `n+' may be used in
-place of `add\-hostname'.
-.TP
-.B revoke\-hostname HOSTNAME
-Revoke a hostname user ID from the server host key.  `n\-' may be used
-in place of `revoke\-hostname'.
-.TP
-.B add\-revoker KEYID|FILE
-Add a revoker to the host's OpenPGP key.  The key ID will be loaded
-from the keyserver.  A file may be loaded instead of pulling the key
-from the keyserver by specifying the path to the file as the argument,
-or by specifying `\-' to load from stdin.  `r+' may be be used in place
-of `add-revoker'.
-.TP
-.B revoke\-key
-Generate (with the option to publish) a revocation certificate for the
-host's OpenPGP key.  If such a certificate is published, your host key
-will be permanently revoked.  This subcommand will ask you a series of
-questions, and then generate a key revocation certificate, sending it
-to stdout.  If you explicitly tell it to publish the revocation
-certificate immediately, it will send it to the public keyservers.
-USE WITH CAUTION!
-.TP
-.B publish\-key
-Publish the host's OpenPGP key to the public keyservers.  `p' may be
-used in place of `publish-key'.  Note that there is no way to remove a
-key from the public keyservers once it is published!
+.B add\-servicename SCHEME://HOSTNAME[:PORT] [KEYID]
+Add a service-specific user ID to the specified certificate.  For
+example, the operator of `https://example.net' may wish to add an
+additional servicename of `https://www.example.net' to the certificate
+corresponding to the secret key used by the TLS-enabled web server.
+`n+' may be used in place of `add\-hostname'.
+.TP
+.B revoke\-servicename SCHEME://HOSTNAME[:PORT] [KEYID]
+Revoke a service-specific user ID from the specified certificate.
+`n\-' may be used in place of `revoke\-hostname'.
+.TP
+.B add\-revoker REVOKER_KEYID|FILE [KEYID]
+Add a revoker to the specified OpenPGP certificate.  The revoker can
+be specified by their own REVOKER_KEYID (in which case it will be
+loaded from an OpenPGP keyserver), or by specifying a path to a file
+containing the revoker's OpenPGP certificate, or by specifying `\-' to
+load from stdin.  `r+' may be be used in place of `add-revoker'.
+.TP
+.B revoke\-key [KEYID]
+Generate (with the option to publish) a revocation certificate for
+given OpenPGP certificate.  If such a certificate is published, the
+given key will be permanently revoked, and will no longer be accepted
+by monkeysphere-enabled clients.  This subcommand will ask you a
+series of questions, and then generate a key revocation certificate,
+sending it to stdout.  You might want to store these certificates
+safely offline, to publish in case of compromise).  If you explicitly
+tell it to publish the revocation certificate immediately, it will
+send it to the public keyservers.  PUBLISH THESE CERTIFICATES ONLY IF
+YOU ARE SURE THE CORRESPONDING KEY WILL NEVER BE RE-USED!
+.TP
+.B publish\-key [KEYID ...]
+Publish the specified OpenPGP certificates to the public keyservers.
+If the special string `--all' is specified, all of the host's OpenPGP
+certificates will be published.  `p' may be used in place of
+`publish-key'.  Note that there is no way to remove a key from the
+public keyservers once it is published!
 .TP
 .B version
 Show the monkeysphere version number.  `v' may be used in place of
@@ -96,37 +112,87 @@ there is a valid host key, that the key is not expired, that the sshd
 configuration points to the right place, etc.  `d' may be used in
 place of `diagnostics'.
 
-.SH SETUP HOST AUTHENTICATION
+.SH SETUP SSH SERVER CERTIFICATES
 
-To enable host verification via the monkeysphere, an OpenPGP key must
-be made out of the host's ssh key, and the key must be published to
-the Web of Trust.  This is not done by default.  The first step is to
-import the host's ssh key into a monkeysphere-style OpenPGP key.  This
-is done with the import\-key command.  When importing a key, you must
-specify the path to the host's ssh RSA key to import, and a hostname
-to use as the key's user ID:
+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 host.example.org
+# monkeysphere\-host import\-key /etc/ssh/ssh_host_rsa_key ssh://host.example.org
 
-On most systems, the ssh host RSA key is stored at
+On most systems, sshd's RSA secret key is stored at
 /etc/ssh/ssh_host_rsa_key.
 
-Once the host key has been imported, it must be published to the Web
-of Trust so that users can retrieve the key when sshing to the host.
-The host key is published to the keyserver with the publish\-key
-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.  Please
-see http://web.monkeysphere.info/signing-host-keys/ for more
-information.  Once an admin's signature is published, users logging
-into the host can use it to validate the host's key without having to
-manually check the host key's fingerprint.
+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.
 
 .SH ENVIRONMENT
 
@@ -149,9 +215,13 @@ If set to `false', never prompt the user for confirmation. (true)
 /etc/monkeysphere/monkeysphere\-host.conf
 System monkeysphere\-host config file.
 .TP
-/var/lib/monkeysphere/host/ssh_host_rsa_key.pub.gpg
-A world-readable copy of the host's public key in OpenPGP format,
-including all relevant self-signatures.
+/var/lib/monkeysphere/host_keys.pub.gpg
+A world-readable copy of all of the host's public keys in OpenPGP
+format, including all relevant self-signatures.
+.TP
+/var/lib/monkeysphere/host/
+A locked directory (readable only by the superuser) containing copies
+of all imported secret keys.
 
 .SH AUTHOR