certdiff

This tool allows you to compare the properties of a given certificate against the prescribed properties from the configuration file and report on any differences.

Please see the man page for details.

If you have questions, comments, or suggestions, please contact the author at jschauma@netmeister.org or at @jschauma.

Examples

Example Configuration File

The following example configuration file mandates that

all certificates have Certificate Transparency logs
valid domains for Subject and SANs must end in 'example.com' or 'example.net'
ECDSA certificates must use a key length of at least 386 bits
RSA certificates must use a key length of at least 2048 bits
certificates must not be valid for more than 180 days
certificates must not have more than 20 SANs
of the SANs and the Subject, there may be at most 4 wildcard names
certificates must be signed using SHA256-RSA
certificates must chain to either the DigiCert EV Root (by way of sha1 pin), or to the VeriSign G5 root (by way of the root serial number)

certdiff(1) will use the the default trusted CA bundle from /etc/pki/tls/cert.pem, since 'cabundle' is not specified in the configuration file.

ct = true 
domains = example.com, example.net
keyLengthECDSA = 386
keyLengthRSA = 2048
maxValidity = 180
maxSANs = 20
maxWildcards = 4

# We only accept certificates issued by the
# DigiCert High Assurance EV Root CA, identified by
# this sha1 pin:
# curl https://www.digicert.com/CACerts/DigiCertHighAssuranceEVRootCA.crt | \
#     openssl x509 -inform DER -pubkey -noout                             | \
#     openssl rsa -pubin -outform DER 2>/dev/null                         | \
#     openssl dgst -sha1 -binary                                          | \
#     openssl enc -base64
pins = sha1/gzF+YoVCU9bXeDGQ7JGQVumRueM=

# Oh, wait, we changed our mind, we also accept
# VeriSign Class 3 Public Primary CA - G5
rootSerials = 18DAD19E267DE8BB4A2158CDCC6B3B4A

sigAlgs = SHA256-RSA

Checking a local certificate

A single stand-alone certificate will likely fail some of the checks, since the certificate cannot be validated without intermediates:

$ certdiff -c /tmp/certdiffrc < cert.pem
80205c2c70ab32906cea79d6b6e790f8 'foo.bar.example.com' (leaf): Incomplete chain!
80205c2c70ab32906cea79d6b6e790f8 'foo.bar.example.com' (leaf): validity > maxValidity (730 > 180)
80205c2c70ab32906cea79d6b6e790f8 'foo.bar.example.com' (leaf): no longer valid
80205c2c70ab32906cea79d6b6e790f8 'foo.bar.example.com' (leaf): Unable to verify validity: x509: certificate signed by unknown authority
80205c2c70ab32906cea79d6b6e790f8 'foo.bar.example.com' (leaf): no valid pin nor root serial found.
$

In addition, this certificate has a validity longer than what we require and has already expired.

Checking a remote service

You can also use certdiff(1) to check the certificate chain provided by a remote service directly:

$ certdiff -s www.yahoo.com
1c25430ed0a602e8cc3a977b0539cce5 'www.yahoo.com' (leaf): too many wildcards (13 > 4).
1c25430ed0a602e8cc3a977b0539cce5 'www.yahoo.com' (leaf): validity > maxValidity (730 > 180)
1c25430ed0a602e8cc3a977b0539cce5 'www.yahoo.com' (leaf): too many SANs (65 > 20)
$

Listing certificate properties

certdiff(1) also allows you to just report certificate properties. That is very similar to running

openssl x509 -text -noout

but adds certificate pins, the full chain, and some other details: