man/man8/monkeysphere-host.8

   1 .TH MONKEYSPHERE-HOST "8" "January 2010" "monkeysphere" "System Commands"
   2
   3 .SH NAME
   4
   5 monkeysphere\-host \- Monkeysphere host key administration tool.
   6
   7 .SH SYNOPSIS
   8
   9 .B monkeysphere\-host \fIsubcommand\fP [\fIargs\fP]
  10
  11 .SH DESCRIPTION
  12
  13 \fBMonkeysphere\fP is a framework to leverage the OpenPGP web of trust
  14 for SSH and TLS key\-based authentication.
  15
  16 \fBmonkeysphere\-host\fP stores and manages OpenPGP certificates for
  17 various services offered by the host.
  18
  19 Most subcommands take a KEYID argument, which identifies (by OpenPGP
  20 key ID (e.g. 0xDEADBEEF) or full OpenPGP fingerprint) which
  21 certificate is to be operated upon.  If only one certificate is
  22 currently managed by \fBmonkeysphere\-host\fP, the KEYID argument may
  23 be omitted, and \fBmonkeysphere\-host\fP will operate on it.
  24
  25 .SH SUBCOMMANDS
  26
  27 \fBmonkeysphere\-host\fP takes various subcommands:
  28 .TP
  29 .B import\-key FILE SCHEME://HOSTNAME[:PORT]
  30 Import a PEM\-encoded host secret key from file FILE.  If FILE is
  31 `\-', then the key will be imported from stdin.  Only RSA keys are
  32 supported at the moment.  SCHEME://HOSTNAME[:PORT] is used to specify
  33 the scheme (e.g. ssh or https), fully\-qualified hostname (and port)
  34 used in the user ID of the new OpenPGP key (e.g. ssh://example.net or
  35 https://www.example.net).  If PORT is not specified, then no port is
  36 added to the user ID, which means the default port for that service
  37 (e.g. 22 for ssh) is assumed.  `i' may be used in place of
  38 `import\-key'.
  39 .TP
  40 .B show\-keys [KEYID ...]
  41 Output information about the OpenPGP certificate(s) for services
  42 offered by the host, including their KEYIDs.  If no KEYID is specified
  43 (or if the special string `\-\-all' is used), output information about
  44 all certificates managed by \fBmonkeysphere\-host\fP.  `s' may be used
  45 in place of `show\-keys'.
  46 .TP
  47 .B set\-expire EXPIRE [KEYID]
  48 Extend the validity of the OpenPGP certificate specified until EXPIRE
  49 from the present.  Expiration is specified as with GnuPG (measured
  50 from today's date):
  51 .nf
  52          0 = key does not expire
  53       <n>  = key expires in n days
  54       <n>w = key expires in n weeks
  55       <n>m = key expires in n months
  56       <n>y = key expires in n years
  57 .fi
  58 `e' may be used in place of `set\-expire'.
  59 .TP
  60 .B add\-servicename SCHEME://HOSTNAME[:PORT] [KEYID]
  61 Add a service\-specific user ID to the specified certificate.  For
  62 example, the operator of `https://example.net' may wish to add an
  63 additional servicename of `https://www.example.net' to the certificate
  64 corresponding to the secret key used by the TLS\-enabled web server.
  65 `add\-name' or `n+' may be used in place of `add\-servicename'.
  66 .TP
  67 .B revoke\-servicename SCHEME://HOSTNAME[:PORT] [KEYID]
  68 Revoke a service\-specific user ID from the specified certificate.
  69 `revoke\-name' or `n\-' may be used in place of `revoke\-servicename'.
  70 .TP
  71 .B add\-revoker REVOKER_KEYID|FILE [KEYID]
  72 Add a revoker to the specified OpenPGP certificate.  The revoker can
  73 be specified by their own REVOKER_KEYID (in which case it will be
  74 loaded from an OpenPGP keyserver), or by specifying a path to a file
  75 containing the revoker's OpenPGP certificate, or by specifying `\-' to
  76 load from stdin.  `r+' may be be used in place of `add\-revoker'.
  77 .TP
  78 .B revoke\-key [KEYID]
  79 Generate (with the option to publish) a revocation certificate for
  80 given OpenPGP certificate.  If such a certificate is published, the
  81 given key will be permanently revoked, and will no longer be accepted
  82 by monkeysphere\-enabled clients.  This subcommand will ask you a
  83 series of questions, and then generate a key revocation certificate,
  84 sending it to stdout.  You might want to store these certificates
  85 safely offline, to publish in case of compromise).  If you explicitly
  86 tell it to publish the revocation certificate immediately, it will
  87 send it to the public keyservers.  PUBLISH THESE CERTIFICATES ONLY IF
  88 YOU ARE SURE THE CORRESPONDING KEY WILL NEVER BE RE\-USED!
  89 .TP
  90 .B publish\-keys [KEYID ...]
  91 Publish the specified OpenPGP certificates to the public keyservers.
  92 If the special string `\-\-all' is specified, all of the host's
  93 OpenPGP certificates will be published.  `p' may be used in place of
  94 `publish\-keys'.  NOTE: that there is no way to remove a key from the
  95 public keyservers once it is published!
  96 .TP
  97 .B version
  98 Show the monkeysphere version number.  `v' may be used in place of
  99 `version'.
 100 .TP
 101 .B help
 102 Output a brief usage summary.  `h' or `?' may be used in place of
 103 `help'.
 104 .TP
 105 .B diagnostics
 106 Review the state of the monkeysphere server host key and report on
 107 suggested changes.  Among other checks, this includes making sure
 108 there is a valid host key, that the key is not expired, that the sshd
 109 configuration points to the right place, etc.  `d' may be used in
 110 place of `diagnostics'.
 111
 112 .SH SETUP SSH SERVER CERTIFICATES
 113
 114 To enable users to verify your SSH host's key via the monkeysphere, an
 115 OpenPGP certificate must be made out of the host's RSA ssh key, and
 116 the certificate must be published to the Web of Trust.  Certificate
 117 publication is not done by default.  The first step is to import the
 118 host's ssh key into a monkeysphere\-style OpenPGP certificate.  This
 119 is done with the import\-key command.  For example:
 120
 121 # monkeysphere\-host import\-key /etc/ssh/ssh_host_rsa_key ssh://host.example.org
 122
 123 On most systems, sshd's RSA secret key is stored at
 124 /etc/ssh/ssh_host_rsa_key.
 125
 126 See PUBLISHING AND CERTIFYING MONKEYSPHERE SERVICE CERTIFICATES for
 127 how to make sure your users can verify the ssh service offered by your
 128 host once the key is imported into \fBmonkeysphere\-host\fP.
 129
 130 .SH SETUP WEB SERVER CERTIFICATES
 131
 132 You can set up your HTTPS\-capable web server so that your users can
 133 verify it via the monkeysphere, without changing your server's
 134 software at all.  You just need access to a (PEM\-encoded) version of
 135 the server's RSA secret key (most secret keys are already stored
 136 PEM\-encoded).  The first step is to import the web server's key into
 137 a monkeysphere\-style OpenPGP certificate.  This is done with the
 138 import\-key command.  For example:
 139
 140 # monkeysphere\-host import\-key /etc/ssl/private/host.example.net\-key.pem https://host.example.net
 141
 142 If you don't know where the web server's key is stored on your
 143 machine, consult the configuration files for your web server.
 144 Debian\-based systems using the `ssl\-cert' packages often have a
 145 default self\-signed certificate stored in
 146 `/etc/ssl/private/ssl\-cert\-snakeoil.key' ; if you're using that key,
 147 your users are getting browser warnings about it.  You can keep using
 148 the same key, but help them use the OpenPGP WoT to verify that it does
 149 belong to your web server by using something like:
 150
 151 # monkeysphere\-host import\-key /etc/ssl/private/ssl\-cert\-snakeoil.key https://$(hostname \-\-fqdn)
 152
 153 If you offer multiple HTTPS websites using the same secret key, you
 154 should add the additional website names with the `add\-servicename'
 155 subcommand.
 156
 157 See PUBLISHING AND CERTIFYING MONKEYSPHERE SERVICE CERTIFICATES (the
 158 next section) for how to make sure your users can verify the https
 159 service offered by your host once the key is imported and any extra
 160 site names have been added.  Note that you can add or remove
 161 additional servicenames at any time, but you'll need to certify any
 162 new ones separately.
 163
 164 .SH PUBLISHING AND CERTIFYING MONKEYSPHERE SERVICE CERTIFICATES
 165
 166 Once the host key has been imported, the corresponding certificate
 167 must be published to the Web of Trust so that users can retrieve the
 168 cert when connecting to the host.  The host certificates are published
 169 to the keyserver with the publish\-key command:
 170
 171 $ monkeysphere\-host publish\-key \-\-all
 172
 173 In order for users accessing the system to be able to identify the
 174 host's service via the monkeysphere, at least one person (e.g. a
 175 server admin) will need to sign the host's certificate.  This is done
 176 using standard OpenPGP keysigning techniques.  Usually: pull the
 177 host's OpenPGP certificate from the keyserver, verify and sign it, and
 178 then re\-publish your signature.  More than one person can certify any
 179 certificate.  Please see
 180 http://web.monkeysphere.info/signing\-host\-keys/ for more information
 181 and details.  Once an admin's signature is published, users accessing
 182 the host can use the certificate to validate the host's key without
 183 having to manually check the host key's fingerprint (in the case of
 184 ssh) or without seeing a nasty "security warning" in their browsers
 185 (in the case of https).
 186
 187 .SH SECURITY CONSIDERATIONS
 188
 189 Note that \fBmonkeysphere\-host\fP currently caches a copy of all
 190 imported secret keys (stored in OpenPGP form for future manipulation)
 191 in /var/lib/monkeysphere/host/secring.gpg.  Cleartext backups of this
 192 file could expose secret key material if not handled sensitively.
 193
 194 .SH ENVIRONMENT
 195
 196 The following environment variables will override those specified in
 197 the config file (defaults in parentheses):
 198 .TP
 199 MONKEYSPHERE_LOG_LEVEL
 200 Set the log level.  Can be SILENT, ERROR, INFO, VERBOSE, DEBUG, in
 201 increasing order of verbosity. (INFO)
 202 .TP
 203 MONKEYSPHERE_KEYSERVER
 204 OpenPGP keyserver to use. (pool.sks\-keyservers.net)
 205 .TP
 206 MONKEYSPHERE_PROMPT
 207 If set to `false', never prompt the user for confirmation. (true)
 208
 209 .SH FILES
 210
 211 .TP
 212 /etc/monkeysphere/monkeysphere\-host.conf
 213 System monkeysphere\-host config file.
 214 .TP
 215 /var/lib/monkeysphere/host_keys.pub.pgp
 216 A world\-readable copy of the host's OpenPGP certificates in ASCII
 217 armored format.  This includes the certificates (including the public
 218 keys, servicename\-based User IDs, and most recent relevant
 219 self\-signatures) corresponding to every key used by
 220 Monkeysphere\-enabled services on the host.
 221 .TP
 222 /var/lib/monkeysphere/host/
 223 A locked directory (readable only by the superuser) containing copies
 224 of all imported secret keys (this is the host's GNUPGHOME directory).
 225
 226 .SH AUTHOR
 227
 228 This man page was written by:
 229 Jameson Rollins <jrollins@finestructure.net>,
 230 Daniel Kahn Gillmor <dkg@fifthhorseman.net>,
 231 Matthew Goins <mjgoins@openflows.com>
 232
 233 .SH SEE ALSO
 234
 235 .BR monkeysphere (1),
 236 .BR monkeysphere (7),
 237 .BR gpg (1),
 238 .BR monkeysphere\-authentication (8),
 239 .BR ssh (1),
 240 .BR sshd (8)