diff options
Diffstat (limited to 'website')
| -rw-r--r-- | website/community.mdwn | 35 | ||||
| -rw-r--r-- | website/doc.mdwn | 70 | ||||
| -rw-r--r-- | website/download.mdwn | 35 | ||||
| -rw-r--r-- | website/getting-started-admin.mdwn | 79 | ||||
| -rw-r--r-- | website/getting-started-user.mdwn | 68 | ||||
| -rw-r--r-- | website/local.css | 1 |
6 files changed, 161 insertions, 127 deletions
diff --git a/website/community.mdwn b/website/community.mdwn index 78ed9be..f2c5fc7 100644 --- a/website/community.mdwn +++ b/website/community.mdwn @@ -13,3 +13,38 @@ subjects around the web of trust. friendly bunch. You can also [look through our archives](https://lists.riseup.net/www/arc/monkeysphere) if you don't believe us. + +# Development # + +The Monkeysphere uses a distributed development model with +[git](http://git.or.cz/). Once you've [installed +git](http://www.spheredev.org/wiki/Git_for_the_lazy), you can [git +clone](http://www.kernel.org/pub/software/scm/git/docs/git-clone.html) +from this web site: + + git clone git://monkeysphere.info/monkeysphere + +## Individual developer repositories ## + +You might also be interested in the repositories of individual +developers, which may contain branches or features not yet in the main +offering: + +[Daniel Kahn Gillmor](http://cmrg.fifthhorseman.net/wiki/dkg): + + git clone git://lair.fifthhorseman.net/~dkg/monkeysphere + +[Jameson Graef Rollins](http://cmrg.fifthhorseman.net/wiki/jrollins): + + git clone git://lair.fifthhorseman.net/~jrollins/monkeysphere + +Micah Anderson + + git clone git://labs.riseup.net/~micah/monkeysphere + + +# Contact # + +Please feel free to contact any of the Monkeysphere developers or post +to the mailing list with questions, comments, bug reports, requests, +etc. diff --git a/website/doc.mdwn b/website/doc.mdwn index 3464455..c083669 100644 --- a/website/doc.mdwn +++ b/website/doc.mdwn @@ -1,25 +1,27 @@ [[!template id="nav"]] +[[meta title="Documentation"]] -# Monkeysphere Documentation # +# Dependencies # +Monkeysphere relies on: -## Dependencies ## + * [GnuTLS](http://gnutls.org/) version 2.4.0 or later + * [OpenSSH](http://openssh.com/) + * [GnuPG](http://gnupg.org/) - * Monkeysphere relies on [GnuTLS](http://gnutls.org/) version 2.4.0 or later. - -## Getting started ## +# Getting started # * Getting started as a [user](/getting-started-user) * Getting started as a [server admin](/getting-started-admin) -## References ## +# References # * [Initial specifications at CMRG](http://cmrg.fifthhorseman.net/wiki/OpenPGPandSSH) * [OpenPGP (RFC 4880)](http://tools.ietf.org/html/rfc4880) * [Secure Shell Authentication Protocol (RFC 4252)](http://tools.ietf.org/html/rfc4252) * [URI scheme for SSH, RFC draft](http://tools.ietf.org/wg/secsh/draft-ietf-secsh-scp-sftp-ssh-uri/) -## Similar Projects ## +# Similar Projects # The monkeysphere isn't the only project intending to implement a PKI for OpenSSH. We provide links to these other projects because they're @@ -29,8 +31,15 @@ All of the other projects we've found so far require a patched version of OpenSSH, which makes adoption more difficult. Most people don't build their own software, and simply overlaying a patched binary is associated with significant maintenance (and therefore security) -problems. A PKI becomes more useful the more people participate in -it, so widespread adoption is important. +problems. + +While ultimately contributing a patch to +[OpenSSH](http://openssh.com/) (or any +[free](http://www.chiark.greenend.org.uk/~sgtatham/putty/) +[SSH](http://www.lysator.liu.se/~nisse/lsh/) +[implementation](http://matt.ucc.asn.au/dropbear/dropbear.html)) is +not a bad thing, we hope to be able to better establish the use of a +PKI without resorting to source modification. ### `openssh-gpg` ### @@ -42,9 +51,8 @@ IETF](http://tools.ietf.org/html/rfc4253#section-6.6). Some concerns with `openssh-gpg`: - * This patch is significantly old; it doesn't appear to have been - maintained beyond OpenSSH 3.6p1. As of this writing, OpenSSH is on - version 5.1p1. + * This patch is old; it doesn't appear to have been maintained beyond + OpenSSH 3.6p1. As of this writing, OpenSSH 5.1p1 is current. * It only provides infrastructure in one direction: the user authenticating the host by name. There doesn't seem to be a @@ -61,23 +69,23 @@ Some concerns with `openssh-gpg`: to avoid collisions with existing use. * It's not clear that `openssh-gpg` acknowledges or respects the - usage flags on the host keys. - - * It requires patching OpenSSH. - + [usage flags](http://tools.ietf.org/html/rfc4880#section-5.2.3.21) + on the host keys. This means that it could accept a "sign-only" + key as suitable for authenticating a host, despite the + clearly-marked intentions of the key-holder. ### Perspectives OpenSSH client ### [The Perspectives project](http://www.cs.cmu.edu/~perspectives/) at CMU has released an [openssh client that uses network notaries](http://www.cs.cmu.edu/~perspectives/openssh.html) to bolster -your confidence in new keys. This offers a defense against a narrow -MITM attack (e.g. by someone who controls your local gateway) by -simply verifying that other machines from around the network see the -same keys for the remote host that you're seeing. +your confidence in newly-seen keys. This offers a defense against a +narrow MITM attack (e.g. by someone who controls your local gateway) +by simply verifying that other machines from around the network see +the same keys for the remote host that you're seeing. -This is quite useful, but doesn't take the system as far as it could -go, and doesn't tie into the existing web of trust. +This tactic is quite useful, but doesn't take the system as far as it +could go, and doesn't tie into any existing web of trust. Some concerns with the Perspectives OpenSSH client: @@ -94,13 +102,14 @@ Some concerns with the Perspectives OpenSSH client: with identifying users by name, or allowing users to globally revoke or change keys. - * It requires patching OpenSSH + * It doesn't provide any mechanism for key rotation or revocation: + Perspectives won't help you if you need to re-key your machine. ### OpenSSH with X.509v3 certificates ### Roumen Petrov [maintains a patch to OpenSSH that works with the X.509 PKI model](http://www.roumenpetrov.info/openssh/). This is the -certificate hierarchy commonly used by TLS (and SSL before that). +certificate hierarchy commonly used by TLS (and SSL). Some concerns about OpenSSH with X.509v3: @@ -120,4 +129,15 @@ Some concerns about OpenSSH with X.509v3: model is more flexible and more adaptable to represent real-world trust than X.509's rigid hierarchy. - * It requires patching OpenSSH. + * X.509 certificates can identify hosts by name, but not by + individual service. This means that a compromised web or e-mail + server with access to the X.509 key for that service could re-use + its certificate as an SSH server, and it would be able to + masquerade successfully. + + The monkeysphere uses [User IDs of the form + `ssh://foo.example.net`](http://tools.ietf.org/wg/secsh/draft-ietf-secsh-scp-sftp-ssh-uri/), + so they are not by-default shared across services on the same host + (you can still share a key across services on the same host if you + like, but the service User IDs can be certified independently of + one another). diff --git a/website/download.mdwn b/website/download.mdwn index 63bdca3..bb0639f 100644 --- a/website/download.mdwn +++ b/website/download.mdwn @@ -19,6 +19,10 @@ key to your apt configuration](http://cmrg.fifthhorseman.net/wiki/apt/importing-keys "Instructions for adding dkg's key to apt") +Once you've installed the packages, you might want to read up on how +to get started [as a regular user](/getting-started-user) or [as a +systems administrator](/getting-started-admin). + ### Enhancements ### As of 2008-08-22, If you run debian lenny you're very close to being @@ -34,34 +38,3 @@ include the `gnutls` component. So they'd look like this instead: deb-src http://monkeysphere.info/debian experimental monkeysphere gnutls You can [read more about this offering](/news/modified-gnutls-2.4.x-available.mdwn). - -## git repositories ## - -The Monkeysphere is attempting to use a completely distributed -development model with [git](http://git.or.cz/). Once you've -[installed git](http://www.spheredev.org/wiki/Git_for_the_lazy), you -can [git -clone](http://www.kernel.org/pub/software/scm/git/docs/git-clone.html) -any of the developer repositories, including: - -The git repo from this web site: - - git clone git://monkeysphere.info/monkeysphere - -[Daniel Kahn Gillmor](http://cmrg.fifthhorseman.net/wiki/dkg): - - git clone git://lair.fifthhorseman.net/~dkg/monkeysphere - -[Jameson Graef Rollins](http://cmrg.fifthhorseman.net/wiki/jrollins): - - git clone git://lair.fifthhorseman.net/~jrollins/monkeysphere - -Micah Anderson - - git clone git://labs.riseup.net/~micah/monkeysphere - -## Contact ## - -Please feel free to contact any of the Monkeysphere developers or post -to [the monkeysphere mailing list](/community) with any questions, -comments, bug reports, requests, etc. diff --git a/website/getting-started-admin.mdwn b/website/getting-started-admin.mdwn index e97c794..69f498a 100644 --- a/website/getting-started-admin.mdwn +++ b/website/getting-started-admin.mdwn @@ -1,77 +1,86 @@ Monkeysphere Server Administrator README ======================================== -FIXME: distinguish between publishing a new monkeysphere-enabled host -key and accepting user identification via the web-of-trust. +As the administrator of an SSH server, you can take advantage of the +monkeysphere in two ways: you can publish the host key of your machine +so that your users can have it automatically verified, and you can set +up your machine to automatically identify connecting users by their +presence in the OpenPGP web of trust. +Server host key publication +--------------------------- +To generate and publish a server host key: -server service publication --------------------------- -To publish a server host key: - - # monkeysphere-server gen-key - # monkeysphere-server publish-key + # monkeysphere-server gen-key + # monkeysphere-server publish-key This will generate the key for server with the service URI -(ssh://server.hostname). The server admin should now sign the server -key so that people in the admin's web of trust can authenticate the +(`ssh://server.example.net`). 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: - $ gpg --search ='ssh://server.hostname' - $ gpg --sign-key ='ssh://server.hostname' + $ gpg --search ='ssh://server.example.net' + $ gpg --sign-key ='ssh://server.example.net' Update OpenSSH configuration files ---------------------------------- To use the newly-generated host key for ssh connections, put the -following line in /etc/ssh/sshd_config (be sure to remove references -to any other key): +following line in `/etc/ssh/sshd_config` (be sure to remove references +to any other keys): - HostKey /var/lib/monkeysphere/ssh_host_rsa_key + HostKey /var/lib/monkeysphere/ssh_host_rsa_key FIXME: should we just suggest symlinks in the filesystem here instead? -FIXME: What about DSA host keys? The SSH RFC seems to require that DSA be available, though OpenSSH will work without a DSA host key. +FIXME: What about DSA host keys? The SSH RFC seems to require implementations support DSA, though OpenSSH will work without a DSA host key. -To enable users to use the monkeysphere to authenticate against the -web-of-trust, add this line to /etc/ssh/sshd_config (again, making -sure that no other AuthorizedKeysFile directive exists): +To enable users to use the monkeysphere to authenticate using the +OpenPGP web of trust, add this line to `/etc/ssh/sshd_config` (again, +making sure that no other AuthorizedKeysFile directive exists): - AuthorizedKeysFile /var/lib/monkeysphere/authorized_keys/%u + AuthorizedKeysFile /var/lib/monkeysphere/authorized_keys/%u +And then read the section below about how to ensure these files are +maintained. 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. -MonkeySphere authorized_keys maintenance +Monkeysphere authorized_keys maintenance ---------------------------------------- -A system can maintain monkeysphere authorized_keys files for it's -users. +A host can maintain ssh authorized_keys files automatically for its +users with the Monkeysphere. For each user account on the server, the userids of people authorized to log into that account would be placed in: - ~/.config/monkeysphere/authorized_user_ids + ~/.config/monkeysphere/authorized_user_ids However, in order for users to become authenticated, the server must -determine that the user 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 user. This would generally be -the server admin. If the server admin's keyid is XXXXXXXX, then on -the server run: +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 trusted identity certifer. +If the admin's OpenPGP keyid is `$GPGID`, then on the server run: - # monkeysphere-server add-identity-certifier XXXXXXXX + # monkeysphere-server add-identity-certifier $GPGID -To update the monkeysphere authorized_keys file for user "bob", the -system would then run the following: +To update the monkeysphere authorized_keys file for user "bob" using +the current set of identity certifiers, run: - # monkeysphere-server update-users bob + # monkeysphere-server update-users bob To update the monkeysphere authorized_keys file for all users on the the system, run the same command with no arguments: - # monkeysphere-server update-users + # monkeysphere-server update-users You probably want to set up a regularly scheduled job (e.g. with cron) -to take care of this regularly. +to take care of this automatically. FIXME: document other likely problems and troubleshooting techniques diff --git a/website/getting-started-user.mdwn b/website/getting-started-user.mdwn index b86240c..5cb96b9 100644 --- a/website/getting-started-user.mdwn +++ b/website/getting-started-user.mdwn @@ -16,20 +16,20 @@ 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 + 0 12 * * * /usr/bin/gpg --refresh-keys > /dev/null 2>&1 This would refresh your keychain every day at noon. -Keeping your known_hosts file in sync with your keyring -------------------------------------------------------- +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: - $ monkeysphere update-known_hosts + $ 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 @@ -37,22 +37,22 @@ 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. -Using monkeysphere-ssh-proxycommand(1) --------------------------------------- +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: +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 by entering: - Host * + Host * On a line by itself. Add the ProxyCommand line just below it. @@ -72,17 +72,13 @@ 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: - - $ monkeysphere gen-subkey $GPGID - -Typically, you can find out what your keyid is by running: +current key, if you don't already have one. If you already have a GPG +key, you can add a subkey with: - $ gpg --list-secret-keys + $ monkeysphere gen-subkey -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. +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. Using your OpenPGP authentication key for SSH @@ -94,43 +90,43 @@ 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: +to `/etc/apt/sources.list.d/monkeysphere.list`: - deb http://monkeysphere.info/debian experimental gnutls - deb-src http://monkeysphere.info/debian experimental gnutls + deb http://monkeysphere.info/debian experimental gnutls + deb-src http://monkeysphere.info/debian experimental gnutls -Next, run `aptitude update; aptitude install libgnuttls26`. +Next, run `aptitude update; aptitude install libgnutls26`. -With the patched gnutls installed, you can feed your authentication sub -key to your ssh agent by running: +With the patched gnutls installed, you can feed your authentication +subkey to your ssh agent by running: - $ monkeysphere subkey-to-ssh-agent + $ monkeysphere subkey-to-ssh-agent -FIXME: using the key with a single session? +FIXME: using the key with a single ssh connection? Miscellaneous ------------- -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. +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 + $ 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 +`~/.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. +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 a job like this in -your crontab so that revocations and rekeyings can take place +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/local.css b/website/local.css index 06b1750..34f376e 100644 --- a/website/local.css +++ b/website/local.css @@ -30,4 +30,5 @@ pre { background: #ddd; border: 1px solid #aaa; padding: 3px 3px 3px 3px; + margin-left: 2em; } |