no need for recursive removal of a single file

[monkeysphere.git] / website / getting-started-user.mdwn

diff --git a/website/getting-started-user.mdwn b/website/getting-started-user.mdwn
index b86240c5c8767397237b4cea022be73d969f3612..22a135f28bbba2daa61dd266cad36304495fa809 100644 (file)
--- a/website/getting-started-user.mdwn
+++ b/website/getting-started-user.mdwn
@@ -1,136 +1,181 @@
 Monkeysphere User README
 ========================
 
 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
 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.
+(ssh), and you should already have an OpenPGP key before you begin.

 
 

-As a regular user on a system where the monkeysphere package is
-installed, you probably want to do a few things:
+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.

 
 

-Keep your keyring up-to-date
-----------------------------
+2. You can manage your own ssh identity on all Monkeysphere-enabled
+servers using the WoT.

 
 

-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:
+These two features are independent: you can do one without the other.

 
 

-               0 12 * * * /usr/bin/gpg --refresh-keys > /dev/null 2>&1

 
 

-This would refresh your keychain every day at noon.
+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

 
 

-Keeping your known_hosts file in sync with your keyring
--------------------------------------------------------
+If you want to have `ssh` always do this, just add the following line
+to the "Host *" section of your `~/.ssh/config` file:

 
 

-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:
+       ProxyCommand monkeysphere ssh-proxycommand %h %p

 
 

-               $ monkeysphere update-known_hosts
+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:

 
 

-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.
+       Host *

 
 

+On a line by itself. Add the ProxyCommand line just below it.

 
 

-Using monkeysphere-ssh-proxycommand(1)
---------------------------------------
+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! 

 
 

-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:
+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.

 
 

-               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:
+Managing your SSH identity through the Web of Trust
+===================================================

 
 

-               Host *
+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.

 
 

-On a line by itself. Add the ProxyCommand line just below it.
+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.

 
 

-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.
+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:

 
 

-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.
+       $ gpg --keyserver pool.sks-keyservers.net --send-key $GPGID

 
 

-The remaining steps will complete the second half: allow servers to
-verify you based on your OpenPGP key.
+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.  

 
 

-Setting up an OpenPGP authentication key
-----------------------------------------

 
 

-First things first: you'll need to create a new subkey for your
-current key, if you don't already have one.  If your OpenPGP key is
-keyid $GPGID, you can set up such a subkey relatively easily with:
+Using your OpenPGP authentication key for SSH via ssh-agent(1)
+--------------------------------------------------------------

 
 

-               $ monkeysphere gen-subkey $GPGID
+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.

 
 

-Typically, you can find out what your keyid is by running:
+First make sure you have an agent running:

 
 

-               $ gpg --list-secret-keys
+       $ ssh-add -l

 
 

-The first line (starting with sec) will include your key length followed
-by the type of key (e.g. 1024D) followed by a slash and then your keyid.
+Then hand off the authentication subkey to the agent:

 
 

+       $ monkeysphere subkey-to-ssh-agent

 
 

-Using your OpenPGP authentication key for SSH
----------------------------------------------
+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:

 
 

-Once you have created an OpenPGP authentication key, you will need to
-feed it to your ssh agent.
+       $ monkeysphere subkey-to-ssh-agent -c

 
 

-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:
+You can verify that the key is in the agent just as you normally
+would:

 
 

-               deb http://monkeysphere.info/debian experimental gnutls
-               deb-src http://monkeysphere.info/debian experimental gnutls
+       $ ssh-add -l

 
 

-Next, run `aptitude update; aptitude install libgnuttls26`.
+Now you can connect to hosts that use the monkeysphere for user
+authentication using that key:

 
 

-With the patched gnutls installed, you can feed your authentication sub
-key to your ssh agent by running:
+       $ ssh server.example.net

 
 

-               $ monkeysphere subkey-to-ssh-agent

 
 

-FIXME: using the key with a single session?
+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 authorized_keys files, for users
-that would be logging into their accounts.  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 a job like this in
-your crontab so that revocations and rekeyings can take place
-automatically.
+ http://web.monkeysphere.info/