X-Git-Url: https://codewiz.org/gitweb?a=blobdiff_plain;f=man%2Fman8%2Fmonkeysphere-host.8;h=00ea7778afc734105410d0f5af6aa95731718fa8;hb=HEAD;hp=f33aea635dcfa8535ecd88425c2b5c75d7c3fdb3;hpb=c073811aa573d0e3486c39ed9514c46e0a7a077f;p=monkeysphere.git diff --git a/man/man8/monkeysphere-host.8 b/man/man8/monkeysphere-host.8 index f33aea6..00ea777 100644 --- a/man/man8/monkeysphere-host.8 +++ b/man/man8/monkeysphere-host.8 @@ -1,46 +1,53 @@ -.TH MONKEYSPHERE-SERVER "8" "June 2008" "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 -.B monkeysphere-host \fIsubcommand\fP [\fIargs\fP] -.br -.B monkeysphere-host expert \fIexpert-subcommand\fP [\fIargs\fP] +.B monkeysphere\-host \fIsubcommand\fP [\fIargs\fP] .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. +\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, and \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. NAME[:PORT] is used -to specify the hostname (and port) used in the user ID of the new -OpenPGP key. If NAME is not specified, then the system -fully-qualified domain name will be used (ie. `hostname -f'). If PORT -is not specified, the no port is added to the user ID, which means -port 22 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 -in place of `show-key'. -.TP -.B extend-key [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: +\fBmonkeysphere\-host\fP takes various subcommands: +.TP +.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\-keys [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\-keys'. +.TP +.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 @@ -48,60 +55,141 @@ GnuPG: m = key expires in n months y = key expires in n years .fi -`e' may be used in place of `extend-key'. -.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 FINGERPRINT -Add a revoker to the host's OpenPGP key. `o' may be be used in place -of `add-revoker'. +`e' may be used in place of `set\-expire'. +.TP +.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. +`add\-name' or `n+' may be used in place of `add\-servicename'. +.TP +.B revoke\-servicename SCHEME://HOSTNAME[:PORT] [KEYID] +Revoke a service\-specific user ID from the specified certificate. +`revoke\-name' or `n\-' may be used in place of `revoke\-servicename'. +.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\-keys [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\-keys'. NOTE: that there is no way to remove a key from the +public keyservers once it is published! .TP -.B revoke-key -Revoke the host's OpenPGP key. `r' may be used in place of -`revoke-key'. -.TP -.B publish-key -Publish the host's OpenPGP key to the keyserver. `p' may be used in -place of `publish-key'. +.B version +Show the monkeysphere version number. `v' may be used in place of +`version'. .TP .B help Output a brief usage summary. `h' or `?' may be used in place of `help'. .TP -.B version -show version number - - -Other commands: -.TP .B diagnostics Review the state of the monkeysphere server host key and report on suggested changes. Among other checks, this includes making sure -there is a valid host key, that the key is published, that the sshd +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 - -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. .SH ENVIRONMENT @@ -109,37 +197,44 @@ The following environment variables will override those specified in the config file (defaults in parentheses): .TP MONKEYSPHERE_LOG_LEVEL -Set the log level (INFO). Can be SILENT, ERROR, INFO, VERBOSE, DEBUG, in -increasing order of verbosity. +Set the log level. Can be SILENT, ERROR, INFO, VERBOSE, DEBUG, in +increasing order of verbosity. (INFO) .TP MONKEYSPHERE_KEYSERVER -OpenPGP keyserver to use (pool.sks-keyservers.net). +OpenPGP keyserver to use. (pool.sks\-keyservers.net) .TP MONKEYSPHERE_PROMPT If set to `false', never prompt the user for confirmation. (true) - .SH FILES .TP -/etc/monkeysphere/monkeysphere-host.conf -System monkeysphere-host config file. +/etc/monkeysphere/monkeysphere\-host.conf +System monkeysphere\-host config file. +.TP +/var/lib/monkeysphere/host_keys.pub.pgp +A world\-readable copy of the host's OpenPGP certificates in ASCII +armored format. This includes the certificates (including the public +keys, servicename\-based User IDs, and most recent relevant +self\-signatures) corresponding to every key used by +Monkeysphere\-enabled services on the host. .TP -/var/lib/monkeysphere/host/ssh_host_rsa_key -Copy of the host's private key in ssh format, suitable for use by -sshd. +/var/lib/monkeysphere/host/ +A locked directory (readable only by the superuser) containing copies +of all imported secret keys (this is the host's GNUPGHOME directory). .SH AUTHOR -Written by: -Jameson Rollins , +This man page was written by: +Jameson Rollins , Daniel Kahn Gillmor , Matthew Goins .SH SEE ALSO .BR monkeysphere (1), -.BR monkeysphere-authentication (8), .BR monkeysphere (7), .BR gpg (1), -.BR ssh (1) +.BR monkeysphere\-authentication (8), +.BR ssh (1), +.BR sshd (8)