*.gcda
*.gcov
*~
+*.html
.deps
.libs
libtool
ltmain.sh
m4
+makefile
Makefile
Makefile.in
missing
-SUBDIRS = po module tests po
+SUBDIRS = module tests doc po
ACLOCAL_AMFLAGS = -I m4
module/p11-kit.pc
po/Makefile.in
tests/Makefile
+ doc/Makefile
])
AC_OUTPUT
--- /dev/null
+
+# p11-kit-glue.xml
+
+PARTS = \
+ p11-kit-config.xml \
+ p11-kit-multiple-problem.xml
+
+BOOK = \
+ p11-kit.xml
+
+DOCUMENTS = \
+ html/p11-kit.html
+
+all-local: $(DOCUMENTS)
+
+html/p11-kit.html: $(BOOK) $(PARTS)
+ xmlto --skip-validation -vv html-nochunks -o html/ p11-kit.xml
+
+EXTRA_DIST = \
+ $(BOOK) \
+ $(PARTS) \
+ docbook-params.xsl
--- /dev/null
+<?xml version="1.0"?>
+<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+
+<!--
+ Parameters for DocBook transformation.
+
+ Copyright (C) 2009 Michael Leupold <lemma@confuego.org>
+
+ This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ License as published by the Free Software Foundation; either
+ version 2.1 of the License, or (at your option) any later version.
+
+ This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.
+
+ You should have received a copy of the GNU Lesser General Public
+ License along with this library; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+-->
+
+ <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl"/>
+
+ <xsl:param name="toc.max.depth">3</xsl:param>
+ <xsl:param name="generate.section.toc.level">0</xsl:param>
+ <xsl:param name="generate.toc">
+ book toc
+ part nop
+ chapter toc
+ </xsl:param>
+ <xsl:param name="html.stylesheet">style.css</xsl:param>
+ <xsl:param name="funcsynopsis.style">ansi</xsl:param>
+ <xsl:param name="funcsynopsis.decoration">1</xsl:param>
+ <xsl:param name="refentry.generate.name">0</xsl:param>
+ <xsl:param name="refentry.generate.title">1</xsl:param>
+
+</xsl:stylesheet>
--- /dev/null
+<?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="config">
+ <title>PKCS#11 Configuration</title>
+
+ <section id="config-introduction">
+ <title>Consistent configuration</title>
+
+ <para>In order for multiple applications on the user's desktop to use
+ PKCS#11 modules in a consistent manner, there must be a configuration
+ or registry to specify which modules to load and how to use them. The
+ PKCS#11 specification does not specify such a configuration standard.
+ </para>
+
+ <para>Because of the multi-library module initialization problem, use of
+ PKCS#11 modules must be coordinated within an application. p11-kit
+ provides that coordination. Since coordination is required, it follows
+ that p11-kit can also implement a consistent module configuration.
+ </para>
+ </section>
+
+ <section id="config-format">
+ <title>File format</title>
+
+ <para>A complete configuration consists of several files. These files are
+ text files. Since <literal>p11-kit</literal> is built to be used in all
+ sorts of environments and at very low levels of the software stack, we
+ cannot make use of high level configuration APIs that you may find on a
+ modern desktop.</para>
+
+ <para>Each setting in the config file is specified consists of a name and
+ a value. The name is a simple string consisting of characters and dashes.
+ The name consists of alpha numeric characters, dot, hyphen and
+ underscore.</para>
+
+ <para>The value is specified after the name on the same line, separated
+ from it by a a <literal>:</literal> colon. White space between the
+ name and value is ignored.</para>
+
+ <para>Blank lines are ignored. White space at the beginning or end of
+ lines is stripped. Lines that begin with a <literal>#</literal> character
+ are ignored as comments. Comments are not recognized when they come after
+ a value on a line.</para>
+
+ <para>A fictitious sample configuration file might look like:</para>
+
+ <programlisting>
+ name:value
+ # Here is a comment
+
+ setting.2: A long value with text.
+ x-custom : text
+ </programlisting>
+
+ </section>
+
+ <section id="config-module">
+ <title>Module Configuration</title>
+
+ <para>Each configured PKCS#11 module has its own config file. The
+ location(s) of these files are described below. Most importantly each
+ config file specifies the location of the PKCS#11 module to load. Each
+ module config file has the following fields:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>module</term>
+ <listitem><para>The absolute path to the PKCS#11 module to load.
+ This should include an extension line <literal>.so</literal></para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Other fields may be present, but it is recommended that field names
+ that are not specified in this document start with a <literal>x-</literal>
+ prefix.</para>
+ </section>
+
+ <section id="config-global">
+ <title>Global Configuration</title>
+
+ <para>A global configuration is also present. This file contains settings
+ that are not related to a single PKCS#11 module. The location(s) of the
+ global configuration are described below. The global configuration file
+ can contain the following fields:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>user-config</term>
+ <listitem><para>This will be equal to one of the following values:
+ <literal>none</literal>, <literal>merge</literal>,
+ <literal>override</literal>.</para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Other fields may be present, but it is recommended that field names
+ that are not specified in this document start with a <literal>x-</literal>
+ prefix.</para>
+ </section>
+
+ <section id="config-locations">
+ <title>Configuration Files</title>
+
+ <para>Each configured PKCS#11 module is has its own config file. These
+ files are placed in a directory. In addition a global config file exists.
+ There is a system configuration consisting of the various module config
+ files and a file for global configuration. Optionally each user can provide
+ additional configuration or override the system configuration.</para>
+
+ <para>The system global configuration file is in
+ <literal>/etc/pkcs11/pkcs11.conf</literal> and the user global
+ configuration file is in <literal>~/.pkcs11/pkcs11.conf</literal> in the
+ user's home directory.</para>
+
+ <para>
+ The module config files are located XXX>
+ </para>
+ </section>
+</chapter>
--- /dev/null
+<?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="sharing">
+ <title>Sharing PKCS#11 modules</title>
+
+ <section xml:id="sharing-problem">
+ <title>Multiple consumers of PKCS#11 in a process</title>
+
+ <para>As more and more applications and libraries use PKCS#11 we run
+ into a very basic problem. The PKCS#11 modules cannot be initialized and
+ finalized properly without coordination between the various consumers.
+ </para>
+
+ <para>An example: An application might use GnuTLS for
+ TLS connections, and use libgcr for display of certificates. Both of
+ these want to load (and initialze) the same PKCS#11 modules. There are
+ many places where this situation occurs, including large applications
+ like Evolution which due to their dependencies end up using both NSS and
+ GnuTLS.</para>
+
+ <para>Consumer A loads a PKCS#11 module and uses the module's
+ C_Initialize function to initialize it, which works as expected.
+ When consumer B initializes the module (also using C_Initialize),
+ the error code <literal>CKR_CRYPTOKI_ALREADY_INITIALIZED</literal>
+ is correctly returned. This is normal PKCS#11 specification
+ defined behavior for when a module is initalized twice in the
+ same process. If consumer B is aware of this situation they may
+ choose to ignore this error code.</para>
+
+ <para>However when the consumer A is done with its use of the
+ PKCS#11 module it finalizes the module using the module's
+ C_Finalize function. This is expected of a well behaved PKCS#11
+ consumer. This then causes errors and/or crashes for consumer B,
+ which cannot know that the module has now been finalized out
+ from underneath it.</para>
+
+ <para>It is necessary for the two consumers to coordinate their
+ initialization and finalization in some fashion. In
+ <literal>p11-kit</literal> we provide this coordination in a
+ loosely coupled, backwards compatible, and flexible way.</para>
+ </section>
+
+ <section xml:id="sharing-initialize">
+ <title>Solution: p11-kit</title>
+
+ <para><literal>p11-kit</literal> provides functions to
+ coordinate initialization and finalization of any PKCS#11
+ module. A module may be initialized any number of times using
+ the p11_kit_initialize_module() function. The first time that
+ p11_kit_initialize_module() is called for a module, that module's
+ C_Initialize function is used. Later invocations for the same
+ module cause p11-kit to increment an internal initialization
+ count, rather than calling C_Initialize again.</para>
+
+ <para>The p11_kit_finalize_module() is used to finalize a module.
+ Each time it is called it decrements the internal initialization
+ count for that module. When the internal initialization count
+ reaches zero, the module's C_Finalize function is called.</para>
+
+ <para>This is done in a thread-safe manner. These functions can
+ be used on modules that the consumer loads themselves.</para>
+ </section>
+
+ <section xml:id="sharing-module">
+ <title>Solution: proxy module</title>
+
+ <para>When an application is aware of the fact that coordination
+ is necessary between multiple consumers of a PKCS#11 module, it
+ can link to p11-kit and use the functions there to provide
+ this coordination.</para>
+
+ <para>However most current consumers of PKCS#11 are ignorant of
+ this problem, and do not link to p11-kit. In order to solve this
+ multiple initialization problem for all applications,
+ <literal>p11-kit</literal> provides a proxy compatibility
+ module.</para>
+
+ <para>This proxy module acts like a normal PKCS#11 module, but
+ internally loads a preconfigured set of PKCS#11 modules and
+ coordinates their initialization and finalization. Each slot
+ in the configured modules is exposed as a slot of the
+ <literal>p11-kit</literal> proxy module. The proxy module is
+ then used as a normal PKCS#11 module would be. It can be loaded by
+ crypto libraries like NSS and behaves as expected.</para>
+
+ <para>The proxy module bends the PKCS#11 rules slightly. It does
+ not return the <literal>CKR_CRYPTOKI_ALREADY_INITIALIZED</literal>
+ error code as specified in PKCS#11. However this is a small
+ price to pay for this compatibility.</para>
+ </section>
+</chapter>
--- /dev/null
+<?xml version="1.0"?>
+<book xml:id="index" xmlns="http://docbook.org/ns/docbook" version="5.0">
+
+ <xi:include href="p11-kit-multiple-problem.xml" xmlns:xi="http://www.w3.org/2001/XInclude">
+ <xi:fallback/>
+ </xi:include>
+ <xi:include href="p11-kit-config.xml" xmlns:xi="http://www.w3.org/2001/XInclude">
+ <xi:fallback/>
+ </xi:include>
+
+</book>
\ No newline at end of file
projects / p11-kit / commitdiff