NAME¶
monkeysphere - Monkeysphere client user interface
SYNOPSIS¶
monkeysphere 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.
SUBCOMMANDS¶
monkeysphere 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
keyserver. 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
command (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 unacceptable 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
status 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 generated. If no
key ID is specified, but only one key exists in the secret keyring, that
key will be used. The length of the generated 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
connected 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 connection 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 command 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 policy 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 monkeysphere-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 specify 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 system.
(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 ALSO¶
monkeysphere-host(8),
monkeysphere-authentication(8),
monkeysphere(7),
ssh(1),
ssh-add(1),
gpg(1)