If we're publishing the server, then we should say something about the
fact that this option exists to talk to it. Also, if the option exists
on the front page at all in a released version of PuTTY, it behooves
us to document it slightly more usefully than just a handwave at 'this
is specialist and experimental'.
SUPDUP came, at my insistence, with a history section in the docs
for people who hadn't heard of it. It seems only fair that the
other obsolete network protocols (or, at least, the ones we *wish*
were obsolete :-) should have the same kind of treatment.
Moved the Raw protocol to below Serial, so that the first two
sections are SSH and Serial, matching the (now very emphatic)
priority order in the config UI.
Similarly, reordered the bullet points in \k{config-hostname}.
I've filled in some text about prime generation methods and Ed448,
which were all the things marked as 'review before release'.
While I'm at it, also filled in a reasonable enough DSA key length
recommendation, because the FIXME comment in that section was within
sight of one of the places I was editing. FIPS 186-4 seemed to think
that RSA and DSA had comparable relationships between the key length
and practical security level, so I see no reason not to use the same
recommendation for both key types.
This seems more useful than the previous behaviour of not prompting for
a passphrase and only emitting the public part; if we want that back
I suppose we could invent a "-O text-public".
Also, document the text dump format a bit in the man page.
This removes both uses of SHA-1 in the file format: it was used as the
MAC protecting the key file against tamperproofing, and also used in
the key derivation step that converted the user's passphrase to cipher
and MAC keys.
The MAC is simply upgraded from HMAC-SHA-1 to HMAC-SHA-256; it is
otherwise unchanged in how it's applied (in particular, to what data).
The key derivation is totally reworked, to be based on Argon2, which
I've just added to the code base. This should make stolen encrypted
key files more resistant to brute-force attack.
Argon2 has assorted configurable parameters for memory and CPU usage;
the new key format includes all those parameters. So there's no reason
we can't have them under user control, if a user wants to be
particularly vigorous or particularly lightweight with their own key
files. They could even switch to one of the other flavours of Argon2,
if they thought side channels were an especially large or small risk
in their particular environment. In this commit I haven't added any UI
for controlling that kind of thing, but the PPK loading function is
all set up to cope, so that can all be added in a future commit
without having to change the file format.
While I'm at it, I've also switched the CBC encryption to using a
random IV (or rather, one derived from the passphrase along with the
cipher and MAC keys). That's more like normal SSH-2 practice.
When I transcribed the code into this document, I misread 'put_data'
as 'put_string' in several places, and documented SSH-style string
length headers that do not actually exist in the format.
Somebody on comp.security.ssh asked about it recently, and I decided
that storing it in a comment in the key file was not really good
enough. Also, that comment was incomplete (it listed the private key
formats for RSA and DSA but not any of the newer ECC key types, simple
as their private-key formats may be).
A user wrote in to point out the one in winhandl.c, and out of sheer
curiosity, I grepped the whole source base for '([a-zA-Z])\1\1' to see
if there were any others. Of course there are a lot of perfectly
sensible ones, like 'www' or 'Grrr', not to mention any amount of
0xFFFF and the iiii/bbbb emphasis system in Halibut code paragraphs,
but I did spot one more in the recently added udp.but section on
traits, and another in a variable name in uxagentsock.c.
A user mentioned having found this confusing recently, and fair
enough, because it's done in a way that doesn't quite match the
built-in OO system of any language I know about. But after the
rewriting in recent years, I think pretty much everything in PuTTY
that has a system of interchangeable implementations of the same
abstract type is now done basically the same way, so this seems like a
good moment to document the idiom we use and explain all its ins and
outs.
It referred to the global variable 'flags' as an example. But 'flags'
was retired (and good riddance) nearly a year ago, in commit
4ea811a0bf. So we should be using a different example now!
When I added the psusan man page, I noticed that they've all got
impenetrable names like 'man-pl.but' to fit within 8.3 naming. But
this source base hasn't had to worry about 8.3 naming conventions in a
long time, so I think I can safely rename all those files to ones
whose purpose is more obvious.
I've been collecting actual examples of things I've used psusan for,
and now I think I have enough of them to make some kind of case for
why it's a useful tool. So I've written a man page, and dumped all my
collected examples in there.
Two minor memory-leak fixes on 0.74 seem not to be needed on master:
the fix in an early exit path of pageant_add_keyfile is done already
on master in a different way, and the missing sfree(fdlist) in
uxsftp.c is in code that's been completely rewritten in the uxcliloop
refactoring.
Other minor conflicts: the rework in commit b52641644905 of
ssh1login.c collided with the change from FLAG_VERBOSE to
seat_verbose(), and master and 0.74 each added an unrelated extra
field to the end of struct SshServerConfig.
This mitigates CVE-2020-14002: if you're in the habit of clicking OK
to unknown host keys (the TOFU policy - trust on first use), then an
active attacker looking to exploit that policy to substitute their own
host key in your first connection to a server can use the host key
algorithm order in your KEXINIT to (not wholly reliably) detect
whether you have a key already stored for this host, and if so, abort
their attack to avoid giving themself away.
However, for users who _don't_ use the TOFU policy and instead check
new host keys out of band, the dynamic policy is more useful. So it's
provided as a configurable option.
The previous prompts were part of transcripts pasted directly from a
particular historical cmd session, but that's no reason to keep them
lying around confusingly, especially since we keep regenerating some
of those transcripts outside that historical context. Replace them all
with nice simple C:\> which shouldn't confuse anyone with extraneous
detail.
