[Bug 63342] New: SSLUserName directive documentation inaccurate

[bu...@apache.org]

https://bz.apache.org/bugzilla/show_bug.cgi?id=63342

            Bug ID: 63342
           Summary: SSLUserName directive documentation inaccurate
           Product: Apache httpd-2
           Version: 2.4.25
          Hardware: PC
            Status: NEW
          Severity: normal
          Priority: P2
         Component: Documentation
          Assignee: docs@httpd.apache.org
          Reporter: tlhackque@yahoo.com
  Target Milestone: ---

See: https://httpd.apache.org/docs/2.4/mod/mod_ssl.html#sslusername, where we
find: "Note that this directive has no effect if the FakeBasicAuth option is
used "

This is not quite true, and confusing.

By experiment:
 When SSLUserName IS specified with FakeBasicAuth, REMOTE_USER IS set.
 When SSLUserName is NOT specified with FakeBasicAuth, REMOTE_USER is NOT set.

So it's not true that the directive "has no effect".  It has no effect on
whether the access is AUTHORIZED by HTTPD.  But it DOES effect REMOTE_USER.

https://httpd.apache.org/docs/trunk/mod/mod_ssl.html#sslusername is worse:
"When the FakeBasicAuth option is enabled, this directive instead controls the
value of the username embedded within the basic authentication header."

This may be true internally, but is not helpful for an administrator.  The
"basic authentication header" comes from the client, not from HTTPD.  So no
directive can control that.  

Better might be "replaces the value of the username..." or "supplies the
username field of the internally generated 'fake' Authorization header" - but
that still specifies "what", without "why".  

I haven't run the experiment, but if a module such as FCGID passes on the
Authorization header to a script, or if it is consulted by a mod_rewrite rule -
what would expr req('HTTP:Authorization') return? base64(
"SSLUsername:password" )? Cleartext?  Or the null string?

And, SSLOptions's description of FakeBasicAuth says:
"When this option is enabled, the Subject Distinguished Name (DN) of the Client
X509 Certificate is translated into a HTTP Basic Authorization username."

In trunk, it also includes: "The optional SSLUserName directive can be used to
specify which part of the certificate Subject is embedded in the username. "

That doesn't talk about a "field in the Apache request object".  (Which is a
good thing - request objects matter to developers, not, usually, users.)

The trunk version should probably read:
"The optional SSLUserName directive can be used to specify which part of the
certificate Subject (IF ANY) is EXPOSED AS the username."

Suggest:

When the FakeBasicAuth option or BasicFakeAuth directive is in effect, the
"username" extracted from the certificate and used for authentication is only
visible to other modules if SSLUserName is specified.  Thus, configuration
rules and CGI scripts that rely on REMOTE_USER (or other productions from
username) require SSLUserName to be specified.

--

This matters because CGI scripts may rely on REMOTE_USER to identify the
client, after the connection has been accepted by HTTPD.  (Both legacy, and
because when either a certificate or a password is accepted (SSLVerify
optional), it is convenient to look in only one place for the username.)

Also, the reference to FakeBasicAuth should also mention AuthBasicFake - as
should any other generic reference to FakeBasicAuth.

-- 
You are receiving this mail because:
You are the assignee for the bug.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org