Feature: SSL Server Certificate Validator

  • Goal: Allow external code to perform SSL/TLS server certificates checks that go beyond OpenSSL validation.

  • Status: completed.

  • Version: v3.4

  • Developer: AlexRousskov

  • More: Not needed without SslBump.


Awaken by DigiNotar CA compromise, various web agents now try harder to validate SSL certificates (see 2011 squid-dev thread titled "SSL Bump Certificate Blacklist" for a good introduction). From user point of view, an SSL bumping Squid is the ultimate authority on server certificate validation, so we need to go beyond basic OpenSSL checks as well.

Various protocols and other validation approaches are floating around: CRLs, OCSP, SCVP, DNSSEC DANE, SSL Notaries, etc. There is no apparent winner at the moment so we are in a stage of local experimentation through trial-and-error. We have seriously considered implementing one of the above mentioned approaches in Squid, but it looks like it would be better to add support for a general validation helper instead, so that admins can experiment with different approaches.

Implementation sketch

The helper will be optionally consulted after an internal OpenSSL validation we do now, regardless of that validation results. The helper will receive:

  • the origin server certificate [chain],
  • the intended domain name, and
  • a list of OpenSSL validation errors (if any).

If the helper decides to honor an OpenSSL error or report another validation error(s), the helper will return:

  • the validation error name (see %err_name error page macro and %err_details logformat code),

  • error reason (%ssl_lib_error macro),

  • the offending certificate (%ssl_subject and %ssl_ca_name macros), and

  • the list of all other discovered errors

The returned information mimics what the internal OpenSSL-based validation code collects now. Returned errors, if any, will be fed to sslproxy_cert_error, triggering the existing SSL error processing code.

Helper responses will be cached to reduce validation performance burden (indexed by validation query parameters).

Helper communication protocol

This interface is similar to the SSL certificate generation interface.

Input line received from Squid:

request size [kv-pairs]

/!\ line refers to a logical input. body may contain \n characters so each line in this format is delimited by a 0x01 byte instead of the standard \n byte.

  • The type of action being requested. Presently the code cert_validate is the only request made.

  • Total size of the following request bytes taken by the key=pair parameters.

  • An optional list of key=value parameters separated by new lines. Supported parameters are:


    FQDN host name or the domain


    The SSL/TLS version


    The SSL/TLS cipher being used


    Server certificate. The ID is an index number for this certificate. This parameter exist as many as the server certificates are


    The openSSL certificate validation error. The ID is an index number for this error


    The ID of the certificate which caused error_name_ID

Example request:

0 cert_validate 1519 host=dmz.example-domain.com
cert_0=-----BEGIN CERTIFICATE-----

Result line sent back to Squid:

result size kv-pairs
  • One of the result codes:


    Success. Certificate validated.


    Success. Certificate not validated.


    Failure. The helper encountered a problem.

  • Total size of the following response bytes taken by the key=pair parameters.

  • A list of key=value parameters separated by new lines. The supported parameters are:


    A certificate send from helper to squid. The ID is an index number for this certificate


    The openSSL error name for the error ID


    A reason for the error ID


    The broken certificate. It can be one of the certificates sent by helper to squid or one of those sent by squid to helper

Example response message:

ERR 1444 cert_10=-----BEGIN CERTIFICATE-----
error_reason_0=Checked by Cert Validator

Design decision points

Why should the helper be consulted after OpenSSL validation? This allows the helper to use and possibly adjust OpenSSL-detected errors. We could add an squid.conf option to control consultation order, but we could not find a good use case to justify its overheads.

Why should the helper be consulted even if OpenSSL already declared a certificate invalid? OpenSSL may get it wrong. For example, its CRL might be out of date or simply not configured correctly. We could add an squid.conf option to control whether the helper is consulted after an OpenSSL-detected error, but since such errors should be rare, the option will likely add overheads to the common case without bringing any functionality advantages for the rare erronous case.


Features/SslServerCertValidator (last edited 2014-12-01 10:14:07 by AmosJeffries)