1UPDATE-CA-TRUST(8) UPDATE-CA-TRUST(8)
2
6 update-ca-trust - manage consolidated and dynamic configuration of CA
7 certificates and associated trust
8
10 update-ca-trust [COMMAND]
11
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 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 Parts of the new feature are also provided in a way to make it useful
23 for legacy applications.
24 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 The dynamic configuration feature provides functionally compatible
31 replacements for classic configuration files and for the classic NSS
32 trust module named libnssckbi.
33 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 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 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
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 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 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 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 • 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 • 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 • 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 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 • add it as a new file to directory /etc/pki/ca-trust/source/anchors/
91 • run update-ca-trust extract
93 QUICK HELP 2: If your certificate is in the extended BEGIN TRUSTED file
95 format (which may contain distrust/blocklist trust flags, or trust
96 flags for usages other than TLS) then:
97 • add it as a new file to directory /etc/pki/ca-trust/source/
99 • run update-ca-trust extract
101 In order to offer simplicity and flexibility, the way certificate files
103 are treated depends on the subdirectory they are installed to.
104 • simple trust anchors subdirectory:
106 /usr/share/pki/ca-trust-source/anchors/ or
107 /etc/pki/ca-trust/source/anchors/
108 • simple blocklist (distrust) subdirectory:
110 /usr/share/pki/ca-trust-source/blocklist/ or
111 /etc/pki/ca-trust/source/blocklist/
112 • extended format directory: /usr/share/pki/ca-trust-source/ or
114 /etc/pki/ca-trust/source/
115 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 • 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 • 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 • 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 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 In the blocklist subdirectories
148 /usr/share/pki/ca-trust-source/blocklist/ or
149 /etc/pki/ca-trust/source/blocklist/ 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 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 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 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
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 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 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 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 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 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 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 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
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 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
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 /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 /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 /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 /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 /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
272 Written by Kai Engert and Stef Walter.
273update-ca-trust 01/19/2022 UPDATE-CA-TRUST(8)