Miscellaneous documentation updates. Finished a first draft of the

Pageant chapter; wrote something about passphrase lengths; added
\versionid to all chapters that didn't have it yet.

[originally from svn r1415]

doc/config.but

@@ -1,3 +1,5 @@
+\versionid $Id: config.but,v 1.12 2001/11/25 16:57:45 simon Exp $
+
 \C{config} Configuring PuTTY
 
 This chapter describes all the configuration options in PuTTY.

doc/faq.but

@@ -1,3 +1,5 @@
+\versionid $Id: faq.but,v 1.11 2001/11/25 16:57:45 simon Exp $
+
 \A{faq} PuTTY FAQ
 
 This FAQ is published on the PuTTY web site, and also provided as an

doc/gs.but

@@ -1,3 +1,5 @@
+\versionid $Id: gs.but,v 1.4 2001/11/25 16:57:45 simon Exp $
+
 \C{gs} Getting started with PuTTY
 
 This chapter gives a quick guide to the simplest types of

doc/intro.but

@@ -1,3 +1,5 @@
+\versionid $Id: intro.but,v 1.4 2001/11/25 16:57:45 simon Exp $
+
 \C{intro} Introduction to PuTTY
 
 PuTTY is a free SSH, Telnet and Rlogin client for 32-bit Windows

doc/pageant.but

@@ -1,3 +1,5 @@
+\versionid $Id: pageant.but,v 1.4 2001/11/25 16:57:45 simon Exp $
+
 \C{pageant} Using Pageant for authentication
 
 Pageant is an SSH authentication agent. It holds your private keys
@@ -42,20 +44,115 @@ Closing the Pageant main window does \e{not} shut down Pageant.
 
 \H{pageant-forward} Using agent forwarding
 
-\# Walk the user through enabling agent forwarding and starting a
-\# second-level session.
+Agent forwarding is a mechanism that allows applications on your SSH
+server machine to talk to the agent on your client machine.
 
-\# Demonstrate the use of ssh-add at the remote end.
+Note that at present, agent forwarding in SSH2 is only available
+when your SSH server is OpenSSH. The \cw{ssh.com} server uses a
+different agent protocol which they have not published. If you would
+like PuTTY to be able to support agent forwarding to an \cw{ssh.com}
+server, please write to \cw{ssh.com} and explain to them that they
+are hurting themselves and their users by keeping their protocol
+secret.
+
+To enable agent forwarding, first start Pageant. Then set up a PuTTY
+SSH session in which \q{Allow agent forwarding} is enabled (see
+\k{config-ssh-agentfwd}). Open the session as normal.
+
+If this has worked, your applications on the server should now have
+access to a Unix domain socket which the SSH server will forward
+back to PuTTY, and PuTTY will forward on to the agent. To check that
+this has actually happened, you can try this command on Unix server
+machines:
+
+\c unixbox:~$ echo $SSH_AUTH_SOCK
+\c /tmp/ssh-XXNP18Jz/agent.28794
+\c unixbox:~$
+
+If the result line comes up blank, agent forwarding has not been
+enabled at all.
+
+Now if you run \c{ssh} on the server and use it to connect through
+to another server that accepts one of the keys in Pageant, you
+should be able to log in without a password:
+
+\c unixbox:~$ ssh -v otherunixbox
+\c [...]
+\c debug: next auth method to try is publickey
+\c debug: userauth_pubkey_agent: trying agent key my-putty-key
+\c debug: ssh-userauth2 successful: method publickey
+\c [...]
+
+If you enable agent forwarding on \e{that} SSH connection as well
+(see the manual for your server-side SSH client to find out how to
+do this), your authentication keys will still be available on the
+next machine you connect to - two SSH connections away from where
+they're actually stored.
+
+In addition, if you have a private key on one of the SSH servers,
+you can send it all the way back to Pageant using the local
+\c{ssh-add} command:
+
+\c unixbox:~$ ssh-add ~/.ssh/id_rsa
+\c Need passphrase for /home/fred/.ssh/id_rsa
+\c Enter passphrase for /home/fred/.ssh/id_rsa:
+\c Identity added: /home/fred/.ssh/id_rsa (/home/simon/.ssh/id_rsa)
+\c unixbox:~$
+
+and then it's available to every machine that has agent forwarding
+available (not just the ones downstream of the place you added it).
 
 \H{pageant-security} Security considerations
 
-\# Explain that local use of Pageant allows you convenient one-touch
-\# authentication without ever storing a decrypted key on disk
+Using Pageant for public-key authentication gives you the
+convenience of being able to open multiple SSH sessions without
+having to type a passphrase every time, but also gives you the
+security benefit of never storing a decrypted private key on disk.
+Many people feel this is a good compromise between security and
+convenience.
 
-\# Explain that, despite this, it still doesn't protect you against
-\# your local machine being hacked (swap files, but more importantly
-\# trojans)
+It \e{is} a compromise, however. Holding your decrypted private keys
+in Pageant is better than storing them in easy-to-find disk files,
+but still less secure than not storing them anywhere at all. This is
+for two reasons:
 
-\# Explain that forwarding agent connections to a remote site
-\# can be abused by the sysadmin of that site, so you'd better know
-\# you can trust them
+\b Windows unfortunately provides no way to protect pieces of memory
+from being written to the system swap file. So if Pageant is holding
+your private keys for a long period of time, it's possible that
+decrypted private key data may be written to the system swap file,
+and an attacker who gained access to your hard disk later on might
+be able to recover that data. (However, if you stored an unencrypted
+key in a disk file they would \e{certainly} be able to recover it.)
+
+\b Although, like most modern operating systems, Windows prevents
+programs from accidentally accessing one another's memory space, it
+does allow programs to access one another's memory space
+deliberately, for special purposes such as debugging. This means
+that if you allow a virus, trojan, or other malicious program on to
+your Windows system while Pageant is running, it could access the
+memory of the Pageant process, extract your decrypted authentication
+keys, and send them back to its master.
+
+Similarly, use of agent \e{forwarding} is a security improvement on
+other methods of one-touch authentication, but not perfect. Holding
+your keys in Pageant on your Windows box has a security advantage
+over holding them on the remote server machine itself (either in an
+agent or just unencrypted on disk), because if the server machine
+ever sees your unencrypted private key then the sysadmin or anyone
+who cracks the machine can steal the keys and pretend to be you for
+as long as they want.
+
+However, the sysadmin of the server machine can always pretend to be
+you \e{on that machine}. So if you forward your agent to a server
+machine, then the sysadmin of that machine can access the forwarded
+agent connection and request signatures from your public keys, and
+can therefore log in to other machines as you. They can only do this
+to a limited extent - when the agent forwarding disappears they lose
+the ability - but using Pageant doesn't actually \e{prevent} the
+sysadmin (or hackers) on the server from doing this.
+
+Therefore, if you don't trust the sysadmin of a server machine, you
+should \e{never} use agent forwarding to that machine. (Of course
+you also shouldn't store private keys on that machine, type
+passphrases into it, or log into other machines from it in any way
+at all; Pageant is hardly unique in this respect.)

doc/plink.but

@@ -1,18 +1,7 @@
-\versionid $Id: plink.but,v 1.9 2001/09/22 17:34:10 simon Exp $
+\versionid $Id: plink.but,v 1.10 2001/11/25 16:57:45 simon Exp $
 
 \C{plink} Using the command-line connection tool Plink
 
-\# Explain Plink
-
-\# Explain that Plink is probably not what you want if you want to
-\# run an interactive session in a Command Prompt window
-
-\# Explain that Plink is really for batch-file use, and that
-\# therefore it works best with public-key authentication; link to
-\# that chapter
-
-\# Give instructions on how to set up Plink with CVS
-
 \i{Plink} (PuTTY Link) is a command-line connection tool similar to
 UNIX \c{ssh}.  It is probably not what you want if you want to run
 an interactive session in a console window.

doc/pubkey.but

@@ -1,4 +1,4 @@
-\versionid $Id: pubkey.but,v 1.6 2001/09/25 19:59:14 simon Exp $
+\versionid $Id: pubkey.but,v 1.7 2001/11/25 16:57:45 simon Exp $
 
 \# FIXME: passphrases, examples (e.g what does a key for pasting into
 \# authorized_keys look like?), index entries, links.
@@ -126,12 +126,16 @@ meaningful comment may help you remember which passphrase to use!  You
 should always enter a \e{Key passphrase} and \e{Confirm passphrase} to
 protect your keys.
 
-\# FIXME: Mention a good length for a passphrase. (I think Schneier
-\# said something about this on counterpane.com once.)
-
-\# In case people don't like the idea of exchanging a short password
-\# typed every time for a longer passphrase typed every time, link
-\# to the Pageant chapter.
+(Choosing a good passphrase is difficult. Just as you shouldn't use
+a dictionary word as a password because it's easy for an attacker to
+run through a whole dictionary, you should not use a song lyric,
+quotation or other well-known sentence as a passphrase. DiceWare
+(\W{www.diceware.com}\cw{www.diceware.com}) recommends using at
+least five words each generated randomly by rolling five dice, which
+gives over 2^64 possible passwords and is probably not a bad scheme.
+If you want your passphrase to make grammatical sense, this cuts
+down the possibilities a lot and you should use a longer one as a
+result.)
 
 Finally save the key by pressing the \e{Save} button. Do not close the
 window but proceed with step \k{pubkey-gettingready}, otherwise you