Blame SOURCES/update-ca-trust.8.txt

6cf4d9
////
6cf4d9
Copyright (C) 2013 Red Hat, Inc.
6cf4d9
6cf4d9
This program is free software; you can redistribute it and/or modify
6cf4d9
it under the terms of the GNU General Public License as published by
6cf4d9
the Free Software Foundation; either version 2 of the License, or
6cf4d9
(at your option) any later version.
6cf4d9
6cf4d9
This program is distributed in the hope that it will be useful,
6cf4d9
but WITHOUT ANY WARRANTY; without even the implied warranty of
6cf4d9
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
6cf4d9
GNU General Public License for more details.
6cf4d9
////
6cf4d9
6cf4d9
6cf4d9
update-ca-trust(8)
6cf4d9
==================
6cf4d9
:doctype: manpage
6cf4d9
:man source: update-ca-trust
6cf4d9
6cf4d9
6cf4d9
NAME
6cf4d9
----
6cf4d9
update-ca-trust - manage consolidated and dynamic configuration of CA 
6cf4d9
certificates and associated trust
6cf4d9
6cf4d9
6cf4d9
SYNOPSIS
6cf4d9
--------
6cf4d9
*update-ca-trust* ['COMMAND']
6cf4d9
6cf4d9
6cf4d9
DESCRIPTION
6cf4d9
-----------
6cf4d9
update-ca-trust(8) is used to manage a consolidated and dynamic configuration 
6cf4d9
feature of Certificate Authority (CA) certificates and associated trust.
6cf4d9
6cf4d9
The feature is available for new applications that read the
6cf4d9
consolidated configuration files found in the /etc/pki/ca-trust/extracted directory
6cf4d9
or that load the PKCS#11 module p11-kit-trust.so
6cf4d9
6cf4d9
Parts of the new feature are also provided in a way to make it useful
6cf4d9
for legacy applications.
6cf4d9
6cf4d9
Many legacy applications expect CA certificates and trust configuration
6cf4d9
in a fixed location, contained in files with particular path and name,
6cf4d9
or by referring to a classic PKCS#11 trust module provided by the 
6cf4d9
NSS cryptographic library.
6cf4d9
6cf4d9
The dynamic configuration feature provides functionally compatible replacements 
6cf4d9
for classic configuration files and for the classic NSS trust module named libnssckbi.
6cf4d9
6cf4d9
In order to enable legacy applications, that read the classic files or 
6cf4d9
access the classic module, to make use of the new consolidated and dynamic configuration 
6cf4d9
feature, the classic filenames have been changed to symbolic links.
6cf4d9
The symbolic links refer to dynamically created and consolidated 
6cf4d9
output stored below the /etc/pki/ca-trust/extracted directory hierarchy.
6cf4d9
6cf4d9
The output is produced using the 'update-ca-trust' command (without parameters),
6cf4d9
or using the 'update-ca-trust extract' command.
6cf4d9
In order to produce the output, a flexible set of source configuration
6cf4d9
is read, as described in section <<sourceconf,SOURCE CONFIGURATION>>.
6cf4d9
6cf4d9
In addition, the classic PKCS#11 module 
6cf4d9
is replaced with a new PKCS#11 module (p11-kit-trust.so) that dynamically 
6cf4d9
reads the same source configuration.
6cf4d9
6cf4d9
6cf4d9
[[sourceconf]]
6cf4d9
SOURCE CONFIGURATION
6cf4d9
--------------------
6cf4d9
The dynamic configuration feature uses several source directories that
6cf4d9
will be scanned for any number of source files. *It is important to select 
6cf4d9
the correct subdirectory for adding files, as the subdirectory defines how 
6cf4d9
contained certificates will be trusted or distrusted, and which file formats are read.*
6cf4d9
6cf4d9
Files in *subdirectories below the directory hierarchy /usr/share/pki/ca-trust-source/* contain CA certificates and 
6cf4d9
trust settings in the PEM file format. The trust settings found here will be
6cf4d9
interpreted with a *low priority*.
6cf4d9
6cf4d9
Files in *subdirectories below the directory hierarchy /etc/pki/ca-trust/source/* contain CA certificates and 
6cf4d9
trust settings in the PEM file format. The trust settings found here will be
6cf4d9
interpreted with a *high priority*.
6cf4d9
6cf4d9
.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:
6cf4d9
* If you are manually adding a configuration file to a system, you probably 
6cf4d9
want it to override any other default configuration, and you most likely should
6cf4d9
add it to the respective subdirectory in the /etc hierarchy.
6cf4d9
* If you are creating a package that provides additional root CA certificates,
6cf4d9
that is intended for distribution to several computer systems, but you still
6cf4d9
want to allow the administrator to override your list, then your package should 
6cf4d9
add your files to the respective subdirectory in the /usr hierarchy.
6cf4d9
* If you are creating a package that is supposed to override the default system
6cf4d9
trust settings, that is intended for distribution to several computer systems, then your package should install the files to the respective
6cf4d9
subdirectory in the /etc hierarchy.
6cf4d9
6cf4d9
.*QUICK HELP 1*: To add a certificate in the simple PEM or DER file formats to the list of CAs trusted on the system:
6cf4d9
* add it as a new file to directory /etc/pki/ca-trust/source/anchors/
6cf4d9
* run 'update-ca-trust extract'
6cf4d9
6cf4d9
.*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:
6cf4d9
* add it as a new file to directory /etc/pki/ca-trust/source/
6cf4d9
* run 'update-ca-trust extract'
6cf4d9
6cf4d9
.In order to offer simplicity and flexibility, the way certificate files are treated depends on the subdirectory they are installed to.
6cf4d9
* simple trust anchors subdirectory: /usr/share/pki/ca-trust-source/anchors/ or /etc/pki/ca-trust/source/anchors/
6cf4d9
* simple blacklist (distrust) subdirectory: /usr/share/pki/ca-trust-source/blacklist/ or /etc/pki/ca-trust/source/blacklist/
6cf4d9
* extended format directory: /usr/share/pki/ca-trust-source/ or /etc/pki/ca-trust/source/
6cf4d9
6cf4d9
.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:
6cf4d9
* certificate files that include trust flags,
6cf4d9
  in the BEGIN/END TRUSTED CERTIFICATE file format
6cf4d9
  (any file name), which have been created using the openssl x509 tool
6cf4d9
  and the -addreject -addtrust options.
6cf4d9
  Bundle files with multiple certificates are supported.
6cf4d9
* files in the p11-kit file format using the .p11-kit file name
6cf4d9
  extension, which can (e.g.) be used to distrust certificates
6cf4d9
  based on serial number and issuer name, without having the
6cf4d9
  full certificate available.
6cf4d9
  (This is currently an undocumented format, to be extended later.
6cf4d9
   For examples of the supported formats, see the files
6cf4d9
   shipped with the ca-certificates package.)
6cf4d9
* certificate files without trust flags in either the DER file format or in
6cf4d9
  the PEM (BEGIN/END CERTIFICATE) file format (any file name). Such files 
6cf4d9
  will be added with neutral trust, neither trusted nor distrusted.
6cf4d9
  They will simply be known to the system, which might be helpful to
6cf4d9
  assist cryptographic software in constructing chains of certificates.
6cf4d9
  (If you want a CA certificate in these file formats to be trusted, you 
6cf4d9
   should remove it from this directory and move it to the 
6cf4d9
   ./anchors subdirectory instead.)
6cf4d9
6cf4d9
In the anchors subdirectories /usr/share/pki/ca-trust-source/anchors/ or /etc/pki/ca-trust/source/anchors/
6cf4d9
you may install one or multiple certificates in either the DER file
6cf4d9
format or in the PEM (BEGIN/END CERTIFICATE) file format.
6cf4d9
Each certificate will be treated as *trusted* for all purposes.
6cf4d9
6cf4d9
In the blacklist subdirectories /usr/share/pki/ca-trust-source/blacklist/ or /etc/pki/ca-trust/source/blacklist/
6cf4d9
you may install one or multiple certificates in either the DER file
6cf4d9
format or in the PEM (BEGIN/END CERTIFICATE) file format.
6cf4d9
Each certificate will be treated as *distrusted* for all purposes.
6cf4d9
6cf4d9
Please refer to the x509(1) manual page for the documentation of the 
6cf4d9
BEGIN/END CERTIFICATE and BEGIN/END TRUSTED CERTIFICATE file formats.
6cf4d9
6cf4d9
Applications that rely on a static file for a list of trusted CAs
6cf4d9
may load one of the files found in the /etc/pki/ca-trust/extracted
6cf4d9
directory. After modifying any file in the
6cf4d9
/usr/share/pki/ca-trust-source/ or /etc/pki/ca-trust/source/
6cf4d9
directories or in any of their subdirectories, or after adding a file, 
6cf4d9
it is necessary to run the 'update-ca-trust extract' command,
6cf4d9
in order to update the consolidated files in /etc/pki/ca-trust/extracted/ .
6cf4d9
6cf4d9
Applications that load the classic PKCS#11 module using filename libnssckbi.so 
6cf4d9
(which has been converted into a symbolic link pointing to the new module)
6cf4d9
and any application capable of 
6cf4d9
loading PKCS#11 modules and loading p11-kit-trust.so, will benefit from
6cf4d9
the dynamically merged set of certificates and trust information stored in the
6cf4d9
/usr/share/pki/ca-trust-source/ and /etc/pki/ca-trust/source/ directories.
6cf4d9
6cf4d9
6cf4d9
[[extractconf]]
6cf4d9
EXTRACTED CONFIGURATION
6cf4d9
-----------------------
6cf4d9
The directory /etc/pki/ca-trust/extracted/ contains generated CA certificate 
6cf4d9
bundle files which are created and updated, based on the <<sourceconf,SOURCE CONFIGURATION>> 
6cf4d9
by running the 'update-ca-trust extract' command.
6cf4d9
6cf4d9
If your application isn't able to load the PKCS#11 module p11-kit-trust.so,
6cf4d9
then you can use these files in your application to load a list of global
6cf4d9
root CA certificates.
6cf4d9
6cf4d9
Please never manually edit the files stored in this directory,
6cf4d9
because your changes will be lost and the files automatically overwritten,
6cf4d9
each time the 'update-ca-trust extract' command gets executed.
6cf4d9
6cf4d9
In order to install new trusted or distrusted certificates,
6cf4d9
please rather install them in the respective subdirectory below the
6cf4d9
/usr/share/pki/ca-trust-source/ or /etc/pki/ca-trust/source/
6cf4d9
directories, as described in the <<sourceconf,SOURCE CONFIGURATION>> section.
6cf4d9
6cf4d9
The directory /etc/pki/ca-trust/extracted/java/ contains 
6cf4d9
a CA certificate bundle in the java keystore file format.
6cf4d9
Distrust information cannot be represented in this file format,
6cf4d9
and distrusted certificates are missing from these files.
6cf4d9
File cacerts contains CA certificates trusted for TLS server authentication.
6cf4d9
6cf4d9
The directory /etc/pki/ca-trust/extracted/openssl/ contains 
6cf4d9
CA certificate bundle files in the extended BEGIN/END TRUSTED CERTIFICATE file format, 
6cf4d9
as described in the x509(1) manual page.
6cf4d9
File ca-bundle.trust.crt contains the full set of all trusted
6cf4d9
or distrusted certificates, including the associated trust flags.
6cf4d9
6cf4d9
The directory /etc/pki/ca-trust/extracted/pem/ contains 
6cf4d9
CA certificate bundle files in the simple BEGIN/END CERTIFICATE file format, 
6cf4d9
as described in the x509(1) manual page.
6cf4d9
Distrust information cannot be represented in this file format,
6cf4d9
and distrusted certificates are missing from these files.
6cf4d9
File tls-ca-bundle.pem contains CA certificates 
6cf4d9
trusted for TLS server authentication.
6cf4d9
File email-ca-bundle.pem contains CA certificates 
6cf4d9
trusted for E-Mail protection.
6cf4d9
File objsign-ca-bundle.pem contains CA certificates 
6cf4d9
trusted for code signing.
6cf4d9
6cf4d9
The directory /etc/pki/ca-trust/extracted/edk2/ contains a CA
6cf4d9
certificate bundle ("cacerts.bin") in the "sequence of
6cf4d9
EFI_SIGNATURE_LISTs" format, defined in the UEFI-2.7 specification,
6cf4d9
sections "31.4.1 Signature Database" and
6cf4d9
"EFI_CERT_X509_GUID". Distrust information cannot be represented in
6cf4d9
this file format, and distrusted certificates are missing from these
6cf4d9
files. File "cacerts.bin" contains CA certificates trusted for TLS
6cf4d9
server authentication.
6cf4d9
6cf4d9
6cf4d9
COMMANDS
6cf4d9
--------
6cf4d9
(absent/empty command)::
6cf4d9
    Same as the *extract* command described below. (However, the command may
6cf4d9
    print fewer warnings, as this command is being run during rpm package 
6cf4d9
    installation, where non-fatal status output is undesired.)
6cf4d9
6cf4d9
*extract*::
6cf4d9
    Instruct update-ca-trust to scan the <<sourceconf,SOURCE CONFIGURATION>> and produce 
6cf4d9
    updated versions of the consolidated configuration files stored below
6cf4d9
    the /etc/pki/ca-trust/extracted directory hierarchy.
6cf4d9
6cf4d9
FILES
6cf4d9
-----
6cf4d9
/etc/pki/tls/certs/ca-bundle.crt::
6cf4d9
	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.
6cf4d9
	This file is a symbolic link that refers to the consolidated output created by the update-ca-trust command.
6cf4d9
6cf4d9
/etc/pki/tls/certs/ca-bundle.trust.crt::
6cf4d9
	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.
6cf4d9
	This file is a symbolic link that refers to the consolidated output created by the update-ca-trust command.
6cf4d9
6cf4d9
/etc/pki/java/cacerts::
6cf4d9
	Classic filename, file contains a list of CA certificates trusted for TLS server authentication usage, in the Java keystore file format, without distrust information.
6cf4d9
	This file is a symbolic link that refers to the consolidated output created by the update-ca-trust command.
6cf4d9
6cf4d9
/usr/share/pki/ca-trust-source::
6cf4d9
	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.
6cf4d9
6cf4d9
/etc/pki/ca-trust/source::
6cf4d9
	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.
6cf4d9
6cf4d9
/etc/pki/ca-trust/extracted::
6cf4d9
	Contains consolidated and automatically generated configuration files for consumption by applications, 
6cf4d9
	which are created using the 'update-ca-trust extract' command. Don't edit files in this directory, because they will be overwritten.
6cf4d9
	See section <<extractconf,EXTRACTED CONFIGURATION>> for additional details.
6cf4d9
6cf4d9
AUTHOR
6cf4d9
------
6cf4d9
Written by Kai Engert and Stef Walter.