Usable certificate validation

A research initiative to make TLS certificate validation usable.

What problems do we want to solve?

The system of working with (validating) TLS certificates:

• It is complicated, even a bit chaotic.
• There are multiple different tools to do the same thing.
• The tools are not unified (they work and behave differently).
• Yet certificate validation is important and frequent (e.g. TLS on the Internet).

So in short, what do we want to do?

Our goal is to simplify the ecosystem by consolidating the errors and their documentation and by explaining better what the validation errors mean. A similar (although much larger) effort was done by Mozilla for browser documentation in 2017.

In the ideal case, we aim for a unified, accessible, widely-used and academically interesting taxonomy of certificate validation errors and accompanying usable documentation. For every error, we aim to provide an example certificate, documentation from OpenSSL and other TLS libraries.

In the future, we plan the possibility of reorganization based on the other libraries (currently, the web is organized by OpenSSL), adding the error frequencies based on IP-wide scans and elaborating on the consequences of individual errors.

Local build

To build TLS clients, the development versions of the following libraries are required:

• OpenSSL
• GnuTLS (also requires libcurl)
• Botan, preferentially version 2
• mBedTLS
• OpenJDK

On Ubuntu 20.04 LTS or Fedora 33 you can install them using the appropriate of the following commands:

# Ubuntu 20.04
apt install libssl-dev libgnutls28-dev botan libbotan-2-dev libmbedtls-dev openjdk-16-jdk libcurl4-openssl-dev
# Fedora 33
dnf install openssl-devel gnutls-devel botan2-devel mbedtls-devel java-latest-openjdk-devel libcurl-devel

The necessary Python packages are locally installed by running make install. Building the certificate chains requires the following Python packages: setuptools, asn1tools and pycryptodomex. Running certificate validation further requires shyaml, yq, jq and pyYAML for parsing and manipulating YAML files.

The website is build using Jekyll. To develop locally, install Jekyll (e.g. according to this guide. Then run make local and see the website served at localhost:4000.

Authors

The project is developed at the Centre for Research on Cryptography and Security of Masaryk University in Brno, Czech Republic. The main contributors are listed in CONTRIBUTORS.md.