+++ /dev/null
-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.
projects / monkeysphere.git / blobdiff