please decrypt your manuals

[Doru Georgescu]

> > 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.

This "possibility" is a degenerated case, and the manual does not deliver the information it should. It is like teaching Pythagoras' theorem for the case of a triangle with one side zero. I am sure that you do not need to be a good computer programmer to understand this. 

> 
> > 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.

The manual is incorrect by not delivering the information it should. It presents a degenerated case which is useless for the normal user. 

> 
> > 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.

In that case, the manual should distinguish between those multiple hosts. 

I am not going to discuss with you who is supposed to "take" and "add" that data, a human or a robot. 

> 
> 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?  

Sorry, but that's how it works. 

They
> would likely want to use ssh for that and that would be a
> bootstrapping problem.  

I use public transportation. Anyway, it is more difficult for someone to put together a SMS and a ssh connection for a man in the middle attack, rather than to wait for you to established a connection unprotected against such an attack. 

Better to check the hash
> fingerprint of the
> key in that case.
> 

I prefer to reserve that choice. I hope you don't propose that the paragraph I discuss in the sshd manual to be removed. 

> > 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.

Then, you should delete those files from the manual. They are used a lot there. What is the point with mentioning them, if they are not explained a little bit and if they are not actually necessary? 

> 
> > 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.

That is your choice. I have been already advised on this mail list to use keys instead of passwords and I also agree with this. 

> 
> > 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.

OK. 

> 
> >          + 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.

OK, so use plain English: ~/.ssh/id_rsa on client. The issue is, do you agree that the manuals should fully specify the files they refer, that is, including the machine on which they live, or not? 

> 
> >       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.

That only appears in one place in the ssh manual, and every file in the sshd manual can be found on both the server and client, and some files are actually used by both the ssh server and the ssh client software on one machine, such that the reader can not know about what functionality is the manual actually speaking and about what file precisely: the one on the server, or the one on the client? 

> 
> >       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.

As a programmer, I saw that the server is running first, and that the server is protected by authentication, so I started with the server. However, if this change makes it to the manual, I wholeheartedly agree with it. 

> 
> >       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.

It should be put into plain English. This is a sketchy note. 

> 
> 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.  

You caught me. 

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.

Still, the manual should make sense. And I am neither a site administrator nor a dumb user. I am a user who wants to use ssh a bit more securely. And some site administrators are also beginners, and they should also read a sane manual. 

> 
> > 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.

No sir, the manual is incorrect. In fact, it is illogically presented. There is a difference between being concise, organized as a reference, and being incoherent. I only concentrated on file specification because it is so glaringly obvious. 

> 
> > 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!

Right, I did not know this, but still the manual is part of the OpenSSH project. And, by the way, Cygwin is more a virtual Unix on Windows, then Windows. 

> 
> > 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.  

Yes, me too. Do the server ssh and client ssh software on one machine use the same key? 

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.

So they are dynamically generated all the time. 
But 
/etc/ssh/ssh_host_[rd]sa_key
/etc/ssh/ssh_host_[rd]sa_key.pub
are rather constant, so you lost me here. 

> 
> 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.

Not clear why. 

> 
> Or you may be talking about host keys used for host
> identification.

Probably these are in /etc/ssh/ssh_host_[rd]sa_key
/etc/ssh/ssh_host_[rd]sa_key.pub. 

Please show me where are these keys explained in the manuals. There should be a list of used keys, like the list of used files. 

> 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
>

Thank you for your answer. You certainly are more logical than the manuals. Please support my proposal to fully specify the location of files referred in the sshd manual. 

Doru