diff options
Diffstat (limited to 'DOC')
| -rw-r--r-- | DOC/BLURB.BUT | 1 | ||||
| -rw-r--r-- | DOC/CONFIG.BUT | 466 | ||||
| -rw-r--r-- | DOC/ERRORS.BUT | 44 | ||||
| -rw-r--r-- | DOC/FAQ.BUT | 50 | ||||
| -rw-r--r-- | DOC/GS.BUT | 13 | ||||
| -rw-r--r-- | DOC/INDEX.BUT | 40 | ||||
| -rw-r--r-- | DOC/MAKEFILE | 80 | ||||
| -rw-r--r-- | DOC/MAN-PSCP.BUT | 13 | ||||
| -rw-r--r-- | DOC/PAGEANT.BUT | 125 | ||||
| -rw-r--r-- | DOC/PGPKEYS.BUT | 46 | ||||
| -rw-r--r-- | DOC/PLINK.BUT | 4 | ||||
| -rw-r--r-- | DOC/PSCP.BUT | 4 | ||||
| -rw-r--r-- | DOC/PUBKEY.BUT | 161 | ||||
| -rw-r--r-- | DOC/SSHNAMES.BUT | 2 | ||||
| -rw-r--r-- | DOC/UDP.BUT | 135 | ||||
| -rw-r--r-- | DOC/USING.BUT | 66 | ||||
| -rw-r--r-- | DOC/man-pageant.but | 14 | ||||
| -rw-r--r-- | DOC/man-plink.but | 13 | ||||
| -rw-r--r-- | DOC/man-psftp.but | 13 | ||||
| -rw-r--r-- | DOC/man-psocks.but | 8 | ||||
| -rw-r--r-- | DOC/man-psusan.but | 64 | ||||
| -rw-r--r-- | DOC/man-pterm.but | 2 | ||||
| -rw-r--r-- | DOC/man-putty.but | 2 | ||||
| -rw-r--r-- | DOC/man-puttygen.but | 62 | ||||
| -rw-r--r-- | DOC/man-puttytel.but | 2 | ||||
| -rw-r--r-- | DOC/pubkeyfmt.but | 6 |
26 files changed, 1063 insertions, 373 deletions
diff --git a/DOC/BLURB.BUT b/DOC/BLURB.BUT index f980e9f1..c68a6262 100644 --- a/DOC/BLURB.BUT +++ b/DOC/BLURB.BUT @@ -17,7 +17,6 @@ page</a>.</p>} \cfg{chm-contents-filename}{index.html} \cfg{chm-template-filename}{%k.html} \cfg{chm-head-end}{<link rel="stylesheet" type="text/css" href="chm.css">} -\cfg{chm-extra-file}{chm.css} \cfg{xhtml-contents-filename}{index.html} \cfg{text-filename}{puttydoc.txt} diff --git a/DOC/CONFIG.BUT b/DOC/CONFIG.BUT index 77313282..f258a356 100644 --- a/DOC/CONFIG.BUT +++ b/DOC/CONFIG.BUT @@ -596,6 +596,33 @@ through to \c{ESC [j}. With control they generate \c{ESC [k} through to \c{ESC [v}, and with shift and control together they generate \c{ESC [w} through to \c{ESC [\{}. +\b In \I{xterm}Xterm 216 mode, the unshifted function keys behave the +same as Xterm R6 mode. But pressing a function key together with Shift +or Alt or Ctrl generates a different sequence containing an extra +numeric parameter of the form (1 for Shift) + (2 for Alt) + (4 for +Ctrl) + 1. For F1-F4, the basic sequences like \c{ESC OP} become +\cw{ESC [1;}\e{bitmap}\cw{P} and similar; for F5 and above, +\cw{ESC[}\e{index}\cw{~} becomes +\cw{ESC[}\e{index}\cw{;}\e{bitmap}\cw{~}. + +If you don't know what any of this means, you probably don't need to +fiddle with it. + +\S{config-sharrow} Changing the action of the \i{shifted arrow keys} + +This option affects the arrow keys, if you press one with any of the +modifier keys Shift, Ctrl or Alt held down. + +\b In the default mode, labelled \c{Ctrl toggles app mode}, the Ctrl +key toggles between the default arrow-key sequences like \c{ESC [A} and +\c{ESC [B}, and the sequences Digital's terminals generate in +\q{application cursor keys} mode, i.e. \c{ESC O A} and so on. Shift +and Alt have no effect. + +\b In the \q{xterm-style bitmap} mode, Shift, Ctrl and Alt all +generate different sequences, with a number indicating which set of +modifiers is active. + If you don't know what any of this means, you probably don't need to fiddle with it. @@ -1342,7 +1369,7 @@ which one of the options is \q{Paste}). (This context menu is always available by holding down Ctrl and right-clicking, regardless of the setting of this option.) -(When PuTTY iself is running on Unix, it follows the X Window System +(When PuTTY itself is running on Unix, it follows the X Window System convention.) \S{config-mouseshift} \q{Shift overrides application's use of mouse} @@ -1916,23 +1943,50 @@ it must always be explicitly configured. \S{config-proxy-type} Setting the proxy type -The \q{Proxy type} radio buttons allow you to configure what type of +The \q{Proxy type} drop-down allows you to configure what type of proxy you want PuTTY to use for its network connections. The default setting is \q{None}; in this mode no proxy is used for any connection. -\b Selecting \I{HTTP proxy}\q{HTTP} allows you to proxy your connections -through a web server supporting the HTTP \cw{CONNECT} command, as documented -in \W{http://www.ietf.org/rfc/rfc2817.txt}{RFC 2817}. +\b Selecting \I{HTTP proxy}\q{HTTP CONNECT} allows you to proxy your +connections through a web server supporting the HTTP \cw{CONNECT} command, +as documented in \W{https://www.rfc-editor.org/rfc/rfc2817}{RFC 2817}. \b Selecting \q{SOCKS 4} or \q{SOCKS 5} allows you to proxy your connections through a \i{SOCKS server}. \b Many firewalls implement a less formal type of proxy in which a -user can make a Telnet connection directly to the firewall machine +user can make a Telnet or TCP connection directly to the firewall machine 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. +allows you to tell PuTTY to use this type of proxy, with the precise +command specified as described in \k{config-proxy-command}. + +\b There are several ways to use a SSH server as a proxy. All of +these cause PuTTY to make a secondary SSH connection to the proxy host +(sometimes called a \q{\i{jump host}} in this context). + +\lcont{ +The \q{Proxy hostname} field will be interpreted as the name of a +PuTTY saved session if one exists, or a hostname if not. This +allows multi-hop jump paths, if the referenced saved session is +itself configured to use an SSH proxy; and it allows combining SSH +and non-SSH proxying. + +\b \q{SSH to proxy and use port forwarding} causes PuTTY to use the +secondary SSH connection to open a port-forwarding channel to the +final destination host (similar to OpenSSH's \cw{-J} option). + +\b \q{SSH to proxy and execute a command} causes PuTTY to run an +arbitrary remote command on the proxy SSH server and use that +command's standard input and output streams to run the primary +connection over. The remote command line is specified as described in +\k{config-proxy-command}. + +\b \q{SSH to proxy and invoke a subsystem} is similar but causes PuTTY +to start an SSH \q{\i{subsystem}} rather than an ordinary command line. +This might be useful with a specially set up SSH proxy server. +} \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 @@ -1945,11 +1999,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}. } @@ -2007,9 +2056,9 @@ set it to \q{Yes}, PuTTY will always pass host names straight to the proxy without trying to look them up first. If you set this option to \q{Auto} (the default), PuTTY will do -something it considers appropriate for each type of proxy. Telnet, -HTTP, and SOCKS5 proxies will have host names passed straight to -them; SOCKS4 proxies will not. +something it considers appropriate for each type of proxy. Most +types of proxy (HTTP, SOCK5, SSH, Telnet, and local) will have host +names passed straight to them; SOCKS4 proxies will not. Note that if you are doing DNS at the proxy, you should make sure that your proxy exclusion settings (see \k{config-proxy-exclude}) do @@ -2022,15 +2071,30 @@ is a protocol extension (SOCKS 4A) which does support it, but not all SOCKS 4 servers provide this extension. If you enable proxy DNS and your SOCKS 4 server cannot deal with it, this might be why. +If you want to avoid PuTTY making \e{any} DNS query related to your +destination host name (for example, because your local DNS resolver is +very slow to return a negative response in that situation), then as +well as setting this control to \q{Yes}, you may also need to turn off +GSSAPI authentication and GSSAPI key exchange in SSH (see +\k{config-ssh-auth-gssapi} and \k{config-ssh-gssapi-kex} +respectively). This is because GSSAPI setup also involves a DNS query +for the destination host name, and that query is performed by the +separate GSSAPI library, so PuTTY can't override or reconfigure it. + \S{config-proxy-auth} \I{proxy username}Username and \I{proxy password}password -If your proxy requires \I{proxy authentication}authentication, you can -enter a username and a password in the \q{Username} and \q{Password} boxes. +You can enter a username and a password in the \q{Username} and +\q{Password} boxes, which will be used if your proxy requires +\I{proxy authentication}authentication. \I{security hazard}Note that if you save your session, the proxy password will be saved in plain text, so anyone who can access your PuTTY configuration data will be able to discover it. +If PuTTY discovers that it needs a proxy username or password and you +have not specified one here, PuTTY will prompt for it interactively in +the terminal window. + Authentication is not fully supported for all forms of proxy: \b Username and password authentication is supported for HTTP @@ -2042,28 +2106,44 @@ 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, any configured proxy password will be used, +but other authentication methods such as public keys and GSSAPI will +be tried first, just as for a primary SSH connection, and if they +require credentials such as a key passphrase, PuTTY will interactively +prompt for these. + \b You can specify a way to include a username and password in the -Telnet/Local proxy command (see \k{config-proxy-command}). +Telnet/Local proxy command (see \k{config-proxy-command}). If you do +so, and don't also specify the actual username and/or password in the +configuration, PuTTY will interactively prompt for them. -\S{config-proxy-command} Specifying the Telnet or Local proxy command +\S{config-proxy-command} Specifying the Telnet, SSH, or Local proxy command If you are using the \i{Telnet proxy} type, the usual command required by the firewall's Telnet server is \c{connect}, followed by a host name and a port number. If your proxy needs a different command, -you can enter an alternative here. +you can enter an alternative in the \q{Command to send to proxy} box. If you are using the \i{Local proxy} type, the local command to run is specified here. +If you are using the \q{SSH to proxy and execute a command} type, the +command to run on the SSH proxy server is specified here. Similarly, if +you are using \q{SSH to proxy and invoke a subsystem}, the subsystem +name is constructed as specified here. + In this string, you can use \c{\\n} to represent a new-line, \c{\\r} to represent a carriage return, \c{\\t} to represent a tab character, and \c{\\x} followed by two hex digits to represent any @@ -2071,12 +2151,15 @@ other character. \c{\\\\} is used to encode the \c{\\} character itself. Also, the special strings \c{%host} and \c{%port} will be replaced -by the host name and port number you want to connect to. The strings -\c{%user} and \c{%pass} will be replaced by the proxy username and -password you specify. The strings \c{%proxyhost} and \c{%proxyport} +by the host name and port number you want to connect to. For Telnet +and Local proxy types, the strings \c{%user} and \c{%pass} will be +replaced by the proxy username and password (which, if not specified +in the configuration, will be prompted for) \dash this does not happen +with SSH proxy types (because the proxy username/password are used +for SSH authentication). The strings \c{%proxyhost} and \c{%proxyport} will be replaced by the host details specified on the \e{Proxy} panel, -if any (this is most likely to be useful for the Local proxy type). -To get a literal \c{%} sign, enter \c{%%}. +if any (this is most likely to be useful for proxy types using a +local or remote command). To get a literal \c{%} sign, enter \c{%%}. If a Telnet proxy server prompts for a username and password before commands can be sent, you can use a command such as: @@ -2086,8 +2169,8 @@ before commands can be sent, you can use a command such as: This will send your username and password as the first two lines to the proxy, followed by a command to connect to the desired host and port. Note that if you do not include the \c{%user} or \c{%pass} -tokens in the Telnet command, then the \q{Username} and \q{Password} -configuration fields will be ignored. +tokens in the Telnet command, then anything specified in \q{Username} +and \q{Password} configuration fields will be ignored. \S{config-proxy-logging} Controlling \i{proxy logging} @@ -2264,24 +2347,51 @@ cipher selection (see \k{config-ssh-encryption}). PuTTY currently supports the following key exchange methods: -\b \q{ECDH}: \i{elliptic curve} \i{Diffie-Hellman key exchange}. +\b \q{NTRU Prime / Curve25519 hybrid}: \q{\i{Streamlined NTRU Prime}} +is a lattice-based algorithm intended to resist \i{quantum attacks}. +In this key exchange method, it is run in parallel with a conventional +Curve25519-based method (one of those included in \q{ECDH}), in such +a way that it should be no \e{less} secure than that commonly-used +method, and hopefully also resistant to a new class of attacks. -\b \q{Group 14}: Diffie-Hellman key exchange with a well-known -2048-bit group. +\b \q{\i{ECDH}}: elliptic curve Diffie-Hellman key exchange, +with a variety of standard curves and hash algorithms. -\b \q{Group 1}: Diffie-Hellman key exchange with a well-known -1024-bit group. We no longer recommend using this method, and it's -not used by default in new installations; however, it may be the -only method supported by very old server software. +\b The original form of \i{Diffie-Hellman key exchange}, with a +variety of well-known groups and hashes: -\b \q{\ii{Group exchange}}: with this method, instead of using a fixed -group, PuTTY requests that the server suggest a group to use for key -exchange; the server can avoid groups known to be weak, and possibly -invent new ones over time, without any changes required to PuTTY's -configuration. We recommend use of this method instead of the -well-known groups, if possible. +\lcont{ +\b \q{Group 18}, a well-known 8192-bit group, used with the SHA-512 +hash function. -\b \q{\i{RSA key exchange}}: this requires much less computational +\b \q{Group 17}, a well-known 6144-bit group, used with the SHA-512 +hash function. + +\b \q{Group 16}, a well-known 4096-bit group, used with the SHA-512 +hash function. + +\b \q{Group 15}, a well-known 3072-bit group, used with the SHA-512 +hash function. + +\b \q{Group 14}: a well-known 2048-bit group, used with the SHA-256 +hash function or, if the server doesn't support that, SHA-1. + +\b \q{Group 1}: a well-known 1024-bit group, used with the SHA-1 +hash function. Neither we nor current SSH standards recommend using +this method any longer, and it's not used by default in new +installations; however, it may be the only method supported by very +old server software. +} + +\b \q{Diffie-Hellman \i{group exchange}}: with this method, instead +of using a fixed group, PuTTY requests that the server suggest a group +to use for a subsequent Diffie-Hellman key exchange; the server can +avoid groups known to be weak, and possibly invent new ones over time, +without any changes required to PuTTY's configuration. This key +exchange method uses the SHA-256 hash or, if the server doesn't +support that, SHA-1. + +\b \q{\i{RSA-based key exchange}}: this requires much less computational effort on the part of the client, and somewhat less on the part of the server, than Diffie-Hellman key exchange. @@ -2303,6 +2413,10 @@ when using Kerberos V5, and not other GSSAPI mechanisms. If the user running PuTTY has current Kerberos V5 credentials, then PuTTY will select the GSSAPI key exchange methods in preference to any of the ordinary SSH key exchange methods configured in the preference list. +There's a GSSAPI-based equivalent to most of the ordinary methods +listed in \k{config-ssh-kex-order}; server support determines which +one will be used. (PuTTY's preference order for GSSAPI-authenticated +key exchange methods is fixed, not controlled by the preference list.) The advantage of doing GSSAPI authentication as part of the SSH key exchange is apparent when you are using credential delegation (see @@ -2317,7 +2431,8 @@ support GSSAPI in the SSH user authentication phase. This will still let you log in using your Kerberos credentials, but will only allow you to delegate the credentials that are active at the beginning of the session; they can't be refreshed automatically later, in a -long-running session. +long-running session. See \k{config-ssh-auth-gssapi} for how to +control GSSAPI user authentication in PuTTY. Another effect of GSSAPI key exchange is that it replaces the usual SSH mechanism of permanent host keys described in \k{gs-hostkey}. @@ -2403,7 +2518,7 @@ protection than SSH-2 without rekeys. \H{config-ssh-hostkey} The Host Keys panel -The Host Keys panel allows you to configure options related to SSH-2 +The Host Keys panel allows you to configure options related to \i{host key management}. Host keys are used to prove the server's identity, and assure you that @@ -2411,8 +2526,8 @@ the server is not being spoofed (either by a man-in-the-middle attack or by completely replacing it on the network). See \k{gs-hostkey} for a basic introduction to host keys. -This entire panel is only relevant to SSH protocol version 2; none of -these settings affect SSH-1 at all. +Much of this panel is only relevant to SSH protocol version 2; SSH-1 +only supports one type of host key. \S{config-ssh-hostkey-order} \ii{Host key type} selection @@ -2431,7 +2546,7 @@ larger elliptic curve with a 448-bit instead of 255-bit modulus (so it has a higher security level than Ed25519). \b \q{ECDSA}: \i{elliptic curve} \i{DSA} using one of the -NIST-standardised elliptic curves. +\i{NIST}-standardised elliptic curves. \b \q{DSA}: straightforward \i{DSA} using modular exponentiation. @@ -2452,7 +2567,7 @@ to that for cipher selection (see \k{config-ssh-encryption}). \S{config-ssh-prefer-known-hostkeys} Preferring known host keys -By default, PuTTY will adjust the preference order for host key +By default, PuTTY will adjust the preference order for SSH-2 host key algorithms so that any host keys it already knows are moved to the top of the list. @@ -2527,6 +2642,146 @@ neither read \e{nor written}, unless you explicitly do so. If the box is empty (as it usually is), then PuTTY's automated host key management will work as normal. +\S{config-ssh-kex-cert} Configuring PuTTY to accept host \i{certificates} + +In some environments, the SSH host keys for a lot of servers will all +be signed in turn by a central \q{certification authority} (\q{CA} for +short). This simplifies host key configuration for users, because if +they configure their SSH client to accept host keys certified by that +CA, then they don't need to individually confirm each host key the +first time they connect to that server. + +In order to do this, press the \q{Configure host CAs} button in the +\q{Host keys} configuration panel. This will launch a secondary +configuration dialog box where you can configure what CAs PuTTY will +accept signatures from. + +\s{Note that this configuration is common to all saved sessions}. +Everything in the main PuTTY configuration is specific to one saved +session, and you can prepare a separate session with all the +configuration different. But there's only one copy of the host CA +configuration, and it applies to all sessions PuTTY runs, whether +saved or not. + +(Otherwise, it would be useless \dash configuring a CA by hand for +each new host wouldn't be any more convenient than pressing the +\q{confirm} button for each new host's host key.) + +To set up a new CA using this config box: + +First, load the CA's public key from a file, or paste it directly into +the \q{Public key of certification authority} edit box. If your +organisation signs its host keys in this way, they will publish the +public key of their CA so that SSH users can include it in their +configuration. + +Next, in the \q{Valid hosts this key is trusted to certify} box, +configure at least one hostname wildcard to say what servers PuTTY +should trust this CA to speak for. For example, suppose you work for +Example Corporation (\cw{example.com}), and the Example Corporation IT +department has advertised a CA that signs all the Example internal +machines' host keys. Then probably you want to trust that CA to sign +host keys for machines in the domain \cw{example.com}, but not for +anything else. So you might enter \cq{*.example.com} into the \q{Valid +hosts} box. + +\s{It's important to limit what the CA key is allowed to sign}. Don't +just enter \cq{*} in that box! If you do that, you're saying that +Example Corporation IT department is authorised to sign a host key for +\e{anything at all} you might decide to connect to \dash even if +you're connecting out of the company network to a machine somewhere +else, such as your own personal server. So that configuration would +enable the Example IT department to act as a \q{man-in-the-middle} +between your PuTTY process and your server, and listen in to your +communications \dash exactly the thing SSH is supposed to avoid. + +So, if the CA was provided to you by the sysadmins responsible for +\cw{example.com} (or whatever), make sure PuTTY will \e{only} trust it +for machines in the \cw{example.com} domain. + +For the full syntax of the \q{Valid hosts} expression, see +\k{config-ssh-cert-valid-expr}. + +Finally, choose an identifying name for this CA; enter that name in +the \q{Name for this CA} edit box at the top of the window, and press +\q{Save} to record the CA in your configuration. The name you chose +will appear in the list of saved CAs to the left of the \q{Save} +button. + +The identifying name can be anything you like. It's there so that if +you store multiple certificates you can tell which is which later when +you want to edit or delete them. It also appears in the PuTTY Event +Log when a server presents a certificate signed by that CA. + +To reload an existing CA configuration, select it in the list box and +press \q{Load}. Then you can make changes, and save it again. + +To remove a CA from your configuration completely, select it in the +list and press \q{Delete}. + +\S2{config-ssh-cert-valid-expr} Expressions you can enter in \q{Valid +hosts} + +The simplest thing you can enter in the \q{Valid hosts this key is +trusted to certify} edit box is just a hostname wildcard such as +\cq{*.example.com}. This matches any host in any subdomain, so +both \cq{ssh.example.com} and \cq{login.dept.example.com} would +match, but \cq{prod.example.net} would not. + +But you can also enter multiple host name wildcards, and port number +ranges, and make complicated Boolean expressions out of them using the +operators \cq{&&} for \q{and}, \cq{||} for \q{or}, \cq{!} for \q{not}, +and parentheses. + +For example, here are some other things you could enter. + +\b \cq{*.foo.example.com || *.bar.example.com}. This means the CA is +trusted to sign the host key for a connection if the host name matches +\q{*.foo.example.com} \e{or} it matches \q{*.bar.example.com}. In +other words, the CA has authority over those two particular subdomains +of \cw{example.com}, but not for anything else, like +\cw{www.example.com}. + +\b \cq{*.example.com && ! *.extrasecure.example.com}. This means the +CA is trusted to sign the host key for a connection if the host name +matches \q{*.example.com} \e{but does not} match +\q{*.extrasecure.example.com}. (Imagine if there was one top-secret +set of servers in your company that the main IT department didn't have +security clearance to administer.) + +\b \cq{*.example.com && port:22}. This means the CA is trusted to sign +the host key for a connection if the host name matches +\q{*.example.com} \e{and} the port number is 22. SSH servers running +on other ports would not be covered. + +\b \cq{(*.foo.example.com || *.bar.example.com) && port:0-1023}. This +matches two subdomains of \cw{example.com}, as before, but \e{also} +restricts the port number to the range 0-1023. + +A certificate configuration expression consists of one or more +individual requirements which can each be a hostname wildcard, a +single port number, or a port number range, combined together with +these Boolean operators. + +Unlike other languages such as C, there is no implied priority between +\cq{&&} and \cq{||}. If you write \cq{A && B || C} (where \cw{A}, +\cw{B} and \cw{C} are some particular requirements), then PuTTY will +report a syntax error, because you haven't said which of the \cq{&&} +and \cq{||} takes priority tightly. You will have to write either +\cq{(A && B) || C}, meaning \q{both of \cw{A} and \cw{B}, or +alternatively just \cw{C}}, or \cq{A && (B || C)} (\q{\cw{A}, and also +at least one of \cw{B} and \cw{C}}), to make it clear. + +\S2{config-ssh-cert-rsa-hash} RSA signature types in certificates + +RSA keys can be used to generate signatures with a choice of secure +hash function. Typically, any version of OpenSSH new enough to support +certificates at all will also be new enough to avoid using SHA-1, so +the default settings of accepting the more modern SHA-256 and SHA-512 +should be suitable for nearly all cases. For completeness, however, +you can configure which types of RSA signature PuTTY will accept in a +certificate from a CA using an RSA key. + \H{config-ssh-encryption} The Cipher panel PuTTY supports a variety of different \i{encryption algorithm}s, and @@ -2541,7 +2796,8 @@ PuTTY currently supports the following algorithms: \b \i{ChaCha20-Poly1305}, a combined cipher and \i{MAC} (SSH-2 only) -\b \i{AES} (Rijndael) - 256, 192, or 128-bit SDCTR or CBC (SSH-2 only) +\b \i{AES} (Rijndael) - 256, 192, or 128-bit SDCTR or CBC, or +256 or 128-bit GCM (SSH-2 only) \b \i{Arcfour} (RC4) - 256 or 128-bit stream cipher (SSH-2 only) @@ -2745,6 +3001,12 @@ username more than once, in case the server complains. If you know your server can cope with it, you can enable the \q{Allow attempted changes of username} option to modify PuTTY's behaviour. +\H{config-ssh-auth-creds} The Credentials panel + +This subpane of the Auth panel contains configuration options that +specify actual \e{credentials} to present to the server: key files and +certificates. + \S{config-ssh-privkey} \q{\ii{Private key} file for authentication} This box is where you enter the name of your private key file if you @@ -2766,6 +3028,54 @@ in this case (in RFC 4716 or OpenSSH format), as that's sufficient to identify the key to Pageant, but of course if Pageant isn't present PuTTY can't fall back to using this file itself. +\S{config-ssh-cert} \q{\ii{Certificate} to use with the private key} + +In some environments, user authentication keys can be signed in turn +by a \q{certifying authority} (\q{CA} for short), and user accounts on +an SSH server can be configured to automatically trust any key that's +certified by the right signature. + +This can be a convenient setup if you have a very large number of +servers. When you change your key pair, you might otherwise have to +edit the \cw{authorized_keys} file on every server individually, to +make them all accept the new key. But if instead you configure all +those servers \e{once} to accept keys signed as yours by a CA, then +when you change your public key, all you have to do is to get the new +key certified by the same CA as before, and then all your servers will +automatically accept it without needing individual reconfiguration. + +One way to use a certificate is to incorporate it into your private +key file. \K{puttygen-cert} explains how to do that using PuTTYgen. +But another approach is to tell PuTTY itself where to find the public +certificate file, and then it will automatically present that +certificate when authenticating with the corresponding private key. + +To do this, enter the pathname of the certificate file into the +\q{Certificate to use with the private key} file selector. + +When this setting is configured, PuTTY will honour it no matter +whether the private key is found in a file, or loaded into Pageant. + +\S{config-ssh-authplugin} \q{\ii{Plugin} to provide authentication responses} + +An SSH server can use the \q{keyboard-interactive} protocol to present +a series of arbitrary questions and answers. Sometimes this is used +for ordinary passwords, but sometimes the server will use the same +mechanism for something more complicated, such as a one-time password +system. + +Some of these systems can be automated. For this purpose, PuTTY allows +you to provide a separate program to act as a \q{plugin} which will +take over the authentication and send answers to the questions on your +behalf. + +If you have been provided with a plugin of this type, you can +configure it here, by entering a full command line in the \q{Plugin +command to run} box. + +(If you want to \e{write} a plugin of this type, see \k{authplugin} +for the full specification of how the plugin is expected to behave.) + \H{config-ssh-auth-gssapi} The \i{GSSAPI} panel The \q{GSSAPI} subpanel of the \q{Auth} panel controls the use of @@ -3206,7 +3516,10 @@ three states: \b \q{On}: PuTTY will assume the server \e{does} have the bug. \b \q{Auto}: PuTTY will use the server's version number announcement -to try to guess whether or not the server has the bug. +to try to guess whether or not the server has the bug. (This option is +not available for bugs that \e{cannot} be detected from the server +version, e.g. because they must be acted on before the server version +is known.) \S{config-ssh-bug-ignore2} \q{Chokes on SSH-2 \i{ignore message}s} @@ -3299,6 +3612,55 @@ send an over-sized packet. If this bug is enabled when talking to a correct server, the session will work correctly, but download performance will be less than it could be. +\S{config-ssh-bug-dropstart} \q{Discards data sent before its greeting} + +Just occasionally, an SSH connection can be established over some +channel that will accidentally discard outgoing data very early in the +connection. + +This is not typically seen as a bug in an actual SSH server, but it +can sometimes occur in situations involving a complicated proxy +process. An example is +\W{https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=991958}{Debian +bug #991958}, in which a connection going over the console of a User +Mode Linux kernel can lose outgoing data before the kernel has fully +booted. + +You can work around this problem by manually enabling this bug flag, +which will cause PuTTY to wait to send its initial SSH greeting until +after it sees the greeting from the server. + +Note that this bug flag can never be automatically detected, since +auto-detection relies on the version string in the server's greeting, +and PuTTY has to decide whether to expect this bug \e{before} it sees +the server's greeting. So this is a manual workaround only. + +\S{config-ssh-bug-filter-kexinit} \q{Chokes on PuTTY's full \cw{KEXINIT}} + +At the start of an SSH connection, the client and server exchange long +messages of type \cw{SSH_MSG_KEXINIT}, containing lists of all the +cryptographic algorithms they're prepared to use. This is used to +negotiate a set of algorithms that both ends can speak. + +Occasionally, a badly written server might have a length limit on the +list it's prepared to receive, and refuse to make a connection simply +because PuTTY is giving it too many choices. + +A workaround is to enable this flag, which will make PuTTY wait to +send \cw{KEXINIT} until after it receives the one from the server, and +then filter its own \cw{KEXINIT} to leave out any algorithm the server +doesn't also announce support for. This will generally make PuTTY's +\cw{KEXINIT} at most the size of the server's, and will otherwise make +no difference to the algorithm negotiation. + +This flag is a minor violation of the SSH protocol, because both sides +are supposed to send \cw{KEXINIT} proactively. It still works provided +\e{one} side sends its \cw{KEXINIT} without waiting, but if both +client and server waited for the other one to speak first, the +connection would deadlock. We don't know of any servers that do this, +but if there is one, then this flag will make PuTTY unable to speak to +them at all. + \S{config-ssh-bug-sig} \q{Requires padding on SSH-2 \i{RSA} \i{signatures}} Versions below 3.3 of \i{OpenSSH} require SSH-2 RSA signatures to be diff --git a/DOC/ERRORS.BUT b/DOC/ERRORS.BUT index 36a42d94..a35a7256 100644 --- a/DOC/ERRORS.BUT +++ b/DOC/ERRORS.BUT @@ -10,8 +10,8 @@ self-explanatory. If you get an error message which is not listed in this chapter and which you don't understand, report it to us as a bug (see \k{feedback}) and we will add documentation for it. -\H{errors-hostkey-absent} \q{The server's host key is not cached in -the registry} +\H{errors-hostkey-absent} \q{The host key is not cached for this +server} This error message occurs when PuTTY connects to a new SSH server. Every server identifies itself by means of a host key; once PuTTY @@ -35,10 +35,13 @@ See \k{gs-hostkey} for more information on host keys. \H{errors-hostkey-wrong} \q{WARNING - POTENTIAL SECURITY BREACH!} This message, followed by \q{The server's host key does not match -the one PuTTY has cached in the registry}, means that PuTTY has +the one PuTTY has cached for this server}, means that PuTTY has connected to the SSH server before, knows what its host key \e{should} be, but has found a different one. +(If the message instead talks about a \q{certified host key}, see +instead \k{errors-cert-mismatch}.) + This may mean that a malicious attacker has replaced your server with a different one, or has redirected your network connection to their own machine. On the other hand, it may simply mean that the @@ -52,6 +55,41 @@ in the same way as you would if it was new. See \k{gs-hostkey} for more information on host keys. +\H{errors-cert-mismatch} \q{This server presented a certified host key +which was signed by a different certification authority ...} + +If you've configured PuTTY to trust at least one +\I{certificate}certification authority for signing host keys (see +\k{config-ssh-kex-cert}), then it will ask the SSH server to send it +any available certified host keys. If the server sends back a +certified key signed by a \e{different} certification authority, PuTTY +will present this variant of the host key prompt, preceded by +\q{WARNING - POTENTIAL SECURITY BREACH!} + +One reason why this can happen is a deliberate attack. Just like an +ordinary man-in-the-middle attack which substitutes a wrong host key, +a particularly ambitious attacker might substitute an entire wrong +certification authority, and hope that you connect anyway. + +But it's also possible in some situations that this error might arise +legitimately. For example, if your organisation's IT department has +just rolled out a new CA key which you haven't yet entered in PuTTY's +configuration, or if your CA configuration involves two overlapping +domains, or something similar. + +So, unfortunately, you'll have to work out what to do about it +yourself: make an exception for this specific case, or abandon this +connection and install a new CA key before trying again (if you're +really sure you trust the CA), or edit your configuration in some +other way, or just stop trying to use this server. + +If you're convinced that this particular server is legitimate even +though the CA is not one you trust, PuTTY will let you cache the +certified host key, treating it in the same way as an uncertified one. +Then that particular certificate will be accepted for future +connections to this specific server, even though other certificates +signed by the same CA will still be rejected. + \H{errors-ssh-protocol} \q{SSH protocol version 2 required by our configuration but remote only provides (old, insecure) SSH-1} diff --git a/DOC/FAQ.BUT b/DOC/FAQ.BUT index 474b984a..9a8deea2 100644 --- a/DOC/FAQ.BUT +++ b/DOC/FAQ.BUT @@ -150,7 +150,7 @@ data at the server end; it's your guarantee that it hasn't been removed and replaced somewhere on the way. Host key checking makes the attacker's job \e{astronomically} hard, compared to packet sniffing, and even compared to subverting a router. Instead of -applying a little intelligence and keeping an eye on Bugtraq, the +applying a little intelligence and keeping an eye on oss-security, the attacker must now perform a brute-force attack against at least one military-strength cipher. That insignificant host key prompt really does make \e{that} much difference. @@ -220,7 +220,7 @@ Currently, release versions of PuTTY tools only run on Windows systems and Unix. As of 0.68, the supplied PuTTY executables run on versions of Windows -from XP onwards, up to and including Windows 10; and we know of no +from XP onwards, up to and including Windows 11; and we know of no reason why PuTTY should not continue to work on future versions of Windows. We provide 32-bit and 64-bit Windows executables for the common x86 processor family; see \k{faq-32bit-64bit} for discussion @@ -250,8 +250,7 @@ There are Unix ports of most of the traditional PuTTY tools, and also one entirely new application. If you look at the source release, you should find a \c{unix} -subdirectory. There are a couple of ways of building it, -including the usual \c{configure}/\c{make}; see the file \c{README} +subdirectory. You need \c{cmake} to build it; see the file \c{README} in the source distribution. This should build you: \b Unix ports of PuTTY, Plink, PSCP, and PSFTP, which work pretty much @@ -325,7 +324,8 @@ unfinished. If any OS X and/or GTK programming experts are keen to have a finished version of this, we urge them to help out with some of the remaining -problems! See the TODO list in \c{unix/gtkapp.c} in the source code. +problems! See the TODO list in \c{unix/main-gtk-application.c} in the +source code. \S{faq-epoc}{Question} Will there be a port to EPOC? @@ -584,7 +584,7 @@ You can also paste by pressing Shift-Ins. keys, proxying, cipher selection, etc.) in PSCP, PSFTP and Plink? Most major features (e.g., public keys, port forwarding) are available -through command line options. See the documentation. +through command line options. See \k{using-general-opts}. Not all features are accessible from the command line yet, although we'd like to fix this. In the meantime, you can use most of @@ -606,9 +606,16 @@ To use PSCP properly, run it from a Command Prompt window. See \S{faq-pscp-spaces}{Question} \I{spaces in filenames}How do I use PSCP to copy a file whose name has spaces in? -If PSCP is using the traditional SCP protocol, this is confusing. If -you're specifying a file at the local end, you just use one set of -quotes as you would normally do: +If PSCP is using the newer SFTP protocol (which is usual with most +modern servers), this is straightforward; all filenames with spaces +in are specified using a single pair of quotes in the obvious way: + +\c pscp "local file" user@host: +\c pscp user@host:"remote file" . + +However, if PSCP is using the older SCP protocol for some reason, +things are more confusing. If you're specifying a file at the local +end, you just use one set of quotes as you would normally do: \c pscp "local filename with spaces" user@host: \c pscp user@host:myfile "local filename with spaces" @@ -632,13 +639,6 @@ Instead, you need to specify the local file name in full: \c c:\>pscp user@host:"\"oo er\"" "oo er" -If PSCP is using the newer SFTP protocol, none of this is a problem, -and all filenames with spaces in are specified using a single pair -of quotes in the obvious way: - -\c pscp "local file" user@host: -\c pscp user@host:"remote file" . - \S{faq-32bit-64bit}{Question} Should I run the 32-bit or the 64-bit version? @@ -1152,6 +1152,22 @@ running, but it doesn't stop the process's memory as a whole from being swapped completely out to disk when the process is long-term inactive. And Pageant spends most of its time inactive. +\S{faq-windowsstore}{Question} Is the version of PuTTY in the +\i{Microsoft Store} legit? + +The free-of-charge \q{PuTTY} application at +\W{https://apps.microsoft.com/store/detail/putty/XPFNZKSKLBP7RJ}{this link} +is published and maintained by us. The copy there is the latest +release, usually updated within a few days of us publishing it on our +own website. + +There have been other copies of PuTTY on the store, some looking quite +similar, and some charging money. Those were uploaded by other people, +and we can't guarantee anything about them. + +The first version we published to the Microsoft Store was 0.76 (some +time after its initial release on our website). + \H{faq-admin} Administrative questions \S{faq-putty-org}{Question} Is \cw{putty.org} your website? @@ -1286,7 +1302,7 @@ Small donations (tens of dollars or tens of euros) will probably be spent on beer or curry, which helps motivate our volunteer team to continue doing this for the world. Larger donations will be spent on something that actually helps development, if we can find anything -(perhaps new hardware, or a copy of Windows XP), but if we can't +(perhaps new hardware, or a new version of Windows), but if we can't find anything then we'll just distribute the money among the developers. If you want to be sure your donation is going towards something worthwhile, ask us first. If you don't like these terms, @@ -50,8 +50,9 @@ section. If you are using SSH to connect to a server for the first time, you will probably see a message looking something like this: -\c The server's host key is not cached in the registry. You have no -\c guarantee that the server is the computer you think it is. +\c The host key is not cached for this server: +\c ssh.example.com (port 22) +\c You have no guarantee that the server is the computer you think it is. \c The server's ssh-ed25519 key fingerprint is: \c ssh-ed25519 255 SHA256:TddlQk20DVs4LRcAsIfDN9pInKpY06D+h4kSHwWAj4w \c If you trust this host, press "Accept" to add the key to PuTTY's @@ -79,10 +80,10 @@ PuTTY \I{host key cache}records the host key for each server you connect to, in the Windows \i{Registry}. Every time you connect to a server, it checks that the host key presented by the server is the same host key as it was the last time you connected. If it is not, -you will see a warning, and you will have the chance to abandon your -connection before you type any private information (such as a -password) into it. (See \k{errors-hostkey-wrong} for what that looks -like.) +you will see a stronger warning, and you will have the chance to +abandon your connection before you type any private information (such +as a password) into it. (See \k{errors-hostkey-wrong} for what that +looks like.) However, when you connect to a server you have not connected to before, PuTTY has no way of telling whether the host key is the diff --git a/DOC/INDEX.BUT b/DOC/INDEX.BUT index f7e7145a..187f5a1e 100644 --- a/DOC/INDEX.BUT +++ b/DOC/INDEX.BUT @@ -245,6 +245,7 @@ saved sessions from \IM{-m} \c{-m} command-line option \IM{-P-upper} \c{-P} command-line option \IM{-pw} \c{-pw} command-line option +\IM{-pwfile} \c{-pwfile} command-line option \IM{-A-upper} \c{-A} command-line option \IM{-a} \c{-a} command-line option \IM{-X-upper} \c{-X} command-line option @@ -607,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 @@ -684,6 +688,16 @@ saved sessions from \IM{group exchange} Diffie-Hellman group exchange \IM{group exchange} group exchange, Diffie-Hellman +\IM{ECDH} \q{ECDH} (elliptic-curve Diffie-Hellman) +\IM{ECDH} elliptic-curve Diffie-Hellman key exchange +\IM{ECDH} key exchange, elliptic-curve Diffie-Hellman +\IM{ECDH} Diffie-Hellman key exchange, with elliptic curves + +\IM{Streamlined NTRU Prime} Streamlined NTRU Prime +\IM{Streamlined NTRU Prime} NTRU Prime + +\IM{quantum attacks} quantum attacks, resistance to + \IM{repeat key exchange} repeat key exchange \IM{repeat key exchange} key exchange, repeat @@ -815,6 +829,12 @@ saved sessions from \IM{DSA} DSA \IM{DSA} Digital Signature Standard +\IM{ECDSA} ECDSA +\IM{ECDSA} elliptic-curve DSA + +\IM{NIST} NIST-standardised elliptic curves +\IM{NIST} elliptic curves, NIST-standardised + \IM{EdDSA} EdDSA \IM{EdDSA} Edwards-curve DSA @@ -863,6 +883,11 @@ saved sessions from \IM{authentication agent} agent, authentication \IM{-c-pageant} \c{-c} Pageant command-line option +\IM{--keylist} \c{--keylist} Pageant command-line option +\IM{--openssh-config} \c{--openssh-config} Pageant command-line option + +\IM{Windows OpenSSH} Windows OpenSSH +\IM{Windows OpenSSH} OpenSSH, on Windows \IM{FAQ} FAQ \IM{FAQ} Frequently Asked Questions @@ -930,3 +955,14 @@ saved sessions from \IM{system tray} system tray, Windows \IM{system tray} notification area, Windows (aka system tray) \IM{system tray} taskbar notification area, Windows (aka system tray) + +\IM{shifted arrow keys} arrow keys, shifted +\IM{shifted arrow keys} shifted arrow keys + +\IM{certificate}{certificates} certificates, SSH +\IM{certificate}{certificates} SSH certificates +\IM{certificate}{certificates} OpenSSH certificates +\IM{certificate}{certificates} CA (certification authority) + +\IM{Microsoft Store} Microsoft Store +\IM{Microsoft Store} Windows Store diff --git a/DOC/MAKEFILE b/DOC/MAKEFILE deleted file mode 100644 index 5ff25d54..00000000 --- a/DOC/MAKEFILE +++ /dev/null @@ -1,80 +0,0 @@ -all: man index.html - -# Decide on the versionid policy. -# -# If the user has passed in $(VERSION) on the command line (`make -# VERSION="Release 0.56"'), we use that as an explicit version string. -# Otherwise, we use `svnversion' to examine the checked-out -# documentation source, and if that returns a single revision number -# then we invent a version string reflecting just that number. Failing -# _that_, we resort to versionids.but which gives 'version -# unavailable'. -# -# So here, we define VERSION using svnversion if it isn't already -# defined ... -ifndef VERSION -SVNVERSION=$(shell test -d .svn && svnversion .) -BADCHARS=$(findstring :,$(SVNVERSION))$(findstring S,$(SVNVERSION)) -ifeq ($(BADCHARS),) -ifneq ($(SVNVERSION),) -ifneq ($(SVNVERSION),exported) -VERSION=Built from revision $(patsubst M,,$(SVNVERSION)) -endif -endif -endif -endif -# ... and now, we condition our build behaviour on whether or not -# VERSION _is_ defined. -ifdef VERSION -VERSIONIDS=vstr -vstr.but: FORCE - printf '\\versionid $(VERSION)\n' > vstr.but -FORCE:; -else -VERSIONIDS=vids -endif - -CHAPTERS := $(SITE) copy blurb intro gs using config pscp psftp plink -CHAPTERS += pubkey pageant errors faq feedback pubkeyfmt licence udp -CHAPTERS += pgpkeys sshnames -CHAPTERS += index $(VERSIONIDS) - -INPUTS = $(patsubst %,%.but,$(CHAPTERS)) - -# This is temporary. Hack it locally or something. -HALIBUT = halibut - -index.html: $(INPUTS) - $(HALIBUT) --text --html --chm $(INPUTS) - -# During formal builds it's useful to be able to build this one alone. -putty.chm: $(INPUTS) - $(HALIBUT) --chm $(INPUTS) - -# We don't ship this any more. -putty.hlp: $(INPUTS) - $(HALIBUT) --winhelp $(INPUTS) - -putty.info: $(INPUTS) - $(HALIBUT) --info $(INPUTS) - -MKMAN = $(HALIBUT) --man=$@ mancfg.but $< -MANPAGES = putty.1 puttygen.1 plink.1 pscp.1 psftp.1 puttytel.1 pterm.1 \ - pageant.1 psocks.1 psusan.1 -man: $(MANPAGES) - -putty.1: man-putty.but mancfg.but; $(MKMAN) -puttygen.1: man-puttygen.but mancfg.but; $(MKMAN) -plink.1: man-plink.but mancfg.but; $(MKMAN) -pscp.1: man-pscp.but mancfg.but; $(MKMAN) -psftp.1: man-psftp.but mancfg.but; $(MKMAN) -puttytel.1: man-puttytel.but mancfg.but; $(MKMAN) -pterm.1: man-pterm.but mancfg.but; $(MKMAN) -pageant.1: man-pageant.but mancfg.but; $(MKMAN) -psocks.1: man-psocks.but mancfg.but; $(MKMAN) -psusan.1: man-psusan.but mancfg.but; $(MKMAN) - -mostlyclean: - rm -f *.html *.txt *.hlp *.cnt *.1 *.info vstr.but *.hh[pck] -clean: mostlyclean - rm -f *.chm diff --git a/DOC/MAN-PSCP.BUT b/DOC/MAN-PSCP.BUT index 60ce4f5e..544d3a40 100644 --- a/DOC/MAN-PSCP.BUT +++ b/DOC/MAN-PSCP.BUT @@ -101,11 +101,16 @@ channel from the server, to prevent remote processes sending confusing escape sequences. This option forces the standard error channel to not be filtered. +\dt \cw{-pwfile} \e{filename} + +\dd Open the specified file, and use the first line of text read from +it as the remote password. + \dt \cw{-pw} \e{password} \dd Set remote password to \e{password}. \e{CAUTION:} this will likely make the password visible to other users of the local machine (via -commands such as \q{\c{w}}). +commands such as \q{\c{ps}} or \q{\c{w}}). Use \cw{-pwfile} instead. \dt \cw{-1} @@ -118,9 +123,9 @@ commands such as \q{\c{w}}). \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}. +only likely to be useful when connecting to a \cw{psusan}(\e{1}) +server, most likely with an absolute path to a Unix-domain socket in +place of \e{host}. \dt \cw{-ssh} diff --git a/DOC/PAGEANT.BUT b/DOC/PAGEANT.BUT index 8abb5cdf..de6d4cb8 100644 --- a/DOC/PAGEANT.BUT +++ b/DOC/PAGEANT.BUT @@ -64,21 +64,24 @@ The large list box in the Pageant main window lists the private keys that are currently loaded into Pageant. The list might look something like this: -\c ssh-ed25519 SHA256:TddlQk20DVs4LRcAsIfDN9pInKpY06D+h4kSHwWAj4w -\c ssh-rsa 2048 SHA256:8DFtyHm3kQihgy52nzX96qMcEVOq7/yJmmwQQhBWYFg +\c Ed25519 SHA256:TddlQk20DVs4LRcAsIfDN9pInKpY06D+h4kSHwWAj4w +\c RSA 2048 SHA256:8DFtyHm3kQihgy52nzX96qMcEVOq7/yJmmwQQhBWYFg For each key, the list box will tell you: \b The type of the key. Currently, this can be -\c{ssh-rsa} (an RSA key for use with the SSH-2 protocol), -\c{ssh-dss} (a DSA key for use with the SSH-2 protocol), -\c{ecdsa-sha2-*} (an ECDSA key for use with the SSH-2 protocol), -\c{ssh-ed25519} (an Ed25519 key for use with the SSH-2 protocol), -\c{ssh-ed448} (an Ed448 key for use with the SSH-2 protocol), -or \c{ssh1} (an RSA key for use with the old SSH-1 protocol). +\q{RSA} (an RSA key for use with the SSH-2 protocol), +\q{DSA} (a DSA key for use with the SSH-2 protocol), +\q{\i{NIST}} (an ECDSA key for use with the SSH-2 protocol), +\q{Ed25519} (an Ed25519 key for use with the SSH-2 protocol), +\q{Ed448} (an Ed448 key for use with the SSH-2 protocol), +or \q{SSH-1} (an RSA key for use with the old SSH-1 protocol). +(If the key has an associated certificate, this is shown here with a +\q{cert} suffix.) \b The size (in bits) of the key, for key types that come in different -sizes. +sizes. (For ECDSA \q{NIST} keys, this is indicated as \q{p256} or +\q{p384} or \q{p521}.) \b The \I{key fingerprint}fingerprint for the public key. This should be the same fingerprint given by PuTTYgen, and (hopefully) also the same @@ -86,10 +89,20 @@ fingerprint shown by remote utilities such as \i\c{ssh-keygen} when applied to your \c{authorized_keys} file. \lcont{ -By default this is shown in the \q{SHA256} format. You can change to the -older \q{MD5} format (which looks like \c{aa:bb:cc:...}) with the -\q{Fingerprint type} drop-down, but bear in mind that this format is -less secure and should be avoided for comparison purposes where possible. +For SSH-2 keys, by default this is shown in the \q{SHA256} format. You +can change to the older \q{MD5} format (which looks like \c{aa:bb:cc:...}) +with the \q{Fingerprint type} drop-down, but bear in mind that this +format is less secure and should be avoided for comparison purposes +where possible. + +If some of the keys loaded into Pageant have certificates attached, +then Pageant will default to showing the fingerprint of the underlying +key. This way, a certified and uncertified version of the same key +will have the same fingerprint, so you can see that they match. You +can instead use the \q{Fingerprint type} drop-down to ask for a +different fingerprint to be shown for certified keys, which includes +the certificate as part of the fingerprinted data. That way you can +tell two certificates apart. } \b The comment attached to the key. @@ -170,6 +183,92 @@ by the command, like this: \c C:\PuTTY\pageant.exe d:\main.ppk -c C:\PuTTY\putty.exe +\S{pageant-cmdline-openssh} Integrating with \i{Windows OpenSSH} + +Windows's own port of OpenSSH uses the same mechanism as Pageant to +talk to its SSH agent (Windows named pipes). This means that Windows +OpenSSH can talk directly to Pageant, if it knows where to find +Pageant's named pipe. + +When Pageant starts up, it can optionally write out a file containing +an OpenSSH configuration directive that tells the Windows \c{ssh.exe} +where to find Pageant. If you include this file from your Windows SSH +configuration, then \c{ssh.exe} should automatically use Pageant as +its agent, so that you can keep your keys in one place and have both +SSH clients able to use them. + +The option is \i\c{--openssh-config}, and you follow it with a filename. + +To refer to this file from your main OpenSSH configuration, you can +use the \cq{Include} directive. For example, you might run Pageant +like this (with your own username substituted, of course): + +\c pageant --openssh-config C:\Users\Simon\.ssh\pageant.conf + +and then add a directive like this to your main \cq{.ssh\\config} file +(assuming that lives in the same directory that you just put +\cw{pageant.conf}): + +\c Include pageant.conf + +\s{Note}: this technique only works with \e{Windows's} port of +OpenSSH, which lives at \cw{C:\\Windows\\System32\\OpenSSH\\ssh.exe} +if you have it installed. (If not, it can be installed as a Windows +optional feature, e.g., via Settings > Apps & features > Optional +features > Add a feature > OpenSSH Client.) + +There are other versions of OpenSSH for Windows, notably the one that +comes with Windows \cw{git}. Those will likely not work with the same +configuration, because they tend to depend on Unix emulation layers +like MinGW or MSys, so they won't speak Windows native pathname syntax +or understand named pipes. The above instructions will only work with +Windows's own version of OpenSSH. + +So, if you want to use Windows \cw{git} with an SSH key held in +Pageant, you'll have to set the environment variable \cw{GIT_SSH}, to +point at a different program. You could point it at +\cw{c:\\Windows\\System32\\OpenSSH\\ssh.exe} once you've done this +setup \dash but it's just as easy to point it at Plink! + +\S{pageant-cmdline-unix} Unix-domain sockets: integrating with WSL 1 + +Pageant can listen on the WinSock implementation of \q{Unix-domain +sockets}. These interoperate with the Unix-domain sockets found in the +original Windows Subsystem for Linux (now known as WSL 1). So if you +ask Pageant to listen on one of these, then your WSL 1 processes can +talk directly to Pageant. + +To configure this, run Pageant with the option \c{--unix}, followed +with a pathname. Then, in WSL 1, set the environment variable +\cw{SSH_AUTH_SOCK} to point at the WSL translation of that pathname. + +For example, you might run + +\c pageant --unix C:\Users\Simon\.ssh\agent.sock + +and in WSL 1, set the environment variable + +\c SSH_AUTH_SOCK=/mnt/c/Users/Simon/.ssh/agent.sock + +Alternatively, you can add a line to your \cw{.ssh/config} file inside +WSL that says + +\c IdentityAgent /mnt/c/Users/Simon/.ssh/agent.sock + +although doing it like that may mean that \cw{ssh-add} commands won't +find the agent, even though \cw{ssh} itself will. + +\s{Security note}: Unix-domain sockets are protected against access by +other users by the file protections on their containing directory. So +if your Windows machine is multiuser, make sure you create the socket +inside a directory that other users can't access at all. (In fact, +that's a good idea on general principles.) + +\s{Compatibility note}: WSL 2 processes cannot talk to Pageant by this +mechanism, because WSL 2's Unix-domain sockets are managed by a +separate Linux kernel, and not by the same kernel that WinSock talks +to. + \S{pageant-cmdline-keylist} Starting with the key list visible Start Pageant with the \i\c{--keylist} option to show the main window diff --git a/DOC/PGPKEYS.BUT b/DOC/PGPKEYS.BUT index 8fab6153..7dc62f89 100644 --- a/DOC/PGPKEYS.BUT +++ b/DOC/PGPKEYS.BUT @@ -56,25 +56,25 @@ The current issue of those keys are available for download from the PuTTY website, and are also available on PGP keyservers using the key IDs listed below. -\dt \W{https://www.chiark.greenend.org.uk/~sgtatham/putty/keys/master-2018.asc}{\s{Master Key} (2018)} +\dt \W{https://www.chiark.greenend.org.uk/~sgtatham/putty/keys/master-2021.asc}{\s{Master Key} (2021)} -\dd RSA, 4096-bit. Key ID: \cw{76BC7FE4EBFD2D9E}. Fingerprint: -\cw{24E1\_B1C5\_75EA\_3C9F\_F752\_\_A922\_76BC\_7FE4\_EBFD\_2D9E} +\dd RSA, 3072-bit. Key ID: \cw{DD4355EAAC1119DE}. Fingerprint: +\cw{A872\_D42F\_1660\_890F\_0E05\_223E\_DD43\_55EA\_AC11\_19DE} -\dt \W{https://www.chiark.greenend.org.uk/~sgtatham/putty/keys/release-2018.asc}{\s{Release Key} (2018)} +\dt \W{https://www.chiark.greenend.org.uk/~sgtatham/putty/keys/release-2021.asc}{\s{Release Key} (2021)} -\dd RSA, 3072-bit. Key ID: \cw{6289A25F4AE8DA82}. Fingerprint: -\cw{E273\_94AC\_A3F9\_D904\_9522\_\_E054\_6289\_A25F\_4AE8\_DA82} +\dd RSA, 3072-bit. Key ID: \cw{E4F83EA2AA4915EC}. Fingerprint: +\cw{2CF6\_134B\_D3F7\_7A65\_88EB\_D668\_E4F8\_3EA2\_AA49\_15EC} -\dt \W{https://www.chiark.greenend.org.uk/~sgtatham/putty/keys/snapshot-2018.asc}{\s{Snapshot Key} (2018)} +\dt \W{https://www.chiark.greenend.org.uk/~sgtatham/putty/keys/snapshot-2021.asc}{\s{Snapshot Key} (2021)} -\dd RSA, 3072-bit. Key ID: \cw{38BA7229B7588FD1}. Fingerprint: -\cw{C92B\_52E9\_9AB6\_1DDA\_33DB\_\_2B7A\_38BA\_7229\_B758\_8FD1} +\dd RSA, 3072-bit. Key ID: \cw{B43979F89F446CFD}. Fingerprint: +\cw{1FD3\_BCAC\_E532\_FBE0\_6A8C\_09E2\_B439\_79F8\_9F44\_6CFD} -\dt \W{https://www.chiark.greenend.org.uk/~sgtatham/putty/keys/contact-2018.asc}{\s{Secure Contact Key} (2018)} +\dt \W{https://www.chiark.greenend.org.uk/~sgtatham/putty/keys/contact-2021.asc}{\s{Secure Contact Key} (2021)} -\dd RSA, 3072-bit. Key ID: \cw{657D487977F95C98}. Fingerprint: -\cw{A680\_0082\_2998\_6E46\_22CA\_\_0E43\_657D\_4879\_77F9\_5C98} +\dd RSA, 3072-bit. Key ID: \cw{012C59D4211BD62A}. Fingerprint: +\cw{E30F\_1354\_2A04\_BE0E\_56F0\_5801\_012C\_59D4\_211B\_D62A} \H{pgpkeys-security} Security details @@ -169,6 +169,28 @@ generated keys. The details of all previous keys are given here. +\s{Keys generated in the 2018 rollover} + +\dt \W{https://www.chiark.greenend.org.uk/~sgtatham/putty/keys/master-2018.asc}{\s{Master Key} (2018)} + +\dd RSA, 4096-bit. Key ID: \cw{76BC7FE4EBFD2D9E}. Fingerprint: +\cw{24E1\_B1C5\_75EA\_3C9F\_F752\_\_A922\_76BC\_7FE4\_EBFD\_2D9E} + +\dt \W{https://www.chiark.greenend.org.uk/~sgtatham/putty/keys/release-2018.asc}{\s{Release Key} (2018)} + +\dd RSA, 3072-bit. Key ID: \cw{6289A25F4AE8DA82}. Fingerprint: +\cw{E273\_94AC\_A3F9\_D904\_9522\_\_E054\_6289\_A25F\_4AE8\_DA82} + +\dt \W{https://www.chiark.greenend.org.uk/~sgtatham/putty/keys/snapshot-2018.asc}{\s{Snapshot Key} (2018)} + +\dd RSA, 3072-bit. Key ID: \cw{38BA7229B7588FD1}. Fingerprint: +\cw{C92B\_52E9\_9AB6\_1DDA\_33DB\_\_2B7A\_38BA\_7229\_B758\_8FD1} + +\dt \W{https://www.chiark.greenend.org.uk/~sgtatham/putty/keys/contact-2018.asc}{\s{Secure Contact Key} (2018)} + +\dd RSA, 3072-bit. Key ID: \cw{657D487977F95C98}. Fingerprint: +\cw{A680\_0082\_2998\_6E46\_22CA\_\_0E43\_657D\_4879\_77F9\_5C98} + \s{Key generated in 2016} (when we first introduced the Secure Contact Key) \dt \W{https://www.chiark.greenend.org.uk/~sgtatham/putty/keys/contact-2016.asc}{\s{Secure Contact Key} (2016)} diff --git a/DOC/PLINK.BUT b/DOC/PLINK.BUT index 30dcead1..39b14f2b 100644 --- a/DOC/PLINK.BUT +++ b/DOC/PLINK.BUT @@ -41,7 +41,7 @@ use Plink: \c C:\>plink \c Plink: command-line connection utility -\c Release 0.76 +\c Release 0.78 \c Usage: plink [options] [user@]host [command] \c ("host" can also be a PuTTY saved session name) \c Options: @@ -61,7 +61,7 @@ use Plink: \c -sercfg configuration-string (e.g. 19200,8,n,1,X) \c Specify the serial configuration (serial only) \c The following options only apply to SSH connections: -\c -pw passw login with specified password +\c -pwfile file login with password read from specified file \c -D [listen-IP:]listen-port \c Dynamic SOCKS-based port forwarding \c -L [listen-IP:]listen-port:host:port diff --git a/DOC/PSCP.BUT b/DOC/PSCP.BUT index e816f3e5..96a2d4b9 100644 --- a/DOC/PSCP.BUT +++ b/DOC/PSCP.BUT @@ -39,7 +39,7 @@ use PSCP: \c C:\>pscp \c PuTTY Secure Copy client -\c Release 0.76 +\c Release 0.78 \c Usage: pscp [options] [user@]host:source target \c pscp [options] source [source...] [user@]host:target \c pscp [options] -ls [user@]host:filespec @@ -53,7 +53,7 @@ use PSCP: \c -load sessname Load settings from saved session \c -P port connect to specified port \c -l user connect with specified username -\c -pw passw login with specified password +\c -pwfile file login with password read from specified file \c -1 -2 force use of particular SSH protocol version \c -ssh -ssh-connection \c force use of particular SSH protocol variant diff --git a/DOC/PUBKEY.BUT b/DOC/PUBKEY.BUT index f40c9526..5ac59390 100644 --- a/DOC/PUBKEY.BUT +++ b/DOC/PUBKEY.BUT @@ -56,15 +56,15 @@ and convenience. See \k{pageant} for further details. There is more than one \i{public-key algorithm} available. The most common are \i{RSA} and \i{ECDSA}, but others exist, notably \i{DSA} -(otherwise known as DSS), the USA's federal Digital Signature Standard. +(otherwise known as \i{DSS}), the USA's federal Digital Signature Standard. The key types supported by PuTTY are described in \k{puttygen-keytype}. \H{pubkey-puttygen} Using \i{PuTTYgen}, the PuTTY key generator PuTTYgen is a key generator. It \I{generating keys}generates pairs of -public and private keys to be used with PuTTY, PSCP, and Plink, as well -as the PuTTY authentication agent, Pageant (see \k{pageant}). PuTTYgen -generates RSA, DSA, ECDSA, and EdDSA keys. +public and private keys to be used with PuTTY, PSCP, PSFTP, and Plink, +as well as the PuTTY authentication agent, Pageant (see \k{pageant}). +PuTTYgen generates RSA, DSA, ECDSA, and EdDSA keys. When you run PuTTYgen you will see a window where you have two main choices: \q{Generate}, to generate a new public/private key pair, or @@ -132,10 +132,13 @@ The \q{Number of bits} input box allows you to choose the strength of the key PuTTYgen will generate. \b For RSA and DSA, 2048 bits should currently be sufficient for most -purposes. +purposes. (Smaller keys of these types are no longer considered +secure, and PuTTYgen will warn if you try to generate them.) -\b For ECDSA, only 256, 384, and 521 bits are supported. (ECDSA offers -equivalent security to RSA with smaller key sizes.) +\b For ECDSA, only 256, 384, and 521 bits are supported, corresponding +to \i{NIST}-standardised elliptic curves. (Elliptic-curve keys do not +need as many bits as RSA keys for equivalent security, so these numbers +are smaller than the RSA recommendations.) \b For EdDSA, the only valid sizes are 255 bits (these keys are also known as \q{\i{Ed25519}} and are commonly used) and 448 bits @@ -145,6 +148,9 @@ the same as 255.) \S{puttygen-primes} Selecting the \i{prime generation method} +(This is entirely optional. Unless you know better, it's entirely +sensible to skip this and use the default settings.) + On the \q{Key} menu, you can also optionally change the method for generating the prime numbers used in the generated key. This is used for RSA and DSA keys only. (The other key types don't require @@ -154,9 +160,6 @@ 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 about this, it's entirely sensible to leave it on the -default setting. - The available methods are: \b Use \i{probable primes} (fast) @@ -177,6 +180,15 @@ are prime, because it generates the output number together with a proof of its primality. This takes more effort, but it eliminates that theoretical risk in the probabilistic method. +There in one way in which PuTTYgen's \q{proven primes} method is not +strictly better than its \q{probable primes} method. If you use +PuTTYgen to generate an RSA key on a computer that is potentially +susceptible to timing- or cache-based \i{side-channel attacks}, such +as a shared computer, the \q{probable primes} method is designed to +resist such attacks, whereas the \q{proven primes} methods are not. +(This is only a concern for RSA keys; for other key types, primes +are either not secret or not involved.) + You might choose to switch from probable to proven primes if you have a local security standard that demands it, or if you don't trust the probabilistic argument for the safety of the usual method. @@ -230,9 +242,9 @@ a particular fingerprint. So some utilities, such as the Pageant key list box (see \k{pageant-mainwin-keylist}) and the Unix \c{ssh-add} utility, will list key fingerprints rather than the whole public key. -By default, PuTTYgen will display fingerprints in the \q{SHA256} -format. If you need to see the fingerprint in the older \q{MD5} format -(which looks like \c{aa:bb:cc:...}), you can choose +By default, PuTTYgen will display SSH-2 key fingerprints in the +\q{SHA256} format. If you need to see the fingerprint in the older +\q{MD5} format (which looks like \c{aa:bb:cc:...}), you can choose \q{Show fingerprint as MD5} from the \q{Key} menu, but bear in mind that this is less cryptographically secure; it may be feasible for an attacker to create a key with the same fingerprint as yours. @@ -298,6 +310,48 @@ a result. \e{Do not forget your passphrase}. There is no way to recover it. +\S{puttygen-cert} Adding a \i{certificate} to your key + +In some environments, user authentication keys can be signed in turn +by a \q{certifying authority} (\q{CA} for short), and user accounts on +an SSH server can be configured to automatically trust any key that's +certified by the right signature. + +This can be a convenient setup if you have a very large number of +servers. When you change your key pair, you might otherwise have to +edit the \cw{authorized_keys} file on every server individually, to +make them all accept the new key. But if instead you configure all +those servers \e{once} to accept keys signed as yours by a CA, then +when you change your public key, all you have to do is to get the new +key certified by the same CA as before, and then all your servers will +automatically accept it without needing individual reconfiguration. + +To get your key signed by a CA, you'll probably send the CA the new +\e{public} key (not the private half), and get back a modified version +of the public key with the certificate included. + +If you want to incorporate the certificate into your PPK file for +convenience, you can use the \q{Add certificate to key} menu option in +PuTTYgen's \q{Key} menu. This will give you a single file containing +your private key and the certificate, which is everything you need to +authenticate to a server prepared to accept that certificate. + +To remove the certificate again and restore the uncertified PPK file, +there's also a \q{Remove certificate from key} option. + +(However, you don't \e{have} to incorporate the certificate into your +PPK file. You can equally well use it separately, via the +\q{Certificate to use with the private key} option in PuTTY itself. +See \k{config-ssh-cert}. It's up to you which you find more +convenient.) + +When the currently loaded key in PuTTYgen contains a certificate, the +large \q{Public key for pasting} edit box (see \k{puttygen-pastekey}) +is replaced by a button that brings up an information box telling you +about the certificate, such as who it certifies your key as belonging +to, when it expires (if ever), and the fingerprint of the CA key that +signed it in turn. + \S{puttygen-savepriv} Saving your private key to a disk file Once you have generated a key, set a comment field and set a @@ -389,8 +443,8 @@ 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. +You might change this if you consider your exposure to \i{side-channel +attacks} to be different to the norm. \dt Memory to use for passphrase hash @@ -469,6 +523,83 @@ you have generated an SSH-1 private key using OpenSSH or Hence, the export options are not available if you have generated an SSH-1 key. +\S{puttygen-cli} PuTTYgen command-line configuration + +PuTTYgen supports a set of command-line options to configure many of +the same settings you can select in the GUI. This allows you to start +it up with your own preferences ready-selected, which might be useful +if you generate a lot of keys. (For example, you could make a Windows +shortcut that runs PuTTYgen with some command line options, or a batch +file or Powershell script that you could distribute to a whole +organisation containing your local standards.) + +The options supported on the command line are: + +\dt \cw{\-t} \e{keytype} + +\dd Type of key to generate. You can select \c{rsa}, \c{dsa}, +\c{ecdsa}, \c{eddsa}, \c{ed25519}, \c{ed448}, or \c{rsa1}. +See \k{puttygen-keytype}. + +\dt \cw{\-b} \e{bits} + +\dd Size of the key to generate, in bits. See \k{puttygen-strength}. + +\dt \cw{\-\-primes} \e{method} + +\dd Method for generating prime numbers. You can select \c{probable}, +\c{proven}, and \c{proven-even}. See \k{puttygen-primes}. + +\dt \cw{\-\-strong-rsa} + +\dd When generating an RSA key, make sure the prime factors of the key +modulus are \q{strong primes}. See \k{puttygen-primes}. + +\dt \cw{\-\-ppk-param} \e{key}\cw{=}\e{value}\cw{,}... + +\dd Allows setting all the same details of the PPK save file format +described in \k{puttygen-save-params}. + +\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: either \cw{3} or \cw{2}. + +\dt \cw{kdf} + +\dd The variant of Argon2 to use: \cw{argon2id}, \cw{argon2i}, and +\cw{argon2d}. + +\dt \cw{memory} + +\dd The amount of memory needed to decrypt the key, in Kbyte. + +\dt \cw{time} + +\dd Specifies how much time is required to attempt decrypting the key, +in milliseconds. + +\dt \cw{passes} + +\dd Alternative to \cw{time}: specifies 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. + +} + +\dt \cw{\-E} \e{fptype} + +\dd Algorithm to use when displaying key fingerprints. You can +select \c{sha256} or \c{md5}. See \k{puttygen-fingerprint}. + \H{pubkey-gettingready} Getting ready for public key authentication Connect to your SSH server using PuTTY with the SSH protocol. When the diff --git a/DOC/SSHNAMES.BUT b/DOC/SSHNAMES.BUT index 6cf82f73..a00ac678 100644 --- a/DOC/SSHNAMES.BUT +++ b/DOC/SSHNAMES.BUT @@ -70,7 +70,7 @@ They have been superseded by \cw{arcfour128} and \cw{arcfour256}. The SSH agent protocol, which is only specified in an Internet-Draft at the time of writing -(\W{https://tools.ietf.org/html/draft-miller-ssh-agent}\cw{draft-miller-ssh-agent}), +(\W{https://datatracker.ietf.org/doc/html/draft-miller-ssh-agent}\cw{draft-miller-ssh-agent}), defines an extension mechanism. These names can be sent in an \cw{SSH_AGENTC_EXTENSION} message. diff --git a/DOC/UDP.BUT b/DOC/UDP.BUT index b3570d5d..12b3392b 100644 --- a/DOC/UDP.BUT +++ b/DOC/UDP.BUT @@ -28,9 +28,9 @@ platform-generic modules. The Unix-specific modules are all in the \c{unix} subdirectory; the Windows-specific modules are in the \c{windows} subdirectory. -All the modules in the main source directory - notably \e{all} of -the code for the various back ends - are platform-generic. We want -to keep them that way. +All the modules in the main source directory and other +subdirectories - notably \e{all} of the code for the various back +ends - are platform-generic. We want to keep them that way. This also means you should stick to the C semantics guaranteed by the C standard: try not to make assumptions about the precise size of @@ -171,9 +171,7 @@ to. C++ friendliness is really a side benefit.) We want PuTTY to continue being pure C, at least in the platform-independent parts and the currently existing ports. Patches which switch the Makefiles to compile it as C++ and start using -classes will not be accepted. Also, in particular, we disapprove of -\cw{//} comments, at least for the moment. (Perhaps once C99 becomes -genuinely widespread we might be more lenient.) +classes will not be accepted. The one exception: a port to a new platform may use languages other than C if they are necessary to code on that platform. If your @@ -278,16 +276,17 @@ should be aware that you might be re-entered if a network event comes in and is passed on to our window procedure by the \cw{MessageBox()} message loop. -Also, the front ends (in particular Windows Plink) can use multiple -threads if they like. However, Windows Plink keeps \e{very} tight -control of its auxiliary threads, and uses them pretty much -exclusively as a form of \cw{select()}. Pretty much all the code -outside \cw{windows/winplink.c} is \e{only} ever called from the one -primary thread; the others just loop round blocking on file handles -and send messages to the main thread when some real work needs -doing. This is not considered a portability hazard because that bit -of \cw{windows/winplink.c} will need rewriting on other platforms in -any case. +Also, the front ends can use multiple threads if they like. For +example, the Windows front-end code spawns subthreads to deal with +bidirectional blocking I/O on non-network streams such as Windows +pipes. However, it keeps tight control of its auxiliary threads, and +uses them only for that one purpose, as a form of \cw{select()}. +Pretty much all the code outside \cw{windows/handle-io.c} is \e{only} +ever called from the one primary thread; the others just loop round +blocking on file handles, and signal the main thread (via Windows +event objects) when some real work needs doing. This is not considered +a portability hazard because that code is already Windows-specific and +needs rewriting on other platforms. One important consequence of this: PuTTY has only one thread in which to do everything. That \q{everything} may include managing @@ -333,51 +332,11 @@ on a 640\u00D7{x}480 display. If you're adding controls to either of these boxes and you find yourself wanting to increase the size of the whole box, \e{don't}. Split it into more panels instead. -\H{udp-makefiles-auto} Automatically generated \cw{Makefile}s - -PuTTY is intended to compile on multiple platforms, and with -multiple compilers. It would be horrifying to try to maintain a -single \cw{Makefile} which handled all possible situations, and just -as painful to try to directly maintain a set of matching -\cw{Makefile}s for each different compilation environment. - -Therefore, we have moved the problem up by one level. In the PuTTY -source archive is a file called \c{Recipe}, which lists which source -files combine to produce which binaries; and there is also a script -called \cw{mkfiles.pl}, which reads \c{Recipe} and writes out the -real \cw{Makefile}s. (The script also reads all the source files and -analyses their dependencies on header files, so we get an extra -benefit from doing it this way, which is that we can supply correct -dependency information even in environments where it's difficult to -set up an automated \c{make depend} phase.) - -You should \e{never} edit any of the PuTTY \cw{Makefile}s directly. -They are not stored in our source repository at all. They are -automatically generated by \cw{mkfiles.pl} from the file \c{Recipe}. - -If you need to add a new object file to a particular binary, the -right thing to do is to edit \c{Recipe} and re-run \cw{mkfiles.pl}. -This will cause the new object file to be added in every tool that -requires it, on every platform where it matters, in every -\cw{Makefile} to which it is relevant, \e{and} to get all the -dependency data right. - -If you send us a patch that modifies one of the \cw{Makefile}s, you -just waste our time, because we will have to convert it into a -change to \c{Recipe}. If you send us a patch that modifies \e{all} -of the \cw{Makefile}s, you will have wasted a lot of \e{your} time -as well! - -(There is a comment at the top of every \cw{Makefile} in the PuTTY -source archive saying this, but many people don't seem to read it, -so it's worth repeating here.) - -\H{udp-ssh-coroutines} Coroutines in the SSH code - -Large parts of the code in the various SSH modules (in fact most of -the protocol layers) are structured using a set of macros that -implement (something close to) Donald Knuth's \q{coroutines} concept -in C. +\H{udp-ssh-coroutines} Coroutines in protocol code + +Large parts of the code in modules implementing wire protocols +(mainly SSH) are structured using a set of macros that implement +(something close to) Donald Knuth's \q{coroutines} concept in C. Essentially, the purpose of these macros are to arrange that a function can call \cw{crReturn()} to return to its caller, and the @@ -388,7 +347,7 @@ This means that any local (automatic) variables declared in such a function will be corrupted every time you call \cw{crReturn}. If you need a variable to persist for longer than that, you \e{must} make it a field in some appropriate structure containing the persistent state -of the coroutine \dash typically the main state structure for an SSH +of the coroutine \dash typically the main state structure for a protocol layer. See @@ -544,13 +503,13 @@ call sites. Instead, what we generally do in this code base is to write a set of \cw{static inline} wrapper functions in the same header file that defined the \cw{MyAbstraction} structure types, like this: -\c static MyAbstraction *myabs_new(const MyAbstractionVtable *vt) +\c static inline MyAbstraction *myabs_new(const MyAbstractionVtable *vt) \c { return vt->new(vt); } -\c static void myabs_free(MyAbstraction *myabs) +\c static inline void myabs_free(MyAbstraction *myabs) \c { myabs->vt->free(myabs); } -\c static void myimpl_modify(MyAbstraction *myabs, unsigned param) +\c static inline void myimpl_modify(MyAbstraction *myabs, unsigned param) \c { myabs->vt->modify(myabs, param); } -\c static unsigned myimpl_query(MyAbstraction *myabs, unsigned param) +\c static inline unsigned myimpl_query(MyAbstraction *myabs, unsigned param) \c { return myabs->vt->query(myabs, param); } And now call sites can use those reasonably clean-looking wrapper @@ -598,8 +557,8 @@ based on the offset within that structure of the field called This system is flexible enough to permit \q{multiple inheritance}, or rather, multiple \e{implementation}: having one object type implement -more than one trait. For example, the \cw{Proxy} type implements both -the \cw{Socket} trait and the \cw{Plug} trait that connects to it, +more than one trait. For example, the \cw{ProxySocket} type implements +both the \cw{Socket} trait and the \cw{Plug} trait that connects to it, because it has to act as an adapter between another instance of each of those types. @@ -791,46 +750,6 @@ other two full implementation vtables. } -\H{udp-compile-once} Single compilation of each source file - -The PuTTY build system for any given platform works on the following -very simple model: - -\b Each source file is compiled precisely once, to produce a single -object file. - -\b Each binary is created by linking together some combination of -those object files. - -Therefore, if you need to introduce functionality to a particular -module which is only available in some of the tool binaries (for -example, a cryptographic proxy authentication mechanism which needs -to be left out of PuTTYtel to maintain its usability in -crypto-hostile jurisdictions), the \e{wrong} way to do it is by -adding \cw{#ifdef}s in (say) \cw{proxy.c}. This would require -separate compilation of \cw{proxy.c} for PuTTY and PuTTYtel, which -means that the entire \cw{Makefile}-generation architecture (see -\k{udp-makefiles-auto}) would have to be significantly redesigned. -Unless you are prepared to do that redesign yourself, \e{and} -guarantee that it will still port to any future platforms we might -decide to run on, you should not attempt this! - -The \e{right} way to introduce a feature like this is to put the new -code in a separate source file, and (if necessary) introduce a -second new source file defining the same set of functions, but -defining them as stubs which don't provide the feature. Then the -module whose behaviour needs to vary (\cw{proxy.c} in this example) -can call the functions defined in these two modules, and it will -either provide the new feature or not provide it according to which -of your new modules it is linked with. - -Of course, object files are never shared \e{between} platforms; so -it is allowable to use \cw{#ifdef} to select between platforms. This -happens in \cw{puttyps.h} (choosing which of the platform-specific -include files to use), and also in \cw{misc.c} (the Windows-specific -\q{Minefield} memory diagnostic system). It should be used -sparingly, though, if at all. - \H{udp-perfection} Do as we say, not as we do The current PuTTY code probably does not conform strictly to \e{all} diff --git a/DOC/USING.BUT b/DOC/USING.BUT index 02a67808..5865ac95 100644 --- a/DOC/USING.BUT +++ b/DOC/USING.BUT @@ -838,17 +838,23 @@ any case.) This option is equivalent to the port number control in the Session panel of the PuTTY configuration box (see \k{config-hostname}). -\S2{using-cmdline-pw} \i\c{-pw}: specify a \i{password} +\S2{using-cmdline-pw} \i\c{-pwfile} and \i\c{-pw}: specify a \i{password} A simple way to automate a remote login is to supply your password -on the command line. This is \e{not recommended} for reasons of -security. If you possibly can, we recommend you set up public-key -authentication instead. See \k{pubkey} for details. +on the command line. -Note that the \c{-pw} option only works when you are using the SSH -protocol. Due to fundamental limitations of Telnet, Rlogin, and -SUPDUP, these protocols do not support automated password -authentication. +The \c{-pwfile} option takes a file name as an argument. The first +line of text in that file will be used as your password. + +The \c{-pw} option takes the password itself as an argument. This is +\s{NOT SECURE} if anybody else uses the same computer, because the +whole command line (including the password) is likely to show up if +another user lists the running processes. \c{-pw} is retained for +backwards compatibility only; you should use \c{-pwfile} instead. + +Note that these options only work when you are using the SSH protocol. +Due to fundamental limitations of Telnet, Rlogin, and SUPDUP, these +protocols do not support automated password authentication. \S2{using-cmdline-agentauth} \i\c{-agent} and \i\c{-noagent}: control use of Pageant for authentication @@ -941,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 @@ -1014,6 +1024,19 @@ This option is equivalent to the \q{Private key file for authentication} box in the Auth panel of the PuTTY configuration box (see \k{config-ssh-privkey}). +\S2{using-cmdline-cert} \i\c{-cert}: specify an SSH \i{certificate} + +The \c{-cert} option allows you to specify the name of a certificate +file containing a signed version of your public key. If you specify +this option, PuTTY will present that certificate in place of the plain +public key, whenever it tries to authenticate with a key that matches. +(This applies whether the key is stored in Pageant or loaded directly +from a file by PuTTY.) + +This option is equivalent to the \q{Certificate to use with the +private key} box in the Auth panel of the PuTTY configuration box (see +\k{config-ssh-cert}). + \S2{using-cmdline-no-trivial-auth} \i\c{-no-trivial-auth}: disconnect if SSH authentication succeeds trivially @@ -1152,3 +1175,12 @@ the extra protection), so it's reasonable to want to run Pageant but not PuTTY with the ACL restrictions. You can force Pageant to start subsidiary PuTTY processes with a restricted ACL if you also pass the \i\c{-restrict-putty-acl} option. + +\S2{using-cmdline-host-ca} \i{\c{-host-ca}}: launch the +\I{certificate}host CA configuration + +If you start PuTTY with the \c{-host-ca} option, it will not launch a +session at all. Instead, it will just display the configuration dialog +box for host certification authorities, as described in +\k{config-ssh-kex-cert}. When you dismiss that dialog box, PuTTY will +terminate. diff --git a/DOC/man-pageant.but b/DOC/man-pageant.but index 358f3a08..d202f166 100644 --- a/DOC/man-pageant.but +++ b/DOC/man-pageant.but @@ -41,7 +41,7 @@ extract their public half. The agent protocol used by \c{pageant} is compatible with the PuTTY tools and also with other implementations such as OpenSSH's SSH client -and \e{ssh-agent(1)}. Some \c{pageant} features are implemented with +and \cw{ssh-agent}(\e{1}). Some \c{pageant} features are implemented with protocol extensions, so will only work if \c{pageant} is on both ends. To run \c{pageant} as an agent, you must provide an option to tell it @@ -256,6 +256,12 @@ be matched \dd to indicate that it is a fingerprint of a specific format +\dt \cq{sha256-cert:} or \cq{md5-cert:} + +\dd to indicate that it is a fingerprint of a specific format, and +specifically matches the fingerprint of the public key \e{including} a +certificate if any + } \dt \cw{--public-openssh} \e{key-identifiers}, \cw{-L} \e{key-identifiers} @@ -317,15 +323,15 @@ by the SSH agent protocol. \dt \cw{--askpass} \e{prompt} -\dd With this option, \c{pageant} acts as an \e{ssh-askpass(1)} +\dd With this option, \c{pageant} acts as an \cw{ssh-askpass}(\e{1}) replacement, rather than performing any SSH agent functionality. This may be useful if you prefer Pageant's GUI prompt style, which minimises information leakage about your passphrase length in its -visual feedback, compared to other \e{ssh-askpass(1)} implementations. +visual feedback, compared to other \cw{ssh-askpass}(\e{1}) implementations. \lcont{ -\c{pageant --askpass} implements the standard \e{ssh-askpass(1)} +\c{pageant --askpass} implements the standard \cw{ssh-askpass}(\e{1}) interface: it can be passed a prompt to display (as a single argument) and, if successful, prints the passphrase on standard output and returns a zero exit status. Typically you would use the environment diff --git a/DOC/man-plink.but b/DOC/man-plink.but index 26e65f71..2a3b36c7 100644 --- a/DOC/man-plink.but +++ b/DOC/man-plink.but @@ -59,9 +59,9 @@ to aid in verifying new files released by the PuTTY team. \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}. +only likely to be useful when connecting to a \cw{psusan}(\e{1}) +server, most likely with an absolute path to a Unix-domain socket in +place of \e{host}. \dt \cw{\-proxycmd} \e{command} @@ -114,11 +114,16 @@ sequences. These options override Plink's default behaviour to enable or disabling such filtering on the standard error and standard output channels. +\dt \cw{-pwfile} \e{filename} + +\dd Open the specified file, and use the first line of text read from +it as the remote password. + \dt \cw{-pw} \e{password} \dd Set remote password to \e{password}. \e{CAUTION:} this will likely make the password visible to other users of the local machine (via -commands such as \q{\c{w}}). +commands such as \q{\c{ps}} or \q{\c{w}}). Use \cw{-pwfile} instead. \dt \cw{\-L} \cw{[}\e{srcaddr}\cw{:]}\e{srcport}\cw{:}\e{desthost}\cw{:}\e{destport} diff --git a/DOC/man-psftp.but b/DOC/man-psftp.but index 52617291..e0b48602 100644 --- a/DOC/man-psftp.but +++ b/DOC/man-psftp.but @@ -89,11 +89,16 @@ channel from the server, to prevent remote processes sending confusing escape sequences. This option forces the standard error channel to not be filtered. +\dt \cw{-pwfile} \e{filename} + +\dd Open the specified file, and use the first line of text read from +it as the remote password. + \dt \cw{-pw} \e{password} \dd Set remote password to \e{password}. \e{CAUTION:} this will likely make the password visible to other users of the local machine (via -commands such as \q{\c{w}}). +commands such as \q{\c{ps}} or \q{\c{w}}). Use \cw{-pwfile} instead. \dt \cw{-1} @@ -106,9 +111,9 @@ commands such as \q{\c{w}}). \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}. +only likely to be useful when connecting to a \cw{psusan}(\e{1}) +server, most likely with an absolute path to a Unix-domain socket in +place of \e{host}. \dt \cw{-ssh} diff --git a/DOC/man-psocks.but b/DOC/man-psocks.but index a9792e44..eb075a6e 100644 --- a/DOC/man-psocks.but +++ b/DOC/man-psocks.but @@ -18,8 +18,8 @@ IPv4 and IPv6 connections. It does not support requiring authentication of its clients. \cw{psocks} can be used together with an SSH client such as -\cw{putty(1)} to implement a reverse dynamic SSH tunnel. It can also -be used for network protocol debugging, as it can record all the +\cw{putty}(\e{1}) to implement a reverse dynamic SSH tunnel. It can +also be used for network protocol debugging, as it can record all the traffic passing through it in various ways. By default, \cw{psocks} listens to connections from localhost only, @@ -84,8 +84,8 @@ have the connection's traffic piped into it, similar to \cw{-f}. \S{psocks-manpage-examples} EXAMPLES -In combination with the \e{plink(1)} SSH client, to set up a reverse -dynamic SSH tunnel, in which the remote listening port 1080 on +In combination with the \cw{plink}(\e{1}) SSH client, to set up a +reverse dynamic SSH tunnel, in which the remote listening port 1080 on remote host \cw{myhost} acts as a SOCKS server giving access to your local network: diff --git a/DOC/man-psusan.but b/DOC/man-psusan.but index fa986e88..64d3a030 100644 --- a/DOC/man-psusan.but +++ b/DOC/man-psusan.but @@ -191,15 +191,36 @@ And the setup script \cw{uml-psusan.sh} might look like this: \c # Choose what shell you want to run inside psusan \e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii \c export SHELL=/bin/bash +\c # Set up a default path +\e iiiiiiiiiiiiiiiiiiiiiii +\c export PATH=/usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin:/bin:/sbin \c # And now run psusan over the serial port \e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii \c exec /home/simon/src/putty/misc/psusan -Now set up a PuTTY saved session as in the Docker example above, using -that \cw{linux} command as the local proxy command, and you'll have a -PuTTY session that starts up a clean UML instance when you run it, and -(if you enabled connection sharing) further instances of the same -session will connect to the same instance again. +Now set up a PuTTY saved session as in the Docker example above. +Basically you'll want to use the above \cw{linux} command as the local +proxy command. However, it's worth wrapping it in \cw{setsid}(\e{1}), +because when UML terminates, it kills its entire process group. So +it's better that PuTTY should not be part of that group, and should +have the opportunity to shut down cleanly by itself. So probably you +end up setting the proxy command to be something more like: + +\c setsid linux mem=512M rootfstype=hostfs rootflags=/ rw \ +\c con=fd:2,fd:2 ssl0=fd:0,fd:1 init=/some/path/to/uml-psusan.sh +\e iiiiiiiiiiiiiiiiiiiiiiiiiii + +You may also find that you have to enable the bug workaround that +indicates that the server \q{Discards data sent before its greeting}, +because otherwise PuTTY's outgoing protocol greeting can be +accidentally lost during UML startup. (See +\W{https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=991958}{Debian +bug #991958}.) + +Once you've done that, you'll have a PuTTY session that starts up a +clean UML instance when you run it, and (if you enabled connection +sharing) further instances of the same session will connect to the +same instance again. \S2{psusan-manpage-examples-wsl} Windows Subsystem for Linux @@ -231,6 +252,39 @@ ports in and out of the WSL environment (e.g. expose a WSL2 network service through the hypervisor's internal NAT), forward Pageant into it, and so on. +\S2{psusan-manpage-examples-cygwin} Cygwin + +Another Unix-like environment on Windows is Cygwin. That comes with +its own GUI terminal application, \cw{mintty} (as it happens, a +derivative of PuTTY); but if you'd prefer to use PuTTY itself to talk +to your Cygwin terminal sessions, \cw{psusan} can help. + +To do this, you'll first need to build the Unix PuTTY tools inside +Cygwin (via the usual \cw{cmake} method). Then, copy the resulting +\cw{psusan.exe} into Cygwin's \cw{/bin} directory. (It has to be +in that directory for non-Cygwin programs to run it; otherwise it +won't be able to find the Cygwin DLL at startup.) + +Then set up your PuTTY saved session like this: + +\b set the local proxy command to run \cw{psusan.exe} via its real +Windows path. You might also want to add the \cw{--sessiondir} option +so that shell sessions start up in your Cygwin home directory. For +example, you might use the command \cq{c:\\cygwin64\\bin\\psusan.exe +--sessiondir /home/simon} (changing the pathname and username to match +your setup). + +\b enter anything you like in the host name box; \cq{Cygwin} is +probably a good choice + +\b set the protocol to \q{Bare ssh-connection}, as usual. + +Port forwarding is probably not particularly useful in this case, +since Cygwin shares the same network port space as the host machine. +But turning on agent forwarding is useful, because then the Cygwin +command-line SSH client can talk to Pageant without any further +configuration. + \S2{psusan-manpage-examples-schroot} \cw{schroot} Another example of a container-like environment is the alternative diff --git a/DOC/man-pterm.but b/DOC/man-pterm.but index fec97f11..d3d1d96a 100644 --- a/DOC/man-pterm.but +++ b/DOC/man-pterm.but @@ -76,7 +76,7 @@ will be ignored unless the \cw{BoldAsColour} resource is set to 0 or 2. \dt \cw{\-geometry} \e{geometry} \dd Specify the size of the terminal, in rows and columns of text. See -\e{X(7)} for more information on the syntax of geometry +\cw{X}(\e{7}) for more information on the syntax of geometry specifications. \dt \cw{\-sl} \e{lines} diff --git a/DOC/man-putty.but b/DOC/man-putty.but index 858ec0b0..a85b4505 100644 --- a/DOC/man-putty.but +++ b/DOC/man-putty.but @@ -55,7 +55,7 @@ will be ignored unless the \cw{BoldAsColour} resource is set to 0 or 2. \dt \cw{\-geometry} \e{geometry} \dd Specify the size of the terminal, in rows and columns of text. -See \e{X(7)} for more information on the syntax of geometry +See \cw{X}(\e{7}) for more information on the syntax of geometry specifications. \dt \cw{\-sl} \e{lines} diff --git a/DOC/man-puttygen.but b/DOC/man-puttygen.but index 021af205..e6a2c990 100644 --- a/DOC/man-puttygen.but +++ b/DOC/man-puttygen.but @@ -12,10 +12,12 @@ \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 [ --certificate cert-file | --remove-certificate ] +\e bbbbbbbbbbbbb iiiiiiiii bbbbbbbbbbbbbbbbbbbb +\c [ -O output-type | -l | -L | -p | --dump | --cert-info ] +\e bb iiiiiiiiiii bb bb bb bbbbbb bbbbbbbbbbb +\c [ --ppk-param key=value,... | -E fptype ] +\e bbbbbbbbbbb iiibiiiiib bb iiiiii \c [ -o output-file ] \e bb iiiiiiiiiii @@ -58,8 +60,9 @@ ssh.com's implementation. You can also specify a file containing only a \e{public} key here. The operations you can do are limited to outputting another public -key format or a fingerprint. Public keys can be in RFC 4716 or -OpenSSH format, or the standard SSH-1 format. +key format (possibly removing an attached certificate first), or a +fingerprint. Public keys can be in RFC 4716 or OpenSSH format, or +the standard SSH-1 format. } @@ -143,6 +146,19 @@ to type). automatic when you are generating a new key, but not when you are modifying an existing key. +\dt \cw{\-\-certificate} \e{certificate-file} + +\dd Adds an OpenSSH-style certificate to the public half of the key, +so that the output file contains a certified public key with the same +private key. If the input file already contained a certificate, it +will be replaced with the new one. (Use \cq{-} to read a certificate +from standard input.) + +\dt \cw{\-\-remove\-certificate} + +\dd Removes any certificate that was part of the key, to recover the +uncertified version of the underlying key. + \dt \cw{\-\-reencrypt} \dd For an existing private key saved with a passphrase, refresh the @@ -260,6 +276,13 @@ newer format even for RSA, DSA, and ECDSA keys. \dd Save an SSH-2 private key in ssh.com's format. This option is not permitted for SSH-1 keys. +\dt \cw{cert-info} + +\dd Save a textual dump of information about the certificate on the +key, if any: whether it's a host or a user certificate, what host(s) +or user(s) it's certified to be, its validity period, ID and serial +number, and the fingerprint of the signing CA. + \dt \cw{text} \dd Save a textual dump of the numeric components comprising the key @@ -269,8 +292,9 @@ SSH. \lcont{ The output consists of a series of \cw{name=value} lines, where each -\c{value} is either a C-like string literal in double quotes, or a -hexadecimal number starting with \cw{0x...} +\c{value} is either a C-like string literal in double quotes, a +hexadecimal number starting with \cw{0x...}, or a binary blob +encoded with base64, denoted by \cw{b64("...")}. } If no output type is specified, the default is \c{private}. @@ -283,8 +307,9 @@ If no output type is specified, the default is \c{private}. this option is not specified, \c{puttygen} will assume you want to overwrite the original file if the input and output file types are the same (changing a comment or passphrase), and will assume you -want to output to stdout if you are asking for a public key or -fingerprint. Otherwise, the \c{\-o} option is required. +want to output to stdout if you are asking for a public key, +fingerprint, or one of the textual dump types. Otherwise, the +\c{\-o} option is required. \dt \cw{\-l} @@ -298,6 +323,10 @@ fingerprint. Otherwise, the \c{\-o} option is required. \dd Synonym for \q{\cw{-O public}}. +\dt \cw{\-\-cert\-info} + +\dd Synonym for \q{\cw{-O cert-info}}. + \dt \cw{\-\-dump} \dd Synonym for \q{\cw{-O text}}. @@ -305,7 +334,18 @@ fingerprint. Otherwise, the \c{\-o} option is required. \dt \cw{-E} \e{fptype} \dd Specify the algorithm to use if generating a fingerprint. The -options are \cw{sha256} (the default) and \cw{md5}. +available algorithms are are \cw{sha256} (the default) and \cw{md5}. + +\lcont{ + +By default, when showing the fingerprint of a public key that includes +a certificate, \c{puttygen} will not include the certificate, so that +the fingerprint shown will be the same as the underlying public key. +If you want the fingerprint including the certificate (for example, so +as to tell two certified keys apart), you can specify \cw{sha256-cert} +or \cw{md5-cert} as the fingerprint type. + +} \dt \cw{\-\-new\-passphrase} \e{file} diff --git a/DOC/man-puttytel.but b/DOC/man-puttytel.but index bf852ddb..075eeea7 100644 --- a/DOC/man-puttytel.but +++ b/DOC/man-puttytel.but @@ -56,7 +56,7 @@ will be ignored unless the \cw{BoldAsColour} resource is set to 0 or 2. \dt \cw{\-geometry} \e{geometry} \dd Specify the size of the terminal, in rows and columns of text. See -\e{X(7)} for more information on the syntax of geometry +\cw{X}(\e{7}) for more information on the syntax of geometry specifications. \dt \cw{\-sl} \e{lines} diff --git a/DOC/pubkeyfmt.but b/DOC/pubkeyfmt.but index 78da4885..836ed527 100644 --- a/DOC/pubkeyfmt.but +++ b/DOC/pubkeyfmt.but @@ -7,7 +7,7 @@ In this appendix, binary data structures are described using data type representations such as \cq{uint32}, \cq{string} and \cq{mpint} as used in the SSH protocol standards themselves. These are defined authoritatively by -\W{https://tools.ietf.org/html/rfc4251#section-5}{RFC 4251 section 5}, +\W{https://www.rfc-editor.org/rfc/rfc4251#section-5}{RFC 4251 section 5}, \q{Data Type Representations Used in the SSH Protocols}. \H{ppk-overview} Overview @@ -86,7 +86,7 @@ can contain any byte values other than 13 and 10 (CR and LF). The next part of the file gives the public key. This is stored unencrypted but base64-encoded -(\W{https://tools.ietf.org/html/rfc4648}{RFC 4648}), and is preceded +(\W{https://www.rfc-editor.org/rfc/rfc4648}{RFC 4648}), and is preceded by a header line saying how many lines of base64 data are shown, looking like this: @@ -241,7 +241,7 @@ of \e{y} in the group generated by \e{g} mod \e{p}. \S{ppk-privkey-ecdsa} NIST elliptic-curve keys -NIST elliptic-curve keys are stored using one of the following +\i{NIST} elliptic-curve keys are stored using one of the following \s{algorithm-name} values, each corresponding to a different elliptic curve and key size: |