blob: dde614cee4e3da01bb5c4427e9d2d9dbb8ee925f (
plain)
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
|
<?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>
|
