1UPDATE-CA-TRUST(8) update-ca-trust 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 This manual page is specific to the series of RHEL 6 releases, which
23 implements this configuration as an optional feature for legacy
24 applications.
25 Many legacy applications expect CA certificates and trust configuration
27 in a fixed location, contained in files with particular path and name,
28 or by referring to a classic PKCS#11 trust module provided by the NSS
29 cryptographic library.
30 The dynamic configuration feature can optionally provide functionally
32 compatible replacements for classic configuration files and for the
33 classic NSS trust module named libnssckbi.
34 By default, the replacements are disabled, the classic file locations
36 are kept as static files, and the classic PKCS#11 module filename still
37 refers to the classic module provided by the NSS cryptographic library.
38 In order to enable legacy applications, that read the classic files or
40 access the classic module name, to make use of the new consolidated and
41 dynamic configuration feature, the compatible replacements can be
42 enabled using the update-ca-trust enable command.
43 When enabled, the classic filenames are changed to symbolic links. The
45 symbolic links will refer to dynamically created and consolidated
46 output stored below the /etc/pki/ca-trust/extracted directory
47 hierarchy.
48 The output is produced using the update-ca-trust command (without
50 parameters), or using the update-ca-trust extract command. In order to
51 produce the output, a flexible set of source configuration is read, as
52 described in section SOURCE CONFIGURATION.
53 In addition, if the replacements are enabled, the classic PKCS#11
55 module is replaced by a new PKCS#11 module (p11-kit-trust.so) that
56 dynamically reads the same source configuration.
57 Use the update-ca-trust check command to display the enabled or
59 disabled state of the compatible replacements.
60 On computer systems that used modified copies of the classic
62 configuration files, prior to enabling the compatible replacements, a
63 manual migration of the system’s CA and trust configuration
64 modifications is required. It is advisable to compare the active
65 configuration with the original configuration that had been used as a
66 base for the modified copies, because software active on the system may
67 depend on past modifications to the classic configuration files.
68 Alternatively, on a system with modified copies of the classic
70 configuration files, you may accept to lose any past configuration
71 modifications and forcefully switch to the most recent set of standard
72 CA certificates and trust, using the update-ca-trust force-enable
73 command.
74 When using the update-ca-trust enable or update-ca-trust force-enable
76 commands, backups of the classic configuration files will be created in
77 the /etc/pki/backup-traditional-original-config (on the first
78 execution) and /etc/pki/backup-traditional-recent-config (on the first
79 on all subsequent executions) directories. The backup files will be
80 restored when disabling the compatible replacements using the
81 update-ca-trust disable or update-ca-trust force-disable commands.
82
84 When disabled (default):
85 · classic configuration files containing CA trust bundles in the PEM
87 or JAVA keystore file formats are still being used
88 · the classic PKCS#11 module named libnssckbi.so, which provides CA
90 trust and distrust information, primarily used by applications that
91 use the NSS cryptographic library, still refers to the classic
92 module provided by the NSS cryptographic library.
93 When enabled:
95 · classic configuration files containing CA trust bundles in the PEM
97 or JAVA keystore file formats are replaced with symbolic links that
98 resolve to consolidated and dynamically updated files below the
99 /etc/pki/ca-trust/extracted directory hierarchy.
100 · the classic PKCS#11 module named libnssckbi.so, which provides CA
102 trust and distrust information, primarily used by applications that
103 use the NSS cryptographic library, refers to the replacement
104 p11-kit-trust.so module
105 The classic filenames and the classic PKCS#11 module mentioned above
107 are:
108 · /etc/pki/tls/cert.pem
110 · /etc/pki/tls/certs/ca-bundle.crt
112 · /etc/pki/tls/certs/ca-bundle.trust.crt
114 · /usr/lib/libnssckbi.so
116 · /usr/lib64/libnssckbi.so
118
120 The dynamic configuration feature uses several source directories that
121 will be scanned for any number of source files. It is important to
122 select the correct subdirectory for adding files, as the subdirectory
123 defines how contained certificates will be trusted or distrusted, and
124 which file formats are read.
125 Files in subdirectories below the directory hierarchy
127 /usr/share/pki/ca-trust-source/ contain CA certificates and trust
128 settings in the PEM file format. The trust settings found here will be
129 interpreted with a low priority.
130 Files in subdirectories below the directory hierarchy
132 /etc/pki/ca-trust/source/ contain CA certificates and trust settings in
133 the PEM file format. The trust settings found here will be interpreted
134 with a high priority.
135 You may use the following rules of thumb to decide, whether your
137 configuration files should be added to the /etc or rather to the /usr
138 directory hierarchy:
139 · If you are manually adding a configuration file to a system, you
141 probably want it to override any other default configuration, and
142 you most likely should add it to the respective subdirectory in the
143 /etc hierarchy.
144 · If you are creating a package that provides additional root CA
146 certificates, that is intended for distribution to several computer
147 systems, but you still want to allow the administrator to override
148 your list, then your package should add your files to the
149 respective subdirectory in the /usr hierarchy.
150 · If you are creating a package that is supposed to override the
152 default system trust settings, that is intended for distribution to
153 several computer systems, then your package should install the
154 files to the respective subdirectory in the /etc hierarchy.
155 QUICK HELP 1: To add a certificate in the simple PEM or DER file
157 formats to the list of CAs trusted on the system:
158 · add it as a new file to directory /etc/pki/ca-trust/source/anchors/
160 · run update-ca-trust extract
162 QUICK HELP 2: If your certificate is in the extended BEGIN TRUSTED file
164 format (which may contain distrust/blacklist trust flags, or trust
165 flags for usages other than TLS) then:
166 · add it as a new file to directory /etc/pki/ca-trust/source/
168 · run update-ca-trust extract
170 In order to offer simplicity and flexibility, the way certificate files
172 are treated depends on the subdirectory they are installed to.
173 · simple trust anchors subdirectory:
175 /usr/share/pki/ca-trust-source/anchors/ or
176 /etc/pki/ca-trust/source/anchors/
177 · simple blacklist (distrust) subdirectory:
179 /usr/share/pki/ca-trust-source/blacklist/ or
180 /etc/pki/ca-trust/source/blacklist/
181 · extended format directory: /usr/share/pki/ca-trust-source/ or
183 /etc/pki/ca-trust/source/
184 In the main directories /usr/share/pki/ca-trust-source/ or
186 /etc/pki/ca-trust/source/ you may install one or multiple files in the
187 following file formats:
188 · certificate files that include trust flags, in the BEGIN/END
190 TRUSTED CERTIFICATE file format (any file name), which have been
191 created using the openssl x509 tool and the -addreject -addtrust
192 options. Bundle files with multiple certificates are supported.
193 · files in the p11-kit file format using the .p11-kit file name
195 extension, which can (e.g.) be used to distrust certificates based
196 on serial number and issuer name, without having the full
197 certificate available. (This is currently an undocumented format,
198 to be extended later. For examples of the supported formats, see
199 the files shipped with the ca-certificates package.)
200 · certificate files without trust flags in either the DER file format
202 or in the PEM (BEGIN/END CERTIFICATE) file format (any file name).
203 Such files will be added with neutral trust, neither trusted nor
204 distrusted. They will simply be known to the system, which might be
205 helpful to assist cryptographic software in constructing chains of
206 certificates. (If you want a CA certificate in these file formats
207 to be trusted, you should remove it from this directory and move it
208 to the ./anchors subdirectory instead.)
209 In the anchors subdirectories /usr/share/pki/ca-trust-source/anchors/
211 or /etc/pki/ca-trust/source/anchors/ you may install one or multiple
212 certificates in either the DER file format or in the PEM (BEGIN/END
213 CERTIFICATE) file format. Each certificate will be treated as trusted
214 for all purposes.
215 In the blacklist subdirectories
217 /usr/share/pki/ca-trust-source/blacklist/ or
218 /etc/pki/ca-trust/source/blacklist/ you may install one or multiple
219 certificates in either the DER file format or in the PEM (BEGIN/END
220 CERTIFICATE) file format. Each certificate will be treated as
221 distrusted for all purposes.
222 Please refer to the x509(1) manual page for the documentation of the
224 BEGIN/END CERTIFICATE and BEGIN/END TRUSTED CERTIFICATE file formats.
225 Applications that rely on a static file for a list of trusted CAs may
227 load one of the files found in the /etc/pki/ca-trust/extracted
228 directory. After modifying any file in the
229 /usr/share/pki/ca-trust-source/ or /etc/pki/ca-trust/source/
230 directories or in any of their subdirectories, or after adding a file,
231 it is necessary to run the update-ca-trust extract command, in order to
232 update the consolidated files in /etc/pki/ca-trust/extracted/ .
233 Legacy applications that rely on classic filenames benefit from
235 configuration updates only if the functionally compatible replacements
236 are enabled.
237 Applications that use the classic PKCS#11 module libnssckbi.so on a
239 system with enabled compatible replacements, and any application
240 capable of loading PKCS#11 modules and loading p11-kit-trust.so, will
241 benefit from the dynamically merged set of certificates and trust
242 information stored in the /usr/share/pki/ca-trust-source/ and
243 /etc/pki/ca-trust/source/ directories.
244
246 The directory /etc/pki/ca-trust/extracted/ contains generated CA
247 certificate bundle files which are created and updated, based on the
248 SOURCE CONFIGURATION by running the update-ca-trust extract command.
249 If your application isn’t able to load the PKCS#11 module
251 p11-kit-trust.so, then you can use these files in your application to
252 load a list of global root CA certificates.
253 Please never manually edit the files stored in this directory, because
255 your changes will be lost and the files automatically overwritten, each
256 time the update-ca-trust extract command gets executed.
257 In order to install new trusted or distrusted certificates, please
259 rather install them in the respective subdirectory below the
260 /usr/share/pki/ca-trust-source/ or /etc/pki/ca-trust/source/
261 directories, as described in the SOURCE CONFIGURATION section.
262 The directory /etc/pki/ca-trust/extracted/java/ contains a CA
264 certificate bundle in the java keystore file format. Distrust
265 information cannot be represented in this file format, and distrusted
266 certificates are missing from these files. File cacerts contains CA
267 certificates trusted for TLS server authentication.
268 The directory /etc/pki/ca-trust/extracted/openssl/ contains CA
270 certificate bundle files in the extended BEGIN/END TRUSTED CERTIFICATE
271 file format, as described in the x509(1) manual page. File
272 ca-bundle.trust.crt contains the full set of all trusted or distrusted
273 certificates, including the associated trust flags.
274 The directory /etc/pki/ca-trust/extracted/pem/ contains CA certificate
276 bundle files in the simple BEGIN/END CERTIFICATE file format, as
277 described in the x509(1) manual page. Distrust information cannot be
278 represented in this file format, and distrusted certificates are
279 missing from these files. File tls-ca-bundle.pem contains CA
280 certificates trusted for TLS server authentication. File
281 email-ca-bundle.pem contains CA certificates trusted for E-Mail
282 protection. File objsign-ca-bundle.pem contains CA certificates trusted
283 for code signing.
284
286 (absent/empty command)
287 Same as the extract command described below. (However, the command
288 may print fewer warnings, as this command is being run during rpm
289 package installation, where non-fatal status output is undesired.)
290 check
292 Report consistency status, and whether the compatible CA trust
293 replacements are currently enabled or disabled.
294 disable
296 Check the consistency status, and if no problems are detected,
297 disable the compatible CA trust replacements, thereby reverting to
298 the classic configuration. Restores previously backuped classic
299 configuration files.
300 enable
302 Check the consistency status, and if no problems are detected,
303 enable the compatible CA trust replacements. Backup copies of
304 classic configuration files will be created.
305 extract
307 Instruct update-ca-trust to scan the SOURCE CONFIGURATION and
308 produce updated versions of the consolidated configuration files
309 stored below the /etc/pki/ca-trust/extracted directory hierarchy.
310 force-enable
312 Enable the compatible CA trust replacements regardless of
313 inconsistencies. Backup copies of classic configuration files will
314 be created.
315 force-disable
317 Disable the compatible CA trust replacements regardless of
318 inconsistencies, thereby reverting to the classic configuration.
319 Restores previously backuped classic configuration files.
320
322 /etc/pki/tls/certs/ca-bundle.crt
323 Legacy filename, file contains a list of CA certificates trusted
324 for TLS server authentication usage, in the simple BEGIN/END
325 CERTIFICATE file format, without distrust information. If
326 compatible CA trust replacements are disabled, this is a static
327 file and will remain unchanged. Only if compatible CA trust
328 replacements are enabled, this file is a symbolic link that refers
329 to the consolidated output created by the update-ca-trust command.
330 /etc/pki/tls/certs/ca-bundle.trust.crt
332 Legacy filename, file contains a list of CA certificates in the
333 extended BEGIN/END TRUSTED CERTIFICATE file format, which includes
334 trust (and/or distrust) flags specific to certificate usage. If
335 compatible CA trust replacements are disabled, this is a static
336 file and will remain unchanged. Only if compatible CA trust
337 replacements are enabled, this file is a symbolic link that refers
338 to the consolidated output created by the update-ca-trust command.
339 /etc/pki/java/cacerts
341 Legacy filename, file contains a list of CA certificates trusted
342 for TLS server authentication usage, in the Java keystore file
343 format, without distrust information. If compatible CA trust
344 replacements are disabled, this is a static file and will remain
345 unchanged. Only if compatible CA trust replacements are enabled,
346 this file is a symbolic link that refers to the consolidated output
347 created by the update-ca-trust command.
348 /usr/share/pki/ca-trust-source
350 Contains multiple, low priority source configuration files as
351 explained in section SOURCE CONFIGURATION. Please pay attention to
352 the specific meanings of the respective subdirectories.
353 /etc/pki/ca-trust/source
355 Contains multiple, high priority source configuration files as
356 explained in section SOURCE CONFIGURATION. Please pay attention to
357 the specific meanings of the respective subdirectories.
358 /etc/pki/ca-trust/extracted
360 Contains consolidated and automatically generated configuration
361 files for consumption by applications, which are created using the
362 update-ca-trust extract command. Don’t edit files in this
363 directory, because they will be overwritten. See section EXTRACTED
364 CONFIGURATION for additional details.
365
367 Written by Kai Engert and Stef Walter.
368update-ca-trust 06/19/2018 UPDATE-CA-TRUST(8)