From 228dba26343aa8fdad67157a85549f102877083b Mon Sep 17 00:00:00 2001 From: Daniel Kahn Gillmor Date: Fri, 20 Feb 2009 13:22:09 -0500 Subject: readability revision for getting-started-admin.mdwn --- website/getting-started-admin.mdwn | 116 ++++++++++++++++++++++--------------- 1 file changed, 68 insertions(+), 48 deletions(-) (limited to 'website') diff --git a/website/getting-started-admin.mdwn b/website/getting-started-admin.mdwn index 9010132..d1146f1 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,40 @@ 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 -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: +This will generate an OpenPGP certificate for server containing the +service URI (`ssh://server.example.net`). 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 +65,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 +86,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 +118,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. -- cgit v1.2.3 From b876492913c3b1aabf08ff44250882d3b9c0b3ad Mon Sep 17 00:00:00 2001 From: Daniel Kahn Gillmor Date: Fri, 20 Feb 2009 15:23:38 -0500 Subject: documentation overhaul for users just getting started. --- website/advanced-user.mdwn | 137 +++++++++++++++++ website/doc.mdwn | 2 + website/getting-started-user.mdwn | 305 +++++++++++++++++--------------------- 3 files changed, 275 insertions(+), 169 deletions(-) create mode 100644 website/advanced-user.mdwn (limited to 'website') diff --git a/website/advanced-user.mdwn b/website/advanced-user.mdwn new file mode 100644 index 0000000..ecb094b --- /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 the Monkeysphere 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 + + 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 + + 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 + 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. diff --git a/website/doc.mdwn b/website/doc.mdwn index 28db2ef..85d619e 100644 --- a/website/doc.mdwn +++ b/website/doc.mdwn @@ -10,7 +10,9 @@ ## Going further ## + * [Advanced Monkeysphere usage](/advanced-user) * [Signing host keys](/signing-host-keys) + * [Understandingn trust models](/trust-models) ## Under the hood ## diff --git a/website/getting-started-user.mdwn b/website/getting-started-user.mdwn index ec157ac..46f9015 100644 --- a/website/getting-started-user.mdwn +++ b/website/getting-started-user.mdwn @@ -3,60 +3,35 @@ 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 @@ -68,146 +43,138 @@ by entering: 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 - - 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 - - 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 - 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/ -- cgit v1.2.3 From 5d98461822dce7c8c0cfe1218decf2f6e7503f98 Mon Sep 17 00:00:00 2001 From: Daniel Kahn Gillmor Date: Fri, 20 Feb 2009 15:25:14 -0500 Subject: documentation tuning. --- website/advanced-user.mdwn | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'website') diff --git a/website/advanced-user.mdwn b/website/advanced-user.mdwn index ecb094b..138fd48 100644 --- a/website/advanced-user.mdwn +++ b/website/advanced-user.mdwn @@ -10,9 +10,9 @@ 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 the Monkeysphere to check on hosts -that were not originally in the monkeysphere, to see if their host key -is now published. +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: -- cgit v1.2.3 From bd0a7f8322f4543044c7e22d0890a2891e44962f Mon Sep 17 00:00:00 2001 From: Daniel Kahn Gillmor Date: Fri, 20 Feb 2009 15:29:34 -0500 Subject: more wordsmithing. --- website/advanced-user.mdwn | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'website') diff --git a/website/advanced-user.mdwn b/website/advanced-user.mdwn index 138fd48..7969018 100644 --- a/website/advanced-user.mdwn +++ b/website/advanced-user.mdwn @@ -105,19 +105,19 @@ 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). +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. 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. +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: -- cgit v1.2.3 From c71fa871b97700d696c5222201405ab681f0b4e9 Mon Sep 17 00:00:00 2001 From: Jameson Graef Rollins Date: Fri, 20 Feb 2009 18:09:37 -0500 Subject: Add "true" to prerm script so that lintian will stop complaining that the script is empty. also small doc tweaks. --- packaging/debian/monkeysphere.prerm | 2 ++ website/doc.mdwn | 4 ++-- website/getting-started-user.mdwn | 2 +- 3 files changed, 5 insertions(+), 3 deletions(-) (limited to 'website') diff --git a/packaging/debian/monkeysphere.prerm b/packaging/debian/monkeysphere.prerm index 1fb2636..5835f53 100755 --- a/packaging/debian/monkeysphere.prerm +++ b/packaging/debian/monkeysphere.prerm @@ -5,6 +5,8 @@ # Author: Jameson Rollins # Copyright 2008-2009 +true + # dh_installdeb will replace this with shell code automatically # generated by other debhelper scripts. diff --git a/website/doc.mdwn b/website/doc.mdwn index 85d619e..47b173a 100644 --- a/website/doc.mdwn +++ b/website/doc.mdwn @@ -12,11 +12,11 @@ * [Advanced Monkeysphere usage](/advanced-user) * [Signing host keys](/signing-host-keys) - * [Understandingn trust models](/trust-models) + * [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-user.mdwn b/website/getting-started-user.mdwn index 46f9015..9e2be26 100644 --- a/website/getting-started-user.mdwn +++ b/website/getting-started-user.mdwn @@ -36,7 +36,7 @@ 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 * -- cgit v1.2.3 From ab8a5011501a708c873122e34ea914a6dfab772e Mon Sep 17 00:00:00 2001 From: Jameson Graef Rollins Date: Sat, 21 Feb 2009 13:08:55 -0500 Subject: added note about specifying a hostname for import-key in the admin getting started page. --- website/getting-started-admin.mdwn | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) (limited to 'website') diff --git a/website/getting-started-admin.mdwn b/website/getting-started-admin.mdwn index d1146f1..c4c2e64 100644 --- a/website/getting-started-admin.mdwn +++ b/website/getting-started-admin.mdwn @@ -22,12 +22,22 @@ 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 import-key /etc/ssh/ssh\_host\_rsa\_key + # monkeysphere-host import-key /etc/ssh/ssh_host_rsa_key -This will generate an OpenPGP certificate for server containing the -service URI (`ssh://server.example.net`). Now you can display -information about the host key's certificate with the 'show-key' -command: +This will generate an OpenPGP certificate for server. The primary +user ID for this certificate will be the ssh service URI for the host, +which by default is based on the output of `hostname -f` +(eg. `ssh://server.example.net`). If the name determined from +`hostname -f` is not the name you want to have in the service URI, +then you can enter one manually: + + # monkeysphere-host import-key /etc/ssh/ssh_host_rsa_key host.example.net + +Remember that the name you provide here must be a fully qualified +domain name for the host in order for the monkeysphere to work. + +Now you can display information about the host key's certificate with +the 'show-key' command: # monkeysphere-host show-key -- cgit v1.2.3 From 5b7c3c817fda89dc5954f79ba2eb209dd07f3edf Mon Sep 17 00:00:00 2001 From: Daniel Kahn Gillmor Date: Sat, 21 Feb 2009 14:49:54 -0500 Subject: tweaking m-h getting started docs. --- website/getting-started-admin.mdwn | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'website') diff --git a/website/getting-started-admin.mdwn b/website/getting-started-admin.mdwn index c4c2e64..6bdd166 100644 --- a/website/getting-started-admin.mdwn +++ b/website/getting-started-admin.mdwn @@ -24,17 +24,17 @@ RSA key. Once that has been done, import the key: # monkeysphere-host import-key /etc/ssh/ssh_host_rsa_key -This will generate an OpenPGP certificate for server. The primary +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, which by default is based on the output of `hostname -f` (eg. `ssh://server.example.net`). If the name determined from `hostname -f` is not the name you want to have in the service URI, -then you can enter one manually: +then you can provide one manually: # monkeysphere-host import-key /etc/ssh/ssh_host_rsa_key host.example.net -Remember that the name you provide here must be a fully qualified -domain name for the host in order for the monkeysphere to work. +The hostname you provide should probably be a fully qualified domain +name for the host in order for your users to find it. Now you can display information about the host key's certificate with the 'show-key' command: -- cgit v1.2.3 From bb8f498db80efcfffdf60ef317254d7355ea54ef Mon Sep 17 00:00:00 2001 From: Jameson Graef Rollins Date: Sat, 21 Feb 2009 15:37:30 -0500 Subject: import-key now requires a hostname be specified, and no longer does any hostname guessing. this is so that we don't have to worry about prompting the user when guessing the hostname. also updated documentation. --- man/man8/monkeysphere-host.8 | 11 +++++------ src/monkeysphere-host | 2 +- src/share/mh/import_key | 30 ++---------------------------- website/getting-started-admin.mdwn | 14 ++++---------- 4 files changed, 12 insertions(+), 45 deletions(-) (limited to 'website') diff --git a/man/man8/monkeysphere-host.8 b/man/man8/monkeysphere-host.8 index 0a9fc1b..7909b62 100644 --- a/man/man8/monkeysphere-host.8 +++ b/man/man8/monkeysphere-host.8 @@ -23,14 +23,13 @@ connection authentication. \fBmonkeysphere-host\fP takes various subcommands: .TP -.B import-key FILE [NAME[:PORT]] +.B import-key FILE NAME[:PORT] Import a pem-encoded ssh secret host key from file FILE. If FILE is '-', then the key will be imported from stdin. NAME[:PORT] is used -to specify the hostname (and port) used in the user ID of the new -OpenPGP key. If NAME is not specified, then the system -fully-qualified domain name will be used (ie. `hostname -f'). If PORT -is not specified, the no port is added to the user ID, which means -port 22 is assumed. `i' may be used in place of `import-key'. +to specify the fully-qualified hostname (and port) used in the user ID +of the new OpenPGP key. If PORT is not specified, the no port is +added to the user ID, which means port 22 is assumed. `i' may be used +in place of `import-key'. .TP .B show-key Output information about host's OpenPGP and SSH keys. `s' may be used diff --git a/src/monkeysphere-host b/src/monkeysphere-host index efa48cd..540a8ab 100755 --- a/src/monkeysphere-host +++ b/src/monkeysphere-host @@ -54,7 +54,7 @@ usage: $PGRM [options] [args] Monkeysphere host admin tool. subcommands: - import-key (i) FILE [NAME[:PORT]] import existing ssh key to gpg + import-key (i) FILE NAME[:PORT] import existing ssh key to gpg show-key (s) output all host key information publish-key (p) publish host key to keyserver set-expire (e) [EXPIRE] set host key expiration diff --git a/src/share/mh/import_key b/src/share/mh/import_key index c545388..f7c69c3 100644 --- a/src/share/mh/import_key +++ b/src/share/mh/import_key @@ -26,39 +26,13 @@ if [ -z "$sshKeyFile" ] ; then failure "Must specify ssh key file to import, or specify '-' for stdin." fi -# use the default hostname if not specified +# fail if hostname not specified if [ -z "$hostName" ] ; then - hostName=$(hostname -f) || failure "Could not determine hostname." - # test that the domain is not obviously illegitimate - domain=${foo##*.} - case $domain in - 'local'|'localdomain') - failure "Host domain '$domain' is not legitimate. Aborting key import." - ;; - esac - # test that there are at least two parts - if (( $(echo "$hostName" | tr . ' ' | wc -w) < 2 )) ; then - failure "Host name '$hostName' is not legitimate. Aborting key import." - fi + failure "You must specify a fully-qualified domain name for use in the host certificate user ID." fi userID="ssh://${hostName}" -if [ "$PROMPT" = "true" ] ; then - cat <