1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
|
////
Copyright (C) 2013 Red Hat, Inc.
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
////
update-ca-trust(8)
==================
:doctype: manpage
:man source: update-ca-trust
NAME
----
update-ca-trust - manage consolidated and dynamic configuration of CA
certificates and associated trust
SYNOPSIS
--------
*update-ca-trust* ['COMMAND']
DESCRIPTION
-----------
update-ca-trust(8) is used to manage a consolidated and dynamic configuration
feature of Certificate Authority (CA) certificates and associated trust.
The feature is available for new applications that read the
consolidated configuration files found in the /etc/ssl/certs or /etc/ca-certificates/extracted directories
or that load the PKCS#11 module p11-kit-trust.so
Parts of the new feature are also provided in a way to make it useful
for legacy applications.
Many legacy applications expect CA certificates and trust configuration
in a fixed location, contained in files with particular path and name,
or by referring to a classic PKCS#11 trust module provided by the
NSS cryptographic library.
The dynamic configuration feature provides functionally compatible replacements
for classic configuration files and for the classic NSS trust module named libnssckbi.
In order to enable legacy applications, that read the classic files or
access the classic module, to make use of the new consolidated and dynamic configuration
feature, some classic filenames have been changed to symbolic links.
The symbolic links refer to dynamically created and consolidated
output stored below the /etc/ca-certificates/extracted directory hierarchy.
The output is produced using the 'update-ca-trust' command (without parameters),
or using the 'update-ca-trust extract' command.
In order to produce the output, a flexible set of source configuration
is read, as described in section <<sourceconf,SOURCE CONFIGURATION>>.
In addition, the classic PKCS#11 module
is replaced with a new PKCS#11 module (p11-kit-trust.so) that dynamically
reads the same source configuration.
[[sourceconf]]
SOURCE CONFIGURATION
--------------------
The dynamic configuration feature uses several source directories that
will be scanned for any number of source files. *It is important to select
the correct subdirectory for adding files, as the subdirectory defines how
contained certificates will be trusted or distrusted, and which file formats are read.*
Files in subdirectories below the directory hierarchy /usr/share/ca-certificates/trust-source/ contain CA certificates and
trust settings in the PEM file format. The trust settings found here will be
interpreted with a *low priority*.
Files in subdirectories below the directory hierarchy /etc/ca-certificates/trust-source/ contain CA certificates and
trust settings in the PEM file format. The trust settings found here will be
interpreted with a *high priority*.
.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:
* If you are manually adding a configuration file to a system, you probably
want it to override any other default configuration, and you most likely should
add it to the respective subdirectory in the /etc hierarchy.
* If you are creating a package that provides additional root CA certificates,
that is intended for distribution to several computer systems, but you still
want to allow the administrator to override your list, then your package should
add your files to the respective subdirectory in the /usr hierarchy.
* If you are creating a package that is supposed to override the default system
trust settings, that is intended for distribution to several computer systems, then your package should install the files to the respective
subdirectory in the /etc hierarchy.
.*QUICK HELP 1*: To add a certificate in the simple PEM or DER file formats to the list of CAs trusted on the system:
* add it as a new file to directory /etc/ca-certificates/trust-source/anchors/
* run 'update-ca-trust extract'
.*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:
* add it as a new file to directory /etc/ca-certificates/trust-source/
* run 'update-ca-trust extract'
.In order to offer simplicity and flexibility, the way certificate files are treated depends on the subdirectory they are installed to.
* simple trust anchors subdirectory: /usr/share/ca-certificates/trust-source/anchors/ or /etc/ca-certificates/trust-source/anchors/
* simple blacklist (distrust) subdirectory: /usr/share/ca-certificates/trust-source/blacklist/ or /etc/ca-certificates/trust-source/blacklist/
* extended format directory: /usr/share/ca-certificates/trust-source/ or /etc/ca-certificates/trust-source/
.In the main directories /usr/share/ca-certificates/trust-source/ or /etc/ca-certificates/trust-source/ you may install one or multiple files in the following file formats:
* certificate files that include trust flags,
in the BEGIN/END TRUSTED CERTIFICATE file format
(any file name), which have been created using the openssl x509 tool
and the -addreject -addtrust options.
Bundle files with multiple certificates are supported.
* files in the p11-kit file format using the .p11-kit file name
extension, which can (e.g.) be used to distrust certificates
based on serial number and issuer name, without having the
full certificate available.
(This is currently an undocumented format, to be extended later.
For examples of the supported formats, see the files
shipped with the ca-certificates-mozilla package.)
* certificate files without trust flags in either the DER file format or in
the PEM (BEGIN/END CERTIFICATE) file format (any file name). Such files
will be added with neutral trust, neither trusted nor distrusted.
They will simply be known to the system, which might be helpful to
assist cryptographic software in constructing chains of certificates.
(If you want a CA certificate in these file formats to be trusted, you
should remove it from this directory and move it to the
./anchors subdirectory instead.)
In the anchors subdirectories /usr/share/ca-certificates/trust-source/anchors/ or /etc/ca-certificates/trust-source/anchors/
you may install one or multiple certificates in either the DER file
format or in the PEM (BEGIN/END CERTIFICATE) file format.
Each certificate will be treated as *trusted* for all purposes.
In the blacklist subdirectories /usr/share/ca-certificates/trust-source/blacklist/ or /etc/ca-certificates/trust-source/blacklist/
you may install one or multiple certificates in either the DER file
format or in the PEM (BEGIN/END CERTIFICATE) file format.
Each certificate will be treated as *distrusted* for all purposes.
Please refer to the x509(1) manual page for the documentation of the
BEGIN/END CERTIFICATE and BEGIN/END TRUSTED CERTIFICATE file formats.
Applications that rely on a static file for a list of trusted CAs
may load one of the files found in the /etc/ssl/certs or /etc/ca-certificates/extracted
directory. After modifying any file in the
/usr/share/ca-certificates/trust-source/ or /etc/ca-certificates/trust-source/
directories or in any of their subdirectories, or after adding a file,
it is necessary to run the 'update-ca-trust extract' command,
in order to update the consolidated files in /etc/ssl/certs or /etc/ca-certificates/extracted/ .
Applications that load the classic PKCS#11 module using filename libnssckbi.so
(which has been converted into a symbolic link pointing to the new module)
and any application capable of
loading PKCS#11 modules and loading p11-kit-trust.so, will benefit from
the dynamically merged set of certificates and trust information stored in the
/usr/share/ca-certificates/trust-source/ and /etc/ca-certificates/trust-source/ directories.
[[extractconf]]
EXTRACTED CONFIGURATION
-----------------------
The directories /etc/ssl/certs and /etc/ca-certificates/extracted/ contains generated CA certificate
bundle files which are created and updated, based on the <<sourceconf,SOURCE CONFIGURATION>>
by running the 'update-ca-trust extract' command.
If your application isn't able to load the PKCS#11 module p11-kit-trust.so,
then you can use these files in your application to load a list of global
root CA certificates.
Please never manually edit the files stored in these directories,
because your changes will be lost and the files automatically overwritten,
each time the 'update-ca-trust extract' command gets executed.
In order to install new trusted or distrusted certificates,
please rather install them in the respective subdirectory below the
/usr/share/ca-certificates/trust-source/ or /etc/ca-certificates/trust-source/
directories, as described in the <<sourceconf,SOURCE CONFIGURATION>> section.
The directory /etc/ssl/certs contains a OpenSSL-cadir-style hash farm.
Distrust information cannot be represented in this format,
and distrusted certificates are missing from these files.
The directory /etc/ssl/certs/java contains
a CA certificate bundle in the java keystore file format.
Distrust information cannot be represented in this file format,
and distrusted certificates are missing from these files.
File cacerts contains CA certificates trusted for TLS server authentication.
The directory /etc/ca-certificates/extracted contains
CA certificate bundle files in the simple BEGIN/END CERTIFICATE file format,
as decribed in the x509(1) manual page.
Distrust information cannot be represented in this file format,
and distrusted certificates are missing from these files.
File tls-ca-bundle.pem contains CA certificates
trusted for TLS server authentication.
File email-ca-bundle.pem contains CA certificates
trusted for E-Mail protection.
File objsign-ca-bundle.pem contains CA certificates
trusted for code signing.
File ca-bundle.trust.crt contains certificates in the extended
BEGIN/END TRUSTED CERTIFICATE file format, as described in the x509(1) manual page.
This bundle contains the full set of all trusted
and distrusted certificates, including the associated trust flags.
COMMANDS
--------
(absent/empty command)::
Same as the *extract* command described below. (However, the command may
print fewer warnings, as this command is being run during package
installation, where non-fatal status output is undesired.)
*extract*::
Instruct update-ca-trust to scan the <<sourceconf,SOURCE CONFIGURATION>> and produce
updated versions of the consolidated configuration files stored below
the /etc/ssl/certs and /etc/ca-certificates/extracted directory
hierarchies.
FILES
-----
/usr/share/ca-certificates/trust-source::
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.
/etc/ca-certificates/trust-source::
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.
/etc/ca-certificates/extracted::
Contains consolidated and automatically generated configuration files for consumption by applications,
which are created using the 'update-ca-trust extract' command. Don't edit files in this directory, because they will be overwritten.
See section <<extractconf,EXTRACTED CONFIGURATION>> for additional details.
/etc/ca-certificates/extracted/tls-ca-bundle.pem::
Contains a list of CA certificates trusted for TLS server authentication, in the simple BEGIN/END CERTIFICATE file format, without distrust information.
/etc/ca-certificates/extracted/email-ca-bundle.pem::
Contains a list of CA certificates trusted for E-Mail protection, in the simple BEGIN/END CERTIFICATE file format, without distrust information.
/etc/ca-certificates/extracted/objsign-ca-bundle.pem::
Contains a list of CA certificates trusted for code signing, in the simple BEGIN/END CERTIFICATE file format, without distrust information.
/etc/ca-certificates/extracted/ca-bundle.trust.crt::
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.
/etc/ca-certificates/extracted/cadir::
Contains individual CA certificates trusted for TLS server authentication usage, in the simple BEGIN/END CERTIFICATE file format, without distrust information.
Also includes the necessary hash symlinks expected by OpenSSL.
/etc/ssl/certs::
Classic directory, contains symlinks into /etc/ca-certificates/extracted/cadir which are maintained by the update-ca-trust command.
/etc/ssl/certs/ca-certificates.crt::
Classic filename, a symlink to /etc/ca-certificates/extracted/tls-ca-bundle.pem.
/etc/ssl/cert.pem::
Classic filename, a symlink to /etc/ca-certificates/extracted/tls-ca-bundle.pem.
/etc/ssl/java/cacerts::
Classic filename, contains a list of CA certificates trusted for TLS server authentication usage, in the Java keystore file format, without distrust information.
This file is consolidated output created by the update-ca-trust command.
AUTHOR
------
Written by Kai Engert and Stef Walter.
|
