Check X.509 Certificate Revocation with dirmngr-client

You will finish with a small, scriptable check for an X.509 certificate using the local GnuPG dirmngr, plus a way to tell a revoked certificate from a failed check. The examples were tested with dirmngr-client from GnuPG 2.4.4, package dirmngr 2.4.4-2ubuntu17.6.

Allow about fifteen minutes. You need a shell, the dirmngr package and one DER-encoded certificate. A PEM certificate also works with --pem. The normal checks are unprivileged. Do not use sudo unless your certificate file is deliberately restricted and you have a separate reason to access it as root.

1. Confirm the installed command

Check the package and binary before building 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 in this guide, use one certificate file. Do not pass a PEM bundle containing many certificates and assume the result identifies which certificate was tested.

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. This command is read-only from your point of view and does not need elevated privileges. A normal certificate operation may start a dirmngr instance if one is not already 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 instead of repeatedly launching 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 that the certificate is valid. It is a revocation result, not a general statement 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 are deliberately different:

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

For example, an unreadable file, an invalid certificate object, a missing or expired CRL, and a network problem belong in the third category. They do not mean that 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

The command can contact network services for CRL or OCSP work. Treat that as a security boundary: a successful online response is only as trustworthy as the dirmngr configuration, responder and trust data that produced it. Do not turn a temporary status 2 into an automatic approval.

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. If a PEM file produces an invalid-object error, check that it contains one complete certificate and that the path is not a CA bundle. A certificate can be syntactically valid while its revocation check still returns status 2.

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. --force-default-responder changes which OCSP responder is used, so do not add it merely to make a failing check pass. Use it only when your deployment deliberately requires the configured default responder instead of the responder named by the certificate.

7. Keep diagnostic operations separate

--validate asks dirmngr to run its internal certificate validation code. It is useful for investigating trust and validation, but its status is not interchangeable with the revocation result. For example, 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. Warning: do not run them in a production check unless you have reviewed the cache lifetime, file provenance and operational effect. They have no general undo command; allow the daemon's cache policy to remove entries, or restart the relevant user dirmngr only under your normal service procedure.