Add some extra documentation: filled in the Getting Started chapter,

added an introduction to public key authentication, and made a
couple of changes in intro.but. Transatlantic flights have some uses
after all.

[originally from svn r1146]

doc/gs.but

@@ -1,3 +1,136 @@
 \C{gs} Getting started with PuTTY
 
-\# Walk the user through starting an SSH or Telnet session.
+This chapter gives a quick guide to the simplest types of
+interactive login session using PuTTY.
+
+\H{gs-insecure} Starting a session
+
+When you start PuTTY, you will see a dialog box. This dialog box
+allows you to control everything PuTTY can do. See \k{config} for
+details of all the things you can control.
+
+You don't usually need to change most of the configuration options.
+To start the simplest kind of session, all you need to do is to
+enter a few basic parameters.
+
+In the \e{Host Name} box, enter the Internet host name of the server
+you want to connect to. You should have been told this by the
+provider of your login account.
+
+Now select a login protocol to use, from the \e{Protocol} buttons.
+For a login session, you should select Telnet, Rlogin or SSH. See
+\k{which-one} for a description of the differences between the three
+protocols, and advice on which one to use. The fourth protocol,
+\e{Raw}, is not used for interactive login sessions; you would
+usually use this for debugging other Internet services.
+
+When you change the selected protocol, the number in the \e{Port}
+box will change. This is normal: it happens because the various
+login services are usually provided on different network ports by
+the server machine. Most servers will use the standard port numbers,
+so you will not need to change the port setting. If your server
+provides login services on a non-standard port, your system
+administrator should have told you which one. (For example, many
+MUDs run Telnet service on a port other than 23.)
+
+Once you have filled in the \e{Host Name}, \e{Protocol}, and
+possibly \e{Port} settings, you are ready to connect. Press the
+\e{Open} button at the bottom of the dialog box, and PuTTY will
+begin trying to connect you to the server.
+
+\H{gs-hostkey} Verifying the Host Key (SSH only)
+
+If you are not using the SSH protocol, you can skip this section.
+
+If you are using SSH to connect to a server for the first time, you
+will probably see a message looking something like this:
+
+\# FIXME: copy the real message from the host key dialog
+
+This is a feature of the SSH protocol. It is designed to protect you
+against a network attack known as \e{spoofing}: secretly redirecting
+your connection to a different computer, so that you send your
+password to the wrong machine. Using this technique, an attacker
+would be able to learn the password that guards your login account,
+and could then log in as if they were you and use the account for
+their own purposes.
+
+To prevent this attack, each server has a unique identifying code,
+called a \e{host key}. These keys are created in a way that prevents
+one server from forging another server's key. So if you connect to a
+server and it sends you a different host key from the one you were
+expecting, PuTTY can warn you that the server may have been switched
+and that a spoofing attack might be in progress.
+
+PuTTY records the host key for each server you connect to, in the
+Windows Registry. Every time you connect to a server, it checks that
+the host key presented by the server is the same host key as it was
+the last time you connected. If it is not, you will see a warning,
+and you will have the chance to abandon your connection before you
+type any private information (such as a password) into it.
+
+However, when you connect to a server you have not connected to
+before, PuTTY has no way of telling whether the host key is the
+right one or not. So it gives the warning shown above, and asks you
+whether you want to trust this host key or not.
+
+Whether or not to trust the host key is your choice. If you are
+connecting within a company network, you might feel that all the
+network users are on the same side and spoofing attacks are
+unlikely, so you might choose to trust the key without checking it.
+If you are connecting across a hostile network (such as the
+Internet), you should check with your system administrator, perhaps
+by telephone or in person. (Some modern servers have more than one
+host key. If the system administrator sends you more than one
+fingerprint, you should make sure the one PuTTY shows you is on the
+list, but it doesn't matter which one it is.)
+
+\# FIXME: this is all very fine but of course in practice the world
+doesn't work that way. Ask the team if they have any good ideas for
+changes to this section!
+
+\H{gs-login} Logging In
+
+After you have connected, and perhaps verified the server's host
+key, you will be asked to log in, probably using a username and a
+password. Your system administrator should have provided you with
+these. Enter the username and the password, and the server should
+grant you access and begin your session. If you have mistyped your
+password, most servers will give you several chances to get it
+right.
+
+If you are using SSH, be careful not to type your username wrongly,
+because you will not have a chance to correct it after you press
+Return. This is an unfortunate feature of the SSH protocol: it does
+not allow you to make two login attempts using different usernames.
+If you type your username wrongly, you must close PuTTY and start
+again.
+
+If your password is refused but you are sure you have typed it
+correctly, check that Caps Lock is not enabled. Many login servers,
+particularly Unix computers, treat upper case and lower case as
+different when checking your password; so if Caps Lock is on, your
+password will probably be refused.
+
+\H{gs-session} After Logging In
+
+After you log in to the server, what happens next is up to the
+server! Most servers will print some sort of login message and then
+present a prompt, at which you can type commands which the server
+will carry out. Some servers will offer you on-line help; others
+might not. If you are in doubt about what to do next, consult your
+system administrator.
+
+\H{gs-logout} Logging Out
+
+When you have finished your session, you should log out by typing
+the server's own logout command. This might vary between servers; if
+in doubt, try \c{logout} or \c{exit}, or consult a manual or your
+system administrator. When the server processes your logout command,
+the PuTTY window should close itself automatically.
+
+You \e{can} close a PuTTY session using the Close button in the
+window border, but this might confuse the server - a bit like
+hanging up a telephone unexpectedly in the middle of a conversation.
+We recommend you do not do this unless the server has stopped
+responding to you and you cannot close the window any other way.

doc/intro.but

@@ -49,7 +49,7 @@ be accessed using Telnet.
 
 You probably do \e{not} want to use SSH, Telnet or Rlogin if:
 
-\b you only use Windows machines. Windows machines have their own
+\b you only use Windows. Windows computers have their own
 ways of networking between themselves, and unless you are doing
 something fairly unusual, you will not need to use any of these
 remote login protocols.
@@ -75,8 +75,9 @@ it has been a constant source of security problems.
 \b SSH and Rlogin both allow you to log in to the server without
 having to type a password. (Rlogin's method of doing this is
 insecure, and can allow an attacker to access your account on the
-server. SSH's method is much more secure, and typically requires the
-attacker to have gained access to your actual client machine.)
+server. SSH's method is much more secure, and typically breaking the
+security requires the attacker to have gained access to your actual
+client machine.)
 
 \b SSH allows you to connect to the server and automatically send a
 command, so that the server will run that command and then
@@ -90,5 +91,3 @@ administrator to install it.
 
 If you are behind a good firewall, it is more likely to be safe to
 use Telnet or Rlogin, but we still recommend you use SSH.
-
-\# perhaps a section on terminal emulation?

doc/pubkey.but

@@ -1,4 +1,4 @@
-\versionid $Id: pubkey.but,v 1.2 2001/02/06 09:34:42 owen Exp $
+\versionid $Id: pubkey.but,v 1.3 2001/06/15 19:31:10 simon Exp $
 
 \# FIXME: passphrases, examples (e.g what does a key for pasting into
 \# authorized_keys look like?), index entries, links.
@@ -7,13 +7,57 @@
 
 \H{pubkey-intro} Public key authentication - an introduction
 
-\# Explain the basic principles of public key authentication. Many
-\# people don't have the faintest idea what it is or why it's good.
+Public key authentication is an alternative means of identifying
+yourself to a login server, instead of typing a password. It is more
+secure and more flexible, but more difficult to set up.
 
-\# Explain the dangers of leaving an unprotected private key around.
-\# Explain passphrases, and urge that people NEVER store
-\# unpassphrased keys unless they really need to or they can be sure
-\# the machine is secure.
+In conventional password authentication, you prove you are who you
+claim to be by proving that you know the correct password. The only
+way to prove you know the password is to tell the server what you
+think the password is. This means that if the server has been
+hacked, or \e{spoofed} (see \k{gs-hostkey}), an attacker can learn
+your password.
+
+Public key authentication solves this problem. You generate a \e{key
+pair}, consisting of a public key (which everybody is allowed to
+know) and a private key (which you keep secret and do not give to
+anybody). The private key is able to generate \e{signatures}.
+A signature created using your private key cannot be forged by
+anybody who does not have that key; but anybody who has your public
+key can verify that a particular signature is genuine.
+
+So you generate a key pair on your own computer, and you copy the
+public key to the server. Then, when the server asks you to prove
+who you are, PuTTY can generate a signature using your private key.
+The server can verify that signature (since it has your public key)
+and allow you to log in. Now if the server is hacked or spoofed, the
+attacker does not gain your private key or password; they only gain
+one signature. And signatures cannot be re-used, so they have gained
+nothing.
+
+There is a problem with this: if your private key is stored
+unprotected on your own computer, then anybody who gains access to
+\e{that} will be able to generate signatures as if they were you. So
+they will be able to log in to your server under your account. For
+this reason, your private key is usually \e{encrypted} when it is
+stored on your local machine, using a passphrase of your choice. In
+order to generate a signature, PuTTY must decrypt the key, so you
+have to type your passphrase.
+
+This can make public-key authentication less convenient than
+password authentication: every time you log in to the server,
+instead of typing a short password, you have to type a longer
+passphrase. One solution to this is to use an \e{authentication
+agent}, a separate program which holds decrypted private keys and
+generates signatures on request. PuTTY's authentication agent is
+called Pageant. When you begin a Windows session, you start Pageant
+and load your public key into it (typing your passphrase once). For
+the rest of your session, you can start PuTTY any number of times
+and Pageant will automatically generate signatures without you
+having to do anything. When you close your Windows session, Pageant
+shuts down, without ever having stored your decrypted private key on
+disk. Many people feel this is a good compromise between security
+and convenience. See \k{pageant} for further details.
 
 \H{pubkey-puttygen} PuTTYgen: RSA key generator for PuTTY
 
@@ -28,7 +72,7 @@ existing private key.
 
 \S{pubkey-puttygen-generate} Generate a new key
 
-Before generating a new key you have to chose the strength of the
+Before generating a new key you have to choose the strength of the
 encryption. With \e{Parameters} you define the strength of the key. The
 default of 1024 should be OK for most users.
 
@@ -37,8 +81,8 @@ new key pair. You then have to move the mouse over the blank area in
 order to generate random data for the algorithm. Continue until the
 progress bar is complete.
 
-As soon as enough random data is available the key is generated.  This 
-may take a little while, especially on slow machines.  Once the key is 
+As soon as enough random data is available the key is generated.  This
+may take a little while, especially on slow machines.  Once the key is
 generated, its details appear in the \e{Key} part of the PuTTYgen
 window.
 
@@ -85,5 +129,3 @@ From now on you can use the private key for authentication to this
 host.  Either select the private key in PuTTY's \e{Connection},
 \e{SSH} panel: \e{Private key file for authentication} dialog or use
 it with Pageant as described in \k{pageant}.
-
-