diff --git a/cmdgen.c b/cmdgen.c index af7bbe33..920317f5 100644 --- a/cmdgen.c +++ b/cmdgen.c @@ -448,7 +448,7 @@ int main(int argc, char **argv) params.argon2_milliseconds = n; } else if (!strcmp(val, "passes")) { params.argon2_passes_auto = false; - params.argon2_milliseconds = n; + params.argon2_passes = n; } else if (!strcmp(val, "parallelism") || !strcmp(val, "parallel")) { params.argon2_parallelism = n; diff --git a/doc/config.but b/doc/config.but index 258974bb..a00ae476 100644 --- a/doc/config.but +++ b/doc/config.but @@ -14,9 +14,9 @@ save your settings to be reloaded later. \S{config-hostname} The \i{host name} section -The top box on the Session panel, labelled \q{Specify your -connection by host name}, contains the details that need to be -filled in before PuTTY can open a session at all. +The top box on the Session panel, labelled \q{Specify the destination +you want to connect to}, contains the details that need to be filled +in before PuTTY can open a session at all. \b The \q{Host Name} box is where you type the name, or the \i{IP address}, of the server you want to connect to. diff --git a/doc/gs.but b/doc/gs.but index f62fadfa..e6a84923 100644 --- a/doc/gs.but +++ b/doc/gs.but @@ -18,7 +18,7 @@ you want to connect to. You should have been told this by the provider of your login account. Now select a login \i{protocol} to use, from the \q{Connection type} -buttons. For a login session, you should select \i{SSH}, \i{Telnet}, +controls. For a login session, you should select \i{SSH}, \i{Telnet}, \i{Rlogin}, or \i{SUPDUP}. See \k{which-one} for a description of the differences between these protocols, and advice on which one to use. The \I{raw protocol}\e{Raw} protocol is not used for interactive @@ -37,7 +37,7 @@ provides login services on a non-standard port, your system administrator should have told you which one. (For example, many \i{MUDs} run Telnet service on a port other than 23.) -Once you have filled in the \q{Host Name}, \q{Protocol}, and +Once you have filled in the \q{Host Name}, \q{Connection type}, and possibly \q{Port} settings, you are ready to connect. Press the \q{Open} button at the bottom of the dialog box, and PuTTY will begin trying to connect you to the server. diff --git a/doc/index.but b/doc/index.but index 5fd0e7fc..f7e7145a 100644 --- a/doc/index.but +++ b/doc/index.but @@ -277,6 +277,11 @@ saved sessions from \IM{PPK} \cw{PPK} file \IM{PPK} private key file, PuTTY +\IM{Argon2} Argon2 passphrase hashing function + +\IM{passphrase hashing} passphrase hashing, for private key files +\IM{passphrase hashing} password hashing, for private key files + \IM{PGP key fingerprint} PGP key fingerprint \IM{PGP key fingerprint} fingerprint, of PGP key diff --git a/doc/man-puttygen.but b/doc/man-puttygen.but index e4421ce2..021af205 100644 --- a/doc/man-puttygen.but +++ b/doc/man-puttygen.but @@ -8,12 +8,14 @@ \S{puttygen-manpage-synopsis} SYNOPSIS -\c puttygen ( keyfile | -t keytype [ -b bits ] [ --primes method ] ) -\e bbbbbbbb iiiiiii bb iiiiiii bb iiii bbbbbbbb iiiiii -\c [ -C new-comment ] [ -P ] [ -q ] -\e bb iiiiiiiiiii bb bb +\c puttygen ( keyfile | -t keytype [ -b bits ] [ --primes method ] [ -q ] ) +\e bbbbbbbb iiiiiii bb iiiiiii bb iiii bbbbbbbb iiiiii bb +\c [ -C new-comment ] [ -P ] [ --reencrypt ] +\e bb iiiiiiiiiii bb bbbbbbbbbbb \c [ -O output-type | -l | -L | -p | --dump ] [ -E fptype ] \e bb iiiiiiiiiii bb bb bb bbbbbb bb iiiiii +\c [ --ppk-param key=value,... ] +\e bbbbbbbbbbb iiibiiiiib \c [ -o output-file ] \e bb iiiiiiiiiii @@ -26,7 +28,7 @@ also interoperate with the key formats used by some other SSH clients. When you run \c{puttygen}, it does three things. Firstly, it either loads an existing key file (if you specified \e{keyfile}), or generates a new key (if you specified \e{keytype}). Then, it -optionally makes modifications to the key (changing the comment +optionally makes modifications to the key (such as changing the comment and/or the passphrase); finally, it outputs the key, or some information about the key, to a file. @@ -75,7 +77,7 @@ OpenSSH format, or the standard SSH-1 format. \dt \cw{\-\-primes} \e{method} \dd Method for generating prime numbers. The acceptable values here -are \c{probable} (the default), \c{proven}, and \c{proven-even}; the +are \c{probable} (the default), \c{proven}, and \c{proven-even}; the later methods are slower. (Various synonyms for these method names are also accepted.) @@ -99,7 +101,7 @@ probabilistic argument for the safety of the usual method. } -\dd \cw{\-\-strong-rsa} +\dt \cw{\-\-strong-rsa} \dd When generating an RSA key, make sure the prime factors of the key modulus are \q{strong primes}. A strong prime is a prime number chosen @@ -141,6 +143,70 @@ to type). automatic when you are generating a new key, but not when you are modifying an existing key. +\dt \cw{\-\-reencrypt} + +\dd For an existing private key saved with a passphrase, refresh the +encryption without changing the passphrase. + +\lcont{ +This is most likely to be useful with the \cw{\-\-ppk-param} option, +to change some aspect of the key file's format or encryption. +} + +\dt \cw{\-\-ppk-param} \e{key}\cw{=}\e{value}\cw{,}... + +\dd When saving a PPK file (the default \cw{private} output type for SSH-2 +keys), adjust details of the on-disk format. + +\lcont{ + +Aspects to change are specified as a series of \e{key}\cw{=}\e{value} pairs +separated by commas. The \e{key}s are: + +\dt \cw{version} + +\dd The PPK format version. Possible values are \cw{3} (the default) +and \cw{2} (which is less resistant to brute-force decryption, but +which you might need if your key needs to be used by old versions of +PuTTY tools, or other PPK consumers). + +\lcont{ +The following \e{key}s only affect PPK version 3 files. +} + +\dt \cw{kdf} + +\dd The variant of the Argon2 key derivation function to use. Options +are \cw{argon2id} (default, and recommended), \cw{argon2i}, and +\cw{argon2d}. + +\lcont{ +You might change this if you consider your exposure to side-channel +attacks to be different to the norm. +} + +\dt \cw{memory} + +\dd The amount of memory needed to decrypt the key, in Kbyte. Default +is 8192 (i.e., 8 Mbyte). + +\dt \cw{time} + +\dd Approximate time, on this machine, required to attempt decrypting +the key, in milliseconds. Default is 100 (ms). + +\dt \cw{passes} + +\dd Alternative to \cw{time}: explicitly specify the number of hash +passes required to attempt decrypting the key. + +\dt \cw{parallelism} + +\dd Number of parallelisable threads that can be used to decrypt the +key. Default is 1 (force decryption to run single-threaded). + +} + In the third phase, \c{puttygen} saves the key or information about it. The options to control this are: @@ -154,7 +220,8 @@ Acceptable options are: \dt \cw{private} \dd Save the private key in a format usable by PuTTY. This will either -be the standard SSH-1 key format, or PuTTY's own SSH-2 key format. +be the standard SSH-1 key format, or PuTTY's own SSH-2 key format +(\q{PPK}). This is the default. \dt \cw{public} diff --git a/doc/pubkey.but b/doc/pubkey.but index 79bd8bed..cad6988b 100644 --- a/doc/pubkey.but +++ b/doc/pubkey.but @@ -108,7 +108,8 @@ Before generating a key pair using PuTTYgen, you need to select which type of key you need. The current version of the SSH protocol, SSH-2, supports several -different key types. PuTTYgen can generate: +different key types, although specific servers may not support all of +them. PuTTYgen can generate: \b An \i{RSA} key for use with the SSH-2 protocol. @@ -153,7 +154,7 @@ The prime-generation method does not affect compatibility: a key generated with any of these methods will still work with all the same SSH servers. -If you don't care abut this, it's entirely sensible to leave it on the +If you don't care about this, it's entirely sensible to leave it on the default setting. The available methods are: @@ -181,7 +182,7 @@ a local security standard that demands it, or if you don't trust the probabilistic argument for the safety of the usual method. For RSA keys, there's also an option on the \q{Key} menu to use -\q{strong primes} as the prime factors of the public key. A strong +\i{\q{strong} primes} as the prime factors of the public key. A \q{strong} prime is a prime number chosen to have a particular structure that makes certain factoring algorithms more difficult to apply, so some security standards recommend their use. However, the most modern @@ -311,6 +312,10 @@ will need to tell PuTTY to use for authentication (see \k{config-ssh-privkey}) or tell Pageant to load (see \k{pageant-mainwin-addkey}). +(You can optionally change some details of the PPK format for your saved +key files; see \k{puttygen-save-params}. But The defaults should be +fine for most purposes.) + \S{puttygen-savepub} Saving your public key to a disk file RFC 4716 specifies a \I{SSH-2 public key format}standard format for @@ -350,6 +355,60 @@ 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-save-params} Parameters for saving key files + +Selecting \q{Parameters for saving key files...} from the \q{Key} menu +lets you adjust some aspects of PPK-format private key files stored on +disk. None of these options affect compatibility with SSH servers. + +In most cases, it's entirely sensible to leave all of these at their +default settings. + +\S2{puttygen-save-ppk-version} PPK file version + +This defaults to version 3, which is fine for most uses. + +You might need to select PPK version 2 if you need your private key +file to be loadable in older versions of PuTTY (0.74 and older), or in +other tools which do not yet support the version 3 format (which was +introduced in 2021). + +The version 2 format is less resistant to brute-force decryption, and +doesn't support any of the following options to control that. + +\S2{puttygen-save-passphrase-hashing} Options affecting \i{passphrase hashing} + +All of the following options only affect keys saved with passphrases. +They control how much work is required to decrypt the key (which +happens every type you type its passphrase). This allows you to trade +off the cost of legitimate use of the key against the resistance of +the encrypted key to password-guessing attacks. + +These options only affect PPK version 3. + +\dt Key derivation function + +\dd The variant of the \i{Argon2} key derivation function to use. +You might change this if you consider your exposure to side-channel +attacks to be different to the norm. + +\dt Memory to use for passphrase hash + +\dd The amount of memory needed to decrypt the key, in Kbyte. + +\dt Time to use for passphrase hash + +\dd Controls how much time is required to attempt decrypting the key. +You can either specify an approximate time in milliseconds (on this +machine), or explicitly specify a number of hash passes (which is what +the time is turned into during encryption). + +\dt Parallelism for passphrase hash + +\dd Number of parallelisable threads that can be used to decrypt the +key. The default, 1, forces the process to run single-threaded, even +on machines with multiple cores. + \S{puttygen-load} Reloading a private key PuTTYgen allows you to load an existing private key file into diff --git a/windows/winhelp.h b/windows/winhelp.h index 0d7132ae..ae5a7a7f 100644 --- a/windows/winhelp.h +++ b/windows/winhelp.h @@ -186,6 +186,8 @@ #define WINHELP_CTX_puttygen_pastekey "puttygen-pastekey" #define WINHELP_CTX_puttygen_load "puttygen-load" #define WINHELP_CTX_puttygen_conversions "puttygen-conversions" +#define WINHELP_CTX_puttygen_ppkver "puttygen-save-ppk-version" +#define WINHELP_CTX_puttygen_kdfparam "puttygen-save-passphrase-hashing" /* These are used in Windows-specific bits of the frontend. * We (ab)use "help context identifiers" (dwContextId) to identify them. */ diff --git a/windows/winpgen.c b/windows/winpgen.c index 7c44a279..065ada80 100644 --- a/windows/winpgen.c +++ b/windows/winpgen.c @@ -310,6 +310,11 @@ static INT_PTR CALLBACK PPKParamsProc(HWND hwnd, UINT msg, SetWindowPos(hwnd, HWND_TOP, 0, 0, 0, 0, SWP_NOMOVE | SWP_NOSIZE | SWP_SHOWWINDOW); + if (has_help()) + SetWindowLongPtr(hwnd, GWL_EXSTYLE, + GetWindowLongPtr(hwnd, GWL_EXSTYLE) | + WS_EX_CONTEXTHELP); + /* * Centre the window. */ @@ -407,6 +412,36 @@ static INT_PTR CALLBACK PPKParamsProc(HWND hwnd, UINT msg, return 0; } return 0; + case WM_HELP: { + int id = ((LPHELPINFO)lParam)->iCtrlId; + const char *topic = NULL; + switch (id) { + case IDC_PPKVER_STATIC: + case IDC_PPKVER_2: + case IDC_PPKVER_3: + topic = WINHELP_CTX_puttygen_ppkver; break; + case IDC_KDF_STATIC: + case IDC_KDF_ARGON2ID: + case IDC_KDF_ARGON2I: + case IDC_KDF_ARGON2D: + case IDC_ARGON2_MEM_STATIC: + case IDC_ARGON2_MEM: + case IDC_ARGON2_MEM_STATIC2: + case IDC_ARGON2_TIME_STATIC: + case IDC_ARGON2_TIME: + case IDC_PPK_AUTO_YES: + case IDC_PPK_AUTO_NO: + case IDC_ARGON2_PARALLEL_STATIC: + case IDC_ARGON2_PARALLEL: + topic = WINHELP_CTX_puttygen_kdfparam; break; + } + if (topic) { + launch_help(hwnd, topic); + } else { + MessageBeep(0); + } + break; + } case WM_CLOSE: EndDialog(hwnd, 0); return 0;