+++ /dev/null
-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 an OpenPGP key before you begin.
-
-As a user, the Monkeysphere lets you do two important things:
-
-1. You can use the OpenPGP Web of Trust (WoT) to automatically verify
-the identity of hosts you connect to.
-
-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.
-
-
-Identifying servers through the Web of Trust
-============================================
-
-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.
-
-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
-
-If you want to have `ssh` always do this, just add the following line
-to the "Host *" section of your `~/.ssh/config` file:
-
- 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
-by entering:
-
- Host *
-
-On a line by itself. Add the ProxyCommand line just below it.
-
-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!
-
-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.
-
-
-Managing your SSH identity through the Web of Trust
-===================================================
-
-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.
-
-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 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.
-
-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.
-
-
-Using your OpenPGP authentication key for SSH via ssh-agent(1)
---------------------------------------------------------------
-
-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.
-
-First make sure you have an agent running:
-
- $ ssh-add -l
-
-Then hand off the authentication subkey to the agent:
-
- $ monkeysphere subkey-to-ssh-agent
-
-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
----------------------------------
-
-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.
-
-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.
-
-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.
-
-
-For those who want more
-=======================
-
-More documentation and details are available on the web at:
-
- http://web.monkeysphere.info/
projects / monkeysphere.git / blobdiff