From 28f67586f568a3ec0388f58b5a87fa5cfed1a637 Mon Sep 17 00:00:00 2001 From: Jacob Nevins Date: Fri, 25 Mar 2016 15:42:42 +0000 Subject: [PATCH] Document host key cross-certification. --- doc/config.but | 6 +++--- doc/gs.but | 16 ++++++++-------- doc/index.but | 3 ++- doc/using.but | 26 ++++++++++++++++++++++++-- 4 files changed, 37 insertions(+), 14 deletions(-) diff --git a/doc/config.but b/doc/config.but index e56c069a..f0ccc150 100644 --- a/doc/config.but +++ b/doc/config.but @@ -1747,7 +1747,7 @@ arbitrary port (say, \cw{localhost} port 10022) were forwarded to a second machine's SSH port (say, \cw{foovax} port 22), and then started a second PuTTY connecting to the forwarded port. -In normal usage, the second PuTTY will access the host key cache +In normal usage, the second PuTTY will access the \i{host key cache} under the host name and port it actually connected to (i.e. \cw{localhost} port 10022 in this example). Using the logical host name option, however, you can configure the second PuTTY to cache @@ -2531,8 +2531,8 @@ If this box contains at least one host key or fingerprint when PuTTY makes an SSH connection, then PuTTY's automated host key management is completely bypassed: the connection will be permitted if and only if the host key presented by the server is one of the keys listed in this -box, and the host key store in the Registry will be neither read -\e{nor written}. +box, and the \I{host key cache}host key store in the Registry will be +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. diff --git a/doc/gs.but b/doc/gs.but index 5909c8a3..c0401fdb 100644 --- a/doc/gs.but +++ b/doc/gs.but @@ -77,13 +77,13 @@ server and it sends you a different host key from the one you were expecting, PuTTY can warn you that the server may have been switched and that a spoofing attack might be in progress. -PuTTY 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. +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. 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 @@ -97,7 +97,7 @@ network users are on the same side and spoofing attacks are unlikely, so you might choose to trust the key without checking it. If you are connecting across a hostile network (such as the Internet), you should check with your system administrator, perhaps -by telephone or in person. (Some modern servers have more than one +by telephone or in person. (Many servers have more than one host key. If the system administrator sends you more than one \I{host key fingerprint}fingerprint, you should make sure the one PuTTY shows you is on the list, but it doesn't matter which one it is.) diff --git a/doc/index.but b/doc/index.but index 204430ce..e11c60ba 100644 --- a/doc/index.but +++ b/doc/index.but @@ -850,7 +850,8 @@ saved sessions from \IM{logical host name} logical host name \IM{logical host name} host name, logical -\IM{logical host name} host key, caching policy + +\IM{host key cache}{host key caching policy} host key caching policy \IM{web browsers} web browser diff --git a/doc/using.but b/doc/using.but index 0a05c2e2..343612b0 100644 --- a/doc/using.but +++ b/doc/using.but @@ -201,6 +201,28 @@ resets associated timers and counters). For more information about repeat key exchanges, see \k{config-ssh-kex-rekey}. } +\b \I{host key cache}Cache new host key type + +\lcont{ +Only available in SSH-2. This submenu appears only if the server has +host keys of a type that PuTTY doesn't already have cached, and so +won't use. Selecting a key here will allow PuTTY to use that key now +and in future: PuTTY will do key here will cause a fresh key-exchange +with the selected key, and immediately add that key to PuTTY's +permanent cache (relying on the host key used at the start of the +connection to cross-certify the new key). That key will be used for +the rest of the current session; it may not actually be used for +future sessions. + +Normally, PuTTY will carry on using a host key it already knows, even +if the server offers key formats that PuTTY would otherwise prefer, +to avoid host key prompts. As a result, if you've been using a server +for some years, you may still be using an older key than a new user +would use, due to server upgrades in the meantime. The SSH protocol +unfortunately does not have organised facilities for host key migration +and rollover, but this allows you to manually upgrade. +} + \b \I{Break, SSH special command}Break \lcont{ @@ -912,7 +934,7 @@ authentication} box in the Auth panel of the PuTTY configuration box \S2{using-cmdline-loghost} \i\c{-loghost}: specify a \i{logical host name} -This option overrides PuTTY's normal SSH host key caching policy by +This option overrides PuTTY's normal SSH \i{host key caching policy} by telling it the name of the host you expect your connection to end up at (in cases where this differs from the location PuTTY thinks it's connecting to). It can be a plain host name, or a host name followed @@ -922,7 +944,7 @@ on this. \S2{using-cmdline-hostkey} \i\c{-hostkey}: \I{manually configuring host keys}manually specify an expected host key -This option overrides PuTTY's normal SSH host key caching policy by +This option overrides PuTTY's normal SSH \i{host key caching policy} by telling it exactly what host key to expect, which can be useful if the normal automatic host key store in the Registry is unavailable. The argument to this option should be either a host key fingerprint, or an