CERTCTL(8)

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.

August 16, 2023 | NetBSD 11.0