diff options
Diffstat (limited to 'doc/manual/p11-kit-trust.xml')
| -rw-r--r-- | doc/manual/p11-kit-trust.xml | 112 |
1 files changed, 112 insertions, 0 deletions
diff --git a/doc/manual/p11-kit-trust.xml b/doc/manual/p11-kit-trust.xml new file mode 100644 index 0000000..0e06446 --- /dev/null +++ b/doc/manual/p11-kit-trust.xml @@ -0,0 +1,112 @@ +<?xml version="1.0"?> +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ +]> +<chapter xml:id="trust"> +<title>Trust Policy Module</title> + + <para>The trust module provides system certificate anchors, blacklists + and other trust policy to crypto libraries applications. This + information is exposed as PKCS#11 objects.</para> + +<section id="trust-files"> + <title>Files loaded by the Module</title> + + <para>The trust module loads certificates and trust policy information + from preconfigured directories and allows them to be looked up via + PKCS#11. The directories can be determined with using the following + commands:</para> + + <itemizedlist> + <listitem> + <para>System Anchors: certificates in these locations + are automatically treated as certificate authority anchors + unless they contain information that prevents that. To check + which locations are being used, run the following command:</para> +<programlisting> +$ pkg-config --variable p11_system_anchors p11-kit-1 +/etc/pki/tls/certs/ca-bundle.trust.crt:/etc/pki/tls/anchors +</programlisting> + </listitem> + <listitem> + <para>System Certificates: certificates in these locations + are not treated as anchors, but simply made available through + the module. To find out which directory is used, run the + following command:</para> +<programlisting> +$ pkg-config --variable p11_system_certificates p11-kit-1 +/etc/pki/tls/other-certs +</programlisting> + </listitem> + </itemizedlist> + + <para>Files in the following formats are supported for loading by the + trust policy module:</para> + + <variablelist> + <varlistentry> + <term>X.509 certificates</term> + <listitem><para>X.509 certificates in raw DER format.</para></listitem> + </varlistentry> + <varlistentry> + <term>OpenSSL trust certificates</term> + <listitem><para>OpenSSL specific certificates in PEM format + that contain trust information. These have a + <literal>TRUSTED CERTIFICATE</literal> PEM header. Both + trust policy and blacklist information can be loaded + from these files.</para></listitem> + </varlistentry> + </variablelist> +</section> + +<section id="trust-nss"> + <title>Using the Trust Policy Module with NSS</title> + + <para>The trust policy module is a drop in replacement for the + <literal>libnssckbi.so</literal> module and thus works out of + the box with NSS. The trust policy module provides NSS style + PKCS#11 trust objects for NSS to retrieve.</para> + + <para>The module may be used to replace the + <literal>libnssckbi.so</literal> file via an distribution + specific alternatives mechanism or otherwise.</para> + + <para>Alternatively NSS applications like Firefox or Thunderbird + may be configured to use the trust policy module by adding + the <literal>p11-kit-trust.so</literal> PKCS#11 module via their + GUI or command line configuration.</para> +</section> + +<section id="trust-glib-networking"> + <title>Using the Trust Policy Module with glib-networking</title> + + <para>The trust policy module can be used as a source of trust + information for glib-networking's <literal>gnutls-pkcs11</literal> backend. + The module provides PKCS#11 trust assertion objects as expected.</para> + + <para>The module should work by default if the <literal>gnutls-pkcs11</literal> + backend is selected as the glib-networking TLS backend.</para> +</section> + +<section id="trust-disable"> + <title>Disabling the Trust Policy Module</title> + + <para>This module is installed and enabled by default. It may + be disabled in the following ways:</para> + + <itemizedlist> + <listitem><para>Use the <option>--disable-trust-module</option> + during the <link linkend="devel-building-configure">p11-kit + build</link>.</para></listitem> + <listitem><para>Disable loading trust policy information + from this module by adding a file to <literal>/etc/pkcs11/modules</literal> + called <literal>p11-kit-trust.module</literal> containing a + <literal>trust-policy:</literal> line.</para></listitem> + <listitem><para>Disable this module completely by + adding a file to <literal>/etc/pkcs11/modules</literal> + called <literal>p11-kit-trust.module</literal> containing a + <literal>enable-in:</literal> line.</para></listitem> + </itemizedlist> + +</section> + +</chapter> |