-.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
.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
.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
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
/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
# Jameson Rollins <jrollins@fifthhorseman.net>
# Micah Anderson <micah@riseup.net>
#
-# Copyright: 2008-2009
+# Copyright: © 2008-2010
# License: GPL v3 or later
# these tests should all be able to run as a non-privileged user.
echo
echo "##################################################"
echo "### getting host key fingerprint..."
-HOSTKEYID=$( monkeysphere-host show-key | grep '^OpenPGP fingerprint: ' | cut -f3 -d\ )
-echo "$HOSTKEYID"
+SSHHOSTKEYID=$( monkeysphere-host show-key | grep '^OpenPGP fingerprint: ' | cut -f3 -d\ )
+echo "$SSHHOSTKEYID"
# change host key expiration
echo
echo "##################################################"
echo "### certifying server host key..."
< "$HOST_KEY_FILE" gpgadmin --import
-echo y | gpgadmin --command-fd 0 --sign-key "$HOSTKEYID"
+echo y | gpgadmin --command-fd 0 --sign-key "$SSHHOSTKEYID"
# FIXME: add revoker?
echo
echo "##################################################"
echo "### export server key to testuser..."
-gpgadmin --armor --export "$HOSTKEYID" | gpg --import
+gpgadmin --armor --export "$SSHHOSTKEYID" | gpg --import
# teach the "server" about the testuser's key
echo
######################################################################
### TESTS
+## see whether keys-for-userid works from the client's perspective:
+echo
+echo "##################################################"
+echo "### testing monkeysphere keys-for-userid ..."
+diff -q <( monkeysphere keys-for-userid ssh://testhost ) <( cut -f1,2 -d' ' < "$TEMPDIR"/ssh_host_rsa_key.pub )
+
# connect to test sshd, using monkeysphere ssh-proxycommand to verify
# the identity before connection. This should work in both directions!
echo
target_hostname=testhost2 ssh_test 255
echo
echo "##################################################"
-echo "### add hostname, certify by admin, import by user..."
-monkeysphere-host add-hostname ssh://testhost2
+echo "### add servicename, certify by admin, import by user..."
+monkeysphere-host add-servicename ssh://testhost2
<"$HOST_KEY_FILE" gpgadmin --import
-printf "y\ny\n" | gpgadmin --command-fd 0 --sign-key "$HOSTKEYID"
+printf "y\ny\n" | gpgadmin --command-fd 0 --sign-key "$SSHHOSTKEYID"
echo
echo "##################################################"
echo "### ssh connection test with hostname 'testhost2' added..."
-gpgadmin --export "$HOSTKEYID" | gpg --import
+gpgadmin --export "$SSHHOSTKEYID" | gpg --import
gpg --check-trustdb
ssh_test
echo
echo "##################################################"
echo "### ssh connection test for failure with 'testhost2' revoked..."
-monkeysphere-host revoke-hostname ssh://testhost2
+monkeysphere-host revoke-servicename ssh://testhost2
gpg --import <"$HOST_KEY_FILE"
gpg --check-trustdb
target_hostname=testhost2 ssh_test 255
# FIXME: addtest: remove admin as id-certifier and check ssh failure
# FIXME: addtest: how do we test that set-expire makes sense after new
-# hostnames have been added?
-
-# FIXME: addtest: revoke the host key and check ssh failure
+# servicenames have been added?
# test to make sure things are OK after the previous tests:
echo
echo
echo "##################################################"
-echo "### revoking host key..."
+echo "### Testing TLS setup..."
+
+openssl req -config "$TESTDIR"/openssl.cnf -x509 -newkey rsa:1024 -subj '/DC=net/DC=example/DC=testhost/CN=testhost.example.net/' -days 3 -keyout "$TEMPDIR"/tls_key.pem -nodes >"$TEMPDIR"/tls_cert.pem
+monkeysphere-host import-key "$TEMPDIR"/tls_key.pem https://testhost
+
+# FIXME: how can we test this via an https client?
+# We don't currently provide one.
+
+# FIXME: should we test other monkeysphere-host operations somehow now
+# that we have more than one key in the host keyring?
+
+echo
+echo "##################################################"
+echo "### revoking ssh host key..."
# generate the revocation certificate and feed it directly to the test
# user's keyring (we're not publishing to the keyservers)
monkeysphere-host revoke-key | gpg --import
projects / monkeysphere.git / commitdiff