ca-certificates/trunk/update-ca-trust.8.txt

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