UPDATE-CA-TRUST(8)

📦
version 2026.2.92_v9.0.319 · 9 versions
, in centos-stream 9

✨ NAME ✨

okay so welcome to update-ca-trust(8) — yes bestie, section 8 of the manual, we're in sysadmin territory 💅

update-ca-trust — manage consolidated and dynamic configuration of CA certificates and associated trust 🎀

🌸 SYNOPSIS 🌸

update-ca-trust [extract] [-o DIR|--output=DIR]

🦋 DESCRIPTION 🦋

So update-ca-trust(8) is the tool you use to manage a consolidated and dynamic configuration feature for Certificate Authority (CA) certificates and all the trust that comes attached to them. 🫶

This whole feature is there for the new-school apps that read the consolidated configuration files sitting in the /etc/pki/ca-trust/extracted directory, or that load the PKCS#11 module p11-kit-trust.so ✨

And like, parts of this new feature are also served up in a way that makes them useful for the legacy apps too — nobody gets left behind 💖

Here's the thing: lots of legacy applications expect CA certificates and trust configuration to live in a fixed location, contained in files with one particular path and name, or by referring to a classic PKCS#11 trust module provided by the NSS cryptographic library. so very rigid, but we respect it 🙈

The dynamic configuration feature provides functionally compatible replacements for those classic configuration files and for the classic NSS trust module named libnssckbi. like a glow-up that still fits in the same jeans 👑

And in order to enable those legacy applications — the ones reading the classic files or accessing the classic module — to make use of the new consolidated and dynamic configuration feature, the classic filenames have been changed to symbolic links. Those symlinks refer to dynamically created and consolidated output stored below the /etc/pki/ca-trust/extracted directory hierarchy. no cap, that's the trick 🔥

The output is produced using the update-ca-trust command (with no parameters at all), or using the update-ca-trust extract command. And to actually produce that output, a flexible set of source configuration gets read — all described down in the SOURCE CONFIGURATION section ⭐

Oh and one more: the classic PKCS#11 module is replaced with a new PKCS#11 module (p11-kit-trust.so) that dynamically reads the very same source configuration. iconic behaviour honestly 🧚

💜 SOURCE CONFIGURATION 💜

The dynamic configuration feature uses several source directories that get scanned for any number of source files. It is super important to pick the correct subdirectory when you're adding files, because the subdirectory is literally what defines how the contained certificates will be trusted or distrusted, and which file formats get read. choose wisely bestie 💅

the two hierarchies

Files in subdirectories below the directory hierarchy /usr/share/pki/ca-trust-source/ contain CA certificates and trust settings in the PEM file format. The trust settings found here will be interpreted with a low priority 💤

Files in subdirectories below the directory hierarchy /etc/pki/ca-trust/source/ contain CA certificates and trust settings in the PEM file format. The trust settings found here will be interpreted with a high priority 🔥

rules of thumb 💡

You may use the following rules of thumb to decide whether your configuration files should be added to the /etc or rather to the /usr directory hierarchy:

  • If you are manually adding a configuration file to a system, you probably want it to override any other default configuration, and you most likely should add it to the respective subdirectory in the /etc hierarchy. 🫵
  • If you are creating a package that provides additional root CA certificates, that is intended for distribution to several computer systems, but you still want to allow the administrator to override your list, then your package should add your files to the respective subdirectory in the /usr hierarchy. 📦
  • If you are creating a package that is supposed to override the default system trust settings, that is intended for distribution to several computer systems, then your package should install the files to the respective subdirectory in the /etc hierarchy. 👑

QUICK HELP 1: To add a certificate in the simple PEM or DER file formats to the list of CAs trusted on the system:

  • add it as a new file to directory /etc/pki/ca-trust/source/anchors/
  • run update-ca-trust extract

QUICK HELP 2: If your certificate is in the extended BEGIN TRUSTED file format (which may contain distrust/blocklist trust flags, or trust flags for usages other than TLS) then:

  • add it as a new file to directory /etc/pki/ca-trust/source/
  • run update-ca-trust extract

how files get treated by subdirectory 🗂️

In order to offer simplicity and flexibility, the way certificate files are treated depends on the subdirectory they are installed to.

  • simple trust anchors subdirectory: /usr/share/pki/ca-trust-source/anchors/ or /etc/pki/ca-trust/source/anchors/
  • simple blocklist (distrust) subdirectory: /usr/share/pki/ca-trust-source/blocklist/ or /etc/pki/ca-trust/source/blocklist/
  • extended format directory: /usr/share/pki/ca-trust-source/ or /etc/pki/ca-trust/source/

the main directories

In the main directories /usr/share/pki/ca-trust-source/ or /etc/pki/ca-trust/source/ you may install one or multiple files in the following file formats:

  • certificate files that include trust flags, in the BEGIN/END TRUSTED CERTIFICATE file format (any file name), which have been created using the openssl x509 tool and the -addreject -addtrust options. Bundle files with multiple certificates are supported. 🎀
  • files in the p11-kit file format using the .p11-kit file name extension, which can (e.g.) be used to distrust certificates based on serial number and issuer name, without having the full certificate available. (This is currently an undocumented format, to be extended later. For examples of the supported formats, see the files shipped with the ca-certificates package.) 🫶
  • certificate files without trust flags in either the DER file format or in the PEM (BEGIN/END CERTIFICATE) file format (any file name). Such files will be added with neutral trust — neither trusted nor distrusted. They will simply be known to the system, which might be helpful to assist cryptographic software in constructing chains of certificates. (If you want a CA certificate in these file formats to be trusted, you should remove it from this directory and move it to the ./anchors subdirectory instead.) 💀

the anchors subdirectories

In the anchors subdirectories /usr/share/pki/ca-trust-source/anchors/ or /etc/pki/ca-trust/source/anchors/ you may install one or multiple certificates in either the DER file format or in the PEM (BEGIN/END CERTIFICATE) file format. Each certificate will be treated as trusted for all purposes. ✅

the blocklist subdirectories

In the blocklist subdirectories /usr/share/pki/ca-trust-source/blocklist/ or /etc/pki/ca-trust/source/blocklist/ you may install one or multiple certificates in either the DER file format or in the PEM (BEGIN/END CERTIFICATE) file format. Each certificate will be treated as distrusted for all purposes. 🚫

Please refer to the x509(1) manual page for the documentation of the BEGIN/END CERTIFICATE and BEGIN/END TRUSTED CERTIFICATE file formats. 📖

how apps actually see this 🍓

Applications that rely on a static file for a list of trusted CAs may load one of the files found in the /etc/pki/ca-trust/extracted directory. But listen — after modifying any file in the /usr/share/pki/ca-trust-source/ or /etc/pki/ca-trust/source/ directories or in any of their subdirectories, or after adding a file, it is necessary to run the update-ca-trust extract command, in order to update the consolidated files in /etc/pki/ca-trust/extracted/ 😭 (yes, every time. don't skip it.)

Applications that load the classic PKCS#11 module using filename libnssckbi.so (which has been converted into a symbolic link pointing to the new module) and any application capable of loading PKCS#11 modules and loading p11-kit-trust.so, will benefit from the dynamically merged set of certificates and trust information stored in the /usr/share/pki/ca-trust-source/ and /etc/pki/ca-trust/source/ directories. 🌈

🎀 EXTRACTED CONFIGURATION 🎀

The directory /etc/pki/ca-trust/extracted/ contains generated CA certificate bundle files which are created and updated, based on the SOURCE CONFIGURATION by running the update-ca-trust extract command. ✨

If your application isn't able to load the PKCS#11 module p11-kit-trust.so, then you can use these files in your application to load a list of global root CA certificates. 🫶

Please never manually edit the files stored in this directory, because your changes will be lost and the files automatically overwritten, each time the update-ca-trust extract command gets executed. 💀 like genuinely, they're gone. poof.

In order to install new trusted or distrusted certificates, please rather install them in the respective subdirectory below the /usr/share/pki/ca-trust-source/ or /etc/pki/ca-trust/source/ directories, as described in the SOURCE CONFIGURATION section. 👑

java/ 🍵

The directory /etc/pki/ca-trust/extracted/java/ contains a CA certificate bundle in the java keystore file format. Distrust information cannot be represented in this file format, and distrusted certificates are missing from these files. File cacerts contains CA certificates trusted for TLS server authentication. 🔐

openssl/ 🐚

The directory /etc/pki/ca-trust/extracted/openssl/ contains CA certificate bundle files in the extended BEGIN/END TRUSTED CERTIFICATE file format, as described in the x509(1) manual page. File ca-bundle.trust.crt contains the full set of all trusted or distrusted certificates, including the associated trust flags. 🌟

pem/ 📄

The directory /etc/pki/ca-trust/extracted/pem/ contains CA certificate bundle files in the simple BEGIN/END CERTIFICATE file format, as described in the x509(1) manual page. Distrust information cannot be represented in this file format, and distrusted certificates are missing from these files. File tls-ca-bundle.pem contains CA certificates trusted for TLS server authentication. File email-ca-bundle.pem contains CA certificates trusted for E-Mail protection. File objsign-ca-bundle.pem contains CA certificates trusted for code signing. 📬

edk2/ 🥾

The directory /etc/pki/ca-trust/extracted/edk2/ contains a CA certificate bundle (cacerts.bin) in the "sequence of EFI_SIGNATURE_LISTs" format, defined in the UEFI-2.7 specification, sections "31.4.1 Signature Database" and "EFI_CERT_X509_GUID". Distrust information cannot be represented in this file format, and distrusted certificates are missing from these files. File cacerts.bin contains CA certificates trusted for TLS server authentication. 🖥️

🌟 COMMANDS 🌟

(absent/empty command) 🌸

Same as the extract command described below. (However, the command may print fewer warnings, as this command is being run during rpm package installation, where non-fatal status output is undesired.) 🤫

extract 🦋

Instruct update-ca-trust to scan the SOURCE CONFIGURATION and produce updated versions of the consolidated configuration files stored below the /etc/pki/ca-trust/extracted directory hierarchy. ⭐

EXTRACT OPTIONS 💅

  • -o DIR, --output=DIR — Write the extracted trust store into the given directory instead of updating /etc/pki/ca-trust/extracted.

💖 FILES 💖

okay so here's the whole map of where everything lives, bestie. each of these paths is doing a specific job and you cannot mix them up, iykyk 🫶

💅 /etc/pki/tls/certs/ca-bundle.crt

Classic filename, and lowkey iconic at this point. this file holds a list of CA certificates trusted for TLS server authentication usage, in the simple BEGIN/END CERTIFICATE file format, with no distrust information. it's a symbolic link that points at the consolidated output created by the update-ca-trust command ✨

🎀 /etc/pki/tls/certs/ca-bundle.trust.crt

Classic filename again, but this one's the upgrade 💅 it holds a list of CA certificates in the extended BEGIN/END TRUSTED CERTIFICATE file format, which includes trust (and/or distrust) flags specific to certificate usage. also a symbolic link that refers to the consolidated output created by the update-ca-trust command.

🦋 /etc/pki/java/cacerts

Classic filename, and she's serving Java keystore file format 🌸 it holds a list of CA certificates trusted for TLS server authentication usage, in the Java keystore file format, with no distrust information. yep, symbolic link → consolidated output created by the update-ca-trust command. consistent queen.

⭐ /usr/share/pki/ca-trust-source

this bad boy contains multiple, low priority source configuration files, as explained in section SOURCE CONFIGURATION 👑 but fr fr, please pay attention to the specific meanings of the respective subdirectories, okay? they are not interchangeable.

🔥 /etc/pki/ca-trust/source

same deal but make it high priority 💀 contains multiple, high priority source configuration files as explained in section SOURCE CONFIGURATION. again — pay attention to the specific meanings of the respective subdirectories. don't just vibe-check them and hope for the best.

🌈 /etc/pki/ca-trust/extracted

this is where the magic lands ✨ contains consolidated and automatically generated configuration files for consumption by applications, which are created using the update-ca-trust extract command.

🚨 Do not edit files in this directory, bestie. they will be overwritten. like immediately. no cap. see section EXTRACTED CONFIGURATION for additional details 🙈

👑 AUTHOR 👑

Written by Kai Engert and Stef Walter. absolute legends, we stan 🫶

and that's the page, baddie 💖 this was update-ca-trust — yes that's the source on the left of the footer, and the page itself is UPDATE-CA-TRUST(8) — dated 10/22/2026, so go forth and trust those CAs responsibly. periodt 🎀✨🌸

📦 where this page comes from