Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.


CERTCTL(8)                  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
     applications as trust anchors for certificate validation in TLS or other
     purposes, 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
     typically 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
         certificates 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
                 metacharacters.

     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
                 certificate search path, and rehash to make it effective
                 immediately.  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
     character `#' 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
                 absolute pathname, vis(3)-encoded if it has any characters
                 outside 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
                 configuration when run, and certctl untrust and certctl trust
                 will still update distrustdir.

FILES
     /etc/openssl/certs                Default directory of hashed TLS CA
                                       certificates.

     /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
                                       certificates.

     /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
                                       authentication.

     /usr/share/certs/mozilla/server   All root CA certificates published by
                                       Mozilla for use in TLS server
                                       authentication.

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
     previously appeared in FreeBSD 12.2.

NetBSD 10.99                    August 16, 2023                   NetBSD 10.99