SecureBlackbox 16: Certificate Pinning and SecureBlackbox

Note: This article applies only to SecureBlackbox Legacy. For future development please consider using the latest version.

The problem

During the SSL/TLS session, in most cases, the server sends an X.509 certificate to the client. This certificate is aimed to prove that the client is connected to the legitimate server (and not a fraud).

The certificate validation procedure, on the client, verifies that the server's host name and the name in the presented certificate match. This requires that the server has acquired a valid CA-signed (we omit self-signed variants for lack of security and flexibility) certificate for the needed host name. So far, so good.

Trust can be given to the verification process due to the hierarchical nature of Public Key Infrastructure (PKI), which includes Certificate Authorities (CA) that issue and sign X.509 certificates for end entities and other authorities. The client trusts a certain (rather small) set of trusted root CAs, and then he or she trusts certificates that are issued or signed by those CAs.

The problem with the above scheme is that if you trust the CA, you also trust all of certificates issued by this CA and all sub-CAs and end entities for which the trusted root CA has issued certificates.

This scheme worked when identity validation rules imposed by CAs were strict and the number of CAs was small. Unfortunately, as the internet grew up, both state authorities and hackers started to abuse the architecture by creating fake certificates for very popular sites and performing MITM (Man In The Middle) attacks using those certificates. Such certificates would be validated, because technically they are valid. But these are not "real" certificates.

The solution

Here's where Certificate Pinning comes into play. Certificate Pinning is a procedure where the client holds a copy of the trusted information about the expected server certificate and uses this information as an additional protection step after regular certificate validation. The stored information can be a copy of the server's certificate, information about the certificate issuer, etc. -- this is what confirms that the certificate presented by the server is likely to be "real" and not forged in the deep cellars of the Russian KGB. For example, if you build a client-server system and you use only well-known CAs such as GlobalSign or VeriSign for obtaining server certificates, you can add the expected issuer names to the client software and compare those names with the name of the CA of the received certificate of the server.

Pinning can cover one or several certificates (when you store the hash of the server's certificates or the certificates themselves in the client software) or a wider group of certificates (when you store just the expected root CA name or intermediate CA names and trust all certificates if issued by those CAs).

Pinning one or several certificate is not very flexible because if the certificate expires or is revoked, you will need to immediately update all the installations of the client's software. Pinning a class of certificates seems to be a better idea.

Certificate Pinning and SecureBlackbox

In SecureBlackbox, you most likely validate certificates using the TElX509CertificateValidator class. This class lets you specify the certificates you trust explicitly (through the AddTrustedCertificates method) and certificates you know but still want to validate as usual (through the AddKnownCertificates method). By default, on Windows, the TElX509CertificateValidator class also makes use of the Windows built-in certificate stores with trusted and known certificates, but this use can be disabled by setting the UseSystemStorages property to false.

So to "pin" one or several certificates, you just add them to the list of trusted certificates using the AddTrustedCertificates method and disable the use of system storages via the UseSystemStorages property.

If you hold just the certificate hashes or other information (accepted CA names, etc.), the procedure is different. The TElX509CertificateValidator class has an OnAfterCertificateValidation event that you need to handle. In your event handler you must compare the information you have and trust with the information passed to the event handler and adjust the Validity and ValidityReason parameters if needed. This method can be used also if you have a fixed set of certificates -- in the event handler you can compare the past certificate with the certificate(s) that you have.

Limitations of this method

When you store certificate information in the client software you must pay special attention to ensure that your users obtain this client software from a legitimate source and that they get unaltered software. This includes the following and similar actions:

  • Signing the installation package (if possible) with your code signing certificate
  • Providing SHA hashes and OpenPGP signatures that correspond to the files on the site. (Note that if the attacker can replace your installation package on the site, they will also replace the hash or the signature.)
  • Sending clients the software burned on the CD-ROM or DVD-ROM disk.
  • Educating clients about the basics of secure computing is warmly welcomed.

Further readings

  1. Detailed article about certificate pinning on OWASP site
  2. Discussion about Certificate pinning on
  3. Pinning in the Firefox browser

We appreciate your feedback.  If you have any questions, comments, or suggestions about this article please contact our support team at