Check X.509 Certificate Revocation with dirmngr-client

A certificate check returns a non-zero exit code, and you need to know whether it is revoked or merely unchecked. You will build a small, scriptable revocation check with dirmngr-client and the local GnuPG dirmngr, and learn to tell a revoked certificate from a failed check. It takes about fifteen minutes. The examples were tested with dirmngr-client from GnuPG 2.4.4, package dirmngr 2.4.4-2ubuntu17.6.

• You need: a shell, the dirmngr package and one DER-encoded certificate. A PEM certificate also works with --pem.
• Privileges: the normal checks are unprivileged. Do not use sudo unless your certificate file is deliberately restricted and you have a separate reason to read it as root.
• What it will not touch: this guide checks revocation state through dirmngr. It does not create a certificate, install trust anchors, edit GnuPG configuration or change a service.

1. Confirm the installed command

Check the package and binary before you build a script around their behaviour:

$ dpkg-query -W -f='${Package} ${Version}\n' dirmngr
dirmngr 2.4.4-2ubuntu17.6
$ command -v dirmngr-client
/usr/bin/dirmngr-client
$ dirmngr-client --version
dirmngr-client (GnuPG) 2.4.4

The local manpage describes the input as either a certificate file or a pattern. For the revocation test here, use one certificate file.

2. Check that dirmngr is available

Run the daemon health check:

$ dirmngr-client --ping
dirmngr-client: a dirmngr daemon is up and running
$ printf 'exit status: %s\n' "$?"
exit status: 0

Status 0 means the daemon answered. From your point of view the command is read-only, and it needs no elevated privileges.

A normal certificate operation may start a dirmngr instance if none is running, but the manpage warns that starting a new instance has a large performance cost. If a check is slow, investigate the daemon and its logs. Do not launch new processes in a loop.

3. Check a DER certificate

Give the command one DER-encoded certificate. Substitute a path you have already verified:

$ CERT='/path/to/certificate.der'
$ test -r "$CERT"
$ dirmngr-client "$CERT"
$ printf 'revocation check status: %s\n' "$?"
revocation check status: 0

Status 0 means dirmngr found a valid CRL in which the certificate was not listed, or an OCSP responder reported the certificate as valid. It is a revocation result. It does not say that every part of the certificate's trust chain is acceptable.

Use --quiet when a script needs less informational output, but still inspect the exit status:

$ dirmngr-client --quiet "$CERT"
$ case "$?" in
    0) echo 'certificate reported valid' ;;
    1) echo 'certificate reported revoked' ;;
    2) echo 'revocation check failed' ;;
    *) echo 'unexpected dirmngr-client error' ;;
esac

4. Interpret failures without guessing

The exit codes mean three different things:

• 0: the CRL or OCSP check reported the certificate valid.
• 1: the certificate was reported revoked.
• 2 and other non-zero values: the command could not establish the revocation state. The diagnostic goes to standard error.

An unreadable file, an invalid certificate object, a missing or expired CRL and a network problem all land in that third bucket. None of them means the certificate is revoked. Capture standard error when a monitoring system needs the reason:

$ dirmngr-client "$CERT" 2>dirmngr-client.err
$ status=$?
$ if [ "$status" -gt 1 ]; then
    printf 'revocation status unavailable (exit %s)\n' "$status" >&2
    sed -n '1,5p' dirmngr-client.err >&2
    exit "$status"
  fi

5. Use PEM input when necessary

PEM is the text form with BEGIN CERTIFICATE and END CERTIFICATE markers. Select it explicitly:

$ CERT_PEM='/path/to/certificate.pem'
$ dirmngr-client --pem "$CERT_PEM"
$ printf 'exit status: %s\n' "$?"

Without --pem, the documented default is a DER-encoded binary certificate.

6. Choose OCSP deliberately

The default check can use the available CRL mechanism. To require OCSP and ignore CRLs, use:

$ dirmngr-client --ocsp "$CERT"
$ printf 'OCSP status: %s\n' "$?"

This may fail with status 2 when the certificate, responder or local dirmngr does not support the requested operation. That is an unavailable check, not a revocation decision.

7. Keep diagnostic operations separate

--validate asks dirmngr to run its internal certificate validation code. It helps when you investigate trust and validation, but its status is not interchangeable with the revocation result. A certificate can be untrusted and still not be reported as revoked.

--cache-cert adds a certificate to a running dirmngr cache. --load-crl loads DER-encoded CRL files into that cache, and with --url it expects URLs rather than filenames. These options change daemon state or cause network retrieval.