certctl-transition

NetBSD<=9 situation
NetBSD 10 and certctl(8)
Transitions
certctl(8) proposal and discussions

NetBSD<=9 situation

Prior to NetBSD 10, NetBSD did not ship any CA certificates for TLS trust anchors, so tools such as pkg_add(8) and ftp(1) would simply not do TLS validation in HTTPS requests.

Applications using OpenSSL look in /etc/openssl/certs by default for hashed certificate links as trust anchors, and pkgsrc's security/openssl/builtin.mk sets SSLCERTS to /etc/openssl/certs to reflect that. Some applications also consult /etc/openssl/certs/ca-certificates.crt for a single-file bundle of concatenated PEM files.

Note: /etc/openssl/certs is only for TLS trust anchors. There is no standard directory that applications will consult for, e.g., S/MIME trust anchors for email.

Several pkgsrc packages provide trust anchors and different ways to manage /etc/openssl/certs, mostly from the Mozilla certdata.txt repository:

security/ca-certificates
- installs certificates from Mozilla certdata.txt as PEM files under $PREFIX/share/ca-certificates/mozilla
- provides an update-ca-certificates(8) command to create hashed symlinks to them under /etc/openssl/certs
- configured by $PKG_SYSCONFDIR/ca-certificates.conf and $PKG_SYSCONFDIR/ca-certificates-dir.conf
- (GPL, so not fit for shipping in base)
security/mozilla-rootcerts
- installs Mozilla certdata.txt at $PREFIX/share/mozilla-rootcerts/certdata.txt
- installs a single-file bundle of concatenated PEM files at $PREFIX/share/mozilla-rootcerts/cacert.pem
- provides a mozilla-rootcerts(8) command to extract the individual certificates and create hashed symlinks to them under /etc/openssl/certs and a single-file bundle of concatenated PEM files at /etc/openssl/certs/ca-certificates.crt
- doesn't support excluding individual trust anchors
- includes non-TLS trust anchors (e.g., S/MIME)
security/mozilla-rootcerts-openssl
- special package based on security/mozilla-rootcerts that installs the hashed symlinks and ca-cdirectly in /etc/openssl/certs
- makes pkg_* tools unhappy if you remove or change anything in /etc/openssl/certs

Users can also manage /etc/openssl/certs manually or in other ways, e.g. to include internal site trust anchors not fit for the public internet.

NetBSD 10 and certctl(8)

NetBSD 10 ships with:

all certificates from Mozilla certdata.txt in /usr/share/certs/mozilla/all, including those not trusted by Mozilla by default or trusted only with restrictions
default TLS trust anchors symlinked in /usr/share/certs/mozilla/server
default S/MIME trust anchors symlinked in /usr/share/certs/mozilla/email
default code-signing trust anchors symlinked in /usr/share/certs/mozilla/code (unused, and empty)
a command certctl(8) to manage exclusions and create hashed symlinks in /etc/openssl/certs
a default /etc/openssl/certs.conf configuration file for certctl(8) pointing at /usr/share/certs/mozilla/server

If you upgrade from NetBSD<=9 to NetBSD 10, it will avoid changing your existing configuration of /etc/openssl/certs. You can switch to using certctl(8) if you want as follows:

Clear the existing /etc/openssl/certs -- e.g., remove the mozilla-rootcerts-openssl package if you're using that, or just delete /etc/openssl/certs if you're using mozilla-rootcerts or ca-certificates.
Make sure you have /etc/openssl/certs.conf without manual set. (Default is in /usr/share/examples/certctl/certs.conf.)
Run certctl rehash.

Other configuration choices you may want to make:

You can change the list of source directories in /etc/openssl/certs.conf, e.g. to add site-specific certificates in addition to the Mozilla ones. Make sure to rerun certctl rehash if you do this.
You can exclude individual trust anchors with, e.g., certctl untrust /usr/share/certs/mozilla/all/TrustCor_RootCert_CA-1.pem. (No need to run certctl rehash, but no harm if you do.)
You can ask certctl(8) not to touch /etc/openssl/certs by putting the line manual in /etc/openssl/certs.conf, if you want to manage it yourself some other way, like one of the pkgsrc packages.

Transitions

Fresh installation with sysinst(8)

sysinst(8) extracts an empty /etc/openssl/certs from base.tgz and default /etc/openssl/certs.conf from etc.tgz, and then runs certctl rehash.

That way, fresh installations have trust anchors installed and configured out of the box.

Fresh installation with live images (live-image, mkimage, arm64.img, etc.)

XXX OOPS -- this doesn't work currently.

Plan: create an rc.d script that runs certctl rehash if /etc/openssl/certs is an empty directory.

cheap to test, so not a burden to run on every boot
does the right thing on a fresh installation
doesn't get in the way of manually configured /etc/openssl/certs
doesn't require /etc to be writable later on
relies on postinstall(8) to apply updates

Draft patch: https://www.NetBSD.org/~riastradh/tmp/20230926/certctl_init.patch

Upgrade with sysinst(8)

Upgrade with sysinst(8) goes through postinstall(8) (q.v., below).

etcupdate(8)

If you use etcupdate(8) to update etc.tgz on upgrades, it may install the default /etc/openssl/certs.conf for you, which asks certctl(8) to take charge of /etc/openssl/certs.

If /etc/openssl/certs was empty, this is probably what you want. (Make sure to run postinstall(8) after etcupdate(8) as usual, of course!)
If /etc/openssl/certs was nonempty, there is now a conflict between what you were previously doing, and what the new default /etc/openssl/certs.conf does. certctl(8) will fail noisily (e.g., when you later run postinstall(8)), because you've asked it to be responsible for /etc/openssl/certs which it can't do without potentially causing harm to your existing configuration:
```
# certctl rehash
certctl: existing certificates; set manual or remove them
```
In this case, you can either:
- clear the existing configuration (e.g., delete the mozilla-rootcerts-openssl package, or empty /etc/openssl/certs) so that certctl(8) can take over, and rerun postinstall(8) or certctl rehash; or
- put the line manual in /etc/openssl/certs.conf, if you want to continue to use your existing method of managing /etc/openssl/certs and not have certctl(8) take over.

postinstall(8)

The postinstall(8) script must be run on every upgrade after extracting sets and updating etc (whether with etcupdate(8) or another method of updating the system configuration).

The logic in postinstall(8) is designed to gracefully handle every reasonable upgrade scenario I could think of via two new items:

opensslcertsconf runs first to ensure that /etc/openssl/certs.conf exists -- as the default (/usr/share/examples/certctl/certs.conf) if /etc/openssl/certs was empty, and with manual set if /etc/openssl/certs was already populated.
opensslcertsrehash runs next to rehash /etc/openssl/certs if needed, accordin to /etc/openssl/certs.conf.

Note: This only works with DESTDIR=/, because it relies on the openssl(1) command-line tool, which is not built as part of the cross-compiler toolchain and not required to be available in the host environment of NetBSD builds.

The only scenario that ends in failure when you run postinstall fix opensslcertsconf opensslcertsrehash is when you have pre-populated /etc/openssl/certs and installed the default /etc/openssl/certs.conf (e.g., with etcupdate(8)) which asks certctl(8) to manage /etc/openssl/certs -- these are inconsistent instructions and the system will fail noisily rather than blow away your existing configuration.

The following transitions have been tested (from the commit):

fresh install: empty /etc/openssl/certs; default /etc/openssl/certs.conf
- opensslcertsconf
  - check: pass
  - fix: pass -- nothing
- opensslcertsrehash
  - check: fail -- needs rehash
  - fix: pass -- quietly rehash successfully (go to 4)
fresh upgrade: empty /etc/openssl/certs; no /etc/openssl/certs.conf
- opensslcertsconf
  - check: fail -- complain missing /etc/openssl/certs.conf
  - fix: pass -- install default /etc/openssl/certs.conf (go to 1)
- opensslcertsrehash
  - check: fail -- complain missing /etc/openssl/certs.conf
  - fix: fail -- complain missing /etc/openssl/certs.conf
upgrade from certctl, changes to certs: certctl-managed /etc/openssl/certs; default /etc/openssl/certs.conf
- opensslcertsconf
  - check: pass
  - fix: pass -- nothing
- opensslcertsrehash
  - check: fail -- needs rehash
  - fix: pass -- quietly rehash successfully (go to 4)
upgrade from certctl, no changes to certs: certctl-managed /etc/openssl/certs; default /etc/openssl/certs.conf
- opensslcertsconf
  - check: pass
  - fix: pass -- nothing
- opensslcertsrehash
  - check: pass
  - fix: pass -- quietly rehash successfully (go to 4)
upgrade from mozilla-rootcerts: populated /etc/openssl/certs; no /etc/openssl/certs.conf
- opensslcertsconf:
  - check: fail -- complain missing /etc/openssl/certs.conf
  - fix: pass -- install manual /etc/openssl/certs.conf (go to 7)
- opensslcertsrehash:
  - check: fail -- complain missing /etc/openssl/certs.conf
  - fix: fail -- complain missing /etc/openssl/certs.conf
upgrade from mozilla-rootcerts with etcupdate naively: populated /etc/openssl/certs; default /etc/openssl/certs.conf
- opensslcertsconf:
  - check: pass
  - fix: pass -- nothing
- opensslcertsrehash:
  - check: fail -- complain mismatched certs/ and certs.conf
  - fix: fail -- complain mismatched certs/ and certs.conf
upgrade from mozilla-rootcerts with etcupdate manually: populated /etc/openssl/certs; manual /etc/openssl/certs.conf
- opensslcertsconf:
  - check: pass
  - fix: pass -- nothing
- opensslcertsrehash:
  - check: pass
  - fix: pass -- skip rehash because manual (go to 7)

XXX Should opensslcertsconf check for /etc/openssl/certs/.certctl when /etc/openssl/certs.conf is missing, in case you were previously managing /etc/openssl/certs with certctl(8) and somehow lost /etc/openssl/certs.conf?

certctl(8) proposal and discussions

https://mail-index.NetBSD.org/tech-userlevel/2023/08/22/msg014140.html

Followup discussions:

Add a comment

Last edited mid-morning Tuesday, September 26th, 2023

Preferences | Logout