CERTCTL(8) System Manager's Manual CERTCTL(8)

certctl
configure OpenSSL certificate trust anchors

certctl [-nv] [-C config] [-c certsdir] [-u distrustdir] cmd [args...]

certctl [options] list

certctl [options] rehash

certctl [options] trust cert

certctl [options] untrust cert

certctl [options] untrusted

The certctl utility manages certificates used by OpenSSL-based applications as trust anchors for certificate validation in TLS or other purposes, for example by ftp(1) in HTTPS. certctl allows configuring the set of certificates and persistently excluding individual certificates.

For trust anchors to validate TLS certificates, OpenSSL applications typically use a directory at /etc/openssl/certs of hashed certificates in PEM format, with names like 3513523f.0 used for lookup; see openssl_rehash(1).

certctl scans all directories in the certificate search path specified by the configuration file config (default: /etc/openssl/certs.conf) for files called *.cer, *.crt, or *.pem in PEM format, except for those that have been excluded by certctl untrust, and keeps certsdir (default: /etc/openssl/certs) populated with:

certctl treats config and distrustdir as configuration, and certsdir strictly as a cache that can be safely deleted and rebuilt with certctl rehash. certctl can also be instructed not to touch certsdir at all by putting manual in config.

List absolute paths to trusted certificates, one per line, in vis(1) format to encode any shell metacharacters, that certctl rehash would use to populate the certsdir cache.
Populate certsdir with all trusted certificates, excluding any from certctl untrust.
cert
Allow cert to be included in the certificate cache if it is in the certificate search path, and rehash the certificate cache. In other words, reverse the persistent effect of certctl untrust cert.

cert must be the full absolute path to a certificate that has been excluded by certctl untrust cert.

This does not add a new certificate which is not in the search path. To do that, you can create a directory to hold it and put that directory in the search path.

cert
Persistently prevent file ... from being included in the certificate cache, and rehash the certificate cache.

cert must be the full absolute path to a certificate that is in the certificate search path.

List absolute paths to untrusted certificates, one per line, in vis(1) format to encode any shell metacharacters, that have been excluded by certctl untrust so that certctl rehash will not put them in certsdir.

The configuration file is a plain text file of lines separated by US-ASCII line feeds.

The first line must be:

netbsd-certctl 20230816

Lines with only whitespace, or whitespace followed by the comment character ‘#’ are ignored. Each line has a directive and arguments separated by whitespace, and may be extended by ‘\’ to continuation lines.

dir
Add dir to the certificate search path. dir must be an absolute pathname, vis(3)-encoded if it has any characters outside the class ‘a-zA-Z0-9,.:=/+-’.

All certificates must have unique base names across all directories in the certificate search path.

Manual override. If specified, certctl will not modify certsdir, but may still check consistency of the configuration when run and update distrustdir.

/etc/openssl/certs
Default directory of hashed TLS CA certificates.
/etc/openssl/certs/ca-certificates.crt
Default single-file TLS CA certificate bundle.
/etc/openssl/certs.conf
Default configuration file for TLS CA certificates.
/etc/openssl/untrusted
Default untrusted directory of excluded TLS CA certificates.
/usr/share/certs/mozilla/all
All root CA certificates published by Mozilla, including untrustworthy certificates.
/usr/share/certs/mozilla/code
All root CA certificates published by Mozilla for use in code-signing.
/usr/share/certs/mozilla/email
All root CA certificates published by Mozilla for use in email authentication.
/usr/share/certs/mozilla/server
All root CA certificates published by Mozilla for use in TLS server authentication.

Example configuration file (/etc/openssl/certs.conf):
netbsd-certctl 20230816

# Blank lines and comments are ignored.
# Comments begin with a `#' sign.

# Gather certificates from files called *.cer, *.crt, and *.pem
# under these directories.
path /usr/share/certs/mozilla/server
path /usr/pkg/share/chromium-cacerts

# If the next line is uncommented, certctl(8) will decline to
# touch /etc/openssl/certs.
#manual

Exclude a certificate:

$ certctl untrust /usr/share/certs/mozilla/server/GTS_Root_R1.pem

There is no need to run certctl rehash explicitly after certctl untrust, but if you do, the setting will persist.

Rebuild the hashed certificate cache at /etc/myapplication/certs from /etc/myapplication/certs.conf and /etc/myapplication/untrusted:

$ certctl -c /etc/myapplication/certs \
        -C /etc/myapplication/certs.conf \
        -u /etc/myapplication/untrusted

The certctl utility exits 0 on success, and >0 if an error occurs.

The certctl utility is mostly compatible with a utility of the same name in FreeBSD. Differences:
  1. FreeBSD certctl supports destdir/metalog handling; NetBSD certctl does not.
  2. FreeBSD certctl treats /etc/ssl/certs and /etc/ssl/untrusted both as configuration and as caches; NetBSD certctl treats /etc/openssl/certs.conf and /etc/openssl/untrusted as configuration, and treats /etc/openssl/certs strictly as a cache. FreeBSD certctl will forget any certctl untrust settings on certctl rehash, but NetBSD certctl will remember them.
  3. FreeBSD certctl takes configuration through environment variables; NetBSD certctl takes configuration through a file and command-line arguments.

openssl(1), openssl_rehash(1)

certctl first appeared in NetBSD 10.0. A utility of the same name previously appeared in FreeBSD 12.2.
August 16, 2023 NetBSD 10.0