summaryrefslogtreecommitdiff
path: root/website/getting-started-admin.mdwn
blob: bff1773a9676a05057cf601ac849cca11b353f7f (plain)

Monkeysphere Server Administrator README

Note: This documentation is for Monkeysphere version 0.23 or later.
If you are running a version prior to 0.23, we recommend that you upgrade.

As the administrator of an SSH server, you can take advantage of the Monkeysphere in two ways:

  1. you can publish the host key of your machine to the Web of Trust (WoT) so that your users can automatically verify it, and

  2. you can set up your machine to automatically identify connecting users by their presence in the OpenPGP Web of Trust.

These two pieces are independent: you can do one without the other.

Monkeysphere for host verification (monkeysphere-host)

Server host key publication

To begin, you must first import an ssh host key. This assumes that you have the ssh server installed, and that you have generated a host RSA key. Once that has been done, import the key:

# monkeysphere-host import-key /etc/ssh/ssh_host_rsa_key server.example.net

This will generate an OpenPGP certificate for the server. The primary user ID for this certificate will be the ssh service URI for the host, (eg. ssh://server.example.net). Remember that the name you provide here should probably be a fully qualified domain name for the host in order for your users to find it.

Now you can display information about the host key's certificate with the 'show-key' command:

# monkeysphere-host show-key

Once the host key's certificate has been generated, you'll probably want to publish it to the public keyservers which distribute the Web of Trust:

# monkeysphere-host publish-key

But anyone could publish a simple self-signed certificate to the WoT with any name attached. Your users should be able to tell that someone they know and trust with the machine (e.g. you, the administrator) has verified that this particular key is indeed the correct key. So your next step is to sign the host's key with your own OpenPGP key.

On your (the admin's) local machine retrieve the host key (it may take several minutes for the key to propagate across the keyserver network), and sign it:

$ gpg --search '=ssh://server.example.net'
$ gpg --sign-key '=ssh://server.example.net'

Make sure you compare the fingerprint of the retrieved certificate with the output from the 'show-key' command above!

Finally, publish your signatures back to the keyservers, so that your users can automatically verify your machine when they connect:

$ gpg --send-key '=ssh://server.example.net'

See http://web.monkeysphere.info/signing-host-keys/ for more info signing host keys.

Monkeysphere for user authentication (monkeysphere-authentication)

A host can maintain ssh-style authorized_keys files automatically for its users with the Monkeysphere. This frees you (the administrator) from the task of manually checking/placing SSH keys, and enables users to do relatively painless key transitions, and to quickly and universally revoke access if they find that their ssh key has become compromised.

You simply tell the system what person (identified by her OpenPGP User ID) should have access to an account, the Monkeysphere takes care of generating the proper authorized_keys file and keeping it up-to-date, and sshd reads the generated authorized_keys files directly.

Monkeysphere authorized_keys maintenance

For each user account on the server, the userids of people authorized to log into that account would be placed in:

~/.monkeysphere/authorized_user_ids

The server will use the Monkeysphere to look up matching OpenPGP certificates, validate them, and generate an authorized_keys file.

To validate the OpenPGP certificates, the server needs to know who it can trust to correctly identify users. The individuals trusted to identify users like this are known in the Monkeysphere as "Identity Certifiers". One obvious choice is to trust you, the administrator, to be an Identity Certifier. If your OpenPGP keyid is $GPGID, then run the following command on the server:

# monkeysphere-authentication add-identity-certifier $GPGID

You'll probably only set up Identity Certifiers when you set up the machine. After that, you'll only need to add or remove Identity Certifiers when the roster of admins on the machine changes, or when one of the admins switches OpenPGP keys.

Now that the server knows who to trust to identify users, the Monkeysphere can generate ssh-style authorized_keys quickly and easily:

To update the Monkeysphere-generated authorized_keys file for user "bob", run:

# monkeysphere-authentication update-users bob

To update the monkeysphere authorized_keys file for all users on the the system, run the same command with no arguments:

# monkeysphere-authentication update-users

You probably want to set up a regularly scheduled job (e.g. with cron) to do this automatically.

Update OpenSSH server AuthorizedKeysFile configuration

Generating the authorized_keys files is not quite enough, because sshd needs to know where to find the generated keys.

You can do this by adding the following line to /etc/ssh/sshd_config, commenting out any other AuthorizedKeysFile directives:

AuthorizedKeysFile /var/lib/monkeysphere/authorized_keys/%u

You'll need to restart sshd to have your changes take effect. As with any change to sshd_config, if you're doing this remotely, be sure to retain an existing session to the machine while you test your changes so you don't get locked out if something went wrong.