Secure Sockets Layer (SSL) directives

SSLClientAuthVerify directive

The SSLClientAuthVerify directive controls whether IBM HTTP Server fails requests when a client certificate is received, but it fails validation (for example, it is expired or revoked).

Use this directive with SSLClientAuth Optional Noverify to provide a user friendly web page, instead of the default browser error message.

If you configure a virtual host with SSLClientAuth Optional Noverify, an SSL connection can be established when a client certificate is received, but it fails validation (for example, it is expired or revoked).

Use this directive in a context such as Location or Directory to fail requests that are received on that connection with a specific error code, or handled normally by setting OFF.

By providing a custom error document for that status, the administrator can control the page that is presented to the user, for example, to tell the user their certificate is invalid and provide further instructions.

If the error document is an internal redirect to another URL in the same virtual host, you must ensure that URL has SSLClientAuthVerify OFF in its context so it does not immediately fail, as well. An example of this scenario follows.

The specified status code must be a response status that is valid in HTTP and known to IBM HTTP Server. The values are between 100 and 599, and are typically defined in an RFC or standards proposal. If you are unsure, try a status code in a test configuration and use apachectl -t to see if it is valid. Other unused codes that are valid and would be good choices include: 418, 419, 420, and 421.

Because the client certificate was invalid, the error document will not have any of the environment variables available that would contain information about the client certificate. The cause of the client certificate validation failure is available in the SSL_LAST_VALIDATION_ERROR environment variable . The variable could be GSKVAL_ERROR_REVOKED_CERT or GSKVAL_ERROR_CERT_EXPIRED. If the certificate has multiple validation problems, the reported cause is often GSKVAL_ERROR_CA_MISSING_CRITICAL_BASIC_CONSTRAINT.

Each time a client certificate validation fails, two messages are logged in the error log at loglevel Error. The second message includes the cause, for example:

[Tue Jun 08 08:54:25 2010] [error] [client 9.37.243.128] [9e44c28] [731] SSL0208E: SSL Handshake Failed, 
   Certificate validation error. [9.37.243.128:60347 -> 9.37.243.67:443] [08:54:25.000223331]
[Tue Jun 08 08:54:25 2010] [error] [client 9.37.243.128] [9e44c28] [731] Certificate validation error 
   during handshake, last PKIX/RFC3280 certificate validation error was 
   GSKVAL_ERROR_CA_MISSING_CRITICAL_BASIC_CONSTRAINT 
   [9.37.243.128:60347 -> 9.37.243.67:443] [08:54:25.000223331]

Example configuration:

<VirtualHost *:443
SSLClientAuth Optional Noverify
<Location />
SSLClientAuthVerify 419
</Location>
ErrorDocument 419 /error419.html
<Location /error419.html>
SSLClientAuthVerify OFF
</Location>
</VirtualHost>

<VirtualHost *:443> 
   SSLEnable 
   SSLProtocolDisable TLSv10
   # Any other directives ...
</VirtualHost>

%{SSL_UNKNOWNREVOCATION_SUBJECT}e

%{ENV:SSL_UNKNOWNREVOCATION_SUBJECT}