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