please decrypt your manuals

[Peter Stuge]

OpenSSH documentation might assume strong familiarity with UNIX
systems. I'm not sure that this is a bad thing.


Doru Georgescu wrote:
> I. most of ssh manual and all sshd manual present server and client
> as one machine, called host. All files mentioned are placed on one
> machine. This is incorrect, and makes the explanation unclear.

I understand your point, but I don't think the documentation is
incorrect. Every system is potentially both a server and a client,
and there is only one set of manual pages.

Although I think wording in OpenSSH man pages is already pretty good,
I'm sure that patches which improve wording even further will be most
welcome.


> II. a general presentation of ssh workings is missing,

This is completely out of scope for OpenSSH IMO. OpenSSH is one of
many implementations of the protocol.

How SSH works, in general, is very well described in the SSH RFCs.
Please read RFC 4250 through 4254 for more info, at least RFC 4251.


> both encrypt their messages with the encryption keys in: 
> both can memorize known hosts' public encryption keys in
> /etc/ssh/ssh_known_hosts and ~/.ssh/known_hosts 
> only the server is protected through authentication.

Check out the RFCs, then go back to the OpenSSH manual to learn more
about how specifically OpenSSH maps SSH onto UNIX systems.


> 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. I believe that this attitude makes Linux lose market in
> favour of Windows servers.

OpenSSH has nothing to do with Linux, really.

And OpenSSH could not care less about the market of Linux.

Finally, OpenSSH runs also on Windows.

That said, I agree with you that open source requires ownership of
one's problems. If you want to solve a problem with open source tools
then you really need to understand the problem, and then the solution
will be easy to find. Or you can hire a consultant to help.

I find that Windows servers often do not even allow me to find out
what the problem actually is, so even though I am fairly experienced
with computers all my methods fail, because I get no data that I can
try to use to find a solution. I can of course hire Microsoft, then
they will gladly send someone to help me, maybe even without
explaining what the problem was.


> I hope that the author of sshd manual will correct his writing.

That's really not very nice. I hope that YOU will correct the
writing - if you think you can do it better! Please do! It would be
fantastic to have even better documentation.

Remember that the OpenSSH project is not the work of one single
author, but the work of many people working together. It is very easy
to get involved - just send an improvement of current state to the
mailing list.


> Please verify my "discoveries" above and publish them somewhere.

Please ask specific questions. Noone will explain every single detail
of OpenSSH to you - but I think many will be happy to give quick
answers to straightforward questions.


> Less important: 
> I still don't know if the encryption keys can be regenerated,

Which encryption keys? There can be many keys involved already in
SSH, and further keys introduced by the OpenSSH implementation.
Please have a look at the protocol description, and ask a more
specific question.


> and I am not sure that every line sent from client to server is
> authenticated, as it should.

Again, have a look at the protocol, to learn more about the format of
bytes between client and server. All data uses encryption and message
authentication.


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

sshd is not likely the only service in your system which accepts
password authentication, so it is clearly not the appropriate entity
to implement your security policy. Something else, more appropriate,
would be PAM, but there are also other possibilities.

In any case, I strongly recommend against using passwords for
authentication at all. Create keys for your users instead.


Kind regards

//Peter