<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
	"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
[
  <!ENTITY sysdir SYSTEM "sysdir.xml">
  <!ENTITY userdir SYSTEM "userdir.xml">
]>

<chapter xml:id="trust-module">
<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>

	<para>You can use the <link linkend="trust">trust</link> command line
	tool to examine and modify the trust policy store.</para>

<section id="trust-files">
	<title>Paths loaded by the Module</title>

	<para>The trust module loads certificates and trust policy information
	from preconfigured paths and allows them to be looked up via PKCS#11.
	The input paths can be determined with using the following command:</para>

<programlisting>
$ pkg-config --variable p11_trust_paths p11-kit-1
/usr/share/p11-kit/trust:/etc/pki/trust
</programlisting>

	<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. Does not
			automatically contain trust policy information.</para></listitem>
		</varlistentry>
		<varlistentry>
			<term>PEM certificates</term>
			<listitem><para>X.509 certificates in PEM format. These have a
			<literal>BEGIN CERTIFICATE</literal> header. This file does not
			automatically contain trust policy information.</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>BEGIN TRUSTED CERTIFICATE</literal> PEM header. Both
			trust anchor and blacklist information can be loaded
			from these files.</para></listitem>
		</varlistentry>
	</variablelist>

	<para>If the input path is a file, then it is loaded. Certificate(s) in the
	file are automatically treated as anchors, unless they contain alternate
	trust policy information.</para>

	<para>If the input path is a directory, files inside that directory are
	parsed and loaded. If the file contains trust policy information (such as the
	OpenSSL trust certificates) then it will be respected. Files without trust policy
	information are not automatically marked as an anchor or blacklisted.</para>

	<para>In addition two optional subdirectories of the input path are loaded. Files
	placed in the <literal>anchors/</literal> subdirectory become trust anchors
	when they do not contain trust policy information. Files placed in the
	<literal>blacklist/</literal> subdirectory are blacklisted whether they
	contain trust information or not.</para>

	<para>The first input path becomes the first PKCS#11 token of the trust
	module, and has the highest priority when callers search for trust
	policy information.</para>
</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>&sysdir;/modules</literal>
		called <literal>p11-kit-trust.module</literal> containing a
		<literal>trust-policy: no</literal> line.</para></listitem>

		<listitem><para>Disable this module completely by
		adding a file to <literal>&sysdir;/modules</literal>
		called <literal>p11-kit-trust.module</literal> containing a
		<literal>enable-in:</literal> line (without a value).</para></listitem>
	</itemizedlist>

</section>

</chapter>
