The CertChecker utility provides diagnostic information for TLS certificates. You can use this utility to assist with TLS configuration. It can be found in the product's bin or bin64 directory. To set the environment correctly for certchecker run:
. $COBDIR/bin/cobsetenv
As a minimum, you must specify at least a certificate and can optionally specify a private key and a CA collection.
The verification that CertChecker will perform depends on the input. If just a certificate is specified then CertChecker will check the validity of the certificate to make sure that it is properly formed, and in date, for example. CertChecker will also display warnings for issues such as weak encryption algorithms or extended key usage that is not suitable for TLS. The file specified for the -certfile option can also contain one or more untrusted intermediate certificates that can be used to help form a trust chain if a -cafile is specified. If the certificate file is encrypted, then the password can be specified with the -certpass option.
If a private key -keyfile is also specified then CertChecker will perform certificate checks and also check that the certificate and private key match and that the private key is correctly formed. If the private key is encrypted then the password can be specified with the -keypass option.
If the -cafile is specified then CertChecker will perform a full chain verification to check that it can form a trust chain from the certificates specified and the untrusted certificates in -certfile. It will also check the validity of each of the certificates in the chain.
The -host option can be used to check that the certificate includes the hostname or IP address specified in its Subject Alternative Names (SANs) or CN for a v1 certificate.
Use the following syntax. Note that you can place the parameters in any order:
certchecker -certfile filepath [-certpass passphrase] [-cafile filepath] [-keyfile filepath] [-keypass passphrase] [-host hostname] [-out outfile]
Check the validity of a certificate:
certchecker -certfile /path/to/cert
Verify a certificate and trust chain:
certchecker -certfile /path/to/cert -cafile /path/to/ca_collection
Verify that a certificate and a private key match:
certchecker -certfile /path/to/cert -keyfile /path/to/keyfile -keypass passphrase
Check that a certificate matches a private key and can be used with the hostname somehost.org:
certchecker -certfile /path/to/cert -keyfile path/to/key -keypass passphrase -host somehost.org
Check the validity of a certificate and write the output to myfile.txt:
certchecker -certfile /path/to/cert -out /path/to/myfile.txt
For an expired certificate, CertChecker will display the following message:
*Error: The certificate has expired: The notAfter date is before the current time.
Similarly for an expired intermediate or root certificate it will display the following error message along with the subject of the certificate:
Certificate: /C=GB/ST=State or Province/L=Locality or City/O=Organization/OU=Comms/CN=IntermediateTestCert1 *Error: The certificate has expired: The notAfter date is before the current time.
If a trust chain could not be established, CertChecker will display the following message with the subject of the certificate that is missing an issuer:
A problem was found with the following certificate: Certificate: /C=GB/ST=State or Province/L=Locality or City/O=Organization/OU=Comms/CN=IdTestCert *Error: The issuer certificate could not be found. This normally means the list of trusted certificates is incomplete or incorrect.
Similarly for an intermediate certificate with a missing issuer, note the different subject:
A problem was found with the following certificate: Certificate: /C=GB/ST=State or Province/L=Locality or City/O=Organization/OU=Comms/CN=IntermediateTestCert1 *Error: The certificate's issuer could not be found. This normally means collection of trusted certificates is not complete.
As a warning about a private key with inadequate security, CertChecker will display a message similar to the following:
*Warning: Security bits: 80 - It is recommended to use a key with at least 128 security bits. This is equivalent to a 3072 bit RSA key or a 256 bit EC key.
If the certificate and private key do not match, CertChecker will display the following error message:
Verifying that the Certificate and private key match. *Error: Verification Failed. Certificate and key do not match.
In the following example the CA certificate contains the extension:
X509v3 Name Constraints: Permitted: DNS:somedomain
which means that it can only issue certificates with SANs that match somedomain, but the certificate contains the SAN:
IP Address:127.0.0.1
which is outside of those constraints resulting in a verification error:
A problem was found with the following certificate: Certificate: /C=GB/ST=State or Province/L=Locality or City/O=Organization/OU=Comms/CN=IdTestCert *Error: A name constraint violation occurred in the permitted subtrees.
If a CA certificate contains the Basic Constraints extension with a pathlen, such as:
X509v3 Basic Constraints: critical CA:TRUE, pathlen:1
The pathlen specifies how many intermediate CAs can exist between the CA and the entity certificate. A pathlen of 0 means there can be no intermediates between the CA and the entity certificate, a pathlen of 1 means there can be 1 intermediate between the CA and the entity certificate and so on. If the path length constraint has been violated then CertChecker will display an error message similar to the following, which lists the CA whose pathlen was violated:
A problem was found with the following certificate: Certificate: /C=GB/ST=State or Province/L=Locality or City/O=Organization/OU=Comms/CN=RootTestCert *Error: The basicConstraints path-length parameter has been exceeded.
The following example explains the full output from CertChecker step by step. In this example, CertChecker is specified with an entity certificate and a valid collection of its intermediate certificates for the -certfile parameter. For the -cafile parameter, a CA certificate was specified that did not sign any of the intermediate certificates specified to -certfile. CertChecker will return a verification error highlighting that it failed to build the complete trust chain.
The following is the full input and output:
C:\TestCertificates>certchecker -certfile ./IDCertAndIntCollection.pem -cafile ./IncorrectRootCert.pem Copyright 2024 Company or one of its affiliates. CertChecker version 1.0.0 OpenSSL version 3.0.8 Loading certificate from file: C:\TestCertificates\IDCertAndIntCollection.pem Loading trusted certficates from file: C:\TestCertificates\IncorrectRootCert.pem Certificate: /C=GB/ST=State or Province/L=Locality or City/O=Organization/OU=Comms/CN=IDCert1708682316.351323 Signature algorithm: ecdsa-with-SHA256 Key type: EC prime256v1 256 bits Security bits: 128 SAN: 127.0.0.1 SAN: localhost SAN: 0000:0000:0000:0000:0000:0000:0000:0001 Verifying certificate and establishing the trust chain. A problem was found with the following certificate: Certificate: /C=GB/ST=State or Province/L=Locality or City/O=Organization/OU=Comms/CN=RootCert1708682315.313869 *Error: The certificate chain could be built up using the untrusted certificates but the root could not be found locally. Verification Failed. Errors: 1 Warnings: 0
From an Enterprise Developer command prompt, consider the following example which specifies a collection of untrusted certificates. In this case, an entity certificate and its intermediates and a root certificate:
C:\TestCertificates>certchecker -certfile ./IDCertAndIntCollection.pem -cafile ./IncorrectRootCert.pem
A similar message is displayed, including the CertChecker version and the OpenSSL API version being used:
Copyright 2024 Company or one of its affiliates. CertChecker version 1.0.0 OpenSSL version 3.0.8
Followed by details about the certificate/key files that it is trying to load. If it fails to load certificates from any of the files specified then it will terminate and give an error message:
Loading certificate from file: C:\TestCertificates\IDCertAndIntCollection.pem Loading trusted certficates from file: C:\TestCertificates\IncorrectRootCert.pem
Information about the entity certificate specified, including its subject, the signature algorithm used, key type, security bits which is a measure of how cryptographically secure the key is (a warning will be displayed if this value is too low), and the SANs included in the certificate:
Certificate: /C=GB/ST=State or Province/L=Locality or City/O=Organization/OU=Comms/CN=IDCert Signature algorithm: ecdsa-with-SHA256 Key type: EC prime256v1 256 bits Security bits: 128 SAN: 127.0.0.1 SAN: localhost SAN: 0000:0000:0000:0000:0000:0000:0000:0001
Following this, information will be given about the types of verification that was performed, this is dependent on the input specified. In this case, a -certfile and a -cafile, so the identity certificate will be checked for any warnings and a full trust chain verification will be performed using the trusted and untrusted certificates specified. If a private key had been specified, then CertChecker would also check that the identity certificate and private key match.
Verifying certificate and establishing the trust chain.
CertChecker will display an error if it cannot complete the trust chain if the trusted certificates specified in -cafile do not contain the correct root CA:
A problem was found with the following certificate: Certificate: /C=GB/ST=State or Province/L=Locality or City/O=Organization/OU=Comms/CN=RootCert1708682315.313869 *Error: The certificate chain could be built up using the untrusted certificates but the root could not be found locally. Verification Failed.
Finally, a summary of the total number of warnings and errors is displayed:
Errors: 1 Warnings: 0