MONKEYSPHERE-HOST(8)

📦
version 0.44 · 2 versions
, in alpine 3.24, nixos 26.05, nixpkgs unstable

💅 MONKEYSPHERE-HOST(8) — the host-key admin glow-up ✨

okay so this is a System Commands girlie, section 8, and her name is monkeysphere-host. buckle up bestie, she's iconic 💖

🎀 NAME

monkeysphere-host — the Monkeysphere host key administration tool. that's it, that's the vibe 🫶

✨ SYNOPSIS

monkeysphere-host subcommand [args]

🌸 DESCRIPTION

so Monkeysphere is this whole framework that leverages the OpenPGP web of trust for SSH and TLS key-based authentication — literally the main character of trust ✨

monkeysphere-host stores and manages OpenPGP certificates for the various services the host is offering. no cap, that's her whole job 💅

most subcommands take a KEYID argument, which identifies which certificate is to be operated upon — by OpenPGP key ID (e.g. 0xDEADBEEF) or by full OpenPGP fingerprint 🦋 and if only one certificate is currently managed by monkeysphere-host, the KEYID argument may be omitted entirely, and monkeysphere-host will just operate on it. convenient? yes. slay? also yes 👑

🔥 SUBCOMMANDS

monkeysphere-host takes various subcommands, let's go 🏃‍♀️

  • import-key FILE SCHEME://HOSTNAME[:PORT] — import an SSH host secret key from file FILE. if FILE is -, then the key gets imported from stdin, and it must be an RSA key 🔑. SCHEME://HOSTNAME[:PORT] specifies the scheme (e.g. ssh or https) and the fully-qualified hostname (and port) used in the user ID of the new OpenPGP key (e.g. ssh://example.net or https://www.example.net 🌈). if PORT is not specified, then no port is added to the user ID, which means the default port for that service is assumed (e.g. 22 for ssh) — iykyk. i may be used in place of import-key.
  • show-keys [KEYID ...] — output info about the OpenPGP certificate(s) for services offered by the host, including their KEYIDs 💖. if no KEYID is specified (or if the special string --all is used), it outputs information about all certificates managed by monkeysphere-host. s may be used in place of show-keys.
  • set-expire EXPIRE [KEYID] — extend the validity of the specified OpenPGP certificate until EXPIRE from the present ⏳. expiration is specified as with GnuPG, measured from today's date:
    • 0 = key does not expire
    • <n> = key expires in n days
    • <n>w = key expires in n weeks
    • <n>m = key expires in n months
    • <n>y = key expires in n years

e may be used in place of set-expire.

  • add-servicename SCHEME://HOSTNAME[:PORT] [KEYID] — add a service-specific user ID to the specified certificate 🎀. for example, the operator of https://example.net may wish to add an additional servicename of https://www.example.net to the certificate corresponding to the secret key used by the TLS-enabled web server. add-name or n+ may be used in place of add-servicename.
  • revoke-servicename SCHEME://HOSTNAME[:PORT] [KEYID] — revoke a service-specific user ID from the specified certificate 🙈. revoke-name or n- may be used in place of revoke-servicename.
  • add-revoker REVOKER_KEYID|FILE [KEYID] — add a revoker to the specified OpenPGP certificate 👑. the revoker can be specified by their own REVOKER_KEYID (in which case it gets loaded from an OpenPGP keyserver), or by specifying a path to a file containing the revoker's OpenPGP certificate, or by specifying - to load from stdin. r+ may be used in place of add-revoker.
  • revoke-key [KEYID] — generate (with the option to publish) a revocation certificate for the given OpenPGP certificate 💀. if such a certificate is published, the given key will be permanently revoked, and will no longer be accepted by monkeysphere-enabled clients. this subcommand asks you a series of questions, then generates a key revocation certificate, sending it to stdout. you might want to store these certificates safely offline, to publish in case of compromise. if you explicitly tell it to publish the revocation certificate immediately, it will send it to the public keyservers.
🚨 PUBLISH THESE CERTIFICATES ONLY IF YOU ARE SURE THE CORRESPONDING KEY WILL NEVER BE RE-USED! 🚨 like, fr fr, not a drill 😭
  • publish-keys [KEYID ...] — publish the specified OpenPGP certificates to the public keyservers 🌈. if the special string --all is specified, all of the host's OpenPGP certificates get published. p may be used in place of publish-keys.
⚠️ NOTE: there is no way to remove a key from the public keyservers once it is published! 😬 no take-backsies, bestie.
  • 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.
  • diagnostics — review the state of the monkeysphere server host key and report on suggested changes 🩺. among other checks, this includes making sure there's a valid host key, that the key is not expired, that the sshd configuration points to the right place, etc. d may be used in place of diagnostics.

🦋 SETUP SSH SERVER CERTIFICATES

so to enable users to verify your SSH host's key via the monkeysphere, an OpenPGP certificate must be made out of the host's RSA ssh key, and that certificate must be published to the Web of Trust ✨. certificate publication is not done by default, fyi.

first step: import the host's ssh key into a monkeysphere-style OpenPGP certificate. this is done with the import-key command. for example:

# monkeysphere-host import-key /etc/ssh/ssh_host_rsa_key ssh://host.example.org

on most systems, sshd's RSA secret key is stored at /etc/ssh/ssh_host_rsa_key 📁.

see PUBLISHING AND CERTIFYING MONKEYSPHERE SERVICE CERTIFICATES for how to make sure your users can verify the ssh service offered by your host once the key is imported into monkeysphere-host 💖

🌐 SETUP WEB SERVER CERTIFICATES

you can set up your HTTPS-capable web server so users can verify it via the monkeysphere without changing your server's software at all 🤯. you just need access to a (PEM-encoded) version of the server's RSA secret key (most secret keys are already stored PEM-encoded, so like, you're probably fine).

first step: import the web server's key into a monkeysphere-style OpenPGP certificate, via the import-key command. for example:

# monkeysphere-host import-key /etc/ssl/private/host.example.net-key.pem https://host.example.net

if you don't know where the web server's key is stored on your machine, consult the configuration files for your web server 🔍. Debian-based systems using the ssl-cert packages often have a default self-signed certificate stored in /etc/ssl/private/ssl-cert-snakeoil.key 🐍 — and if you're using that key, your users are getting browser warnings about it 😭. you can keep using the same key, but help them use the OpenPGP WoT to verify that it does belong to your web server by using something like:

# monkeysphere-host import-key /etc/ssl/private/ssl-cert-snakeoil.key https://$(hostname --fqdn)

if you offer multiple HTTPS websites using the same secret key, you should add the additional website names with the add-servicename subcommand 💅

see PUBLISHING AND CERTIFYING MONKEYSPHERE SERVICE CERTIFICATES (the next section) for how to make sure your users can verify the https service offered by your host once the key is imported and any extra site names have been added 🌸. note that you can add or remove additional servicenames at any time, but you'll need to certify any new ones separately 👀

👑 PUBLISHING AND CERTIFYING MONKEYSPHERE SERVICE CERTIFICATES

once the host key has been imported, the corresponding certificate must be published to the Web of Trust so users can retrieve the cert when connecting to the host 🌈. host certificates are published to the keyserver with the publish-key command:

$ monkeysphere-host publish-key --all

in order for users accessing the system to be able to identify the host's service via the monkeysphere, at least one person (e.g. a server admin) needs to sign the host's certificate ✍️. this is done using standard OpenPGP keysigning techniques. usually: pull the host's OpenPGP certificate from the keyserver, verify and sign it, then re-publish your signature 💖. more than one person can certify any certificate — the more the merrier, honestly 🫶.

please see https://web.monkeysphere.info/doc/host-keys/ for more information and details 📚.

once an admin's signature is published, users accessing the host can use the certificate to validate the host's key without having to manually check the host key's fingerprint (in the case of ssh) or without seeing a nasty "security warning" in their browsers (in the case of https) 😌✨ iconic behavior, truly.

💀 SECURITY CONSIDERATIONS

heads up: monkeysphere-host currently caches a copy of all imported secret keys (stored in OpenPGP form for future manipulation) in /var/lib/monkeysphere/host/ 🔐.

cleartext backups of files in this directory could expose secret key material if not handled sensitively. like, be careful, bestie 😭

🌱 ENVIRONMENT

the following environment variables override those specified in the config 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_KEYSERVER — OpenPGP keyserver to use. (pool.sks-keyservers.net)
  • MONKEYSPHERE_PROMPT — if set to false, never prompt the user for confirmation. (true)

📁 FILES

  • /etc/monkeysphere/monkeysphere-host.conf — system monkeysphere-host config file 🗂️
  • /var/lib/monkeysphere/host_keys.pub.pgp — a world-readable copy of the host's OpenPGP certificates in ASCII armored format ✨. this includes the certificates (including the public keys, servicename-based User IDs, and most recent relevant self-signatures) corresponding to every key used by Monkeysphere-enabled services on the host.
  • /var/lib/monkeysphere/host/ — a locked directory (readable only by the superuser) containing copies of all imported secret keys — this is the host's GNUPGHOME directory 🔒
  • /etc/monkeysphere/monkeysphere-host-x509-anchors.crt or /etc/monkeysphere/monkeysphere-x509-anchors.crt — if monkeysphere-host is configured to query an hkps keyserver for publish-keys, it will use the PEM-encoded X.509 Certificate Authority certificates in this file to validate any X.509 certificates used by the keyserver 🧚. if the monkeysphere-host-x509 file is present, the monkeysphere-x509 file will be ignored.

🫶 AUTHOR

this man page was written by: Jameson Rollins <jrollins@finestructure.net>, Daniel Kahn Gillmor <dkg@fifthhorseman.net>, Matthew Goins <mjgoins@openflows.com> — absolute legends, all three 💜

🔗 SEE ALSO

monkeysphere(1), monkeysphere(7), gpg(1), monkeysphere-authentication(8), ssh(1), sshd(8)

okay that's the whole page, go be a host-key icon 👑💅

~ brought to you by monkeysphere, dated January 2010, filed under MONKEYSPHERE-HOST(8) — periodt. 🎀✨

📦 where this page comes from