The start of some documentation.

8 files changed, 287 insertions, 1 deletions

diff --git a/.gitignore b/.gitignore
index 601cff0..7549859 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,6 +6,7 @@
 *.gcda
 *.gcov
 *~
+*.html
 
 .deps
 .libs
@@ -30,6 +31,7 @@ INSTALL
 libtool
 ltmain.sh
 m4
+makefile
 Makefile
 Makefile.in
 missing
diff --git a/Makefile.am b/Makefile.am
index 1d42904..e8f0c0c 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -1,5 +1,5 @@
 
-SUBDIRS = po module tests po
+SUBDIRS = module tests doc po
 
 ACLOCAL_AMFLAGS = -I m4
 
diff --git a/configure.ac b/configure.ac
index 4cfc5d6..9f63f66 100644
--- a/configure.ac
+++ b/configure.ac
@@ -138,6 +138,7 @@ AC_CONFIG_FILES([Makefile
 		module/p11-kit.pc
 		po/Makefile.in
 		tests/Makefile
+		doc/Makefile
 		])
 AC_OUTPUT
 
diff --git a/doc/Makefile.am b/doc/Makefile.am
new file mode 100644
index 0000000..52c269b
--- /dev/null
+++ b/doc/Makefile.am
@@ -0,0 +1,22 @@
+
+# 	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
diff --git a/doc/docbook-params.xsl b/doc/docbook-params.xsl
new file mode 100644
index 0000000..5d8591a
--- /dev/null
+++ b/doc/docbook-params.xsl
@@ -0,0 +1,39 @@
+<?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>
diff --git a/doc/p11-kit-config.xml b/doc/p11-kit-config.xml
new file mode 100644
index 0000000..851f5dc
--- /dev/null
+++ b/doc/p11-kit-config.xml
@@ -0,0 +1,119 @@
+<?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>
diff --git a/doc/p11-kit-multiple-problem.xml b/doc/p11-kit-multiple-problem.xml
new file mode 100644
index 0000000..a1c19a7
--- /dev/null
+++ b/doc/p11-kit-multiple-problem.xml
@@ -0,0 +1,92 @@
+<?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>
diff --git a/doc/p11-kit.xml b/doc/p11-kit.xml
new file mode 100644
index 0000000..6231800
--- /dev/null
+++ b/doc/p11-kit.xml
@@ -0,0 +1,11 @@
+<?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