Provided by: monkeysphere_0.28-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/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).

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

AUTHOR

       This    man    page     was     written     by:     Jameson     Rollins
       <jrollins@fifthhorseman.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)