X-Git-Url: https://codewiz.org/gitweb?a=blobdiff_plain;f=website%2Fgetting-started-user.mdwn;h=22a135f28bbba2daa61dd266cad36304495fa809;hb=1472a139953e68630cc0e409872fb4eaf69fff7f;hp=9b1646e127bf060ed1d0ef717f4f0f2fd60ff6c6;hpb=f5e80ac0f393733ac80feb3ed4ca5aedee77d330;p=monkeysphere.git diff --git a/website/getting-started-user.mdwn b/website/getting-started-user.mdwn deleted file mode 120000 index 9b1646e..0000000 --- a/website/getting-started-user.mdwn +++ /dev/null @@ -1 +0,0 @@ -../doc/README \ No newline at end of file diff --git a/website/getting-started-user.mdwn b/website/getting-started-user.mdwn new file mode 100644 index 0000000..22a135f --- /dev/null +++ b/website/getting-started-user.mdwn @@ -0,0 +1,181 @@ +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/