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

Monkeysphere Server Administrator README

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 have it automatically verified, and

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

These things are not mutually required, and it is in fact possible to do one without the other. However, it is highly recommend that you at least do the first. Even if you decide that you do not want to use the monkeysphere to authenticate users to your system, you should at least the host key into the Web of Trust so that your users can be sure they're connecting to the correct machine.

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 /etc/ssh/ssh\_host\_rsa\_key

This will generate the key for server with the service URI (ssh://server.example.net). You can output the new key information with the 'show-key' command:

# monkeysphere-host show-key

Once the key has been imported, it needs to be publish to the Web of Trust:

# monkeysphere-host publish-key

The server admin should now sign the server key so that people in the admin's web of trust can identify the server without manual host key checking. On your (the admin's) local machine retrieve the host key:

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

Now sign the server key:

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

Make sure you compare the fingerprint of the retrieved with the one output with the 'show-key' command above, to verify you are signing the correct key. Finally, publish your signatures back to the keyservers:

$ 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 authorized_keys files automatically for its users with the Monkeysphere. These authorized_keys files can then be used to enable users to use the monkeysphere to authenticate to your machine using the OpenPGP web of trust.

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

However, in order for users to become authenticated, the server must determine that the user IDs on their keys have "full" validity. This means that the server must fully trust at least one person whose signature on the connecting user's key would validate the relevant user ID. The individuals trusted to identify users like this are known in the Monkeysphere as "Identity Certifiers". In a simple scenario, the host's administrator would be a trusted identity certifer. If the admin's OpenPGP keyid is $GPGID, then on the server run:

# monkeysphere-authentication add-identity-certifier $GPGID

To update the monkeysphere authorized_keys file for user "bob" using the current set of identity certifiers, 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 take care of this automatically.

Update OpenSSH server AuthorizedKeysFile configuration

SSH must be configured to point to the monkeysphere generated authorized_keys file. Add this line to /etc/ssh/sshd_config (again, making sure that no other AuthorizedKeysFile directive is left uncommented):

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, be sure to retain an existing session to the machine while you test your changes so you don't get locked out.