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 and TLS key-based authentication.  OpenPGP keys are
  15 tracked via GnuPG, and added to the authorized_keys and known_hosts
  16 files used by OpenSSH for connection authentication.  Monkeysphere can
  17 also be used by a validation agent to validate TLS connections
  18 (e.g. https).
  19
  20 \fBmonkeysphere\fP is the Monkeysphere client utility.
  21
  22 .SH SUBCOMMANDS
  23
  24 \fBmonkeysphere\fP takes various subcommands:
  25 .TP
  26 .B update\-known_hosts [HOST]...
  27 Update the known_hosts file.  For each specified host, gpg will be
  28 queried for a key associated with the host URI (see HOST
  29 IDENTIFICATION in
  30 .BR monkeysphere(7)),
  31 optionally querying a keyserver.
  32 If an acceptable key is found for the host (see KEY ACCEPTABILITY in
  33 .BR monkeysphere(7)),
  34 the key is added to the user's known_hosts file.  If a key is found
  35 but is unacceptable for the host, any matching keys are removed from
  36 the user's known_hosts file.  If no gpg key is found for the host,
  37 nothing is done.  If no hosts are specified, all hosts listed in the
  38 known_hosts file will be processed.  This subcommand will exit with a
  39 status of 0 if at least one acceptable key was found for a specified
  40 host, 1 if no matching keys were found at all, and 2 if matching keys
  41 were found but none were acceptable.  `k' may be used in place of
  42 `update\-known_hosts'.
  43 .TP
  44 .B update\-authorized_keys
  45 Update the authorized_keys file for the user executing the command
  46 (see MONKEYSPHERE_AUTHORIZED_KEYS in ENVIRONMENT, below).  First all
  47 monkeysphere keys are cleared from the authorized_keys file.  Then,
  48 for each user ID in the user's authorized_user_ids file, gpg will be
  49 queried for keys associated with that user ID, optionally querying a
  50 keyserver.  If an acceptable key is found (see KEY ACCEPTABILITY in
  51 .BR monkeysphere (7)),
  52 the key is added to the user's authorized_keys file.
  53 If a key is found but is unacceptable for the user ID, any matching
  54 keys are removed from the user's authorized_keys file.  If no gpg key
  55 is found for the user ID, nothing is done.  This subcommand will exit
  56 with a status of 0 if at least one acceptable key was found for a user
  57 ID, 1 if no matching keys were found at all, and 2 if matching keys
  58 were found but none were acceptable.  `a' may be used in place of
  59 `update\-authorized_keys'.
  60 .TP
  61 .B gen\-subkey [KEYID]
  62 Generate an authentication subkey for a private key in your GnuPG
  63 keyring.  KEYID is the key ID for the primary key for which the subkey
  64 with "authentication" capability will be generated.  If no key ID is
  65 specified, but only one key exists in the secret keyring, that key
  66 will be used.  The length of the generated key can be specified with
  67 the `\-\-length' or `\-l' option.  `g' may be used in place of
  68 `gen\-subkey'.
  69 .TP
  70 .B ssh\-proxycommand [--no-connect] HOST [PORT]
  71 An ssh ProxyCommand that can be used to trigger a monkeysphere update
  72 of the ssh known_hosts file for a host that is being connected to with
  73 ssh.  This works by updating the known_hosts file for the host first,
  74 before an attempted connection to the host is made.  Once the
  75 known_hosts file has been updated, a TCP connection to the host is
  76 made by exec'ing netcat(1).  Regular ssh communication is then done
  77 over this netcat TCP connection (see ProxyCommand in ssh_config(5) for
  78 more info).
  79
  80 This command is meant to be run as the ssh "ProxyCommand".  This can
  81 either be done by specifying the proxy command on the command line:
  82
  83 .B ssh \-o ProxyCommand="monkeysphere ssh\-proxycommand %h %p" ...
  84
  85 or by adding the following line to your ~/.ssh/config script:
  86
  87 .B ProxyCommand monkeysphere ssh\-proxycommand %h %p
  88
  89 The script can easily be incorporated into other ProxyCommand scripts
  90 by calling it with the "\-\-no\-connect" option, i.e.:
  91
  92 .B monkeysphere ssh\-proxycommand \-\-no\-connect "$HOST" "$PORT"
  93
  94 This will run everything except the final exec of netcat to make the
  95 TCP connection to the host.  In this way this command can be added to
  96 another proxy command that does other stuff, and then makes the
  97 connection to the host itself.
  98
  99 KEYSERVER CHECKING:
 100 The proxy command has a fairly nuanced policy for when keyservers are
 101 queried when processing a host.  If the host userID is not found in
 102 either the user's keyring or in the known_hosts file, then the
 103 keyserver is queried for the host userID.  If the host userID is found
 104 in the user's keyring, then the keyserver is not checked.  This
 105 assumes that the keyring is kept up-to-date, in a cronjob or the like,
 106 so that revocations are properly handled.  If the host userID is not
 107 found in the user's keyring, but the host is listed in the known_hosts
 108 file, then the keyserver is not checked.  This last policy might
 109 change in the future, possibly by adding a deferred check, so that
 110 hosts that go from non-monkeysphere-enabled to monkeysphere-enabled
 111 will be properly checked.
 112
 113 Setting the CHECK_KEYSERVER variable in the config file or the
 114 MONKEYSPHERE_CHECK_KEYSERVER environment variable to either `true' or
 115 `false' will override the keyserver-checking policy defined above and
 116 either always or never check the keyserver for host key updates.
 117
 118 .TP
 119 .B subkey\-to\-ssh\-agent [ssh\-add arguments]
 120 Push all authentication-capable subkeys in your GnuPG secret keyring
 121 into your running ssh-agent.  Additional arguments are passed through
 122 to
 123 .BR ssh\-add (1).
 124 For example, to remove the authentication subkeys, pass an additional
 125 `\-d' argument.  To require confirmation on each use of the key, pass
 126 `\-c'.  The MONKEYSPHERE_SUBKEYS_FOR_AGENT environment can be used to
 127 specify the full fingerprints of specific keys to add to the agent
 128 (space separated), instead of adding them all.  `s' may be used in
 129 place of `subkey\-to\-ssh\-agent'.
 130 .TP
 131 .B sshfpr KEYID
 132 Output the ssh fingerprint of a key in your gpg keyring. `f' may be
 133 used in place of `fingerprint'.
 134 .TP
 135 .B keys\-for\-userid USERID
 136 Output to stdout all acceptable keys for a given user ID literal.
 137 `u' may be used in place of `keys\-for\-userid'.
 138 .TP
 139 .B version
 140 Show the monkeysphere version number.  `v' may be used in place of
 141 `version'.
 142 .TP
 143 .B help
 144 Output a brief usage summary.  `h' or `?' may be used in place of
 145 `help'.
 146
 147 .SH ENVIRONMENT
 148
 149 The following environment variables will override those specified in
 150 the monkeysphere.conf configuration file (defaults in parentheses):
 151 .TP
 152 MONKEYSPHERE_LOG_LEVEL
 153 Set the log level.  Can be SILENT, ERROR, INFO, VERBOSE, DEBUG,
 154 in increasing order of verbosity. (INFO)
 155 .TP
 156 MONKEYSPHERE_GNUPGHOME, GNUPGHOME
 157 GnuPG home directory. (~/.gnupg)
 158 .TP
 159 MONKEYSPHERE_KEYSERVER
 160 OpenPGP keyserver to use. (pool.sks-keyservers.net)
 161 .TP
 162 MONKEYSPHERE_CHECK_KEYSERVER
 163 Whether or not to check keyserver when making gpg queries. (true)
 164 .TP
 165 MONKEYSPHERE_KNOWN_HOSTS
 166 Path to ssh known_hosts file. (~/.ssh/known_hosts)
 167 .TP
 168 MONKEYSPHERE_HASH_KNOWN_HOSTS
 169 Whether or not to hash to the known_hosts file entries. (true)
 170 .TP
 171 MONKEYSPHERE_AUTHORIZED_KEYS
 172 Path to ssh authorized_keys file. (~/.ssh/authorized_keys)
 173 .TP
 174 MONKEYSPHERE_PROMPT
 175 If set to `false', never prompt the user for confirmation. (true)
 176 .TP
 177 MONKEYSPHERE_STRICT_MODES
 178 If set to `false', ignore too-loose permissions on known_hosts,
 179 authorized_keys, and authorized_user_ids files.  NOTE: setting this to
 180 false may expose you to abuse by other users on the system. (true)
 181 .TP
 182 MONKEYSPHERE_SUBKEYS_FOR_AGENT
 183 A space-separated list of authentication-capable subkeys to add to the
 184 ssh agent with subkey-to-ssh-agent.
 185
 186 .SH FILES
 187
 188 .TP
 189 ~/.monkeysphere/monkeysphere.conf
 190 User monkeysphere config file.
 191 .TP
 192 /etc/monkeysphere/monkeysphere.conf
 193 System-wide monkeysphere config file.
 194 .TP
 195 ~/.monkeysphere/authorized_user_ids
 196 A list of OpenPGP user IDs, one per line.  OpenPGP keys with an
 197 exactly-matching User ID (calculated valid by the designated identity
 198 certifiers), will have any valid authorization-capable keys or subkeys
 199 added to the given user's authorized_keys file.
 200
 201 .SH AUTHOR
 202
 203 Written by:
 204 Jameson Rollins <jrollins@fifthhorseman.net>,
 205 Daniel Kahn Gillmor <dkg@fifthhorseman.net>
 206
 207 .SH SEE ALSO
 208
 209 .BR monkeysphere\-host (8),
 210 .BR monkeysphere\-authentication (8),
 211 .BR monkeysphere (7),
 212 .BR ssh (1),
 213 .BR ssh\-add (1),
 214 .BR gpg (1)