Provided by: monkeysphere_0.36-1_all bug

NAME

       monkeysphere-host - Monkeysphere host key administration tool.

SYNOPSIS

       monkeysphere-host subcommand [args]

DESCRIPTION

       Monkeysphere is a framework to leverage the OpenPGP web of trust for SSH and TLS key-based
       authentication.

       monkeysphere-host 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 monkeysphere-host, the KEYID argument may be
       omitted, and monkeysphere-host will operate on it.

SUBCOMMANDS

       monkeysphere-host takes various subcommands:

       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'.

       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
              monkeysphere-host.  `s' may be used in place of `show-keys'.

       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):
                       0 = key does not expire
                    <n>  = key expires in n days
                    <n>w = key expires in n weeks
                    <n>m = key expires in n months
                    <n>y = key expires in n years
              `e' may be used in place of `set-expire'.

       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'.

       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'.

       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'.

       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!

       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!

       version
              Show the monkeysphere version number.  `v' may be used in place of `version'.

       help   Output a brief usage summary.  `h' or `?' may be used in place of `help'.

       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 not expired, that the sshd configuration points to the right place,
              etc.  `d' may be used in place of `diagnostics'.

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
       monkeysphere-host.

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.

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/doc/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).

SECURITY CONSIDERATIONS

       Note that monkeysphere-host 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.

ENVIRONMENT

       The following environment variables will override  those  specified  in  the  config  file
       (defaults in parentheses):

       MONKEYSPHERE_LOG_LEVEL
              Set the log level.  Can be SILENT, ERROR, INFO, VERBOSE, DEBUG, in increasing order
              of verbosity. (INFO)

       MONKEYSPHERE_KEYSERVER
              OpenPGP keyserver to use. (pool.sks-keyservers.net)

       MONKEYSPHERE_PROMPT
              If set to `false', never prompt the user for confirmation. (true)

FILES

       /etc/monkeysphere/monkeysphere-host.conf
              System monkeysphere-host config file.

       /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.

       /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).

       /etc/monkeysphere/monkeysphere-host-x509-anchors.crt                                    or
       /etc/monkeysphere/monkeysphere-x509-anchors.crt
              If  monkeysphere-host is configured to query an hkps keyserver for publish-keys, it
              will use X.509 Certificate Authority certificates in  this  file  to  validate  any
              X.509  certificates  used  by the keyserver.  If the monkeysphere-host-x509 file is
              present, the monkeysphere-x509 file will be ignored.

AUTHOR

       This man page was written by: Jameson Rollins  <jrollins@finestructure.net>,  Daniel  Kahn
       Gillmor <dkg@fifthhorseman.net>, Matthew Goins <mjgoins@openflows.com>

SEE ALSO

       monkeysphere(1), monkeysphere(7), gpg(1), monkeysphere-authentication(8), ssh(1), sshd(8)