1UPDATE-CA-TRUST(8)                                          UPDATE-CA-TRUST(8)
2
3
4

NAME

6       update-ca-trust - manage consolidated and dynamic configuration of CA
7       certificates and associated trust
8

SYNOPSIS

10       update-ca-trust [COMMAND]
11

DESCRIPTION

13       update-ca-trust(8) is used to manage a consolidated and dynamic
14       configuration feature of Certificate Authority (CA) certificates and
15       associated trust.
16
17       The feature is available for new applications that read the
18       consolidated configuration files found in the
19       /etc/pki/ca-trust/extracted directory or that load the PKCS#11 module
20       p11-kit-trust.so
21
22       Parts of the new feature are also provided in a way to make it useful
23       for legacy applications.
24
25       Many legacy applications expect CA certificates and trust configuration
26       in a fixed location, contained in files with particular path and name,
27       or by referring to a classic PKCS#11 trust module provided by the NSS
28       cryptographic library.
29
30       The dynamic configuration feature provides functionally compatible
31       replacements for classic configuration files and for the classic NSS
32       trust module named libnssckbi.
33
34       In order to enable legacy applications, that read the classic files or
35       access the classic module, to make use of the new consolidated and
36       dynamic configuration feature, the classic filenames have been changed
37       to symbolic links. The symbolic links refer to dynamically created and
38       consolidated output stored below the /etc/pki/ca-trust/extracted
39       directory hierarchy.
40
41       The output is produced using the update-ca-trust command (without
42       parameters), or using the update-ca-trust extract command. In order to
43       produce the output, a flexible set of source configuration is read, as
44       described in section SOURCE CONFIGURATION.
45
46       In addition, the classic PKCS#11 module is replaced with a new PKCS#11
47       module (p11-kit-trust.so) that dynamically reads the same source
48       configuration.
49

SOURCE CONFIGURATION

51       The dynamic configuration feature uses several source directories that
52       will be scanned for any number of source files. It is important to
53       select the correct subdirectory for adding files, as the subdirectory
54       defines how contained certificates will be trusted or distrusted, and
55       which file formats are read.
56
57       Files in subdirectories below the directory hierarchy
58       /usr/share/pki/ca-trust-source/ contain CA certificates and trust
59       settings in the PEM file format. The trust settings found here will be
60       interpreted with a low priority.
61
62       Files in subdirectories below the directory hierarchy
63       /etc/pki/ca-trust/source/ contain CA certificates and trust settings in
64       the PEM file format. The trust settings found here will be interpreted
65       with a high priority.
66
67       You may use the following rules of thumb to decide, whether your
68       configuration files should be added to the /etc or rather to the /usr
69       directory hierarchy:
70
71       ·   If you are manually adding a configuration file to a system, you
72           probably want it to override any other default configuration, and
73           you most likely should add it to the respective subdirectory in the
74           /etc hierarchy.
75
76       ·   If you are creating a package that provides additional root CA
77           certificates, that is intended for distribution to several computer
78           systems, but you still want to allow the administrator to override
79           your list, then your package should add your files to the
80           respective subdirectory in the /usr hierarchy.
81
82       ·   If you are creating a package that is supposed to override the
83           default system trust settings, that is intended for distribution to
84           several computer systems, then your package should install the
85           files to the respective subdirectory in the /etc hierarchy.
86
87       QUICK HELP 1: To add a certificate in the simple PEM or DER file
88       formats to the list of CAs trusted on the system:
89
90       ·   add it as a new file to directory /etc/pki/ca-trust/source/anchors/
91
92       ·   run update-ca-trust extract
93
94       QUICK HELP 2: If your certificate is in the extended BEGIN TRUSTED file
95       format (which may contain distrust/blacklist trust flags, or trust
96       flags for usages other than TLS) then:
97
98       ·   add it as a new file to directory /etc/pki/ca-trust/source/
99
100       ·   run update-ca-trust extract
101
102       In order to offer simplicity and flexibility, the way certificate files
103       are treated depends on the subdirectory they are installed to.
104
105       ·   simple trust anchors subdirectory:
106           /usr/share/pki/ca-trust-source/anchors/ or
107           /etc/pki/ca-trust/source/anchors/
108
109       ·   simple blacklist (distrust) subdirectory:
110           /usr/share/pki/ca-trust-source/blacklist/ or
111           /etc/pki/ca-trust/source/blacklist/
112
113       ·   extended format directory: /usr/share/pki/ca-trust-source/ or
114           /etc/pki/ca-trust/source/
115
116       In the main directories /usr/share/pki/ca-trust-source/ or
117       /etc/pki/ca-trust/source/ you may install one or multiple files in the
118       following file formats:
119
120       ·   certificate files that include trust flags, in the BEGIN/END
121           TRUSTED CERTIFICATE file format (any file name), which have been
122           created using the openssl x509 tool and the -addreject -addtrust
123           options. Bundle files with multiple certificates are supported.
124
125       ·   files in the p11-kit file format using the .p11-kit file name
126           extension, which can (e.g.) be used to distrust certificates based
127           on serial number and issuer name, without having the full
128           certificate available. (This is currently an undocumented format,
129           to be extended later. For examples of the supported formats, see
130           the files shipped with the ca-certificates package.)
131
132       ·   certificate files without trust flags in either the DER file format
133           or in the PEM (BEGIN/END CERTIFICATE) file format (any file name).
134           Such files will be added with neutral trust, neither trusted nor
135           distrusted. They will simply be known to the system, which might be
136           helpful to assist cryptographic software in constructing chains of
137           certificates. (If you want a CA certificate in these file formats
138           to be trusted, you should remove it from this directory and move it
139           to the ./anchors subdirectory instead.)
140
141       In the anchors subdirectories /usr/share/pki/ca-trust-source/anchors/
142       or /etc/pki/ca-trust/source/anchors/ you may install one or multiple
143       certificates in either the DER file format or in the PEM (BEGIN/END
144       CERTIFICATE) file format. Each certificate will be treated as trusted
145       for all purposes.
146
147       In the blacklist subdirectories
148       /usr/share/pki/ca-trust-source/blacklist/ or
149       /etc/pki/ca-trust/source/blacklist/ you may install one or multiple
150       certificates in either the DER file format or in the PEM (BEGIN/END
151       CERTIFICATE) file format. Each certificate will be treated as
152       distrusted for all purposes.
153
154       Please refer to the x509(1) manual page for the documentation of the
155       BEGIN/END CERTIFICATE and BEGIN/END TRUSTED CERTIFICATE file formats.
156
157       Applications that rely on a static file for a list of trusted CAs may
158       load one of the files found in the /etc/pki/ca-trust/extracted
159       directory. After modifying any file in the
160       /usr/share/pki/ca-trust-source/ or /etc/pki/ca-trust/source/
161       directories or in any of their subdirectories, or after adding a file,
162       it is necessary to run the update-ca-trust extract command, in order to
163       update the consolidated files in /etc/pki/ca-trust/extracted/ .
164
165       Applications that load the classic PKCS#11 module using filename
166       libnssckbi.so (which has been converted into a symbolic link pointing
167       to the new module) and any application capable of loading PKCS#11
168       modules and loading p11-kit-trust.so, will benefit from the dynamically
169       merged set of certificates and trust information stored in the
170       /usr/share/pki/ca-trust-source/ and /etc/pki/ca-trust/source/
171       directories.
172

EXTRACTED CONFIGURATION

174       The directory /etc/pki/ca-trust/extracted/ contains generated CA
175       certificate bundle files which are created and updated, based on the
176       SOURCE CONFIGURATION by running the update-ca-trust extract command.
177
178       If your application isn’t able to load the PKCS#11 module
179       p11-kit-trust.so, then you can use these files in your application to
180       load a list of global root CA certificates.
181
182       Please never manually edit the files stored in this directory, because
183       your changes will be lost and the files automatically overwritten, each
184       time the update-ca-trust extract command gets executed.
185
186       In order to install new trusted or distrusted certificates, please
187       rather install them in the respective subdirectory below the
188       /usr/share/pki/ca-trust-source/ or /etc/pki/ca-trust/source/
189       directories, as described in the SOURCE CONFIGURATION section.
190
191       The directory /etc/pki/ca-trust/extracted/java/ contains a CA
192       certificate bundle in the java keystore file format. Distrust
193       information cannot be represented in this file format, and distrusted
194       certificates are missing from these files. File cacerts contains CA
195       certificates trusted for TLS server authentication.
196
197       The directory /etc/pki/ca-trust/extracted/openssl/ contains CA
198       certificate bundle files in the extended BEGIN/END TRUSTED CERTIFICATE
199       file format, as described in the x509(1) manual page. File
200       ca-bundle.trust.crt contains the full set of all trusted or distrusted
201       certificates, including the associated trust flags.
202
203       The directory /etc/pki/ca-trust/extracted/pem/ contains CA certificate
204       bundle files in the simple BEGIN/END CERTIFICATE file format, as
205       described in the x509(1) manual page. Distrust information cannot be
206       represented in this file format, and distrusted certificates are
207       missing from these files. File tls-ca-bundle.pem contains CA
208       certificates trusted for TLS server authentication. File
209       email-ca-bundle.pem contains CA certificates trusted for E-Mail
210       protection. File objsign-ca-bundle.pem contains CA certificates trusted
211       for code signing.
212
213       The directory /etc/pki/ca-trust/extracted/edk2/ contains a CA
214       certificate bundle ("cacerts.bin") in the "sequence of
215       EFI_SIGNATURE_LISTs" format, defined in the UEFI-2.7 specification,
216       sections "31.4.1 Signature Database" and "EFI_CERT_X509_GUID". Distrust
217       information cannot be represented in this file format, and distrusted
218       certificates are missing from these files. File "cacerts.bin" contains
219       CA certificates trusted for TLS server authentication.
220

COMMANDS

222       (absent/empty command)
223           Same as the extract command described below. (However, the command
224           may print fewer warnings, as this command is being run during rpm
225           package installation, where non-fatal status output is undesired.)
226
227       extract
228           Instruct update-ca-trust to scan the SOURCE CONFIGURATION and
229           produce updated versions of the consolidated configuration files
230           stored below the /etc/pki/ca-trust/extracted directory hierarchy.
231

FILES

233       /etc/pki/tls/certs/ca-bundle.crt
234           Classic filename, file contains a list of CA certificates trusted
235           for TLS server authentication usage, in the simple BEGIN/END
236           CERTIFICATE file format, without distrust information. This file is
237           a symbolic link that refers to the consolidated output created by
238           the update-ca-trust command.
239
240       /etc/pki/tls/certs/ca-bundle.trust.crt
241           Classic filename, file contains a list of CA certificates in the
242           extended BEGIN/END TRUSTED CERTIFICATE file format, which includes
243           trust (and/or distrust) flags specific to certificate usage. This
244           file is a symbolic link that refers to the consolidated output
245           created by the update-ca-trust command.
246
247       /etc/pki/java/cacerts
248           Classic filename, file contains a list of CA certificates trusted
249           for TLS server authentication usage, in the Java keystore file
250           format, without distrust information. This file is a symbolic link
251           that refers to the consolidated output created by the
252           update-ca-trust command.
253
254       /usr/share/pki/ca-trust-source
255           Contains multiple, low priority source configuration files as
256           explained in section SOURCE CONFIGURATION. Please pay attention to
257           the specific meanings of the respective subdirectories.
258
259       /etc/pki/ca-trust/source
260           Contains multiple, high priority source configuration files as
261           explained in section SOURCE CONFIGURATION. Please pay attention to
262           the specific meanings of the respective subdirectories.
263
264       /etc/pki/ca-trust/extracted
265           Contains consolidated and automatically generated configuration
266           files for consumption by applications, which are created using the
267           update-ca-trust extract command. Don’t edit files in this
268           directory, because they will be overwritten. See section EXTRACTED
269           CONFIGURATION for additional details.
270

AUTHOR

272       Written by Kai Engert and Stef Walter.
273
274
275
276update-ca-trust                   05/11/2019                UPDATE-CA-TRUST(8)
Impressum