Monkeysphere User README
========================
+ 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.
+
You don't have to be an OpenSSH or OpenPGP expert to use the
Monkeysphere. However, you should be comfortable using secure shell
-(ssh), and you should already have GnuPG installed and an OpenPGP key
-pair before you begin.
-
-As a regular user on a system where the monkeysphere package is
-installed, you probably want to do a few things:
-
-
-Keep your keyring up-to-date
-----------------------------
+(ssh), and you should already have an OpenPGP key before you begin.
-Regularly refresh your GnuPG keyring from the keyservers. This can be
-done with a simple cronjob. An example of crontab line to do this is:
+As a user, the Monkeysphere lets you do two important things:
- 0 12 * * * /usr/bin/gpg --refresh-keys > /dev/null 2>&1
+1. You can use the OpenPGP Web of Trust (WoT) to automatically verify
+the identity of hosts you connect to.
-This would refresh your keychain every day at noon.
+2. You can manage your own ssh identity on all Monkeysphere-enabled
+servers using the WoT.
+These two features are independent: you can do one without the other.
-Keeping your `known_hosts` file in sync with your keyring
------------------------------------------------------------
-With your keyring updated, you want to make sure that OpenSSH can
-still see the most recent trusted information about who the various
-hosts are. This can be done with the monkeysphere-ssh-proxycommand
-(see next section) or with the update-known_hosts command:
+Identifying servers through the Web of Trust
+============================================
- $ monkeysphere update-known_hosts
+The simplest way to identify servers through the Web of Trust is to
+tell `ssh` to use `monkeysphere ssh-proxycommand` to connect, instead
+of connecting to the remote host directly. This command will make sure
+the `known_hosts` file is up-to-date for the host you are connecting
+to with ssh.
-This command will check to see if there is an OpenPGP key for
-each (non-hashed) host listed in the known_hosts file, and then add
-the key for that host to the known_hosts file if one is found. This
-command could be added to a crontab as well, if desired.
+You can try this out when connecting to a server which has published
+their host key to the monkeysphere with:
+ $ ssh -oProxyCommand='monkeysphere ssh-proxycommand %h %p' server.example.net
-Using `monkeysphere-ssh-proxycommand`(1)
-----------------------------------------
+If you want to have `ssh` always do this, just add the following line
+to the "Host *" section of your `~/.ssh/config` file:
-The best way to handle host keys is to use the monkeysphere ssh proxy
-command. This command will make sure the known_hosts file is
-up-to-date for the host you are connecting to with ssh. The best way
-to integrate this is to add the following line to the "Host *" section
-of your `~/.ssh/config` file:
-
- ProxyCommand monkeysphere-ssh-proxycommand %h %p
+ ProxyCommand monkeysphere ssh-proxycommand %h %p
The "Host *" section specifies what ssh options to use for all
-connections. If you don't already have a "Host *" line, you can add it
+connections. If you don't already have a "Host \*" line, you can add it
by entering:
Host *
On a line by itself. Add the ProxyCommand line just below it.
-Once you've completed this step - you are half-way there. You will now
-be able to verify servers participating in the monkeysphere provided
-their keys have been signed by someone that you trust.
+Note that the Monkeysphere will help you identify servers whose host
+keys are published in the WoT, and which are signed by people who you
+know and trust to identify such things!
-FIXME: We should setup a way for someone to download a test gpg key and
-then connect to a test server that is signed by this gpg key so users
-can establish that they are setup correctly.
+If you aren't connected to your administrator(s) through the Web of
+Trust, you should talk to them and establish that relationship. If
+you have already established that relationship, but a server's host
+key isn't published, you might suggest to your administrator that they
+publish it.
-The remaining steps will complete the second half: allow servers to
-verify you based on your OpenPGP key.
+Managing your SSH identity through the Web of Trust
+===================================================
-Setting up an OpenPGP authentication key
-----------------------------------------
+You've already got an OpenPGP identity in the Web of Trust. But you
+probably don't currently use it to identify yourself to SSH servers.
-First things first: you'll need to create a new subkey for your
-current key, if you don't already have one. If you already have a GPG
-key, you can add a subkey with:
+To do that, you'll need to add an authentication-capable subkey to
+your OpenPGP identity. You can do that with:
$ monkeysphere gen-subkey
If you have more than one secret key, you'll need to specify the key
-you want to add a subkey to on the command line.
+you want to add the subkey to on the command line.
+
+Since this is a change to your key, you probably want to re-publish
+your key to the public keyservers. If your key ID is $GPGID:
+
+ $ gpg --keyserver pool.sks-keyservers.net --send-key $GPGID
+This way, remote services that use the monkeysphere for user
+authentication will know about your SSH identity.
-Using your OpenPGP authentication key for SSH
----------------------------------------------
+You may need to wait a few minutes for your new key to propagate
+around the keyserver network, and another little while for any remote
+host running the monkeysphere to pick up the new subkey.
-Once you have created an OpenPGP authentication key, you will need to
-feed it to your ssh agent.
-Currently (2008-08-23), gnutls does not support this operation. In order
-to take this step, you will need to upgrade to a patched version of
-gnutls. You can easily upgrade a Debian system by adding the following
-to `/etc/apt/sources.list.d/monkeysphere.list`:
+Using your OpenPGP authentication key for SSH via ssh-agent(1)
+--------------------------------------------------------------
- deb http://archive.monkeysphere.info/debian experimental gnutls
- deb-src http://archive.monkeysphere.info/debian experimental gnutls
+Once you have created an OpenPGP authentication subkey, you will need
+to feed it to your `ssh-agent`. Your agent can then manage the key
+for all of your ssh sessions.
-Next, run `aptitude update; aptitude install libgnutls26`.
+First make sure you have an agent running:
-With the patched gnutls installed, you can feed your authentication
-subkey to your ssh agent by running:
+ $ ssh-add -l
+
+Then hand off the authentication subkey to the agent:
$ monkeysphere subkey-to-ssh-agent
-FIXME: using the key with a single ssh connection?
+You can supply normal ssh-add(1) flags to this command if you want to
+give the agent different instructions. For example, if you want the
+agent to always ask for confirmation before using this key, you should
+do this instead:
+
+ $ monkeysphere subkey-to-ssh-agent -c
+
+You can verify that the key is in the agent just as you normally
+would:
+
+ $ ssh-add -l
+
+Now you can connect to hosts that use the monkeysphere for user
+authentication using that key:
+
+ $ ssh server.example.net
+
+
+Using your OpenPGP authentication key for SSH without the agent
+---------------------------------------------------------------
+
+Currently, the monkeysphere does not support using your SSH subkey
+without the ssh-agent :( It's not impossible, we just haven't gotten
+around to it yet. Patches are welcome!
+
+If you are not running an agent, and you just want a single session
+with the key, you could cobble something together a one-shot agent
+like this:
+
+ $ ssh-agent sh -c 'monkeysphere subkey-to-ssh-agent && ssh server.example.net'
+
+Maintenance
+===========
+
+As a regular user of the monkeysphere, you probably want to do a few
+things to make sure that you get automatically notified of any
+re-keyings or revocation of monkeysphere-enabled hosts, and that your
+keys are properly managed.
+
+
+Keep your keyring up-to-date
+----------------------------
+
+Regularly refresh your GnuPG keyring from the keyservers. This can be
+done with a simple cronjob. An example of crontab line to do this is:
+
+ 0 12 * * * /usr/bin/gpg --refresh-keys > /dev/null 2>&1
+
+This would refresh your keychain every day at noon.
+
+Keep your SSH identity up-to-date
+---------------------------------
-Miscellaneous
--------------
+If your SSH identity or your whole OpenPGP keyring is compromised, you
+should be sure to revoke it and publish the revocations to the
+keyserver. If only your SSH identity was compromised, you should just
+revoke the authentication subkey. For keys with small sizes, or which
+may have been otherwise compromised, you may wish to simply revoke the
+old authentication subkey, add a new one, and publish those changes to
+the public keyservers together.
-Users can also maintain their own `~/.ssh/authorized_keys` files with
-the Monkeysphere. This is primarily useful for accounts on hosts that
-are not already systematically using the monkeysphere for user
-authentication. If you're not sure whether this is the case for your
-host, ask your system administrator.
+Many people believe that it is good security practice to only use
+asymmetric keys (such as the RSA keys used by SSH and the
+Monkeysphere) for a limited period of time, and prefer to transition
+from key to key every year or two.
-If you want to do this as a regular user, use the
-update-authorized_keys command:
+Without the monkeysphere, you would have needed to update your
+`authorized_keys` file on every host you connect to in order to effect
+such a transition. But all hosts that use the Monkeysphere to
+generate their authorized keys files will transition automatically to
+your new key, if you publish/revoke as described above.
- $ monkeysphere update-authorized_keys
-This command will take all the user IDs listed in the
-`~/.config/monkeysphere/authorized_user_ids` file and check to see if
-there are acceptable keys for those user IDs available. If so, they
-will be added to the `~/.ssh/authorized_keys` file.
+For those who want more
+=======================
-You must have indicated reasonable ownertrust in some key for this
-account, or no keys will be found with trusted certification paths.
+More documentation and details are available on the web at:
-If you find this useful, you might want to place this command in your
-crontab so that revocations and rekeyings can take place
-automatically.
+ http://web.monkeysphere.info/
projects / monkeysphere.git / blobdiff