Navigating the world of pinned certificates in a decryption policy is time consuming and painful to troubleshoot. The issue is also that a lot of people have already invested in some time to figure things out. With these isolated pockets of development it’s hard to create a comprehensive list of host names that do not allow decryption to take place. This post is an extension on my previous one.

What is a pinned certificate?

A pinned certificate is where an application is expecting the presented certificate to come from a signed trusted authority. If the certificate is not presented from the correct authority, then a Man-in-the-Middle (MitM) attack is potentially occurring and rather than keeping the secure connection alive, the connection terminates.

From an end-user experience point of view this is typically not ideal as the certificate error handling within an application does not display well (i.e. the application might not work at all or only parts of the application work.)

Making a better end-user experience.

To help “smooth” out the end-user experience when a decryption policy is applied, I created a Github repository to help crowdsource all the collective knowledge out there. The simple data structure of the pinned certificate hostnames allow a lot of people to contribute their individual findings and ultimately support a larger eco-system.

Data structure

data/
  -> category/
     -> application-name/
        -> hostnames
        -> header

How to interpret this data structure:

• The data directory always remains constant.
• Applications can be divided into categories. For example, Starbucks could be classified under retail.
• Within each application-name directory are 2 files:
  • hostnames lists all the hostnames that are using pinned certificates.
  • header is a header file that contains a single line with the application name and the date it was last modified. Every time the hostnames file is updated, the last modified date needs to be updated.

Running the compile.py python script, it gathers the contents of all the header and hostnames files and outputs them into 2 separate files:

• compiled_with_comments.txt – this file contains a list of hostnames with the hostnames that are gathered from the directory names as well as the header file.
• compiled_without_comments.txt – this file contains an ordered list of hostnames only.
• file-validation.hash – this file contains a SHA256 hash of the 2 files above.

In each of these 2 text files, a header is added to indicate when it was last updated.

Cloudflare hosting

These 3 files are hosted at these locations:

• compiled_with_comments.txt
• compiled_without_comments.txt
• file-validation.hash

Contributions

If you’d like to contribute to the content, feel free to submit a pull request with your findings. In your findings, please include the following information:

• Vendor
• Application Name
• Application Category – ideally use one of the existing categories defined, but opent to creating a new one.
• Public URL (if applicable) that mentions pinned certificate hostnames or wildcard domains.
• (Optional/Preferred) Wireshark capture showing the TLS handshake failing and the Fatal error. Need to see the hostname being established in the handshake to make a correlation.