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:
- cd modules/mod_ssl_error
- apxs -cia /I../openssl/include /I../openssl/include/openssl mod_ssl_error.c (adapt the path to OpenSSL include files)
- add the directive 'LoadModule ssl_error_module modules/mod_ssl_error.so' to 'httpd.conf'
- apachectl stop
- 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.
- If nothing is specified, the server sends an error 403 to the browser.
- 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.
- 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:
- 2 unable to get issuer certificate
- 3 unable to get CRL
- 4 unable to decrypt certificate signature
- 5 unable to decrypt CRL signature
- 6 unable to decode issuer public key
- 7 certificate signature failure
- 8 CRL signature failure
- 9 certificate not yet valid
- 10 certificate has expired
- 11 CRL not yet valid
- 12 CRL has expired
- 13 error in certificate “not before” field
- 14 error in certificate “not after” field
- 15 error in CRL “last update” field
- 16 error in CRL “next update” field
- 17 out of memory
- 18 depth zero self signed certificate
- 19 self signed certificate in chain
- 20 unable to get issuer certificate locally
- 21 unable to verify leaf signature
- 22 certificate chain too long
- 23 certificate revoked
- 24 invalid certification authority
- 25 path length exceeded
- 26 invalid purpose
- 27 certificate not trusted
- 28 certificate rejected
- 29 subject issuer mismatch
- 30 “akid” skid mismatch
- 31 “akid” issuer serial mismatch
- 32 “keyusage” different from “certsign”
- 33 unable to get CRL issuer
- 34 unhandled critical extension
- 35 “keyusage” not for CRL signing
- 36 unhandled critical CRL extension
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
-
The code is ready to either forbid HTTPS URL, or to remap them to HTTP,
but it is is comment because somebody may want to redirect to a HTTPS URL
without certificate validation.
Maybe I could check the referrer, and map the URL to HTTP only if the referrer
is the same page we target ?
-
Maybe we could trap some other errors ?
Download
Download the source: mod_ssl_error.c