'certstate' is a simple helper tool to monitor the validity of public key certificates (digital certificate, SSL/TLS certificate, X.509 certificate). It grabs the certificate, checks the OCSP state (staple, service), checks the CRL state (all lists), and prints a subset of the collected data as plain text. It's up to you, to monitor the data and generate an alarm if the certificate has become invalid or threatens to become invalid.
$ ./certstate -help
Program:
Name : certstate
Release : v0.7.0 - 2019/11/04
Purpose : monitor public key certificate
Info : Prints public key certificate details offered by TLS service.
What does this tool do?
- connects to a TLS service and grabs the public key certificate
- if certificate contains OCSP stapling data: parses the data
- if requested: validates leaf certificate against OCSP services
- if requested: validates leaf certificate against CRLs
- prints out a subset (the important part) of the collected data
Possible return values:
- 0 = OK
- >0 = NOK
How to check the validity of a public key certificate?
- assess 'NotBefore' value of leaf certificate
- assess 'NotAfter' value of leaf certificate
- assess 'CertificateStatus' values of OCSP responses
- assess 'CertificateStatus' values of CRL validations
Possible certificate 'KeyUsage' values (binary encoded):
- 000000001 = DigitalSignature
- 000000010 = ContentCommitment
- 000000100 = KeyEncipherment
- 000001000 = DataEncipherment
- 000010000 = KeyAgreement
- 000100000 = CertSign
- 001000000 = CRLSign
- 010000000 = EncipherOnly
- 100000000 = DecipherOnly
Possible certificate 'ExtKeyUsage' values:
- Any
- ServerAuth
- ClientAuth
- CodeSigning
- EmailProtection
- IPSECEndSystem
- IPSECTunnel
- IPSECUser
- TimeStamping
- OCSPSigning
- MicrosoftServerGatedCrypto
- NetscapeServerGatedCrypto
- MicrosoftCommercialCodeSigning
- MicrosoftKernelCodeSigning
Possible OCSP 'CertificateStatus' values:
- Good
- Revoked
- Unknown
- ServerFailed
Possible OCSP 'RevocationReason' values:
- 0 = Unspecified
- 1 = KeyCompromise
- 2 = CACompromise
- 3 = AffiliationChanged
- 4 = Superseded
- 5 = CessationOfOperation
- 6 = CertificateHold
- 8 = RemoveFromCRL
- 9 = PrivilegeWithdrawn
- 10 = AACompromise
Possible CRL 'CertificateStatus' values:
- Good
- Revoked
Possible CRL 'RevocationReason' values:
- Id=ExtensionId, Value=ExtensionValue
Usage:
certstate [-timeout=sec] [-verbose] [-ocsp] [-crl] address:port
Examples:
certstate -ocsp example.com:443
certstate -timeout=7 example.com:443
certstate -verbose example.com:443
certstate -crl example.com:443
Options:
-crl
validates leaf certificate against Certificate Revokation Lists (CRL)
-ocsp
validates leaf certificate against Online Certificate Status Protocol services (OCSP)
-timeout int
communication timeout in seconds (default 19)
-verbose
adds fingerprints, PEM certificates, PEM OCSP responses, PEM CRLs
Arguments:
address:port
address (name/ip) and port of TLS service
Remarks:
- The timeout setting will be used:
+ as connection timeout when requesting the TLS service
+ as overall timeout when requesting an OCSP service
+ as overall timeout when fetching a CRL
- empty or invalid values are not printed
Reference output:
GENERAL INFORMATION ...
Command : ./certstate -ocsp -crl example.com:443
Service : example.com:443
Timeout : 19
Verbose : false
OCSP : true
CRL : true
Time : 2019-11-04 11:10:03 +0100 CET
TLS CONNECTION DETAILS ...
Version : 772 (0x0304, VersionTLS13)
HandshakeComplete : true
CipherSuite : 4866 (0x1302, TLS_AES_256_GCM_SHA384)
NETWORK ADDRESS DETAILS ...
LocalAddr : 192.168.178.55:57652
LocalHost : Klauss-MBP.fritz.box
RemoteAddr : 93.184.216.34:443
CERTIFICATE DETAILS ...
SignatureAlgorithm : SHA256-RSA
PublicKeyAlgorithm : RSA
Version : 3
SerialNumber : 21020869104500376438182461249190639870
Subject : CN=www.example.org,OU=Technology,O=Internet Corporation for Assigned Names and Numbers,L=Los Angeles,ST=California,C=US
Issuer : CN=DigiCert SHA2 Secure Server CA,O=DigiCert Inc,C=US
NotBefore : 2018-11-28 00:00:00 +0000 UTC (valid for 735 days)
NotAfter : 2020-12-02 12:00:00 +0000 UTC (expires in 394 days)
KeyUsage : 5 (101, KeyEncipherment, DigitalSignature)
ExtKeyUsage : ServerAuth, ClientAuth
IsCA : false
DNSNames : www.example.org, example.com, example.edu, example.net, example.org, www.example.com, www.example.edu, www.example.net
OCSPServer : http://ocsp.digicert.com
IssuingCertificateURL : http://cacerts.digicert.com/DigiCertSHA2SecureServerCA.crt
CRLDistributionPoints : http://crl3.digicert.com/ssca-sha2-g6.crl, http://crl4.digicert.com/ssca-sha2-g6.crl
PolicyIdentifiers : 2.16.840.1.114412.1.1, 2.23.140.1.2.2 (organization validation)
SubjectKeyId : 66986202e00991a7d9e336fb76c6b0bfa16da7be
AuthorityKeyId : 0f80611c823161d52f28e78d4638b42ce1c6d9e2
CERTIFICATE DETAILS ...
SignatureAlgorithm : SHA256-RSA
PublicKeyAlgorithm : RSA
Version : 3
SerialNumber : 2646203786665923649276728595390119057
Subject : CN=DigiCert SHA2 Secure Server CA,O=DigiCert Inc,C=US
Issuer : CN=DigiCert Global Root CA,OU=www.digicert.com,O=DigiCert Inc,C=US
NotBefore : 2013-03-08 12:00:00 +0000 UTC (valid for 3652 days)
NotAfter : 2023-03-08 12:00:00 +0000 UTC (expires in 1220 days)
KeyUsage : 97 (1100001, CRLSign, CertSign, DigitalSignature)
IsCA : true
OCSPServer : http://ocsp.digicert.com
CRLDistributionPoints : http://crl3.digicert.com/DigiCertGlobalRootCA.crl, http://crl4.digicert.com/DigiCertGlobalRootCA.crl
PolicyIdentifiers : 2.5.29.32.0
SubjectKeyId : 0f80611c823161d52f28e78d4638b42ce1c6d9e2
AuthorityKeyId : 03de503556d14cbb66f0a3e21b1bc397b23dd155
CERTIFICATE DETAILS ...
SignatureAlgorithm : SHA1-RSA
PublicKeyAlgorithm : RSA
Version : 3
SerialNumber : 10944719598952040374951832963794454346
Subject : CN=DigiCert Global Root CA,OU=www.digicert.com,O=DigiCert Inc,C=US
Issuer : CN=DigiCert Global Root CA,OU=www.digicert.com,O=DigiCert Inc,C=US
NotBefore : 2006-11-10 00:00:00 +0000 UTC (valid for 9131 days)
NotAfter : 2031-11-10 00:00:00 +0000 UTC (expires in 4388 days)
KeyUsage : 97 (1100001, CRLSign, CertSign, DigitalSignature)
IsCA : true
SubjectKeyId : 03de503556d14cbb66f0a3e21b1bc397b23dd155
AuthorityKeyId : 03de503556d14cbb66f0a3e21b1bc397b23dd155
OCSP DETAILS - STAPLED INFORMATION ...
CertificateStatus : Good
SerialNumber : 21020869104500376438182461249190639870
ProducedAt : 2019-11-03 05:27:47 +0000 UTC
ThisUpdate : 2019-11-03 05:27:47 +0000 UTC (was provided 28 hours ago)
NextUpdate : 2019-11-10 04:42:47 +0000 UTC (will be provided in 138 hours)
OCSP DETAILS - SERVICE RESPONSE ...
Server : http://ocsp.digicert.com
ServerStatus : Ok
CertificateStatus : Good
SerialNumber : 21020869104500376438182461249190639870
ProducedAt : 2019-11-04 06:27:51 +0000 UTC
ThisUpdate : 2019-11-04 06:27:51 +0000 UTC (was provided 3 hours ago)
NextUpdate : 2019-11-11 05:42:51 +0000 UTC (will be provided in 163 hours)
CRL DETAILS ...
DistributionPoint : http://crl3.digicert.com/ssca-sha2-g6.crl
DownloadSupport : Yes
ReadingStatus : Ok
Signature : Valid
Version : 1
Issuer : CN=DigiCert SHA2 Secure Server CA,O=DigiCert Inc,C=US
ThisUpdate : 2019-11-03 22:48:37 +0000 UTC (was provided 11 hours ago)
NextUpdate : 2019-11-13 22:48:37 +0000 UTC (will be provided in 228 hours)
Extension : Id=2.5.29.35, Value=[48 22 128 20 15 128 97 28 130 49 97 213 47 40 231 141 70 56 180 44 225 198 217 226]
Extension : Id=2.5.29.20, Value=[2 2 2 210]
Extension : Id=2.5.29.28, Value=[48 47 160 45 160 43 134 41 104 116 116 112 58 47 47 99 114 108 51 46 100 105 103 105 99 101 114 116 46 99 111 109 47 115 115 99 97 45 115 104 97 50 45 103 54 46 99 114 108]
CertificateStatus : Good
SerialNumber : 21020869104500376438182461249190639870
CRL DETAILS ...
DistributionPoint : http://crl4.digicert.com/ssca-sha2-g6.crl
DownloadSupport : Yes
ReadingStatus : Ok
Signature : Valid
Version : 1
Issuer : CN=DigiCert SHA2 Secure Server CA,O=DigiCert Inc,C=US
ThisUpdate : 2019-11-03 22:48:37 +0000 UTC (was provided 11 hours ago)
NextUpdate : 2019-11-13 22:48:37 +0000 UTC (will be provided in 228 hours)
Extension : Id=2.5.29.35, Value=[48 22 128 20 15 128 97 28 130 49 97 213 47 40 231 141 70 56 180 44 225 198 217 226]
Extension : Id=2.5.29.20, Value=[2 2 2 210]
Extension : Id=2.5.29.28, Value=[48 47 160 45 160 43 134 41 104 116 116 112 58 47 47 99 114 108 51 46 100 105 103 105 99 101 114 116 46 99 111 109 47 115 115 99 97 45 115 104 97 50 45 103 54 46 99 114 108]
CertificateStatus : Good
SerialNumber : 21020869104500376438182461249190639870The master branch is used for program development and may be unstable. See 'Releases' for pre-build binaries.
go get github.com/Klaus-Tockloth/certstate
make
github.com/Klaus-Tockloth/certstate-pemdecode
- initial release
- output format modified, verbose mode implemented
- added: time calculations, ExtKeyUsage, fingerprints
- added: SubjectKeyId, AuthorityKeyId, debug option, connection details, network details
- added: PolicyIdentifiers
- added: TLS 1.3 support
- CRL support added, code restructed, options -ocsp and -crl implemented