\"      $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 .

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.