ca-certificates/README.usr

This directory /usr/share/pki/ca-trust-source/ contains CA certificates and 
trust settings in the PEM file format. The trust settings found here will be
interpreted with a low priority - lower than the ones found in 
/etc/pki/ca-trust/source/ .

=============================================================================
QUICK HELP: To add a certificate in the simple PEM or DER file formats to the
            list of CAs trusted on the system:

            Copy it to the
                    /usr/share/pki/ca-trust-source/anchors/
            subdirectory, and run the
                    update-ca-trust
            command.

            If your certificate is in the extended BEGIN TRUSTED file format,
            then place it into the main source/ directory instead.
=============================================================================

Description of the source directory and its subdirectories:
-----------------------------------------------------------
In order to offer simplicity and flexibility, the way certificate files
are treated depend on the subdirectory they are installed to.

  trust anchors subdirectory : /usr/share/pki/ca-trust-source/anchors/
  extended format directory  : /usr/share/pki/ca-trust-source/
  blacklist subdirectory     : /usr/share/pki/ca-trust-source/blacklist/

In the main directory /usr/share/pki/ca-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
  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 an example of a distrusted certificate, see the files
   shipped with the ca-certificates 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 copy it to the 
   ./anchors subdirectory instead.)

In the anchors subdirectory: /usr/share/pki/ca-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 subdirectory: /usr/share/pki/ca-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.


Purpose:
--------
Applications that are able to use PKCS#11 modules can load the 
p11-kit-trust.so module and will benefit from the dynamically merged
set of certificates and trust information stored in the
/usr/share/pki/ca-trust-source/ and /etc/pki/ca-trust/source/
directories.

Applications that rely on a static file for a list of trusted CAs
may load one of the files found in the /etc/pki/ca-trust/extracted
directory. After modifying any file stored in the
/usr/share/pki/ca-trust-source/ or /etc/pki/ca-trust/source/
directories, it is required to run the update-ca-trust command,
in order to update the merged files in /etc/pki/ca-trust/extracted/ .