X-Git-Url: https://git.distorted.org.uk/~mdw/sgt/putty/blobdiff_plain/35cffede3bf184026cc35c666063b6dd8e3c892e..3d5040f8f85f049cbb072a827a6184b4b4314b08:/doc/pageant.but

diff --git a/doc/pageant.but b/doc/pageant.but
index d08563e9..698908cc 100644
--- a/doc/pageant.but
+++ b/doc/pageant.but
@@ -1,20 +1,20 @@
-\versionid $Id: pageant.but,v 1.11 2004/05/22 11:09:31 simon Exp $
+\define{versionidpageant} \versionid $Id$
 
-\C{pageant} Using Pageant for authentication
+\C{pageant} Using \i{Pageant} for authentication
 
 \cfg{winhelp-topic}{pageant.general}
 
-Pageant is an SSH authentication agent. It holds your private keys
-in memory, already decoded, so that you can use them often without
-needing to type a passphrase.
+Pageant is an SSH \i{authentication agent}. It holds your \i{private key}s
+in memory, already decoded, so that you can use them often
+\I{passwordless login}without needing to type a \i{passphrase}.
 
 \H{pageant-start} Getting started with Pageant
 
-Before you run Pageant, you need to have a private key in \c{*.PPK}
+Before you run Pageant, you need to have a private key in \c{*.\i{PPK}}
 format. See \k{pubkey} to find out how to generate and use one.
 
 When you run Pageant, it will put an icon of a computer wearing a
-hat into the System tray. It will then sit and do nothing, until you
+hat into the \ii{System tray}. It will then sit and do nothing, until you
 load a private key into it.
 
 If you click the Pageant icon with the right mouse button, you will
@@ -42,6 +42,10 @@ automatically from Pageant, and use it to authenticate. You can now
 open as many PuTTY sessions as you like without having to type your
 passphrase again.
 
+(PuTTY can be configured not to try to use Pageant, but it will try
+by default. See \k{config-ssh-tryagent} and
+\k{using-cmdline-agentauth} for more information.)
+
 When you want to shut down Pageant, click the right button on the
 Pageant icon in the System tray, and select \q{Exit} from the menu.
 Closing the Pageant main window does \e{not} shut down Pageant.
@@ -68,15 +72,15 @@ something like this:
 For each key, the list box will tell you:
 
 \b The type of the key. Currently, this can be \c{ssh1} (an RSA key
-for use with the SSH v1 protocol), \c{ssh-rsa} (an RSA key for use
-with the SSH v2 protocol), or \c{ssh-dss} (a DSA key for use with
-the SSH v2 protocol).
+for use with the SSH-1 protocol), \c{ssh-rsa} (an RSA key for use
+with the SSH-2 protocol), or \c{ssh-dss} (a DSA key for use with
+the SSH-2 protocol).
 
 \b The size (in bits) of the key.
 
-\b The fingerprint for the public key. This should be the same
-fingerprint given by PuTTYgen, and (hopefully) also the same
-fingerprint shown by remote utilities such as \c{ssh-keygen} when
+\b The \I{key fingerprint}fingerprint for the public key. This should be
+the same fingerprint given by PuTTYgen, and (hopefully) also the same
+fingerprint shown by remote utilities such as \i\c{ssh-keygen} when
 applied to your \c{authorized_keys} file.
 
 \b The comment attached to the key.
@@ -118,9 +122,14 @@ or to keys you added remotely using agent forwarding (see
 \H{pageant-cmdline} The Pageant command line
 
 Pageant can be made to do things automatically when it starts up, by
-specifying instructions on its command line. If you're starting
-Pageant from the Windows GUI, you can arrange this by editing the
-properties of the Windows shortcut that it was started from.
+\I{command-line arguments}specifying instructions on its command line.
+If you're starting Pageant from the Windows GUI, you can arrange this
+by editing the properties of the \i{Windows shortcut} that it was
+started from.
+
+If Pageant is already running, invoking it again with the options
+below causes actions to be performed with the existing instance, not a
+new one.
 
 \S{pageant-cmdline-loadkey} Making Pageant automatically load keys
 on startup
@@ -134,6 +143,9 @@ command line might then look like:
 If the keys are stored encrypted, Pageant will request the
 passphrases on startup.
 
+If Pageant is already running, this syntax loads keys into the
+existing Pageant.
+
 \S{pageant-cmdline-command} Making Pageant run another program
 
 You can arrange for Pageant to start another program once it has
@@ -142,18 +154,18 @@ line. This program (perhaps a PuTTY, or a WinCVS making use of
 Plink, or whatever) will then be able to use the keys Pageant has
 loaded.
 
-You do this by specifying the \c{-c} option followed by the command,
-like this:
+You do this by specifying the \I{-c-pageant}\c{-c} option followed
+by the command, like this:
 
 \c C:\PuTTY\pageant.exe d:\main.ppk -c C:\PuTTY\putty.exe
 
-\H{pageant-forward} Using agent forwarding
+\H{pageant-forward} Using \i{agent forwarding}
 
 Agent forwarding is a mechanism that allows applications on your SSH
 server machine to talk to the agent on your client machine.
 
-Note that at present, agent forwarding in SSH2 is only available
-when your SSH server is OpenSSH. The \cw{ssh.com} server uses a
+Note that at present, agent forwarding in SSH-2 is only available
+when your SSH server is \i{OpenSSH}. The \i\cw{ssh.com} server uses a
 different agent protocol, which PuTTY does not yet support.
 
 To enable agent forwarding, first start Pageant. Then set up a PuTTY
@@ -194,7 +206,7 @@ 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:
+\i\c{ssh-add} command:
 
 \c unixbox:~$ ssh-add ~/.ssh/id_rsa
 \c Need passphrase for /home/fred/.ssh/id_rsa
@@ -207,7 +219,7 @@ available (not just the ones downstream of the place you added it).
 
 \H{pageant-security} Security considerations
 
-Using Pageant for public-key authentication gives you the
+\I{security risk}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.
@@ -220,7 +232,7 @@ but still less secure than not storing them anywhere at all. This is
 for two reasons:
 
 \b Windows unfortunately provides no way to protect pieces of memory
-from being written to the system swap file. So if Pageant is holding
+from being written to the system \i{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
@@ -248,7 +260,7 @@ 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
+agent connection and request signatures from your private 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