diff options
Diffstat (limited to 'website')
| -rw-r--r-- | website/bugs/useful_information.mdwn | 50 | ||||
| -rw-r--r-- | website/doc.mdwn | 18 | ||||
| -rw-r--r-- | website/download.mdwn | 78 | ||||
| -rw-r--r-- | website/features.mdwn | 4 | ||||
| -rw-r--r-- | website/getting-started-admin.mdwn | 2 | ||||
| -rw-r--r-- | website/getting-started-user.mdwn | 9 | ||||
| -rw-r--r-- | website/news/release-0.20-1.mdwn | 18 | ||||
| -rw-r--r-- | website/news/release-0.21-1.mdwn | 10 | ||||
| -rw-r--r-- | website/signing-host-keys.mdwn | 127 | ||||
| -rw-r--r-- | website/technical-details.mdwn | 28 |
10 files changed, 303 insertions, 41 deletions
diff --git a/website/bugs/useful_information.mdwn b/website/bugs/useful_information.mdwn new file mode 100644 index 0000000..025d678 --- /dev/null +++ b/website/bugs/useful_information.mdwn @@ -0,0 +1,50 @@ +I would like to know, at INFO (default) log level, when the +monkeyspehere makes a "real" modification to my known\_hosts file; that +is, when it adds or deletes a key. + +Apparently this is hard because monkeysphere is currently configured to +delete all keys and then add good keys, so a key added for the first +time seems to the monkeysphere very similar to a key re-added ten +seconds after last login. + +Still, from a UI perspective, I want to know what monkeysphere is doing. + +------ + +It looks like jrollins committed a change for reporting at INFO level +when a host key gets added by the monkeysphere: +2459fa3ea277d7b9289945748619eab1e3441e5c + +When i connect to a host whose key is not already present in my +known_hosts file, i get the following to stderr: + + ms: * new key for squeak.fifthhorseman.net added to known_hosts file. + +This doesn't fully close this bug, because we aren't notifying on key +deletion, afaict. + +------ + +So current log level DEBUG will output a message if the known host +file has been modified. If the issue is that you want to know at the +default log level everytime the known\_hots file is modified, then we +should just move this message to INFO instead of debug, and then maybe +remove the message that I added above. I was under the impression +that the issue was more about notification that a *new* key was added +to the known\_hosts file, and therefore the new INFO message above +fixed that problem. Should we do this instead? + +In general, more verbose log levels *do* tell the user what the +monkeysphere is doing. Moving to DEBUG log level will tell you pretty +much everything that happens. I do *not* think that this should be +the default log level, though. + +------ + +I wouldn't want to see an extremely verbose default log level. But i +do think that saying something like "key blah blah blah was stripped +from your known\_hosts file because it was expired" (for example) +would be useful. I think this case would occur infrequently enough +that it is worth reporting in the UI at the regular log level. + + --dkg diff --git a/website/doc.mdwn b/website/doc.mdwn index 56498e8..cd7bc76 100644 --- a/website/doc.mdwn +++ b/website/doc.mdwn @@ -2,24 +2,24 @@ # Documentation # -## Dependencies ## - -Monkeysphere relies on: - - * [GnuTLS](http://gnutls.org/) version 2.4.0 or later - * [OpenSSH](http://openssh.com/) - * [GnuPG](http://gnupg.org/) - ## Getting started ## * [Downloading and installing](/download) * Getting started as a [user](/getting-started-user) * Getting started as a [server admin](/getting-started-admin) + +## Going further ## + + * [Signing host keys](/signing-host-keys) + +## Under the hood ## + * [Developing the monkeysphere](/community) + * [Technical details](/technical-details) ## References ## - * [Initial specifications at CMRG](http://cmrg.fifthhorseman.net/wiki/OpenPGPandSSH) + * [Initial Monkeysphere 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/) diff --git a/website/download.mdwn b/website/download.mdwn index 1f27fde..6d5a73f 100644 --- a/website/download.mdwn +++ b/website/download.mdwn @@ -2,10 +2,25 @@ # Downloading and Installing # +Once you've installed the packages, please see the [documentation +page](/doc) to read up on how to get started [as a regular +user](/getting-started-user) or [as a systems +administrator](/getting-started-admin). + +## Dependencies ## + +Monkeysphere relies on: + + * [GnuTLS](http://gnutls.org/) + * version 2.4 or later for general use + * [version 2.6 or later](/news/gnutls-2.6-enables-monkeysphere) to use the `monkeysphere subkey-to-ssh-agent` subcommand. + * [OpenSSH](http://openssh.com/) + * [GnuPG](http://gnupg.org/) + ## Debian ## -If you are running a Debian system, you can install Monkeysphere -by following these directions: +If you are running a [Debian](http://www.debian.org/) system, you can +install Monkeysphere by following these directions: You can add this repo to your system by putting the following lines in `/etc/apt/sources.list.d/monkeysphere.list`: @@ -13,23 +28,20 @@ You can add this repo to your system by putting the following lines in deb http://archive.monkeysphere.info/debian experimental monkeysphere deb-src http://archive.monkeysphere.info/debian experimental monkeysphere -The repository is currently signed by the Monkeysphere archive -signing key, key id EB8AF314 (fingerprint: `2E8D -D26C 53F1 197D DF40 3E61 18E6 67F1 EB8A F314`). To cryptographically +The repository is currently signed by [The Monkeysphere archive +signing key](/archive-key), key id EB8AF314 (fingerprint: `2E8D D26C +53F1 197D DF40 3E61 18E6 67F1 EB8A F314`). To cryptographically verify the packages, you'll want to [add this key to your apt configuration after verifying its integrity](/archive-key). To use the `monkeysphere subkey-to-ssh-agent` subcommand, you will -also need [version 2.6 of GnuTLS](/news/gnutls-2.6-enables-monkeysphere), -which is available in Debian experimental. - -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). +also need [version 2.6 of +GnuTLS](/news/gnutls-2.6-enables-monkeysphere), which is available in +Debian experimental. ## FreeBSD ## -There is [now a FreeBSD port available](/news/FreeBSD-port-available/) +There is [now a FreeBSD port available](/news/FreeBSD-port-available) for the Monkeysphere. While the monkeysphere is not officially included in the ports tree @@ -51,44 +63,50 @@ port with: cd /usr/ports/security/monkeysphere make && make install +To use the `monkeysphere subkey-to-ssh-agent` subcommand, you will +also need [version 2.6 of +GnuTLS](/news/gnutls-2.6-enables-monkeysphere), which is [slated to be +available after the 7.1 ports slush is +over](http://www.freebsd.org/cgi/query-pr.cgi?pr=ports/127330). + ## Source ## For those that would like to download the source directly, [the source is available](/community) via [git](http://git.or.cz/). The [latest -tarball](http://archive.monkeysphere.info/debian/pool/monkeysphere/m/monkeysphere/monkeysphere_0.19.orig.tar.gz) +tarball](http://archive.monkeysphere.info/debian/pool/monkeysphere/m/monkeysphere/monkeysphere_0.21.orig.tar.gz) is also available, and has these checksums: <pre> -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 -checksums for the monkeysphere 0.19 release: +checksums for the monkeysphere 0.21 release: MD5: -64c643dd0ab642bbc8814aec1718000e monkeysphere_0.19.orig.tar.gz +15fe181983565aca0fbe4c41f9f6752e monkeysphere_0.21.orig.tar.gz SHA1: -ea3c263b084d2c0b7922cd96677be192201700e4 monkeysphere_0.19.orig.tar.gz +27e915a45cdbe50a139ed4f4b13746b17c165b0f monkeysphere_0.21.orig.tar.gz SHA256: -321b77c1e10fe48ffbef8491893f5dd22842c35c11464efa7893150ce756a522 monkeysphere_0.19.orig.tar.gz +1535c3f722f5f5c1646a4981efef4a262ac7b23bf4b980c9aee11af2600eedc2 monkeysphere_0.21.orig.tar.gz -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.9 (GNU/Linux) -iQIVAwUBSQgMCRjmZ/HrivMUAQI2Jg//bZoSxx0Nor6uBikRGHQny8LzgUT/0kpv -xg0eRmL9kQwhGis/sdOiJ9cHykJ1ukhRiIZGfxPBdxiQbWGs9nM6147TGIDgqx6D -yYIW41dvzTRB0TwjNd7g1q6MaSiDNuU/6dD+ooM3/IiR8PDR7X8we0WhSM63KD+v -HeMsN51UMhBfeaZ06fxrjYoJCvnp0YNYJpLuvtd5tzxqJCJA2Vh5VqJMbMP/MtbY -zM/zuNXRI1mJnQZeU++IaAnimX7c7SsGjLaloZG8mapYqqY0tKJ5Yod6aeloq+i5 -wI4gZuuPcgAntD6cnPaqB1ni/d71yywme5F75zpezXGzKzDSh1J5oE6akjMi2lJE -DSOKp7zb7TvDwXxCl+vOVod81F260gPhonlTsD/LpBfPGPBdWlWP+fFchb9N/a2u -weCMhUYX1u8Jg/bHIycjoQjPEgZwCkJT9RKF1NTLyWvb4P4a3sPe+fauCMZFbTQ/ -3EYPRBY+PfIDO09XswdB5O3gq6B33ChyWJpdwlXEEHMcFt1FuezuP0avVM9/3ZNp -MkqalDrUEd65X8o+CE3KjFxjMceVdda9mz2netnoHrFMW6X3mFqE2fTldgHi1mCT -hMCqpPzY04+HOHYZ0GapR3pvedd4dwhkNYrdpckp+nJMTRfexEPH/NXDVNH/mxKg -jLoIos0SaiY= -=VUsz +iQIVAwUBSR8+7BjmZ/HrivMUAQLeKg/+JT4LCXBR/06p/w2KBd1MKqch5Qf2ryIo +mxCTWtZRgVQSeOFUJ5SXX+Tfs7VZfkV5HuahUH3NmGC6EMhYyB2olwBOOoIAqEKw +1zVyn49bowCee+gTc3QHyT0Eqgt2ARtzl3/VrHkiw2MaJN3IZXseovyL8ksnEu+u +s8fq26imtBrrucIxp4ZtHUw/h/YrJohHcJ8QQN5/UWFLug4C4aRFmnzL+oCySxAa +0au/zFxxRZE5pMhLUvRwwCwPFx2CGBz6y9lAOiDPhhUqh+Bf7JKWJzk35Dj5Tm+2 +lCIzYtfpBkuF9ehCrm8WYF5aFg+gto8Bc6IJci9J6h2npBYIG0IbWOknMZz3+Ti2 +c3EltlJjK0LKEHujDYjf9tkNAxbBdtlYuw8x925ILeK7n8xX0Jr1TDzPyAIYaogv +IVqsgnvQ489K8k06173kyrPaetyvOlU3bN1zcPdqTyCD6+eBbeCeKXO4324C8iMF +rQPW4HScOdIidqFuzHyIT7PoY4DwWMgeAVymRSEufifvRcdCvQdlC4MaxxVf5I8A +ATkD3CrY+5NZeERAGbmlu7Uz+sUk5tLUH0Q2qvjZUIQRctfr4BMheuBubsLR9yP3 +FZ4Q4kl34eU/WU7NtTmIFy7gDhLSIoeQINfYZlNEXQ7Y/RZUOEwoPI/spAXgw6De +Xpsw0wPZtcM= +=JDaA -----END PGP SIGNATURE----- </pre> diff --git a/website/features.mdwn b/website/features.mdwn new file mode 100644 index 0000000..1aabda1 --- /dev/null +++ b/website/features.mdwn @@ -0,0 +1,4 @@ +[[meta title="Features"]] + +# Features # + diff --git a/website/getting-started-admin.mdwn b/website/getting-started-admin.mdwn index 6c8ad53..1c373ac 100644 --- a/website/getting-started-admin.mdwn +++ b/website/getting-started-admin.mdwn @@ -7,6 +7,7 @@ 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: @@ -48,6 +49,7 @@ 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 ---------------------------------------- diff --git a/website/getting-started-user.mdwn b/website/getting-started-user.mdwn index 66378dc..9b04edc 100644 --- a/website/getting-started-user.mdwn +++ b/website/getting-started-user.mdwn @@ -20,19 +20,21 @@ done with a simple cronjob. An example of crontab line to do this is: 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. +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). + 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 @@ -47,6 +49,7 @@ 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) ---------------------------------------- @@ -91,6 +94,7 @@ 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. + Using your OpenPGP authentication key for SSH --------------------------------------------- @@ -105,6 +109,7 @@ you can feed your authentication subkey to your ssh agent by running: FIXME: using the key with a single ssh connection? + Establish trust --------------- diff --git a/website/news/release-0.20-1.mdwn b/website/news/release-0.20-1.mdwn new file mode 100644 index 0000000..841369d --- /dev/null +++ b/website/news/release-0.20-1.mdwn @@ -0,0 +1,18 @@ +[[meta title="Monkeysphere 0.20-1 released!"]] + +Monkeysphere 0.20-1 has been released. + +Notes from the changelog: + +<pre> + [ Daniel Kahn Gillmor ] + * ensure that tempdirs are properly created, bail out otherwise instead + of stumbling ahead. + * minor fussing with the test script to make it cleaner. + + [ Jameson Graef Rollins ] + * clean up Makefile to generate more elegant source tarballs. + * make myself the maintainer. +</pre> + +[[Download]] it now! diff --git a/website/news/release-0.21-1.mdwn b/website/news/release-0.21-1.mdwn new file mode 100644 index 0000000..e807775 --- /dev/null +++ b/website/news/release-0.21-1.mdwn @@ -0,0 +1,10 @@ +[[meta title="Monkeysphere 0.21-1 released!"]] + +Monkeysphere 0.21-1 has been released. + +Notes from the changelog: + +<pre> +</pre> + +[[Download]] it now! diff --git a/website/signing-host-keys.mdwn b/website/signing-host-keys.mdwn new file mode 100644 index 0000000..1eb61a0 --- /dev/null +++ b/website/signing-host-keys.mdwn @@ -0,0 +1,127 @@ +# Signing a host's SSH key using OpenPGP # + +This page is meant to address the issue of signing OpenPGP-based SSH +host keys. Machines are not people, so the circumstances under which +one should sign a host key are different from those under which one +should sign another person's key. + +# Why are signatures on an SSH host key important? # + +In order for users to validate a host (an SSH server) in a +monkeysphere-enabled network, the host key must have *full* calculated +validity from the perspective of the connecting user. If the user has +not themselves signed the server's key, then the server's key can only +be valid if other people that the user trusts have signed the key. + +If only one person has signed the server's key, then the user must +fully trust the single person who has signed the host key. Full trust +should be granted sparingly and with consideration, though, so unless +the user knows the server admin very well, they will in general not +have full trust of this person. + +However, full trust of the host key can also be achieved if the +server key has been signed by three or more people that the user has + *marginal* trust of. In other words, three or more *marginally* +trusted signatures equals one *fully* trusted signature. It is much +more common for users to have marginal trust of other users in the Web +of Trust. For this reason, it is advisable to have as many people +sign the server key as possible. + +## What information should you have before signing a host key? ## + +Before signing the key of a person, you want to do two things: + +1. verify the identity of the person. +2. verify that the person is actually in control of the key that you +are signing. + +For a server, you want to do basically the same thing: + +1. verify the identity of the server. +2. verify that the server is actually in control of the key that you +are signing. + +However, verifying these things for a server is less intuitive than it +is for a human. + +Verifying that the host is in control of the key is, in principle, +straightforward. If you are logged on to the machine in question, +then you can check directly that the key exists on the system. + +What is not so straightforward is what exactly it means to "verify the +identity" of a remote server on the internet? The identity in this +case is the fully qualified domain name (FQDN) of the host. Verifying +this identity amounts to being sure that the host in question really +is located at that FQDN. + +## Signing the host key ## + +If you are the person (or persons) that actually setup the server and +configured Monkeysphere and ssh on the server, then you should sign +the host key as part of that process. When the server is first set +up, the administrators who set it up are the only ones who can +actually vouch for the server key, so their signatures are necessary +to get things going. Their signatures are also necessary so that they +can validate the host key themselves and log into the server via +monkeysphere-enabled ssh in the future. + +If you did not set up the server initially, you do not have an +accumulated full trust of the person(s) who did, and you do not +necessarily have console access to the server directly, it's hard to +confidently verify the server identity and key ownership. You would +like to be able to walk up to the server, log in at the console, and +get the fingerprint of the ssh host key directly. But this is usually +impossible. + +However, it is still possible to verify the server identity *and* +server ownership of the key, even in this case. + +## Remotely verifying host identity and key possession ## + +It is in fact possible to verify the identity and key ownership of a +server in one fell swoop with monkeysphere-enabled ssh. Here is the +procedure: + +> **Attempt to make a monkeysphere-enabled ssh connection to the host in +question. Monkeysphere will check that the ssh host key offered by the +host matches the OpenPGP key with the correct host FQDN user ID. If +the ssh host key and the OpenPGP key with the correct user ID match, +then you will have effectively:** + +>**1. verified the host identity, because you actually connected to the +host in question, which you know because you:** + +>**2. verified the host is in control of the key, because the ssh host +key offered by the host matches the OpenPGP key with correct host FQDN +user ID.** + +Here is an example: + + servo:~ 0$ ssh zimmermann.mayfirst.org + -------------------- Monkeysphere warning ------------------- + Monkeysphere found OpenPGP keys for this hostname, but none had full validity. + An OpenPGP key matching the ssh key offered by the host was found: + + pub 2048R/860E8F9C 2008-10-29 [expires: 2009-02-26] + uid [marginal] ssh://zimmermann.mayfirst.org + sig! 76CC057D 2008-11-15 Jamie McClelland <jamie@mayfirst.org> + sig!3 860E8F9C 2008-10-29 ssh://zimmermann.mayfirst.org + sig! D21739E9 2008-10-29 Daniel Kahn Gillmor <dkg@fifthhorseman.net> + sig! 1CF2D62A 2008-11-16 Micah Anderson <micah@riseup.net> + + RSA key fingerprint is 81:96:13:3e:24:c9:3c:5b:3c:6d:55:ba:58:85:e9:9e. + -------------------- ssh continues below -------------------- + The authenticity of host 'zimmermann.mayfirst.org (<no hostip for proxy command>)' can't be established. + RSA key fingerprint is 81:96:13:3e:24:c9:3c:5b:3c:6d:55:ba:58:85:e9:9e. + No matching host key fingerprint found in DNS. + Are you sure you want to continue connecting (yes/no)? no + Host key verification failed. + servo:~ 255$ + +I have attempted to connect to the host zimmermann.mayfirst.org. +zimmermann's host key has only *marginal* validity for the FQDN user +ID in question, so I am not able to connect. However, the +Monkeysphere has checked that the ssh host key actually does match the +OpenPGP key with the correct user ID `ssh://zimmermann.mayfirst.org`. +I have therefore verified the identity of zimmermann, and verified +that zimmermann is in possession of the key in question. diff --git a/website/technical-details.mdwn b/website/technical-details.mdwn new file mode 100644 index 0000000..902e356 --- /dev/null +++ b/website/technical-details.mdwn @@ -0,0 +1,28 @@ +[[meta title="Technical Details"]] + +# Technical Details # + +Under construction. + +## Host key verification ## + +When an ssh connection is initiated, the ssh client checks that the +host key presented by the server matches one found in the connecting +user's `known_hosts` file. If so, the ssh client allows the +connection to continue. If not, the client asks the user if they +would like to accept the host key for future session by asking the +user to verify the host key's fingerprint. + +### Adding a server to the monkeysphere ### + +Servers are "monkeysphere enabled" by generating an OpenPGP +authentication key for the server, translating the key into on ssh +key, and publishing the host key to the Web of Trust. + +### Verifying a host key ### + +## User authentication ## + +### Adding an individual to the monkeysphere ### + +### Verifying a user key ### |