Merge fixes (mostly docs) from 'pre-0.75' branch.

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;

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.

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.

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
 

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}
 

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

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. */

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;