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 7fb89543..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. @@ -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 5b0e3a39..cad6988b 100644 --- a/doc/pubkey.but +++ b/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