MONKEYSPHERE(1) User Commands MONKEYSPHERE(1)NAMEmonkeysphere - Monkeysphere client user interface
SYNOPSISmonkeysphere 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.
SUBCOMMANDSmonkeysphere 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 key‐
server. 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 com‐
mand (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 unac‐
ceptable 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 sta‐
tus 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 gener‐
ated. If no key ID is specified, but only one key exists in the
secret keyring, that key will be used. The length of the gener‐
ated 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 con‐
nected 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 con‐
nection 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 com‐
mand 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.
KEYSERVER CHECKING: The proxy command has a fairly nuanced pol‐
icy 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 monkey‐
sphere-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 spec‐
ify 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 sys‐
tem. (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 ALSOmonkeysphere-host(8), monkeysphere-authentication(8), monkeysphere(7),
ssh(1), ssh-add(1), gpg(1)monkeysphere June 2008 MONKEYSPHERE(1)
