update-ca-trust(8) is used to manage a consolidated and dynamic configuration feature of Certificate Authority (CA) certificates and associated trust.
The feature is available for new applications that read the consolidated configuration files found in the /etc/pki/ca-trust/extracted directory or that load the PKCS#11 module p11-kit-trust.so
Parts of the new feature are also provided in a way to make it useful for legacy applications.
Many legacy applications expect CA certificates and trust configuration in a fixed location, contained in files with particular path and name, or by referring to a classic PKCS#11 trust module provided by the NSS cryptographic library.
The dynamic configuration feature provides functionally compatible replacements for classic configuration files and for the classic NSS trust module named libnssckbi.
In order to enable legacy applications, that read the classic files or access the classic module, to make use of the new consolidated and dynamic configuration feature, the classic filenames have been changed to symbolic links. The symbolic links refer to dynamically created and consolidated output stored below the /etc/pki/ca-trust/extracted directory hierarchy.
The output is produced using the update-ca-trust command (without parameters), or using the update-ca-trust extract command. In order to produce the output, a flexible set of source configuration is read, as described in section SOURCE CONFIGURATION.
The dynamic configuration feature uses several source directories that will be scanned for any number of source files. It is important to select the correct subdirectory for adding files, as the subdirectory defines how contained certificates will be trusted or distrusted, and which file formats are read.
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.
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:
QUICK HELP 1: To add a certificate in the simple PEM or DER file formats to the list of CAs trusted on the system:
QUICK HELP 2: If your certificate is in the extended BEGIN TRUSTED file format (which may contain distrust/blacklist trust flags, or trust flags for usages other than TLS) then:
In order to offer simplicity and flexibility, the way certificate files are treated depends on the subdirectory they are installed to.
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:
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.
In the blacklist subdirectories /usr/share/pki/ca-trust-source/blacklist/ or /etc/pki/ca-trust/source/blacklist/ 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.
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. 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/ .
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.
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.
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.
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.
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.
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.
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.
Written by Kai Engert and Stef Walter.