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