Looking Inside TLS Certificates

January 12, 2021

The Difficulty of Dealing with Certs

In the last decade, it has become increasingly important to secure websites and applications using HTTPS instead of HTTP. A GroundWork Monitor installation is no exception, so in GroundWork 8, using HTTPS to access the system is the default setup, and you can add TLS certificates to it that you generate or purchase. See Adding Certificates to HTTPS for more information on doing so. TLS (Transport Layer Security) is the successor to the now-obsolete SSL (Secure Sockets Layer), and TLS certificates support the companion protocol that uses modern cryptography to ensure your HTTPS data on the wire cannot be usefully seen by or altered by third parties.

When dealing with certificates, there are many technical questions about how to efficiently and effectively manage the security setup on a web application. While GroundWork does offer several ways to manage certs and system naming, it’s important at the start to make sure you have the right certificates to begin with. To that end, this post describes a small tool we have developed to assist in this process. Future blog posts and documentation pages will cover additional aspects of the security setup on GroundWork systems.

Supporting HTTPS on a web server requires the server be provided with a TLS Certificate used to authenticate a client connection to the server. This server certificate is often called a leaf cert. The validation your browser performs when it sees a leaf cert depends upon how that cert was generated. It can be self-signed (basically no trust chain), signed directly by a Certification Authority you control (Private CA), or signed by a public CA, typically with an intermediate certificate that is signed by a public CA root cert, creating a “trust chain” from the leaf cert, to the intermediate, to the root. Browsers will validate this chain and allow access, or will block access and warn the user something is amiss. The server you are connecting to has the private key as well as the certificate, and so can set up the required encrypted connection.

To make matters more complicated, the content of a cert file is generally an unreadable hash, like

-----BEGIN CERTIFICATE-----
MIIFtDCCA5gyAwIBAgIJANVLyuEvWDe0MA0GCSqGSIb3DQEBCwUAMGcxCzAJBgNV
BAYTAlVTMRMwEQYDVQQIDApDYWxpZm9ybmlhMQswCQYDVQQHDAJTRjENMAsGA1UE
... lots more lines like that ...
NAJzISwRnI4sFZXAn/vDZL5K2VPmBJTSUY+RBFESTtwqsA3j3Q8C/YA47nw0h/eL
oiMS1vxRCH9evqmVSwwSx40N6+HbFAJW
-----END CERTIFICATE-----

Proper Content for the Context?

Therein lies a problem. If you need to use a cert file, how can you be assured it has the proper content for the context in which you must apply it? You cannot just read it yourself. How do you know you are not accidentally using a file that also contains a private key that you must absolutely not reveal to anyone? In questions like those lies the utility of our small tool, which we call tlscerts.

tlscerts Tool

This tool decodes each certificate contained in the file you hand to it, and prints out the most useful data in a clean format, ignoring all the rest of the less relevant information it contains. You get to see only what you care about, quickly, with a minimum of fuss. There are other tools around (such as openssl) that can spill out lots more detail, but then you have to paw through it looking for the bits that will affect your immediate use.

To illustrate, here is the output from running the tool on a sample cert file.

% tlscerts client-cert.pem
OpenSSL version:  OpenSSL 1.0.2k-fips  26 Jan 2017
---------------------------------------------------------------------------
Certificate #1:
subject= 
    countryName               = US
issuer= 
    countryName               = US
    stateOrProvinceName       = CA
    organizationName          = Synadia
    organizationalUnitName    = nats.io
    commonName                = localhost
    emailAddress              = derek@nats.io
serial=90922D7F93AF95B3
SHA1 Fingerprint=AD:1A:72:E3:0E:8C:2F:7D:EB:5B:A3:EF:75:9A:3F:2C:B5:3C:76:28
notBefore=Oct 17 13:22:42 2019 GMT
notAfter=Oct 14 13:22:42 2029 GMT
X509v3 Subject Alternative Name: 
    DNS:localhost, IP Address:127.0.0.1, email:derek@nats.io
---------------------------------------------------------------------------

That cert contains minimal information about itself (only the country name), but more detail about the issuer. The fact the commonName is localhost means that this is a self-signed cert, which has limited usefulness outside of a testing or initial installation scenario. GroundWork Monitor starts up new installations with a self-signed cert, for example. There are considerations for assessing what constitutes a “good” certificate file in various contexts; for the moment, all we care about is that we can understand what is contained in the file under consideration.

Here’s the output when the tool is applied to a file obtained from a certain well-known public Certificate Authority, Let’s Encrypt:

% tlscerts myserver-letsencrypt.fullchain.pem
OpenSSL version:  OpenSSL 1.0.2k-fips  26 Jan 2017
---------------------------------------------------------------------------
Certificate #1:
subject= 
    commonName                = myserver.mydomain.com
issuer= 
    countryName               = US
    organizationName          = Let's Encrypt
    commonName                = Let's Encrypt Authority X3
serial=04676B4E097A6E817428E6676F6E4E6F95E3
SHA1 Fingerprint=FF:D3:43:9A:C9:56:E5:48:DC:19:60:07:EB:1A:3B:61:2C:4A:6B:E1
notBefore=May  8 17:40:38 2020 GMT
notAfter=Aug  6 17:40:38 2020 GMT
X509v3 Subject Alternative Name: 
    DNS:myserver.mydomain.com
---------------------------------------------------------------------------
Certificate #2:
subject= 
    countryName               = US
    organizationName          = Let's Encrypt
    commonName                = Let's Encrypt Authority X3
issuer= 
    organizationName          = Digital Signature Trust Co.
    commonName                = DST Root CA X3
serial=0A0143420000015395736A0B65FCA708
SHA1 Fingerprint=E6:A3:B4:5B:06:2D:05:9B:33:82:28:7D:19:6E:FE:97:D5:95:6C:CB
notBefore=Mar 17 16:40:46 2016 GMT
notAfter=Mar 17 16:40:46 2021 GMT
---------------------------------------------------------------------------

That file contains a leaf cert, issued for the myserver.mydomain.com machine, as well as an intermediate cert that links the leaf cert to the root cert (which is not provided in this file, nor should it be). The visible linkage between the leaf cert and the intermediate cert is revealed by the fact the issuer commonName in the first (leaf) cert is the same as the commonName in the subject of the second (intermediate) cert. A more-complex, technical linkage between the two certs is that the leaf cert is digitally signed using the intermediate cert, and that this signature can be verified (through some complicated calculations the browser or other tools do). The tlscerts tool does not show that detail because it’s not relevant for identifying what’s in the file at hand. The root cert is to be found elsewhere, and is typically already available in the browser or other tools. It is identified by the commonName of the issuer of the intermediate cert, namely “DST Root CA X3", and at a technical level by the fact that the intermediate cert is verifiably signed using the root cert.

What would we have seen if we had accidentally handed the tool a file containing a private key instead of the public cert we wanted to use?

% tlscerts myserver-letsencrypt.privkey.pem
OpenSSL version:  OpenSSL 1.0.2k-fips  26 Jan 2017
---------------------------------------------------------------------------
NOTICE:  This file contains an unidentified private key.
---------------------------------------------------------------------------

That’s clear enough. The tool doesn’t spill the details because they are only a bunch of mathematical objects, and not anything like an organization name you might immediately recognize. If you care about that detail, you will need to decode the file using other tools. That said, the simple notion that you have a private key in the file is sufficient for most practical usage, and allows you to use this file in the appropriate context, for example loading it onto your GroundWork server along with its corresponding certificate.

The tlscerts tool is not bundled into GroundWork 8, however it can be downloaded from the GroundWork Support site, see the Downloads page.

To run it, you will need to have your operating system’s copies of both Perl and OpenSSL installed.

GroundWork recommends you use this tool to check any cert files you intend to install for use with GroundWork Monitor, so you can have some confidence the files contain what you think they contain. At present, this identification is not a full validation of the file content, and we may extend the tool to provide more of that in the future. Even so, in its current form it can go a long way in making sure you are not installing the wrong certs. We’ll be using it in examples as we expand this series of blog posts.

Thanks for reading our Blog.