xenial (1) monkeysphere.1.gz

Provided by: monkeysphere_0.37-3_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)