diff options
Diffstat (limited to 'website/getting-started-admin.mdwn')
| -rw-r--r-- | website/getting-started-admin.mdwn | 182 |
1 files changed, 0 insertions, 182 deletions
diff --git a/website/getting-started-admin.mdwn b/website/getting-started-admin.mdwn deleted file mode 100644 index ab0acc6..0000000 --- a/website/getting-started-admin.mdwn +++ /dev/null @@ -1,182 +0,0 @@ -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: - -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 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: - - # 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! - -Next, find out your key's Key ID, which is a hexadecimal string like "ABCDEF19" - - $ gpg --list-keys '=ssh://server.example.net' - -which will output something like: - - pub 2048R/ABCDEF19 2009-05-07 - uid [ full ] ssh://server.example.net - -Finally, publish your signatures back to the keyservers, so that your -users can automatically verify your machine when they connect: - - $ gpg --send-key ABCDEF19 - -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, one per line, in: - - ~/.monkeysphere/authorized_user_ids - -For example, this file could contain: - - Joe User <joe@example.net> - Joe User at Work <joe@example.org> - -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. - -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. - -You will need to know your full 40 hex character gpg fingerprint. This can be learned by doing: - - gpg --with-colons --fingerprint user@example.org - -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-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 - -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. - -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. |