X-Git-Url: https://codewiz.org/gitweb?a=blobdiff_plain;f=website%2Fgetting-started-admin.mdwn;h=ab0acc6af8198c18544ecfbd8d4c9680dc89f848;hb=71d180394c3357d2a99e9f1fc6a2fa7514552da9;hp=1c373acffa1883d8de5f1ec351fa8dd33bb84697;hpb=647a0fc70e28d641d914f183489d815d4feb7e2b;p=monkeysphere.git diff --git a/website/getting-started-admin.mdwn b/website/getting-started-admin.mdwn index 1c373ac..ab0acc6 100644 --- a/website/getting-started-admin.mdwn +++ b/website/getting-started-admin.mdwn @@ -1,88 +1,182 @@ Monkeysphere Server Administrator README ======================================== + Note: This documentation is for Monkeysphere version 0.28 or later. + If you are running a version prior to 0.28, we recommend that you upgrade. + As the administrator of an SSH server, you can take advantage of the -monkeysphere in two ways: you can publish the host key of your machine -so that your users can have it automatically verified, and you can set -up your machine to automatically identify connecting users by their -presence in the OpenPGP web of trust. +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 generate and publish a server host key: - # monkeysphere-server gen-key - # monkeysphere-server publish-key +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 ssh://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, +(e.g. `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: -This will generate the key for server with the service URI -(`ssh://server.example.net`). 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: + # 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! -Update OpenSSH configuration files ----------------------------------- +Next, find out your key's Key ID, which is a hexadecimal string like "ABCDEF19" -To use the newly-generated host key for ssh connections, put the -following line in `/etc/ssh/sshd_config` (be sure to remove references -to any other keys): + $ gpg --list-keys '=ssh://server.example.net' - HostKey /var/lib/monkeysphere/ssh_host_rsa_key +which will output something like: -FIXME: should we just suggest symlinks in the filesystem here instead? + pub 2048R/ABCDEF19 2009-05-07 + uid [ full ] ssh://server.example.net -FIXME: What about DSA host keys? The SSH RFC seems to require implementations support DSA, though OpenSSH will work without a DSA host key. +Finally, publish your signatures back to the keyservers, so that your +users can automatically verify your machine when they connect: -To enable users to use the monkeysphere to authenticate using the -OpenPGP web of trust, add this line to `/etc/ssh/sshd_config` (again, -making sure that no other AuthorizedKeysFile directive exists): + $ gpg --send-key ABCDEF19 - AuthorizedKeysFile /var/lib/monkeysphere/authorized_keys/%u +See http://web.monkeysphere.info/signing-host-keys/ for more info +signing host keys. + +Monkeysphere for user authentication (monkeysphere-authentication) +================================================================== -And then read the section below about how to ensure these files are -maintained. 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. +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 ---------------------------------------- -A host can maintain ssh authorized_keys files automatically for its -users with the Monkeysphere. - For each user account on the server, the userids of people authorized -to log into that account would be placed in: +to log into that account would be placed, one per line, 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 trusted identity certifer. -If the admin's OpenPGP keyid is `$GPGID`, then on the server run: +For example, this file could contain: + + Joe User + Joe User at Work + +Provided that those exact strings are among the uids for which the user's gpg +key is valid. + +The server will use the Monkeysphere to look up matching OpenPGP +certificates, validate them, and generate an `authorized_keys` file. - # monkeysphere-server add-identity-certifier $GPGID +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. -To update the monkeysphere authorized_keys file for user "bob" using -the current set of identity certifiers, run: +You will need to know your full 40 hex character gpg fingerprint. This can be learned by doing: - # monkeysphere-server update-users bob + gpg --with-colons --fingerprint user@example.org -To update the monkeysphere authorized_keys file for all users on the +Replacing "user@example.org" with either your gpg key id, or your gpg uid. +The output of this command is very long and difficult to read. Look for a line like: + + fpr:::::::::D8E6414012D371BFC5AB8E2540D6B49E0E708ADF: + +The portion between the ":::::::::" and ":" is your 40 digit fingerprint. + +With your OpenPGP 40-digit hex fingerprint replacing `$GPGFPR`, then +run the following command on the server: + + # monkeysphere-authentication add-identity-certifier $GPGFPR + +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-server update-users + # monkeysphere-authentication update-users You probably want to set up a regularly scheduled job (e.g. with cron) -to take care of this automatically. +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 + +Warning: Be aware that with this change in configuration, only those users whose +authorized keys files appear under the above path will be able to log in via +ssh. This includes the root user if root has ssh access. Remember to run +'monkeysphere-authentication update-users' if you are unsure whether any users' +authorized_keys files have been updated. -FIXME: document other likely problems and troubleshooting techniques +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.