nhyatt/putty-source
1
0
Fork 0
mirror of https://git.tartarus.org/simon/putty.git synced 2025-01-25 09:12:24 +00:00
Code Issues Projects Releases Wiki Activity

Updated the PuTTYgen section in pubkey.but so that it gives

Browse Source 
individual documentation of the various PuTTYgen controls; also
implemented context help in PuTTYgen to go with it. Shame there
isn't space for a generic `Help' button in the PuTTYgen window.

[originally from svn r1478]
This commit is contained in:
Simon Tatham 2001-12-12 18:45:56 +00:00
parent 7983d2dd28
commit f9cbbc3387
2 changed files with 347 additions and 67 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

327
doc/pubkey.but
View File

@ -1,7 +1,4 @@
\versionid $Id: pubkey.but,v 1.11 2001/12/06 20:05:39 simon Exp $ \versionid $Id: pubkey.but,v 1.12 2001/12/12 18:45:56 simon Exp $
\# FIXME: passphrases, examples (e.g what does a key for pasting into
\# authorized_keys look like?), index entries, links.
\C{pubkey} Using public keys for SSH authentication \C{pubkey} Using public keys for SSH authentication
@ -59,10 +56,61 @@ shuts down, without ever having stored your decrypted private key on
disk. Many people feel this is a good compromise between security disk. Many people feel this is a good compromise between security
and convenience. See \k{pageant} for further details. and convenience. See \k{pageant} for further details.
\S{pubkey-types} Different types of public key There is more than one public-key algorithm available. The most
common is RSA, but others exist, notably DSA (otherwise known as
DSS), the USA's federal Digital Signature Standard. The key types
supported by PuTTY are described in \k{puttygen-keytype}.
The PuTTY key generator, described in \k{pubkey-puttygen}, offers \H{pubkey-puttygen} Using PuTTYgen, the PuTTY key generator
you the opportunity to generate several types of key pair:
PuTTYgen is a key generator. It generates pairs of public and private
keys to be used with PuTTY, PSCP, and Plink, as well as the PuTTY
authentication agent, Pageant (see \k{pageant}). PuTTYgen generates
RSA keys.
When you run PuTTYgen you will see a window where you have two
choices: \q{Generate}, to generate a new public/private key pair, or
\q{Load} to load in an existing private key.
\S{puttygen-generating} Generating a new key
This is a general outline of the procedure for generating a new key
pair. The following sections describe the process in more detail.
\b First, you need to select which type of key you want to generate,
and also select the strength of the key. This is described in more
detail in \k{puttygen-keytype} and
\k{puttygen-strength}.
\b Then press the \q{Generate} button, to actually generate the key.
\K{puttygen-generate} describes this step.
\b Once you have generated the key, select a comment field
(\k{puttygen-comment}) and a passphrase (\k{puttygen-passphrase}).
\b Now you're ready to save the private key to disk; press the
\q{Save private key} button. (See \k{puttygen-savepriv}).
Your key pair is now ready for use. You may also want to copy the
public key to your server, either by copying it out of the \q{Public
key for pasting into authorized_keys file} box (see
\k{puttygen-pastekey}), or by using the \q{Save public key} button
(\k{puttygen-savepub}). However, you don't need to do this
immediately; if you want, you can load the private key back into
PuTTYgen later (see \k{puttygen-load}) and the public key will be
available for copying and pasting again.
\k{pubkey-gettingready} describes the typical process of configuring
PuTTY to attempt public-key authentication, and configuring your SSH
server to accept it.
\S{puttygen-keytype} Selecting the type of key
\cfg{winhelp-topic}{puttygen.keytype}
Before generating a public key using PuTTYgen, you need to select
which type of key you need. PuTTYgen currently supports three types
of key:
\b An RSA key for use with the SSH 1 protocol. \b An RSA key for use with the SSH 1 protocol.
@ -74,8 +122,8 @@ The SSH 1 protocol only supports RSA keys; if you will be connecting
using the SSH 1 protocol, you must select the first key type or your using the SSH 1 protocol, you must select the first key type or your
key will be completely useless. key will be completely useless.
SSH 2 supports more than one key type. The two types supported by The SSH 2 protocol supports more than one key type. The two types
PuTTY are RSA and DSA. supported by PuTTY are RSA and DSA.
The PuTTY developers \e{strongly} recommend you use RSA. DSA has an The PuTTY developers \e{strongly} recommend you use RSA. DSA has an
intrinsic weakness which makes it very easy to create a signature intrinsic weakness which makes it very easy to create a signature
@ -91,44 +139,111 @@ DSA, then you probably have no choice but to use DSA. If you do use
DSA, we recommend you do not use the same key to authenticate with DSA, we recommend you do not use the same key to authenticate with
more than one server. more than one server.
\H{pubkey-puttygen} PuTTYgen: Key generator for PuTTY \S{puttygen-strength} Selecting the size (strength) of the key
PuTTYgen is a key generator. It generates pairs of public and private \cfg{winhelp-topic}{puttygen.bits}
keys to be used with PuTTY, PSCP, and Plink, as well as the PuTTY
authentication agent, Pageant (see \k{pageant}). PuTTYgen generates
RSA keys.
When you run PuTTYgen you will see a window where you have two The \q{Number of bits} input box allows you to choose the strength
choices: \q{Generate}, to generate a new public/private key pair, or of the key PuTTYgen will generate.
\q{Load} to load in an existing private key.
\S{pubkey-puttygen-generate} Generate a new key Currently 1024 bits should be sufficient for most purposes.
Before generating a new key you have to choose the strength of the \S{puttygen-generate} The \q{Generate} button
encryption, and the type of the key (see \k{pubkey-types}). With
\q{Parameters} you define the strength of the key. The default of
1024 should be OK for most users.
Pressing the \q{Generate} button starts the process of generating a \cfg{winhelp-topic}{puttygen.generate}
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 Once you have chosen the type of key you want, and the strength of
may take a little while, especially on slow machines. Once the key is the key, press the \q{Generate} button and PuTTYgen will begin the
generated, its details appear in the \q{Key} part of the PuTTYgen process of actually generating the key.
window.
Now you can change the \q{Key comment} field to something more First, a progress bar will appear and PuTTYgen will ask you to move
meaningful than the default (which is based on the current date). the mouse around to generate randomness. Wave the mouse in circles
e.g. add the name of the host you will use it for. When using over the blank area in the PuTTYgen window, and the progress bar
multiple keys a meaningful comment may help you remember which will gradually fill up as PuTTYgen collects enough randomness. You
passphrase to use! You should always enter a passphrase in the don't need to wave the mouse in particularly imaginative patterns
\q{Key passphrase} and \q{Confirm passphrase} fields, to protect (although it can't hurt); PuTTYgen will collect enough randomness
your keys. just from the fine detail of \e{exactly} how far the mouse has moved
each time Windows samples its position.
(Choosing a good passphrase is difficult. Just as you shouldn't use When the progress bar reaches the end, PuTTYgen will begin creating
a dictionary word as a password because it's easy for an attacker to the key. The progress bar will reset to the start, and gradually
move up again to track the progress of the key generation. It will
not move evenly, and may occasionally slow down to a stop; this is
unfortunately unavoidable, because key generation is a random
process and it is impossible to reliably predict how long it will
take.
When the key generation is complete, a new set of controls will
appear in the window to indicate this.
\S{puttygen-fingerprint} The \q{Key fingerprint} box
\cfg{winhelp-topic}{puttygen.fingerprint}
The \q{Key fingerprint} box shows you a fingerprint value for the
generated key. This is derived cryptographically from the \e{public}
key value, so it doesn't need to be kept secret.
The fingerprint value is intended to be cryptographically secure, in
the sense that it is computationally infeasible for someone to
invent a second key with the same fingerprint, or to find a key with
a particular fingerprint. So some utilities, such as the Pageant key
list box (see \k{pageant-mainwin-keylist}) and the Unix \c{ssh-add}
utility, will list key fingerprints rather than the whole public key.
\S{puttygen-comment} Setting a comment for your key
\cfg{winhelp-topic}{puttygen.comment}
If you have more than one key and use them for different purposes,
you don't need to memorise the key fingerprints in order to tell
them apart. PuTTY allows you to enter a \e{comment} for your key,
which will be displayed whenever PuTTY or Pageant asks you for the
passphrase.
The default comment format, if you don't specify one, contains the
key type and the date of generation, such as \c{rsa-key-20011212}.
Another commonly used approach is to use your name and the name of
the computer the key will be used on, such as \c{simon@simons-pc}.
To alter the key comment, just type your comment text into the
\q{Key comment} box before saving the private key. If you want to
change the comment later, you can load the private key back into
PuTTYgen, change the comment, and save it again.
\S{puttygen-passphrase} Setting a passphrase for your key
\cfg{winhelp-topic}{puttygen.passphrase}
The \q{Key passphrase} and \q{Confirm passphrase} boxes allow you to
choose a passphrase for your key. The passphrase will be used to
encrypt the key on disk, so you will not be able to use the key
without first entering the passphrase.
When you save the key, PuTTY will check that the \q{Key passphrase}
and \q{Confirm passphrase} boxes both contain exactly the same
passphrase, and will refuse to save the key otherwise.
If you leave the passphrase fields blank, the key will be saved
unencrypted. You should \e{not} do this without good reason; if you
do, your private key file on disk will be all an attacker needs to
gain access to any machine configured to accept that key. If you
want to be able to log in without having to type a passphrase every
time, you should consider using Pageant (\k{pageant}) so that your
decrypted key is only held in memory rather than on disk.
Under special circumstances you may genuinely \e{need} to use a key
with no passphrase; for example, if you need to run an automated
batch script that needs to make an SSH connection, you can't be
there to type the passphrase. In this case we recommend you generate
a special key for each specific batch script (or whatever) that
needs one, and on the server side you should arrange that each key
is \e{restricted} so that it can only be used for that specific
purpose. The documentation for your SSH server should explain how to
do this (it will probably vary between servers).
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, run through a whole dictionary, you should not use a song lyric,
quotation or other well-known sentence as a passphrase. DiceWare quotation or other well-known sentence as a passphrase. DiceWare
(\W{http://www.diceware.com/}\cw{www.diceware.com}) recommends using (\W{http://www.diceware.com/}\cw{www.diceware.com}) recommends using
@ -136,21 +251,84 @@ at least five words each generated randomly by rolling five dice,
which gives over 2^64 possible passphrases and is probably not a bad which gives over 2^64 possible passphrases and is probably not a bad
scheme. If you want your passphrase to make grammatical sense, this 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 cuts down the possibilities a lot and you should use a longer one as
a result.) a result.
Finally save the key by pressing the \q{Save} button. Do not close the \e{Do not forget your passphrase}. There is no way to recover it.
window but proceed with step \k{pubkey-gettingready}, otherwise you
will have to load the private key again (as described below).
\S{pubkey-puttygen-load} Load and modify a key \S{puttygen-savepriv} Saving your private key to a disk file
PuTTYgen does not store the public key in a file by default. If you \cfg{winhelp-topic}{puttygen.savepriv}
have to distribute the public key you can press the \q{Load} button,
select the private key file, and PuTTYgen will give you the public key
again. You can also change the comment and passphrase for your
private key this way. Just modify the values and save the key.
\S{pubkey-gettingready} Getting ready for public key authentication Once you have generated a key, set a comment field and set a
passphrase, you are ready to save your private key to disk.
Press the \q{Save private key} button. PuTTYgen will put up a dialog
box asking you where to save the file. Select a directory, type in a
file name, and press \q{Save}.
This file is the one you will need to tell PuTTY to use for
authentication (see \k{config-ssh-privkey}) or tell Pageant to load
(see \k{pageant-mainwin-addkey}).
\S{puttygen-savepub} Saving your public key to a disk file
\cfg{winhelp-topic}{puttygen.savepub}
The SSH 2 protocol drafts specify a standard format for storing
public keys on disk. Some SSH servers (such as \cw{ssh.com}'s)
require a public key in this format in order to accept
authentication with the corresponding private key. (Others, such as
OpenSSH, use a different format; see \k{puttygen-pastekey}.)
To save your public key in the SSH 2 standard format, press the
\q{Save public key} button in PuTTYgen. PuTTYgen will put up a
dialog box asking you where to save the file. Select a directory,
type in a file name, and press \q{Save}.
You will then probably want to copy the public key file to your SSH
server machine. See \k{pubkey-gettingready} for general instructions
on configuring public-key authentication once you have generated a
key.
If you use this option with an SSH 1 key, the file PuTTYgen saves
will contain exactly the same text that appears in the \q{Public key
for pasting} box. This is the only existing standard for SSH 1
public keys.
\S{puttygen-pastekey} \q{Public key for pasting into authorized_keys
file}
\cfg{winhelp-topic}{puttygen.pastekey}
All SSH 1 servers require your public key to be given to it in a
one-line format before it will accept authentication with your
private key. The OpenSSH server also requires this for SSH 2.
The \q{Public key for pasting into authorized_keys file} gives the
public-key data in the correct one-line format. Typically you will
want to select the entire contents of the box using the mouse, press
Ctrl+C to copy it to the clipboard, and then paste the data into a
PuTTY session which is already connected to the server.
See \k{pubkey-gettingready} for general instructions on configuring
public-key authentication once you have generated a key.
\S{puttygen-load} Reloading a private key
\cfg{winhelp-topic}{puttygen.load}
PuTTYgen allows you to load an existing private key file into
memory. If you do this, you can then change the passphrase and
comment before saving it again; you can also make extra copies of
the public key.
To load an existing key, press the \q{Load} button. PuTTYgen will
put up a dialog box where you can browse around the file system and
find your key file. Once you select the file, PuTTYgen will ask you
for a passphrase (if necessary) and will then display the key
details in the same way as if it had just generated the key.
\H{pubkey-gettingready} Getting ready for public key authentication
Connect to your SSH server using PuTTY with the SSH protocol. When the Connect to your SSH server using PuTTY with the SSH protocol. When the
connection succeeds you will be prompted for your user name and connection succeeds you will be prompted for your user name and
@ -162,28 +340,43 @@ into the \c{.ssh} directory and open the file \c{authorized_keys}
with your favorite editor. (You may have to create this file if this with your favorite editor. (You may have to create this file if this
is the first key you have put in it). Then switch to the PuTTYgen is the first key you have put in it). Then switch to the PuTTYgen
window, select all of the text in the \q{Public key for pasting into window, select all of the text in the \q{Public key for pasting into
authorized_keys file} box, and copy it to the clipboard authorized_keys file} box (see \k{puttygen-pastekey}), and copy it
(\c{Ctrl+C}). Then, switch back to the PuTTY window and insert the to the clipboard (\c{Ctrl+C}). Then, switch back to the PuTTY window
data into the open file, making sure it ends up all on one line. and insert the data into the open file, making sure it ends up all
Save the file. on one line. Save the file.
\b If your server is OpenSSH and is using the SSH 2 protocol, you \b If your server is OpenSSH and is using the SSH 2 protocol, you
should follow the same instructions except that the file will be should follow the same instructions, except that in earlier versions
called \c{authorized_keys2}. of OpenSSH 2 the file might be called \c{authorized_keys2}. (In
modern versions the same \c{authorized_keys} file is used for both
SSH 1 and SSH 2 keys.)
\b If your server is \cw{ssh.com}'s SSH 2 product, you need to save \b If your server is \cw{ssh.com}'s SSH 2 product, you need to save
a \e{public} key file from PuTTYgen, and copy that into the a \e{public} key file from PuTTYgen (see \k{puttygen-savepub}), and
\c{.ssh2} directory on the server. Then you should go into that copy that into the \c{.ssh2} directory on the server. Then you
\c{.ssh2} directory, and edit (or create) a file called should go into that \c{.ssh2} directory, and edit (or create) a file
\c{authorization}. In this file you should put a line like \c{Key called \c{authorization}. In this file you should put a line like
mykey.pub}, with \c{mykey.pub} replaced by the name of your key \c{Key mykey.pub}, with \c{mykey.pub} replaced by the name of your
file. key file.
\b For other SSH server software, you should refer to the manual for \b For other SSH server software, you should refer to the manual for
that server. that server.
From now on you should be able to use the private key for You may also need to ensure that your home directory, your \c{.ssh}
authentication to this host. Either select the private key in directory, and any other files involved (such as
PuTTY's \q{Connection}, \q{SSH} panel: \q{Private key file for \c{authorized_keys}, \c{authorized_keys2} or \c{authorization}) are
authentication} dialog or use it with Pageant as described in not group-writable. You can typically do this by using a command
\k{pageant}. such as
\c chmod g-w $HOME $HOME/.ssh $HOME/.ssh/authorized_keys
Your server should now be configured to accept authentication using
your private key. Now you need to configure PuTTY to \e{attempt}
authentication using your private key. You can do this in either of
two ways:
\b Select the private key in PuTTY's configuration. See
\k{config-ssh-privkey} for details.
\b Load the private key into Pageant (see \k{pageant}). In this case
PuTTY will automatically try to use it for authentication if it can.

87
puttygen.c
View File

@ -18,6 +18,8 @@
#define DEFAULT_KEYSIZE 1024 #define DEFAULT_KEYSIZE 1024
static int requested_help;
/* ---------------------------------------------------------------------- /* ----------------------------------------------------------------------
* Progress report code. This is really horrible :-) * Progress report code. This is really horrible :-)
*/ */
@ -518,6 +520,17 @@ static int CALLBACK MainDlgProc(HWND hwnd, UINT msg,
switch (msg) { switch (msg) {
case WM_INITDIALOG: case WM_INITDIALOG:
if (help_path)
SetWindowLong(hwnd, GWL_EXSTYLE,
GetWindowLong(hwnd, GWL_EXSTYLE) | WS_EX_CONTEXTHELP);
else {
/*
* If we add a Help button, this is where we destroy it
* if the help file isn't present.
*/
}
requested_help = FALSE;
/* /*
* Centre the window. * Centre the window.
*/ */
@ -1067,9 +1080,62 @@ static int CALLBACK MainDlgProc(HWND hwnd, UINT msg,
hidemany(hwnd, generating_ids, TRUE); hidemany(hwnd, generating_ids, TRUE);
hidemany(hwnd, gotkey_ids, FALSE); hidemany(hwnd, gotkey_ids, FALSE);
break; break;
case WM_HELP:
if (help_path) {
int id = ((LPHELPINFO)lParam)->iCtrlId;
char *cmd = NULL;
switch (id) {
case IDC_GENERATING:
case IDC_PROGRESS:
case IDC_GENSTATIC:
case IDC_GENERATE:
cmd = "JI(`',`puttygen.generate')"; break;
case IDC_PKSTATIC:
case IDC_KEYDISPLAY:
cmd = "JI(`',`puttygen.pastekey')"; break;
case IDC_FPSTATIC:
case IDC_FINGERPRINT:
cmd = "JI(`',`puttygen.fingerprint')"; break;
case IDC_COMMENTSTATIC:
case IDC_COMMENTEDIT:
cmd = "JI(`',`puttygen.comment')"; break;
case IDC_PASSPHRASE1STATIC:
case IDC_PASSPHRASE1EDIT:
case IDC_PASSPHRASE2STATIC:
case IDC_PASSPHRASE2EDIT:
cmd = "JI(`',`puttygen.passphrase')"; break;
case IDC_LOADSTATIC:
case IDC_LOAD:
cmd = "JI(`',`puttygen.load')"; break;
case IDC_SAVESTATIC:
case IDC_SAVE:
cmd = "JI(`',`puttygen.savepriv')"; break;
case IDC_SAVEPUB:
cmd = "JI(`',`puttygen.savepub')"; break;
case IDC_TYPESTATIC:
case IDC_KEYSSH1:
case IDC_KEYSSH2RSA:
case IDC_KEYSSH2DSA:
cmd = "JI(`',`puttygen.keytype')"; break;
case IDC_BITSSTATIC:
case IDC_BITS:
cmd = "JI(`',`puttygen.bits')"; break;
}
if (cmd) {
WinHelp(hwnd, help_path, HELP_COMMAND, (DWORD)cmd);
requested_help = TRUE;
} else {
MessageBeep(0);
}
}
break;
case WM_CLOSE: case WM_CLOSE:
state = (struct MainDlgState *) GetWindowLong(hwnd, GWL_USERDATA); state = (struct MainDlgState *) GetWindowLong(hwnd, GWL_USERDATA);
sfree(state); sfree(state);
if (requested_help) {
WinHelp(hwnd, help_path, HELP_QUIT, 0);
requested_help = FALSE;
}
EndDialog(hwnd, 1); EndDialog(hwnd, 1);
return 0; return 0;
} }
@ -1080,6 +1146,27 @@ int WINAPI WinMain(HINSTANCE inst, HINSTANCE prev, LPSTR cmdline, int show)
{ {
InitCommonControls(); InitCommonControls();
hinst = inst; hinst = inst;
/*
* See if we can find our Help file.
*/
{
char b[2048], *p, *q, *r;
FILE *fp;
GetModuleFileName(NULL, b, sizeof(b) - 1);
r = b;
p = strrchr(b, '\\');
if (p && p >= r) r = p+1;
q = strrchr(b, ':');
if (q && q >= r) r = q+1;
strcpy(r, "putty.hlp");
if ( (fp = fopen(b, "r")) != NULL) {
help_path = dupstr(b);
fclose(fp);
} else
help_path = NULL;
}
random_init(); random_init();
return DialogBox(hinst, MAKEINTRESOURCE(201), NULL, return DialogBox(hinst, MAKEINTRESOURCE(201), NULL,
MainDlgProc) != IDOK; MainDlgProc) != IDOK;