.\" $NetBSD: certctl.8,v 1.2.2.2 2023/09/04 17:33:27 martin Exp $ .\" .\" 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. .Pp For trust anchors to validate TLS certificates, OpenSSL applications typically use a directory at .Pa /etc/openssl/certs of hashed certificates in PEM format, with names like .Pa "3513523f.0" used for lookup; see .Xr openssl_rehash 1 . .Pp .Nm scans all directories in the certificate search path specified by the configuration file .Ar config .Pq default: Pa /etc/openssl/certs.conf for files called .Pa *.cer , .Pa *.crt , or .Pa *.pem in PEM format, except for those that have been excluded by .Nm Cm untrust , and keeps .Ar certsdir .Pq default: Pa /etc/openssl/certs populated with: .Bl -dash .It symlinks to the original files in the certificate search path, for applications that scan a directory for all files matching .Pa *.cer , .Pa *.crt , or .Pa *.pem ; .It hashed symlinks as in .Xr openssl_rehash 1 ; and .It a single-file bundle .Pa ca-certificates.crt concatenating all the certificates in PEM format. .El .Pp .Nm treats .Ar config and .Ar distrustdir as configuration, and .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 .Bl -tag -width Cm .\"""""""""""""""""" .It Cm list List absolute paths to trusted certificates, one per line, in .Xr vis 1 format to encode any shell metacharacters, that .Nm Cm rehash would use to populate the .Ar certsdir cache. .\"""""""""""""""""" .It Cm rehash Populate .Ar certsdir with all trusted certificates, excluding any from .Nm Cm untrust . .\"""""""""""""""""" .It Cm trust Ar cert Allow .Ar 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 .Nm Cm untrust Ar cert . .Pp .Ar cert must be the full absolute path to a certificate that has been excluded by .Nm Cm untrust Ar cert . .Pp 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. .\"""""""""""""""""" .It Cm untrust Ar cert Persistently prevent .Ar from being included in the certificate cache, and rehash the certificate cache. .Pp .Ar cert must be the full absolute path to a certificate that is in the certificate search path. .\"""""""""""""""""" .It Cm untrusted List absolute paths to untrusted certificates, one per line, in .Xr vis 1 format to encode any shell metacharacters, that have been excluded by .Nm Cm untrust so that .Nm Cm rehash will not put them in .Ar certsdir . .\"""""""""""""""""" .El .\"""""""""""""""""""""""""""""""""""""" .Ss Configuration file The configuration file is a plain text file of lines separated by .Tn US-ASCII line feeds. .Pp .Pp The first line must be: .Dl netbsd-certctl 20230816 .Pp 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. .Bl -tag -width Cm .\"""""""""""""""""" .It 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,.:=/+-" . .Pp All certificates must have unique base names across all directories in the certificate search path. .\"""""""""""""""""" .It Cm manual Manual override. If specified, .Nm will .Em not modify .Ar certsdir , but may still check consistency of the configuration when run and update .Ar distrustdir . .\"""""""""""""""""" .El .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" .Sh FILES .Bl -tag -width Pa .It Pa /etc/openssl/certs Default directory of hashed TLS CA certificates. .It Pa /etc/openssl/certs/ca-certificates.crt Default single-file TLS CA certificate bundle. .It Pa /etc/openssl/certs.conf Default configuration file for TLS CA certificates. .It Pa /etc/openssl/untrusted Default .Ar untrusted directory of excluded TLS CA certificates. .It Pa /usr/share/certs/mozilla/all All root CA certificates published by Mozilla, including untrustworthy certificates. .It Pa /usr/share/certs/mozilla/code All root CA certificates published by Mozilla for use in code-signing. .It Pa /usr/share/certs/mozilla/email All root CA certificates published by Mozilla for use in email authentication. .It 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 .Pq Pa /etc/openssl/certs.conf : .Bd -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 # If the next line is uncommented, certctl(8) will decline to # touch /etc/openssl/certs. #manual .Ed .Pp Exclude a certificate: .Bd -literal -offset indent $ certctl untrust /usr/share/certs/mozilla/server/GTS_Root_R1.pem .Ed .Pp There is no need to run .Nm Cm rehash explicitly after .Nm Cm untrust , but if you do, the setting will persist. .Pp Rebuild the hashed certificate cache at .Pa /etc/myapplication/certs from .Pa /etc/myapplication/certs.conf and .Pa /etc/myapplication/untrusted : .Bd -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: .Bl -enum .\"""""""""""""""""" .It .Fx Nm supports destdir/metalog handling; .Nx Nm does not. .\"""""""""""""""""" .It .Fx Nm treats .Pa /etc/ssl/certs and .Pa /etc/ssl/untrusted both as configuration .Em and as caches; .Nx Nm treats .Pa /etc/openssl/certs.conf and .Pa /etc/openssl/untrusted as configuration, and treats .Pa /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. .\"""""""""""""""""" .It .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 .