Document PPK format parameters, and --reencrypt.

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.
 
@@ -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

@@ -312,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
@@ -351,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