certctl(8)
- NetBSD Manual Pages
CERTCTL(8) NetBSD System Manager's Manual CERTCTL(8)
NAME
certctl -- configure OpenSSL certificate trust anchors
SYNOPSIS
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
DESCRIPTION
The certctl utility manages certificates used by OpenSSL-based applica-
tions as trust anchors for certificate validation in TLS or other pur-
poses, 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 typ-
ically 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:
- symlinks to the original files in the certificate search path, for
applications that scan a directory for all files matching *.cer,
*.crt, or *.pem;
- hashed symlinks as in openssl_rehash(1); and
- a single-file bundle ca-certificates.crt concatenating all the cer-
tificates in PEM format.
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.
Commands
list List absolute paths to trusted certificates. certctl rehash
will populate certsdir with these. Paths are printed one per
line, encoded in vis(1) format to escape any shell metachar-
acters.
rehash Populate certsdir with all trusted certificates, excluding
any from certctl untrust.
trust cert Allow cert to be included in certsdir if it is in the cer-
tificate search path, and rehash to make it effective immedi-
ately. 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.
untrust cert
Persistently prevent cert from being included in certsdir,
and rehash to make it effective immediately.
cert must be the full absolute path to a certificate that is
in the certificate search path.
untrusted List absolute paths to certificates that have been excluded
by 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.
Configuration file
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 charac-
ter `#' are ignored. Each line has a directive and arguments separated
by whitespace, and may be extended by `\' to continuation lines.
path dir Add dir to the certificate search path. dir must be an abso-
lute pathname, vis(3)-encoded if it has any characters out-
side the class `a-zA-Z0-9,.:=/+-'.
All certificates must have unique base names across all
directories in the certificate search path.
manual Manual override. If specified, certctl will not modify
certsdir, but may still check consistency of the configura-
tion when run, and certctl untrust and certctl trust will
still update distrustdir.
FILES
/etc/openssl/certs Default directory of hashed TLS CA cer-
tificates.
/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 distrustdir directory of
excluded TLS CA certificates.
/usr/share/certs/mozilla/all All root CA certificates published by
Mozilla, including untrustworthy cer-
tificates.
/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 authentica-
tion.
/usr/share/certs/mozilla/server All root CA certificates published by
Mozilla for use in TLS server authenti-
cation.
EXAMPLES
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
DIAGNOSTICS
The certctl utility exits 0 on success, and >0 if an error occurs.
COMPATIBILITY
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.
SEE ALSO
openssl(1), openssl_rehash(1)
HISTORY
certctl first appeared in NetBSD 10.0. A utility of the same name previ-
ously appeared in FreeBSD 12.2.
NetBSD 10.99 August 16, 2023 NetBSD 10.99
Powered by man-cgi (2024-03-20).
Maintained for NetBSD
by Kimmo Suominen.
Based on man-cgi by Panagiotis Christias.