332 lines
17 KiB
Plaintext
332 lines
17 KiB
Plaintext
////
|
|
Copyright (C) 2013 Red Hat, Inc.
|
|
|
|
This program is free software; you can redistribute it and/or modify
|
|
it under the terms of the GNU General Public License as published by
|
|
the Free Software Foundation; either version 2 of the License, or
|
|
(at your option) any later version.
|
|
|
|
This program is distributed in the hope that it will be useful,
|
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
GNU General Public License for more details.
|
|
////
|
|
|
|
|
|
update-ca-trust(8)
|
|
==================
|
|
:doctype: manpage
|
|
:man source: update-ca-trust
|
|
|
|
|
|
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 <<sourceconf,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
|
|
|
|
|
|
[[sourceconf]]
|
|
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.
|
|
|
|
|
|
[[extractconf]]
|
|
EXTRACTED CONFIGURATION
|
|
-----------------------
|
|
The directory /etc/pki/ca-trust/extracted/ contains generated CA certificate
|
|
bundle files which are created and updated, based on the <<sourceconf,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 <<sourceconf,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.
|
|
|
|
|
|
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 <<sourceconf,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 <<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.
|
|
|
|
AUTHOR
|
|
------
|
|
Written by Kai Engert and Stef Walter.
|
