From f9d0557330f985ff23dbe5b8e014dc22cecbf13e Mon Sep 17 00:00:00 2001 From: Simon Tatham Date: Thu, 30 Dec 2021 11:49:35 +0000 Subject: [PATCH] Update proxy documentation. This update covers several recently added features: SSH proxying, HTTP Digest proxy auth, and interactive prompting for proxy auth in general. Also, downplayed the use of 'plink -nc' as a Local-type proxy command. It still works, but it's no longer the recommended way of tunnelling SSH over SSH, so there's no need to explain it quite so enthusiastically. --- doc/config.but | 34 ++++++++++++++++++++++++++-------- doc/index.but | 7 +++++-- doc/using.but | 22 +++++++++++++--------- 3 files changed, 44 insertions(+), 19 deletions(-) diff --git a/doc/config.but b/doc/config.but index df935388..b5ad41d0 100644 --- a/doc/config.but +++ b/doc/config.but @@ -1961,6 +1961,12 @@ and enter a command such as \c{connect myhost.com 22} to connect through to an external host. Selecting \I{Telnet proxy}\q{Telnet} allows you to tell PuTTY to use this type of proxy. +\b Selecting \q{SSH} causes PuTTY to make a secondary SSH connection +to the proxy host, and then open a port-forwarding channel to the +final destination host. The \q{Proxy hostname} field will be +interpreted as the name of a PuTTY saved session if one exists, or a +hostname if not. + \b Selecting \I{Local proxy}\q{Local} allows you to specify an arbitrary command on the local machine to act as a proxy. When the session is started, instead of creating a TCP connection, PuTTY runs the command @@ -1972,11 +1978,6 @@ This could be used, for instance, to talk to some kind of network proxy that PuTTY does not natively support; or you could tunnel a connection over something other than TCP/IP entirely. -If you want your local proxy command to make a secondary SSH -connection to a proxy host and then tunnel the primary connection -over that, you might well want the \c{-nc} command-line option in -Plink. See \k{using-cmdline-ncmode} for more information. - You can also enable this mode on the command line; see \k{using-cmdline-proxycmd}. } @@ -2069,18 +2070,35 @@ proxies and SOCKS 5 proxies. supports it (this is not supported in \i{PuTTYtel}); otherwise the password is sent to the proxy in \I{plaintext password}plain text. -\b With HTTP proxying, the only currently supported authentication -method is \I{HTTP basic}\q{basic}, where the password is sent to the proxy -in \I{plaintext password}plain text. +\b With HTTP proxying, authentication is via \q{\i{HTTP Digest}} if +possible (again, not supported in PuTTYtel), or \q{\i{HTTP Basic}}. In +the latter case, the password is sent to the proxy in \I{plaintext +password}plain text. } \b SOCKS 4 can use the \q{Username} field, but does not support passwords. +\b SSH proxying can use all the same forms of SSH authentication +supported by PuTTY for its main connection. If the SSH server requests +password authentication, the configured proxy password will be used, +but other authentication methods such as public keys will be tried +first, just as for a primary SSH connection. + \b You can specify a way to include a username and password in the Telnet/Local proxy command (see \k{config-proxy-command}). +If PuTTY discovers that it needs a proxy username or password and you +have not specified one in the configuration, it will prompt for it +interactively in the terminal. + +(For SSH proxying, this will also happen in the case of other +interactive SSH login prompts, such as SSH key passphrases or GSSAPI. +For the Telnet and Local proxy types, PuTTY will prompt for a username +or password if you included \c{%user} or \c{%pass} in the command +string and did not provide a corresponding configuration entry.) + \S{config-proxy-command} Specifying the Telnet or Local proxy command If you are using the \i{Telnet proxy} type, the usual command required diff --git a/doc/index.but b/doc/index.but index 1e04acc1..afd74167 100644 --- a/doc/index.but +++ b/doc/index.but @@ -608,8 +608,11 @@ saved sessions from \IM{proxy authentication} proxy authentication \IM{proxy authentication} authentication, to proxy -\IM{HTTP basic} HTTP \q{basic} authentication -\IM{HTTP basic} \q{basic} authentication (HTTP) +\IM{HTTP Basic} HTTP Basic authentication +\IM{HTTP Basic} \q{basic} authentication (HTTP) + +\IM{HTTP Digest} HTTP Digest authentication +\IM{HTTP Digest} \q{digest} authentication (HTTP) \IM{plaintext password} plain text password \IM{plaintext password} password, plain text diff --git a/doc/using.but b/doc/using.but index 8811b5fa..d5cf41c4 100644 --- a/doc/using.but +++ b/doc/using.but @@ -947,15 +947,19 @@ this: \c plink host1.example.com -nc host2.example.com:1234 -You might want to use this feature if you needed to make an SSH -connection to a target host which you can only reach by going -through a proxy host, and rather than using port forwarding you -prefer to use the local proxy feature (see \k{config-proxy-type} for -more about local proxies). In this situation you might select -\q{Local} proxy type, set your local proxy command to be \cq{plink -%proxyhost -nc %host:%port}, enter the target host name on the -Session panel, and enter the directly reachable proxy host name on -the Proxy panel. +This can be useful if you're trying to make a connection to a target +host which you can only reach by SSH forwarding through a proxy host. +One way to do this would be to have an existing SSH connection to the +proxy host, with a port forwarding, but if you prefer to have the +connection started on demand as needed, then this approach can also +work. + +However, this does depend on the program \e{using} the proxy being +able to run a subprocess in place of making a network connection. +PuTTY itself can do this using the \q{Local} proxy type, but there's a +built-in more flexible way using the \q{SSH} proxy type. (See +\k{config-proxy-type} for a description of both.) So this feature is +probably most useful with another client program as the end user. This feature is only available in SSH protocol version 2 (since the version 1 protocol assumes you will always want to run a shell). It