mod_ssl_error: Certificate validation error trapping

In case a SSL connection fails because a certificate is expired, or a CRL is unavailable, etc., the browser receives a SSL error that results in a cryptic technical error displayed to the user - sometimes only an error number like in Firefox.

This module allows, in such a situation, to redirect the browser to a page with the specific error message ("Your certificate is expired", "We cannot check the validity of the certificate - retry later", etc.).

This module was developed by Approach Belgium for the Belgian Government, and provided for free to everybody.

This module should be (I hope) incorporated in future version of mod_ssl.

Requirements

This module works with Apache 2.2.x, with the patch to allow it.

Usage

Module installation

Install mod_ssl_error as Dynamic Shared Object:
  1. cd modules/mod_ssl_error
  2. apxs -cia /I../openssl/include /I../openssl/include/openssl mod_ssl_error.c (adapt the path to OpenSSL include files)
  3. add the directive 'LoadModule ssl_error_module modules/mod_ssl_error.so' to 'httpd.conf'
  4. apachectl stop
  5. apachectl start

Module loading

To enable this feature, the module must be loaded:
LoadModule ssl_error_module modules/mod_ssl_error.so

Error page customization

All directives can be used at the server, location, or directory level.
  1. If nothing is specified, the server sends an error 403 to the browser.

  2. If a default URL is specified, the browser is redirected to that page
    <IfModule mod_ssl_error.c>
    SSL_Error_DefaultURL "http://.../error/ssl_valid.html"
    </IfModule>
    The browser is redirected to http:/@@/.../error/ssl_valid.html?errorNb=XXX&serial=YYY&dn=ZZZ, where XXX is the error number given by the OpenSSL library, YYY is the certificate serial number, ZZZ is the certificate distinguished name.
    A script on the server could thus get the exact error message from the variable/header “error”, and customize the page displayed to the user.

  3. If a specific error is specified, the browser is redirected to that page
    <IfModule mod_ssl_error.c>
    SSL_Error_URL 10 "/error/expired.html"
    SSL_Error_URL 12 "/error/crl_expired.html"
    SSL_Error_URL 23 "/error/revoked.html"
    </IfModule>
    The certificate serial number and distinguished name are included as above.
    Valid errors are:

Important remarks

The URL provided for the redirection should normally use the HTTP protocol, not HTTPS, otherwise it may provoke another SSL error, resulting in a redirection, ... thus an infinite loop. The URL can be relative; in this case, a HTTP connection is used.

To do

Download

Download the source: mod_ssl_error.c