MONKEYSPHERE(1)

💖 MONKEYSPHERE 💖

okay so bestie, welcome to the Monkeysphere client — section 1 of the user commands, and honestly? she's iconic. this is the girl you actually talk to on the command line. 🐒✨

---

✨ NAME ✨

monkeysphere — the Monkeysphere client user interface, aka the group chat where you and your keys finally talk to each other 💅

---

🌸 SYNOPSIS 🌸

monkeysphere subcommand [args]

---

🦋 DESCRIPTION 🦋

so. Monkeysphere is a framework that leverages the OpenPGP web of trust for OpenSSH and TLS key-based authentication. that's the whole vibe. 🫶

OpenPGP keys get tracked via GnuPG, and then they get added to the authorized_keys and known_hosts files that OpenSSH uses for connection authentication. like, your keys are in the files now. main character behavior. 👑

Monkeysphere can also be used by a validation agent to validate TLS connections (think https). yes queen, even your browser traffic. 🌈

and monkeysphere itself? that's the Monkeysphere client utility. that's the one you're looking at right now. hi. 💖

---

🎀 SUBCOMMANDS 🎀

monkeysphere takes various subcommands (one per bullet, no skipping, i don't make the rules):

• update-known_hosts [HOST]... — updates the known_hosts file. for each host you name, gpg gets queried for a key associated with the host URI (see HOST IDENTIFICATION in monkeysphere(7)), and it optionally queries a keyserver too. if an acceptable key is found for the host (see KEY ACCEPTABILITY in monkeysphere(7)), the key gets added to your known_hosts file. if a key is found but it's unacceptable for the host, any matching keys get removed from your known_hosts file. if no gpg key is found for the host, nothing happens — no drama. if you specify no hosts at all, then all hosts listed in the known_hosts file get processed. 🧚

exit status tea: 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. also k may be used in place of update-known_hosts. iykyk.

• update-authorized_keys — updates the authorized_keys file for the user executing the command (see MONKEYSPHERE_AUTHORIZED_KEYS in ENVIRONMENT, below). first, all monkeysphere keys get cleared out of the authorized_keys file. then, for each user ID in your authorized_user_ids file, gpg gets 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 gets added to your authorized_keys file. if a key is found but it's unacceptable for the user ID, any matching keys get removed from your authorized_keys file. if no gpg key is found for the user ID, nothing is done. ✨

exit status tea: 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. periodt.

• gen-subkey [KEYID] — generates an authentication subkey for a private key in your GnuPG keyring. KEYID is the key ID for the primary key that the subkey with "authentication" capability will be generated for. if you don't specify a key ID, but only one key exists in the secret keyring, that key gets 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. slay. 🔥
• 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 you're connecting to with ssh. how? it updates 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". you can do that either 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. for example, in ~/.ssh/config:

ProxyCommand sh -c 'monkeysphere ssh-proxycommand --no-connect %h
%p ; ssh -W %h:%p jumphost.example.net'

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 your keyring or in the known_hosts file, then the keyserver is queried for the host userID.
• if the host userID is found in your 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 your 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] — pushes 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 — outputs to stdout all acceptable keys for a given user ID. u may be used in place of keys-for-userid. 💖
• sshfprs-for-userid USERID — outputs the ssh fingerprints of acceptable keys for a given user ID. 🍓
• version — shows the monkeysphere version number. v may be used in place of version. ⭐
• help — outputs 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 are in parentheses, bestie):

• MONKEYSPHERE_LOG_LEVEL — sets 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 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)

bestie. i am begging you. loose permissions = other people on the box can mess with you. this one is not a vibe. 😭

• 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> — legends, fr fr. 🫶

---

👑 SEE ALSO 👑

monkeysphere-host(8), monkeysphere-authentication(8), monkeysphere(7), ssh(1), ssh-add(1), gpg(1)

---

okay that's the whole page, no cap. this beauty is monkeysphere from June 2008, and she's still serving. go read the other pages too, they're all in the same friend group. bye bestie, stay encrypted 💖✨🌸

MONKEYSPHERE(1) 💅