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