UsePAM documentation clarification in sshd_config.

[Peter Bisroev]

Dear OpenSSH Portable developers,

Firstly, thank you for the fantastic port and the effort you take to
maintain it!

I have a minor suggestion regarding the documentation of UsePAM in
sshd_config. Currently it has a comment that states that 'Depending on
your PAM configuration, PAM authentication via
ChallengeResponseAuthentication may bypass the setting of
"PermitRootLogin without-password".'

Due to a recent project, I needed to take a look at this in a bit more
depth, to see under what circumstances this bypass of "PermitRootLogin
without-password" can happen. The first thing that jumps to mind is
someone misconfiguring PAM and using pam_permit.so in the wrong place.
Of course, there could be a lot more subtle configuration issues that
can lead to the same situation.

So while looking through the code in the master branch of portable
OpenSSH, in auth-pam.c in function sshpam_query(), during the check
for PAM_SUCCESS there is a check for 'options.permit_root_login !=
PERMIT_YES' and if that fails, a fatal error message is logged
"Internal error: PAM auth succeeded when it should have failed", and
the connection is closed. Please see the reference below:
* https://anongit.mindrot.org/openssh.git/tree/auth-pam.c#n768

These lines were added during commit for bug fix #971 in January 2005,
as can be seen in the commit <63e6b0f4>, referenced below:
* https://anongit.mindrot.org/openssh.git/commit/?id=36a3d60347f23528695e550317d5ba6d63e6b0f4

The documentation comment in sshd_config for UsePAM was added in
commit <90407053>, dated May 2004, referenced below:
* https://anongit.mindrot.org/openssh.git/commit/sshd_config?id=701d0514ee3ffc5e8fde36bb0559709490407053

And is still present in the master branch of sshd_config:
* https://anongit.mindrot.org/openssh.git/tree/sshd_config

Unless I am missing something (and that could well be the case :)),
that check in auth-pam.c, should only allow PAM auth to succeed if
PasswordAuthentication for root is enabled, otherwise it should always
fail. Just to be sure, I have verified this using the following
*broken* lines in /etc/pam.d/sshd:
    auth    [default=ignore success=1] pam_succeed_if.so uid != 0
    auth    sufficient pam_permit.so

These configuration changes do result in the expected line from
auth-pam.c in the logs. So if my understanding of this behavior is
correct, would it be beneficial for other users to document that
behavior in sshd_config and the associated man page for option UsePAM?
Maybe remove the bypass of "PermitRootLogin without-password"
statement in order to avoid confusion?

It would also be helpful to mention the specific error line that can
appear in the logs in order to explain to the user that the problem is
not with OpenSSH itself but with the PAM configuration.

Of course if I am missing something and my assumptions are incorrect,
under what circumstances can the behavior describe in sshd_config
manifest itself? Should a sample PAM configuration that can lead to
such behavior be documented?

What are your thoughts?

Thank you!
--peter