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, and keeps
certsdir (default:
/etc/openssl/certs) populated with:
certctl
will exclude from
certsdir any certificates that have been marked
untrustworthy with certctl
untrust
, which are persistently maintained in the
private state directory distrustdir (default:
/etc/openssl/untrusted).
certctl
treats
config and distrustdir as
configuration, and treats 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
certctl
rehash
will
populate certsdir with these. Paths are printed one
per line, encoded in vis(1)
format to escape any shell metacharacters.rehash
certctl
untrust
.trust
certcertctl
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.
untrust
certcert must be the full absolute path to a certificate that is in the certificate search path.
untrusted
certctl
untrust
.
certctl
rehash
will not
put these in certsdir. Paths are printed one per
line, encoded in vis(1) format
to escape any shell metacharacters.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.
path
dira-zA-Z0-9,.:=/+-
’.
All certificates must have unique base names across all directories in the certificate search path.
manual
certctl
will
not modify
certsdir, but may still check consistency of the
configuration when run, and certctl
untrust
and certctl
trust
will still update
distrustdir.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 path /etc/openssl/certs.local # 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:
certctl
supports
destdir/metalog handling; NetBSD
certctl
does not.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.certctl
takes
configuration through environment variables;
NetBSD certctl
takes
configuration through a file and command-line arguments.certctl
first appeared in
NetBSD 10.0. A utility of the same name previously
appeared in FreeBSD 12.2.
August 16, 2023 | NetBSD 10.99 |