UPDATE-CA-TRUST(8) update-ca-trust UPDATE-CA-TRUST(8)
NAME
update-ca-trust - manage consolidated and dynamic configuration of CA
certificates and associated trust
SYNOPSIS
update-ca-trust [COMMAND]
DESCRIPTION
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
This manual page is specific to the series of RHEL 6 releases, which
implements this configuration as an optional feature 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 can optionally provide functionally
compatible replacements for classic configuration files and for the
classic NSS trust module named libnssckbi.
By default, the replacements are disabled, the classic file locations
are kept as static files, and the classic PKCS#11 module filename still
refers to the classic module provided by the NSS cryptographic library.
In order to enable legacy applications, that read the classic files or
access the classic module name, to make use of the new consolidated and
dynamic configuration feature, the compatible replacements can be
enabled using the update-ca-trust enable command.
When enabled, the classic filenames are changed to symbolic links. The
symbolic links will 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.
In addition, if the replacements are enabled, the classic PKCS#11
module is replaced by a new PKCS#11 module (p11-kit-trust.so) that
dynamically reads the same source configuration.
Use the update-ca-trust check command to display the enabled or
disabled state of the compatible replacements.
On computer systems that used modified copies of the classic
configuration files, prior to enabling the compatible replacements, a
manual migration of the system’s CA and trust configuration
modifications is required. It is advisable to compare the active
configuration with the original configuration that had been used as a
base for the modified copies, because software active on the system may
depend on past modifications to the classic configuration files.
Alternatively, on a system with modified copies of the classic
configuration files, you may accept to lose any past configuration
modifications and forcefully switch to the most recent set of standard
CA certificates and trust, using the update-ca-trust force-enable
command.
When using the update-ca-trust enable or update-ca-trust force-enable
commands, backups of the classic configuration files will be created in
the /etc/pki/backup-traditional-original-config (on the first
execution) and /etc/pki/backup-traditional-recent-config (on the first
on all subsequent executions) directories. The backup files will be
restored when disabling the compatible replacements using the
update-ca-trust disable or update-ca-trust force-disable commands.
DISABLED OR ENABLED COMPATIBLE REPLACEMENTS
When disabled (default):
• classic configuration files containing CA trust bundles in the PEM
or JAVA keystore file formats are still being used
• the classic PKCS#11 module named libnssckbi.so, which provides CA
trust and distrust information, primarily used by applications that
use the NSS cryptographic library, still refers to the classic
module provided by the NSS cryptographic library.
When enabled:
• classic configuration files containing CA trust bundles in the PEM
or JAVA keystore file formats are replaced with symbolic links that
resolve to consolidated and dynamically updated files below the
/etc/pki/ca-trust/extracted directory hierarchy.
• the classic PKCS#11 module named libnssckbi.so, which provides CA
trust and distrust information, primarily used by applications that
use the NSS cryptographic library, refers to the replacement
p11-kit-trust.so module
The classic filenames and the classic PKCS#11 module mentioned above
are:
• /etc/pki/tls/cert.pem
• /etc/pki/tls/certs/ca-bundle.crt
• /etc/pki/tls/certs/ca-bundle.trust.crt
• /usr/lib/libnssckbi.so
• /usr/lib64/libnssckbi.so
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:
• 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/blacklist 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
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 blacklist (distrust) subdirectory:
/usr/share/pki/ca-trust-source/blacklist/ or
/etc/pki/ca-trust/source/blacklist/
• 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.
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/ .
Legacy applications that rely on classic filenames benefit from
configuration updates only if the functionally compatible replacements
are enabled.
Applications that use the classic PKCS#11 module libnssckbi.so on a
system with enabled compatible replacements, 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.
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
decribed 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.
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.)
check
Report consistency status, and whether the compatible CA trust
replacements are currently enabled or disabled.
disable
Check the consistency status, and if no problems are detected,
disable the compatible CA trust replacements, thereby reverting to
the classic configuration. Restores previously backuped classic
configuration files.
enable
Check the consistency status, and if no problems are detected,
enable the compatible CA trust replacements. Backup copies of
classic configuration files will be created.
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.
force-enable
Enable the compatible CA trust replacements regardless of
inconsistencies. Backup copies of classic configuration files will
be created.
force-disable
Disable the compatible CA trust replacements regardless of
inconsistencies, thereby reverting to the classic configuration.
Restores previously backuped classic configuration files.
FILES
/etc/pki/tls/certs/ca-bundle.crt
Legacy 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. If
compatible CA trust replacements are disabled, this is a static
file and will remain unchanged. Only if compatible CA trust
replacements are enabled, this file is a symbolic link that refers
to the consolidated output created by the update-ca-trust command.
/etc/pki/tls/certs/ca-bundle.trust.crt
Legacy 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. If
compatible CA trust replacements are disabled, this is a static
file and will remain unchanged. Only if compatible CA trust
replacements are enabled, this file is a symbolic link that refers
to the consolidated output created by the update-ca-trust command.
/etc/pki/java/cacerts
Legacy filename, file contains a list of CA certificates trusted
for TLS server authentication usage, in the Java keystore file
format, without distrust information. If compatible CA trust
replacements are disabled, this is a static file and will remain
unchanged. Only if compatible CA trust replacements are enabled,
this file is a symbolic link that refers to the consolidated output
created by the update-ca-trust command.
/usr/share/pki/ca-trust-source
Contains multiple, low priority source configuration files as
explained in section 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 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 EXTRACTED
CONFIGURATION for additional details.
AUTHOR
Written by Kai Engert and Stef Walter.
update-ca-trust 09/03/2013 UPDATE-CA-TRUST(8)