Copyright (c) 2023 The NetBSD Foundation, Inc.
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
.Dd August 16, 2023 .Dt CERTCTL 8 .Os """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh NAME .Nm certctl .Nd configure OpenSSL certificate trust anchors """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh SYNOPSIS .Nm .Op Fl nv .Op Fl C Ar config .Op Fl c Ar certsdir .Op Fl u Ar distrustdir .Ar cmd .Op Ar args... """""""""""""""""
.Nm .Oo Ar options Oc Cm list .Nm .Oo Ar options Oc Cm rehash .Nm .Oo Ar options Oc Cm trust Ar cert .Nm .Oo Ar options Oc Cm untrust Ar cert .Nm .Oo Ar options Oc Cm untrusted """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh DESCRIPTION The .Nm utility manages certificates used by OpenSSL-based applications as trust anchors for certificate validation in TLS or other purposes, for example by .Xr ftp 1 in HTTPS. .Nm allows configuring the set of certificates and persistently excluding individual certificates.
p For trust anchors to validate TLS certificates, OpenSSL applications typically use a directory at
a /etc/openssl/certs of hashed certificates in PEM format, with names like
a "3513523f.0" used for lookup; see .Xr openssl_rehash 1 .
p .Nm scans all directories in the certificate search path specified by the configuration file .Ar config
q default: Pa /etc/openssl/certs.conf for files called
a *.cer ,
a *.crt , or
a *.pem in PEM format, and keeps .Ar certsdir
q default: Pa /etc/openssl/certs populated with: l -dash t symlinks to the original files in the certificate search path, for applications that scan a directory for all files matching
a *.cer ,
a *.crt , or
a *.pem ; t hashed symlinks as in .Xr openssl_rehash 1 ; and t a single-file bundle
a ca-certificates.crt concatenating all the certificates in PEM format. .El
p .Nm will exclude from .Ar certsdir any certificates that have been marked untrustworthy with .Nm Cm untrust , which are persistently maintained in the private state directory .Ar distrustdir
q default: Pa /etc/openssl/untrusted .
p
.Nm
treats
.Ar config
and
.Ar distrustdir
as configuration, and treats
.Ar certsdir
strictly as a cache that can be safely deleted and rebuilt with
.Nm Cm rehash .
.Nm
can also be instructed not to touch
.Ar certsdir
at all by putting
.Cm manual
in
.Ar config .
"""""""""""""""""""""""""""""""""""""
.Ss Commands
l -tag -width Cm """""""""""""""""
t Cm list List absolute paths to trusted certificates.
.Nm Cm rehash
will populate
.Ar certsdir
with these.
Paths are printed one per line, encoded in
.Xr vis 1
format to escape any shell metacharacters.
"""""""""""""""""
t Cm rehash Populate
.Ar certsdir
with all trusted certificates, excluding any from
.Nm Cm untrust .
"""""""""""""""""
t Cm trust Ar cert Allow
.Ar cert
to be included in
.Ar certsdir
if it is in the certificate search path, and rehash to make it
effective immediately.
In other words, reverse the persistent effect of
.Nm Cm untrust Ar cert .
p .Ar cert must be the full absolute path to a certificate that has been excluded by .Nm Cm untrust Ar cert .
p
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.
"""""""""""""""""
t Cm untrust Ar cert Persistently prevent
.Ar cert
from being included in
.Ar certsdir ,
and rehash to make it effective immediately.
p
.Ar cert
must be the full absolute path to a certificate that is in the
certificate search path.
"""""""""""""""""
t Cm untrusted List absolute paths to certificates that have been excluded by
.Nm Cm untrust .
.Nm Cm rehash
will not put these in
.Ar certsdir .
Paths are printed one per line, encoded in
.Xr vis 1
format to escape any shell metacharacters.
"""""""""""""""""
.El
"""""""""""""""""""""""""""""""""""""
.Ss Configuration file
The configuration file is a plain text file of lines separated by
.Tn US-ASCII
line feeds.
p
p The first line must be: .Dl netbsd-certctl 20230816
p
Lines with only whitespace, or whitespace followed by the comment
character
.Ql #
are ignored.
Each line has a directive and arguments separated by whitespace, and
may be extended by
.Ql \e
to continuation lines.
l -tag -width Cm """""""""""""""""
t Cm path Ar dir Add
.Ar dir
to the certificate search path.
.Ar dir
must be an absolute pathname,
.Xr vis 3 Ns -encoded
if it has any characters outside the class
.Ql "a-zA-Z0-9,.:=/+-" .
p
All certificates must have unique base names across all directories
in the certificate search path.
"""""""""""""""""
t Cm manual Manual override.
If specified,
.Nm
will
.Em not
modify
.Ar certsdir ,
but may still check consistency of the configuration when run, and
.Nm Cm untrust
and
.Nm Cm trust
will still update
.Ar distrustdir .
"""""""""""""""""
.El
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh FILES
l -tag -width Pa t Pa /etc/openssl/certs Default directory of hashed TLS CA certificates.
t Pa /etc/openssl/certs/ca-certificates.crt Default single-file TLS CA certificate bundle.
t Pa /etc/openssl/certs.conf Default configuration file for TLS CA certificates.
t Pa /etc/openssl/untrusted Default
.Ar distrustdir
directory of excluded TLS CA certificates.
t Pa /usr/share/certs/mozilla/all All root CA certificates published by Mozilla, including untrustworthy
certificates.
t Pa /usr/share/certs/mozilla/code All root CA certificates published by Mozilla for use in code-signing.
t Pa /usr/share/certs/mozilla/email All root CA certificates published by Mozilla for use in email
authentication.
t Pa /usr/share/certs/mozilla/server All root CA certificates published by Mozilla for use in TLS server
authentication.
.El
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh EXAMPLES
Example configuration file
q Pa /etc/openssl/certs.conf : d -literal -offset indent 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 .Ed
p Exclude a certificate: d -literal -offset indent $ certctl untrust /usr/share/certs/mozilla/server/GTS_Root_R1.pem .Ed
p There is no need to run .Nm Cm rehash explicitly after .Nm Cm untrust , but if you do, the setting will persist.
p Rebuild the hashed certificate cache at
a /etc/myapplication/certs from
a /etc/myapplication/certs.conf and
a /etc/myapplication/untrusted :
d -literal -offset indent $ certctl -c /etc/myapplication/certs \e
-C /etc/myapplication/certs.conf \e
-u /etc/myapplication/untrusted
.Ed
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh DIAGNOSTICS
.Ex -std
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh COMPATIBILITY
The
.Nm
utility is mostly compatible with a utility of the same name in
.Fx .
Differences:
l -enum """""""""""""""""
t .Fx Nm
supports destdir/metalog handling;
.Nx Nm
does not.
"""""""""""""""""
t .Fx Nm
treats
a /etc/ssl/untrusted both as configuration .Em and as caches; .Nx Nm treats
a /etc/openssl/certs.conf and
a /etc/openssl/untrusted as configuration, and treats
a /etc/openssl/certs
strictly as a cache.
.Fx Nm
will forget any
.Nm Cm untrust
settings on
.Nm Cm rehash ,
but
.Nx Nm
will remember them.
"""""""""""""""""
t .Fx Nm
takes configuration through environment variables;
.Nx Nm
takes configuration through a file and command-line arguments.
.El
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh SEE ALSO
.Xr openssl 1 ,
.Xr openssl_rehash 1
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh HISTORY
.Nm
first appeared in
.Nx 10.0 .
A utility of the same name previously appeared in
.Fx 12.2 .
Indexes created Sat Sep 20 22:09:52 GMT 2025