370 lines
9.4 KiB
Groff
370 lines
9.4 KiB
Groff
.\" $NetBSD: certctl.8,v 1.3 2023/10/11 15:28:05 riastradh 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, 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
|
|
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
|
|
.Pq default: Pa /etc/openssl/untrusted .
|
|
.Pp
|
|
.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
|
|
.Bl -tag -width Cm
|
|
.\""""""""""""""""""
|
|
.It 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.
|
|
.\""""""""""""""""""
|
|
.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
|
|
.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 .
|
|
.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 cert
|
|
from being included in
|
|
.Ar certsdir ,
|
|
and rehash to make it effective immediately.
|
|
.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 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.
|
|
.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
|
|
.Nm Cm untrust
|
|
and
|
|
.Nm Cm trust
|
|
will still 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 distrustdir
|
|
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
|
|
path /etc/openssl/certs.local
|
|
|
|
# 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 .
|