From ef26ecd81c559339b702a9d6d8779e9cb1a62e37 Mon Sep 17 00:00:00 2001 From: Jacob Nevins Date: Mon, 19 Apr 2021 15:40:35 +0100 Subject: [PATCH 1/4] uxpgnt: Briefly document --symlink and --test-sign. --- doc/man-pageant.but | 32 ++++++++++++++++++++++++++++++++ unix/uxpgnt.c | 1 + 2 files changed, 33 insertions(+) diff --git a/doc/man-pageant.but b/doc/man-pageant.but index 5e31c8b9..358f3a08 100644 --- a/doc/man-pageant.but +++ b/doc/man-pageant.but @@ -294,6 +294,25 @@ with the \cw{--encrypted} option.) (This may leave some keys in cleartext, if they were not previously added with the \cw{--encrypted} option.) +\dt \cw{--test-sign} \e{key-identifier} + +\dt \cw{--test-sign-with-flags=}\e{flags} \e{key-identifier} + +\dd Sign arbitrary data with the given key. This mode is only likely +to be useful when testing \c{pageant} itself. + +\lcont{ + +The data to sign is taken from standard input, signed by the agent +with the key identified by \e{key-identifier}, and the resulting +signature emitted on standard output (as a binary blob in the format +defined by the SSH specifications). + +\e{flags} is a number representing a combination of flag bits defined +by the SSH agent protocol. + +} + \S{pageant-manpage-askpass} SSH-ASKPASS REPLACEMENT \dt \cw{--askpass} \e{prompt} @@ -349,6 +368,19 @@ respectively. If neither option is given, Pageant will guess based on whether the environment variable \cw{SHELL} has a value ending in \cq{csh}. +\dt \cw{--symlink} \e{fixed-path} + +\dd When operating in agent mode, as well as creating a uniquely named +listening socket, \c{pageant} will also create (or update) a symbolic +link at \e{fixed-path} pointing to that socket. + +\lcont{ +This allows access to an agent instance by setting the +\c{SSH_AUTH_SOCK} environment variable to \e{fixed-path}, rather than +having to use the value invented by \c{pageant} when it starts. It's +mainly expected to be useful for debugging. +} + \dt \cw{--encrypted}, \cw{--no-decrypt} \dd When adding keys to the agent (at startup or later), keep them diff --git a/unix/uxpgnt.c b/unix/uxpgnt.c index 4adca625..21087d63 100644 --- a/unix/uxpgnt.c +++ b/unix/uxpgnt.c @@ -211,6 +211,7 @@ static void usage(void) printf("Other options:\n"); printf(" -v verbose mode (in agent mode)\n"); printf(" -s -c force POSIX or C shell syntax (in agent mode)\n"); + printf(" --symlink path create symlink to socket (in agent mode)\n"); printf(" --encrypted when adding keys, don't decrypt\n"); printf(" -E alg, --fptype alg fingerprint type for -l (sha256, md5)\n"); printf(" --tty-prompt force tty-based passphrase prompt\n"); From a0a985957f1d979999a6f500291f54a58992180a Mon Sep 17 00:00:00 2001 From: Jacob Nevins Date: Mon, 19 Apr 2021 15:57:13 +0100 Subject: [PATCH 2/4] Document -ssh-connection (and -ssh) options. --- doc/man-plink.but | 7 +++++++ doc/man-pscp.but | 13 +++++++++++++ doc/man-psftp.but | 13 +++++++++++++ doc/plink.but | 2 +- doc/pscp.but | 4 +++- pscp.c | 2 ++ psftp.c | 2 ++ unix/uxplink.c | 2 +- windows/winplink.c | 2 +- 9 files changed, 43 insertions(+), 4 deletions(-) diff --git a/doc/man-plink.but b/doc/man-plink.but index e5744890..33386227 100644 --- a/doc/man-plink.but +++ b/doc/man-plink.but @@ -56,6 +56,13 @@ to aid in verifying new files released by the PuTTY team. \dd Force serial mode. +\dt \cw{-ssh-connection} + +\dd Force use of the \q{bare \cw{ssh-connection}} protocol. This is +only likely to be useful when connecting to a \e{psusan(1)} server, +most likely with an absolute path to a Unix-domain socket in place +of \e{host}. + \dt \cw{\-proxycmd} \e{command} \dd Instead of making a TCP connection, use \e{command} as a proxy; diff --git a/doc/man-pscp.but b/doc/man-pscp.but index 857a497e..b62e8cc2 100644 --- a/doc/man-pscp.but +++ b/doc/man-pscp.but @@ -115,6 +115,19 @@ commands such as \q{\c{w}}). \dd Force use of SSH protocol version 2. +\dt \cw{-ssh-connection} + +\dd Force use of the \q{bare \cw{ssh-connection}} protocol. This is +only likely to be useful when connecting to a \e{psusan(1)} server, +most likely with an absolute path to a Unix-domain socket in place +of \e{host}. + +\dt \cw{-ssh} + +\dd Force use of the SSH protocol. (This is usually not needed; it's +only likely to be useful if you need to override some other +configuration of the \q{bare \cw{ssh-connection}} protocol.) + \dt \cw{-4}, \cw{-6} \dd Force use of IPv4 or IPv6 for network connections. diff --git a/doc/man-psftp.but b/doc/man-psftp.but index 5611d290..19f820e3 100644 --- a/doc/man-psftp.but +++ b/doc/man-psftp.but @@ -103,6 +103,19 @@ commands such as \q{\c{w}}). \dd Force use of SSH protocol version 2. +\dt \cw{-ssh-connection} + +\dd Force use of the \q{bare \cw{ssh-connection}} protocol. This is +only likely to be useful when connecting to a \e{psusan(1)} server, +most likely with an absolute path to a Unix-domain socket in place +of \e{host}. + +\dt \cw{-ssh} + +\dd Force use of the SSH protocol. (This is usually not needed; it's +only likely to be useful if you need to override some other +configuration of the \q{bare \cw{ssh-connection}} protocol.) + \dt \cw{-4}, \cw{-6} \dd Force use of IPv4 or IPv6 for network connections. diff --git a/doc/plink.but b/doc/plink.but index 8f486e23..4ca7c91b 100644 --- a/doc/plink.but +++ b/doc/plink.but @@ -71,7 +71,7 @@ use Plink: \c -X -x enable / disable X11 forwarding \c -A -a enable / disable agent forwarding \c -t -T enable / disable pty allocation -\c -1 -2 force use of particular protocol version +\c -1 -2 force use of particular SSH protocol version \c -4 -6 force use of IPv4 or IPv6 \c -C enable compression \c -i key private key file for user authentication diff --git a/doc/pscp.but b/doc/pscp.but index 6243938f..381a5864 100644 --- a/doc/pscp.but +++ b/doc/pscp.but @@ -55,6 +55,8 @@ use PSCP: \c -l user connect with specified username \c -pw passw login with specified password \c -1 -2 force use of particular SSH protocol version +\c -ssh -ssh-connection +\c force use of particular SSH protocol variant \c -4 -6 force use of IPv4 or IPv6 \c -C enable compression \c -i key private key file for user authentication @@ -255,7 +257,7 @@ scripts: using \c{-batch}, if something goes wrong at connection time, the batch job will fail rather than hang. \S2{pscp-usage-options-backend}\i\c{-sftp}, \i\c{-scp} force use of -particular protocol +particular file transfer protocol As mentioned in \k{pscp-usage-basics}, there are two different file transfer protocols in use with SSH. Despite its name, PSCP (like many diff --git a/pscp.c b/pscp.c index dc91b18e..0bfda92d 100644 --- a/pscp.c +++ b/pscp.c @@ -2196,6 +2196,8 @@ static void usage(void) printf(" -l user connect with specified username\n"); printf(" -pw passw login with specified password\n"); printf(" -1 -2 force use of particular SSH protocol version\n"); + printf(" -ssh -ssh-connection\n"); + printf(" force use of particular SSH protocol variant\n"); printf(" -4 -6 force use of IPv4 or IPv6\n"); printf(" -C enable compression\n"); printf(" -i key private key file for user authentication\n"); diff --git a/psftp.c b/psftp.c index 57a56eba..40cb73f5 100644 --- a/psftp.c +++ b/psftp.c @@ -2531,6 +2531,8 @@ static void usage(void) printf(" -P port connect to specified port\n"); printf(" -pw passw login with specified password\n"); printf(" -1 -2 force use of particular SSH protocol version\n"); + printf(" -ssh -ssh-connection\n"); + printf(" force use of particular SSH protocol variant\n"); printf(" -4 -6 force use of IPv4 or IPv6\n"); printf(" -C enable compression\n"); printf(" -i key private key file for user authentication\n"); diff --git a/unix/uxplink.c b/unix/uxplink.c index 443c970b..3e2a9b6b 100644 --- a/unix/uxplink.c +++ b/unix/uxplink.c @@ -521,7 +521,7 @@ static void usage(void) printf(" -X -x enable / disable X11 forwarding\n"); printf(" -A -a enable / disable agent forwarding\n"); printf(" -t -T enable / disable pty allocation\n"); - printf(" -1 -2 force use of particular protocol version\n"); + printf(" -1 -2 force use of particular SSH protocol version\n"); printf(" -4 -6 force use of IPv4 or IPv6\n"); printf(" -C enable compression\n"); printf(" -i key private key file for user authentication\n"); diff --git a/windows/winplink.c b/windows/winplink.c index da6c3de2..9bda0712 100644 --- a/windows/winplink.c +++ b/windows/winplink.c @@ -143,7 +143,7 @@ static void usage(void) printf(" -X -x enable / disable X11 forwarding\n"); printf(" -A -a enable / disable agent forwarding\n"); printf(" -t -T enable / disable pty allocation\n"); - printf(" -1 -2 force use of particular protocol version\n"); + printf(" -1 -2 force use of particular SSH protocol version\n"); printf(" -4 -6 force use of IPv4 or IPv6\n"); printf(" -C enable compression\n"); printf(" -i key private key file for user authentication\n"); From 20d5055a3a25106ff4fd031680e766ffa4effa9b Mon Sep 17 00:00:00 2001 From: Jacob Nevins Date: Mon, 19 Apr 2021 16:22:33 +0100 Subject: [PATCH 3/4] Docs: index and cross-reference ssh-connection. --- doc/config.but | 10 +++++++--- doc/index.but | 5 +++++ doc/using.but | 5 ++--- 3 files changed, 14 insertions(+), 6 deletions(-) diff --git a/doc/config.but b/doc/config.but index 7c21c0b9..258974bb 100644 --- a/doc/config.but +++ b/doc/config.but @@ -3389,13 +3389,13 @@ will be impossible. This is an SSH-1-specific bug. -\H{config-psusan} The \q{Bare \cw{ssh-connection}} protocol +\H{config-psusan} The \q{Bare \cw{\i{ssh-connection}}} protocol In addition to SSH itself, PuTTY also supports a second protocol that is derived from SSH. It's listed in the PuTTY GUI under the name \q{Bare \cw{ssh-connection}}. -This protocol consists of just the innermost of SSH's three layers: it +This protocol consists of just the innermost of SSH-2's three layers: it leaves out the cryptography layer providing network security, and it leaves out the authentication layer where you provide a username and prove you're allowed to log in as that user. @@ -3417,7 +3417,7 @@ network namespace. Explicit support for this protocol is new in PuTTY 0.75. As of 2021-04, the only known server for the bare \cw{ssh-connection} -protocol is the Unix program \cq{psusan} that is also part of the +protocol is the Unix program \cq{\i{psusan}} that is also part of the PuTTY tool suite. (However, this protocol is also the same one used between instances of @@ -3428,6 +3428,10 @@ possible to connect another instance of PuTTY directly to that Unix socket, by entering its pathname in the host name box and selecting \q{Bare \cw{ssh-connection}} as the protocol!) +Many of the options under the SSH panel also affect this protocol, +although options to do with cryptography and authentication do not, +for obvious reasons. + I repeat, \s{DON'T TRY TO USE THIS PROTOCOL FOR NETWORK CONNECTIONS!} That's not what it's for, and it's not at all safe to do it. diff --git a/doc/index.but b/doc/index.but index 5f9d59ea..5fd0e7fc 100644 --- a/doc/index.but +++ b/doc/index.but @@ -195,6 +195,11 @@ saved sessions from \IM{protocol selection} selecting a protocol \IM{protocol selection} choosing a protocol +\IM{ssh-connection} bare \cw{ssh-connection} protocol +\IM{ssh-connection} \cw{ssh-connection} protocol, bare + +\IM{psusan} \cq{psusan} program + \IM{login name}{username} login name \IM{login name}{username} user name \IM{login name}{username} account name diff --git a/doc/using.but b/doc/using.but index 9c86b196..b583dc8c 100644 --- a/doc/using.but +++ b/doc/using.but @@ -727,9 +727,8 @@ of these options: \b \i\c{-ssh} selects the SSH protocol. \b \i\c{-ssh-connection} selects the bare ssh-connection protocol. -(This is only useful in specialised circumstances.) -\#{FIXME: describe those circumstances somewhere in this manual, -with reference to the psusan man page} +(This is only useful in specialised circumstances; see \k{config-psusan} +for more information.) \b \i\c{-telnet} selects the Telnet protocol. From 97137f5cfd8b30dc7bf7054ac1ec6a30b9ba7162 Mon Sep 17 00:00:00 2001 From: Jacob Nevins Date: Mon, 19 Apr 2021 17:03:05 +0100 Subject: [PATCH 4/4] PuTTYgen: explicitly use 'Kbyte' in Argon2 naming. Instead of 'Kb', which could be misread as 'Kbit'. --- cmdgen.c | 2 +- doc/pubkeyfmt.but | 2 +- ssh.h | 2 +- test/cryptsuite.py | 2 +- windows/puttygen.rc | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/cmdgen.c b/cmdgen.c index 409b4c5b..e9a17093 100644 --- a/cmdgen.c +++ b/cmdgen.c @@ -157,7 +157,7 @@ void help(void) "default 3)\n" " kdf key derivation function (argon2id, " "argon2i, argon2d)\n" - " memory Kb of memory to use in password hash " + " memory Kbyte of memory to use in password hash " "(default 8192)\n" " time approx milliseconds to hash for " "(default 100)\n" diff --git a/doc/pubkeyfmt.but b/doc/pubkeyfmt.but index d1c92d6d..78da4885 100644 --- a/doc/pubkeyfmt.but +++ b/doc/pubkeyfmt.but @@ -124,7 +124,7 @@ passphrase: password-hashing function. The three integer values are used as parameters for Argon2, which -allows you to configure the amount of memory used (in Kb), the number +allows you to configure the amount of memory used (in Kbyte), the number of passes of the algorithm to run (to tune its running time), and the degree of parallelism required by the hash function. The salt is decoded into a sequence of binary bytes and used as an additional diff --git a/ssh.h b/ssh.h index 08c6797c..49ab2796 100644 --- a/ssh.h +++ b/ssh.h @@ -1242,7 +1242,7 @@ typedef struct ppk_save_parameters { * Parameters for fmt_version == 3 */ Argon2Flavour argon2_flavour; - uint32_t argon2_mem; /* in Kb */ + uint32_t argon2_mem; /* in Kbyte */ bool argon2_passes_auto; union { uint32_t argon2_passes; /* if auto == false */ diff --git a/test/cryptsuite.py b/test/cryptsuite.py index b1eb2818..757de673 100755 --- a/test/cryptsuite.py +++ b/test/cryptsuite.py @@ -1932,7 +1932,7 @@ culpa qui officia deserunt mollit anim id est laborum. secret = b"secret" assoc = b"associated data" - # Smallest memory (8Kb) and parallelism (1) parameters the + # Smallest memory (8Kbyte) and parallelism (1) parameters the # reference implementation will accept, but lots of passes self.assertEqualBin( argon2('i', 8, 16, 1, 24, pwd, salt, secret, assoc), unhex( diff --git a/windows/puttygen.rc b/windows/puttygen.rc index 9d15015d..1209ec48 100644 --- a/windows/puttygen.rc +++ b/windows/puttygen.rc @@ -69,7 +69,7 @@ BEGIN LTEXT "Memory to use for password hash:", IDC_ARGON2_MEM_STATIC, 5, 36, 115, 8 EDITTEXT IDC_ARGON2_MEM, 120, 34, 40, 12 - LTEXT "Kb", IDC_ARGON2_MEM_STATIC2, 170, 36, 34, 8 + LTEXT "Kbyte", IDC_ARGON2_MEM_STATIC2, 170, 36, 34, 8 LTEXT "Time to use for password hash:", IDC_ARGON2_TIME_STATIC, 5, 50, 115, 8 EDITTEXT IDC_ARGON2_TIME, 120, 48, 40, 12