diff options
Diffstat (limited to 'website')
| -rw-r--r-- | website/advanced-user.mdwn | 137 | ||||
| -rw-r--r-- | website/doc.mdwn | 4 | ||||
| -rw-r--r-- | website/getting-started-admin.mdwn | 120 | ||||
| -rw-r--r-- | website/getting-started-user.mdwn | 307 |
4 files changed, 349 insertions, 219 deletions
diff --git a/website/advanced-user.mdwn b/website/advanced-user.mdwn new file mode 100644 index 0000000..7969018 --- /dev/null +++ b/website/advanced-user.mdwn @@ -0,0 +1,137 @@ +[[meta title="Advanced usage of the Monkeysphere"]] + +Advanced usage of the monkeysphere +================================== + + +Keeping your `known_hosts` file in sync with your keyring +--------------------------------------------------------- + +If you want to keep your keyring updated without attempting +connections to a remote host, you want to make sure that OpenSSH can +still see the most recent trusted information about who the various +hosts are. You might also want to check on hosts that were not +originally in the Monkeysphere, to see if their host key is now +published. + +You can do this kind of independent update with the +`update-known_hosts` command: + + $ monkeysphere update-known_hosts + +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, if desired. + + + +Establishing trust +------------------ + +The Monkeysphere is predicated on the idea that users and +administrators know each other (or know people who know each other, +etc). It uses the Web of Trust to explicitly represent those links. +If you haven't used the Web of Trust explicitly, you will need to +establish an acceptable trust path to the admin(s) of the +monkeysphere-enabled servers that you will be connecting to. You need +to do this because the admin is certifying the host, and you need a +mechanism to validate that certification. The only way to do that is +by indicating who you trust to certify hosts. This is a two step +process: first you must sign the key, and then you have to indicate a +trust level. If you do not indicate that you trust the administrator +to certify host keys, then the monkeysphere will show you her +certification on every connection, but will not treat it as an +automatic verification. + +The process of signing another key is outside the scope of this +document, however the [gnupg +README](http://cvs.gnupg.org/cgi-bin/viewcvs.cgi/branches/STABLE-BRANCH-1-4/README?root=GnuPG&view=markup) +details the signing process and you can find good [documentation +](http://www.debian.org/events/keysigning) online detailing this +process. + +If you have signed your admins' key, you need to denote some kind of +trust to that key. To do this you should edit the key and use the +'trust' command. For the Monkeysphere to trust the assertions that are +made about a host, you need full calculated validity to the host +certifiers. This can be done either by giving full trust to one +host-certifying key, or by giving marginal trust to three different +host-certifiers. In the following we demonstrate how to add full trust +validity to a host-certifying key: + + + $ gpg --edit-key 'Jane Admin' + gpg (GnuPG) 1.4.9; Copyright (C) 2008 Free Software Foundation, Inc. + This is free software: you are free to change and redistribute it. + There is NO WARRANTY, to the extent permitted by law. + + + pub 4096R/ABCD123A created: 2007-06-02 expires: 2012-05-31 usage: SC + trust: unknown validity: full + sub 2048R/01DECAF7 created: 2007-06-02 expires: 2012-05-31 usage: E + [ full ] (1). Jane Admin <jane_admin@example.net> + + Command> trust + pub 4096R/ABCD123A created: 2007-06-02 expires: 2012-05-31 usage: SC + trust: unknown validity: full + sub 2048R/01DECAF7 created: 2007-06-02 expires: 2012-05-31 usage: E + [ full ] (1). Jane Admin <jane_admin@example.net> + + Please decide how far you trust this user to correctly verify other users' keys + (by looking at passports, checking fingerprints from different sources, etc.) + + 1 = I don't know or won't say + 2 = I do NOT trust + 3 = I trust marginally + 4 = I trust fully + 5 = I trust ultimately + m = back to the main menu + + Your decision? 4 + + pub 4096R/ABCD123A created: 2007-06-02 expires: 2012-05-31 usage: SC + trust: full validity: full + sub 2048R/01DECAF7 created: 2007-06-02 expires: 2012-05-31 usage: E + [ full ] (1). Jane Admin <jane_admin@example.net> + Please note that the shown key validity is not necessarily correct + unless you restart the program. + + Command> save + Key not changed so no update needed. + $ + +Note: Due to a limitation with gnupg, it is not currently possible to +limit the domain scope properly, which means that if you fully trust +an admin, you'll trust all their certifications. + +Because the Monkeysphere currently relies on GPG's definition of the +OpenPGP web of trust, it is important to understand [how GPG +calculates User ID validity for a key](/trust-models). + + +Miscellaneous +------------- + +Users can also maintain their own `~/.ssh/authorized_keys` files with +the Monkeysphere directly. 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. + +If you want to do this as a regular user, use the +`update-authorized_keys` command: + + $ monkeysphere update-authorized_keys + +This command will take all the user IDs listed in the +`~/.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. + +You must have indicated reasonable ownertrust in some key for this +account, or no keys will be found with trusted certification paths. + +If you find this useful, you might want to place this command in your +crontab so that revocations and rekeyings can take place +automatically. diff --git a/website/doc.mdwn b/website/doc.mdwn index 28db2ef..47b173a 100644 --- a/website/doc.mdwn +++ b/website/doc.mdwn @@ -10,11 +10,13 @@ ## Going further ## + * [Advanced Monkeysphere usage](/advanced-user) * [Signing host keys](/signing-host-keys) + * [Understanding trust models](/trust-models) ## Under the hood ## - * [Developing the monkeysphere](/community) + * [Developing the Monkeysphere](/community) * [Technical details](/technical-details) ## References ## diff --git a/website/getting-started-admin.mdwn b/website/getting-started-admin.mdwn index 9010132..ca44956 100644 --- a/website/getting-started-admin.mdwn +++ b/website/getting-started-admin.mdwn @@ -2,21 +2,15 @@ Monkeysphere Server Administrator README ======================================== As the administrator of an SSH server, you can take advantage of the -monkeysphere in two ways: +Monkeysphere in two ways: 1. you can publish the host key of your machine to the Web of Trust -(WoT) so that your users can have it automatically verified, and +(WoT) so that your users can automatically verify it, and 2. you can set up your machine to automatically identify connecting users by their presence in the OpenPGP Web of Trust. -These things are not mutually required, and it is in fact possible to -do one without the other. However, it is highly recommend that you at -least do the first. Even if you decide that you do not want to use -the monkeysphere to authenticate users to your system, you should at -least the host key into the Web of Trust so that your users can be -sure they're connecting to the correct machine. - +These two pieces are independent: you can do one without the other. Monkeysphere for host verification (monkeysphere-host) ====================================================== @@ -28,33 +22,44 @@ 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: - # monkeysphere-host /etc/ssh/ssh\_host\_rsa\_key + # monkeysphere-host import-key /etc/ssh/ssh_host_rsa_key server.example.net + +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. -This will generate the key for server with the service URI -(`ssh://server.example.net`). You can output the new key information -with the 'show-key' command: +Now you can display information about the host key's certificate with +the 'show-key' command: # monkeysphere-host show-key -Once the key has been imported, it needs to be publish to the Web of -Trust: +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: # monkeysphere-host publish-key -The server admin should now sign the server key so that people in the -admin's web of trust can identify the server without manual host key -checking. On your (the admin's) local machine retrieve the host key: - - $ gpg --search '=ssh://server.example.net' +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. -Now sign the server key: +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 with the one -output with the 'show-key' command above, to verify you are signing -the correct key. Finally, publish your signatures back to the -keyservers: +Make sure you compare the fingerprint of the retrieved certificate +with the output from the 'show-key' command above! + +Finally, publish your signatures back to the keyservers, so that your +users can automatically verify your machine when they connect: $ gpg --send-key '=ssh://server.example.net' @@ -64,10 +69,18 @@ signing host keys. Monkeysphere for user authentication (monkeysphere-authentication) ================================================================== -A host can maintain ssh `authorized_keys` files automatically for its -users with the Monkeysphere. These `authorized_keys` files can then -be used to enable users to use the monkeysphere to authenticate to -your machine using the OpenPGP web of trust. +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 ---------------------------------------- @@ -77,20 +90,29 @@ to log into that account would be placed in: ~/.monkeysphere/authorized_user_ids -However, in order for users to become authenticated, the server must -determine that the user IDs on their 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 relevant -user ID. The individuals trusted to identify users like this are -known in the Monkeysphere as "Identity Certifiers". In a simple -scenario, the host's administrator would be a trusted identity -certifer. If the admin's OpenPGP keyid is `$GPGID`, then on the -server run: +The server will use the Monkeysphere to look up matching OpenPGP +certificates, validate them, and generate an `authorized_keys` file. + +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. If your OpenPGP keyid is `$GPGID`, then +run the following command on the server: # monkeysphere-authentication add-identity-certifier $GPGID -To update the monkeysphere `authorized_keys` file for user "bob" using -the current set of identity certifiers, run: +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 @@ -100,19 +122,21 @@ the system, run the same command with no arguments: # monkeysphere-authentication update-users You probably want to set up a regularly scheduled job (e.g. with cron) -to take care of this automatically. +to do this automatically. Update OpenSSH server AuthorizedKeysFile configuration ------------------------------------------------------ -SSH must be configured to point to the monkeysphere generated -`authorized_keys` file. Add this line to `/etc/ssh/sshd_config` -(again, making sure that no other AuthorizedKeysFile directive is left -uncommented): +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 You'll need to restart `sshd` to have your changes take effect. As -with any change to `sshd_config`, be sure to retain an existing -session to the machine while you test your changes so you don't get -locked out. +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. diff --git a/website/getting-started-user.mdwn b/website/getting-started-user.mdwn index ec157ac..9e2be26 100644 --- a/website/getting-started-user.mdwn +++ b/website/getting-started-user.mdwn @@ -3,211 +3,178 @@ Monkeysphere User README 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 ----------------------------- - -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. - - -Install the monkeysphere software on your system ------------------------------------------------- - -If you haven't installed monkeysphere yet, you will need to [download -and install](/download) before continuing. - -Make sure that you have the GnuTLS library version 2.6 or later -installed on your system. If you can't (or don't want to) upgrade to -GnuTLS 2.6 or later, there are patches for GnuTLS 2.4 available in -[the Monkeysphere git repo](/community). +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) ----------------------------------------- - -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 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 +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: allowing 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 have a OpenPGP "authentication" -subkey for your current key, if you don't already have one. If you -already have a GPG key, you can generate an authentication subkey with -the `gen-subkey` command: +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-keysevers.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 ---------------------------------------------- + +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. +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 -The GnuTLS library supports this operation as of version 2.6, but -earlier versions do not. With a recent version of GnuTLS installed, -you can feed your authentication subkey to your ssh agent by running: +Then hand off the authentication subkey to the agent (Note: the GnuTLS +library supports this operation as of version 2.6, but earlier +versions do not): $ monkeysphere subkey-to-ssh-agent -FIXME: using the key with a single ssh connection? - - -Establish trust ---------------- - -Now that you have the above setup, you will need to establish an -acceptable trust path to the admin(s) of a monkeysphere-enabled server -that you will be connecting to. You need to do this because the admin -is certifying the host, and you need a mechanism to validate that -certification. The only way to do that is by indicating who you trust -to certify hosts. This is a two step process: first you must sign the -key, and then you have to indicate a trust level. - -The process of signing another key is outside the scope of this -document, however the [gnupg -README](http://cvs.gnupg.org/cgi-bin/viewcvs.cgi/branches/STABLE-BRANCH-1-4/README?root=GnuPG&view=markup) -details the signing process and you can find good [documentation -](http://www.debian.org/events/keysigning) online detailing this -process. - -If you have signed your admins' key, you need to denote some kind of -trust to that key. To do this you should edit the key and use the -'trust' command. For the Monkeysphere to trust the assertions that are -made about a host, you need full calculated validity to the host -certifiers. This can be done either by giving full trust to one -host-certifying key, or by giving marginal trust to three different -host-certifiers. In the following we demonstrate how to add full trust -validity to a host-certifying key: - - - $ gpg --edit-key 'Jane Admin' - gpg (GnuPG) 1.4.9; Copyright (C) 2008 Free Software Foundation, Inc. - This is free software: you are free to change and redistribute it. - There is NO WARRANTY, to the extent permitted by law. - - - pub 4096R/ABCD123A created: 2007-06-02 expires: 2012-05-31 usage: SC - trust: unknown validity: full - sub 2048R/01DECAF7 created: 2007-06-02 expires: 2012-05-31 usage: E - [ full ] (1). Jane Admin <jane_admin@example.net> - - Command> trust - pub 4096R/ABCD123A created: 2007-06-02 expires: 2012-05-31 usage: SC - trust: unknown validity: full - sub 2048R/01DECAF7 created: 2007-06-02 expires: 2012-05-31 usage: E - [ full ] (1). Jane Admin <jane_admin@example.net> - - Please decide how far you trust this user to correctly verify other users' keys - (by looking at passports, checking fingerprints from different sources, etc.) - - 1 = I don't know or won't say - 2 = I do NOT trust - 3 = I trust marginally - 4 = I trust fully - 5 = I trust ultimately - m = back to the main menu - - Your decision? 4 - - pub 4096R/ABCD123A created: 2007-06-02 expires: 2012-05-31 usage: SC - trust: full validity: full - sub 2048R/01DECAF7 created: 2007-06-02 expires: 2012-05-31 usage: E - [ full ] (1). Jane Admin <jane_admin@example.net> - Please note that the shown key validity is not necessarily correct - unless you restart the program. - - Command> save - Key not changed so no update needed. - $ - -Note: Due to a limitation with gnupg, it is not currently possible to -limit the domain scope properly, which means that if you fully trust -an admin, you'll trust all their certifications. - -Because the Monkeysphre relies on GPG's definition of the OpenPGP web -of trust, it is important to understand [how GPG calculates User ID -validity for a key](/trust-models). - - -Miscellaneous -------------- - -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. - -If you want to do this as a regular user, use the -`update-authorized_keys` command: - - $ monkeysphere update-authorized_keys - -This command will take all the user IDs listed in the -`~/.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. - -You must have indicated reasonable ownertrust in some key for this -account, or no keys will be found with trusted certification paths. - -If you find this useful, you might want to place this command in your -crontab so that revocations and rekeyings can take place -automatically. +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/ |