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