Bug 63342 - SSLUserName directive documentation inaccurate
Summary: SSLUserName directive documentation inaccurate
Status: NEW
Alias: None
Product: Apache httpd-2
Classification: Unclassified
Component: Documentation (show other bugs)
Version: 2.4.25
Hardware: PC
: P2 normal (vote)
Target Milestone: ---
Assignee: HTTP Server Documentation List
Depends on:
Reported: 2019-04-12 15:23 UTC by tlhackque
Modified: 2019-04-12 15:23 UTC (History)
0 users


Note You need to log in before you can comment on or make changes to this bug.
Description tlhackque 2019-04-12 15:23:45 UTC
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."


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.