Monkeysphere Server Administrator README
========================================
-FIXME: distinguish between publishing a new monkeysphere-enabled host
-key and accepting user identification via the web-of-trust.
+ 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:
-server service publication
---------------------------
-To publish a server host key:
+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
- # monkeysphere-server gen-key
- # monkeysphere-server publish-key
+2. you can set up your machine to automatically identify connecting
+users by their presence in the OpenPGP Web of Trust.
-This will generate the key for server with the service URI
-(ssh://server.hostname). The server admin should now sign the server
-key so that people in the admin's web of trust can authenticate the
-server without manual host key checking:
+These two pieces are independent: you can do one without the other.
- $ gpg --search ='ssh://server.hostname'
- $ gpg --sign-key ='ssh://server.hostname'
+Monkeysphere for host verification (monkeysphere-host)
+======================================================
+Server host key publication
+---------------------------
-Update OpenSSH configuration files
-----------------------------------
+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:
-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 key):
+ # monkeysphere-host import-key /etc/ssh/ssh_host_rsa_key server.example.net
- HostKey /var/lib/monkeysphere/ssh_host_rsa_key
+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.
-FIXME: should we just suggest symlinks in the filesystem here instead?
+Now you can display information about the host key's certificate with
+the 'show-key' command:
-FIXME: What about DSA host keys? The SSH RFC seems to require that DSA be available, though OpenSSH will work without a DSA host key.
+ # monkeysphere-host show-key
-To enable users to use the monkeysphere to authenticate against the
-web-of-trust, add this line to /etc/ssh/sshd_config (again, making
-sure that no other AuthorizedKeysFile directive exists):
+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:
- AuthorizedKeysFile /var/lib/monkeysphere/authorized_keys/%u
+ # 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.
-MonkeySphere authorized_keys maintenance
-----------------------------------------
+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:
-A system can maintain monkeysphere authorized_keys files for it's
-users.
+ $ 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 in:
+to log into that account would be placed, one per line, in:
+
+ ~/.monkeysphere/authorized_user_ids
+
+For example, this file could contain:
- ~/.config/monkeysphere/authorized_user_ids
+ Joe User <joe@example.net>
+ Joe User at Work <joe@example.org>
-However, in order for users to become authenticated, the server must
-determine that the user 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 user. This would generally be
-the server admin. If the server admin's keyid is XXXXXXXX, then on
-the server run:
+Provided that those exact strings are among the uids for which the user's gpg
+key is valid.
- # monkeysphere-server add-identity-certifier XXXXXXXX
+The server will use the Monkeysphere to look up matching OpenPGP
+certificates, validate them, and generate an `authorized_keys` file.
-To update the monkeysphere authorized_keys file for user "bob", the
-system would then run the following:
+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.
- # monkeysphere-server update-users bob
+You will need to know your full 40 hex character gpg fingerprint. This can be learned by doing:
-To update the monkeysphere authorized_keys file for all users on the
+ 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-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 regularly.
+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.
projects / monkeysphere.git / blobdiff