Provided by: monkeysphere_0.43-3.1_all bug

NAME

       monkeysphere - Monkeysphere client user interface

SYNOPSIS

       monkeysphere subcommand [args]

DESCRIPTION

       Monkeysphere  is a framework to leverage the OpenPGP web of trust for OpenSSH and TLS key-
       based  authentication.   OpenPGP  keys  are  tracked  via  GnuPG,   and   added   to   the
       authorized_keys  and  known_hosts  files  used  by  OpenSSH for connection authentication.
       Monkeysphere can also be used by a validation agent  to  validate  TLS  connections  (e.g.
       https).

       monkeysphere is the Monkeysphere client utility.

SUBCOMMANDS

       monkeysphere takes various subcommands:

       update-known_hosts [HOST]...
              Update  the  known_hosts  file.  For each specified host, gpg will be queried for a
              key associated with the host URI  (see  HOST  IDENTIFICATION  in  monkeysphere(7)),
              optionally  querying  a keyserver.  If an acceptable key is found for the host (see
              KEY ACCEPTABILITY in monkeysphere(7)), the key is added to the  user's  known_hosts
              file.   If  a  key is found but is unacceptable for the host, any matching keys are
              removed from the user's known_hosts file.  If no gpg key is  found  for  the  host,
              nothing  is  done.   If no hosts are specified, all hosts listed in the known_hosts
              file will be processed.  This subcommand will exit with a status of 0 if  at  least
              one acceptable key was found for a specified host, 1 if no matching keys were found
              at all, and 2 if matching keys were found but none were  acceptable.   `k'  may  be
              used in place of `update-known_hosts'.

       update-authorized_keys
              Update   the   authorized_keys  file  for  the  user  executing  the  command  (see
              MONKEYSPHERE_AUTHORIZED_KEYS in ENVIRONMENT, below).  First all  monkeysphere  keys
              are  cleared  from  the authorized_keys file.  Then, for each user ID in the user's
              authorized_user_ids file, gpg will be queried for keys associated  with  that  user
              ID,  optionally  querying  a  keyserver.   If  an  acceptable key is found (see KEY
              ACCEPTABILITY in monkeysphere(7)), the key is added to the  user's  authorized_keys
              file.  If a key is found but is unacceptable for the user ID, any matching keys are
              removed from the user's authorized_keys file.  If no gpg key is found for the  user
              ID,  nothing is done.  This subcommand will exit with a status of 0 if at least one
              acceptable key was found for a user ID, 1 if no matching keys were  found  at  all,
              and  2  if  matching  keys were found but none were acceptable.  `a' may be used in
              place of `update-authorized_keys'.

       gen-subkey [KEYID]
              Generate an authentication subkey for a private key in your GnuPG  keyring.   KEYID
              is  the  key  ID  for  the  primary  key for which the subkey with "authentication"
              capability will be generated.  If no key ID is specified, but only one  key  exists
              in  the secret keyring, that key will be used.  The length of the generated key can
              be specified with the `--length' or `-l' option.  `g'  may  be  used  in  place  of
              `gen-subkey'.

       ssh-proxycommand [--no-connect] HOST [PORT]
              An  ssh  ProxyCommand  that can be used to trigger a monkeysphere update of the ssh
              known_hosts file for a host that is being connected to with  ssh.   This  works  by
              updating the known_hosts file for the host first, before an attempted connection to
              the host is made.  Once the known_hosts file has been updated, a TCP connection  to
              the  host  is  made  by exec'ing netcat(1).  Regular ssh communication is then done
              over this netcat TCP connection (see ProxyCommand in ssh_config(5) for more info).

              This command is meant to be run as the ssh "ProxyCommand".  This can either be done
              by specifying the proxy command on the command line:

              ssh -o ProxyCommand="monkeysphere ssh-proxycommand %h %p" ...

              or by adding the following line to your ~/.ssh/config script:

              ProxyCommand monkeysphere ssh-proxycommand %h %p

              The script can easily be incorporated into other ProxyCommand scripts by calling it
              with the "--no-connect" option, i.e.:

              monkeysphere ssh-proxycommand --no-connect $HOST $PORT

              This will run everything except the final exec of netcat to make the TCP connection
              to  the  host.  In this way this command can be added to another proxy command that
              does other stuff, and then makes the connection to the host itself.   For  example,
              in ~/.ssh/config:

              ProxyCommand sh -c 'monkeysphere ssh-proxycommand --no-connect %h %p ; ssh -W %h:%p
              jumphost.example.net'

              KEYSERVER CHECKING: The  proxy  command  has  a  fairly  nuanced  policy  for  when
              keyservers  are queried when processing a host.  If the host userID is not found in
              either the user's keyring or in the known_hosts file, then the keyserver is queried
              for  the  host userID.  If the host userID is found in the user's keyring, then the
              keyserver is not checked.  This assumes that the keyring is kept up-to-date,  in  a
              cronjob  or the like, so that revocations are properly handled.  If the host userID
              is not found in the user's keyring, but the host is listed in the known_hosts file,
              then  the  keyserver  is not checked.  This last policy might change in the future,
              possibly by adding a deferred check, so that hosts that go  from  non-monkeysphere-
              enabled to monkeysphere-enabled will be properly checked.

              Setting    the    CHECK_KEYSERVER    variable   in   the   config   file   or   the
              MONKEYSPHERE_CHECK_KEYSERVER environment variable to either `true' or `false'  will
              override  the  keyserver-checking  policy  defined above and either always or never
              check the keyserver for host key updates.

       subkey-to-ssh-agent [ssh-add arguments]
              Push all authentication-capable subkeys in your  GnuPG  secret  keyring  into  your
              running  ssh-agent.   Additional  arguments  are passed through to ssh-add(1).  For
              example, to remove the authentication subkeys, pass an  additional  `-d'  argument.
              To   require   confirmation   on   each   use   of   the   key,   pass  `-c'.   The
              MONKEYSPHERE_SUBKEYS_FOR_AGENT  environment  can  be  used  to  specify  the   full
              fingerprints  of  specific  keys  to add to the agent (space separated), instead of
              adding them all.  `s' may be used in place of `subkey-to-ssh-agent'.

       keys-for-userid USERID
              Output to stdout all acceptable keys for a given user ID.  `u' may be used in place
              of `keys-for-userid'.

       sshfprs-for-userid USERID
              Output the ssh fingerprints of acceptable keys for a given user ID.

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

ENVIRONMENT

       The following environment variables will override those specified in the monkeysphere.conf
       configuration 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_GNUPGHOME, GNUPGHOME
              GnuPG home directory. (~/.gnupg)

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

       MONKEYSPHERE_CHECK_KEYSERVER
              Whether or not to check keyserver when making gpg queries. (true)

       MONKEYSPHERE_KNOWN_HOSTS
              Path to ssh known_hosts file. (~/.ssh/known_hosts)

       MONKEYSPHERE_HASH_KNOWN_HOSTS
              Whether or not to hash to the known_hosts file entries. (false)

       MONKEYSPHERE_AUTHORIZED_KEYS
              Path to ssh authorized_keys file. (~/.ssh/authorized_keys)

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

       MONKEYSPHERE_STRICT_MODES
              If  set  to  `false', ignore too-loose permissions on known_hosts, authorized_keys,
              and authorized_user_ids files.  NOTE: setting this to false may expose you to abuse
              by other users on the system. (true)

       MONKEYSPHERE_SUBKEYS_FOR_AGENT
              A  space-separated  list  of authentication-capable subkeys to add to the ssh agent
              with subkey-to-ssh-agent.

FILES

       ~/.monkeysphere/monkeysphere.conf
              User monkeysphere config file.

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

       ~/.monkeysphere/authorized_user_ids
              A list of OpenPGP user IDs, one per line.  OpenPGP keys  with  an  exactly-matching
              User  ID  (calculated  valid  by the designated identity certifiers), will have any
              valid  authorization-capable  keys  or  subkeys   added   to   the   given   user's
              authorized_keys file.

AUTHOR

       Written   by:   Jameson   Rollins   <jrollins@finestructure.net>,   Daniel   Kahn  Gillmor
       <dkg@fifthhorseman.net>

SEE ALSO

       monkeysphere-host(8), monkeysphere-authentication(8), monkeysphere(7), ssh(1), ssh-add(1),
       gpg(1)