man/man1/monkeysphere.1

   1 .TH MONKEYSPHERE "1" "June 2008" "monkeysphere 0.1" "User Commands"
   2
   3 .SH NAME
   4
   5 monkeysphere \- Monkeysphere client user interface
   6
   7 .SH SYNOPSIS
   8
   9 .B monkeysphere \fIsubcommand\fP [\fIargs\fP]
  10
  11 .SH DESCRIPTION
  12
  13 \fBMonkeysphere\fP is a framework to leverage the OpenPGP web of trust
  14 for OpenSSH authentication.  OpenPGP keys are tracked via GnuPG, and
  15 added to the authorized_keys and known_hosts files used by OpenSSH for
  16 connection authentication.
  17
  18 \fBmonkeysphere\fP is the Monkeysphere client utility.
  19
  20 .SH SUBCOMMANDS
  21
  22 \fBmonkeysphere\fP takes various subcommands:
  23 .TP
  24 .B update-known_hosts [HOST]...
  25 Update the known_hosts file.  For each specified host, gpg will be
  26 queried for a key associated with the host URI (see HOST
  27 IDENTIFICATION in
  28 .BR monkeysphere(7)),
  29 optionally querying a keyserver.
  30 If an acceptable key is found for the host (see KEY ACCEPTABILITY in
  31 .BR monkeysphere(7)),
  32 the key is added to the user's known_hosts file.  If a key is found
  33 but is unacceptable for the host, any matching keys are removed from
  34 the user's known_hosts file.  If no gpg key is found for the host,
  35 nothing is done.  If no hosts are specified, all hosts listed in the
  36 known_hosts file will be processed.  This subcommand will exit with a
  37 status of 0 if at least one acceptable key was found for a specified
  38 host, 1 if no matching keys were found at all, and 2 if matching keys
  39 were found but none were acceptable.  `k' may be used in place of
  40 `update-known_hosts'.
  41 .TP
  42 .B ssh-proxycommand
  43 an ssh proxy command that can be used
  44 to trigger a monkeysphere update of the ssh known_hosts file for a
  45 host that is being connected to with ssh.  This works by updating the
  46 known_hosts file for the host first, before an attempted connection to
  47 the host is made.  Once the known_hosts file has been updated, a TCP
  48 connection to the host is made by exec'ing netcat(1).  Regular ssh
  49 communication is then done over this netcat TCP connection (see
  50 ProxyCommand in ssh_config(5) for more info).
  51
  52 This command is meant to be run as the ssh "ProxyCommand".  This can
  53 either be done by specifying the proxy command on the command line:
  54
  55 .B ssh -o ProxyCommand="monkeysphere ssh-proxycommand %h %p" ...
  56
  57 or by adding the following line to your ~/.ssh/config script:
  58
  59 .B ProxyCommand monkeysphere ssh-proxycommand %h %p
  60
  61 The script can easily be incorporated into other ProxyCommand scripts
  62 by calling it with the "--no-connect" option, i.e.:
  63
  64 .B monkeysphere ssh-proxycommand --no-connect "$HOST" "$PORT"
  65
  66 This will run everything except the final exec of netcat to make the
  67 TCP connection to the host.  In this way this command can be added to
  68 another proxy command that does other stuff, and then makes the
  69 connection to the host itself.
  70
  71 KEYSERVER CHECKING:
  72 The proxy command has a fairly nuanced policy for when keyservers are
  73 queried when processing a host.  If the host userID is not found in
  74 either the user's keyring or in the known_hosts file, then the
  75 keyserver is queried for the host userID.  If the host userID is found
  76 in the user's keyring, then the keyserver is not checked.  This
  77 assumes that the keyring is kept up-to-date, in a cronjob or the like,
  78 so that revocations are properly handled.  If the host userID is not
  79 found in the user's keyring, but the host is listed in the known_hosts
  80 file, then the keyserver is not checked.  This last policy might
  81 change in the future, possibly by adding a deferred check, so that
  82 hosts that go from non-monkeysphere-enabled to monkeysphere-enabled
  83 will be properly checked.
  84
  85 Setting the MONKEYSPHERE_CHECK_KEYSERVER
  86 variable (to `true' or `false') will override the keyserver-checking policy
  87 defined above.
  88
  89 .TP
  90 .B update-authorized_keys
  91 Update the authorized_keys file for the user executing the command
  92 (see MONKEYSPHERE_AUTHORIZED_KEYS in ENVIRONMENT, below).  First all
  93 monkeysphere keys are cleared from the authorized_keys file.  Then, or
  94 each user ID in the user's authorized_user_ids file, gpg will be
  95 queried for keys associated with that user ID, optionally querying a
  96 keyserver.  If an acceptable key is found (see KEY ACCEPTABILITY in
  97 .BR monkeysphere (7)),
  98 the key is added to the user's authorized_keys file.
  99 If a key is found but is unacceptable for the user ID, any matching
 100 keys are removed from the user's authorized_keys file.  If no gpg key
 101 is found for the user ID, nothing is done.  This subcommand will exit
 102 with a status of 0 if at least one acceptable key was found for a user
 103 ID, 1 if no matching keys were found at all, and 2 if matching keys
 104 were found but none were acceptable.  `a' may be used in place of
 105 `update-authorized_keys'.
 106 .TP
 107 .B gen-subkey [KEYID]
 108 Generate an authentication subkey for a private key in your GnuPG
 109 keyring.  For the primary key with the specified key ID, generate a
 110 subkey with "authentication" capability that can be used for
 111 monkeysphere transactions.  An expiration length can be specified with
 112 the `-e' or `--expire' option (prompt otherwise).  If no key ID is
 113 specified, but only one key exists in the secret keyring, that key
 114 will be used.  `g' may be used in place of `gen-subkey'.
 115 .TP
 116 .B subkey-to-ssh-agent [ssh-add arguments]
 117 Push all authentication-capable subkeys in your GnuPG secret keyring
 118 into your running ssh-agent.  Additional arguments are passed through
 119 to
 120 .BR ssh-add (1).
 121 For example, to remove the authentication subkeys, pass an additional
 122 `-d' argument.  To require confirmation on each use of the key, pass
 123 `-c'.  `s' may be used in place of `subkey-to-ssh-agent'.
 124 .TP
 125 .B help
 126 Output a brief usage summary.  `h' or `?' may be used in place of
 127 `help'.
 128
 129 .SH ENVIRONMENT
 130
 131 The following environment variables will override those specified in
 132 the monkeysphere.conf configuration file (defaults in parentheses):
 133 .TP
 134 MONKEYSPHERE_LOG_LEVEL
 135 Set the log level (INFO).  Can be SILENT, ERROR, INFO, VERBOSE, DEBUG,
 136 in increasing order of verbosity.
 137 .TP
 138 MONKEYSPHERE_GNUPGHOME, GNUPGHOME
 139 GnuPG home directory (~/.gnupg).
 140 .TP
 141 MONKEYSPHERE_KEYSERVER
 142 OpenPGP keyserver to use (subkeys.pgp.net).
 143 .TP
 144 MONKEYSPHERE_CHECK_KEYSERVER
 145 Whether or not to check keyserver when making gpg queries (`true').
 146 .TP
 147 MONKEYSPHERE_KNOWN_HOSTS
 148 Path to ssh known_hosts file (~/.ssh/known_hosts).
 149 .TP
 150 MONKEYSPHERE_HASH_KNOWN_HOSTS
 151 Whether or not to hash to the known_hosts file entries (`true').
 152 .TP
 153 MONKEYSPHERE_AUTHORIZED_KEYS
 154 Path to ssh authorized_keys file (~/.ssh/authorized_keys).
 155
 156 .SH FILES
 157
 158 .TP
 159 ~/.monkeysphere/monkeysphere.conf
 160 User monkeysphere config file.
 161 .TP
 162 /etc/monkeysphere/monkeysphere.conf
 163 System-wide monkeysphere config file.
 164 .TP
 165 ~/.monkeysphere/authorized_user_ids
 166 OpenPGP user IDs associated with keys that will be checked for
 167 addition to the authorized_keys file.
 168
 169 .SH AUTHOR
 170
 171 Written by Jameson Rollins <jrollins@fifthhorseman.net>, Daniel
 172 Kahn Gillmor <dkg@fifthhorseman.net>
 173
 174 .SH SEE ALSO
 175
 176 \" DELETEME
 177 \".BR monkeysphere-ssh-proxycommand (1),
 178 \".BR monkeysphere-server (8),
 179 .BR monkeysphere-host (8),
 180 .BR monkeysphere-authentication (8),
 181 .BR monkeysphere (7),
 182 .BR ssh (1),
 183 .BR ssh-add (1),
 184 .BR gpg (1)