summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorStef Walter <stefw@gnome.org>2013-01-24 11:34:47 +0100
committerStef Walter <stefw@gnome.org>2013-02-05 14:54:46 +0100
commit5147d71466455b3d087b3f3a7472a35e8216c55a (patch)
tree4b81eee35b7d0ec877a34c4fde06478d700a3960 /doc
parent603c7d4eb996f51178ccc9d235597497bbb2c7a4 (diff)
Add basic trust module
This is based off the roots-store from gnome-keyring and loads certificates from a root directory and exposes them as PKCS#11 objects.
Diffstat (limited to 'doc')
-rw-r--r--doc/Makefile.am2
-rw-r--r--doc/p11-kit-config.xml10
-rw-r--r--doc/p11-kit-devel.xml24
-rw-r--r--doc/p11-kit-docs.sgml1
-rw-r--r--doc/p11-kit-trust.xml90
-rw-r--r--doc/style.css6
6 files changed, 132 insertions, 1 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 1846993..3154215 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -52,6 +52,7 @@ IGNORE_HFILES= \
dict.h \
mock-module.h \
pkcs11.h \
+ pkcs11x.h \
private.h \
util.h \
array.h \
@@ -66,6 +67,7 @@ HTML_IMAGES=
# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
content_files=p11-kit-config.xml p11-kit-sharing.xml \
p11-kit-devel.xml \
+ p11-kit-trust.xml \
p11-kit.xml \
$(NULL)
diff --git a/doc/p11-kit-config.xml b/doc/p11-kit-config.xml
index d35b112..da413e0 100644
--- a/doc/p11-kit-config.xml
+++ b/doc/p11-kit-config.xml
@@ -167,6 +167,16 @@ critical: yes
not present, then any process will load the module.</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term>trust-policy</term>
+ <listitem>
+ <para>If this setting is present then this module is used to load
+ trust policy information such as certificate anchors and black lists.
+ The value should be an integer. Modules with a lower number are loaded
+ first. Trust policy information in modules loaded later overrides
+ those loaded first.</para>
+ </listitem>
+ </varlistentry>
</variablelist>
<para>Do not specify both <literal>enable-in</literal> and <literal>disable-in</literal>
diff --git a/doc/p11-kit-devel.xml b/doc/p11-kit-devel.xml
index f2a1f58..f3acde1 100644
--- a/doc/p11-kit-devel.xml
+++ b/doc/p11-kit-devel.xml
@@ -131,6 +131,8 @@ $ make install
<listitem><para><command>xsltproc</command> is required to build the command
manual pages. Use <literal>--enable-doc</literal> to control this
dependency.</para></listitem>
+ <listitem><para><command>libtasn1</command> is required to build the trust
+ module and code that interacts with certificates.</para></listitem>
</itemizedlist>
</section>
@@ -143,6 +145,10 @@ $ make install
<variablelist>
<varlistentry>
+ <term><option>--disable-trust-module</option></term>
+ <listitem><para>Disables building of the trust policy module.</para></listitem>
+ </varlistentry>
+ <varlistentry>
<term><option>--disable-debug</option>, <option>--enable-debug</option></term>
<listitem><para>By default p11-kit is built with debug symbols assertions and
and precondition checks. Enabling the debug option configures even more
@@ -164,11 +170,29 @@ $ make install
compiler warnings become errors.</para></listitem>
</varlistentry>
<varlistentry>
+ <term><option>--with-libtasn1</option>, <option>--without-libtasn1</option></term>
+ <listitem><para>Build with a dependency on the libtasn1 library. This dependency
+ allows the trust policy module to be built as well as other code that interacts with
+ certificates.</para></listitem>
+ </varlistentry>
+ <varlistentry>
<term><option>--with-module-path</option></term>
<listitem><para>Specify the path to look for PKCS#11 modules which were
listed in a module config file with a relative path.</para></listitem>
</varlistentry>
<varlistentry>
+ <term><option>--with-system-anchors</option></term>
+ <listitem><para>Specify the files or directories to look for system
+ certificate anchors. Multiple files and/or directories are specified with
+ a <literal>:</literal> in between them.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--with-system-certificates</option></term>
+ <listitem><para>Specify the files or directories to look for other
+ non-anchor system certificates. Multiple files and/or directories are
+ specified with a <literal>:</literal> in between them.</para></listitem>
+ </varlistentry>
+ <varlistentry>
<term><option>--with-system-config</option></term>
<listitem><para>Specify the path to look for p11-kit config files. This
usually defaults to something like <literal>/etc/pkcs11</literal></para></listitem>
diff --git a/doc/p11-kit-docs.sgml b/doc/p11-kit-docs.sgml
index 2d3760a..5627f6f 100644
--- a/doc/p11-kit-docs.sgml
+++ b/doc/p11-kit-docs.sgml
@@ -13,6 +13,7 @@
<xi:include href="p11-kit-config.xml"/>
<xi:include href="p11-kit-sharing.xml"/>
+ <xi:include href="p11-kit-trust.xml"/>
<chapter xml:id="tools">
<title>Command Line Tools</title>
diff --git a/doc/p11-kit-trust.xml b/doc/p11-kit-trust.xml
new file mode 100644
index 0000000..7496f7b
--- /dev/null
+++ b/doc/p11-kit-trust.xml
@@ -0,0 +1,90 @@
+<?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>
+ </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 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-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>
diff --git a/doc/style.css b/doc/style.css
index e70190a..b4b8d47 100644
--- a/doc/style.css
+++ b/doc/style.css
@@ -99,10 +99,14 @@ DIV.toc DL {
margin-bottom: 0;
}
-DIV.toc > DL > DT {
+DIV.book > DIV.toc > DL > DT {
margin-top: 1em;
}
DIV.toc DT {
margin-bottom: 0.3em;
}
+
+TABLE.variablelist SPAN.term {
+ padding-right: 1em;
+}