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:
* 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/
.*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:
* extended format directory: /usr/share/pki/ca-trust-source/ or /etc/pki/ca-trust/source/
.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.)
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.
Classic filename, file contains a list of CA certificates trusted for TLS server authentication usage, in the simple BEGIN/END CERTIFICATE file format, without distrust information.
Classic filename, file contains 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.
Classic filename, file contains a list of CA certificates trusted for TLS server authentication usage, in the Java keystore file format, without distrust information.
Contains multiple, low priority source configuration files as explained in section <<sourceconf,SOURCE CONFIGURATION>>. Please pay attention to the specific meanings of the respective subdirectories.
/etc/pki/ca-trust/source::
Contains multiple, high priority source configuration files as explained in section <<sourceconf,SOURCE CONFIGURATION>>. Please pay attention to the specific meanings of the respective subdirectories.
/etc/pki/ca-trust/extracted::
Contains consolidated and automatically generated configuration files for consumption by applications,
which are created using the 'update-ca-trust extract' command. Don't edit files in this directory, because they will be overwritten.
See section <<extractconf,EXTRACTED CONFIGURATION>> for additional details.
