From d670eab60c0ce98bb9f4dc439f9bbd0452ee0d0a Mon Sep 17 00:00:00 2001 From: Daniel Kahn Gillmor Date: Fri, 15 Jan 2010 00:47:19 -0500 Subject: [PATCH] overhaul monkeysphere-host(8) to match new multi-key capable interface --- man/man8/monkeysphere-host.8 | 226 +++++++++++++++++++++++------------ 1 file 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 = 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 -- 2.26.2