please decrypt your manuals

[Bob Proulx]

Doru Georgescu wrote:
> I. most of ssh manual and all sshd manual present server and client
> as one machine, called host.

Well, that is certainly one possibility.  A single host may be
operating both as a client and as a server *to itself* and that is
perfectly okay.  The documentation is very generically and very
precisely correct by not making assumptions and simply explaining
things dryly.

> All files mentioned are placed on one machine. This is incorrect,
> and makes the explanation unclear.

But it isn't incorrect.  A single host may be either a client or a
server or both.  The choice is completely controlled by how it is
configured.  The administrator may configure it ether one way or the
other way or both ways.

The documentation is very generically and very precisely correct by
not making assumptions and simply explaining things dryly.

> For example, man sshd SSH_KNOWN_HOSTS FILE FORMAT suggests to copy
> keys from /etc/ssh/ssh_host_key.pub into /etc/ssh/ssh_known_hosts,
> as if those files are on the same machine.

I do not see that in my copy of the manual.  I do see an explanation
of where the bits come from.  But I don't see a suggestion that a
human do this copying.  In fact I see an admonition that you would not
want to "type them in by hand" but would instead "generate them by a
script or by taking /etc/ssh/ssh_host_key.pub and adding the host
names at the front."  By "host names" it is clearly talking about
multiple hosts, in the plural, and cannot be referring to a single
host.

But...  I think most users of ssh can use it for many years and never
even know about the files in /etc/ssh/*.  It isn't necessary in the
normal course of operation for them to know about them.  I wouldn't
recommend that a user copy files /etc/ssh/ssh_host_rsa_key.pub to
their ~/known_hosts file.  How would they actually do that?  They
would likely want to use ssh for that and that would be a
bootstrapping problem.  Better to check the hash fingerprint of the
key in that case.

> II. a general presentation of ssh workings is missing, and makes the
> decryption of those manuals even more difficult. i suppose, but i am
> not sure that:
> 
> both encrypt their messages with the encryption keys in: 
> /etc/ssh/ssh_host_[rd]sa_key
> /etc/ssh/ssh_host_[rd]sa_key.pub

On one level I don't think this matters to a user.  Users don't need
to know this in order to use ssh securely.  As an alternate example,
people drive cars.  People drive cars over bridges.  Documenting how
the bridge is constructed is definitely of interest to public safety
but most drivers do not need to know how to construct a bridge in
order to drive over one safely.  Therefore I would leave this
documentation for other resources.

> both can memorize known hosts' public encryption keys in
> /etc/ssh/ssh_known_hosts and ~/.ssh/known_hosts

Checking the key's fingerprint is more commonly the check method of
choice.

> only the server is protected through authentication. this happens in
> two ways:
> 
> 1. server side: 
>       a. the client provides an authentication key: 
>          + public part in //server/~/.ssh/authorized_keys 
>             with chmod 700 .ssh; chmod 600 authorized_keys 

It isn't necessary that the file not be readable, just not writable by
other than the owner.  Your use of 700 and 600 is too restrictive.

>          + private part in //client/~/.ssh/id_rsa 

There is a problem with using //client/etc/ssh/... and
//server/etc/ssh/... types of paths in the documentation to mean
that files reside on the client and server however.  The "//"
characters are special at the front of a path name.  Apollo Domain
systems, later OSF/1, and currently Cygwin all use it to indicate that
the next part is a hostname.  Because of this POSIX has standardized
that when "//" occurs at the leading part of a path name that the
result is implementation defined.  (Or maybe undefined, I didn't look
it up now to be certain.)

Therefore it would be very confusing to use it here to indicate that
some files exist on the client side of the ssh connection and another
file on the server side of the ssh connection when, depending upon the
system the user happens to be running on, the syntax on that machine
might actually indicate something completely different from what you
are trying to indicate.  It is possible that on a user's system that
//client/etc/... might be an actual working live path to a real system!
They might end up trying it literally and getting files from some
other system other than the one you intended.  Therefore you shouldn't
use it as an example meaning something completely different.  Even
though it doesn't work that way on most systems we avoid it out of
neighborly politeness and respect for the standard.

>       the authentication key is created with: 
>       ssh-keygen -t rsa
>       ll gives: 
>       -rw-------    1 dave     dave          526 Nov  3 01:21 id_rsa
>       -rw-r--r--    1 dave     dave          330 Nov  3 01:21 id_rsa.pub
>       and can be copied with (just a direct copy from
>       //client/~/.ssh/id_rsa.pub to //server/~/.ssh/authorized_keys,
>       or append to preserve other keys):

>       ssh-copy-id username at host 

The ssh man page already says:

  The user creates his/her key pair by running ssh-keygen(1).  ...
  The user should then copy the public key to ~/.ssh/authorized_keys
  in his/her home directory on the remote machine.

A few more reinforcing "on the server host" and "on the client host"
sprinkled through the docs may be beneficial though.

>       b. the client provides its password 
> 
> 2. client side: 

I think the client side should be described first.  Since that is
where most users will start.  Otherwise before the cart is where the
horse is put.

>       b. verifying the server's public encryption key against the
>       lists of servers' public encryption keys in:
>          //client/etc/ssh/ssh_known_hosts and //client/~/.ssh/known_hosts 
>       you can copy and paste the key from
>       //server/etc/ssh/ssh_host_rsa_key.pub to
>       //client/~/.ssh/known_hosts, minus username at server at the end,
>       plus username at server at the beginning, with blanks as
>       separators. ssh-keygen -H to hash names.

I think that is very confusing.  I don't think it would survive most
humans trying to execute those instructions.

Better for most people is to verify the key fingerprint and let the
software handle manipulating the known hosts information for you.  I
know many ssh users who have used it (securely) for years and have
never known about /etc/ssh/ssh_host*.pub keys.  I wouldn't start a
user there.  But of course if at a site with many systems locally then
maintaining a site ssh_known_hosts by the site administrator makes
sense.  But again that isn't usually where people would start when
learning about ssh.  Site administrators are expected to have a
familiarity with the operating system.

> These few lines took me three frustating days of hard work, instead
> of two easy hours of learning, and I am still not sure I guessed
> rightly.

The format of man pages makes them good reference documents but not so
good user manuals.  This has long been argued.  HOWTO documents,
tutorials, user manuals, and FAQs really are better served in a format
more specific to their needs.  There are many ssh HOWTOs and tutorials
in the world.  I think what you are realy wanting is to have ssh
include the best of them with the ssh suite instead of having them be
independent works available elsewhere.  The problem is that someone
would actually need to do the work and it would be a lot of work.

There are a lot of good Getting Started style user manuals and HOWTOs
that are available on the web.  I would start there when trying to
learn how to use ssh.  They are a lot easier than the man pages.  And
if you try to change the man pages into a Gentle Introduction to ssh
then they lose their value as man pages.

> I believe that this attitude makes Linux lose market in favour of
> Windows servers.

OpenSSH really doesn't relate to Linux market share.  Natively OpenSSH
is part of OpenBSD which doesn't make use of Linux.  GNU/Linux based
systems use OpenSSH from OpenBSD as a port.  (And we are very
appreciative of it!)  Plus ssh runs on all kinds of operating system
platforms including MS-Windows.  Someone trying to use ssh on
MS-Windows could be just as frustrated and issue the same statement
there too!

> I still don't know if the encryption keys can be regenerated, and I
> am not sure that every line sent from client to server is
> authenticated, as it should. Also, I was surprised to see that I can
> not limit the number of tries for passwords. That config option is
> about logging of tries, not limiting them.

When I think of encryption keys in conjuction with ssh connections I
think of the session key used to encrypt the communication between the
two hosts.  This is handled automatically by ssh.  You don't need to
manually re-key the connection.  However you may do so with a newline
followed by "~R".  Terminal escape characters are documented in the
ssh(1) manual where it says:

     ~R      Request rekeying of the connection (only useful for SSH protocol
             version 2 and if the peer supports it).

The RekeyLimit is documented in the ssh_config(5) manual and says:

     RekeyLimit
             Specifies the maximum amount of data that may be transmitted
             before the session key is renegotiated.  The argument is the num-
             ber of bytes, with an optional suffix of ‘K’, ‘M’, or ‘G’ to
             indicate Kilobytes, Megabytes, or Gigabytes, respectively.  The
             default is between ‘1G’ and ‘4G’, depending on the cipher.  This
             option applies to protocol version 2 only.

But you are probably thinking about keys used for user authentication.
You can change those keys too.  Of course if you do then the previous
credentials are no longer valid and the new ones would need to be
installed.  I do this every so often as a matter of routine when I
move from one system to another during system upgrades.

Or you may be talking about host keys used for host identification.
Host keys can certainly be changed too but doing so will appear to
users the same as if the host were being attacked with a man in the
middle attack.  Therefore this type of change must be communicated
such that the user can expect it and manually deal with the change.
That would mean removing the old host key and verifying the
fingerprint of the new host.  Fortunately changing host keys isn't
often needed and so this isn't something routinely seen.

Bob