This guide aims to be a simple bullet-point introduction to Monkeysphere. It doesn't mean to rival with the full documentation but merely provide a quick way for new users to get started with the Monkeysphere and SSH.

Users

There are two different things you can do here: allow other users to verify your SSH key through the OpenPGP web of trust or verify server SSH keys through the OpenPGP web of trust.

This is an abbreviated guide, more information in the complete guide.

Creating a SSH key signed with your OpenPGP key

This will generate a subkey for your main OpenPGP key that will be signed with that key. That way, other admins can verify your SSH key through the OpenPGP web of trust.

To setup your key, do this once:

# generate a new SSH key signed by your OpenPGP key
monkeysphere gen-subkey
# send your new subkey to the keyservers, optional
gpg --send-keys <keyid>

Then to use that key, you need to add it to your running ssh-agent (which you should already be using):

# add the key material to the agent
monkeysphere s

Checking servers through the OpenPGP web of trust

Add this to your ~/.ssh/config:

Host *
    ProxyCommand monkeysphere ssh-proxycommand %h %p

This will check the SSH key of the server against the OpenPGP web of trust if the server is thus ceritified.

Admins

As a server administrator, you can also make sure people can verify the SSH key of your server through the OpenPGP web of trust.

This is just the start! You can also use monkeysphere to verify SSH keys of users, which will allow users to revoke certificates and so on, see the complete guide for more information.

Publishing a server's SSH key on the web of trust

This will publish the SSH key of a server into the OpenPGP web of trust.

# import the server RSA key in monkeysphere
monkeysphere-host import-key /etc/ssh/ssh_host_rsa_key ssh://server.example.net
# push the key to the keyservers
monkeysphere-host publish-key
# check the resulting fingerprint
monkeysphere-host show-key

Now on a machine where you have a good certification key:

# download the key, use the fingerprint from `show-key` taken from a secure channel
gpg --recv-key <fingerprint>
# sign the key
gpg --sign-key <fingerprint>
# send the key back to the keyservers
gpg --send-key <fingerprint>

Authenticating users with the web of trust

You can also simply allow users to manage their SSH credentials through the OpenPGP web of trust directly, without having to manually populate the authorized_keys file (which is still supported).

The following should get Monkeysphere keys hooked into your SSH server configuration:

# add yourself (the admin of the server) as a certifier
monkeysphere-authentication add-identity-certifier $YOUR_FINGERPRINT
# tell OpenSSH to use the Monkeysphere SSH keys in addition to `authorized_keys`
if echo "AuthorizedKeysFile foo bar" | /usr/sbin/sshd -t -f /dev/stdin; then
  # OpenSSH 6.0 and later, multiple authorized_keys supported
  sed -i '/^AuthorizedKeysFile/s!^.*$!AuthorizedKeysFile .ssh/authorized_keys .ssh/authorized_keys2 /var/lib/monkeysphere/authorized_keys/%u!' /etc/ssh/sshd_config
  echo "RAW_AUTHORIZED_KEYS='none'" >> /etc/monkeysphere/monkeysphere-authentication.conf
else
  # OpenSSH 5.5 and earlier - only one authorized_keys available
  sed -i '/^AuthorizedKeysFile/s!^.*$!AuthorizedKeysFile /var/lib/monkeysphere/authorized_keys/%u!' /etc/ssh/sshd_config
fi
# update the SSH keys based on the OpenPGP web of trust
monkeysphere-authentication update-users
# restart OpenSSH
service openssh reload

Then users can specify which OpenPGP key to use for their account like this:

# specify which OpenPGP key to user for user Alice
echo 'Alice <alice@example.net>' >> ~alice/.monkeysphere/authorized_user_ids

In the example above, user Alice <alice@example.net> need to have their key signed by you, the certifier. They can change which key is used (and revoke it), naturally, but it still requires that key to be signed by you, the certifier (and multiple certifiers can be added with the first command).

Warning: notice how this will replace your current AuthorizedKeys configuration. If there are problems in your Monkeysphere configuration, the SSH keys you currently use on the server may STOP WORKING. Normally, the current authorized_keys file gets appended to Monkeysphere's configuration, but to be safe, make sure you keep a way to login to the server while you test the migration.

Also note that changes will not take effect until monkeysphere-authentication update-users is ran, so you probably want to create a cronjob somewhat like this:

0 * * * * /usr/sbin/monkeysphere-authentication update-users

This will expire, revoke or import keys once per hour. To avoid load on your infrastructure or the central key servers, you should probably spread that time evenly across different servers (ie. change 0 for something else, above).

Manually extracting Monkeysphere RSA keys

If, for some reason, you don't want to or can't deploy Monkeysphere server-wide, you can still use it to authenticate users.

Provided that you have Monkeysphere installed somewhere and that the OpenPGP key of the target user is verified in some way through the web of trust, the following command should output the SSH public keys for the user:

monkeysphere u 'Alice <alice@example.net>'