please decrypt your manuals

[Doru Georgescu]

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

Please, help me understand what do you mean by "I understand your point", and "I don't think the documentation is incorrect". You mean, the manual shows good humour by explaining how to connect safely, using keys, from one computer to itself? I refer to man sshd, where the SSH_KNOWN_HOSTS FILE FORMAT section 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. 

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

I timidly propose to specify, for each file, the machine on which it lives, this way: //client/etc/ssh/ssh_host_key.pub and //server/etc/ssh/ssh_known_hosts. The fact that ssh and sshd are always installed together, and files for both client and server are present on each machine, only increases the manual reader's confusion. 

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

I referred to a short scheme about how ssh files are actually used and managed by the user. I tried to begin the creation of such a scheme in my paragraph II, which is no longer here ... ;-). 

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

Are you sure that those RFC's explain whether /etc/ssh/ssh_known_hosts is used by the client or by the server? I didn't find this name in those RFC's, but maybe I can deduce somehow what ssh_known_hosts is doing if I read them. 

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

I thought about ssh as a part of Linux, but ssh manuals are part of the ssh product, and I expected its developers to care about the quality of their product. 

Can I access dos with ssh through cygwin? 

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

I started to propose small improvements. If we work out where do those files actually reside, I hope we will pass through the few lines in my paragaph II, sometimes. 

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

I should improve my paragraph II, of course. I hope I will find help for this. 

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

I was referring to the keys memorized in the /etc/ssh/ssh_host_dsa_key.pub and /etc/ssh/ssh_host_rsa_key.pub files. I suspect that they contain public keys used by both ssh client and server to encrypt their messages under protocol 2. 

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

But there is no way to authenticate messages from server to client! This should be in RFC, anyway. 

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

Right, thanks for this. I'll use the keys ... :) 

> Kind regards

> //Peter

Thanks, maybe I'll untie this node. 

Doru